@securityreviewai/vibereview-cli 0.1.6 → 0.1.8

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 (7) hide show
  1. package/README.md +321 -106
  2. package/SECURITY.md +8 -4
  3. package/dist/src/core/integration.js +1 -1
  4. package/dist/src/providers/claude.js +30 -2
  5. package/dist/src/runners/claude.js +1 -1
  6. package/docs/provider-contracts.md +5 -3
  7. package/package.json +9 -1
package/README.md CHANGED
@@ -1,194 +1,409 @@
1
1
  # VibeReview CLI
2
2
 
3
- Local-first security guardrails for AI coding agents. VibeReview detects a repository's technology stack, selects relevant rules from its bundled catalog, and uses the developer's chosen coding-agent CLI to derive a small set of repository-specific guardrails.
4
-
5
- ## Current status
6
-
7
- Milestone 3 is implemented across Cursor, Codex, Claude Code, and GitHub Copilot:
8
-
9
- - interactive provider selection;
10
- - provider-specific installation and authentication preflight;
11
- - deterministic, token-free technology detection;
12
- - 77 compact guardrail packs bundled as one compressed runtime asset;
13
- - deterministic pack matching and guardrail deduplication;
14
- - bundled `guardrail-generator` skill with a strict, versioned output contract;
15
- - bounded collection of security-relevant source evidence;
16
- - optional, explicitly confirmed code-specific guardrail generation;
17
- - explicit `vibereview guardrails generate` regeneration; and
18
- - atomic workspace updates that preserve custom guardrails;
19
- - native workspace instructions, project skills, and session hooks for every provider;
20
- - prompt-time local guardrail selection and PWNISMS threat modelling;
21
- - direct OSV.dev checks for every added or version-changed dependency;
22
- - secure-by-default implementation guidance and verification; and
23
- - one human-readable Markdown security report per IDE chat.
24
-
25
- No server, VibeReview account, MCP server, artifact upload, or report synchronization is required.
3
+ Local-first security guardrails for AI coding agents.
4
+
5
+ VibeReview profiles your repository, installs security guidance matched to its technology stack, and gives your coding agent a repeatable workflow for threat modelling, secure-by-default implementation, dependency checks, and per-chat security reports.
6
+
7
+ It works with Cursor, Codex, Claude Code, and GitHub Copilot. There is no VibeReview server or account, and VibeReview never receives your source code or synchronizes your reports. Optional code-specific generation goes directly through your chosen provider CLI.
8
+
9
+ ## Why VibeReview?
10
+
11
+ AI coding agents can move quickly, but security expectations are often implicit, inconsistent, or introduced too late. VibeReview places project-aware security context directly in the repository so the agent can use it while designing and implementing a feature.
12
+
13
+ - **Local-first:** stack detection, catalog matching, workspace configuration, and reports stay on your machine.
14
+ - **Useful immediately:** deterministic baseline guardrails require no model call and consume no provider tokens.
15
+ - **Project-aware:** optional code-specific guardrails are derived from a bounded set of security-relevant files.
16
+ - **Agent-native:** instructions, skills, and session hooks are installed using each supported provider's project conventions.
17
+ - **Secure dependency changes:** added or changed dependency versions are checked directly with OSV.dev.
18
+ - **Auditable:** each IDE chat gets one readable Markdown report that is updated as the feature evolves.
19
+ - **No catalog clutter:** the complete guardrail catalog remains in the npm package instead of being copied into your repository.
20
+
21
+ ## How it works
22
+
23
+ ```text
24
+ npx @securityreviewai/vibereview-cli init
25
+ │
26
+ ├─ Select your coding agent
27
+ ├─ Detect the technology stack locally
28
+ ├─ Match bundled guardrail packs without an AI call
29
+ ├─ Install baseline guardrails and the local agent workflow
30
+ └─ Optionally generate code-specific guardrails with your provider CLI
31
+
32
+ Security-relevant prompt
33
+ │
34
+ ├─ Select applicable project guardrails
35
+ ├─ Threat-model the requested change
36
+ ├─ Check changed dependencies with OSV.dev
37
+ ├─ Implement and verify secure-by-default code
38
+ └─ Create or update one Markdown report for that IDE chat
39
+ ```
40
+
41
+ Baseline setup is deterministic and token-free. Code-specific generation is optional, clearly confirmed before it runs, and billed under your existing provider account.
26
42
 
27
43
  ## Requirements
28
44
 
29
45
  - Node.js 20.12 or newer
30
- - Git, recommended but not required
31
- - at least one supported coding CLI: Cursor, Codex, Claude Code, or GitHub Copilot
46
+ - npm or another way to run npm packages
47
+ - A project directory; a Git repository is recommended but not required
48
+ - The CLI for the coding agent you select
32
49
 
33
- Useful provider checks:
50
+ VibeReview does **not** install Cursor, Codex, Claude Code, or GitHub Copilot for you. Install and authenticate the provider CLI using its official documentation first, or let VibeReview start its interactive login flow when code-specific generation requires authentication.
34
51
 
