runlist 0.0.0 → 0.94.1

package/src/decision-action.mjs

@@ -0,0 +1,58 @@
+import { parseDecisionItems, decisionSettings, dispositionOf } from './decisions.mjs';
+import { SourceEditError } from './source-editor.mjs';
+
+// A source preparation shared by the CLI and the app. The source editor owns
+// authority, claims, revision checking, operation receipts, and publication.
+export function prepareDecisionAction(source, request, settings = {}) {
+  const {id,line,disposition,note,choice,actor,at}=request;
+  const fail=message=>{throw new SourceEditError('decision-invalid-action',message);};
+  if(!['open','held','ruled','closed'].includes(disposition))fail('Choose open, held, ruled or closed.');
+  if(!actor?.id||!['human','agent'].includes(actor.kind))fail('A verified actor is required.');
+  if(disposition==='ruled'&&actor.kind!=='human')fail('A ruling must be recorded by a human; an agent can keep a recommendation in the source.');
+  if(typeof note!=='string'||!note.trim()||note.length>4000)fail('Give a reason, up to 4,000 characters.');
+  if(disposition==='ruled'&&(typeof choice!=='string'||!choice.trim()))fail('Write the selected answer before recording a ruling.');
+  if(typeof at!=='string'||Number.isNaN(Date.parse(at)))fail('A recording timestamp is required.');
+  const settingsResolved=decisionSettings(settings??{}),items=parseDecisionItems(source,settingsResolved);
+  const item=items.find(item=>item.id===id&&item.line===line);
+  if(!item)throw new SourceEditError('decision-revision-conflict','This decision moved or changed. Reload its record before recording an outcome.');
+  const one=value=>String(value??'').replace(/[\r\n]+/g,' ').replace(/[<>|]/g,c=>({'<':'&lt;','>':'&gt;','|':'&#124;'}[c]));
+  // Inline provenance follows the newest explicit disposition. Earlier source
+  // and earlier outcomes remain verbatim, behind it, in the same record.
+  const outcome=`Disposition: ${disposition.toUpperCase()} ${at}. Recorded by ${one(actor.label??actor.id)} (${one(actor.kind)}). ${disposition==='ruled'?`Selected answer: ${one(choice)}. `:''}Reason: ${one(note)}.`;
+  const lines=source.match(/[^\r\n]*(?:\r\n|\n|\r|$)/g).filter(Boolean),index=line-1;
+  const original=lines[index],eol=original.match(/\r\n|\n|\r$/)?.[0]??'\n';
+  if(item.kind==='heading'){if(!/[\r\n]$/.test(original))lines[index]+=eol;lines.splice(index+1,0,`${outcome}${eol}`);}
+  else {
+    // Keep a one-line record one line, including register/table rows.
+    const escaped=id.replace(/[.*+?^${}()|[\]\\]/g,'\\$&');
+    const match=item.kind==='table'?original.match(/^(\|\s*\**[^|]+\**\s*\|\s*)/):item.kind==='register'?original.match(/^(\S+\s{1,3})/):original.match(new RegExp(`^((?:[-*]\\s+(?:\\[[ xX]\\]\\s+)?)?\\**${escaped}\\**[\\s,.:—-]+)`));
+    if(!match)fail('This record cannot be updated unambiguously. Open its source to edit it.');
+    lines[index]=original.slice(0,match[0].length)+'**Recorded outcome:** '+outcome+' **Original record:** '+original.slice(match[0].length);
+  }
+  const next=lines.join(''),after=parseDecisionItems(next,settingsResolved).find(i=>i.id===id&&i.line===line);
+  if(!after||dispositionOf(after,settingsResolved)!==disposition)fail('The updated record no longer parses. Its source was left unchanged.');
+  return next;
+}
+
+export async function runDecisionAction(argv,config,{dryRun=false,env=process.env}={}) {
+  const [{createSourceEditor},{resolveDocArg},{hostSessionSource},{randomUUID,createHash},{default:os},{default:path}]=await Promise.all([import('./source-editor.mjs'),import('./index.mjs'),import('./util.mjs'),import('node:crypto'),import('node:os'),import('node:path')]);
+  const positional=[],options={};
+  for(let i=0;i<argv.length;i++){if(argv[i].startsWith('--')){if(argv[i]==='--json')options.json=true;else options[argv[i].slice(2)]=argv[++i];}else positional.push(argv[i]);}
+  const [input,id]=positional;
+  if(!input||!id||!options.disposition||!options.note)throw new SourceEditError('decision-invalid-action','Use runlist decision <file> <id> --disposition open|held|ruled|closed --note <reason> [--choice <answer>].');
+  const file=resolveDocArg(input,config),session=hostSessionSource(env),agent=session?.scope==='session';
+  if(session?.scope==='process')throw new SourceEditError('decision-invalid-actor','An agent needs a session-scoped identity before recording an outcome.');
+  const actor=agent?{kind:'agent',id:session.id,session_id:session.id,label:session.host??session.id}:{kind:'human',id:`human:local:${createHash('sha256').update(`${os.userInfo().username}:${os.userInfo().uid}`).digest('hex').slice(0,24)}`,label:os.userInfo().username};
+  const editor=createSourceEditor({config,legacyTypes:[...(config.validTypes??['plan','doc'])].filter(t=>t!=='prompt'),authenticate:()=>actor,authorize:({path:target})=>({allowed:target===file&&!path.relative(config.repoRoot,target).split(path.sep).some(p=>p==='prompts'||p==='.git'||config.excludeDirs?.has(p)),...(agent?{grant_id:`cli:decision:${actor.session_id}:${path.relative(config.repoRoot,file)}`}:{})})});
+  const current=editor.read(null,{path:file});
+  if(['flag','decision'].includes(current.type))throw new SourceEditError('record-read-only','Native flag and decision records require their domain writer; this command records outcomes in existing plan/register sections.');
+  const items=parseDecisionItems(current.source,decisionSettings(config.raw?.decisions??{}));
+  const matches=items.filter(item=>item.id===id);
+  if(matches.length!==1)throw new SourceEditError('decision-invalid-action','The source must contain exactly one decision with this ID.');
+  if(!current.editable)throw new SourceEditError('record-read-only','This source does not support managed decision actions.');
+  if(options['expected-revision']&&options['expected-revision']!==current.revision)throw new SourceEditError('decision-revision-conflict','The source changed; read the decision again before recording an outcome.');
+  const source=prepareDecisionAction(current.source,{id,line:matches[0].line,disposition:options.disposition,note:options.note,choice:options.choice,actor,at:new Date().toISOString()},config.raw?.decisions);
+  if(dryRun){process.stdout.write(source);return {dryRun:true,source};}
+  const outcome=editor.save(null,{path:file,source,expectedRevision:current.revision,operationId:randomUUID()});
+  process.stdout.write(options.json?JSON.stringify(outcome)+'\n':`${id}: ${options.disposition} recorded in ${path.relative(config.repoRoot,file)}.\n`);return outcome;
+}

