@algolia/wizard 0.15.0 → 0.17.0

package/dist/main.js

@@ -2246,7 +2246,7 @@ async function ensureApplication() {
 }
 
 // src/workflows/default.ts
-import { z as z28 } from "zod";
+import { z as z29 } from "zod";
 
 // src/actions/listIndices.ts
 import { z as z5 } from "zod";
@@ -2507,8 +2507,8 @@ function writeFileTool(ctx) {
 // src/lib/tools/writeAlgoliaCredentials.ts
 import { tool as tool6 } from "ai";
 import z13 from "zod";
-import { mkdir as mkdir4, readFile as readFile5, writeFile as writeFile4 } from "node:fs/promises";
-import { dirname as dirname5 } from "node:path";
+import { mkdir as mkdir4, readFile as readFile6, writeFile as writeFile5 } from "node:fs/promises";
+import { dirname as dirname5, relative as relative3 } from "node:path";
 
 // src/lib/algoliaApiKey.ts
 import { z as z12 } from "zod";
@@ -2690,6 +2690,79 @@ async function resolveSearchOnlyKey(index, appId, envKey) {
   );
 }
 
+// src/lib/gitignore.ts
+import { execFile } from "node:child_process";
+import { lstat as lstat2, readFile as readFile5, writeFile as writeFile4 } from "node:fs/promises";
+import { join as join8, relative as relative2 } from "node:path";
+var GIT_ENV_OVERRIDES = [
+  "GIT_DIR",
+  "GIT_WORK_TREE",
+  "GIT_INDEX_FILE",
+  "GIT_OBJECT_DIRECTORY",
+  "GIT_COMMON_DIR"
+];
+function gitSucceeds(root, args) {
+  const env = { ...process.env };
+  for (const key of GIT_ENV_OVERRIDES) delete env[key];
+  return new Promise((resolve4) => {
+    execFile("git", ["-C", root, ...args], { env }, (err) => {
+      if (!err) return resolve4(true);
+      resolve4(
+        err.code === 1 ? false : void 0
+      );
+    });
+  });
+}
+function isIgnoredByRule(root, relPath) {
+  return gitSucceeds(root, ["check-ignore", "-q", "--no-index", "--", relPath]);
+}
+function isTracked(root, relPath) {
+  return gitSucceeds(root, ["ls-files", "--error-unmatch", "--", relPath]);
+}
+async function inspect(root, target) {
+  const relPath = relative2(root, target);
+  if (!relPath || relPath.startsWith("..")) {
+    return { ignoredByRule: void 0, tracked: false };
+  }
+  const ignoredByRule = await isIgnoredByRule(root, relPath);
+  if (ignoredByRule === void 0) {
+    logger.warn(
+      { root, relPath },
+      "gitignore: git check-ignore could not answer; not reporting on this path"
+    );
+    return { ignoredByRule, tracked: false };
+  }
+  return { ignoredByRule, tracked: await isTracked(root, relPath) };
+}
+async function ensureGitIgnored(root, target) {
+  const { ignoredByRule, tracked } = await inspect(root, target);
+  if (ignoredByRule === void 0) return "unknown";
+  if (ignoredByRule) return tracked ? "tracked" : "covered";
+  const pattern = relative2(root, target);
+  const gitIgnore = join8(root, ".gitignore");
+  try {
+    const link = await lstat2(gitIgnore).catch(() => null);
+    if (link?.isSymbolicLink()) {
+      logger.warn(
+        { gitIgnore },
+        "gitignore: root .gitignore is a symlink; not writing to it"
+      );
+      return "unknown";
+    }
+    const existing = link ? await readFile5(gitIgnore, "utf8") : "";
+    const prefix = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+    await writeFile4(gitIgnore, `${existing}${prefix}${pattern}
+`, "utf8");
+    return tracked ? "tracked" : "added";
+  } catch (err) {
+    logger.warn(
+      { gitIgnore, pattern, err: err.message },
+      "gitignore: could not add the pattern; continuing"
+    );
+    return "unknown";
+  }
+}
+
 // src/lib/tools/writeAlgoliaCredentials.ts
 var APP_ID_VAR = "ALGOLIA_APPLICATION_ID";
 var API_KEY_VAR = "ALGOLIA_WRITE_API_KEY";
