mainflow 0.28.0 → 0.29.0

package/dist/hooks.d.ts

@@ -1,3 +1,507 @@
+import { a as Decision, d as OpsEntry, g as Task, i as ChecklistItem, l as Issue, m as Session, n as ActionBlock, s as Finding, t as Action, u as Mainline } from "./index-DV6Gqu8K.js";
+import { z } from "zod";
+//#region ../core/dist/ids/allocators.d.ts
+/** The letters ids start with. */
+type IdPrefix = 'm' | 't' | 'd' | 'i' | 'f' | 'c' | 'r' | 'a';
+/** One id an operation needs. */
+interface IdRequest {
+  prefix: IdPrefix;
+  /** Ids already used in the scope the new one goes into */
+  taken: readonly string[];
+  /** The reference an id makes in this scope, like id => `m001/t002#${id}`; allocations are reported as references */
+  ref: (id: string) => string;
+}
+interface Allocation {
+  id: string;
+  /** The reference the id makes, e.g. m001/t002#c003 */
+  ref: string;
+  /** Numbered while offline; the sync server confirms it or gives another when it is taken */
+  provisional: boolean;
+  /** The provisional reference this id replaces, when the sender's number was taken */
+  replaced?: string;
+}
+interface IdAllocator {
+  readonly mode: 'local' | 'server' | 'offline';
+  next(request: IdRequest): Allocation;
+}
+//#endregion
+//#region ../core/dist/ops/document.d.ts
+/** What an operation needs from its caller besides its input. */
+interface OpContext {
+  /**
+   * The caller's local time to the minute, like 2026-09-24T15:30. Dates and times an operation writes come
+   * from it, so an operation run where the clock is in another time zone, such as UTC in Workers, writes the
+   * same dates as one run on the caller's machine.
+   */
+  now: string;
+  /** Who numbers new entries (src/ids/); without one, the next free id, final at once */
+  ids?: IdAllocator;
+}
+//#endregion
+//#region ../core/dist/storage/types.d.ts
+/** One name inside a directory. */
+interface Entry {
+  name: string;
+  dir: boolean;
+}
+/** What an operation may read. */
+interface HubReader {
+  /** The text of a file, or null when it does not exist. */
+  read(path: string): string | null;
+  /** The files and directories directly inside `dir`, sorted by name; empty when `dir` does not exist. */
+  list(dir: string): Entry[];
+  /** How messages name a path, such as the absolute file path on disk. */
+  where(path: string): string;
+}
+//#endregion
+//#region ../core/dist/ids/renumber.d.ts
+/** One id the sync server replaced, as references: the provisional one and the one the entry has now. */
+interface Renumbering {
+  from: string;
+  to: string;
+}
+//#endregion
+//#region ../core/dist/ops/draft.d.ts
+/** One change to a hub's storage. */
+type Change = {
+  kind: 'write';
+  path: string;
+  text: string;
+} | {
+  kind: 'append';
+  path: string;
+  text: string;
+} | {
+  kind: 'makeDir';
+  path: string;
+} | {
+  kind: 'remove';
+  path: string;
+};
+/** Something the writer should be told although the operation went through, such as a file kept against its request. */
+interface Notice {
+  path: string;
+  message: string;
+}
+interface OpResult<T> {
+  /** What the operation reports back, such as the entry it created */
+  value: T;
+  /** The changes to apply, in order */
+  changes: Change[];
+  /** Ids this operation numbered, as references like m014, m001/t007 or claude-code-1a2b3c4d#a003, in the order it numbered them */
+  allocated: string[];
+  /** Provisional ids the allocator replaced because they were taken, with the ids the entries have instead */
+  renumbered: Renumbering[];
+  notices: Notice[];
+}
+//#endregion
+//#region ../core/dist/ops/status.d.ts
+/** What a new criterion or checklist item says: what to do and when it counts as done. */
+interface ListItemInput {
+  text: string;
+  doneWhen: string;
+}
+//#endregion
+//#region ../core/dist/ops/hub.d.ts
+/** Register a repository the hub's tasks may point at; `path` is relative to the hub root. */
+declare function addRepo(hub: HubReader, input: {
+  name: string;
+  path: string;
+}): OpResult<string>;
+/**
+ * Register another hub whose documents this hub's references may point at, as `{name}:m001`. `path` is relative
+ * to this hub's root; the caller checks that it holds that hub under the same name.
+ */
+declare function addHub(hub: HubReader, input: {
+  name: string;
+  path: string;
+}): OpResult<string>;
+//#endregion
+//#region ../core/dist/ops/mainlines.d.ts
+interface MainlineInput {
+  slug: string;
+  title: string;
+}
+declare function createMainline(hub: HubReader, input: MainlineInput, ctx: OpContext): OpResult<{
+  id: string;
+  dir: string;
+}>;
+/** Move a mainline to another status; done is refused while criteria are open or decisions are proposed. */
+declare function setMainlineStatus(hub: HubReader, input: {
+  id: string;
+  status: string;
+  expectedVersion?: string;
+}, ctx: OpContext): OpResult<Mainline>;
+/** Rename a mainline. References use its ID, so they keep resolving and show the new title. */
+declare function setMainlineTitle(hub: HubReader, input: {
+  id: string;
+  title: string;
+  expectedVersion?: string;
+}): OpResult<Mainline>;
+declare function setMainlineArchived(hub: HubReader, input: {
+  id: string;
+  archived: boolean;
+  expectedVersion?: string;
+}, ctx: OpContext): OpResult<Mainline>;
+/** Add an open criterion at the end of the mainline's list, numbered by the context's allocator. */
+declare function addCriterion(hub: HubReader, input: ListItemInput & {
+  mainline: string;
+}, ctx: OpContext): OpResult<{
+  ref: string;
+}>;
+declare function setCriterion(hub: HubReader, input: {
+  ref: string;
+  done: boolean;
+  evidence?: string;
+  expectedVersion?: string;
+}, ctx: OpContext): OpResult<Mainline>;
+/** What `criterion set` rewrites; at least one must be given. `done` stays as it is; use criterion check/uncheck for that. */
+interface CriterionTextPatch {
+  text?: string;
+  doneWhen?: string;
+}
+/** Rewrite a criterion's text or doneWhen, leaving done and evidence as they are. */
+declare function setCriterionText(hub: HubReader, input: {
+  ref: string;
+  patch: CriterionTextPatch;
+  expectedVersion?: string;
+}): OpResult<Mainline>;
+//#endregion
+//#region ../core/dist/ops/tasks.d.ts
+interface TaskInput {
+  slug: string;
+  title: string;
+  kind?: string;
+  parent?: string | null;
+  repo?: string | null;
+}
+declare function createTask(hub: HubReader, input: TaskInput & {
+  mainline: string;
+}, ctx: OpContext): OpResult<{
+  ref: string;
+  dir: string;
+}>;
+/**
+ * What `task set` changes: the status with the fields a transition needs, and the repository and branch
+ * the task works on. Title, parent and prose are written in task.md directly.
+ */
+interface TaskPatch {
+  status?: string;
+  repo?: string | null;
+  /** Required with status blocked; cleared when the task leaves blocked */
+  blockedBy?: {
+    reason: string;
+    waitingFor?: string;
+    signal?: string;
+  };
+  branch?: string;
+  worktree?: string;
+  base?: string;
+  merge?: string;
+}
+declare function updateTask(hub: HubReader, input: {
+  ref: string;
+  patch: TaskPatch;
+  expectedVersion?: string;
+}, ctx: OpContext): OpResult<Task>;
+/** Add an open item at the end of the task's checklist, numbered by the context's allocator. */
+declare function addChecklistItem(hub: HubReader, input: ListItemInput & {
+  task: string;
+  serves?: string[];
+}, ctx: OpContext): OpResult<{
+  ref: string;
+  item: ChecklistItem;
+}>;
+declare function setChecklistItem(hub: HubReader, input: {
+  ref: string;
+  done: boolean;
+  evidence?: string;
+  expectedVersion?: string;
+}, ctx: OpContext): OpResult<Task>;
+/** Mark an item as no longer needed, naming what replaced it when something did. */
+declare function dropChecklistItem(hub: HubReader, input: {
+  ref: string;
+  supersededBy?: string;
+  note?: string;
+  expectedVersion?: string;
+}): OpResult<Task>;
+/** Bring a dropped item back as an open one: clears dropped and supersededBy, keeps the note. */
+declare function undropChecklistItem(hub: HubReader, input: {
+  ref: string;
+  expectedVersion?: string;
+}): OpResult<Task>;
+//#endregion
+//#region ../core/dist/ops/decisions.d.ts
+interface DecisionInput {
+  slug: string;
+  title: string;
+  /** proposed while the question is open; accepted by default */
+  status?: string;
+  by?: string;
+  /** explicit when the decider named an option, recommended when they went with the recommendation */
+  basis?: string;
+  /** Tasks and items the decision shapes; the checklist items among them wait while it is proposed */
+  affects?: string[];
+}
+declare function createDecision(hub: HubReader, input: DecisionInput & {
+  mainline: string;
+}, ctx: OpContext): OpResult<{
+  ref: string;
+  file: string;
+}>;
+/** Who settled a decision, and whether they named an option or went with the recommendation. */
+interface DecisionSettlement {
+  by?: string;
+  basis?: string;
+}
+/** Settle a proposed decision: record who decided, how and when; the items it affects stop waiting for it. */
+declare function acceptDecision(hub: HubReader, input: {
+  ref: string;
+  expectedVersion?: string;
+} & DecisionSettlement, ctx: OpContext): OpResult<Decision>;
+declare function supersedeDecision(hub: HubReader, input: {
+  ref: string;
+  by: string;
+  expectedVersion?: string;
+}, ctx: OpContext): OpResult<Decision>;
+//#endregion
+//#region ../core/dist/ops/hub-items.d.ts
+interface HubItemInput {
+  slug: string;
+  title: string;
+  origin?: string;
+  labels?: string[];
+}
+declare function createIssue(hub: HubReader, input: HubItemInput, ctx: OpContext): OpResult<{
+  id: string;
+  file: string;
+}>;
+/** Schedule an issue into the task that will carry it out. */
+declare function planIssue(hub: HubReader, input: {
+  id: string;
+  task: string;
+  expectedVersion?: string;
+}): OpResult<Issue>;
+declare function closeIssue(hub: HubReader, input: {
+  id: string;
+  resolution: string;
+  expectedVersion?: string;
+}, ctx: OpContext): OpResult<Issue>;
+declare function reopenIssue(hub: HubReader, input: {
+  id: string;
+  expectedVersion?: string;
+}): OpResult<Issue>;
+/** Archive or unarchive an issue; the status stays as it is, so a closed issue is visible until archived. */
+declare function setIssueArchived(hub: HubReader, input: {
+  id: string;
+  archived: boolean;
+  expectedVersion?: string;
+}, ctx: OpContext): OpResult<Issue>;
+declare function createFinding(hub: HubReader, input: HubItemInput, ctx: OpContext): OpResult<{
+  id: string;
+  file: string;
+}>;
+declare function setFindingStatus(hub: HubReader, input: {
+  id: string;
+  status: string;
+  expectedVersion?: string;
+}, ctx: OpContext): OpResult<Finding>;
+/** Archive or unarchive a finding; the status stays as it is, so an obsolete finding is visible until archived. */
+declare function setFindingArchived(hub: HubReader, input: {
+  id: string;
+  archived: boolean;
+  expectedVersion?: string;
+}, ctx: OpContext): OpResult<Finding>;
+/** Append one external operation to ops/{YYYY-MM}.log; the log is never rewritten. `at` defaults to the context's time. */
+declare function appendOps(hub: HubReader, input: Omit<OpsEntry, 'at'> & {
+  at?: string;
+}, ctx: OpContext): OpResult<OpsEntry>;
+//#endregion
+//#region ../core/dist/ops/sections.d.ts
+/** Add text at the end of a section of a document's body; the front matter is kept as it is written. */
+declare function appendSection(hub: HubReader, input: {
+  ref: string;
+  section: string;
+  text: string;
+}): OpResult<{
+  file: string;
+}>;
+//#endregion
+//#region ../core/dist/ops/files.d.ts
+type Removal = 'removed' | 'absent' | 'kept';
+/**
+ * Remove the file at `path` when it is still the version the deleter had, given as its content hash (`base`).
+ * A deletion only takes away what the deleter saw: when the file changed since, such as an action another
+ * environment added to a session at the same time, removing it would lose that change unseen. The file is kept
+ * as it is now and a notice tells the deleter why. A file that is already gone stays gone.
+ */
+declare function removeFile(hub: HubReader, input: {
+  path: string;
+  base: string;
+}): OpResult<Removal>;
+//#endregion
+//#region ../core/dist/ops/sessions.d.ts
+interface SessionInput {
+  /** The caller picks the id, such as `{agent}-{8 random hex}`, since an operation draws no random numbers */
+  id: string;
+  agent: string;
+  cwd: string;
+  delegatedFrom?: string | null;
+  handoffFrom?: string | null;
+}
+/**
+ * Start a session. Taking over from another session moves its unfinished actions into this one and marks
+ * the other session handed-off, so the queue continues where it stopped.
+ */
+declare function startSession(hub: HubReader, input: SessionInput, ctx: OpContext): OpResult<Session>;
+/**
+ * Start the session unless it already exists. An existing paused or ended session becomes active again, and
+ * an archived one comes back into view, since resumed work should not stay hidden.
+ */
+declare function ensureSession(hub: HubReader, input: SessionInput, ctx: OpContext): OpResult<{
+  session: Session;
+  created: boolean;
+}>;
+/**
+ * Take over another session's unfinished actions into a session that already exists, such as one a host hook
+ * created when the conversation opened. The receiving session must have nothing unfinished of its own, so the
+ * carried queue is not mixed into work already under way; its finished actions stay and the carried ones are
+ * numbered after them.
+ */
+declare function handoffSession(hub: HubReader, input: {
+  id: string;
+  from: string;
+}, ctx: OpContext): OpResult<Session>;
+/** Environment facts a platform adapter learns about a session; only the given fields change. */
+type SessionInfo = Partial<Pick<Session, 'transcript' | 'worktree' | 'branch' | 'model' | 'effort' | 'description' | 'depth' | 'summary'>>;
+declare function setSessionInfo(hub: HubReader, input: {
+  id: string;
+  info: SessionInfo;
+}): OpResult<Session>;
+/** Remember the digest of what the last turn reminder listed in full; null forgets it, so the next reminder lists everything again. */
+declare function setReminderDigest(hub: HubReader, input: {
+  id: string;
+  digest: string | null;
+}): OpResult<Session>;
+declare function setSessionStatus(hub: HubReader, input: {
+  id: string;
+  status: string;
+}): OpResult<Session>;
+type Settled = 'removed' | 'ended' | 'kept';
+/**
+ * Settle a session when its turn ends. A session that tracked no action, and whose subagents tracked none, leaves
+ * no record, since nothing in it points at the hub's work. Then every active main session with no action left to
+ * do and no subagent still running ends, the others as well as this one: another session may have finished its
+ * last action, or it was closed before its own turn could settle it. The next prompt or action brings it back.
+ */
+declare function settleSession(hub: HubReader, input: {
+  id: string;
+}): OpResult<Settled>;
+/** Archive or unarchive a session; the status stays as it is, so an ended session is visible until archived. */
+declare function setSessionArchived(hub: HubReader, input: {
+  id: string;
+  archived: boolean;
+}, ctx: OpContext): OpResult<Session>;
+interface ActionInput {
+  session: string;
+  do: string;
+  serves: string[];
+  before?: string;
+}
+/** Queue an action; the value is its reference, like claude-code-1a2b3c4d#a003. */
+declare function addAction(hub: HubReader, input: ActionInput, ctx: OpContext): OpResult<string>;
+interface ActionPatch {
+  status?: string;
+  do?: string;
+  serves?: string[];
+  before?: string;
+  note?: string;
+  /** Required with status blocked; cleared when the action leaves blocked */
+  blockedBy?: ActionBlock;
+}
+declare function updateAction(hub: HubReader, input: {
+  ref: string;
+  patch: ActionPatch;
+}, ctx: OpContext): OpResult<Action>;
+//#endregion
+//#region ../core/dist/ops/protocol.d.ts
+/**
+ * Every operation by name. A name is the CLI command that sends it with the words joined by a dot, the noun
+ * first (`new task` sends `task.new`); a pair of commands that set and clear one thing shares an operation
+ * (`item check` and `item uncheck` send `item.check`, with done true or false). The operations no command sends
+ * are listed in COMMANDLESS_OPERATIONS with who sends them.
+ */
+declare const OPERATION_NAMES: readonly ['repo.add', 'hub.add', 'mainline.new', 'mainline.set', 'mainline.title', 'mainline.archive', 'criterion.add', 'criterion.check', 'criterion.set', 'task.new', 'task.set', 'item.add', 'item.check', 'item.drop', 'item.undrop', 'decision.new', 'decision.accept', 'decision.supersede', 'issue.new', 'issue.plan', 'issue.close', 'issue.reopen', 'issue.archive', 'finding.new', 'finding.set', 'finding.archive', 'ops.add', 'section.append', 'session.start', 'session.ensure', 'session.handoff', 'session.info', 'session.reminder', 'session.set', 'session.settle', 'session.archive', 'action.add', 'action.set', 'file.remove'];
+type OperationName = (typeof OPERATION_NAMES)[number];
+//#endregion
+//#region ../core/dist/ops/operations.d.ts
+/**
+ * The operations by name, for a server that receives them from elsewhere. The names are the protocol's
+ * (OPERATION_NAMES in protocol.ts): the table must hold every one of them and nothing else. `migrate` and `init`
+ * are absent: migration rewrites the whole hub in one go and a new hub starts on the caller's machine, so neither
+ * is sent as an operation.
+ */
+declare const OPERATIONS: {
+  readonly 'repo.add': typeof addRepo;
+  readonly 'hub.add': typeof addHub;
+  readonly 'mainline.new': typeof createMainline;
+  readonly 'mainline.set': typeof setMainlineStatus;
+  readonly 'mainline.title': typeof setMainlineTitle;
+  readonly 'mainline.archive': typeof setMainlineArchived;
+  readonly 'criterion.add': typeof addCriterion;
+  readonly 'criterion.check': typeof setCriterion;
+  readonly 'criterion.set': typeof setCriterionText;
+  readonly 'task.new': typeof createTask;
+  readonly 'task.set': typeof updateTask;
+  readonly 'item.add': typeof addChecklistItem;
+  readonly 'item.check': typeof setChecklistItem;
+  readonly 'item.drop': typeof dropChecklistItem;
+  readonly 'item.undrop': typeof undropChecklistItem;
+  readonly 'decision.new': typeof createDecision;
+  readonly 'decision.accept': typeof acceptDecision;
+  readonly 'decision.supersede': typeof supersedeDecision;
+  readonly 'issue.new': typeof createIssue;
+  readonly 'issue.plan': typeof planIssue;
+  readonly 'issue.close': typeof closeIssue;
+  readonly 'issue.reopen': typeof reopenIssue;
+  readonly 'issue.archive': typeof setIssueArchived;
+  readonly 'finding.new': typeof createFinding;
+  readonly 'finding.set': typeof setFindingStatus;
+  readonly 'finding.archive': typeof setFindingArchived;
+  readonly 'ops.add': typeof appendOps;
+  readonly 'section.append': typeof appendSection;
+  readonly 'session.start': typeof startSession;
+  readonly 'session.ensure': typeof ensureSession;
+  readonly 'session.handoff': typeof handoffSession;
+  readonly 'session.info': typeof setSessionInfo;
+  readonly 'session.reminder': typeof setReminderDigest;
+  readonly 'session.set': typeof setSessionStatus;
+  readonly 'session.settle': typeof settleSession;
+  readonly 'session.archive': typeof setSessionArchived;
+  readonly 'action.add': typeof addAction;
+  readonly 'action.set': typeof updateAction;
+  readonly 'file.remove': typeof removeFile;
+};
+type OperationInput<N extends OperationName> = Parameters<(typeof OPERATIONS)[N]>[1];
+type OperationValue<N extends OperationName> = ReturnType<(typeof OPERATIONS)[N]>['value'];
+//#endregion
+//#region src/remote/operation.d.ts
+/** What a write reports: the operation's value, and what its caller tells the user about it. */
+interface Written<N extends OperationName = OperationName> {
+  value: OperationValue<N>;
+  /** Waiting in the outbox, not yet answered by the sync server; new entries in `value` have provisional ids */
+  queued: boolean;
+  /** Why nothing sends the outbox for now: no sync client runs and none could be started */
+  stopped?: string;
+  /** Why a sync client was started although one was expected to run */
+  restarted?: string;
+  /** Provisional ids the server gave to other entries, so this write's entries got the ids after the arrow */
+  renumbered: Renumbering[];
+  /** What the operation said about the write although it went through, such as a file it kept */
+  notices: Notice[];
+}
+type HubWrite = <N extends OperationName>(op: N, input: OperationInput<N>) => Promise<Written<N>>;
+//#endregion
 //#region src/hooks.d.ts
 /** Fields Claude Code sends on stdin to every command hook, plus the ones specific to the events handled here. */
 export interface ClaudeCodePayload {
@@ -36,6 +540,11 @@ export interface HookContext {
   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;
+  /**
+   * How the hub a handler runs in is written; runHook sets it. In remote mode it applies the operation here and puts
+   * it in the hub's outbox, as the writing commands do, so a hook's write is never a direct edit (src/remote/operation.ts).
+   */
+  write?: HubWrite;
 }
 /**
  * Read a hook's stdin: one JSON object, as Claude Code sends it. Anything else is null, including arrays,
@@ -43,7 +552,9 @@ export interface HookContext {
  */
 export declare function parsePayload(text: string): ClaudeCodePayload | null;
 export declare const claudeCodeSessionId: (raw: string) => string;
-type Handler = (root: string, ctx: HookContext) => string | null;
+type Handler = (root: string, ctx: HookContext & {
+  write: HubWrite;
+}) => Promise<string | null> | 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. */
@@ -63,8 +574,8 @@ export declare function hookFallback(platform: string, event: string, ctx: HookC
  * 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): {
+export declare function runHook(platform: string, event: string, ctx: HookContext): Promise<{
   stdout: string | null;
   error: string | null;
-};
+}>;
 //#endregion