@algolia/wizard 0.1.0

package/README.md

@@ -0,0 +1,69 @@
+# @algolia/wizard
+
+A composable CLI that implements Algolia functionality directly in your codebase.
+
+Wizard runs **workflows** — ordered sequences of steps that inspect your project, talk to Algolia APIs, and make AI-authored changes to your repo.
+
+## Install & run
+
+```bash
+# run the default workflow
+npx @algolia/wizard
+
+# run a specific workflow by id
+npx @algolia/wizard <workflow-id>
+```
+
+On first run, Wizard checks for an Algolia profile. If none exists it launches `algolia auth login` and writes a default profile.
+
+You'll also be asked once to consent to AI-authored changes to the repository.
+
+## Development
+
+### Requirements
+
+- Node 24+
+- PNPM
+
+### Development Commands
+
+```bash
+pnpm install
+pnpm dev          # run from source via tsx
+pnpm test         # vitest
+pnpm test:tools   # run tool evals (tool-evals/); pass a spec name to run one, e.g. pnpm test:tools searchFiles
+pnpm typecheck    # tsc --noEmit
+pnpm build        # bundle to dist/main.js via esbuild
+```
+
+### Environment
+
+Create a `.env` with:
+
+```
+PROVIDER_API_KEY=...   # Algolia AI Enablers inference platform key
+```
+
+#### Logging
+
+Logging is configured via environment variables (see [src/lib/logger.ts](src/lib/logger.ts)):
+
+| Variable    | Default                              | Description                                                                                                           |
+| ----------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
+| `LOG_LEVEL` | `info`                               | Minimum pino level to emit: `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `silent`.                            |
+| `WIZARD_LOG`| `~/.algolia/<project-slug>/wizard.log` | Log file destination                        |
+
+## How it works
+
+- **Workflows** ([src/workflows/](src/workflows/)) — a `Workflow` is `{ id, title, description, steps[] }`. The registry lives in [src/workflows/index.ts](src/workflows/index.ts); the default is [src/workflows/default.ts](src/workflows/default.ts).
+- **Steps** ([src/core/orchestrator.ts](src/core/orchestrator.ts)) — each step has a Zod `outputSchema` and a `run(ctx)` function. Output is validated and persisted before the next step runs. The `StepContext` exposes prior step outputs, `requestUserInput`, `updateAlgoliaState`, and read-only config.
+- **State & resume** ([src/core/persistence.ts](src/core/persistence.ts), [src/core/config.ts](src/core/config.ts)) — run state and cross-workflow config live under `~/.algolia/<project-slug>/`, never in your repo's working tree. An interrupted workflow resumes from its last incomplete step.
+- **Auth** ([src/lib/algoliaProfile.ts](src/lib/algoliaProfile.ts)) — profiles are read from the Algolia CLI's `config.toml`; the default profile (or first configured) is used as the active one.
+- **AI** ([src/lib/agent.ts](src/lib/agent.ts)) — steps call the agent against the Algolia AI Enablers inference platform.
+- **UI** ([src/ui/](src/ui/)) — Ink/React components for steps, progress, prompts, and the concepts tutorial. State is held in a Zustand store ([src/core/store.ts](src/core/store.ts)).
+
+### Adding a workflow
+
+1. Define a `Workflow` with `defineStep(...)` calls (see [src/workflows/default.ts](src/workflows/default.ts)).
+2. Register it in [src/workflows/index.ts](src/workflows/index.ts).
+3. Run it: `npx @algolia/wizard <your-workflow-id>`.