@viberaven/cli 0.1.0-beta.7 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. package/AGENTS.md +78 -88
  2. package/README.md +69 -82
  3. package/SECURITY.md +52 -36
  4. package/assets/report/station.js +8319 -0
  5. package/dist/cli.js +4535 -4569
  6. package/dist/cli.js.map +4 -4
  7. package/dist/report/station.js +8319 -0
  8. package/package.json +16 -7
  9. package/templates/AGENTS.snippet.md +43 -39
  10. package/templates/CLAUDE.snippet.md +16 -0
  11. package/templates/CURSOR.snippet.md +16 -0
package/AGENTS.md CHANGED
@@ -1,92 +1,82 @@
1
- # VibeRaven CLI — agent instructions
2
-
3
-
4
-
5
- Use this when the user asks whether their app is **production-ready**, **launch-ready**, what they are **missing before ship**, or how to improve **auth / database / payments / deployment** on an AI-built project.
6
-
7
-
8
-
9
- ## Humans (interactive menu)
10
-
11
-
12
-
13
- ```bash
14
-
15
- npx -y @viberaven/cli@beta
16
-
17
- # or: viberaven tui
18
-
19
- ```
20
-
21
-
22
-
23
- No subcommand needed — opens an interactive menu for scan, gaps, prompts, and sign-in.
24
-
25
-
26
-
27
- ## Run (agents — you run this, not the user)
28
-
29
-
30
-
31
- ```bash
32
-
33
- npx -y @viberaven/cli@beta scan
34
-
35
- ```
36
-
37
-
38
-
39
- If not signed in, `scan` starts VibeRaven sign-in, opens the browser approval page when possible, waits for the user to approve the editor/agent connection, then continues the scan.
40
-
41
- If the local agent environment cannot open a browser, show the printed `Open:` URL to the user. After approval, rerun `npx -y @viberaven/cli@beta scan`.
42
-
43
- Manual fallback if the scan flow cannot start login:
1
+ # VibeRaven CLI - Agent Instructions
2
+
3
+ Use VibeRaven when the user asks whether an app is production-ready, launch-ready, safe to deploy, or missing auth, database, payments, deployment, monitoring, security, provider setup, Vercel, or Supabase checks.
4
+
5
+ VibeRaven is the Agent Context + Production Gate.
6
+
7
+ ## Required Agent Loop
8
+
9
+ Run from the project root:
10
+
11
+ ```bash
12
+ npx -y @viberaven/cli --agent-mode
13
+ ```
14
+
15
+ Read in this order:
16
+
17
+ 1. `.viberaven/agent-tasklist.md` - the tasklist-first gate
18
+ 2. `.viberaven/gate-result.json` - the machine verdict
19
+ 3. `.viberaven/context-map.json` - compact context for the next agent step
20
+ 4. `.viberaven/agent-summary.md` - scan context
21
+ 5. `.viberaven/launch-playbook.md` - full launch checklist
22
+
23
+ Fix one repo-code gap at a time. Prefer:
24
+
25
+ ```bash
26
+ npx -y @viberaven/cli next --json
27
+ npx -y @viberaven/cli prompt --gap <id>
28
+ ```
29
+
30
+ After a fix:
31
+
32
+ ```bash
33
+ npx -y @viberaven/cli --verify
34
+ npx -y @viberaven/cli --strict
35
+ ```
36
+
37
+ For Vercel + Supabase checks:
44
38
 
45
39
  ```bash
46
- npx -y @viberaven/cli@beta login
40
+ npx -y @viberaven/cli audit --vercel-supabase
47
41
  ```
48
42
 
