@allstak/wizard 0.1.3 → 0.1.4

package/docs/beta/react.md

@@ -0,0 +1,83 @@
+# React (Vite or CRA)
+
+**Stability:** `stable`. Validated end-to-end against fixture and dogfooded
+against AllStak `admin-web` and `web` packages.
+
+## What you get
+
+- `@allstak/react` SDK installed via your package manager.
+- `.env.local` (Vite) or `.env` (CRA) populated with `ALLSTAK_API_KEY`,
+  `ALLSTAK_HOST`, `ALLSTAK_ENVIRONMENT`, and (if configured) `ALLSTAK_RELEASE`.
+- `AllStakProvider` import added to your entry file via AST mutation.
+- Managed-block hint guiding you to wrap `<App />` in the provider.
+- For Vite projects: `@allstak/js/vite` plugin import added to `vite.config.*`.
+
+## Run
+
+```bash
+# Auto-detect:
+npx @allstak/wizard@beta
+
+# Explicit:
+npx @allstak/wizard@beta -i react
+
+# Non-interactive (CI):
+npx @allstak/wizard@beta -i react -y --api-key $ALLSTAK_API_KEY \
+  --org $ORG --project $PROJECT --release $GIT_SHA
+```
+
+## Compatibility
+
+- `react >= 16.8`. Older React versions are refused with `E_UNSUPPORTED_VERSION`.
+- Works with Vite 4+ and Create React App. Webpack-only setups get a
+  managed-block hint instead of AST mutation (Webpack configs vary too much
+  for safe AST patching in v0.1).
+
+## Wiring the provider
+
+The wizard injects the import but **does not** rewrite your `ReactDOM.createRoot`
+call — too risky across CRA / Vite / RN-Web variants. Wrap your app
+manually:
+
+```tsx
+import { AllStakProvider } from '@allstak/react';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <AllStakProvider
+    apiKey={import.meta.env?.VITE_ALLSTAK_API_KEY ?? process.env.ALLSTAK_API_KEY}
+    environment="production"
+    release={import.meta.env?.VITE_GIT_SHA}
+  >
+    <App />
+  </AllStakProvider>,
+);
+```
+
+## Verify
+
+```bash
+npx @allstak/wizard@beta doctor -i react
+```
+
+For an end-to-end ingestion check:
+
+```bash
+npx @allstak/wizard@beta doctor -i react --live-probe \
+  --api-key ask_live_... \
+  --project-id <project-uuid>
+```
+
+## Idempotent
+
+Re-running `init` produces byte-identical output. The wizard wraps every
+patch in `// >>> allstak-wizard:v1` markers so subsequent runs replace the
+managed block instead of duplicating it.
+
+## Uninstall
+
+```bash
+npx @allstak/wizard@beta uninstall -i react
+```
+
+Removes the `@allstak/react` and `@allstak/js` deps, strips the AST import,
+deletes the managed env block, and unwires the Vite plugin.

package/docs/beta/restore.md

@@ -0,0 +1,84 @@
+# `allstak restore`
+
+Every wizard mutation is captured in a persistent snapshot under
+`.allstak-wizard/backups/<timestamp>--<integration>--<random>/`. The
+`restore` family lets you inspect and roll back those snapshots.
+
+## Subcommands
+
+```bash
+npx @allstak/wizard@beta restore list
+npx @allstak/wizard@beta restore show <id|latest>
+npx @allstak/wizard@beta restore diff <id|latest>
+npx @allstak/wizard@beta restore apply <id|latest> [--files=a,b,c] [--dry-run]
+```
+
+`<id>` is the trailing slug of a backup directory. `latest` always
+resolves to the most recent snapshot.
+
+## What's in a snapshot
+
+```
+.allstak-wizard/backups/2026-05-07T..--react--abc123/
+  manifest.json                    schemaVersion, integration, files[], dryRun, label
+  files/
+    src/main.tsx                   pre-image bytes (UTF-8)
+    .env.local                     pre-image bytes
+    .env.local.allstak-deleted     marker (file did not exist before)
+```
+
+Manifests and pre-images are plain text — they're safe to inspect with `cat`.
+
+## Common workflows
+
+### "I made a mess, give me my files back"
+
+```bash
+npx @allstak/wizard@beta restore apply latest
+```
+
+Confirms before writing. Pass `-y` to skip confirmation.
+
+### "What did the wizard change vs my current state?"
+
+```bash
+npx @allstak/wizard@beta restore diff latest
+```
+
+Each file shows one of: `identical`, `modified`, `created-since`, or
+`deleted-since`.
+
+### "Restore one file from a specific run"
+
+```bash
+npx @allstak/wizard@beta restore apply 2026-05-07T..--react--abc123 \
+  --files=src/main.tsx,.env.local
+```
+
+### "What WOULD restore do?"
+
+```bash
+npx @allstak/wizard@beta restore apply latest --dry-run
+```
+
+## Retention
+
+`init` prunes old snapshots after a successful run. The default keeps the
+10 most recent — override with `--snapshot-keep <n>` (0 disables pruning).
+`repair` and `uninstall` also write snapshots but do NOT prune.
+
+## Transactional
+
+Restoring is itself a transaction — partial failure rolls back to the
+pre-restore state. If a file in the snapshot is missing on disk, the
+restore reports `skipped` for that file and continues.
+
+## Limitations
+
+- Restoring across wizard major versions is supported but a `manifest.json`
+  with a `schemaVersion` higher than the running wizard's is refused.
+- Snapshots live in your repo by default. Add
+  `.allstak-wizard/` to `.gitignore` to keep them out of git (the wizard
+  does not auto-edit your `.gitignore`).
+- Snapshots are NOT encrypted. Don't store them in a public artifact bucket
+  — they contain the original contents of files the wizard touched.

