mainflow 0.6.0

package/dist/facts.d.ts

@@ -0,0 +1,518 @@
+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;
+//#endregion
+//#region src/facts.d.ts
+export interface CommandSpec {
+  usage: string;
+  summary: string;
+  /** Number of positional arguments after the command words */
+  args: number;
+  /** Extra positional arguments the command also accepts */
+  optionalArgs?: number;
+  needsHub: boolean;
+}
+export declare const COMMAND_SPECS: {
+  readonly init: {
+    readonly usage: 'init <hub-name>';
+    readonly summary: 'Create .mainflow/ in the current directory';
+    readonly args: 1;
+    readonly needsHub: false;
+  };
+  readonly status: {
+    readonly usage: 'status [--all]';
+    readonly summary: 'List mainlines with checklist progress';
+    readonly args: 0;
+    readonly needsHub: true;
+  };
+  readonly check: {
+    readonly usage: 'check';
+    readonly summary: 'Validate every file under .mainflow/';
+    readonly args: 0;
+    readonly needsHub: true;
+  };
+  readonly migrate: {
+    readonly usage: 'migrate [--dry-run]';
+    readonly summary: 'Convert the hub to the data format this CLI reads; --dry-run lists the changes without writing';
+    readonly args: 0;
+    readonly needsHub: true;
+  };
+  readonly ui: {
+    readonly usage: 'ui [--port <port>] [--no-open]';
+    readonly summary: 'Open the web interface at {hub}.mainflow.localhost, starting it on a free port if it is not running';
+    readonly args: 0;
+    readonly needsHub: true;
+  };
+  readonly 'repo add': {
+    readonly usage: 'repo add <name> <path>';
+    readonly summary: 'Register a repository that tasks can point at (path relative to the hub root)';
+    readonly args: 2;
+    readonly needsHub: true;
+  };
+  readonly 'hub add': {
+    readonly usage: 'hub add <name> <path>';
+    readonly summary: 'Register another hub that references may point into as {name}:m001 (path relative to the hub root)';
+    readonly args: 2;
+    readonly needsHub: true;
+  };
+  readonly 'session start': {
+    readonly usage: 'session start [--agent <agent>] [--id <id>] [--delegated-from <session>] [--handoff-from <session>]';
+    readonly summary: 'Start a session; --handoff-from carries over its unfinished actions';
+    readonly args: 0;
+    readonly needsHub: true;
+  };
+  readonly 'session show': {
+    readonly usage: 'session show [session]';
+    readonly summary: 'Print the briefing a hook would give this session';
+    readonly args: 0;
+    readonly optionalArgs: 1;
+    readonly needsHub: true;
+  };
+  readonly 'session set': {
+    readonly usage: 'session set <session> --status <status>';
+    readonly summary: 'Change session status';
+    readonly args: 1;
+    readonly needsHub: true;
+  };
+  readonly 'session end': {
+    readonly usage: 'session end [session]';
+    readonly summary: 'Mark a session as ended';
+    readonly args: 0;
+    readonly optionalArgs: 1;
+    readonly needsHub: true;
+  };
+  readonly 'session archive': {
+    readonly usage: 'session archive <session>';
+    readonly summary: 'Hide a session from default views; the status stays as it is';
+    readonly args: 1;
+    readonly needsHub: true;
+  };
+  readonly 'session unarchive': {
+    readonly usage: 'session unarchive <session>';
+    readonly summary: 'Show an archived session again';
+    readonly args: 1;
+    readonly needsHub: true;
+  };
+  readonly 'action add': {
+    readonly usage: 'action add <text> --serves <m/t#c>[,<m/t#c>] [--before <a>] [--session <session>]';
+    readonly summary: 'Add an action to the session queue';
+    readonly args: 1;
+    readonly needsHub: true;
+  };
+  readonly 'action set': {
+    readonly usage: 'action set <a|session#a> [--status] [--text] [--serves] [--before <a>] [--note <text>] [--session <session>]';
+    readonly summary: 'Change, reorder or finish an action';
+    readonly args: 1;
+    readonly needsHub: true;
+  };
+  readonly hook: {
+    readonly usage: 'hook <platform> <event>';
+    readonly summary: 'Handle a host hook event read from stdin, e.g. hook claude-code session-start';
+    readonly args: 2;
+    readonly needsHub: false;
+  };
+  readonly 'new mainline': {
+    readonly usage: 'new mainline <slug> --title <title>';
+    readonly summary: 'Create mainline.md with the next id and the section template; write the rest in the file';
+    readonly args: 1;
+    readonly needsHub: true;
+  };
+  readonly 'new task': {
+    readonly usage: 'new task <m> <slug> --title <title> [--kind phase|branch] [--parent <t>] [--repo <name>]';
+    readonly summary: 'Create task.md with the next id and the section template; write the rest in the file';
+    readonly args: 2;
+    readonly needsHub: true;
+  };
+  readonly 'new decision': {
+    readonly usage: 'new decision <m> <slug> --title <title> [--status proposed] [--by user|ai|relay] [--affects <m/t or m/t#c>,...]';
+    readonly summary: 'Create a decision file; proposed while the question is still open';
+    readonly args: 2;
+    readonly needsHub: true;
+  };
+  readonly 'new issue': {
+    readonly usage: 'new issue <slug> --title <title> [--origin <ref>]';
+    readonly summary: 'Create an issue file for a follow-up that must outlive its mainline';
+    readonly args: 1;
+    readonly needsHub: true;
+  };
+  readonly 'new finding': {
+    readonly usage: 'new finding <slug> --title <title> [--origin <ref>] [--labels a,b]';
+    readonly summary: 'Create a finding file for a lesson the next task should read';
+    readonly args: 1;
+    readonly needsHub: true;
+  };
+  readonly 'mainline set': {
+    readonly usage: 'mainline set <m> --status <status>';
+    readonly summary: 'Change status; done needs every criterion met and no proposed decision';
+    readonly args: 1;
+    readonly needsHub: true;
+  };
+  readonly 'mainline archive': {
+    readonly usage: 'mainline archive <m>';
+    readonly summary: 'Hide a mainline from default lists';
+    readonly args: 1;
+    readonly needsHub: true;
+  };
+  readonly 'mainline unarchive': {
+    readonly usage: 'mainline unarchive <m>';
+    readonly summary: 'Show an archived mainline again';
+    readonly args: 1;
+    readonly needsHub: true;
+  };
+  readonly 'criterion check': {
+    readonly usage: 'criterion check <m#r> --evidence <evidence>';
+    readonly summary: 'Mark a criterion as met';
+    readonly args: 1;
+    readonly needsHub: true;
+  };
+  readonly 'criterion uncheck': {
+    readonly usage: 'criterion uncheck <m#r>';
+    readonly summary: 'Mark a criterion as not met';
+    readonly args: 1;
+    readonly needsHub: true;
+  };
+  readonly 'task set': {
+    readonly usage: 'task set <m/t> [--status] [--reason --waiting-for --signal] [--repo] [--branch --worktree --base --merge]';
+    readonly summary: 'Change status, repository or branch state; --status blocked needs --reason';
+    readonly args: 1;
+    readonly needsHub: true;
+  };
+  readonly 'item check': {
+    readonly usage: 'item check <m/t#c> --evidence <evidence>';
+    readonly summary: 'Check an item with evidence';
+    readonly args: 1;
+    readonly needsHub: true;
+  };
+  readonly 'item uncheck': {
+    readonly usage: 'item uncheck <m/t#c>';
+    readonly summary: 'Uncheck an item';
+    readonly args: 1;
+    readonly needsHub: true;
+  };
+  readonly 'decision accept': {
+    readonly usage: 'decision accept <m/d> [--by user|ai|relay]';
+    readonly summary: 'Settle a proposed decision; the items it affects stop waiting for it';
+    readonly args: 1;
+    readonly needsHub: true;
+  };
+  readonly 'item drop': {
+    readonly usage: 'item drop <m/t#c> [--by <ref>] [--note <text>]';
+    readonly summary: 'Mark an item as no longer needed, naming what replaced it';
+    readonly args: 1;
+    readonly needsHub: true;
+  };
+  readonly 'issue plan': {
+    readonly usage: 'issue plan <i> <m/t>';
+    readonly summary: 'Schedule an issue into the task that will carry it out';
+    readonly args: 2;
+    readonly needsHub: true;
+  };
+  readonly 'issue close': {
+    readonly usage: 'issue close <i> --by <what closed it>';
+    readonly summary: 'Close an issue';
+    readonly args: 1;
+    readonly needsHub: true;
+  };
+  readonly 'issue reopen': {
+    readonly usage: 'issue reopen <i>';
+    readonly summary: 'Reopen an issue';
+    readonly args: 1;
+    readonly needsHub: true;
+  };
+  readonly 'issue archive': {
+    readonly usage: 'issue archive <i>';
+    readonly summary: 'Hide an issue from default views; the status stays as it is';
+    readonly args: 1;
+    readonly needsHub: true;
+  };
+  readonly 'issue unarchive': {
+    readonly usage: 'issue unarchive <i>';
+    readonly summary: 'Show an archived issue again';
+    readonly args: 1;
+    readonly needsHub: true;
+  };
+  readonly 'issue list': {
+    readonly usage: 'issue list [--all]';
+    readonly summary: 'List open and planned issues (--all includes closed)';
+    readonly args: 0;
+    readonly needsHub: true;
+  };
+  readonly 'finding set': {
+    readonly usage: 'finding set <f> --status valid|obsolete';
+    readonly summary: 'Mark a finding obsolete or valid again';
+    readonly args: 1;
+    readonly needsHub: true;
+  };
+  readonly 'finding archive': {
+    readonly usage: 'finding archive <f>';
+    readonly summary: 'Hide a finding from default views; the status stays as it is';
+    readonly args: 1;
+    readonly needsHub: true;
+  };
+  readonly 'finding unarchive': {
+    readonly usage: 'finding unarchive <f>';
+    readonly summary: 'Show an archived finding again';
+    readonly args: 1;
+    readonly needsHub: true;
+  };
+  readonly 'finding list': {
+    readonly usage: 'finding list [--all]';
+    readonly summary: 'List valid findings (--all includes obsolete)';
+    readonly args: 0;
+    readonly needsHub: true;
+  };
+  readonly 'ops add': {
+    readonly usage: 'ops add --target <system> --op <operation> --result <result> [--ref <ref>]';
+    readonly summary: 'Append an external operation to the audit log';
+    readonly args: 0;
+    readonly needsHub: true;
+  };
+  readonly 'ops list': {
+    readonly usage: 'ops list [--month YYYY-MM]';
+    readonly summary: 'List logged external operations';
+    readonly args: 0;
+    readonly needsHub: true;
+  };
+  readonly 'decision supersede': {
+    readonly usage: 'decision supersede <m/d> --by <d>';
+    readonly summary: 'Mark a decision as replaced by another';
+    readonly args: 1;
+    readonly needsHub: true;
+  };
+};
+export type CommandName = keyof typeof COMMAND_SPECS;
+export declare const OPTIONS: {
+  readonly title: {
+    readonly type: 'string';
+  };
+  readonly status: {
+    readonly type: 'string';
+  };
+  readonly kind: {
+    readonly type: 'string';
+  };
+  readonly parent: {
+    readonly type: 'string';
+  };
+  readonly repo: {
+    readonly type: 'string';
+  };
+  readonly evidence: {
+    readonly type: 'string';
+  };
+  readonly by: {
+    readonly type: 'string';
+  };
+  readonly port: {
+    readonly type: 'string';
+  };
+  readonly 'no-open': {
+    readonly type: 'boolean';
+    readonly default: false;
+  };
+  readonly session: {
+    readonly type: 'string';
+  };
+  readonly agent: {
+    readonly type: 'string';
+  };
+  readonly id: {
+    readonly type: 'string';
+  };
+  readonly 'delegated-from': {
+    readonly type: 'string';
+  };
+  readonly 'handoff-from': {
+    readonly type: 'string';
+  };
+  readonly text: {
+    readonly type: 'string';
+  };
+  readonly serves: {
+    readonly type: 'string';
+  };
+  readonly before: {
+    readonly type: 'string';
+  };
+  readonly note: {
+    readonly type: 'string';
+  };
+  readonly reason: {
+    readonly type: 'string';
+  };
+  readonly 'waiting-for': {
+    readonly type: 'string';
+  };
+  readonly signal: {
+    readonly type: 'string';
+  };
+  readonly branch: {
+    readonly type: 'string';
+  };
+  readonly worktree: {
+    readonly type: 'string';
+  };
+  readonly base: {
+    readonly type: 'string';
+  };
+  readonly merge: {
+    readonly type: 'string';
+  };
+  readonly affects: {
+    readonly type: 'string';
+  };
+  readonly origin: {
+    readonly type: 'string';
+  };
+  readonly labels: {
+    readonly type: 'string';
+  };
+  readonly target: {
+    readonly type: 'string';
+  };
+  readonly op: {
+    readonly type: 'string';
+  };
+  readonly result: {
+    readonly type: 'string';
+  };
+  readonly ref: {
+    readonly type: 'string';
+  };
+  readonly month: {
+    readonly type: 'string';
+  };
+  readonly all: {
+    readonly type: 'boolean';
+    readonly default: false;
+  };
+  readonly 'dry-run': {
+    readonly type: 'boolean';
+    readonly default: false;
+  };
+  readonly version: {
+    readonly type: 'boolean';
+    readonly default: false;
+  };
+  readonly help: {
+    readonly type: 'boolean';
+    readonly default: false;
+  };
+};
+export declare const STATUSES: {
+  readonly mainline: readonly ["planning", "active", "paused", "done", "dropped"];
+  readonly task: readonly ["todo", "doing", "blocked", "done", "dropped"];
+  readonly action: readonly ["todo", "doing", "blocked", "done", "dropped"];
+  readonly decision: readonly ["proposed", "accepted", "superseded"];
+  readonly issue: readonly ["open", "planned", "closed"];
+  readonly finding: readonly ["valid", "obsolete"];
+  readonly session: readonly ["active", "paused", "ended", "handed-off"];
+  readonly merge: readonly ["open", "merged", "abandoned"];
+  readonly decider: readonly ["user", "ai", "relay"];
+};
+/** Reference formats, one example each, in the order a reader meets them. */
+export declare const REFERENCES: readonly [{
+  readonly target: 'mainline';
+  readonly format: 'm{NNN}';
+  readonly example: 'm001';
+}, {
+  readonly target: 'task';
+  readonly format: 'm{NNN}/t{NNN}';
+  readonly example: 'm001/t002';
+}, {
+  readonly target: 'checklist item';
+  readonly format: 'm{NNN}/t{NNN}#c{NNN}';
+  readonly example: 'm001/t002#c003';
+}, {
+  readonly target: 'criterion';
+  readonly format: 'm{NNN}#r{NNN}';
+  readonly example: 'm001#r001';
+}, {
+  readonly target: 'decision';
+  readonly format: 'm{NNN}/d{NNN}';
+  readonly example: 'm001/d001';
+}, {
+  readonly target: 'issue';
+  readonly format: 'i{NNN}';
+  readonly example: 'i001';
+}, {
+  readonly target: 'finding';
+  readonly format: 'f{NNN}';
+  readonly example: 'f001';
+}, {
+  readonly target: 'another hub';
+  readonly format: '{hub}:{reference}';
+  readonly example: 'other-hub:m001/t002';
+}, {
+  readonly target: 'action';
+  readonly format: '{sessionId}#a{NNN}';
+  readonly example: 'claude-code-1a2b3c4d#a003';
+}];
+/** Relation types a document's links take; readers derive the reverse direction. */
+export declare const LINKS: {
+  readonly rels: readonly ["depends-on", "relates", "split-from"];
+};
+/** Where each kind of entry lives under the hub root. */
+export declare const LAYOUT: {
+  readonly config: '.mainflow/config.yaml';
+  readonly mainline: '.mainflow/mainlines/m{NNN}-{slug}/mainline.md';
+  readonly decision: '.mainflow/mainlines/m{NNN}-{slug}/decisions/d{NNN}-{slug}.md';
+  readonly task: '.mainflow/mainlines/m{NNN}-{slug}/tasks/t{NNN}-{slug}/task.md';
+  readonly issue: '.mainflow/issues/i{NNN}-{slug}.md';
+  readonly finding: '.mainflow/findings/f{NNN}-{slug}.md';
+  readonly ops: '.mainflow/ops/{YYYY-MM}.log';
+  readonly sessions: '.mainflow/local/sessions/{sessionId}.yaml';
+};
+/** Statuses that close each kind of document; the CLI stamps closedAt when a document enters one. */
+export declare const CLOSED_STATUSES: {
+  readonly mainline: readonly ['done', 'dropped'];
+  readonly task: readonly ['done', 'dropped'];
+  readonly decision: readonly ['superseded'];
+  readonly issue: readonly ['closed'];
+  readonly finding: readonly ['obsolete'];
+};
+/** Classification every document shares: one category from the list (a hub adds more in config.yaml), P0 to P3. */
+export declare const CLASSIFICATION: {
+  readonly categories: readonly ["feature", "fix", "refactor", "docs", "research", "ops", "chore"];
+  readonly priorities: readonly ["P0", "P1", "P2", "P3"];
+  readonly defaultPriority: "P2";
+};
+/** Body sections each document is created with; the task sections in `taskRequired` must be filled while it is open. */
+export declare const SECTIONS: {
+  readonly mainline: readonly ["概述", "背景與前置", "範圍與不做", "限制"];
+  readonly task: readonly ["目標", "背景", "做法", "完成定義", "不做", "紀錄", "接手須知"];
+  readonly taskRequired: readonly ["目標", "完成定義"];
+  readonly decision: readonly ["背景", "選項", "建議", "決定", "理由"];
+  readonly issue: readonly ["背景", "要做的事", "完成條件"];
+  readonly finding: readonly ["發現", "影響", "做法"];
+};
+/** One front matter field: its name, whether a document is invalid without it, and what it holds. */
+export interface FieldSpec {
+  name: string;
+  required: boolean;
+  description: string;
+}
+/** 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 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 link: readonly [FieldSpec, FieldSpec, FieldSpec];
+};
+//#endregion