@rungs/cli 0.3.0 → 0.4.0

package/src/detect.ts

@@ -2,7 +2,8 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import type { DetectResult, Manifest } from './types.ts';
 import { matchAny, walk } from './glob.ts';
-import { contentHash, emittedFiles } from './add.ts';
+import { contentHash, emittedFiles, preflightModuleEmissions } from './add.ts';
+import { resolveEmittedPath } from './emitted-path.ts';
 import type { Params } from './substitute.ts';
 
 const SAMPLE = 3;
@@ -215,7 +216,9 @@ export interface InstalledModule {
  */
 export function ownedState(mod: Manifest, repoRoot: string, installed: InstalledModule) {
   const params = installed.params_all ?? {};
-  const emitted = emittedFiles(mod, params, installed.skillsDir ?? '.claude/skills');
+  const skillsDir = installed.skillsDir ?? '.claude/skills';
+  preflightModuleEmissions([mod], repoRoot, params, skillsDir);
+  const emitted = emittedFiles(mod, params, skillsDir);
   const kept = new Set(installed.kept?.files ?? []);
   const out = {
     version: installed.version,
@@ -232,7 +235,12 @@ export function ownedState(mod: Manifest, repoRoot: string, installed: Installed
       out.kept.push(rel);
       continue;
     }
-    const full = join(repoRoot, rel);
+    const resolved = resolveEmittedPath(repoRoot, mod.name, rel);
+    const full = resolved.absolute;
+    if (resolved.leafAlias) {
+      out.diverged.push(rel);
+      continue;
+    }
     if (!existsSync(full)) {
       out.missing.push(rel);
       continue;

package/src/emitted-path.ts

@@ -0,0 +1,274 @@
+import { lstatSync, realpathSync, statSync } from 'node:fs';
+import { basename, dirname, isAbsolute, relative, resolve, sep, win32 } from 'node:path';
+import { canonicalCaselessSegmentEqual } from './storage-key.ts';
+
+/**
+ * A module path is repository-relative data, not a host-native path.  Treating
+ * both separators as structural is what makes the same parameter safe when a
+ * record written on Windows is later upgraded on POSIX (or the reverse).
+ */
+export class UnsafeEmittedPathError extends Error {
+  readonly moduleName: string;
+  readonly target: string;
+  readonly reason: string;
+
+  constructor(
+    moduleName: string,
+    target: string,
+    reason: string,
+  ) {
+    super(`module '${moduleName}' emitted unsafe target ${JSON.stringify(target)}: ${reason}`);
+    this.name = 'UnsafeEmittedPathError';
+    this.moduleName = moduleName;
+    this.target = target;
+    this.reason = reason;
+  }
+}
+
+export interface ResolvedEmittedPath {
+  /** Portable, slash-separated form used in actions and install records. */
+  target: string;
+  /** Canonical absolute destination proven to be below the canonical repo root. */
+  absolute: string;
+  /** The final path entry itself is an alias; writes must not follow it. */
+  leafAlias: boolean;
+}
+
+export interface EmittedPathCandidate {
+  moduleName: string;
+  target: string;
+  /** Managed block/shared-registry destinations may intentionally coincide. */
+  shared?: boolean;
+  /** This phase replaces or merges an existing file rather than keeping it. */
+  writeExisting?: boolean;
+}
+
+const missingEntry = (error: unknown) =>
+  error instanceof Error && 'code' in error && (error.code === 'ENOENT' || error.code === 'ENOTDIR');
+
+function hasUnpairedUtf16Surrogate(value: string): boolean {
+  for (let i = 0; i < value.length; i++) {
+    const unit = value.charCodeAt(i);
+    if (unit >= 0xd800 && unit <= 0xdbff) {
+      const next = value.charCodeAt(i + 1);
+      if (!(next >= 0xdc00 && next <= 0xdfff)) return true;
+      i++;
+      continue;
+    }
+    if (unit >= 0xdc00 && unit <= 0xdfff) return true;
+  }
+  return false;
+}
+
+function canonicalCaselessAncestor(ancestor: string, descendant: string): boolean {
+  const ancestorSegments = ancestor.split(sep);
+  const descendantSegments = descendant.split(sep);
+  return (
+    ancestorSegments.length < descendantSegments.length &&
+    ancestorSegments.every((segment, index) => canonicalCaselessSegmentEqual(segment, descendantSegments[index]))
+  );
+}
+
+function canonicalCaselessPathEqual(left: string, right: string): boolean {
+  const leftSegments = left.split(sep);
+  const rightSegments = right.split(sep);
+  return (
+    leftSegments.length === rightSegments.length &&
+    leftSegments.every((segment, index) => canonicalCaselessSegmentEqual(segment, rightSegments[index]))
+  );
+}
+
+/**
+ * Realpath the deepest existing ancestor, then append the still-missing suffix.
+ * `resolve()` alone cannot see an in-repository symlink or junction that points
+ * out of the repository.  A dangling alias fails closed because realpath cannot
+ * establish where a subsequent write would land.
+ */
+function canonicalWithMissing(path: string, moduleName: string, target: string): string {
+  let cursor = resolve(path);
+  const suffix: string[] = [];
+
+  for (;;) {
+    try {
+      lstatSync(cursor);
+    } catch (error) {
+      if (!missingEntry(error)) {
+        throw new UnsafeEmittedPathError(moduleName, target, 'its existing ancestor cannot be inspected');
+      }
+      const parent = dirname(cursor);
+      if (parent === cursor) {
+        throw new UnsafeEmittedPathError(moduleName, target, 'no canonical existing ancestor can be established');
+      }
+      suffix.unshift(basename(cursor));
+      cursor = parent;
+      continue;
+    }
+
+    let canonical: string;
+    try {
+      canonical = realpathSync.native(cursor);
+    } catch {
+      throw new UnsafeEmittedPathError(moduleName, target, 'its existing ancestor cannot be resolved canonically');
+    }
+    if (suffix.length) {
+      try {
+        if (!statSync(canonical).isDirectory()) {
+          throw new UnsafeEmittedPathError(moduleName, target, 'its deepest existing ancestor is not a directory');
+        }
+      } catch (error) {
+        if (error instanceof UnsafeEmittedPathError) throw error;
+        throw new UnsafeEmittedPathError(moduleName, target, 'its existing ancestor cannot be inspected');
+      }
+    }
+    return resolve(canonical, ...suffix);
+  }
+}
+
+/**
+ * Resolve one module-emitted destination and prove it remains in `repoRoot`.
+ * Unsafe syntax is refused before host path resolution so `C:relative`, `\\rooted`
+ * and mixed-separator traversal cannot change meaning between operating systems.
+ */
+export function resolveEmittedPath(repoRoot: string, moduleName: string, target: string): ResolvedEmittedPath {
+  if (!target || target.includes('\0')) {
+    throw new UnsafeEmittedPathError(moduleName, target, 'a non-empty portable relative file path is required');
+  }
+
+  const portable = target.replace(/\\/g, '/');
+  if (portable.startsWith('/') || win32.isAbsolute(target) || /^[A-Za-z]:/.test(portable)) {
+    throw new UnsafeEmittedPathError(moduleName, target, 'absolute, rooted, and drive-relative paths are not allowed');
+  }
+
+  const segments = portable.split('/');
+  if (segments.includes('..')) {
+    throw new UnsafeEmittedPathError(moduleName, target, "parent traversal ('..') is not allowed");
+  }
+  if (segments.some((segment) => segment === '' || segment === '.')) {
+    throw new UnsafeEmittedPathError(moduleName, target, "empty and current-directory ('.') path segments are not allowed");
+  }
+  if (segments.some(hasUnpairedUtf16Surrogate)) {
+    throw new UnsafeEmittedPathError(
+      moduleName,
+      target,
+      'unpaired UTF-16 surrogate code units are not allowed in path segments',
+    );
+  }
+  if (segments.some((segment) => /[\u0000-\u001f<>:"|?*]/.test(segment) || /[ .]$/.test(segment))) {
+    throw new UnsafeEmittedPathError(
+      moduleName,
+      target,
+      'it contains a character or trailing suffix that is not a portable filename',
+    );
+  }
+  const windowsDevice = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i;
+  if (segments.some((segment) => windowsDevice.test(segment))) {
+    throw new UnsafeEmittedPathError(moduleName, target, 'Windows device-name path segments are not allowed');
+  }
+
+  const canonicalRoot = canonicalWithMissing(repoRoot, moduleName, target);
+  const lexicalDestination = resolve(repoRoot, ...segments);
+  const canonicalDestination = canonicalWithMissing(lexicalDestination, moduleName, target);
+  const fromRoot = relative(canonicalRoot, canonicalDestination);
+
+  if (!fromRoot || fromRoot === '..' || fromRoot.startsWith(`..${sep}`) || isAbsolute(fromRoot)) {
+    throw new UnsafeEmittedPathError(moduleName, target, 'it resolves outside the canonical consumer repository');
+  }
+
+  let leafAlias = false;
+  try {
+    leafAlias = lstatSync(lexicalDestination).isSymbolicLink();
+  } catch (error) {
+    if (!missingEntry(error)) {
+      throw new UnsafeEmittedPathError(moduleName, target, 'its destination cannot be inspected');
+    }
+  }
+
+  return { target: portable, absolute: canonicalDestination, leafAlias };
+}
+
+/** Resolve a complete operation and reject two exclusive names for one destination. */
+export function preflightEmittedPaths(
+  repoRoot: string,
+  candidates: EmittedPathCandidate[],
+): ResolvedEmittedPath[] {
+  const resolved = candidates.map((candidate) => {
+    const destination = resolveEmittedPath(repoRoot, candidate.moduleName, candidate.target);
+    if (candidate.writeExisting) {
+      if (destination.leafAlias) {
+        throw new UnsafeEmittedPathError(
+          candidate.moduleName,
+          candidate.target,
+          'the destination is a symlink or junction leaf and this operation will not write through it',
+        );
+      }
+
+      // Every overwrite/merge sink ultimately uses writeFileSync.  Prove an
+      // existing leaf is a regular file now, during the complete-operation
+      // preflight, so a later directory/FIFO/socket cannot fail after an
+      // earlier candidate has already been written. A hard-linked file is also
+      // refused: replacing it would mutate every other name for the same inode,
+      // including a name outside the consumer repository.
+      try {
+        const leaf = lstatSync(destination.absolute);
+        if (!leaf.isFile()) {
+          throw new UnsafeEmittedPathError(
+            candidate.moduleName,
+            candidate.target,
+            'the existing destination is not a regular file',
+          );
+        }
+        if (leaf.nlink > 1) {
+          throw new UnsafeEmittedPathError(
+            candidate.moduleName,
+            candidate.target,
+            'the existing destination has multiple hard links and this operation will not overwrite it',
+          );
+        }
+      } catch (error) {
+        if (error instanceof UnsafeEmittedPathError) throw error;
+        if (!missingEntry(error)) {
+          throw new UnsafeEmittedPathError(
+            candidate.moduleName,
+            candidate.target,
+            'the destination cannot be inspected before writing',
+          );
+        }
+      }
+    }
+    return destination;
+  });
+  const seen: { candidate: EmittedPathCandidate; resolved: ResolvedEmittedPath }[] = [];
+
+  for (let i = 0; i < candidates.length; i++) {
+    const candidate = candidates[i];
+    const destination = resolved[i];
+    // A module plan is portable: names that coexist only on a case-sensitive
+    // checkout are still one destination when that record reaches Windows or a
+    // default case-insensitive macOS volume. Use the same conservative storage
+    // relation as managed refs, including compatibility and full case forms.
+    const prior = seen.find((entry) => canonicalCaselessPathEqual(entry.resolved.absolute, destination.absolute));
+    if (!prior) {
+      const structural = seen.find((entry) =>
+        canonicalCaselessAncestor(entry.resolved.absolute, destination.absolute) ||
+        canonicalCaselessAncestor(destination.absolute, entry.resolved.absolute),
+      );
+      if (!structural) {
+        seen.push({ candidate, resolved: destination });
+        continue;
+      }
+      throw new UnsafeEmittedPathError(
+        candidate.moduleName,
+        candidate.target,
+        `it has a file/descendant collision with module '${structural.candidate.moduleName}' target '${structural.candidate.target}' after canonical resolution`,
+      );
+    }
+    if (candidate.shared && prior.candidate.shared && destination.target === prior.resolved.target) continue;
+    throw new UnsafeEmittedPathError(
+      candidate.moduleName,
+      candidate.target,
+      `it collides with module '${prior.candidate.moduleName}' target '${prior.candidate.target}' after canonical resolution`,
+    );
+  }
+
+  return resolved;
+}

package/src/engine-table.ts

@@ -0,0 +1,66 @@
+/**
+ * One table-section authority for every declared engine dispatch path.
+ *
+ * F-041 existed because the production runner, module self-test runner and
+ * ejected runner each kept a different map and then fell back to the whole
+ * table. A missing entry therefore looked exactly like a green gate that had
+ * nothing to examine. Keep this file dependency-free so eject can copy the
+ * selector without pulling the CLI into the consumer.
+ */
+
+export const WHOLE_TABLE = '__whole__';
+
+export const ENGINE_TABLE_KEYS: Readonly<Record<string, string>> = Object.freeze({
+  'file-budget': 'file_budget',
+  sections: 'sections',
+  'frontmatter-schema': 'frontmatter_schema',
+  'link-integrity': 'link_integrity',
+  'file-population': 'file_population',
+  'gate-meta': 'gate_meta',
+  'id-integrity': WHOLE_TABLE,
+  'render-freshness': 'render_freshness',
+  'register-schema': 'register_schema',
+  'self-declared-closure': 'self_declared_closure',
+  'filename-schema': 'filename_schema',
+  'cross-reference': 'cross_reference',
+  'git-status-reconcile': 'merged_status',
+  'computed-claim': 'computed_claim',
+  'term-ownership': 'term_ownership',
+  'rule-propagation': 'rule_propagation',
+  'git-state': 'git_state',
+  'merge-driver-check': 'merge_driver_check',
+  'board-reconcile': 'board_reconcile',
+  'changelog-freshness': 'changelog_freshness',
+  'change-requires-file': 'change_requires_file',
+  'shell-safety': 'shell_safety',
+});
+
+const entryMatches = (entry: any, gateId: string) =>
+  !!entry?.id && gateId.includes(String(entry.id));
+
+/** Select exactly the section an engine declared, or refuse an unknown shape. */
+export function selectEngineTable(raw: any, engine: string, gateId: string): any {
+  if (!Object.prototype.hasOwnProperty.call(ENGINE_TABLE_KEYS, engine)) {
+    throw new Error(`engine '${engine}' has no table-section mapping`);
+  }
+
+  const key = ENGINE_TABLE_KEYS[engine];
+  if (key === WHOLE_TABLE) return raw;
+  if (!raw || typeof raw !== 'object' || !(key in raw)) {
+    throw new Error(`gate '${gateId}' requires table section '${key}' for engine '${engine}'`);
+  }
+
+  const section = raw[key];
+  if (!Array.isArray(section)) return section;
+
+  const identified = section.filter((entry: any) => entry?.id);
+  if (!identified.length) return section;
+  const matched = identified.filter((entry: any) => entryMatches(entry, gateId));
+  // Some sections intentionally share one subject-named spec across sibling
+  // gates (`id = "rules"`). A matching id narrows an array; no match keeps the
+  // already-selected section. The dangerous fallback was from a missing
+  // *section* to the whole document, and that remains forbidden above.
+  return matched.length
+    ? section.filter((entry: any) => !entry?.id || entryMatches(entry, gateId))
+    : section;
+}

package/src/engines.ts

@@ -1,13 +1,16 @@
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { matchAny, walk } from './glob.ts';
 import { parse as parseToml } from 'smol-toml';
 import { runSelfTests } from './selftest.ts';
 import { loadAllModules } from './manifest.ts';
+
 import { resolveParams, substitute } from './substitute.ts';
 import {
   computedClaim,
   crossReference,
+  changeRequiresFile,
   filenameSchema,
   gitStatusReconcile,
   idIntegrity,
@@ -16,10 +19,31 @@ import {
   selfDeclaredClosure,
 } from './engines2.ts';
 import { boardReconcile, changelogFreshness, gitState, mergeDriverCheck, rulePropagation, termOwnership } from './engines3.ts';
+import { selectEngineTable } from './engine-table.ts';
+import { semanticText } from './text.ts';
+
+/**
+ * Where the CLI's own `modules/` lives.
+ *
+ * This was `new URL(import.meta.url).pathname.slice(1)` in three places. The
+ * `.slice(1)` strips a leading `/`, which is right on Windows — `/C:/…` becomes
+ * `C:/…` — and **wrong everywhere else**, where `/home/runner/…` becomes the
+ * relative `home/runner/…`. On Linux and macOS the directory did not resolve,
+ * `loadAllModules` found nothing, and three gates silently lost the data they
+ * read from the module set: `skills-spec-pure` and `skills-description-routes`
+ * reported every opted-in extension as a non-spec key, and
+ * `gates-self-tests-both-directions` reported gates that have fixtures as
+ * having none. All three passed here and failed on the first Linux run (F-036).
+ *
+ * `fileURLToPath` is what the rest of the codebase already used.
+ */
+const CLI_MODULES = join(dirname(fileURLToPath(import.meta.url)), '..', 'modules');
 
 export interface Finding {
   file?: string;
   message: string;
+  /** Stable comparison form when the displayed diagnostic carries environment-specific detail. */
+  identity?: string;
 }
 export interface EngineResult {
   findings: Finding[];
@@ -30,7 +54,7 @@ export type Engine = (table: any, repoRoot: string, files: string[]) => EngineRe
 
 const read = (root: string, rel: string) => {
   try {
-    return readFileSync(join(root, rel), 'utf8');
+    return semanticText(readFileSync(join(root, rel), 'utf8'));
   } catch {
     return '';
   }
@@ -352,7 +376,7 @@ export const gateMeta: Engine = (_t, root) => {
 
   const registry = join(root, '.ai', 'gates.toml');
   if (!existsSync(registry)) return { findings, examined: 0 };
-  const text = readFileSync(registry, 'utf8');
+  const text = semanticText(readFileSync(registry, 'utf8'));
   const entries = [...text.matchAll(/\[\[gates\]\][\s\S]*?(?=\n\[\[gates\]\]|\n# rungs:end|$)/g)].map((m) => m[0]);
   let examined = 0;
   for (const entry of entries) {
@@ -362,8 +386,8 @@ export const gateMeta: Engine = (_t, root) => {
     if (!id || kind !== 'declared' || !table) continue;
     examined++;
     // Tables live in the CLI, not the repo, so read them from the module set.
-    const tablePath = join(dirname(new URL(import.meta.url).pathname.slice(1)), '..', 'modules', dirname(table), 'gates', table.split('/').pop()!);
-    const src = existsSync(tablePath) ? readFileSync(tablePath, 'utf8') : '';
+    const tablePath = join(CLI_MODULES, dirname(table), 'gates', table.split('/').pop()!);
+    const src = existsSync(tablePath) ? semanticText(readFileSync(tablePath, 'utf8')) : '';
     const forGate = [...src.matchAll(/\[\[self_test\]\][\s\S]*?(?=\n\[\[|\n\[|$)/g)]
       .map((m) => m[0])
       .filter((b) => b.includes(`gate   = "${id}"`) || b.includes(`gate    = "${id}"`) || b.includes(`gate = "${id}"`));
@@ -393,9 +417,14 @@ export const gateMeta: Engine = (_t, root) => {
       const blocks = (Array.isArray(parsed.self_test) ? parsed.self_test : [])
         .filter((b: any) => b?.gate === id)
         .map((b: any) => ({ expect: String(b.expect), input: b.input, fixture: b.fixture }));
-      for (const r of runSelfTests(id, engine, parsed[tableKeyFor(engine)] ?? parsed, blocks)) {
-        if (r.outcome === 'mismatch') findings.push({ message: `self-test for '${id}' ${r.detail}` });
-        else if (r.outcome === 'unrun') unrun++;
+      try {
+        const section = selectEngineTable(parsed, engine, id);
+        for (const r of runSelfTests(id, engine, section, blocks)) {
+          if (r.outcome === 'mismatch') findings.push({ message: `self-test for '${id}' ${r.detail}` });
+          else if (r.outcome === 'unrun') unrun++;
+        }
+      } catch (e: any) {
+        findings.push({ message: `gate '${id}' table dispatch failed: ${e.message}` });
       }
     }
   }
@@ -426,7 +455,7 @@ function optedInExtensions(rel: string, spec: any): Set<string> {
   const name = rel.split('/').slice(-2)[0];
   if (!name) return new Set();
   try {
-    const mods = loadAllModules(join(dirname(new URL(import.meta.url).pathname.slice(1)), '..', 'modules'));
+    const mods = loadAllModules(CLI_MODULES);
     const owner = mods.find((m) => m.skills?.[name]?.extensions);
     return new Set(Object.keys(owner?.skills?.[name]?.extensions ?? {}));
   } catch {
@@ -450,36 +479,14 @@ function parseTable(path: string, module: string): any | null {
     // and the runner reported the gate broken — a mismatch entirely of the
     // harness's making. A fixture and the table it tests must resolve against
     // the same parameters or neither means anything.
-    const mods = loadAllModules(join(dirname(new URL(import.meta.url).pathname.slice(1)), '..', 'modules'));
+    const mods = loadAllModules(CLI_MODULES);
     const params = resolveParams(mods, {}, '.');
-    return parseToml(substitute(readFileSync(path, 'utf8'), module, params));
+    return parseToml(substitute(semanticText(readFileSync(path, 'utf8')), module, params));
   } catch {
     return null;
   }
 }
 
-/** Duplicated from `check.ts` rather than imported, to keep engines dependency-free of the runner. */
-const tableKeyFor = (engine: string) =>
-  ({
-    'file-budget': 'file_budget',
-    'frontmatter-schema': 'frontmatter_schema',
-    'link-integrity': 'link_integrity',
-    'file-population': 'file_population',
-    'render-freshness': 'render_freshness',
-    'register-schema': 'register_schema',
-    'self-declared-closure': 'self_declared_closure',
-    'filename-schema': 'filename_schema',
-    'cross-reference': 'cross_reference',
-    'git-status-reconcile': 'merged_status',
-    'computed-claim': 'computed_claim',
-    'term-ownership': 'term_ownership',
-    'rule-propagation': 'rule_propagation',
-    'git-state': 'git_state',
-    'merge-driver-check': 'merge_driver_check',
-    'board-reconcile': 'board_reconcile',
-    'changelog-freshness': 'changelog_freshness',
-  })[engine] ?? engine;
-
 export const ENGINES: Record<string, Engine> = {
   'file-budget': fileBudget,
   sections,
@@ -501,6 +508,7 @@ export const ENGINES: Record<string, Engine> = {
   'merge-driver-check': mergeDriverCheck,
   'board-reconcile': boardReconcile,
   'changelog-freshness': changelogFreshness,
+  'change-requires-file': changeRequiresFile,
 };
 
 /**