49
- Agents should use `scan` without `--open`; open the report only when the user wants the browser map.
50
-
51
-
52
-
53
- ## Read
54
-
55
-
56
-
57
- 1. `.viberaven/agent-summary.md` — short briefing and top gaps
58
-
59
- 2. `.viberaven/last-scan.json` — full mission map, providers, checks
60
-
61
- 3. `.viberaven/report.html` — visual map for the user (human menu or `--open`)
62
-
63
-
64
-
65
- ## Fix loop
66
-
67
-
68
-
69
- 1. `npx -y @viberaven/cli@beta prompt` — stdout = copy-ready prompt for the top gap
70
-
71
- Or: `viberaven prompt --gap <id>` / `--area database` / `--provider supabase`
72
-
73
- 2. Implement the change in the repo.
74
-
75
- 3. `npx -y @viberaven/cli@beta scan` — verify production core % and gap count improved.
76
-
77
- 4. Tell the user to review `.viberaven/report.html` for the provider map.
78
-
79
-
80
-
81
- ## Rules
82
-
83
-
84
-
85
- - Do not skip the scan — VibeRaven uses repo evidence plus managed analysis, not generic checklists.
86
-
87
- - Prefer fixing **critical** gaps first unless the user names an area.
88
-
89
- - Do not claim external dashboard setup is done unless checks pass or the user confirmed manually.
90
-
91
- - Do not claim human-provider actions as repo-code fixes. Human-provider actions include dashboard setup, billing/product configuration, DNS, webhooks, provider credentials, quota upgrades, and read-only MCP/provider-live verification.
92
-
43
+ ## Production Copilot Loop
44
+
45
+ After every scan, read `.viberaven/agent-tasklist.md` for the prioritized task list.
46
+
47
+ The loop is:
48
+
49
+ 1. Read `VIBERAVEN_NEXT_ACTION` from scan output for `batchSize`, `batchApplied`, `scanNow`, and `stalled`.
50
+ 2. If `stalled: true`, stop calling verify — address provider-action gaps or report to the user.
51
+ 3. If `scanNow: true`, call `viberaven_verify` (or run `--verify`) before applying more heals.
52
+ 4. For each repo-code task where `requiresUserAction: false` (up to `batchSize` per batch):
53
+ - Call MCP: `viberaven_heal_apply { gap: "<gapId>", yes: true }`
54
+ - Or run `--heal --apply --gap <id> --yes`
55
+ 5. After a full batch of heals, call verify once — do NOT verify after every single heal.
56
+ 6. Repeat until `gate.status === 'clear'` in `.viberaven/gate-result.json`.
57
+ 7. If `requiresUserAction: true`:
58
+ - Read `VIBERAVEN_PROVIDER_ACTION` from terminal output.
59
+ - Present `dashboardUrl` and `exactStep` to the user.
60
+ - Wait for user confirmation, then verify.
61
+ 8. If `fixType === 'upgrade-required'`, provide `upgradeUrl` and move on.
62
+
63
+ Do not stop at "scan complete." The loop is not done until `gate.status === 'clear'`.
64
+
65
+ ### Batch discipline
66
+
67
+ ```
68
+ for each repo-code task (up to batchSize):
69
+ viberaven_heal_apply { gap: "<gapId>", yes: true }
70
+
71
+ viberaven_verify ← once per batch, not per fix
72
+ ```
73
+
74
+ On Pro plans, `viberaven_provider_verify` is available as an MCP tool for read-only provider gap verification via Supabase/Vercel MCP evidence.
75
+
76
+ ## Rules
77
+
78
+ - Do not skip VibeRaven before deploy/build/cleanup when production readiness is in scope.
79
+ - Do not claim provider dashboard checks are fixed by repo-code edits.
80
+ - Provider dashboard checks, billing/product configuration, DNS, webhooks, credentials, quotas, and live provider verification must be completed or verified in the provider dashboard or through read-only provider evidence.
81
+ - If VibeRaven prints `LOGIN_URL_READY`, open that URL for the user. Say: "I opened VibeRaven sign-in so you can approve access; I will continue after approval."
82
+ - Do not ask for passwords, tokens, cookies, or secrets.
package/README.md CHANGED
@@ -1,93 +1,80 @@
1
- # @viberaven/cli
2
-
3
- Launch readiness for Claude Code, Codex, and other coding agents — same mission map and provider intelligence as VibeRaven Station.
4
-
5
- ## For humans
6
-
7
- ```bash
8
- npx -y @viberaven/cli@beta login
9
- npx -y @viberaven/cli@beta scan --open
10
- ```
11
-
12
- Sign in once, then scan with `--open` to view `.viberaven/report.html` in the browser (same editorial Mission Map skin as the extension). Or run **`viberaven`** with no args for the interactive terminal menu.
13
-
14
- Uses the **same VibeRaven account and scan quota** as the VS Code extension. **Does not use your `OPENAI_API_KEY`** — scans go through the managed API after login. See [SECURITY.md](./SECURITY.md).
15
-
16
- ## For coding agents
17
-
18
- Use VibeRaven when the user asks whether an AI-built app is launch-ready, production-ready, or missing auth/database/payments/deployment/security work.
19
-
20
- ```bash
21
- npx -y @viberaven/cli@beta scan
1
+ # @viberaven/cli
2
+
3
+ VibeRaven is the Agent Context + Production Gate for AI-built apps. It gives Claude Code, Codex, Cursor, and other coding agents a production-readiness loop before Vercel/Supabase deployment.
4
+
5
+ ## Humans
6
+
7
+ ```bash
8
+ npx -y @viberaven/cli
22
9
  ```
23
10
 
24
- If login is missing, `scan` starts VibeRaven sign-in, opens the browser approval page when possible, waits for the user to approve the connection, then continues the scan.
11
+ No subcommand is needed in a real terminal. It opens the interactive menu for sign-in, scan, report, provider guides, dashboards, prompts, and sign-out.
12
+
13
+ ## Coding Agents
14
+
15
+ Agents should run:
16
+
17
+ ```bash
18
+ npx -y @viberaven/cli --agent-mode
19
+ ```
20
+
21
+ Then read artifacts in this order:
22
+
23
+ 1. `.viberaven/agent-tasklist.md`
24
+ 2. `.viberaven/gate-result.json`
25
+ 3. `.viberaven/context-map.json`
26
+ 4. `.viberaven/agent-summary.md`
27
+ 5. `.viberaven/launch-playbook.md`
28
+
29
+ Fix one repo-code gap, then run:
30
+
31
+ ```bash
32
+ npx -y @viberaven/cli --verify
33
+ npx -y @viberaven/cli --strict
34
+ ```
25
35
 
26
- If the local agent environment cannot open a browser, show the printed `Open:` URL to the user. After they approve it, rerun:
36
+ For focused work:
27
37
 
28
38
  ```bash