35
- ```bash
36
- cursor-agent --version
37
- cursor-agent status
52
+ | Coding agent | Provider ID | Executable | Version check | Authentication/login |
53
+ |---|---|---|---|---|
54
+ | [Cursor](https://docs.cursor.com/en/cli) | `cursor` | `cursor-agent` | `cursor-agent --version` | `cursor-agent login` |
55
+ | [OpenAI Codex](https://developers.openai.com/codex/) | `codex` | `codex` | `codex --version` | `codex login` |
56
+ | [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) | `claude` | `claude` | `claude --version` | `claude auth login` |
57
+ | [GitHub Copilot CLI](https://docs.github.com/en/copilot/concepts/agents/about-copilot-cli) | `copilot` | `copilot` | `copilot version` | `copilot login --web-flow` |
38
58
 
39
- codex --version
40
- codex login status
59
+ Copilot does not provide a documented non-interactive authentication-status command equivalent to the other providers. VibeReview uses available token or GitHub CLI signals and otherwise lets the first Copilot agent request perform the definitive check.
41
60
 
42
- claude --version
43
- claude auth status
61
+ ### Claude Code with Requesty
62
+
63
+ VibeReview supports Claude Code routed through Requesty without requiring first-party Anthropic OAuth. Export the Requesty gateway URL, your Requesty API key, and the model before running VibeReview:
64
+
65
+ ```bash
66
+ export ANTHROPIC_BASE_URL="https://router.requesty.ai"
67
+ export ANTHROPIC_AUTH_TOKEN="<your-requesty-api-key>"
68
+ export ANTHROPIC_MODEL="anthropic/claude-sonnet-4-5"
44
69
 
45
- copilot version
70
+ npx @securityreviewai/vibereview-cli@0.1.8 init --provider claude
46
71
  ```
47
72
 
48
- Copilot has no documented non-interactive authentication-status command. VibeReview detects configured token environment variables or GitHub CLI authentication when available; otherwise it defers the definitive authentication check until the first Copilot agent run.
73
+ VibeReview requires both a valid `ANTHROPIC_BASE_URL` and a non-empty `ANTHROPIC_AUTH_TOKEN` (or `ANTHROPIC_API_KEY`) in its inherited environment. It recognizes the configuration without reading or printing the key and skips `claude auth status` and `claude auth login`. Claude Code then inherits the same variables for code-specific guardrail generation.
49
74
 
50
- The exact preflight contract and primary documentation links are maintained in [docs/provider-contracts.md](docs/provider-contracts.md).
75
+ If Requesty is configured only inside `~/.claude/settings.json`, export the variables in the terminal that launches VibeReview as shown above so preflight can recognize them. Choose a model or Requesty policy supported by your account; the example model can be replaced through `ANTHROPIC_MODEL`.
51
76
 
52
- ## Install and initialize
77
+ ## Quick start
53
78
 
54
- Run the CLI without a global installation:
79
+ From the root of the project you want to protect:
55
80
 
56
81
  ```bash
57
82
  npx @securityreviewai/vibereview-cli init
58
83
  ```
59
84
 
60
- Or install it globally and use the shorter executable name:
85
+ VibeReview will ask which coding agent you use, analyze the repository, install matched baseline guardrails, and configure that agent's local security workflow. It will then explain code-specific guardrails and ask whether you want to generate them.
61
86
 
62
- ```bash
63
- npm install --global @securityreviewai/vibereview-cli
64
- vibereview init
65
- ```
87
+ After initialization, restart an already-running IDE agent so it reloads the new project instructions, skills, and hooks.
88
+
89
+ VibeReview's documented interface is the scoped `npx` command. It requires no global installation and avoids depending on npm's global binary directory being configured on your `PATH`.
90
+
91
+ ## Commands
66
92
 
67
- ## Development usage
93
+ ### `npx @securityreviewai/vibereview-cli init`
94
+
95
+ Detect the stack, select baseline guardrails, and install the security workflow for a coding agent.
68
96
 
69
97
  ```bash
70
- npm install
71
- npm run build
72
- node bin/vibereview.js init
98
+ npx @securityreviewai/vibereview-cli init
73
99
  ```
74
100
 
75
- Non-interactive usage:
101
+ Common examples:
76
102
 
77
103
  ```bash
