@shardflux/cli 0.19.1 → 0.20.0

package/dist/machine-setup.d.ts

@@ -0,0 +1,180 @@
+import type { AgentFilesystem, Workspace } from '@shardflux/sdk';
+import type { Ctx, Handler } from './commands.js';
+import { AgentStateStore } from './agent-state.js';
+import { type Values } from './args.js';
+export type Runner = 'claude' | 'codex' | 'cloud';
+type Env = Record<string, string | undefined>;
+/** Set for the local agent's processes: the `shard` it runs only reaches this machine VM (see `setupGuard`). */
+export declare const SETUP_VM_ENV = "SHARDFLUX_MACHINE_SETUP_VM";
+export declare const DEFAULT_AGENT_TIMEOUT_MS: number;
+export interface ChildResult {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+}
+export interface ChildOptions {
+    cwd?: string;
+    env?: Env;
+    input?: string;
+    timeoutMs: number;
+    signal?: AbortSignal;
+    onLine?: (line: string) => void;
+    maxBytes?: number;
+}
+/**
+ * Runs argv without a shell in its own process group; past the time box (or on abort) the whole group gets SIGTERM, then
+ * SIGKILL 5 s later. Keeps the last `maxBytes` of each stream. Never throws for a non-zero exit or a missing program.
+ */
+export declare function runChild(argv: string[], o: ChildOptions): Promise<ChildResult>;
+/** The first executable `name` on PATH or in the usual install folders (a menu bar app's PATH is short). */
+export declare function findExecutable(name: string, env: Env): string | undefined;
+export interface LocalAgent {
+    app: 'claude' | 'codex';
+    bin: string;
+    version: string;
+    help: string;
+    signedIn: boolean;
+    usable: boolean;
+    reason?: string;
+}
+/** Flags a restricted `claude -p` run needs (checked against `claude --help` of the installed version). */
+export declare const CLAUDE_REQUIRED_FLAGS: readonly ["--print", "--tools", "--allowedTools", "--disallowedTools", "--permission-mode", "dontAsk", "--strict-mcp-config", "--setting-sources", "--output-format", "stream-json"];
+/** Flags `codex exec` needs for a sandboxed run (checked against `codex exec --help`). */
+export declare const CODEX_REQUIRED_FLAGS: readonly ["--sandbox", "workspace-write", "--skip-git-repo-check", "--json", "--cd"];
+export declare function inspectClaude(env: Env): Promise<LocalAgent | undefined>;
+export declare function inspectCodex(env: Env): Promise<LocalAgent | undefined>;
+export interface Candidate {
+    runner: Runner;
+    agent?: LocalAgent;
+}
+/**
+ * The agents to try, in order: this computer's Claude Code, then its Codex, then the account's cloud Claude in the
+ * machine VM. When one stops for a reason the next would not hit (a usage limit, a sign-in that expired, a sandbox that
+ * keeps shard from the VM, a crash, its time box), the next one runs. `--agent` names exactly one.
+ */
+export declare function runnerChain(claude: LocalAgent | undefined, codex: LocalAgent | undefined, forced?: Runner): {
+    chain: Candidate[];
+    skipped: string[];
+};
+/** Every agent gets its own time box, and all of them together at most twice it: the apps wait 30 minutes. */
+export declare const AGENT_BUDGET_FACTOR = 2;
+export declare function attemptTimeout(perAgentMs: number, spentMs: number): number | undefined;
+/** Read-only commands a local Claude may run on this computer (each a prefix rule). No cat: file reads go through Read, where the secret paths are denied. */
+export declare const READ_ONLY_COMMANDS: readonly ["brew list", "brew leaves", "brew info", "brew --prefix", "brew --version", "ls", "which", "command -v", "uname", "sw_vers", "git config --global --get", "git config --global --list", "git config --get", "git config --list", "npm ls -g", "npm list -g", "pnpm ls -g", "pipx list", "uv tool list", "gem list", "cargo install --list", "gh extension list", "asdf current", "asdf list", "mise ls", "mise current", "pyenv versions", "rbenv versions", "fnm list", "volta list"];
+/** Tools whose `--version` (or `version`) a local Claude may print. */
+export declare const VERSION_TOOLS: readonly ["node", "npm", "pnpm", "yarn", "bun", "deno", "python3", "python", "pip3", "uv", "go", "rustc", "cargo", "ruby", "java", "php", "dotnet", "git", "gh", "docker", "kubectl", "terraform", "aws", "gcloud", "zsh", "bash", "fish", "tmux", "nvim", "vim", "starship", "mise", "asdf"];
+/** Never read on this computer, whatever the agent decides: keys, tokens, cloud and package-registry credentials, keychains, browser and app data. */
+export declare const SECRET_PATHS: readonly ["~/.ssh/**", "~/.aws/**", "~/.azure/**", "~/.config/gcloud/**", "~/.kube/**", "~/.docker/**", "~/.gnupg/**", "~/.password-store/**", "~/Library/**", "~/.local/share/keyrings/**", "~/.config/op/**", "~/.config/gh/**", "~/.config/hub", "~/.config/shardflux/**", "~/.netrc", "~/.git-credentials", "~/.npmrc", "~/.yarnrc.yml", "~/.pypirc", "~/.gem/credentials", "~/.cargo/credentials", "~/.cargo/credentials.toml", "~/.vault-token", "~/.terraform.d/**", "~/.claude.json", "~/.claude/.credentials.json", "~/.codex/auth.json", "~/.mozilla/**", "~/.config/google-chrome/**", "//**/.env", "//**/.env.*", "//**/*.pem", "//**/*.key", "//**/*.p12", "//**/*.pfx", "//**/id_rsa*", "//**/id_ed25519*", "//**/id_ecdsa*", "//**/*credentials*", "//**/*secret*", "//**/*token*"];
+/** `claude` argv for the restricted run (the task goes on standard input). `help` is the installed version's `--help`. */
+export declare function claudeArgs(key: string, help: string): string[];
+/** `codex exec` argv: writes only in `workDir` (and temp folders), network on for `shard`, the task on standard input. */
+export declare function codexArgs(workDir: string, help: string): string[];
+/**
+ * While `SHARDFLUX_MACHINE_SETUP_VM` is set (the setup agent's own commands), shard only runs commands on that VM: exec,
+ * file writes from standard input, reads and listings. Returns the refusal, or undefined when the command may run.
+ */
+export declare function setupGuard(env: Env, command: string, values: Values, positionals: string[]): string | undefined;
+export interface Inventory {
+    os: string;
+    shell: string | null;
+    homebrew: string[] | null;
+    runtimes: Record<string, string>;
+    version_files: Record<string, string>;
+    version_managers: string[];
+    clis: string[];
+    npm_globals: string[];
+    git: {
+        name?: string;
+        email?: string;
+    };
+    dotfiles: string[];
+}
+/** What is on this computer, without contents that could hold a secret: names, versions, the git identity. */
+export declare function collectInventory(env: Env): Promise<Inventory>;
+/** Skills this computer's config copy brings to the machine: ~/.claude/skills and ~/.codex/skills (not Codex's bundled .system). */
+export declare function countSkills(home: string): number;
+/**
+ * The fixed task: agent-setup.ts's "Build the machine" step, extended to recreate this computer. `where` is 'local' for
+ * an agent on this computer (it reaches the VM through shard) or 'vm' for the cloud Claude inside the machine VM.
+ */
+export declare function setupTask(where: 'local' | 'vm', key: string, inventory: Inventory): string;
+export interface SetupSummary {
+    tools: string[];
+    runtimes: string[];
+    shell: string | null;
+    dotfiles: string[];
+    skipped: Array<{
+        item: string;
+        reason: string;
+    }>;
+}
+/** The last JSON object in the agent's final message (a fenced block or bare), normalised. */
+export declare function parseSummary(text: string): SetupSummary | undefined;
+/** "Cloud machine ready: gh, Node 24, Python 3.13, 12 skills": what a person recognises, at most 80 characters. */
+export declare function readyLine(summary: SetupSummary | undefined, skills: number): string;
+export declare function workingLine(runner: Runner): string;
+export declare function failedLine(message: string): string;
+export interface SetupRecord {
+    state: 'running' | 'ready' | 'failed';
+    runner: Runner | null;
+    pid: number | null;
+    started_at: string;
+    finished_at: string | null;
+    machine_version: number | null;
+    line: string;
+    summary: (SetupSummary & {
+        skills: number;
+        runner: Runner;
+    }) | null;
+    /** Each agent tried, in order (0.20.0+): the one that set the machine up last, with ok. */
+    attempts?: Attempt[];
+    error: string | null;
+    duration_ms: number | null;
+}
+export interface Attempt {
+    runner: Runner;
+    ok: boolean;
+    error: string | null;
+    duration_ms: number;
+}
+export declare function readRecord(store: AgentStateStore, apiUrl: string, org: string): SetupRecord | undefined;
+/**
+ * Claims the run under agents.json's lock: a live run is never doubled; with `ifNeeded` a machine already set up from
+ * this computer is left alone.
+ */
+export declare function claimRun(store: AgentStateStore, apiUrl: string, org: string, ifNeeded: boolean, start: SetupRecord): {
+    claimed: true;
+} | {
+    claimed: false;
+    record: SetupRecord;
+};
+/**
+ * Whether the agent reached the machine VM at all: every shard command it ran failed (a sandbox without network, a
+ * permission it was never given) means nothing was set up, whatever its reply says, and the next agent should try.
+ */
+export declare class ShardReach {
+    private calls;
+    private ok;
+    private firstError;
+    record(succeeded: boolean, output?: string): void;
+    check(app: string): void;
+}
+export interface SetupDeps {
+    inspectClaude?: typeof inspectClaude;
+    inspectCodex?: typeof inspectCodex;
+    inventory?: typeof collectInventory;
+    open?: (ctx: Ctx, state: AgentFilesystem) => Promise<{
+        state: AgentFilesystem;
+        ws: Workspace;
+    }>;
+}
+export declare function machineSetup(ctx: Ctx, values: Values, deps?: SetupDeps): Promise<number>;
+/**
+ * Starts `shard machine setup --from-this-computer --if-needed --json` detached (the terminal onboarding, right after
+ * its Agents step): its output goes to machine-setup.out in the config directory. Returns false without a runtime.
+ */
+export declare function startMachineSetupInBackground(ctx: Ctx): boolean;
+export declare const MACHINE_SETUP_HANDLERS: Record<string, Handler>;
+export {};