@soloworks/smking-wizard 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# @soloworks/smking-wizard
+
+## 0.1.0
+
+Initial release — single-command install wizard for smking SDKs.
+
+### Features
+
+- **OAuth PKCE flow** — public client with localhost callback (ports 8235–8240), 6-min timeout, browser auto-open with URL fallback for SSH.
+- **Framework detection** — Laravel (via `artisan` presence) and Next.js App Router (via `package.json` + `app/` or `src/app/`).
+- **Package manager detection** — pnpm > bun > yarn > npm via lockfile.
+- **Deterministic installers**:
+  - Laravel: `composer require smking/laravel` → `vendor:publish --tag=smking-config` → `.env` keys → `config:clear`.
+  - Next.js: `<pm> add @soloworks/smking-next` → `.env.local` keys → AST-style edit of `app/layout.tsx` to add `<SmkingAEO />`.
+- **AI agent loop** — Claude Sonnet 4.6 via smking's gateway proxy (no customer Anthropic key needed). 6 typed tools (`detect_framework`, `detect_package_manager`, `install_package`, `set_env`, `run_doctor`, `report_failure`), zero bash, Zod-locked env keys.
+- **Doctor verification** — runs `php artisan smking:doctor --json` (Laravel) or `smking-next doctor --json` (Next.js), parses structured output, agent retries up to 3× per failing check.
+- **Failure telemetry** — unfixable failures POST to `/api/v1/doctor-reports` with structured ticket so smking founder can triage from dashboard.
+- **Safety guards** — refuse on production-like environments (Node env / Vercel / Docker / Railway / fly.io / `/var/www` heuristics) and refuse on dirty git working tree, both with explicit override flags.
+- **ink TUI** — welcome screen with trust signals, OAuth waiting screen with URL fallback, run screen with rolling progress log, done/error terminals.
+
+### Architecture
+
+- Backend: smking SaaS routes `/api/v1/wizard/{install-prompt, gateway/*, doctor-reports}` + dashboard inbox `/dashboard/[siteId]/doctor-reports`.
+- DB: `doctor_reports`, `wizard_sessions` tables. `oauth_codes` gains PKCE columns.
+- LLM proxy: per-session 200K token quota + per-user 5 sessions/day quota enforced server-side.
+
+### Known limitations
+
+- WordPress: out of scope. WP plugin install runs through `wp-admin` zip upload, not CLI.
+- CI mode: `--ci` flag with personal API key not yet implemented.
+- Token-level quota accounting: currently uses request-count proxy (80 req/session). Full token-stream parsing planned for 0.2.

package/README.md

@@ -0,0 +1,90 @@
+# @soloworks/smking-wizard
+
+AI-powered install wizard for smking SDKs. One command installs the SDK, configures your `.env`, and verifies the install with a doctor check.
+
+```bash
+npx @soloworks/smking-wizard
+```
+
+Supported frameworks: **Laravel** ([smking/laravel](https://packagist.org/packages/smking/laravel)) and **Next.js** ([@soloworks/smking-next](https://www.npmjs.com/package/@soloworks/smking-next)).
+
+## What the wizard does
+
+1. Opens your browser to log in to smking (OAuth)
+2. Detects your framework (Laravel or Next.js App Router)
+3. Runs the install command sequence (`composer require` / `pnpm add`)
+4. Writes `SMKING_API_KEY` + `SMKING_BASE_URL` to your `.env`
+5. For Next.js: injects `<SmkingAEO />` into `app/layout.tsx`
+6. Runs `smking:doctor` to verify the install
+7. If a check fails, an AI agent attempts to auto-fix (up to 3 retries per check)
+8. If the agent gives up, posts a structured failure ticket back to smking so the founder can investigate
+
+## What the wizard will NEVER do
+
+- Commit, push, stash, or otherwise mutate git state — you review the diff yourself
+- Read or upload your `.env` values to any server
+- Run destructive commands (`rm`, `drop`, `migrate:fresh`, etc.)
+- Modify environment variables other than `SMKING_*`
+- Install packages other than the smking SDK for your framework
+
+The agent's tool surface is 8 typed functions: `detect_framework`, `detect_package_manager`, `install_package`, `set_env`, `run_doctor`, `read_project_file` (cwd-scoped, extension-allowlisted), `run_artisan` (Laravel-only, 8 commands allowlisted), and `report_failure`. No bash, no generic file ops, no escape hatches.
+
+## Requirements
+
+- Node 20.10+
+- A clean git working tree (the wizard wants its diff to be unambiguous — override with `--allow-dirty`)
+- Not a production-like environment (override with `--allow-prod`)
+
+## Flags
+
+```
+--debug          Verbose debug output (also writes to /tmp/smking-wizard.log)
+--dry-run        Print intended changes without writing files
+--allow-prod     Override production-environment refusal
+--allow-dirty    Override the git-status-must-be-clean check
+--version        Print version
+--help           Print usage
+```
+
+## Environment variables
+
+```
+SMKING_SAAS_URL          Override the SaaS origin the wizard talks to.
+                         Default: https://smking-alone.vercel.app (current
+                         production deploy). Set to http://localhost:3001
+                         for local dev against a `pnpm dev` SaaS.
+SMKING_WIZARD_CLIENT_ID  Override the OAuth client_id (default: smking_wizard_v1).
+                         Only useful when running against a custom SaaS
+                         deploy that registered a different client.
+```
+
+## How LLM cost works
+
+Wizard's LLM calls go through the smking gateway proxy. **The customer never sees or pays for an Anthropic API key** — smking covers it as a customer-onboarding cost.
+
+The agent runs `claude-opus-4-7` with adaptive thinking + prompt caching on the system prompt, so a typical install does 4–6 round-trips at ≈ $0.05 total.
+
+Quota caps (enforced server-side):
+- 200,000 tokens per wizard session
+- 5 sessions per user per day
+
+If you hit the daily limit during testing, wait until UTC midnight or DM smking support.
+
+## For SSH / remote dev environments
+
+The wizard opens your browser via [`open`](https://npm.im/open). If you're SSH'd into a remote machine, that won't work — but the TUI also prints the OAuth URL as text. Copy that URL to a browser on your laptop, log in, and the wizard's localhost callback will catch the redirect (because the laptop's browser proxies the localhost callback to your SSH tunnel — assuming you've set up port forwarding for one of `8235-8240`).
+
+For headless CI: not yet supported. CI mode (`--ci` with a personal API key) is on the roadmap.
+
+## How to debug a failed install
+
+If the doctor check fails and the agent can't fix it after 3 retries, the wizard automatically files a ticket to smking support with:
+- Which checks failed (structured list)
+- Your environment (Node / PHP / framework versions)
+- Raw doctor output
+
+You'll see a ticket ID printed (`dr_xxxxxxxxxxxx`). smking support can look it up directly — no need to send a separate email with logs.
+
+## License
+
+MIT. See [LICENSE](../../LICENSE).