78
- node bin/vibereview.js init --provider codex --yes
104
+ # Select the provider interactively
105
+ npx @securityreviewai/vibereview-cli init
106
+
107
+ # Non-interactive baseline-only setup
108
+ npx @securityreviewai/vibereview-cli init --provider codex --yes
109
+
110
+ # Non-interactive setup including token-consuming code-specific generation
111
+ npx @securityreviewai/vibereview-cli init --provider claude --yes --generate
112
+
113
+ # Explicitly skip the optional generation prompt
114
+ npx @securityreviewai/vibereview-cli init --provider cursor --skip-generation
115
+
116
+ # Initialize a different project directory
117
+ npx @securityreviewai/vibereview-cli init --cwd /path/to/project
118
+
119
+ # Re-detect the stack and refresh VibeReview-managed files
120
+ npx @securityreviewai/vibereview-cli init --provider copilot --force
121
+
122
+ # Return a machine-readable result
123
+ npx @securityreviewai/vibereview-cli init --provider codex --yes --json
79
124
  ```
80
125
 
81
- Accepted provider IDs are `cursor`, `codex`, `claude`, and `copilot`.
126
+ | Option | Meaning |
127
+ |---|---|
128
+ | `--provider <name>` | Use `cursor`, `codex`, `claude`, or `copilot` instead of prompting. |
129
+ | `--yes`, `-y` | Accept non-interactive defaults. Requires `--provider`; baseline setup remains token-free unless `--generate` is also present. |
130
+ | `--generate` | Generate code-specific guardrails during initialization. This invokes the selected provider and consumes provider tokens. |
131
+ | `--skip-generation` | Install only deterministic baseline guardrails and skip the optional generation prompt. |
132
+ | `--force` | Refresh managed files while preserving existing custom and code-specific guardrails. |
133
+ | `--cwd <path>` | Operate on a project other than the current directory. |
134
+ | `--json` | Print machine-readable JSON instead of the normal terminal summary. |
135
+ | `--verbose` | Show matched packs, detection warnings, and additional generation details. |
82
136
 
83
- Initialization deterministically installs baseline rules first. In an interactive terminal it then explains code-specific guardrails, discloses that the selected provider agent will consume tokens, and asks for confirmation. Declining leaves the baseline workflow fully active. If the user accepts and authentication is missing, VibeReview launches the provider's browser-capable login flow before generation.
137
+ Running `init` again without `--force` stops rather than overwriting an initialized workspace.
84
138
 
85
- To generate or regenerate code-specific rules later, with the same confirmation:
139
+ ### `npx @securityreviewai/vibereview-cli guardrails generate`
140
+
141
+ Generate or regenerate repository-specific guardrails using the provider saved during initialization.
86
142
 
87
143
  ```bash
88
144
  npx @securityreviewai/vibereview-cli guardrails generate
89
145
  ```
90
146
 
91
- For explicitly authorized non-interactive use, pass `--yes`. Non-interactive initialization skips code-specific generation unless `--generate` is also supplied.
147
+ The command explains the token cost and asks for confirmation. A successful run atomically replaces only the `code_specific` section; baseline and custom guardrails are preserved.
148
+
149
+ ```bash
150
+ # Confirm non-interactively
151
+ npx @securityreviewai/vibereview-cli guardrails generate --yes
92
152
 
93
- Initialization also installs the local security workflow for the selected provider. Restart an already-running IDE agent after initialization so it reloads workspace instructions, skills, and hooks.
153
+ # Generate for another initialized project
154
+ npx @securityreviewai/vibereview-cli guardrails generate --cwd /path/to/project
94
155
 
95
- Additional options:
156
+ # Include evidence-bundle statistics
157
+ npx @securityreviewai/vibereview-cli guardrails generate --verbose
96
158
 
97
- ```text
98
- --force Refresh managed files while preserving custom rules
99
- --json Print machine-readable output
100
- --verbose Print detailed detection evidence and warnings
101
- --cwd <path> Initialize another workspace
159
+ # Return a machine-readable result
160
+ npx @securityreviewai/vibereview-cli guardrails generate --yes --json
102
161
  ```
103
162
 
104
- ## Workspace output
163
+ Regenerate after meaningful changes to security boundaries, authentication, authorization, external integrations, data access, secrets, infrastructure, or other sensitive parts of the codebase. You do not need to regenerate for every small edit.
164
+
165
+ ### General commands
166
+
167
+ ```bash
168
+ npx @securityreviewai/vibereview-cli --help
169
+ npx @securityreviewai/vibereview-cli --version
170
+ ```
105
171
 
106
- VibeReview creates:
172
+ ## What initialization creates
173
+
174
+ The provider-independent workspace state lives under `.vibereview/`:
107
175
 
108
176
  ```text
109
177
  .vibereview/
110
- ├── config.json
111
- ├── profile.json
112
- ├── guardrails.yml
113
- ├── guardrails.md
114
- ├── state.json
115
- ├── gates/
178
+ ├── config.json # Selected provider and project configuration
179
+ ├── profile.json # Deterministically detected technology profile
180
+ ├── guardrails.yml # Canonical baseline, generated, and custom rules
181
+ ├── guardrails.md # Generated human-readable guardrail tables
182
+ ├── state.json # Catalog/profile state used for safe refreshes
183
+ ├── gates/ # Reserved local workflow state
184
+ ├── hooks/
185
+ │ └── context.cjs # Local session-context hook runtime
116
186
  └── reports/
187
+ └── <session-id>.md
117
188
  ```
118
189
 
119
- The full catalog and generator skill remain inside the installed npm package. They are not copied into the target workspace. `guardrails.yml` is the canonical machine-readable source containing matched baseline, generated code-specific, and user-maintained custom rules. `guardrails.md` is an automatically regenerated, table-formatted view for humans; do not edit it directly.
190
+ `guardrails.yml` is the canonical file read by the agent workflow. `guardrails.md` is a generated view intended for people; do not edit it directly.
120
191
 
121
- ## Code-specific generation
192
+ VibeReview also installs provider-native project files:
122
193
 
