simt-dev 0.0.0-stage → 0.1.1

package/src/upgrade/plan.mjs

@@ -0,0 +1,203 @@
+import { MANIFEST_COMMENT } from '../projection/manifest.mjs';
+import { CLI } from '../name.mjs';
+import { MANIFEST_FILE } from '../name.mjs';
+// Classify one repository's upgrade state. Pure: no filesystem, no git.
+//
+// The line this module draws is narrow on purpose. `upgrade` moves a PIN. It does not
+// adopt a repo, repair a broken one, or decide that a repo should have a region it never
+// had. Each of those is a different command with a different review, and a command that
+// silently performs them during an "upgrade" is a command nobody can predict.
+//
+// So there are exactly two outcomes that write: `updated` and `unchanged`. Everything
+// else is a skip with its own remedy, and the skip is reported rather than tolerated -
+// a repo silently left behind is the exact failure `compare` exists to surface, and it
+// must not be one this command creates.
+
+/**
+ * @param {object} input
+ * @param {string} input.name
+ * @param {string} input.path
+ * @param {object|null} input.manifest parsed simt-dev.json, or null
+ * @param {boolean} input.manifestExists
+ * @param {string|null} input.manifestError parse failure, when there is one
+ * @param {object[]} input.targets every planned target from `plan(root).targets`: the
+ *   AGENTS.md region first, then the generated `.mdc` rules
+ * @param {string} input.sha the SHA this simt-dev stamps into regions
+ */
+export function planUpgrade({ name, path, manifest, manifestExists, manifestError, targets, sha }) {
+  const list = Array.isArray(targets) ? targets : [];
+  const primary = list[0] ?? null;
+  const base = { name, path, sha, pinnedSha: manifest?.projection?.simtDevSha ?? null };
+
+  // A repo that never adopted is not behind; it is absent. `simt-dev init` is the command
+  // for it, and calling this a failure would make the exit code describe the estate's
+  // migration progress rather than this run's correctness.
+  if (!manifestExists) {
+    return { ...base, state: 'not-adopted', action: 'skip', detail: `no ${MANIFEST_FILE}`, remedy: `${CLI} init` };
+  }
+  if (manifestError) {
+    return {
+      ...base,
+      state: 'broken-manifest',
+      action: 'skip',
+      detail: `${MANIFEST_FILE} is unparseable (${manifestError})`,
+      remedy: `fix the JSON, or run: ${CLI} init`,
+    };
+  }
+  // Only a hand-owned file's malformed region is a fault. A managed `.mdc` rule is a
+  // generated file, so a malformed region there is repaired by replacement and nothing
+  // hand-written is lost — `plan` reports its action as `updated`, not `malformed`, and
+  // the write fixes it. AGENTS.md holds hand-written prose around its region, so
+  // overwriting it could destroy work: that is the fault, and the whole repo is left
+  // alone so no file is half-migrated.
+  const malformed = list.find((t) => t.action === 'malformed');
+  if (malformed) {
+    return {
+      ...base,
+      state: 'malformed-region',
+      action: 'skip',
+      detail: `${malformed.file} region is malformed (${malformed.reason})`,
+      remedy: `fix the markers at ${malformed.file}:${malformed.line}, then: ${CLI} sync --yes`,
+    };
+  }
+  if (primary === null) {
+    return {
+      ...base,
+      state: 'no-region',
+      action: 'skip',
+      detail: 'no generated file could be planned for this repo',
+      remedy: `run: ${CLI} check`,
+    };
+  }
+  // A manifest with no region is a repo mid-adoption or one that never adopted, and
+  // `upgrade` writing a region into it turns adoption into a side effect of a version
+  // bump. The question is whether the region exists, and `parse` has always answered it —
+//  reading `previousBytes` instead gets a repository whose AGENTS.md is hand-written prose
+//  wrong, which is the shape this guard was written for and the one it let through. A
+//  byte count cannot tell "no region" from "small file", and a hand-written AGENTS.md is
+//  never small.
+//
+// Keyed on the PRIMARY target alone, and that is not a simplification. The estate builds
+// this state by adopting and then replacing AGENTS.md with prose, which leaves the
+// baselines' regions in place: a guard asking whether *every* target lost its region sees
+// two regions, decides the repo is adopted, and writes one — which is the defect. It is
+// also the rule `compare` already applies (ADR-016 ruling on display versus gate: the row's
+// `region` field is the primary document's), so the two commands now agree on which
+// repository counts as adopted.
+  if (primary.region === 'absent') {
+    return {
+      ...base,
+      state: 'no-region',
+      action: 'skip',
+      detail: `${MANIFEST_FILE} exists but AGENTS.md has no generated region`,
+      // `sync --yes`, not `init --yes`. The remedy is a command that does the thing the
+      // skip refused to do and nothing else: `sync` writes regions and leaves the rest of
+      // the repository alone, while `init` re-runs adoption. `compare` already names
+      // `sync --yes` for this state, and two commands must not answer the same question
+      // with different instructions.
+      remedy: `run: ${CLI} sync --yes`,
+    };
+  }
+
+  // Every target counts: a repo whose AGENTS.md is current but whose `.mdc` rules are
+  // stale is behind, and restamping only the first of its files would leave `check` red
+  // immediately after a successful `upgrade`.
+  const regionBehind = list.some((t) => t.action !== 'unchanged');
+  // "Behind" is not "the rules changed", and the difference is what the message below
+  // has to state. A target is `updated` for two unrelated reasons: its region BODY moved,
+  // which is a change to the content this tool projects, or its seam moved, which is this
+  // tool's own formatting around a body that was already correct (ADR-037). Both read as
+  // `updated`, so reading the cause off `action` reports a formatting repair as a change
+  // of policy — and this command's whole purpose is to say why a repository is behind, so
+  // a false cause here sends the reader to diff the rules when the rules did not move.
+  //
+  // The comparison is body to body rather than byte to byte, because the region header
+  // carries the stamp: a stamp-only move is what `pinBehind` already reports separately,
+  // and folding it in here would make every pin bump claim the rules changed.
+  //
+  // And the two kinds of projected content are counted apart, because they are different
+  // files to diff. A baseline region is not a rule: `.editorconfig` and `.gitattributes`
+  // are settings a repository owns, and telling a reader the RULES changed when only an
+  // indentation setting did sends them to the wrong file (S53). It was reachable because
+  // the stamp could not see a baseline body change at all, so the pin reported unchanged
+  // and the only cause left to report was the one that was least true.
+  const moved = (t) => {
+    if (t.action === 'unchanged' || t.action === 'added') return t.action === 'added';
+    const before = (t.previousBody ?? '').replace(/^\n+/, '').replace(/\n+$/, '');
+    const after = (t.body ?? '').replace(/^\n+/, '').replace(/\n+$/, '');
+    return before !== after;
+  };
+  const rulesChanged = list.some((t) => t.kind !== 'baseline' && moved(t));
+  const baselineChanged = list.some((t) => t.kind === 'baseline' && moved(t));
+  // The cause, as the sentence the reader is sent to act on. Null means no projected body
+  // moved, so whatever is behind this repository is a seam, a stamp or the manifest.
+  const cause = rulesChanged && baselineChanged
+    ? 'the rules and a baseline changed'
+    : rulesChanged
+      ? 'the rules changed'
+      : baselineChanged
+        ? 'a baseline changed'
+        : null;
+  const pinBehind = base.pinnedSha !== sha;
+  // A generated field of the manifest can alone be stale. `$comment` is written by
+  // simt-dev and describes this file's provenance, so an adopted repo whose regions
+  // and pin are all current can still be carrying an older version's wording -
+  // and because `sync` does not own the manifest, nothing else would ever correct
+  // it. Counting it here is what gives staleness a path back to being correct: a
+  // field nobody checks is a field nobody fixes.
+  const manifestBehind =
+    manifest?.$comment !== undefined && manifest.$comment !== MANIFEST_COMMENT.$comment;
+  if (!regionBehind && !pinBehind && !manifestBehind) {
+    return { ...base, state: 'current', action: 'unchanged', detail: 'already at this simt-dev' };
+  }
+
+  // Why it moved is worth stating, and the causes are different problems even though
+  // one command fixes all of them: content drift means a projected BODY changed, a seam
+  // repair means none did and only the formatting around one was wrong, a pin-only move
+  // means the region was already correct and only its stamp was stale, and a
+  // generated-field move means nothing about the repo changed and this tool's own
+  // wording did. The transition itself is printed on its own `pin` line, so `detail`
+  // names the cause without repeating it.
+  // `cause` is null on the last branch and can only be: a body that moved is a target
+  // whose action is not `unchanged`, so "no region behind" already implies no cause.
+  return {
+    ...base,
+    state: 'behind',
+    action: 'updated',
+    detail: pinBehind
+      ? regionBehind
+        ? cause === null
+          ? 'pin moved and region repaired; the rules were already correct'
+          : `pin moved and region restamped (${cause})`
+        : 'pin moved; the region was already current'
+      : regionBehind
+        ? cause === null
+          ? 'region repaired; the pin and the rules were already current'
+          : `region restamped; the pin was already current (${cause})`
+        : 'manifest metadata refreshed; the rules and the pin were already current',
+  };
+}
+
+/**
+ * States that mean something is WRONG, as opposed to states that mean something is
+ * merely ABSENT. Only these fail the run.
+ *
+ * The distinction is the same one `compare` makes, and it is load-bearing: on day one of
+ * a migration most repos have no manifest at all. A command that exits non-zero for them
+ * would report a workspace that looks broken and is merely early, and people would stop
+ * reading its exit code.
+ */
+export const FAULT_STATES = new Set(['broken-manifest', 'malformed-region', 'no-region']);
+
+/** @returns {{repos:number, updated:number, unchanged:number, skipped:number, faults:number, skippedStates:string[]}} */
+export function summariseUpgrade(plans) {
+  const skipped = plans.filter((p) => p.action === 'skip');
+  return {
+    repos: plans.length,
+    updated: plans.filter((p) => p.action === 'updated').length,
+    unchanged: plans.filter((p) => p.action === 'unchanged').length,
+    skipped: skipped.length,
+    faults: skipped.filter((p) => FAULT_STATES.has(p.state)).length,
+    skippedStates: [...new Set(skipped.map((p) => p.state))].sort(),
+  };
+}

