@algolia/wizard 0.1.0

package/docs/algolia-sdk/README.md

@@ -0,0 +1,36 @@
+# Algolia JS SDK reference (search)
+
+Authoritative reference for wiring **Algolia search** in JavaScript/TypeScript apps.
+Prefer the method shapes documented here over prior knowledge — they are pinned to
+the current stable majors and avoid known pitfalls (e.g. v5 type mismatches with
+InstantSearch).
+
+## Versions
+
+- `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`
+
+Always install the **latest stable** within the major (use a caret range like `^5` /
+`^7`); never pin an exact patch.
+
+## Golden rules
+
+- Use a **search-only API key** in any browser/client code. It is safe to expose.
+  NEVER ship an admin or any write-capable key to the client.
+- Read the Application ID and search-only key from **public env vars**, never hardcode
+  them inline.
+- Instantiate the search client **once, outside your components**, and pass a stable
+  reference. Do not inline `algoliasearch(...)` as a prop value — it breaks the
+  client cache and causes re-renders.
+- For InstantSearch, import the client from `algoliasearch/lite` (smaller bundle and
+  correct types — see `instantsearch-setup.md`).
+
+## Files
+
+- `instantsearch-setup.md` — framework-specific InstantSearch wiring (React, Vue,
+  Angular, vanilla). 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-angular.md

@@ -0,0 +1,80 @@
+# 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()
+```

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

@@ -0,0 +1,33 @@
+# 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)
+```
+
+## 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()
+```

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

@@ -0,0 +1,39 @@
+# InstantSearch setup
+
+Install `react-instantsearch` (v7)
+
+## 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)
+```
+
+## React (`react-instantsearch` v7)
+
+```tsx
+import { liteClient as algoliasearch } from 'algoliasearch/lite'
+import { InstantSearch, SearchBox, Hits } from 'react-instantsearch'
+
+// Read from PUBLIC env vars; never hardcode. (Vite shown; use the framework's
+// convention: NEXT_PUBLIC_* for Next.js, etc.)
+const searchClient = algoliasearch(
+  import.meta.env.VITE_ALGOLIA_APP_ID,
+  import.meta.env.VITE_ALGOLIA_SEARCH_API_KEY,
+)
+
+export function Search() {
+  return (
+    <InstantSearch searchClient={searchClient} indexName="INDEX_NAME">
+      <SearchBox />
+      <Hits />
+    </InstantSearch>
+  )
+}
+```
+
+Do not inline `searchClient={algoliasearch(...)}` — keep the stable reference above.

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