123
- VibeReview selects at most 30 security-relevant source files, capped at 80 KB in total and 24 KB per file. It excludes common dependency/build directories, provider configuration directories, `.env` files, credential-like paths, private keys, lockfiles, binary files, and symbolic links. The selected contents are sent through the configured provider CLI under that provider's own account and data-handling terms.
194
+ | Provider | Always-on instructions | Project skills | Hook configuration |
195
+ |---|---|---|---|
196
+ | Cursor | `.cursor/rules/vibereview-security.mdc` | `.cursor/skills/vibereview-*` | `.cursor/hooks.json` |
197
+ | Codex | Managed block in `AGENTS.md` | `.codex/skills/vibereview-*` | `.codex/hooks.json` |
198
+ | Claude Code | Managed block in `.claude/CLAUDE.md` | `.claude/skills/vibereview-*` | `.claude/settings.json` |
199
+ | GitHub Copilot | Managed block in `.github/copilot-instructions.md` | `.github/skills/vibereview-*` | `.github/hooks/vibereview.json` |
124
200
 
125
- The provider runs in a temporary empty directory rather than the repository. Cursor uses read-only ask mode and sandboxing; Codex uses an ephemeral read-only execution; Claude Code runs in plan mode with tools disabled and no persisted session; Copilot runs non-interactively with only its read tool exposed to the empty directory. The model receives the bounded evidence inline and cannot edit the repository through this job.
201
+ Existing instruction text and unrelated hook entries are preserved. Files dedicated to VibeReview are refreshed only when they carry VibeReview ownership markers, preventing accidental replacement of user-owned files.
126
202
 
127
- Generated output must pass the bundled JSON schema. Every rule needs an exact evidence path from the supplied bundle, generic or baseline-duplicate rules are removed, and invalid output gets one repair attempt. A successful regeneration atomically replaces only `code_specific`; baseline and custom rules remain intact.
203
+ For a team-wide setup, commit the guardrails and provider integration files that should apply to every contributor. Decide separately whether `.vibereview/reports/` belongs in version control: reports can contain useful security context, but they may also describe sensitive boundaries and residual risks.
128
204
 
129
- ## Prompt-time security workflow
205
+ ## Guardrail types
130
206
 
131
- For a security-relevant prompt, the configured coding agent performs this local sequence:
207
+ VibeReview combines three sources into one active guardrail file:
132
208
 
133
- 1. shortlist applicable rules from `.vibereview/guardrails.yml`;
134
- 2. run a focused PWNISMS threat model before implementation;
135
- 3. when dependencies change, scan exact proposed versions with OSV.dev and re-scan any selected fix;
136
- 4. implement secure-by-default code using the threats, guardrails, and dependency decision;
137
- 5. run proportionate verification; and
138
- 6. write or update the chat's Markdown report.
209
+ | Source | How it is created | Update behavior |
210
+ |---|---|---|
211
+ | `baseline` | Deterministically selected from bundled technology packs | Refreshed by `init --force` |
212
+ | `code_specific` | Optionally generated from bounded repository evidence | Replaced by `guardrails generate` |
213
+ | `custom` | Written and maintained by your team | Preserved by refresh and regeneration |
139
214
 
140
- The bundled skills are installed into the selected provider's project skill directory. Always-on workspace instructions route security-relevant prompts through them; hooks supply session/startup context where the provider supports it.
215
+ ### Adding custom guardrails
141
216
 
