setup-agent 0.0.2 → 0.0.4

package/src/cli.ts

@@ -1,9 +1,8 @@
-/// <reference types="node" />
 import { connectCheckout } from "./client";
 import type { CheckoutClient } from "./client";
 import { INPUT_PRESETS, isPresetId, presetInput } from "./presets";
 import { spawn } from "node:child_process";
-import { readFile, writeFile } from "node:fs/promises";
+import { open, readFile } from "node:fs/promises";
 import { createInterface } from "node:readline/promises";
 import { resolve } from "node:path";
 import {
@@ -14,23 +13,23 @@ import {
   isAgentPresent,
   isClosed,
   isOptionIcon,
-  parseModelAnswer,
+  isValidModelAnswer,
   parseMultipleAnswer,
   stepProgress,
 } from "./protocol";
 import type { Checkout } from "./protocol";
 
-const HELP = `setup-agent <url> [command]
+export const HELP = `setup-agent <url> [command]
 
 Commands (the url always comes first):
-  status                            Print the checkout as JSON.
-  stream                            Follow the checkout: one JSON array of events per line.
+  status                            Print the setup as JSON.
+  stream                            Follow the setup: one JSON array of events per line.
   log <text>                        Send a message to the user: a reply, something no question or step conveys, or one wrap-up when finished.
   ack <message-id>                  Acknowledge a user message.
   ask <prompt> [--placeholder <text>] [--optional] [--step <step-id>] [--wait]
                                     Ask the user for a line of text.
   ask [prompt] --preset <framework|llm-provider|project> [--only <id,id>] [--choices <id=description,...>] [--default <id>] [--optional] [--step <step-id>] [--wait]
-                                    Ask a standard question. --only restricts the options (one id locks it in); --default preselects one.
+                                    Ask a standard question. --only restricts the options and leaves out --choices (one id locks it in); --default preselects one.
                                     "framework" answers "<framework>:<language>"; "llm-provider" answers JSON with provider, model and reasoningEffort; the key itself arrives through "env".
                                     "project" lists the React projects you found as --choices "<path>=<what it is>,..." ahead of "New project"; it answers a path, or "new:<next|vite|react-router|tanstack-start|expo>".
   ask <prompt> --choices <id,id,...> --icons <id=icon,...> [--single] [--default <id>] [--optional] [--step <step-id>] [--wait]
@@ -39,8 +38,8 @@ Commands (the url always comes first):
                                     --single is for options that exclude each other (one framework, one model, yes or no); the answer is then one id.
                                     --icons is required and names an icon for every option, from: ${OPTION_ICONS.join(", ")}.
   ask <prompt> --product <slug> [--wait]
-                                    Propose adding a product to this checkout, such as one another product needs first. Answers "added"; the product and its guide then appear in "status".
-  wait start                        Block until the user clicks Begin plan in their browser; after a finished or cancelled checkout, until the next one begins.
+                                    Propose adding a product to this setup, such as one another product needs first. Answers "added"; the product and its guide then appear in "status".
+  wait start                        Block until the user clicks Begin plan in their browser; after a finished or cancelled setup, until the next one begins.
   wait <input-id>                   Block until the user answers or dismisses an input. A multi-select answer prints as an array.
   plan (<markdown> | --file <path>) [--wait]
                                     Propose the plan for the user to approve. --wait blocks until they decide.
@@ -55,19 +54,19 @@ Commands (the url always comes first):
                                     Mark every remaining step done and propose closing; the user closes it.
 `;
 
-const INSTRUCTIONS = (
+export const INSTRUCTIONS = (
   url: string,
-) => `You are the coding agent for a checkout the user opened in their browser. The browser shows this checkout live; every command below updates it. The user watches the browser, not this terminal: once setup begins, send questions through "ask" so the user can answer in their browser.
+) => `You are the coding agent for a setup the user opened in their browser. The browser shows this setup live; every command below updates it. The user watches the browser, not this terminal: once setup begins, send questions through "ask" so the user can answer in their browser.
 
 First, start a persistent Monitor on
   npx setup-agent ${url} stream
-and keep it running: the browser shows you as connected only while it runs, and it is how answers reach you. The URL is the user's link to you from their browser, not one checkout: it outlives this setup, and their next setup arrives on the same stream. Each line is a JSON array of events: "planning.started", "input.answered" ({inputId, answer, note?}; answer is an array for a choice question not asked with --single), "input.dismissed", "plan.approved", "plan.changes-requested" ({feedback}), "message.created" ({messageId, text}), "finished", "cancelled", "checkout.created" ({products}).
+and keep it running: the browser shows you as connected only while it runs, and it is how answers reach you. The URL is the user's link to you from their browser, not one setup: it outlives this one, and their next setup arrives on the same stream. Each line is a JSON array of events: "planning.started", "input.answered" ({inputId, answer, note?}; answer is an array for a choice question not asked with --single), "input.dismissed", "plan.approved", "plan.changes-requested" ({feedback}), "message.created" ({messageId, text}), "finished", "cancelled", "setup.created" ({products}).
 
 The user can message you at any time, including while a question is waiting. Read "message.created" events, acknowledge each with "npx setup-agent ${url} ack <message-id>", and reply using "log" with what you will do. Pending messages are replayed when the stream starts and listed in "status". A message is not an answer or plan approval; keep those decisions explicit.
 
 "log" is a message to the user, and the user reads every one: send it only to reply to their message, to tell them something no question or step conveys (a blocker, a deviation from the plan, a decision you made for them), or once as a wrap-up when the install is finished. Findings go in the plan, progress in step notes, questions in "ask"; do not narrate.
 
-Before planning, check the current checkout status. If it is "waiting", tell the user in your own conversation: "I'm connected. Go back to your browser and click Begin plan. You can watch my progress, answer questions, and steer me there." Then run:
+Before planning, check the current setup status. If it is "waiting", tell the user in your own conversation: "I'm connected. Go back to your browser and click Begin plan. You can watch my progress, answer questions, and steer me there." Then run:
   npx setup-agent ${url} wait start
 Keep the stream running while you wait. Do not inspect the project, fetch guides, ask setup questions, or propose a plan until this command returns {"ok":true}. Only the user in the browser should start planning; never invoke the browser's start command yourself. "planning.started" also arrives on the stream. If the status is already "planning" or "installing", resume that phase without asking the user to begin again. If it is "done" or "cancelled", that setup is over: tell the user you are connected and waiting for their next setup, and run "wait start", which returns once the next one begins.
 
@@ -75,16 +74,16 @@ The remaining phases are plan, then install.
 
 1. Plan. Investigate only; change nothing yet. If the current directory is not an app to install into (a monorepo root, an empty folder, a library), ask where to install first:
   npx setup-agent ${url} ask "Which project should I install into?" --placeholder "An absolute path, or a path for a new Next.js app" --wait
-Read the project: its app framework and package manager, the agent framework and model provider it already uses, where components live, any existing chat route. Fetch each product's "guide" URL from the checkout below; it is the install reference. Ask for what the project does not decide, using the standard questions so the browser can render them well:
+Read the project: its app framework and package manager, the agent framework and model provider it already uses, where components live, any existing chat route. Fetch each product's "guide" URL from the setup below; it is the install reference. Ask for what the project does not decide, using the standard questions so the browser can render them well:
   npx setup-agent ${url} ask --preset framework
   npx setup-agent ${url} ask --preset llm-provider
-If a product's guide needs another product the project does not have yet (most need assistant-ui installed and rendering a thread), do not stop and do not install it on the side. Propose adding it to this checkout:
+If a product's guide needs another product the project does not have yet (most need assistant-ui installed and rendering a thread), do not stop and do not install it on the side. Propose adding it to this setup:
   npx setup-agent ${url} ask "assistant-ui is not installed in this project yet. Add it to this setup?" --product assistant-ui --wait
 On "added", run "status", fetch the new product's guide, and install it first in your plan. If the user dismisses it, follow what the guide says about the missing product.
 Skip a preset the code already answers (a chat route on the AI SDK, a provider key in .env.local) and log why. Ask everything at once, keep investigating, and block with "wait <input-id>" only when nothing else can proceed. A framework answer is "<framework>:<language>", for example "ai-sdk:typescript". A model answer is JSON {"provider","model","reasoningEffort"?}. An answer may carry a "note" from the user; follow it. A choice answer that matches none of the options is the user's own text.
 Then write the plan as markdown and submit it:
   npx setup-agent ${url} plan --file <path> --wait
-Use these headings, each with bullets: "## What I found" (facts as \`- **Label:** value\`: app framework, package manager, agent framework, model provider and model, where components live), "## What I will install" (packages and files, one per bullet), "## Steps" (a numbered list, one line each), and "## Open questions" only if any remain. Keep it under 30 lines; no preamble. "plan --wait" prints {"decision":"approve"} or {"decision":"revise","feedback":"..."}. On revise, address the feedback (ask again if you need to) and submit a new plan; repeat until approved. Do not change the project before approval: the checkout refuses steps until then.
+Use these headings, each with bullets: "## What I found" (facts as \`- **Label:** value\`: app framework, package manager, agent framework, model provider and model, where components live), "## What I will install" (packages and files, one per bullet), "## Steps" (a numbered list, one line each), and "## Open questions" only if any remain. Keep it under 30 lines; no preamble. "plan --wait" prints {"decision":"approve"} or {"decision":"revise","feedback":"..."}. On revise, address the feedback (ask again if you need to) and submit a new plan; repeat until approved. Do not change the project before approval: the setup refuses steps until then.
 
 2. Install. Declare the steps from your plan up front, in order:
   npx setup-agent ${url} add-step "<title>" --detail "<one line>"
@@ -95,9 +94,9 @@ which writes ENV_VAR=<key> into that file. Use the answer's model in the chat ro
 
 When every product is installed and verified, run
   npx setup-agent ${url} done --summary "<one or two lines on what you installed and how to try it>" --preview http://localhost:<port>
-Before that, start the project's dev server in the background when the project has one, check that the page you changed loads, and pass the address as --preview (the page itself when it is not the root); leave the server running so the user can try the result. Omit --preview when there is nothing to open. This proposes closing the checkout; only the user closes it. Do not stop the stream or exit: stay idle on it, because the user may follow up with a "message.created" event. Handle it, then run "done" again. The stream prints "finished" once the user closes the checkout, and "cancelled" if they end it early. Keep the stream running after either: the user's next setup starts on this same URL and arrives as "checkout.created" with its products. Run
+Before that, start the project's dev server in the background when the project has one, check that the page you changed loads, and pass the address as --preview (the page itself when it is not the root); leave the server running so the user can try the result. Omit --preview when there is nothing to open. This proposes closing the setup; only the user closes it. Do not stop the stream or exit: stay idle on it, because the user may follow up with a "message.created" event. Handle it, then run "done" again. The stream prints "finished" once the user closes the setup, and "cancelled" if they end it early. Keep the stream running after either: the user's next setup starts on this same URL and arrives as "setup.created" with its products. Run
   npx setup-agent ${url} wait start
-which returns once that setup begins, then run "status" for its products, guides and instructions and go through plan and install again. A "checkout.created" event while you are still working means the user replaced this setup: drop what you were doing and start over the same way.
+which returns once that setup begins, then run "status" for its products, guides and instructions and go through plan and install again. A "setup.created" event while you are still working means the user replaced this setup: drop what you were doing and start over the same way.
 `;
 
 type Parsed = { positional: string[]; flags: Map<string, string | true> };
