setup-agent 0.0.1

package/README.md

@@ -0,0 +1,38 @@
+# setup-agent
+
+One checkout, shared live between the browser that opened it and the coding agent installing its products. The state is a Statewire host (`setup-agent/host`) served from a Cloudflare Durable Object (`apps/checkout-worker`); the CLI (`npx setup-agent <url>`) is a thin Statewire client the agent drives from its shell.
+
+```sh
+npx setup-agent <url>              # instructions plus the current checkout
+npx setup-agent <url> stream       # one JSON array of events per line; run it under a Monitor
+npx setup-agent <url> wait start   # wait for the user to click Begin plan in their browser
+npx setup-agent <url> log "Sure, I will keep the existing chat route"   # a reply, or something no question or step conveys
+npx setup-agent <url> ask --preset llm-provider --only openai,anthropic --default openai
+npx setup-agent <url> ask "Where should assistant-ui live?" --optional   # keep working; the answer arrives on the stream
+npx setup-agent <url> ask "Which integrations?" --choices slack,email --icons "slack=message,email=mail"   # multi-select; answers ["slack","email"]
+npx setup-agent <url> ask "Which package manager?" --choices pnpm,npm --icons "pnpm=package,npm=package" --single   # the options exclude each other; answers "pnpm"
+npx setup-agent <url> wait q1      # block only when nothing else can proceed
+npx setup-agent <url> plan --file plan.md --wait   # {"decision":"approve"} or {"decision":"revise","feedback":"..."}
+npx setup-agent <url> add-step "Install the packages" --detail "pnpm add ..." --active   # prints {"stepId":"s1"}
+npx setup-agent <url> step s1 done --note "installed"
+npx setup-agent <url> env q2 OPENAI_API_KEY --file .env.local   # write the key behind a model answer without seeing it
+npx setup-agent <url> done --summary "installed the thread and a chat route" --preview http://localhost:3000
+```
+
+## Phases
+
+A checkout opens `waiting` with its products and nothing else: no steps, no questions. After connecting, the agent tells the user to return to their browser and click **Begin plan**. It keeps the stream running and blocks on `wait start`. The browser sends `checkout/begin-plan`, moving the checkout to `planning` and emitting `planning.started` on the stream. Questions and plan submissions are refused while waiting. When a product needs another one the project lacks, the agent proposes it with `ask "<why>" --product <slug>`; the browser, which owns the catalog, accepts with `checkout/add-product` (the product and its guide join `products`, the input answers `added`) or dismisses the input. In `planning`, the agent investigates the project, asks what the code does not decide, and proposes a markdown plan with `plan` carrying its findings. `log` is for replying to the user and for what no question or step conveys. The user approves the plan or asks for changes with feedback; every revision is kept. Approval moves the checkout to `installing`, where the agent declares its own steps with `add-step` and works through them with `step`. `add-step` and `step` are refused before approval. `done` marks the remaining steps done and proposes closing, with an optional `--summary` and an optional `--preview <url>` naming a dev server the agent left running; a preview must be an http(s) URL on localhost, and the browser offers to open it. `done` does not close. The browser shows the proposal with a close action that sends `checkout/finish`, and the stream prints `finished`. Until then the agent stays idle on the stream, because the user may send a follow-up message; after handling one it runs `done` again to renew the proposal.
+
+The URL is the browser's link to its agent, not one checkout. A finished or cancelled checkout stays on the link, and the browser's next setup replaces it with a new `checkout/create` carrying a new `id`: the plans, steps, inputs and log start over, the agent's presence carries across when it is still connected, and the stream prints `checkout.created` with the new products. The agent keeps the stream running after `finished` or `cancelled` and blocks on `wait start`, which returns once the next checkout begins planning; a checkout already closed when the wait begins is skipped rather than reported.
+
+## Inputs
+
+Every input is `text`, `choice` or `model`. A choice carries `options` (`id`, `label`, `description`, `icon`, `variants`), an optional `default` and a `help` note the browser renders as a "help me choose" disclosure. The answer is the option id, `<option>:<variant>` when the option has variants (`langgraph:python`), or the user's own text when none of the options fit; the stream marks that answer `custom`. An agent's own choice is multi-select unless asked with `--single`: the user checks any number of options (none may have variants), and the answer is a JSON array of those entries, which `wait` and the stream print as an array and `status` holds as text. `--single` is for options that exclude each other (one framework, one model, yes or no) and answers one id. Every one of the agent's own options must carry an `icon` from the pack `OPTION_ICONS` exports (`--icons "slack=message,email=mail"`); the CLI refuses the question otherwise. A preset option carries a brand mark instead. Every answer may carry a `note` from the user. A model input lists providers as its options; the browser collects the provider, its API key, the model and an optional reasoning effort, and the answer is that object as JSON (`{"provider","model","reasoningEffort"?}`); the API key is deposited separately and only ever reaches the env file the agent names through `env`.
+
+Three standard choices ship as presets (`setup-agent` exports `INPUT_PRESETS` and `presetInput`), so the browser and the CLI agree on their options and brand marks:
+
+- `framework`: Vercel AI SDK, Mastra, LangGraph, each with its language.
+- `llm-provider`: OpenAI, Anthropic, Google Gemini, OpenRouter, xAI, Mistral, DeepSeek, Groq, Fireworks AI; defaults to OpenAI. Rendered as the model picker (provider, key, model, reasoning effort).
+- `project`: the React projects the agent found, passed as `--choices "apps/web=Next.js,apps/admin"`, ahead of a fixed "New project" option whose second pick is the meta framework. Answers a path, or `new:<next|vite|react-router|tanstack-start|expo>`.
+
+`--only` restricts a preset to some of its options (a single id locks the choice in) and `--default` preselects one.

