Skip to content

cli.md

Latest commit

 

History

History
107 lines (71 loc) · 5.15 KB

cli.md

File metadata and controls

107 lines (71 loc) · 5.15 KB
Raw

CLI and Project Creator

NERVA v0.1 includes a deliberately small project-creation preview. It provides new and version; it is not the mature multi-command CLI planned for v0.6.

Native CLI

During development, run the CLI directly from this source checkout:

go run ./cmd/nerva version
go run ./cmd/nerva new first-project

Before v0.1.0 exists publicly, the generated dependency cannot be downloaded. To run a development scaffold, add a temporary replacement pointing at this checkout, then remove it before publishing the application:

cd first-project
go mod edit -replace github.com/nerva-framework/nerva=/absolute/path/to/nerva-go
go mod tidy
go run .

Once a public NERVA version is tagged, install the released command with:

go install github.com/nerva-framework/nerva/cmd/nerva@latest
nerva new first-project

The destination name is also the default Go module path. Supply an explicit module path for a project that will be published:

nerva new --module github.com/you/first-project first-project

The creator writes a minimal go.mod and main.go. It is offline and deterministic: it does not execute go, download dependencies, initialize Git, or modify global configuration. It refuses any destination that already exists, including an empty directory, and does not provide a force or merge mode.

Project creation reserves a new destination and uses exclusive file creation to prevent accidental overwrites and collisions with another ordinary creator. It is not a privilege boundary against a malicious process running under the same operating-system identity; do not run the creator with elevated privileges inside a directory writable by an untrusted user.

After a released version is available:

cd first-project
go mod tidy
go run .

The generated service listens on :8080 and includes a small JSON route in addition to NERVA's built-in health route.

npm Launcher

After the create-nerva-app package is published, the shortest npm flow is:

npx create-nerva-app first-project

No npm installation is required for that form. An optional global installation exposes the same launcher command:

npm install --global create-nerva-app
create-nerva-app first-project

The equivalent npm initializer spelling is:

npm create nerva-app@latest -- first-project

The npm package is only a launcher; the Go CLI remains the single scaffold implementation. It passes arguments as a process argument array with shell execution disabled. It does not contain a second template or install JavaScript dependencies into the generated Go project.

The launcher requires Node.js 22.14.0 or newer and a supported Go toolchain. It uses an explicitly configured native CLI only when NERVA_CLI contains its absolute path; otherwise it uses Go's module-aware command runner for the launcher-matched NERVA version. It intentionally does not select an arbitrary nerva executable from PATH. The default fallback is pinned to the npm package version; NERVA_CLI_VERSION=latest is an explicit opt-in to the newest published Go release. The fallback may require network access when the selected module is not already in the Go module cache.

Publication Status

The commands containing @latest are distribution commands, not a claim that the packages are already public. Before they can work for another developer, maintainers must:

  1. publish the repository with an immutable NERVA version tag;
  2. verify go install github.com/nerva-framework/nerva/cmd/nerva@<version> through the public Go module path;
  3. publish the same version of create-nerva-app to npm; and
  4. test both commands from a clean environment.

Go is published first because the npm launcher depends on the corresponding Go CLI version. The publish.yml workflow checks that the Git tag, Go version, npm version, and lockfile agree, then waits for the tagged CLI to become installable through the public Go module proxy before publishing npm. A failed or missing dependency is reported before project creation; it is never replaced with a partial scaffold.

Before enabling that workflow, the npm package owner must configure publish.yml as the trusted GitHub Actions publisher for the repository, allow npm publish, and use the npm GitHub environment. The workflow requests an OIDC identity and does not use a long-lived npm write token.

There is one bootstrap exception: a trusted publisher can only be attached after the npm package exists. For the first create-nerva-app publication, a maintainer must first complete all repository checks, confirm the matching Go tag through the public proxy, and publish once with an MFA-protected npm account. Immediately afterward, configure publish.yml as the trusted publisher and disable token-based automation. Later versions use the OIDC workflow. Do not publish the final version merely to reserve the name before its matching Go release is usable.

Local Verification

From the repository root:

go test ./...
go vet ./...

From npm/create-nerva-app:

npm ci
npm test
npm run test:pack

Public release smoke tests should cover both npx create-nerva-app and npm create nerva-app on Linux, Windows, and macOS.