@allstak/wizard 0.1.3

package/docs/architecture/v02-bare-react-native-spec.md

@@ -0,0 +1,92 @@
+# v0.2 spec — Bare React Native integration
+
+**Status:** UNSUPPORTED in v0.1.x — wizard refuses with `UnsupportedFrameworkError`.
+
+This spec is what v0.2 must implement before `react-native` flips from `unsupported` to `experimental` (and eventually `beta`).
+
+---
+
+## Why bare RN is hard
+
+Bare RN integration is the only wizard target that touches **three** ecosystems at once:
+
+1. JavaScript / TypeScript source (entry file wrap).
+2. **iOS native** — Podfile + AppDelegate.swift modifications, CocoaPods install.
+3. **Android native** — settings.gradle + app/build.gradle, Gradle plugin classpath, AndroidManifest.
+
+Any one of these going wrong bricks `xcodebuild` or `./gradlew assembleDebug`. Wizard cannot validate that without running real device builds, which the v0.1.x test infrastructure does not have.
+
+Expo (config-plugin path) is a strict subset of this surface and is already partially scaffolded (`stability: experimental`).
+
+---
+
+## Validation matrix v0.2 must pass
+
+Before flipping `stability` from `unsupported`:
+
+| Path | Validation |
+|------|------------|
+| Patch idempotency | `init` → `init` produces byte-identical project (already a wizard invariant; just needs a fixture to assert against). |
+| iOS sim build | `npx react-native run-ios` succeeds on iOS 16/17/18 simulators against a fresh fixture; AllStak crash hook captured a synthetic crash. |
+| Android emu build | `npx react-native run-android` succeeds against API 31/33/34 emulators. |
+| Hermes source-map round-trip | A symbolicated stack frame from a bundled-and-uploaded JS file resolves on the dashboard. |
+| Uninstall | After `init` then `uninstall`, both `xcodebuild` and `gradlew assembleDebug` still pass; no dangling Pod or Gradle entries. |
+| Repair | After hand-deleting our managed Podfile region, `repair` reinstates it without touching any other Podfile content. |
+| New Architecture (Fabric / TurboModules) | If the project enables `newArchEnabled=true`, the integration must not regress build. |
+
+The v0.1.x repo already supports Fixture-based testing in `fixtures/`. v0.2 needs a `fixtures/react-native-bare/` (and matching `react-native-expo/`) plus a CI runner that has Xcode + Android emulator access.
+
+---
+
+## Files the integration patches
+
+### iOS
+
+- `ios/Podfile` — append (inside the project's main target):
+  ```ruby
+  pod 'AllStakRN', :path => '../node_modules/@allstak/react-native'
+  ```
+- `ios/<App>/AppDelegate.{m,mm,swift}` — call `[AllStak start]` from `application:didFinishLaunchingWithOptions:`.
+  - Wizard MUST detect Obj-C vs Swift AppDelegate and choose the right insertion.
+  - All insertions wrapped in markers (`// >>> allstak-wizard:v1 ...`).
+
+### Android
+
+- `android/settings.gradle` — append `include ':allstak-react-native'` and the matching `project(...)` line.
+- `android/app/build.gradle` — `dependencies { implementation project(':allstak-react-native') }`.
+- `android/app/src/main/java/.../MainApplication.{java,kt}` — register the package in `getPackages()`.
+- Wizard MUST read `org.gradle.jvmargs` to detect Hermes and conditionally wire the source-map post-build hook from `allstak-react-native/build-hooks/allstak-sourcemaps.gradle`.
+
+### JavaScript
+
+- `index.js` / `App.tsx` — wrap root component in `<AllStakProvider>` (same pattern as `react`).
+- `metro.config.js` — extend `transformer.hermesParser` only when needed; default leave alone.
+
+---
+
+## Open questions for v0.2 design
+
+1. **Does `pod install` run inside the wizard's transaction?** Recommendation: NO. Pod install mutates `Podfile.lock` and the `Pods/` tree atomically; rolling that back is not feasible. The wizard should print "Pods updated; run `pod install` once more if you see linker errors" and let the user own that step.
+2. **Does the integration block on a connected emulator?** Recommendation: NO. The wizard is offline-first; users can run `react-native run-ios` themselves. Integration tests in CI gate on emulator presence.
+3. **Expo bare workflow** (post-`expo prebuild`) — is this `expo` integration (config-plugin path) or `react-native` (bare path)? Recommendation: detect `npx expo prebuild` evidence (presence of `ios/` AND a `app.json` with `expo` key) and offer the user a choice.
+4. **Old Architecture vs New Architecture** — wizard reads `android/gradle.properties:newArchEnabled`. If true, the integration must include the Fabric component registration (a more involved Gradle change). v0.2 might gate this behind `--experimental` even after the rest of bare RN is `beta`.
+
+---
+
+## Wizard-side plumbing already in place
+
+These already exist and don't need re-work:
+
+- The `react-native` integration object refuses cleanly with a clear `UnsupportedFrameworkError` and pointer to manual docs.
+- The `IntegrationManifest` has `wire-native-ios` / `wire-native-android` capabilities to declare in v0.2.
+- `Transaction` + `SnapshotStore` already handle the JS-side patches transactionally.
+
+---
+
+## Recommended ticket breakdown
+
+1. **RN-1** Add `fixtures/react-native-bare/` with a minimal RN 0.74 + 0.75 + 0.76 project. CI runner with Xcode + Android emu (use macOS GitHub-hosted runner for iOS, Ubuntu + Android emulator for Android).
+2. **RN-2** Implement `src/integrations/react-native-bare/` (renamed from current placeholder) with `manifest`/`detect`/`patch`/`uninstall`/`doctor`. Reuse `_shared.ts` and `_scaffold.ts`.
+3. **RN-3** Native patchers: `src/patchers/podfile.ts`, `src/patchers/gradle.ts`, `src/patchers/appdelegate.ts`. Each writes through `Transaction` with a parser-based syntax check.
+4. **RN-4** End-to-end `pod install` + `gradle assembleDebug` smoke in CI gated to RN-2.
+5. **RN-5** Hermes source-map upload roundtrip — depends on the source-maps E2E spec landing first.

package/docs/architecture/v02-java-host-fix-spec.md

@@ -0,0 +1,125 @@
+# v0.2 spec — Java SDK host configurability
+
+**Status:** PROPOSED. No code in `allstak-java-sdk` has been modified by this wizard release.
+
+---
+
+## Problem
+
+The wizard's `--host` / `--ingest-host` / `--dashboard-host` flags allow users
+to point the wizard at a self-hosted AllStak deployment. For most SDKs this
+flows through to a runtime `host` field on `init()` config.
+
+For `sa.allstak:allstak-spring-boot-starter` and `sa.allstak:allstak-java-core`,
+the host is **hardcoded** to `https://api.allstak.sa` in the SDK source.
+Wizard's `--host` is silently a no-op for Java users — events go to the wrong
+backend without any error.
+
+Per the v0.1 implementation report (2026-05-07): "filed below as a v0.2
+SDK-side blocker."
+
+---
+
+## Required SDK-side change
+
+Reference the AllStak SDK workspace at:
+
+```
+/Volumes/M.2/MyProjects/AllStak-Projects/sdks/allstak-java-sdk
+```
+
+The change is small but needs to land in the SDK before the wizard's `java`
+integration can graduate from `experimental`:
+
+### 1. Add a `host` field to `AllStakConfig`
+
+```java
+public class AllStakConfig {
+  private String apiKey;
+  private String environment;
+  private String release;
+  private String serviceName;
+  private String host;          // NEW — defaults to "https://api.allstak.sa"
+  // …existing fields…
+
+  // Builder method:
+  public Builder host(String host) { this.host = host; return this; }
+}
+```
+
+### 2. Read `ALLSTAK_HOST` env var in the auto-config
+
+```java
+@ConfigurationProperties(prefix = "allstak")
+public class AllStakProperties {
+  // existing fields…
+  private String host = System.getenv().getOrDefault("ALLSTAK_HOST", "https://api.allstak.sa");
+}
+```
+
+### 3. Spring Boot `application.yml` exposure
+
+```yaml
+allstak:
+  api-key: ${ALLSTAK_API_KEY}
+  host: ${ALLSTAK_HOST:https://api.allstak.sa}    # NEW
+```
+
+### 4. Pass `host` through to the HTTP transport
+
+The transport class (likely `AllStakHttpClient` or similar) currently has a
+hardcoded base URL. Replace with `config.getHost()`.
+
+---
+
+## Compatibility implications
+
+- **Backwards compatible:** existing users who pass nothing get the old
+  default. No breaking change to the public API.
+- **Bumps the minor version** — first SDK release with the field should be
+  `0.2.0` (not `0.1.x`) per semver.
+- **Wizard manifest update:** once shipped, edit
+  `src/integrations/java.ts` and the manifest's `compatibility` to require
+  the new minimum version: `{ name: 'sa.allstak:allstak-java-core',
+  minVersion: '0.2', maxMajorExclusive: null, required: true }`.
+- **Wizard's `java` integration warning** can be removed from
+  `manifest.stabilityNote` once v0.2.0 of the SDK is the minimum.
+
+---
+
+## Wizard-side validation v0.2 must add
+
+After the SDK ships:
+
+1. Update `src/integrations/java.ts` to actually patch `pom.xml` /
+   `build.gradle` (currently the integration is `experimental` and only
+   writes env vars).
+2. Add `fixtures/spring-boot/` with a minimal Spring Boot 3.x project
+   (`./mvnw test` runs in CI).
+3. Doctor stage `event-ingest` should be runnable against a Java-emitted
+   event (the existing doctor probe is a generic event so this Just Works
+   once the SDK respects `--host`).
+
+---
+
+## Why the wizard does NOT change this from this side
+
+- CLAUDE.md's monorepo policy: "Do not modify unrelated SDKs unless required."
+- Even with permission, modifying a Java SDK from a TypeScript wizard
+  session has no path to validate the change (no `mvn` in the wizard's CI
+  matrix).
+- The change is small enough (~20 LoC) that it belongs in a focused PR
+  against `allstak-java-sdk` rather than being smuggled in through wizard
+  work.
+
+---
+
+## Action items for whoever picks this up
+
+1. Open a ticket against `allstak-java-sdk` referencing this spec.
+2. Implement the `host` field + env-var lookup in the SDK.
+3. Bump SDK to `0.2.0` and publish to Maven Central.
+4. Update `src/integrations/java.ts` manifest to require `0.2+`.
+5. Remove the warning blurb from the manifest's `stabilityNote`.
+6. Move the integration's `stability` from `experimental` toward `beta`
+   once Spring Boot fixture validation lands.

package/docs/architecture/v02-sourcemaps-e2e-spec.md

@@ -0,0 +1,157 @@
+# v0.2 spec — Source-maps end-to-end roundtrip
+
+**Status:** Wizard wires bundler plugins via `SourceMapProvider` (v0.1.1) but
+does NOT yet validate the upload → release-binding → symbolication chain
+against the live backend. This spec documents what v0.2 must add.
+
+---
+
+## What works today (v0.1.x)
+
+- `vite` provider: AST-injects `import { allstakVitePlugin } from '@allstak/js/vite'` and adds a managed-block hint.
+- `next` provider: managed-block hint pointing the user at `withAllStak`.
+- `webpack` provider: managed-block hint only.
+- `metro` provider: intentionally inert; `detect()` returns false.
+- `doctor` reports per-provider `wired` / `drifted` / `missing` state.
+
+What this gives us: the bundler is correctly configured to produce + upload
+source maps. What it does NOT verify: that uploaded maps actually resolve
+stack frames in the dashboard.
+
+---
+
+## Backend contract (verified 2026-05-07)
+
+Endpoint:
+
+```
+POST /api/v1/sourcemaps/upload?projectId=:id&release=:version&fileName=:path&bundleUrl=:url
+  Content-Type: application/json
+  Authorization: Bearer <user JWT>
+
+  Body: raw .map JSON content (size limit 16 MB)
+
+  Response: 200 OK
+  {
+    "id": "uuid",
+    "release": "1.2.3",
+    "fileName": "assets/main-abc123.js.map",
+    "sizeBytes": 12345,
+    "uploadedAt": "2026-05-07T..."
+  }
+```
+
+Server-side resolution: the dashboard's error detail view symbolicates frames
+on read by looking up `(projectId, release, fileName)`. Maps are stored
+indefinitely (no TTL).
+
+Symbolication endpoint (used by error-detail UI; we can use it to verify):
+
+```
+POST /api/v1/sourcemaps/symbolicate
+  Body: { projectId, release, frames: [stackString] }
+  Response: { release, totalFrames, resolvedFrames, frames: [{ raw, resolved }] }
+```
+
+---
+
+## Validation matrix v0.2 must pass
+
+| # | Check | Pass condition |
+|---|-------|----------------|
+| 1 | Upload happens during `npm run build` | Per-bundler post-build hook actually POSTs `.map` files. |
+| 2 | Release binding | Uploaded maps are queryable by `(projectId, release)`. |
+| 3 | Round-trip resolution | Send a synthetic event with a stack frame referencing the uploaded bundle → symbolicate endpoint resolves it to the original source line. |
+| 4 | Idempotent upload | Re-running build with same `(release, fileName)` is a no-op or a clean overwrite — never a duplicate. |
+| 5 | Auth scope | Upload requires JWT (not API key). Wizard's `requireUserCredentials` already handles this. |
+
+---
+
+## What v0.2 needs to build
+
+### A. A real upload runner
+
+`src/sourcemaps/upload.ts`:
+
+```ts
+export async function uploadSourceMap(
+  apiHost: string,
+  accessToken: string,
+  params: {
+    projectId: string;
+    release: string;
+    fileName: string;     // e.g. "assets/main-abc123.js"
+    bundleUrl?: string;   // public URL of the bundle (helps dashboard match)
+    mapContent: string;   // raw JSON from .map
+  },
+): Promise<{ id: string }> {
+  // Use apiRequest from src/api/http.ts with body=mapContent and contentType='application/json'.
+}
+```
+
+This already has a slot in `src/api/http.ts` (the `contentType` override
+parameter exists for exactly this case).
+
+### B. A `wizard sourcemaps upload` CLI subcommand
+
+```bash
+allstak sourcemaps upload \
+  --project-id <uuid> \
+  --release "$GIT_SHA" \
+  --build-dir dist \
+  --pattern "**/*.js.map"
+```
+
+Walks `build-dir`, POSTs each `.map` file, prints the upload manifest. Reuses
+`getCredentialStore()` + `requireUserCredentials()`.
+
+### C. End-to-end doctor stage
+
+Extend `runDoctor` with a new stage `source-maps-e2e` that runs only with
+`--live-probe`:
+
+1. Build a tiny known fixture into a temp dir.
+2. Upload its `.map`.
+3. Send a probe event whose stack frame points at the uploaded bundle.
+4. Hit `/api/v1/sourcemaps/symbolicate` and assert `resolvedFrames > 0`.
+
+### D. CI matrix entry
+
+Add a `source-maps-e2e` job to the wizard's CI workflow gated on a
+repository secret (`ALLSTAK_E2E_API_KEY` + `ALLSTAK_E2E_PROJECT_ID`).
+Without those secrets the job skips.
+
+---
+
+## Risks
+
+1. **`.map` files can be huge** (50MB+ for production bundles). Backend
+   currently caps at 16MB. v0.2 should either:
+   - Detect maps larger than the cap and skip with a warning, OR
+   - Negotiate a larger cap with the backend team.
+2. **`bundleUrl` parameter is optional but improves resolution accuracy.**
+   The wizard should compute it from the project's deploy target where
+   possible (Vercel? Netlify? Cloudflare Pages? — heuristics).
+3. **Hermes maps require a different upload format.** Bytecode → JS source
+   resolution is a separate symbolication pipeline; the v0.1 wizard does NOT
+   support this. Document explicitly when implementing.
+4. **Token rotation during long uploads.** The user JWT has a 15-minute TTL.
+   If uploading 100 `.map` files takes >15 minutes, the wizard must
+   `refreshTokens()` mid-upload. The credential store + auth client already
+   support this; just needs a wrapper.
+5. **Idempotency**: backend probably accepts the same `(release, fileName)`
+   twice and overwrites. Verify before relying on this.
+
+---
+
+## Why this is deferred
+
+End-to-end validation requires:
+- A live AllStak instance (production or staging).
+- A real org + project the engineer can write to.
+- Credentials with both ingest scope AND user scope.
+- The ability to assert dashboard-side symbolication output.
+
+None of these are available in the v0.1.x wizard test environment. The
+provider abstraction landed in v0.1.1 specifically so this work can plug in
+without rewriting integrations.

package/package.json

@@ -0,0 +1,98 @@
+{
+  "name": "@allstak/wizard",
+  "version": "0.1.3",
+  "description": "Unified installation and configuration wizard for AllStak SDKs.",
+  "type": "module",
+  "bin": {
+    "allstak-wizard": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./registry": {
+      "types": "./dist/registry/index.d.ts",
+      "import": "./dist/registry/index.js"
+    },
+    "./detect": {
+      "types": "./dist/detect/index.d.ts",
+      "import": "./dist/detect/index.js"
+    },
+    "./sourcemaps": {
+      "types": "./dist/sourcemaps/index.d.ts",
+      "import": "./dist/sourcemaps/index.js"
+    },
+    "./migrations": {
+      "types": "./dist/migrations/index.d.ts",
+      "import": "./dist/migrations/index.js"
+    },
+    "./output": {
+      "types": "./dist/output/index.d.ts",
+      "import": "./dist/output/index.js"
+    },
+    "./telemetry": {
+      "types": "./dist/telemetry/provider.d.ts",
+      "import": "./dist/telemetry/provider.js"
+    },
+    "./snapshot": {
+      "types": "./dist/snapshot/store.d.ts",
+      "import": "./dist/snapshot/store.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "docs/architecture"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "type-check": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test --test-concurrency=1 --import tsx test/markers.test.mts test/transaction.test.mts test/patchers.test.mts test/detect.test.mts test/integration-react.test.mts test/integration-next.test.mts test/integration-js.test.mts test/snapshot.test.mts test/compat.test.mts test/lifecycle.test.mts test/sourcemaps.test.mts test/migrations.test.mts test/output.test.mts test/config.test.mts test/credentials.test.mts test/restore.test.mts test/error-codes.test.mts test/telemetry.test.mts test/config-migrations.test.mts",
+    "test:integration": "node --test --test-concurrency=1 --import tsx test/integration-*.test.mts",
+    "wizard": "tsx src/cli.ts",
+    "prepublishOnly": "npm run type-check && npm run test && npm run build"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.7.0",
+    "commander": "^12.1.0",
+    "magicast": "^0.3.5",
+    "picocolors": "^1.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.12.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.4.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "allstak",
+    "wizard",
+    "cli",
+    "sdk-install",
+    "observability",
+    "react",
+    "nextjs"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/allstak-io/sdks.git",
+    "directory": "allstak-wizard"
+  },
+  "homepage": "https://github.com/allstak-io/sdks/tree/main/allstak-wizard",
+  "bugs": {
+    "url": "https://github.com/allstak-io/sdks/issues"
+  },
+  "private": false
+}