simt-dev 0.6.3 → 0.7.1

package/src/commands/agent.mjs

@@ -0,0 +1,205 @@
+// simt agents install | simt agents status
+//
+// Two commands, one subject: the one agent this tool ships, written into each
+// harness's own agents directory. `install` writes the file, and `status`
+// reports what each harness carries and what still has to be installed.
+//
+// An agent is a file the tool owns whole — markdown with a frontmatter the
+// harness documents, or a TOML file for Codex — not a config entry to merge.
+// So the install is a byte comparison: created, unchanged, updated. There is no
+// parse that can fail and no partial state, which is what makes this command
+// shorter than `agent-hooks install`.
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { commitJournal } from '../journal.mjs';
+import { diffField, emitDiffs, readBefore } from '../diff.mjs';
+import { EXIT, emit, emitJson, fail, isJson, note, writeMode } from '../output/index.mjs';
+import { CLI } from '../name.mjs';
+import {
+  adapter,
+  adapters,
+  agentPath,
+  agentRows,
+  loadAgent,
+  planAgents,
+  rendered,
+  writeAgentPlan,
+} from '../agents/render.mjs';
+import { commandRoot } from '../repo-root.mjs';
+
+export async function agentsCommand(sub, args, flags) {
+  const root = commandRoot(flags, args);
+  if (sub === 'install') return installAgents(root, flags);
+  if (sub === 'status') return agentsStatus(root, flags);
+  return fail(`unknown agents subcommand ${sub}`, EXIT.USAGE, `run: ${CLI} agents status`);
+}
+
+// The label for a reader the run did not write, by the state that names why:
+// `none` documents no agents file, `other` is a reader this tool does not write,
+// `skipped` was an adapter the caller did not ask for (ADR-107).
+const OTHER_LABEL = { none: 'NO FILE ', other: 'NOT OURS', skipped: 'SKIPPED ' };
+
+async function installAgents(root, flags) {
+  const mode = writeMode(flags);
+  // `--harness` narrows the install to one reader (ADR-107). The id is validated
+  // against the same table the loop reads, so a typo fails before anything is
+  // planned; the remedy names the ids the way `agent-hook` does.
+  const selected = flags.harness;
+  if (selected !== undefined && adapter(selected) === null) {
+    return fail(
+      `unknown harness \`${selected}\``,
+      EXIT.USAGE,
+      `--harness <id>, one of: ${adapters().map((a) => a.id).join(', ')}`,
+    );
+  }
+
+  const plan = await planAgents(root, { harness: selected });
+
+  // The readers this tool does not write a file for, reported rather than skipped in
+  // silence: a command that writes six files and says nothing about the two harnesses
+  // that document no agents file reads as "those are covered too". A narrowed install
+  // adds a third state: an adapter that is this tool's but was not requested (ADR-107).
+  const others = [];
+  for (const r of agentRows()) {
+    if (r.path === null) others.push({ id: r.id, path: null, state: 'none', note: r.note });
+    else if (adapter(r.id) === null) others.push({ id: r.id, path: r.path, state: 'other', note: r.note });
+    else if (selected !== undefined && r.id !== selected) {
+      others.push({ id: r.id, path: r.path, state: 'skipped', note: 'not requested; install without --harness to write every harness' });
+    }
+  }
+
+  // The `--diff` pairs, read before anything is written so the before side is
+  // true in preview and in apply alike (R50).
+  const diffs =
+    flags.diff === true
+      ? await Promise.all(
+        plan
+          .filter((p) => p.action !== 'unchanged')
+          .map(async (p) => ({ path: p.path, before: await readBefore(join(root, p.path)), after: p.text })),
+      )
+      : [];
+
+  if (!mode.apply) {
+    if (isJson(flags)) {
+      emitJson({
+        ok: true,
+        command: 'agents install',
+        root,
+        dryRun: true,
+        plan: plan.map(({ text, ...rest }) => rest),
+        notWritten: others,
+        filesWritten: false,
+        ...diffField(diffs, flags),
+      });
+      return EXIT.OK;
+    }
+    emit(
+      [
+        `repo     ${root}`,
+        ...plan.map((p) => `${p.action.toUpperCase().padEnd(9)} ${p.id.padEnd(12)} ${p.path}`),
+        ...others.map((o) => `${OTHER_LABEL[o.state]} ${o.id.padEnd(12)} ${o.path ?? '(no agents file is documented)'}`),
+        '',
+        `PLAN     nothing written; apply with: ${CLI} agents install --yes`,
+      ].join('\n'),
+    );
+    // After the report: the report says what, the diff shows it (R50).
+    emitDiffs(diffs, flags);
+    return EXIT.OK;
+  }
+
+  // Journaled so `undo` restores this run (R49).
+  const journal = [];
+  const written = await writeAgentPlan(root, journal, plan);
+  await commitJournal(root, 'agents install', journal);
+
+  if (isJson(flags)) {
+    emitJson({
+      ok: true,
+      command: 'agents install',
+      root,
+      plan: plan.map(({ text, ...rest }) => rest),
+      notWritten: others,
+      written,
+      filesWritten: true,
+      ...diffField(diffs, flags),
+    });
+    return EXIT.OK;
+  }
+  emit(
+    [
+      `repo     ${root}`,
+      ...plan.map((p) => `${p.action.toUpperCase().padEnd(9)} ${p.id.padEnd(12)} ${p.path}`),
+      ...others.map((o) => `${OTHER_LABEL[o.state]} ${o.id.padEnd(12)} ${o.path ?? '(no agents file is documented)'}`),
+      '',
+      `WROTE    ${written.length} agent file(s)`,
+    ].join('\n'),
+  );
+  // After the report: the report says what, the diff shows it (R50).
+  emitDiffs(diffs, flags);
+  for (const o of others) note(`note     ${o.id}: not written - ${o.note}`);
+  if (written.length === 0) note('note     every documented agents file already carried this agent');
+  note(`note     never committed or pushed (ADR-001); review, then commit yourself`);
+  return EXIT.OK;
+}
+
+async function agentsStatus(root, flags) {
+  const agent = await loadAgent();
+  const rows = [];
+  const problems = [];
+
+  // The file this tool owns whole is compared against what `install` would write
+  // right now, so status reads the same bytes install reads: a file that matches
+  // the preview is present, anything else is drift an install will rewrite.
+  for (const row of adapters()) {
+    const path = agentPath(row.id);
+    const existing = await readIfExists(join(root, path));
+    if (existing === null) {
+      rows.push({ id: row.id, path, state: 'absent', note: null });
+      continue;
+    }
+    const present = rendered(row, agent, existing).action === 'unchanged';
+    rows.push({
+      id: row.id,
+      path,
+      state: present ? 'present' : 'drift',
+      note: present ? null : 'differs from what install would write; run install to restore it',
+    });
+  }
+
+  // The readers whose agents are not a file this tool can write — a vendor page
+  // that documents none — are reported from the same table that documents them,
+  // rather than from a second list of the harnesses this command happens to know.
+  for (const r of agentRows()) {
+    if (r.path === null) rows.push({ id: r.id, path: null, state: 'none', note: r.note });
+    else if (adapter(r.id) === null) rows.push({ id: r.id, path: r.path, state: 'other', note: r.note });
+  }
+
+  if (isJson(flags)) {
+    emitJson({ ok: problems.length === 0, command: 'agents status', root, harnesses: rows, problems });
+    return problems.length === 0 ? EXIT.OK : EXIT.FAIL;
+  }
+
+  const lines = [`repo     ${root}`];
+  for (const r of rows) {
+    const state = { present: 'PRESENT ', absent: 'ABSENT  ', drift: 'DRIFT   ', none: 'NO FILE ', other: 'NOT OURS' }[r.state];
+    lines.push(`${state} ${r.id.padEnd(12)} ${r.path ?? '(no agents file is documented)'}`);
+    if (r.state === 'absent') lines.push(`          ${' '.repeat(12)} install: ${CLI} agents install --yes`);
+    if (r.note) lines.push(`          ${' '.repeat(12)} ${r.note}`);
+  }
+  if (problems.length > 0) {
+    lines.push('', 'problems:');
+    for (const p of problems) lines.push(`  ${p}`);
+  }
+  emit(lines.join('\n'));
+  return problems.length === 0 ? EXIT.OK : EXIT.FAIL;
+}
+
+async function readIfExists(path) {
+  try {
+    return await readFile(path, 'utf8');
+  } catch {
+    return null;
+  }
+}

