@xhulz/nina 0.48.0 → 0.50.0

package/releases/0.50.0/surfaces/prisma/tree/.claude/agents/integration-tester.md

@@ -0,0 +1,2 @@
+<!-- nina:slot prisma.1 -->
+| `prisma-cli` | a Prisma CLI command |

package/releases/0.50.0/surfaces/prisma/tree/.claude/agents/reviewer.md

@@ -0,0 +1,2 @@
+<!-- nina:slot prisma.1 -->
+| `prisma-client-api` | a new or changed Prisma query |

package/releases/0.50.0/surfaces/prisma/tree/.claude/patterns.md

@@ -0,0 +1,15 @@
+<!-- nina:slot prisma.1 -->
+- **Database table/column names** (Prisma `@map` / `@@map`): `snake_case` in SQL, `camelCase` in TS.
+
+<!-- nina:slot prisma.2 -->
+- Where Prisma reads are cached through Accelerate, `cacheStrategy` lives in `{{DB_PKG}}`: services do not add, strip, or override cache policies.
+
+<!-- nina:slot prisma.3 -->
+
+### Prisma
+
+- Schema lives in `{{DB_PKG}}/prisma/schema.prisma`. Nowhere else.
+- **Never write raw SQL** unless justified in a code comment with perf data.
+- N+1 is solved with `include` / `select`, chosen deliberately.
+- Where reads are cached through Accelerate, every `findUnique` / `findMany` on a hot path defines its `cacheStrategy`, and no direct connection string is embedded in code.
+- Tests run a real Prisma client against a real database; the client is never mocked.

package/releases/0.50.0/surfaces/prisma/tree/CLAUDE.md

@@ -0,0 +1,5 @@
+<!-- nina:slot prisma.1 -->
+| Run any `prisma` CLI command (the database gate, devops, and the integration gate where there is one) | `prisma-cli` | flags differ between versions; `migrate diff --shadow-database-url` against a live DB wiped dev/staging once |
+
+<!-- nina:slot prisma.2 -->
+| Write or audit a Prisma query (architect, implementer, the database gate, reviewer) | `prisma-client-api` | filters, operators, `$transaction` semantics. a caching or edge layer on top of the client is **NOT covered** — its cache strategy belongs to that layer's own integration doc |

package/src/commands/check.mjs

@@ -14,7 +14,7 @@ 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 { existsSync, readdirSync, realpathSync } from 'node:fs';
 import { join, resolve, sep } from 'node:path';
 import { SLOT, closedGate, defaultedSlots, layerRootFor, noticeOf, readLayerText, stripWhy, walk } from './compose.mjs';
 import { PLACEHOLDER, defaultVocabulary } from '../vocabulary.mjs';
@@ -182,6 +182,138 @@ export async function unwiredScripts(layerRoot, surfaces, target) {
     .sort();
 }
 
