@sabaiway/agent-workflow-kit 1.17.0 → 1.18.0

package/tools/set-recipe.mjs

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+// set-recipe.mjs — the WRITER for docs/ai/orchestration.json. The division of labor (AD-025): the AGENT
+// turns plain language into explicit `--set <activity>.<slot>=<recipe>` / `--unset <activity>.<slot>`
+// ops; the KIT does the deterministic validate → merge → preview → write. The kit ships NO NL parser
+// (stays dependency-free + deterministic) and performs no `all`-magic — the agent expands "both review"
+// into explicit per-activity ops (asking if scope is unclear).
+//
+// Posture: PREVIEW BY DEFAULT (dry-run); `--write` applies. It NEVER commits and NEVER runs a backend.
+// It previews current→proposed for the CHANGED slots only, resolves the effective recipe vs LIVE backend
+// readiness (degradation honesty on BOTH the preview and the --write path), and writes only via the
+// hardened writeConfig (deployment gate; exclusive-create tmp+rename; symlink/TOCTOU-safe; last-writer-
+// wins). A no-op set never writes and never spuriously seeds the _README. `--unset` returns a slot to its
+// computed default, so reverting needs no hand-edit either. Hand-edit stays first-class — this is an
+// OFFERED convenience, never a lock.
+//
+// Output is ENGLISH/structured (repo-artifact Hard Constraint); the agent localizes to the user's
+// language when narrating. Exit codes: 0 success (an explicit recipe that gracefully degrades is still
+// 0); 2 usage (bad/duplicate op, --write with zero ops); 1 config error (malformed/unreadable config)
+// or a write STOP (no deployment / symlinked leaf). main(argv, ctx) → { code, stdout, stderr }; cwd /
+// env / home / detect / fs are injectable for host-independent tests.
+//
+// Dependency-free, Node >= 18. No side effects on import (the isDirectRun idiom).
+
+import { readFileSync, lstatSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { pathToFileURL } from 'node:url';
+import { detectBackends } from './detect-backends.mjs';
+import { resolveActivityRecipe } from './recipes.mjs';
+import {
+  CONFIG_REL,
+  fail,
+  loadConfig,
+  validateConfig,
+  parseOp,
+  applySetOps,
+  serializeConfig,
+  CANON_README,
+} from './orchestration-config.mjs';
+import { writeConfig as writeConfigFs } from './orchestration-write.mjs';
+
+// ── argument parsing (usage errors → exit 2) ────────────────────────────────────────
+
+// Parse argv → { ops, write, json }. `--set`/`--unset` take a fully-qualified token (parseOp validates
+// it). A duplicate op for the same activity.slot, a `--write` with zero ops, an unknown flag, or a bad
+// token → exit 2. `--set=<tok>` / `--unset=<tok>` inline forms are accepted too.
+const parseArgs = (argv) => {
+  const ops = [];
+  const seen = new Set();
+  let write = false;
+  let json = false;
+  const takeOp = (kind, tok) => {
+    if (tok === undefined || tok.startsWith('--')) throw fail(2, `--${kind} requires <activity>.<slot>${kind === 'set' ? '=<recipe>' : ''}`);
+    const op = parseOp(kind, tok);
+    const key = `${op.activity}.${op.slot}`;
+    if (seen.has(key)) throw fail(2, `duplicate op for "${key}" — name each activity.slot at most once`);
+    seen.add(key);
+    ops.push(op);
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--json') json = true;
+    else if (a === '--write') write = true;
+    else if (a === '--set') { takeOp('set', argv[i + 1]); i += 1; }
+    else if (a === '--unset') { takeOp('unset', argv[i + 1]); i += 1; }
+    else if (a.startsWith('--set=')) takeOp('set', a.slice('--set='.length));
+    else if (a.startsWith('--unset=')) takeOp('unset', a.slice('--unset='.length));
+    else if (a.startsWith('-')) throw fail(2, `unknown flag: ${a}`);
+    else throw fail(2, `unexpected argument: ${a}`);
+  }
+  if (write && ops.length === 0) throw fail(2, 'nothing to write — pass at least one --set/--unset (a bare --write is a no-op)');
+  return { ops, write, json };
+};
+
+// ── effective-recipe resolution per op (degradation honesty) ────────────────────────
+
+// A single op's before/after value + the effective recipe it resolves to here (vs live readiness).
+// `to` is null for an unset (falls to the computed default). degradedFrom/reason carry the honesty.
+const resolveOp = (op, current, after, detection) => {
+  const from = current?.[op.activity]?.[op.slot] ?? null;
+  const to = after?.[op.activity]?.[op.slot] ?? null;
+  const r = resolveActivityRecipe({ config: after ?? {}, readiness: detection, activity: op.activity, slot: op.slot });
+  return { activity: op.activity, slot: op.slot, from, to, effective: r.recipe, degradedFrom: r.degradedFrom, reason: r.reason };
+};
+
+// ── rendering (ENGLISH; the agent localizes) ────────────────────────────────────────
+
+const valueLabel = (v) => (v == null ? '(computed default)' : v);
+
+const effectiveLine = (e) =>
+  e.degradedFrom
+    ? `effective here: ${e.effective} (requested ${e.degradedFrom} → degraded: ${e.reason})`
+    : `effective here: ${e.effective}`;
+
+const formatHuman = ({ changed, unchanged, warnings, willWrite, wrote, fileBody }) => {
+  const lines = [];
+  if (wrote) lines.push(`wrote ${CONFIG_REL}`);
+  else if (changed.length) lines.push(`set-recipe — preview (nothing written; re-run with --write to apply)`);
+  for (const e of changed) {
+    lines.push(`  ${e.activity}.${e.slot}: ${valueLabel(e.from)} → ${valueLabel(e.to)}`);
+    lines.push(`      ↳ ${effectiveLine(e)}`);
+  }
+  for (const e of unchanged) lines.push(`  ${e.activity}.${e.slot}: already ${valueLabel(e.from)} (no change)`);
+  for (const w of warnings) lines.push(`  ⚠ ${w}`);
+  if (wrote && fileBody) lines.push('', `${CONFIG_REL} now reads:`, fileBody.replace(/\n$/, ''));
+  if (!wrote) {
+    if (!changed.length) lines.push('  no changes — nothing to write.');
+    else if (willWrite) lines.push('', `would write ${CONFIG_REL} — re-run with --write to apply.`);
+  }
+  return lines.join('\n');
+};
+
+const buildJson = ({ changed, unchanged, warnings, writtenPath, noop }) => ({
+  changed: changed.map((e) => ({ activity: e.activity, slot: e.slot, from: e.from, to: e.to, effective: e.effective, degradedFrom: e.degradedFrom ?? null, reason: e.reason ?? null })),
+  unchanged: unchanged.map((e) => ({ activity: e.activity, slot: e.slot, recipe: e.from })),
+  writtenPath: writtenPath ?? null,
+  noop,
+  warnings,
+});
+
+const HELP = `set-recipe — write the per-project orchestration config (docs/ai/orchestration.json).
+
+Usage:
+  node set-recipe.mjs [--set <activity>.<slot>=<recipe>]... [--unset <activity>.<slot>]... [--write] [--json]
+
+  --set    <activity>.<slot>=<recipe>   pin a recipe (fully-qualified; e.g. plan-authoring.review=council)
+  --unset  <activity>.<slot>            return a slot to its computed default
+  --write                               apply the change (default: preview only — writes nothing)
+  --json                                machine-readable output
+  --help, -h                            this help
+
+Activities/slots: plan-authoring → review;  plan-execution → execute, review
+Recipes:          review accepts solo|reviewed|council;  execute accepts solo|delegated
+
+Previews by default; --write applies via an atomic, symlink/TOCTOU-safe write behind a deployment gate.
+Config writer only: it NEVER runs a backend and NEVER commits. Hand-editing the file stays fully supported.
+
+Exit codes: 0 success (an explicit recipe that gracefully degrades is still 0);
+            2 usage (bad/duplicate op, or --write with no ops);
+            1 config error (malformed/unreadable config) or a write STOP (no deployment / symlinked leaf).`;
+
+// ── main ────────────────────────────────────────────────────────────────────────────
+
+export const main = (argv, ctx = {}) => {
+  const cwd = ctx.cwd ?? process.cwd();
+  const detect = ctx.detect ?? detectBackends;
+  const readFile = ctx.readFileSync ?? readFileSync;
+  const lstat = ctx.lstatSync ?? lstatSync;
+  const writeConfig = ctx.writeConfig ?? writeConfigFs;
+  try {
+    if (argv.includes('--help') || argv.includes('-h')) return { code: 0, stdout: HELP, stderr: '' };
+    const { ops, write, json } = parseArgs(argv);
+
+    // Load the current config first (loadConfig throws fail(1) loud on malformed/unreadable — a write
+    // never clobbers an unparseable file; the message points the agent at the parse error to help fix it).
+    const { config: current, source } = loadConfig(cwd, readFile, lstat);
+
+    // No ops + no --write → show the current config + a hint (read-only; nothing changes).
+    if (ops.length === 0) {
+      if (json) {
+        return { code: 0, stdout: JSON.stringify(buildJson({ changed: [], unchanged: [], warnings: [], writtenPath: null, noop: true }), null, 2), stderr: '' };
+      }
+      const shown = current == null ? `(no ${CONFIG_REL} yet — computed defaults apply)` : serializeConfig(current).replace(/\n$/, '');
+      const hint = `\nPass --set <activity>.<slot>=<recipe> (preview) then --write to apply. Activities/slots: plan-authoring.review, plan-execution.execute, plan-execution.review.`;
+      return { code: 0, stdout: `${source === 'none' ? '' : `${CONFIG_REL}:\n`}${shown}${hint}`, stderr: '' };
+    }
+
+    const after = applySetOps(current, ops, { seedReadme: CANON_README });
+
+    // Detection is a SECONDARY input — it only refines the EFFECTIVE recipe note. A throw must NOT block
+    // the write (the config write is readiness-independent): treat all backends as not-ready, warn, exit 0.
+    const warnings = [];
+    let detection = [];
+    try {
+      detection = detect();
+    } catch (err) {
+      warnings.push(`backend detection failed (${(err && err.message) || err}) — treating all backends as not ready; recipes needing a backend degrade to solo.`);
+    }
+
+    const resolved = ops.map((op) => resolveOp(op, current, after, detection));
+    const changed = resolved.filter((e) => e.from !== e.to);
+    const unchanged = resolved.filter((e) => e.from === e.to);
+    const noop = changed.length === 0;
+
+    if (!write) {
+      const stdout = json
+        ? JSON.stringify(buildJson({ changed, unchanged, warnings, writtenPath: null, noop }), null, 2)
+        : formatHuman({ changed, unchanged, warnings, willWrite: !noop, wrote: false });
+      return { code: 0, stdout, stderr: '' };
+    }
+
+    // --write. A no-op never writes (idempotent; never re-seeds the _README).
+    if (noop) {
+      const stdout = json
+        ? JSON.stringify(buildJson({ changed, unchanged, warnings, writtenPath: null, noop: true }), null, 2)
+        : formatHuman({ changed, unchanged, warnings, willWrite: false, wrote: false });
+      return { code: 0, stdout, stderr: '' };
+    }
+
+    validateConfig(after); // defensive re-validate immediately before the write
+    const { writtenPath } = writeConfig(cwd, after, ctx);
+    const fileBody = serializeConfig(after);
+    const stdout = json
+      ? JSON.stringify(buildJson({ changed, unchanged, warnings, writtenPath, noop: false }), null, 2)
+      : formatHuman({ changed, unchanged, warnings, wrote: true, fileBody });
+    return { code: 0, stdout, stderr: '' };
+  } catch (err) {
+    return { code: err.exitCode ?? 1, stdout: '', stderr: `set-recipe: ${err.message}` };
+  }
+};
+
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) {
+  const r = main(process.argv.slice(2));
+  if (r.stdout) console.log(r.stdout);
+  if (r.stderr) console.error(r.stderr);
+  process.exit(r.code);
+}

