@xhulz/nina 0.38.0 → 0.40.0

package/src/commands/check.mjs

@@ -9,14 +9,14 @@
  */
 
 import { readFile, readdir } from 'node:fs/promises';
-import { HARNESS, describeMove, interruptedMove, legacyHint } from '../paths.mjs';
+import { describeMove, HARNESS, interruptedMove, readProfile, surfacesIn } from '../paths.mjs';
 import { expectedUnfilled } from '../expected.mjs';
 import { parseGraph, validateGraph } from '../graph.mjs';
 import { frontmatterFindings, installedSkills, modelFindings, toolFindings } from '../tools.mjs';
 import { HOOK_SCRIPTS, missingWiring, shippedScripts } from '../wiring.mjs';
 import { existsSync } from 'node:fs';
 import { join, resolve, sep } from 'node:path';
-import { REQUIRES, SLOT, defaultedSlots, layerRootFor, noticeOf, readLayerText, stripWhy, walk } from './compose.mjs';
+import { SLOT, closedGate, defaultedSlots, layerRootFor, noticeOf, readLayerText, stripWhy, walk } from './compose.mjs';
 import { PLACEHOLDER, defaultVocabulary } from '../vocabulary.mjs';
 import { NEEDS } from '../surfaces.mjs';
 
@@ -49,8 +49,7 @@ export async function referencedVocabulary(layerRoot, surfaces, target) {
   const found = new Set();
   for (const rel of await walk(coreTree)) {
     const core = await readFile(join(coreTree, rel), 'utf8');
-    const requires = REQUIRES.exec(core);
-    if (requires && !surfaces.includes(requires[1])) continue;
+    if (closedGate(core, surfaces)) continue;
     const texts = [core];
     for (const s of surfaces) {
       const t = await readFile(join(layerRoot, 'surfaces', s, 'tree', rel), 'utf8').catch(() => null);
@@ -80,8 +79,7 @@ export async function projectSlots(layerRoot, surfaces) {
   const slots = new Set();
   for (const rel of await walk(coreTree)) {
     const core = await readFile(join(coreTree, rel), 'utf8');
-    const requires = REQUIRES.exec(core);
-    if (requires && !surfaces.includes(requires[1])) continue;
+    if (closedGate(core, surfaces)) continue;
     for (const line of core.split('\n')) {
       const marker = SLOT.exec(line);
       if (marker?.[1].startsWith('project.')) slots.add(`${rel} ${marker[1]}`);
@@ -142,13 +140,6 @@ export async function owedDocuments(layerRoot, surfaces) {
   return owed;
 }
 
-/**
- * `nina check`.
- *
- * @param {string[]} argv - Command arguments; `--project <dir>` selects the target.
- * @param {{root: string}} ctx - CLI context; `root` is the NINA install directory.
- * @returns {Promise<number>} Process exit code.
- */
 /**
  * Composed scripts that nothing in the project runs.
  *
@@ -191,6 +182,13 @@ export async function unwiredScripts(layerRoot, surfaces, target) {
     .sort();
 }
 
+/**
+ * `nina check`.
+ *
+ * @param {string[]} argv - Command arguments; `--project <dir>` selects the target.
+ * @param {{root: string}} ctx - CLI context; `root` is the NINA install directory.
+ * @returns {Promise<number>} Process exit code.
+ */
 export async function check(argv, ctx) {
   const target = resolve(argv.includes('--project') ? argv[argv.indexOf('--project') + 1] : '.');
   // `--detector`: run by every project's harness:check. Inside `nina upgrade --apply` the move measures
@@ -204,10 +202,9 @@ export async function check(argv, ctx) {
   }
 
   const expected = expectedUnfilled(argv);
-  const profilePath = join(target, HARNESS, 'profile.json');
-  if (!existsSync(profilePath)) {
-    const hint = legacyHint(target);
-    console.error(`  no .nina/profile.json under ${target}${hint || ' — run `nina init` first.'}\n`);
+  const { profile, error } = readProfile(target);
+  if (error) {
+    console.error(`  ${error}\n`);
     return 1;
   }
 
@@ -216,14 +213,6 @@ export async function check(argv, ctx) {
   /** Things that are merely stale — worth saying, not worth failing. */
   const notes = [];
 
-  let profile;
-  try {
-    profile = JSON.parse(await readFile(profilePath, 'utf8'));
-  } catch (error) {
-    console.error(`  .nina/profile.json is not valid JSON: ${error.message}\n`);
-    return 1;
-  }
-
   const resolved = layerRootFor(ctx.root, profile.core);
   if (resolved.error) {
     console.error(`  ${resolved.error}\n`);
@@ -235,9 +224,7 @@ export async function check(argv, ctx) {
   if (stopped) problems.push(`${describeMove(stopped)} \`nina upgrade --abort\` undoes it`);
 
   const surfaces = profile.surfaces ?? [];
-  const available = (await readdir(join(resolved.dir, 'surfaces'), { withFileTypes: true }))
-    .filter((e) => e.isDirectory())
-    .map((e) => e.name);
+  const available = (await surfacesIn(resolved.dir));
   for (const s of surfaces) {
     if (!available.includes(s)) {
       problems.push(`surface "${s}" does not exist in core ${profile.core} — available: ${available.join(', ')}`);

package/src/commands/compose.mjs

@@ -10,18 +10,20 @@
  * placeholder, filled from the profile. A surface the project does not declare has its
  * markers dropped, so a project with no database never reads a word about Prisma.
  *
- * The test that keeps this honest is a recomposition of the project it was extracted
- * from: the output must be byte-identical to what is running. Anything weaker depends on
- * someone's judgement that no rule was lost, and judgement is what let a mandatory rule
- * sit unenforceable for three months here.
+ * What keeps this honest is `scripts/compose-test.mjs`: every fixture composed and held to the
+ * properties it lists, so no rule is lost on someone's judgement that none was. It began as a
+ * recomposition of the project the harness was extracted from, byte for byte; that oracle went
+ * when projects began pinning frozen releases.
  */
 
 import { mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
-import { HARNESS, legacyHint } from '../paths.mjs';
+import { HARNESS, layerRootFor, readProfile } from '../paths.mjs';
 import { expectedUnfilled } from '../expected.mjs';
 import { existsSync, lstatSync, readFileSync } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
-import { NAME, defaultVocabulary } from '../vocabulary.mjs';
+import { NAME, PLACEHOLDER, defaultVocabulary } from '../vocabulary.mjs';
+
+export { layerRootFor };
 
 /**
  * Matches a slot marker on its own line, with an optional label.
@@ -60,6 +62,19 @@ export function stripWhy(text, { keepLines = false } = {}) {
  */
 export const REQUIRES = /^<!-- nina:requires ([a-z-]+) -->\n/;
 
+/**
+ * The surface a core file is gated on when the project does not declare it — the file is not composed there —
+ * or null. Every reader that asks whether a gated file applies asks this.
+ *
+ * @param {string} text - The core file.
+ * @param {string[]} surfaces - What the project declares.
+ * @returns {string|null}
+ */
+export function closedGate(text, surfaces) {
+  const gate = REQUIRES.exec(text)?.[1] ?? null;
+  return gate && !surfaces.includes(gate) ? gate : null;
+}
+
 /**
  * A slot inside a line — text before it, and the marker last. Filled with its fragment collapsed
  * to one line; dropped, like any slot, when its surface is not declared.
@@ -199,33 +214,6 @@ export function stamp(text, rel, slots) {
   return `${preamble}${generatedNotice(rel, slots, script)}\n\n${body}`;
 }
 
-/**
- * Where a project's layers are read from.
- *
- * A project pins a frozen release, or tracks the working tree with "dev". A pinned release
- * that is missing is an error, never a silent fall back to whatever the harness happens to
- * look like right now: that would compose an unreviewed core into a project that asked for
- * a reviewed one, and nothing downstream would say so.
- *
- * @param {string} root - The NINA install directory.
- * @param {string|undefined} core - The profile's `core` field.
- * @returns {{dir: string}|{error: string}}
- */
-export function layerRootFor(root, core) {
-  if (!core || core === 'dev') {
-    // `dev` means "track the layers as they are being worked on", which only exists in a
-    // checkout of this repo. An installed package ships frozen releases and nothing else,
-    // so say that rather than composing an empty tree and reporting nothing wrong.
-    if (!existsSync(join(root, 'core'))) {
-      return { error: `profile pins core "dev", which tracks the NINA working tree — ${root} is an installed package and has only releases` };
-    }
-    return { dir: root };
-  }
-  const dir = join(root, 'releases', core);
-  if (!existsSync(dir)) return { error: `profile pins core ${core}, which is not in ${join(root, 'releases')}` };
-  return { dir };
-}
-
 /**
  * Orders release names by their numbers rather than as text.
  *
@@ -376,8 +364,7 @@ export async function composedPaths(layerRoot, surfaces = []) {
   const coreTree = join(layerRoot, 'core', 'tree');
   const out = new Set();
   for (const rel of await walk(coreTree)) {
-    const gate = REQUIRES.exec(await readFile(join(coreTree, rel), 'utf8'));
-    if (gate && !surfaces.includes(gate[1])) continue;
+    if (closedGate(await readFile(join(coreTree, rel), 'utf8'), surfaces)) continue;
     out.add(rel);
   }
   return out;
@@ -432,11 +419,8 @@ export async function composeProject(target, ctx, options = {}) {
   /** Files composed for a surface this profile no longer declares, moved to {@link REMOVED}. */
   const removed = [];
 
-  const profilePath = join(target, HARNESS, 'profile.json');
-  if (!existsSync(profilePath)) {
-    return { error: `no .nina/profile.json under ${target}${legacyHint(target)}`, written, differ, unfilled: [], skipped };
-  }
-  const profile = JSON.parse(await readFile(profilePath, 'utf8'));
+  const { profile, error } = readProfile(target);
+  if (error) return { error, written, differ, unfilled: [], skipped };
   const surfaces = profile.surfaces ?? [];
 
   const resolved = layerRootFor(ctx.root, profile.core);
@@ -479,29 +463,27 @@ export async function composeProject(target, ctx, options = {}) {
     let core = await readFile(join(coreTree, rel), 'utf8');
     const dest = join(target, rel);
 
-    const requires = REQUIRES.exec(core);
-    if (requires) {
-      core = core.slice(requires[0].length);
-      if (!surfaces.includes(requires[1])) {
-        // The project has no such surface, so the file does not exist for it. One composed for it before the
-        // surface left the profile is still dispatched as a stage the graph no longer has, and was reported as
-        // drift that no compose cleared: it goes, with a copy kept. A file there with no notice is the project's.
-        skipped.push(rel);
-        let stale = false;
-        try {
-          stale = lstatSync(dest).isFile() && noticeOf(await readFile(dest, 'utf8')) !== null;
-        } catch {
-          // Not there.
-        }
-        if (stale && check) differ.push(`${rel} (present, but no '${requires[1]}' surface)`);
-        if (stale && !check) {
-          await mkdir(dirname(join(target, REMOVED, rel)), { recursive: true });
-          await writeFile(join(target, REMOVED, rel), await readFile(dest));
-          await rm(dest);
-          removed.push(rel);
-        }
-        continue;
+    const closed = closedGate(core, surfaces);
+    core = core.replace(REQUIRES, '');
+    if (closed) {
+      // The project has no such surface, so the file does not exist for it. One composed for it before the
+      // surface left the profile is still dispatched as a stage the graph no longer has, and was reported as
+      // drift that no compose cleared: it goes, with a copy kept. A file there with no notice is the project's.
+      skipped.push(rel);
+      let stale = false;
+      try {
+        stale = lstatSync(dest).isFile() && noticeOf(await readFile(dest, 'utf8')) !== null;
+      } catch {
+        // Not there.
       }
+      if (stale && check) differ.push(`${rel} (present, but no '${closed}' surface)`);
+      if (stale && !check) {
+        await mkdir(dirname(join(target, REMOVED, rel)), { recursive: true });
+        await writeFile(join(target, REMOVED, rel), await readFile(dest));
+        await rm(dest);
+        removed.push(rel);
+      }
+      continue;
     }
 
     // History is stripped from each piece before the pieces are joined. Joined first, an opener left
@@ -558,8 +540,8 @@ export async function composeProject(target, ctx, options = {}) {
     let text = out.join('\n');
     if (text.includes('nina:why')) malformed.push(rel);
     for (const [name, value] of Object.entries(profile.vocabulary ?? {})) {
-      // `null` means "declared but not filled in yet" — leave the placeholder standing so
-      // it is reported, rather than composing the rule with a hole where a noun should be.
+      // `null` means "declared but not filled in yet": it composes as owed, below, and `check` reports it,
+      // rather than the rule composing with a hole where a noun should be.
       if (value === null || value === undefined) continue;
       text = text.split(`{{${name}}}`).join(value);
     }
@@ -574,6 +556,10 @@ export async function composeProject(target, ctx, options = {}) {
     for (const [name, why] of Object.entries(profile.deferred ?? {})) {
       if (typeof why === 'string' && why.trim() && NAME.test(name)) text = text.split(`{{${name}}}`).join(`[${name}: not decided yet]`);
     }
+    // What is still a placeholder is owed: no default answers it, and the project has not declared it, or has
+    // declared it null. Left raw, it reached a stage as `{{TENANT_KEY}}` — once inside a shell block it was told to
+    // run — and reads as an editing slip to guess past. Said, it is a noun the stage knows it does not have.
+    text = text.replace(PLACEHOLDER, (_, name) => `[${name}: not declared yet]`);
 
     // Only what has a comment syntax the notice knows. A layer that one day composes JSON
     // would be corrupted by it rather than marked, so it gets nothing and says nothing.

package/src/commands/eval.mjs

@@ -225,7 +225,7 @@ export function fixtureDiff(fixture) {
 }
 
 /** What the judge must answer: a call on every planted defect, with the words it rests on, and on everything else. */
-export const JUDGE_SCHEMA = {
+const JUDGE_SCHEMA = {
   type: 'object',
   properties: {
     defects: {

package/src/commands/export.mjs

@@ -20,7 +20,7 @@
 
 import { createHash } from 'node:crypto';
 import { existsSync } from 'node:fs';
-import { mkdir, open, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, readdir, rename, writeFile } from 'node:fs/promises';
 import { spawn } from 'node:child_process';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -32,6 +32,7 @@ import { readStoreFile } from '../store.mjs';
 import { readConfig, statusPath, targetOf } from './langfuse.mjs';
 import { projectName } from './stats.mjs';
 import { handsToModel } from '../detectors.mjs';
+import { takeLock } from '../lock.mjs';
 
 /** The CLI, for the export the detector starts in the background. */
 const BIN = fileURLToPath(new URL('../../bin/nina.mjs', import.meta.url));
@@ -84,37 +85,6 @@ async function sentOf(slug) {
   }
 }
 
-/**
- * Holds a project's export for one run. Two at once would each read what was sent before either wrote,
- * and send the same runs twice. A lock left by a run that died is taken over: it names its process.
- *
- * @returns {Promise<(() => Promise<void>)|null>} The release, or null when another export holds it.
- */
-async function lock(slug) {
-  await mkdir(join(exportsDir(), 'langfuse'), { recursive: true });
-  const path = join(exportsDir(), 'langfuse', `${slug}.lock`);
-  for (let attempt = 0; attempt < 2; attempt += 1) {
-    try {
-      const handle = await open(path, 'wx');
-      await handle.writeFile(String(process.pid));
-      await handle.close();
-      return () => rm(path, { force: true });
-    } catch (error) {
-      if (error.code !== 'EEXIST') throw error;
-      const pid = Number(await readFile(path, 'utf8').catch(() => ''));
-      let alive = false;
-      try {
-        alive = pid > 0 && process.kill(pid, 0);
-      } catch (e) {
-        alive = e.code === 'EPERM';
-      }
-      if (alive) return null;
-      await rm(path, { force: true });
-    }
-  }
-  return null;
-}
-
 /** Writes it by rename, so an interruption leaves the last whole version. */
 async function keep(slug, sent) {
   await mkdir(join(exportsDir(), 'langfuse'), { recursive: true });
@@ -203,7 +173,7 @@ export async function exportCommand(argv, ctx = {}) {
   if (auto) {
     const setting = config.projects[only ?? ''];
     if (!setting || !target.publicKey || !target.secretKey) return 0;
-    const release = await lock(only);
+    const release = await takeLock(join(exportsDir(), 'langfuse', `${only}.lock`));
     if (!release) return 0;
     try {
       const result = await exportProject({ slug: only, name: projectName(only), file: join(snapshotsDir(), `${only}.jsonl`), target, now: ctx.now, since: setting.since, quiet: true, content: contextMode(setting) });
@@ -236,7 +206,7 @@ export async function exportCommand(argv, ctx = {}) {
   let failed = false;
   for (const slug of slugs) {
     const name = projectName(slug);
-    const release = dry ? async () => {} : await lock(slug);
+    const release = dry ? async () => {} : await takeLock(join(exportsDir(), 'langfuse', `${slug}.lock`));
     if (!release) {
       console.log(`  ${name}: ✗ another export of this project is running — nothing sent`);
       failed = true;

package/src/commands/gate.mjs

@@ -18,7 +18,7 @@ import { spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, resolve } from 'node:path';
-import { HARNESS, legacyHint, slugFor } from '../paths.mjs';
+import { readProfile, slugFor } from '../paths.mjs';
 import { GATE, hookCommand, missingWiring, shippedScripts } from '../wiring.mjs';
 import { LEDGER_TAIL, ledgerPath, loadProject, projectGateDir, readLedger, runGate } from '../gate.mjs';
 import { projectRecords } from '../store.mjs';
@@ -279,16 +279,9 @@ export async function gate(argv, ctx) {
   const target = resolve(argv.includes('--project') ? argv[argv.indexOf('--project') + 1] : '.');
   if (argv.includes('--hook')) return runGate({ root: target });
 
-  const profilePath = join(target, HARNESS, 'profile.json');
-  if (!existsSync(profilePath)) {
-    console.error(`  no ${HARNESS}/profile.json under ${target}${legacyHint(target)}\n`);
-    return 2;
-  }
-  let profile;
-  try {
-    profile = JSON.parse(readFileSync(profilePath, 'utf8'));
-  } catch (error) {
-    console.error(`  ${profilePath} is not valid JSON — ${error.message}\n`);
+  const { profile, error } = readProfile(target);
+  if (error) {
+    console.error(`  ${error}\n`);
     return 2;
   }
   const resolved = layerRootFor(ctx.root, profile.core);

package/src/commands/init.mjs

@@ -13,16 +13,16 @@
  */
 
 import { createInterface } from 'node:readline/promises';
-import { HARNESS } from '../paths.mjs';
+import { HARNESS, readProfile, surfacesIn } from '../paths.mjs';
 import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
-import { applyWiring, missingWiring, shippedScripts } from '../wiring.mjs';
-import { existsSync, readFileSync } from 'node:fs';
+import { applyWiring, lacksPackage, missingWiring, shippedScripts } from '../wiring.mjs';
+import { existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
-import { REQUIRES, SLOT, byVersion, composeProject, composedPaths, defaultedSlots, layerRootFor, projectOwned, walk } from './compose.mjs';
+import { REQUIRES, SLOT, byVersion, closedGate, composedPaths, composeProject, defaultedSlots, layerRootFor, projectOwned, walk } from './compose.mjs';
 import { owedDocuments } from './check.mjs';
 import { PLACEHOLDER, defaultVocabulary } from '../vocabulary.mjs';
-import { PINK, useColor } from '../banner.mjs';
 import { DETECTABLE, NEEDS } from '../surfaces.mjs';
+import { bold, dim, green, pink } from '../look.mjs';
 
 /**
  * The question each surface answers. Detection can confirm three of them from files; all
@@ -72,11 +72,10 @@ export function askOrder(available) {
   return [...available].sort((a, b) => rank(a) - rank(b) || a.localeCompare(b));
 }
 
-/** The interview's colors — the banner's pink, on a terminal that takes color, and plain everywhere else. */
-const tint = (code, text) => (useColor() ? `\x1b[${code}m${text}\x1b[0m` : text);
-const strong = (text) => tint(`1;38;2;${PINK.join(';')}`, text);
-const faint = (text) => tint('2', text);
-const found = (text) => tint('32', text);
+/** The interview's colors — the reports' own, on a terminal that takes color, and plain everywhere else. */
+const strong = (text) => bold(pink(text));
+const faint = dim;
+const found = green;
 
 /**
  * What declaring a surface actually adds, counted from the layer rather than described.
@@ -149,14 +148,13 @@ async function applicableFiles(root, surfaces) {
   const out = [];
   for (const rel of (await walk(coreTree)).sort()) {
     const core = await readFile(join(coreTree, rel), 'utf8');
-    const requires = REQUIRES.exec(core);
-    if (requires && !surfaces.includes(requires[1])) continue;
+    if (closedGate(core, surfaces)) continue;
     const fragments = [];
     for (const s of surfaces) {
       const text = await readFile(join(root, 'surfaces', s, 'tree', rel), 'utf8').catch(() => null);
       if (text !== null) fragments.push(text);
     }
-    out.push({ rel, core: requires ? core.slice(requires[0].length) : core, fragments });
+    out.push({ rel, core: core.replace(REQUIRES, ''), fragments });
   }
   return out;
 }
@@ -270,21 +268,15 @@ export async function init(argv, ctx) {
   // itself says to re-run with --force to add one, and doing so used to write a profile from nothing —
   // every vocabulary value and integration gone, and the pin moved to the newest release past every
   // check `upgrade` makes.
-  let previous = null;
-  try {
-    previous = JSON.parse(readFileSync(join(harness, 'profile.json'), 'utf8'));
-  } catch (error) {
-    // None: there is nothing to keep. One that is there but cannot be read still holds the pin and every
-    // value the project declared — read as "none", a trailing comma moved the pin to the newest release and
-    // wrote every vocabulary value away.
-    if (error.code !== 'ENOENT') {
-      console.error(
-        `  ${HARNESS}/profile.json cannot be read (${error.message}). Starting over would write a new one over it and keep ` +
-          'nothing it declares — fix it and run this again, or move it aside to start from nothing.\n',
-      );
-      return 1;
-    }
+  // None: there is nothing to keep. One that is there but cannot be read still holds the pin and every value
+  // the project declared — read as "none", a trailing comma moved the pin to the newest release and wrote every
+  // vocabulary value away.
+  const read = readProfile(target);
+  if (read.error && !read.missing) {
+    console.error(`  ${read.error}. Starting over would write a new one over it and keep nothing it declares — fix it and run this again, or move it aside to start from nothing.\n`);
+    return 1;
   }
+  const previous = read.profile ?? null;
   if (previous?.core && arg('--core') && arg('--core') !== previous.core) {
     console.error(`  ${target} pins ${previous.core}. A pin moves with \`nina upgrade --to ${arg('--core')}\`, which says what the move costs and rolls it back when it fails.\n`);
     return 1;
@@ -314,7 +306,7 @@ export async function init(argv, ctx) {
   // harness the project is actually going to compose, not whatever the working tree says.
   // In the order the interview asks them, so the TODO, the brief and the hints list them as it did.
   const available = askOrder(
-    (await readdir(join(resolved.dir, 'surfaces'), { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name),
+    (await surfacesIn(resolved.dir)),
   );
   // Only what the pinned core has: a file can reveal a surface a release added after it.
   matched = matched.filter((d) => available.includes(d.surface));
@@ -441,7 +433,7 @@ export async function init(argv, ctx) {
     `## 1. Vocabulary — ${vocabulary.size} entries`,
     '',
     `Every name below appears in a rule the chosen core and surfaces state generically. Fill each one`,
-    `in \`.nina/profile.json\`; a \`null\` leaves the placeholder standing in the composed output.`,
+    `in \`.nina/profile.json\`; a \`null\` composes as \`[NAME: not declared yet]\` until it is filled.`,
     '',
     ...[...vocabulary].sort().map((name) => `- [ ] \`${name}\``),
     ...(defaulted.length > 0
@@ -608,7 +600,7 @@ export async function init(argv, ctx) {
         : `    composed:  ${composed.written.length} file(s), with holes where .nina/TODO.md §1–§3 go`,
     );
   }
-  const uninstalled = unwired.some((w) => w.startsWith('@xhulz/nina is not installed'));
+  const uninstalled = lacksPackage(unwired);
   if (uninstalled) {
     console.log('    first:     install @xhulz/nina here — until then no hook can load, and nothing tells the model anything');
   }

package/src/commands/langfuse.mjs

@@ -27,7 +27,7 @@ import { exportsDir, slugFor } from '../paths.mjs';
 import { projectName } from './stats.mjs';
 
 /** Where the keys and the switches live. */
-export const configPath = () => join(exportsDir(), 'langfuse.json');
+const configPath = () => join(exportsDir(), 'langfuse.json');
 
 /** What a project sends, in words, by `contextMode`. */
 const LABELS = { full: "with each stage's own context", prompts: "with each stage's prompt and report", none: 'as metadata only' };

package/src/commands/learn.mjs

@@ -25,10 +25,10 @@
 import { existsSync, readdirSync } from 'node:fs';
 import { mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';
 import { join, relative, resolve } from 'node:path';
-import { HARNESS, legacyHint, slugFor, snapshotsDir } from '../paths.mjs';
+import { HARNESS, readProfile, slugFor, snapshotsDir } from '../paths.mjs';
 import { localDay, projectRecords } from '../store.mjs';
 import { isLoopBack, runOf } from '../transcripts.mjs';
-import { REQUIRES, byVersion, layerRootFor } from './compose.mjs';
+import { byVersion, closedGate, layerRootFor } from './compose.mjs';
 import { GRADUATION_AT, RETIRED, frontmatter, graduationTarget, list, pillFiles, roleGates, tidyRetired } from './pills.mjs';
 import { decodeProjectDir } from './stats.mjs';
 import { snapshot } from './snapshot.mjs';
@@ -39,7 +39,7 @@ import { autoExport } from './export.mjs';
 import { beforeModel } from '../detectors.mjs';
 
 /** Loop-backs from one role, since its newest lesson, that make a lesson overdue. */
-export const CAPTURE_AT = 3;
+const CAPTURE_AT = 3;
 
 /**
  * How far back a loop-back still counts. Older ones are history nobody remembers well enough to
@@ -226,7 +226,7 @@ const shift = (date, days) => new Date(Date.parse(`${date}T12:00:00Z`) + days *
  * @param {number} n - Out of how many.
  * @returns {[number, number]}
  */
-export function wilson(k, n) {
+function wilson(k, n) {
   if (n === 0) return [0, 1];
   const z = 1.96;
   const p = k / n;
@@ -349,7 +349,7 @@ export function relapsed(known, filed) {
  * @param {{pill: string}[]} filed - Requests already written, open or closed.
  * @returns {Awaited<ReturnType<typeof lessons>>}
  */
-export function unfiled(known, filed) {
+function unfiled(known, filed) {
   const asked = new Set(filed.map((r) => r.pill));
   return known.filter((l) => !l.retired && l.occurrences >= GRADUATION_AT && !asked.has(l.rel));
 }
@@ -473,8 +473,7 @@ async function missingSurface(layerRoot, layerPath, surfaces) {
   const own = /^surfaces\/([^/]+)\/tree\//.exec(layerPath)?.[1];
   if (own && !surfaces.includes(own)) return own;
   const core = await readFile(join(layerRoot, 'core', 'tree', composedPath(layerPath)), 'utf8').catch(() => '');
-  const gate = REQUIRES.exec(core)?.[1] ?? null;
-  return gate && !surfaces.includes(gate) ? gate : null;
+  return closedGate(core, surfaces);
 }
 
 /**
@@ -494,7 +493,7 @@ async function missingSurface(layerRoot, layerPath, surfaces) {
  */
 export async function closeAnswered(target, layerRoot, version) {
   const given = await answers(layerRoot);
-  const profile = JSON.parse(await readFile(join(target, HARNESS, 'profile.json'), 'utf8').catch(() => '{}'));
+  const profile = readProfile(target).profile ?? {};
   const out = [];
   for (const r of (await filedRequests(target)).filter((r) => r.status === 'open' && given[r.id])) {
     const a = given[r.id];
@@ -685,12 +684,11 @@ export async function learn(argv, ctx) {
   const check = argv.includes('--check');
   const days = argv.includes('--days') ? Number(argv[argv.indexOf('--days') + 1]) || CAPTURE_DAYS : CAPTURE_DAYS;
 
-  const profilePath = join(target, HARNESS, 'profile.json');
-  if (!existsSync(profilePath)) {
-    console.error(`  no ${HARNESS}/profile.json under ${target}${legacyHint(target)}\n`);
+  const { profile, error } = readProfile(target);
+  if (error) {
+    console.error(`  ${error}\n`);
     return check ? 2 : 1;
   }
-  const profile = JSON.parse(await readFile(profilePath, 'utf8'));
   const resolved = layerRootFor(ctx.root, profile.core);
   if (resolved.error) {
     console.error(`  ${resolved.error}\n`);

package/src/commands/pills.mjs

@@ -11,7 +11,7 @@
  */
 
 import { mkdir, readFile, readdir, rename } from 'node:fs/promises';
-import { HARNESS } from '../paths.mjs';
+import { HARNESS, readProfile } from '../paths.mjs';
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import { dirname, join, resolve } from 'node:path';
@@ -124,7 +124,7 @@ export function list(value) {
  * @param {string} citation - `path` or `path:line`.
  * @returns {{state: 'ok'|'gone'|'truncated', path: string, line: number|null, lines?: number}}
  */
-export function resolveCitation(target, citation) {
+function resolveCitation(target, citation) {
   const at = /^(.*):(\d+)$/.exec(citation);
   const path = at ? at[1] : citation;
   const line = at ? Number(at[2]) : null;
@@ -153,7 +153,7 @@ export function resolveCitation(target, citation) {
  * @param {string} path - A path inside it.
  * @returns {string | null} `YYYY-MM-DD`, or `null` when git cannot say.
  */
-export function lastChanged(target, path) {
+function lastChanged(target, path) {
   const git = spawnSync('git', ['-C', target, 'log', '-1', '--format=%cs', '--', path], { encoding: 'utf8' });
   if (git.status !== 0) return null;
   const when = git.stdout.trim();
@@ -383,8 +383,8 @@ export async function pills(argv, ctx) {
   // of a surface, and composition strips that gate — so it has to come from the layers.
   let gates = null;
   try {
-    const profile = JSON.parse(await readFile(join(target, HARNESS, 'profile.json'), 'utf8'));
-    const layers = layerRootFor(ctx?.root ?? '.', profile.core);
+    const { profile } = readProfile(target);
+    const layers = layerRootFor(ctx?.root ?? '.', profile?.core);
     if (!layers.error) gates = await roleGates(layers.dir);
   } catch {
     /* without a profile the candidate is still worth naming; only its target is unknown */