simt-dev 0.3.0 → 0.4.0

package/src/projection/disclosure.mjs

@@ -0,0 +1,92 @@
+// The names a reader needs before it can open anything that was kept out of the region.
+//
+// A scoped profile and an installed skill are the same situation: the body is not in the
+// file the reader loads at session start, and a reader that is not told the name will
+// never ask for it. This module reads only what the index line needs — a skill's name and
+// its description — and never the body. The body is the cost the index exists to avoid.
+
+import { readdir, readFile, realpath } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { readFrontmatter } from '../graph/spec.mjs';
+
+/**
+ * Where an installed skill can live. These are the directories `skills install` writes
+ * and the directories the loader table records, which are the same four. A fifth would
+ * be a place this tool can write a skill and then fail to tell the reader it is there.
+ */
+const SKILL_DIRS = ['.agents/skills', '.cursor/skills', '.claude/skills', '.opencode/skills'];
+
+/**
+ * The skills installed in a repository, one entry per file.
+ *
+ * A symlink fan-out is one skill: the file is counted by its real path, so the same
+ * body linked from two of these directories produces one line. Two different files that
+ * share a name both stay, because dropping one would hide a trigger.
+ *
+ * @param {string} root
+ * @returns {Promise<{name: string, trigger: string, dir: string}[]>}
+ */
+export async function installedSkills(root) {
+  const seen = new Set();
+  const skills = [];
+  for (const dir of SKILL_DIRS) {
+    let entries;
+    try {
+      entries = await readdir(join(root, dir), { withFileTypes: true });
+    } catch (error) {
+      if (error.code === 'ENOENT' || error.code === 'ENOTDIR') continue;
+      throw error;
+    }
+    for (const entry of entries) {
+      const file = await skillFile(root, dir, entry);
+      if (file === null) continue;
+      let key;
+      try {
+        key = await realpath(file);
+      } catch (error) {
+        if (error.code === 'ENOENT') continue;
+        throw error;
+      }
+      if (seen.has(key)) continue;
+      seen.add(key);
+      let text;
+      try {
+        text = await readFile(key, 'utf8');
+      } catch (error) {
+        if (error.code === 'ENOENT') continue;
+        throw error;
+      }
+      const { meta } = readFrontmatter(text);
+      const fallback = entry.isDirectory() ? entry.name : entry.name.replace(/\.md$/, '');
+      const name = typeof meta.name === 'string' && meta.name !== '' ? meta.name : fallback;
+      const trigger = typeof meta.description === 'string' ? meta.description.replace(/\s+/g, ' ').trim() : '';
+      skills.push({ name, trigger, dir });
+    }
+  }
+  skills.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : a.dir < b.dir ? -1 : a.dir > b.dir ? 1 : 0));
+  return skills;
+}
+
+/**
+ * The file that holds one skill, or null when the entry is not a skill.
+ *
+ * A symlink is the fan-out case: the directory a reader opens is a link, and
+ * `Dirent.isDirectory` is false for it, so treating "not a directory" as "not a
+ * skill" would index the canonical copy and then miss a repository whose only
+ * copy is the link.
+ */
+async function skillFile(root, dir, entry) {
+  const base = join(root, dir, entry.name);
+  if (entry.isDirectory() || entry.isSymbolicLink()) {
+    const nested = join(base, 'SKILL.md');
+    try {
+      await realpath(nested);
+      return nested;
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+  }
+  if ((entry.isFile() || entry.isSymbolicLink()) && entry.name.endsWith('.md')) return base;
+  return null;
+}

package/src/projection/lock.mjs

@@ -0,0 +1,125 @@
+// The lock records the two digests a frozen check compares (ADR-086).
+//
+// Input is everything the projection reads that a repository can change, plus the
+// digest of what this package ships. Output is the region body. An output that moves
+// while the input does not is a renderer that is not a function of its inputs, and
+// that is the failure `--frozen` exists to catch. An input that moves is a stale
+// lock: the projection changed because the repository did, and the lock was not
+// rewritten.
+
+import { createHash } from 'node:crypto';
+import { readFile, readdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { readLockedVariants } from '../kernel/variants.mjs';
+import { fingerprint } from '../resolve/fingerprint.mjs';
+import { desiredRegion, provenanceDigest, LOCAL_PROFILE_DIR } from './rules.mjs';
+import { readManifest } from './manifest.mjs';
+
+export const LOCK_FILE = 'simt-dev.lock.json';
+
+/** Manifest keys that change what the region contains. Anything else in the file is
+ *  the repository's own notes, and hashing it would make a comment fail the lock. */
+const MANIFEST_KEYS = ['mode', 'budget', 'shared', 'surfaces', 'gates'];
+
+/**
+ * The lock this repository's projection should have.
+ *
+ * @param {string} root
+ * @param {object} [flags] the same flags `sync` rendered with, so the output is the
+ *   body that was written and not a body for a different set of surfaces
+ */
+export async function computeLock(root, flags = {}) {
+  const variants =
+    flags?.variants !== undefined ? flags.variants : await readLockedVariants(root);
+  const desired = await desiredRegion(root, { ...flags, variants });
+  const inputs = await inputDigest(root, variants);
+  const outputs = createHash('sha256').update(desired.body).digest('hex');
+  const hasVariants =
+    variants && typeof variants === 'object' && Object.keys(variants).length > 0;
+  return hasVariants ? { inputs, outputs, variants } : { inputs, outputs };
+}
+
+/**
+ * Record locked variant winners in `simt-dev.lock.json` alongside updated digests.
+ */
+export async function writeLockVariants(root, nextVariants, flags = {}) {
+  const existing = await readLockedVariants(root);
+  const merged = { ...existing, ...(nextVariants ?? {}) };
+  const lock = await computeLock(root, { ...flags, variants: merged });
+  await writeFile(join(root, LOCK_FILE), `${JSON.stringify(lock, null, 2)}\n`, 'utf8');
+  return lock;
+}
+
+/** Read a lock, or null when the file is not there. A file that does not parse is an
+ *  error the caller reports, not a missing lock: absence and damage are different
+ *  repairs. */
+export async function readLock(root) {
+  let text;
+  try {
+    text = await readFile(join(root, LOCK_FILE), 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') return { lock: null, error: null };
+    throw error;
+  }
+  try {
+    const lock = JSON.parse(text);
+    if (typeof lock?.inputs !== 'string' || typeof lock?.outputs !== 'string') {
+      return { lock: null, error: 'must be an object with inputs and outputs' };
+    }
+    if (
+      lock.variants !== undefined &&
+      (typeof lock.variants !== 'object' || lock.variants === null || Array.isArray(lock.variants))
+    ) {
+      return { lock: null, error: 'variants must be an object' };
+    }
+    return { lock, error: null };
+  } catch (error) {
+    return { lock: null, error: error.message };
+  }
+}
+
+async function inputDigest(root, variants = {}) {
+  const hash = createHash('sha256');
+  hash.update(`provenance:${await provenanceDigest()}\n`);
+  const { stack, facts } = await fingerprint(root);
+  hash.update(`signals:${JSON.stringify({ stack, facts })}\n`);
+  const { manifest } = await readManifest(root);
+  const owned = {};
+  if (manifest && typeof manifest === 'object') {
+    for (const key of MANIFEST_KEYS) {
+      if (manifest[key] !== undefined) owned[key] = manifest[key];
+    }
+  }
+  hash.update(`manifest:${JSON.stringify(owned)}\n`);
+  let names = [];
+  try {
+    names = (await readdir(join(root, LOCAL_PROFILE_DIR))).filter((n) => n.endsWith('.md')).sort();
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  for (const name of names) {
+    const bytes = await readFile(join(root, LOCAL_PROFILE_DIR, name));
+    hash.update(`profile:${name}:${bytes.length}:`);
+    hash.update(bytes);
+  }
+  try {
+    const raw = await readFile(join(root, 'package.json'), 'utf8');
+    const scripts = JSON.parse(raw).scripts ?? {};
+    hash.update(`scripts:${JSON.stringify(scripts)}\n`);
+  } catch (error) {
+    if (error.code !== 'ENOENT' && !(error instanceof SyntaxError)) throw error;
+  }
+  const variantKeys =
+    variants && typeof variants === 'object' ? Object.keys(variants).sort() : [];
+  if (variantKeys.length > 0) {
+    const winners = {};
+    for (const key of variantKeys) {
+      const entry = variants[key];
+      winners[key] =
+        typeof entry === 'string' ? entry : (entry?.winner ?? entry?.variant ?? null);
+    }
+    hash.update(`variants:${JSON.stringify(winners)}\n`);
+  }
+  return hash.digest('hex');
+}

package/src/projection/manifest.mjs

@@ -463,6 +463,15 @@ export function buildManifest({ root, stack = [], sha, version, existing = null,
     // compliance (plan 0003 R02) — a mode chosen by default would be a bet the
     // repository never made. Declared, not generated, for the same reason as `budget`.
     ...(existing?.mode === undefined ? {} : { mode: existing.mode }),
+    // ADR-084: the rules this repository hands to the workspace's user-level copy, and
+    // the level that copy lives at. Declared, not generated, for the same reason as
+    // `budget` and `mode`: `shared install` writes the list once, but the bytes that land
+    // in a repository's region depend on it on every `sync` — so if `upgrade` rewrote it
+    // from its own opinion of what a workspace shares, a repository's region would change
+    // without anybody asking, which is the failure `budget` moving by itself was.
+    // Absent means "no repository in this workspace shares anything", which is the state
+    // every repository is in until somebody runs `shared install`.
+    ...(existing?.shared === undefined ? {} : { shared: existing.shared }),
     // ADR-020: which editors this repo's rules are projected into. Absent means the
     // global standard applies; an explicit empty list is a real choice meaning
     // AGENTS.md only. Recorded rather than inferred, because "which IDE does this repo
@@ -631,6 +640,24 @@ function defaultId(root) {
  */
 export const DEFAULT_BUDGET_BYTES = 30000;
 
+/**
+ * The budget a repository declared, or the default it gets for declaring nothing.
+ *
+ * One reader for one number, and it exists because two callers need it and a third
+ * already had its own: the packer that cuts a kernel to fit (ADR-083) and the meter that
+ * reports what it carries, against a ceiling each would otherwise spell differently. The
+ * byte they disagree about is the byte the repository wrote down.
+ *
+ * `0` is honoured — "this repository wants an empty projection" is a decision somebody can
+ * make. `null`, a string and `NaN` are not budgets at all, and a hand-edited manifest is
+ * exactly where one turns up; the default stands in rather than the ceiling becoming a
+ * string that every comparison against it silently passes.
+ */
+export function declaredBudget(manifest) {
+  const declared = manifest?.budget?.bytes;
+  return Number.isFinite(declared) && declared >= 0 ? declared : DEFAULT_BUDGET_BYTES;
+}
+
 /**
  * Report a projection that carries more than the repository agreed to carry.
  *
@@ -667,6 +694,31 @@ export function budgetFinding(bytes, budget, mode = 'full') {
   };
 }
 
+/**
+ * The workspace-shared rules this repository declared, as a set of ids.
+ *
+ * One reader, because the region, `doctor` and `shared` all need the same answer and a
+ * projection that renders a delta the meter cannot see is the one-question-two-answers
+ * defect this repository exists to end.
+ *
+ * `level` is read and validated rather than assumed, because `user` is the only level any
+ * reader loads from outside a repository and a hand-edited manifest is exactly where a
+ * second value turns up. A list that is not a list of strings yields an empty set: the
+ * repository then projects everything it selects, which is the state it was in before
+ * anybody ran `shared install`, and is never a state that loses a rule.
+ */
+export function declaredShared(manifest) {
+  const shared = manifest?.shared;
+  if (shared === undefined || shared === null) return { level: null, rules: new Set() };
+  const level = shared.level === 'user' ? 'user' : null;
+  const rules = new Set(Array.isArray(shared.rules) ? shared.rules.filter((id) => typeof id === 'string') : []);
+  // A level of `user` with nothing in it is a declaration that changes nothing, and a
+  // level that is not `user` names a place this tool cannot write — so neither is a
+  // reason to drop rules out of a region.
+  if (level === null || rules.size === 0) return { level: null, rules: new Set() };
+  return { level, rules };
+}
+
 export const GENERATED_KEYS = new Set(['$comment', 'projection']);
 
 /**

package/src/projection/markers.mjs

@@ -189,6 +189,57 @@ function readSha(body, style) {
  * never drift independently of it.
  */
 export function compose(body, { sha, sources = [] } = {}, style) {
+  return render(body, { sha, sources }, style, (s, sha, sources) =>
+    [
+      s.line(`${MARKER_PREFIX}:generated`),
+      s.line(`${MARKER_PREFIX}:sha=${sha}`),
+      ...(sources.length > 0 ? [s.line(`${MARKER_PREFIX}:sources=${sources.join(',')}`)] : []),
+      // Addressed to whoever reads this repo, not to whoever owns the rules upstream.
+      // "Edit the source in simt-dev" was the wrong instruction twice over: a consumer
+      // of the published package has no such tree, and an agent reading this repo has
+      // no business editing the region it was told not to edit. The only two actions
+      // available to a reader are: don't edit it, or regenerate it.
+      s.note(
+        'Generated content. Do not edit by hand - your changes are overwritten.',
+        `Run \`${CLI} sync --yes\` to regenerate, or \`${CLI} check\` to see what is stale.`,
+      ),
+    ],
+  );
+}
+
+/**
+ * The user-level shared region (ADR-084).
+ *
+ * A different note from `compose`, and the difference is the whole point of having two
+ * functions. `compose`'s remedy is `simt sync --yes`, and that remedy is wrong for a file
+ * in the reader's home directory: `sync` acts on a repository, so a reader who follows
+ * the instruction inside `~/.config/opencode/AGENTS.md` runs a command that will not
+ * repair it and concludes the projection is broken. The stamp and the marker grammar are
+ * shared, so `parse`, `inject` and `diff` read this region exactly as they read a
+ * repository's own — only the two sentences a reader acts on differ.
+ */
+export function composeShared(body, { sha, sources = [] } = {}, style) {
+  return render(body, { sha, sources }, style, (s, sha, sources) =>
+    [
+      s.line(`${MARKER_PREFIX}:generated`),
+      s.line(`${MARKER_PREFIX}:sha=${sha}`),
+      ...(sources.length > 0 ? [s.line(`${MARKER_PREFIX}:sources=${sources.join(',')}`)] : []),
+      s.note(
+        'Generated content shared by every repository in this workspace. Do not edit it by hand - your changes are overwritten.',
+        `Run \`${CLI} shared install --yes\` to regenerate it, or \`${CLI} doctor\` to see whether this copy is stale.`,
+      ),
+    ],
+  );
+}
+
+/**
+ * A region, markers and provenance header included, with a header this module chose.
+ *
+ * Split out because two headers now exist and the trailing-newline and empty-body cases
+ * below are load-bearing twice over — the formatter fight the header shape prevents does
+ * not care which of the two files it is happening in.
+ */
+function render(body, { sha, sources = [] }, style, headerLines) {
   const s = styleOf(style);
   // A stamp this tool cannot read back is worse than no stamp: `parse` matches
   // `[0-9a-f]{7,40}`, so the old `unknown` fallback produced a region that reported
@@ -200,21 +251,7 @@ export function compose(body, { sha, sources = [] } = {}, style) {
   }
   // Write-new, like the markers: the legacy spelling is read but never emitted, so a
   // migrated region is stable and a legacy one drifts exactly once.
-  const header = [s.line(`${MARKER_PREFIX}:generated`), s.line(`${MARKER_PREFIX}:sha=${sha}`)];
-  if (sources.length > 0) {
-    header.push(s.line(`${MARKER_PREFIX}:sources=${sources.join(',')}`));
-  }
-  // Addressed to whoever reads this repo, not to whoever owns the rules upstream.
-  // "Edit the source in simt-dev" was the wrong instruction twice over: a consumer
-  // of the published package has no such tree, and an agent reading this repo has
-  // no business editing the region it was told not to edit. The only two actions
-  // available to a reader are: don't edit it, or regenerate it.
-  header.push(
-    s.note(
-      'Generated content. Do not edit by hand - your changes are overwritten.',
-      `Run \`${CLI} sync --yes\` to regenerate, or \`${CLI} check\` to see what is stale.`,
-    ),
-  );
+  const header = headerLines(s, sha, sources);
   const trimmed = body.replace(/\n+$/, '');
   // Two lines here exist only because a real repo proved they are needed. A
   // formatter that runs on commit - several repositories have one, and three of the
@@ -269,7 +306,9 @@ function splice(state, region, where) {
  * adopted?" — `region: 'absent'` is that answer, and reading it off `previousBytes` gets a
  * repository with hand-written prose and no region wrong.
  *
- * @param {object} [opts] `style` overrides the syntax; `where` overrides placement.
+ * @param {object} [opts] `style` overrides the syntax; `where` overrides placement;
+ *   `compose` overrides which header the region carries (`composeShared` for the
+ *   user-level file, whose remedy is not `sync`).
  * @returns {{text: string, action: 'added'|'updated'|'unchanged'|'malformed', reason?: string,
  *   region: 'absent'|'ok'|'malformed', previousBody: string}}
  */
@@ -281,7 +320,7 @@ export function inject(text, body, meta, opts = {}) {
   if (state.status === 'malformed') {
     return { ...seen, text, action: 'malformed', reason: state.reason, line: state.line };
   }
-  const region = compose(body, meta, s);
+  const region = (opts.compose ?? compose)(body, meta, s);
 
   if (state.status === 'absent') {
     if (where === 'top') {

package/src/projection/project.mjs

@@ -26,6 +26,7 @@ import { checkTsconfig } from '../tsconfig.mjs';
 import { checkToolchain } from '../toolchain.mjs';
 import { diff, parse, inject, BEGIN, END } from './markers.mjs';
 import { budgetFinding, readManifest } from './manifest.mjs';
+import { budgetCutFinding } from '../kernel/budget.mjs';
 import { measureRoot } from '../measure/context.mjs';
 import { loadMdcRules, renderMdc } from './mdc.mjs';
 import { foldsRules, resolveSurfaces, SURFACES, SURFACE_IDS } from './surfaces.mjs';
@@ -165,23 +166,6 @@ export async function checkTargets(root, flags = {}) {
     findings.push(...readLimitFindings(text, PRIMARY_TARGET));
   }
 
-  // The budget: what this repository agreed to carry, against what it carries.
-  //
-  // Measured from the same `desiredRegion` the region above was compared against, plus
-  // the rule files this function went on to compare, because a gate and a meter that
-  // each counted their own set would report two different totals for one repository and
-  // the reader would have no way to tell which was the budget. Both numbers are the
-  // DESIRED ones, so a drifted repo is reported against what it would carry after a
-  // sync rather than what it carries today.
-  //
-  // Non-blocking by design: nothing is cut, because there is nothing to cut yet (ADR-072).
-  const budgetTotal = await alwaysOnBytes(root);
-  if (budgetTotal !== null) {
-    const { manifest } = await readManifest(root);
-    const over = budgetFinding(budgetTotal.bytes, manifest?.budget, manifest?.mode);
-    if (over) findings.push({ ...over, file: MANIFEST_FILE, detail: over.detail });
-  }
-
   // Every package of a monorepo is a projection root in its own right, so the gate
   // covers it the way it covers the root. A nested region that drifts is as stale as
   // the root's region, and the reader working in that package reads only that file.
@@ -246,6 +230,29 @@ export async function checkTargets(root, flags = {}) {
   const all = await loadMdcRules();
   const desired = await desiredRegion(root, flags);
   const { stack, facts, manifest } = desired;
+
+  // The budget, both halves of it, and in that order: what this repository agreed to
+  // carry against what it carries, then what was cut to get there.
+  //
+  // The total comes from the meter rather than from a sum this file could do itself,
+  // because a gate and a meter that each counted their own set would report two different
+  // numbers for one repository and the reader would have no way to tell which was the
+  // budget (ADR-072). The cut comes from the projection itself for the same reason — the
+  // packer wrote it, so the packer's own record of it is the one that cannot disagree with
+  // what `sync` would write.
+  //
+  // Both are non-blocking, for the reason ADR-072 gave for the first and ADR-083 for the
+  // second: the remedy is a decision about the number, not a missing file.
+  const budgetTotal = await alwaysOnBytes(root);
+  if (budgetTotal !== null) {
+    const over = budgetFinding(budgetTotal.bytes, manifest?.budget, manifest?.mode);
+    if (over) findings.push({ ...over, file: MANIFEST_FILE, detail: over.detail });
+  }
+  const packed = desired.budget;
+  if (packed !== null && packed.cuts.length > 0) {
+    findings.push(budgetCutFinding({ file: PRIMARY_TARGET, ...packed }));
+  }
+
   const declared = await readDeclared(root);
   const resolved = resolveSurfaces(manifest, flags);
   for (const p of resolved.problems) {