simt-dev 0.2.0__py3-none-any.whl

simt_dev/vendored/src/commands/compare.mjs

@@ -0,0 +1,195 @@
+// simt-dev compare - the org-wide matrix.
+//
+// This command exists because the 2026-10-05 audit had to be reconstructed by
+// hand, from 16 repositories, into 40 KB of prose. Everything it found is a fact
+// this command computes: which repos are adopted, which have drifted, which route
+// hooks, which declare gates the dispatcher cannot run.
+//
+// Two decisions make it useful rather than decorative:
+//
+//   1. It is a READ of the workspace, never a write. No `sync`, no `upgrade`, no
+//      tag. A dashboard that can change state is not a dashboard; an agent running
+//      `compare` to orient itself must not be able to mutate 16 repositories.
+//   2. The exit code is a SIGNAL, not a score. It fails when something is wrong
+//      (drift, malformed region, a gate that cannot run), and succeeds when repos
+//      are merely not adopted yet - an unadopted repo is the expected mid-migration
+//      state, not a defect, and a command that went red for it would train people
+//      to ignore it.
+//
+// Output is one fact per line in fixed field order (plan 0002 section 6): a
+// human can read the table, an agent can grep it, and two runs diff cleanly.
+
+import { basename, resolve } from 'node:path';
+
+import { EXIT, emit, emitJson, fail, isJson, note } from '../output/index.mjs';
+import { provenanceDigest } from '../projection/project.mjs';
+import { GATES } from '../hooks/gates.mjs';
+import { buildRow, summarise } from '../compare/row.mjs';
+import { discover } from '../compare/discover.mjs';
+import { targetRoot, WORKSPACE_REMEDY } from '../workspace.mjs';
+
+/** Gate kinds, so a row can tell a command gate with no command from a script gate. */
+const GATE_KINDS = new Map(Object.entries(GATES).map(([name, g]) => [name, g.kind]));
+
+export async function compareCommand(positional, flags) {
+  // The estate root. `--root` is explicit and wins; otherwise it is the resolved
+  // workspace, which may be none (ADR-014: a single repo is a first-class case, and
+  // "no workspace" is a fact to report rather than a failure).
+  //
+  // A path that IS a repository is compared as itself, not scanned for children:
+  // naming one repo almost certainly meant that repo. Discovery decides which,
+  // rather than this command guessing.
+  //
+  // `targetRoot` owns the precedence so `compare` and `upgrade` cannot disagree about
+  // which source named the directory.
+  const target = await targetRoot(flags, positional);
+  const root = resolve(target.root);
+  const found = await discover(root);
+  if (found.error) {
+    return fail(`${root}: ${found.error}`, EXIT.CONFIG, 'pass --root <path>');
+  }
+  if (found.repos.length === 0) {
+    return fail(
+      `${root} contains no git repositories`,
+      EXIT.CONFIG,
+      `point --root at the directory holding the repos, or at one repo to see just it`,
+    );
+  }
+
+  const expectedSha = await provenanceDigest();
+  const context = { expectedSha, gates: new Set(Object.keys(GATES)), gateKinds: GATE_KINDS };
+
+  // Sequential on purpose. 16 fingerprint+region computations each spawn a git
+  // process; running them concurrently produces a burst of subprocesses and no
+  // measurable speedup, because the work is process-spawn bound rather than CPU
+  // bound. Determinism of the output matters more than wall clock on a dashboard.
+  const rows = [];
+  for (const repo of found.repos) rows.push(await buildRow(repo, context));
+
+  const summary = summarise(rows, {
+    root,
+    shape: found.shape,
+    source: target.source,
+    expectedSha,
+    worktrees: found.worktrees.length,
+    directories: found.directories.length,
+  });
+
+  if (isJson(flags)) {
+    emitJson({
+      ok: !rows.some((r) => r.problems.length > 0),
+      command: 'compare',
+      root: summary.root,
+      shape: summary.shape,
+      source: summary.source,
+      expectedSha: summary.expectedSha,
+      // Spread, not a hand-listed copy. A copy is a second place to forget: a field
+      // added to `summarise` renders in the text output and silently vanishes from
+      // `--json`, which is the combination automation trusts most. That is not
+      // hypothetical — `withOwnHooks` and `staleRuleFiles` both did it, and both
+      // were caught only because a test asserts the two shapes agree.
+      summary: {
+        repos: summary.repos,
+        adopted: summary.adopted,
+        unmanaged: summary.unmanaged,
+        broken: summary.broken,
+        drifted: summary.drifted,
+        current: summary.current,
+        noRegion: summary.noRegion,
+        malformed: summary.malformed,
+        staleRuleFiles: summary.staleRuleFiles,
+        hooksRouted: summary.hooksRouted,
+        withProblems: summary.withProblems,
+        withOwnHooks: summary.withOwnHooks,
+        shas: summary.shas,
+      },
+      rows,
+      worktrees: found.worktrees.map((w) => ({
+        name: w.name,
+        path: w.path,
+        owner: w.ownerName,
+        ownerMatchesDirName: w.ownerMatches,
+      })),
+      directories: found.directories.map((d) => basename(d)),
+    });
+    return rows.some((r) => r.problems.length > 0) ? EXIT.FAIL : EXIT.OK;
+  }
+
+  emit(render(rows, summary, found), { maxBytes: flags.maxBytes ?? 0 });
+  if (summary.shape === 'repo') {
+    note('note     one repository compared; pass --root at a workspace directory to compare its siblings');
+  } else if (target.source === 'none') {
+    note(`note     no workspace configured, so this compared the current directory; ${WORKSPACE_REMEDY}`);
+  }
+  for (const w of found.worktrees) {
+    // A worktree is reported, not compared. Its files are the parent repo's HEAD
+    // checked out elsewhere, so its projection state is the parent's - reporting
+    // it as an independent consumer would double-count one repo's drift.
+    note(`note     ${w.name} is a worktree of ${w.ownerName ?? '(unknown)'}, not compared separately`);
+    if (!w.ownerMatches) {
+      note(`note     ${w.name}: git slug does not match its directory name; owner inferred from the gitdir path`);
+    }
+  }
+  if (found.directories.length > 0) {
+    note(
+      `note     ${found.directories.length} non-repo director${found.directories.length === 1 ? 'y' : 'ies'}: ${found.directories.map((d) => basename(d)).join(', ')}`,
+    );
+  }
+  return rows.some((r) => r.problems.length > 0) ? EXIT.FAIL : EXIT.OK;
+}
+
+/**
+ * Fixed field order, one repo per block. A single aligned table would be prettier
+ * and worse: variable-length stacks and gate lists force padding that breaks on
+ * the longest value, and an agent cannot tell which column is which without
+ * counting spaces.
+ */
+function render(rows, summary, found) {
+  const lines = [
+    // `workspace` and `repo` are the same field with different names, and the name is the
+    // honest one: a reader who sees "workspace" and gets one repo was told a lie. `root`
+    // plus `shape` is the one reading that is true in both cases (ADR-014).
+    `${summary.shape === 'repo' ? 'repo     ' : 'workspace'} ${summary.root}`,
+    `shape    ${summary.shape}${summary.shape === 'workspace' ? ` (root from ${summary.source})` : ''}`,
+    `simt-dev  ${summary.expectedSha}`,
+    `repos     ${summary.repos} (${summary.adopted} adopted, ${summary.unmanaged} unmanaged${summary.broken > 0 ? `, ${summary.broken} broken` : ''})`,
+    `region    ${summary.current} current, ${summary.drifted} drifted, ${summary.noRegion} with no region, ${summary.malformed} malformed`,
+    `rules     ${summary.staleRuleFiles === 0 ? 'every rule file current' : `${summary.staleRuleFiles} rule file${summary.staleRuleFiles === 1 ? '' : 's'} not current`}`,
+    `hooks     ${summary.hooksRouted}/${summary.adopted} adopted repos route the shared dispatcher`,
+    `          ${summary.withOwnHooks} repo${summary.withOwnHooks === 1 ? '' : 's'} run their own hooks; adopting replaces them (a note, not a problem)`,
+    `problems  ${summary.withProblems} repo${summary.withProblems === 1 ? '' : 's'}`,
+    `pinned    ${summary.shas.map(([sha, n]) => `${sha} x${n}`).join(', ')}`,
+    '',
+  ];
+
+  for (const r of rows) {
+    lines.push(`repo      ${r.name}`);
+    lines.push(`          adoption ${r.adoption}${r.id && r.id !== r.name ? ` (id ${r.id})` : ''}`);
+    lines.push(`          stack   ${r.stack.length > 0 ? r.stack.join(', ') : '(none)'}${r.declaredStack.length > 0 ? ` (manifest declares ${r.declaredStack.join(', ')})` : ''}`);
+    if (r.facts.length > 0) lines.push(`          facts   ${r.facts.join(', ')}`);
+    lines.push(`          region  ${r.region}${r.regionDetail ? ` (${r.regionDetail})` : ''}`);
+    // The rule files are the answer to "does every editor see the same rule?".
+    lines.push(
+      `          rules   ${r.ruleFiles.total === 0 ? '(none)' : `${r.ruleFiles.current}/${r.ruleFiles.total} current`}${r.ruleFiles.stale.length > 0 ? ` - ${r.ruleFiles.stale.join(', ')}` : ''}`,
+    );
+    lines.push(`          sha     pinned ${r.pinnedSha ?? '(none)'} region ${r.recordedSha ?? '(none)'}`);
+    lines.push(
+      `          hooks   ${r.hooksRouted ? 'shared dispatcher' : r.adoption === 'adopted' ? 'NOT ROUTED' : '(n/a)'}${r.hooksRouted && !r.hooksComplete ? ' (incomplete)' : ''}`,
+    );
+    lines.push(
+      `          gates   ${r.gatesDeclared.length > 0 ? r.gatesDeclared.join(', ') : r.adoption === 'adopted' ? '(none declared)' : '(n/a)'}`,
+    );
+    if (r.problems.length > 0) {
+      lines.push('          PROBLEMS');
+      for (const p of r.problems) lines.push(`            ${p}`);
+    }
+    if (r.notes.length > 0) {
+      for (const n of r.notes) lines.push(`          note ${n}`);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n').trimEnd();
+}
+
+export { discover };

simt_dev/vendored/src/commands/graph.mjs

@@ -0,0 +1,73 @@
+// `simt-dev graph lint` - verify the hand-authored registry against reality.
+//
+// Implementation sequence step 2. This command is the reason hand-authoring the
+// registry is safe: 38 nodes across 6 repos is bookkeeping that rots silently.
+//
+// Output is line-oriented and bounded (plan 0002 section 6). A lint failure names
+// the offending node, the file it disagrees with, and both numbers.
+
+import { EXIT, emit, fail, isJson } from '../output/index.mjs';
+import { loadRegistry, REGISTRY_PATH } from '../graph/load.mjs';
+
+export async function lintCommand(positional, flags) {
+  const path = positional[0] ?? REGISTRY_PATH;
+  const { ok, registry, errors, warnings, verified, workspace } = await loadRegistry(path, flags);
+
+  if (isJson(flags)) {
+    emit(
+      `${JSON.stringify(
+        {
+          ok,
+          registry: path,
+          capabilities: registry?.capabilities?.length ?? 0,
+          skills: registry?.skills?.length ?? 0,
+          // `verified: false` means the byte counts in the registry were NOT
+          // checked against files on disk. It is not a failure - it is the difference
+          // between "the registry is right" and "the registry could not be checked",
+          // and an agent that cannot see the difference will trust a number nobody
+          // measured (ADR-014).
+          verified,
+          workspace,
+          errors,
+          warnings,
+        },
+        null,
+        2,
+      )}\n`,
+      { maxBytes: flags.maxBytes ?? 0 },
+    );
+    return ok ? EXIT.OK : EXIT.REGISTRY;
+  }
+
+  if (!registry) {
+    return fail(errors[0] ?? `${path}: unreadable`, EXIT.REGISTRY);
+  }
+
+  const lines = [
+    `registry  ${path}`,
+    `nodes     ${registry.skills.length} skills, ${registry.capabilities.length} capabilities`,
+    `verified  ${verified ? 'byte counts checked against disk' : 'NOT checked - see WARN below'}`,
+  ];
+
+  const deferred = registry.skills.filter((s) => s.deferred);
+  lines.push(
+    `deferred  ${deferred.length} over ${registry.deferredThreshold} bytes ` +
+      `(${deferred.map((s) => s.name).join(', ') || 'none'})`,
+  );
+
+  if (warnings.length > 0) {
+    lines.push('', `WARN ${warnings.length}`);
+    for (const warning of warnings) lines.push(`  ${warning}`);
+  }
+
+  if (errors.length > 0) {
+    lines.push('', `FAIL ${errors.length}`);
+    for (const error of errors) lines.push(`  ${error}`);
+    emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+    return EXIT.REGISTRY;
+  }
+
+  lines.push('', verified ? 'OK no findings' : 'OK structural checks only');
+  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
+}

simt_dev/vendored/src/commands/help.mjs

@@ -0,0 +1,108 @@
+import { emit } from '../output/index.mjs';
+import { parse } from '../argv.mjs';
+import { CLI } from '../name.mjs';
+
+const COMMANDS = `${CLI} init [path]            adopt or scaffold a repo into the ecosystem
+                           (dry-run unless --yes; conflicts block without
+                           --accept-conflicts; never commits or pushes)
+${CLI} doctor                 classify a repo and check config health
+${CLI} check                  the gate: projection drift, manifest validity, policy
+${CLI} sync [--yes]           regenerate the projection (idempotent)
+                           (prints the plan and exits 1 on drift without --yes,
+                           so it also works as a check)
+${CLI} upgrade                move every consumer to this simt-dev SHA, as one set
+                           (dry-run unless --yes; moves a pin only - it never
+                           adopts or repairs a repo; never commits or pushes)
+
+${CLI} skills index           tier-0 catalog: every skill, one line each
+${CLI} skills brief --task    tier-1 pre-assembled brief  <- the common case
+${CLI} skills show <name>     tier-2 body (respects --max-bytes)
+${CLI} skills why <name>      the signal chain that selected it
+${CLI} skills find <query>    search across capability and keyword
+${CLI} skills install <name>  pin a skill into the repo as a local override
+                           (dry-run unless --yes; a multi-variant skill needs
+                           --variant or --from rather than a guess)
+
+${CLI} rules list             the rule catalogue (--root marks what applies to a repo)
+${CLI} rules show <id>        one rule body
+${CLI} rules why <id|ADR-NNN> the decision that settled it, and whether it is still in force
+${CLI} hooks install [--yes]   install the shared dispatcher; report what it would run
+                           (dry-run unless --yes; refuses to take over routing git
+                            already uses, and --yes is that consent)
+${CLI} ci                     simt-dev's own .github files: create or refresh them
+                           (dry-run unless --yes; refreshes the templates' own copies
+                            and no repository else's)
+${CLI} compare                org-wide matrix across every sibling repo
+                           (read-only; exits non-zero on defects, not on
+                           repos that have not adopted yet)
+${CLI} mcp                    the read-only surface as MCP tools over stdio
+                           (--list prints it without reading stdin; init, sync,
+                           upgrade and the installers stay CLI-only by design)`;
+
+const FLAGS = `--json                 structured output
+--max-bytes <n>         hard ceiling on emitted bytes (0 = unlimited, default 0)
+--budget <n>            context budget for skills brief (default 20480)
+--plan                  emit a fetch plan instead of inlining skill bodies
+--skill <name>          force a skill into the brief (repeatable)
+--task "<text>"         the task text used for capability resolution
+--paths <globs>         comma-separated path globs used for path resolution
+--root <path>           repository root (default: cwd)
+--surfaces <ids>        comma-separated editors to write rule files for;
+                         "" means AGENTS.md only (default: every surface,
+                         or the "surfaces" list in simt-dev.json)
+--workspace <path>      where the skill sources live; "off" declines it
+                        (default: SIMT_DEV_WORKSPACE, then the user config
+                        file, then the sibling heuristic if it verifies)
+--dry-run               report what would change, change nothing
+--yes                   assume yes; required in automation, never prompts
+--all                   ignore the budget and resolve everything
+--variant <id>          which body of a multi-variant skill to use
+--from <repo/path>      install from a declared source by name`;
+
+const PRINCIPLES = `design rules:
+  deterministic       same repo + same task = same answer, forever
+  explainable         skills why prints the signal chain for any selection;
+                      rules why prints the decision behind any rule
+  zero dependencies   a DX tool that needs an install step fails on a fresh machine
+  bounded output      one fact per line, fixed field order, explicit TRUNCATED lines`;
+
+export async function help(argv) {
+  const { ok, value } = parse(argv);
+  if (!ok) return value.code;
+  const { flags } = value;
+  if (flags.version) {
+    emit((await version()).trim());
+    return 0;
+  }
+  emit(
+    [
+      'simt-dev - shared agent rules, skills and gates for a repo ecosystem',
+      '',
+      'usage: simt-dev <command> [args] [flags]',
+      '',
+      'commands:',
+      COMMANDS,
+      '',
+      'flags:',
+      FLAGS,
+      '',
+      PRINCIPLES,
+      '',
+      // The plans ship inside the installed package but have no command that surfaces
+      // them, so naming the path would again be advice the reader cannot take. They
+      // are an implementation record; the rulings are the part a reader can act on.
+      `rulings  ${CLI} rules list   the decisions behind the rules you just read`,
+    ].join('\n'),
+    { maxBytes: flags.maxBytes ?? 0 },
+  );
+  return 0;
+}
+
+async function version() {
+  const { readFile } = await import('node:fs/promises');
+  const { fileURLToPath } = await import('node:url');
+  const { dirname, join } = await import('node:path');
+  const root = join(dirname(fileURLToPath(import.meta.url)), '..');
+  const pkg = JSON.parse(await readFile(join(root, '..', 'package.json'), 'utf8'));
+  return `simt-dev ${pkg.version}\n`;
+}