setup-agent 0.0.4 → 0.0.5

package/src/cli.ts

@@ -14,6 +14,7 @@ import {
   isClosed,
   isOptionIcon,
   isValidModelAnswer,
+  parseEntryPointOptions,
   parseMultipleAnswer,
   stepProgress,
 } from "./protocol";
@@ -28,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 [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]
@@ -54,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.
 
@@ -73,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
@@ -99,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 => {
@@ -506,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)) {

package/src/host.test.ts

@@ -310,12 +310,6 @@ describe("steps", () => {
         host.commands["agent/step"]({ stepId: "nope", status: "done" }),
       ),
     ).toEqual({ reason: "unknown-step" });
-    expect(
-      await reason(
-        host.commands["agent/add-step"]({ title: "x", product: "nope" }),
-      ),
-    ).toEqual({ reason: "unknown-product" });
-
     await host.commands["agent/ask"]({ prompt: "Port?", stepId: "s2" });
     expect(await reason(host.commands["checkout/finish"]())).toEqual({
       reason: "finish-not-proposed",
@@ -776,6 +770,138 @@ describe("setup chat", () => {
   });
 });
 
+describe("entry-point questions", () => {
+  const options = [
+    {
+      id: "ticket-sidebar",
+      label: "Ticket sidebar",
+      description: "Keep the support ticket visible while drafting a reply.",
+      entryPoint: {
+        formFactor: "sidebar" as const,
+        placement: "Right side of the ticket detail page",
+        trigger: "Draft reply button in the ticket toolbar",
+        recommended: true,
+      },
+    },
+    {
+      id: "inbox-sidebar",
+      label: "Inbox sidebar",
+      description: "Draft replies from the selected ticket in the inbox.",
+      entryPoint: {
+        formFactor: "sidebar" as const,
+        placement: "Right side of the inbox",
+        trigger: "Assist button in the inbox header",
+      },
+    },
+  ];
+
+  it("persists agent-generated placements and answers by stable id across restore", async () => {
+    const host = mount();
+    await host.commands["checkout/create"](seed);
+    await host.commands["checkout/begin-plan"]();
+    const { inputId } = await host.commands["agent/ask"]({
+      kind: "entry-point",
+      prompt: "Where should support agents draft replies?",
+      options,
+      default: "ticket-sidebar",
+    });
+    expect(host.state.inputs[0]?.options).toEqual(options);
+    for (const answer of [
+      "sidebar",
+      "ticket-sidebar:variant",
+      '["ticket-sidebar"]',
+      "",
+    ]) {
+      expect(
+        await reason(host.commands["checkout/answer"]({ inputId, answer })),
+      ).toEqual({ reason: "invalid-answer" });
+    }
+    await host.commands["checkout/answer"]({
+      inputId,
+      answer: "inbox-sidebar",
+      note: "Keep the ticket list visible",
+    });
+    const restored = mount(host.snapshot());
+    expect(restored.state.inputs[0]).toMatchObject({
+      kind: "entry-point",
+      options,
+      status: "answered",
+      answer: "inbox-sidebar",
+      note: "Keep the ticket list visible",
+    });
+  });
+
+  it("rejects invalid structured inputs before they enter persisted state", async () => {
+    const host = mount();
+    await host.commands["checkout/create"](seed);
+    await host.commands["checkout/begin-plan"]();
+    for (const invalid of [
+      { options: [] },
+      { options: [options[0]!, options[0]!] },
+      { options, multiple: true as const },
+      { options, default: "unknown" },
+      { options: [{ ...options[0]!, description: "" }] },
+      {
+        options: [
+          {
+            ...options[0]!,
+            entryPoint: { ...options[0]!.entryPoint, trigger: "" },
+          },
+        ],
+      },
+    ]) {
+      expect(
+        await reason(
+          host.commands["agent/ask"]({
+            kind: "entry-point",
+            prompt: "Where?",
+            ...invalid,
+          }),
+        ),
+      ).toEqual({ reason: "invalid-input" });
+    }
+    expect(host.state.inputs).toEqual([]);
+  });
+});
+
+describe("product discovery", () => {
+  it("rejects an empty related-product identifier", async () => {
+    const host = await approvedHost();
+    expect(
+      await reason(
+        host.commands["agent/add-step"]({
+          title: "Install integration",
+          product: " ",
+        }),
+      ),
+    ).toEqual({ reason: "invalid-input" });
+    expect(host.state.steps).toEqual([]);
+  });
+
+  it("tracks relevant products outside the starting list without changing that list", async () => {
+    const host = await approvedHost();
+    const discovered = await host.commands["agent/add-step"]({
+      title: "Install discovered integration",
+      product: "discovered-integration",
+    });
+    expect(
+      host.state.steps.find((step) => step.id === discovered.stepId),
+    ).toMatchObject({
+      product: "discovered-integration",
+    });
+    await host.commands["agent/step"]({
+      stepId: discovered.stepId,
+      status: "done",
+    });
+    const restored = mount(host.snapshot());
+    expect(restored.state.steps[0]).toMatchObject({
+      product: "discovered-integration",
+      status: "done",
+    });
+    expect(restored.state.products).toEqual(seed.products);
+  });
+});
+
 describe("closing", () => {
   it("keeps a finished setup done when a late cancel arrives", async () => {
     const host = await approvedHost();
@@ -785,6 +911,27 @@ describe("closing", () => {
     expect(host.state.status).toBe("done");
   });
 
+  it("ignores a cancel meant for another checkout", async () => {
+    const host = mount();
+    await host.commands["checkout/create"](seed);
+    await host.commands["checkout/cancel"]({ id: "c0" });
+    expect(host.state.status).toBe("waiting");
+  });
+
+  it("cancels the checkout a cancel names", async () => {
+    const host = mount();
+    await host.commands["checkout/create"](seed);
+    await host.commands["checkout/cancel"]({ id: seed.id });
+    expect(host.state.status).toBe("cancelled");
+  });
+
+  it("cancels the current checkout when a cancel names none", async () => {
+    const host = mount();
+    await host.commands["checkout/create"](seed);
+    await host.commands["checkout/cancel"]({});
+    expect(host.state.status).toBe("cancelled");
+  });
+
   it("ignores a cancel before the setup exists", async () => {
     const host = mount();
     await host.commands["checkout/cancel"]();

package/src/host.ts

@@ -12,6 +12,9 @@ import {
   isAgentPresent,
   isClosed,
   isValidModelAnswer,
+  isValidEntryPointAnswer,
+  isValidEntryPointInput,
+  parseEntryPointOptions,
   parsePreviewUrl,
 } from "./protocol";
 import type { Checkout } from "./protocol";
@@ -83,6 +86,16 @@ const useCheckoutHost = (restored: unknown) => {
 
   const ask = (seed: Checkout.InputSeed & { stepId?: string }) => {
     const kind = seed.kind ?? "text";
+    const options =
+      kind === "entry-point"
+        ? parseEntryPointOptions(seed.options)
+        : seed.options;
+    if (kind === "entry-point" && !isValidEntryPointInput(seed)) {
+      throw reject(
+        "invalid-input",
+        "an entry-point input needs a prompt and 1–3 distinct options with descriptions, form factors, placements and triggers; at most one is recommended",
+      );
+    }
     if (kind === "product") {
       if (!seed.product) {
         throw reject("invalid-input", "a product input names a product");
@@ -148,7 +161,7 @@ const useCheckoutHost = (restored: unknown) => {
       ...(seed.preset !== undefined && { preset: seed.preset }),
       prompt: seed.prompt,
       ...(seed.placeholder !== undefined && { placeholder: seed.placeholder }),
-      ...(seed.options !== undefined && { options: seed.options }),
+      ...(options !== undefined && { options }),
       ...(seed.multiple && { multiple: true }),
       ...(kind === "product" && { product: seed.product }),
       ...(seed.default !== undefined && { default: seed.default }),
@@ -237,6 +250,12 @@ const useCheckoutHost = (restored: unknown) => {
             : `"${answer}" names an option without a valid variant`,
         );
       }
+      if (
+        input.kind === "entry-point" &&
+        !isValidEntryPointAnswer(input, answer)
+      ) {
+        throw reject("invalid-answer", "an entry-point answer is an option id");
+      }
       if (input.kind === "model" && !isValidModelAnswer(input, answer)) {
         throw reject(
           "invalid-answer",
@@ -328,8 +347,9 @@ const useCheckoutHost = (restored: unknown) => {
       plan.decidedAt = Date.now();
       plan.feedback = params.feedback.trim();
     },
-    "checkout/cancel": () => {
+    "checkout/cancel": ({ id } = {}) => {
       if (state.createdAt === null || isClosed(state)) return;
+      if (id !== undefined && id !== state.id) return;
       state.status = "cancelled";
       dismissOpenInputs();
     },
@@ -383,11 +403,11 @@ const useCheckoutHost = (restored: unknown) => {
     },
     "agent/add-step": ({ title, detail, product, active }) => {
       requireInstalling();
-      if (
-        product !== undefined &&
-        !state.products.some((candidate) => candidate.slug === product)
-      ) {
-        throw reject("unknown-product", `no product "${product}"`);
+      if (product !== undefined && product.trim() === "") {
+        throw reject(
+          "invalid-input",
+          "a step's product identifier cannot be empty",
+        );
       }
       const id = `s${state.steps.length + 1}`;
       state.steps.push({

package/src/index.ts

@@ -12,8 +12,11 @@ export {
   isClosed,
   isOptionIcon,
   isValidModelAnswer,
+  isValidEntryPointAnswer,
+  isValidEntryPointInput,
   openInputs,
   parseChoiceAnswer,
+  parseEntryPointOptions,
   parseModelAnswer,
   parseMultipleAnswer,
   parsePreviewUrl,

package/src/protocol.test.ts

@@ -0,0 +1,128 @@
+import { describe, expect, it } from "vitest";
+import {
+  isValidEntryPointAnswer,
+  isValidEntryPointInput,
+  parseEntryPointOptions,
+  type Checkout,
+} from "./protocol";
+
+const option: Checkout.EntryPointOption = {
+  id: "ticket-sidebar",
+  label: "Ticket sidebar",
+  description: "Draft replies beside the selected support ticket.",
+  entryPoint: {
+    formFactor: "sidebar",
+    placement: "The right side of the ticket detail page",
+    trigger: "Open with the Draft reply button in the ticket toolbar",
+    recommended: true,
+  },
+};
+
+const input: Checkout.Input = {
+  id: "q1",
+  kind: "entry-point",
+  phase: "planning",
+  prompt: "Where should agents draft replies?",
+  options: [option],
+  default: option.id,
+  optional: false,
+  status: "open",
+  createdAt: 1,
+};
+
+describe("entry-point options", () => {
+  it("keeps contextual metadata and permits different placements of the same form factor", () => {
+    const second = {
+      ...option,
+      id: "inbox-sidebar",
+      entryPoint: {
+        ...option.entryPoint,
+        placement: "The inbox list",
+        trigger: "Open with the inbox Assist button",
+        recommended: false,
+      },
+    };
+    expect(parseEntryPointOptions([option, second])).toEqual([option, second]);
+    expect(isValidEntryPointInput(input)).toBe(true);
+    expect(isValidEntryPointAnswer(input, "ticket-sidebar")).toBe(true);
+    expect(isValidEntryPointAnswer(input, "sidebar")).toBe(false);
+    expect(isValidEntryPointAnswer(input, "ticket-sidebar:variant")).toBe(
+      false,
+    );
+    expect(isValidEntryPointAnswer(input, '["ticket-sidebar"]')).toBe(false);
+  });
+
+  it.each(
+    [
+      null,
+      {},
+      [],
+      [null],
+      [option, option],
+      [option, { ...option, id: "another" }],
+      [
+        option,
+        { ...option, id: "b" },
+        { ...option, id: "c" },
+        { ...option, id: "d" },
+      ],
+      [{ ...option, id: "with:variant" }],
+      [{ ...option, id: "x".repeat(65) }],
+      [{ ...option, label: " " }],
+      [{ ...option, description: "" }],
+      [{ ...option, description: "x".repeat(1001) }],
+      [{ ...option, entryPoint: null }],
+      [
+        {
+          ...option,
+          entryPoint: { ...option.entryPoint, formFactor: "drawer" },
+        },
+      ],
+      [{ ...option, entryPoint: { ...option.entryPoint, placement: "" } }],
+      [{ ...option, entryPoint: { ...option.entryPoint, trigger: " " } }],
+      [{ ...option, entryPoint: { ...option.entryPoint, recommended: "yes" } }],
+      [{ ...option, variants: [] }],
+    ].map((value) => ({ value })),
+  )("rejects malformed or ambiguous choices %#", ({ value }) => {
+    expect(parseEntryPointOptions(value)).toBeUndefined();
+  });
+
+  it("types an option with only the fields the parser keeps", () => {
+    const withIcon: Checkout.EntryPointOption = {
+      ...option,
+      // @ts-expect-error an entry-point option carries no icon
+      icon: "sidebar",
+    };
+    const withVariants: Checkout.EntryPointOption = {
+      ...option,
+      // @ts-expect-error an entry-point option carries no variants
+      variants: [],
+    };
+    expect(parseEntryPointOptions([withIcon])).toEqual([option]);
+    expect(parseEntryPointOptions([withVariants])).toBeUndefined();
+  });
+
+  it("strips undeclared payload fields", () => {
+    expect(
+      parseEntryPointOptions([{ ...option, icon: "untrusted", extra: 1 }]),
+    ).toEqual([option]);
+  });
+
+  it("requires an exact default and a single selection", () => {
+    expect(isValidEntryPointInput({ ...input, multiple: true })).toBe(false);
+    expect(isValidEntryPointInput({ ...input, default: "unknown" })).toBe(
+      false,
+    );
+    expect(isValidEntryPointInput({ ...input, prompt: " " })).toBe(false);
+    expect(isValidEntryPointInput({ ...input, kind: "choice" })).toBe(false);
+  });
+
+  it("refuses a help note, which the entry-point card has no place for", () => {
+    expect(
+      isValidEntryPointInput({
+        ...input,
+        help: { summary: "Pick one" },
+      }),
+    ).toBe(false);
+  });
+});

package/src/protocol.ts

@@ -32,7 +32,26 @@ export namespace Checkout {
    * another product depends on. The browser owns the catalog, so it answers
    * with `checkout/add-product`; dismissing the input declines.
    */
-  export type InputKind = "text" | "choice" | "model" | "product";
+  export type InputKind =
+    | "text"
+    | "choice"
+    | "model"
+    | "product"
+    | "entry-point";
+
+  export type EntryPoint = {
+    formFactor: "modal" | "sidebar" | "full-page";
+    placement: string;
+    trigger: string;
+    recommended?: boolean;
+  };
+
+  export type EntryPointOption = {
+    id: string;
+    label: string;
+    description: string;
+    entryPoint: EntryPoint;
+  };
 
   export type ChoiceVariant = { id: string; label: string };
 
@@ -44,6 +63,7 @@ export namespace Checkout {
     icon?: string;
     /** A second pick under this option, such as the language of a framework. */
     variants?: ChoiceVariant[];
+    entryPoint?: EntryPoint;
   };
 
   /** A short nudge for users who need help choosing, with a longer guide to link to. */
@@ -199,7 +219,8 @@ export namespace Checkout {
     "agent/ack": (params: { messageId: string }) => void;
     "checkout/dismiss": (params: { inputId: string }) => void;
     "checkout/plan": (params: PlanDecision) => void;
-    "checkout/cancel": () => void;
+    /** A cancel that names another checkout than the current one is a no-op. */
+    "checkout/cancel": (params?: { id?: string }) => void;
     "checkout/finish": () => void;
     "agent/intro": (params: { kind?: string }) => void;
     "agent/hello": (params: { cwd?: string; kind?: string }) => void;
@@ -437,6 +458,76 @@ export const classifyChoiceAnswer = (
   return kinds.includes("custom") ? "custom" : "option";
 };
 
+const isEntryPointText = (value: unknown, max: number): value is string =>
+  typeof value === "string" && value.trim() !== "" && value.length <= max;
+
+export const parseEntryPointOptions = (
+  value: unknown,
+): Checkout.EntryPointOption[] | undefined => {
+  if (!Array.isArray(value) || value.length < 1 || value.length > 3)
+    return undefined;
+  const options: Checkout.EntryPointOption[] = [];
+  for (const candidate of value) {
+    if (typeof candidate !== "object" || candidate === null) return undefined;
+    const { id, label, description, entryPoint, variants } =
+      candidate as Record<string, unknown>;
+    if (
+      typeof id !== "string" ||
+      !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/.test(id) ||
+      options.some((option) => option.id === id) ||
+      !isEntryPointText(label, 160) ||
+      !isEntryPointText(description, 1000) ||
+      variants !== undefined ||
+      typeof entryPoint !== "object" ||
+      entryPoint === null
+    )
+      return undefined;
+    const { formFactor, placement, trigger, recommended } =
+      entryPoint as Record<string, unknown>;
+    if (
+      (formFactor !== "modal" &&
+        formFactor !== "sidebar" &&
+        formFactor !== "full-page") ||
+      !isEntryPointText(placement, 400) ||
+      !isEntryPointText(trigger, 400) ||
+      (recommended !== undefined && typeof recommended !== "boolean")
+    )
+      return undefined;
+    options.push({
+      id,
+      label,
+      description,
+      entryPoint: {
+        formFactor,
+        placement,
+        trigger,
+        ...(recommended !== undefined && { recommended }),
+      },
+    });
+  }
+  return options.filter((option) => option.entryPoint.recommended).length <= 1
+    ? options
+    : undefined;
+};
+
+export const isValidEntryPointInput = (input: Checkout.InputSeed) => {
+  const options = parseEntryPointOptions(input.options);
+  return (
+    input.kind === "entry-point" &&
+    isEntryPointText(input.prompt, 1000) &&
+    options !== undefined &&
+    input.multiple === undefined &&
+    input.help === undefined &&
+    (input.default === undefined ||
+      options.some((option) => option.id === input.default))
+  );
+};
+
+export const isValidEntryPointAnswer = (
+  input: Checkout.Input,
+  answer: string,
+) => input.options?.some((option) => option.id === answer) ?? false;
+
 const REASONING_EFFORTS = new Set(["low", "medium", "high"]);
 
 const isReasoningEffort = (