genesis-compiler 1.10.20 → 1.10.22

package/src/index/pass-record.js

@@ -3,27 +3,50 @@ import path from 'node:path';
 
 import { fail } from './errors.js';
 import { gitContext } from './git.js';
-import { PASSES } from './passes.js';
+import { MASTER_PASS, PASSES } from './passes.js';
+import { runGitText } from './process.js';
 import { inspectProjectFormatAtRoot } from './project-format.js';
 import { stableJson, writeFileAtomic } from './utils.js';
 
 // When each pass last finished, committed with the project so every clone and host sees the same record:
-// `{ "<pass id>": "<UTC time>" }`. The pass's own last step writes it, so it lands in the pass's commit and a pass
-// that never finished is never recorded.
+// `{ "<pass id>": "<UTC time>" }`, and the Master pass's time with the passes it ran,
+// `"master-pass": { "lastRun": "<UTC time>", "passes": ["<pass id>", ...] }`. The pass's own last step writes it, so
+// it lands in the pass's commit and a pass that never finished is never recorded.
+// Two files, so that a Genesis older than a pass never meets its record: genesis-compiler 1.10.21 and earlier read only
+// `genesis/passes.json` and refuse an id they do not know, so that file keeps the passes they know, and every pass
+// added since, the Master pass among them, is recorded in `genesis/passes-added.json`. This Genesis keeps an entry it
+// does not know, which a newer Genesis wrote, and leaves it unused, so a pass added later never strands it.
 export const PASS_RECORD_PATH = 'genesis/passes.json';
+export const ADDED_PASS_RECORD_PATH = 'genesis/passes-added.json';
 
+const FIRST_PASS_IDS = Object.freeze([
+  'deslop', 'ui-pass', 'identity-pass', 'quality-pass', 'data-pass', 'security-pass', 'ux-pass', 'speed-pass',
+]);
 const PASS_IDS = PASSES.map(({ task }) => task);
+const RECORDED_IDS = [...PASS_IDS, MASTER_PASS.task];
 const UTC_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/u;
 