@@ -2722,7 +2795,7 @@ function upsertEnv(content, name, value) {
 }
 function writeCredentialsTool(ctx) {
   return tool6({
-    description: `Write the active Algolia credentials (${APP_ID_VAR} and ${API_KEY_VAR}) and the target index name (${INDEX_NAME_VAR}) into the given env file. The credentials come from the selected Algolia application, with a write key scoped to the target index; you only pass the path to the env file. ${INDEX_NAME_VAR} is always set to this run's target index, replacing any value already there. An ${APP_ID_VAR} or ${API_KEY_VAR} the file already gives a value is left untouched; a missing or blank one is filled in when it can be paired with the selected application.`,
+    description: `Write the active Algolia credentials (${APP_ID_VAR} and ${API_KEY_VAR}) and the target index name (${INDEX_NAME_VAR}) into the given env file. The credentials come from the selected Algolia application, with a write key scoped to the target index; you only pass the path to the env file. ${INDEX_NAME_VAR} is always set to this run's target index, replacing any value already there. An ${APP_ID_VAR} or ${API_KEY_VAR} the file already gives a value is left untouched; a missing or blank one is filled in when it can be paired with the selected application. The env file is added to .gitignore automatically; do not edit .gitignore yourself.`,
     inputSchema: z13.object({
       filePath: z13.string().describe(
         'Path to the env file to write credentials into (e.g. ".env")'
@@ -2743,7 +2816,7 @@ function writeCredentialsTool(ctx) {
           return `Refused: ${resolved2.target} is outside the repo root (${ctx.root}).`;
         }
         try {
-          existing = await readFile5(resolved2.target, "utf8");
+          existing = await readFile6(resolved2.target, "utf8");
         } catch (err) {
           if (err.code !== "ENOENT") throw err;
         }
@@ -2782,6 +2855,7 @@ function writeCredentialsTool(ctx) {
           return `Error: could not resolve Algolia credentials (${err.message}). Ask the user to authenticate with the Algolia CLI first.`;
         }
       }
+      let wrote;
       try {
         const updated = [
           ...credentials,
@@ -2793,7 +2867,7 @@ function writeCredentialsTool(ctx) {
           existing
         );
         await mkdir4(dirname5(resolved2.target), { recursive: true });
-        await writeFile4(resolved2.target, updated, "utf8");
+        await writeFile5(resolved2.target, updated, "utf8");
         const sentences = [
           `Wrote ${[...credentials.map(([name]) => name), INDEX_NAME_VAR].join(", ")} to ${filePath}.`
         ];
@@ -2807,19 +2881,33 @@ function writeCredentialsTool(ctx) {
             `Skipped ${present.join(" and ")}: already defined there.`
           );
         }
-        return [...sentences, ...notes].join(" ");
+        wrote = [...sentences, ...notes].join(" ");
       } catch (err) {
         return `Error writing credentials to ${filePath}: ${err.message}`;
       }
+      return wrote + await gitIgnoreOutcome(ctx, resolved2.target);
     }
   });
 }
+async function gitIgnoreOutcome(ctx, target) {
+  const name = relative3(ctx.root, target);
+  switch (await ensureGitIgnored(ctx.root, target)) {
+    case "added":
+      return ` Added "${name}" to .gitignore so the credentials are not stageable.`;
+    case "tracked":
+      return ` Warning: ${name} is already tracked by git, and a .gitignore rule cannot un-stage it. Tell the user with notifyUser to run "git rm --cached ${name}" before committing.`;
+    case "unknown":
+      return ` Warning: could not confirm ${name} is gitignored. Tell the user with notifyUser to check before committing.`;
+    case "covered":
+      return "";
+  }
+}
 
 // src/lib/tools/searchFiles.ts
 import { tool as tool7 } from "ai";
 import z14 from "zod";
-import { readdir as readdir2, readFile as readFile6 } from "node:fs/promises";
-import { join as join8 } from "node:path";
+import { readdir as readdir2, readFile as readFile7 } from "node:fs/promises";
+import { join as join9 } from "node:path";
 var MAX_QUERY_LENGTH = 1e3;
 var SKIP_DIRS = /* @__PURE__ */ new Set([
   "node_modules",
@@ -2834,7 +2922,7 @@ async function walkFiles(dir) {
   const out = [];
   for (const e of await readdir2(dir, { withFileTypes: true })) {
     if (e.name.startsWith(".") || SKIP_DIRS.has(e.name)) continue;
-    const full = join8(dir, e.name);
+    const full = join9(dir, e.name);
     if (e.isDirectory()) out.push(...await walkFiles(full));
     else if (e.isFile()) out.push(full);
   }
@@ -2867,7 +2955,7 @@ function searchFilesTool(ctx) {
       for (const file of await walkFiles(resolved2.target)) {
         let content;
         try {
-          content = await readFile6(file, "utf8");
+          content = await readFile7(file, "utf8");
         } catch {
           continue;
         }
@@ -2890,7 +2978,16 @@ function searchFilesTool(ctx) {
 // src/lib/tools/runShell.ts
 import { tool as tool8 } from "ai";
 import z15 from "zod";
-import { relative as relative2 } from "node:path";
+import { relative as relative4 } from "node:path";
+
+// src/lib/tools/utils/prompt.ts
+var chain = Promise.resolve();
+function serializePrompt(work) {
+  const result = chain.then(work);
+  chain = result.catch(() => {
+  });
+  return result;
+}
 
 // src/lib/tools/utils/runShell.ts
 import { spawn as spawn2 } from "node:child_process";
@@ -2922,7 +3019,8 @@ function createToolContext(limits = DEFAULT_TOOL_LIMITS, cwd = process.cwd(), sh
     cwd,
     limits: { ...limits },
     counts: { list: 0, search: 0, read: 0, shell: 0 },
-    shell: shell2
+    shell: shell2,
+    reviewed: []
   };
 }
 
@@ -2987,7 +3085,7 @@ function runShell(command, opts) {
 // src/lib/tools/runShell.ts
 function storeApproval(root) {
   return async (req) => {
-    const rel = relative2(root, req.cwd);
+    const rel = relative4(root, req.cwd);
     const answer = await useWizard.getState().requestUserInput({
       prompt: "Run this command?",
       promptType: "commandApproval",
@@ -3000,13 +3098,6 @@ function storeApproval(root) {
     return answer === "approve" ? "approve" : "reject";
   };
 }
-var shellChain = Promise.resolve();
-function serialize(work) {
-  const result = shellChain.then(work);
-  shellChain = result.catch(() => {
-  });
-  return result;
-}
 async function approveAndRun(ctx, command, cwd, explanation) {
   const decision = await ctx.shell.approve({ command, cwd, explanation });
   if (decision === "reject") {
@@ -3070,20 +3161,81 @@ function runShellTool(ctx) {
       const resolved2 = resolveInRoot(ctx, cwd ?? ".");
       if (!resolved2.ok) return resolved2.error;
       logger.info({ command, cwd: resolved2.target }, "called runShell tool");
-      return serialize(
+      return serializePrompt(
         () => approveAndRun(ctx, command, resolved2.target, explanation)
       );
     }
   });
 }
 
+// src/lib/tools/reviewScript.ts
+import { tool as tool9 } from "ai";
+import z16 from "zod";
+import { stat as stat2 } from "node:fs/promises";
+import { relative as relative5 } from "node:path";
+
+// src/lib/editor.ts
+import { spawn as spawn3 } from "node:child_process";
+function openInEditor(filePath) {
+  const { command, args } = process.platform === "darwin" ? (
+    // -t forces the default *text* editor; plain `open` on an extension
+    // with no handler (.mjs, .py) pops a "choose an application" dialog.
+    { command: "open", args: ["-t", filePath] }
+  ) : process.platform === "win32" ? { command: "cmd", args: ["/c", "start", "", filePath] } : { command: "xdg-open", args: [filePath] };
+  try {
+    const child = spawn3(command, args, { stdio: "ignore", detached: true });
+    child.on("error", () => {
+    });
+    child.unref();
+  } catch {
+  }
+}
+
+// src/lib/tools/reviewScript.ts
+function reviewScriptTool(ctx) {
+  return tool9({
+    description: "Show a script you have written to the user and wait while they read it. Call this as soon as the script is finished and before you run it for the first time, so nothing with a side effect happens behind their back. It opens the file in their editor and returns once they have confirmed.",
+    inputSchema: z16.object({
+      filePath: z16.string().describe(
+        "Path to the script to review, relative to the project root."
+      )
+    }),
+    execute: async ({ filePath }) => {
+      logger.info({ filePath }, "called reviewScript tool");
+      const resolved2 = resolveInRoot(ctx, filePath);
+      if (resolved2.ok === false) return resolved2.error;
+      const isFile = await stat2(resolved2.target).then(
+        (s) => s.isFile(),
+        () => false
+      );
+      if (!isFile) {
+        return `Refused: ${filePath} is not a file. Write the script first, then review the path you wrote.`;
+      }
+      return serializePrompt(async () => {
+        openInEditor(resolved2.target);
+        await useWizard.getState().requestUserInput({
+          prompt: "",
+          promptType: "enterToContinue",
+          options: [],
+          messages: [
+            `Please review ${relative5(ctx.root, resolved2.target)} before it runs:`,
+            resolved2.target
+          ]
+        });
+        ctx.reviewed.push(resolved2.target);
+        return "The user has reviewed the script. You may run it now.";
+      });
+    }
+  });
+}
+
 // src/lib/tools/generateRecord.ts
-import { tool as tool9, generateText, Output, NoObjectGeneratedError } from "ai";
+import { tool as tool10, generateText, Output, NoObjectGeneratedError } from "ai";
 import { createAnthropic } from "@ai-sdk/anthropic";
 import { nanoid as nanoid2 } from "nanoid";
-import { mkdir as mkdir5, writeFile as writeFile5 } from "node:fs/promises";
+import { mkdir as mkdir5, writeFile as writeFile6 } from "node:fs/promises";
 import { dirname as dirname6 } from "node:path";
-import z16 from "zod";
+import z17 from "zod";
 var DATA_DIR = ".algolia-wizard/data";
 var RECORD_MODEL = "claude-haiku-4-5";
 var MAX_RECORDS = 100;
@@ -3093,19 +3245,19 @@ var anthropic = createAnthropic({
   apiKey: process.env.PROVIDER_API_KEY ?? ""
 });
 function generateRecordTool(ctx) {
-  return tool9({
+  return tool10({
     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: z16.object({
-      entityName: z16.string().describe("Name of the entity to generate records for."),
-      attributes: z16.array(z16.string()).describe("Attribute names each record must contain."),
-      count: z16.number().int().min(1).max(MAX_RECORDS).default(10).describe(`How many records to generate (max ${MAX_RECORDS}).`),
-      hint: z16.string().optional().describe("Optional context to steer realistic values.")
+    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."),
+      count: z17.number().int().min(1).max(MAX_RECORDS).default(10).describe(`How many records to generate (max ${MAX_RECORDS}).`),
+      hint: z17.string().optional().describe("Optional context to steer realistic values.")
     }),
     execute: async ({ entityName, attributes, count, hint }) => {
       logger.info({ entityName, count }, "called generateRecord tool");
       try {
-        const value = z16.union([z16.string(), z16.number(), z16.boolean(), z16.null()]);
-        const recordSchema = z16.object(
+        const value = z17.union([z17.string(), z17.number(), z17.boolean(), z17.null()]);
+        const recordSchema = z17.object(
           Object.fromEntries(attributes.map((attr) => [attr, value]))
         );
         const generateBatch = async (batchCount) => {
@@ -3115,8 +3267,8 @@ function generateRecordTool(ctx) {
               const { output } = await generateText({
                 model: anthropic(RECORD_MODEL),
                 output: Output.object({
-                  schema: z16.object({
-                    records: z16.array(recordSchema).length(batchCount)
+                  schema: z17.object({
+                    records: z17.array(recordSchema).length(batchCount)
                   })
                 }),
                 prompt: [
@@ -3158,7 +3310,7 @@ function generateRecordTool(ctx) {
           return `Refused: ${resolved2.target} is outside the repo root (${ctx.root}).`;
         }
         await mkdir5(dirname6(resolved2.target), { recursive: true });
-        await writeFile5(resolved2.target, JSON.stringify(records, null, 2), "utf8");
+        await writeFile6(resolved2.target, JSON.stringify(records, null, 2), "utf8");
         logger.info({ entityName, count: records.length, relPath }, "generateRecord wrote records to disk");
         return {
           filePath: relPath,
@@ -3173,13 +3325,13 @@ function generateRecordTool(ctx) {
 }
 
 // src/lib/tools/notifyUser.ts
-import { tool as tool10 } from "ai";
-import z17 from "zod";
+import { tool as tool11 } from "ai";
+import z18 from "zod";
 function notifyUserTool() {
-  return tool10({
+  return tool11({
     description: `Give the user a brief, high-level update on what you are currently doing or about to do next. This is for the big picture (e.g. "Reading through your data models", "Writing the search UI") \u2014 not granular detail like individual tool calls, which are already logged separately. Call it when you start a new phase of work or your focus shifts, just not on every step, enough to keep the user engaged. Don't say things like "starting", just describe what you are doing. Don't mention tool calls themselves, just general direction of the work.`,
-    inputSchema: z17.object({
-      message: z17.string().describe(
+    inputSchema: z18.object({
+      message: z18.string().describe(
         "Short, plain-language description of what you are doing now."
       )
     }),
@@ -3223,6 +3375,7 @@ function createTools(ctx, { output, tools }) {
     ),
     searchFiles: withLogging("searchFiles", searchFilesTool(ctx)),
     runShell: withLogging("runShell", runShellTool(ctx)),
+    reviewScript: withLogging("reviewScript", reviewScriptTool(ctx)),
     generateRecord: withLogging("generateRecord", generateRecordTool(ctx)),
     notifyUser: withLogging("notifyUser", notifyUserTool())
   };
@@ -3344,10 +3497,10 @@ async function runAgent(req) {
 }
 
 // src/actions/detectLanguage.ts
-import z20 from "zod";
-var detectLanguageSchema = z20.object({
-  languages: z20.array(z20.object({ name: z20.string(), version: z20.string() })),
-  frameworks: z20.array(z20.object({ name: z20.string(), version: z20.string() }))
+import z21 from "zod";
+var detectLanguageSchema = z21.object({
+  languages: z21.array(z21.object({ name: z21.string(), version: z21.string() })),
+  frameworks: z21.array(z21.object({ name: z21.string(), version: z21.string() }))
 });
 var detectLanguage = () => runAgent({
   instructions: [
@@ -3365,31 +3518,31 @@ var detectLanguage = () => runAgent({
 });
 
 // src/actions/analyzeCodebase.ts
-import z21 from "zod";
+import z22 from "zod";
 var READONLY_TOOLS = [
   "listFiles",
   "changeDirectory",
   "readFile",
   "searchFiles"
 ];
-var ingestionAnalysisSchema = z21.object({
-  ingestionAnalysis: z21.array(
-    z21.object({
-      name: z21.string(),
-      paths: z21.array(z21.string()),
+var ingestionAnalysisSchema = z22.object({
+  ingestionAnalysis: z22.array(
+    z22.object({
+      name: z22.string(),
+      paths: z22.array(z22.string()),
       // indexable fields the agent found for this entity
-      attributes: z21.array(z21.string())
+      attributes: z22.array(z22.string())
     })
   )
 });
-var searchImplementationAnalysisSchema = z21.object({
-  searchImplementationAnalysis: z21.string()
+var searchImplementationAnalysisSchema = z22.object({
+  searchImplementationAnalysis: z22.string()
 });
-var verificationSchema = z21.object({
-  verification: z21.array(z21.string())
+var verificationSchema = z22.object({
+  verification: z22.array(z22.string())
 });
 var confirmedEntitiesFieldSchema = ingestionAnalysisSchema.shape.ingestionAnalysis.optional();
-var analyzeCodebaseSchema = z21.object({
+var analyzeCodebaseSchema = z22.object({
   ingestionAnalysis: ingestionAnalysisSchema.shape.ingestionAnalysis.optional(),
   searchImplementationAnalysis: searchImplementationAnalysisSchema.shape.searchImplementationAnalysis.optional(),
   verification: verificationSchema.shape.verification.optional(),
@@ -3451,7 +3604,7 @@ async function runAnalysis(mode, extraInstructions = []) {
 // package.json
 var package_default = {
   name: "@algolia/wizard",
-  version: "0.15.0",
+  version: "0.17.0",
   description: "Magically implement Algolia functionality in your codebase",
   type: "module",
   engines: {
@@ -3570,8 +3723,8 @@ async function askList(ctx, prompt, { required = false } = {}) {
 }
 
 // src/actions/confirmLanguage.ts
-import z23 from "zod";
-var confirmLanguageSchema = z23.object({
+import z24 from "zod";
+var confirmLanguageSchema = z24.object({
   languages: detectLanguageSchema.shape.languages
 });
 async function confirmLanguage(ctx) {
@@ -3592,8 +3745,8 @@ async function confirmLanguage(ctx) {
 }
 
 // src/actions/confirmFramework.ts
-import z24 from "zod";
-var confirmFrameworkSchema = z24.object({
+import z25 from "zod";
+var confirmFrameworkSchema = z25.object({
   frameworks: detectLanguageSchema.shape.frameworks
 });
 var CURATED_FRAMEWORKS = [
@@ -3726,8 +3879,8 @@ async function promptUser(ctx, params) {
 }
 
 // src/actions/confirmEntities.ts
-import z25 from "zod";
-var confirmEntitiesSchema = z25.object({
+import z26 from "zod";
+var confirmEntitiesSchema = z26.object({
   // Final detection — the focused re-run may supersede project-scan's.
   ingestionAnalysis: ingestionAnalysisSchema.shape.ingestionAnalysis.optional(),
   confirmedEntities: confirmedEntitiesFieldSchema
@@ -3797,15 +3950,15 @@ async function confirmEntities(ctx) {
 }
 
 // src/actions/review.ts
-import { z as z26 } from "zod";
-var reviewSchema = z26.object({
+import { z as z27 } from "zod";
+var reviewSchema = z27.object({
   // Broad, high-level takeaways grouped by theme (e.g. ingestion, search UI),
   // not one entry per workflow step — a step's raw output can be a long,
   // multi-paragraph blob (see implement.ts's summaries.join), and mirroring
   // that 1:1 is what made the old per-step summary an unreadable wall of text.
-  summaryPoints: z26.array(z26.string()),
-  reviewPrompt: z26.string(),
-  nextSteps: z26.array(z26.string())
+  summaryPoints: z27.array(z27.string()),
+  reviewPrompt: z27.string(),
+  nextSteps: z27.array(z27.string())
 });
 function formatCompletedSteps(steps) {
   if (!steps.length) return "(no prior steps completed)";
@@ -3856,18 +4009,19 @@ ${formatCompletedSteps(ctx.completedSteps)}`,
 };
 
 // src/actions/implement.ts
-import z27 from "zod";
+import z28 from "zod";
+import { join as join12 } from "node:path";
 
 // src/lib/worktree.ts
-import { execFile } from "node:child_process";
-import { copyFile, mkdir as mkdir6, readdir as readdir3, readFile as readFile7, stat as stat2, writeFile as writeFile6 } from "node:fs/promises";
-import { basename as basename2, dirname as dirname7, isAbsolute as isAbsolute2, join as join9, resolve as resolve3 } from "node:path";
+import { execFile as execFile2 } from "node:child_process";
+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) => {
-    execFile("git", args, { maxBuffer: MAX_BUFFER }, (err, stdout, stderr) => {
+    execFile2("git", args, { maxBuffer: MAX_BUFFER }, (err, stdout, stderr) => {
       if (err)
         return reject(
           new Error(
@@ -3892,7 +4046,7 @@ async function isWorkingTreeDirty(repoRoot) {
   return out.trim().length > 0;
 }
 async function pruneOldWorktrees(repoRoot) {
-  const dir = join9(stateDir(repoRoot), "worktrees");
+  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);
@@ -3903,7 +4057,7 @@ async function pruneOldWorktrees(repoRoot) {
         "worktree",
         "remove",
         "--force",
-        join9(dir, slug)
+        join10(dir, slug)
       ]);
       await git(["-C", repoRoot, "branch", "-D", branch]);
     } catch (err) {
@@ -3917,7 +4071,7 @@ async function pruneOldWorktrees(repoRoot) {
 async function createWorktree(repoRoot) {
   const branch = `${WIZARD_BRANCH_PREFIX}${Date.now()}`;
   const dirSlug = branch.replace(/\//g, "-");
-  const path = join9(stateDir(repoRoot), "worktrees", dirSlug);
+  const path = join10(stateDir(repoRoot), "worktrees", dirSlug);
   await git(["-C", repoRoot, "worktree", "prune"]);
   await pruneOldWorktrees(repoRoot);
   await mkdir6(dirname7(path), { recursive: true });
@@ -3931,14 +4085,14 @@ async function copyUploadIntoWorktree(repoRoot, worktreePath, ingestDir, sourceP
   }
   const source = isAbsolute2(trimmed) ? trimmed : resolve3(repoRoot, trimmed);
   try {
-    if (!(await stat2(source)).isFile()) {
+    if (!(await stat3(source)).isFile()) {
       return { ok: false, reason: `"${sourcePath}" is not a file` };
     }
   } catch {
     return { ok: false, reason: `"${sourcePath}" does not exist` };
   }
-  const relPath = join9(ingestDir, basename2(source));
-  const dest = join9(worktreePath, relPath);
+  const relPath = join10(ingestDir, basename2(source));
+  const dest = join10(worktreePath, relPath);
   try {
     await mkdir6(dirname7(dest), { recursive: true });
     await copyFile(source, dest);
@@ -3956,7 +4110,7 @@ function hasEnvVar(content, name) {
 async function readEnvVar(worktreePath, name) {
   let content;
   try {
-    content = await readFile7(join9(worktreePath, ".env"), "utf8");
+    content = await readFile8(join10(worktreePath, ".env"), "utf8");
   } catch (err) {
     if (err.code !== "ENOENT") throw err;
     return void 0;
@@ -3971,10 +4125,10 @@ async function readEnvVar(worktreePath, name) {
   return value;
 }
 async function writeSearchEnvValues(worktreePath, vars) {
-  const target = join9(worktreePath, ".env");
+  const target = join10(worktreePath, ".env");
   let existing = "";
   try {
-    existing = await readFile7(target, "utf8");
+    existing = await readFile8(target, "utf8");
   } catch (err) {
     if (err.code !== "ENOENT") throw err;
   }
@@ -3983,7 +4137,7 @@ async function writeSearchEnvValues(worktreePath, vars) {
   const prefix = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
   const lines = missing.map(({ name, value }) => `${name}=${value}
 `).join("");
-  await writeFile6(target, existing + prefix + lines, "utf8");
+  await writeFile7(target, existing + prefix + lines, "utf8");
   return missing.map((v) => v.name);
 }
 async function listChangedFiles(worktreePath) {
@@ -4044,13 +4198,13 @@ async function confirmDirtyWorkingTree(ctx, repoRoot) {
 
 // src/lib/algoliaDocs.ts
 import { readFileSync, readdirSync, existsSync } from "node:fs";
-import { dirname as dirname8, join as join10 } from "node:path";
+import { dirname as dirname8, join as join11 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
-var DOCS_SUBPATH = join10("docs", "algolia-sdk");
+var DOCS_SUBPATH = join11("docs", "algolia-sdk");
 function findDocsDir() {
   let dir = dirname8(fileURLToPath2(import.meta.url));
   for (; ; ) {
-    const candidate = join10(dir, DOCS_SUBPATH);
+    const candidate = join11(dir, DOCS_SUBPATH);
     if (existsSync(candidate)) return candidate;
     const parent = dirname8(dir);
     if (parent === dir) return void 0;
@@ -4073,7 +4227,7 @@ function loadAlgoliaDoc(language) {
     );
     return "";
   }
-  return readFileSync(join10(docsDir, files[0]), "utf8").trim();
+  return readFileSync(join11(docsDir, files[0]), "utf8").trim();
 }
 function getNamedDoc(name, language) {
   const docsDir = findDocsDir();
@@ -4081,7 +4235,7 @@ function getNamedDoc(name, language) {
     logger.warn("docs/algolia-sdk not found");
     return "";
   }
-  const file = join10(docsDir, `${name}-${language}.md`);
+  const file = join11(docsDir, `${name}-${language}.md`);
   if (!existsSync(file)) {
     logger.warn({ name, language }, "named SDK reference not found");
     return "";
@@ -4106,30 +4260,30 @@ function shellQuote(value) {
 }
 
 // src/actions/implement.ts
-var implementSchema = z27.object({
-  filesChanged: z27.array(z27.string()),
-  summary: z27.string(),
-  worktreePath: z27.string().optional(),
-  ingestCommand: z27.string().optional(),
-  ingestScriptRan: z27.boolean().optional(),
-  ingestRecordCount: z27.number().optional(),
-  ingestDurationMs: z27.number().optional(),
-  ingestionSource: z27.enum(["local", "fileUpload", "generated"]),
-  searchEnvVars: z27.array(
-    z27.object({
-      name: z27.string(),
-      value: z27.string()
+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(),
+  ingestDurationMs: z28.number().optional(),
+  ingestionSource: z28.enum(["local", "fileUpload", "generated"]),
+  searchEnvVars: z28.array(
+    z28.object({
+      name: z28.string(),
+      value: z28.string()
     })
   ).optional()
 });
-var implementationOutputSchema = z27.object({
-  summary: z27.string(),
-  ingestCommand: z27.string().optional()
+var implementationOutputSchema = z28.object({
+  summary: z28.string(),
+  ingestCommand: z28.string().optional()
 });
-var verificationOutputSchema = z27.object({
-  summary: z27.string(),
-  sufficient: z27.boolean(),
-  additionalInstructions: z27.string().optional()
+var verificationOutputSchema = z28.object({
+  summary: z28.string(),
+  sufficient: z28.boolean(),
+  additionalInstructions: z28.string().optional()
 });
 var MAX_IMPLEMENT_VERIFICATION_ATTEMPTS = 3;
 var DEFAULT_IMPLEMENT_USE_CASES = ["ingestion", "search"];
@@ -4262,6 +4416,7 @@ function ingestionInstructions(input) {
       "After a successful ingest, the script must print exactly one line to stdout in the form `ALGOLIA_WIZARD_RECORD_COUNT=<n>`, where <n> is the total number of records pushed to Algolia. Print it last, on its own line, with no surrounding text.",
       ...algoliaClientDoc(input),
       "Install the Algolia client with the project's own package manager via runShell, declaring it in whatever manifest the project uses (e.g. package.json, requirements.txt, Gemfile, go.mod, composer.json) so the dependency is not just installed ad hoc.",
+      "When the script is finished, call reviewScript with its path and wait: running it writes records to a live index, so the developer reads it first. Do not run it before that call returns.",
       'Then run the script yourself via runShell, and report the command you ran as "ingestCommand" so the developer can re-run it. Its explanation must say that running it writes records to Algolia.',
       "The summary should be extremely concise.",
       ...sourceSpecificInstructions(input)
@@ -4332,6 +4487,7 @@ var useCaseToolMap = {
     "writeFile",
     "writeCredentials",
     "runShell",
+    "reviewScript",
     "notifyUser"
   ],
   search: [...FS_READ_TOOLS, "writeFile", "runShell", "notifyUser"],
@@ -4586,7 +4742,8 @@ async function implement(ctx, useCases = DEFAULT_IMPLEMENT_USE_CASES, existingWo
       const result = await runImplementationUseCase("ingestion");
       summaries.push(formatSummary("ingestion", result.summary));
       ingestCommand = result.ingestCommand;
-      const executions = (ingestionTools ?? searchTools).shell.executions;
+      const ingestionContext = ingestionTools ?? searchTools;
+      const executions = ingestionContext.shell.executions;
       const {
         run: ingestRun,
         attempt: ingestAttempt,
@@ -4595,6 +4752,15 @@ async function implement(ctx, useCases = DEFAULT_IMPLEMENT_USE_CASES, existingWo
       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."
+        );
+        logger.warn(
+          { ingestCommand },
+          "implement: ingestion ran without a reviewScript call"
+        );
+      }
       if (ingestScriptRan) {
         ingestOutcomeMessage = `\u2705 Ingestion succeeded${ingestRecordCount != null ? ` \u2014 ${ingestRecordCount} record(s) indexed.` : "."}`;
         if (ingestRecordCount != null) {
@@ -4728,6 +4894,14 @@ ${detail}` : ""}`
         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;
@@ -4816,8 +4990,8 @@ var defaultWorkflow = {
     defineStep({
       id: "select-index",
       title: "Set up index",
-      outputSchema: z28.object({
-        selection: z28.string()
+      outputSchema: z29.object({
+        selection: z29.string()
       }),
       run: (ctx) => selectIndexStep(ctx)
     }),
@@ -5100,7 +5274,7 @@ function parseCliArgs(argv) {
 
 // src/lib/resetState.ts
 import { readdir as readdir4, rm as rm2 } from "node:fs/promises";
-import { join as join11 } from "node:path";
+import { join as join13 } from "node:path";
 var KEEP = ["wizard.log"];
 async function resetProjectState() {
   const dir = stateDir();
@@ -5114,7 +5288,7 @@ async function resetProjectState() {
   const targets = entries.filter((name) => !KEEP.includes(name));
   await Promise.all(
     targets.map(
-      (name) => rm2(join11(dir, name), { recursive: true, force: true })
+      (name) => rm2(join13(dir, name), { recursive: true, force: true })
     )
   );
   return { dir, removed: targets };

package/package.json

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