@algolia/wizard 0.13.0 → 0.15.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",
@@ -2821,11 +2821,19 @@ import z14 from "zod";
 import { readdir as readdir2, readFile as readFile6 } from "node:fs/promises";
 import { join as join8 } 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;
+    if (e.name.startsWith(".") || SKIP_DIRS.has(e.name)) continue;
     const full = join8(dir, e.name);
     if (e.isDirectory()) out.push(...await walkFiles(full));
     else if (e.isFile()) out.push(full);
@@ -3155,7 +3163,7 @@ function generateRecordTool(ctx) {
         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 +3352,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 +3451,7 @@ async function runAnalysis(mode, extraInstructions = []) {
 // package.json
 var package_default = {
   name: "@algolia/wizard",
-  version: "0.13.0",
+  version: "0.15.0",
   description: "Magically implement Algolia functionality in your codebase",
   type: "module",
   engines: {
@@ -3592,9 +3600,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 +3617,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);
@@ -4076,6 +4089,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 +4097,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 +4134,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 +4174,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 +4215,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 +4236,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 +4258,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,13 +4269,18 @@ 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 \u2014 at least a working SearchBox and Hits against the target index.`,
+    `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}". 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
@@ -4261,8 +4291,9 @@ function searchInstructions(input) {
     // 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 public env var names in the code: ${input.searchEnvVars.map(({ name }) => name).join(", ")}.`,
-    'Install any Algolia/InstantSearch packages you import via runShell, and add them to package.json "dependencies" with a valid version range.',
+    `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."
   ];
 }
@@ -4491,7 +4522,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);

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.13.0",
+  "version": "0.15.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()
-```