@0xgeorgemathew/zcode 0.4.4 → 0.5.1

package/lib/commands/exec.js

@@ -6,7 +6,9 @@
 //
 // Output contract:
 //   --json   stdout = NDJSON events + exactly one final {"type":"result"}
-//            line (--quiet: only that line). stderr = diagnostics only.
+//            line (--quiet: only that line): the compact brief
+//            (zcode.brief/1, lib/brief.js), or the full record with --full.
+//            stderr = diagnostics only.
 //   plain    stdout = the answer (run/agent) or the handback summary (task);
 //            stderr = the live feed (header, phases, tools, checks).
 const fs = require('node:fs');
@@ -15,17 +17,22 @@ const { spawn } = require('node:child_process');
 const store = require('../store.js');
 const { execute, prepareSession, exitCodeFor, ExecError, readSettings } = require('../executor.js');
 const { ConfigError } = require('../bootstrap.js');
-const { normalizeContract, ContractError } = require('../contract.js');
+const { ContractError } = require('../contract.js');
+const { buildContract } = require('../taskspec.js');
 const { workspaceRoot, normalizeOwns, OwnershipError } = require('../workspace.js');
+const { buildBrief } = require('../brief.js');
 const { makeReporter, formatResult, useColor } = require('../ui.js');
-const { normalizeModel, normalizeEffort } = require('../models.js');
+const { normalizeModel, normalizeEffort, effortProblem } = require('../models.js');
 
 const BIN = path.join(__dirname, '..', '..', 'bin', 'zcode.js');
 const DEFAULT_TIMEOUT = { run: 600000, agent: 600000, task: 1800000 };
 
