codex-app-server-bridge/openspec/specs/git-npm-package-distribution/spec.md

Purpose

Provide a reproducible repository-backed installation path for the prebuilt Codex App Server bridge while a private npm registry is unavailable.

Requirements

Requirement: Runnable package from immutable Git revision

The project SHALL support normal global npm installation from an immutable Git tag or full commit whose installed codex-app-server-bridge executable launches the compiled bridge without a source checkout, TypeScript compiler, local tarball, or package lifecycle scripts.

Scenario: install a pinned Git revision

• WHEN a user globally installs a supported Git repository URL pinned to a release tag or full commit on Node.js 24 or newer
• THEN npm installs a real package directory and codex-app-server-bridge resolves on the normal global PATH

Scenario: install without lifecycle scripts

• WHEN the pinned Git revision is installed with package lifecycle scripts disabled
• THEN installation succeeds because the selected revision already contains the compiled runtime required by the launcher

Scenario: reject an unbuilt revision

• WHEN a selected Git revision lacks the launcher or either declared compiled runtime file
• THEN Git-package verification fails before that revision is documented or installed

Requirement: Source and committed runtime remain synchronized

The project SHALL provide a repeatable freshness check proving that the committed dist/cli.js and dist/config.js runtime matches the current TypeScript source while excluding all other generated output from Git distribution.

Scenario: fresh committed runtime

• WHEN a maintainer compiles from a clean indexed baseline and runs the freshness check
• THEN rebuilding produces no difference in either committed runtime file

Scenario: stale committed runtime

• WHEN TypeScript source changes without its corresponding compiled runtime update
• THEN the freshness check exits unsuccessfully and identifies generated runtime drift

Requirement: Independent Git-install validation

The project SHALL provide a repeatable verifier that accepts exactly one supported Git package URL pinned to a release tag or full commit, installs it into an isolated global prefix with lifecycle scripts disabled and a dedicated cache, rejects temporary-cache links or missing runtime files, and exercises the installed executable without contacting a Codex App Server.

Scenario: valid Git-installed package

• WHEN the verifier installs a selected immutable Git revision
• THEN the package is independent of npm temporary clone paths and its installed executable reaches the expected unsupported-invocation contract

Scenario: invalid Git verifier input

• WHEN the verifier receives no package spec, multiple specs, a mutable branch, an abbreviated commit, an unsupported URL, or an unusable executable
• THEN it exits unsuccessfully with a diagnostic that does not expose repository credentials or configuration secrets

Requirement: Documented Git installation lifecycle

The project SHALL document the canonical repository, Git access and default-branch preflight, immutable tag-or-commit selection, normal global installation, upgrade, rollback, removal, PATH verification, and unchanged agent-shell configuration.

Scenario: upgrade from tarball installation

• WHEN a user installs a newer verified Git release over the existing local-tarball package
• THEN npm replaces the package while the executable name and Emacs CODEX_PATH integration remain valid

Scenario: roll back Git installation

• WHEN a user reinstalls a previously verified Git revision or tarball
• THEN npm restores that version without requiring an agent-shell configuration change

Scenario: activate the replacement bridge

• WHEN the globally installed Git release has been verified
• THEN new agent-shell launches resolve the replacement PATH executable while existing bridge processes and the shared App Server remain unmanaged