@@ -0,0 +1,41 @@
+# InstantSearch setup
+
+Install `vue-instantsearch` (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)
+```
+
+## Vue (`vue-instantsearch` v4)
+
+```vue
+<template>
+  <ais-instant-search :search-client="searchClient" index-name="INDEX_NAME">
+    <ais-search-box />
+    <ais-hits />
+  </ais-instant-search>
+</template>
+
+<script setup>
+import { liteClient as algoliasearch } from 'algoliasearch/lite'
+
+const searchClient = algoliasearch(
+  import.meta.env.VITE_ALGOLIA_APP_ID,
+  import.meta.env.VITE_ALGOLIA_SEARCH_API_KEY,
+)
+</script>
+```
+
+Register the widgets via the InstantSearch Vue plugin in your app entry:
+
+```js
+import InstantSearch from 'vue-instantsearch/vue3/es'
+app.use(InstantSearch)
+```

package/docs/algolia-sdk/save-records-js.md

@@ -0,0 +1,39 @@
+# Save records (algoliasearch v5)
+
+Adds records to an index. Write op — use a **write key**, server-side only.
+
+`saveObjects` adds records, auto-batching in groups of 1,000 (Batch API,
+`addObject` action).
+
+```js
+import { algoliasearch } from 'algoliasearch'
+
+const client = algoliasearch(APP_ID, WRITE_KEY)
+
+const response = await client.saveObjects({
+  indexName: 'playlists',
+  objects: [{ objectID: '1', name: 'Hot 100', visibility: 'public' }],
+  waitForTasks: true,
+  batchSize: 1000,
+})
+```
+
+```ts
+client.saveObjects(
+  params: {
+    indexName: string                   // required
+    objects: Record<string, unknown>[]  // required
+    waitForTasks?: boolean              // default false
+    batchSize?: number                  // default 1000
+  },
+  requestOptions?: RequestOptions,      // optional
+)
+```
+
+Returns an array (one entry per batch), not a single object — don't destructure:
+
+```ts
+type SaveObjectsResponse = { taskID: number; objectIDs: string[] }[]
+```
+
+Subject to indexing rate limits.

package/docs/algolia-sdk/search-single-index.md

@@ -0,0 +1,42 @@
+# Direct search with the core client (v5)
+
+Use this only when NOT using InstantSearch (e.g. a custom search box, a server
+route, or programmatic queries). For UI, prefer `instantsearch-setup-<framework>.md`.
+
+## Client
+
+```ts
+import { algoliasearch } from 'algoliasearch'
+
+const client = algoliasearch(APP_ID, SEARCH_ONLY_KEY)
+```
+
+In v5 there is no `client.initIndex(...)`. Index methods take the index name as a
+parameter on the client. Every method takes a single options object.
+
+## Search a single index
+
+```ts
+const { hits, nbHits } = await client.searchSingleIndex({
+  indexName: 'INDEX_NAME',
+  searchParams: { query: 'shoes', hitsPerPage: 20, page: 0 },
+})
+```
+
+## Search multiple indices / queries in one request
+
+```ts
+const { results } = await client.search({
+  requests: [
+    { indexName: 'INDEX_NAME', query: 'shoes' },
+    { indexName: 'OTHER_INDEX', query: 'shoes' },
+  ],
+})
+```
+
+## Notes
+
+- `searchSingleIndex` returns up to 1,000 hits. For larger exports use the `browse`
+  operation instead.
+- Keep using a **search-only** key for any client-exposed search. Use an admin key
+  only in trusted server-side code.

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@algolia/wizard",
+  "version": "0.1.0",
+  "description": "Magically implement Algolia functionality in your codebase",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "bin": {
+    "wizard": "dist/main.js"
+  },
+  "files": [
+    "dist",
+    "docs"
+  ],
+  "scripts": {
+    "build:proxy": "esbuild src/proxy/index.ts --bundle --platform=node --format=esm --target=node24 --banner:js='import { createRequire as __cr } from \"module\"; const require = __cr(import.meta.url);' --outfile=dist/proxy.mjs",
+    "build": "esbuild src/main.tsx --bundle --platform=node --format=esm --target=node18 --packages=external --jsx=automatic --banner:js='#!/usr/bin/env node' --outfile=dist/main.js && cp src/ui/algolia.png dist/algolia.png",
+    "dev:proxy": "NODE_OPTIONS=--use-system-ca tsx watch src/proxy/index.ts",
+    "dev": "touch .env && tsx --env-file=.env ./src/main.tsx",
+    "env:load": "pnpm exec -- varlock load",
+    "prepare": "husky",
+    "prepublishOnly": "pnpm build",
+    "reset": "tsx ./scripts/reset-state.ts",
+    "test:fixtures": "touch .env && tsx --env-file=.env ./fixtures/run-fixtures.ts",
+    "test:tools": "tsx ./tool-evals/toolEval.ts",
+    "test": "vitest",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "packageManager": "pnpm@11.9.0+sha512.bd682d5d03fe525ef7c9fd6780c6884d1e756ac4c9c9fe00c538782824310dcf90e3ddc4f53835f06dfaebd5085e41855e0bcbb3b60de2ac5bbab89e5036f03b",
+  "devDependencies": {
+    "@clack/prompts": "^1.6.0",
+    "@types/ioredis-mock": "^8.2.7",
+    "@types/node": "^25.9.1",
+    "@types/react": "^19.2.16",
+    "esbuild": "^0.28.0",
+    "husky": "^9.1.7",
+    "ink-testing-library": "^4.0.0",
+    "ioredis-mock": "^8.13.1",
+    "lint-staged": "^17.0.8",
+    "tsx": "^4.22.3",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  },
+  "dependencies": {
+    "@ai-sdk/anthropic": "^3.0.81",
+    "@ai-sdk/openai-compatible": "^2.0.47",
+    "@algolia/cli": "^5.11.0",
+    "@hono/node-server": "^2.0.10",
+    "@mishieck/ink-titled-box": "^0.4.2",
+    "@segment/analytics-node": "^3.1.0",
+    "ai": "^6.0.190",
+    "dotenv": "^17.4.2",
+    "hono": "^4.12.27",
+    "ink": "^7.0.5",
+    "ink-picture": "^2.1.0",
+    "ink-spinner": "^5.0.0",
+    "ink-text-input": "^6.0.0",
+    "ioredis": "^5.11.1",
+    "nanoid": "^5.1.15",
+    "pino": "^10.3.1",
+    "react": "^19.2.7",
+    "toml": "^4.1.1",
+    "varlock": "^1.5.1",
+    "zod": "^4.4.3",
+    "zustand": "^5.0.14"
+  }
+}