@allstak/wizard 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -4,7 +4,59 @@ All notable changes to `@allstak/wizard` will be documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/) and this project
 adheres to [Semantic Versioning](https://semver.org/).
 
-## [Unreleased] — 0.1.3
+## [Unreleased] — 0.1.4-beta.0
+
+### Added
+- **Expo (managed workflow) → beta.** New `expo` integration patches
+  `app.json:expo.plugins[]` (idempotent), AST-injects `AllStakProvider`
+  import in `App.tsx`, and appends a managed-block hint. Refuses on
+  prebuilt projects (`ios/` or `android/` present) with a clear error.
+  See `docs/beta/expo.md`.
+- **NestJS → beta.** New `nestjs` integration AST-injects
+  `AllStakNestExceptionFilter` / `AllStakNestInterceptor` imports and
+  appends a managed-block hint demonstrating `useGlobalFilters` /
+  `useGlobalInterceptors` registration. Wizard does NOT auto-mutate
+  `bootstrap()`. Compat: `@nestjs/core >= 9`. See `docs/beta/nestjs.md`.
+- **Fastify → beta.** New `fastify` integration; ESM entries get an
+  AST-injected `allstakFastify` import, CJS entries get a hint-only
+  patch. Both branches append a managed-block hint demonstrating
+  `app.register(allstakFastify, ...)`. Compat: `fastify >= 4`. See
+  `docs/beta/fastify.md`.
+- Next 15 fixture (`fixtures/next-app-router-15`) added to the
+  integration test matrix; `next` integration now exercised against
+  Next 13/14/15 in unit tests + CI.
+- Three new fixtures (`fixtures/expo-managed`, `fixtures/nestjs-app`,
+  `fixtures/fastify-server`) drive ~30 new integration tests covering
+  detect (incl. version refusal), patch shape, idempotency (byte-equal
+  re-run), uninstall reversal, and `doctor` warn→pass transitions.
+- CI matrix expanded to 8 fixtures × 3 Node versions (18/20/22) =
+  **24 install/uninstall/repair/restore/idempotency cycles per push**.
+
+### Changed
+- Test count: **157 / 157** passing (was 123/123).
+- Next.js uninstall ordering fixed: `removeManagedSourceBlock` now runs
+  BEFORE `patchJsModule(removeImport)`, so wizard-created
+  `instrumentation.ts` files (whose entire content lives inside the
+  managed markers) are correctly deleted on uninstall instead of being
+  orphaned.
+- Next.js `ensureInstrumentationFile` now wraps wizard-generated
+  `register()` content inside managed-block markers when creating the
+  file from scratch — required for clean uninstall round-trip.
+- `next` stability **explicitly held at `beta`** until source-map upload
+  + symbolication roundtrip is validated end-to-end (tracked by an
+  assertion in the unit tests so we cannot accidentally promote it).
+- README rewritten to reflect the v0.1.3 beta surface (real auth, full
+  command list, telemetry contract, error catalog, current v0.2
+  roadmap), and the integration matrix updated to show Expo / NestJS /
+  Fastify at `beta`.
+- Package metadata polished for npm: tighter description, `sdk-install`
+  keyword consolidated to `sdk`, exports map gains `./config` and
+  `./errors` subpaths, `files` whitelist gains `docs/errors.md` and
+  `docs/beta/`.
+- Scrubbed two absolute local paths from shipped content
+  (`docs/architecture/v02-java-host-fix-spec.md`, `src/api/types.ts`).
+
+## [0.1.3] — 2026-05-07
 
 ### Added
 - Privacy-safe telemetry (`src/telemetry/*`) — disabled by default until an

package/LICENSE

@@ -0,0 +1,191 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2024-2026 AllStak
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,79 +1,331 @@
 # @allstak/wizard
 
-> v0.1 — Unified installation and configuration wizard for AllStak SDKs.
+> **v0.1.4** — Unified installation and configuration wizard for AllStak SDKs.
 
-A Sentry-Wizard-style CLI that installs and configures AllStak SDKs in your project with one command. Designed to be **honest by default**: only integrations validated end-to-end against real fixture projects ship with the `VALIDATED` tag; everything else is `SCAFFOLD` and refuses to apply patches without `--experimental`.
+A Sentry-Wizard-style CLI that installs and configures AllStak SDKs in
+your project with one command where automation is complete, and shows
+Manual/light setup guidance where the runtime is Stable but automation is not
+finished. Designed to be **honest by default**: runtime stability and wizard
+automation maturity are separate claims.
 
-## Status
+## Public SDK Status
 
-| Integration   | Tag         | Notes |
-|---------------|-------------|-------|
-| `react`       | VALIDATED   | Vite + plain React, AST-tested |
-| `next`        | VALIDATED   | Next 13+ app & pages router |
-| `js`          | VALIDATED   | Vanilla Node entry-point patching |
-| `expo`        | SCAFFOLD    | Config-plugin path scaffolded; native build verification deferred to v0.2 |
-| `react-native` | UNSUPPORTED | Bare RN intentionally refused — Podfile/Gradle patching not validated |
-| `nestjs` / `fastify` / `otel` / `python` / `go` / `java` / `php` / `ruby` / `dotnet` / `flutter` | SCAFFOLD | Env-var writing only; framework wiring deferred to v0.2 |
+| Integration | Runtime status | Wizard status | Notes |
+|-------------|----------------|-------------------|-------|
+| `js` (JavaScript / TypeScript) | Stable | Stable | Validated end-to-end; wizard can install and wire init. |
+| `react` (Vite or CRA) | Stable | Stable | Validated end-to-end; wizard can install and wire common app entry patterns. |
+| `react-native` (Expo + bare RN) | Stable | Manual/light | Runtime is Stable; wizard provides setup guidance. |
+| `next` (13+, app + pages router) | Beta | Beta | Runtime is Beta (certification score 32); wizard provides App Router and pages-router onboarding. Edge Runtime and Server Actions are not certified. |
+| `java` (Java / Spring Boot) | Beta | Manual/light | Runtime is Beta (certification score 34); wizard provides setup guidance. |
+| `python` | Beta | Manual/light | Runtime is Beta (certification score 34); wizard provides setup guidance. |
+| `go` | Beta | Manual/light | Runtime is Beta (certification score 33); wizard provides setup guidance. |
 
-Run `allstak-wizard list` to see this matrix at runtime.
+`allstak-wizard list` prints public runtime SDKs and makes wizard maturity
+explicit. Manual/light entries are setup guidance, not full automation.
 
-## Install
+## Install + run
 
-In v0.1 the package is not published. To run from source:
+```bash
+# Show help (also fetches and runs the package via npx).
+npx @allstak/wizard --help
+
+# Authenticate against AllStak (email OTP, optional 2FA).
+npx @allstak/wizard login
+
+# Configure your project (auto-detects React / Next / Node).
+npx @allstak/wizard -i react
+
+# Verify with a real test event roundtrip.
+npx @allstak/wizard doctor --live-probe \
+  --api-key ask_live_... \
+  --project-id <project-uuid>
+```
+
+Five-minute walkthrough: [`docs/beta/quickstart.md`](./docs/beta/quickstart.md).
+
+## Authentication
+
+Real AllStak auth flow — no fake endpoints. Backed by the verified
+`/api/v1/auth/*` endpoints on `api.allstak.sa`.
 
 ```bash
-cd /path/to/sdks/allstak-wizard
-npm install
-npx tsx src/cli.ts --help
+allstak-wizard login              # email OTP → JWT pair stored in OS keychain
+allstak-wizard whoami [--verify]  # show current user; --verify round-trips /auth/me
+allstak-wizard logout             # revoke session + clear local credentials
+```
+
+Supports:
+
+- **Email OTP** primary flow (`/api/v1/auth/request-otp` → `/api/v1/auth/verify-otp`).
+- **TOTP** second factor when enabled on the account.
+- **JWT refresh** with proactive 60s pre-expiry refresh + token rotation.
+- **CI mode** via `--api-key` / `ALLSTAK_API_KEY` (skip login entirely).
+- **Cross-platform credential storage**: macOS Keychain, Linux Secret
+  Service (`secret-tool`), AES-256-GCM encrypted-file fallback.
+
+`--api-key` is for project-scoped data-plane operations (sending events).
+The user JWT is for control-plane operations (orgs, projects, doctor). The
+two are NOT interchangeable — that mirrors the backend's design.
+
+## Commands
+
+```
+init [-i <integration>] [--api-key|--org|--project|--release|...] [--dry-run] [-y]
+doctor [-i <integration>] [--live-probe --api-key --project-id <uuid>]
+repair -i <integration> [--dry-run]
+uninstall -i <integration> [-y] [--dry-run]
+list
+
+login [--email <e> --code <c>] [--totp <c>]
+logout [--local-only]
+whoami [--verify]
+
+orgs list
+projects list [--org <id>]
+projects create [--name --slug --platform --with-api-key]
+
+restore list
+restore show <id|latest>
+restore apply <id|latest> [--files=a,b,c] [--dry-run] [-y]
+restore diff <id|latest>
+
+config validate
+config migrate [--dry-run]
+```
+
+Global flags:
+
+```
+--debug              verbose debug logging
+--json               machine-readable output to stdout (status text → stderr)
+--no-telemetry       disable anonymous usage telemetry for this run
+--telemetry-debug    print the telemetry payload to stderr without sending
+```
+
+## Telemetry & privacy
+
+**Default provider is `noopTelemetry`** — the wizard does not phone home in
+beta. An HTTP provider exists (`httpTelemetry({ endpoint })`) for operators
+to wire in once a backend telemetry endpoint is decided on.
+
+Three independent ways to opt out, any one suffices:
+
+```bash
+npx @allstak/wizard --no-telemetry ...
+ALLSTAK_WIZARD_TELEMETRY=0 npx @allstak/wizard ...
+# Or: leave the default noop provider in place (no operator config).
 ```
 
-## Usage
+Inspect what _would_ be sent:
 
 ```bash
-# Auto-detect framework, interactive
-allstak-wizard
+npx @allstak/wizard --telemetry-debug -i react --dry-run
+```
+
+The wizard's payload type is the entire on-the-wire contract. We do **NOT**
+collect:
+
+- API keys, DSNs, refresh tokens, OAuth secrets
+- Org names, project names, project ids, org ids
+- File paths (absolute or relative)
+- Env-var values
+- Source code, error message text, stack frames
+- Email addresses, IP addresses, hostnames
+
+We do collect: wizard version, command, integration id, stability level,
+OS family + major, Node major, package manager, outcome, stage, canonical
+error code (no message text), `rollbackTriggered` (boolean), `durationMs`.
 
-# Explicit, non-interactive
-allstak-wizard -i react --api-key $ALLSTAK_API_KEY -y
+Full contract: [`docs/beta/privacy.md`](./docs/beta/privacy.md).
 
-# Self-hosted
-allstak-wizard -i next --host https://api.acme.allstak.com --api-key $KEY -y
+## Config (`allstak.config.{ts,mjs,js,cjs,json}`)
 
-# Dry run (prints diff, writes nothing)
-allstak-wizard -i react --dry-run -y
+Optional project-level config so you don't repeat `--org`, `--project`,
+`--host`, etc. on every wizard invocation.
 
-# Other commands
-allstak-wizard list
-allstak-wizard doctor [-i react]
-allstak-wizard repair -i react
-allstak-wizard uninstall -i react -y
+```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',
+  },
+});
 ```
 
-## Authentication (v0.1)
+**Precedence:** `CLI flag > env var > config file > built-in default`.
 
-Browser/device-flow login is **not** implemented in v0.1. Provide a key via `--api-key` or `ALLSTAK_API_KEY`. `allstak-wizard login` exits with a clear hint.
+Validate:
 
-## Architecture
+```bash
+allstak-wizard config validate
+```
 
-- **Registry** — every integration is an `Integration` object with `detect`, `plan`, `install`, `patch`, `validate`, `uninstall`, `repair`, `doctor` methods. New integrations register themselves; the CLI is integration-agnostic.
-- **Transaction** — every file mutation goes through a `Transaction` that snapshots before writing, validates syntax after writing, and rolls back the entire batch on any failure.
-- **Markers** — every injected region is wrapped with `>>> allstak-wizard:v1` markers. Re-runs replace the existing block (idempotent). `uninstall` removes the block cleanly.
-- **AST patching** — JS/TS files use `magicast` (recast under the hood) to add imports without disturbing user code; non-AST changes (provider wrap hints, Vite plugin hints) live in marker blocks.
-- **Dry-run** — every command supports `--dry-run`; the transaction layer captures the diff but skips disk writes.
+Migrate to a new schema version:
 
-## Self-hosted support
+```bash
+allstak-wizard config migrate --dry-run    # preview
+allstak-wizard config migrate              # rewrites .json in place
+```
 
-The wizard never assumes `api.allstak.sa`; pass `--host`, `--ingest-host`, and `--dashboard-host` to point at any AllStak deployment. Note: the Java SDK currently hardcodes its host — that's a known SDK-side bug, not a wizard bug. See the v0.1 implementation report for details.
+Full reference: [`docs/beta/config.md`](./docs/beta/config.md).
 
-## Testing
+## Doctor (deterministic diagnostics)
+
+```bash
+allstak-wizard doctor                              # offline check
+allstak-wizard doctor --live-probe \               # send + verify a real event
+  --api-key ask_live_... --project-id <uuid>
+```
+
+Runs seven named stages in fixed order — `auth → reachability → config →
+integration → event-ingest → release-linkage → source-maps`. Each stage
+reports `pass`/`warn`/`fail`/`skip` with an actionable fix. Live probe POSTs
+to `/ingest/v1/errors`, polls `/api/v1/errors`, and prints the dashboard URL
+of the captured event.
+
+Full reference: [`docs/beta/doctor.md`](./docs/beta/doctor.md).
+
+SDK reliability and outage behavior are documented in
+[`docs/beta/reliability.md`](./docs/beta/reliability.md). Wizard-generated
+runtime integrations must be fail-open: AllStak ingest outages should drop or
+delay telemetry, not break the host application.
+
+## Restore (persistent snapshots)
+
+Every wizard mutation is captured under
+`.allstak-wizard/backups/<id>/manifest.json` plus per-file pre-images.
 
 ```bash
-npm run test              # 46 tests across markers, transaction, patchers, detect, integrations
-npm run type-check
+allstak-wizard restore list
+allstak-wizard restore show latest
+allstak-wizard restore diff latest
+allstak-wizard restore apply latest [--files=src/main.tsx]
 ```
 
-Tests use temp-dir fixtures (no network, no SDK install required) and validate idempotency, rollback, dry-run, and uninstall round-trips for all VALIDATED integrations.
+Full reference: [`docs/beta/restore.md`](./docs/beta/restore.md).
+
+## Error codes
+
+22 canonical error codes — stable across releases (added; never renamed).
+Both human and `--json` output expose `{code, stage, subcode?, message,
+hint}`. Catalog: [`docs/errors.md`](./docs/errors.md).
+
+```bash
+$ allstak-wizard --json -i react -y --skip-deps
+{
+  "outcome": "failure",
+  "errorCode": "E_AUTH_REQUIRED",
+  "data": { "error": {
+    "code": "E_AUTH_REQUIRED",
+    "stage": "auth",
+    "subcode": "E_MISSING_KEY",
+    "message": "...",
+    "hint": "Pass --api-key or run `allstak login`."
+  } }
+}
+```
+
+Exit codes: `0` success, `2` `WizardError`, `130` user cancellation.
+
+## Self-hosted
+
+Pass `--host`, `--ingest-host`, `--dashboard-host` directly, or set
+`selfHosted.*` in `allstak.config.*`. The wizard never assumes
+`api.allstak.sa`.
+
+**Caveat:** `allstak-java-sdk` currently hardcodes its host. Until that
+SDK ships a configurable `host` field, the wizard's `--host` flag is a
+no-op for `-i java`. Spec for the SDK fix:
+[`docs/architecture/v02-java-host-fix-spec.md`](./docs/architecture/v02-java-host-fix-spec.md).
+
+## Architecture
+
+- **Registry** — every integration is an `Integration` object with
+  `detect`, `plan`, `install`, `patch`, `validate`, `uninstall`, `repair`,
+  `doctor` methods. New integrations register themselves; the CLI is
+  integration-agnostic.
+- **Transaction** — every file mutation snapshots before write, syntax-
+  validates after write, and rolls back the entire batch on any failure.
+- **Persistent snapshots** — alongside in-memory rollback, every run
+  writes a backup under `.allstak-wizard/backups/<id>/` for cross-run
+  recovery via `restore`.
+- **Markers** — every injected region wrapped with `>>> allstak-wizard:v1`
+  markers. Re-runs replace in place (idempotent). `uninstall` removes the
+  block cleanly.
+- **AST patching** — `magicast` (recast under the hood) for JS/TS imports;
+  managed-block hints for non-AST patches (Vite plugins, Next config).
+- **Dry-run** — every command supports `--dry-run`; transaction layer
+  captures the diff and skips disk writes.
+- **Source-map providers** — pluggable abstraction (`vite`, `webpack`,
+  `next`, `metro`); integrations select a provider by id.
+- **Lifecycle hooks** — `beforeInstall`/`afterInstall`/`beforePatch`/
+  `afterPatch`/`beforeRollback`/`afterRollback`/`beforeUninstall`/
+  `afterUninstall` for telemetry + plugin extensions.
+
+Full design docs: [`docs/architecture/`](./docs/architecture/).
+
+## Development from source
+
+```bash
+cd /path/to/sdks/allstak-wizard
+npm install
+npm run type-check         # tsc --noEmit (clean)
+npm test                   # 157 tests, ~5s
+npm run build              # emits dist/ with .d.ts + source maps
+npx tsx src/cli.ts --help  # run from source
+
+# Smoke against a fixture (no network, no SDK install):
+cd fixtures/react-vite
+ALLSTAK_API_KEY=ask_test \
+  npx --prefix ../.. tsx ../../src/cli.ts -i react --dry-run -y --skip-deps
+```
+
+## Testing
+
+| Status | Count |
+|--------|-------|
+| Type-check | clean |
+| Unit + integration tests | **157 / 157** passing |
+| Build | clean (.js + .d.ts + source maps) |
+
+Tests run on temp-dir fixtures (no network, no real SDK install) and
+validate idempotency, rollback, dry-run, restore round-trip, error catalog
+coverage, telemetry payload contract, and config migration plumbing.
+
+## Roadmap
+
+Beta is shipping intentionally narrow. v0.2 priorities:
+
+1. **Bare React Native** — Podfile + Gradle patchers + iOS/Android
+   validation matrix. Spec:
+   [`docs/architecture/v02-bare-react-native-spec.md`](./docs/architecture/v02-bare-react-native-spec.md).
+2. **Source-maps end-to-end** — upload + symbolication round-trip against
+   `/api/v1/sourcemaps/upload`. Spec:
+   [`docs/architecture/v02-sourcemaps-e2e-spec.md`](./docs/architecture/v02-sourcemaps-e2e-spec.md).
+3. **Astro support** — currently falls through to `js` (env vars only).
+4. **Java SDK host fix** — coordinate with `allstak-java-sdk` to make
+   host configurable.
+5. **Backend SDK framework wiring** — NestJS `main.ts`, Spring Boot
+   `application.yml`, Django/FastAPI/Flask/Rails/.NET/Go/PHP entry-point
+   patching with per-framework fixture validation.
+6. **Telemetry HTTP endpoint** — backend contract pending.
+
+## License
+
+Apache-2.0 — see [`LICENSE`](./LICENSE).
 
-## v0.2 roadmap
+## Issues
 
-See `docs/reports/allstak-unified-sdk-wizard-v0.1-implementation.md` (in the platform monorepo) for the full plan.
+[github.com/allstak-io/sdks/issues](https://github.com/allstak-io/sdks/issues)

package/dist/api/http.d.ts

@@ -33,6 +33,8 @@ export interface RequestInit {
     signal?: AbortSignal;
     /** Override Content-Type — used by source-map upload (still JSON in body but custom MIME). */
     contentType?: string;
+    /** Extra non-auth headers. Callers must not pass secrets except purpose-scoped control-plane headers. */
+    headers?: Record<string, string | undefined>;
 }
 export interface ApiResponse<T> {
     status: number;

package/dist/api/http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/api/http.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AAEH,MAAM,MAAM,QAAQ,GAChB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpC,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,uBAAuB;IACvB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC;IAC9D,IAAI,EAAE,QAAQ,CAAC;IACf,qCAAqC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,8FAA8F;IAC9F,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,CAAC,CAAC;IACR,oBAAoB;IACpB,EAAE,EAAE,OAAO,CAAC;CACb;AAID,wBAAsB,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAsE5F"}
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/api/http.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AAEH,MAAM,MAAM,QAAQ,GAChB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpC,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,uBAAuB;IACvB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC;IAC9D,IAAI,EAAE,QAAQ,CAAC;IACf,qCAAqC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,8FAA8F;IAC9F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yGAAyG;IACzG,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CAC9C;AAED,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,CAAC,CAAC;IACR,oBAAoB;IACpB,EAAE,EAAE,OAAO,CAAC;CACb;AAID,wBAAsB,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CA2E5F"}

package/dist/api/http.js

@@ -13,6 +13,12 @@ export async function apiRequest(host, init) {
     else if (init.auth.kind === 'apiKey') {
         headers['X-AllStak-Key'] = init.auth.key;
     }
+    if (init.headers) {
+        for (const [key, value] of Object.entries(init.headers)) {
+            if (value !== undefined && value !== '')
+                headers[key] = value;
+        }
+    }
     const controller = new AbortController();
     const externalSignal = init.signal;
     const timeout = setTimeout(() => controller.abort(new Error('timeout')), init.timeoutMs ?? DEFAULT_TIMEOUT);