trackfw 7.6.0 → 8.0.0-rc2

package/README.md

@@ -93,15 +93,23 @@ brew install kgsaran/tap/trackfw
 go install github.com/kgsaran/trackfw/cmd/trackfw@latest
 ```
 
-### npm (pure Node.js — no binary)
+### npm
 
 ```bash
 npm install -g trackfw
 ```
 
-The npm package is pure Node.js — no compiled binary or postinstall download.
-It installs wherever Node.js ≥ 18 is installed. Shared behavior, including the AI
-integration lifecycle, follows the [CLI parity contract](docs/cli-parity.md).
+From v8.0.0, the npm package is a ~80-line JavaScript shim that resolves
+`@trackfw-bin/<platform>` at install time and executes the Go binary. **It is no
+longer pure Node.js — it contains a compiled binary.** The binary arrives through
+the `npm` channel rather than as a separate download, so organisations whose policy
+allows `npm install` but blocks direct executable downloads remain served.
+
+If your policy forbids compiled binaries in any form regardless of channel, this
+version is a breaking change for you. See [Changelog](CHANGELOG.md) for the full
+declaration.
+
+Shared behavior follows the [command contract](docs/cli-parity.md).
 
 > **The CLI installs on Node ≥ 18 alone — the generated guard hooks do not run on
 > Node alone.** They are POSIX shell scripts and need a POSIX shell to execute. On
@@ -118,8 +126,9 @@ are than let you find them after adoption.
 
 **What we know works**
 
-- The three CLIs install (`npm install -g trackfw`, `pip install trackfw`, and the
-  published `trackfw_<version>_windows_amd64.tar.gz`).
+- All three channels install (`npm install -g trackfw`, `pip install trackfw`, and the
+  published `trackfw_<version>_windows_amd64.tar.gz` / `windows_arm64.tar.gz`). From v8.0.0 all
+  three deliver the same Go binary; no separate Node.js or Python implementation.
 - Core governance commands — `req new`, `roadmap new`, `roadmap move`, `status`,
   `validate` — run, and artifacts are written with LF endings.
 
@@ -129,8 +138,6 @@ are than let you find them after adoption.
   Install manually from the release archive for now.
 - Our Windows CI still reports **known test failures**. They are mapped by root cause,
   not unknown — but they are not zero.
-- **Windows ARM64 is not built.** Only `windows_amd64` is published.
-
 **Guard hooks on Windows — measured, per agent CLI**
 
 The guard hooks are `.sh` scripts, executed by *your* AI agent CLI. Which shell that CLI
@@ -168,9 +175,19 @@ an issue with what you measured.
 pip install trackfw
 ```
 
-The pip package is pure Python 3.10+ — no compiled binary or postinstall
-download. Shared commands, validation rules, and by_agent behavior follow the
-[CLI parity contract](docs/cli-parity.md).
+From v8.0.0, the pip package is a binary wheel in `gh-bin` format — **it contains
+no Python files and no source**. The Go binary is installed into the PATH by pip.
+`python -m trackfw` no longer works; use the `trackfw` executable directly.
+
+Platforms not covered by the published wheels now fail at resolution time with
+"no matching distribution found" — a clean failure instead of silently installing
+the wrong thing. Eight wheels are published: `manylinux_2_17_x86_64`, `musllinux_1_2_x86_64`,
+`manylinux_2_17_aarch64`, `musllinux_1_2_aarch64`, `macosx_10_9_x86_64`,
+`macosx_11_0_arm64`, `win_amd64`, `win_arm64`. Linux publishes two wheels per
+architecture (manylinux + musllinux), so Alpine and similar musl-based distributions
+are covered.
+
+Shared behavior follows the [command contract](docs/cli-parity.md).
 
 ---
 

