toolroll 0.5.0

package/dist/cli.d.ts

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+/**
+ * The command.
+ *
+ * `toolroll` with no arguments reads the repositories below the working
+ * directory and prints what is in flight. It writes nothing, starts nothing,
+ * and asks nothing. Everything it knows comes from git and from the operator's
+ * own filesystem.
+ *
+ * `--json` exists because half the intended audience is an agent, and an agent
+ * should not have to parse a column layout.
+ */
+import { previewGithubRepo, cloneGithubRepo } from "./onboard.js";
+import { type SessionCliOptions } from "./session-cli.js";
+import { type TeamCliOptions } from "./team-cli.js";
+import { type OperateOptions } from "./operate.js";
+export type CliOptions = {
+    roots: string[];
+    /** The positional tokens exactly as typed, index-aligned with `roots` —
+     * kept because a resolved absolute path can no longer say whether the
+     * operator typed a bare word that might have been a command. */
+    rawRoots: string[];
+    /** Whether roots came from the command line, as opposed to the default. */
+    rootsGiven: boolean;
+    maxDepth: number;
+    json: boolean;
+    includeHidden: boolean;
+    /** Report everything discoverable, ignoring the enrolled list. */
+    all: boolean;
+    dirty: boolean;
+    /** Skip the network entirely: branches only, no pull requests or issues. */
+    local: boolean;
+    help: boolean;
+};
+export type ParseResult = {
+    options: CliOptions;
+} | {
+    error: string;
+};
+type Write = (line: string) => void;
+export declare const HELP = "toolroll \u2014 a control plane for unattended coding agents\n\nUsage\n  toolroll [path...]        report what is in flight\n  toolroll pulls            report what is waiting on a person\n  toolroll graph            report which work graph is already here\n  toolroll repos            list connected repositories, and how to adjust\n  toolroll repos add <path> connect one (no path: the repo you are in)\n  toolroll repos remove <path>\n  toolroll repos add-from-github <owner/name> --root <dir>\n                                   preview, then clone and connect (--yes)\n  toolroll link             put `toolroll` on your PATH\n  toolroll unlink           take it off again\n  toolroll contract         the machine contract: envelope version + capabilities\n                                   (--commands dumps the declared command guide)\n  toolroll skills install --claude-code [--dir <path>]\n                                   install this binary's guides for Claude Code (preview first)\n  toolroll skills install   teach a repo's agents this queue exists (preview first)\n  toolroll skills list      the guides this exact binary serves\n  toolroll skills get <name>  print one guide (version-matched, never stale)\n  toolroll demo             a seeded throwaway sandbox \u2014 see it working in 90 seconds\n  toolroll up               app + builder for every saved project \u2014 the normal start\n  toolroll status           running, queued, ready results, release check and plan windows\n  toolroll session          native coding sessions through the running service\n  toolroll connect          save a private connection to your central service\n  toolroll lead             named leads on the connected service\n  toolroll conversation     shared and private conversations on that service\n  toolroll chat --lead <id> --conversation <id>  central chat (use --local for local chat)\n\nOperating the queue \u2014 `toolroll task` prints the whole surface,\nand any queue command + --help prints it too\n  toolroll approver add <name>\n                               mint the credential that lets a person say yes\n  toolroll ready            what could be dispatched right now\n  toolroll check-progress <run>  current or final approved check progress\n  toolroll task wait <id> [--timeout <seconds>]\n                               wait for this attempt to finish or need a person\n  toolroll task add <title> queue work\n  toolroll task scope <id> --goal <text>\n                               state what success is; approval binds to it\n  toolroll task approve <id>\n                               the yes \u2014 nothing builds without one\n  toolroll claim <id> --runner <name>\n  toolroll heartbeat <lease> / release <lease> / reap\n  toolroll tick --runner <name> --token <t> --repo <path>\n                               one unattended pass over the ready set\n  toolroll chat --as <you> --token <t>\n                               talk to the mate: one conversation across every\n                               project; it proposes, you confirm (--say \"\u2026\" for one turn)\n  toolroll serve --repo <path>  advanced: run only the console\n                               (--editor vscode with --runner: file links\n                               open in VS Code on the device you browse from)\n  toolroll watch / daemon install   advanced: run only the builder\n  toolroll reconcile        recover what the last stretch left behind\n\nWith nothing connected it reports everything it can find below the working\ndirectory. Once you connect repositories it reports those instead.\n\nOptions\n  --all         report everything discoverable, ignoring connected repos\n  --depth <n>   directory levels to descend (default: 6)\n  --hidden      include dot-directories, which are skipped by default\n  --dirty       also read each working tree for uncommitted files\n  --local       branches only: no network, no pull requests, no issues\n  --json        emit a machine-readable envelope instead of a report\n  -o <file>     also write that envelope to a file (requires --json)\n  -h, --help    show this\n\nNothing is written, installed, or configured. Every repository is read\nthrough git with --no-optional-locks, so a scan never contends for the\nindex lock with an editor you have open.\n\n--dirty is off by default because reading a working tree is unbounded\nwork: on a large or cloud-synced repo `git status` can take minutes,\nwhere listing branches takes milliseconds.\n\nlink shows what it would do and changes nothing; add --yes to apply it,\nor --to <dir> to choose where. It never uses sudo, never leaves your\nhome directory, and never touches a file it did not create.";
+export declare function parseArgs(argv: readonly string[]): ParseResult;
+/** The commands that operate the queue rather than report on the world. */
+/** Every verb the CLI routes OUTSIDE runOperate. Exported (with
+ * OPERATE_COMMANDS) so the declared command guide's drift tests compare
+ * exact sets instead of regex-reading source. "" is the no-verb report,
+ * which answers as `scan`. */
+export declare const TOP_LEVEL_COMMANDS: readonly string[];
+export declare const OPERATE_COMMANDS: Set<string>;
+/** binSource exists so tests can exercise linking without depending on a build. */
+export type MainOptions = {
+    binSource?: string;
+    operate?: OperateOptions;
+    session?: SessionCliOptions;
+    team?: TeamCliOptions;
+    /** Injected by tests: the gh-facing halves of `repos add-from-github` —
+     * the verb's parsing, gating, and enrollment are what CLI tests prove;
+     * gh itself is proved by onboard.test.ts. */
+    onboard?: {
+        preview?: typeof previewGithubRepo;
+        clone?: typeof cloneGithubRepo;
+    };
+};
+/**
+ * Strip `-o <file>` / `--output <file>` before dispatch. The flag belongs to
+ * the entry point, not to any one command: after the command runs, whatever
+ * envelope it serialized is copied to the file, so an agent reads its answer
+ * from a path instead of scraping a terminal. Requires `--json`, because the
+ * file receives the machine envelope and nothing else does.
+ */
+export declare function extractOutputFlag(argv: readonly string[]): {
+    args: string[];
+    outputFile?: string;
+} | {
+    error: string;
+};
+export declare function main(argv: readonly string[], write?: Write, mainOptions?: MainOptions): Promise<number>;
+export declare function partitionRoots(roots: readonly string[], exists: (path: string) => boolean): {
+    present: string[];
+    missing: string[];
+};
+export type LinkArgs = {
+    to?: string;
+    yes: boolean;
+};
+export declare function parseLinkArgs(argv: readonly string[]): {
+    args: LinkArgs;
+} | {
+    error: string;
+};
+/**
+ * `skills install`: with --claude-code, install this binary's lead guides
+ * in the user's Claude Code skills directory. Without it, retain the older
+ * repository-local Agent Skills entry and optional managed AGENTS.md block.
+ * Both paths preview by default, write only with --yes, and refuse files
+ * they do not own.
+ */
+/** The skills subcommands and their EXACT flag vocabularies — consulted
+ * by the parser above and compared verbatim by the command guide's tests
+ * (arc-5 review, finding 5). */
+export declare const SKILLS_ACTIONS: readonly ["install", "list", "get"];
+export declare const SKILLS_FLAGS: {
+    readonly install: {
+        readonly json: "flag";
+        readonly yes: "flag";
+        readonly "claude-code": "flag";
+        readonly dir: "value";
+        readonly "write-context": "flag";
+        readonly repo: "value";
+    };
+    readonly list: {
+        readonly json: "flag";
+    };
+    readonly get: {
+        readonly json: "flag";
+    };
+};
+/**
+ * `contract` is the machine contract, stated by the machine: the envelope
+ * version and the capability tokens an agent consumer can feature-detect on.
+ * Behaviors, not versions — consumers ignore tokens they do not recognize.
+ */
+/** contract's EXACT flags — consulted below and compared by the command
+ * guide's tests (arc-5 review, finding 5). */
+export declare const CONTRACT_FLAGS: readonly ["json", "commands"];
+/**
+ * Whether this module is the program being run, rather than an import.
+ *
+ * Node resolves a module to its real path while argv[1] keeps whatever name it
+ * was invoked by, so a symlinked `toolroll` on PATH compares unequal to
+ * itself unless both sides are resolved. Getting this wrong is silent: the
+ * command runs, prints nothing, and exits 0.
+ */
+export declare function isDirectInvocation(moduleUrl: string, entry: string | undefined, toRealPath?: (path: string) => string): boolean;
+/** The process entry the bin calls: the SQLite notice hushed, the exit code set. */
+export declare function runCliProcess(argv: readonly string[]): Promise<void>;
+export {};