mainflow 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carlos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+//#region src/cli.d.ts
+export declare function run(argv: string[], cwd: string): number;
+//#endregion

package/dist/cli.js

@@ -0,0 +1,324 @@
+#!/usr/bin/env node
+import { A as createFinding, C as startSession, E as sessionBriefing, F as setFindingStatus, H as TASK_FILE, I as setIssueArchived, L as HubError, M as planIssue, N as reopenIssue, O as appendOps, P as setFindingArchived, R as loadHub, S as setSessionStatus, T as updateAction, V as MAINLINE_FILE, W as WriteError, a as createDecision, b as setSessionArchived, c as dropChecklistItem, d as setChecklistItem, f as setCriterion, g as addAction, h as updateTask, i as addRepo, j as createIssue, k as closeIssue, l as initHub, m as supersedeDecision, n as acceptDecision, o as createMainline, p as setMainlineStatus, q as findHubRoot, r as addHub, s as createTask, t as migrateHub, u as setArchived, y as readSession } from "./dist-BktkzRuK.js";
+import { r as launchUi, s as listProgress } from "./launch-BR70uSMc.js";
+import { COMMAND_SPECS, OPTIONS } from "./facts.js";
+import { runHook } from "./hooks.js";
+import { readFileSync, realpathSync } from "node:fs";
+import { join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+//#region src/cli.ts
+const RUNS = {
+	init: ({ root, args }) => done(`created ${relative(root, initHub(root, args[0]))}`),
+	status: ({ root, opts }) => printStatus(loadHub(root), opts.all ?? false),
+	check: ({ root }) => {
+		const hub = loadHub(root);
+		printProblems(hub.warnings, "!");
+		if (hub.problems.length === 0) return done(`✓ ${hub.mainlines.length} mainlines, no problems${hub.warnings.length ? `, ${hub.warnings.length} ${hub.warnings.length === 1 ? "warning" : "warnings"}` : ""}`);
+		printProblems(hub.problems);
+		return 1;
+	},
+	migrate: ({ root, opts }) => {
+		const dryRun = opts["dry-run"] ?? false;
+		const report = migrateHub(root, { dryRun });
+		console.log(`format ${report.from} → ${report.to}${dryRun ? " (dry run, nothing written)" : ""}`);
+		for (const file of report.written) console.log(`  ${dryRun ? "would write" : "wrote"}   ${file}`);
+		for (const file of report.removed) console.log(`  ${dryRun ? "would remove" : "removed"} ${file}`);
+		if (report.missingDefinitions.length) {
+			console.log(`${report.missingDefinitions.length} open entries still need a definition of done; fill them in the files:`);
+			for (const entry of report.missingDefinitions) console.log(`  ${entry}`);
+		}
+		return 0;
+	},
+	ui: ({ root, opts }) => {
+		const config = loadHub(root).config;
+		launchUi(root, config.hub, config.ui?.port, {
+			port: opts.port,
+			open: !opts["no-open"]
+		}).catch((error) => {
+			console.error(error instanceof WriteError ? `✗ ${error.message}` : error);
+			process.exitCode = 1;
+		});
+		return 0;
+	},
+	"repo add": ({ root, args }) => done(`registered ${addRepo(root, args[0], args[1])} ${args[1]}`),
+	"hub add": ({ root, args }) => done(`registered hub ${addHub(root, args[0], args[1])} ${args[1]}`),
+	"session start": ({ root, opts }) => {
+		const session = startSession(root, {
+			id: opts.id,
+			agent: opts.agent ?? "manual",
+			cwd: process.cwd(),
+			delegatedFrom: opts["delegated-from"],
+			handoffFrom: opts["handoff-from"]
+		});
+		return done(`started ${session.id}${session.actions.length ? ` with ${session.actions.length} carried actions` : ""}`);
+	},
+	"session show": ({ root, args, opts }) => {
+		const id = sessionOf(opts, args[0]);
+		const session = readSession(root, id);
+		if (!session) throw new WriteError(`session ${id} not found; start one with "mainflow session start"`);
+		return done(sessionBriefing(root, session, { cli: CLI }));
+	},
+	"session set": ({ root, args, opts }) => done(`updated ${args[0]} (${setSessionStatus(root, args[0], required(opts, "status", "--status paused")).status})`),
+	"session end": ({ root, args, opts }) => done(`ended ${setSessionStatus(root, sessionOf(opts, args[0]), "ended").id}`),
+	"session archive": ({ root, args }) => done(`archived ${setSessionArchived(root, args[0], true).id}`),
+	"session unarchive": ({ root, args }) => done(`unarchived ${setSessionArchived(root, args[0], false).id}`),
+	"action add": ({ root, args, opts }) => done(`created ${addAction(root, sessionOf(opts), {
+		do: args[0],
+		serves: list(opts.serves),
+		before: opts.before
+	})}`),
+	"action set": ({ root, args, opts }) => {
+		const ref = /^a\d{3}$/.test(args[0]) ? `${sessionOf(opts)}#${args[0]}` : args[0];
+		return done(`updated ${ref} (${updateAction(root, ref, {
+			status: opts.status,
+			do: opts.text,
+			serves: opts.serves === void 0 ? void 0 : list(opts.serves),
+			before: opts.before,
+			note: opts.note
+		}).status})`);
+	},
+	hook: ({ args }) => {
+		let payload = {};
+		try {
+			payload = JSON.parse(readFileSync(0, "utf8") || "{}");
+		} catch {
+			console.error("mainflow hook: stdin is not JSON; nothing to do");
+			return 0;
+		}
+		const { stdout, error } = runHook(args[0], args[1], {
+			payload,
+			envFile: process.env.CLAUDE_ENV_FILE,
+			cli: CLI
+		});
+		if (error) console.error(error);
+		if (stdout) console.log(stdout);
+		return 0;
+	},
+	"new mainline": ({ root, args, opts }) => {
+		const { id, dir } = createMainline(root, {
+			slug: args[0],
+			title: required(opts, "title", "--title \"重建 mainline 任務管理\"")
+		});
+		return done(`created ${id} ${relative(root, join(dir, MAINLINE_FILE))}`);
+	},
+	"new task": ({ root, args, opts }) => {
+		const { ref, dir } = createTask(root, args[0], {
+			slug: args[1],
+			title: required(opts, "title", "--title \"定義資料格式 schema\""),
+			kind: opts.kind,
+			parent: opts.parent,
+			repo: opts.repo
+		});
+		return done(`created ${ref} ${relative(root, join(dir, TASK_FILE))}`);
+	},
+	"new decision": ({ root, args, opts }) => {
+		const { ref, file } = createDecision(root, args[0], {
+			slug: args[1],
+			title: required(opts, "title", "--title \"以文字檔為準\""),
+			status: opts.status,
+			by: opts.by,
+			affects: opts.affects ? list(opts.affects) : void 0
+		});
+		return done(`created ${ref} ${relative(root, file)}`);
+	},
+	"new issue": ({ root, args, opts }) => {
+		const { id, file } = createIssue(root, {
+			slug: args[0],
+			title: required(opts, "title", "--title \"重試不穩定的 VM\""),
+			origin: opts.origin
+		});
+		return done(`created ${id} ${relative(root, file)}`);
+	},
+	"new finding": ({ root, args, opts }) => {
+		const { id, file } = createFinding(root, {
+			slug: args[0],
+			title: required(opts, "title", "--title \"先 await 再寫入 state\""),
+			origin: opts.origin,
+			labels: opts.labels ? list(opts.labels) : void 0
+		});
+		return done(`created ${id} ${relative(root, file)}`);
+	},
+	"mainline set": ({ root, args, opts }) => {
+		const m = setMainlineStatus(root, args[0], required(opts, "status", "--status active"));
+		return done(`updated ${m.id} (${m.status})`);
+	},
+	"mainline archive": ({ root, args }) => done(`archived ${setArchived(root, args[0], true).id}`),
+	"mainline unarchive": ({ root, args }) => done(`unarchived ${setArchived(root, args[0], false).id}`),
+	"criterion check": ({ root, args, opts }) => {
+		setCriterion(root, args[0], true, opts.evidence);
+		return done(`checked ${args[0]}`);
+	},
+	"criterion uncheck": ({ root, args }) => {
+		setCriterion(root, args[0], false);
+		return done(`unchecked ${args[0]}`);
+	},
+	"task set": ({ root, args, opts }) => {
+		const blockedBy = opts.reason ? {
+			reason: opts.reason,
+			...opts["waiting-for"] ? { waitingFor: opts["waiting-for"] } : {},
+			...opts.signal ? { signal: opts.signal } : {}
+		} : void 0;
+		const t = updateTask(root, args[0], {
+			status: opts.status,
+			repo: opts.repo,
+			blockedBy,
+			branch: opts.branch,
+			worktree: opts.worktree,
+			base: opts.base,
+			merge: opts.merge
+		});
+		return done(`updated ${args[0]} (${t.status})`);
+	},
+	"item check": ({ root, args, opts }) => {
+		setChecklistItem(root, args[0], true, opts.evidence);
+		return done(`checked ${args[0]}`);
+	},
+	"item uncheck": ({ root, args }) => {
+		setChecklistItem(root, args[0], false);
+		return done(`unchecked ${args[0]}`);
+	},
+	"decision accept": ({ root, args, opts }) => done(`accepted ${args[0]} (${acceptDecision(root, args[0], opts.by).decidedAt})`),
+	"item drop": ({ root, args, opts }) => {
+		dropChecklistItem(root, args[0], {
+			supersededBy: opts.by,
+			note: opts.note
+		});
+		return done(`dropped ${args[0]}`);
+	},
+	"issue plan": ({ root, args }) => done(`planned ${planIssue(root, args[0], args[1]).id} in ${args[1]}`),
+	"issue close": ({ root, args, opts }) => done(`closed ${closeIssue(root, args[0], opts.by ?? "").id}`),
+	"issue reopen": ({ root, args }) => done(`reopened ${reopenIssue(root, args[0]).id}`),
+	"issue archive": ({ root, args }) => done(`archived ${setIssueArchived(root, args[0], true).id}`),
+	"issue unarchive": ({ root, args }) => done(`unarchived ${setIssueArchived(root, args[0], false).id}`),
+	"issue list": ({ root, opts }) => {
+		const shown = loadHub(root).issues.filter((i) => opts.all || i.status !== "closed");
+		for (const i of shown) console.log(`  ${i.id}  ${i.status.padEnd(7)}  ${i.title}${i.plannedIn ? `  → ${i.plannedIn}` : ""}${i.origin ? `  (from ${i.origin})` : ""}`);
+		return done(`${shown.length} issues`);
+	},
+	"finding set": ({ root, args, opts }) => done(`updated ${setFindingStatus(root, args[0], required(opts, "status", "--status obsolete")).id}`),
+	"finding archive": ({ root, args }) => done(`archived ${setFindingArchived(root, args[0], true).id}`),
+	"finding unarchive": ({ root, args }) => done(`unarchived ${setFindingArchived(root, args[0], false).id}`),
+	"finding list": ({ root, opts }) => {
+		const shown = loadHub(root).findings.filter((f) => opts.all || f.status === "valid");
+		for (const f of shown) console.log(`  ${f.id}  ${f.created}  ${f.title}${f.labels?.length ? `  [${f.labels.join(", ")}]` : ""}`);
+		return done(`${shown.length} findings`);
+	},
+	"ops add": ({ root, opts }) => {
+		const entry = appendOps(root, {
+			target: required(opts, "target", "--target github.com/owner/repo"),
+			operation: required(opts, "op", "--op \"push tag v1.2.0\""),
+			result: required(opts, "result", "--result success"),
+			...opts.ref ? { ref: opts.ref } : {}
+		});
+		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));
+		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}`);
+	}
+};
+const COMMANDS = Object.fromEntries(Object.keys(COMMAND_SPECS).map((name) => [name, {
+	...COMMAND_SPECS[name],
+	run: RUNS[name]
+}]));
+const USAGE = [
+	"Usage: mainflow <command>",
+	"",
+	"Commands:",
+	...Object.values(COMMANDS).map((c) => `  ${c.usage}\n      ${c.summary}`),
+	"",
+	"Options:",
+	"  --version  Print the version",
+	"  --help     Print this message"
+].join("\n");
+function run(argv, cwd) {
+	let parsed;
+	try {
+		parsed = parseArgs({
+			args: argv,
+			allowPositionals: true,
+			options: OPTIONS
+		});
+	} catch (error) {
+		return fail(`${error.message}\n\n${USAGE}`);
+	}
+	const { values: opts, positionals } = parsed;
+	if (opts.version) return done(JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version);
+	if (opts.help || positionals.length === 0) {
+		console.log(USAGE);
+		return opts.help ? 0 : 1;
+	}
+	const pair = positionals.slice(0, 2).join(" ");
+	const key = COMMANDS[pair] ? pair : positionals[0];
+	const command = COMMANDS[key];
+	if (!command) return fail(`Unknown command "${positionals.join(" ")}".\n\n${USAGE}`);
+	const args = positionals.slice(key.split(" ").length);
+	if (args.length < command.args || args.length > command.args + (command.optionalArgs ?? 0)) return fail(`Usage: mainflow ${command.usage}`);
+	let root = cwd;
+	if (command.needsHub) {
+		const found = findHubRoot(cwd);
+		if (!found) return fail("No .mainflow/config.yaml found in this directory or any parent. Run mainflow inside a hub repository.");
+		root = found;
+	}
+	try {
+		return command.run({
+			root,
+			args,
+			opts
+		});
+	} catch (error) {
+		if (error instanceof HubError) {
+			printProblems(error.problems);
+			return fail(error.message);
+		}
+		if (error instanceof WriteError) return fail(`✗ ${error.message}`);
+		throw error;
+	}
+}
+function done(line) {
+	console.log(line);
+	return 0;
+}
+function fail(message) {
+	console.error(message);
+	return 1;
+}
+/** How the executor runs this CLI inside a hub; used in the texts hooks inject. */
+const CLI = "pnpm exec mainflow";
+/** The session a command acts on: an explicit argument, then --session, then MAINFLOW_SESSION set by the SessionStart hook. */
+function sessionOf(opts, arg) {
+	const id = arg ?? opts.session ?? process.env.MAINFLOW_SESSION;
+	if (!id) throw new WriteError("no session given; pass --session <id> or set MAINFLOW_SESSION (the SessionStart hook sets it)");
+	return id;
+}
+const list = (value) => (value ?? "").split(",").map((v) => v.trim()).filter(Boolean);
+function required(opts, name, example) {
+	const value = opts[name];
+	if (!value) throw new WriteError(`--${name} is required, e.g. ${example}`);
+	return value;
+}
+function printStatus(hub, all) {
+	const shown = hub.mainlines.filter((m) => all || !m.archivedAt);
+	console.log(`${hub.config.hub}: ${shown.length} mainlines${all ? "" : " (archived hidden)"}`);
+	for (const m of shown) {
+		const items = listProgress(m.tasks.flatMap((t) => t.checklist));
+		const archived = m.archivedAt ? "  [archived]" : "";
+		console.log(`  ${m.id}  ${m.status.padEnd(8)}  ${items.done}/${items.total}  ${m.title}${archived}`);
+	}
+	if (hub.problems.length === 0) return 0;
+	console.error(`${hub.problems.length} problems found; run "mainflow check" for details`);
+	return 1;
+}
+function printProblems(problems, mark = "✗") {
+	for (const problem of problems) console.error(`${mark} ${problem.file}${problem.field ? ` › ${problem.field}` : ""}: ${problem.message}`);
+}
+const entry = process.argv[1];
+if (entry && realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url))) process.exitCode = run(process.argv.slice(2), process.cwd());
+//#endregion
+export { run };