@sabaiway/agent-workflow-kit 5.6.0 → 5.7.0

package/tools/source-size-gate-cmd.mjs

@@ -1,55 +1,27 @@
-// source-size-gate-cmd.mjs — whether a declared gate cmd IS this checker. Mirrors the SHAPE of the
-// review-dependent matcher (gates-declaration.mjs) without joining either of its arrays: this gate is
-// neither a final core check nor review-dependent.
+// source-size-gate-cmd.mjs — whether a declared gate cmd IS this checker, and — when it is not —
+// WHICH of the three claims it makes instead. The shape, admissibility and realpath screens live in
+// checker-claim.mjs (the ONE home, twinned into the standalone migration); this module owns only
+// the binding to THIS tool. Mirrors the SHAPE of the review-dependent matcher
+// (gates-declaration.mjs) without joining either of its arrays: this gate is neither a final core
+// check nor review-dependent.
 //
 // Dependency-free, Node >= 22. No side effects on import.
 
-import { realpathSync } from 'node:fs';
-import { isAbsolute, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { CHECKER_CLAIM, checkerClaimTool, classifyCheckerClaim, dqUnsafePath } from './checker-claim.mjs';
 
-// STRICT full command — `node` + ONE (quoted or bare) path token + the exact basename + ` --check` +
-// END — and the token must realpath-resolve to THIS kit's own checker, so an id squatter never
-// matches.
-//
-// Separators are PLAIN SPACES, not \s: a newline between the tokens is not a command a runner would
-// execute as written. The token is screened by the rules of the quoting it actually carries, because
-// the two halves are interpreted differently and a single screen would be wrong for one of them:
-//   • QUOTED — double quotes survive most bytes, so only what breaks OUT of them is refused.
-//   • BARE   — anything the shell may split, expand or glob makes the executed command different
-//              from the string, so a bare token is admitted only from a known-safe alphabet.
-// Either way the point is the same: a path that resolves literally here while the shell would read
-// it differently must never be called canonical, or the matcher certifies a command that never runs.
-export const dqUnsafePath = (text) => [...text].some((ch) => {
-  const code = ch.codePointAt(0);
-  return ch === '"' || ch === '$' || code === 96 || code === 92 || code === 13 || code === 10;
-});
-
-// Stated as the bytes the shell ACTS on, not as an alphabet of blessed ones: an allow-list refuses
-// perfectly ordinary paths (`@`, `+`, `,`, `%`, `=`, anything non-ASCII) that the shell passes
-// through verbatim, and refusing a command that really is canonical is its own defect. Whitespace
-// and ASCII control bytes are refused too — a bare token cannot contain them and still be one token.
-const SHELL_ACTIVE_BARE = new Set([...'"\'\\$|&;<>(){}[]*?!#~^`']);
-const bareTokenSafe = (text) => text.length > 0 && ![...text].some((ch) => {
-  const code = ch.codePointAt(0);
-  return code <= 0x20 || code === 0x7f || SHELL_ACTIVE_BARE.has(ch);
-});
+export { dqUnsafePath };
 
-const CHECK_CMD_RE = /^node +(?:"((?:[^"]*[/\\])?source-size-check\.mjs)"|((?:[^\s"]*[/\\])?source-size-check\.mjs)) +--check$/;
 export const SOURCE_SIZE_GATE_ID = 'source-size';
 export const SOURCE_SIZE_TOOL_PATH = fileURLToPath(new URL('./source-size-check.mjs', import.meta.url));
 
-export const matchesSourceSizeGate = (cmd, projectDir) => {
-  if (typeof cmd !== 'string') return false;
-  const match = CHECK_CMD_RE.exec(cmd.trim());
-  if (!match) return false;
-  const token = match[1] ?? match[2];
-  const admissible = match[1] !== undefined ? !dqUnsafePath(token) : bareTokenSafe(token);
-  if (!admissible) return false;
-  const abs = isAbsolute(token) ? token : join(projectDir, token);
-  try {
-    return realpathSync(abs) === realpathSync(SOURCE_SIZE_TOOL_PATH);
-  } catch {
-    return false; // unresolvable → never canonical (fail closed)
-  }
-};
+const SOURCE_SIZE_TOOL = checkerClaimTool('source-size-check.mjs', SOURCE_SIZE_TOOL_PATH);
+
+// The three-outcome read: `canonical` (this copy), `tool-elsewhere` (the same invocation shape
+// resolving to another real copy of the checker — a vendored deployment, not an absence), or
+// `not-the-tool`.
+export const classifySourceSizeGate = (cmd, projectDir) => classifyCheckerClaim(SOURCE_SIZE_TOOL, cmd, projectDir);
+
+// The boolean surface every existing consumer already asks through — "is this gate MY checker?" —
+// kept exactly as narrow as it was: only the canonical claim answers yes.
+export const matchesSourceSizeGate = (cmd, projectDir) => classifySourceSizeGate(cmd, projectDir) === CHECKER_CLAIM.CANONICAL;

package/tools/tracked-tree-census.mjs

