codex-app-server-bridge/openspec/changes/archive/2026-08-23-support-codex-app-server-bridge-git-install/proposal.md

Why

The bridge can be installed reliably from a locally built .tgz, but a normal npm install from its Git repository needs the compiled Node 24 runtime to already exist in the selected revision. An immutable Git tag or commit provides a portable distribution path while a private npm registry is not yet available.

What Changes

• Commit only the compiled dist/cli.js and dist/config.js runtime required by the existing launcher while excluding other generated output.
• Remove npm lifecycle triggers that could compile inside a consumer-side Git clone and replace implicit packaging with explicit verified workflows.
• Support normal global npm installation from an immutable Git tag or full commit without TypeScript, lifecycle scripts, a source checkout, or a local tarball.
• Add generated-runtime freshness, isolated Git-install, and packed-artifact verification.
• Document Git access preflight, immutable version selection, upgrade, rollback, removal, PATH validation, and unchanged CODEX_PATH integration.

Capabilities

New Capabilities

• git-npm-package-distribution: Reproducible installation and verification of the prebuilt bridge CLI from an immutable Git repository revision.

Modified Capabilities

• codex-app-server-bridge: Change the Node package contract from uncommitted tarball-only output to committed runtime supporting both verified tarballs and lifecycle-free Git installation.

Impact

• Repository: /Users/dnabracz/Work/scm/codex-app-server-bridge.
• Affected files are package metadata, generated-file ignore rules, committed runtime output, verification scripts, package/documentation tests, and installation documentation.
• Package version becomes 0.1.1; the package name, executable, invocation, transport behavior, Node 24 minimum, lack of runtime dependencies, and Emacs CODEX_PATH configuration remain unchanged.
• Release fc1fd48525f6d664b6ac4c236c04931001cf01ad is published as immutable tag v0.1.1 on both remotes and installed from the canonical Gogs repository.