+const STORE = 'node_modules/.pnpm/';
+const PATH_CHAR = /[\w.@+\-/]/;
+const STORE_DIR = `${sep}node_modules${sep}.pnpm${sep}`;
+
+/** The project's root and every directory two levels down holding a package.json: where a package links its deps. */
+function packageDirs(target) {
+  const dirs = [target];
+  const visit = (dir, depth) => {
+    let entries = [];
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.name === 'node_modules' || entry.name.startsWith('.')) continue;
+      const sub = join(dir, entry.name);
+      if (existsSync(join(sub, 'package.json'))) dirs.push(sub);
+      if (depth > 1) visit(sub, depth - 1);
+    }
+  };
+  visit(target, 2);
+  return dirs;
+}
+
+/** The libraries a `node_modules` directory links, scoped ones included. */
+function linksIn(modules) {
+  const out = [];
+  let entries = [];
+  try {
+    entries = readdirSync(modules);
+  } catch {
+    return out;
+  }
+  for (const name of entries.filter((entry) => !entry.startsWith('.'))) {
+    if (!name.startsWith('@')) out.push(join(modules, name));
+    else {
+      try {
+        for (const inner of readdirSync(join(modules, name))) out.push(join(modules, name, inner));
+      } catch {
+        // Not a scope after all.
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Each store's directories the install uses: those a package links, and every one they link in turn. What is left
+ * is what a peer change renamed away, kept on disk and linked by nothing.
+ *
+ * @param {string} target - The project directory.
+ * @returns {Map<string, Set<string>>} Store directory (real path) → the names in it still in use.
+ */
+function liveStoreDirs(target) {
+  const live = new Map();
+  const queue = [];
+  const reach = (link) => {
+    let real;
+    try {
+      real = realpathSync(link);
+    } catch {
+      return;
+    }
+    const at = real.indexOf(STORE_DIR);
+    if (at === -1) return;
+    const store = real.slice(0, at + STORE_DIR.length - 1);
+    const name = real.slice(at + STORE_DIR.length).split(sep)[0];
+    if (!live.has(store)) live.set(store, new Set());
+    if (live.get(store).has(name)) return;
+    live.get(store).add(name);
+    queue.push(join(store, name, 'node_modules'));
+  };
+  for (const dir of packageDirs(target)) for (const link of linksIn(join(dir, 'node_modules'))) reach(link);
+  while (queue.length > 0) for (const link of linksIn(queue.pop())) reach(link);
+  return live;
+}
+
+/**
+ * The paths into the package manager's store that a text cites and the install no longer uses. Only the store: its
+ * directory names carry a suffix per peer, renamed when an unrelated dependency changes one, and the old directory
+ * stays on disk, linked by nothing — so a citation still opens on the machine that wrote it. A store path is stale
+ * when its file is gone, or when its directory is not among those the install reaches from the packages' own links
+ * (the root and packages two levels down); a store nothing reaches is judged by the file alone. A path through a
+ * package's own link, or one written from some package's directory, cannot be told stale from here. A line number
+ * after a path is not part of it; an elision (`...`, `…`), a template and a URL are not citations. Each occurrence of
+ * the store is read outwards, and the next is looked for past it, so the text is read once.
+ *
+ * @param {string} text
+ * @param {string} target - The project directory.
+ * @param {Map<string, Map<string, Set<string>>>} [reached] - What the install reaches, by project, kept between
+ *   the docs of one run so the store is walked once.
+ * @returns {string[]} Each stale path once, in the order cited.
+ */
+export function unresolvedCitations(text, target, reached = new Map()) {
+  const cited = new Set();
+  let at = text.indexOf(STORE);
+  while (at !== -1) {
+    let start = at;
+    while (start > 0 && PATH_CHAR.test(text[start - 1])) start -= 1;
+    let end = at + STORE.length;
+    while (end < text.length && PATH_CHAR.test(text[end])) end += 1;
+    const path = text.slice(start, end).replace(/[/.]+$/, '');
+    const url = text[start - 1] === ':' && path.startsWith('//');
+    const elided = text[start - 1] === '…' || text[end] === '…' || path.split('/').includes('...');
+    const template = text[end] === '<';
+    if (!url && !elided && !template && !path.endsWith('.pnpm')) cited.add(path);
+    at = text.indexOf(STORE, end);
+  }
+  if (cited.size === 0) return [];
+  if (!reached.has(target)) reached.set(target, liveStoreDirs(target));
+  const live = reached.get(target);
+  const stale = (path) => {
+    const from = path.indexOf(STORE);
+    const [dir, ...rest] = path.slice(from + STORE.length).split('/');
+    // The store the citation names: the one under the directory it is written in (a spike's own), else the
+    // project's — an absolute path from another machine, or `../../` from a package's directory, leads there.
+    const prefix = path.startsWith('/') ? '' : path.slice(0, from).replace(/^(?:\.\.?\/)+/, '');
+    const named = join(target, prefix, 'node_modules', '.pnpm');
+    if (!existsSync(join(named, dir, ...rest))) return true;
+    let store;
+    try {
+      store = realpathSync(named);
+    } catch {
+      return true;
+    }
+    const used = live.get(store);
+    return Boolean(used) && !used.has(dir);
+  };
+  return [...cited].filter(stale);
+}
+
 /**
  * `nina check`.
  *
@@ -307,6 +439,19 @@ export async function check(argv, ctx) {
     if (why) deferredUsed.add(key);
     notes.push(why ? `deferred: ${key} — ${why}` : `${key} documents no declared integration — declare it, or say under "deferred" why not: retired, or waiting for its boundary`);
   }
+  // A premise cites installed source by its path, and a path into the package manager's store dies when a peer
+  // change renames the directory: the version and the file unchanged, the citation pointing where no fresh install
+  // looks. Said per doc, so each premise is re-cited before anyone trusts it.
+  const reached = new Map();
+  for (const doc of docs.filter((name) => name.endsWith('.md')).sort()) {
+    const key = `.claude/integrations/${doc}`;
+    const gone = unresolvedCitations(await readFile(join(target, key), 'utf8').catch(() => ''), target, reached);
+    if (gone.length > 0) {
+      notes.push(
+        `${key} cites ${gone.length} path(s) in the package manager's store that the install no longer uses — ${gone[0]}${gone.length > 1 ? ', …' : ''}: a peer change renames those directories, and the old one stays on disk linked by nothing; re-cite each from the depending package's own node_modules link, with its version beside it`,
+      );
+    }
+  }
 
   const slots = await projectSlots(resolved.dir, surfaces);
   const filled = await filledSlots(target);

package/src/commands/gate.mjs

@@ -21,7 +21,7 @@ import { tmpdir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { readProfile, slugFor } from '../paths.mjs';
 import { GATE, hookCommand, missingWiring, shippedScripts } from '../wiring.mjs';
-import { LEDGER_TAIL, ledgerPath, loadProject, loopState, projectGateDir, readLedger, runGate } from '../gate.mjs';
+import { LEDGER_TAIL, ledgerPath, loadProject, loopState, projectGateDir, readLedger, runGate, sessionLedgers } from '../gate.mjs';
 import { projectRecords } from '../store.mjs';
 import { layerRootFor } from './compose.mjs';
 import { handsToModel } from '../detectors.mjs';
@@ -286,24 +286,18 @@ function loopStatus(target, wanted) {
     console.error('  .claude/graph.md is not composed, so the gate has no loops to hold — run `nina compose`\n');
     return 2;
   }
-  const dir = projectGateDir(target);
-  const ledgers = (existsSync(dir) ? readdirSync(dir) : [])
-    .filter((f) => f.endsWith('.jsonl') && f !== 'errors.jsonl')
-    .map((f) => ({ session: f.slice(0, -'.jsonl'.length), written: statSync(join(dir, f)).mtime }))
-    .sort((a, b) => b.written - a.written);
+  const { dir, ledgers, picked, why } = sessionLedgers(target, wanted);
   if (ledgers.length === 0 && !wanted) {
     console.log(`  the gate has no ledger here yet: no session has dispatched a stage since it was wired (${dir})`);
     console.log('gate: no open loop');
     return 0;
   }
-  const matching = wanted ? ledgers.filter((l) => l.session.startsWith(wanted)) : ledgers.slice(0, 1);
-  if (matching.length !== 1) {
-    const why = matching.length === 0 ? `no session starts with "${wanted}"` : `${matching.length} sessions start with "${wanted}" — give more of the id`;
+  if (!picked) {
     console.error(`  ${why} (${dir})\n`);
     return 2;
   }
-  const { session, written } = matching[0];
-  const state = loopState(project, readLedger(join(dir, `${session}.jsonl`)));
+  const { session, written, path } = picked;
+  const state = loopState(project, readLedger(path));
   const others = ledgers.length > 1 ? `; ${ledgers.length - 1} other session(s) kept here, --session <id> for one` : '';
   console.log(`  session ${session}, its ledger last written ${written.toISOString().slice(0, 16).replace('T', ' ')} UTC${others}`);
   for (const line of state.lines) console.log(`  ${line}`);

package/src/commands/pipeline.mjs

@@ -168,7 +168,8 @@ export function historyOf(records, since) {
 /**
  * Runs the command.
  *
- * @param {string[]} argv - `[--project <dir>] [--for <number or words>] [--since <YYYY-MM-DD>]`.
+ * @param {string[]} argv - `[--project <dir>] [--for <number or words>] [--since <YYYY-MM-DD>]`, or `--view [--session <id>]
+ *   [--replay] [--port <n>] [--open]` for the office.
  * @returns {Promise<number>} Process exit code.
  */
 export async function pipeline(argv) {
@@ -179,6 +180,26 @@ export async function pipeline(argv) {
     console.error(`  no .claude/graph.md in ${dir} — this draws a composed pipeline: \`nina compose\` writes one`);
     return 1;
   }
+  // The office: the same graph as a room, its agents at their desks, live or replayed (src/office.mjs).
+  const viewOnly = ['--session', '--replay', '--port', '--open'].filter((flag) => argv.includes(flag));
+  if (viewOnly.length > 0 && !argv.includes('--view')) {
+    console.error(`  ${viewOnly.join(', ')} ${viewOnly.length > 1 ? 'belong' : 'belongs'} to the office, and mean${viewOnly.length > 1 ? '' : 's'} nothing without --view`);
+    return 2;
+  }
+  if (argv.includes('--view')) {
+    const drawingOnly = ['--for', '--since'].filter((flag) => argv.includes(flag));
+    if (drawingOnly.length > 0) {
+      console.error(`  ${drawingOnly.join(', ')} ${drawingOnly.length > 1 ? 'are' : 'is'} for the drawing, not the office`);
+      return 2;
+    }
+    const { viewOffice } = await import('../office.mjs');
+    const port = arg('--port');
+    if (port !== null && !(/^\d+$/.test(port) && Number(port) <= 65535)) {
+      console.error(`  --port takes a port number, 0 to 65535, and was given ${port}`);
+      return 2;
+    }
+    return viewOffice({ target: dir, wanted: arg('--session') || undefined, replay: argv.includes('--replay'), port: port === null ? undefined : Number(port), open: argv.includes('--open') });
+  }
   const graphText = readFileSync(graphPath, 'utf8');
   const graph = parseGraph(graphText);
   const words = stageWords(graphText);

package/src/commands/upgrade.mjs

@@ -364,6 +364,14 @@ export async function upgrade(argv, ctx) {
   const scriptsBefore = await shippedScripts(from.dir, surfaces);
   const newScripts = new Set([...(await shippedScripts(onto.dir, kept))].filter((s) => !scriptsBefore.has(s)));
   const unwired = newScripts.size > 0 ? await missingWiring(target, newScripts) : [];
+  // A script already run whose hooks this NINA needs more of — a matcher that grew — holds what it held, so it does
+  // not stop the move; it is said, with what fixes it.
+  const stillRun = new Set([...(await shippedScripts(onto.dir, kept))].filter((s) => scriptsBefore.has(s)));
+  const widened = stillRun.size > 0 ? (await missingWiring(target, stillRun)).filter((w) => / hook running `[^`]+` does not match /.test(w)) : [];
+  if (widened.length > 0) {
+    for (const w of widened) console.log(`  · ${w}`);
+    console.log('');
+  }
   if (unwired.length > 0) {
     console.log(`  ✗ ${unwired.length} hook(s) or script(s) that ${to}'s new ${[...newScripts].join(', ')} need(s) are not wired:`);
     for (const w of unwired) console.log(`      ${w}`);

package/src/gate.mjs

@@ -18,6 +18,8 @@
  *   PreToolUse / PostToolUse on Agent, Task, SendMessage
  *                                     a dispatch launched, and the agent it launched
  *   UserPromptSubmit (human text only) the owner spoke, and every open loop gets one round more
+ *   PreToolUse / PostToolUse on AskUserQuestion
+ *                                     the orchestrator asked the owner, and was answered: when, for the office
  *   PreToolUse on Agent, Task, SendMessage
  *                                     the decision: let it through, or send the round past the cap to
  *                                     the owner to confirm
@@ -606,6 +608,10 @@ function onPost(input, project, path, at) {
   }
   // A dispatch made inside a subagent is not the pipeline's: its stages are dispatched by the orchestrator.
   if (input.agent_id) return null;
+  if (tool === 'AskUserQuestion') {
+    append(path, { k: 'answered', at });
+    return null;
+  }
   if (!DISPATCH.has(tool)) return null;
   const response = input.tool_response && typeof input.tool_response === 'object' ? input.tool_response : {};
   let role;
@@ -659,13 +665,23 @@ function confirmation(r) {
 
 /** A dispatch is about to go out: note when, and send the round past its edge's cap to the owner to confirm. */
 function onPre(input, project, path, at) {
+  // The orchestrator asking the owner, as it asks: when it was, and nothing it said. Nothing counts it; the office
+  // (`nina pipeline --view`) draws the question over its head until the answer, which `onPost` records.
+  if (!input.agent_id && input.tool_name === 'AskUserQuestion') {
+    append(path, { k: 'question', at });
+    return null;
+  }
   if (input.agent_id || !DISPATCH.has(input.tool_name)) return null;
   const entries = readLedger(path);
-  const role = input.tool_name === 'SendMessage' ? recipient(entries, project, input.tool_input?.to).role : input.tool_input?.subagent_type;
+  const to = input.tool_name === 'SendMessage' ? recipient(entries, project, input.tool_input?.to) : null;
+  const role = to ? to.role : input.tool_input?.subagent_type;
   if (!role || !project.graph.stages.has(role)) return null;
   // When it went out, whatever the owner decides: joined to its `dispatch` entry by the tool_use id,
-  // it is the moment the fixer was sent — which is what a later review has to begin after.
-  append(path, { k: 'pre', at, role, id: input.tool_use_id ?? null });
+  // it is the moment the fixer was sent — which is what a later review has to begin after. A message says so, and
+  // names its agent when the ledger already knows it — never a name the model wrote that nothing launched — so the
+  // office can tell a message to a running agent from a resume before the `dispatch` entry is written.
+  const known = to?.agent && entries.some((e) => e.k === 'dispatch' && e.agent === to.agent);
+  append(path, { k: 'pre', at, role, id: input.tool_use_id ?? null, ...(to ? { via: 'SendMessage', ...(known ? { agent: to.agent } : {}) } : {}) });
   const over = roundsFor(entries, role, project.loops, project.forward)
     .filter((r) => excess(r) > 0)
     .sort((a, b) => excess(b) - excess(a));
@@ -686,6 +702,35 @@ function onPre(input, project, path, at) {
   return confirmation(worst);
 }
 
+/**
+ * A project's session ledgers, the newest first, and the one asked for: the latest, or the one whose id starts
+ * with `wanted`. `nina gate --status` and the office (`nina pipeline --view`) pick a session through this, so
+ * the two never show different ones.
+ *
+ * @param {string} root - The project directory.
+ * @param {string} [wanted] - The start of a session id; absent, the session whose ledger was written last.
+ * @returns {{dir: string, ledgers: {session: string, written: Date, path: string}[], picked: {session: string, written: Date, path: string}|null, why: string|null}}
+ *   `why` says why nothing was picked, and is null when there is simply no ledger yet.
+ */
+export function sessionLedgers(root, wanted) {
+  const dir = projectGateDir(root);
+  const ledgers = (existsSync(dir) ? readdirSync(dir) : [])
+    .filter((f) => f.endsWith('.jsonl') && f !== 'errors.jsonl')
+    .flatMap((f) => {
+      // Pruned between the listing and here, by another session: gone, and not a failure.
+      try {
+        return [{ session: f.slice(0, -'.jsonl'.length), written: statSync(join(dir, f)).mtime, path: join(dir, f) }];
+      } catch {
+        return [];
+      }
+    })
+    .sort((a, b) => b.written - a.written);
+  const matching = wanted ? ledgers.filter((l) => l.session.startsWith(wanted)) : ledgers.slice(0, 1);
+  if (matching.length === 1) return { dir, ledgers, picked: matching[0], why: null };
+  const why = !wanted ? null : matching.length === 0 ? `no session starts with "${wanted}"` : `${matching.length} sessions start with "${wanted}" — give more of the id`;
+  return { dir, ledgers, picked: null, why };
+}
+
 /** Stages as a sentence lists them: `qa`, `implementer or architect`, `a, b or c`. */
 const either = (stages) => (stages.length < 2 ? stages.join('') : `${stages.slice(0, -1).join(', ')} or ${stages.at(-1)}`);