simt-dev 0.6.3 → 0.7.1

package/src/commands/init.mjs

@@ -18,7 +18,7 @@
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { mkdir, readFile, symlink } from 'node:fs/promises';
-import { commitJournal, journaledWriteFile } from '../journal.mjs';
+import { commitJournal, ignoreJournal, journaledWriteFile } from '../journal.mjs';
 import { invalidateCheckCache } from '../status.mjs';
 import { dirname, join } from 'node:path';
 
@@ -31,10 +31,12 @@ import { readCapability } from '../hooks/capability.mjs';
 import { readHooksState } from '../compare/hooksstate.mjs';
 import { planWorkflow, renderWorkflow, WORKFLOWS_DIR } from '../ci/workflow.mjs';
 import { planDependabot, renderDependabot } from '../ci/dependabot.mjs';
-import { planTsconfigBase, renderTsconfigBase, TSCONFIG_BASE_FILE } from '../tsconfig.mjs';
+import { planTsconfigBase } from '../tsconfig.mjs';
 import {
   IDENTITY_FILE,
   INCLUDE_KEY,
+  gitignoreWithIdentity,
+  identityIgnored,
   ignoreIdentity,
   includeOwnIdentity,
   includesOwnIdentity,
@@ -44,10 +46,16 @@ import {
 import { pointerState, pointerTargets } from '../projection/project.mjs';
 import { surfacesLine } from '../projection/surfaces.mjs';
 import { plan, provenanceDigest, PRIMARY_TARGET, LOCAL_PROFILE_DIR } from '../projection/project.mjs';
+import { planAgents, writeAgentPlan, writeSkillFile } from '../agents/render.mjs';
+import { computeLock } from '../projection/lock.mjs';
 import { parse as parseRegion } from '../projection/markers.mjs';
+import { reindex, SQLITE_FILE } from '../index/store.mjs';
 import { CLI } from '../name.mjs';
 import { MANIFEST_FILE } from '../name.mjs';
 import { packageVersion, hasNpm } from '../package-version.mjs';
+import { resolveNodeRunner } from '../ecosystem/node-runner.mjs';
+import { PACKAGE_NAME } from '../name.mjs';
+import { commandRoot } from '../repo-root.mjs';
 
 const run = promisify(execFile);
 
@@ -55,7 +63,7 @@ const BACKUP_TAG = 'backup-before-simt-dev';
 const ADOPT_BRANCH = 'simt-dev/adopt';
 
 export async function initCommand(positional, flags) {
-  const root = flags.root ?? positional[0] ?? process.cwd();
+  const root = commandRoot(flags, positional);
 
   const detected = await fingerprint(root);
   if (detected.error) {
@@ -68,6 +76,20 @@ export async function initCommand(positional, flags) {
   // a repository without node_modules obtains the binary in CI.
   const version = packageVersion();
   const npm = await hasNpm(root);
+  // Q31: the CI install step and the plan row that names it read the same
+  // resolver as the card and the gates — lockfile first, `packageManager` next.
+  // `manager` is the Node manager id or null (no package.json: binary channel).
+  let manager = null;
+  if (npm) {
+    let packageManager = null;
+    try {
+      const pkg = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
+      if (typeof pkg.packageManager === 'string') packageManager = pkg.packageManager;
+    } catch {
+      // Unreadable here is reported by the manifest path; the default stays npm.
+    }
+    manager = resolveNodeRunner({ facts: detected.facts, packageManager }).id;
+  }
   const existing = await readManifest(root);
   const { manifest: current, exists, error } = existing;
   if (error) {
@@ -87,9 +109,15 @@ export async function initCommand(positional, flags) {
   const manifest = buildManifest({ root, stack: detected.stack, sha, version, existing: current, capability, facts: detected.facts });
   const findings = await scanRepo(root);
   const summary = summarise(findings);
+  // Every repo-file write is journaled, so `undo` can restore this run (R49).
+  // Created before `plan()` because the skill file must be on disk when
+  // `installedSkills` reads the directory for the region's disclosure section.
+  const journal = [];
+  await writeSkillFile(root, journal);
   const projected = await plan(root, flags);
   const region = projected.targets[0];
   const mdcProblems = projected.mdcProblems ?? [];
+  const crossRefs = projected.crossRefs ?? [];
 
   // Which editors this repo's rules reach. `--surfaces` wins for this run and is
   // recorded in the manifest so the choice survives; with nothing declared the
@@ -105,7 +133,30 @@ export async function initCommand(positional, flags) {
     // not a line to save.
     else pointerPlan.push({ ...p, state: st.state });
   }
-  manifest.surfaces = projected.surfaces;
+  // Record the choice only when it was made: a flag for this run, or a key the
+  // manifest already carries with a real value. A fresh adoption with neither gets
+  // no surfaces of its own - "absent" means the global standard applies, and writing
+  // today's default into every fresh manifest would freeze it for every release after
+  // (review 0003 Q30). With a declared array, `projected.surfaces` is that same array
+  // resolved, so the assignment records rather than rewrites.
+  if (flags.surfaces !== undefined || Array.isArray(existing?.surfaces)) {
+    manifest.surfaces = projected.surfaces;
+  }
+
+  // The lock's input digest includes the manifest this run writes. On a fresh adoption
+  // there is no manifest on disk yet, so the lock `plan` computed is the one for a repo
+  // that has none - and the adoption would be red on `check --frozen` the moment the
+  // manifest lands. Recompute it with the manifest about to write, so the bytes in the
+  // plan, the diff and the write are the same (Q29). A re-init preserves every lock
+  // input, so its `plan` bytes are already right and are left alone. After the
+  // surfaces line: that is the last mutation of the manifest, and the digest must
+  // cover the bytes that land on disk, not an earlier draft of them.
+  const lockTarget = projected.targets.find((t) => t.kind === 'lock');
+  if (lockTarget && !exists) {
+    const lock = await computeLock(root, flags, manifest);
+    lockTarget.text = `${JSON.stringify(lock, null, 2)}\n`;
+    lockTarget.bytes = Buffer.byteLength(lockTarget.text);
+  }
 
   const adoption = exists || Boolean(region?.exists);
   // One decider for `--yes --dry-run`: the inline copy used to agree with it today,
@@ -120,10 +171,25 @@ export async function initCommand(positional, flags) {
   const ci = await planWorkflow(root);
   const dependabot = await planDependabot(root);
   const tsconfigBase = await planTsconfigBase(root);
+  // ADR-111. The one agent this tool ships, planned with the rest so the operator sees
+  // it in the same preview that lists everything else. Written in the apply path with
+  // everything else, journaled the same way.
+  const agentPlan = await planAgents(root);
   // Per-developer, and planned with the rest so the operator sees it in the same
   // preview that lists everything else. `exists` short-circuits the write: a
   // repository that already has one keeps it exactly as it is.
   const identity = await resolveIdentity(root);
+  // The .gitignore edit and the include repoint are writes too, so they get plan
+  // lines of their own: a line the run does not print is a write the reader
+  // approves from the diff afterwards (review 0003 Q30). The before-bytes are read
+  // once here and reused by the --diff pair below, so the preview's before side is
+  // the same bytes the plan's verb was decided from.
+  let gitignoreBefore = null;
+  let gitignoreAction = null;
+  if (!identity.exists && identity.from !== null && !(await identityIgnored(root))) {
+    gitignoreBefore = await readBefore(join(root, '.gitignore'));
+    gitignoreAction = gitignoreBefore === null ? 'create' : 'update';
+  }
   const identityPlan = {
     file: IDENTITY_FILE,
     action: identity.exists ? 'unchanged' : identity.from === null ? 'skip' : 'created',
@@ -139,6 +205,9 @@ export async function initCommand(positional, flags) {
     // pointing at another repository's identity file works here and breaks for the
     // next person who clones without that sibling checkout.
     include: await includesOwnIdentity(root),
+    // The .gitignore edit, planned like every other write: null when the entry is
+    // already there or no file is being created, 'create'/'update' otherwise.
+    gitignore: gitignoreAction,
   };
 
   const payload = {
@@ -182,8 +251,18 @@ export async function initCommand(positional, flags) {
       bytes: tsconfigBase.bytes,
       reason: tsconfigBase.reason,
     },
+    // ADR-111. The agent files the apply path will write, one per harness that documents
+    // an agents directory. `text` is stripped from the emitted payload the way the other
+    // plans strip their rendered bytes; the apply path writes from `agentPlan`, which
+    // keeps it.
+    agents: agentPlan.map(({ text, ...rest }) => rest),
     adoption,
     manifest: { file: MANIFEST, action: manifestAction, path: manifestFile },
+    // Local state, not a repository file: gitignored, rebuildable from `git ls-files -s`,
+    // and not journaled. The plan names it because a file that appears after the run
+    // without being in the plan is the same silent write as any other. `build` means
+    // "built when --yes is applied"; the apply path replaces this with the result.
+    index: { file: SQLITE_FILE, action: 'build' },
     region: region && {
       file: region.file,
       action: region.action,
@@ -245,6 +324,10 @@ export async function initCommand(positional, flags) {
     );
   }
 
+  // A dangling cross-reference does not stop the adoption: the region renders, and one
+  // unreachable reference is a defect to report, not a reason to withhold the rest.
+  for (const p of crossRefs) note(`PROBLEM  ${p}`);
+
   // Step 3: block on a real conflict before doing anything else. A duplicate is
   // reported but never blocks - restating a ruling is a hygiene problem, while
   // instructing an agent to do the forbidden thing is a correctness problem.
@@ -254,7 +337,7 @@ export async function initCommand(positional, flags) {
     if (isJson(flags)) {
       emitJson(payload);
     } else {
-      emit(render(payload, manifest, { npm, version }));
+      emit(render(payload, manifest, { npm, manager, version }));
       note('');
       note(
         `blocked  ${summary.conflicts} conflict${summary.conflicts === 1 ? '' : 's'}; nothing written`,
@@ -275,7 +358,7 @@ export async function initCommand(positional, flags) {
     payload.ok = false;
     payload.blockedBy = 'malformed-region';
     if (isJson(flags)) emitJson(payload);
-    else emit(render(payload, manifest, { npm, version }));
+    else emit(render(payload, manifest, { npm, manager, version }));
     return fail(
       `${malformed.length} target(s) have a malformed generated region (${malformed[0].file}: ${malformed[0].reason})`,
       EXIT.FAIL,
@@ -304,11 +387,18 @@ export async function initCommand(positional, flags) {
         after: renderIdentityFile(identity),
       });
     }
+    if (payload.identity.gitignore !== null) {
+      diffs.push({
+        path: '.gitignore',
+        before: gitignoreBefore,
+        after: gitignoreWithIdentity(gitignoreBefore ?? ''),
+      });
+    }
     if (payload.ci.action === 'create') {
       diffs.push({
         path: payload.ci.file,
         before: await readBefore(join(root, payload.ci.file)),
-        after: renderWorkflow({ own: payload.ci.own, npm, version }),
+        after: renderWorkflow({ own: payload.ci.own, npm, manager, version }),
       });
     }
     if (payload.dependabot.action === 'create') {
@@ -321,13 +411,6 @@ export async function initCommand(positional, flags) {
         }),
       });
     }
-    if (payload.tsconfigBase.action === 'create') {
-      diffs.push({
-        path: payload.tsconfigBase.file,
-        before: await readBefore(join(root, payload.tsconfigBase.file)),
-        after: renderTsconfigBase(),
-      });
-    }
     for (const target of projected.targets) {
       if (target.action === 'unchanged' || target.action === 'malformed') continue;
       diffs.push({
@@ -343,7 +426,7 @@ export async function initCommand(positional, flags) {
   if (isJson(flags)) {
     if (!apply) emitJson(payload);
   } else {
-    emit(render(payload, manifest, { npm, version }));
+    emit(render(payload, manifest, { npm, manager, version }));
     // After the report: the report says what, the diff shows it (R50).
     emitDiffs(diffs, flags);
   }
@@ -394,7 +477,6 @@ export async function initCommand(positional, flags) {
 
   // Every repo-file write below is journaled, so `undo` can restore this run
   // (R49). Pointer symlinks carry no bytes and are not journaled.
-  const journal = [];
   await writeManifest(root, manifest, journal);
   note(`wrote    ${MANIFEST_FILE} (${manifestAction})`);
 
@@ -410,7 +492,14 @@ export async function initCommand(positional, flags) {
   // a change.
   if (payload.identity.action === 'created') {
     await journaledWriteFile(root, journal, join(root, IDENTITY_FILE), renderIdentityFile(identity));
-    await ignoreIdentity(root);
+    // Both .gitignore edits are journaled, and the journal line lands first: the two
+    // entries fold to one (first before, last after), so undo restores the pre-run
+    // bytes — or removes the file — in one step. If the journal line landed after,
+    // unrecorded, the file would no longer match the recorded after-bytes and undo
+    // would refuse (review 0003 Q30). The `ignoreJournal` inside `commitJournal`
+    // below is then a no-op.
+    await ignoreJournal(root, journal);
+    await ignoreIdentity(root, journal);
     note(`wrote    ${IDENTITY_FILE} (${identity.from === 'last-commit' ? 'from the last commit in this repository' : 'from the identity configured on this machine'}); gitignored, because it is yours and not the repository's`);
   } else if (payload.identity.action === 'unchanged') {
     note(`kept     ${IDENTITY_FILE} (${payload.identity.reason})`);
@@ -418,7 +507,7 @@ export async function initCommand(positional, flags) {
     note(`skipped  ${IDENTITY_FILE}  ${payload.identity.reason}`);
   }
   if (!payload.identity.include) {
-    await includeOwnIdentity(root);
+    await includeOwnIdentity(root, journal);
     note(`set      ${INCLUDE_KEY} = ../${IDENTITY_FILE}  this repository's own identity file`);
   }
 
@@ -433,7 +522,7 @@ export async function initCommand(positional, flags) {
   // guaranteed to be misled.
   if (payload.ci.action === 'create') {
     await mkdir(dirname(join(root, payload.ci.file)), { recursive: true });
-    await journaledWriteFile(root, journal, join(root, payload.ci.file), renderWorkflow({ own: payload.ci.own, npm, version }));
+    await journaledWriteFile(root, journal, join(root, payload.ci.file), renderWorkflow({ own: payload.ci.own, npm, manager, version }));
     note(`wrote    ${payload.ci.file} (create; yours to edit from here, simt-dev will not rewrite it)`);
   }
   if (payload.dependabot.action === 'create') {
@@ -455,13 +544,6 @@ export async function initCommand(positional, flags) {
       `wrote    ${payload.dependabot.file} (create; watches ${payload.dependabot.ecosystems.join(', ') || 'github actions'} — yours to edit, simt-dev will not rewrite it)`,
     );
   }
-  if (payload.tsconfigBase.action === 'create') {
-    await journaledWriteFile(root, journal, join(root, payload.tsconfigBase.file), renderTsconfigBase());
-    note(
-      `wrote    ${payload.tsconfigBase.file} (create; ${TSCONFIG_BASE_FILE} is JSON, so it cannot say this itself — add "extends": "./${TSCONFIG_BASE_FILE}" to your tsconfig.json or nothing reads it)`,
-    );
-  }
-
   // Every planned target is written, not just the AGENTS.md region. An adoption that
   // scaffolds the manifest and one region but leaves the `.mdc` rules for a later
   // `sync` produces a repo whose `check` fails on files the user was never told
@@ -507,12 +589,34 @@ export async function initCommand(positional, flags) {
   for (const p of pointerBlocked) {
     note(`BLOCKED ${p.file}: ${p.detail} (${p.bytes} bytes); left as it is`);
   }
+  // ADR-111. The agent files, written with everything else and journaled the same way,
+  // so `undo` restores them with the rest of the adoption. Written from `agentPlan`,
+  // which keeps the rendered bytes the display payload strips.
+  const agentWritten = await writeAgentPlan(root, journal, agentPlan);
+  for (const f of agentWritten) note(`wrote    ${f} (agent)`);
   await commitJournal(root, 'init', journal);
   // The tree changed, so the last `check` no longer describes it: the line
   // goes back to "no cache" rather than reporting the tree as it was (R48).
   await invalidateCheckCache(root);
   payload.written = true;
 
+  // The index is a cache of git blobs (ADR-089): gitignored, rebuildable, and not
+  // journaled. Building it here means the first `simt map` or `simt brief` in a fresh
+  // adoption answers from real files instead of walking the tree on the reader's first
+  // prompt. A failure is a note, not a failed adoption: the next read rebuilds what
+  // this one could not.
+  try {
+    const built = await reindex(root);
+    payload.index = { file: SQLITE_FILE, action: 'built', files: built.files, symbols: built.symbols, ms: built.ms };
+    note(
+      `index    ${built.files} files, ${built.symbols} symbols in ${built.ms} ms; gitignored cache, ` +
+        `refreshed on read by ${CLI} map, brief and slice`,
+    );
+  } catch (error) {
+    payload.index = { file: SQLITE_FILE, action: 'failed', reason: error.message };
+    note(`index    not built (${error.message}); ${CLI} index rebuilds it`);
+  }
+
   if (isJson(flags)) emitJson(payload);
 
   note('');
@@ -617,7 +721,7 @@ async function git(cwd, args) {
 }
 
 /** Every line is a decision with a reason. Nothing is silent. */
-function render(payload, manifest, { npm = true, version } = {}) {
+function render(payload, manifest, { npm = true, manager = null, version } = {}) {
   const lines = [
     `repo        ${payload.root}`,
     `stack       ${payload.stack.length > 0 ? payload.stack.join(', ') : '(undetected)'}`,
@@ -649,6 +753,18 @@ function render(payload, manifest, { npm = true, version } = {}) {
         ? id.reason
         : `${id.name} <${id.email}>  from ${id.from === 'last-commit' ? "this repository's last commit" : 'the identity configured on this machine'}`;
     lines.push(`  ${verb.padEnd(9)} ${id.file}${detail ? `\n            ${detail}` : ''}`);
+    // The two side writes of the same action, each with its own line: a dry run that
+    // says `created git.config` and stops is a plan missing two of its three writes
+    // (review 0003 Q30). The include line mirrors the apply note byte for byte, so
+    // preview and run cannot tell the reader two different stories.
+    if (id.gitignore !== null) {
+      lines.push(
+        `  ${id.gitignore.padEnd(9)} .gitignore  ${IDENTITY_FILE} is per-developer, and committing it publishes one identity to everyone`,
+      );
+    }
+    if (id.include === false) {
+      lines.push(`  set        ${INCLUDE_KEY} = ../${IDENTITY_FILE}  this repository's own identity file`);
+    }
   }
   // Every gate the stack suggested and this repo cannot run is named, with the reason.
   // A silently shorter gate list reads as "this repo needs no formatting check", when
@@ -687,7 +803,9 @@ function render(payload, manifest, { npm = true, version } = {}) {
         ? 'hand-written content outside the markers is never modified'
         : target.kind === 'baseline'
           ? 'a region placed first, so your own settings below it still win (ADR-025)'
-          : 'generated file: frontmatter kept, body replaced (ADR-016)';
+          : target.kind === 'lock'
+            ? 'the two digests a frozen check compares (ADR-086)'
+            : 'generated file: frontmatter kept, body replaced (ADR-016)';
     lines.push(
       `  ${target.action.padEnd(9)} ${target.file}  ${target.previousBytes} -> ${target.bytes} bytes  ${caption}`,
     );
@@ -705,17 +823,30 @@ function render(payload, manifest, { npm = true, version } = {}) {
     lines.push(`            remedy: move it aside, or delete it and rerun init`);
   }
 
+  // ADR-111. The agent files, one per harness that documents an agents directory.
+  // Printed as their own kind: the file is owned whole by the tool, so the action is
+  // created, unchanged or updated and there is no byte delta to show.
+  for (const a of payload.agents ?? []) {
+    lines.push(`  ${a.action.padEnd(9)} ${a.path}  agent (ADR-111)`);
+  }
+
   // The CI gate is listed as its own kind because it is the one plan entry whose
   // absence is a decision rather than a default. Skipped states its reason inline so
   // a reader can tell "this repo does not use GitHub Actions" from "this repo was
   // not offered the gate".
   if (payload.ci.action === 'create') {
-    lines.push(`  ${'create'.padEnd(9)} ${payload.ci.file}  ${renderWorkflow({ own: payload.ci.own, npm, version }).length} bytes`);
+    lines.push(`  ${'create'.padEnd(9)} ${payload.ci.file}  ${renderWorkflow({ own: payload.ci.own, npm, manager, version }).length} bytes`);
     lines.push(
       payload.ci.own
         ? `            this repository is simt-dev's own; ${CLI} ci --yes refreshes this copy when the gate changes`
         : `            runs ${CLI} check where a pull request is merged; yours to edit after this`,
     );
+    // Q31: the workflow installs simt-dev as a devDependency, so the plan states
+    // the install the reader must run — `<pm> add -D`, never a bare npm guess.
+    if (!payload.ci.own && manager) {
+      const addDev = { npm: `npm i -D ${PACKAGE_NAME}`, pnpm: `pnpm add -D ${PACKAGE_NAME}`, yarn: `yarn add -D ${PACKAGE_NAME}`, bun: `bun add -d ${PACKAGE_NAME}` }[manager];
+      if (addDev) lines.push(`  ${'needs'.padEnd(9)} ${addDev}   (CI installs the pinned devDependency before it can run ${CLI} check)`);
+    }
   } else if (payload.ci.action === 'refresh') {
     // init does not write it. `simt ci` owns the template's own copy, and a
     // second writer would be a second answer to who owns it.
@@ -746,19 +877,21 @@ function render(payload, manifest, { npm = true, version } = {}) {
     lines.push(`            create ${WORKFLOWS_DIR}/ first if this repo is on GitHub Actions, then rerun init`);
   }
 
-  // Two states rather than three: there is no refresh, because `init` writes this file once
-  // and there is no repository in this estate that owns the template. A third state here
-  // would be a mechanism for keeping a copy current that nobody has asked for.
+  // One state, and it is the point: init no longer creates the file (review 0003 Q28),
+  // so the plan line says what it will not write and why, instead of a floor appearing
+  // after the run without being in the plan. An existing base file is repo-owned and
+  // left exactly as it is, which needs no line because nothing changes.
   const tb = payload.tsconfigBase;
-  if (tb && tb.action === 'create') {
-    lines.push(`  ${'create'.padEnd(9)} ${tb.file}  ${renderTsconfigBase().length} bytes`);
-    lines.push(
-      `            the strictness flags these repositories already agree on; add "extends": "./${tb.file}" to your tsconfig.json to use it`,
-    );
-  } else if (tb && tb.action === 'skip') {
+  if (tb && tb.action === 'skip') {
     lines.push(`  ${'skip'.padEnd(9)} ${tb.file}  ${tb.reason}`);
   }
 
+  // The index is local state, not a repository file: gitignored and rebuildable, so the
+  // plan line describes what apply does rather than a file written into the tree.
+  lines.push(
+    `  ${'build'.padEnd(9)} ${payload.index.file}  gitignored cache of the git index; built on apply, refreshed on read by ${CLI} map, brief and slice (ADR-089)`,
+  );
+
   const { findings, summary } = payload;
   if (summary.conflicts > 0) {
     lines.push('', `CONFLICTS ${summary.conflicts} - blocking without --accept-conflicts`);