package/bin/trackfw.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+"use strict";
+
+// trackfw shim — resolves the platform binary at runtime.
+// Design: NO postinstall. Binary is located here, at require() time.
+// Prior art: esbuild (https://esbuild.github.io/getting-started/#download-using-npm)
+//
+// Resolution strategy: platform packages carry NO `bin` field — that field would
+// create a collision in node_modules/.bin/trackfw (npm install-order dependent,
+// nondeterministic). Instead, the shim computes the binary subpath from os.platform()
+// directly (same pattern as esbuild), then joins with the already-known pkgDir.
+// No package metadata consulted for the path.
+//
+// Ported from prototype/packages/trackfw-shim/bin/trackfw.js (validated in
+// darwin/arm64, win32/arm64, win32/x64) — ML-1B, ROADMAP-2026-09-12-v8.
+
+const path = require("path");
+const fs = require("fs");
+const { spawnSync } = require("child_process");
+const os = require("os");
+
+function getPlatformPackage() {
+  const platform = os.platform();   // 'linux', 'darwin', 'win32'
+  const arch = os.arch();           // 'x64', 'arm64'
+  // Dynamic: package name is constructed from platform+arch.
+  // No hardcoded allowlist — new platforms are supported automatically once published.
+  return `@trackfw-bin/${platform}-${arch}`;
+}
+
+function resolveBinaryPath(pkg) {
+  // Resolve the platform package from node_modules relative to this shim.
+  // This works with or without postinstall, under --ignore-scripts.
+  let pkgPath;
+  try {
+    pkgPath = require.resolve(`${pkg}/package.json`);
+  } catch (e) {
+    const platform = os.platform();
+    const arch = os.arch();
+    process.stderr.write(
+      `trackfw: platform package for ${platform}/${arch} (${pkg}) is not installed.\n` +
+      `This usually means the optional dependency was skipped during install.\n` +
+      `Try: npm install (without --no-optional) or install ${pkg} directly.\n`
+    );
+    process.exit(1);
+  }
+
+  const pkgDir = path.dirname(pkgPath);
+
+  // Compute binary subpath from platform — platform packages carry no `bin` field
+  // (avoids nondeterministic collision in node_modules/.bin/ from install order).
+  const binaryName = os.platform() === "win32" ? "trackfw.exe" : "trackfw";
+  const resolvedBin = path.join(pkgDir, "bin", binaryName);
+
+  // Fail loudly and name the cause — AC7: no MODULE_NOT_FOUND surprises.
+  if (!fs.existsSync(resolvedBin)) {
+    process.stderr.write(
+      `trackfw: platform binary not found in ${pkg}.\n` +
+      `Expected: ${resolvedBin}\n` +
+      `The platform package may be corrupted or missing the binary in bin/${binaryName}.\n`
+    );
+    process.exit(1);
+  }
+
+  return resolvedBin;
+}
+
+const pkg = getPlatformPackage();
+const binPath = resolveBinaryPath(pkg);
+
+// Pass all argv through to the binary.
+const result = spawnSync(binPath, process.argv.slice(2), {
+  stdio: "inherit",
+  env: process.env,
+});
+
+if (result.error) {
+  process.stderr.write(`trackfw: failed to run binary: ${result.error.message}\n`);
+  process.exit(1);
+}
+
+process.exit(result.status ?? 1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackfw",
-  "version": "7.6.0",
+  "version": "8.0.0-rc2",
   "description": "Governance CLI for AI-native software delivery and AI coding agents. Enforces traceability: ADR → REQ → ROADMAP → kanban. Native support for Codex, Claude Code, Gemini CLI, Cursor, Copilot, Windsurf, Amazon Q, OpenCode, and Kiro.",
   "keywords": [
     "cli",
@@ -45,23 +45,29 @@
   },
   "license": "MIT",
   "bin": {
-    "trackfw": "./bin/trackfw"
+    "trackfw": "./bin/trackfw.js"
   },
-  "main": "./src/commands/index.js",
   "files": [
-    "bin/",
-    "src/"
+    "bin/trackfw.js"
   ],
   "scripts": {
     "test": "node --test tests/*.test.js",
-    "smoke": "node bin/trackfw --help && node bin/trackfw version"
+    "smoke": "node --check bin/trackfw.js && echo 'shim syntax ok'"
   },
-  "dependencies": {
-    "commander": "^12.0.0",
+  "devDependencies": {
     "@inquirer/prompts": "^5.0.0",
+    "commander": "^12.0.0",
     "yaml": "^2.9.0"
   },
   "engines": {
     "node": ">=18"
+  },
+  "optionalDependencies": {
+    "@trackfw-bin/darwin-arm64": "8.0.0-rc2",
+    "@trackfw-bin/darwin-x64": "8.0.0-rc2",
+    "@trackfw-bin/linux-arm64": "8.0.0-rc2",
+    "@trackfw-bin/linux-x64": "8.0.0-rc2",
+    "@trackfw-bin/win32-arm64": "8.0.0-rc2",
+    "@trackfw-bin/win32-x64": "8.0.0-rc2"
   }
 }

package/bin/trackfw

@@ -1,41 +0,0 @@
-#!/usr/bin/env node
-'use strict'
-
-const { reportFatalError, installGlobalHandlers } = require('../src/lib/fatal-error')
-
-// Registered before any command runs — see fatal-error.js for why this is a
-// single entrypoint-level handler instead of a try/catch per command.
-installGlobalHandlers()
-
-const program = require('../src/commands/index').createProgram()
-
-// trackfw sem argumento é uso legítimo (pedir ajuda), não erro — decisão do
-// arquiteto no ML-1C (ROADMAP-2026-08-16-higiene-...). Sem intervenção,
-// commander trata "nenhum operando" como "provavelmente faltou um
-// subcomando" (Command._parseCommand: `this.commands.length && this.args
-// .length === 0 && !this._actionHandler` → `this.help({error: true})`) —
-// help em stderr, exit 1. Interceptar SÓ o caso de zero argumentos aqui,
-// antes de entrar no parser, reusa o MESMO texto de ajuda (outputHelp) na
-// saída canônica (stdout, exit 0) sem tocar no parsing normal — em
-// particular sem registrar uma .action() no root, que reclassificaria um
-// comando desconhecido (ex.: "trackfw naoexiste") como argumento posicional
-// da action em vez de disparar o listener 'command:*' (regressão descartada
-// em favor desta abordagem: ver ROADMAP ML-1C).
-//
-// Fica ANTES do parseAsync e DEPOIS de installGlobalHandlers(): o caminho de
-// zero argumentos é sucesso e nunca deve passar pelo reportFatalError abaixo.
-if (process.argv.length <= 2) {
-  program.outputHelp()
-  process.exit(0)
-}
-
-program
-  .parseAsync(process.argv)
-  .catch((err) => {
-    // The primary path: an action (sync or async) threw, and since the
-    // program is driven by parseAsync() that surfaces here as a rejected
-    // promise — not as an uncaughtException/unhandledRejection, which is
-    // why this .catch exists in addition to installGlobalHandlers() above.
-    reportFatalError(err)
-    process.exitCode = 1
-  })