29
- npx -y @viberaven/cli@beta scan
39
+ npx -y @viberaven/cli next --json
40
+ npx -y @viberaven/cli prompt --gap <id>
41
+ npx -y @viberaven/cli audit --vercel-supabase
30
42
  ```
31
43
 
32
- Manual fallback:
44
+ Provider dashboard checks are not cleared by repo-code edits. Billing/product configuration, DNS, webhooks, credentials, quotas, and live provider verification must be completed or verified in the provider dashboard or through read-only provider evidence.
45
+
46
+ ## Production Copilot Loop
47
+
48
+ VibeRaven runs a batch-disciplined loop until the production gate clears. Do not stop at "scan complete."
49
+
50
+ 1. **Scan** — Run `--agent-mode`. Read `.viberaven/agent-tasklist.md` and parse `VIBERAVEN_NEXT_ACTION` from stdout for `batchSize`, `batchApplied`, `scanNow`, and `stalled`.
51
+ 2. **Batch heals** — For each repo-code task where `requiresUserAction: false`, apply up to `batchSize` heals per batch (free=3, pro=10) via `viberaven_heal_apply { gap: "<gapId>", yes: true }` or `--heal --apply --gap <id> --yes`. When `scanNow: true`, verify before applying more heals.
52
+ 3. **Verify and clear** — Run `--verify` once per batch (not after every heal). Repeat until `gate.status === 'clear'` in `.viberaven/gate-result.json`. For provider gaps, read `VIBERAVEN_PROVIDER_ACTION`, complete the dashboard step, then verify.
53
+
54
+ If `stalled: true`, stop calling verify and address provider-action gaps or report to the user. Run `--strict` before deploy or CI pass.
55
+
56
+ ## Machine Output
33
57
 
34
58
  ```bash