142
- | Provider | Always-on instructions | Project skills | Hook configuration |
143
- |---|---|---|---|
144
- | Cursor | `.cursor/rules/vibereview-security.mdc` | `.cursor/skills/vibereview-*` | `.cursor/hooks.json` |
145
- | Codex | `AGENTS.md` managed block | `.codex/skills/vibereview-*` | `.codex/hooks.json` |
146
- | Claude Code | `.claude/CLAUDE.md` managed block | `.claude/skills/vibereview-*` | `.claude/settings.json` |
147
- | GitHub Copilot | `.github/copilot-instructions.md` managed block | `.github/skills/vibereview-*` | `.github/hooks/vibereview.json` |
217
+ Add project policies to the `custom` list in `.vibereview/guardrails.yml`:
218
+
219
+ ```yaml
220
+ custom:
221
+ - id: custom-admin-authorization
222
+ source: custom
223
+ type: must
224
+ category: authorization
225
+ title: Enforce server-side authorization for admin actions
226
+ instruction: Every admin action must verify the authenticated user's admin role on the server.
227
+ rationale: Client-side route protection is not an authorization boundary.
228
+ cwe_ids:
229
+ - CWE-862
230
+ owasp_top10:
231
+ - A01:2021
232
+ ```
233
+
234
+ Use a stable, unique `id`; set `source` to `custom`; and use `must` or `must_not` for `type`. Custom edits are active immediately because the agent reads `guardrails.yml`. The human-readable `guardrails.md` view is rebuilt the next time you run `init --force` or successfully regenerate code-specific guardrails.
235
+
236
+ ## Code-specific guardrails and privacy
237
+
238
+ Code-specific generation is opt-in. Before it runs, VibeReview tells you that it will invoke the selected provider CLI and consume tokens from your configured provider account.
239
+
240
+ VibeReview selects at most 30 security-relevant files, capped at 80 KB in total and 24 KB per file. It excludes common dependency and build directories, provider configuration directories, `.env` files, credential-like paths, private keys, lockfiles, binary files, and symbolic links.
241
+
242
+ The bounded evidence is sent directly through your selected provider CLI under that provider's billing, retention, and privacy terms. When an LLM gateway such as Requesty is configured, its routing, billing, retention, and privacy terms also apply. VibeReview has no intermediary server.
243
+
244
+ The provider job runs from a temporary empty directory with provider-appropriate restrictions:
245
+
246
+ - Cursor uses sandboxed, read-only ask mode.
247
+ - Codex uses an ephemeral, read-only execution and ignores user configuration.
248
+ - Claude Code runs in plan mode with tools disabled, an empty MCP configuration, and no session persistence.
249
+ - GitHub Copilot runs non-interactively with only its read capability exposed to the empty working directory.
250
+
251
+ Generated output must pass VibeReview's schema and cite exact evidence paths. Generic rules, duplicates, unsupported fields, and invalid evidence references are rejected. VibeReview makes one repair attempt when a provider responds successfully with invalid structured output.
252
+
253
+ If generation fails, the deterministic baseline guardrails remain installed and active.
254
+
255
+ ## Security workflow during coding
256
+
257
+ For a security-relevant request, the installed instructions guide the coding agent through this sequence:
258
+
259
+ 1. Read the project profile and shortlist applicable baseline, code-specific, and custom guardrails.
260
+ 2. Perform a focused PWNISMS threat model for the requested feature or change.
261
+ 3. Query OSV.dev when a dependency is added or its version changes, and re-check any proposed remediation version.
262
+ 4. Implement secure-by-default code using the applicable guardrails and identified threats.
263
+ 5. Run checks proportionate to the change.
264
+ 6. Create or update the current IDE chat's Markdown security report.
148
265
 
149
- Existing instruction content and unrelated hooks are preserved. Dedicated VibeReview files are overwritten only when they already contain VibeReview ownership markers.
266
+ PWNISMS covers product, workload, network, identity and access management, secrets, monitoring, and supply-chain risks. The analysis is scoped to the requested work; it is not a claim that every risk in the repository has been audited.
150
267
 
151
- ## Markdown session reports
268
+ For OSV.dev checks, only the package ecosystem, canonical package name, and exact version are sent directly to `https://api.osv.dev/v1/query`. Source code, prompts, repository names, secrets, and lockfiles are not sent to OSV.dev.
152
269
 
153
- Reports live at:
270
+ ## Session reports
271
+
272
+ Reports are written locally to:
154
273
 
155
274
  ```text
156
275
  .vibereview/reports/<chat-session-id>.md
157
276
  ```
158
277
 
159
- The IDE agent writes the report directly; the CLI does not generate a JSON scan. The session ID is the complete file identity, so feature title changes cannot create another report accidentally. A new IDE chat creates one Markdown file. Every security-relevant follow-up reads and rewrites that same file. The agent may add, revise, reorder, or remove content so the report describes the latest cumulative state rather than preserving a chronological log.
278
+ VibeReview uses one report per IDE chat, not one report per prompt:
279
+
280
+ - the first security-relevant request in a new chat creates a report;
281
+ - follow-up work in the same chat updates that same file;
282
+ - the agent may add, revise, reorder, or remove entries so the report reflects the feature's latest state; and
283
+ - a new IDE chat receives a new report file.
284
+
285
+ Reports use YAML frontmatter plus readable Markdown tables. Depending on the work performed, they cover scope and assumptions, threats and mitigations, security practices, OSV.dev results, secure code changes, applied guardrails, OWASP mappings, verification, and residual risks.
286
+
287
+ Treat reports as security-sensitive project documentation. They intentionally avoid full prompts, secrets, hidden reasoning, and raw tool output, but may still describe trust boundaries or remaining exposure.
160
288
 
161
- Reports retain the established VibeReview fields in table-formatted sections: scope and assumptions, threats mitigated, best practices achieved, OSV.dev dependency security, secure code changes, guardrails applied, OWASP mappings, verification, and residual risks. YAML frontmatter carries session identity, provider, status, and timestamps.
289
+ ## Deterministic technology detection
162
290
 
163
- ## Deterministic detection
291
+ The initial profile does not invoke a model. VibeReview derives technologies from recognized manifests, dependency names, source extensions, infrastructure files, and a small number of bounded content signals.
164
292
 
165
- The detector ignores dependency, build, virtual-environment, and VCS directories. It derives technologies from manifests, dependency names, source extensions, and recognized infrastructure files. It does not invoke a model and does not read `.env` files or credentials.
293
+ Detection ignores dependency, build, virtual-environment, and version-control directories and does not read `.env` files or credentials. Recognized signals include major JavaScript/TypeScript and Python frameworks, Go, Rust, Java, databases, authentication libraries, Docker, Kubernetes, Terraform providers, GitHub Actions, OpenAPI, MCP, and popular agent frameworks.
166
294
 
