@algolia/wizard 0.33.0 → 0.34.0-rc.125.243

package/dist/main.js

@@ -2759,17 +2759,23 @@ async function hasSymlinkParent(ctx, target) {
 // src/lib/tools/listFiles.ts
 function listFilesTool(ctx) {
   return tool({
-    description: "List files in the current working directory",
-    inputSchema: z6.object(),
-    execute: async () => {
-      logger.info("called listFiles tool");
+    description: 'List files in a directory (default: the current working directory). Pass path to list a subdirectory directly \u2014 e.g. "packages/api" \u2014 without first changeDirectory-ing into it.',
+    inputSchema: z6.object({
+      path: z6.string().optional().describe("Directory to list, relative to cwd (default: cwd)")
+    }),
+    execute: async ({ path = "." }) => {
+      logger.info({ path }, "called listFiles tool");
       if (++ctx.counts.list > ctx.limits.list) {
         return `Refused: list limit (${ctx.limits.list}) reached. Stop listing and proceed with the information you already have.`;
       }
-      const resolved2 = resolveInRoot(ctx, ".");
+      const resolved2 = resolveInRoot(ctx, path);
       if (!resolved2.ok) return resolved2.error;
-      const entries = await readdir(resolved2.target, { withFileTypes: true });
-      return entries.map((e) => e.isDirectory() ? `${e.name}/` : e.name).join("\n");
+      try {
+        const entries = await readdir(resolved2.target, { withFileTypes: true });
+        return entries.map((e) => e.isDirectory() ? `${e.name}/` : e.name).join("\n");
+      } catch (err) {
+        return `Error listing ${path}: ${err.message}`;
+      }
     }
   });
 }
@@ -3196,11 +3202,13 @@ function appendEnv(content, entries) {
   return content + prefix + lines;
 }
 function hasEnv(content, name) {
-  return new RegExp(`^(\\s*(?:export\\s+)?${name})\\s*=`, "m").test(content);
+  return new RegExp(`^([ \\t]*(?:export[ \\t]+)?${name})[ \\t]*=`, "m").test(
+    content
+  );
 }
 function readEnv(content, name) {
   const found = content.match(
-    new RegExp(`^\\s*(?:export\\s+)?${name}\\s*=\\s*(.*)$`, "m")
+    new RegExp(`^[ \\t]*(?:export[ \\t]+)?${name}[ \\t]*=[ \\t]*(.*)$`, "m")
   );
   if (!found) return null;
   const raw = found[1].trim();
@@ -3211,16 +3219,16 @@ function readEnv(content, name) {
 function upsertEnv(content, name, value) {
   if (!hasEnv(content, name)) return appendEnv(content, [[name, value]]);
   return content.replace(
-    new RegExp(`^\\s*(?:export\\s+)?${name}\\s*=.*$`, "gm"),
+    new RegExp(`^[ \\t]*(?:export[ \\t]+)?${name}[ \\t]*=.*$`, "gm"),
     () => `${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. The env file is added to .gitignore automatically; do not edit .gitignore yourself.`,
+    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. If the script or app that reads these credentials lives in a subdirectory (e.g. a package in a monorepo), an env file at the repo root is the wrong default \u2014 a script only loads env vars from its own directory (or one it's explicitly configured to read), so check every directory from the script's own up to the repo root, not just those two: its own directory, each ancestor in between (a shared workspace-level directory above the immediate package is common), and the root. Use whichever of those already holds real credentials; only fall back to the repo root when none of them do. Never invent a brand-new file in one of those directories when a real one already exists in another \u2014 that leaves the real one stale and the new one wrong. Listing just the script's own directory and the very top-level root is not enough to find a workspace-level file in between; check the intermediate ones too. If instructions describe a location that doesn't match the project you actually find (e.g. a path outside the repo, or a convention the project doesn't follow), don't stop and ask before doing anything \u2014 call this tool on the real, in-repo file the script actually reads (that's always the safe default), then note the mismatch afterward. Ending your turn with only a question and no call to this tool leaves the project unconfigured.`,
     inputSchema: z13.object({
       filePath: z13.string().describe(
-        'Path to the env file to write credentials into (e.g. ".env")'
+        'Path to the env file to write credentials into, relative to the repo root (e.g. ".env", or "packages/api/.env" when the consuming script lives in that package)'
       )
     }),
     execute: async ({ filePath }) => {
@@ -3974,6 +3982,7 @@ var detectLanguage = () => runAgent({
     "Return the exact version",
     "Exclude things like CSS frameworks, build tools, or testing frameworks",
     `Determine publicEnvVarPrefix: check the project's own env var usage first (e.g. names already referenced in code, .env/.env.example); if none exists, fall back to the detected framework's known convention for exposing env vars to client-side code; use "" when the project has no such convention (e.g. a backend-only project).`,
+    "A brand-new project has no existing env var usage to find \u2014 one or two targeted checks (e.g. .env/.env.example, or a grep for the bundler's public-prefix convention) are enough to confirm that. Do not keep searching once those turn up nothing; fall back to the framework convention immediately.",
     'Use as few tools as possible, but do not guess. If you cant find the answer, say "unknown"',
     "When done, call reportStatus"
   ],
@@ -4069,7 +4078,7 @@ async function runAnalysis(mode, extraInstructions = []) {
 // package.json
 var package_default = {
   name: "@algolia/wizard",
-  version: "0.33.0",
+  version: "0.34.0-rc.125.243",
   description: "Magically implement Algolia functionality in your codebase",
   type: "module",
   engines: {
@@ -4475,7 +4484,7 @@ ${formatCompletedSteps(ctx.completedSteps)}`,
 
 // src/actions/implement.ts
 import z29 from "zod";
-import { join as join12, relative as relative6 } from "node:path";
+import { relative as relative6 } from "node:path";
 
 // src/lib/git.ts
 import { execFile as execFile2 } from "node:child_process";
@@ -4533,41 +4542,43 @@ async function copyUploadIntoProject(repoRoot, ingestDir, sourcePath) {
   }
   return { ok: true, relPath };
 }
-function hasEnvVar(content, name) {
-  return new RegExp(`^(\\s*(?:export\\s+)?${name})\\s*=`, "m").test(content);
-}
-async function readEnvVar(repoRoot, name) {
-  let content;
+var ENV_FILE_PRECEDENCE = [".env", ".env.local"];
+async function readEnvFileIfExists(path) {
   try {
-    content = await readFile8(join10(repoRoot, ".env"), "utf8");
+    return await readFile8(path, "utf8");
   } catch (err) {
     if (err.code !== "ENOENT") throw err;
     return void 0;
   }
-  const match = new RegExp(
-    `^[ \\t]*(?:export[ \\t]+)?${name}[ \\t]*=[ \\t]*(.*)$`,
-    "m"
-  ).exec(content);
-  if (!match) return void 0;
-  const value = match[1].trim().replace(/^(['"])(.*)\1$/, "$2").trim();
-  if (!value || value.startsWith("<")) return void 0;
-  return value;
 }
-async function writeSearchEnvValues(repoRoot, vars) {
-  const target = join10(repoRoot, ".env");
-  let existing = "";
-  try {
-    existing = await readFile8(target, "utf8");
-  } catch (err) {
-    if (err.code !== "ENOENT") throw err;
+async function definingEnvFile(repoRoot, name) {
+  let found;
+  for (const file of ENV_FILE_PRECEDENCE) {
+    const path = join10(repoRoot, file);
+    const content = await readEnvFileIfExists(path);
+    if (content !== void 0 && hasEnv(content, name)) found = { path, content };
   }
-  const missing = vars.filter((v) => !hasEnvVar(existing, v.name));
-  if (missing.length === 0) return [];
-  const prefix = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
-  const lines = missing.map(({ name, value }) => `${name}=${value}
-`).join("");
-  await writeFile7(target, existing + prefix + lines, "utf8");
-  return missing.map((v) => v.name);
+  return found;
+}
+function usableEnvValue(content, name) {
+  const value = readEnv(content, name);
+  return value && !value.startsWith("<") ? value : void 0;
+}
+async function readEnvVar(repoRoot, name) {
+  const found = await definingEnvFile(repoRoot, name);
+  return found ? usableEnvValue(found.content, name) : void 0;
+}
+async function writeSearchEnvValues(repoRoot, vars, defaultFileName = ".env") {
+  const written = [];
+  for (const { name, value } of vars) {
+    const found = await definingEnvFile(repoRoot, name);
+    if (found && usableEnvValue(found.content, name) !== void 0) continue;
+    const path = found?.path ?? join10(repoRoot, defaultFileName);
+    const existing = found?.content ?? await readEnvFileIfExists(path) ?? "";
+    await writeFile7(path, upsertEnv(existing, name, value), "utf8");
+    written.push({ name, file: path });
+  }
+  return written;
 }
 function normalizeFindingPaths(findings) {
   return {
@@ -4658,6 +4669,7 @@ var resolveEnvVarPrefix = (frameworkName) => runAgent({
   instructions: [
     `The developer corrected the project's framework to "${frameworkName}".`,
     `Determine publicEnvVarPrefix for this framework: check the project's own env var usage first (e.g. names already referenced in code, .env/.env.example); if none exists, fall back to this framework's known convention for exposing env vars to client-side code; use "" when the framework has no such convention (e.g. a backend-only framework).`,
+    "A brand-new project has no existing env var usage to find \u2014 one or two targeted checks (e.g. .env/.env.example, or a grep for the framework's public-prefix convention) are enough to confirm that. Do not keep searching once those turn up nothing; fall back to the framework convention immediately.",
     'Use as few tools as possible, but do not guess. If you cant find the answer, say "unknown"',
     "When done, call reportStatus"
   ],
@@ -4694,6 +4706,7 @@ var MAX_IMPLEMENT_VERIFICATION_ATTEMPTS = 3;
 var DEFAULT_IMPLEMENT_USE_CASES = ["ingestion", "search"];
 var INGEST_DIR = ".algolia-wizard";
 var JS_LANGUAGES = ["javascript", "typescript", "jsx", "tsx", "node"];
+var ENV_LOCAL_AWARE_PREFIXES = ["VITE_", "NEXT_PUBLIC_", "REACT_APP_"];
 function lower(entries) {
   return entries.map((entry) => entry.name.toLowerCase());
 }
@@ -4793,17 +4806,19 @@ function searchInstructions(input) {
     `Create the search experience as its own component in a new file, following the project's existing component conventions (location, naming, styling approach). Do not write it inline into an existing file.`,
     `Import and render that new component from ${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 its usage with an import and render of your new component; remove the old implementation.",
+    "When rendering results with an existing shared component (e.g. a card), import and reuse that component rather than inlining its markup \u2014 inlining silently drops the styles and behavior its own file provides.",
     `Read the index name from the ${publicIndexNameVar(input.publicEnvVarPrefix)} 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.
-    `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.
+    // reads the project's env files to decide whether a key already exists —
+    // an agent-scaffolded value there, even a blank one, would be treated as
+    // real and silently override whatever the wizard writes.
+    `Add Algolia App ID "${input.appId}"; leave the search-only key as a placeholder in the code only. Do not create or edit any .env* file (.env, .env.local, etc.) yourself, not even to add a blank placeholder line \u2014 the wizard resolves the real key and writes it there itself.`,
+    // The wizard writes these exact names into the project's env files right after this step.
     `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."
+    "The summary should be extremely concise; do not mention env var setup or manual testing steps \u2014 the wizard writes the resolved credentials to the project env files and reports that separately."
   ];
 }
 function verificationInstructions(input) {
@@ -5063,11 +5078,11 @@ async function implement(ctx, useCases = DEFAULT_IMPLEMENT_USE_CASES) {
       const appIdVarName = publicAppIdVar(publicEnvVarPrefix);
       const searchKeyVarName = publicSearchKeyVar(publicEnvVarPrefix);
       summaries.push(
-        `\u26A0\uFE0F .env already sets ${appIdVarName}=${envAppId}, but the active Algolia application is ${appId}. The wizard left those values alone \u2014 update ${appIdVarName} and ${searchKeyVarName} by hand, or searches will fail.`
+        `\u26A0\uFE0F Your project's env files already set ${appIdVarName}=${envAppId}, but the active Algolia application is ${appId}. The wizard left those values alone \u2014 update ${appIdVarName} and ${searchKeyVarName} by hand, or searches will fail.`
       );
       logger.warn(
         { envAppId, appId },
-        "implement: .env holds credentials for a different Algolia application; not reusing its search key"
+        "implement: env files hold credentials for a different Algolia application; not reusing its search key"
       );
     }
   }
@@ -5240,7 +5255,7 @@ ${detail}` : ""}`
         searchKeyError = err.message;
         logger.warn(
           { err: searchKeyError },
-          "implement: could not provision a search-only API key; the .env value stays a placeholder"
+          "implement: could not provision a search-only API key; the env value stays a placeholder"
         );
       }
     }
@@ -5254,34 +5269,42 @@ ${detail}` : ""}`
       (v) => !v.value.startsWith("<")
     );
     if (resolvedSearchEnvVars.length > 0) {
+      const defaultEnvFile = ENV_LOCAL_AWARE_PREFIXES.includes(
+        publicEnvVarPrefix
+      ) ? ".env.local" : ".env";
       const written = await writeSearchEnvValues(
         repoRoot,
-        resolvedSearchEnvVars
+        resolvedSearchEnvVars,
+        defaultEnvFile
       );
-      if (written.length > 0) {
-        summaries.push(`Wrote ${written.join(", ")} to .env.`);
-      }
-      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.'
-        );
+      const writtenFiles = [...new Set(written.map((w) => w.file))];
+      for (const file of writtenFiles) {
+        const label = relative6(repoRoot, file);
+        const names = written.filter((w) => w.file === file).map((w) => w.name);
+        summaries.push(`Wrote ${names.join(", ")} to ${label}.`);
+        const ignored = await ensureGitIgnored(repoRoot, file);
+        if (ignored === "added") {
+          summaries.push(`Added ${label} to .gitignore.`);
+        } else if (ignored === "tracked") {
+          summaries.push(
+            `\u26A0\uFE0F ${label} is tracked by git, so a .gitignore rule cannot un-stage it. Run "git rm --cached ${label}" before committing, or the credentials go into history.`
+          );
+        }
       }
+      const writtenNames = new Set(written.map((w) => w.name));
       const stale = [];
       for (const v of resolvedSearchEnvVars) {
-        if (written.includes(v.name)) continue;
+        if (writtenNames.has(v.name)) continue;
         const current = await readEnvVar(repoRoot, 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.`
+          `\u26A0\uFE0F Your project's env files already assign 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"
+          "implement: env files hold different values for the resolved search credentials; not overwriting them"
         );
       }
     }
@@ -5290,7 +5313,7 @@ ${detail}` : ""}`
     );
     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}` : "")
+        `Could not resolve a value for ${unresolvedSearchEnvVars.map((v) => v.name).join(", ")} \u2014 fill it in manually in .env or .env.local.` + (searchKeyError ? ` Reason: ${searchKeyError}` : "")
       );
     }
   } else {
@@ -5624,7 +5647,7 @@ function parseCliArgs(argv) {
 
 // src/lib/resetState.ts
 import { readdir as readdir3, rm as rm2 } from "node:fs/promises";
-import { join as join13 } from "node:path";
+import { join as join12 } from "node:path";
 var KEEP = ["wizard.log"];
 async function resetProjectState() {
   const dir = stateDir();
@@ -5638,7 +5661,7 @@ async function resetProjectState() {
   const targets = entries.filter((name) => !KEEP.includes(name));
   await Promise.all(
     targets.map(
-      (name) => rm2(join13(dir, name), { recursive: true, force: true })
+      (name) => rm2(join12(dir, name), { recursive: true, force: true })
     )
   );
   return { dir, removed: targets };

package/package.json

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