package/src/commands/agenthook.mjs

@@ -22,15 +22,18 @@
 // tool call. Failures of this command exit 1, which a harness reports as a failed hook,
 // and that is the right blast radius for a hook that is broken rather than refusing.
 
+import { existsSync } from 'node:fs';
 import { mkdir, readFile } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
+import { dirname, isAbsolute, join } from 'node:path';
 import { commitJournal, journaledWriteFile } from '../journal.mjs';
+import { AGENT_HOOK_SHIM, renderAgentHookShim } from '../agenthooks/shim.mjs';
 import { diffField, emitDiffs, readBefore } from '../diff.mjs';
 
 import { EXIT, emit, emitJson, fail, isJson, note, writeMode } from '../output/index.mjs';
-import { CLI } from '../name.mjs';
-import { ALLOW_ENV, EVENTS, POLICY_IDS } from '../agenthooks/policy.mjs';
+import { CLI, MANIFEST_FILE, MANIFEST_LEGACY } from '../name.mjs';
+import { ALLOW_ENV, EVENTS, POLICY_IDS, SESSION_ENV } from '../agenthooks/policy.mjs';
 import { decide, factsFor } from '../agenthooks/decide.mjs';
+import { repoRoot } from '../repo-root.mjs';
 import {
   adapter,
   adapters,
@@ -41,6 +44,7 @@ import {
   installedIn,
   rendered,
 } from '../agenthooks/render.mjs';
+import { commandRoot } from '../repo-root.mjs';
 
 export async function agentHookCommand(args, flags) {
   const event = args[0];
@@ -74,7 +78,7 @@ export async function agentHookCommand(args, flags) {
   // dynamic import that only this event opens.
   if (event === 'prompt-submit') {
     const { deliverPrompt } = await import('../agenthooks/prompt.mjs');
-    const delivered = await deliverPrompt(row, payload);
+    const delivered = await deliverPrompt(row, payload, { root: flags.root });
     if (delivered.skipped) {
       note(`note     ${id}: no packet delivered (${delivered.skipped})`);
       return EXIT.OK;
@@ -97,10 +101,33 @@ export async function agentHookCommand(args, flags) {
   // `--root` outranks the payload: a packaged hook runs from the plugin directory and the
   // harness's environment variable names the project, so a payload cwd that is the plugin's
   // own working directory must not win. The repository-install path passes no flag, and the
-  // payload's cwd is what the harness reports.
-  const { root, command, writes } = factsFrom(row, payload, { root: flags.root });
-  const facts = await factsFor(root, { command, writes });
-  const decision = decide({ event, facts, env: process.env });
+  // payload's cwd is what the harness reports. The answer is then resolved to the
+  // repository's top level: a harness reports the directory it happens to be in, and an
+  // agent works from subdirectories, so every repository-relative fact (the lease file,
+  // `.gitmodules`) must resolve against the root git itself uses, not the cwd (review
+  // 0003 Q16).
+  const { root: payloadRoot, command, writes, session: payloadSession } = factsFrom(row, payload, { root: flags.root });
+  const root = repoRoot(payloadRoot);
+  // A relative write path is relative to the directory the harness is in, not to the
+  // repository root the facts resolve against: an agent editing `keep.mjs` from `src/`
+  // means `src/keep.mjs`, and a path joined to the wrong base is a path the lease file
+  // will never meet (review 0003 Q16).
+  // Writes are `{path, ...edit}` rows (Q17): the path resolves against the harness
+  // cwd, the edit detail travels untouched so the region check sees the old_string.
+  const writesAbsolute = writes.map((w) => {
+    const path = typeof w === 'string' ? w : w?.path;
+    const abs = typeof path === 'string' && isAbsolute(path) ? path : join(payloadRoot, path);
+    return typeof w === 'string' ? abs : { ...w, path: abs };
+  });
+  const facts = await factsFor(root, { command, writes: writesAbsolute });
+  // Harness hook processes rarely carry SIMT_SESSION, so the payload's own
+  // session id is the fallback: without it an agent is blocked by its own
+  // lease (review 0003 Q20). The environment still wins when it names one.
+  const session =
+    typeof process.env[SESSION_ENV] === 'string' && process.env[SESSION_ENV] !== ''
+      ? process.env[SESSION_ENV]
+      : (payloadSession ?? '');
+  const decision = decide({ event, facts, env: { ...process.env, [SESSION_ENV]: session } });
 
   // Both notes are about a conclusion the author is about to draw: a lift that did
   // nothing because of a typo, and a lift that is the reason the command they expected to
@@ -115,7 +142,11 @@ export async function agentHookCommand(args, flags) {
   const json = decisionJson(row, decision);
   if (json === null) return EXIT.OK;
 
-  if (root) {
+  // A denial is recorded only for a repository that adopted the tool: hook
+  // denials in a never-adopted repo are noise about someone else's policy, and
+  // that is how an unadopted checkout accumulated 23 candidates nobody would
+  // ever promote (review 0003 Q36). The manifest is the adoption mark.
+  if (root && (existsSync(join(root, MANIFEST_FILE)) || existsSync(join(root, MANIFEST_LEGACY)))) {
     try {
       const { recordHookDenial } = await import('../memory/lessons.mjs');
       await recordHookDenial(root, {
@@ -137,14 +168,30 @@ export async function agentHookCommand(args, flags) {
 }
 
 export async function agentHooksCommand(sub, args, flags) {
-  const root = flags.root ?? args[0] ?? process.cwd();
+  const root = commandRoot(flags, args);
   if (sub === 'install') return installHooks(root, flags);
   if (sub === 'status') return hooksStatus(root, flags);
   return fail(`unknown agent-hooks subcommand ${sub}`, EXIT.USAGE, `run: ${CLI} agent-hooks status`);
 }
 
+// The label for a reader the run did not write, by the state that names why:
+// `none` documents no hooks file, `other` is a reader this tool does not write,
+// `skipped` was an adapter the caller did not ask for (ADR-107).
+const OTHER_LABEL = { none: 'NO FILE ', other: 'NOT OURS', skipped: 'SKIPPED ' };
+
 async function installHooks(root, flags) {
   const mode = writeMode(flags);
+  // `--harness` narrows the install to one reader (ADR-107). The id is validated
+  // against the same table the loop reads, so a typo fails before anything is
+  // planned; the remedy names the ids the way `agent-hook` does.
+  const selected = flags.harness;
+  if (selected !== undefined && adapter(selected) === null) {
+    return fail(
+      `unknown harness \`${selected}\``,
+      EXIT.USAGE,
+      `--harness <id>, one of: ${adapters().map((a) => a.id).join(', ')}`,
+    );
+  }
   // The delivery is a second entry in the same config, and a repository asks for it by
   // declaring a `brief` key rather than by having the entry. Read through a dynamic
   // import for the same reason the hook delivers through one.
@@ -155,8 +202,9 @@ async function installHooks(root, flags) {
     listPromotedLessons(root).catch(() => []),
   ]);
   const hasLessons = promotedLessons.length > 0;
+  const rows = selected === undefined ? adapters() : adapters().filter((r) => r.id === selected);
   const plan = [];
-  for (const row of adapters()) {
+  for (const row of rows) {
     const path = hookPath(row.id);
     const existing = await readIfExists(join(root, path));
     const result = rendered(row, existing, { prompt: optIn.optedIn, post: hasLessons });
@@ -178,15 +226,28 @@ async function installHooks(root, flags) {
 
   // The readers this tool does not write an entry for, reported rather than skipped in
   // silence: a command that writes four files and says nothing about the fifth harness
-  // in the repository reads as "that one is covered too".
+  // in the repository reads as "that one is covered too". A narrowed install adds a
+  // third state: an adapter that is this tool's but was not requested (ADR-107).
   const others = [];
   for (const r of hookRows()) {
     if (r.path === null) others.push({ id: r.id, path: null, state: 'none', note: r.note });
     else if (adapter(r.id) === null) others.push({ id: r.id, path: r.path, state: 'other', note: r.note });
+    else if (selected !== undefined && r.id !== selected) {
+      others.push({ id: r.id, path: r.path, state: 'skipped', note: 'not requested; install without --harness to write every harness' });
+    }
   }
 
   const refused = plan.filter((p) => p.error);
 
+  // The shim every harness config points at: without it the entries above name a
+  // binary no harness has on PATH (review 0003 Q21). Its remedy installs the
+  // dependency the same way the git shims' does — a devDependency where the
+  // repository has a package.json, the release binary where it does not.
+  const shimText = renderAgentHookShim({ npm: (await readIfExists(join(root, 'package.json'))) !== null });
+  const shimBefore = await readBefore(join(root, AGENT_HOOK_SHIM));
+  const shimAction = shimBefore === null ? 'create' : shimBefore === shimText ? 'unchanged' : 'update';
+  const shimRow = { id: 'shim', path: AGENT_HOOK_SHIM, action: shimAction };
+
   // The `--diff` pairs, read before anything is written so the before side is
   // true in preview and in apply alike (R50).
   const diffs =
@@ -194,7 +255,8 @@ async function installHooks(root, flags) {
       ? await Promise.all(
         plan
           .filter((p) => p.action !== 'unchanged')
-          .map(async (p) => ({ path: p.path, before: await readBefore(join(root, p.path)), after: p.text })),
+          .map(async (p) => ({ path: p.path, before: await readBefore(join(root, p.path)), after: p.text }))
+          .concat(shimAction === 'unchanged' ? [] : [{ path: AGENT_HOOK_SHIM, before: shimBefore, after: shimText }]),
       )
       : [];
 
@@ -206,6 +268,7 @@ async function installHooks(root, flags) {
         root,
         dryRun: true,
         plan: plan.map(({ text, ...rest }) => rest),
+        shim: shimRow,
         notWritten: others,
         filesWritten: false,
         ...diffField(diffs, flags),
@@ -216,14 +279,14 @@ async function installHooks(root, flags) {
       [
         `repo     ${root}`,
         ...plan.map((p) => `${p.action.toUpperCase().padEnd(9)} ${p.id.padEnd(12)} ${p.path}${p.error ? `  (${p.error})` : ''}`),
-        ...others.map((o) => `${o.state === 'none' ? 'NO FILE ' : 'NOT OURS'} ${o.id.padEnd(12)} ${o.path ?? '(no hooks file is documented)'}`),
+        `${shimAction.toUpperCase().padEnd(9)} shim         ${AGENT_HOOK_SHIM}`,
+        ...others.map((o) => `${OTHER_LABEL[o.state]} ${o.id.padEnd(12)} ${o.path ?? '(no hooks file is documented)'}`),
         ...promptLine,
         '',
         refused.length > 0
           ? `REFUSED  ${refused.length} config file(s) could not be read; nothing written`
           :        `PLAN     nothing written; apply with: ${CLI} agent-hooks install --yes`,
       ].join('\n'),
-      { maxBytes: flags.maxBytes ?? 0 },
     );
     // After the report: the report says what, the diff shows it (R50).
     emitDiffs(diffs, flags);
@@ -245,6 +308,14 @@ async function installHooks(root, flags) {
     await journaledWriteFile(root, journal, join(root, p.path), p.text);
     written.push(p);
   }
+  // The shim is a file like the configs: unchanged installs leave it alone, and a
+  // changed one is journaled so `undo` removes or restores it with the configs.
+  let shimWritten = false;
+  if (shimAction !== 'unchanged') {
+    await mkdir(join(root, dirname(AGENT_HOOK_SHIM)), { recursive: true });
+    await journaledWriteFile(root, journal, join(root, AGENT_HOOK_SHIM), shimText, { mode: 0o755 });
+    shimWritten = true;
+  }
   await commitJournal(root, 'agent-hooks install', journal);
 
   const notes = [];
@@ -260,6 +331,7 @@ async function installHooks(root, flags) {
       command: 'agent-hooks install',
       root,
       plan: plan.map(({ text, ...rest }) => rest),
+      shim: { ...shimRow, written: shimWritten },
       notWritten: others,
       written: written.map((p) => p.path),
       filesWritten: true,
@@ -272,12 +344,12 @@ async function installHooks(root, flags) {
     [
       `repo     ${root}`,
       ...plan.map((p) => `${p.action.toUpperCase().padEnd(9)} ${p.id.padEnd(12)} ${p.path}`),
-      ...others.map((o) => `${o.state === 'none' ? 'NO FILE ' : 'NOT OURS'} ${o.id.padEnd(12)} ${o.path ?? '(no hooks file is documented)'}`),
+      `${shimAction.toUpperCase().padEnd(9)} shim         ${AGENT_HOOK_SHIM}`,
+      ...others.map((o) => `${OTHER_LABEL[o.state]} ${o.id.padEnd(12)} ${o.path ?? '(no hooks file is documented)'}`),
       ...promptLine,
       '',
-      `WROTE    ${written.length} hooks file(s); each one runs ${CLI} agent-hook before the tool call`,
+      `WROTE    ${written.length} hooks file(s)${shimWritten ? ' and the shim' : ''}; each one runs the ${AGENT_HOOK_SHIM} shim before the tool call`,
     ].join('\n'),
-    { maxBytes: flags.maxBytes ?? 0 },
   );
   // After the report: the report says what, the diff shows it (R50).
   emitDiffs(diffs, flags);
@@ -290,10 +362,31 @@ async function installHooks(root, flags) {
 async function hooksStatus(root, flags) {
   const rows = [];
   const problems = [];
+  // The plugin file this tool owns whole is compared against what `install` would write
+  // right now, so status reads the same opt-in install reads: a file that matches the
+  // preview is present, anything else is drift an install will rewrite.
+  const { promptOptIn } = await import('../agenthooks/prompt.mjs');
+  const optIn = await promptOptIn(root);
 
   for (const row of adapters()) {
     const path = hookPath(row.id);
     const existing = await readIfExists(join(root, path));
+    if (row.file) {
+      if (existing === null) {
+        rows.push({ id: row.id, path, state: 'absent', entries: 0, prompt: row.prompt ? 'absent' : null, note: null });
+      } else {
+        const present = rendered(row, existing, { prompt: optIn.optedIn }).action === 'unchanged';
+        rows.push({
+          id: row.id,
+          path,
+          state: present ? 'present' : 'drift',
+          entries: present ? 1 : 0,
+          prompt: row.prompt ? (present && optIn.optedIn ? 'present' : 'absent') : null,
+          note: present ? null : 'differs from what install would write; run install to restore it',
+        });
+      }
+      continue;
+    }
     if (existing === null) {
       rows.push({ id: row.id, path, state: 'absent', entries: 0, prompt: row.prompt ? 'absent' : null, note: null });
       continue;
@@ -341,7 +434,7 @@ async function hooksStatus(root, flags) {
 
   const lines = [`repo     ${root}`];
   for (const r of rows) {
-    const state = { present: 'PRESENT ', absent: 'ABSENT  ', unreadable: 'INVALID ', none: 'NO FILE ', other: 'NOT OURS' }[r.state];
+    const state = { present: 'PRESENT ', absent: 'ABSENT  ', unreadable: 'INVALID ', drift: 'DRIFT   ', none: 'NO FILE ', other: 'NOT OURS' }[r.state];
     lines.push(`${state} ${r.id.padEnd(12)} ${r.path ?? '(no hooks file is documented)'}`);
     if (r.state === 'absent') lines.push(`          ${' '.repeat(12)} install: ${CLI} agent-hooks install --yes`);
     // The second event is a separate answer to a separate question: a harness can carry
@@ -354,7 +447,7 @@ async function hooksStatus(root, flags) {
     lines.push('', 'problems:');
     for (const p of problems) lines.push(`  ${p}`);
   }
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   return problems.length === 0 ? EXIT.OK : EXIT.FAIL;
 }