mainflow 0.6.0

package/dist/facts.js

@@ -0,0 +1,516 @@
+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";
+//#region src/facts.ts
+const COMMAND_SPECS = {
+	init: {
+		usage: "init <hub-name>",
+		summary: "Create .mainflow/ in the current directory",
+		args: 1,
+		needsHub: false
+	},
+	status: {
+		usage: "status [--all]",
+		summary: "List mainlines with checklist progress",
+		args: 0,
+		needsHub: true
+	},
+	check: {
+		usage: "check",
+		summary: "Validate every file under .mainflow/",
+		args: 0,
+		needsHub: true
+	},
+	migrate: {
+		usage: "migrate [--dry-run]",
+		summary: "Convert the hub to the data format this CLI reads; --dry-run lists the changes without writing",
+		args: 0,
+		needsHub: true
+	},
+	ui: {
+		usage: "ui [--port <port>] [--no-open]",
+		summary: "Open the web interface at {hub}.mainflow.localhost, starting it on a free port if it is not running",
+		args: 0,
+		needsHub: true
+	},
+	"repo add": {
+		usage: "repo add <name> <path>",
+		summary: "Register a repository that tasks can point at (path relative to the hub root)",
+		args: 2,
+		needsHub: true
+	},
+	"hub add": {
+		usage: "hub add <name> <path>",
+		summary: "Register another hub that references may point into as {name}:m001 (path relative to the hub root)",
+		args: 2,
+		needsHub: true
+	},
+	"session start": {
+		usage: "session start [--agent <agent>] [--id <id>] [--delegated-from <session>] [--handoff-from <session>]",
+		summary: "Start a session; --handoff-from carries over its unfinished actions",
+		args: 0,
+		needsHub: true
+	},
+	"session show": {
+		usage: "session show [session]",
+		summary: "Print the briefing a hook would give this session",
+		args: 0,
+		optionalArgs: 1,
+		needsHub: true
+	},
+	"session set": {
+		usage: "session set <session> --status <status>",
+		summary: "Change session status",
+		args: 1,
+		needsHub: true
+	},
+	"session end": {
+		usage: "session end [session]",
+		summary: "Mark a session as ended",
+		args: 0,
+		optionalArgs: 1,
+		needsHub: true
+	},
+	"session archive": {
+		usage: "session archive <session>",
+		summary: "Hide a session from default views; the status stays as it is",
+		args: 1,
+		needsHub: true
+	},
+	"session unarchive": {
+		usage: "session unarchive <session>",
+		summary: "Show an archived session again",
+		args: 1,
+		needsHub: true
+	},
+	"action add": {
+		usage: "action add <text> --serves <m/t#c>[,<m/t#c>] [--before <a>] [--session <session>]",
+		summary: "Add an action to the session queue",
+		args: 1,
+		needsHub: true
+	},
+	"action set": {
+		usage: "action set <a|session#a> [--status] [--text] [--serves] [--before <a>] [--note <text>] [--session <session>]",
+		summary: "Change, reorder or finish an action",
+		args: 1,
+		needsHub: true
+	},
+	hook: {
+		usage: "hook <platform> <event>",
+		summary: "Handle a host hook event read from stdin, e.g. hook claude-code session-start",
+		args: 2,
+		needsHub: false
+	},
+	"new mainline": {
+		usage: "new mainline <slug> --title <title>",
+		summary: "Create mainline.md with the next id and the section template; write the rest in the file",
+		args: 1,
+		needsHub: true
+	},
+	"new task": {
+		usage: "new task <m> <slug> --title <title> [--kind phase|branch] [--parent <t>] [--repo <name>]",
+		summary: "Create task.md with the next id and the section template; write the rest in the file",
+		args: 2,
+		needsHub: true
+	},
+	"new decision": {
+		usage: "new decision <m> <slug> --title <title> [--status proposed] [--by user|ai|relay] [--affects <m/t or m/t#c>,...]",
+		summary: "Create a decision file; proposed while the question is still open",
+		args: 2,
+		needsHub: true
+	},
+	"new issue": {
+		usage: "new issue <slug> --title <title> [--origin <ref>]",
+		summary: "Create an issue file for a follow-up that must outlive its mainline",
+		args: 1,
+		needsHub: true
+	},
+	"new finding": {
+		usage: "new finding <slug> --title <title> [--origin <ref>] [--labels a,b]",
+		summary: "Create a finding file for a lesson the next task should read",
+		args: 1,
+		needsHub: true
+	},
+	"mainline set": {
+		usage: "mainline set <m> --status <status>",
+		summary: "Change status; done needs every criterion met and no proposed decision",
+		args: 1,
+		needsHub: true
+	},
+	"mainline archive": {
+		usage: "mainline archive <m>",
+		summary: "Hide a mainline from default lists",
+		args: 1,
+		needsHub: true
+	},
+	"mainline unarchive": {
+		usage: "mainline unarchive <m>",
+		summary: "Show an archived mainline again",
+		args: 1,
+		needsHub: true
+	},
+	"criterion check": {
+		usage: "criterion check <m#r> --evidence <evidence>",
+		summary: "Mark a criterion as met",
+		args: 1,
+		needsHub: true
+	},
+	"criterion uncheck": {
+		usage: "criterion uncheck <m#r>",
+		summary: "Mark a criterion as not met",
+		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
+	},
+	"item check": {
+		usage: "item check <m/t#c> --evidence <evidence>",
+		summary: "Check an item with evidence",
+		args: 1,
+		needsHub: true
+	},
+	"item uncheck": {
+		usage: "item uncheck <m/t#c>",
+		summary: "Uncheck an item",
+		args: 1,
+		needsHub: true
+	},
+	"decision accept": {
+		usage: "decision accept <m/d> [--by user|ai|relay]",
+		summary: "Settle a proposed decision; the items it affects stop waiting for it",
+		args: 1,
+		needsHub: true
+	},
+	"item drop": {
+		usage: "item drop <m/t#c> [--by <ref>] [--note <text>]",
+		summary: "Mark an item as no longer needed, naming what replaced it",
+		args: 1,
+		needsHub: true
+	},
+	"issue plan": {
+		usage: "issue plan <i> <m/t>",
+		summary: "Schedule an issue into the task that will carry it out",
+		args: 2,
+		needsHub: true
+	},
+	"issue close": {
+		usage: "issue close <i> --by <what closed it>",
+		summary: "Close an issue",
+		args: 1,
+		needsHub: true
+	},
+	"issue reopen": {
+		usage: "issue reopen <i>",
+		summary: "Reopen an issue",
+		args: 1,
+		needsHub: true
+	},
+	"issue archive": {
+		usage: "issue archive <i>",
+		summary: "Hide an issue from default views; the status stays as it is",
+		args: 1,
+		needsHub: true
+	},
+	"issue unarchive": {
+		usage: "issue unarchive <i>",
+		summary: "Show an archived issue again",
+		args: 1,
+		needsHub: true
+	},
+	"issue list": {
+		usage: "issue list [--all]",
+		summary: "List open and planned issues (--all includes closed)",
+		args: 0,
+		needsHub: true
+	},
+	"finding set": {
+		usage: "finding set <f> --status valid|obsolete",
+		summary: "Mark a finding obsolete or valid again",
+		args: 1,
+		needsHub: true
+	},
+	"finding archive": {
+		usage: "finding archive <f>",
+		summary: "Hide a finding from default views; the status stays as it is",
+		args: 1,
+		needsHub: true
+	},
+	"finding unarchive": {
+		usage: "finding unarchive <f>",
+		summary: "Show an archived finding again",
+		args: 1,
+		needsHub: true
+	},
+	"finding list": {
+		usage: "finding list [--all]",
+		summary: "List valid findings (--all includes obsolete)",
+		args: 0,
+		needsHub: true
+	},
+	"ops add": {
+		usage: "ops add --target <system> --op <operation> --result <result> [--ref <ref>]",
+		summary: "Append an external operation to the audit log",
+		args: 0,
+		needsHub: true
+	},
+	"ops list": {
+		usage: "ops list [--month YYYY-MM]",
+		summary: "List logged external operations",
+		args: 0,
+		needsHub: true
+	},
+	"decision supersede": {
+		usage: "decision supersede <m/d> --by <d>",
+		summary: "Mark a decision as replaced by another",
+		args: 1,
+		needsHub: true
+	}
+};
+const OPTIONS = {
+	title: { type: "string" },
+	status: { type: "string" },
+	kind: { type: "string" },
+	parent: { type: "string" },
+	repo: { type: "string" },
+	evidence: { type: "string" },
+	by: { type: "string" },
+	port: { type: "string" },
+	"no-open": {
+		type: "boolean",
+		default: false
+	},
+	session: { type: "string" },
+	agent: { type: "string" },
+	id: { type: "string" },
+	"delegated-from": { type: "string" },
+	"handoff-from": { type: "string" },
+	text: { type: "string" },
+	serves: { type: "string" },
+	before: { type: "string" },
+	note: { type: "string" },
+	reason: { type: "string" },
+	"waiting-for": { type: "string" },
+	signal: { type: "string" },
+	branch: { type: "string" },
+	worktree: { type: "string" },
+	base: { type: "string" },
+	merge: { type: "string" },
+	affects: { type: "string" },
+	origin: { type: "string" },
+	labels: { type: "string" },
+	target: { type: "string" },
+	op: { type: "string" },
+	result: { type: "string" },
+	ref: { type: "string" },
+	month: { type: "string" },
+	all: {
+		type: "boolean",
+		default: false
+	},
+	"dry-run": {
+		type: "boolean",
+		default: false
+	},
+	version: {
+		type: "boolean",
+		default: false
+	},
+	help: {
+		type: "boolean",
+		default: false
+	}
+};
+const STATUSES = {
+	mainline: MAINLINE_STATUS,
+	task: WORK_STATUS,
+	action: WORK_STATUS,
+	decision: DECISION_STATUS,
+	issue: ISSUE_STATUS,
+	finding: FINDING_STATUS,
+	session: SESSION_STATUS,
+	merge: MERGE_STATES,
+	decider: DECIDERS
+};
+/** Reference formats, one example each, in the order a reader meets them. */
+const REFERENCES = [
+	{
+		target: "mainline",
+		format: "m{NNN}",
+		example: "m001"
+	},
+	{
+		target: "task",
+		format: "m{NNN}/t{NNN}",
+		example: "m001/t002"
+	},
+	{
+		target: "checklist item",
+		format: "m{NNN}/t{NNN}#c{NNN}",
+		example: "m001/t002#c003"
+	},
+	{
+		target: "criterion",
+		format: "m{NNN}#r{NNN}",
+		example: "m001#r001"
+	},
+	{
+		target: "decision",
+		format: "m{NNN}/d{NNN}",
+		example: "m001/d001"
+	},
+	{
+		target: "issue",
+		format: "i{NNN}",
+		example: "i001"
+	},
+	{
+		target: "finding",
+		format: "f{NNN}",
+		example: "f001"
+	},
+	{
+		target: "another hub",
+		format: "{hub}:{reference}",
+		example: "other-hub:m001/t002"
+	},
+	{
+		target: "action",
+		format: "{sessionId}#a{NNN}",
+		example: "claude-code-1a2b3c4d#a003"
+	}
+];
+/** Relation types a document's links take; readers derive the reverse direction. */
+const LINKS = { rels: LINK_RELS };
+/** Where each kind of entry lives under the hub root. */
+const LAYOUT = {
+	config: ".mainflow/config.yaml",
+	mainline: ".mainflow/mainlines/m{NNN}-{slug}/mainline.md",
+	decision: ".mainflow/mainlines/m{NNN}-{slug}/decisions/d{NNN}-{slug}.md",
+	task: ".mainflow/mainlines/m{NNN}-{slug}/tasks/t{NNN}-{slug}/task.md",
+	issue: ".mainflow/issues/i{NNN}-{slug}.md",
+	finding: ".mainflow/findings/f{NNN}-{slug}.md",
+	ops: ".mainflow/ops/{YYYY-MM}.log",
+	sessions: ".mainflow/local/sessions/{sessionId}.yaml"
+};
+/** Statuses that close each kind of document; the CLI stamps closedAt when a document enters one. */
+const CLOSED_STATUSES = CLOSED_STATUS;
+/** Classification every document shares: one category from the list (a hub adds more in config.yaml), P0 to P3. */
+const CLASSIFICATION = {
+	categories: DEFAULT_CATEGORIES,
+	priorities: PRIORITIES,
+	defaultPriority: "P2"
+};
+/** Body sections each document is created with; the task sections in `taskRequired` must be filled while it is open. */
+const SECTIONS = {
+	mainline: MAINLINE_SECTIONS,
+	task: TASK_SECTIONS,
+	taskRequired: TASK_REQUIRED_SECTIONS,
+	decision: DECISION_SECTIONS,
+	issue: ISSUE_SECTIONS,
+	finding: FINDING_SECTIONS
+};
+const field = (name, required, description) => ({
+	name,
+	required,
+	description
+});
+/** Fields every document shares, described once and reused by each kind below. */
+const COMMON = {
+	id: field("id", true, "由 new 指令配發的編號，與目錄或檔名前綴一致"),
+	title: field("title", true, "一句話說明這份文件是什麼"),
+	status: field("status", true, "狀態值見 STATUSES，只用狀態轉移指令改"),
+	priority: field("priority", false, "P0 至 P3，沒填視為 P2"),
+	category: field("category", false, "預設類別或 config.yaml 追加的類別，擇一"),
+	labels: field("labels", false, "自由分類，字串清單"),
+	created: field("created", true, "建立的日期，決策帶時分"),
+	closedAt: field("closedAt", false, "狀態轉為結束時由 CLI 寫入"),
+	resolution: field("resolution", false, "怎麼結束的，一句話"),
+	origin: field("origin", false, "從哪個主脈絡、任務、項目、決策、待辦或發現產生，可指向其他 hub"),
+	refs: field("refs", false, "參考來源清單，每筆 title 加 url 或 path，可附讀取日期 date"),
+	links: field("links", false, "和其他主脈絡或其他 hub 的關係清單，每筆的欄位見 link；同一條主脈絡內用 parent、dependsOn、affects")
+};
+const shared = (...names) => names.map((name) => COMMON[name]);
+const EVERY = [
+	"id",
+	"title",
+	"status",
+	"priority",
+	"category",
+	"labels",
+	"created",
+	"closedAt",
+	"resolution",
+	"origin",
+	"refs",
+	"links"
+];
+/** Criteria and checklist items share these; items add serves. */
+const LIST_ITEM = [
+	field("id", true, "清單內不重複的編號，解決條件為 r{NNN}，checklist 項目為 c{NNN}；直接改檔時自己寫下一個"),
+	field("text", true, "要做到的事，一句話"),
+	field("doneWhen", false, "怎樣才算完成；還沒結束的條目必填，check 會檢查"),
+	field("done", true, "是否已完成，用 check 指令改"),
+	field("evidence", false, "完成的證據，done 為 true 時必填"),
+	field("doneAt", false, "完成的日期，由 CLI 寫入"),
+	field("dropped", false, "不再需要時為 true，用 item drop 標記"),
+	field("supersededBy", false, "被哪個參照取代"),
+	field("note", false, "一句備註，例如放棄的原因")
+];
+/** Every front matter field of each document and list entry; facts.test keeps it equal to the schema. */
+const FIELDS = {
+	mainline: [
+		...shared(...EVERY),
+		field("due", false, "預計完成的日期"),
+		field("archivedAt", false, "封存的日期，和狀態分開"),
+		field("criteria", true, "解決條件清單，每條的欄位見 criterion"),
+		field("budget", false, "預算的金額與單位"),
+		field("costs", false, "花費清單，每筆有日期、項目、單位，可附預估、實際、備註")
+	],
+	task: [
+		...shared(...EVERY),
+		field("kind", true, "phase 是依序推進的階段，branch 是從某個任務岔出的分支"),
+		field("parent", false, "上層任務，branch 必填"),
+		field("order", false, "在主脈絡內的順序，小的在前"),
+		field("dependsOn", false, "開始前必須先完成的任務"),
+		field("repo", false, "主要動到的倉庫，名稱需在 config.yaml 登記"),
+		field("startedAt", false, "第一次轉為 doing 時由 CLI 寫入"),
+		field("checklist", true, "checklist 項目清單，每項的欄位見 checklistItem"),
+		field("blockedBy", false, "卡住時的原因、等待對象與繼續的訊號，blocked 時必填"),
+		field("branch", false, "工作所在的分支"),
+		field("worktree", false, "worktree 的路徑"),
+		field("base", false, "分支基於哪個 commit"),
+		field("merge", false, "合併狀態：open、merged、abandoned")
+	],
+	decision: [
+		...shared(...EVERY),
+		field("decidedAt", false, "裁決的時間，由 CLI 寫入"),
+		field("supersededBy", false, "取代它的決策，superseded 時必填"),
+		field("by", false, "決策者：user、ai、relay"),
+		field("affects", false, "影響的任務或 checklist 項目；待裁決時其中的項目在等它"),
+		field("reversible", false, "之後能不能低成本改回來")
+	],
+	issue: [
+		...shared(...EVERY),
+		field("order", false, "待辦之間的順序"),
+		field("due", false, "預計完成的日期"),
+		field("plannedIn", false, "排進的任務，planned 時必填"),
+		field("archivedAt", false, "封存的日期，和狀態分開")
+	],
+	finding: [
+		...shared("id", "title", "status", "category", "labels", "created", "closedAt", "resolution", "origin", "refs", "links"),
+		field("appliesTo", false, "這個經驗適用的倉庫或路徑"),
+		field("reviewAfter", false, "到這天要重新確認它還成立"),
+		field("archivedAt", false, "封存的日期，和狀態分開")
+	],
+	criterion: LIST_ITEM,
+	checklistItem: [...LIST_ITEM, field("serves", false, "這個項目推進的解決條件，r{NNN} 清單")],
+	link: [
+		field("rel", true, "關係類型：depends-on、relates、split-from，反向由讀者推出"),
+		field("to", true, "對方的參照，不能在同一條主脈絡內；其他 hub 的加 {hub}: 前綴"),
+		field("note", false, "一句話說明這個關係")
+	]
+};
+//#endregion
+export { CHECKLIST_REF, CLASSIFICATION, CLOSED_STATUSES, COMMAND_SPECS, FIELDS, FORMAT_VERSION, ID_PATTERNS, LAYOUT, LINKS, OPTIONS, REFERENCES, SECTIONS, SLUG, STATUSES };