167
- Currently recognized signals include major JavaScript/TypeScript and Python frameworks, Go, Rust, Java, common databases, authentication libraries, Docker, Kubernetes, Terraform providers, GitHub Actions, OpenAPI, MCP, and popular agent frameworks.
295
+ Run initialization with `--verbose` to see matched packs, warnings, and technologies without a bundled pack.
168
296
 
169
- ## Catalog maintenance
297
+ ## Troubleshooting
170
298
 
171
- The checked-in catalog is a compact runtime projection. It deliberately omits the much larger compliance-description payloads used by VibeReview Main.
299
+ ### `vibereview: command not found`
172
300
 
173
- To import the source packs and rebuild the compressed asset:
301
+ The standalone `vibereview` command is not the documented installation path. Use the scoped package through `npx`:
174
302
 
175
303
  ```bash
176
- npm run catalog:import -- /path/to/guardrail-packs
177
- npm run build:catalog
304
+ npx @securityreviewai/vibereview-cli init
305
+ ```
306
+
307
+ ### Provider CLI not found
308
+
309
+ VibeReview does not install provider CLIs. Install the selected provider's executable, verify its version using the command in the Requirements table, and retry.
310
+
311
+ You can still install token-free baseline guardrails without running code-specific generation. The provider CLI must be available when that provider actually handles prompts.
312
+
313
+ ### Authentication does not open or complete
314
+
315
+ Run the provider's login command directly in an interactive terminal, complete the browser flow, verify authentication, and retry generation:
316
+
317
+ ```bash
318
+ cursor-agent login
319
+ codex login
320
+ claude auth login
321
+ copilot login --web-flow
322
+ ```
323
+
324
+ VibeReview can only launch interactive authentication when both stdin and stdout are attached to a terminal. Headless and CI environments must be authenticated separately using provider-supported credentials.
325
+
326
+ ### Code-specific generation fails
327
+
328
+ Baseline guardrails remain active. Retry with additional diagnostics:
329
+
330
+ ```bash
331
+ npx @securityreviewai/vibereview-cli guardrails generate --verbose
332
+ ```
333
+
334
+ Common causes are missing authentication, provider quota or rate limits, a provider timeout, or invalid structured output. The default timeout is five minutes. It can be changed to a value of at least 10,000 milliseconds:
335
+
336
+ ```bash
337
+ VIBEREVIEW_AGENT_TIMEOUT_MS=600000 npx @securityreviewai/vibereview-cli guardrails generate
338
+ ```
339
+
340
+ ### Workspace is already initialized
341
+
342
+ Refresh VibeReview-managed files without discarding custom or generated rules:
343
+
344
+ ```bash
345
+ npx @securityreviewai/vibereview-cli init --provider <cursor|codex|claude|copilot> --force
178
346
  ```
179
347
 
180
- ## Testing
348
+ ### The coding agent does not use the workflow
349
+
350
+ Restart the IDE agent after initialization. Then confirm that the provider-specific instructions, project skills, and hook file listed above exist and are enabled by that provider. The workflow improves consistency but cannot guarantee compliance by an underlying model or provider runtime.
351
+
352
+ ### Reports are not appearing
353
+
354
+ Reports are created by the coding agent for security-relevant work, not by the deterministic initialization command. Restart the agent, begin a new chat, and make a request that changes a security boundary, sensitive data flow, dependency, authentication, authorization, external integration, or infrastructure configuration.
355
+
356
+ ## Updating VibeReview
357
+
358
+ With `npx`, select the latest published release explicitly when you want to avoid a cached version:
181
359
 
182
360
  ```bash
361
+ npx @securityreviewai/vibereview-cli@latest --version
362
+ npx @securityreviewai/vibereview-cli@latest init --provider codex --force
363
+ ```
364
+
365
+ Review release notes before refreshing managed workflow files in important repositories.
366
+
367
+ ## Removing VibeReview
368
+
369
+ There is currently no automated uninstall command. Removal is intentionally manual because VibeReview merges managed blocks and hook entries into files that may also contain your own configuration.
370
+
371
+ To remove it safely, review and delete the VibeReview-owned instruction blocks, skills, and hook entries listed under **What initialization creates**, then remove `.vibereview/` if you no longer need its guardrails or reports. Back up or retain reports required for audit or project history.
372
+
373
+ ## Security considerations
374
+
375
+ VibeReview is a security workflow aid, not a replacement for code review, security testing, architecture review, or professional assessment. Provider output can be incomplete or incorrect. Review security-critical changes and verify important controls independently.
376
+
377
+ See [SECURITY.md](SECURITY.md) for the security model, data-handling boundaries, and vulnerability-reporting process. Do not disclose suspected vulnerabilities in a public issue.
378
+
379
+ ## Contributing
380
+
381
+ Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the complete workflow and security-sensitive review expectations. A typical local development workflow is:
382
+
383
+ ```bash
384
+ npm install
385
+ npm run typecheck
183
386
  npm test
184
387
  ```
185
388
 