35
- npx -y @viberaven/cli@beta login
59
+ npx -y @viberaven/cli --agent-mode --json
60
+ npx -y @viberaven/cli --agent-mode --jsonl
61
+ npx -y @viberaven/cli --strict --json
36
62
  ```
37
63
 
38
- Read `.viberaven/agent-summary.md` and `.viberaven/launch-playbook.md`. Loop:
39
-
40
- 1. `viberaven next --json`
41
- 2. Repo fix → `viberaven prompt --gap <id>` → implement → `viberaven report` (free) or `scan`
42
- 3. Provider → `viberaven guide <provider>` and `viberaven open <provider>`
43
- 4. Repeat until done; check `viberaven status --json` before each new scan
44
-
45
- Do not claim dashboard, billing, DNS, webhook, MCP, or provider-live actions as repo-code fixes. Tell the user when `.viberaven/report.html` has manual provider actions to review.
46
-
47
- See [AGENTS.md](./AGENTS.md). Paste [templates/AGENTS.snippet.md](./templates/AGENTS.snippet.md) into your repo's `AGENTS.md`.
48
-
49
- ## Artifacts
50
-
51
- | File | Purpose |
52
- |------|---------|
53
- | `.viberaven/last-scan.json` | Full scan payload |
54
- | `.viberaven/agent-summary.md` | Short briefing + next action for agents |
55
- | `.viberaven/launch-playbook.md` | Ordered launch checklist |
56
- | `.viberaven/report.html` | Visual mission map + `report/station.css` (extension editorial UI) |
57
-
58
- ## Switch providers (matches the extension map)
59
-
60
- The report shows a provider switch per production area (database, auth, payments, deployment, monitoring, security). Picking one copies a command:
61
-
62
- ```bash
63
- viberaven stack set database neon && viberaven scan --open
64
- ```
65
-
66
- You can also set it directly:
67
-
68
- ```bash
69
- viberaven stack set auth clerk # persists to .viberaven/stack.json
70
- viberaven stack list
71
- viberaven stack clear # remove all overrides
72
- ```
73
-
74
- The next `scan` re-maps that area using your chosen provider.
75
-
76
- ## Development
77
-
78
- From repo root:
79
-
80
- ```bash
81
- npm run cli:build
82
- npm run cli:test
83
- node packages/cli/dist/cli.js scan
84
- ```
85
-
86
- Inside `packages/cli`:
87
-
88
- ```bash
89
- npm run typecheck # tsc against the shared station engine
90
- npm run demo-report # render a sample report.html and open it
91
- ```
92
-
93
- The report reuses the Station Mission Map visual language (`src/report/reportStyles.ts`) for parity with the extension.
64
+ Machine artifact contract:
65
+
66
+ ```text
67
+ docs/contracts/artifacts.md
68
+ https://viberaven.dev/schemas/gate-result.schema.json
69
+ https://viberaven.dev/schemas/context-map.schema.json
70
+ https://viberaven.dev/schemas/gap.schema.json
71
+ https://viberaven.dev/schemas/heal-result.schema.json
72
+ ```
73
+
74
+ ## Development
75
+
76
+ ```bash
77
+ npm run cli:build
78
+ npm run cli:test
79
+ node packages/cli/dist/cli.js scan
80
+ ```
package/SECURITY.md CHANGED
@@ -1,36 +1,52 @@
1
- # Security — `@viberaven/cli`
2
-
3
- ## Your OpenAI key stays on your machine (extension only)
4
-
5
- The **npm CLI does not read `OPENAI_API_KEY`** and does not accept a bring-your-own-key scan path. Scans use the **VibeRaven managed API** after device login (`viberaven login`), same as the signed-in VS Code extension.
6
-
7
- - API keys for model calls live on the **server**, not in the published npm package.
8
- - Local credentials store only a **VibeRaven access token** in `%APPDATA%\viberaven\credentials.json` (or `~/.config/viberaven/`).
9
- - Never commit `credentials.json` or paste tokens into chat.
10
-
11
- ## What gets written to your repo
12
-
13
- After `viberaven scan`, the CLI may create:
14
-
15
- | Path | Contents |
16
- |------|----------|
17
- | `.viberaven/last-scan.json` | Mission map + gaps (secrets redacted before write) |
18
- | `.viberaven/agent-summary.md` | Agent briefing |
19
- | `.viberaven/report.html` | Local HTML report + `report/station.css` |
20
-
21
- Repo scanners already redact common key patterns in evidence strings; the CLI runs an extra redaction pass before writing files.
22
-
23
- ## Safe `npx` usage
24
-
25
- ```bash
26
- npx -y @viberaven/cli@beta login
27
- npx -y @viberaven/cli@beta scan
28
- ```
29
-
30
- - Use official package name `@viberaven/cli` from npm.
31
- - Do not set `OPENAI_API_KEY` for CLI scans — it is ignored by design.
32
- - Add `.viberaven/` to `.gitignore` if you do not want scan output in git (optional; files should not contain raw keys after redaction).
33
-
34
- ## Reporting issues
35
-
36
- If you believe a scan artifact leaked a secret, rotate the key immediately and open an issue at https://github.com/ohad6k/VibeRaven/issues with the redacted file path only (not the secret).
1
+ # Security - `@viberaven/cli`
2
+
3
+ ## Managed Scan Boundary
4
+
5
+ The npm CLI does not read `OPENAI_API_KEY` and does not accept a bring-your-own-key scan path. Scans use the VibeRaven managed API after device login, same as the signed-in VS Code extension.
6
+
7
+ - API keys for model calls live on the server, not in the published npm package.
8
+ - Local credentials store only a VibeRaven access token in `%APPDATA%\viberaven\credentials.json` or `~/.config/viberaven/`.
9
+ - Never commit `credentials.json` or paste tokens into chat.
10
+
11
+ ## Safe Commands
12
+
13
+ Human terminal:
14
+
15
+ ```bash
16
+ npx -y @viberaven/cli
17
+ ```
18
+
19
+ Agent or CI gate:
20
+
21
+ ```bash
22
+ npx -y @viberaven/cli --agent-mode
23
+ npx -y @viberaven/cli --verify
24
+ npx -y @viberaven/cli --strict
25
+ ```
26
+
27
+ VibeRaven is the Agent Context + Production Gate. Agents should read `.viberaven/agent-tasklist.md`, `.viberaven/gate-result.json`, and `.viberaven/context-map.json` before claiming an app is safe to deploy.
28
+
29
+ ## Written Artifacts
30
+
31
+ After a scan, the CLI may create:
32
+
33
+ | Path | Contents |
34
+ |------|----------|
35
+ | `.viberaven/last-scan.json` | Full scan payload |
36
+ | `.viberaven/agent-tasklist.md` | Agent tasklist |
37
+ | `.viberaven/gate-result.json` | Machine gate verdict |
38
+ | `.viberaven/context-map.json` | Compact agent context |
39
+ | `.viberaven/gaps/<gapId>.json` | Per-gap evidence |
40
+ | `.viberaven/agent-summary.md` | Human/agent summary |
41
+ | `.viberaven/launch-playbook.md` | Launch checklist |
42
+ | `.viberaven/report.html` | Local HTML report |
43
+
44
+ Repo scanners redact common key patterns in evidence strings; the CLI runs an extra redaction pass before writing files.
45
+
46
+ ## Provider Boundaries
47
+
48
+ Provider dashboard checks are not cleared by repo-code edits. Billing/product configuration, DNS, webhooks, credentials, quotas, and live provider verification must be completed or verified in the provider dashboard or through read-only provider evidence.
49
+
50
+ ## Reporting Issues
51
+
52
+ If you believe a scan artifact leaked a secret, rotate the key immediately and open an issue at https://github.com/ohad6k/VibeRaven/issues with the redacted file path only.