@algolia/wizard 0.14.0 → 0.16.0

package/dist/main.js

@@ -1079,12 +1079,12 @@ var sidebarItems = [
     description: "push 100 records to Algolia in seconds"
   },
   {
-    title: "detect your framework",
-    description: "React, Vue, Angular, Vanilla JS"
+    title: "detect your stack",
+    description: "whatever language and framework you already use"
   },
   {
     title: "scaffold a search UI",
-    description: "a styled InstantSearch component, wired into your app"
+    description: "a search box and results, wired into your app"
   },
   {
     title: "ship it",
@@ -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,26 +2881,48 @@ 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",
+  "dist",
+  "build",
+  "vendor",
+  "venv",
+  "__pycache__",
+  "target"
+]);
 async function walkFiles(dir) {
-  const skip = /* @__PURE__ */ new Set(["node_modules", ".git", "dist"]);
   const out = [];
   for (const e of await readdir2(dir, { withFileTypes: true })) {
-    if (e.name.startsWith(".") || skip.has(e.name)) continue;
-    const full = join8(dir, e.name);
+    if (e.name.startsWith(".") || SKIP_DIRS.has(e.name)) continue;
+    const full = join9(dir, e.name);
     if (e.isDirectory()) out.push(...await walkFiles(full));
     else if (e.isFile()) out.push(full);
   }
@@ -2859,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;
         }
@@ -2882,7 +2978,7 @@ 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/runShell.ts
 import { spawn as spawn2 } from "node:child_process";