186
- The suite covers catalog and skill assets, stack detection, evidence limits and exclusions, output validation, retry behavior, runner isolation flags, rule normalization, atomic updates, all-provider workflow installation, existing-file preservation, hook session identity, Markdown report contracts, and non-interactive initialization. Tests do not invoke paid provider requests.
389
+ To run the local build against a test repository:
390
+
391
+ ```bash
392
+ npm run build
393
+ node bin/vibereview.js init --cwd /path/to/test-project
394
+ ```
395
+
396
+ Tests do not invoke paid provider requests. They cover catalog and skill assets, stack detection, evidence limits and exclusions, structured-output validation, runner restrictions, rule normalization, safe workspace updates, all four provider integrations, hook session identity, report contracts, and non-interactive setup.
187
397
 
188
- ## Security
398
+ The checked-in guardrail catalog is a compact runtime projection. Maintainers can import source packs and rebuild the compressed asset with:
399
+
400
+ ```bash
401
+ npm run catalog:import -- /path/to/guardrail-packs
402
+ npm run build:catalog
403
+ ```
189
404
 
190
- Please read [SECURITY.md](SECURITY.md) before reporting a vulnerability. Deterministic profiling is local; code-specific generation sends the documented bounded evidence through the selected provider CLI.
405
+ Please keep changes focused, include tests for behavior changes, and avoid fixtures containing real credentials or proprietary source code.
191
406
 
192
407
  ## License
193
408
 
194
- Apache License 2.0. See [LICENSE](LICENSE).
409
+ Licensed under the [Apache License 2.0](LICENSE).
package/SECURITY.md CHANGED
@@ -1,20 +1,24 @@
1
1
  # Security Policy
2
2
 
3
+ ## Supported versions
4
+
5
+ Security fixes are provided for the latest published version of `@securityreviewai/vibereview-cli`. Upgrade to the latest release before reporting an issue that may already have been fixed.
6
+
3
7
  ## Reporting a vulnerability
4
8
 
