agentic-dev 0.2.9 → 0.2.11

package/bin/agentic-dev.mjs

@@ -1,18 +1,90 @@
 #!/usr/bin/env node
+import fs from "node:fs";
 import path from "node:path";
 import process from "node:process";
 import * as readline from "node:readline";
 import { createInterface } from "node:readline/promises";
 import {
+  DEFAULT_TEMPLATE_OWNER,
   ensureTargetDir,
   fetchTemplateRepos,
   installTemplateRepo,
   parseArgs,
   resolveTemplateRepo,
-  selectTemplateRepo,
   usage,
 } from "../lib/scaffold.mjs";
 
+const DEFAULT_TARGET_DIR = ".";
+const DEFAULT_APP_MODE = "fullstack";
+const DEFAULT_AI_PROVIDERS = ["codex", "claude"];
+
+const GITHUB_AUTH_CHOICES = [
+  {
+    label: "public",
+    value: "public",
+    description: "Use public template-* repos from say828 without a token",
+  },
+  {
+    label: "env",
+    value: "env",
+    description: "Use GH_TOKEN, GITHUB_TOKEN, or AGENTIC_GITHUB_TOKEN from the shell",
+  },
+  {
+    label: "pat",
+    value: "pat",
+    description: "Paste a GitHub PAT for this run only",
+  },
+];
+
+const APP_MODE_CHOICES = [
+  {
+    label: "fullstack",
+    value: "fullstack",
+    description: "Install dependencies and run frontend parity bootstrap",
+  },
+  {
+    label: "frontend",
+    value: "frontend",
+    description: "Keep frontend-focused setup with browser install and parity bootstrap",
+  },
+  {
+    label: "backend",
+    value: "backend",
+    description: "Install workspace dependencies but skip browser install and parity bootstrap",
+  },
+];
+
+const AI_PROVIDER_CHOICES = [
+  {
+    label: "codex",
+    value: "codex",
+    description: "Keep Codex workspace config in the generated repo",
+  },
+  {
+    label: "claude",
+    value: "claude",
+    description: "Keep Claude workspace config in the generated repo",
+  },
+  {
+    label: "ollama",
+    value: "ollama",
+    description: "Record Ollama as a provider in setup metadata",
+  },
+];
+
+const CONFIRM_CHOICES = [
+  {
+    label: "Proceed",
+    value: "proceed",
+    description: "Run clone, install, and bootstrap now",
+  },
+  {
+    label: "Cancel",
+    value: "cancel",
+    description: "Stop without writing files",
+  },
+];
+
 function clearMenu(lines) {
   if (lines <= 0) {
     return;
@@ -21,18 +93,318 @@ function clearMenu(lines) {
   readline.clearScreenDown(process.stdout);
 }
 
-function renderRepoSelect(label, repos, cursor) {
-  const lines = [`${label} Use ↑/↓ and Enter.`];
-  for (let index = 0; index < repos.length; index += 1) {
-    const pointer = index === cursor ? ">" : " ";
-    const summary = repos[index].description ? ` - ${repos[index].description}` : "";
-    lines.push(`${pointer} ${repos[index].name}${summary}`);
+function inferProjectName(targetDir) {
+  const normalized = (targetDir || DEFAULT_TARGET_DIR).trim() || DEFAULT_TARGET_DIR;
+  const resolved = path.resolve(process.cwd(), normalized);
+  return path.basename(resolved);
+}
+
+function directoryHasUserFiles(targetDir) {
+  const normalized = (targetDir || DEFAULT_TARGET_DIR).trim() || DEFAULT_TARGET_DIR;
+  const resolved = path.resolve(process.cwd(), normalized);
+  if (!fs.existsSync(resolved)) {
+    return false;
+  }
+
+  const entries = fs
+    .readdirSync(resolved, { withFileTypes: true })
+    .filter((entry) => entry.name !== ".git");
+  return entries.length > 0;
+}
+
+function normalizeProviders(providers) {
+  const normalized = Array.isArray(providers)
+    ? providers.map((provider) => provider.trim()).filter(Boolean)
+    : [];
+  if (normalized.length > 0) {
+    return [...new Set(normalized)];
+  }
+  return [...DEFAULT_AI_PROVIDERS];
+}
+
+function uniqueProviders(providers) {
+  return Array.isArray(providers)
+    ? [...new Set(providers.map((provider) => provider.trim()).filter(Boolean))]
+    : [];
+}
+
+function hydrateOptions(options) {
+  const state = {
+    targetDir: (options.targetDir || DEFAULT_TARGET_DIR).trim() || DEFAULT_TARGET_DIR,
+    projectName: (options.projectName || "").trim(),
+    template: (options.template || "").trim(),
+    githubAuthMode: (options.githubAuthMode || "public").trim() || "public",
+    githubPat: options.githubPat || "",
+    appMode: (options.appMode || DEFAULT_APP_MODE).trim() || DEFAULT_APP_MODE,
+    aiProviders: normalizeProviders(options.aiProviders),
+    force: Boolean(options.force),
+    skipBootstrap: Boolean(options.skipBootstrap),
+    owner: options.owner || DEFAULT_TEMPLATE_OWNER,
+  };
+
+  if (!state.projectName) {
+    state.projectName = inferProjectName(state.targetDir);
+  }
+
+  return state;
+}
+
+function applyRuntimeGitHubAuth(state) {
+  if (state.githubAuthMode === "pat" && state.githubPat) {
+    process.env.AGENTIC_GITHUB_TOKEN = state.githubPat;
+    return;
+  }
+
+  if (state.githubAuthMode === "public") {
+    delete process.env.AGENTIC_GITHUB_TOKEN;
+  }
+}
+
+function sanitizeStateForInstall(state) {
+  return {
+    ...state,
+    targetDir: (state.targetDir || DEFAULT_TARGET_DIR).trim() || DEFAULT_TARGET_DIR,
+    projectName: (state.projectName || inferProjectName(state.targetDir)).trim(),
+    aiProviders: normalizeProviders(state.aiProviders),
+  };
+}
+
+function buildTemplateChoices(repos) {
+  return repos.map((repo) => ({
+    label: repo.name,
+    value: repo.name,
+    description: repo.description || "Public template repo",
+  }));
+}
+
+function buildSteps(state, repos) {
+  const steps = [
+    {
+      key: "targetDir",
+      type: "text",
+      label: "Project directory",
+      description: "Type the destination directory, then press Enter. Use ←/→ to move between screens.",
+      placeholder: DEFAULT_TARGET_DIR,
+    },
+    {
+      key: "projectName",
+      type: "text",
+      label: "Project name",
+      description: "Written into scaffold metadata and Claude workspace nickname.",
+      placeholder: inferProjectName(state.targetDir),
+    },
+    {
+      key: "githubAuthMode",
+      type: "single",
+      label: "GitHub auth mode",
+      description: "Choose how this run should access template repos.",
+      choices: GITHUB_AUTH_CHOICES,
+    },
+  ];
+
+  if (state.githubAuthMode === "pat") {
+    steps.push({
+      key: "githubPat",
+      type: "password",
+      label: "GitHub PAT",
+      description: "Used only for this run. The token is not written into the generated repo.",
+      placeholder: "",
+    });
+  }
+
+  steps.push(
+    {
+      key: "template",
+      type: "single",
+      label: `Template repo from ${state.owner}`,
+      description: "Pick the public template-* repo to scaffold.",
+      choices: buildTemplateChoices(repos),
+    },
+    {
+      key: "appMode",
+      type: "single",
+      label: "App mode",
+      description: "Choose how much of the bootstrap flow should run after clone.",
+      choices: APP_MODE_CHOICES,
+    },
+    {
+      key: "aiProviders",
+      type: "multi",
+      label: "AI providers",
+      description: "Use Space to toggle. At least one provider must stay selected.",
+      choices: AI_PROVIDER_CHOICES,
+    },
+  );
+
+  if (!state.force && directoryHasUserFiles(state.targetDir)) {
+    steps.push({
+      key: "force",
+      type: "single",
+      label: "Target directory is not empty",
+      description: "Choose whether scaffolding may continue in the current directory.",
+      choices: [
+        {
+          label: "Continue",
+          value: true,
+          description: "Allow scaffolding into the existing directory",
+        },
+        {
+          label: "Cancel",
+          value: false,
+          description: "Stop without changing files",
+        },
+      ],
+    });
+  }
+
+  steps.push({
+    key: "confirm",
+    type: "confirm",
+    label: "Review and run",
+    description: "Confirm every choice before the CLI starts cloning or installing.",
+    choices: CONFIRM_CHOICES,
+  });
+
+  return steps;
+}
+
+function stepValue(state, step) {
+  if (step.key === "targetDir") {
+    return state.targetDir || step.placeholder || DEFAULT_TARGET_DIR;
+  }
+  if (step.key === "projectName") {
+    return state.projectName || step.placeholder || inferProjectName(state.targetDir);
+  }
+  if (step.key === "githubPat") {
+    return state.githubPat || "";
   }
+  return state[step.key];
+}
+
+function renderHeader(step, index, total) {
+  return [
+    `Agentic Dev Setup ${index + 1}/${total}`,
+    step.label,
+    step.description,
+    "",
+  ];
+}
+
+function renderTextStep(step, state, buffers, index, total) {
+  const lines = renderHeader(step, index, total);
+  if (!buffers.has(step.key)) {
+    buffers.set(step.key, stepValue(state, step) || "");
+  }
+
+  const rawValue = buffers.get(step.key);
+  const displayValue =
+    step.type === "password" ? "*".repeat(rawValue.length) : rawValue || step.placeholder || "";
+
+  lines.push(`Value: ${displayValue}`);
+  lines.push("");
+  lines.push("Controls: type text, Backspace to edit, Enter or → to continue, ← to go back.");
+  process.stdout.write(`${lines.join("\n")}\n`);
+  return lines.length;
+}
+
+function renderSingleChoiceStep(step, state, cursors, index, total) {
+  const lines = renderHeader(step, index, total);
+  if (!cursors.has(step.key)) {
+    const currentValue = stepValue(state, step);
+    const currentIndex = Math.max(
+      0,
+      step.choices.findIndex((choice) => choice.value === currentValue),
+    );
+    cursors.set(step.key, currentIndex >= 0 ? currentIndex : 0);
+  }
+
+  const cursor = cursors.get(step.key);
+  step.choices.forEach((choice, choiceIndex) => {
+    const pointer = choiceIndex === cursor ? ">" : " ";
+    const suffix = choice.description ? ` - ${choice.description}` : "";
+    lines.push(`${pointer} ${choice.label}${suffix}`);
+  });
+
+  lines.push("");
+  lines.push("Controls: ↑/↓ to choose, Enter or → to continue, ← to go back.");
+  process.stdout.write(`${lines.join("\n")}\n`);
+  return lines.length;
+}
+
+function renderMultiChoiceStep(step, state, cursors, index, total) {
+  const lines = renderHeader(step, index, total);
+  if (!cursors.has(step.key)) {
+    cursors.set(step.key, 0);
+  }
+
+  const selected = new Set(uniqueProviders(stepValue(state, step)));
+  const cursor = cursors.get(step.key);
+  step.choices.forEach((choice, choiceIndex) => {
+    const pointer = choiceIndex === cursor ? ">" : " ";
+    const checked = selected.has(choice.value) ? "[x]" : "[ ]";
+    const suffix = choice.description ? ` - ${choice.description}` : "";
+    lines.push(`${pointer} ${checked} ${choice.label}${suffix}`);
+  });
+
+  lines.push("");
+  lines.push("Controls: ↑/↓ to move, Space to toggle, Enter or → to continue, ← to go back.");
+  process.stdout.write(`${lines.join("\n")}\n`);
+  return lines.length;
+}
+
+function executionPreview(state, selectedRepo) {
+  const lines = [
+    `Project directory: ${path.resolve(process.cwd(), state.targetDir)}`,
+    `Project name: ${state.projectName}`,
+    `GitHub auth mode: ${state.githubAuthMode}`,
+    `Template repo: ${selectedRepo?.name || state.template}`,
+    `App mode: ${state.appMode}`,
+    `AI providers: ${state.aiProviders.join(", ")}`,
+    `Allow non-empty directory: ${state.force ? "yes" : "no"}`,
+  ];
+
+  if (state.githubAuthMode === "pat") {
+    lines.push(`GitHub PAT supplied: ${state.githubPat ? "yes" : "no"}`);
+  }
+
+  lines.push("Run plan:");
+  lines.push(`  1. Clone ${selectedRepo?.name || state.template}`);
+  lines.push("  2. Copy .env.example to .env if needed");
+  lines.push("  3. Run pnpm install");
+  if (state.appMode === "backend") {
+    lines.push("  4. Skip browser install and parity bootstrap");
+  } else {
+    lines.push("  4. Install Playwright Chromium for the default frontend target");
+    lines.push("  5. Run frontend parity bootstrap");
+  }
+
+  return lines;
+}
+
+function renderConfirmStep(step, state, repos, cursors, index, total) {
+  const lines = renderHeader(step, index, total);
+  const selectedRepo = resolveTemplateRepo(state.template, repos);
+  executionPreview(state, selectedRepo).forEach((line) => lines.push(line));
+  lines.push("");
+
+  if (!cursors.has(step.key)) {
+    cursors.set(step.key, 0);
+  }
+
+  const cursor = cursors.get(step.key);
+  step.choices.forEach((choice, choiceIndex) => {
+    const pointer = choiceIndex === cursor ? ">" : " ";
+    const suffix = choice.description ? ` - ${choice.description}` : "";
+    lines.push(`${pointer} ${choice.label}${suffix}`);
+  });
+
+  lines.push("");
+  lines.push("Controls: ↑/↓ to choose, Enter or → to confirm, ← to go back.");
   process.stdout.write(`${lines.join("\n")}\n`);
   return lines.length;
 }
 
-async function runArrowMenu(render, onInput) {
+async function runInteractiveSession(render, onInput) {
   const stdin = process.stdin;
   const stdout = process.stdout;
   const previousRawMode = typeof stdin.setRawMode === "function" ? stdin.isRaw : undefined;
@@ -78,80 +450,315 @@ async function runArrowMenu(render, onInput) {
   });
 }
 
-async function promptForTemplateRepo(rl, repos, owner) {
-  if (process.stdin.isTTY && process.stdout.isTTY) {
-    console.log("");
-    let cursor = 0;
-    return runArrowMenu(
-      () => renderRepoSelect(`Public template repos from ${owner}:`, repos, cursor),
-      (chunk, rerender) => {
-        if (chunk === "\u0003") {
-          throw new Error("Prompt cancelled");
+function validateStepValue(step, state, value) {
+  if (step.key === "targetDir") {
+    const trimmed = value.trim() || DEFAULT_TARGET_DIR;
+    return trimmed;
+  }
+
+  if (step.key === "projectName") {
+    const trimmed = value.trim();
+    if (!trimmed) {
+      throw new Error("Project name cannot be empty.");
+    }
+    return trimmed;
+  }
+
+  if (step.key === "githubPat") {
+    const trimmed = value.trim();
+    if (!trimmed) {
+      throw new Error("GitHub PAT cannot be empty.");
+    }
+    return trimmed;
+  }
+
+  if (step.key === "aiProviders") {
+    const providers = normalizeProviders(value);
+    if (providers.length === 0) {
+      throw new Error("Select at least one AI provider.");
+    }
+    return providers;
+  }
+
+  if (step.key === "force" && value === false) {
+    throw new Error("Prompt cancelled");
+  }
+
+  return value;
+}
+
+function setStateValue(state, step, value) {
+  if (step.key === "targetDir") {
+    const previousInferred = inferProjectName(state.targetDir);
+    state.targetDir = value;
+    if (!state.projectName || state.projectName === previousInferred) {
+      state.projectName = inferProjectName(value);
+    }
+    return;
+  }
+
+  state[step.key] = value;
+}
+
+async function runWizard(initialState, repos) {
+  const state = sanitizeStateForInstall(initialState);
+  const buffers = new Map();
+  const cursors = new Map();
+  let stepIndex = 0;
+
+  return runInteractiveSession(
+    () => {
+      const steps = buildSteps(state, repos);
+      if (stepIndex >= steps.length) {
+        stepIndex = steps.length - 1;
+      }
+      const step = steps[stepIndex];
+      process.stdout.write("\n");
+      if (step.type === "text" || step.type === "password") {
+        return renderTextStep(step, state, buffers, stepIndex, steps.length);
+      }
+      if (step.type === "multi") {
+        return renderMultiChoiceStep(step, state, cursors, stepIndex, steps.length);
+      }
+      if (step.type === "confirm") {
+        return renderConfirmStep(step, state, repos, cursors, stepIndex, steps.length);
+      }
+      return renderSingleChoiceStep(step, state, cursors, stepIndex, steps.length);
+    },
+    (chunk, rerender) => {
+      const steps = buildSteps(state, repos);
+      const step = steps[stepIndex];
+
+      if (chunk === "\u0003") {
+        throw new Error("Prompt cancelled");
+      }
+
+      if (step.type === "text" || step.type === "password") {
+        if (!buffers.has(step.key)) {
+          buffers.set(step.key, stepValue(state, step) || "");
+        }
+
+        if (chunk === "\u007f") {
+          buffers.set(step.key, buffers.get(step.key).slice(0, -1));
+          rerender();
+          return undefined;
         }
-        if (chunk === "\r" || chunk === "\n") {
-          return repos[cursor].name;
+
+        if (chunk === "\u001b[D") {
+          if (stepIndex > 0) {
+            stepIndex -= 1;
+            rerender();
+          }
+          return undefined;
         }
-        if (chunk === "\u001b[A") {
-          cursor = (cursor - 1 + repos.length) % repos.length;
+
+        if (chunk === "\r" || chunk === "\n" || chunk === "\u001b[C") {
+          const nextValue = validateStepValue(step, state, buffers.get(step.key));
+          setStateValue(state, step, nextValue);
+          const nextSteps = buildSteps(state, repos);
+          if (stepIndex < nextSteps.length - 1) {
+            stepIndex += 1;
+            rerender();
+            return undefined;
+          }
+          return sanitizeStateForInstall(state);
+        }
+
+        if (/^[\x20-\x7e]$/.test(chunk)) {
+          buffers.set(step.key, `${buffers.get(step.key)}${chunk}`);
           rerender();
-        } else if (chunk === "\u001b[B") {
-          cursor = (cursor + 1) % repos.length;
+        }
+        return undefined;
+      }
+
+      if (!cursors.has(step.key)) {
+        const currentValue = stepValue(state, step);
+        const initialIndex = Math.max(
+          0,
+          step.choices.findIndex((choice) => choice.value === currentValue),
+        );
+        cursors.set(step.key, initialIndex >= 0 ? initialIndex : 0);
+      }
+
+      if (chunk === "\u001b[D") {
+        if (stepIndex > 0) {
+          stepIndex -= 1;
           rerender();
         }
         return undefined;
-      },
-    );
-  }
+      }
 
+      if (chunk === "\u001b[A") {
+        const nextCursor = (cursors.get(step.key) - 1 + step.choices.length) % step.choices.length;
+        cursors.set(step.key, nextCursor);
+        rerender();
+        return undefined;
+      }
+
+      if (chunk === "\u001b[B") {
+        const nextCursor = (cursors.get(step.key) + 1) % step.choices.length;
+        cursors.set(step.key, nextCursor);
+        rerender();
+        return undefined;
+      }
+
+      if (step.type === "multi" && chunk === " ") {
+        const selected = new Set(uniqueProviders(state.aiProviders));
+        const currentChoice = step.choices[cursors.get(step.key)];
+        if (selected.has(currentChoice.value)) {
+          selected.delete(currentChoice.value);
+        } else {
+          selected.add(currentChoice.value);
+        }
+        state.aiProviders = [...selected];
+        rerender();
+        return undefined;
+      }
+
+      if (chunk === "\r" || chunk === "\n" || chunk === "\u001b[C") {
+        if (step.type === "multi") {
+          const providers = validateStepValue(step, state, state.aiProviders);
+          setStateValue(state, step, providers);
+        } else {
+          const selectedChoice = step.choices[cursors.get(step.key)];
+          if (step.type === "confirm") {
+            if (selectedChoice.value === "cancel") {
+              throw new Error("Prompt cancelled");
+            }
+            return sanitizeStateForInstall(state);
+          }
+          const nextValue = validateStepValue(step, state, selectedChoice.value);
+          setStateValue(state, step, nextValue);
+        }
+
+        const nextSteps = buildSteps(state, repos);
+        if (stepIndex < nextSteps.length - 1) {
+          stepIndex += 1;
+          rerender();
+          return undefined;
+        }
+        return sanitizeStateForInstall(state);
+      }
+
+      return undefined;
+    },
+  );
+}
+
+async function promptForChoice(rl, label, choices) {
   console.log("");
-  console.log(`Public template repos from ${owner}:`);
-  repos.forEach((repo, index) => {
-    const summary = repo.description ? ` - ${repo.description}` : "";
-    console.log(`  ${index + 1}. ${repo.name}${summary}`);
+  console.log(label);
+  choices.forEach((choice, index) => {
+    const summary = choice.description ? ` - ${choice.description}` : "";
+    console.log(`  ${index + 1}. ${choice.label}${summary}`);
   });
   console.log("");
 
   while (true) {
-    const answer = await rl.question("Select template repo (number or repo name): ");
-    try {
-      return selectTemplateRepo(answer, repos).name;
-    } catch (error) {
-      console.log(error.message);
+    const answer = (await rl.question("Select option: ")).trim();
+    if (/^\d+$/.test(answer)) {
+      const index = Number.parseInt(answer, 10) - 1;
+      if (index >= 0 && index < choices.length) {
+        return choices[index].value;
+      }
+    }
+
+    const exact = choices.find((choice) => choice.label === answer || choice.value === answer);
+    if (exact) {
+      return exact.value;
     }
+    console.log(`Invalid selection: ${answer || "(empty)"}`);
   }
 }
 
-async function promptForMissing(options, repos) {
-  if (options.yes && (!options.targetDir || !options.template)) {
-    throw new Error("`--yes` requires both target directory and template repo.");
-  }
+async function promptForMultiChoice(rl, label, choices, defaults) {
+  console.log("");
+  console.log(label);
+  console.log("Enter one or more labels separated by commas.");
+  choices.forEach((choice, index) => {
+    const summary = choice.description ? ` - ${choice.description}` : "";
+    console.log(`  ${index + 1}. ${choice.label}${summary}`);
+  });
+  console.log("");
 
-  if (options.targetDir && options.template) {
-    return options;
+  while (true) {
+    const answer = (await rl.question(`Providers [${defaults.join(",")}]: `)).trim();
+    const selected = normalizeProviders(
+      answer
+        ? answer.split(",").map((entry) => entry.trim())
+        : defaults,
+    );
+    const invalid = selected.filter(
+      (provider) => !choices.some((choice) => choice.value === provider),
+    );
+    if (invalid.length === 0 && selected.length > 0) {
+      return selected;
+    }
+    console.log(`Invalid providers: ${invalid.join(", ")}`);
   }
+}
 
+function printFallbackPlan(state, repos) {
+  const selectedRepo = resolveTemplateRepo(state.template, repos);
+  console.log("");
+  executionPreview(state, selectedRepo).forEach((line) => console.log(line));
+}
+
+async function promptLinearly(initialState, repos) {
+  const state = sanitizeStateForInstall(initialState);
   const rl = createInterface({
     input: process.stdin,
     output: process.stdout,
   });
 
   try {
-    while (!options.targetDir) {
-      const answer = await rl.question("Project directory: ");
-      options.targetDir = answer.trim();
-      if (!options.targetDir) {
-        console.log("Project directory cannot be empty.");
+    const targetDirAnswer = await rl.question(`Project directory [${state.targetDir}]: `);
+    state.targetDir = targetDirAnswer.trim() || state.targetDir;
+
+    const defaultProjectName = inferProjectName(state.targetDir);
+    const projectNameAnswer = await rl.question(`Project name [${state.projectName || defaultProjectName}]: `);
+    state.projectName = projectNameAnswer.trim() || state.projectName || defaultProjectName;
+
+    state.githubAuthMode = await promptForChoice(rl, "GitHub auth mode", GITHUB_AUTH_CHOICES);
+    if (state.githubAuthMode === "pat") {
+      state.githubPat = (await rl.question("GitHub PAT: ")).trim();
+      if (!state.githubPat) {
+        throw new Error("GitHub PAT cannot be empty.");
+      }
+    }
+
+    state.template = await promptForChoice(rl, `Template repo from ${state.owner}`, buildTemplateChoices(repos));
+    state.appMode = await promptForChoice(rl, "App mode", APP_MODE_CHOICES);
+    state.aiProviders = await promptForMultiChoice(rl, "AI providers", AI_PROVIDER_CHOICES, state.aiProviders);
+
+    if (!state.force && directoryHasUserFiles(state.targetDir)) {
+      state.force = await promptForChoice(rl, "Target directory is not empty", [
+        {
+          label: "Continue",
+          value: true,
+          description: "Allow scaffolding into the existing directory",
+        },
+        {
+          label: "Cancel",
+          value: false,
+          description: "Stop without changing files",
+        },
+      ]);
+      if (!state.force) {
+        throw new Error("Prompt cancelled");
       }
     }
 
-    if (!options.template) {
-      options.template = await promptForTemplateRepo(rl, repos, options.owner);
+    printFallbackPlan(state, repos);
+    const confirmation = await promptForChoice(rl, "Run scaffold now?", CONFIRM_CHOICES);
+    if (confirmation !== "proceed") {
+      throw new Error("Prompt cancelled");
     }
   } finally {
     rl.close();
   }
 
-  return options;
+  return sanitizeStateForInstall(state);
 }
 
 function printSuccess(result) {
@@ -172,6 +779,25 @@ function printSuccess(result) {
   }
 }
 
+function validateNonInteractiveState(state) {
+  if (!state.targetDir) {
+    throw new Error("`--yes` requires a target directory.");
+  }
+  if (!state.template) {
+    throw new Error("`--yes` requires a template repo.");
+  }
+  if (!state.projectName) {
+    state.projectName = inferProjectName(state.targetDir);
+  }
+  if (state.githubAuthMode === "pat" && !state.githubPat) {
+    throw new Error("`--github-auth pat` requires `--github-pat`.");
+  }
+  if (!Array.isArray(state.aiProviders) || state.aiProviders.length === 0) {
+    state.aiProviders = [...DEFAULT_AI_PROVIDERS];
+  }
+  return state;
+}
+
 async function main() {
   let options;
   try {
@@ -203,18 +829,29 @@ async function main() {
   }
 
   try {
-    const repos = await fetchTemplateRepos({ owner: options.owner });
+    const state = hydrateOptions(options);
+    applyRuntimeGitHubAuth(state);
+    const repos = await fetchTemplateRepos({ owner: state.owner });
     if (repos.length === 0) {
-      throw new Error(`No public template-* repos found for ${options.owner}.`);
+      throw new Error(`No public template-* repos found for ${state.owner}.`);
     }
 
-    options = await promptForMissing(options, repos);
-    const selectedRepo = resolveTemplateRepo(options.template, repos);
-    const destinationRoot = ensureTargetDir(options.targetDir, { force: options.force });
+    const resolvedState = options.yes
+      ? validateNonInteractiveState(sanitizeStateForInstall(state))
+      : process.stdin.isTTY && process.stdout.isTTY
+        ? await runWizard(state, repos)
+        : await promptLinearly(state, repos);
+
+    applyRuntimeGitHubAuth(resolvedState);
+    const selectedRepo = resolveTemplateRepo(resolvedState.template, repos);
+    const destinationRoot = ensureTargetDir(resolvedState.targetDir, {
+      force: resolvedState.force,
+    });
     const result = installTemplateRepo({
       destinationRoot: path.resolve(destinationRoot),
       templateRepo: selectedRepo,
-      skipBootstrap: options.skipBootstrap,
+      setupSelections: resolvedState,
+      skipBootstrap: resolvedState.skipBootstrap,
     });
     printSuccess(result);
   } catch (error) {