@allstak/wizard 0.1.3 → 0.1.4

package/docs/beta/config.md

@@ -0,0 +1,124 @@
+# `allstak.config.*`
+
+Optional project-level config so you don't repeat `--org`, `--project`,
+`--host`, etc. on every wizard invocation. Discovered from the project root
+upward; the first matching file wins.
+
+Loader order (first match wins):
+
+1. `allstak.config.ts`
+2. `allstak.config.mts`
+3. `allstak.config.mjs`
+4. `allstak.config.js`
+5. `allstak.config.cjs`
+6. `allstak.config.json`
+
+`.ts` / `.mts` configs require running the wizard via a TypeScript-aware
+launcher (`npx tsx`, `bun`, or `deno run`). Plain `.mjs` / `.json` work
+without any toolchain.
+
+## Schema
+
+```ts
+import { defineConfig } from '@allstak/wizard/config';
+
+export default defineConfig({
+  schemaVersion: 1,
+  organization: 'my-org',
+  project: 'my-project',
+  environment: 'production',
+  release: process.env.GIT_SHA,
+  sourceMaps: {
+    enabled: true,
+    ignore: ['node_modules'],
+  },
+  selfHosted: {
+    apiHost: 'https://api.allstak.example',
+    ingestHost: 'https://api.allstak.example',
+    dashboardHost: 'https://app.allstak.example',
+  },
+  snapshotKeep: 10,
+});
+```
+
+All fields are optional. `defineConfig` is a typed-identity helper; at
+runtime it just returns its input.
+
+## Precedence
+
+```
+CLI flag  >  env var  >  config file  >  built-in default
+```
+
+Examples:
+
+| Setting | CLI | Env | Config | Default |
+|---------|-----|-----|--------|---------|
+| organization | `--org` | `ALLSTAK_ORG` | `organization` | — |
+| project | `--project` | `ALLSTAK_PROJECT` | `project` | — |
+| environment | `--environment` | `ALLSTAK_ENVIRONMENT` | `environment` | `production` |
+| release | `--release` | `ALLSTAK_RELEASE` | `release` (string or function) | — |
+| api host | `--host` | `ALLSTAK_HOST` | `selfHosted.apiHost` | `https://api.allstak.sa` |
+| ingest host | `--ingest-host` | `ALLSTAK_INGEST_HOST` | `selfHosted.ingestHost` | matches api host |
+| dashboard host | `--dashboard-host` | `ALLSTAK_DASHBOARD_HOST` | `selfHosted.dashboardHost` | derived from api |
+| source-maps | `--skip-source-maps` | — | `sourceMaps.enabled` | `true` |
+| snapshot-keep | `--snapshot-keep` | `ALLSTAK_SNAPSHOT_KEEP` | `snapshotKeep` | `10` |
+
+## Validation
+
+```bash
+npx @allstak/wizard@beta config validate
+```
+
+Reports the discovered file path, the declared `schemaVersion`, and any
+deprecation warnings.
+
+## Migration
+
+When the wizard ships a new schema, `allstak config migrate` upgrades your
+config in place.
+
+```bash
+npx @allstak/wizard@beta config migrate            # rewrites .json files
+npx @allstak/wizard@beta config migrate --dry-run  # prints planned changes
+```
+
+For `.ts` / `.mjs` configs the wizard prints the migrated shape and asks
+you to apply it manually — we don't roundtrip TypeScript through an AST
+serializer that would mangle your imports and comments.
+
+The wizard treats a missing `schemaVersion` as `1`. Always declaring it
+explicitly future-proofs your config.
+
+## Self-hosted
+
+Wizard never assumes `api.allstak.sa`. For a self-hosted deployment:
+
+```ts
+export default defineConfig({
+  schemaVersion: 1,
+  selfHosted: {
+    apiHost: 'https://api.allstak.acme.com',
+    ingestHost: 'https://api.allstak.acme.com',
+    dashboardHost: 'https://app.allstak.acme.com',
+  },
+});
+```
+
+CLI users can also pass `--host`, `--ingest-host`, `--dashboard-host`
+directly. **Caveat:** the Java SDK currently hardcodes its host; the wizard
+will warn when `-i java` runs against a non-default host until the SDK
+ships a configurable host field.
+
+## Release as a function
+
+Useful for CI:
+
+```ts
+release: process.env.GIT_SHA,                 // string at config-load time
+release: () => process.env.GIT_SHA,           // function evaluated each run
+release: () => execSync('git rev-parse HEAD').toString().trim(),
+```
+
+If the function returns `undefined`, the wizard falls through the precedence
+chain (env, default).

