mainflow 0.21.0 → 0.22.0

package/dist/cli.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
-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-BsLqiI0_.js";
-import { F as parseRef, I as refExample } from "./dist-BrotcvKi.js";
+import { $ as reopenIssue, A as addAction, C as setCriterionText, D as updateTask, E as supersedeDecision, F as setSessionArchived, J as appendOps, L as setSessionStatus, M as handoffSession, O as sessionBriefing, P as readSession, Q as planIssue, S as setCriterion, V as updateAction, X as createFinding, Y as closeIssue, Z as createIssue, _ as createTask, b as setArchived, et as setFindingArchived, f as acceptDecision, ft as WriteError, g as createMainline, gt as findHubRoot, h as createDecision, it as loadHub, l as migrateHub, lt as MAINLINE_FILE, m as addRepo, nt as setIssueArchived, p as addHub, rt as HubError, tt as setFindingStatus, ut as TASK_FILE, v as dropChecklistItem, w as setMainlineStatus, x as setChecklistItem, y as initHub, z as startSession } from "./host-0_zkFbzM.js";
+import { F as parseRef, I as refExample } from "./dist-DCYzrl7J.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-CBXoFsFC.js";
+import { hookFallback, parsePayload, runHook } from "./hooks.js";
+import { l as CLI_VERSION, r as launchUi, s as startUiInBackground } from "./launch-B8-NVG2g.js";
 import { readFileSync, realpathSync } from "node:fs";
 import { join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -85,16 +85,24 @@ const RUNS = {
 		}).status})`);
 	},
 	hook: ({ args }) => {
-		let payload = {};
+		let input = "";
 		try {
-			payload = JSON.parse(readFileSync(0, "utf8") || "{}");
-		} catch {
-			console.error("mainflow hook: stdin is not JSON; nothing to do");
+			input = readFileSync(0, "utf8");
+		} catch {}
+		const payload = parsePayload(input);
+		if (!payload) {
+			console.error("mainflow hook: stdin is not a JSON object; nothing to do");
+			const fallback = hookFallback(args[0], args[1], {
+				payload: {},
+				cli: CLI
+			}, { kind: "unreadable-input" });
+			if (fallback) console.log(fallback);
 			return 0;
 		}
 		const { stdout, error } = runHook(args[0], args[1], {
 			payload,
 			envFile: process.env.CLAUDE_ENV_FILE,
+			projectDir: process.env.CLAUDE_PROJECT_DIR,
 			cli: CLI,
 			startUi: startUiInBackground
 		});

package/dist/{dist-BrotcvKi.js → dist-DCYzrl7J.js}

@@ -1,4 +1,349 @@
 import { z } from "zod";
+//#region ../schema/dist/grants.js
+/** What a mainline can authorize ahead of time. */
+const GRANT_ACTIONS = [
+	"commit",
+	"push",
+	"merge-pr",
+	"publish",
+	"release",
+	"install-prompts",
+	"sync-hubs"
+];
+/** How each action's target is written, for error messages and the framework facts. */
+const GRANT_TARGET_FORMS = {
+	commit: {
+		form: "{repo}[:{branch}]",
+		example: "mainflow:main"
+	},
+	push: {
+		form: "{repo}[:{branch}]",
+		example: "mainflow:main"
+	},
+	"merge-pr": {
+		form: "{repo}[:{branch}]",
+		example: "mainflow:main"
+	},
+	publish: {
+		form: "{package}@{semver range}",
+		example: "mainflow@0.21.x"
+	},
+	release: {
+		form: "{repo}@{tag pattern}",
+		example: "mainflow@v0.21.*"
+	},
+	"install-prompts": {
+		form: "{unit}",
+		example: "user"
+	},
+	"sync-hubs": {
+		form: "{hub} or *",
+		example: "carlos-space"
+	}
+};
+const KEBAB = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** A git branch name, `*` standing for any run of characters. */
+const BRANCH = /^(?!\/)(?!.*\/\/)(?!.*\.\.)[A-Za-z0-9._/*-]+(?<!\/)$/;
+/** npm package names: lowercase, optionally scoped. */
+const PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/;
+/** A tag pattern: no whitespace, `*` and `?` as in a shell glob. */
+const TAG_PATTERN = /^[^\s~^:\\[]+$/;
+const fail = (action, why) => ({
+	ok: false,
+	message: `${why}; a ${action} target is written ${GRANT_TARGET_FORMS[action].form}, e.g. ${GRANT_TARGET_FORMS[action].example}`
+});
+/** Split a target by its action's form, or say what is wrong with it. */
+function parseGrantTarget(action, target) {
+	switch (action) {
+		case "commit":
+		case "push":
+		case "merge-pr": {
+			const colon = target.indexOf(":");
+			const repo = colon < 0 ? target : target.slice(0, colon);
+			const branch = colon < 0 ? void 0 : target.slice(colon + 1);
+			if (!repo) return fail(action, "the repo name is missing");
+			if (branch !== void 0 && !BRANCH.test(branch)) return fail(action, `"${branch}" is not a branch name`);
+			return {
+				ok: true,
+				target: {
+					action,
+					repo,
+					...branch !== void 0 ? { branch } : {}
+				}
+			};
+		}
+		case "publish": {
+			const at = target.lastIndexOf("@");
+			if (at <= 0) return fail(action, "the version range is missing");
+			const name = target.slice(0, at);
+			const range = target.slice(at + 1);
+			if (!range.trim()) return fail(action, "the version range is missing");
+			if (!PACKAGE_NAME.test(name)) return fail(action, `"${name}" is not an npm package name`);
+			if (!parseRange(range)) return fail(action, `"${range}" is not a semver range this CLI reads (exact, x-range, ^, ~, comparators, ||)`);
+			return {
+				ok: true,
+				target: {
+					action,
+					name,
+					range
+				}
+			};
+		}
+		case "release": {
+			const at = target.indexOf("@");
+			if (at <= 0) return fail(action, "the tag pattern is missing");
+			const repo = target.slice(0, at);
+			const tag = target.slice(at + 1);
+			if (!TAG_PATTERN.test(tag)) return fail(action, `"${tag}" is not a tag pattern`);
+			return {
+				ok: true,
+				target: {
+					action,
+					repo,
+					tag
+				}
+			};
+		}
+		case "install-prompts": return KEBAB.test(target) ? {
+			ok: true,
+			target: {
+				action,
+				unit: target
+			}
+		} : fail(action, `"${target}" is not a unit name`);
+		case "sync-hubs": return target === "*" || KEBAB.test(target) ? {
+			ok: true,
+			target: {
+				action,
+				hub: target
+			}
+		} : fail(action, `"${target}" is not a hub name`);
+	}
+}
+/** The repository a target names, for the actions that name one. */
+const grantRepo = (target) => "repo" in target ? target.repo : void 0;
+/** Whether a grant's target covers the request. Only the actions a hook can resolve have requests. */
+function grantCovers(target, request) {
+	if (target.action !== request.action) return false;
+	if (target.action === "publish" && request.action === "publish") return target.name === request.name && satisfies(request.version, target.range);
+	if (target.action === "release" && request.action === "release") return request.repos.includes(target.repo) && globMatch(target.tag, request.tag);
+	return false;
+}
+/**
+* The one way each hook-enforced action may be written for a grant to allow it; the hook asks for any other
+* writing, since what a free-form shell call publishes cannot be predicted reliably.
+*/
+const GRANT_FORMS = {
+	publish: "在套件目錄單獨執行 `pnpm publish --ignore-scripts` 或 `npm publish --ignore-scripts`（可加 --access public|restricted、--tag <名稱>、--dry-run、--provenance，pnpm 另可加 --no-git-checks）",
+	release: "單獨執行 `gh release create <tag> -R <owner/repo>`（可加 --title、--notes、--generate-notes、--draft、--prerelease、--verify-tag）"
+};
+/** The fixed form a grant allows, filled in with its target; undefined for actions the hook does not allow. */
+function grantForm(target) {
+	if (target.action === "publish") return `在 ${target.name} 的套件目錄單獨執行 \`pnpm publish --ignore-scripts\` 或 \`npm publish --ignore-scripts\``;
+	if (target.action === "release") return `單獨執行 \`gh release create <符合 ${target.tag} 的 tag> -R <${target.repo} 的 GitHub owner/repo>\``;
+}
+/** How much of a request a reason or an ops entry names. */
+const DESCRIBED = 200;
+/** One line naming a request, for reasons and the ops log. */
+function describeRequest(request) {
+	const text = request.action === "publish" ? `publish ${request.name}@${request.version}` : `release ${request.repos.join("/") || "(unknown repo)"}@${request.tag}`;
+	return text.length > DESCRIBED ? `${text.slice(0, DESCRIBED)}…` : text;
+}
+/** Whether `text` matches a pattern where `*` is any run of characters and `?` one character, neither crossing `/`. */
+function globMatch(pattern, text) {
+	const source = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]");
+	return new RegExp(`^${source}$`).test(text);
+}
+const VERSION = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+const PARTIAL = /^v?(\d+|[xX*])(?:\.(\d+|[xX*]))?(?:\.(\d+|[xX*]))?(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+const preParts = (pre) => pre ? pre.split(".").map((p) => /^\d+$/.test(p) ? Number(p) : p) : [];
+function parseVersion(text) {
+	const m = VERSION.exec(text.trim());
+	return m ? {
+		major: Number(m[1]),
+		minor: Number(m[2]),
+		patch: Number(m[3]),
+		pre: preParts(m[4])
+	} : null;
+}
+function compareVersions(a, b) {
+	for (const key of [
+		"major",
+		"minor",
+		"patch"
+	]) if (a[key] !== b[key]) return a[key] - b[key];
+	if (a.pre.length === 0 || b.pre.length === 0) return (a.pre.length === 0 ? 1 : 0) - (b.pre.length === 0 ? 1 : 0);
+	for (let i = 0; i < Math.max(a.pre.length, b.pre.length); i++) {
+		const x = a.pre[i];
+		const y = b.pre[i];
+		if (x === void 0) return -1;
+		if (y === void 0) return 1;
+		if (x === y) continue;
+		if (typeof x === "number" && typeof y === "number") return x - y;
+		if (typeof x === "number") return -1;
+		if (typeof y === "number") return 1;
+		return x < y ? -1 : 1;
+	}
+	return 0;
+}
+const v = (major, minor, patch, pre = []) => ({
+	major,
+	minor,
+	patch,
+	pre
+});
+/** The lowest version above every release of the given line, e.g. 2.0.0-0 above 1.x. */
+const floor = (major, minor, patch) => v(major, minor, patch, [0]);
+function parsePartial(text) {
+	if (text === "" || text === "*" || text === "x" || text === "X") return { pre: [] };
+	const m = PARTIAL.exec(text);
+	if (!m) return null;
+	const num = (s) => s === void 0 || /^[xX*]$/.test(s) ? void 0 : Number(s);
+	const major = num(m[1]);
+	const minor = major === void 0 ? void 0 : num(m[2]);
+	const patch = minor === void 0 ? void 0 : num(m[3]);
+	if (m[4] && patch === void 0) return null;
+	return {
+		major,
+		minor,
+		patch,
+		pre: preParts(m[4])
+	};
+}
+/** The comparators one range item stands for, or null when it cannot be read. */
+function comparators(item) {
+	const m = /^(\^|~>?|<=|>=|<|>|=)?\s*(.*)$/.exec(item);
+	const op = m[1] ?? "";
+	const p = parsePartial(m[2]);
+	if (!p) return null;
+	const { major, minor, patch, pre } = p;
+	const low = v(major ?? 0, minor ?? 0, patch ?? 0, pre);
+	switch (op) {
+		case "":
+		case "=":
+			if (major === void 0) return [];
+			if (minor === void 0) return [{
+				op: ">=",
+				version: low
+			}, {
+				op: "<",
+				version: floor(major + 1, 0, 0)
+			}];
+			if (patch === void 0) return [{
+				op: ">=",
+				version: low
+			}, {
+				op: "<",
+				version: floor(major, minor + 1, 0)
+			}];
+			return [{
+				op: "=",
+				version: low
+			}];
+		case "^": {
+			if (major === void 0) return [];
+			const high = major > 0 || minor === void 0 ? floor(major + 1, 0, 0) : minor > 0 || patch === void 0 ? floor(0, minor + 1, 0) : floor(0, 0, patch + 1);
+			return [{
+				op: ">=",
+				version: low
+			}, {
+				op: "<",
+				version: high
+			}];
+		}
+		case "~":
+		case "~>": {
+			if (major === void 0) return [];
+			const high = minor === void 0 ? floor(major + 1, 0, 0) : floor(major, minor + 1, 0);
+			return [{
+				op: ">=",
+				version: low
+			}, {
+				op: "<",
+				version: high
+			}];
+		}
+		case ">=": return major === void 0 ? [] : [{
+			op: ">=",
+			version: low
+		}];
+		case "<": return major === void 0 ? [{
+			op: "<",
+			version: floor(0, 0, 0)
+		}] : [{
+			op: "<",
+			version: patch === void 0 ? floor(major, minor ?? 0, 0) : low
+		}];
+		case ">":
+			if (major === void 0) return [{
+				op: "<",
+				version: floor(0, 0, 0)
+			}];
+			if (minor === void 0) return [{
+				op: ">=",
+				version: v(major + 1, 0, 0)
+			}];
+			if (patch === void 0) return [{
+				op: ">=",
+				version: v(major, minor + 1, 0)
+			}];
+			return [{
+				op: ">",
+				version: low
+			}];
+		case "<=":
+			if (major === void 0) return [];
+			if (minor === void 0) return [{
+				op: "<",
+				version: floor(major + 1, 0, 0)
+			}];
+			if (patch === void 0) return [{
+				op: "<",
+				version: floor(major, minor + 1, 0)
+			}];
+			return [{
+				op: "<=",
+				version: low
+			}];
+	}
+	return null;
+}
+/** A range as alternatives of comparator sets, or null when any part of it cannot be read. */
+function parseRange(range) {
+	const alternatives = range.trim().split(/\s*\|\|\s*/);
+	const sets = [];
+	for (const alt of alternatives) {
+		if (alt.trim() === "") return null;
+		if (/\s-\s/.test(alt)) return null;
+		const items = alt.trim().replace(/(\^|~>?|<=|>=|<|>|=)\s+/g, "$1").split(/\s+/).filter(Boolean);
+		const set = [];
+		for (const item of items) {
+			const parsed = comparators(item);
+			if (!parsed) return null;
+			set.push(...parsed);
+		}
+		sets.push(set);
+	}
+	return sets;
+}
+const holds = (c, version) => {
+	const d = compareVersions(version, c.version);
+	return c.op === "=" ? d === 0 : c.op === "<" ? d < 0 : c.op === "<=" ? d <= 0 : c.op === ">" ? d > 0 : d >= 0;
+};
+/** The upper bounds this file adds for x-ranges, caret and tilde; they name no prerelease of their own. */
+const isFloor = (c) => c.op === "<" && c.version.pre.length === 1 && c.version.pre[0] === 0;
+/** Whether `version` satisfies `range`; false when either cannot be read. */
+function satisfies(version, range) {
+	const parsed = parseVersion(version);
+	const sets = parseRange(range);
+	if (!parsed || !sets) return false;
+	return sets.some((set) => {
+		if (!set.every((c) => holds(c, parsed))) return false;
+		if (parsed.pre.length === 0) return true;
+		return set.some((c) => c.version.pre.length > 0 && !isFloor(c) && c.version.major === parsed.major && c.version.minor === parsed.minor && c.version.patch === parsed.patch);
+	});
+}
+//#endregion
 //#region ../schema/dist/index.js
 const FORMAT_VERSION = 2;
 const ID_PATTERNS = {
@@ -9,7 +354,8 @@ const ID_PATTERNS = {
 	decision: /^d\d{3}$/,
 	action: /^a\d{3}$/,
 	issue: /^i\d{3}$/,
-	finding: /^f\d{3}$/
+	finding: /^f\d{3}$/,
+	grant: /^g\d{3}$/
 };
 const CHECKLIST_REF = /^m\d{3}\/t\d{3}#c\d{3}$/;
 const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
@@ -357,6 +703,23 @@ const costSchema = z.object({
 	actual: z.number().nonnegative().optional(),
 	note: text.optional()
 });
+/**
+* One thing the mainline authorizes ahead of time: an action plus the target it covers. It applies only while
+* a session's action in progress serves this mainline and the mainline is still open.
+*/
+const grantSchema = z.object({
+	id: id("grant"),
+	action: z.enum(GRANT_ACTIONS),
+	target: text,
+	note: text.optional()
+}).superRefine((g, ctx) => {
+	const parsed = parseGrantTarget(g.action, g.target);
+	if (!parsed.ok) ctx.addIssue({
+		code: "custom",
+		path: ["target"],
+		message: parsed.message
+	});
+});
 const mainlineSchema = z.object({
 	id: id("mainline"),
 	title: text,
@@ -371,7 +734,8 @@ const mainlineSchema = z.object({
 		amount: z.number().positive(),
 		unit: text
 	}).optional(),
-	costs: z.array(costSchema).optional()
+	costs: z.array(costSchema).optional(),
+	grants: z.array(grantSchema).optional()
 });
 const decisionSchema = z.object({
 	id: id("decision"),
@@ -537,4 +901,4 @@ function parseOpsLine(line) {
 	return parsed.success ? parsed.data : null;
 }
 //#endregion
-export { formatOpsEntry as A, waitingForRef as B, SURVEY_SECTION as C, configSchema as D, WORK_STATUS as E, parseRef as F, refExample as I, refMainline as L, mainlineSchema as M, opsEntrySchema as N, decisionSchema as O, parseOpsLine as P, sessionSchema as R, SURVEY_LINES as S, TASK_SECTIONS 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, issueSchema as j, findingSchema 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, TASK_REQUIRED_SECTIONS as w, SLUG as x, RESERVED_HUB_NAMES as y, taskSchema as z };
+export { formatOpsEntry as A, waitingForRef as B, SURVEY_SECTION as C, configSchema as D, WORK_STATUS as E, parseRef as F, grantCovers as G, GRANT_FORMS as H, refExample as I, parseGrantTarget as J, grantForm as K, refMainline as L, mainlineSchema as M, opsEntrySchema as N, decisionSchema as O, parseOpsLine as P, sessionSchema as R, SURVEY_LINES as S, TASK_SECTIONS as T, GRANT_TARGET_FORMS as U, GRANT_ACTIONS as V, describeRequest as W, 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, issueSchema as j, findingSchema as k, FORMAT_VERSION as l, MAINLINE_SECTIONS as m, CLOSED_STATUS as n, DEFAULT_CATEGORIES as o, LINK_RELS as p, grantRepo as q, DECIDERS as r, FINDING_SECTIONS as s, CHECKLIST_REF as t, ID_PATTERNS as u, REF_EXAMPLES as v, TASK_REQUIRED_SECTIONS as w, SLUG as x, RESERVED_HUB_NAMES as y, taskSchema as z };

package/dist/facts.d.ts

@@ -1,28 +1,4 @@
-import { z } from "zod";
-//#region ../schema/dist/index.d.ts
-export declare const FORMAT_VERSION = 2;
-export declare const ID_PATTERNS: {
-  readonly mainline: RegExp;
-  readonly task: RegExp;
-  readonly checklistItem: RegExp;
-  readonly criterion: RegExp;
-  readonly decision: RegExp;
-  readonly action: RegExp;
-  readonly issue: RegExp;
-  readonly finding: RegExp;
-};
-export declare const CHECKLIST_REF: RegExp;
-export declare const SLUG: RegExp;
-/** One source the survey checks: the line's label, what it holds, and how it may be left unchecked. */
-interface SurveyLine {
-  label: string;
-  holds: string;
-  /** The word that marks the source as not checked, followed by the reason, e.g. 不適用：{理由}. Absent when the source is always checked. */
-  skip?: string;
-  /** Text a checked line must contain, e.g. the environment a spike ran in. */
-  requires?: string;
-}
-//#endregion
+import { a as SurveyLine, i as SLUG, n as FORMAT_VERSION, r as ID_PATTERNS, t as CHECKLIST_REF } from "./index-CV30LkNZ.js";
 //#region src/facts.d.ts
 export interface CommandSpec {
   usage: string;
@@ -500,6 +476,24 @@ export declare const REFERENCES: readonly [{
 export declare const LINKS: {
   readonly rels: readonly ["depends-on", "relates", "split-from"];
 };
+/**
+ * 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.
+ */
+export declare const GRANTS: {
+  readonly actions: readonly ["commit", "push", "merge-pr", "publish", "release", "install-prompts", "sync-hubs"];
+  readonly targets: Record<"commit" | "install-prompts" | "merge-pr" | "publish" | "push" | "release" | "sync-hubs", {
+    form: string;
+    example: string;
+  }>;
+  readonly enforcedByHook: readonly ['publish', 'release'];
+  readonly forms: {
+    readonly publish: '在套件目錄單獨執行 `pnpm publish --ignore-scripts` 或 `npm publish --ignore-scripts`（可加 --access public|restricted、--tag <名稱>、--dry-run、--provenance，pnpm 另可加 --no-git-checks）';
+    readonly release: '單獨執行 `gh release create <tag> -R <owner/repo>`（可加 --title、--notes、--generate-notes、--draft、--prerelease、--verify-tag）';
+  };
+};
 /** Where each kind of entry lives under the hub root. */
 export declare const LAYOUT: {
   readonly config: '.mainflow/config.yaml';
@@ -551,13 +545,15 @@ export interface FieldSpec {
 }
 /** Every front matter field of each document and list entry; facts.test keeps it equal to the schema. */
 export declare const FIELDS: {
-  readonly mainline: readonly [...FieldSpec[], FieldSpec, FieldSpec, FieldSpec, FieldSpec, FieldSpec];
+  readonly mainline: readonly [...FieldSpec[], FieldSpec, FieldSpec, FieldSpec, FieldSpec, FieldSpec, FieldSpec];
   readonly task: readonly [...FieldSpec[], FieldSpec, FieldSpec, FieldSpec, FieldSpec, FieldSpec, FieldSpec, FieldSpec, FieldSpec, FieldSpec, FieldSpec, FieldSpec, FieldSpec];
   readonly decision: readonly [...FieldSpec[], FieldSpec, FieldSpec, FieldSpec, FieldSpec, FieldSpec];
   readonly issue: readonly [...FieldSpec[], FieldSpec, FieldSpec, FieldSpec, FieldSpec];
   readonly finding: readonly [...FieldSpec[], FieldSpec, FieldSpec, FieldSpec];
   readonly criterion: FieldSpec[];
   readonly checklistItem: readonly [...FieldSpec[], FieldSpec];
+  readonly grant: readonly [FieldSpec, FieldSpec, FieldSpec, FieldSpec];
   readonly link: readonly [FieldSpec, FieldSpec, FieldSpec];
 };
-//#endregion
+//#endregion
+export { CHECKLIST_REF, FORMAT_VERSION, ID_PATTERNS, SLUG };

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_SECTION, E as WORK_STATUS, H as GRANT_FORMS, S as SURVEY_LINES, T as TASK_SECTIONS, U as GRANT_TARGET_FORMS, V as GRANT_ACTIONS, _ 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-DCYzrl7J.js";
 //#region src/facts.ts
 const COMMAND_SPECS = {
 	init: {
@@ -408,6 +408,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 +512,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),
@@ -540,6 +553,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 +566,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