package/bin/setup-agent.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from "../dist/cli.js";
+
+main(process.argv.slice(2));

package/dist/cli.d.ts

@@ -0,0 +1,64 @@
+/// <reference types="node" />
+import { Checkout } from "./protocol.js";
+import { CheckoutClient } from "./client.js";
+//#region src/cli.d.ts
+type Parsed = {
+  positional: string[];
+  flags: Map<string, string | true>;
+};
+/** The coding agent this process runs under, from the variables each one exports to its shell. */
+declare const detectAgentKind: (env?: NodeJS.ProcessEnv) => string | undefined;
+/** True when a person typed the command into a terminal rather than an agent running it from its shell. */
+declare const isDirectInvocation: (env?: NodeJS.ProcessEnv, stdin?: {
+  isTTY?: boolean | undefined;
+}, stdout?: {
+  isTTY?: boolean | undefined;
+}) => boolean;
+type StreamEvent = {
+  event: "planning.started";
+} | {
+  event: "message.created";
+  messageId: string;
+  text: string;
+} | {
+  event: "input.answered";
+  inputId: string;
+  prompt: string;
+  /** The entries of a multiple choice answer, else the answer text. */
+  answer: string | string[];
+  note?: string;
+  /** True when a choice answer is, or a multiple one contains, the user's own text rather than an option. */
+  custom?: true;
+} | {
+  event: "input.dismissed";
+  inputId: string;
+  prompt: string;
+} | {
+  event: "plan.approved";
+  revision: number;
+} | {
+  event: "plan.changes-requested";
+  revision: number;
+  feedback: string;
+} | {
+  event: "finished";
+  next: string;
+} | {
+  event: "cancelled";
+  next: string;
+} | {
+  event: "checkout.created";
+  products: string[];
+};
+declare const diffEvents: (before: Checkout.State, after: Checkout.State) => StreamEvent[];
+/** Resolves once a checkout is planning or installing, or once the one being waited on is cancelled; a checkout already closed when the wait begins is over, so the wait is for the next one. */
+declare const waitForStart: (client: Pick<CheckoutClient, "state" | "subscribe">) => Promise<Checkout.Status>;
+declare const askSeed: (rest: readonly string[], flags: Parsed["flags"]) => Checkout.InputSeed & {
+  stepId?: string;
+};
+/** Sets `key=value` in dotenv text, replacing an existing line for the key. */
+declare const upsertEnvLine: (content: string, key: string, value: string) => string;
+declare const main: (argv: readonly string[]) => Promise<undefined>;
+//#endregion
+export { askSeed, detectAgentKind, diffEvents, isDirectInvocation, main, upsertEnvLine, waitForStart };
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","names":[],"sources":["../src/cli.ts"],"mappings":";;;KAsGK;EAAW;EAAsB,OAAO;;;cA8ChC,kBAAmB,MAAK,OAAO;;cA2C/B,qBACX,MAAK,OAAO,YACZ;EAAS;GACT;EAAU;;KA8FP;EACC;;EACA;EAA0B;EAAmB;;EAE7C;EACA;EACA;;EAEA;EACA;;EAEA;;EAEA;EAA0B;EAAiB;;EAC3C;EAAwB;;EACxB;EAAiC;EAAkB;;EACnD;EAAmB;;EACnB;EAAoB;;EACpB;EAA2B;;cAKpB,aACX,QAAQ,SAAS,OACjB,OAAO,SAAS,UACf;;cAkHU,eACX,QAAQ,KAAK,2CAAsC,QAAA,SAAA;cAyExC,UACX,yBACA,OAAO,oBACN,SAAS;EAAc;;;cAoFb,gBAAiB,iBAAiB,aAAa;cA2B/C,OAAc,4BAAuB"}