package/docs/beta/doctor.md

@@ -0,0 +1,79 @@
+# `allstak doctor`
+
+Deterministic diagnostic with named stages. Read-only by default;
+`--live-probe` adds a real test event roundtrip.
+
+## Stages
+
+The doctor runs all stages in this fixed order, even when an early stage
+fails (so you see the whole picture):
+
+| Stage | What it checks |
+|-------|----------------|
+| `auth` | Credentials present + accepted (`--api-key` or stored JWT). Auto-refreshes JWT if it expires soon. |
+| `reachability` | Configured host responds (HTTP-level only — no `/health` exists, so it probes `/api/v1/auth/me` and treats `401` as "alive"). |
+| `config` | `allstak.config.*` discovered (or absent — both fine). Reports the source path. |
+| `integration` | Delegates to the integration's own doctor — env present? entry patched? imports wired? |
+| `event-ingest` | (only with `--live-probe`) Sends a real event to `/ingest/v1/errors`, polls `/api/v1/errors` for ingestion. |
+| `release-linkage` | Confirms the configured release is attached to the test event. |
+| `source-maps` | Asks each registered source-map provider for its wired/drifted/missing state. |
+
+## Output
+
+Each stage emits exactly one line: `pass`, `warn`, `fail`, or `skip`, plus
+a fix hint when applicable. `--json` produces a structured array under
+`data.stages` for programmatic consumption.
+
+```bash
+npx @allstak/wizard@beta doctor
+```
+
+```
+» Doctor
+✓ [auth] Authenticated as me@example.com.
+✓ [reachability] Reached https://api.allstak.sa.
+✓ [config] Loaded config from /repo/allstak.config.ts.
+✓ [integration] react: ok (4 checks)
+- [event-ingest] Skipped (pass --live-probe to enable).
+- [release-linkage] Skipped: live probe required to verify release linkage end-to-end.
+✓ [source-maps] Wired: vite
+✓ Doctor: setup looks good.
+```
+
+## Live probe
+
+Requires both:
+
+- `--api-key` (project-scoped — sends the test event),
+- `--project-id <uuid>` (the project UUID, visible in the dashboard URL).
+
+```bash
+npx @allstak/wizard@beta doctor --live-probe \
+  --api-key ask_live_... \
+  --project-id 7e8e... \
+  --live-probe-timeout 60000
+```
+
+Flow:
+
+1. Wizard generates a random fingerprint (`wizard-probe-<6-hex>`).
+2. POSTs an event to `/ingest/v1/errors` with that fingerprint in metadata.
+3. Polls `/api/v1/errors?projectId=&from=&query=<fingerprint>` every 2.5s.
+4. Reports the dashboard URL of the captured event when found.
+
+If polling times out, the doctor returns `E_INGEST_VERIFY_FAILED` with the
+event id you can hand to support.
+
+## JSON mode
+
+```bash
+npx @allstak/wizard@beta --json doctor | jq '.data.stages'
+```
+
+Each entry is `{ stage, status, detail, fix?, data? }`.
+
+## When stages fail
+
+The CLI exits non-zero (code 2) on any `fail`. `warn` and `skip` do not
+change exit code. See [errors.md](../errors.md) for the canonical error
+codes each stage can emit.

package/docs/beta/known-limitations.md

