mainflow 0.42.0 → 0.43.0-alpha.2

package/dist/hooks.d.ts

@@ -1,541 +1,4 @@
-import { _ as Task, a as Decision, c as Group, d as Mainline, f as OpsEntry, h as Session, i as ChecklistItem, n as ActionBlock, s as Finding, t as Action, u as Issue } from "./index-Dk4fCI7q.js";
-import { z } from "zod";
-//#region ../core/dist/ids/allocators.d.ts
-/** The letters ids start with. */
-type IdPrefix = 'm' | 't' | 'd' | 'i' | 'f' | 'w' | '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 with its offset from UTC, like 2026-09-24T15:30+08:00 (`Z` for UTC).
-   * 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 caller's dates, and its times keep the caller's offset.
-   */
-  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;
-  /** A group of this hub the mainline belongs to */
-  group?: string;
-  priority?: string;
-}
-declare function createMainline(hub: HubReader, input: MainlineInput, ctx: OpContext): OpResult<{
-  id: string;
-  dir: string;
-}>;
-/** What `mainline set` changes; at least one. */
-interface MainlinePatch {
-  id: string;
-  status?: string;
-  /** A group of this hub, or `none` (null) to leave every group */
-  group?: string | null;
-  priority?: string;
-  expectedVersion?: string;
-}
-/**
- * Change a mainline's status, group or priority. Done is refused while criteria are open or decisions are
- * proposed; the other fields change without conditions, in the same write.
- */
-declare function setMainline(hub: HubReader, input: MainlinePatch, 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 list of the mainline or group in `mainline`, 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 | Group>;
-/** 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 | Group>;
-//#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 & {
-  group?: string;
-  priority?: string;
-}, ctx: OpContext): OpResult<{
-  id: string;
-  file: string;
-}>;
-/** What `issue set` changes: the group the issue is taken up with and its priority; at least one. */
-interface IssuePatch {
-  /** A group of this hub, or `none` (null) to leave every group */
-  group?: string | null;
-  priority?: string;
-}
-declare function setIssue(hub: HubReader, input: {
-  id: string;
-  patch: IssuePatch;
-  expectedVersion?: string;
-}): OpResult<Issue>;
-/** 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>;
-/**
- * A group gathers mainlines and issues that are taken up together, apart from what depends on what. Its members name
- * it in their own `group`, so creating a group writes only the group's file.
- */
-declare function createGroup(hub: HubReader, input: HubItemInput & {
-  priority?: string;
-  trigger?: string;
-}, ctx: OpContext): OpResult<{
-  id: string;
-  file: string;
-}>;
-/** What `group set` changes; at least one. An empty trigger removes it. */
-interface GroupPatch {
-  status?: string;
-  priority?: string;
-  trigger?: string;
-  title?: string;
-}
-declare function setGroup(hub: HubReader, input: {
-  id: string;
-  patch: GroupPatch;
-  expectedVersion?: string;
-}, ctx: OpContext): OpResult<Group>;
-/** 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.set', 'issue.plan', 'issue.close', 'issue.reopen', 'issue.archive', 'finding.new', 'finding.set', 'finding.archive', 'group.new', 'group.set', '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 setMainline;
-  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.set': typeof setIssue;
-  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 'group.new': typeof createGroup;
-  readonly 'group.set': typeof setGroup;
-  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
+import { a as Renumbering, i as Notice, n as OperationValue, o as HubDirs, r as OperationName, t as OperationInput } from "./index-DRpamPge.js";
 //#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> {
@@ -587,11 +50,13 @@ export interface HookContext {
   /** How the executor should invoke the CLI inside the hub, used in the texts it reads */
   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;
+  startUi?: (dirs: HubDirs) => 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;
+  /** The environment whose MAINFLOW_HOME holds the hub registry the hub is looked up in; process.env when left out */
+  env?: Record<string, string | undefined>;
   /**
    * 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).
@@ -604,7 +69,7 @@ export interface HookContext {
  */
 export declare function parsePayload(text: string): ClaudeCodePayload | null;
 export declare const claudeCodeSessionId: (raw: string) => string;
-type Handler = (root: string, ctx: HookContext & {
+type Handler = (dirs: HubDirs, 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. */