mainflow 0.6.0

package/dist/dist-D2NK-QQP.js

@@ -0,0 +1,511 @@
+import { z } from "zod";
+//#region ../schema/dist/index.js
+const FORMAT_VERSION = 2;
+const ID_PATTERNS = {
+	mainline: /^m\d{3}$/,
+	task: /^t\d{3}$/,
+	checklistItem: /^c\d{3}$/,
+	criterion: /^r\d{3}$/,
+	decision: /^d\d{3}$/,
+	action: /^a\d{3}$/,
+	issue: /^i\d{3}$/,
+	finding: /^f\d{3}$/
+};
+const CHECKLIST_REF = /^m\d{3}\/t\d{3}#c\d{3}$/;
+const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+const DATETIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}$/;
+/** A hub name: kebab-case, also the first label of {hub}.mainflow.localhost and the prefix of a cross-hub reference. */
+const HUB_NAME = SLUG;
+/** Prefixes the web interface already uses in its own references, so no registered hub may take them. */
+const RESERVED_HUB_NAMES = ["file", "session"];
+const REF_FORMS = [
+	{
+		kind: "mainline",
+		pattern: /^(m\d{3})$/,
+		example: "m001"
+	},
+	{
+		kind: "task",
+		pattern: /^(m\d{3})\/(t\d{3})$/,
+		example: "m001/t002"
+	},
+	{
+		kind: "checklistItem",
+		pattern: /^(m\d{3})\/(t\d{3})#(c\d{3})$/,
+		example: "m001/t002#c003"
+	},
+	{
+		kind: "criterion",
+		pattern: /^(m\d{3})#(r\d{3})$/,
+		example: "m001#r001"
+	},
+	{
+		kind: "decision",
+		pattern: /^(m\d{3})\/(d\d{3})$/,
+		example: "m001/d001"
+	},
+	{
+		kind: "issue",
+		pattern: /^(i\d{3})$/,
+		example: "i001"
+	},
+	{
+		kind: "finding",
+		pattern: /^(f\d{3})$/,
+		example: "f001"
+	}
+];
+/** The forms a reference can take, for error messages. */
+const REF_EXAMPLES = `${REF_FORMS.map((f) => f.example).join(", ")}, or any of them after another hub's name, like other-hub:m001`;
+/** Split a `{hub}:` prefix off a reference; `hub` is undefined when there is none. */
+function splitHub(input) {
+	const colon = input.indexOf(":");
+	if (colon < 0) return { local: input };
+	const hub = input.slice(0, colon);
+	return HUB_NAME.test(hub) ? {
+		hub,
+		local: input.slice(colon + 1)
+	} : {
+		hub: "",
+		local: input
+	};
+}
+/** Parse a reference string, or return null when it matches none of the forms. */
+function parseRef(input) {
+	const { hub, local } = splitHub(input);
+	if (hub === "") return null;
+	const parsed = parseLocal(local);
+	return parsed && hub !== void 0 ? {
+		...parsed,
+		hub
+	} : parsed;
+}
+function parseLocal(input) {
+	for (const form of REF_FORMS) {
+		const m = form.pattern.exec(input);
+		if (!m) continue;
+		const [, a = "", b = "", c = ""] = m;
+		switch (form.kind) {
+			case "mainline": return {
+				kind: "mainline",
+				mainline: a
+			};
+			case "task": return {
+				kind: "task",
+				mainline: a,
+				task: b
+			};
+			case "checklistItem": return {
+				kind: "checklistItem",
+				mainline: a,
+				task: b,
+				item: c
+			};
+			case "criterion": return {
+				kind: "criterion",
+				mainline: a,
+				criterion: b
+			};
+			case "decision": return {
+				kind: "decision",
+				mainline: a,
+				decision: b
+			};
+			case "issue": return {
+				kind: "issue",
+				issue: a
+			};
+			case "finding": return {
+				kind: "finding",
+				finding: a
+			};
+		}
+	}
+	return null;
+}
+/** 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. */
+const refExample = (kind) => REF_FORMS.find((f) => f.kind === kind)?.example ?? "";
+const id = (kind) => z.string().regex(ID_PATTERNS[kind]);
+const date = z.string().regex(DATE);
+const datetime = z.string().regex(DATETIME);
+/** A day, or a day with the time when the moment matters (who decided what, and when). */
+const dateOrTime = z.string().regex(/^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2})?$/);
+const text = z.string().min(1);
+/** Any reference parseRef understands, in this hub or, with a `{hub}:` prefix, in another one. */
+const anyRef = z.string().refine((s) => parseRef(s) !== null, `expected a reference like ${REF_EXAMPLES}`);
+const MAINLINE_STATUS = [
+	"planning",
+	"active",
+	"paused",
+	"done",
+	"dropped"
+];
+const WORK_STATUS = [
+	"todo",
+	"doing",
+	"blocked",
+	"done",
+	"dropped"
+];
+const DECISION_STATUS = [
+	"proposed",
+	"accepted",
+	"superseded"
+];
+const DECIDERS = [
+	"user",
+	"ai",
+	"relay"
+];
+const MERGE_STATES = [
+	"open",
+	"merged",
+	"abandoned"
+];
+const ISSUE_STATUS = [
+	"open",
+	"planned",
+	"closed"
+];
+const FINDING_STATUS = ["valid", "obsolete"];
+const SESSION_STATUS = [
+	"active",
+	"paused",
+	"ended",
+	"handed-off"
+];
+/** Statuses after which an entity is closed and carries closedAt. */
+const CLOSED_STATUS = {
+	mainline: ["done", "dropped"],
+	task: ["done", "dropped"],
+	decision: ["superseded"],
+	issue: ["closed"],
+	finding: ["obsolete"]
+};
+/** Default categories, aligned with Conventional Commits types; a hub adds its own in config.yaml. */
+const DEFAULT_CATEGORIES = [
+	"feature",
+	"fix",
+	"refactor",
+	"docs",
+	"research",
+	"ops",
+	"chore"
+];
+/** P0 blocks other work, P1 must land this round, P2 should be done (the default), P3 when there is time. */
+const PRIORITIES = [
+	"P0",
+	"P1",
+	"P2",
+	"P3"
+];
+const MAINLINE_SECTIONS = [
+	"概述",
+	"背景與前置",
+	"範圍與不做",
+	"限制"
+];
+const TASK_SECTIONS = [
+	"目標",
+	"背景",
+	"做法",
+	"完成定義",
+	"不做",
+	"紀錄",
+	"接手須知"
+];
+/** Task sections that must not stay empty while the task is open. */
+const TASK_REQUIRED_SECTIONS = ["目標", "完成定義"];
+const DECISION_SECTIONS = [
+	"背景",
+	"選項",
+	"建議",
+	"決定",
+	"理由"
+];
+const ISSUE_SECTIONS = [
+	"背景",
+	"要做的事",
+	"完成條件"
+];
+const FINDING_SECTIONS = [
+	"發現",
+	"影響",
+	"做法"
+];
+const configSchema = z.object({
+	/** Also the first label of the hub's host name, {hub}.mainflow.localhost, so kebab-case */
+	hub: z.string().regex(HUB_NAME, "hub name must be kebab-case, e.g. carlos-space"),
+	formatVersion: z.number().int().positive(),
+	repos: z.record(z.string(), z.string()),
+	/** Other hubs this hub's references point into: hub name to its root, relative to this hub's root */
+	hubs: z.record(z.string().regex(HUB_NAME, "a hub name must be kebab-case").refine((n) => !RESERVED_HUB_NAMES.includes(n), `${RESERVED_HUB_NAMES.join(" and ")} are reserved`), z.string()).optional(),
+	/** Categories this hub uses on top of DEFAULT_CATEGORIES */
+	categories: z.array(z.string().regex(SLUG, "a category must be kebab-case")).optional(),
+	/** The port `mainflow ui` tries first for this hub; when it is taken, the next free one is used and the host name follows */
+	ui: z.object({ port: z.number().int().min(1024).max(65535) }).optional()
+});
+const refSchema = z.object({
+	title: text,
+	url: z.string().url().optional(),
+	path: text.optional(),
+	date: date.optional()
+}).refine((r) => r.url || r.path, "a reference needs a url or a path");
+/**
+* How a document relates to something outside its own mainline. Only one direction is written: the
+* reverse (what depends on this, what was split from this) is derived by readers, so a relation never
+* has two copies that can disagree.
+*/
+const LINK_RELS = [
+	"depends-on",
+	"relates",
+	"split-from"
+];
+const linkSchema = z.object({
+	rel: z.enum(LINK_RELS),
+	to: anyRef,
+	note: text.optional()
+});
+/**
+* Attributes every document carries (mainline, task, decision, issue, finding) besides id, title, status
+* and priority, which each schema lists first so the front matter reads the same way in every file. `category` is checked
+* against DEFAULT_CATEGORIES plus config.categories when the hub loads, not here, because the schema does
+* not see the config. `updated` is not stored: readers derive it from the file.
+*/
+const documentShape = {
+	category: z.string().regex(SLUG, "a category must be kebab-case").optional(),
+	labels: z.array(text).optional(),
+	created: dateOrTime,
+	closedAt: dateOrTime.optional(),
+	resolution: text.optional(),
+	origin: anyRef.optional(),
+	refs: z.array(refSchema).optional(),
+	/** Relations to documents outside this document's mainline, in this hub or another */
+	links: z.array(linkSchema).optional()
+};
+const priority = z.enum(PRIORITIES).optional();
+const evidenceRequired = (item, ctx) => {
+	if (item.done && !item.evidence) ctx.addIssue({
+		code: "custom",
+		path: ["evidence"],
+		message: "evidence is required once the item is checked"
+	});
+};
+const checkedOrDropped = (item, ctx) => {
+	if (item.done && item.dropped) ctx.addIssue({
+		code: "custom",
+		path: ["dropped"],
+		message: "an item is either checked or dropped, not both"
+	});
+};
+/** Resolution criteria and checklist items have the same shape; items also name the criteria they serve. */
+const listItemShape = {
+	text,
+	/** What has to be true to check it; required while the item is still open */
+	doneWhen: text.optional(),
+	done: z.boolean(),
+	evidence: text.nullable().optional(),
+	doneAt: date.nullable().optional(),
+	/** No longer needed; supersededBy names what replaced it, when something did */
+	dropped: z.boolean().optional(),
+	supersededBy: anyRef.optional(),
+	note: text.optional()
+};
+const criterionSchema = z.object({
+	id: id("criterion"),
+	...listItemShape
+}).superRefine(evidenceRequired).superRefine(checkedOrDropped);
+const checklistItemSchema = z.object({
+	id: id("checklistItem"),
+	...listItemShape,
+	serves: z.array(id("criterion")).optional()
+}).superRefine(evidenceRequired).superRefine(checkedOrDropped);
+const costSchema = z.object({
+	date,
+	item: text,
+	unit: text,
+	estimate: z.number().nonnegative().optional(),
+	actual: z.number().nonnegative().optional(),
+	note: text.optional()
+});
+const mainlineSchema = z.object({
+	id: id("mainline"),
+	title: text,
+	status: z.enum(MAINLINE_STATUS),
+	priority,
+	...documentShape,
+	due: date.optional(),
+	/** Hidden from the default listings; independent of status, a done mainline may stay visible */
+	archivedAt: date.optional(),
+	criteria: z.array(criterionSchema),
+	budget: z.object({
+		amount: z.number().positive(),
+		unit: text
+	}).optional(),
+	costs: z.array(costSchema).optional()
+});
+const decisionSchema = z.object({
+	id: id("decision"),
+	title: text,
+	status: z.enum(DECISION_STATUS),
+	priority,
+	...documentShape,
+	decidedAt: dateOrTime.optional(),
+	supersededBy: id("decision").optional(),
+	by: z.enum(DECIDERS).optional(),
+	/** Tasks and items the decision shapes; while it is proposed, the checklist items among them wait for it */
+	affects: z.array(anyRef).optional(),
+	/** Whether the choice can be undone cheaply later */
+	reversible: z.boolean().optional()
+}).superRefine((d, ctx) => {
+	if (d.status === "superseded" && !d.supersededBy) ctx.addIssue({
+		code: "custom",
+		path: ["supersededBy"],
+		message: "a superseded decision must point to its successor"
+	});
+});
+const taskSchema = z.object({
+	id: id("task"),
+	title: text,
+	status: z.enum(WORK_STATUS),
+	priority,
+	...documentShape,
+	kind: z.enum(["phase", "branch"]),
+	parent: id("task").nullable().optional(),
+	/** Position among the mainline's tasks; lower first */
+	order: z.number().int().positive().optional(),
+	/** Tasks that must be done before this one starts */
+	dependsOn: z.array(id("task")).optional(),
+	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 */
+	blockedBy: z.object({
+		reason: text,
+		waitingFor: text.optional(),
+		signal: text.optional()
+	}).optional(),
+	branch: text.optional(),
+	worktree: text.optional(),
+	base: text.optional(),
+	merge: z.enum(MERGE_STATES).optional()
+}).superRefine((t, ctx) => {
+	if (t.kind === "branch" && !t.parent) ctx.addIssue({
+		code: "custom",
+		path: ["parent"],
+		message: "a branch task must name the task it branches from"
+	});
+	if (t.status === "blocked" && !t.blockedBy) ctx.addIssue({
+		code: "custom",
+		path: ["blockedBy"],
+		message: "a blocked task must say what blocks it"
+	});
+	if (t.dependsOn?.includes(t.id)) ctx.addIssue({
+		code: "custom",
+		path: ["dependsOn"],
+		message: "a task cannot depend on itself"
+	});
+});
+const actionSchema = z.object({
+	id: id("action"),
+	do: z.string().min(1),
+	status: z.enum(WORK_STATUS),
+	serves: z.array(z.string().regex(CHECKLIST_REF)),
+	note: text.optional(),
+	/** Set when the action turns doing and done; the transcript trace attributes tool use by these */
+	startedAt: datetime.optional(),
+	doneAt: datetime.optional()
+});
+const sessionSchema = z.object({
+	id: z.string().min(1),
+	agent: z.string().min(1),
+	status: z.enum(SESSION_STATUS),
+	started: datetime,
+	delegatedFrom: z.string().min(1).nullable(),
+	handoffFrom: z.string().min(1).nullable(),
+	cwd: z.string().min(1),
+	actions: z.array(actionSchema),
+	/** Where the platform keeps the conversation, for tracing and for opening it */
+	transcript: text.optional(),
+	worktree: text.optional(),
+	branch: text.optional(),
+	model: text.optional(),
+	effort: text.optional(),
+	/** Subagents: what the delegating session asked for, nesting depth, and the final reply in brief */
+	description: text.optional(),
+	depth: z.number().int().nonnegative().optional(),
+	summary: text.optional(),
+	/** Hidden from the default views; independent of status, an ended session stays visible until archived */
+	archivedAt: date.optional()
+});
+/** Front matter of issues/i{NNN}-{slug}.md: follow-ups and waits that must survive the mainline that found them. */
+const issueSchema = z.object({
+	id: id("issue"),
+	title: text,
+	status: z.enum(ISSUE_STATUS),
+	priority,
+	...documentShape,
+	order: z.number().int().positive().optional(),
+	due: date.optional(),
+	plannedIn: z.string().regex(/^m\d{3}\/t\d{3}$/).optional(),
+	/** Hidden from the default views; independent of status, a closed issue stays visible until archived */
+	archivedAt: date.optional()
+}).superRefine((i, ctx) => {
+	if (i.status === "planned" && !i.plannedIn) ctx.addIssue({
+		code: "custom",
+		path: ["plannedIn"],
+		message: "a planned issue must name the task it is planned in"
+	});
+	if (i.status === "closed" && !i.resolution) ctx.addIssue({
+		code: "custom",
+		path: ["resolution"],
+		message: "a closed issue must say what closed it"
+	});
+});
+/** Front matter of findings/f{NNN}-{slug}.md: lessons and pitfalls the next task should read before it starts. */
+const findingSchema = z.object({
+	id: id("finding"),
+	title: text,
+	status: z.enum(FINDING_STATUS),
+	...documentShape,
+	/** Repositories or paths the lesson applies to, so a task working there can find it */
+	appliesTo: z.array(text).optional(),
+	/** When to check whether the lesson still holds */
+	reviewAfter: date.optional(),
+	/** Hidden from the default views; independent of status, an obsolete finding stays visible until archived */
+	archivedAt: date.optional()
+});
+/** One line of ops/{YYYY-MM}.log: an external operation, append-only. */
+const opsEntrySchema = z.object({
+	at: datetime,
+	target: text,
+	operation: text,
+	result: text,
+	ref: anyRef.optional()
+});
+const OPS_SEPARATOR = " | ";
+function formatOpsEntry(entry) {
+	return [
+		entry.at,
+		entry.target,
+		entry.operation,
+		entry.result,
+		...entry.ref ? [entry.ref] : []
+	].join(OPS_SEPARATOR);
+}
+function parseOpsLine(line) {
+	const [at, target, operation, result, ref] = line.split(OPS_SEPARATOR).map((part) => part.trim());
+	const parsed = opsEntrySchema.safeParse({
+		at,
+		target,
+		operation,
+		result,
+		...ref ? { ref } : {}
+	});
+	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 };