session-orchestrator 5.3.0 → 5.5.0

package/scripts/self-update.mjs

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+/**
+ * Bring every LOCAL install of Session Orchestrator to the newest version in
+ * one command: this clone, the Claude Code plugin, and the Codex plugin.
+ *
+ * WHY THIS EXISTS: an update was three independent manual acts, and the
+ * second one has a silent hole. Measured 2026-10-02 (5.3.0 → 5.4.0, Claude
+ * Code 2.1.287): `claude plugin update` succeeded but left the cache WITHOUT
+ * node_modules — `claude plugin list --json` carried
+ * `noteDetails: [{type: "dependencies-refused"}]` because package.json sets
+ * `overrides`. Hooks survive that (no static third-party imports), skill
+ * scripts and the MCP server do not. This script reads that state back and
+ * installs the runtime dependencies itself.
+ *
+ * Steps (each skipped when its harness is not installed on this host):
+ *   1. repo    — `git fetch origin` + `git merge --ff-only origin/main`, then
+ *                `npm ci` when HEAD moved or node_modules is missing.
+ *   2. claude  — marketplace update + plugin update, then verify version and
+ *                runtime dependencies in the reported installPath.
+ *   3. codex   — only if the plugin is already installed in Codex: re-run
+ *                scripts/codex-install.mjs (refreshes the installed bundle).
+ *
+ * Never deletes an old plugin cache directory: the running session still
+ * loads it until the harness restarts.
+ *
+ * Exit codes: 0 all steps ok/skipped · 1 usage error · 2 a step failed.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+import { isMainModule } from './lib/is-main-module.mjs';
+
+const SO_ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const PLUGIN_ID = 'session-orchestrator@kanevry';
+const MARKETPLACE = 'kanevry';
+const COMMAND_TIMEOUT_MS = 300_000;
+// `codex plugin list --available --json` is 2.56 MB on a host with several
+// marketplaces (measured 2026-10-02); the 1 MiB default fails with ENOBUFS.
+const MAX_BUFFER = 64 * 1024 * 1024;
+
+/**
+ * Pick the session-orchestrator entry from `claude plugin list --json`.
+ * Accepts both the bare-array and the `{plugins: [...]}` shape.
+ * @param {unknown} listJson
+ * @returns {{version?: string, installPath?: string, enabled?: boolean, noteDetails?: Array<{type?: string}>} | null}
+ */
+export function findClaudeEntry(listJson) {
+  const entries = Array.isArray(listJson) ? listJson : listJson?.plugins;
+  if (!Array.isArray(entries)) return null;
+  return entries.find((e) => e?.id === PLUGIN_ID && e?.scope === 'user')
+    ?? entries.find((e) => e?.id === PLUGIN_ID)
+    ?? null;
+}
+
+/**
+ * Runtime dependencies of the package at `dir` that have no directory under
+ * `dir/node_modules`. A presence check, not a version check: its job is to
+ * catch the harness having skipped the install entirely.
+ * @param {string} dir
+ * @returns {string[]}
+ */
+export function missingRuntimeDeps(dir) {
+  const pkg = JSON.parse(readFileSync(path.join(dir, 'package.json'), 'utf8'));
+  return Object.keys(pkg.dependencies ?? {})
+    .filter((name) => !existsSync(path.join(dir, 'node_modules', name)));
+}
+
+function parseArguments(argv) {
+  const opts = { dryRun: false, json: false, skipPull: false, help: false };
+  for (const arg of argv) {
+    if (arg === '--dry-run') opts.dryRun = true;
+    else if (arg === '--json') opts.json = true;
+    else if (arg === '--skip-pull') opts.skipPull = true;
+    else if (arg === '--help' || arg === '-h') opts.help = true;
+    else throw Object.assign(new Error(`Unknown argument '${arg}'. Run with --help.`), { usage: true });
+  }
+  return opts;
+}
+
+const HELP = `Usage: node scripts/self-update.mjs [--dry-run] [--skip-pull] [--json]
+
+Update this clone, the Claude Code plugin and (if installed) the Codex plugin
+to the newest Session Orchestrator, and verify each one afterwards.
+
+  --dry-run    Print what would run; change nothing
+  --skip-pull  Leave the clone as it is (e.g. right after a release)
+  --json       Print the per-step result as JSON
+`;
+
+function makeRunner({ dryRun, json }) {
+  const log = (line) => { if (!json) process.stdout.write(`${line}\n`); };
+  /** Run a command; read-only queries also run under --dry-run. */
+  function run(cmd, args, { cwd = SO_ROOT, mutates = true } = {}) {
+    const shown = `${cmd} ${args.join(' ')}`;
+    if (dryRun && mutates) {
+      log(`  [dry-run] ${shown}${cwd === SO_ROOT ? '' : `   (in ${cwd})`}`);
+      return { ok: true, stdout: '' };
+    }
+    const r = spawnSync(cmd, args, { cwd, encoding: 'utf8', timeout: COMMAND_TIMEOUT_MS, maxBuffer: MAX_BUFFER });
+    if (r.error) return { ok: false, detail: `${shown}: ${r.error.message}` };
+    if (r.status !== 0) {
+      return { ok: false, detail: `${shown} exited ${r.status}: ${(r.stderr || r.stdout || '').trim().slice(-400)}` };
+    }
+    return { ok: true, stdout: r.stdout };
+  }
+  return { run, log };
+}
+
+function onPath(bin) {
+  return spawnSync('which', [bin], { encoding: 'utf8' }).status === 0;
+}
+
+function repoVersion() {
+  return JSON.parse(readFileSync(path.join(SO_ROOT, 'package.json'), 'utf8')).version;
+}
+
+function updateRepo({ run, log }, opts) {
+  if (opts.skipPull) return { step: 'repo', status: 'skipped', detail: '--skip-pull' };
+  const before = run('git', ['rev-parse', 'HEAD'], { mutates: false });
+  if (!before.ok) return { step: 'repo', status: 'failed', detail: before.detail };
+  const branch = run('git', ['branch', '--show-current'], { mutates: false }).stdout?.trim();
+  if (branch !== 'main') {
+    return { step: 'repo', status: 'failed', detail: `clone is on '${branch}', not main — switch or use --skip-pull` };
+  }
+  log('repo: fetching origin and fast-forwarding main');
+  for (const [cmd, args] of [['git', ['fetch', 'origin']], ['git', ['merge', '--ff-only', 'origin/main']]]) {
+    const r = run(cmd, args);
+    if (!r.ok) return { step: 'repo', status: 'failed', detail: r.detail };
+  }
+  const after = run('git', ['rev-parse', 'HEAD'], { mutates: false });
+  const moved = before.stdout !== after.stdout;
+  if (moved || !existsSync(path.join(SO_ROOT, 'node_modules'))) {
+    const r = run('npm', ['ci']);
+    if (!r.ok) return { step: 'repo', status: 'failed', detail: r.detail };
+  }
+  return { step: 'repo', status: 'ok', detail: `${repoVersion()}${moved ? ' (updated)' : ' (already current)'}` };
+}
+
+function updateClaude({ run, log }, opts) {
+  if (!onPath('claude')) return { step: 'claude', status: 'skipped', detail: 'claude not on PATH' };
+  log('claude: refreshing marketplace and plugin');
+  for (const args of [['plugin', 'marketplace', 'update', MARKETPLACE], ['plugin', 'update', PLUGIN_ID]]) {
+    const r = run('claude', args);
+    if (!r.ok) return { step: 'claude', status: 'failed', detail: r.detail };
+  }
+  const list = run('claude', ['plugin', 'list', '--json'], { mutates: false });
+  if (!list.ok) return { step: 'claude', status: 'failed', detail: list.detail };
+  let entry;
+  try { entry = findClaudeEntry(JSON.parse(list.stdout)); } catch (e) {
+    return { step: 'claude', status: 'failed', detail: `plugin list --json unparseable: ${e.message}` };
+  }
+  if (!entry) return { step: 'claude', status: 'skipped', detail: `${PLUGIN_ID} not installed` };
+  if (!entry.installPath || !existsSync(entry.installPath)) {
+    return { step: 'claude', status: 'failed', detail: `installPath missing: ${entry.installPath}` };
+  }
+  const missing = missingRuntimeDeps(entry.installPath);
+  if (missing.length > 0) {
+    const refused = (entry.noteDetails ?? []).some((n) => n?.type === 'dependencies-refused');
+    log(`claude: ${missing.length} runtime deps missing${refused ? ' (harness refused the install)' : ''} — installing`);
+    const r = run('npm', ['ci', '--omit=dev'], { cwd: entry.installPath });
+    if (!r.ok) return { step: 'claude', status: 'failed', detail: r.detail };
+    const still = opts.dryRun ? [] : missingRuntimeDeps(entry.installPath);
+    if (still.length > 0) return { step: 'claude', status: 'failed', detail: `still missing after npm ci: ${still.join(', ')}` };
+  }
+  const want = repoVersion();
+  // The marketplace tracks GitHub main, so it can trail this clone until the
+  // release is pushed — report it, do not fail on it.
+  const lag = entry.version !== want ? `; clone is ${want} — marketplace not yet at it` : '';
+  return {
+    step: 'claude',
+    status: 'ok',
+    detail: `${entry.version}${missing.length ? `, installed ${missing.length} missing deps` : ''}${lag}`,
+  };
+}
+
+function updateCodex({ run, log }, opts) {
+  if (!onPath('codex')) return { step: 'codex', status: 'skipped', detail: 'codex not on PATH' };
+  const list = run('codex', ['plugin', 'list'], { mutates: false });
+  if (!list.ok) return { step: 'codex', status: 'failed', detail: list.detail };
+  if (!new RegExp(`^${PLUGIN_ID}\\s+installed`, 'm').test(list.stdout)) {
+    return { step: 'codex', status: 'skipped', detail: 'plugin not installed in Codex (install: node scripts/codex-install.mjs)' };
+  }
+  log('codex: re-running codex-install');
+  const r = run(process.execPath, [path.join(SO_ROOT, 'scripts', 'codex-install.mjs'), '--json']);
+  if (!r.ok) return { step: 'codex', status: 'failed', detail: r.detail };
+  if (opts.dryRun) return { step: 'codex', status: 'ok', detail: 'dry-run' };
+  try {
+    return { step: 'codex', status: 'ok', detail: JSON.parse(r.stdout).pluginVersion };
+  } catch {
+    return { step: 'codex', status: 'ok', detail: 'installed (version not reported)' };
+  }
+}
+
+function main(opts) {
+  const io = makeRunner(opts);
+  const results = [];
+  // Order matters: the Codex installer installs FROM this clone, so the clone
+  // must be current first. A failed repo step stops the chain for that reason.
+  results.push(updateRepo(io, opts));
+  if (results[0].status !== 'failed') {
+    results.push(updateClaude(io, opts));
+    results.push(updateCodex(io, opts));
+  }
+  const ok = results.every((r) => r.status !== 'failed');
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify({ ok, dryRun: opts.dryRun, results }, null, 2)}\n`);
+  } else {
+    io.log('');
+    for (const r of results) io.log(`  ${r.status.padEnd(7)} ${r.step.padEnd(7)} ${r.detail}`);
+    io.log(ok
+      ? '\nRestart Claude Code / Codex to load the new version. Old cache folders stay until then — delete them only after the restart.'
+      : '\nA step failed (a failed repo step skips the plugin steps). Fix it and re-run — every step is idempotent.');
+  }
+  return ok ? 0 : 2;
+}
+
+if (isMainModule(import.meta.url)) {
+  try {
+    const opts = parseArguments(process.argv.slice(2));
+    if (opts.help) process.stdout.write(HELP);
+    else process.exitCode = main(opts);
+  } catch (error) {
+    process.stderr.write(`ERROR: ${error.message}\n`);
+    process.exitCode = error.usage ? 1 : 2;
+  }
+}

package/scripts/site-numbers.mjs

@@ -91,6 +91,13 @@
  * silent skip — a generator that quietly stops filling a surface is the exact
  * failure this file exists to end.
  *
+ * ## The sitemap `<lastmod>` (`site/sitemap.xml`, #1484)
+ *
+ * `--write` changes what `/` and `/de` SHOW, so it also dates them in the
+ * sitemap: `lastmod` becomes max(lastmod, the page's own `counted-at` cell).
+ * `--check` reports a `lastmod` older than that cell as drift. Rule, mapping and
+ * reasons: `SITEMAP_PAGES`.
+ *
  * Exit codes (`.claude/rules/cli-design.md`):
  *   0 — no drift (--check) / files updated or already current (--write)
  *   1 — drift found (--check), or a contract violation in either mode
@@ -99,7 +106,7 @@
  */
 
 import { readFileSync, writeFileSync, readdirSync, existsSync, statSync } from 'node:fs';
-import { join, resolve, relative } from 'node:path';
+import { join, resolve, relative, sep } from 'node:path';
 import { execFileSync } from 'node:child_process';
 
 import { writeStdoutLineSync, writeJsonAtomicSync } from './lib/io.mjs';
@@ -963,6 +970,118 @@ export function syncCensusBlocks(siteDir, values, { write = false } = {}) {
   return CENSUS_BLOCK_FILES.map((file) => syncCensusBlock(siteDir, values, { write, file }));
 }
 
+// ---------------------------------------------------------------------------
+// The sitemap <lastmod> in site/sitemap.xml (#1484)
+// ---------------------------------------------------------------------------
+
+/** The sitemap, relative to the SITE directory. */
+export const SITEMAP_FILE = 'sitemap.xml';
+
+/**
+ * Every page ↔ sitemap `<loc>`, explicitly.
+ *
+ * Why the sitemap is this generator's business: `--write` changes what `/` and
+ * `/de` show (version card, number cards, "Counted on … at commit …"), and the
+ * release that ran it left their `lastmod` behind. Measured 2026-10-01: `/`
+ * claimed 2026-09-08 while its content was counted 2026-09-22.
+ *
+ * The rule takes no second clock. A page's `counted-at` cell is the date this
+ * script last changed that page — `rewrite()` stamps every cell in one pass —
+ * so `lastmod` becomes max(lastmod, that cell), and never moves backwards. A
+ * page without a `counted-at` cell (the guide and the legal pages, whose only
+ * cell is the header version) is never dated: a version bump in a page header
+ * is not a content change.
+ *
+ * Unknown either way is an ERROR, never a skip (the `METRIC_IDS` rule): a
+ * sitemap `<loc>` missing here would never be dated, and a page carrying cells
+ * that is missing here would drift unseen.
+ */
+export const SITEMAP_PAGES = Object.freeze([
+  { page: 'index.html', loc: 'https://session-orchestrator.com/' },
+  { page: 'de/index.html', loc: 'https://session-orchestrator.com/de' },
+  { page: 'guide/index.html', loc: 'https://session-orchestrator.com/guide' },
+  { page: 'impressum/index.html', loc: 'https://session-orchestrator.com/impressum' },
+  { page: 'datenschutz/index.html', loc: 'https://session-orchestrator.com/datenschutz' },
+]);
+
+const URL_BLOCK_RE = /<url>([\s\S]*?)<\/url>/g;
+const ISO_DAY_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+/**
+ * Judge (and optionally rewrite) the `<lastmod>` of every sitemap entry. Only the
+ * date text of an entry that moves is rewritten; the rest of the file is handed
+ * back byte-for-byte.
+ *
+ * @param {string} siteDir
+ * @param {Array<{page:string, metrics:string[], countedAt:string|null}>} pages
+ *   every HTML file under `siteDir` carrying metric cells: its site-relative path
+ *   (`/`-separated), its metric ids, and its `counted-at` cell as it stands AFTER
+ *   this run (`null` when it has none)
+ * @param {{write?: boolean}} [opts]
+ * @returns {{present:boolean, file:string, errors?:string[],
+ *            drift?:Array<{loc:string, line:number, actual:string, expected:string}>,
+ *            written?:boolean}}
+ */
+export function syncSitemapLastmod(siteDir, pages, { write = false } = {}) {
+  const abs = join(siteDir, SITEMAP_FILE);
+  // Absent file: like the census blocks, not this generator's to create.
+  if (!existsSync(abs) || !statSync(abs).isFile()) return { present: false, file: abs };
+
+  const errors = [];
+  const dated = new Map(); // loc → the counting date its page carries
+  for (const p of pages) {
+    const entry = SITEMAP_PAGES.find((e) => e.page === p.page);
+    if (!entry) {
+      errors.push(
+        `${p.page} carries metric cells but has no sitemap mapping — known pages: ` +
+          SITEMAP_PAGES.map((e) => e.page).join(', '),
+      );
+    } else if (p.countedAt !== null) {
+      if (ISO_DAY_RE.test(p.countedAt)) dated.set(entry.loc, p.countedAt);
+      else errors.push(`${p.page}: counted-at cell "${p.countedAt}" is not a YYYY-MM-DD date`);
+    } else if (p.metrics.some((m) => m !== 'version')) {
+      // Counted cells with no stamp to date them by: their changes would never
+      // reach the sitemap.
+      errors.push(`${p.page} carries counted cells but no counted-at cell — its lastmod cannot be dated`);
+    }
+  }
+
+  const text = readFileSync(abs, 'utf8');
+  const drift = [];
+  const seen = new Set();
+  const next = text.replace(URL_BLOCK_RE, (block, inner, offset) => {
+    const loc = /<loc>([^<]*)<\/loc>/.exec(inner)?.[1].trim();
+    if (loc === undefined || !SITEMAP_PAGES.some((e) => e.loc === loc)) {
+      errors.push(
+        `unknown sitemap <loc> "${loc ?? '(none)'}" — known: ${SITEMAP_PAGES.map((e) => e.loc).join(', ')}`,
+      );
+      return block;
+    }
+    seen.add(loc);
+    const lm = /<lastmod>([^<]*)<\/lastmod>/.exec(block);
+    if (!lm || !ISO_DAY_RE.test(lm[1])) {
+      errors.push(`<lastmod> of ${loc} is missing or not a YYYY-MM-DD date`);
+      return block;
+    }
+    const date = dated.get(loc);
+    // ISO days compare as strings. Never backwards: a lastmod a hand edit dated
+    // after the count stays.
+    if (date === undefined || date <= lm[1]) return block;
+    drift.push({ loc, line: lineOf(text, offset + lm.index), actual: lm[1], expected: date });
+    return `${block.slice(0, lm.index)}<lastmod>${date}</lastmod>${block.slice(lm.index + lm[0].length)}`;
+  });
+  for (const loc of dated.keys()) {
+    if (!seen.has(loc)) errors.push(`${loc} carries a counted-at cell but has no sitemap <url> entry`);
+  }
+
+  const out = { present: true, file: abs, errors, drift, written: false };
+  if (write && errors.length === 0 && next !== text) {
+    writeFileSync(abs, next, 'utf8');
+    out.written = true;
+  }
+  return out;
+}
+
 // ---------------------------------------------------------------------------
 // Markup
 // ---------------------------------------------------------------------------
@@ -1134,6 +1253,7 @@ function printHelp() {
   writeStdoutLineSync('  --check        (default) report drift, change nothing; exit 1 on drift');
   writeStdoutLineSync(`  --write        rewrite the cells in place; also refreshes ${CENSUS_FILE.join('/')}`);
   writeStdoutLineSync('                 (skipped when --site points outside the repo\'s own site/)');
+  writeStdoutLineSync(`                 and dates each counted page's <lastmod> in <site>/${SITEMAP_FILE}`);
   writeStdoutLineSync('  --json         machine-readable envelope on stdout');
   writeStdoutLineSync('  --site <dir>   site directory (default <repo-root>/site)');
   writeStdoutLineSync('  --version      print the package version');