@@ -0,0 +1,93 @@
+# Known limitations (public beta)
+
+This page is the **honest** list of what the wizard does and doesn't do
+today. Read it before making the wizard part of a critical onboarding
+path.
+
+## Supported integrations
+
+| Integration | Stability | Notes |
+|-------------|-----------|-------|
+| `react` (Vite or CRA) | ✅ stable | Validated end-to-end; dogfooded against `admin-web` and `web`. |
+| `next` (13+, app + pages router) | 🟡 beta | Implementation complete; production-build validation in progress. |
+| `js` (vanilla Node) | ✅ stable | Validated end-to-end. |
+
+Everything else is `experimental` (refuses without `--experimental`) or
+`unsupported` (refuses always).
+
+## Explicitly NOT supported in beta
+
+| Target | Why |
+|--------|-----|
+| **Astro** | The wizard's framework detector falls through to `js`, which writes env vars but does not wire Astro middleware. Real Astro support is on the v0.2 roadmap. Until then: do the setup manually following the SDK README. |
+| **Bare React Native** | Podfile + Gradle patching cannot be validated without iOS sim + Android emulator builds. The wizard refuses with `E_UNSUPPORTED_FRAMEWORK`. Use the Expo path (config plugin) if you can; otherwise follow the manual setup. |
+| **Flutter source maps** | The Flutter SDK itself does not yet ship source-map upload tooling. Wizard's Flutter integration is `experimental` and only writes env vars. |
+| **Backend SDK auto-wiring** (NestJS, Fastify, OTel, Spring Boot, Django, Flask, Rails, .NET, Go, PHP) | Each is `experimental`. Install + env-var writing is supported under `--experimental`; framework wiring is NOT — too many entry-point shapes to AST-patch safely without per-framework fixture validation. v0.2 roadmap. |
+
+## Java self-hosted: blocked by SDK
+
+`allstak-java-sdk` currently hardcodes its host to `https://api.allstak.sa`.
+Until the SDK adds a configurable `host` field on `AllStakConfig`, the
+wizard's `--host` / `--ingest-host` flags are a **no-op for Java users**.
+The wizard will warn when `-i java` runs against a non-default host.
+
+Tracking spec: `docs/architecture/v02-java-host-fix-spec.md`.
+
+## Auth specifics
+
+- Login uses email-OTP (no OAuth device-flow). Rate-limited; 4–8 digit
+  codes valid for ~10 minutes.
+- Two-factor (TOTP) is supported but not unit-tested end-to-end (the test
+  matrix doesn't include accounts with 2FA enabled).
+- JWT refresh has a 60-second early-refresh window; the access token TTL
+  is 15 minutes, the refresh token rotates on each `/refresh` call.
+
+## Source-maps
+
+- **Vite**: AST-injects the plugin import + managed-block hint.
+- **Next.js**: managed-block hint only (next.config shapes vary too much
+  for safe AST mutation).
+- **Webpack**: managed-block hint only.
+- **Metro / Hermes (RN)**: provider registered but inert in v0.1 — `detect()`
+  returns `false` and `wire()` is a no-op. Real validation needs device
+  builds.
+- End-to-end **upload roundtrip** (POST `/api/v1/sourcemaps/upload` →
+  symbolicate) is NOT verified by `doctor` in v0.1.x. The wizard wires the
+  plugin; the upload + dashboard symbolication are the SDK + dashboard's
+  responsibility.
+
+## Other gaps
+
+- **Windows Credential Manager** is not yet a credential store backend on
+  Windows — Windows users get the AES-256-GCM encrypted-file fallback.
+- **CRA + standalone Webpack** are detected but the wizard does not AST-mutate
+  Webpack configs.
+- **Multi-package monorepos** are detected (pnpm/turbo/nx/lerna/npm-workspaces)
+  but the wizard operates on the cwd's nearest manifest. There is no
+  "which package?" prompt yet.
+- **`allstak login`** is the only path to a user JWT in beta. There is no
+  PAT (personal access token) flow, because the backend doesn't expose one.
+
+## What's safe to use in production
+
+- React + Vite onboarding flows.
+- React + CRA onboarding flows (without source-map upload — manual wiring).
+- Vanilla Node entry-point patching.
+- Next.js with manual `next.config.js` follow-up.
+- All commands in their `--dry-run` form (no disk writes anywhere).
+- `restore` / snapshot inspection (read-only ops).
+
+## What to avoid
+
+- Running `--experimental` integrations in CI without manual review.
+- Deploying based on `doctor --live-probe` for Java integrations until the
+  host-config fix lands.
+- Treating Astro / bare-RN as "the wizard handles it."
+
+## Reporting an issue
+
+Re-run with `--debug` and grab the canonical `errorCode` + `subcode` from
+the output. Snapshot directory contents (under `.allstak-wizard/backups/`)
+are useful for support. Do **not** paste your full env file or
+`allstak.config.*` to a public issue — redact `apiKey` / DSN / refresh
+token values first.

package/docs/beta/next.md

@@ -0,0 +1,77 @@
+# Next.js
+
+**Stability:** `beta`. Implementation complete and unit-tested. The wizard
+emits a one-line warning on use because end-to-end integration testing
+against Next 13/14/15 production builds is still in progress.
+
+## What you get
+
+- `@allstak/next@beta` + `@allstak/js` installed.
+- `.env.local` populated with **both** `ALLSTAK_API_KEY` and `ALLSTAK_DSN`
+  (the beta SDK still accepts `ALLSTAK_DSN` during the env-var transition).
+- `instrumentation.ts` created at the project root if missing, otherwise a
+  managed-block hint appended to the existing one. The wizard does NOT
+  modify the body of an existing `register()` function.
+- `next.config.{js,mjs,ts}` gains a managed-block hint reminding you to
+  wrap with `withAllStak` and enable `productionBrowserSourceMaps: true`.
+
+## Run
+
+```bash
+npx @allstak/wizard@beta -i next
+```
+
+## Compatibility
+
+- `next >= 13`. Both app router and pages router supported.
+- Older Next versions refused with `E_UNSUPPORTED_VERSION`.
+
+## Wiring `register()`
+
+Wizard creates this if `instrumentation.ts` did not exist:
+
+```ts
+import { initAllStakNext } from '@allstak/next';
+
+export function register() {
+  initAllStakNext({
+    dsn: process.env.ALLSTAK_DSN,
+    endpoint: process.env.ALLSTAK_HOST ?? 'https://api.allstak.sa',
+    release: process.env.ALLSTAK_RELEASE,
+    environment: process.env.ALLSTAK_ENVIRONMENT ?? 'production',
+  });
+}
+```
+
+If you already have `register()`, copy the body of `initAllStakNext({ ... })`
+into it.
+
+## Source maps
+
+Wrap `next.config.*` with `withAllStak`:
+
+```js
+const { withAllStak } = require('@allstak/js/next');
+module.exports = withAllStak({
+  ...nextConfig,
+  productionBrowserSourceMaps: true,
+});
+```
+
+The wizard does NOT auto-mutate `next.config.*` for you — Next configs use
+many factory shapes (`module.exports = (phase, { defaultConfig }) => …`) and
+auto-mutation has too high a blast-radius. Follow the managed-block hint.
+
+## Known beta-tier limitations
+
+- Live `doctor --live-probe` works for Next-emitted events only when your
+  Next app runs in a place the wizard can reach. (No magic — the SDK posts
+  to `/ingest/v1/errors` and the wizard polls `/api/v1/errors`.)
+- Source-map upload roundtrip not yet validated end-to-end (wizard's job is
+  to wire the plugin; the SDK + dashboard own upload + symbolication).
+
+## Verify
+
+```bash
+npx @allstak/wizard@beta doctor -i next
+```

package/docs/beta/node.md

@@ -0,0 +1,60 @@
+# Vanilla Node.js (`@allstak/js`)
+
+**Stability:** `stable`. Validated against fixture and dogfooded.
+
+## What you get
+
+- `@allstak/js` SDK installed.
+- `.env` populated with the standard `ALLSTAK_*` vars.
+- AST-injected `import { AllStak } from '@allstak/js'` in your entry file.
+- Managed-block call to `AllStak.init({...})` appended to the entry.
+
+## Run
+
+```bash
+npx @allstak/wizard@beta -i js
+```
+
+## Entry detection
+
+The wizard looks at `package.json:scripts.start` for a `node X.js` pattern,
+then falls back to:
+
+- `src/index.ts` / `src/index.js`
+- `index.ts` / `index.js`
+- `app.ts` / `app.js`
+- `server.ts` / `server.js`
+
+If none match, the wizard skips entry patching and reports
+`config-only run` — env vars are still written; you need to call
+`AllStak.init(...)` manually.
+
+## What the patched entry looks like
+
+After `init`, the bottom of your entry file gains:
+
+```js
+// >>> allstak-wizard:v1 (do not edit) >>>
+AllStak.init({
+  apiKey: process.env.ALLSTAK_API_KEY,
+  host: process.env.ALLSTAK_HOST ?? 'https://api.allstak.sa',
+  environment: process.env.ALLSTAK_ENVIRONMENT ?? 'production',
+  release: process.env.ALLSTAK_RELEASE,
+});
+// <<< allstak-wizard:v1 <<<
+```
+
+Re-running the wizard replaces this block in place. `uninstall` removes it.
+
+## Compatibility
+
+- Node 18+ required by the wizard itself.
+- The `@allstak/js` SDK supports Node 16+.
+- Works with TypeScript entries via `tsx`/`bun`/`deno run` toolchains.
+
+## What this integration does NOT do
+
+- No bundler-level source-map wiring — Node is interpreted, not bundled.
+- No express/fastify/hono middleware registration — those are framework-
+  specific and live in their own integrations (`fastify` is `experimental`
+  for now; nest/express integrations are deferred).

package/docs/beta/privacy.md

@@ -0,0 +1,99 @@
+# Privacy & telemetry
+
+The wizard ships a minimal anonymous-usage telemetry channel. This page
+documents **exactly** what is sent and how to disable it.
+
+## What we send
+
+| Field | Example | Why |
+|-------|---------|-----|
+| `schemaVersion` | `1` | Stable version of this payload shape. |
+| `installId` | `b9c4...` | Anonymous v4 UUID stored at `~/.config/allstak/install-id`. Coalesces events for the same install. Rotate by deleting the file. |
+| `wizardVersion` | `0.1.3` | The wizard's own version. |
+| `command` | `init`, `doctor`, `restore-apply`, … | Which wizard command ran. |
+| `integration` | `react`, `next`, `js`, `null` | Selected integration (`null` for commands that don't have one — `login`, `restore-list`, etc.). |
+| `stability` | `stable`, `beta`, `experimental`, `unsupported`, `null` | Stability level of the active integration. |
+| `os.family` | `darwin`, `linux`, `win32` | Node's `process.platform`. |
+| `os.majorRelease` | `23`, `5`, `10` | Major version of the OS kernel. |
+| `os.arch` | `x64`, `arm64` | Process architecture. |
+| `node.major` | `20`, `22` | Major Node version. |
+| `packageManager` | `npm`, `pnpm`, `yarn`, `yarn-berry`, `bun`, `null` | Detected package manager. |
+| `outcome` | `success`, `failure`, `cancelled`, `noop` | Final state. |
+| `stage` | `auth`, `patch`, `restore`, … | Stage at termination. |
+| `errorCode` | `E_PATCH_FAILED`, `null` | Canonical error code; never message text. |
+| `rollbackTriggered` | `true`/`false` | Did an in-process rollback fire? |
+| `durationMs` | `4231` | Wall-clock duration. |
+
+That's the entire payload. There are no opaque "metadata" or "extras"
+fields.
+
+## What we NEVER send
+
+The TypeScript type in `src/telemetry/payload.ts` is the contract. The
+wizard CANNOT send any of the following — there is no field for them:
+
+- API keys, DSNs, OAuth tokens, refresh tokens.
+- Org names, project names, project ids, org ids.
+- File paths (absolute or relative).
+- `process.env` values.
+- Source code from your repo.
+- Error message text or stack frames.
+- Email addresses, IP addresses, hostnames.
+
+The error code `E_PATCH_FAILED` reaches us; the patcher's stack trace and
+the file path it failed on do not.
+
+## How to disable
+
+Three independent ways, any one of them is sufficient:
+
+```bash
+# Per-run flag:
+npx @allstak/wizard@beta --no-telemetry ...
+
+# Process env:
+ALLSTAK_WIZARD_TELEMETRY=0 npx @allstak/wizard@beta ...
+
+# Globally for your shell:
+export ALLSTAK_WIZARD_TELEMETRY=0
+```
+
+Disabling does NOT disable the wizard's local audit trail (snapshots in
+`.allstak-wizard/backups/`). Those are local-only and never sent anywhere.
+
+## How to inspect what would be sent
+
+```bash
+npx @allstak/wizard@beta --telemetry-debug -i react --dry-run
+```
+
+`--telemetry-debug` prints the would-be payload to stderr instead of
+sending it, regardless of the gate state.
+
+## Where the data goes
+
+- **Default provider** is `noop` — the wizard does NOT phone home in beta.
+  `noopTelemetry` is selected unless an operator (or you) explicitly wires
+  in `httpTelemetry({ endpoint })`. This is a deliberate beta-period
+  posture: build the abstraction, don't quietly start collecting.
+- When configured: HTTPS POST of the JSON payload with a 1.5s timeout,
+  failures swallowed.
+
+## Credentials
+
+`allstak login` stores your JWT pair in your OS keychain (macOS / libsecret)
+or an AES-256-GCM encrypted file fallback. Never sent to telemetry. See
+`src/credentials/` for the implementation.
+
+## Anonymous install id
+
+Stored at `~/.config/allstak/install-id` (or the platform equivalent).
+Generated lazily on first telemetry-emitting run. Delete the file to
+rotate. Telemetry-disabled runs do NOT generate or read it.
+
+## Audit
+
+The complete payload type is at `src/telemetry/payload.ts`. The unit-test
+suite asserts that the runtime payload contains EXACTLY the documented
+fields (no more, no fewer) — adding a field requires updating both the
+type and this doc, and the test fails until you do.

package/docs/beta/quickstart.md

@@ -0,0 +1,89 @@
+# Quickstart — `@allstak/wizard@beta`
+
+> Status: **public beta**. The wizard is honest about what works and what
+> doesn't — see [known limitations](./known-limitations.md) for the gaps you
+> need to know about before adopting.
+
+## Install + run in one command
+
+```bash
+# React (Vite or CRA)
+npx @allstak/wizard@beta -i react
+
+# Next.js (app or pages router; 13+)
+npx @allstak/wizard@beta -i next
+
+# Vanilla Node
+npx @allstak/wizard@beta -i js
+```
+
+The wizard auto-detects your framework if you omit `-i`.
+
+## Five-minute first run
+
+```bash
+# 1. Authenticate against AllStak (email OTP).
+npx @allstak/wizard@beta login
+
+# 2. List your orgs and projects.
+npx @allstak/wizard@beta orgs list
+npx @allstak/wizard@beta projects list
+
+# 3. Create a project + mint an API key in one go.
+npx @allstak/wizard@beta projects create \
+  --name "My App" --slug my-app \
+  --with-api-key
+
+# 4. Run the wizard against your project.
+cd /path/to/my/app
+npx @allstak/wizard@beta            # auto-detect
+# or:
+npx @allstak/wizard@beta -i next
+
+# 5. Verify the setup with a real test event.
+npx @allstak/wizard@beta doctor --live-probe \
+  --api-key ask_live_... \
+  --project-id <project-uuid>
+```
+
+## What the wizard does (in order)
+
+1. Detects your framework + package manager.
+2. Loads `allstak.config.*` if present.
+3. Verifies framework version compatibility.
+4. **Asks for confirmation** before any disk write (skip with `-y`).
+5. Installs the right `@allstak/*` package via your package manager.
+6. Writes env vars to `.env.local` / `.env` — never overwrites your values.
+7. Patches your entry file (AST-injects the import; appends a managed-block
+   hint).
+8. Wires the source-map plugin into `vite.config.*` / `next.config.*`.
+9. Snapshots every touched file to `.allstak-wizard/backups/<id>/`.
+10. Runs a doctor pass and reports the result.
+
+## Always reversible
+
+```bash
+# Roll back the latest snapshot.
+npx @allstak/wizard@beta restore apply latest
+
+# Or fully uninstall.
+npx @allstak/wizard@beta uninstall -i react
+```
+
+## Dry-run before committing
+
+```bash
+npx @allstak/wizard@beta -i react --dry-run --json | jq '.diff'
+```
+
+The dry-run never touches disk.
+
+## Next reads
+
+- [`react.md`](./react.md), [`next.md`](./next.md), [`node.md`](./node.md) — per-integration guides.
+- [`config.md`](./config.md) — `allstak.config.ts` precedence + migrations.
+- [`doctor.md`](./doctor.md) — diagnosing a setup.
+- [`restore.md`](./restore.md) — restoring snapshots.
+- [`privacy.md`](./privacy.md) — telemetry contract.
+- [`troubleshooting.md`](./troubleshooting.md) — common errors and fixes.
+- [`known-limitations.md`](./known-limitations.md) — what's NOT supported in beta.