@viberaven/cli 0.1.0-beta.7 → 1.0.0

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 +43 -86
  2. package/README.md +59 -82
  3. package/SECURITY.md +52 -36
  4. package/assets/report/station.js +8319 -0
  5. package/dist/cli.js +4003 -4574
  6. package/dist/cli.js.map +4 -4
  7. package/dist/report/station.js +8319 -0
  8. package/package.json +6 -6
  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,49 @@
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.
1
+ # VibeRaven CLI - Agent Instructions
40
2
 
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`.
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.
42
4
 
43
- Manual fallback if the scan flow cannot start login:
5
+ VibeRaven is the Agent Context + Production Gate.
6
+
7
+ ## Required Agent Loop
8
+
9
+ Run from the project root:
44
10
 
45
11
  ```bash
46
- npx -y @viberaven/cli@beta login
12
+ npx -y @viberaven/cli --agent-mode
47
13
  ```
48
14
 
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
-
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:
38
+
39
+ ```bash
40
+ npx -y @viberaven/cli audit --vercel-supabase
41
+ ```
42
+
43
+ ## Rules
44
+
45
+ - Do not skip VibeRaven before deploy/build/cleanup when production readiness is in scope.
46
+ - Do not claim provider dashboard checks are fixed by repo-code edits.
47
+ - 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.
48
+ - 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."
49
+ - Do not ask for passwords, tokens, cookies, or secrets.
package/README.md CHANGED
@@ -1,93 +1,70 @@
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`
25
28
 
26
- If the local agent environment cannot open a browser, show the printed `Open:` URL to the user. After they approve it, rerun:
29
+ Fix one repo-code gap, then run:
27
30
 
28
31
  ```bash
29
- npx -y @viberaven/cli@beta scan
32
+ npx -y @viberaven/cli --verify
33
+ npx -y @viberaven/cli --strict
30
34
  ```
31
35
 
32
- Manual fallback:
36
+ For focused work:
33
37
 
34
38
  ```bash
35
- npx -y @viberaven/cli@beta login
39
+ npx -y @viberaven/cli next --json
40
+ npx -y @viberaven/cli prompt --gap <id>
41
+ npx -y @viberaven/cli audit --vercel-supabase
36
42
  ```
37
43
 
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.
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
+ ## Machine Output
47
+
48
+ ```bash
49
+ npx -y @viberaven/cli --agent-mode --json
50
+ npx -y @viberaven/cli --agent-mode --jsonl
51
+ npx -y @viberaven/cli --strict --json
52
+ ```
53
+
54
+ Machine artifact contract:
55
+
56
+ ```text
57
+ docs/contracts/artifacts.md
58
+ https://viberaven.dev/schemas/gate-result.schema.json
59
+ https://viberaven.dev/schemas/context-map.schema.json
60
+ https://viberaven.dev/schemas/gap.schema.json
61
+ https://viberaven.dev/schemas/heal-result.schema.json
62
+ ```
63
+
64
+ ## Development
65
+
66
+ ```bash
67
+ npm run cli:build
68
+ npm run cli:test
69
+ node packages/cli/dist/cli.js scan
70
+ ```
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.