@@ -2979,7 +3075,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",
@@ -3073,7 +3169,7 @@ function runShellTool(ctx) {
 import { tool as tool9, 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";
 var DATA_DIR = ".algolia-wizard/data";
@@ -3150,12 +3246,12 @@ 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,
           count: records.length,
-          message: `Wrote ${records.length} records to ${relPath}. Read and parse this file in the script at runtime (e.g. JSON.parse(readFileSync(...)) in Node/Bun, json.load(open(...)) in Python) \u2014 do not inline the records as literals.`
+          message: `Wrote ${records.length} records to ${relPath}. Read and parse this file in the script at runtime using your language's standard JSON support \u2014 do not inline the records as literals.`
         };
       } catch (err) {
         return `Error generating records: ${err.message}`;
@@ -3344,8 +3440,8 @@ var detectLanguageSchema = z20.object({
 var detectLanguage = () => runAgent({
   instructions: [
     "Analyze the codebase and determine the programming languages and frameworks used",
-    "If a superset language is found, exclude the subset language. TS-over-JS.",
-    "If a meta-framework is used, exclude the framework. Next-over-React.",
+    "If a superset language is found, exclude the subset language (e.g. TypeScript over JavaScript).",
+    "If a meta-framework is used, exclude the framework it builds on (e.g. Next.js over React, Rails over Rack).",
     "Return the exact version",
     "Exclude things like CSS frameworks, build tools, or testing frameworks",
     'Use as few tools as possible, but do not guess. If you cant find the answer, say "unknown"',
@@ -3443,7 +3539,7 @@ async function runAnalysis(mode, extraInstructions = []) {
 // package.json
 var package_default = {
   name: "@algolia/wizard",
-  version: "0.14.0",
+  version: "0.16.0",
   description: "Magically implement Algolia functionality in your codebase",
   type: "module",
   engines: {
@@ -3592,9 +3688,11 @@ var CURATED_FRAMEWORKS = [
   "Next.js",
   "React",
   "Vue",
-  "Angular",
-  "Svelte",
-  "Vanilla JS"
+  "Vanilla JS",
+  "Django",
+  "Laravel",
+  "Rails",
+  "Symfony"
 ];
 var OTHER_OPTION = "Other";
 var normalize = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, "");
@@ -3607,12 +3705,15 @@ var FRAMEWORK_ALIASES = {
   vuejs: "vue",
   angular: "angular",
   angularjs: "angular",
-  svelte: "svelte",
-  sveltekit: "svelte",
   vanillajs: "vanillajs",
   vanilla: "vanillajs",
   javascript: "vanillajs",
-  js: "vanillajs"
+  js: "vanillajs",
+  django: "django",
+  laravel: "laravel",
+  rails: "rails",
+  rubyonrails: "rails",
+  symfony: "symfony"
 };
 var isSameFramework = (a, b) => {
   const x = FRAMEWORK_ALIASES[normalize(a)] ?? normalize(a);
@@ -3844,17 +3945,18 @@ ${formatCompletedSteps(ctx.completedSteps)}`,
 
 // src/actions/implement.ts
 import z27 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 stat2, 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(
@@ -3879,7 +3981,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);
@@ -3890,7 +3992,7 @@ async function pruneOldWorktrees(repoRoot) {
         "worktree",
         "remove",
         "--force",
-        join9(dir, slug)
+        join10(dir, slug)
       ]);
       await git(["-C", repoRoot, "branch", "-D", branch]);
     } catch (err) {
@@ -3904,7 +4006,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 });
@@ -3924,8 +4026,8 @@ async function copyUploadIntoWorktree(repoRoot, worktreePath, ingestDir, sourceP
   } 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);
@@ -3943,7 +4045,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;
@@ -3958,10 +4060,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;
   }
@@ -3970,7 +4072,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) {
@@ -4031,13 +4133,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;
@@ -4060,7 +4162,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();
@@ -4068,7 +4170,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 "";
@@ -4076,6 +4178,7 @@ function getNamedDoc(name, language) {
   return readFileSync(file, "utf8").trim();
 }
 function getFrameworkSpecificDoc(frameworks) {
+  if (frameworks.length === 0) return "";
   const fw = frameworks.map((f) => f.toLowerCase());
   if (fw.includes("vue") || fw.includes("nuxt")) {
     return loadAlgoliaDoc("vue");
@@ -4083,9 +4186,6 @@ function getFrameworkSpecificDoc(frameworks) {
   if (fw.includes("react") || fw.includes("next.js")) {
     return loadAlgoliaDoc("react");
   }
-  if (fw.includes("angular")) {
-    return loadAlgoliaDoc("angular");
-  }
   return loadAlgoliaDoc("js");
 }
 
@@ -4123,30 +4223,34 @@ var verificationOutputSchema = z27.object({
 var MAX_IMPLEMENT_VERIFICATION_ATTEMPTS = 3;
 var DEFAULT_IMPLEMENT_USE_CASES = ["ingestion", "search"];
 var INGEST_DIR = ".algolia-wizard";
-function detectUiFramework(language) {
-  const names = language.frameworks.map((f) => f.name.toLowerCase());
-  if (names.some((n) => n.includes("vue") || n.includes("nuxt"))) return "Vue";
-  if (names.some((n) => n.includes("react") || n.includes("next")))
-    return "React";
-  if (names.some((n) => n.includes("angular"))) return "Angular";
-  return "JavaScript";
-}
-function frameworksForDoc(framework) {
-  switch (framework) {
-    case "React":
-      return ["react"];
-    case "Vue":
-      return ["vue"];
-    case "Angular":
-      return ["angular"];
-    case "JavaScript":
-      return [];
-  }
+var JS_LANGUAGES = ["javascript", "typescript", "jsx", "tsx", "node"];
+function lower(entries) {
+  return entries.map((entry) => entry.name.toLowerCase());
 }
-function publicEnvPrefix(language) {
-  const frameworkNames = language.frameworks.map(
-    (framework) => framework.name.toLowerCase()
+function isJsProject(language) {
+  return lower(language.languages).some(
+    (name) => JS_LANGUAGES.some((js) => name.includes(js))
   );
+}
+var UI_FRAMEWORKS = [
+  { match: ["vue", "nuxt"], target: "Vue", doc: "vue" },
+  { match: ["react", "next"], target: "React", doc: "react" },
+  { match: ["angular"], target: "Angular" }
+];
+function matchUiFramework(language) {
+  const names = lower(language.frameworks);
+  return UI_FRAMEWORKS.find(
+    (ui) => ui.match.some((needle) => names.some((name) => name.includes(needle)))
+  );
+}
+function searchUiTarget(language) {
+  return matchUiFramework(language)?.target ?? language.frameworks[0]?.name ?? (isJsProject(language) ? "JavaScript" : "this project");
+}
+function frameworksForDoc(language) {
+  return [matchUiFramework(language)?.doc ?? "js"];
+}
+function publicEnvPrefix(language) {
+  const frameworkNames = lower(language.frameworks);
   if (frameworkNames.some((name) => name.includes("next"))) {
     return "NEXT_PUBLIC_";
   }
@@ -4159,7 +4263,7 @@ function publicEnvPrefix(language) {
   if (frameworkNames.some((name) => name.includes("vite"))) {
     return "VITE_";
   }
-  return "PUBLIC_";
+  return isJsProject(language) ? "PUBLIC_" : "";
 }
 var APP_ID_VAR_SUFFIX = "ALGOLIA_APP_ID";
 var SEARCH_KEY_VAR_SUFFIX = "ALGOLIA_SEARCH_API_KEY";
@@ -4200,6 +4304,7 @@ function baseInstructions(input) {
     `Project languages and frameworks: ${JSON.stringify(input.language)}`,
     "Make minimal, idiomatic changes; do not touch unrelated code.",
     `Commands run through a shell on ${process.platform}. Write commands that work there.`,
+    "Use the project's own tooling for every command \u2014 its package manager, task runner, and test/lint commands. Do not assume a JavaScript toolchain.",
     "runShell needs the developer to approve each command, so give every call a clear `explanation` naming what it does and any side effect. If a command is rejected, do not retry it \u2014 take a different approach or report the limitation."
   ];
 }
@@ -4220,12 +4325,21 @@ function sourceSpecificInstructions(input) {
     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 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 (e.g. JSON.parse(readFileSync(...)) in Node/Bun, json.load(open(...)) in Python) instead of inlining the records as literals.",
+      "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."
     ]
   };
   return byLine[input.ingestionSource];
 }
+function algoliaClientDoc(input) {
+  const doc = getNamedDoc("save-records", "js");
+  if (!doc) return [];
+  if (isJsProject(input.language)) return [doc];
+  return [
+    "The reference below is written in JavaScript. Use it for the method names, arguments, and record shape, then translate to this project's language and its official Algolia client:",
+    doc
+  ];
+}
 function ingestionInstructions(input) {
   return [
     ...input.confirmed && input.confirmed.length ? [
@@ -4233,10 +4347,10 @@ function ingestionInstructions(input) {
       `Ingest only these confirmed entities (name, source paths, attributes): ${JSON.stringify(input.confirmed)}.`,
       `Ingesting writes to Algolia, so the script needs a write API key and App ID \u2014 read them from the ${API_KEY_VAR} and ${APP_ID_VAR} environment variables rather than hardcoding them. The wizard sets these when it runs the script.`,
       `Read the index name from the ${INDEX_NAME_VAR} environment variable, which the wizard sets to "${input.targetIndex}". Never hardcode an index name or derive one from the project, file, or entity name \u2014 the write key only works for that exact index. Exit with an error if ${INDEX_NAME_VAR} is unset.`,
-      "Use the appropriate Algolia package in the ingestion script. Do not use the raw HTTP API.",
+      "Write the script in the project's primary language, using Algolia's official client for that language. Do not use the raw HTTP API.",
       "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.",
-      getNamedDoc("save-records", "js"),
-      'Install the Algolia client via runShell and add it to package.json "dependencies" with a valid version range, so the dependency is not just installed ad hoc.',
+      ...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.",
       '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)
@@ -4244,20 +4358,31 @@ function ingestionInstructions(input) {
   ];
 }
 function searchInstructions(input) {
-  const doc = getFrameworkSpecificDoc(frameworksForDoc(input.uiFramework));
+  const doc = getFrameworkSpecificDoc(frameworksForDoc(input.language));
   return [
     "Implement an in-app Algolia search experience.",
-    `Build the search UI for ${input.uiFramework}.`,
-    "Follow the Algolia JS SDK reference below for client setup and InstantSearch wiring; prefer it over prior knowledge:",
-    doc,
-    `Add the search UI at ${input.searchLocation ? `"${input.searchLocation}"` : "the best shared, always-rendered layout location (e.g. a header/nav component)"} so it is reachable across the app.`,
+    `Build the search UI for ${input.searchUiTarget}.`,
+    ...doc ? [
+      "Follow the Algolia SDK reference below for client setup and search UI wiring; prefer it over prior knowledge:",
+      doc
+    ] : [
+      "No bundled Algolia SDK reference exists for this stack, so rely on the project's own conventions and Algolia's official client for its language. Do not invent APIs \u2014 keep to the documented search endpoint and its parameters."
+    ],
+    `Add the search UI at ${input.searchLocation ? `"${input.searchLocation}"` : "the best shared, always-rendered layout location (e.g. a header/nav component)"} so it is reachable across the app \u2014 at least a working search input and results list against the target index.`,
     "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}". Do not fabricate the index name.`,
+    `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, 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.`,
-    `Use exactly these public env var names in the code: ${input.searchEnvVars.map(({ name }) => name).join(", ")}.`,
-    "The search-only key is safe to expose client-side.",
-    'Install any Algolia/InstantSearch packages you import via runShell, and add them to package.json "dependencies" with a valid version range.',
-    "Match the styles of the application as closely as possible",
+    // 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.",
     "The summary should be extremely concise; do not mention env var setup or manual testing steps \u2014 the wizard writes the resolved credentials to .env and reports that separately."
   ];
 }
@@ -4486,7 +4611,7 @@ async function implement(ctx, useCases = DEFAULT_IMPLEMENT_USE_CASES, existingWo
       ingestDir: INGEST_DIR,
       ingestionSource,
       uploadFilePath,
-      uiFramework: detectUiFramework(language)
+      searchUiTarget: searchUiTarget(language)
     };
     const summaries = [];
     if (uploadWarning) summaries.push(uploadWarning);
@@ -4692,6 +4817,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;
@@ -5064,7 +5197,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();
@@ -5078,7 +5211,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/docs/algolia-sdk/README.md

@@ -10,8 +10,8 @@ InstantSearch).
 - `algoliasearch` v5 (install `^5`)
 - `react-instantsearch` v7 (install `^7`)
 - `vue-instantsearch` v4 (install `^4`)
-- `instantsearch.js` v4 (install `^4`) — also the recommended choice for Angular
-- `angular-instantsearch` — DEPRECATED/archived (Sep 2024); do not use, prefer `instantsearch.js`
+- `instantsearch.js` v4 (install `^4`) — also the choice for any framework without
+  its own flavor (Angular, Svelte); `angular-instantsearch` is archived, never use it
 
 Always install the **latest stable** within the major (use a caret range like `^5` /
 `^7`); never pin an exact patch.
@@ -30,7 +30,7 @@ Always install the **latest stable** within the major (use a caret range like `^
 
 ## Files
 
-- `instantsearch-setup.md` — framework-specific InstantSearch wiring (React, Vue,
-  Angular, vanilla). Use this for the in-app search UI.
+- `instantsearch-setup-*.md` — InstantSearch wiring per framework (React, Vue, and
+  vanilla for everything else). Use this for the in-app search UI.
 - `search-single-index.md` — direct/manual search via the core client
   (`searchSingleIndex`), for cases where InstantSearch is not used.

package/docs/algolia-sdk/instantsearch-setup-js.md

@@ -31,3 +31,14 @@ search.addWidgets([
 
 search.start()
 ```
+
+## Frameworks without their own flavor
+
+Only React and Vue have a maintained InstantSearch wrapper. For any other
+framework — Angular, Svelte, Solid — drive `instantsearch.js` directly from a
+component, mounting widgets against element refs and calling `search.dispose()`
+on teardown.
+
+Do NOT install `angular-instantsearch` or a community `*-instantsearch` package:
+`angular-instantsearch` is deprecated and archived (last release v4.4.3, Sep 2024),
+is incompatible with Angular v13+, and receives no security fixes.

package/package.json

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

package/docs/algolia-sdk/instantsearch-setup-angular.md

@@ -1,80 +0,0 @@
-# InstantSearch setup
-
-Install `instantsearch.js` (v4)
-
-## Search client: always use the lite client
-
-Import the client from `algoliasearch/lite` and alias it to `algoliasearch`
-
-```ts
-import { liteClient as algoliasearch } from 'algoliasearch/lite'
-
-// Instantiate ONCE, outside components, with a stable reference.
-const searchClient = algoliasearch(APP_ID, SEARCH_ONLY_KEY)
-```
-
-## Angular (use `instantsearch.js`)
-
-Do NOT use `angular-instantsearch`: it is deprecated and archived (last release
-v4.4.3, Sep 2024), not compatible with Ivy / modern Angular (v13+), and receives no
-security fixes. Algolia recommends driving `instantsearch.js` directly from an Angular
-component instead.
-
-```ts
-import {
-  Component,
-  ElementRef,
-  OnDestroy,
-  OnInit,
-  ViewChild,
-} from '@angular/core'
-import { liteClient as algoliasearch } from 'algoliasearch/lite'
-import instantsearch from 'instantsearch.js'
-import { searchBox, hits } from 'instantsearch.js/es/widgets'
-
-@Component({
-  selector: 'app-search',
-  template: `<div #searchbox></div>
-    <div #hits></div>`,
-})
-export class SearchComponent implements OnInit, OnDestroy {
-  @ViewChild('searchbox', { static: true }) searchbox!: ElementRef
-  @ViewChild('hits', { static: true }) hits!: ElementRef
-
-  private search = instantsearch({
-    indexName: 'INDEX_NAME',
-    searchClient: algoliasearch(APP_ID, SEARCH_ONLY_KEY),
-  })
-
-  ngOnInit() {
-    this.search.addWidgets([
-      searchBox({ container: this.searchbox.nativeElement }),
-      hits({ container: this.hits.nativeElement }),
-    ])
-    this.search.start()
-  }
-
-  ngOnDestroy() {
-    this.search.dispose()
-  }
-}
-```
-
-## Vanilla (`instantsearch.js` v4)
-
-```js
-import { liteClient as algoliasearch } from 'algoliasearch/lite'
-import instantsearch from 'instantsearch.js'
-import { searchBox, hits } from 'instantsearch.js/es/widgets'
-
-const searchClient = algoliasearch(APP_ID, SEARCH_ONLY_KEY)
-
-const search = instantsearch({ indexName: 'INDEX_NAME', searchClient })
-
-search.addWidgets([
-  searchBox({ container: '#searchbox' }),
-  hits({ container: '#hits' }),
-])
-
-search.start()
-```