package/dist/hooks.d.ts

@@ -0,0 +1,41 @@
+//#region src/hooks.d.ts
+/** Fields Claude Code sends on stdin to every command hook, plus the ones specific to the events handled here. */
+export interface ClaudeCodePayload {
+  session_id?: string;
+  transcript_path?: string;
+  cwd?: string;
+  source?: string;
+  agent_id?: string;
+  agent_type?: string;
+  last_assistant_message?: string;
+  effort?: {
+    level?: string;
+  };
+  /** PostToolUse: the tool that ran and its input */
+  tool_name?: string;
+  tool_input?: {
+    file_path?: string;
+    command?: string;
+  };
+}
+/** The parent transcript `<dir>/<session>.jsonl` keeps its subagents under `<dir>/<session>/subagents/`. */
+export declare function subagentTranscript(parentTranscript: string, agentId: string): string;
+export interface HookContext {
+  payload: ClaudeCodePayload;
+  /** Path from $CLAUDE_ENV_FILE; SessionStart writes MAINFLOW_SESSION there so later Bash calls see it */
+  envFile?: string;
+  /** How the executor should invoke the CLI inside the hub, used in the texts it reads */
+  cli: string;
+}
+export declare const claudeCodeSessionId: (raw: string) => string;
+type Handler = (root: string, ctx: HookContext) => string | null;
+export declare const HOOK_PLATFORMS: Record<string, Record<string, Handler>>;
+/**
+ * Run a hook handler. A hook must never break the host session, so outside a hub it stays silent and any
+ * failure is reported on stderr while the caller still exits 0.
+ */
+export declare function runHook(platform: string, event: string, ctx: HookContext): {
+  stdout: string | null;
+  error: string | null;
+};
+//#endregion