@@ -251,7 +250,7 @@ const launchAgent = async (url: string) => {
 };
 
 const requireState = (client: CheckoutClient): Checkout.State =>
-  client.state ?? fail("the checkout has no state");
+  client.state ?? fail("the setup has no state");
 
 const summary = (state: Checkout.State) => {
   const plan = currentPlan(state);
@@ -304,7 +303,7 @@ type StreamEvent =
   | { event: "plan.changes-requested"; revision: number; feedback: string }
   | { event: "finished"; next: string }
   | { event: "cancelled"; next: string }
-  | { event: "checkout.created"; products: string[] };
+  | { event: "setup.created"; products: string[] };
 
 const STAY_CONNECTED =
   "This setup is over, not your connection. Keep the stream running, tell the user you are connected and waiting for their next setup, and run wait start.";
@@ -376,7 +375,7 @@ export const diffEvents = (
   }
   if (after.id !== null && after.id !== before.id) {
     events.push({
-      event: "checkout.created",
+      event: "setup.created",
       products: after.products.map((product) => product.slug),
     });
   }
@@ -425,7 +424,7 @@ const stream = async (client: CheckoutClient) => {
   await new Promise(() => {});
 };
 
-/** 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. */
+/** Resolves once a setup is planning or installing, or once the one being waited on is cancelled; a setup already closed when the wait begins is over, so the wait is for the next one. */
 export const waitForStart = (
   client: Pick<CheckoutClient, "state" | "subscribe">,
 ) =>
@@ -586,18 +585,50 @@ export const askSeed = (
   };
 };
 
