audit-tools 0.32.51 → 0.32.53

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "audit-tools",
-  "version": "0.32.51",
+  "version": "0.32.53",
   "private": false,
   "license": "ISC",
   "description": "Portable hybrid code auditing + remediation orchestrators for arbitrary repositories.",

package/remediate-code.mjs

@@ -36,44 +36,66 @@ function newestMtimeMs(path) {
   return newest;
 }
 
-function shouldBuildDist() {
+export function shouldBuildDist() {
   if (!existsSync(sourceRoot)) {
     return false;
   }
-  if (!existsSync(tsconfigPath)) {
-    return !existsSync(distEntry);
-  }
   if (!existsSync(distEntry)) {
     return true;
   }
-  return statSync(distEntry).mtimeMs < Math.max(
-    newestMtimeMs(sourceRoot),
-    statSync(tsconfigPath).mtimeMs,
-  );
+  // Compare dist freshness against src/ (and tsconfig.json when present). A
+  // missing tsconfig.json must NOT collapse this to an existence-only check: a
+  // dist older than src/ is still stale and must rebuild (CE-003). Previously
+  // the tsconfig-absent branch returned `!existsSync(distEntry)`, so a present
+  // but stale dist was silently used.
+  const newestSourceMs = existsSync(tsconfigPath)
+    ? Math.max(newestMtimeMs(sourceRoot), statSync(tsconfigPath).mtimeMs)
+    : newestMtimeMs(sourceRoot);
+  return statSync(distEntry).mtimeMs < newestSourceMs;
+}
+
+// Default build runner (platform-branched npm run build). Injectable in
+// ensureBuilt so the build-failure control flow is unit-testable without
+// spawning a real build.
+function runNpmBuild() {
+  return process.platform === "win32"
+    ? spawnSync(process.env.ComSpec ?? "cmd.exe", ["/d", "/s", "/c", "npm run build"], {
+        cwd: __dirname,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+      })
+    : spawnSync("npm", ["run", "build"], {
+        cwd: __dirname,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+      });
 }
 
-function ensureBuilt() {
-  if (!shouldBuildDist()) return;
-  const result =
-    process.platform === "win32"
-      ? spawnSync(process.env.ComSpec ?? "cmd.exe", ["/d", "/s", "/c", "npm run build"], {
-          cwd: __dirname,
-          encoding: "utf8",
-          stdio: ["ignore", "pipe", "pipe"],
-        })
-      : spawnSync("npm", ["run", "build"], {
-          cwd: __dirname,
-          encoding: "utf8",
-          stdio: ["ignore", "pipe", "pipe"],
-        });
+// Returns true when it is safe to proceed to dist forwarding, false when a
+// failed/signaled build has initiated a terminating exit action and the caller
+// MUST stop. The signal branch of applyWrapperExitAction re-raises the signal
+// and schedules a fallback exit but RETURNS control (the fallback can only fire
+// once the event loop is free); without this boolean guard main() would then
+// run its blocking spawnSync and forward the command against a stale/absent
+// dist before the fallback ever fires (CE-002). The exit-code branch terminates
+// synchronously, so it never reaches the `return false`.
+export function ensureBuilt({
+  shouldBuild = shouldBuildDist,
+  runBuild = runNpmBuild,
+  applyExit = applyWrapperExitAction,
+} = {}) {
+  if (!shouldBuild()) return true;
+  const result = runBuild();
   if (result.stdout) process.stderr.write(result.stdout);
   if (result.stderr) process.stderr.write(result.stderr);
   if (result.error) {
     console.error(`remediate-code: failed to auto-build dist (${result.error.message})`);
   }
   if (result.status !== 0 || result.signal) {
-    applyWrapperExitAction(getWrapperExitAction(result));
+    applyExit(getWrapperExitAction(result));
+    return false;
   }
+  return true;
 }
 
 export function getWrapperExitAction(result, platform = process.platform) {
@@ -119,7 +141,11 @@ export async function main(argv = process.argv.slice(2)) {
     return;
   }
 
-  ensureBuilt();
+  // A failed/signaled build returns false here; stop rather than forward the
+  // command against a stale/absent dist (CE-002). The exit action is already
+  // in flight (synchronous exit for a nonzero status, pending fallback exit for
+  // a re-raised signal).
+  if (!ensureBuilt()) return;
   if (!existsSync(distEntry)) {
     console.error("remediate-code: dist/remediate/index.js not found. Run: npm run build");
     process.exit(1);

package/wrapper/audit-code-wrapper-lib.mjs

@@ -23,12 +23,31 @@ const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
 const distEntry = join(repoRoot, 'dist', 'audit', 'index.js');
 const packageJsonPath = join(repoRoot, 'package.json');
 const promptAssetPath = join(repoRoot, 'skills', 'audit-code', 'audit-code.prompt.md');
-const packageVersion = JSON.parse(await readFile(packageJsonPath, 'utf8')).version;
+
+// Deferred (NOT a top-level await): package.json is only needed by the
+// `--version` branch, and a top-level read would fail EVERY invocation —
+// including `--help` — whenever package.json is unreadable (CE-006).
+async function readPackageVersion() {
+  return JSON.parse(await readFile(packageJsonPath, 'utf8')).version;
+}
 
 function hasFlag(argv, name) {
   return argv.includes(name);
 }
 
+// Informational flags (--help/--version) short-circuit the wrapper only when
+// they appear BEFORE the first non-flag token (the command). A whole-argv scan
+// hijacks post-command tokens that belong to the dist CLI — e.g.
+// `audit-code explain-task -v` printed the wrapper's version instead of
+// forwarding `-v` to the dist command (CE-007).
+function hasLeadingFlag(argv, name) {
+  for (const token of argv) {
+    if (token === name) return true;
+    if (!token.startsWith('-')) return false;
+  }
+  return false;
+}
+
 function getFlag(argv, name) {
   const index = argv.indexOf(name);
   if (index < 0) return undefined;
@@ -41,6 +60,22 @@ function setDefaultFlag(argv, name, value) {
   }
 }
 
+// Overwrite an existing flag's value (or append when absent). setDefaultFlag
+// only fills a MISSING flag, so a user-supplied RELATIVE --root/--artifacts-dir
+// was forwarded raw and then re-resolved against the child's cwd (repoRoot),
+// not the caller's cwd — e.g. `--root .` pointed at the package dir (CE-001).
+// Normalizing to an absolute path here makes the forwarded value cwd-stable.
+function setFlag(argv, name, value) {
+  const index = argv.indexOf(name);
+  if (index < 0) {
+    argv.push(name, value);
+  } else {
+    argv[index + 1] = value;
+  }
+}
+
+export { hasLeadingFlag, setFlag };
+
 function nodeExecutable() {
   return process.execPath;
 }
@@ -193,8 +228,10 @@ async function runDistCommand(commandName, argv, { ensureArtifactsDir = false }
   const rootValue = resolve(getFlag(commandArgs, '--root') ?? '.');
   const artifactsDir = resolve(getFlag(commandArgs, '--artifacts-dir') ?? join(rootValue, '.audit-tools', 'audit'));
 
-  setDefaultFlag(commandArgs, '--root', rootValue);
-  setDefaultFlag(commandArgs, '--artifacts-dir', artifactsDir);
+  // Overwrite (not default) so a user-supplied relative value is normalized to
+  // the caller-cwd-resolved absolute path before it reaches the child (CE-001).
+  setFlag(commandArgs, '--root', rootValue);
+  setFlag(commandArgs, '--artifacts-dir', artifactsDir);
 
   if (ensureArtifactsDir) {
     await mkdir(artifactsDir, { recursive: true });
@@ -206,15 +243,21 @@ async function runDistCommand(commandName, argv, { ensureArtifactsDir = false }
   });
 }
 
-async function runDistCommandInline(commandName, argv) {
+async function runDistCommandInline(commandName, argv, { ensureArtifactsDir = false } = {}) {
   const commandArgs = [...argv];
   const rootValue = resolve(getFlag(commandArgs, '--root') ?? '.');
   const artifactsDir = resolve(getFlag(commandArgs, '--artifacts-dir') ?? join(rootValue, '.audit-tools', 'audit'));
 
-  setDefaultFlag(commandArgs, '--root', rootValue);
-  setDefaultFlag(commandArgs, '--artifacts-dir', artifactsDir);
+  setFlag(commandArgs, '--root', rootValue);
+  setFlag(commandArgs, '--artifacts-dir', artifactsDir);
 
-  await mkdir(artifactsDir, { recursive: true });
+  // Gate the mkdir behind the same ensureArtifactsDir flag as runDistCommand so
+  // "the artifacts directory is created only for designated stateful commands"
+  // holds on this path too (CE-001); mcp is a designated stateful command and
+  // opts in explicitly at its call site.
+  if (ensureArtifactsDir) {
+    await mkdir(artifactsDir, { recursive: true });
+  }
   await ensureBuilt();
 
   // Propagate the invocation hint into this (long-lived) server process so it
@@ -238,13 +281,13 @@ export async function runAuditCodeWrapper({
   argv = process.argv.slice(2),
   preferredEntrypoint
 }) {
-  if (hasFlag(argv, '--help') || hasFlag(argv, '-h')) {
+  if (hasLeadingFlag(argv, '--help') || hasLeadingFlag(argv, '-h')) {
     printHelp({ usageName, preferredEntrypoint });
     return;
   }
 
-  if (hasFlag(argv, '--version') || hasFlag(argv, '-v')) {
-    console.log(packageVersion);
+  if (hasLeadingFlag(argv, '--version') || hasLeadingFlag(argv, '-v')) {
+    console.log(await readPackageVersion());
     return;
   }
 
@@ -280,7 +323,7 @@ export async function runAuditCodeWrapper({
   //    because they may be the FIRST call in a fresh repo and must create the
   //    run directory before dist reads it.
   if (argv[0] === 'mcp') {
-    await runDistCommandInline('mcp', argv.slice(1));
+    await runDistCommandInline('mcp', argv.slice(1), { ensureArtifactsDir: true });
     return;
   }