mainflow 0.11.2 → 0.13.0

package/dist/cli.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
-import { C as supersedeDecision, F as updateAction, G as createIssue, H as appendOps, I as sessionBriefing, J as setFindingArchived, K as planIssue, N as startSession, O as readSession, Q as loadHub, T as addAction, U as closeIssue, W as createFinding, X as setIssueArchived, Y as setFindingStatus, Z as HubError, _ as initHub, b as setCriterion, d as addHub, f as addRepo, g as dropChecklistItem, h as createTask, it as WriteError, j as setSessionStatus, k as setSessionArchived, l as migrateHub, m as createMainline, nt as TASK_FILE, p as createDecision, q as reopenIssue, st as findHubRoot, tt as MAINLINE_FILE, u as acceptDecision, v as setArchived, w as updateTask, x as setMainlineStatus, y as setChecklistItem } from "./host-C3MyDGB_.js";
+import { $ as setFindingStatus, A as addAction, C as setCriterionText, D as updateTask, E as supersedeDecision, F as setSessionArchived, J as createFinding, K as appendOps, L as setSessionStatus, M as handoffSession, O as sessionBriefing, P as readSession, Q as setFindingArchived, S as setCriterion, V as updateAction, X as planIssue, Y as createIssue, Z as reopenIssue, _ as createTask, b as setArchived, ct as TASK_FILE, et as setIssueArchived, f as acceptDecision, g as createMainline, h as createDecision, l as migrateHub, m as addRepo, nt as loadHub, p as addHub, pt as findHubRoot, q as closeIssue, st as MAINLINE_FILE, tt as HubError, ut as WriteError, v as dropChecklistItem, w as setMainlineStatus, x as setChecklistItem, y as initHub, z as startSession } from "./host-daQGe7no.js";
+import { N as parseRef, P as refExample } from "./dist-BQmXEfAf.js";
 import { t as listProgress } from "./progress-1BfPg2zN.js";
 import { COMMAND_SPECS, OPTIONS } from "./facts.js";
 import { runHook } from "./hooks.js";
-import { l as CLI_VERSION, r as launchUi, s as startUiInBackground } from "./launch-T0sXbTgT.js";
+import { l as CLI_VERSION, r as launchUi, s as startUiInBackground } from "./launch-JK8l8BYu.js";
 import { readFileSync, realpathSync } from "node:fs";
 import { join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -54,6 +55,10 @@ const RUNS = {
 		});
 		return done(`started ${session.id}${session.actions.length ? ` with ${session.actions.length} carried actions` : ""}`);
 	},