package/src/decision.mjs

@@ -0,0 +1,220 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { mutateFileSet } from './atomic-mutation.mjs';
+import { authorizeManagedSource } from './managed-path.mjs';
+import { walkSections } from './section.mjs';
+import { die, nowIso, resolveDocPath, toRepoPath } from './util.mjs';
+import { green, dim } from './color.mjs';
+
+// `runlist new decision <plan> --question "…" @record.md`
+//
+// A decision is not a document of its own: it is an entry in the owning plan's
+// decisions section, carrying an id, a disposition and a written record. This
+// adds one, numbered after the highest id of its prefix the plan (and the
+// register, when there is one) already uses, at the end of the plan's top-level
+// decisions section, creating `## Decisions` when the plan has none. A
+// decisions heading nested inside a workstream is that workstream's record and
+// is left alone.
+//
+// Config (`runlist.config.mjs`), all optional:
+//   export const decisions = {
+//     section: 'Decisions',   // the heading the entry lands under
+//     prefix: 'D',            // what a new id is written under
+//     register: { file: 'docs/plans/register.md', statusLine: 'waiting on you:' },
+//   };
+// With a register, ids are one sequence across the corpus: the next id is
+// numbered after the highest the register or the plan uses, and the register
+// gets the entry's index row in the same locked write as the plan. Without
+// one, ids are plan-local.
+
+const DISPOSITIONS = new Set(['open', 'held']);
+const DECISION_HEADING = /\bdecisions?\b/i;
+
+function splitDoc(raw) {
+  if (!raw.startsWith('---\n')) return null;
+  const end = raw.indexOf('\n---\n', 4);
+  if (end === -1) return null;
+  return { frontmatter: raw.slice(4, end), body: raw.slice(end + 5) };
+}
+
+function stripFences(text) {
+  return text.replace(/^(`{3,}|~{3,})[^\n]*\n[\s\S]*?^\1[^\n]*$/gm, '');
+}
+
+const escapeRe = text => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+// Ids are read where a decision item starts (a heading, a list or bold lead,
+// a table row or a register row), never from prose, where the same shape is
+// as likely to be a job code or a citation of another plan's decision.
+function highestId(text, prefix) {
+  const re = new RegExp(`^\\s*(?:#{1,6}\\s+|[-*]\\s+(?:\\[[ xX]\\]\\s+)?|\\|\\s*)?\\**${escapeRe(prefix)}(\\d{1,4})\\b`);
+  let max = 0;
+  for (const line of text.split('\n')) {
+    const m = line.match(re);
+    if (m) max = Math.max(max, Number(m[1]));
+  }
+  return max;
+}
+
+export function nextDecisionId(body, prefix, register = null) {
+  let max = highestId(stripFences(body), prefix);
+  if (register) {
+    const rows = register.rows.map(row => row.match(new RegExp(`^${escapeRe(prefix)}(\\d{1,4})\\b`))?.[1]);
+    for (const n of rows) if (n) max = Math.max(max, Number(n));
+  }
+  return `${prefix}${max + 1}`;
+}
+
+// The register block: a fence whose first line carries the configured status
+// line. Returns its rows and where the closing fence sits, or null.
+export function findRegister(text, statusLine) {
+  const lines = text.split('\n');
+  const wanted = statusLine.trim().toLowerCase();
+  for (let i = 0; i < lines.length; i++) {
+    const open = lines[i].match(/^(`{3,}|~{3,})/);
+    if (!open) continue;
+    let close = i + 1;
+    while (close < lines.length && !lines[close].startsWith(open[1])) close++;
+    if (close >= lines.length) return null;
+    const first = (lines[i + 1] ?? '').trim().toLowerCase();
+    if (first.includes(wanted)) {
+      return { closeLine: close, rows: lines.slice(i + 2, close).filter(line => line.trim()) };
+    }
+    i = close;
+  }
+  return null;
+}
+
+export function insertRegisterRow(text, register, row) {
+  const lines = text.split('\n');
+  let at = register.closeLine;
+  while (at > 0 && lines[at - 1].trim() === '') at--;
+  lines.splice(at, 0, row);
+  return lines.join('\n');
+}
+
+// Returns the new body and where the entry went. Pure, for tests.
+export function insertDecision(body, { id, question, disposition, record, section: heading = 'Decisions' }) {
+  const lines = body.split('\n');
+  const sections = walkSections(body);
+  const named = s => s.heading.replace(/[^\w\s]+$/, '').trim().toLowerCase() === heading.toLowerCase();
+  const section = sections.find(s => s.level === 2 && named(s))
+    ?? sections.find(s => s.level === 2 && DECISION_HEADING.test(s.heading));
+  const level = section ? Math.min(section.level + 1, 6) : 3;
+  const entry = [
+    `${'#'.repeat(level)} ${id}  ${question.trim()}`,
+    '',
+    `Disposition: ${disposition.toUpperCase()}.`,
+    '',
+    record.trim(),
+  ];
+
+  if (section) {
+    // After the section's last non-blank line, subsections included.
+    let at = section.lineEnd;
+    while (at > section.lineStart && lines[at - 1].trim() === '') at--;
+    const tail = at < lines.length && lines[at].trim() !== '' ? [''] : [];
+    lines.splice(at, 0, '', ...entry, ...tail);
+    return { body: lines.join('\n'), placement: `under \`${section.heading}\``, heading: section.heading };
+  }
+
+  const block = [`## ${heading}`, '', ...entry];
+  const before = sections.find(s => s.level === 2 && /^(version history|closeout)\b/i.test(s.heading));
+  if (before) {
+    lines.splice(before.lineStart - 1, 0, ...block, '');
+    return { body: lines.join('\n'), placement: `in a new \`## ${heading}\` before \`${before.heading}\``, heading };
+  }
+  const trimmed = body.replace(/\n+$/, '');
+  return { body: `${trimmed}\n\n${block.join('\n')}\n`, placement: `in a new \`## ${heading}\` at the end`, heading };
+}
+
+export function runNewDecision({ planArg, question, disposition, record, answers = null }, config, { dryRun = false } = {}) {
+  const usage = 'Usage: runlist new decision <plan> --question "<the question>" @record.md';
+  if (!planArg) die(`${usage}\nThe plan is the file whose decisions section gets the entry.`);
+  if (!question || !question.trim()) die(`--question is required.\n${usage}`);
+  if (/\n/.test(question)) die('--question is one line; the record carries the rest.');
+  if (!record || !record.trim()) {
+    die('A decision needs its record: the situation, what exists today, and what each answer leaves in place.\n'
+      + `Write it to a file and pass @path, pipe it in, or pass --body "...".\n${usage}`);
+  }
+  disposition = (disposition ?? 'open').toLowerCase();
+  if (!DISPOSITIONS.has(disposition)) {
+    die(`--disposition must be open or held; a ruled or closed decision is edited in place, not added.`);
+  }
+
+  const resolved = resolveDocPath(planArg, config)
+    ?? (planArg.endsWith('.md') ? null : resolveDocPath(`${planArg}.md`, config))
+    ?? (planArg.includes('/') ? null : resolveDocPath(path.join('plans', `${planArg}.md`), config));
+  if (!resolved) die(`No such plan: ${planArg}`);
+  const planPath = authorizeManagedSource(resolved, config, { kind: 'Decision target' }).path;
+  const planRepoPath = toRepoPath(planPath, config.repoRoot);
+
+  const settings = config.raw?.decisions ?? {};
+  const prefix = settings.prefix ?? 'D';
+  const section = settings.section ?? 'Decisions';
+  let registerPath = null;
+  if (settings.register?.file) {
+    if (!settings.register.statusLine) die('decisions.register needs a statusLine: the first line of the register block.');
+    const registerResolved = resolveDocPath(settings.register.file, config);
+    if (!registerResolved) die(`The decisions register in config does not exist: ${settings.register.file}`);
+    registerPath = authorizeManagedSource(registerResolved, config, { kind: 'Decision register' }).path;
+  }
+  const sameFile = registerPath === planPath;
+  if (registerPath && (!answers || !answers.trim())) {
+    die('--answers is required with a register: the row says what each answer leaves in place and what it costs.\n'
+      + `${usage} --answers "Yes: … No: …"`);
+  }
+
+  const today = nowIso();
+  const planRaw = readFileSync(planPath, 'utf8');
+  const registerRaw = registerPath && !sameFile ? readFileSync(registerPath, 'utf8') : null;
+
+  const planDoc = splitDoc(planRaw.replace(/\r\n/g, '\n'));
+  if (!planDoc) die(`${planRepoPath} has no frontmatter block; runlist only adds decisions to managed documents.`);
+  const registerText = sameFile ? planDoc.body : registerRaw?.replace(/\r\n/g, '\n');
+  const register = registerPath ? findRegister(registerText, settings.register.statusLine) : null;
+  if (registerPath && !register) {
+    die(`${toRepoPath(registerPath, config.repoRoot)} has no block whose first line carries "${settings.register.statusLine}".`);
+  }
+
+  const id = nextDecisionId(planDoc.body, prefix, register);
+  const inserted = insertDecision(planDoc.body, { id, question, disposition, record, section });
+  let planBody = inserted.body;
+  let row = null;
+  if (register && sameFile) {
+    row = registerRow({ id, disposition, today, question, answers, heading: inserted.heading, link: path.basename(planPath) });
+    planBody = insertRegisterRow(planBody, findRegister(planBody, settings.register.statusLine), row);
+  }
+  const bump = fm => (/^updated:/m.test(fm) ? fm.replace(/^updated:.*$/m, `updated: ${today}`) : fm);
+  const planOut = `---\n${bump(planDoc.frontmatter)}\n---\n${planBody}`;
+
+  const updates = [{ path: planPath, expectedContent: planRaw, content: planOut }];
+  if (register && !sameFile) {
+    const link = path.relative(path.dirname(registerPath), planPath).split(path.sep).join('/');
+    row = registerRow({ id, disposition, today, question, answers, heading: inserted.heading, link });
+    const registerOut = insertRegisterRow(registerText, register, row);
+    const registerDoc = splitDoc(registerOut);
+    updates.push({
+      path: registerPath,
+      expectedContent: registerRaw,
+      content: registerDoc ? `---\n${bump(registerDoc.frontmatter)}\n---\n${registerDoc.body}` : registerOut,
+    });
+  }
+
+  const registerRepoPath = registerPath ? toRepoPath(registerPath, config.repoRoot) : null;
+  if (dryRun) {
+    process.stdout.write(`[dry-run] Would add ${id} to ${planRepoPath} ${inserted.placement}\n`);
+    if (row) process.stdout.write(`[dry-run] Would add its row to the register in ${registerRepoPath}:\n  ${row}\n`);
+    return { id, row };
+  }
+
+  mutateFileSet({ updates }, { repoRoot: config.repoRoot });
+  process.stdout.write(`${green('Added')} ${id} to ${planRepoPath} ${dim(inserted.placement)}\n`);
+  if (row) process.stdout.write(`${green('Added')} its row to the register in ${registerRepoPath}\n`);
+  return { id, row };
+}
+
+function registerRow({ id, disposition, today, question, answers, heading, link }) {
+  const text = `${question.trim()} ${answers.trim()}`;
+  return `${id} ${disposition.toUpperCase()} ${today.slice(0, 10)}: ${text} Record: [${link} § ${heading} ${id}](${link}).`;
+}