package/tools/setup-backends.mjs

@@ -24,9 +24,9 @@ import {
 import { join, resolve, relative, dirname, isAbsolute } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import os from 'node:os';
-import { KNOWN_BACKENDS, detectBackend, resolveDir, guideFor } from './detect-backends.mjs';
+import { KNOWN_BACKENDS, detectBackend, detectBackends, resolveDir, guideFor, READY } from './detect-backends.mjs';
 import { copyTreeRefresh, linkManaged } from './fs-safe.mjs';
-import { validateManifest, UNSUPPORTED, INVALID } from './manifest/validate.mjs';
+import { validateManifest, readAuthoritativeVersion, UNSUPPORTED, INVALID } from './manifest/validate.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 // bridges/ ships beside tools/ in both the repo and the installed kit, so this resolves in both.
@@ -315,9 +315,18 @@ export const planFor = (backend, deps = {}) => {
   }
 
   let links;
+  let version = null;
+  let priorVersion = null;
   try {
     const fs = fsDeps(deps);
-    const derived = deriveLinks(readBundledManifest(place.bundleDir, deps), skillDir);
+    const readVersion = deps.readVersion ?? readAuthoritativeVersion;
+    const bundledManifest = readBundledManifest(place.bundleDir, deps);
+    // The bundled bridge version (what setup will place/refresh) + the prior installed version (only on
+    // a refresh — a place has no prior). readAuthoritativeVersion is the SAME source `status` reads, so
+    // setup never invents a second version reader. A place / absent-prior shows no arrow (never "vnull").
+    version = typeof bundledManifest.version === 'string' ? bundledManifest.version : null;
+    priorVersion = place.action === 'refresh' ? readVersion(skillDir).version ?? null : null;
+    const derived = deriveLinks(bundledManifest, skillDir);
     // Preflight the BUNDLE sources (what we will copy → link). After place, the skill source IS the
     // bundle source, so checking it here makes a dry-run faithfully predict linkWrappers instead of
     // reporting "ok" and then throwing at apply time.
@@ -347,7 +356,7 @@ export const planFor = (backend, deps = {}) => {
   const onPath = bindirOnPath(bindir, deps.getenv ?? process.env, platform);
   const bindirHint = onPath ? null : `add ${bindir} to PATH to use the wrappers: export PATH="${bindir}:$PATH"  (persist in ~/.bashrc / ~/.zshrc)`;
 
-  return { name: entry.name, skillDir, bindir, platform, place, links, guides, bindirHint, outcome: 'ok' };
+  return { name: entry.name, skillDir, bindir, platform, place, links, guides, bindirHint, outcome: 'ok', version, priorVersion };
 };
 
 // Perform an `ok` plan's deterministic steps. Re-derives + re-checks inside the primitives (no trust
@@ -361,6 +370,16 @@ const applyBackend = (plan, deps) => {
 
 // ── formatting ─────────────────────────────────────────────────────────────────
 
+// The bridge version label for the skill line: place / absent-prior → "(vX)" (no arrow, never
+// "vnull → vX"); refresh with a DIFFERENT prior → "(vOld → vNew)"; refresh equal / null prior → "(vX)".
+const versionLabel = (plan) => {
+  if (!plan.version) return '';
+  if (plan.place?.action === 'refresh' && plan.priorVersion && plan.priorVersion !== plan.version) {
+    return ` (v${plan.priorVersion} → v${plan.version})`;
+  }
+  return ` (v${plan.version})`;
+};
+
 const formatBackend = (plan, applied) => {
   const lines = [`  ${plan.name} → ${plan.outcome}`];
   if (plan.outcome === 'unsupported') {
@@ -372,7 +391,7 @@ const formatBackend = (plan, applied) => {
     return lines.join('\n');
   }
   const placeVerb = applied ? { place: 'placed', refresh: 'refreshed' } : { place: 'will place', refresh: 'will refresh' };
-  lines.push(`      • skill: ${placeVerb[plan.place.action]} → ${plan.skillDir}`);
+  lines.push(`      • skill: ${placeVerb[plan.place.action]}${versionLabel(plan)} → ${plan.skillDir}`);
   for (const l of plan.links) {
     const verb = l.dstState === 'ours' ? 'already linked' : applied ? 'linked' : 'will link';
     lines.push(`      • wrapper ${l.cmd}: ${verb} → ${l.dst}`);
@@ -382,6 +401,41 @@ const formatBackend = (plan, applied) => {
   return lines.join('\n');
 };
 
+// ── close-the-loop: surface versions + a proactive recipe offer ───────────────────
+
+// The closing pointer: setup surfaces only the bridge it touched; the full family + deployment version
+// view lives in the read-only status mode.
+const STATUS_POINTER = 'Full family + deployment versions: /agent-workflow-kit status';
+
+// Count the review-capable backends that are READY right now (both bridges provide review, so a READY
+// count ≥1 unlocks Reviewed, ≥2 unlocks Council). Uses the MULTI-backend detector. A detection failure
+// → null: we can't tell, so we make NO offer (never a false one). Read-only.
+const reviewReadyCount = (deps) => {
+  const detectAll = deps.detectAll ?? detectBackends;
+  try {
+    return detectAll(deps).filter((d) => d.readiness === READY).length;
+  } catch {
+    return null;
+  }
+};
+
+// After a successful setup, if a review backend NEWLY became ready (the pre-apply readiness in planFor
+// is stale — re-detect AFTER apply), offer to set the review recipe — for BOTH planning AND execution
+// review (planning review is a core goal; never offer only plan-execution). Council when ≥2 are ready,
+// else Reviewed (with a one-reviewer alternative noted). English; the agent localizes when it narrates.
+export const proactiveReviewOffer = (before, after) => {
+  if (before == null || after == null || after <= before) return null;
+  const depth = after >= 2 ? 'council' : 'reviewed';
+  const lines = [
+    '',
+    `A review backend is now ready (${after} ready). To have your plans reviewed, set the review recipe (preview first; I'll write it for you — or edit docs/ai/orchestration.json yourself):`,
+    `  /agent-workflow-kit set-recipe --set plan-authoring.review=${depth}`,
+    `  /agent-workflow-kit set-recipe --set plan-execution.review=${depth}`,
+  ];
+  if (depth === 'council') lines.push('  (or =reviewed for a single reviewer)');
+  return lines.join('\n');
+};
+
 // ── CLI ─────────────────────────────────────────────────────────────────────────
 
 const USAGE = `usage: setup-backends [<backend>] [--bindir <path>] [--dry-run] [--help]
@@ -448,12 +502,16 @@ export const main = (argv = process.argv.slice(2), deps = {}) => {
 
   const runDeps = { ...deps, bindir: args.bindir ?? deps.bindir };
   log(args.dryRun ? 'agent-workflow backend setup — DRY RUN (no changes)' : 'agent-workflow backend setup (link-only)');
+  // Snapshot review readiness BEFORE applying, so we can offer the recipe only on a true readiness flip.
+  const reviewBefore = args.dryRun ? null : reviewReadyCount(runDeps);
   let worst = 0;
+  let appliedOk = false;
   for (const name of targets) {
     let plan = planFor(name, runDeps);
     if (!args.dryRun && plan.outcome === 'ok') {
       try {
         applyBackend(plan, runDeps);
+        appliedOk = true;
       } catch (err) {
         plan = { ...plan, outcome: err.code === SETUP_STOP ? 'stop' : 'error', reason: err.message };
       }
@@ -461,6 +519,14 @@ export const main = (argv = process.argv.slice(2), deps = {}) => {
     log(formatBackend(plan, !args.dryRun));
     if (plan.outcome === 'stop' || plan.outcome === 'error') worst = 1;
   }
+  log('');
+  log(STATUS_POINTER);
+  // Re-detect AFTER apply (pre-apply readiness is stale): a review backend that just became ready earns
+  // a proactive set-recipe offer. Only after a real apply (never on a dry-run or a no-op run).
+  if (!args.dryRun && appliedOk) {
+    const offer = proactiveReviewOffer(reviewBefore, reviewReadyCount(runDeps));
+    if (offer) log(offer);
+  }
   return worst;
 };