package/docs/beta/troubleshooting.md

@@ -0,0 +1,133 @@
+# Troubleshooting
+
+Common failure modes mapped to canonical error codes (see [errors.md](../errors.md)).
+
+## "I just ran `allstak login` and got `E_AUTH_FAILED`"
+
+- The OTP code expires after ~10 minutes. Run `login` again to request a new one.
+- Codes are 4–8 digits. If you typed an extra space, the wizard rejects with
+  the same code.
+- If you see `OTP_RATE_LIMITED` in the subcode, wait a minute and retry.
+
+## "`E_AUTH_REQUIRED` from `orgs list` but I am logged in"
+
+You were logged in to a different host. The wizard scopes credentials by
+host. Check `allstak whoami --verify` and rerun with the matching `--host`,
+or re-run `login --host <url>`.
+
+## "`E_AUTH_EXPIRED` after a long break"
+
+The refresh token was probably revoked (server-side logout, password reset,
+or it just expired). Run `allstak logout && allstak login`.
+
+## "`E_NETWORK_FAILED` everywhere"
+
+- Verify the configured host with `allstak whoami` (it prints the host).
+- Pass `--debug` and re-run; the underlying message includes the URL.
+- For self-hosted: confirm DNS + TLS are working from the wizard's host.
+
+## "`E_UNSUPPORTED_FRAMEWORK` even though I'm using React"
+
+- `package.json` may not declare `react` directly. The wizard reads
+  `dependencies` + `devDependencies`.
+- For monorepos, run the wizard from the **package directory**, not the
+  root.
+- Pass `-i react` explicitly if detection is ambiguous.
+
+## "`E_UNSUPPORTED_VERSION` but my React/Next is current"
+
+The compat engine reads the version range from `package.json`. If you have
+`"react": "*"` it cannot infer a minimum and reports too-old. Pin a real
+version range in `package.json`.
+
+## "`E_PACKAGE_MANAGER_CONFLICT`"
+
+Two lockfiles in the project root (e.g. both `pnpm-lock.yaml` and
+`package-lock.json`). The wizard refuses to guess. Delete the stale one.
+
+## "`E_PATCH_FAILED` mid-run"
+
+The transaction layer ALREADY rolled back your files. Re-run with
+`--debug` to see which patcher threw. Common causes:
+
+- A pre-existing syntax error in the file we tried to patch — fix the
+  syntax first, re-run the wizard.
+- File permissions denied on the entry file or `.env.local`.
+
+If rollback itself failed (`E_PATCH_ROLLBACK_FAILED`):
+
+```bash
+allstak restore list
+allstak restore apply <id>
+```
+
+## "`E_RESTORE_FAILED: No snapshot matches "<id>""
+
+`allstak restore list` shows what's available. Use the trailing slug
+(e.g. `2026-05-07T..--react--abc123`) or just `latest`.
+
+## "`E_INGEST_VERIFY_FAILED` on `--live-probe`"
+
+- The probe uses `--api-key` (project-scoped). If the key was issued for
+  a different project than `--project-id`, verification will never see the
+  event. Check both match.
+- The probe waits 60s by default. Increase via
+  `--live-probe-timeout 120000` if your backend is slow.
+- Open the dashboard URL printed in the probe output and look for the
+  fingerprint manually. The event id is in the JSON output even when
+  polling times out.
+
+## "`E_CONFIG_INVALID` after editing `allstak.config.ts`"
+
+```bash
+allstak config validate
+```
+
+prints the exact path-to-blame (e.g. `selfHosted.apiHost — expected
+absolute URL, got "api.acme"`). Fix and rerun.
+
+## "`E_CONFIG_MIGRATION_FAILED`"
+
+The migration runner refuses on:
+
+- A `schemaVersion` higher than the wizard supports (subcode
+  `E_CONFIG_FUTURE_VERSION`) — upgrade `@allstak/wizard`.
+- A migration that didn't bump the version correctly (subcode
+  `E_MIGRATION_NO_BUMP`) — file an issue, this is a wizard bug.
+
+## "`E_USER_CANCELLED` in CI"
+
+You forgot `-y`. The wizard refuses to apply changes without it in
+non-interactive mode.
+
+## "Wizard hung at the login OTP prompt in CI"
+
+CI has no TTY, so `@clack/prompts` rejects. Pass `--email` AND `--code` (or
+use a long-lived API key with `--api-key` instead of logging in).
+
+## "Telemetry warning showed up in my CI logs"
+
+Telemetry is on by default. To silence:
+
+```bash
+ALLSTAK_WIZARD_TELEMETRY=0
+# or
+allstak --no-telemetry ...
+```
+
+## "I see `// >>> allstak-wizard:v1` in my git diff"
+
+That's the wizard's idempotency marker. It's intentional — re-runs replace
+the block in place; `uninstall` removes it. Commit it; do not hand-edit
+inside the markers (your edits will be overwritten on the next run).
+
+## Last resort: nuke everything
+
+```bash
+allstak uninstall -i react -y    # remove SDK + patches
+allstak logout                   # clear credentials
+rm -rf .allstak-wizard/          # drop persistent snapshots
+```
+
+The local credential store on macOS may keep the keychain entry until you
+explicitly clear it: `security delete-generic-password -s allstak-wizard`.

