@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.

npx @soloworks/smking-wizard

Supported frameworks: Laravel (smking/laravel) and Next.js (@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. 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.