package/src/workspace.mjs

@@ -0,0 +1,289 @@
+// Where the workspace is, and how to be sure.
+//
+// The workspace is the directory that CONTAINS repositories. It is not the same thing as a
+// repository, and it is not required: a single repo with no workspace is a normal, supported
+// case (ADR-014). What the workspace provides is the *sibling* relationship - it is how
+// `graph/skills.graph.json`'s `repo/path` sources resolve, and how `compare` finds the rest of
+// the estate.
+//
+// Three real failure modes motivated this module, all measured rather than reasoned about:
+//
+//   1. `resolve(HERE, '..', '..', '..')` is correct in the checkout and wrong in node_modules,
+//      where it lands inside `node_modules/@quazarmedia`. Every `skills` command then fails
+//      with ENOENT for all 38 sources.
+//   2. A single repo passed to `compare` was reported as "contains no git repositories",
+//      because discovery scanned the CHILDREN of the given path.
+//   3. The published package shipped no `docs/`, so `rules why` could not resolve a single ADR.
+//
+// The fix is not a cleverer heuristic. It is: resolve from explicit configuration, fall back to
+// the heuristic only when it verifies, and report which one answered. A silent fallback to the
+// wrong directory is worse than no answer at all, because every downstream answer is then
+// confidently wrong.
+
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { homedir, platform as osPlatform } from 'node:os';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+/**
+ * The package root. Here that is ONE level up from `src/`, not two - and getting
+ * it wrong silently shifts the workspace heuristic by a whole directory, which is
+ * why it is a named constant rather than an inline expression.
+ */
+export const PACKAGE_ROOT = resolve(HERE, '..');
+
+// Re-exported rather than re-spelled: the literal belongs to src/name.mjs with the
+// other LOCKED on-disk names, and a second copy here is a name that can drift from the
+// list of names that are allowed to move. Imported as well as re-exported, because a
+// bare `export { X } from` does not bind X here and every use below would fail.
+import { CONFIG_DIR } from './name.mjs';
+export { CONFIG_DIR };
+export const CONFIG_FILE = 'config.json';
+
+/**
+ * Candidate config paths, most explicit first.
+ *
+ * `$XDG_CONFIG_HOME` comes first on every platform because it is the only way to *override* the
+ * location on a POSIX system, and honouring an explicit override before guessing is the entire
+ * point. macOS is listed after it because `~/Library/Application Support` is Apple's documented
+ * location for application data, but a developer who already exports XDG_CONFIG_HOME should not
+ * have to also move the file. Both conventions are therefore supported, and which one is in use
+ * is reported rather than assumed.
+ *
+ * Windows is listed although ADR-012 drops Windows support. Keeping the function total makes it
+ * testable on any host and correct if that ruling is ever reversed; `package.json` still refuses
+ * to install on Windows.
+ *
+ * @returns {string[]}
+ *
+ * `env` defaults to `process.env`, NOT to an empty object. An earlier version
+ * defaulted to `{}` so that a test could pass a fake environment, and the result was
+ * that `XDG_CONFIG_HOME` - the one documented way to OVERRIDE the config location -
+ * was silently ignored on every real invocation. Every unit test passed `{env}`
+ * explicitly, so nothing caught it; only running the CLI did. The default is part of
+ * this function's contract, not a convenience.
+ */
+export function configPaths({ env = process.env, platform = osPlatform(), home = homedir() } = {}) {
+  const candidates = [];
+  const push = (p) => {
+    if (p && !candidates.includes(p)) candidates.push(p);
+  };
+
+  if (env.XDG_CONFIG_HOME) push(join(env.XDG_CONFIG_HOME, CONFIG_DIR, CONFIG_FILE));
+  push(join(home, '.config', CONFIG_DIR, CONFIG_FILE));
+  if (platform === 'darwin') {
+    push(join(home, 'Library', 'Application Support', CONFIG_DIR, CONFIG_FILE));
+  }
+  if (platform === 'win32') {
+    const base = env.APPDATA ?? join(home, 'AppData', 'Roaming');
+    push(join(base, CONFIG_DIR, CONFIG_FILE));
+  }
+  return candidates;
+}
+
+/**
+ * Read the user config, if there is one.
+ *
+ * An absent file is not an error: it means "not configured", and resolution continues down the
+ * precedence list. Only a file that EXISTS and does not parse is an error, because that is a
+ * real mistake the reader can fix - and silently ignoring it would send them looking for a
+ * configuration problem in the wrong place.
+ */
+export async function readUserConfig(options = {}) {
+  const searched = configPaths(options);
+  for (const path of searched) {
+    let text;
+    try {
+      text = await readFile(path, 'utf8');
+    } catch {
+      continue;
+    }
+    try {
+      const parsed = JSON.parse(text);
+      return { path, exists: true, config: parsed ?? {}, error: null, searched };
+    } catch (error) {
+      return { path, exists: true, config: {}, error: `unparseable JSON (${error.message})`, searched };
+    }
+  }
+  return { path: null, exists: false, config: {}, error: null, searched };
+}
+
+/**
+ * Does this directory contain at least one git repository? The heuristic is only accepted when
+ * it verifies, which is what stops a stray `node_modules` parent from being silently believed.
+ */
+async function looksLikeWorkspace(dir) {
+  const { readdir } = await import('node:fs/promises');
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return false;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
+    if (entry.name === 'node_modules') continue;
+    if (existsSync(join(dir, entry.name, '.git'))) return true;
+  }
+  return false;
+}
+
+/**
+ * Resolve the workspace.
+ *
+ * Precedence, highest first: `--workspace`, `SIMT_DEV_WORKSPACE`, the user config file, then the
+ * sibling heuristic of this package - and that last one only if it actually contains a git
+ * repository.
+ *
+ * @returns {Promise<{root: string|null, source: string, detail: string, searched: string[], error: string|null}>}
+ */
+export async function resolveWorkspace(flags = {}, options = {}) {
+  const env = options.env ?? process.env;
+  const searched = configPaths(options);
+
+  // The config file is read FIRST, before precedence is applied, and a parse failure
+  // is reported immediately. That is deliberate: precedence decides which *answer*
+  // wins, but a config file that exists and does not parse is a defect in the
+  // reader's setup, and hiding it because some other source outranked it would send
+  // them looking for a configuration problem in the wrong place.
+  const user = await readUserConfig(options);
+  if (user.error) {
+    return { root: null, source: 'config', detail: user.path, searched, error: user.error };
+  }
+
+  // Only `--workspace` counts here. `--root` names a REPOSITORY, and a repository
+  // is not its own parent, so treating one as the other would resolve every
+  // `repo/path` source one directory too low - a wrong answer that reads as right.
+  const flag = flags.workspace;
+  if (flag) {
+    return (
+      disabled(flag, 'flag', '--workspace', searched) ?? {
+        root: absolute(flag),
+        source: 'flag',
+        detail: '--workspace',
+        searched,
+        error: null,
+      }
+    );
+  }
+
+  if (env.SIMT_DEV_WORKSPACE) {
+    return (
+      disabled(env.SIMT_DEV_WORKSPACE, 'env', 'SIMT_DEV_WORKSPACE', searched) ?? {
+        root: absolute(env.SIMT_DEV_WORKSPACE),
+        source: 'env',
+        detail: 'SIMT_DEV_WORKSPACE',
+        searched,
+        error: null,
+      }
+    );
+  }
+
+  if (user.exists && typeof user.config.workspace === 'string' && user.config.workspace.length > 0) {
+    return (
+      disabled(user.config.workspace, 'config', user.path, searched) ?? {
+        root: absolute(user.config.workspace),
+        source: 'config',
+        detail: user.path,
+        searched,
+        error: null,
+      }
+    );
+  }
+
+  const parent = resolve(PACKAGE_ROOT, '..');
+  if (await looksLikeWorkspace(parent)) {
+    return { root: parent, source: 'heuristic', detail: 'sibling of this package', searched, error: null };
+  }
+
+  return {
+    root: null,
+    source: 'none',
+    detail: 'no workspace configured',
+    searched,
+    error: null,
+  };
+}
+
+/** Values that mean "there is deliberately no workspace", from any source. */
+const OFF = new Set(['off', 'none', 'no', '0', '-']);
+
+/**
+ * The sentinel. Without it there is no way to *decline* the sibling heuristic, so a
+ * reader who does not want a directory guessed for them cannot say so - and no test
+ * running from this checkout can reach the unconfigured path at all. `off` is
+ * returned from any source and takes the same shape as any other answer, so callers
+ * need no special case for it.
+ */
+function disabled(value, source, detail, searched) {
+  return OFF.has(String(value).trim().toLowerCase())
+    ? {
+        root: null,
+        source: 'disabled',
+        detail: `${detail}=off (workspace declined)`,
+        searched: searched ?? [],
+        error: null,
+      }
+    : null;
+}
+
+/**
+ * The one-line remedy every workspace-dependent failure prints.
+ *
+ * Built from this machine's OWN candidate list rather than a hardcoded example, because a
+ * remedy that names a path the reader does not have is a second problem stacked on the first.
+ * Index 0 is the right one to name: on POSIX that is `$XDG_CONFIG_HOME/...` when set and
+ * `$HOME/.config/...` when not, which is the path the reader most likely already expects.
+ */
+// The remedy is a phrase, not a sentence: several callers embed it after their own
+// lead-in ("workspace none configured - <here>"), so it must not start with one.
+export const WORKSPACE_REMEDY = (() => {
+  const first = configPaths()[0];
+  const where = first ?? join('$HOME', '.config', CONFIG_DIR, CONFIG_FILE);
+  return `--workspace <path>, the SIMT_DEV_WORKSPACE environment variable, or ${where}`;
+})();
+
+function absolute(p) {
+  const expanded = p.startsWith('~/')
+    ? join(homedir(), p.slice(2))
+    : p;
+  return isAbsolute(expanded) ? expanded : resolve(expanded);
+}
+
+/**
+ * The workspace, or null. Callers that can degrade use this and report `source: 'none'`;
+ * callers that genuinely cannot proceed should use `resolveWorkspace` and fail with its detail.
+ */
+export async function workspaceOrNull(flags = {}, options = {}) {
+  const { root, error } = await resolveWorkspace(flags, options);
+  return error ? null : root;
+}
+
+/**
+ * The path a multi-repo command should work on: `--root` or the first positional if
+ * given, else the resolved workspace, else the current directory.
+ *
+ * This lives here rather than in each command because precedence is a user-visible
+ * contract: `compare`, `upgrade` and any future workspace-wide command must agree on
+ * which source named the directory, or a reader who set `SIMT_DEV_WORKSPACE` gets
+ * three different answers from three commands.
+ *
+ * `--root` is returned verbatim as the source even though it names a repository; whether
+ * that repository is the only thing that counts is the caller's question, and `discover`
+ * answers it from the filesystem rather than from a guess.
+ */
+export async function targetRoot(flags = {}, positional = []) {
+  const explicit = flags.root ?? positional[0];
+  if (explicit) {
+    return { root: absolute(explicit), source: 'flag', detail: explicit, ws: null };
+  }
+  const ws = await resolveWorkspace(flags);
+  return {
+    root: absolute(ws.root ?? process.cwd()),
+    source: ws.source,
+    detail: ws.detail,
+    ws,
+  };
+}