+const assertEnvKey = (key: string) => {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+    throw new Error(`"${key}" is not an environment variable name`);
+  }
+};
+
 /** Sets `key=value` in dotenv text, replacing an existing line for the key. */
 export const upsertEnvLine = (content: string, key: string, value: string) => {
+  assertEnvKey(key);
   const line = `${key}=${value}`;
   const lines = content === "" ? [] : content.replace(/\n$/, "").split("\n");
-  const index = lines.findIndex((entry) =>
-    new RegExp(`^(export\\s+)?${key}\\s*=`).test(entry),
+  const index = lines.findIndex(
+    (entry) =>
+      /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(entry)?.[1] === key,
   );
   if (index === -1) lines.push(line);
   else lines[index] = line;
   return `${lines.join("\n")}\n`;
 };
 
+/**
+ * Write the secret `take` returns to `file` under `key`, leaving the file
+ * owner-only. The file is opened before `take` runs, because taking the
+ * secret consumes it and an unwritable destination must fail while it is
+ * still deposited; it is read after, so lines written meanwhile survive.
+ */
+export const writeEnvSecret = async (
+  file: string,
+  key: string,
+  take: () => Promise<string>,
+) => {
+  assertEnvKey(key);
+  const handle = await open(file, "a+", 0o600);
+  try {
+    await handle.chmod(0o600);
+    const value = await take();
+    const current = await handle.readFile("utf8");
+    await handle.truncate(0);
+    await handle.writeFile(upsertEnvLine(current, key, value));
+  } finally {
+    await handle.close();
+  }
+};
+
 const answerFields = (input: Checkout.Input, answer: string) => ({
   answer: (input.multiple && parseMultipleAnswer(answer)) || answer,
   ...(input.note !== undefined && { note: input.note }),
@@ -637,7 +668,7 @@ export const main = async (argv: readonly string[]) => {
           ...(kind !== undefined && { kind }),
         }).catch(() => {});
         process.stdout.write(INSTRUCTIONS(url));
-        process.stdout.write("\nCurrent checkout:\n");
+        process.stdout.write("\nCurrent setup:\n");
         print(summary(requireState(client)));
         break;
       }
@@ -738,27 +769,36 @@ export const main = async (argv: readonly string[]) => {
         if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(envKey)) {
           fail(`"${envKey}" is not an environment variable name`);
         }
+        const state = requireState(client);
         const input =
-          requireState(client).inputs.find(
-            (candidate) => candidate.id === inputId,
-          ) ?? fail(`no input "${inputId}"`);
+          state.inputs.find((candidate) => candidate.id === inputId) ??
+          fail(`no input "${inputId}"`);
+        const setupId = state.id ?? fail("the setup has not been created yet");
+        if (isClosed(state)) {
+          fail("the setup is not open");
+        }
         if (input.status !== "answered") {
           fail(`input "${inputId}" is ${input.status}`);
         }
-        if (parseModelAnswer(input.answer ?? "") === undefined) {
+        if (
+          input.kind !== "model" ||
+          !isValidModelAnswer(input, input.answer ?? "")
+        ) {
           fail(`input "${inputId}" is not an llm-provider answer`);
         }
         const file = resolve(flagText(flags, "file") ?? ".env.local");
-        const response = await fetch(
-          `${url.replace(/\/$/, "")}/secret/${encodeURIComponent(inputId)}`,
-        );
-        if (response.status === 404) {
-          fail(`the key for "${inputId}" was already taken or never deposited`);
-        }
-        if (!response.ok) fail(`could not fetch the key: ${response.status}`);
-        const value = await response.text();
-        const current = await readFile(file, "utf8").catch(() => "");
-        await writeFile(file, upsertEnvLine(current, envKey, value));
+        await writeEnvSecret(file, envKey, async () => {
+          const response = await fetch(
+            `${url.replace(/\/$/, "")}/secret/${encodeURIComponent(inputId)}?setup=${encodeURIComponent(setupId)}`,
+          );
+          if (response.status === 404) {
+            fail(
+              `the key for "${inputId}" was already taken or never deposited`,
+            );
+          }
+          if (!response.ok) fail(`could not fetch the key: ${response.status}`);
+          return response.text();
+        });
         print({ ok: true, envKey, file });
         break;
       }
@@ -784,7 +824,7 @@ export const main = async (argv: readonly string[]) => {
         print({
           ok: true,
           status: "proposed",
-          next: "Keep the stream running and stay idle. The user closes the checkout or sends a follow-up message.",
+          next: "Keep the stream running and stay idle. The user closes the setup or sends a follow-up message.",
         });
         break;
       }

package/src/client.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it, vi } from "vitest";
+import { connectCheckout } from "./client";
+
+const { created } = vi.hoisted(() => ({
+  created: [] as {
+    options: { onError: (error: unknown) => void };
+    state: unknown;
+    listener: () => void;
+    dispose: ReturnType<typeof vi.fn>;
+    unsubscribe: ReturnType<typeof vi.fn>;
+  }[],
+}));
+
+vi.mock("statewire", async (importOriginal) => ({
+  ...(await importOriginal()),
+  StatewireHttp: () => ({}),
+  StatewireClient: class {
+    state: unknown = undefined;
+    listener = () => {};
+    connection = { status: "connecting" };
+    dispose = vi.fn();
+    unsubscribe = vi.fn();
+    options: { onError: (error: unknown) => void };
+    constructor(options: { onError: (error: unknown) => void }) {
+      this.options = options;
+      created.push(this);
+    }
+    subscribe = (listener: () => void) => {
+      this.listener = listener;
+      return this.unsubscribe;
+    };
+  },
+}));
+
+describe("connectCheckout", () => {
+  it("disposes the client when the first connection fails", async () => {
+    const connecting = connectCheckout("https://checkout.test/session");
+    const client = created.at(-1)!;
+    client.options.onError(new Error("offline"));
+    await expect(connecting).rejects.toThrow("offline");
+    expect(client.unsubscribe).toHaveBeenCalled();
+    expect(client.dispose).toHaveBeenCalled();
+  });
+
+  it("keeps the client it resolved with when a later error arrives", async () => {
+    const connecting = connectCheckout("https://checkout.test/session");
+    const client = created.at(-1)!;
+    client.state = {};
+    client.listener();
+    await expect(connecting).resolves.toBe(client);
+    client.options.onError(new Error("later"));
+    expect(client.dispose).not.toHaveBeenCalled();
+  });
+});

package/src/client.ts

@@ -6,27 +6,35 @@ export type CheckoutClient = StatewireClient<
   Checkout.Commands
 >;
 
-/** Attach to a checkout by its base URL and resolve once its state has arrived. */
+/** Attach to a setup by its base URL and resolve once its state has arrived. */
 export const connectCheckout = (url: string): Promise<CheckoutClient> =>
   new Promise((resolve, reject) => {
+    let settled = false;
+    const fail = (error: unknown) => {
+      if (settled) return;
+      settled = true;
+      unsubscribe();
+      client.dispose();
+      reject(error);
+    };
     const client: CheckoutClient = new StatewireClient({
       transport: StatewireHttp({ url }),
-      onError: (error) => reject(error),
+      onError: fail,
     });
     const settle = () => {
+      if (settled) return;
       if (client.state === undefined) {
         if (client.connection.status !== "stopped") return;
-        unsubscribe();
-        client.dispose();
-        reject(
+        fail(
           new Error(
-            `checkout unreachable: ${client.connection.reason}${
+            `setup unreachable: ${client.connection.reason}${
               client.connection.message ? ` (${client.connection.message})` : ""
             }`,
           ),
         );
         return;
       }
+      settled = true;
       unsubscribe();
       resolve(client);
     };