@@ -1208,12 +1328,18 @@ export function main(argv = process.argv.slice(2), env = {}) {
   // the source producing it is corrupt, and writing the rest would be a
   // partial write reported as success.
   let rejectedTotal = 0;
+  // Every page carrying cells, for the sitemap's <lastmod> (syncSitemapLastmod).
+  const pages = [];
 
-  for (const abs of files) {
-    // Repo-relative when the file is inside the repo; absolute otherwise (a
-    // `--site` fixture in $TMPDIR would otherwise render as ../../../../var/...).
+  // Repo-relative when the file is inside the repo; absolute otherwise (a
+  // `--site` fixture in $TMPDIR would otherwise render as ../../../../var/...).
+  const display = (abs) => {
     const r = relative(root, abs);
-    const rel = r && !r.startsWith('..') ? r : abs;
+    return r && !r.startsWith('..') ? r : abs;
+  };
+
+  for (const abs of files) {
+    const rel = display(abs);
     const html = readFileSync(abs, 'utf8');
     const spans = inspectHtml(html, values);
     spanTotal += spans.length;
@@ -1250,6 +1376,16 @@ export function main(argv = process.argv.slice(2), env = {}) {
       }
     }
 
+    if (spans.length > 0) {
+      const stamp = spans.find((s) => s.metric === 'counted-at');
+      pages.push({
+        page: relative(siteDir, abs).split(sep).join('/'),
+        metrics: spans.map((s) => s.metric),
+        // As the page stands AFTER this run: a written file carries every value.
+        countedAt: stamp ? (written > 0 ? values['counted-at'] : stamp.actual.trim()) : null,
+      });
+    }
+
     report.push({
       file: rel,
       spans: spans.length,
@@ -1294,6 +1430,17 @@ export function main(argv = process.argv.slice(2), env = {}) {
   // read `llmsFull`; `censusBlocks` below carries all of them.
   const llms = censusBlocks[CENSUS_BLOCK_FILES.indexOf(LLMS_FULL_FILE)];
 
+  // The sitemap <lastmod>: a date older than the counting stamp on its page is
+  // drift, like a stale number. Written from the pages as they stand after the
+  // loop above, so page and sitemap come from the same run.
+  const sitemap = syncSitemapLastmod(siteDir, pages, { write: args.write });
+  const sitemapRel = display(sitemap.file);
+  for (const e of sitemap.errors ?? []) {
+    stderr(`Error: ${sitemapRel}: ${e}`);
+    contractTotal += 1;
+  }
+  driftTotal += sitemap.drift?.length ?? 0;
+
   // The named silent-failure class: a generator that matches nothing, changes
   // nothing, and reports success. Zero spans means the markup contract is not in
   // the page — that is a defect, in BOTH modes, never a no-op.
@@ -1390,6 +1537,13 @@ export function main(argv = process.argv.slice(2), env = {}) {
             stale: b.stale === true,
             written: b.written === true,
           })),
+          sitemap: {
+            file: sitemap.present ? sitemapRel : null,
+            present: sitemap.present,
+            errors: sitemap.errors ?? [],
+            drift: sitemap.drift ?? [],
+            written: sitemap.written === true,
+          },
           censusWritten,
           ok,
         },
@@ -1404,6 +1558,7 @@ export function main(argv = process.argv.slice(2), env = {}) {
         censusBlocks
           .map((b, i) => (b.written ? ` + ${CENSUS_BLOCK_FILES[i]}` : ''))
           .join('') +
+        (sitemap.written ? ` + ${SITEMAP_FILE}` : '') +
         (censusWritten ? ` + ${CENSUS_FILE.join('/')}` : ''),
     );
   } else {
@@ -1416,6 +1571,9 @@ export function main(argv = process.argv.slice(2), env = {}) {
       }
     }
     for (const l of censusDriftLines) stdout(l);
+    for (const d of sitemap.drift ?? []) {
+      stdout(`DRIFT ${sitemapRel}:${d.line} lastmod ${d.loc}: sitemap says "${d.actual}", page counted "${d.expected}"`);
+    }
     stdout(
       driftTotal === 0 && !noSpans && contractTotal === 0
         ? `site-numbers: ${spanTotal} metric cell(s) current across ${files.length} file(s)`