package/docs/errors.md

@@ -0,0 +1,88 @@
+# `@allstak/wizard` error catalog
+
+Every error thrown out of the wizard CLI carries a canonical `code` from this
+catalog. The code is stable across releases (we add new codes; we never
+rename or remove existing ones without a major-version bump). The `subcode`
+field exists for finer-grained internal granularity and is **not** part of
+the public contract — it can change between minors.
+
+JSON output (`--json`) and telemetry (when enabled) only include the
+canonical `code` + `stage` + (sanitised) `context`. Raw error messages and
+stack traces are NEVER sent to telemetry.
+
+| Code | Stage | What it means | What to try |
+|------|-------|---------------|-------------|
+| `E_AUTH_REQUIRED` | auth | A command needs credentials but none were available. | Run `allstak login`, or pass `--api-key` for ingest-only commands. |
+| `E_AUTH_FAILED` | auth | Credentials were rejected by the AllStak backend. | Verify the email and OTP are correct; check `allstak.config.*` host setting. |
+| `E_AUTH_EXPIRED` | auth | Stored credentials are no longer valid (token revoked or refresh failed). | Run `allstak login` to refresh. |
+| `E_BACKEND_CONTRACT_MISSING` | reachability | The wizard requires a backend endpoint that does not exist on the configured host. | Confirm `--host` points at a current AllStak deployment, or open an issue. |
+| `E_PROJECT_NOT_FOUND` | config | The specified project could not be found. | Run `allstak projects list`. |
+| `E_PROJECT_CREATE_FAILED` | config | Backend rejected the project-create call. | Check the slug is unique and the org has quota. |
+| `E_API_KEY_CREATE_FAILED` | config | Backend refused to mint a new API key. | Check API-key quota for the org's plan. |
+| `E_UNSUPPORTED_FRAMEWORK` | detect | No registered integration matches the project, or detection was ambiguous. | Pass `-i <integration>`. Run `allstak list`. |
+| `E_UNSUPPORTED_VERSION` | detect | Detected framework version is below the supported minimum. | Upgrade the framework, or pin to a wizard version that supports your range. |
+| `E_PACKAGE_MANAGER_CONFLICT` | install | Multiple lockfiles present. | Delete the unused lockfile and re-run. |
+| `E_PATCH_FAILED` | patch | A wizard patch threw mid-transaction; all changes rolled back. | Re-run with `--debug`; consult `allstak doctor`. |
+| `E_PATCH_ROLLBACK_FAILED` | rollback | A patch failed AND the in-process rollback could not restore one or more files. | Use `allstak restore list` then `restore apply <id>`. |
+| `E_RESTORE_FAILED` | restore | A `restore` operation could not complete. | Inspect `.allstak-wizard/backups/<snapshot>/manifest.json`. |
+| `E_CONFIG_INVALID` | config | `allstak.config.*` failed schema validation. | Run `allstak config validate`. |
+| `E_CONFIG_MIGRATION_FAILED` | config | A config-schema migration threw or refused. | Run `allstak config migrate --dry-run`. |
+| `E_DOCTOR_FAILED` | validate | One or more `doctor` stages failed. | Read the per-stage `fix:` lines in the doctor output. |
+| `E_INGEST_VERIFY_FAILED` | event-ingest | Live event probe could not be confirmed. | Verify API-key scope and project id. Increase `--live-probe-timeout`. |
+| `E_SOURCEMAP_VERIFY_FAILED` | source-maps | Source-map upload or symbolication failed. | Run `allstak doctor`, then `allstak repair`. |
+| `E_NETWORK_FAILED` | reachability | A network call timed out, refused, or hit DNS failure. | Check connectivity and the configured `--host`. |
+| `E_PERMISSION_DENIED` | cli | OS-level permission was denied (file write, keychain, secret-tool, etc). | Check filesystem permissions; unlock your OS keychain. |
+| `E_USER_CANCELLED` | cli | The user cancelled the operation. | No action needed. |
+| `E_UNKNOWN` | cli | An unexpected error not yet categorised. | Re-run with `--debug` and open an issue. |
+
+## Subcodes
+
+Subcodes are an internal grep-aid for support; they are visible in `--debug`
+output and in the wizard's stack traces but are **not** part of the JSON
+contract. Examples currently in use:
+
+- `E_NO_EMAIL` / `E_NO_CODE` / `E_2FA_REQUIRED` (under `E_AUTH_REQUIRED`)
+- `E_AUTH_REFRESH_FAILED` (under `E_AUTH_EXPIRED`)
+- `E_NO_DETECT` / `E_AMBIGUOUS` (under `E_UNSUPPORTED_FRAMEWORK`)
+- `E_HTTP_TIMEOUT` / `E_HTTP_NETWORK` (under `E_NETWORK_FAILED`)
+- `E_PATCH_SYNTAX` / `E_TX_ABORT` (under `E_PATCH_FAILED`)
+- `E_KEYCHAIN` / `E_DECRYPT` / `E_SECRET_TOOL` (under `E_PERMISSION_DENIED`)
+- `E_NO_CONFIRM` / `E_CANCELLED` (under `E_USER_CANCELLED`)
+- `E_RESTORE_UNKNOWN_FILES` / `E_NO_SNAPSHOTS` / `E_SNAPSHOT_NOT_FOUND` (under `E_RESTORE_FAILED`)
+
+Adding a new subcode does not require a wizard release bump. Adding a new
+canonical code does — this is enforced by the type union in
+`src/util/error-codes.ts`.
+
+## Reading wizard errors
+
+### Human (default) output
+
+```
+✗ E_AUTH_EXPIRED: Stored credentials for https://api.allstak.sa are no longer valid (...)
+› Run `allstak login` to refresh.
+```
+
+### `--json` output
+
+```json
+{
+  "outcome": "failure",
+  "errorCode": "E_AUTH_EXPIRED",
+  "data": {
+    "error": {
+      "code": "E_AUTH_EXPIRED",
+      "stage": "auth",
+      "subcode": "E_AUTH_REFRESH_FAILED",
+      "message": "Stored credentials for https://api.allstak.sa are no longer valid (...)",
+      "hint": "Run `allstak login` to refresh."
+    }
+  }
+}
+```
+
+### `--debug` output
+
+Adds the underlying `originalCause` stack and the `context` bag. Both are
+intentionally limited — `context` keys are checked against a documented
+allowlist (no file paths, no token values, no PII).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@allstak/wizard",
-  "version": "0.1.3",
-  "description": "Unified installation and configuration wizard for AllStak SDKs.",
+  "version": "0.1.4",
+  "description": "AllStak SDK installation and configuration wizard (public beta). Auto-installs and wires the right @allstak/* SDK for React, Next.js, and Node — with deterministic rollback, persistent snapshots, and a real-event doctor.",
   "type": "module",
   "bin": {
     "allstak-wizard": "./dist/cli.js"
@@ -40,6 +40,14 @@
     "./snapshot": {
       "types": "./dist/snapshot/store.d.ts",
       "import": "./dist/snapshot/store.js"
+    },
+    "./config": {
+      "types": "./dist/config/index.d.ts",
+      "import": "./dist/config/index.js"
+    },
+    "./errors": {
+      "types": "./dist/util/error-codes.d.ts",
+      "import": "./dist/util/error-codes.js"
     }
   },
   "files": [
@@ -47,7 +55,9 @@
     "README.md",
     "LICENSE",
     "CHANGELOG.md",
-    "docs/architecture"
+    "docs/errors.md",
+    "docs/architecture",
+    "docs/beta"
   ],
   "engines": {
     "node": ">=18"
@@ -79,7 +89,7 @@
     "allstak",
     "wizard",
     "cli",
-    "sdk-install",
+    "sdk",
     "observability",
     "react",
     "nextjs"