toolroll 0.5.0

package/dist/operate.d.ts

@@ -0,0 +1,118 @@
+import { type TriggerIo } from "./flow-triggers.js";
+import { type StepIo } from "./flow-steps.js";
+import { type Store } from "./store.js";
+import { type DispatchAdapter } from "./sync.js";
+import { type TelegramTransport } from "./telegram.js";
+import { type MateCliSeams } from "./mate-cli.js";
+import { type PublishExec } from "./publish.js";
+import { type Runner as CommandRunner } from "./builder.js";
+export type Write = (line: string) => void;
+/**
+ * 0 done · 1 broke · 2 bad usage · 3 ran fine, the answer is no.
+ *
+ * 3 is the one that matters. `toolroll claim` losing a race and
+ * `toolroll claim` failing to open the database must not look the same to a
+ * caller deciding whether to try the next task or wake somebody up.
+ */
+export declare const EXIT: {
+    readonly ok: 0;
+    readonly failed: 1;
+    readonly usage: 2;
+    readonly refused: 3;
+};
+/** Storage retention: how long a finished task's clean checkout is kept after it was let go, and a result marked
+ * complete's or a release candidate's after it was (its checkout holds the build a deploy installs). */
+export declare const CHECKOUT_KEEP_MS: number;
+export declare const RESULT_KEEP_MS: number;
+export type OperateOptions = {
+    /** Native-shell proof key, passed in memory rather than command-line arguments. */
+    desktopIdentity?: string;
+    /** A desktop service directory is state, never an implicitly enrolled project. */
+    inferProjectFromCwd?: boolean;
+    /** Exact additions approved by the native project picker, independent of the enrollment registry. */
+    additionalProjectRepos?: () => readonly string[];
+    /** Overridden by tests and by an agent that wants its own queue. */
+    databaseFile?: string;
+    openDatabase?: (file: string) => Store;
+    now?: Date;
+    /**
+     * Injected by tests: the processes `tick` and `build` run. The agent runner
+     * is what spends money, so a test that forgets to stub it fails loudly on a
+     * missing `claude` binary rather than quietly building something.
+     */
+    agentRunner?: CommandRunner;
+    gitRunner?: CommandRunner;
+    /** Injected by tests: the Telegram Bot API. Production dials the real one. */
+    telegramTransport?: TelegramTransport;
+    publishExec?: PublishExec;
+    /** Injected by tests: the stop fence a watch would set. */
+    shouldStop?: () => boolean;
+    /** Injected by tests: the external-dispatch gh surface. */
+    dispatchAdapter?: DispatchAdapter;
+    /** Injected by tests: how flow triggers reach GitHub (gh) and Linear (fetch), and where their secrets live. */
+    flowTriggerIo?: Partial<TriggerIo>;
+    /** Injected by tests: how flow check and update steps run commands and reach GitHub and Linear. */
+    flowStepIo?: Partial<StepIo>;
+    /** Injected by tests: the mate's provider fetch, key environment, and stdin lines. */
+    mateSeams?: MateCliSeams;
+    /** Injected by tests: a held-session coordinator, so a `tick` exercises
+     * the attended road exactly as a co-located `up` would (production wires
+     * one only inside `up`). */
+    heldCoordinator?: import("./held.js").HeldSessionCoordinator;
+    /** Test seam for the short indexed wait loop. */
+    waitSleep?: (milliseconds: number) => Promise<void>;
+};
+export declare const OPERATE_HELP: string;
+/** Parsed flags, with the positionals left over. */
+type Args = {
+    positional: string[];
+    flags: Map<string, string | true>;
+    /** EVERY --repo occurrence, in order (arc 2 finding 22): the Map keeps its
+     * last-wins behavior for every existing verb; only `up` reads this. */
+    repoList: string[];
+};
+/**
+ * The subcommand inventories the dispatchers consult (arc 5): each verb's
+ * runner refuses an action outside its list BEFORE its switch, so these
+ * exports are behavior, not commentary — and the declared command guide
+ * (surface.ts) is tested for exact equality against them.
+ */
+export declare const TASK_ACTIONS: readonly ["add", "list", "show", "wait", "state", "block", "unblock", "next", "steer", "assign", "reopen", "scope", "approve", "hold", "unhold", "require", "requeue", "regate", "plan", "review", "accept", "repair", "route", "stop", "resume", "complete", "revise"];
+export declare const PUBLISH_ACTIONS: readonly ["grant", "revoke", "status", "unblock", "rearm", "merge", "refire"];
+export declare const CONFIG_ACTIONS: readonly ["show", "set", "clear"];
+export declare const APPROVER_ACTIONS: readonly ["list", "add"];
+export declare const ROUTINE_ACTIONS: readonly ["list", "add", "show", "approve", "refresh", "pause", "resume", "run-now"];
+export declare const CONTEST_ACTIONS: readonly ["show", "exclude"];
+export declare const PEOPLE_ACTIONS: readonly ["list", "invite", "projects", "revoke"];
+export declare const KEYS_ACTIONS: readonly ["status", "set", "clear", "verify", "auth"];
+/**
+ * The GLOBAL flag vocabulary (exported for the command guide's drift
+ * tests): every value-taking flag any verb reads, and every boolean.
+ * A --flag in neither set is a typo, refused by name.
+ */
+export declare const OPERATE_VALUE_FLAGS: ReadonlySet<string>;
+export declare const OPERATE_BOOLEAN_FLAGS: ReadonlySet<string>;
+export declare function parseOperateArgs(argv: readonly string[]): Args | {
+    error: string;
+};
+/** Route an `operate` command. Returns the process exit code. */
+export declare function runOperate(command: string, argv: readonly string[], write: Write, options?: OperateOptions): Promise<number>;
+/** Durably create the login file BEFORE the bootstrap commits (arc 2
+ * finding 27): exclusive, 0600, fsynced — file and directory both — so the
+ * row only ever follows a durable secret. Throws on any failure. */
+export declare function writeLoginFileDurably(path: string, name: string, password: string): void;
+/**
+ * The people allowed to agree to a scope.
+ *
+ * Kept apart from runners deliberately: a runner credential takes work, and an
+ * approver credential agrees to it. One token that did both would collapse the
+ * gate into a formality the moment an agent held it.
+ */
+/**
+ * Who is acting, from flags — or from a person at the terminal. Scripts and
+ * agents pass --as/--token and never see a prompt; a human who left them off
+ * is simply asked, with the password hidden. Under --json (or any non-TTY)
+ * missing credentials stay a usage refusal, exactly as before.
+ */
+export declare const PROPOSALS_ACTIONS: readonly ["list", "confirm", "dismiss"];
+export {};