@algolia/wizard 0.19.0-rc.111.186 → 0.19.0

package/README.md

@@ -23,7 +23,7 @@ npx @algolia/wizard --help
 | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `--seed <step-id>` | Start the workflow at the step with this id (e.g. `--seed ingestion`), with the earlier steps pre-filled with test data. Pass with no value to print the step ids. |
 | `--no-telemetry` | Send no telemetry or analytics for this run.                                                                                                                    |
-| `--reset-on-run` | Wipe this project's wizard state (run state, AI-changes consent) before starting, so the run behaves like a first-ever run. Credentials are untouched. |
+| `--reset-on-run` | Wipe this project's wizard state (run state, AI-changes consent, worktrees) before starting, so the run behaves like a first-ever run. Credentials are untouched. |
 | `-h`, `--help`   | Print usage.                                                                                                                                                   |
 
 `--seed` pre-fills the earlier steps with fabricated data so a single step can be exercised without running the whole workflow — useful for testing a step, not for a real implementation. It replaces any in-progress run for that workflow and pre-grants the AI-changes consent. See [Starting mid-workflow](CONTRIBUTING.md#starting-mid-workflow---seed).

package/dist/main.js

@@ -1200,7 +1200,7 @@ var accessItems = [
   {
     tag: "WRITE",
     title: "Code changes",
-    description: "creates & edits files (search UI, config) directly in your branch. You are asked to confirm first if it has uncommitted changes."
+    description: "creates & edits files (search UI, config) in a throwaway git worktree \u2014 your checkout is never touched."
   },
   {
     tag: "EXEC",
@@ -1215,7 +1215,7 @@ var accessItems = [
   {
     tag: "KEY",
     title: "Credentials",
-    description: "writes your Algolia app id and a search-only key (safe to expose) to .env in your project."
+    description: "writes your Algolia app id and a search-only key (safe to expose) to .env in the worktree."
   }
 ];
 var neverItems = [
@@ -3246,7 +3246,7 @@ var anthropic = createAnthropic({
 });
 function generateRecordTool(ctx) {
   return tool10({
-    description: "Generate realistic sample records for an entity and write them to a JSON file. Provide the entity name and its attributes; this tool asks a model to invent varied, realistic values, each with a unique objectID, and returns the file path to read them from at runtime. Do not invent the record values or objectIDs yourself, and do not inline the returned records into the script \u2014 call this tool and read the file it writes.",
+    description: "Generate realistic sample records for an entity and write them to a JSON file in the worktree. Provide the entity name and its attributes; this tool asks a model to invent varied, realistic values, each with a unique objectID, and returns the file path to read them from at runtime. Do not invent the record values or objectIDs yourself, and do not inline the returned records into the script \u2014 call this tool and read the file it writes.",
     inputSchema: z17.object({
       entityName: z17.string().describe("Name of the entity to generate records for."),
       attributes: z17.array(z17.string()).describe("Attribute names each record must contain."),
@@ -3604,7 +3604,7 @@ async function runAnalysis(mode, extraInstructions = []) {
 // package.json
 var package_default = {
   name: "@algolia/wizard",
-  version: "0.19.0-rc.111.186",
+  version: "0.19.0",
   description: "Magically implement Algolia functionality in your codebase",
   type: "module",
   engines: {
@@ -3971,10 +3971,11 @@ ${JSON.stringify(s.output, null, 2)}`
 function formatReviewSummary(result) {
   const nextStepLines = result.nextSteps.map((step) => {
     const isIngestCommand = step.includes(".algolia-wizard/ingest.sh");
+    const isWorktreeCommand = step.includes("/worktrees/");
     return {
       text: `\u2192 ${step}`,
-      color: isIngestCommand ? COLORS.brand : void 0,
-      bold: isIngestCommand
+      color: isIngestCommand ? COLORS.brand : isWorktreeCommand ? COLORS.secondary : void 0,
+      bold: isIngestCommand || isWorktreeCommand
     };
   });
   return [
@@ -4011,11 +4012,13 @@ ${formatCompletedSteps(ctx.completedSteps)}`,
 import z28 from "zod";
 import { join as join12 } from "node:path";
 
-// src/lib/git.ts
+// src/lib/worktree.ts
 import { execFile as execFile2 } from "node:child_process";
-import { copyFile, mkdir as mkdir6, readFile as readFile8, stat as stat3, writeFile as writeFile7 } from "node:fs/promises";
+import { copyFile, mkdir as mkdir6, readdir as readdir3, readFile as readFile8, stat as stat3, writeFile as writeFile7 } from "node:fs/promises";
 import { basename as basename2, dirname as dirname7, isAbsolute as isAbsolute2, join as join10, resolve as resolve3 } from "node:path";
 var MAX_BUFFER = 32 * 1024 * 1024;
+var MAX_WIZARD_WORKTREES = 3;
+var WIZARD_BRANCH_PREFIX = "wizard/implement-";
 function git(args) {
   return new Promise((resolve4, reject) => {
     execFile2("git", args, { maxBuffer: MAX_BUFFER }, (err, stdout, stderr) => {
@@ -4042,7 +4045,40 @@ async function isWorkingTreeDirty(repoRoot) {
   const out = await git(["-C", repoRoot, "status", "--porcelain"]);
   return out.trim().length > 0;
 }
-async function copyUploadIntoProject(repoRoot, ingestDir, sourcePath) {
+async function pruneOldWorktrees(repoRoot) {
+  const dir = join10(stateDir(repoRoot), "worktrees");
+  const stale = (await readdir3(dir).catch(() => [])).filter((name) => /^wizard-implement-\d+$/.test(name)).sort().reverse().slice(MAX_WIZARD_WORKTREES - 1);
+  for (const slug of stale) {
+    const branch = slug.replace("wizard-implement-", WIZARD_BRANCH_PREFIX);
+    try {
+      await git([
+        "-C",
+        repoRoot,
+        "worktree",
+        "remove",
+        "--force",
+        join10(dir, slug)
+      ]);
+      await git(["-C", repoRoot, "branch", "-D", branch]);
+    } catch (err) {
+      logger.warn(
+        { branch, err: err.message },
+        "createWorktree: failed to prune a stale wizard worktree; continuing"
+      );
+    }
+  }
+}
+async function createWorktree(repoRoot) {
+  const branch = `${WIZARD_BRANCH_PREFIX}${Date.now()}`;
+  const dirSlug = branch.replace(/\//g, "-");
+  const path = join10(stateDir(repoRoot), "worktrees", dirSlug);
+  await git(["-C", repoRoot, "worktree", "prune"]);
+  await pruneOldWorktrees(repoRoot);
+  await mkdir6(dirname7(path), { recursive: true });
+  await git(["-C", repoRoot, "worktree", "add", "-b", branch, path, "HEAD"]);
+  return { path, branch };
+}
+async function copyUploadIntoWorktree(repoRoot, worktreePath, ingestDir, sourcePath) {
   const trimmed = sourcePath.trim();
   if (!trimmed) {
     return { ok: false, reason: "no file path was provided" };
@@ -4056,10 +4092,7 @@ async function copyUploadIntoProject(repoRoot, ingestDir, sourcePath) {
     return { ok: false, reason: `"${sourcePath}" does not exist` };
   }
   const relPath = join10(ingestDir, basename2(source));
-  const dest = join10(repoRoot, relPath);
-  if (resolve3(source) === resolve3(dest)) {
-    return { ok: true, relPath };
-  }
+  const dest = join10(worktreePath, relPath);
   try {
     await mkdir6(dirname7(dest), { recursive: true });
     await copyFile(source, dest);
@@ -4074,10 +4107,10 @@ async function copyUploadIntoProject(repoRoot, ingestDir, sourcePath) {
 function hasEnvVar(content, name) {
   return new RegExp(`^(\\s*(?:export\\s+)?${name})\\s*=`, "m").test(content);
 }
-async function readEnvVar(repoRoot, name) {
+async function readEnvVar(worktreePath, name) {
   let content;
   try {
-    content = await readFile8(join10(repoRoot, ".env"), "utf8");
+    content = await readFile8(join10(worktreePath, ".env"), "utf8");
   } catch (err) {
     if (err.code !== "ENOENT") throw err;
     return void 0;
@@ -4091,8 +4124,8 @@ async function readEnvVar(repoRoot, name) {
   if (!value || value.startsWith("<")) return void 0;
   return value;
 }
-async function writeSearchEnvValues(repoRoot, vars) {
-  const target = join10(repoRoot, ".env");
+async function writeSearchEnvValues(worktreePath, vars) {
+  const target = join10(worktreePath, ".env");
   let existing = "";
   try {
     existing = await readFile8(target, "utf8");
@@ -4107,8 +4140,8 @@ async function writeSearchEnvValues(repoRoot, vars) {
   await writeFile7(target, existing + prefix + lines, "utf8");
   return missing.map((v) => v.name);
 }
-async function listChangedFiles(repoRoot) {
-  const raw = await git(["-C", repoRoot, "status", "--porcelain", "-z"]);
+async function listChangedFiles(worktreePath) {
+  const raw = await git(["-C", worktreePath, "status", "--porcelain", "-z"]);
   const entries = raw.split("\0");
   const files = [];
   for (let i = 0; i < entries.length; i += 1) {
@@ -4124,20 +4157,20 @@ function normalizeFindingPaths(findings) {
     ...findings,
     ingestionAnalysis: findings.ingestionAnalysis?.map((e) => ({
       ...e,
-      paths: e.paths.map(toRootRelative)
+      paths: e.paths.map(toWorktreeRelative)
     })),
     searchImplementationAnalysis: findings.searchImplementationAnalysis ? normalizeSearchLocation(findings.searchImplementationAnalysis) : void 0,
     confirmedEntities: findings.confirmedEntities?.map((e) => ({
       ...e,
-      paths: e.paths.map(toRootRelative)
+      paths: e.paths.map(toWorktreeRelative)
     }))
   };
 }
 function normalizeSearchLocation(path) {
-  const normalized = path ? toRootRelative(path).trim() : "";
+  const normalized = path ? toWorktreeRelative(path).trim() : "";
   return normalized && normalized.toLowerCase() !== "unknown" ? normalized : void 0;
 }
-function toRootRelative(p) {
+function toWorktreeRelative(p) {
   return p.replace(/^\/+/, "");
 }
 async function confirmDirtyWorkingTree(ctx, repoRoot) {
@@ -4146,19 +4179,19 @@ async function confirmDirtyWorkingTree(ctx, repoRoot) {
   const shown = dirty.slice(0, MAX_LISTED_DIRTY_FILES);
   const overflow = dirty.length - shown.length;
   const answer = await ctx.requestUserInput({
-    prompt: "Proceed with uncommitted changes in your checkout? The wizard will edit files there directly, alongside them.",
+    prompt: "Proceed using HEAD only? Uncommitted changes will NOT be included in the generated implementation.",
     promptType: "acceptReject",
     options: [],
     messages: [
-      `${dirty.length} uncommitted change(s) detected:`,
+      `${dirty.length} uncommitted change(s) detected. The wizard builds an isolated worktree from HEAD, so these are ignored:`,
       ...shown.map((file) => `  \u2022 ${file}`),
       ...overflow > 0 ? [`  \u2022 \u2026and ${overflow} more`] : [],
-      "Commit or stash them first if you want to review the wizard's changes on their own."
+      "Commit or stash them first to include them in the implementation."
     ]
   });
   if (answer !== true) {
     throw new Error(
-      "implement aborted: commit or stash your changes first, then re-run the wizard."
+      "implement aborted: commit or stash your changes so they are built into the worktree, then re-run the wizard."
     );
   }
 }
@@ -4221,10 +4254,16 @@ function getFrameworkSpecificDoc(frameworks) {
   return loadAlgoliaDoc("js");
 }
 
+// src/lib/shell.ts
+function shellQuote(value) {
+  return "'" + value.replace(/'/g, "'\\''") + "'";
+}
+
 // src/actions/implement.ts
 var implementSchema = z28.object({
   filesChanged: z28.array(z28.string()),
   summary: z28.string(),
+  worktreePath: z28.string().optional(),
   ingestCommand: z28.string().optional(),
   ingestScriptRan: z28.boolean().optional(),
   ingestRecordCount: z28.number().optional(),
@@ -4313,8 +4352,9 @@ function searchEnvVars(language, index, appId, searchKey) {
       name: searchKeyVar(language),
       value: searchKey ?? "<your-algolia-search-only-api-key>"
     },
-    // Wizard-supplied rather than written into the generated code: an agent
-    // that retypes the name leaves the UI querying an index that doesn't exist.
+    // Wizard-supplied rather than written into the generated code, because an
+    // agent that retypes the name (appending the project name, re-casing it)
+    // leaves the UI querying an index that does not exist.
     {
       name: searchIndexVar(language),
       value: index
@@ -4323,6 +4363,8 @@ function searchEnvVars(language, index, appId, searchKey) {
 }
 function baseInstructions(input) {
   return [
+    // Agents have renamed this (e.g. appending the project name), which the
+    // index-scoped keys then reject with a 403.
     `Target Algolia index, to be used exactly as written \u2014 never renamed, re-cased, prefixed, or suffixed: "${input.targetIndex}"`,
     `Project languages and frameworks: ${JSON.stringify(input.language)}`,
     "Make minimal, idiomatic changes; do not touch unrelated code.",
@@ -4340,14 +4382,14 @@ function sourceSpecificInstructions(input) {
       "Add env vars for any local source access (DB URL, API base, file paths) that is not a fixed repo path."
     ],
     fileUpload: [
-      `Records come from the developer's file, already copied into the project at "${input.uploadFilePath}". Read and parse that exact file.`,
+      `Records come from the developer's file, already copied into the worktree at "${input.uploadFilePath}". Read and parse that exact file.`,
       "Parse by extension: JSON = array of objects; CSV/TSV = header row maps to keys.",
       "Map parsed columns/fields to the confirmed entity attributes.",
       "Never fabricate, hardcode, or substitute a different file."
     ],
     generated: [
       "No real data source exists; use sample records for each confirmed entity.",
-      "Call the generateRecord tool once per entity (entityName, attributes, count 20-50); it invents the values and unique objectIDs and writes them to a JSON file, returning the file path. Do not write records or objectIDs yourself.",
+      "Call the generateRecord tool once per entity (entityName, attributes, count 20-50); it invents the values and unique objectIDs and writes them to a JSON file in the worktree, returning the file path. Do not write records or objectIDs yourself.",
       "In the script, read and parse each returned file path at runtime using your language's standard JSON support, instead of inlining the records as literals.",
       "Add a prominent TODO where the developer swaps the generated records (and the JSON file under `.algolia-wizard/data/`) for their real record source."
     ]
@@ -4396,11 +4438,14 @@ function searchInstructions(input) {
     "If a search box already exists, replace it with yours.",
     `Read the index name from the ${searchIndexVar(input.language)} env var, which the wizard sets to "${input.targetIndex}". Never hardcode an index name or derive one from the project, file, or component name.`,
     "Read the App ID, the search-only API key, and the index name from env vars; never hardcode them. A search-only key is safe to expose client-side.",
-    // The key is provisioned only after verification passes, and the wizard
-    // reads .env to decide whether a key already exists — an agent-invented
-    // value there would be reused as if it were real.
+    // The key is provisioned only after verification passes, so the agent never
+    // sees one. It must also leave .env alone: the wizard reads that file to
+    // decide whether a key already exists, and an agent-invented value there
+    // would be reused as if it were real.
     `Add Algolia App ID "${input.appId}"; leave the search-only key as a placeholder. Do not create or edit .env \u2014 the wizard writes the resolved key there itself.`,
-    // The wizard writes these exact names into .env right after this step.
+    // Not the agent's to rename: the wizard writes these exact names into
+    // ".env" right after this step, so a renamed prefix would leave the code
+    // reading a var the wizard never wrote.
     `Use exactly these env var names in the code: ${input.searchEnvVars.map(({ name }) => name).join(", ")}.`,
     "Install any Algolia packages you import with the project's own package manager via runShell, and declare them in the project's dependency manifest.",
     "Match the styles of the application as closely as possible.",
@@ -4409,10 +4454,10 @@ function searchInstructions(input) {
 }
 function verificationInstructions(input) {
   return [
-    "Verify the Algolia implementation changes.",
+    "Verify the Algolia implementation changes in the current worktree.",
     `Verification tools found in the codebase: ${JSON.stringify(input.findings.verification ?? [])}.`,
     "Run the project's own checks (lint, type check, tests) via runShell, using the commands the project actually defines \u2014 its task runner, manifest scripts, or Makefile. Run every check that applies, not just the first.",
-    "If a check fails because packages or modules are missing, install the dependencies via runShell and re-run it rather than changing the code.",
+    "This worktree starts with no installed dependencies. If a check fails because packages or modules are missing, install the dependencies via runShell and re-run it rather than changing the code.",
     "For issues caused by the implementation, make minimal fixes with writeFile and re-run the checks.",
     "Do not make speculative fixes when no checks exist, a check cannot run, or failures are unrelated to these changes \u2014 note the limitation in your summary.",
     "Do not add new Algolia functionality here; only validate and make minimal correctness fixes.",
@@ -4507,11 +4552,11 @@ function ingestFailure(attempt, executions) {
   }
   return { reason: `it failed (exit ${attempt.exitCode ?? "unknown"})`, detail };
 }
-function makeToolContext(root, env = async () => ({})) {
+function makeToolContext(worktree, env = async () => ({})) {
   return createToolContext(
     DEFAULT_TOOL_LIMITS,
-    root,
-    createShellContext({ env, approve: storeApproval(root) })
+    worktree,
+    createShellContext({ env, approve: storeApproval(worktree) })
   );
 }
 function verificationRetryInstructions(verification) {
@@ -4519,7 +4564,7 @@ function verificationRetryInstructions(verification) {
     `Implementation insufficient. Address these findings before reporting completion: ${verification.additionalInstructions ?? verification.summary}`
   ];
 }
-async function implement(ctx, useCases = DEFAULT_IMPLEMENT_USE_CASES) {
+async function implement(ctx, useCases = DEFAULT_IMPLEMENT_USE_CASES, existingWorktreePath) {
   const repoRoot = process.cwd();
   const scan = ctx.getStepOutput("project-scan");
   const entities = ctx.getStepOutput(
@@ -4585,11 +4630,9 @@ async function implement(ctx, useCases = DEFAULT_IMPLEMENT_USE_CASES) {
   const targetIndex = selected?.selection;
   useWizard.getState().setTargetIndex(targetIndex ?? null);
   await assertGitRepoWithHead(repoRoot);
-  const ingestionAlreadyRan = ctx.getStepOutput("ingestion") != null;
-  if (!ingestionAlreadyRan && await isWorkingTreeDirty(repoRoot)) {
+  if (await isWorkingTreeDirty(repoRoot)) {
     await confirmDirtyWorkingTree(ctx, repoRoot);
   }
-  const baselineFiles = new Set(await listChangedFiles(repoRoot));
   const normalized = normalizeFindingPaths(findings);
   const confirmed2 = normalized.confirmedEntities;
   const searchLocation = normalized.searchImplementationAnalysis;
@@ -4601,292 +4644,314 @@ async function implement(ctx, useCases = DEFAULT_IMPLEMENT_USE_CASES) {
   if (useCases.includes("ingestion")) {
     ingestAppId = appId ?? (await requireApplication()).id;
   }
-  let uploadFilePath;
-  let uploadWarning;
-  if (ingestionSource === "fileUpload") {
-    const copied = await copyUploadIntoProject(
-      repoRoot,
-      INGEST_DIR,
-      uploadSourcePath ?? ""
-    );
-    if (copied.ok) {
-      uploadFilePath = copied.relPath;
-    } else {
-      ingestionSource = "generated";
-      uploadWarning = `\u26A0\uFE0F Could not use the uploaded file (${copied.reason}); generating sample records instead.`;
-      logger.warn(
-        { reason: copied.reason },
-        "implement: file upload unavailable; falling back to generated sample records"
+  const worktree = existingWorktreePath ?? (await createWorktree(repoRoot)).path;
+  try {
+    process.chdir(worktree);
+    let uploadFilePath;
+    let uploadWarning;
+    if (ingestionSource === "fileUpload") {
+      const copied = await copyUploadIntoWorktree(
+        repoRoot,
+        worktree,
+        INGEST_DIR,
+        uploadSourcePath ?? ""
       );
+      if (copied.ok) {
+        uploadFilePath = copied.relPath;
+      } else {
+        ingestionSource = "generated";
+        uploadWarning = `\u26A0\uFE0F Could not use the uploaded file (${copied.reason}); generating sample records instead.`;
+        logger.warn(
+          { reason: copied.reason },
+          "implement: file upload unavailable; falling back to generated sample records"
+        );
+      }
     }
-  }
-  const input = {
-    findings: normalized,
-    confirmed: confirmed2,
-    searchLocation,
-    targetIndex,
-    language,
-    appId,
-    searchEnvVars: searchEnvVars(language, targetIndex, appId),
-    ingestDir: INGEST_DIR,
-    ingestionSource,
-    uploadFilePath,
-    searchUiTarget: searchUiTarget(language)
-  };
-  const summaries = [];
-  if (uploadWarning) summaries.push(uploadWarning);
-  let envSearchKey;
-  let envAppIdMismatch = false;
-  if (useCases.includes("search") && appId) {
-    const envAppId = await readEnvVar(repoRoot, appIdVar(language));
-    if (envAppId === appId) {
-      envSearchKey = await readEnvVar(repoRoot, searchKeyVar(language));
-    } else if (envAppId) {
-      envAppIdMismatch = true;
-      summaries.push(
-        `\u26A0\uFE0F .env already sets ${appIdVar(language)}=${envAppId}, but the active Algolia application is ${appId}. The wizard left those values alone \u2014 update ${appIdVar(language)} and ${searchKeyVar(language)} by hand, or searches will fail.`
-      );
-      logger.warn(
-        { envAppId, appId },
-        "implement: .env holds credentials for a different Algolia application; not reusing its search key"
-      );
+    const input = {
+      findings: normalized,
+      confirmed: confirmed2,
+      searchLocation,
+      targetIndex,
+      language,
+      appId,
+      searchEnvVars: searchEnvVars(language, targetIndex, appId),
+      ingestDir: INGEST_DIR,
+      ingestionSource,
+      uploadFilePath,
+      searchUiTarget: searchUiTarget(language)
+    };
+    const summaries = [];
+    if (uploadWarning) summaries.push(uploadWarning);
+    let envSearchKey;
+    let envAppIdMismatch = false;
+    if (useCases.includes("search") && appId) {
+      const envAppId = await readEnvVar(worktree, appIdVar(language));
+      if (envAppId === appId) {
+        envSearchKey = await readEnvVar(worktree, searchKeyVar(language));
+      } else if (envAppId) {
+        envAppIdMismatch = true;
+        summaries.push(
+          `\u26A0\uFE0F .env already sets ${appIdVar(language)}=${envAppId}, but the active Algolia application is ${appId}. The wizard left those values alone \u2014 update ${appIdVar(language)} and ${searchKeyVar(language)} by hand, or searches will fail.`
+        );
+        logger.warn(
+          { envAppId, appId },
+          "implement: .env holds credentials for a different Algolia application; not reusing its search key"
+        );
+      }
     }
-  }
-  let finalSearchEnvVars = input.searchEnvVars;
-  let agentRuns = 0;
-  let ingestCommand;
-  let ingestScriptRan = false;
-  let ingestRecordCount;
-  let ingestDurationMs;
-  let ingestOutcomeMessage;
-  const ingestKeyAppId = ingestAppId;
-  const ingestionTools = ingestKeyAppId ? makeToolContext(repoRoot, async () => ({
-    [APP_ID_VAR]: ingestKeyAppId,
-    [API_KEY_VAR]: (await resolveWriteKey(targetIndex, ingestKeyAppId)).key,
-    [INDEX_NAME_VAR]: targetIndex
-  })) : void 0;
-  const searchTools = makeToolContext(repoRoot);
-  async function runImplementationUseCase(currentUseCase, extraInstructions = []) {
-    if (agentRuns > 0) ctx.recordStepExecution();
-    agentRuns += 1;
-    return runAgent({
-      instructions: buildAgentInstructions(
-        currentUseCase,
-        input,
-        extraInstructions
-      ),
-      tools: toolsForUseCase(currentUseCase, input.ingestionSource),
-      outputSchema: implementationOutputSchema,
-      toolContext: currentUseCase === "ingestion" ? ingestionTools ?? searchTools : searchTools
-    });
-  }
-  async function runVerificationUseCase() {
-    if (agentRuns > 0) ctx.recordStepExecution();
-    agentRuns += 1;
-    return runAgent({
-      instructions: buildAgentInstructions("verification", input),
-      tools: toolsForUseCase("verification"),
-      outputSchema: verificationOutputSchema,
-      toolContext: searchTools
-    });
-  }
-  if (useCases.includes("ingestion")) {
-    let ingestFailureDetail;
-    const result = await runImplementationUseCase("ingestion");
-    summaries.push(formatSummary("ingestion", result.summary));
-    ingestCommand = result.ingestCommand;
-    const ingestionContext = ingestionTools ?? searchTools;
-    const executions = ingestionContext.shell.executions;
-    const {
-      run: ingestRun,
-      attempt: ingestAttempt,
-      recordCount
-    } = ingestOutcome(executions, ingestCommand);
-    ingestScriptRan = ingestRun != null;
-    ingestRecordCount = recordCount;
-    ingestDurationMs = ingestRun?.durationMs;
-    if (ingestScriptRan && ingestionContext.reviewed.length === 0) {
-      summaries.push(
-        "\u26A0\uFE0F The ingestion script ran without being shown to you for review. Read it in your project before trusting the index contents."
-      );
-      logger.warn(
-        { ingestCommand },
-        "implement: ingestion ran without a reviewScript call"
-      );
+    let finalSearchEnvVars = input.searchEnvVars;
+    let agentRuns = 0;
+    let ingestCommand;
+    let ingestScriptRan = false;
+    let ingestRecordCount;
+    let ingestDurationMs;
+    let ingestOutcomeMessage;
+    const ingestKeyAppId = ingestAppId;
+    const ingestionTools = ingestKeyAppId ? makeToolContext(worktree, async () => ({
+      [APP_ID_VAR]: ingestKeyAppId,
+      [API_KEY_VAR]: (await resolveWriteKey(targetIndex, ingestKeyAppId)).key,
+      [INDEX_NAME_VAR]: targetIndex
+    })) : void 0;
+    const searchTools = makeToolContext(worktree);
+    async function runImplementationUseCase(currentUseCase, extraInstructions = []) {
+      if (agentRuns > 0) ctx.recordStepExecution();
+      agentRuns += 1;
+      return runAgent({
+        instructions: buildAgentInstructions(
+          currentUseCase,
+          input,
+          extraInstructions
+        ),
+        tools: toolsForUseCase(currentUseCase, input.ingestionSource),
+        outputSchema: implementationOutputSchema,
+        toolContext: currentUseCase === "ingestion" ? ingestionTools ?? searchTools : searchTools
+      });
     }
-    if (ingestScriptRan) {
-      ingestOutcomeMessage = `\u2705 Ingestion succeeded${ingestRecordCount != null ? ` \u2014 ${ingestRecordCount} record(s) indexed.` : "."}`;
-      if (ingestRecordCount != null) {
-        track("AI Wizard Ingest Successful", {
-          entity_name: confirmed2?.map((e) => e.name).join(", ") || "unknown",
-          record_count: ingestRecordCount,
-          duration_ms: ingestDurationMs ?? 0
-        });
-      }
-    } else {
-      const { reason, detail } = ingestFailure(ingestAttempt, executions);
-      ingestOutcomeMessage = `\u26A0\uFE0F Records were not indexed \u2014 ${reason}.${ingestCommand ? " Run the command below when you are ready." : ""}`;
-      ingestFailureDetail = detail;
-      summaries.push(
-        `\u26A0\uFE0F Ingestion did not complete: ${reason}.${detail ? `
-${detail}` : ""}`
-      );
-      logger.warn(
-        {
-          ingestCommand,
-          reason,
-          approved: ingestAttempt?.approved,
-          exitCode: ingestAttempt?.exitCode,
-          timedOut: ingestAttempt?.timedOut,
-          commandsRun: executions.length
-        },
-        "implement: ingestion script did not complete successfully"
-      );
-      track("Error", {
-        step: "Push Data",
-        error: `ingestion did not complete: ${reason}`,
-        product_area: "AI Wizard"
+    async function runVerificationUseCase() {
+      if (agentRuns > 0) ctx.recordStepExecution();
+      agentRuns += 1;
+      return runAgent({
+        instructions: buildAgentInstructions("verification", input),
+        tools: toolsForUseCase("verification"),
+        outputSchema: verificationOutputSchema,
+        toolContext: searchTools
       });
     }
-    const commandMessages = ingestCommand ? [`Ingestion command: ${ingestCommand}`] : [];
-    await ctx.requestUserInput({
-      prompt: "",
-      promptType: "enterToContinue",
-      options: [],
-      // One message per line: Notices.tsx counts a message as one wrapped
-      // line, so an embedded newline overflows the panel's height accounting.
-      messages: [
-        ingestOutcomeMessage,
-        ...ingestFailureDetail?.split("\n").filter((l) => l.trim()) ?? [],
-        ...commandMessages
-      ]
-    });
-  }
-  if (useCases.includes("search")) {
-    let extraInstructions = [];
-    const preSearchFiles = new Set(await listChangedFiles(repoRoot));
-    for (let attempt = 1; attempt <= MAX_IMPLEMENT_VERIFICATION_ATTEMPTS; attempt++) {
-      if (attempt > 1) {
-        logger.info(
-          {
-            attempt,
-            maxAttempts: MAX_IMPLEMENT_VERIFICATION_ATTEMPTS,
-            extraInstructions
-          },
-          "implement: retrying search implementation after failed verification"
-        );
-      }
-      const { summary } = await runImplementationUseCase(
-        "search",
-        extraInstructions
-      );
-      summaries.push(formatSummary("search", summary));
-      const verification = await runVerificationUseCase();
-      summaries.push(formatSummary("verification", verification.summary));
-      if (verification.sufficient) {
-        ctx.setUserInput("implementation", "success");
-        const searchFilesChanged = (await listChangedFiles(repoRoot)).filter(
-          (file) => !preSearchFiles.has(file)
+    if (useCases.includes("ingestion")) {
+      let ingestFailureDetail;
+      const result = await runImplementationUseCase("ingestion");
+      summaries.push(formatSummary("ingestion", result.summary));
+      ingestCommand = result.ingestCommand;
+      const ingestionContext = ingestionTools ?? searchTools;
+      const executions = ingestionContext.shell.executions;
+      const {
+        run: ingestRun,
+        attempt: ingestAttempt,
+        recordCount
+      } = ingestOutcome(executions, ingestCommand);
+      ingestScriptRan = ingestRun != null;
+      ingestRecordCount = recordCount;
+      ingestDurationMs = ingestRun?.durationMs;
+      if (ingestScriptRan && ingestionContext.reviewed.length === 0) {
+        summaries.push(
+          "\u26A0\uFE0F The ingestion script ran without being shown to you for review. Read it in the worktree before trusting the index contents."
         );
-        track("AI Wizard Frontend Component Generated", {
-          filePaths: searchFilesChanged
-        });
-        track("AI Wizard Wired to UI", {
-          location_heuristic: searchLocation ?? "unknown"
-        });
-        break;
-      }
-      if (attempt === MAX_IMPLEMENT_VERIFICATION_ATTEMPTS) {
-        ctx.setUserInput("implementation", "fail");
-        throw new Error(
-          `Implementation verification failed after ${MAX_IMPLEMENT_VERIFICATION_ATTEMPTS} attempts: ${verification.additionalInstructions ?? verification.summary}`
+        logger.warn(
+          { ingestCommand },
+          "implement: ingestion ran without a reviewScript call"
         );
       }
-      extraInstructions = verificationRetryInstructions(verification);
-    }
-    let searchKey;
-    let searchKeyError;
-    if (appId) {
-      try {
-        const resolved2 = await resolveSearchOnlyKey(
-          targetIndex,
-          appId,
-          envSearchKey
-        );
-        searchKey = resolved2.key;
+      if (ingestScriptRan) {
+        ingestOutcomeMessage = `\u2705 Ingestion succeeded${ingestRecordCount != null ? ` \u2014 ${ingestRecordCount} record(s) indexed.` : "."}`;
+        if (ingestRecordCount != null) {
+          track("AI Wizard Ingest Successful", {
+            entity_name: confirmed2?.map((e) => e.name).join(", ") || "unknown",
+            record_count: ingestRecordCount,
+            duration_ms: ingestDurationMs ?? 0
+          });
+        }
+      } else {
+        const { reason, detail } = ingestFailure(ingestAttempt, executions);
+        ingestOutcomeMessage = `\u26A0\uFE0F Records were not indexed \u2014 ${reason}.${ingestCommand ? " Run the command below when you are ready." : ""}`;
+        ingestFailureDetail = detail;
         summaries.push(
-          resolved2.source === "created" ? `Created a new search-only Algolia API key for the "${targetIndex}" index in app ${appId} \u2014 safe to expose in frontend code.` : `Reused the existing search-only Algolia API key for the "${targetIndex}" index in app ${appId}.`
+          `\u26A0\uFE0F Ingestion did not complete: ${reason}.${detail ? `
+${detail}` : ""}`
         );
-      } catch (err) {
-        searchKeyError = err.message;
         logger.warn(
-          { err: searchKeyError },
-          "implement: could not provision a search-only API key; the .env value stays a placeholder"
+          {
+            ingestCommand,
+            reason,
+            approved: ingestAttempt?.approved,
+            exitCode: ingestAttempt?.exitCode,
+            timedOut: ingestAttempt?.timedOut,
+            commandsRun: executions.length
+          },
+          "implement: ingestion script did not complete successfully"
         );
+        track("Error", {
+          step: "Push Data",
+          error: `ingestion did not complete: ${reason}`,
+          product_area: "AI Wizard"
+        });
       }
-    }
-    finalSearchEnvVars = searchEnvVars(language, targetIndex, appId, searchKey);
-    const resolvedSearchEnvVars = finalSearchEnvVars.filter(
-      (v) => !v.value.startsWith("<")
-    );
-    if (resolvedSearchEnvVars.length > 0) {
-      const written = await writeSearchEnvValues(repoRoot, resolvedSearchEnvVars);
-      if (written.length > 0) {
-        summaries.push(`Wrote ${written.join(", ")} to .env.`);
+      const commandMessages = [`Open the worktree: cd ${shellQuote(worktree)}`];
+      if (ingestCommand) {
+        commandMessages.push(`Ingestion command: ${ingestCommand}`);
       }
-      const ignored = await ensureGitIgnored(repoRoot, join12(repoRoot, ".env"));
-      if (ignored === "added") {
-        summaries.push("Added .env to .gitignore.");
-      } else if (ignored === "tracked") {
-        summaries.push(
-          '\u26A0\uFE0F .env is tracked by git, so a .gitignore rule cannot un-stage it. Run "git rm --cached .env" before committing, or the credentials go into history.'
+      await ctx.requestUserInput({
+        prompt: "",
+        promptType: "enterToContinue",
+        options: [],
+        // The wizard never streams command output, so a failed run's tail is the
+        // only place the developer sees why it failed. One message per line:
+        // the panel's height accounting counts a message as one wrapped line
+        // (see Notices.tsx), so an embedded newline overflows it.
+        messages: [
+          ingestOutcomeMessage,
+          ...ingestFailureDetail?.split("\n").filter((l) => l.trim()) ?? [],
+          ...commandMessages
+        ]
+      });
+    }
+    if (useCases.includes("search")) {
+      let extraInstructions = [];
+      const preSearchFiles = new Set(await listChangedFiles(worktree));
+      for (let attempt = 1; attempt <= MAX_IMPLEMENT_VERIFICATION_ATTEMPTS; attempt++) {
+        if (attempt > 1) {
+          logger.info(
+            {
+              attempt,
+              maxAttempts: MAX_IMPLEMENT_VERIFICATION_ATTEMPTS,
+              extraInstructions
+            },
+            "implement: retrying search implementation after failed verification"
+          );
+        }
+        const { summary } = await runImplementationUseCase(
+          "search",
+          extraInstructions
         );
+        summaries.push(formatSummary("search", summary));
+        const verification = await runVerificationUseCase();
+        summaries.push(formatSummary("verification", verification.summary));
+        if (verification.sufficient) {
+          ctx.setUserInput("implementation", "success");
+          const searchFilesChanged = (await listChangedFiles(worktree)).filter(
+            (file) => !preSearchFiles.has(file)
+          );
+          track("AI Wizard Frontend Component Generated", {
+            filePaths: searchFilesChanged
+          });
+          track("AI Wizard Wired to UI", {
+            location_heuristic: searchLocation ?? "unknown"
+          });
+          break;
+        }
+        if (attempt === MAX_IMPLEMENT_VERIFICATION_ATTEMPTS) {
+          ctx.setUserInput("implementation", "fail");
+          throw new Error(
+            `Implementation verification failed after ${MAX_IMPLEMENT_VERIFICATION_ATTEMPTS} attempts: ${verification.additionalInstructions ?? verification.summary}`
+          );
+        }
+        extraInstructions = verificationRetryInstructions(verification);
       }
-      const stale = [];
-      for (const v of resolvedSearchEnvVars) {
-        if (written.includes(v.name)) continue;
-        const current = await readEnvVar(repoRoot, v.name);
-        if (current && current !== v.value) stale.push(v);
+      let searchKey;
+      let searchKeyError;
+      if (appId) {
+        try {
+          const resolved2 = await resolveSearchOnlyKey(
+            targetIndex,
+            appId,
+            envSearchKey
+          );
+          searchKey = resolved2.key;
+          summaries.push(
+            resolved2.source === "created" ? `Created a new search-only Algolia API key for the "${targetIndex}" index in app ${appId} \u2014 safe to expose in frontend code.` : `Reused the existing search-only Algolia API key for the "${targetIndex}" index in app ${appId}.`
+          );
+        } catch (err) {
+          searchKeyError = err.message;
+          logger.warn(
+            { err: searchKeyError },
+            "implement: could not provision a search-only API key; the .env value stays a placeholder"
+          );
+        }
       }
-      if (stale.length > 0 && !envAppIdMismatch) {
-        summaries.push(
-          `\u26A0\uFE0F .env already assigns a different value to ${stale.map((v) => `${v.name} (should be ${v.value})`).join(", ")} \u2014 the wizard left it alone. Fix it by hand, or searches will fail.`
+      finalSearchEnvVars = searchEnvVars(
+        language,
+        targetIndex,
+        appId,
+        searchKey
+      );
+      const resolvedSearchEnvVars = finalSearchEnvVars.filter(
+        (v) => !v.value.startsWith("<")
+      );
+      if (resolvedSearchEnvVars.length > 0) {
+        const written = await writeSearchEnvValues(
+          worktree,
+          resolvedSearchEnvVars
         );
-        logger.warn(
-          { vars: stale.map((v) => v.name) },
-          "implement: .env holds different values for the resolved search credentials; not overwriting them"
+        if (written.length > 0) {
+          summaries.push(`Wrote ${written.join(", ")} to .env.`);
+        }
+        const ignored = await ensureGitIgnored(worktree, join12(worktree, ".env"));
+        if (ignored === "added") {
+          summaries.push("Added .env to .gitignore.");
+        } else if (ignored === "tracked") {
+          summaries.push(
+            '\u26A0\uFE0F .env is tracked by git, so a .gitignore rule cannot un-stage it. Run "git rm --cached .env" before committing, or the credentials go into history.'
+          );
+        }
+        const stale = [];
+        for (const v of resolvedSearchEnvVars) {
+          if (written.includes(v.name)) continue;
+          const current = await readEnvVar(worktree, v.name);
+          if (current && current !== v.value) stale.push(v);
+        }
+        if (stale.length > 0 && !envAppIdMismatch) {
+          summaries.push(
+            `\u26A0\uFE0F .env already assigns a different value to ${stale.map((v) => `${v.name} (should be ${v.value})`).join(", ")} \u2014 the wizard left it alone. Fix it by hand, or searches will fail.`
+          );
+          logger.warn(
+            { vars: stale.map((v) => v.name) },
+            "implement: .env holds different values for the resolved search credentials; not overwriting them"
+          );
+        }
+      }
+      const unresolvedSearchEnvVars = finalSearchEnvVars.filter(
+        (v) => v.value.startsWith("<")
+      );
+      if (unresolvedSearchEnvVars.length > 0) {
+        summaries.push(
+          `Could not resolve a value for ${unresolvedSearchEnvVars.map((v) => v.name).join(", ")} \u2014 fill it in manually in .env.` + // Without the reason the line is a dead end.
+          (searchKeyError ? ` Reason: ${searchKeyError}` : "")
         );
       }
+    } else {
+      ctx.setUserInput("implementation", "success");
     }
-    const unresolvedSearchEnvVars = finalSearchEnvVars.filter(
-      (v) => v.value.startsWith("<")
-    );
-    if (unresolvedSearchEnvVars.length > 0) {
-      summaries.push(
-        `Could not resolve a value for ${unresolvedSearchEnvVars.map((v) => v.name).join(", ")} \u2014 fill it in manually in .env.` + (searchKeyError ? ` Reason: ${searchKeyError}` : "")
+    const filesChanged = await listChangedFiles(worktree);
+    if (filesChanged.length === 0) {
+      logger.warn(
+        "implement: agent reported success but no files changed in the worktree"
       );
     }
-  } else {
-    ctx.setUserInput("implementation", "success");
-  }
-  const filesChanged = (await listChangedFiles(repoRoot)).filter(
-    (file) => !baselineFiles.has(file)
-  );
-  if (filesChanged.length === 0) {
-    logger.warn("implement: agent reported success but no files changed");
+    return {
+      ingestionSource,
+      filesChanged,
+      summary: summaries.join("\n\n"),
+      worktreePath: worktree,
+      ...useCases.includes("ingestion") && ingestCommand ? {
+        ingestCommand,
+        ingestScriptRan,
+        ...ingestRecordCount != null ? { ingestRecordCount } : {},
+        ...ingestDurationMs != null ? { ingestDurationMs } : {}
+      } : {},
+      ...useCases.includes("search") ? { searchEnvVars: finalSearchEnvVars } : {}
+    };
+  } finally {
+    process.chdir(repoRoot);
   }
-  return {
-    ingestionSource,
-    filesChanged,
-    summary: summaries.join("\n\n"),
-    ...useCases.includes("ingestion") && ingestCommand ? {
-      ingestCommand,
-      ingestScriptRan,
-      ...ingestRecordCount != null ? { ingestRecordCount } : {},
-      ...ingestDurationMs != null ? { ingestDurationMs } : {}
-    } : {},
-    ...useCases.includes("search") ? { searchEnvVars: finalSearchEnvVars } : {}
-  };
 }
 
 // src/workflows/default.ts
@@ -4958,7 +5023,10 @@ var defaultWorkflow = {
         ctx.notify({
           messages: ["Building your Algolia search experience\u2026"]
         });
-        return implement(ctx, ["search"]);
+        const ingestion2 = ctx.getStepOutput(
+          "ingestion"
+        );
+        return implement(ctx, ["search"], ingestion2?.worktreePath);
       }
     }),
     defineStep({
@@ -4973,8 +5041,9 @@ var defaultWorkflow = {
           "ingestion"
         );
         return reviewStep(ctx, {
-          // ingestCommand was already shown verbatim as a notice; an
-          // LLM-paraphrased restatement in nextSteps risks being wrong.
+          // The ingestion step already showed the user the exact `ingestCommand`
+          // and worktree path as a notice, so nextSteps must not restate it —
+          // an LLM-paraphrased command risks being wrong.
           nextStepsGuidance: ingestion2?.ingestScriptRan ? "The wizard already ran the ingestion script and records are in the index. Do NOT tell the user to run it again; instead point them at the target index to confirm the records. Do not restate the ingestion command \u2014 the wizard already showed it to them." : "Tell the user to run the ingestion script; do not restate the exact command \u2014 the wizard already showed it to them above."
         });
       }
@@ -5045,7 +5114,7 @@ var review = {
     "Ingested 25 generated Product records into wizard_seed_products.",
     "Added an InstantSearch search experience to the shared header."
   ],
-  reviewPrompt: "Review the Algolia ingestion and search changes.",
+  reviewPrompt: "Review the Algolia ingestion and search changes in this worktree.",
   nextSteps: ["Point the ingestion script at your real product data."]
 };
 var SEEDS = {
@@ -5162,9 +5231,9 @@ Options:
                    steps pre-filled with test data. Pass with no value to print
                    the step ids. See CONTRIBUTING.md.
   --no-telemetry   Send no telemetry or analytics for this run.
-  --reset-on-run   Wipe this project's wizard state (run state, AI consent)
-                   before starting, so the run behaves like a first-ever
-                   run. Also drops every API key the wizard has
+  --reset-on-run   Wipe this project's wizard state (run state, AI consent,
+                   worktrees) before starting, so the run behaves like a
+                   first-ever run. Also drops every API key the wizard has
                    stored in your keychain (or, where the platform has none,
                    the encrypted file it falls back to \u2014 see CONTRIBUTING.md),
                    for this project and any other, so later runs create new
@@ -5204,7 +5273,7 @@ function parseCliArgs(argv) {
 }
 
 // src/lib/resetState.ts
-import { readdir as readdir3, rm as rm2 } from "node:fs/promises";
+import { readdir as readdir4, rm as rm2 } from "node:fs/promises";
 import { join as join13 } from "node:path";
 var KEEP = ["wizard.log"];
 async function resetProjectState() {
@@ -5212,7 +5281,7 @@ async function resetProjectState() {
   await forgetResolvedKeys();
   let entries;
   try {
-    entries = await readdir3(dir);
+    entries = await readdir4(dir);
   } catch {
     return { dir, removed: [] };
   }
@@ -5225,6 +5294,45 @@ async function resetProjectState() {
   return { dir, removed: targets };
 }
 
+// src/lib/terminalSize.ts
+var MIN_ROWS = 30;
+var MIN_COLUMNS = 100;
+async function requestTerminalSize(stdout = process.stdout, {
+  rows = MIN_ROWS,
+  columns = MIN_COLUMNS,
+  timeoutMs = 150,
+  settleMs = 120
+} = {}) {
+  if (!stdout.isTTY) return;
+  const currentRows = stdout.rows ?? 0;
+  const currentColumns = stdout.columns ?? 0;
+  if (currentRows >= rows && currentColumns >= columns) return;
+  stdout.write(
+    `\x1B[8;${Math.max(currentRows, rows)};${Math.max(currentColumns, columns)}t`
+  );
+  const resized = await waitForResize(stdout, timeoutMs);
+  if (!resized) return;
+  await delay(settleMs);
+  stdout.write("\x1B[2J\x1B[H");
+}
+function waitForResize(stdout, timeoutMs) {
+  return new Promise((resolve4) => {
+    const finish = (didResize) => () => {
+      clearTimeout(timer);
+      stdout.off("resize", onResize);
+      resolve4(didResize);
+    };
+    const onResize = finish(true);
+    const timer = setTimeout(finish(false), timeoutMs);
+    stdout.once("resize", onResize);
+  });
+}
+function delay(ms) {
+  return new Promise((resolve4) => {
+    setTimeout(resolve4, ms);
+  });
+}
+
 // src/main.tsx
 import { jsx as jsx15 } from "react/jsx-runtime";
 async function startup() {
@@ -5309,6 +5417,7 @@ async function run(workflow) {
   }
   runWorkflow(workflow, app.id);
 }
+await requestTerminalSize();
 var started = await startup();
 if (typeof started === "number") {
   process.exitCode = started;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@algolia/wizard",
-  "version": "0.19.0-rc.111.186",
+  "version": "0.19.0",
   "description": "Magically implement Algolia functionality in your codebase",
   "type": "module",
   "engines": {