simt-dev 0.1.1 → 0.2.1

package/src/identity.mjs

@@ -0,0 +1,207 @@
+// The per-developer git identity, as a file the repository does not track.
+//
+// A repository has more than one person in it, and each of them may already have an
+// identity this tool has no business choosing. So the rules here are conservative in
+// that order:
+//
+//   1. If `git.config` already exists, it is left exactly as it is. Not updated, not
+//      merged, not reformatted. It may have been written by a person, by an older
+//      version of this tool, or by hand years ago, and none of those are this tool's
+//      to second-guess.
+//   2. Otherwise the identity comes from the repository's own last commit author.
+//      That is the person who has been working here, which is the best available
+//      answer to "who commits here" and requires no guessing: it is a fact, not a
+//      default.
+//   3. Otherwise from the git identity configured for this machine or this user,
+//      which is what would have been used anyway had this file never existed.
+//   4. Otherwise nothing is written. An identity nobody configured is not one to
+//      invent, and a file with a placeholder in it is worse than no file: git would
+//      use the placeholder.
+//
+// The file is deliberately NOT written into the repository's tracked files. It holds
+// whoever is committing, and committing it publishes one developer's name and email
+// to everybody else in the repository. `init` adds it to .gitignore when it creates
+// one; a repository that already tracks it is left that way, because removing a
+// tracked file is not something an adopting command should do silently.
+
+import { execFile } from 'node:child_process';
+import { readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+
+const exec = promisify(execFile);
+
+/** The file, at the repository root. Named for what it is: a git config fragment. */
+export const IDENTITY_FILE = 'git.config';
+
+/** The git config key that pulls the file in. */
+export const INCLUDE_KEY = 'include.path';
+
+/**
+ * Run a git command and return trimmed stdout, or null if it fails.
+ *
+ * Null rather than an exception for every case: a repository that is not a git
+ * repository, a version of git that does not know a flag, a machine with no
+ * configured identity. None of those is an error worth refusing an adoption over.
+ *
+ * @param {string} cwd
+ * @param {string[]} args
+ * @returns {Promise<string|null>}
+ */
+async function git(cwd, args) {
+  try {
+    const { stdout } = await exec('git', args, { cwd });
+    return stdout.trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Who last committed here.
+ *
+ * `%an` and `%ae` rather than the configured identity on purpose: this is what
+ * actually happened, which is the answer to the question being asked. Reading
+ * `git config user.email` here would return the value this file is about to be
+ * derived from, and the step would be circular.
+ *
+ * @param {string} root
+ * @returns {Promise<{name: string|null, email: string|null}>}
+ */
+export async function lastCommitAuthor(root) {
+  const line = await git(root, ['log', '-1', '--format=%an <%ae>']);
+  if (!line) return { name: null, email: null };
+  // The name may itself contain angle brackets, so the address is split off the
+  // LAST one rather than the first.
+  const at = line.lastIndexOf('<');
+  const close = line.lastIndexOf('>');
+  if (at === -1 || close < at) return { name: line || null, email: null };
+  return {
+    name: line.slice(0, at).trim() || null,
+    email: line.slice(at + 1, close).trim() || null,
+  };
+}
+
+/**
+ * The identity this machine would use anyway.
+ *
+ * `--get` rather than `--global`: it resolves through system, global and local in
+ * git's own order, so what it returns is what a commit would have used had this file
+ * never been created. That is the fallback's whole point - it must not be a second
+ * opinion about what identity means.
+ *
+ * @param {string} root
+ * @returns {Promise<{name: string|null, email: string|null}>}
+ */
+export async function configuredIdentity(root) {
+  const read = async (key) => {
+    const value = await git(root, ['config', '--get', key]);
+    return value && value !== '' ? value : null;
+  };
+  return { name: await read('user.name'), email: await read('user.email') };
+}
+
+/**
+ * The identity to write, and where it came from.
+ *
+ * @param {string} root
+ * @returns {Promise<{name: string|null, email: string|null, from: 'last-commit'|'configured'|null,
+ *                    exists: boolean, bytes: number}>}
+ */
+export async function resolveIdentity(root) {
+  const path = join(root, IDENTITY_FILE);
+  try {
+    const info = await stat(path);
+    if (info.isFile()) {
+      return { name: null, email: null, from: null, exists: true, bytes: info.size };
+    }
+  } catch {
+    // Absent is the case this whole module exists for.
+  }
+
+  const committed = await lastCommitAuthor(root);
+  if (committed.name && committed.email) {
+    return { ...committed, from: 'last-commit', exists: false, bytes: 0 };
+  }
+  const configured = await configuredIdentity(root);
+  if (configured.name || configured.email) {
+    return { ...configured, from: 'configured', exists: false, bytes: 0 };
+  }
+  return { name: null, email: null, from: null, exists: false, bytes: 0 };
+}
+
+/**
+ * The file's bytes.
+ *
+ * Only the keys that were found are written. A partial identity is written as a
+ * partial identity rather than padded with a placeholder, because a placeholder is
+ * an identity git would use.
+ *
+ * @param {{name: string|null, email: string|null}} identity
+ * @returns {string} LF-terminated
+ */
+export function renderIdentityFile({ name, email }) {
+  const lines = ['[user]'];
+  if (name) lines.push(`\tname = ${name}`);
+  if (email) lines.push(`\temail = ${email}`);
+  return `${lines.join('\n')}\n`;
+}
+
+/**
+ * Whether `include.path` already names this repository's own file.
+ *
+ * @param {string} root
+ * @returns {Promise<boolean>}
+ */
+export async function includesOwnIdentity(root) {
+  const values = (await git(root, ['config', '--local', '--get-all', INCLUDE_KEY])) ?? '';
+  return values.split('\n').map((v) => v.trim()).filter(Boolean).includes(`../${IDENTITY_FILE}`);
+}
+
+/**
+ * Point `core.hooksPath`-style local config at this repository's own identity file.
+ *
+ * `--replace-all` rather than `--add`, and that is the whole point: a value naming
+ * ANOTHER repository's identity file is not an addition to keep, it is a link to
+ * break. Two of the repositories here had exactly that, and both worked only because
+ * the sibling checkout happened to exist at the expected relative path.
+ *
+ * @param {string} root
+ * @returns {Promise<void>}
+ */
+export async function includeOwnIdentity(root) {
+  await git(root, ['config', '--local', '--replace-all', INCLUDE_KEY, `../${IDENTITY_FILE}`]);
+}
+
+/**
+ * Add the identity file to .gitignore, if it is not already there.
+ *
+ * Matching on the exact line rather than a substring, because a `.gitignore`
+ * entry of `/git.config` or `git.config` both mean it while a comment mentioning
+ * it means nothing, and appending a duplicate of an entry that is already present
+ * is how a file ends up listed twice.
+ *
+ * @param {string} root
+ * @returns {Promise<boolean>} whether the file was changed
+ */
+export async function ignoreIdentity(root) {
+  const path = join(root, '.gitignore');
+  let text;
+  try {
+    text = await readFile(path, 'utf8');
+  } catch {
+    text = '';
+  }
+  const already = text.split('\n').map((l) => l.trim()).includes(IDENTITY_FILE);
+  if (already) return false;
+  const prefix = text === '' || text.endsWith('\n') ? '' : '\n';
+  const block =
+    `${prefix}\n` +
+    '# Per-developer git identity, written by `simt init`. Not a file to share:\n' +
+    '# it carries whoever is committing into the tree, and a repository has more than\n' +
+    '# one of those.\n' +
+    `${IDENTITY_FILE}\n`;
+  const { writeFile } = await import('node:fs/promises');
+  await writeFile(path, text + block);
+  return true;
+}

package/src/mcp/tools.mjs

@@ -19,7 +19,7 @@
 // cause by accident because the caller cannot see the size until it has paid for it.
 
 import { fingerprint } from '../resolve/fingerprint.mjs';
-import { loadRegistry, REGISTRY_PATH } from '../graph/load.mjs';
+import { loadRegistry } from '../graph/load.mjs';
 import { tokenize, rankSkills, closure, selectWithinBudget, scoreSkill, selectionVerdict, stackCompatible } from '../resolve/resolve.mjs';
 import { loadRules, select, checkTargets, provenanceDigest } from '../projection/project.mjs';
 import { loadDecisions, byId, citations } from '../decisions/index.mjs';
@@ -46,7 +46,7 @@ function rootOf(args) {
 }
 
 async function registry(args) {
-  const { registry, errors, ok, verified, workspace } = await loadRegistry(REGISTRY_PATH, args ?? {});
+  const { registry, errors, ok, verified, workspace } = await loadRegistry(null, args ?? {});
   if (!ok) {
     throw Object.assign(new Error(errors[0]), {
       remedy: `run: ${CLI} graph lint`,

package/src/output/index.mjs

@@ -12,13 +12,18 @@ export const EXIT = {
   OK: 0,
   FAIL: 1, // a gate failed: drift, policy violation, missing evidence
   USAGE: 2, // bad arguments; the remedy is in the message
-  CONFIG: 3, // simt-dev.json missing or invalid
+  CONFIG: 3, // simt.json missing or invalid
   REGISTRY: 4, // skills.graph.json invalid: orphan, dangling edge, cycle
   UNSUPPORTED: 5, // the request cannot be satisfied on this platform or repo
 };
 
 const REMEDY = {
-  [EXIT.USAGE]: 'run: simt-dev --help',
+  // Every default remedy below is `${CLI}` and not the package name, because this
+  // package installs exactly one binary and `package.json`'s `bin` map says which:
+  // `simt`. A remedy naming `simt-dev` is a command the reader types and gets
+  // `unknown command` from, which is the one answer that leaves them with no next
+  // step at all - and it was this default, printed on every bad invocation.
+  [EXIT.USAGE]: `run: ${CLI} --help`,
   [EXIT.CONFIG]: `run: ${CLI} init`,
   [EXIT.REGISTRY]: `run: ${CLI} graph lint`,
 };
@@ -32,7 +37,7 @@ export function fail(message, code = EXIT.FAIL, remedy) {
   // default and it was only ever resolvable from inside simt-dev's own checkout;
   // a reader in a consumer repo got a remedy naming a file that does not exist
   // where they are. Every remedy here is something the reader can run.
-  const resolved = remedy ?? REMEDY[code] ?? 'run: simt-dev --help';
+  const resolved = remedy ?? REMEDY[code] ?? `run: ${CLI} --help`;
   process.stderr.write(`ERROR ${code} ${message}\nREMEDY ${resolved}\n`);
   return code;
 }
@@ -60,10 +65,6 @@ export function writeMode(flags) {
   return { dryRun, apply: flags.yes === true && !dryRun };
 }
 
-export function isTty() {
-  return process.stdout.isTTY === true && !process.env.NO_COLOR;
-}
-
 /**
  * Emit a block of text under a heading, respecting --max-bytes.
  * Truncation is always announced with an explicit line, never a silent ellipsis:

package/src/package-version.mjs

@@ -0,0 +1,74 @@
+// How simt-dev is installed, and the version a repository holds it to.
+//
+// Three distinct things that must not be confused:
+//   - packageVersion() is the version of the binary that is RUNNING. It is read from
+//     the package this code lives in, so it is correct whether the binary was resolved
+//     from node_modules, a global install, or a source checkout.
+//   - hasNpm(root) is the KIND of repository: does it have a package.json? That decides
+//     how it obtains simt-dev at all — pinned as a devDependency where one exists, a
+//     pinned global install where there is no node_modules to pin in.
+//   - the pin is the version a repository recorded when it adopted simt-dev, stored in
+//     the manifest's projection.version. It is what a global install must match: npm
+//     pins the node_modules copy for us, but nothing pins a global binary, so the gate
+//     compares the running version against the pin and refuses on a mismatch.
+
+import { readFileSync } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { MANIFEST_FILE } from './name.mjs';
+
+/**
+ * The version of the simt-dev package this code is running from.
+ *
+ * Sync, because the render functions it feeds are sync: a rendered artifact bakes in
+ * the version that produced it, and that must be known before the bytes are written.
+ * A missing or unreadable package.json degrades to 'unknown' rather than throwing —
+ * the same call already tolerates it in `--version`, and a render that cannot read its
+ * own version is not a reason to crash the command that calls it.
+ */
+export function packageVersion() {
+  try {
+    const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+    return pkg.version;
+  } catch {
+    return 'unknown';
+  }
+}
+
+/**
+ * Whether a repository has a package.json, i.e. whether it pins simt-dev as a
+ * devDependency (npm) or must fall back to a global install. Async because the render
+ * call sites that feed it (init, hooks install, the compare stale check) are all async,
+ * and a missing file is an answer (false), not an error.
+ */
+export async function hasNpm(root) {
+  try {
+    await stat(join(root, 'package.json'));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Whether the running binary matches the version a repository pinned when it adopted
+ * simt-dev. Returns null when there is nothing to refuse, otherwise a message that
+ * names both versions and the one command that fixes it.
+ *
+ * This is the gate's fail-closed guard against a stale global binary: for a repository
+ * without npm, simt-dev is a global install and the only thing that knows which version
+ * it should be is the pin. A node_modules copy is pinned by npm itself, so its mismatch
+ * is a stale manifest, which `upgrade` refreshes — the remedy is the same either way.
+ *
+ * A manifest with no recorded pin (adopted before the field existed) is skipped, not
+ * failed: there is nothing to compare against, and failing it would turn every pre-0.2
+ * repository into a red gate the moment this check ships.
+ */
+export function assertVersionPin(manifest) {
+  const pin = manifest?.projection?.version;
+  if (!pin || pin === 'unknown') return null;
+  const running = packageVersion();
+  if (running === pin) return null;
+  return `simt-dev version mismatch: ${MANIFEST_FILE} pins ${pin}, the running binary is ${running}`;
+}

package/src/projection/baselines.mjs

@@ -93,7 +93,7 @@ indent_style = tab`;
  * every path as text and is the single most common way to corrupt a binary in a
  * repository, because nothing tells git it is wrong. `auto` makes git decide per path
  * from its own content sniffing, so a `.tif`, a `.zip` and a `.mc` file are left exactly
- * as they are and only files that genuinely are text get normalised. simt-garmin
+ * as they are and only files that genuinely are text get normalised. One
  * already worked this out on its own, which is the strongest evidence available that
  * the conservative form is the one the estate would have picked.
  *

package/src/projection/conflicts.mjs

@@ -6,11 +6,13 @@
 // the same rule restated in prose outside a generated region - prohibited by the
 // anti-duplication doctrine, but not a contradiction.
 //
-// The distinction is not academic. bunnyland's AGENTS.md says "Do not use `uv run
+// The distinction is not academic. One AGENTS.md says "Do not use `uv run
 // pytest`" - which contains the forbidden string `uv run pytest` verbatim. A naive
 // substring scan reports that file as violating the very rule it is correctly
 // restating. So every match is checked for prohibition context first.
 
+import { POINTERS, SURFACES } from './surfaces.mjs';
+
 /** Files whose text is a hand-written rule surface. Scanned for conflicts only;
  *  generated regions are excluded at read time by the caller.
  *
@@ -18,11 +20,60 @@
  *  worth recording: the estate's three always-on `.mdc` families were the single
  *  worst-drifted content in it, and `simt-dev init` reported `CONFLICTS none detected`
  *  on the repo holding them. A conflict detector that only looks at the filenames
- *  it was written for will quietly miss a whole rule surface added later. */
+ *  it was written for will quietly miss a whole rule surface added later.
+ *
+ *  And then it did. The comment above was written as a lesson and the lesson was not
+ *  taken: the list stayed hand-written, two surfaces were added to `SURFACES`
+ *  afterwards, and `.claude/rules/` and `.agents/rules/` were silently unscanned —
+ *  two of the five surfaces, and both of them read a rule that this tool writes. A
+ *  comment saying "derive this" is not deriving it. So the per-rule directories come
+ *  from `SURFACES` now (see `ruleGlobs`), and this list holds only the files no
+ *  surface declares. */
 export const RULE_FILES = ['AGENTS.md', 'CLAUDE.md', 'CONTRIBUTING.md'];
 
-/** Rule files discovered by glob rather than by name. */
-export const RULE_GLOBS = ['.cursor/rules/*.mdc', '.github/instructions/*.md'];
+/** Pointer targets, scanned because this tool writes them and they are rule files.
+ *
+ *  `CLAUDE.md` was named by hand in `RULE_FILES` for the whole life of the tool, and
+ *  `GEMINI.md` — which `POINTERS` creates for a repo on the Antigravity surface — was
+ *  not. So one file this tool writes was scanned and the other was not, with nothing
+ *  in the source saying which was which: the difference was an accident of the order
+ *  the two were added. Derived from `POINTERS` now, so it cannot recur. */
+function pointerFiles() {
+  return POINTERS.map((p) => p.path);
+}
+
+/**
+ * The per-rule directories, read out of `SURFACES` rather than written out here.
+ *
+ * One list of surfaces, read by everything that has to know where a surface keeps its
+ * rules. A surface added to `SURFACES` is now scanned for conflicts the moment it
+ * exists, which is the property the hand-written list kept failing to have — and it
+ * could only fail quietly, because a detector that matches nothing reports the same
+ * answer as a repository with no rules.
+ *
+ * `CLAUDE.md` and `GEMINI.md` are here through `RULE_FILES`/`POINTERS` rather than
+ * through this: they are symlinks to the primary region, so they are scanned as
+ * *files*, and `CONTRIBUTING.md` belongs to no surface at all.
+ *
+ * Takes the list as an argument rather than closing over it so the derivation can be
+ * shown on a surface that does not exist. The default is `SURFACES`, so every caller
+ * still reads the one authority; there is no way to pass anything else in production.
+ *
+ * @param {{rule?: string}[]} [surfaces]
+ */
+export function ruleGlobs(surfaces = SURFACES) {
+  return surfaces.filter((s) => typeof s.rule === 'string').map((s) => {
+    const slash = s.rule.lastIndexOf('/');
+    const extension = s.rule.slice(s.rule.lastIndexOf('.'));
+    // The FINAL extension, not the whole tail after `{name}`. Copilot's template is
+    // `{name}.instructions.md`, and matching that whole suffix would be narrower than
+    // the `.md` this file used to list by hand — which is the difference between seeing
+    // a hand-written `reviewer.md` in that directory and reporting the directory as
+    // empty. A file this tool writes always carries its own suffix; a file a person
+    // wrote in the same directory need not, and the person is who this scanner is for.
+    return `${s.rule.slice(0, slash)}/*${extension}`;
+  });
+}
 
 /** Every hand-written rule path in a repo, named or globbed.
  *
@@ -36,8 +87,8 @@ export const RULE_GLOBS = ['.cursor/rules/*.mdc', '.github/instructions/*.md'];
 export async function rulePaths(root) {
   const { readdir } = await import('node:fs/promises');
   const { join } = await import('node:path');
-  const out = RULE_FILES.map((f) => join(root, f));
-  for (const glob of RULE_GLOBS) {
+  const out = [...new Set([...RULE_FILES, ...pointerFiles()])].map((f) => join(root, f));
+  for (const glob of ruleGlobs()) {
     const star = glob.lastIndexOf('*');
     const dir = join(root, glob.slice(0, star));
     const tail = glob.slice(star + 1);