mainflow 0.21.0 → 0.23.0

package/dist/facts.js

@@ -1,4 +1,4 @@
-import { C as SURVEY_SECTION, E as WORK_STATUS, S as SURVEY_LINES, T as TASK_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 TASK_REQUIRED_SECTIONS, x as SLUG } from "./dist-BrotcvKi.js";
+import { C as SURVEY_LINES, D as WORK_STATUS, E as TASK_SECTIONS, H as GRANT_ACTIONS, S as SLUG, T as TASK_REQUIRED_SECTIONS, U as GRANT_FORMS, W as GRANT_TARGET_FORMS, _ as MERGE_STATES, a as DECISION_SECTIONS, c as FINDING_SECTIONS, d as ID_PATTERNS, f as ISSUE_SECTIONS, g as MAINLINE_STATUS, h as MAINLINE_SECTIONS, i as DECISION_BASES, l as FINDING_STATUS, m as LINK_RELS, n as CLOSED_STATUS, o as DECISION_STATUS, p as ISSUE_STATUS, r as DECIDERS, s as DEFAULT_CATEGORIES, t as CHECKLIST_REF, u as FORMAT_VERSION, v as PRIORITIES, w as SURVEY_SECTION, x as SESSION_STATUS } from "./dist-Dy45myuN.js";
 //#region src/facts.ts
 const COMMAND_SPECS = {
 	init: {
@@ -118,7 +118,7 @@ const COMMAND_SPECS = {
 		needsHub: true
 	},
 	"new decision": {
-		usage: "new decision <m> <slug> --title <title> [--status proposed] [--by user|ai|relay] [--affects <m/t or m/t#c>,...]",
+		usage: "new decision <m> <slug> --title <title> [--status proposed] [--by user|ai|relay] [--basis explicit|recommended] [--affects <m/t or m/t#c>,...]",
 		summary: "Create a decision file; proposed while the question is still open",
 		args: 2,
 		needsHub: true
@@ -196,7 +196,7 @@ const COMMAND_SPECS = {
 		needsHub: true
 	},
 	"decision accept": {
-		usage: "decision accept <m/d> [--by user|ai|relay]",
+		usage: "decision accept <m/d> [--by user|ai|relay] [--basis explicit|recommended]",
 		summary: "Settle a proposed decision; the items it affects stop waiting for it",
 		args: 1,
 		needsHub: true
@@ -300,6 +300,7 @@ const OPTIONS = {
 	repo: { type: "string" },
 	evidence: { type: "string" },
 	by: { type: "string" },
+	basis: { type: "string" },
 	port: { type: "string" },
 	"no-open": {
 		type: "boolean",
@@ -356,7 +357,8 @@ const STATUSES = {
 	finding: FINDING_STATUS,
 	session: SESSION_STATUS,
 	merge: MERGE_STATES,
-	decider: DECIDERS
+	decider: DECIDERS,
+	basis: DECISION_BASES
 };
 /** Reference formats, one example each, in the order a reader meets them. */
 const REFERENCES = [
@@ -408,6 +410,18 @@ const REFERENCES = [
 ];
 /** Relation types a document's links take; readers derive the reverse direction. */
 const LINKS = { rels: LINK_RELS };
+/**
+* What a mainline's grants authorize: each action with the form of its target. A grant applies only while the
+* session's action in progress serves the mainline and the mainline is active or planning. The PreToolUse hook
+* allows `publish` and `release` only when the command is written in the fixed form in `forms`; the other
+* actions are for the executor to read.
+*/
+const GRANTS = {
+	actions: GRANT_ACTIONS,
+	targets: GRANT_TARGET_FORMS,
+	enforcedByHook: ["publish", "release"],
+	forms: GRANT_FORMS
+};
 /** Where each kind of entry lives under the hub root. */
 const LAYOUT = {
 	config: ".mainflow/config.yaml",
@@ -500,7 +514,8 @@ const FIELDS = {
 		field("archivedAt", false, "封存的日期，和狀態分開"),
 		field("criteria", true, "解決條件清單，每條的欄位見 criterion"),
 		field("budget", false, "預算的金額與單位"),
-		field("costs", false, "花費清單，每筆有日期、項目、單位，可附預估、實際、備註")
+		field("costs", false, "花費清單，每筆有日期、項目、單位，可附預估、實際、備註"),
+		field("grants", false, "預先授權清單，每條的欄位見 grant；只在會話進行中的行動服務這條主脈絡、且主脈絡是 active 或 planning 時生效")
 	],
 	task: [
 		...shared(...EVERY),
@@ -522,6 +537,7 @@ const FIELDS = {
 		field("decidedAt", false, "裁決的時間，由 CLI 寫入"),
 		field("supersededBy", false, "取代它的決策，superseded 時必填"),
 		field("by", false, "決策者：user、ai、relay"),
+		field("basis", false, "裁決方式：explicit（明確選了某個選項）、recommended（照建議預設，沒有明確選）"),
 		field("affects", false, "影響的任務或 checklist 項目；待裁決時其中的項目在等它"),
 		field("reversible", false, "之後能不能低成本改回來")
 	],
@@ -540,6 +556,12 @@ const FIELDS = {
 	],
 	criterion: LIST_ITEM,
 	checklistItem: [...LIST_ITEM, field("serves", false, "這個項目推進的解決條件，r{NNN} 清單")],
+	grant: [
+		field("id", true, "清單內不重複的編號 g{NNN}"),
+		field("action", true, "授權的動作：commit、push、merge-pr、publish、release、install-prompts、sync-hubs"),
+		field("target", true, "授權的目標，格式依動作而定，見 GRANTS.targets；倉庫名稱需在 config.yaml 登記"),
+		field("note", false, "一句話說明")
+	],
 	link: [
 		field("rel", true, "關係類型：depends-on、relates、split-from，反向由讀者推出"),
 		field("to", true, "對方的參照，不能在同一條主脈絡內；其他 hub 的加 {hub}: 前綴"),
@@ -547,4 +569,4 @@ const FIELDS = {
 	]
 };
 //#endregion
-export { CHECKLIST_REF, CLASSIFICATION, CLOSED_STATUSES, COMMAND_SPECS, FIELDS, FORMAT_VERSION, ID_PATTERNS, LAYOUT, LINKS, OPTIONS, REFERENCES, SECTIONS, SLUG, STATUSES, SURVEY };
+export { CHECKLIST_REF, CLASSIFICATION, CLOSED_STATUSES, COMMAND_SPECS, FIELDS, FORMAT_VERSION, GRANTS, ID_PATTERNS, LAYOUT, LINKS, OPTIONS, REFERENCES, SECTIONS, SLUG, STATUSES, SURVEY };

package/dist/grant-commands.d.ts

@@ -0,0 +1,73 @@
+import "./index-CV30LkNZ.js";
+//#region ../schema/dist/grants.d.ts
+/** An operation about to run, resolved to what a grant is written against. */
+type GrantRequest = {
+  action: 'publish';
+  name: string;
+  version: string;
+} |
+/** `repos` holds every config.yaml name whose checkout points at the repository, usually one */
+{
+  action: 'release';
+  repos: string[];
+  tag: string;
+};
+//#endregion
+//#region src/grant-commands.d.ts
+export declare const quote: (text: string) => string;
+/** A call in one of the fixed forms, not yet checked against the package or the repository. */
+export type Fixed = {
+  action: 'publish';
+  tool: 'npm' | 'pnpm';
+  text: string;
+} | {
+  action: 'release';
+  tag: string;
+  repo: string;
+  text: string;
+};
+/** none: nothing grantable, stay silent. refused: not a fixed form, so ask. fixed: one of the two forms. */
+export type Scan = {
+  kind: 'none';
+} | {
+  kind: 'refused';
+  reason: string;
+} | {
+  kind: 'fixed';
+  call: Fixed;
+};
+/** A git tag a release may create: no path separators, no `..`. */
+export declare const TAG: RegExp;
+/** Whether a Bash call is one this hook decides and, if so, whether it is in a fixed form. */
+export declare function scanCommand(command: string): Scan;
+export interface ResolveContext {
+  /** Directory the call runs in, already checked by scopedCwd */
+  cwd: string;
+  /** Hub root; config.yaml repo paths are relative to it */
+  root: string;
+  /** config.yaml `repos`: name to path */
+  repos: Record<string, string>;
+}
+export type Resolved = {
+  ok: true;
+  request: GrantRequest;
+} | {
+  ok: false;
+  reason: string;
+};
+/**
+ * The payload's cwd after realpath, when it exists and lies in the hub or in a repository config.yaml lists; a
+ * listed repository counts as part of the hub even when it sits outside the hub directory, as ../mainflow does.
+ */
+export declare function scopedCwd(cwd: unknown, root: string, repos: Record<string, string>): {
+  ok: true;
+  dir: string;
+} | {
+  ok: false;
+  reason: string;
+};
+/** The origin remote of a checkout as github.com/owner/repo in lowercase, or null when it is not on github.com. */
+export declare function githubOrigin(dir: string): string | null;
+/** What a fixed-form call would publish or release; refused when the package or repository does not qualify. */
+export declare function resolveFixed(call: Fixed, ctx: ResolveContext): Resolved;
+//#endregion

package/dist/grant-commands.js

@@ -0,0 +1,245 @@
+import { U as GRANT_FORMS } from "./dist-Dy45myuN.js";
+import { closeSync, constants, fstatSync, openSync, readFileSync, realpathSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+//#region src/grant-commands.ts
+/**
+* Text that may hold a grantable command; a call that matches neither is not one this hook decides. It is matched
+* in lowercase with quotes and backslashes removed, because the shell drops those (pn\pm, 'pnpm') and a
+* case-insensitive file system runs NPM as npm.
+*/
+const MENTIONS = {
+	publish: /\b(?:npm|pnpm)\b[\s\S]*\bpublish\b/,
+	release: /\bgh\b[\s\S]*\brelease\b[\s\S]*\b(?:create|new)\b/
+};
+const mentionText = (command) => command.toLowerCase().replace(/[\\'"]/g, "");
+/** How much of a command a reason quotes. */
+const QUOTED = 200;
+const quote = (text) => text.length > QUOTED ? `${text.slice(0, QUOTED)}…` : text;
+var Refused = class extends Error {};
+/** A bare word: no shell syntax at all. */
+const BARE = /^[A-Za-z0-9._/@:=+-]+$/;
+/** A title or notes value in quotes, where the shell expands nothing. */
+const QUOTED_VALUE = /^'[^']*'$|^"[^"\\$`]*"$/;
+/** A git tag a release may create: no path separators, no `..`. */
+const TAG = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const OWNER_REPO = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+/** Split a call into words separated by spaces; only printable ASCII, and quotes only around a whole word. */
+function words(command) {
+	const text = command.trim();
+	if (!/^[\x20-\x7e]*$/.test(text)) throw new Refused("指令含換行、tab 或其他不可見字元");
+	const result = [];
+	let i = 0;
+	while (i < text.length) {
+		if (text[i] === " ") {
+			i++;
+			continue;
+		}
+		const quoteChar = text[i] === "'" || text[i] === "\"" ? text[i] : null;
+		const space = text.indexOf(" ", i);
+		const end = quoteChar ? text.indexOf(quoteChar, i + 1) + 1 : space < 0 ? text.length : space;
+		if (quoteChar && (end === 0 || end < text.length && text[end] !== " ")) throw new Refused("引號要包住一整個值");
+		const word = text.slice(i, end);
+		if (!(quoteChar ? QUOTED_VALUE : BARE).test(word)) throw new Refused(`「${quote(word)}」含 shell 語法`);
+		result.push(word);
+		i = end;
+	}
+	return result;
+}
+/** Take the flags after the command words: `values` take the next word, `flags` stand alone; each at most once. */
+function flagsOf(rest, values, flags) {
+	const found = /* @__PURE__ */ new Map();
+	for (let i = 0; i < rest.length; i++) {
+		const word = rest[i];
+		if (found.has(word)) throw new Refused(`${word} 重複`);
+		if (values.has(word)) {
+			const value = rest[++i];
+			if (value === void 0) throw new Refused(`${word} 沒有值`);
+			found.set(word, value);
+		} else if (flags.has(word)) found.set(word, "");
+		else throw new Refused(`「${quote(word)}」不在固定寫法裡`);
+	}
+	return found;
+}
+/** Values other than --title and --notes are bare words, so they cannot hide a quote. */
+function bareValue(flag, value) {
+	if (value !== void 0 && !BARE.test(value)) throw new Refused(`${flag} 的值不能加引號`);
+	return value;
+}
+function publishForm(list, text) {
+	const [tool, sub, ...rest] = list;
+	if (tool !== "npm" && tool !== "pnpm" || sub !== "publish") throw new Refused("不是單獨一條 npm publish 或 pnpm publish");
+	const flags = flagsOf(rest, /* @__PURE__ */ new Set(["--access", "--tag"]), /* @__PURE__ */ new Set([
+		"--ignore-scripts",
+		"--dry-run",
+		"--provenance",
+		...tool === "pnpm" ? ["--no-git-checks"] : []
+	]));
+	if (!flags.has("--ignore-scripts")) throw new Refused("沒有帶 --ignore-scripts，lifecycle 腳本會執行");
+	const access = bareValue("--access", flags.get("--access"));
+	if (access !== void 0 && access !== "public" && access !== "restricted") throw new Refused("--access 只能是 public 或 restricted");
+	const tag = bareValue("--tag", flags.get("--tag"));
+	if (tag !== void 0 && !TAG.test(tag)) throw new Refused("--tag 不是 dist-tag 名稱");
+	return {
+		action: "publish",
+		tool,
+		text
+	};
+}
+function releaseForm(list, text) {
+	const [tool, sub, verb, tag, ...rest] = list;
+	if (tool !== "gh" || sub !== "release" || verb !== "create") throw new Refused("不是單獨一條 gh release create");
+	if (!tag || !TAG.test(tag) || tag.includes("..")) throw new Refused("tag 只能用英數字、點、底線與連字號，不能含 / 或 ..");
+	const repo = bareValue("-R", flagsOf(rest, /* @__PURE__ */ new Set([
+		"-R",
+		"--title",
+		"--notes"
+	]), /* @__PURE__ */ new Set([
+		"--generate-notes",
+		"--draft",
+		"--prerelease",
+		"--verify-tag"
+	])).get("-R"));
+	if (!repo || !OWNER_REPO.test(repo)) throw new Refused("-R <owner/repo> 必填");
+	return {
+		action: "release",
+		tag,
+		repo,
+		text
+	};
+}
+/** Whether a Bash call is one this hook decides and, if so, whether it is in a fixed form. */
+function scanCommand(command) {
+	const text = mentionText(command);
+	const publish = MENTIONS.publish.test(text);
+	const release = MENTIONS.release.test(text);
+	if (!publish && !release) return { kind: "none" };
+	const forms = [...publish ? [GRANT_FORMS.publish] : [], ...release ? [GRANT_FORMS.release] : []].join("，或");
+	try {
+		const list = words(command);
+		return {
+			kind: "fixed",
+			call: release && (!publish || list[0] === "gh") ? releaseForm(list, command.trim()) : publishForm(list, command.trim())
+		};
+	} catch (error) {
+		if (error instanceof Refused) return {
+			kind: "refused",
+			reason: `授權放行只接受${forms}（這次：${error.message}）`
+		};
+		throw error;
+	}
+}
+const refuse = (form, why) => ({
+	ok: false,
+	reason: `授權放行只接受${GRANT_FORMS[form]}（這次：${why}）`
+});
+const real = (path) => {
+	try {
+		return realpathSync(path);
+	} catch {
+		return null;
+	}
+};
+const within = (path, root) => {
+	const rel = relative(root, path);
+	return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
+};
+/**
+* The payload's cwd after realpath, when it exists and lies in the hub or in a repository config.yaml lists; a
+* listed repository counts as part of the hub even when it sits outside the hub directory, as ../mainflow does.
+*/
+function scopedCwd(cwd, root, repos) {
+	const scope = (why) => ({
+		ok: false,
+		reason: `授權只在 hub 與 config.yaml 登記的倉庫內生效（這次：${why}）`
+	});
+	if (typeof cwd !== "string" || !isAbsolute(cwd)) return scope("payload 的 cwd 不是絕對路徑");
+	const dir = real(cwd);
+	if (!dir) return scope(`目錄 ${quote(cwd)} 不存在`);
+	return [root, ...Object.values(repos).map((path) => resolve(root, path))].flatMap((r) => real(r) ?? []).some((r) => within(dir, r)) ? {
+		ok: true,
+		dir
+	} : scope(`${quote(dir)} 不在 hub 或登記的倉庫內`);
+}
+/** A version as npm publishes it: no v prefix, no spaces, no leading zeros. */
+const SEMVER = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+/** Largest package.json read; a bigger one is not a manifest this hook trusts. */
+const MAX_MANIFEST = 1048576;
+/**
+* Read a file only when it is a regular file of at most MAX_MANIFEST bytes, following symlinks. It is opened
+* without blocking and checked on the open descriptor, so a FIFO or a device such as /dev/zero is refused rather
+* than waited on, and the file checked is the file read.
+*/
+function readManifest(file) {
+	let fd;
+	try {
+		fd = openSync(file, constants.O_RDONLY | constants.O_NONBLOCK);
+	} catch {
+		return null;
+	}
+	try {
+		const stat = fstatSync(fd);
+		return stat.isFile() && stat.size <= MAX_MANIFEST ? readFileSync(fd, "utf8") : null;
+	} catch {
+		return null;
+	} finally {
+		closeSync(fd);
+	}
+}
+/** name and version from package.json in `dir`; a private package, or one that publishes another directory, is refused. */
+function resolvePublish(dir) {
+	const text = readManifest(join(dir, "package.json"));
+	if (text === null) return refuse("publish", `${quote(dir)} 的 package.json 不是 1 MB 以內的一般檔案`);
+	let data;
+	try {
+		data = JSON.parse(text);
+	} catch {
+		return refuse("publish", `${quote(dir)} 的 package.json 不是 JSON`);
+	}
+	if (typeof data !== "object" || data === null) return refuse("publish", "package.json 不是物件");
+	if (typeof data.name !== "string" || typeof data.version !== "string") return refuse("publish", "package.json 沒有 name 或 version");
+	if (!SEMVER.test(data.version)) return refuse("publish", `version ${quote(JSON.stringify(data.version))} 不是標準的 semver`);
+	if (data.version.split("+")[0].split(/[.-]/).filter((part) => /^\d+$/.test(part)).some((part) => !Number.isSafeInteger(Number(part)))) return refuse("publish", `version ${quote(data.version)} 有超過 Number.MAX_SAFE_INTEGER 的數字`);
+	if (data.private) return refuse("publish", `${data.name} 是 private 套件`);
+	if (data.publishConfig?.directory !== void 0) return refuse("publish", "package.json 的 publishConfig.directory 會改發布別的目錄");
+	return {
+		ok: true,
+		request: {
+			action: "publish",
+			name: data.name,
+			version: data.version
+		}
+	};
+}
+/** The origin remote of a checkout as github.com/owner/repo in lowercase, or null when it is not on github.com. */
+function githubOrigin(dir) {
+	const result = spawnSync("git", [
+		"-C",
+		dir,
+		"remote",
+		"get-url",
+		"origin"
+	], { encoding: "utf8" });
+	const url = result.status === 0 ? result.stdout.trim().replace(/\.git$/, "") : "";
+	const match = /^(?:https:\/\/github\.com\/|git@github\.com:|ssh:\/\/git@github\.com\/)([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+)$/.exec(url);
+	return match ? `github.com/${match[1]}`.toLowerCase() : null;
+}
+function resolveRelease(call, ctx) {
+	const slug = `github.com/${call.repo}`.toLowerCase();
+	const repos = Object.entries(ctx.repos).filter(([, path]) => githubOrigin(resolve(ctx.root, path)) === slug).map(([name]) => name);
+	if (repos.length === 0) return refuse("release", `${quote(call.repo)} 不是 config.yaml 裡任何倉庫的 origin`);
+	return {
+		ok: true,
+		request: {
+			action: "release",
+			repos,
+			tag: call.tag
+		}
+	};
+}
+/** What a fixed-form call would publish or release; refused when the package or repository does not qualify. */
+function resolveFixed(call, ctx) {
+	return call.action === "publish" ? resolvePublish(ctx.cwd) : resolveRelease(call, ctx);
+}
+//#endregion
+export { TAG, githubOrigin, quote, resolveFixed, scanCommand, scopedCwd };

package/dist/hooks.d.ts

@@ -15,7 +15,7 @@ export interface ClaudeCodePayload {
   stop_hook_active?: boolean;
   /** MessageDisplay: the lines of an assistant message about to be shown */
   delta?: string;
-  /** PostToolUse: the tool that ran and its input */
+  /** PreToolUse and PostToolUse: the tool about to run or that ran, and its input */
   tool_name?: string;
   tool_input?: {
     file_path?: string;
@@ -32,15 +32,36 @@ export interface HookContext {
   cli: string;
   /** Start the hub's interface without waiting; given by the CLI entry point, left out by callers that must not spawn */
   startUi?: (root: string) => void;
+  /** Report something on stderr without changing what the hook prints; runHook sets it */
+  warn?: (message: string) => void;
+  /** $CLAUDE_PROJECT_DIR: where the session was opened; events in PROJECT_HUB_EVENTS find the hub from it first */
+  projectDir?: string;
 }
+/**
+ * Read a hook's stdin: one JSON object, as Claude Code sends it. Anything else is null, including arrays,
+ * scalars, empty input, and an object with a key written twice, since which value the host acted on is unknown.
+ */
+export declare function parsePayload(text: string): ClaudeCodePayload | null;
 export declare const claudeCodeSessionId: (raw: string) => string;
 type Handler = (root: string, ctx: HookContext) => string | null;
 /** How a hub's interface is linked from a reply: through its /open route, which shows the address in the app. */
 export declare const openLink: (hub: string) => (path: string) => string;
+/** Why an event could not run its handler: outside a hub, the handler threw, or stdin was not JSON. */
+export type HookFailure = {
+  kind: 'outside-hub';
+} | {
+  kind: 'error';
+  message: string;
+} | {
+  kind: 'unreadable-input';
+};
 export declare const HOOK_PLATFORMS: Record<string, Record<string, Handler>>;
+/** What an event prints when it cannot run its handler; null for the events that stay silent. */
+export declare function hookFallback(platform: string, event: string, ctx: HookContext, failure: HookFailure): string | null;
 /**
  * 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.
+ * failure is reported on stderr while the caller still exits 0. Events listed in the fallbacks print their
+ * fallback instead of staying silent.
  */
 export declare function runHook(platform: string, event: string, ctx: HookContext): {
   stdout: string | null;