+	"session handoff": ({ root, args, opts }) => {
+		const session = handoffSession(root, sessionOf(opts), args[0]);
+		return done(`${session.id} took over ${session.actions.filter((a) => a.status === "todo" || a.status === "doing").length} actions from ${args[0]}`);
+	},
 	"session show": ({ root, args, opts }) => {
 		const id = sessionOf(opts, args[0]);
 		const session = readSession(root, id);
@@ -155,6 +160,13 @@ const RUNS = {
 		setCriterion(root, args[0], false);
 		return done(`unchecked ${args[0]}`);
 	},
+	"criterion set": ({ root, args, opts }) => {
+		setCriterionText(root, args[0], {
+			text: opts.text,
+			doneWhen: opts["done-when"]
+		});
+		return done(`updated ${args[0]}`);
+	},
 	"task set": ({ root, args, opts }) => {
 		const blockedBy = opts.reason ? {
 			reason: opts.reason,
@@ -172,6 +184,18 @@ const RUNS = {
 		});
 		return done(`updated ${args[0]} (${t.status})`);
 	},
+	"task show": ({ root, args }) => {
+		const { mainline, task } = findTask(loadHub(root), args[0]);
+		console.log(`${mainline.id}/${task.id}  ${task.status.padEnd(8)}  ${task.kind}  ${task.title}`);
+		if (task.checklist.length === 0) console.log("  (no checklist items)");
+		for (const c of task.checklist) {
+			const mark = c.done ? "[x]" : "[ ]";
+			const state = c.dropped ? "  (dropped)" : "";
+			console.log(`  ${mark} ${c.id}  ${c.text}${state}`);
+		}
+		for (const link of task.links ?? []) console.log(`  ${link.rel} → ${link.to}${link.note ? `  ${link.note}` : ""}`);
+		return done(`${task.checklist.length} checklist items`);
+	},
 	"item check": ({ root, args, opts }) => {
 		setChecklistItem(root, args[0], true, opts.evidence);
 		return done(`checked ${args[0]}`);
@@ -216,13 +240,18 @@ const RUNS = {
 		return done(`logged ${entry.at} ${entry.operation}`);
 	},
 	"ops list": ({ root, opts }) => {
-		const shown = loadHub(root).ops.filter((o) => !opts.month || o.at.startsWith(opts.month));
+		const shown = loadHub(root).ops.filter((o) => (!opts.month || o.at.startsWith(opts.month)) && (!opts.ref || o.ref === opts.ref));
 		for (const o of shown) console.log(`  ${o.at}  ${o.target}  ${o.operation}  ${o.result}${o.ref ? `  ${o.ref}` : ""}`);
 		return done(`${shown.length} operations`);
 	},
 	"decision supersede": ({ root, args, opts }) => {
 		const d = supersedeDecision(root, args[0], required(opts, "by", "--by d002"));
 		return done(`superseded ${args[0]} by ${d.supersededBy}`);
+	},
+	"decision list": ({ root, args }) => {
+		const mainline = findMainline(loadHub(root), args[0]);
+		for (const d of mainline.decisions) console.log(`  ${mainline.id}/${d.id}  ${d.status.padEnd(10)}  ${d.title}`);
+		return done(`${mainline.decisions.length} decisions`);
 	}
 };
 const COMMANDS = Object.fromEntries(Object.keys(COMMAND_SPECS).map((name) => [name, {
@@ -300,6 +329,24 @@ function sessionOf(opts, arg) {
 	return id;
 }
 const list = (value) => (value ?? "").split(",").map((v) => v.trim()).filter(Boolean);
+/** The mainline a reference names; throws with the same message resolve.ts gives when it is missing. */
+function findMainline(hub, id) {
+	const mainline = hub.mainlines.find((m) => m.id === id);
+	if (!mainline) throw new WriteError(`mainline ${id} not found; run "mainflow status --all" to list mainlines`);
+	return mainline;
+}
+/** The task a `m/t` reference names, with the mainline it sits in. */
+function findTask(hub, refInput) {
+	const ref = parseRef(refInput);
+	if (ref?.kind !== "task") throw new WriteError(`expected a task reference like ${refExample("task")}, got "${refInput}"`);
+	const mainline = findMainline(hub, ref.mainline);
+	const task = mainline.tasks.find((t) => t.id === ref.task);
+	if (!task) throw new WriteError(`task ${refInput} not found`);
+	return {
+		mainline,
+		task
+	};
+}
 function required(opts, name, example) {
 	const value = opts[name];
 	if (!value) throw new WriteError(`--${name} is required, e.g. ${example}`);

package/dist/{dist-D2NK-QQP.js → dist-BQmXEfAf.js}

@@ -124,6 +124,8 @@ function parseLocal(input) {
 	}
 	return null;
 }
+/** The reference a blocked task waits for, when its whole `waitingFor` text is one; free text such as 使用者 gives undefined. */
+const waitingForRef = (waitingFor) => waitingFor && parseRef(waitingFor) ? waitingFor : void 0;
 /** The mainline a reference sits in, or undefined for hub-level issues and findings. */
 const refMainline = (ref) => "mainline" in ref ? ref.mainline : void 0;
 /** The example reference for a kind, used in error messages. */
@@ -382,7 +384,10 @@ const taskSchema = z.object({
 	repo: z.string().min(1).nullable().optional(),
 	startedAt: date.optional(),
 	checklist: z.array(checklistItemSchema),
-	/** Why a blocked task cannot move, what it waits for, and which signal says the wait is over */
+	/**
+	* Why a blocked task cannot move, what it waits for, and which signal says the wait is over. `waitingFor`
+	* is free text, or a reference such as m031/t002 when the whole text is one (see waitingForRef).
+	*/
 	blockedBy: z.object({
 		reason: text,
 		waitingFor: text.optional(),
@@ -508,4 +513,4 @@ function parseOpsLine(line) {
 	return parsed.success ? parsed.data : null;
 }
 //#endregion
-export { mainlineSchema as A, TASK_SECTIONS as C, findingSchema as D, decisionSchema as E, refMainline as F, sessionSchema as I, taskSchema as L, parseOpsLine as M, parseRef as N, formatOpsEntry as O, refExample as P, TASK_REQUIRED_SECTIONS as S, configSchema as T, PRIORITIES as _, DECISION_STATUS as a, SESSION_STATUS as b, FINDING_STATUS as c, ISSUE_SECTIONS as d, ISSUE_STATUS as f, MERGE_STATES as g, MAINLINE_STATUS as h, DECISION_SECTIONS as i, opsEntrySchema as j, issueSchema as k, FORMAT_VERSION as l, MAINLINE_SECTIONS as m, CLOSED_STATUS as n, DEFAULT_CATEGORIES as o, LINK_RELS as p, DECIDERS as r, FINDING_SECTIONS as s, CHECKLIST_REF as t, ID_PATTERNS as u, REF_EXAMPLES as v, WORK_STATUS as w, SLUG as x, RESERVED_HUB_NAMES as y };
+export { mainlineSchema as A, TASK_SECTIONS as C, findingSchema as D, decisionSchema as E, refMainline as F, sessionSchema as I, taskSchema as L, parseOpsLine as M, parseRef as N, formatOpsEntry as O, refExample as P, waitingForRef as R, TASK_REQUIRED_SECTIONS as S, configSchema as T, PRIORITIES as _, DECISION_STATUS as a, SESSION_STATUS as b, FINDING_STATUS as c, ISSUE_SECTIONS as d, ISSUE_STATUS as f, MERGE_STATES as g, MAINLINE_STATUS as h, DECISION_SECTIONS as i, opsEntrySchema as j, issueSchema as k, FORMAT_VERSION as l, MAINLINE_SECTIONS as m, CLOSED_STATUS as n, DEFAULT_CATEGORIES as o, LINK_RELS as p, DECIDERS as r, FINDING_SECTIONS as s, CHECKLIST_REF as t, ID_PATTERNS as u, REF_EXAMPLES as v, WORK_STATUS as w, SLUG as x, RESERVED_HUB_NAMES as y };

package/dist/facts.d.ts

@@ -73,6 +73,12 @@ export declare const COMMAND_SPECS: {
     readonly args: 0;
     readonly needsHub: true;
   };
+  readonly 'session handoff': {
+    readonly usage: 'session handoff <session> [--session <session>]';
+    readonly summary: 'Take over the unfinished actions of another session into this one';
+    readonly args: 1;
+    readonly needsHub: true;
+  };
   readonly 'session show': {
     readonly usage: 'session show [session]';
     readonly summary: 'Print the briefing a hook would give this session';
@@ -183,12 +189,24 @@ export declare const COMMAND_SPECS: {
     readonly args: 1;
     readonly needsHub: true;
   };
+  readonly 'criterion set': {
+    readonly usage: 'criterion set <m#r> [--text <text>] [--done-when <text>]';
+    readonly summary: 'Rewrite a criterion\'s text or doneWhen; done stays as it is (use criterion check/uncheck)';
+    readonly args: 1;
+    readonly needsHub: true;
+  };
   readonly 'task set': {
     readonly usage: 'task set <m/t> [--status] [--reason --waiting-for --signal] [--repo] [--branch --worktree --base --merge]';
     readonly summary: 'Change status, repository or branch state; --status blocked needs --reason';
     readonly args: 1;
     readonly needsHub: true;
   };
+  readonly 'task show': {
+    readonly usage: 'task show <m/t>';
+    readonly summary: 'Print a task: status, kind, checklist and links';
+    readonly args: 1;
+    readonly needsHub: true;
+  };
   readonly 'item check': {
     readonly usage: 'item check <m/t#c> --evidence <evidence>';
     readonly summary: 'Check an item with evidence';
@@ -280,8 +298,8 @@ export declare const COMMAND_SPECS: {
     readonly needsHub: true;
   };
   readonly 'ops list': {
-    readonly usage: 'ops list [--month YYYY-MM]';
-    readonly summary: 'List logged external operations';
+    readonly usage: 'ops list [--month YYYY-MM] [--ref <ref>]';
+    readonly summary: 'List logged external operations, optionally filtered by month or by the exact ref that was logged';
     readonly args: 0;
     readonly needsHub: true;
   };
@@ -291,6 +309,12 @@ export declare const COMMAND_SPECS: {
     readonly args: 1;
     readonly needsHub: true;
   };
+  readonly 'decision list': {
+    readonly usage: 'decision list <m>';
+    readonly summary: 'List a mainline\'s decisions';
+    readonly args: 1;
+    readonly needsHub: true;
+  };
 };
 export type CommandName = keyof typeof COMMAND_SPECS;
 export declare const OPTIONS: {
@@ -340,6 +364,9 @@ export declare const OPTIONS: {
   readonly text: {
     readonly type: 'string';
   };
+  readonly 'done-when': {
+    readonly type: 'string';
+  };
   readonly serves: {
     readonly type: 'string';
   };

package/dist/facts.js

@@ -1,4 +1,4 @@
-import { C as TASK_SECTIONS, S as TASK_REQUIRED_SECTIONS, _ as PRIORITIES, a as DECISION_STATUS, b as SESSION_STATUS, c as FINDING_STATUS, d as ISSUE_SECTIONS, f as ISSUE_STATUS, g as MERGE_STATES, h as MAINLINE_STATUS, i as DECISION_SECTIONS, l as FORMAT_VERSION, m as MAINLINE_SECTIONS, n as CLOSED_STATUS, o as DEFAULT_CATEGORIES, p as LINK_RELS, r as DECIDERS, s as FINDING_SECTIONS, t as CHECKLIST_REF, u as ID_PATTERNS, w as WORK_STATUS, x as SLUG } from "./dist-D2NK-QQP.js";
+import { C as TASK_SECTIONS, S as TASK_REQUIRED_SECTIONS, _ as PRIORITIES, a as DECISION_STATUS, b as SESSION_STATUS, c as FINDING_STATUS, d as ISSUE_SECTIONS, f as ISSUE_STATUS, g as MERGE_STATES, h as MAINLINE_STATUS, i as DECISION_SECTIONS, l as FORMAT_VERSION, m as MAINLINE_SECTIONS, n as CLOSED_STATUS, o as DEFAULT_CATEGORIES, p as LINK_RELS, r as DECIDERS, s as FINDING_SECTIONS, t as CHECKLIST_REF, u as ID_PATTERNS, w as WORK_STATUS, x as SLUG } from "./dist-BQmXEfAf.js";
 //#region src/facts.ts
 const COMMAND_SPECS = {
 	init: {
@@ -49,6 +49,12 @@ const COMMAND_SPECS = {
 		args: 0,
 		needsHub: true
 	},
+	"session handoff": {
+		usage: "session handoff <session> [--session <session>]",
+		summary: "Take over the unfinished actions of another session into this one",
+		args: 1,
+		needsHub: true
+	},
 	"session show": {
 		usage: "session show [session]",
 		summary: "Print the briefing a hook would give this session",
@@ -159,12 +165,24 @@ const COMMAND_SPECS = {
 		args: 1,
 		needsHub: true
 	},
+	"criterion set": {
+		usage: "criterion set <m#r> [--text <text>] [--done-when <text>]",
+		summary: "Rewrite a criterion's text or doneWhen; done stays as it is (use criterion check/uncheck)",
+		args: 1,
+		needsHub: true
+	},
 	"task set": {
 		usage: "task set <m/t> [--status] [--reason --waiting-for --signal] [--repo] [--branch --worktree --base --merge]",
 		summary: "Change status, repository or branch state; --status blocked needs --reason",
 		args: 1,
 		needsHub: true
 	},
+	"task show": {
+		usage: "task show <m/t>",
+		summary: "Print a task: status, kind, checklist and links",
+		args: 1,
+		needsHub: true
+	},
 	"item check": {
 		usage: "item check <m/t#c> --evidence <evidence>",
 		summary: "Check an item with evidence",
@@ -256,8 +274,8 @@ const COMMAND_SPECS = {
 		needsHub: true
 	},
 	"ops list": {
-		usage: "ops list [--month YYYY-MM]",
-		summary: "List logged external operations",
+		usage: "ops list [--month YYYY-MM] [--ref <ref>]",
+		summary: "List logged external operations, optionally filtered by month or by the exact ref that was logged",
 		args: 0,
 		needsHub: true
 	},
@@ -266,6 +284,12 @@ const COMMAND_SPECS = {
 		summary: "Mark a decision as replaced by another",
 		args: 1,
 		needsHub: true
+	},
+	"decision list": {
+		usage: "decision list <m>",
+		summary: "List a mainline's decisions",
+		args: 1,
+		needsHub: true
 	}
 };
 const OPTIONS = {
@@ -287,6 +311,7 @@ const OPTIONS = {
 	"delegated-from": { type: "string" },
 	"handoff-from": { type: "string" },
 	text: { type: "string" },
+	"done-when": { type: "string" },
 	serves: { type: "string" },
 	before: { type: "string" },
 	note: { type: "string" },
@@ -477,7 +502,7 @@ const FIELDS = {
 		field("repo", false, "主要動到的倉庫，名稱需在 config.yaml 登記"),
 		field("startedAt", false, "第一次轉為 doing 時由 CLI 寫入"),
 		field("checklist", true, "checklist 項目清單，每項的欄位見 checklistItem"),
-		field("blockedBy", false, "卡住時的原因、等待對象與繼續的訊號，blocked 時必填"),
+		field("blockedBy", false, "卡住時的原因、等待對象與繼續的訊號，blocked 時必填；等待對象整串是參照時（例如 m031/t002）會檢查它存在"),
 		field("branch", false, "工作所在的分支"),
 		field("worktree", false, "worktree 的路徑"),
 		field("base", false, "分支基於哪個 commit"),

package/dist/hooks.js

@@ -1,4 +1,4 @@
-import { A as setSessionInfo, B as headerLine, E as ensureSession, I as sessionBriefing, L as turnReminder, M as settleSession, O as readSession, Q as loadHub, R as decorateReply, V as mayDecorate, Z as HubError, at as DATA_DIR, ct as worktreesOf, i as hostName, j as setSessionStatus, ot as currentBranch, st as findHubRoot, z as endsWithMarker } from "./host-C3MyDGB_.js";
+import { G as mayDecorate, H as decorateReply, I as setSessionInfo, L as setSessionStatus, O as sessionBriefing, P as readSession, R as settleSession, U as endsWithMarker, W as headerLine, dt as DATA_DIR, ft as currentBranch, i as hostName, j as ensureSession, k as turnReminder, mt as worktreesOf, nt as loadHub, pt as findHubRoot, tt as HubError } from "./host-daQGe7no.js";
 import { appendFileSync, existsSync, readFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 //#region src/hooks.ts
@@ -75,21 +75,45 @@ const displayReply = (root, { payload }) => {
 		displayContent: shown
 	} });
 };
+/** Mainline ids a reply mentions, e.g. m001 in `m001/t003`; not inside a longer word or path. */
+const MAINLINE_MENTION = /(?<![\w/#.[-])(m\d{3})(?![\w\]])/g;
+/** The open mainlines the text mentions; loads the hub only when the text mentions one. */
+function openMainlinesIn(root, text) {
+	const mentioned = new Set([...text.matchAll(MAINLINE_MENTION)].map((m) => m[1]));
+	if (mentioned.size === 0) return [];
+	return loadHub(root, { remotes: false }).mainlines.filter((m) => mentioned.has(m.id) && !m.archivedAt && (m.status === "active" || m.status === "planning")).map((m) => m.id);
+}
+/**
+* What to ask for when a turn ends without its header line: the header itself when an action is in progress, or
+* an action first when the queue is empty but the reply talks about an open mainline, since the header only names
+* the session's own action in progress. Null when there is nothing to ask for.
+*/
+function missingHeaderRequest(root, { payload, cli }) {
+	if (!payload.session_id || payload.stop_hook_active) return null;
+	const message = payload.last_assistant_message ?? "";
+	if (endsWithMarker(message)) return null;
+	const session = readSession(root, claudeCodeSessionId(payload.session_id));
+	const header = headerLine(session);
+	if (header) return `[mainflow] 這一輪最後一則回覆的最後一行不是標頭。請只回一則內容為「${header}」的訊息，不加其他文字。`;
+	if (session && session.actions.length > 0) return null;
+	const mainlines = openMainlinesIn(root, message);
+	if (mainlines.length === 0) return null;
+	return `[mainflow] 這一輪的回覆提到 ${mainlines.join("、")}，但這場會話沒有行動，所以回覆結尾沒有標頭。這一輪若在推進它，先用 ${cli} action add "<做法>" --serves <m/t#c> 列出行動並用 ${cli} action set <a編號> --status doing 標為進行中，或用 ${cli} session handoff <會話> 接手上一場沒做完的行動；再只回一則內容為「▸ <m/t> · <a編號>」的訊息，不加其他文字。只是提到、沒有推進時，不必處理。`;
+}
 /**
-* Stop: settle the session, then ask for the header line when a session with an action in progress ended its
-* turn without one. Only the model knows which message closes a turn, so the header is its to write; this makes
-* a forgotten one cost a single extra message. stop_hook_active stops it from asking twice in a row.
+* Stop: ask for what the turn's header needs, then settle the session. Only the model knows which message closes a
+* turn, so the header is its to write; this makes a forgotten one cost a single extra message. stop_hook_active
+* stops it from asking twice in a row. A session asked to list an action is not settled yet: settling removes a
+* session with no actions, and the action it is asked to add needs the session to exist.
 */
 const settleAndCheckMarker = (root, context) => {
-	settleOnEnd(root, context);
-	const { payload } = context;
-	if (!payload.session_id || payload.stop_hook_active || endsWithMarker(payload.last_assistant_message ?? "")) return null;
-	const header = headerLine(readSession(root, claudeCodeSessionId(payload.session_id)));
-	if (!header) return null;
-	return JSON.stringify({ hookSpecificOutput: {
+	const request = missingHeaderRequest(root, context);
+	const session = context.payload.session_id ? readSession(root, claudeCodeSessionId(context.payload.session_id)) : null;
+	if (!request || session && session.actions.length > 0) settleOnEnd(root, context);
+	return request ? JSON.stringify({ hookSpecificOutput: {
 		hookEventName: "Stop",
-		additionalContext: `[mainflow] 這一輪最後一則回覆的最後一行不是標頭。請只回一則內容為「${header}」的訊息，不加其他文字。`
-	} });
+		additionalContext: request
+	} }) : null;
 };
 const CLAUDE_CODE_EVENTS = {
 	"session-start": (root, { payload, envFile, cli, startUi }) => {