setup-agent 0.0.3 → 0.0.5

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,7 +13,8 @@ import {
   isAgentPresent,
   isClosed,
   isOptionIcon,
-  parseModelAnswer,
+  isValidModelAnswer,
+  parseEntryPointOptions,
   parseMultipleAnswer,
   stepProgress,
 } from "./protocol";
@@ -29,17 +29,16 @@ Commands (the url always comes first):
   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 [prompt] --preset <framework|llm-provider> [--only <id,id>] [--choices <id=description,...>] [--default <id>] [--optional] [--step <step-id>] [--wait]
+                                    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]
                                     Ask the user to pick from your own options; they may also type their own answer.
                                     The user checks any number of options and the answer is a JSON array of option ids (their own text is one entry).
                                     --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 setup, such as one another product needs first. Answers "added"; the product and its guide then appear in "status".
+  ask <prompt> --entry-points '<JSON array>' [--default <id>] [--optional] [--step <step-id>] [--wait]
+                                    Ask where users should access the assistant. Each of 1–3 options has id, label, description and entryPoint {formFactor: modal|sidebar|full-page, placement, trigger, recommended?}. Answers one option id.
   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]
@@ -55,7 +54,7 @@ Commands (the url always comes first):
                                     Mark every remaining step done and propose closing; the user closes it.
 `;
 
-export const INSTRUCTIONS = (
+export const agentInstructions = (
   url: string,
 ) => `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.
 
@@ -74,13 +73,14 @@ Keep the stream running while you wait. Do not inspect the project, fetch guides
 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
+  npx setup-agent ${url} ask "Which project should I install into?" --placeholder "An absolute path to the 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 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 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.
+The setup's products are starting names and guide references. Explore each product's setup instructions, then discover and plan any other relevant products or dependencies the app needs. Read /catalog.md on the guide URL’s origin to find related products and fetch their setup guides. The starting list does not restrict the implementation or require adding another product to the list. Include relevant additions in the plan for approval.
+When the setup puts an assistant in the app, ask how users should access it after discovering the actual app and before proposing the plan. Skip this question when no product's guide installs an assistant (a standalone library or service setup, for example). Use an entry-point question with only 1–3 sensible alternatives. Describe the actual app's pages, workflow and component placement, not generic placeholder copy. Recommend one clear fit when there is one; two options may use the same form factor in different places. Each option needs a stable id, label, contextual description and entryPoint {"formFactor":"modal"|"sidebar"|"full-page","placement":"where it appears","trigger":"how users open it or navigate to it","recommended":true?}. Write the JSON array for this app and send it with:
+  npx setup-agent ${url} ask "Where should users access the assistant?" --entry-points '<JSON array>' --wait
+Mark a clear fit with "recommended":true rather than --default, so the user makes the pick. When you ask it, do not submit the plan before the user picks an entry point. Respect the selected placement and trigger in the plan and implementation. Do not ask for a new-versus-existing app setting; discover the app from its files and ask only for an install path when needed.
 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
@@ -100,6 +100,8 @@ Before that, start the project's dev server in the background when the project h
 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.
 `;
 
+export const INSTRUCTIONS = agentInstructions;
+
 type Parsed = { positional: string[]; flags: Map<string, string | true> };
 
 const parseArgs = (argv: readonly string[]): Parsed => {
@@ -507,6 +509,52 @@ export const askSeed = (
   const stepId = flagText(flags, "step");
   const optional = flags.has("optional");
   const fallback = flagText(flags, "default");
+  if (flags.has("entry-points")) {
+    if (
+      [
+        "preset",
+        "product",
+        "choices",
+        "icons",
+        "multiple",
+        "single",
+        "only",
+        "placeholder",
+      ].some((flag) => flags.has(flag))
+    )
+      return fail(
+        "--entry-points cannot be combined with other input kinds, --multiple, --single or --only",
+      );
+    const json = flagText(flags, "entry-points");
+    let value: unknown;
+    try {
+      value = JSON.parse(json ?? "");
+    } catch {
+      return fail("--entry-points needs a JSON array of options");
+    }
+    const options = parseEntryPointOptions(value);
+    if (!options)
+      return fail(
+        "--entry-points needs 1–3 unique options with id, label, description and entryPoint {formFactor, placement, trigger, recommended?}; at most one is recommended",
+      );
+    if (
+      fallback !== undefined &&
+      !options.some((option) => option.id === fallback)
+    )
+      return fail(`no option "${fallback}" to default to`);
+    const prompt =
+      rest[0] ?? fail("usage: ask <prompt> --entry-points '<JSON array>'");
+    if (prompt.trim() === "")
+      return fail("an entry-point prompt cannot be empty");
+    return {
+      kind: "entry-point",
+      prompt,
+      options,
+      ...(fallback !== undefined && { default: fallback }),
+      optional,
+      ...(stepId !== undefined && { stepId }),
+    };
+  }
   const preset = flagText(flags, "preset");
   if (preset !== undefined) {
     if (!isPresetId(preset)) {
@@ -586,18 +634,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 }),
@@ -738,27 +818,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;
       }

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

@@ -9,16 +9,23 @@ export type CheckoutClient = StatewireClient<
 /** 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(
             `setup unreachable: ${client.connection.reason}${
               client.connection.message ? ` (${client.connection.message})` : ""
@@ -27,6 +34,7 @@ export const connectCheckout = (url: string): Promise<CheckoutClient> =>
         );
         return;
       }
+      settled = true;
       unsubscribe();
       resolve(client);
     };