@@ -0,0 +1,102 @@
+// tracked-tree-census.mjs — how much of a project's TRACKED tree the changed-line coverage domain
+// can actually assess, in the closed vocabulary that domain already speaks. A LEAF: it imports the
+// classification and nothing else, and it spawns exactly one read-only `git ls-files`.
+//
+// Why this exists: the coverage checker's domain is `.mjs/.cjs/.js` by design, and on a TS project
+// that domain is a rounding error of the tree. Certifying it and calling the flow optimal is the
+// false green one layer up. The census is the FACT that turns "certified" into "certified over the
+// assessable minority" — it never changes what a run may certify.
+//
+// Read-only: never writes, never commits. Dependency-free, Node >= 22. No side effects on import.
+
+import { spawnSync } from 'node:child_process';
+import { classifyChangedPath } from './changed-surface.mjs';
+
+const GIT_MAX_BUFFER = 256 * 1024 * 1024; // a large tracked tree; never truncate
+
+export const CENSUS_VERDICT = Object.freeze({ NARROW: 'domain-narrow', WITHIN_DOMAIN: 'within-domain' });
+
+// The tracked tree is listed with -z and split on NUL. A newline-split of the plain form would be
+// wrong twice over: git C-QUOTES a path carrying quotes/control/non-ASCII bytes (so the classifier
+// would read `"src/\303\251.ts"`, extension and all, as some other path), and a path containing a
+// real newline would split into two phantom entries. -z emits raw bytes and never quotes.
+//
+// DE-DUPLICATED, because `ls-files` lists per INDEX ENTRY, not per file: during an unresolved merge
+// one conflicted path appears once per stage (probed: three times for a content conflict). Counting
+// those would inflate one population and could flip a tie into the narrow verdict on nothing but a
+// merge in progress.
+//
+// The split and the de-duplication happen on RAW BYTES, before any decoding. A filename is a byte
+// string on this platform and need not be valid UTF-8; decoding first turns every invalid sequence
+// into the same replacement character, so two genuinely different paths would collapse into one and
+// the de-duplication — added to fix an over-count — would become an UNDER-count. Decoding happens
+// once per surviving entry, for the classifier only.
+const NUL = 0;
+const splitOnNul = (buffer) => {
+  const parts = [];
+  let start = 0;
+  for (let at = buffer.indexOf(NUL, start); at !== -1; at = buffer.indexOf(NUL, start)) {
+    if (at > start) parts.push(buffer.subarray(start, at));
+    start = at + 1;
+  }
+  if (start < buffer.length) parts.push(buffer.subarray(start));
+  return parts;
+};
+
+const listTrackedPaths = (root, spawn) => {
+  const result = spawn('git', ['ls-files', '-z'], { cwd: root, maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
+  if (result.error || result.status !== 0) {
+    const reason = result.error ? (result.error.code ?? result.error.message) : `git exited ${result.status}`;
+    throw Object.assign(new Error(`tracked-tree census unavailable: ${reason}`), { code: 'CENSUS_UNAVAILABLE' });
+  }
+  // A spawn seam may hand back a string (an injected fixture); anything else is the real Buffer.
+  const raw = Buffer.isBuffer(result.stdout) ? result.stdout : Buffer.from(String(result.stdout ?? ''), 'utf8');
+  const seenBytes = new Set();
+  const paths = [];
+  for (const part of splitOnNul(raw)) {
+    const identity = part.toString('latin1'); // byte-exact key: one char per byte, never lossy
+    if (seenBytes.has(identity)) continue;
+    seenBytes.add(identity);
+    paths.push(part.toString('utf8'));
+  }
+  return paths;
+};
+
+// takeCensus(root) → { counts, unsupportedExtensions, verdict, total }.
+//
+// The verdict fires on STRICT DOMINANCE only — the unsupported population must strictly outnumber
+// the assessable one. A tie, or a lone `.d.ts` shim beside a real JS tree, is not a narrow domain
+// and must not raise an item the project cannot act on. `.d.ts` counts as unsupported like any
+// other `.ts` (stated: the classification is by extension, and this leaf adds no exceptions to it).
+// Anything outside both sets — `.py`, `.go`, a README — is `out-of-domain` and counted, never
+// judged: detecting whole out-of-domain-language projects is deliberately not this census's job.
+// An UNAVAILABLE census throws (a non-git tree, a broken git) — the caller's stated-skip lane. It
+// never returns a verdict it could not compute; a silent "within-domain" would be the same false
+// green one layer down.
+export const takeCensus = (root, { spawn = spawnSync } = {}) => {
+  const counts = { assessable: 0, unsupported: 0, 'out-of-domain': 0, 'excluded-test': 0 };
+  const unsupportedExtensions = new Set();
+  for (const path of listTrackedPaths(root, spawn)) {
+    const kind = classifyChangedPath(path);
+    counts[kind] += 1;
+    if (kind === 'unsupported') {
+      const base = path.split('/').pop();
+      unsupportedExtensions.add(base.slice(base.lastIndexOf('.')));
+    }
+  }
+  const verdict = counts.unsupported > counts.assessable ? CENSUS_VERDICT.NARROW : CENSUS_VERDICT.WITHIN_DOMAIN;
+  return {
+    counts,
+    unsupportedExtensions: [...unsupportedExtensions].sort(),
+    verdict,
+    total: Object.values(counts).reduce((sum, n) => sum + n, 0),
+  };
+};
+
+// censusFact(census) → the canonical string an acknowledgment binds. It carries the VERDICT and the
+// sorted set of unsupported extensions present — never the per-file counts. A count-bound fact
+// would re-fire the moment any file is added, turning a durable acknowledgment into a nag; the
+// FACT the maintainer acknowledged ("this tree is dominated by .ts/.tsx, and certification covers
+// the JS minority") is exactly what stays stable while the tree grows, and exactly what changes
+// when a new unsupported language arrives or the verdict flips back.
+export const censusFact = (census) => `${census.verdict}:${census.unsupportedExtensions.join(',')}`;

package/tools/upgrade-runlist.mjs

@@ -0,0 +1,92 @@
+// upgrade-runlist.mjs — the ORDERED registry of the upgrade step-3 operations: the ONE home for
+// their identity (stable id · exact command · consent gate · relayed outcome vocabulary).
+//
+// references/modes/upgrade.md step 3 opens with a checklist rendered from these entries — the
+// structure test (test/upgrade-runlist.test.mjs) binds checklist rows ↔ entries: same backticked
+// ids, same order, each row carrying its registry command and naming its outcomes — and the future
+// reconcile driver reads its item tokens from here (queue row UPGRADE-RECONCILE-DRIVER).
+//
+// A PURE LEAF with zero imports (the ensure-vocabulary.mjs pattern): reading operation identity
+// must never drag an operation's implementation — and through it the writers — into a read-only
+// consumer's import graph. The `configs` outcomes are a literal copy of RELAYED_ENSURE_TOKENS
+// (ensure-vocabulary.mjs stays the owner); the structure test asserts the copy never drifts.
+//
+// `consent` is null for an operation the agent runs outright, else the ONE consent gate the mode
+// doc teaches for it. `outcomes` is the vocabulary the doc names for relaying that operation's
+// result — for `configs` the closed ensure tokens, elsewhere the doc's own outcome words.
+
+const entry = (id, command, consent, outcomes) =>
+  Object.freeze({ id, command, consent, outcomes: Object.freeze(outcomes) });
+
+export const UPGRADE_RUNLIST = Object.freeze([
+  entry(
+    'pointers',
+    'node ${CLAUDE_SKILL_DIR}/tools/inject-methodology.mjs reconcile <project>/AGENTS.md',
+    null,
+    ['added', 'already present', 'skipped', 'STOP'],
+  ),
+  entry(
+    'footprint',
+    'node ${CLAUDE_SKILL_DIR}/tools/hide-footprint.mjs --dir <project> --reconcile --dry-run',
+    'ambiguous → ask the user which it is; hidden → the conditional re-run without --dry-run (surfaced paths ask per bootstrap step 9)',
+    ['visible', 'ambiguous', 'hidden'],
+  ),
+  entry(
+    'configs',
+    'node ${CLAUDE_SKILL_DIR}/tools/ensure-configs.mjs --reconcile --cwd <project>',
+    null,
+    [
+      'seeded',
+      'note-refreshed',
+      'already-current',
+      'customized-preserved',
+      'malformed-preserved',
+      'already-present',
+      'skipped-no-node',
+      'old-adr-layout-migration-instructed',
+      'failed',
+    ],
+  ),
+  entry(
+    'gates-migration',
+    'node ${CLAUDE_SKILL_DIR}/references/scripts/migrate-gates.mjs --kit-tools ${CLAUDE_SKILL_DIR}/tools --cwd <project>',
+    'preview first — apply only on an explicit yes, re-run with --apply',
+    ['preview', 'INERT', 'CUSTOMIZED'],
+  ),
+  entry(
+    'bridges',
+    'node ${CLAUDE_SKILL_DIR}/tools/setup-backends.mjs --refresh-placed',
+    null,
+    [
+      'refreshed',
+      'already current',
+      'skipped',
+      'not placed',
+      'newer than the bundle',
+      'unsupported host',
+      'skipped-readonly',
+      'could not refresh',
+    ],
+  ),
+  entry(
+    'lens',
+    'node ${CLAUDE_SKILL_DIR}/tools/lens-region.mjs reconcile <project>/docs/ai/agent_rules.md',
+    null,
+    [
+      'refreshed',
+      'already current',
+      'custom edit preserved',
+      'file absent',
+      'engine too old',
+      'over the line cap — refused',
+      'section absent — noted',
+      'STOP',
+    ],
+  ),
+  entry(
+    'bridge-settings',
+    'node ${CLAUDE_SKILL_DIR}/tools/bridge-settings.mjs --reconcile',
+    null,
+    ['ok', 'absent', 'flagged', 'duplicates', 'unusable'],
+  ),
+]);