-function invalidRecord(problem) {
-  fail('PASS_RECORD_INVALID', `${PASS_RECORD_PATH} ${problem}. It maps pass ids (${PASS_IDS.join(', ')}) to UTC times such as 2026-01-31T09:30:00Z; fix or remove the entry.`, { path: PASS_RECORD_PATH });
+/** The file that records `pass`. */
+export function passRecordPath(pass) {
+  return FIRST_PASS_IDS.includes(pass) ? PASS_RECORD_PATH : ADDED_PASS_RECORD_PATH;
 }
 
-/** The project's pass record: each recorded pass id with the UTC time it last finished. A missing file records none. */
-export async function readPassRecord(root) {
+function invalidRecord(file, problem) {
+  fail('PASS_RECORD_INVALID', `${file} ${problem}. It maps pass ids to UTC times such as 2026-01-31T09:30:00Z, and ${MASTER_PASS.task} to { "lastRun": <UTC time>, "passes": [<pass id>, ...] }; fix or remove the entry.`, { path: file });
+}
+
+const utcTime = (value) => typeof value === 'string' && UTC_TIME.test(value) && !Number.isNaN(Date.parse(value));
+
+// The passes a Master pass ran: pass ids, each once, at least one. A record may name a pass a newer Genesis added; a
+// Master pass recorded here names only passes this Genesis has.
+const passList = (value, known = null) => Array.isArray(value) && value.length > 0
+  && new Set(value).size === value.length
+  && value.every((id) => typeof id === 'string' && (!known || known.includes(id)));
+
+async function readRecordFile(root, file) {
   let source;
   try {
-    source = await readFile(path.join(root, PASS_RECORD_PATH), 'utf8');
+    source = await readFile(path.join(root, file), 'utf8');
   } catch (error) {
     if (error?.code === 'ENOENT') return {};
     throw error;
@@ -32,30 +55,109 @@ export async function readPassRecord(root) {
   try {
     record = JSON.parse(source);
   } catch (error) {
-    invalidRecord(`is not JSON (${error.message})`);
+    invalidRecord(file, `is not JSON (${error.message})`);
   }
-  if (record === null || typeof record !== 'object' || Array.isArray(record)) invalidRecord('is not a JSON object');
-  for (const [id, time] of Object.entries(record)) {
-    if (!PASS_IDS.includes(id)) invalidRecord(`names ${JSON.stringify(id)}, which is not a pass`);
-    if (typeof time !== 'string' || !UTC_TIME.test(time) || Number.isNaN(Date.parse(time))) {
-      invalidRecord(`records ${JSON.stringify(time)} for ${id}, which is not a UTC time`);
+  if (record === null || typeof record !== 'object' || Array.isArray(record)) invalidRecord(file, 'is not a JSON object');
+  return record;
+}
+
+/**
+ * The project's pass record, from both files: each recorded pass id with the UTC time it last finished, and the Master
+ * pass's time with the passes it ran; and, as `unknown`, the entries this Genesis does not know, which it keeps and
+ * does not use. Missing files record none.
+ * @returns {Promise<{ record: object, unknown: { id: string, path: string }[] }>}
+ */
+export async function inspectPassRecord(root) {
+  const record = {};
+  const unknown = [];
+  for (const file of [PASS_RECORD_PATH, ADDED_PASS_RECORD_PATH]) {
+    for (const [id, value] of Object.entries(await readRecordFile(root, file))) {
+      if (!RECORDED_IDS.includes(id)) {
+        unknown.push({ id, path: file });
+        continue;
+      }
+      if (passRecordPath(id) !== file) invalidRecord(file, `records ${id}, which belongs in ${passRecordPath(id)}; move the entry there`);
+      if (id === MASTER_PASS.task) {
+        if (!utcTime(value?.lastRun) || !passList(value?.passes) || Object.keys(value).length !== 2) {
+          invalidRecord(file, `records ${JSON.stringify(value)} for ${id}, which is not a UTC time with the passes it ran`);
+        }
+      } else if (!utcTime(value)) {
+        invalidRecord(file, `records ${JSON.stringify(value)} for ${id}, which is not a UTC time`);
+      }
+      record[id] = value;
     }
   }
-  return record;
+  return { record, unknown };
 }
 
-/** Records that `pass` finished now, as its last step. */
-export async function recordProjectPassDone({ projectRoot, pass, now = new Date() } = {}) {
-  if (!PASS_IDS.includes(pass)) {
-    fail('PASS_UNKNOWN', `${JSON.stringify(pass)} is not a pass; use one of ${PASS_IDS.join(', ')}.`);
+/** The project's pass record: each pass id this Genesis knows with its last finished run. */
+export async function readPassRecord(root) {
+  return (await inspectPassRecord(root)).record;
+}
+
+/** What a reader says about entries it does not know: a newer Genesis wrote them, and updating Genesis uses them. */
+export function unknownRecordMessage(unknown) {
+  const names = unknown.map(({ id, path: file }) => `${id} (${file})`).join(', ');
+  return `The pass record names passes this Genesis does not know: ${names}. A newer Genesis recorded them; they are `
+    + 'kept as they are. Update genesis-compiler to the release that has them to use those records.';
+}
+
+/**
+ * Records that `pass` finished now, as its last step; the Master pass records the passes it ran with it, in the order
+ * it runs them. Entries this Genesis does not know stay as they are.
+ */
+export async function recordProjectPassDone({ projectRoot, pass, passes = [], now = new Date() } = {}) {
+  if (!RECORDED_IDS.includes(pass)) {
+    fail('PASS_UNKNOWN', `${JSON.stringify(pass)} is not a pass this Genesis knows; use one of ${RECORDED_IDS.join(', ')}, or update genesis-compiler to the release that added it.`);
+  }
+  const master = pass === MASTER_PASS.task;
+  if (master ? !passList(passes, PASS_IDS) : passes.length > 0) {
+    fail('PASS_RECORD_PASSES_INVALID', master
+      ? `The ${MASTER_PASS.title} records the passes it ran, each once: name at least one of ${PASS_IDS.join(', ')}.`
+      : `Only the ${MASTER_PASS.title} records the passes it ran; record ${pass} on its own.`);
   }
   const root = (await gitContext(projectRoot)).repositoryRoot;
   const format = await inspectProjectFormatAtRoot(root);
   if (format.status !== 'current') {
     fail('PASS_RECORD_PROJECT_REQUIRED', `Passes are recorded in a current Genesis project; this one is ${format.status} (next action: ${format.action}).`);
   }
+  await inspectPassRecord(root);
+  const file = passRecordPath(pass);
   const lastRun = now.toISOString().replace(/\.\d{3}Z$/u, 'Z');
-  const record = { ...await readPassRecord(root), [pass]: lastRun };
-  await writeFileAtomic(path.join(root, PASS_RECORD_PATH), stableJson(record));
-  return { status: 'recorded', pass, lastRun, path: PASS_RECORD_PATH, changedFiles: [PASS_RECORD_PATH] };
+  const ran = MASTER_PASS.order.filter((id) => passes.includes(id));
+  const entries = { ...await readRecordFile(root, file), [pass]: master ? { lastRun, passes: ran } : lastRun };
+  await writeFileAtomic(path.join(root, file), stableJson(entries));
+  return {
+    status: 'recorded',
+    pass,
+    lastRun,
+    ...(master ? { passes: ran } : {}),
+    path: file,
+    changedFiles: [file],
+  };
+}
+
+/**
+ * The commit that recorded a pass's last completed run, which is the pass's own commit, and the commits since it on
+ * HEAD; null when the run is not committed or that commit is no longer in HEAD's history. Git keeps it: the commit
+ * that added this exact entry to the pass's record file (for the Master pass, its time), so nothing else is stored.
+ * @param {string} root the project's repository root
+ * @param {string} pass the pass id
+ * @param {string | null} lastRun the run's UTC time, from readPassRecord
+ * @returns {Promise<{ commit: string, commitsSince: number } | null>}
+ */
+export async function passRecordCommit(root, pass, lastRun) {
+  if (!lastRun) return null;
+  try {
+    await runGitText(root, ['rev-parse', '--verify', '--quiet', 'HEAD^{commit}']);
+  } catch (error) {
+    // A repository without commits has no history to find the run in.
+    if (error?.code === 'GIT_EXEC_FAILED') return null;
+    throw error;
+  }
+  const entry = pass === MASTER_PASS.task ? `"lastRun": "${lastRun}"` : `"${pass}": "${lastRun}"`;
+  const commit = await runGitText(root, ['log', '-1', '--format=%h', `-S${entry}`, 'HEAD', '--', passRecordPath(pass)]);
+  if (!commit) return null;
+  const commitsSince = Number(await runGitText(root, ['rev-list', '--count', `${commit}..HEAD`]));
+  return { commit, commitsSince };
 }

package/src/index/pass-support.js

@@ -0,0 +1,71 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { projectGenesis } from './agent-skills.js';
+import { GENESIS_CONTRACTS } from './contracts.js';
+
+// The npm option that keeps genesis-compiler in the manifest field the project declares it in.
+const SAVE_OPTIONS = Object.freeze({
+  dependencies: '--save',
+  devDependencies: '--save-dev',
+  optionalDependencies: '--save-optional',
+});
+let hostManifest;
+
+async function readManifest(directory) {
+  try {
+    return JSON.parse(await readFile(path.join(directory, 'package.json'), 'utf8'));
+  } catch (error) {
+    if (['ENOENT', 'ENOTDIR'].includes(error?.code)) return null;
+    throw error;
+  }
+}
+
+/**
+ * Which of this Genesis's passes the project's own Genesis runs. A pass's prompt sends the agent to that Genesis's
+ * workflow skill, and its PASS RECORD step to that Genesis's `passes done`, so that Genesis alone decides, from what
+ * it ships: it runs passes when its package declares this pass-run contract (`genesisContracts.passRuns`), and it has
+ * a pass when its skills folder holds the pass's workflow skill, and it runs each pass's Deep run when its package also
+ * declares the deep-run contract (`genesisContracts.deepRuns`). A project pinned to a release without either, or
+ * whose pinned release is not installed, is told plainly, with the step that fixes it; nothing else stands in for
+ * that release.
+ * @param {string} projectRoot the project's repository root
+ */
+export async function projectPassSupport(projectRoot) {
+  hostManifest ??= projectGenesis().then(({ root }) => readManifest(root));
+  const [genesis, host, project] = await Promise.all([
+    projectGenesis({ projectRoot }).catch((error) => {
+      // A project that declares genesis-compiler without installing it has no Genesis to run a pass yet.
+      if (error?.code === 'AGENT_SKILL_UNAVAILABLE') return null;
+      throw error;
+    }),
+    hostManifest,
+    readManifest(projectRoot),
+  ]);
+  const own = genesis && await readManifest(genesis.root);
+  const named = `This project's Genesis (genesis-compiler ${own?.version || 'of unknown version'})`;
+  const field = Object.keys(SAVE_OPTIONS).find((name) => Object.hasOwn(project?.[name] || {}, 'genesis-compiler'));
+  const update = field
+    ? `Update it to ${host.version} or later with npm install ${SAVE_OPTIONS[field]} genesis-compiler@${host.version}, then commit the change.`
+    : `Update it to ${host.version} or later.`;
+  const declared = own?.genesisContracts?.passRuns;
+  let unavailable = null;
+  if (!genesis) {
+    unavailable = "This project's Genesis (genesis-compiler) is not installed. Install the project's dependencies with npm install.";
+  } else if (declared !== GENESIS_CONTRACTS.passRuns) {
+    unavailable = declared
+      ? `${named} runs passes differently from genesis-compiler ${host.version}. Update the older of the two.`
+      : `${named} cannot run passes. ${update}`;
+  }
+  const has = (pass) => Boolean(genesis?.coreSkills.includes(`genesis-${pass.task}`));
+  return {
+    /** Why the project's Genesis runs no pass, naming the update; null when it runs them. */
+    unavailable,
+    /** Whether the project's Genesis has the pass's task, which its prompt needs even when no pass is recorded. */
+    has,
+    /** Whether the project's Genesis runs each pass's Deep run: its package declares this deep-run contract. */
+    deep: unavailable === null && own.genesisContracts.deepRuns === GENESIS_CONTRACTS.deepRuns,
+    /** Why the project's Genesis cannot run this pass, naming the update; null when it can. */
+    unavailableFor: (pass) => unavailable ?? (has(pass) ? null : `${named} has no ${pass.title}. ${update}`),
+  };
+}

package/src/index/passes.js

@@ -1,17 +1,24 @@
 /**
  * The passes: operations a person asks for by name over a scope of the project, never run because a turn finished.
  * Each is a prompt task (`task`) with a workflow skill (`genesis-<task>`) and a Stack section (`section`), whose prose
- * the selected components add to the task's prompt under `heading`. `request` is the request when none is given.
+ * the selected components add to the task's prompt under `heading`. `request` is the pass's own request, which names
+ * the whole app: a pass covers the whole app, and Genesis records a pass only when its prompt carries this request.
+ * The task's request when none is given is the task's own (prompt.js), which for Deslop and the UI pass stays the
+ * agent's own changes.
  * A host lists the passes with inspectPasses() and decides itself when to offer one: `recommend` is a hint
- * (`when`: `after-change`, `first-version` or `periodic`), never a schedule.
+ * (`when`: `after-change`, `first-version` or `periodic`), never a schedule. A host may also run a pass over the
+ * changes since a base commit it chooses, such as where a piece of work started (baseRequest); Genesis never records
+ * those runs, so they never move the pass's last completed run.
+ * `selfContained` marks a pass whose prompt carries all its instructions, without its skill: it was a task before it
+ * was a pass, so it still runs as that task, and over a base, where the project's own Genesis lacks the pass.
  */
 export const PASSES = Object.freeze([
   {
     task: 'deslop',
     title: 'Deslop',
-    description: 'Simplifies changes without changing what they do: no repeated helpers, unclear code or code that ignores the project\'s patterns.',
+    description: 'Simplifies the app\'s code without changing what it does: no repeated helpers, unclear code or code that ignores the project\'s patterns.',
     recommend: { when: 'after-change', hint: 'after each saved change' },
-    request: 'Deslop your own changes for the current task.',
+    request: 'Deslop the whole app.',
     section: 'Deslop',
     field: 'deslop',
     heading: 'SELECTED STACK CLEANUP GUIDANCE',
@@ -21,7 +28,7 @@ export const PASSES = Object.freeze([
     title: 'UI pass',
     description: 'Makes screens follow the design rules of the project\'s technology exactly, without changing what they do.',
     recommend: { when: 'after-change', hint: 'after a change to the screens' },
-    request: 'UI pass your own changes for the current task.',
+    request: 'UI pass the whole app.',
     section: 'UI pass',
     field: 'uiPass',
     heading: 'SELECTED STACK UI PASS GUIDANCE',
@@ -56,4 +63,84 @@ export const PASSES = Object.freeze([
     field: 'dataPass',
     heading: 'SELECTED STACK DATA PASS GUIDANCE',
   },
+  {
+    task: 'security-pass',
+    title: 'Security pass',
+    description: 'Makes the app refuse what it should: permission checked on every action, guarded sign-in, inputs checked at the boundary, no exposed secrets and safe production settings, each fix proved by trying the attack.',
+    recommend: { when: 'periodic', hint: 'after a stretch of changes, about every few weeks of active work, and before a first release' },
+    request: 'Security pass the whole app.',
+    section: 'Security pass',
+    field: 'securityPass',
+    heading: 'SELECTED STACK SECURITY PASS GUIDANCE',
+  },
+  {
+    task: 'ux-pass',
+    title: 'User experience pass',
+    description: 'Makes the main things people do short and clear: fewer steps and decisions, easy to find, plain words, good defaults and mistakes easy to undo, each task walked before and after.',
+    recommend: { when: 'periodic', hint: 'after a stretch of changes, about every few weeks of active work, and before new people start using the app' },
+    request: 'User experience pass the whole app.',
+    section: 'User experience pass',
+    field: 'uxPass',
+    heading: 'SELECTED STACK UX PASS GUIDANCE',
+  },
+  {
+    task: 'speed-pass',
+    title: 'Speed pass',
+    description: 'Makes the app and its tests fast: tests prepared once and run in parallel, screens that load only what they need, and requests that do each piece of work once, each wait measured before and after with nothing weakened.',
+    recommend: { when: 'periodic', hint: 'after a stretch of changes, about every few weeks of active work, and whenever tests, pages or saves feel slow' },
+    request: 'Speed pass the whole app.',
+    section: 'Speed pass',
+    field: 'speedPass',
+    heading: 'SELECTED STACK SPEED PASS GUIDANCE',
+  },
+  {
+    task: 'review',
+    title: 'Review',
+    description: 'Checks the work against what the app should do: a test that would fail without each behavior, nothing weakened or skipped, and gaps between intent, code and explanation, changing only tests.',
+    recommend: { when: 'after-change', hint: 'after each saved change' },
+    request: 'Review the whole app.',
+    section: 'Review',
+    field: 'review',
+    heading: 'SELECTED STACK REVIEW GUIDANCE',
+    selfContained: true,
+  },
 ].map((pass) => Object.freeze({ ...pass, recommend: Object.freeze(pass.recommend) })));
+
+/**
+ * The Master pass: the passes run deeply, one after another, each as its own Deep run, committed and tested before the
+ * next starts. It runs every pass the project offers, or the ones a request names, always in `order`, whatever order
+ * they were named in: the review first, so every later pass starts from tested work, then security, so later passes
+ * build on the access it fixes, and Deslop last, so it cleans up after what the others changed. Every pass has a place
+ * in `order`; a pass added later takes one there.
+ */
+export const MASTER_PASS = Object.freeze({
+  task: 'master-pass',
+  title: 'Master pass',
+  description: 'Runs every pass deeply, one after another, or the passes you choose, committing and running the whole test suite after each.',
+  request: 'Master pass the whole app.',
+  order: Object.freeze([
+    'review', 'security-pass', 'data-pass', 'quality-pass', 'speed-pass', 'ux-pass', 'identity-pass', 'ui-pass', 'deslop',
+  ]),
+});
+
+/**
+ * The request of a pass's Deep run: its pass request deeply, or, for a Master pass since its last completed run, the
+ * changes since that commit deeply, judged against the whole app.
+ * @param {{ title: string, request: string }} pass
+ * @param {string | null} [commit] the commit of the Master pass's last completed run, for a run since it
+ */
+export function deepRequest(pass, commit = null) {
+  return commit
+    ? `${pass.title} deeply: the changes since commit ${commit}, judged against the whole app.`
+    : pass.request.replace(/\.$/u, ' deeply.');
+}
+
+/**
+ * The request of a run over the changes since a base commit a host chooses, judged against the whole app, or of its
+ * deep form; `{base}` stands for the commit. Genesis never records these runs.
+ * @param {{ title: string }} pass
+ * @param {boolean} [deep]
+ */
+export function baseRequest(pass, deep = false) {
+  return `${pass.title}${deep ? ' deeply' : ''}: the changes since base commit {base}, judged against the whole app.`;
+}

package/src/index/project-files.js

@@ -4,7 +4,8 @@ import { runGit } from './process.js';
 import { pathState } from './utils.js';
 import { inspectProjectContent } from './project-inspection.js';
 
-async function visiblePaths(projectRoot) {
+/** Git-visible paths: tracked and untracked files that are not ignored or deleted, sorted. */
+export async function visiblePaths(projectRoot) {
   const [visible, deleted] = await Promise.all([
     runGit(projectRoot, ['ls-files', '-z', '--cached', '--others', '--exclude-standard', '--', '.']),
     runGit(projectRoot, ['ls-files', '-z', '--deleted', '--', '.']),