+// Thrown (not exited) so builders can be reused by the plan supervisor; the
+// command entry points below turn it into the one-line exit 2.
+class UsageError extends Error {}
+
 function usage(message) {
-  process.stderr.write(`zcode: ${message}\n`);
-  process.exit(2);
+  throw new UsageError(message);
 }
 
 function readStdin() {
@@ -39,7 +46,7 @@ function readStdin() {
 // --task <file|->: .json (or text starting with "{") is a contract object,
 // anything else is a markdown brief that becomes the objective.
 function loadTaskBase(spec) {
-  if (spec === undefined) return {};
+  if (spec === undefined) return { base: {}, dir: null };
   const text = spec === '-' ? readStdin() : (() => {
     try {
       return fs.readFileSync(spec, 'utf8');
@@ -48,19 +55,24 @@ function loadTaskBase(spec) {
     }
   })();
   const trimmed = text.trim();
+  // "@file" entries inside a contract resolve next to the contract file.
+  const dir = spec === '-' ? null : path.dirname(path.resolve(spec));
   if (spec.endsWith('.json') || trimmed.startsWith('{')) {
     try {
-      return JSON.parse(trimmed);
+      return { base: JSON.parse(trimmed), dir };
     } catch (err) {
       return usage(`--task JSON is invalid: ${err.message}`);
     }
   }
-  return { objective: trimmed };
+  return { base: { objective: trimmed }, dir };
 }
 
-function buildInvocation(parsed) {
+// `spec` ({base, dir}) replaces --task: the plan supervisor hands over an
+// assembled contract instead of a file.
+function buildInvocation(parsed, spec) {
   const { command, flags, prompts } = parsed;
   const kind = command;
+  let effortSource = '--effort';
   const inv = {
     kind,
     id: flags.id || store.newId(),
@@ -88,19 +100,30 @@ function buildInvocation(parsed) {
 
   if (kind === 'task') {
     const objective = prompts.join(' ');
-    let base = loadTaskBase(flags.task);
-    if (!objective.trim() && flags.task === undefined && !process.stdin.isTTY) {
+    let { base, dir } = spec || loadTaskBase(flags.task);
+    if (!spec && !objective.trim() && flags.task === undefined && !process.stdin.isTTY) {
       base = { objective: readStdin().trim() };
     }
     let contract;
     try {
-      contract = normalizeContract(base, {
+      contract = buildContract({
+        base,
+        baseDir: dir || process.cwd(),
+        cwd: inv.cwd,
         objective,
-        acceptance: flags.accept,
-        checks: flags.check,
-        files: flags.file,
-        context: flags.context,
-        owns: flags.owns,
+        additions: {
+          acceptance: flags.accept,
+          checks: flags.check,
+          files: flags.file,
+          context: flags.context,
+          decisions: flags.decisions,
+          units: flags.units,
+          visual: flags.visual,
+          viewports: flags.viewports,
+          serve: flags.serve,
+          owns: flags.owns,
+          touch: flags.touch,
+        },
       });
     } catch (err) {
       if (err instanceof ContractError) usage(err.message);
@@ -111,6 +134,7 @@ function buildInvocation(parsed) {
       inv.model = normalizeModel(contract.model) || usage(`contract model "${contract.model}" is not supported.`);
     }
     if (contract.effort && !parsed.given.has('effort')) {
+      effortSource = 'contract effort';
       inv.effort = normalizeEffort(contract.effort) || usage(`contract effort "${contract.effort}" is not valid.`);
     }
     const lim = contract.limits;
@@ -120,7 +144,9 @@ function buildInvocation(parsed) {
     inv.contract = contract;
     inv.checks = contract.checks;
     inv.ownsDisplay = contract.owns;
+    inv.touchDisplay = contract.touch;
     inv.acceptanceDeclared = contract.acceptance.length > 0;
+    inv.preflight = Boolean(flags.preflight);
   } else {
     let prompt = prompts.join(' ');
     if (!prompt && kind === 'run' && !process.stdin.isTTY) prompt = readStdin();
@@ -128,8 +154,14 @@ function buildInvocation(parsed) {
     inv.prompt = prompt;
   }
 
+  // The model/effort pair that will actually run, refused before any spawn.
+  const problem = effortProblem(inv.model, inv.effort, { source: effortSource });
+  if (problem) usage(problem);
+
   try {
-    inv.owns = normalizeOwns(inv.ownsDisplay, inv.cwd, workspaceRoot(inv.cwd));
+    const root = workspaceRoot(inv.cwd);
+    inv.owns = normalizeOwns(inv.ownsDisplay, inv.cwd, root);
+    inv.touch = normalizeOwns(inv.touchDisplay || [], inv.cwd, root, '--touch');
   } catch (err) {
     if (err instanceof OwnershipError) usage(err.message);
     throw err;
@@ -145,6 +177,10 @@ function buildResume(parsed, ref, message) {
   if (!settings) usage(`session "${id}" has no stored settings; it cannot be resumed.`);
   const { flags, given } = parsed;
   if (settings.kind !== 'task' && !message.trim()) usage(`resume of a ${settings.kind} session needs a message.`);
+  const model = given.has('model') ? flags.model : settings.model;
+  const effort = given.has('effort') ? flags.effort : settings.effort;
+  const problem = effortProblem(model, effort);
+  if (problem) usage(problem);
   return {
     ...settings,
     id,
@@ -168,23 +204,19 @@ function readTask(id) {
   }
 }
 
-// --detach: claim the id, hand the invocation to a detached worker
-// (`zcode __exec <id>`), print the handle, exit 0. The worker writes its
-// NDJSON to <session>/stdout.ndjson and diagnostics to stderr.log.
-function detach(inv, flags) {
+// Claims the id, hands the invocation to a detached worker
+// (`zcode __exec <id>`) and returns its handle. The worker writes its NDJSON
+// to <session>/stdout.ndjson and diagnostics to stderr.log. Throws
+// store.SessionExistsError for a taken id, ExecError (exit 7) when a resumed
+// session is still running.
+function startDetached(inv) {
   if (inv.resume) {
     const view = store.viewSession(store.readSession(inv.id));
     if (view && view.live) {
-      process.stderr.write(`zcode: session "${inv.id}" is still running (pid ${view.pid}).\n`);
-      process.exit(7);
+      throw new ExecError(`session "${inv.id}" is still running (pid ${view.pid}).`, { exitCode: 7, kind: 'busy' });
     }
   } else {
-    try {
-      prepareSession(inv);
-    } catch (err) {
-      if (err instanceof store.SessionExistsError) usage(err.message);
-      throw err;
-    }
+    prepareSession(inv);
   }
   const dir = store.sessionDir(inv.id);
   store.writeJsonAtomic(path.join(dir, 'pending.json'), inv);
@@ -200,8 +232,10 @@ function detach(inv, flags) {
     env: process.env,
   });
   child.unref();
+  fs.closeSync(out);
+  fs.closeSync(err);
   store.updateSession(inv.id, { state: 'queued', phase: 'queued', pid: child.pid, status: null });
-  const handle = {
+  return {
     type: 'detached',
     id: inv.id,
     pid: child.pid,
@@ -209,17 +243,32 @@ function detach(inv, flags) {
     status: 'queued',
     files: { session: dir, stdout: path.join(dir, 'stdout.ndjson'), stderr: path.join(dir, 'stderr.log') },
   };
+}
+
+// --detach: start in the background, print the handle, exit 0.
+function detach(inv, flags) {
+  let handle;
+  try {
+    handle = startDetached(inv);
+  } catch (err) {
+    if (err instanceof store.SessionExistsError) usage(err.message);
+    if (err instanceof ExecError) {
+      process.stderr.write(`zcode: ${err.message}\n`);
+      process.exit(err.exitCode);
+    }
+    throw err;
+  }
   if (flags.json) process.stdout.write(JSON.stringify(handle) + '\n');
   else {
     process.stdout.write(`${inv.id}\n`);
     if (!flags.quiet) {
-      process.stderr.write(`zcode: started ${inv.id} in the background (pid ${child.pid}). zcode status ${inv.id} · zcode wait ${inv.id}\n`);
+      process.stderr.write(`zcode: started ${inv.id} in the background (pid ${handle.pid}). zcode status ${inv.id} · zcode wait ${inv.id}\n`);
     }
   }
   process.exit(0);
 }
 
-module.exports = async function exec(parsed) {
+async function exec(parsed) {
   const { command, flags } = parsed;
   let inv;
   let worker = false;
@@ -251,6 +300,7 @@ module.exports = async function exec(parsed) {
   // Workers always emit NDJSON (to their stdout file) and never a TTY feed.
   const json = worker || flags.json;
   const quiet = flags.quiet && !worker;
+  const full = flags.full && !worker;
   const kind = inv.kind;
   const reporter = makeReporter({
     quiet,
@@ -295,7 +345,7 @@ module.exports = async function exec(parsed) {
         type: 'result', ok: false, status: 'failed', id: inv.id, kind,
         error: { kind: err.kind || 'config', message: err.message }, issues: [err.message],
       };
-      if (json) process.stdout.write(JSON.stringify(failed) + '\n');
+      if (json) process.stdout.write(JSON.stringify(full ? failed : buildBrief(failed)) + '\n');
       // A detached worker's caller polls the store: record why it never ran
       // (conflicts already record themselves).
       if (worker && err.kind !== 'conflict' && store.readSession(inv.id)) {
@@ -311,7 +361,7 @@ module.exports = async function exec(parsed) {
 
   const code = exitCodeFor(result);
   if (json) {
-    process.stdout.write(JSON.stringify(result) + '\n');
+    process.stdout.write(JSON.stringify(full ? result : buildBrief(result)) + '\n');
   } else if (kind === 'task') {
     reporter.closeThinking();
     process.stdout.write(formatResult(result, { color: useColor(process.stdout) }));
@@ -325,4 +375,19 @@ module.exports = async function exec(parsed) {
     }
   }
   process.exit(code);
+}
+
+module.exports = async function execCommand(parsed) {
+  try {
+    return await exec(parsed);
+  } catch (err) {
+    if (!(err instanceof UsageError)) throw err;
+    process.stderr.write(`zcode: ${err.message}\n`);
+    process.exit(2);
+  }
 };
+
+module.exports.buildInvocation = buildInvocation;
+module.exports.buildResume = buildResume;
+module.exports.startDetached = startDetached;
+module.exports.UsageError = UsageError;

package/lib/commands/plan.js

@@ -0,0 +1,301 @@
+'use strict';
+// lib/commands/plan.js — plan check|run|wait|status|resume, and __plan (the
+// detached supervisor). Logic lives in lib/plan.js.
+//
+// Output contract: JSON mode prints exactly one line per call (plan check:
+// {type:"plan-check"}; run/wait/status/resume: {type:"plan",name,status,
+// sessions:[{id,status}],briefs:[…]}; a timeout or --detach: the same
+// without briefs). `plan run --preflight` prints one brief per session with
+// questions. Exit codes: 0 completed · 10 blocked · 8 partial/failed ·
+// 124 timeout · 2 usage · 7 plan exists.
+const store = require('../store.js');
+const plans = require('../plan.js');
+const { buildBrief } = require('../brief.js');
+const { exitCodeFor } = require('../executor.js');
+const { questionText } = require('../contract.js');
+const { formatResult, useColor } = require('../ui.js');
+
+const out = (line) => process.stdout.write(line + '\n');
+
+function die(code, message) {
+  process.stderr.write(`zcode: ${message}\n`);
+  process.exit(code);
+}
+
+function load(file, parsed) {
+  if (!file) die(2, 'plan needs a plan file.');
+  try {
+    return plans.resolvePlan(file, parsed.given.has('cwd') ? parsed.flags.cwd : undefined);
+  } catch (err) {
+    if (err instanceof plans.PlanError) return die(2, err.message);
+    throw err;
+  }
+}
+
+function nameOf(parsed, file) {
+  try {
+    return plans.planName(parsed.flags.id, file);
+  } catch (err) {
+    if (err instanceof plans.PlanError) return die(2, err.message);
+    throw err;
+  }
+}
+
+// A plan by name (state + its plan file), or exit 2.
+function open(name) {
+  const state = store.readPlanState(name);
+  if (!state) die(2, `no plan "${name}" (zcode plan run <file> starts one).`);
+  try {
+    return { state, r: plans.resolvePlan(state.file, state.cwd) };
+  } catch (err) {
+    if (err instanceof plans.PlanError) return die(2, err.message);
+    throw err;
+  }
+}
+
+function problemsOrExit(problems, json) {
+  if (!problems.length) return;
+  if (json) out(JSON.stringify({ type: 'plan-check', ok: false, problems }));
+  for (const p of problems) process.stderr.write(`zcode: ${p}\n`);
+  process.exit(2);
+}
+
+// One line per session; a non-completed session adds its one-line summary,
+// a blocked one its questions.
+function humanReport(report) {
+  const brief = new Map((report.briefs || []).map((b) => [b.id, b]));
+  const lines = [];
+  for (const s of report.sessions) {
+    const b = brief.get(s.id);
+    const note = b && (b.summary || (b.error && b.error.message) || '');
+    lines.push(`${s.id} ${s.status}${note ? ` - ${note.replace(/\s+/g, ' ').slice(0, 120)}` : ''}`);
+    if (b && b.questions) for (const q of b.questions) lines.push(`  ? ${questionText(q).replace(/\n/g, '\n  ')}`);
+  }
+  return lines.join('\n');
+}
+
+function print(report, flags) {
+  if (flags.json) out(JSON.stringify(report));
+  else {
+    process.stderr.write(`plan ${report.name}: ${report.status}\n`);
+    out(humanReport(report));
+  }
+}
+
+const reportOf = (name) => {
+  const { state, r } = open(name);
+  return plans.planReport(name, r, state);
+};
+
+function finish(report, flags) {
+  print(report, flags);
+  process.exit(plans.exitCodeForPlan(report.status));
+}
+
+// Timeout / detach summary: statuses only.
+function brief(name, flags, status) {
+  const { state, r } = open(name);
+  const report = plans.planReport(name, r, state, { briefs: false });
+  if (status) report.status = status;
+  if (flags.json) return print(report, flags);
+  // Human mode: the whole timeout/detach summary is one stdout line.
+  out(`plan ${report.name}: ${report.status} (${report.sessions.map((s) => `${s.id} ${s.status}`).join(', ')})`);
+}
+
+// Supervises in-process until the plan settles (or the deadline). On a
+// deadline the supervision is handed to a detached supervisor so the plan
+// keeps going.
+async function superviseAndReport(name, flags, given) {
+  const deadline = given.has('timeoutMs') ? Date.now() + flags.timeoutMs : Infinity;
+  const res = await plans.supervise(name, { deadline });
+  if (res.timedOut) {
+    plans.startSupervisor(name);
+    brief(name, flags, 'running');
+    process.exit(124);
+  }
+  if (res.busy) {
+    // Another supervisor already drives it: just wait for it.
+    return waitFor(name, flags, given);
+  }
+  return finish(reportOf(name), flags);
+}
+
+async function waitFor(name, flags, given) {
+  const deadline = given.has('timeoutMs') ? Date.now() + flags.timeoutMs : Infinity;
+  for (;;) {
+    const report = reportOf(name);
+    if (report.status !== 'running') return finish(report, flags);
+    if (Date.now() >= deadline) {
+      brief(name, flags, 'running');
+      process.exit(124);
+    }
+    await plans.sleep(plans.POLL_MS);
+  }
+}
+
+async function check(parsed, file) {
+  const r = load(file, parsed);
+  const name = nameOf(parsed, file);
+  const problems = plans.checkPlan(r, { name, state: store.readPlanState(name) });
+  problemsOrExit(problems, parsed.flags.json);
+  const n = plans.sessionList(r.plan).length;
+  if (parsed.flags.json) out(JSON.stringify({ type: 'plan-check', ok: true, name, sessions: n }));
+  else out(`plan ${name}: ${n} session${n === 1 ? '' : 's'}, ok`);
+  process.exit(0);
+}
+
+async function run(parsed, file) {
+  const { flags, given } = parsed;
+  const r = load(file, parsed);
+  const name = nameOf(parsed, file);
+  const state = store.readPlanState(name);
+  if (flags.preflight) return preflight(parsed, r, name, state);
+  if (state) {
+    die(7, `plan "${name}" already exists. Continue it with "zcode plan resume ${name}" (status: "zcode plan status ${name}"), or run again with another --id.`);
+  }
+  problemsOrExit(plans.checkPlan(r, { name }), flags.json);
+  const ok = store.createPlanState(name, {
+    file: r.file,
+    cwd: r.cwd,
+    sessions: plans.sessionList(r.plan).map((s) => s.id),
+    supervisor: null,
+    launchErrors: {},
+  });
+  if (!ok) die(7, `plan "${name}" already exists. Continue it with "zcode plan resume ${name}".`);
+  return startSupervision(name, flags, given);
+}
+
+async function startSupervision(name, flags, given) {
+  if (flags.detach) {
+    plans.startSupervisor(name);
+    out(JSON.stringify({ type: 'plan', name, status: 'running' }));
+    process.exit(0);
+  }
+  return superviseAndReport(name, flags, given);
+}
+
+// Preflight every session (read-only, in parallel, as "<id>.pre"), wait for
+// all, print one brief per session that has questions. Creates no plan state.
+async function preflight(parsed, r, name, state) {
+  const { flags, given } = parsed;
+  problemsOrExit(plans.checkPlan(r, { name, state }), flags.json);
+  const sessions = plans.sessionList(r.plan);
+  const e = require('./exec.js');
+  const ids = [];
+  const failed = [];
+  for (const s of sessions) {
+    const pre = `${s.id}.pre`;
+    const old = store.readSession(pre);
+    if (old) {
+      if (store.viewSession(old).live) die(7, `preflight session "${pre}" is still running; cancel it first (zcode cancel ${pre}).`);
+      store.deleteSession(pre);
+    }
+    try {
+      e.startDetached(plans.sessionInvocation(r, name, s, { id: pre, preflight: true }));
+      ids.push(pre);
+    } catch (err) {
+      if (err instanceof e.UsageError || err.exitCode || err instanceof store.SessionExistsError) {
+        failed.push(plans.launchFailure(pre, err.message));
+      } else throw err;
+    }
+  }
+  const { finalResult } = require('./sessions.js');
+  const deadline = Date.now() + (given.has('timeoutMs') ? flags.timeoutMs : 600000);
+  const pending = new Set(ids);
+  const results = [...failed];
+  for (;;) {
+    for (const id of [...pending]) {
+      const view = store.viewSession(store.readSession(id));
+      if (view.state === 'finished' || view.state === 'interrupted') {
+        pending.delete(id);
+        results.push(finalResult(view));
+      }
+    }
+    if (!pending.size) break;
+    if (Date.now() >= deadline) {
+      for (const id of pending) {
+        const v = store.viewSession(store.readSession(id));
+        out(flags.json ? JSON.stringify({ type: 'pending', id, state: v.state, phase: v.phase }) : `${id} ${v.state} ${v.phase}`);
+      }
+      process.exit(124);
+    }
+    await plans.sleep(plans.POLL_MS);
+  }
+  const asked = results.filter((x) => x.questions && x.questions.length);
+  const broken = results.filter((x) => !(x.questions && x.questions.length) && x.status !== 'completed');
+  for (const x of [...asked, ...broken]) {
+    if (flags.json) out(JSON.stringify(buildBrief(x)));
+    else out(formatResult(x, { color: useColor(process.stdout) }));
+  }
+  if (!asked.length && !broken.length) {
+    if (flags.json) out(JSON.stringify({ type: 'preflight', name, status: 'completed', sessions: ids.length }));
+    else out(`plan ${name}: preflight found no open questions (${ids.length} session${ids.length === 1 ? '' : 's'})`);
+  }
+  process.exit(asked.length ? 10 : broken.length ? Math.max(...broken.map((x) => exitCodeFor(x))) : 0);
+}
+
+async function resume(parsed, name, words) {
+  const { flags, given } = parsed;
+  const { state, r } = open(name);
+  const text = words.join(' ').trim();
+  const statuses = plans.sessionStatuses(r, state);
+  const RESUMABLE = new Set(['failed', 'partial', 'unverified', 'blocked', 'cancelled', 'interrupted']);
+  let targets;
+  if (flags.session) {
+    const e = statuses.get(flags.session);
+    if (!e) die(2, `plan "${name}" has no session "${flags.session}".`);
+    if (!RESUMABLE.has(e.status) || !e.view) die(2, `session "${flags.session}" is ${e.status}; only failed, partial, unverified, blocked, cancelled or interrupted sessions resume.`);
+    targets = [flags.session];
+  } else {
+    targets = plans.sessionList(r.plan).map((s) => s.id).filter((id) => RESUMABLE.has(statuses.get(id).status) && statuses.get(id).view);
+  }
+  const blocked = targets.filter((id) => statuses.get(id).status === 'blocked');
+  if (blocked.length && !text) {
+    die(2, `${blocked.join(', ')} ${blocked.length === 1 ? 'is' : 'are'} blocked: answer the questions: zcode plan resume ${name} "…" (or --session <id> "…" for one session)`);
+  }
+  if (!targets.length && !flags.session && ![...statuses.values()].some((x) => x.status === 'pending' || x.status === 'skipped')) {
+    // nothing to resume: report as is
+    return finish(plans.planReport(name, r, state), flags);
+  }
+  const message = text || 'Continue: fix the remaining issues.';
+  for (const id of targets) {
+    const refusal = plans.resumeSession(id, message);
+    if (refusal) die(7, refusal);
+  }
+  // Launch failures recorded earlier are retried by the supervisor.
+  if (state.launchErrors && Object.keys(state.launchErrors).length) {
+    store.updatePlanState(name, { launchErrors: {} });
+  }
+  return startSupervision(name, flags, given);
+}
+
+// Detached supervisor process: `zcode __plan <name>`.
+async function supervisorWorker(name) {
+  if (!store.readPlanState(name)) die(2, `no plan "${name}".`);
+  await plans.supervise(name);
+  process.exit(0);
+}
+
+module.exports = async function plan(parsed) {
+  if (parsed.command === '__plan') return supervisorWorker(parsed.prompts[0]);
+  const [sub, ...rest] = parsed.prompts;
+  switch (sub) {
+    case 'check':
+      return check(parsed, rest[0]);
+    case 'run':
+      return run(parsed, rest[0]);
+    case 'wait':
+    case 'status': {
+      if (!rest[0]) die(2, `plan ${sub} needs a plan name.`);
+      open(rest[0]);
+      if (sub === 'wait') return waitFor(rest[0], parsed.flags, parsed.given);
+      print(reportOf(rest[0]), parsed.flags);
+      process.exit(0);
+    }
+    case 'resume':
+      if (!rest[0]) die(2, 'plan resume needs a plan name.');
+      return resume(parsed, rest[0], rest.slice(1));
+    default:
+      return die(2, 'plan needs a subcommand: check | run | wait | status | resume (zcode --help).');
+  }
+};