5
- Do not open a public issue for a suspected vulnerability. Contact the VibeReview maintainers privately with:
9
+ Do not open a public issue for a suspected vulnerability. Use [GitHub private vulnerability reporting](https://github.com/securityreviewai/vibereview-cli/security/advisories/new) and include:
6
10
 
7
11
  - the affected version;
8
12
  - reproduction steps;
9
13
  - expected and observed behavior; and
10
14
  - the potential security impact.
11
15
 
12
- A dedicated private reporting address or GitHub private vulnerability reporting link must be added before the first public release.
16
+ You should receive an acknowledgement within five business days. Please allow the maintainers a reasonable opportunity to investigate and release a fix before public disclosure.
13
17
 
14
- ## Security properties through Milestone 3
18
+ ## Security properties
15
19
 
16
20
  - Technology detection runs locally and does not invoke an AI provider.
17
- - The selected provider's preflight completes before workspace files are written.
21
+ - Provider authentication preflight completes before optional code-specific generation. Token-free baseline files may already be installed at that point.
18
22
  - Known dependency, build, VCS, and virtual-environment directories are excluded from scanning.
19
23
  - The detector reads recognized manifests and selected infrastructure files; it does not read `.env` or credential files.
20
24
  - Workspace files are written with restrictive permissions and atomic replacement.
package/dist/src/core/integration.js CHANGED
@@ -48,7 +48,7 @@ function workflowPolicy(projectName, provider, skills) {
48
48
  const safeProjectName = projectName.replace(/[\u0000-\u001f\u007f`]/g, "_").slice(0, 200) || "workspace";
49
49
  return `# VibeReview Local Security Workflow
50
50
 
51
- Configured project: \`${safeProjectName}\`
51
+ Configured project: \`${safeProjectName}\`<br>
52
52
  Configured provider: \`${provider}\`
53
53
 
54
54
  This workspace uses VibeReview locally. There is no VibeReview server, MCP lookup, upload, sync, or JSON scan artifact in this workflow.
package/dist/src/providers/claude.js CHANGED
@@ -1,5 +1,5 @@
1
1
  import { cleanVersion, runProviderCommand } from "./process.js";
2
- export async function checkClaudePreflight(run = runProviderCommand) {
2
+ export async function checkClaudePreflight(run = runProviderCommand, environment = process.env) {
3
3
  let version;
4
4
  try {
5
5
  version = cleanVersion(await run("claude", ["--version"], 10_000));
@@ -7,13 +7,26 @@ export async function checkClaudePreflight(run = runProviderCommand) {
7
7
  catch {
8
8
  throw new Error("Claude Code was not found. Install it, then run `claude --version` to verify the installation.");
9
9
  }
10
+ const gateway = configuredGateway(environment);
11
+ if (gateway) {
12
+ return {
13
+ provider: "claude",
14
+ displayName: "Claude Code",
15
+ executable: "claude",
16
+ version,
17
+ authentication: "configured",
18
+ authenticationMessage: gateway === "requesty"
19
+ ? "Claude Code Requesty gateway authentication configured"
20
+ : "Claude Code gateway authentication configured",
21
+ };
22
+ }
10
23
  try {
11
24
  const output = await run("claude", ["auth", "status"]);
12
25
  if (/not logged in|not authenticated|logged out|\berror:/i.test(output))
13
26
  throw new Error("not authenticated");
14
27
  }
15
28
  catch {
16
- throw new Error("Claude Code authentication could not be verified. Run `claude auth status` or `claude auth login`, then retry `vibereview init`.");
29
+ throw new Error("Claude Code authentication could not be verified. Configure ANTHROPIC_BASE_URL with ANTHROPIC_AUTH_TOKEN for a gateway, or run `claude auth login`, then retry.");
17
30
  }
18
31
  return {
19
32
  provider: "claude",
@@ -24,4 +37,19 @@ export async function checkClaudePreflight(run = runProviderCommand) {
24
37
  authenticationMessage: "Claude Code authentication verified",
25
38
  };
26
39
  }
40
+ function configuredGateway(environment) {
41
+ const baseUrl = environment.ANTHROPIC_BASE_URL?.trim();
42
+ const token = environment.ANTHROPIC_AUTH_TOKEN?.trim() || environment.ANTHROPIC_API_KEY?.trim();
43
+ if (!baseUrl || !token)
44
+ return undefined;
45
+ try {
46
+ const url = new URL(baseUrl);
47
+ if (url.protocol !== "https:" && url.protocol !== "http:")
48
+ return undefined;
49
+ return url.hostname === "router.requesty.ai" || url.hostname.endsWith(".requesty.ai") ? "requesty" : "gateway";
50
+ }
51
+ catch {
52
+ return undefined;
53
+ }
54
+ }
27
55
  //# sourceMappingURL=claude.js.map
package/dist/src/runners/claude.js CHANGED
@@ -8,7 +8,7 @@ export function claudeArguments(input) {
8
8
  "--tools", "",
9
9
  "--no-session-persistence",
10
10
  "--strict-mcp-config",
11
- "--mcp-config", JSON.stringify({ mcpServers: {} }),
11
+ `--mcp-config=${JSON.stringify({ mcpServers: {} })}`,
12
12
  input.prompt,
13
13
  ];
14
14
  }
package/docs/provider-contracts.md CHANGED
@@ -1,12 +1,12 @@
1
1
  # Provider CLI contracts
2
2
 
3
- These commands are the installation, authentication, and Milestone 2 generation contract. Re-verify them before changing minimum supported provider versions.
3
+ These commands are the installation, authentication, and generation contract. Re-verify them before changing minimum supported provider versions.
4
4
 
5
5
  | Provider | Executable | Version check | Authentication check | Login recovery |
6
6
  |---|---|---|---|---|
7
7
  | Cursor | `cursor-agent` | `cursor-agent --version` | `cursor-agent status` | `cursor-agent login` |
8
8
  | Codex | `codex` | `codex --version` | `codex login status` | `codex login` |
9
- | Claude Code | `claude` | `claude --version` | `claude auth status` | `claude auth login` |
9
+ | Claude Code | `claude` | `claude --version` | Valid `ANTHROPIC_BASE_URL` plus `ANTHROPIC_AUTH_TOKEN`/`ANTHROPIC_API_KEY`, otherwise `claude auth status` | `claude auth login` |
10
10
  | GitHub Copilot | `copilot` | `copilot version` | Best-effort token/GitHub CLI discovery; definitive check deferred | `copilot login` |
11
11
 
12
12
  Copilot is deliberately different. Its documentation describes OAuth, environment-token, GitHub CLI fallback, and BYOK authentication, but does not expose a documented non-interactive status command equivalent to the other three. VibeReview does not spend an AI request merely to test Copilot authentication.
@@ -24,7 +24,9 @@ All providers receive the bundled skill, compact profile, baseline rules, and bo
24
24
 
25
25
  The default execution timeout is five minutes and can be changed with `VIBEREVIEW_AGENT_TIMEOUT_MS` (minimum ten seconds). VibeReview performs one additional provider request only when the first response executes successfully but fails the structured-output contract.
26
26
 
27
- ## Milestone 3 workspace integration
27
+ Claude gateway detection never reads or prints the credential value. The gateway URL and credential must both be present in the environment inherited by VibeReview. Requesty uses `ANTHROPIC_BASE_URL=https://router.requesty.ai` with `ANTHROPIC_AUTH_TOKEN`; when that pair is configured, first-party `claude auth status` and OAuth login are skipped. The Claude generation process inherits the same environment, so its request follows the configured gateway.
28
+
29
+ ## Workspace integration
28
30
 
29
31
  VibeReview uses provider-native always-on instructions as the enforcement layer and hooks for session/startup context. This split is intentional: not every provider permits a command hook to modify each submitted prompt.
30
32
 
package/package.json CHANGED
@@ -1,7 +1,15 @@
1
1
  {
2
2
  "name": "@securityreviewai/vibereview-cli",
3
- "version": "0.1.6",
3
+ "version": "0.1.8",
4
4
  "description": "Local-first security guardrails for AI coding agents.",
5
+ "repository": {
6
+ "type": "git",
7
+ "url": "git+https://github.com/securityreviewai/vibereview-cli.git"
8
+ },
9
+ "homepage": "https://github.com/securityreviewai/vibereview-cli#readme",
10
+ "bugs": {
11
+ "url": "https://github.com/securityreviewai/vibereview-cli/issues"
12
+ },
5
13
  "type": "module",
6
14
  "bin": {
7
15
  "vibereview": "bin/vibereview.js",