dvalincode 0.14.0 → 0.16.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 (100) hide show
  1. package/README.md +186 -60
  2. package/README.zh-CN.md +193 -72
  3. package/THIRD_PARTY_NOTICES.md +295 -147
  4. package/dist/agent/compact.js.map +1 -1
  5. package/dist/agent/loop.d.ts +8 -0
  6. package/dist/agent/loop.js +8 -1
  7. package/dist/agent/loop.js.map +1 -1
  8. package/dist/agent/runner.d.ts +1 -0
  9. package/dist/agent/runner.js +10 -1
  10. package/dist/agent/runner.js.map +1 -1
  11. package/dist/agent/session.d.ts +23 -1
  12. package/dist/agent/session.js +63 -11
  13. package/dist/agent/session.js.map +1 -1
  14. package/dist/agent/types.d.ts +2 -0
  15. package/dist/audit/log.d.ts +3 -0
  16. package/dist/audit/log.js.map +1 -1
  17. package/dist/audit/report.js +2 -0
  18. package/dist/audit/report.js.map +1 -1
  19. package/dist/audit/taps.js.map +1 -1
  20. package/dist/cli.js +24 -2
  21. package/dist/cli.js.map +1 -1
  22. package/dist/commands/dvalin.d.ts +1 -1
  23. package/dist/commands/dvalin.js +12 -0
  24. package/dist/commands/dvalin.js.map +1 -1
  25. package/dist/commands/mcpServe.d.ts +2 -0
  26. package/dist/commands/mcpServe.js +36 -0
  27. package/dist/commands/mcpServe.js.map +1 -0
  28. package/dist/commands/policy.js +12 -0
  29. package/dist/commands/policy.js.map +1 -1
  30. package/dist/commands/run.d.ts +30 -0
  31. package/dist/commands/run.js +229 -0
  32. package/dist/commands/run.js.map +1 -0
  33. package/dist/commands/update.js.map +1 -1
  34. package/dist/core/context.js.map +1 -1
  35. package/dist/core/guiUpdate.js.map +1 -1
  36. package/dist/core/policy.d.ts +25 -4
  37. package/dist/core/policy.js +32 -0
  38. package/dist/core/policy.js.map +1 -1
  39. package/dist/core/selfUpdate.d.ts +1 -1
  40. package/dist/core/selfUpdate.js.map +1 -1
  41. package/dist/core/subprocessSandbox.d.ts +49 -6
  42. package/dist/core/subprocessSandbox.js +175 -64
  43. package/dist/core/subprocessSandbox.js.map +1 -1
  44. package/dist/core/trust.js +12 -0
  45. package/dist/core/trust.js.map +1 -1
  46. package/dist/data/archive.js.map +1 -1
  47. package/dist/evidence/pack.js.map +1 -1
  48. package/dist/harness/run.d.ts +70 -0
  49. package/dist/harness/run.js +185 -0
  50. package/dist/harness/run.js.map +1 -0
  51. package/dist/mcp/client.d.ts +12 -0
  52. package/dist/mcp/client.js +2 -2
  53. package/dist/mcp/client.js.map +1 -1
  54. package/dist/mcp/config.d.ts +33 -3
  55. package/dist/mcp/config.js +32 -3
  56. package/dist/mcp/config.js.map +1 -1
  57. package/dist/mcp/register.d.ts +23 -6
  58. package/dist/mcp/register.js +42 -8
  59. package/dist/mcp/register.js.map +1 -1
  60. package/dist/mcp/server.d.ts +40 -0
  61. package/dist/mcp/server.js +317 -0
  62. package/dist/mcp/server.js.map +1 -0
  63. package/dist/mcp/stdio.d.ts +34 -0
  64. package/dist/mcp/stdio.js +183 -0
  65. package/dist/mcp/stdio.js.map +1 -0
  66. package/dist/memory/store.js.map +1 -1
  67. package/dist/providers/manager.js.map +1 -1
  68. package/dist/remediation/cases.js.map +1 -1
  69. package/dist/remediation/sarif.js.map +1 -1
  70. package/dist/remediation/sarifExport.d.ts +7 -0
  71. package/dist/remediation/sarifExport.js +102 -0
  72. package/dist/remediation/sarifExport.js.map +1 -0
  73. package/dist/remediation/scannerSuite.js +11 -1
  74. package/dist/remediation/scannerSuite.js.map +1 -1
  75. package/dist/server/configStore.d.ts +2 -8
  76. package/dist/server/configStore.js +12 -7
  77. package/dist/server/configStore.js.map +1 -1
  78. package/dist/server/index.js.map +1 -1
  79. package/dist/server/wsHandler.js +8 -0
  80. package/dist/server/wsHandler.js.map +1 -1
  81. package/dist/sessions/journal.js.map +1 -1
  82. package/dist/sessions/markdown.js.map +1 -1
  83. package/dist/tools/memoryImport.d.ts +1 -1
  84. package/dist/tools/memorySearch.d.ts +1 -1
  85. package/dist/tools/memoryUpdate.d.ts +3 -3
  86. package/dist/tools/memoryWrite.d.ts +4 -4
  87. package/dist/tools/registry.js.map +1 -1
  88. package/dist/tools/runCheck.d.ts +2 -2
  89. package/dist/tools/runSecuritySuite.d.ts +1 -1
  90. package/dist/tools/shell.d.ts +1 -1
  91. package/dist/tools/shell.js +1 -1
  92. package/dist/tools/shell.js.map +1 -1
  93. package/dist/tui/app.js +4 -1
  94. package/dist/tui/app.js.map +1 -1
  95. package/dist/tui/render.d.ts +1 -0
  96. package/dist/tui/render.js +11 -0
  97. package/dist/tui/render.js.map +1 -1
  98. package/dist/version.d.ts +1 -1
  99. package/dist/version.js +1 -1
  100. package/package.json +12 -5
package/README.md CHANGED
@@ -9,48 +9,119 @@
9
9
  <p align="center">
10
10
  <a href="https://github.com/arthurpanhku/dvalincode/releases/latest"><img src="https://img.shields.io/github/v/release/arthurpanhku/dvalincode?style=for-the-badge&color=818cf8&label=Release" alt="Release"></a>
11
11
  <a href="https://github.com/arthurpanhku/dvalincode/releases"><img src="https://img.shields.io/github/downloads/arthurpanhku/dvalincode/total?style=for-the-badge&color=blue&label=Downloads" alt="Downloads"></a>
12
- <a href="#-tests"><img src="https://img.shields.io/badge/Tests-229%20%2F%20229%20%E2%9C%93-success?style=for-the-badge" alt="Tests"></a>
12
+ <a href="#-tests"><img src="https://img.shields.io/badge/Tests-323%20%2F%20323%20%E2%9C%93-success?style=for-the-badge" alt="Tests"></a>
13
13
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge" alt="License"></a>
14
14
  <a href="https://scorecard.dev/viewer/?uri=github.com/arthurpanhku/dvalincode"><img src="https://api.scorecard.dev/projects/github.com/arthurpanhku/dvalincode/badge" alt="OpenSSF Scorecard"></a>
15
- <a href="docs/governance/ISO-42001-AIMS.md"><img src="https://img.shields.io/badge/ISO%2FIEC%2042001-AIMS%20Aligned-0F766E?style=for-the-badge" alt="ISO/IEC 42001 AIMS aligned"></a>
16
- <a href="docs/EVIDENCE-PACK.md"><img src="https://img.shields.io/badge/Compliance-Evidence%20Pack-2563EB?style=for-the-badge" alt="Compliance evidence pack"></a>
17
- <a href="docs/security/OPENSSF-SCORECARD.md"><img src="https://img.shields.io/badge/DevSecOps-Native-B91C1C?style=for-the-badge" alt="DevSecOps native"></a>
18
15
  <a href="#-quick-install"><img src="https://img.shields.io/badge/Platforms-macOS%20·%20Windows%20·%20Linux-blue?style=for-the-badge" alt="Platforms"></a>
19
16
  <a href="#-providers"><img src="https://img.shields.io/badge/LLM-OpenAI%20·%20Claude%20·%20DeepSeek%20·%20Ollama%20·%20Groq-7C3AED?style=for-the-badge" alt="LLM Support"></a>
20
17
  <a href="README.zh-CN.md"><img src="https://img.shields.io/badge/i18n-EN%20·%20中文-orange?style=for-the-badge" alt="English / 中文"></a>
21
18
  </p>
22
19
 
23
20
  <p align="center">
24
- <b>The approvable coding agent for regulated teams.</b><br>
25
- <b>Built for finance, healthcare, and security-sensitive engineering where AI coding must be controllable, transparent, and auditable.</b>
21
+ <b>Find the security holes in your repo, fix them, and prove the fix — in one command.</b><br>
22
+ Every fix is diffed, tested, re-scanned, and recorded in a tamper-evident audit log before it can become a PR.
26
23
  </p>
27
24
 
28
- <p align="center">
29
- <b>🔑 Any model · local-first · policy-bound · audit-ready — the agent your security team can actually approve.</b>
30
- </p>
25
+ ---
31
26
 
32
- <p align="center">
33
- Bring your own model — DeepSeek, OpenAI, Claude (via OpenRouter), Groq, Ollama, or any OpenAI-compatible endpoint. Switch with one click, no code changes, no lock-in.
34
- </p>
27
+ ## ⏱️ 30 seconds, no install, no API key
35
28
 
36
- ---
29
+ ```sh
30
+ npx dvalincode dvalin .
31
+ ```
37
32
 
38
- ## ⏱️ 60 seconds to proof
33
+ That is the whole thing. It runs the built-in rules for injection, hardcoded
34
+ secrets, XSS, `eval`, and unsafe shell use against the current directory and
35
+ prints what it found. No account, no model, no config, no code leaves your
36
+ machine. Add `--scanners builtin,semgrep,trivy,osv-scanner` to pull in whichever
37
+ of those engines you already have on `PATH`.
38
+
39
+ ### Or put it on every pull request — nothing to install at all
40
+
41
+ ```yaml
42
+ # .github/workflows/security.yml
43
+ permissions:
44
+ contents: read
45
+ security-events: write
46
+ steps:
47
+ - uses: actions/checkout@v5
48
+ - uses: arthurpanhku/dvalincode@v0.15.0
49
+ with:
50
+ fail-on: high
51
+ ```
52
+
53
+ Findings land inline on the pull request diff and in your Security tab.
54
+ No API key, no secrets, no model — the scan is deterministic and local to the
55
+ runner. [Full example →](docs/examples/dvalin-scan.yml)
56
+
57
+ ### Or let your agent call it
39
58
 
40
- Don't take the claims on trust — verify them on your own machine:
59
+ If an agent is writing the code, something other than that agent has to check
60
+ it. DvalinCode is an MCP server, so any agent that speaks MCP can:
41
61
 
42
62
  ```sh
43
- curl -fsSL https://raw.githubusercontent.com/arthurpanhku/dvalincode/main/scripts/install.sh | bash
44
- dvalincode trust
63
+ claude mcp add dvalin -- npx -y dvalincode mcp-serve --workspace .
45
64
  ```
46
65
 
47
- `trust` prints this install's **live security posture**: the resolved org policy and its hash, per-boundary network enforcement (provider · shell · MCP), and the tamper-evident audit status — the exact evidence a security reviewer needs, straight from the tool itself.
66
+ `dvalin_scan` is read-only and deterministic — no model runs, no credentials are
67
+ needed, no files are touched — so an agent can call it after every edit. A real
68
+ call against a vulnerable fixture returns in ~170ms with a ~600 byte payload.
69
+ The same server also exposes `dvalin_run_task` for delegating a whole governed
70
+ task, plus the session and audit-evidence tools.
71
+ [Agent integrations →](integrations/)
72
+
73
+ ### Then let it fix what it found
74
+
75
+ ```sh
76
+ dvalincode dvalin . --fix --verify --draft-pr
77
+ ```
78
+
79
+ This step *does* use a model — your model, any OpenAI-compatible endpoint. It
80
+ prepares focused repairs in an isolated worktree, runs your tests, and requires
81
+ a clean re-scan before anything can proceed to a draft PR. It never auto-merges,
82
+ and a clean scan is never treated as proof that the code is safe.
48
83
 
49
84
  <p align="center">
50
- <img src="assets/cli-trust.gif" alt="dvalincode trust — live security posture under an org policy" width="100%">
85
+ <img src="assets/dvalin-remediation.gif" alt="Dvalin scanning a vulnerable OWASP NodeGoat example at 22/100 F with 10 findings, then showing a clean verified re-scan at 100/100 A" width="100%">
51
86
  </p>
52
87
 
53
- Then let the agent work, and prove what it did after the fact:
88
+ This animation is made from the real application, not a mock. The input is an
89
+ Apache-2.0-licensed example adapted from
90
+ [OWASP NodeGoat](https://github.com/OWASP/NodeGoat/tree/c5cb68a7084e4ae7dcc60e6a98768720a81841e8/app/routes),
91
+ whose contribution route evaluated user-controlled text.
92
+
93
+ ## 🛡️ What that run actually did
94
+
95
+ Dvalin turns open-source scanner evidence into a controlled scan → fix → test →
96
+ re-scan → draft-PR workflow. Here is the run in the animation above, measured:
97
+
98
+ | Real NodeGoat-derived run | Before | After Dvalin remediation |
99
+ |---|---:|---:|
100
+ | Security health (triage heuristic) | 22 / 100 · F | 100 / 100 · A |
101
+ | Findings | 10 (`eval` across 3 rules, 2 engines) | 0 |
102
+ | Tests | 2 passing | 3 passing, including an injection regression test |
103
+ | Scanner fleet | 4 / 4 completed | 4 / 4 completed |
104
+
105
+ The scanning and hardening **control plane** uses open-source components:
106
+
107
+ - [Semgrep CE](https://github.com/semgrep/semgrep) and its community rules for
108
+ semantic SAST.
109
+ - [Trivy](https://github.com/aquasecurity/trivy) for filesystem vulnerabilities,
110
+ secrets, and misconfiguration.
111
+ - [OSV-Scanner](https://github.com/google/osv-scanner) with the open
112
+ [OSV database](https://osv.dev/) for dependency vulnerabilities.
113
+ - DvalinCode's MIT-licensed built-in rules, remediation orchestration, test and
114
+ re-scan gates, plus [SARIF 2.1](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html)
115
+ import for other compatible scanners.
116
+
117
+ The scanners find and rank evidence. The configured model proposes source
118
+ changes; DvalinCode constrains that work, records the diff, runs project tests,
119
+ re-scans the changed tree, and keeps PR publication explicit. It does not
120
+ auto-merge and it does not claim that a clean scan proves the absence of bugs.
121
+ Choose an open-weight model through Ollama if the repair-proposal step must also
122
+ stay fully local and open; hosted model licensing depends on the provider.
123
+
124
+ You can still prove what the agent did after the fact:
54
125
 
55
126
  ```sh
56
127
  dvalincode report verify # re-derive the hash chain of the last run's audit log
@@ -58,6 +129,22 @@ dvalincode report verify # re-derive the hash chain of the last run's audit l
58
129
 
59
130
  ---
60
131
 
132
+ ## 🏛️ And it survives a security review
133
+
134
+ That last command is the part that matters once more than one person depends on
135
+ this. DvalinCode is a full coding agent — terminal, web GUI, and desktop app —
136
+ built so that an organization, not the developer, bounds what it may do: a
137
+ policy file constrains modes, commands, paths, tools, and models; every run is
138
+ hash-chained into a tamper-evident audit log; nothing reaches a provider that
139
+ the egress guard did not allow. A repo policy can only ever *narrow* the
140
+ machine-level one.
141
+
142
+ If you are the person who has to approve this class of tool, start at
143
+ [APPROVABILITY-PLAN.md](docs/APPROVABILITY-PLAN.md) and the
144
+ [Evidence Pack](docs/EVIDENCE-PACK.md) that every release ships of itself.
145
+
146
+ ---
147
+
61
148
  <table>
62
149
  <tr><td><b>🏠 Home</b></td><td>One place for read-only <b>Ask</b> and approval-gated <b>Collaborate</b> workflows. Switch intent without leaving the project or conversation.</td></tr>
63
150
  <tr><td><b>⚡ Code</b></td><td>Focused autonomous coding with full tool access and Ask / Plan / Auto / Bypass permission levels. Security and browser routines no longer compete with the core coding workflow.</td></tr>
@@ -67,7 +154,8 @@ dvalincode report verify # re-derive the hash chain of the last run's audit l
67
154
  <tr><td><b>📚 Skills</b></td><td>Upload, download, and inspect local skill bundles. DvalinCode ships built-in secure-code-scan and secure-code-remediation skills, plus agent tools for listing skills, reading skill instructions, scanning, listing cases, and preparing remediation worktrees. <a href="docs/SKILLS.md">Format →</a></td></tr>
68
155
  <tr><td><b>🛡️ Audit trail</b></td><td>Every run emits a tamper-evident, hash-chained JSONL log — every file read/written, every command, every approval. A Run Report renders it as Markdown; <code>dvalincode report verify</code> proves the chain is intact. <a href="docs/AUDIT-TRAIL.md">Threat model →</a></td></tr>
69
156
  <tr><td><b>🔒 Org policy &amp; <code>trust</code></b></td><td>A company — not the developer — bounds the agent. A <code>dvalin.policy.json</code> constrains modes, shell commands, file paths, tools, and models; a repo policy can only ever <i>narrow</i> the machine-level one, never widen it. Each run records the governing policy's hash. <code>dvalincode trust</code> prints the install's live security posture — active policy + hashes, audit status, runtime — so a reviewer can verify it directly. <a href="docs/POLICY-REFERENCE.md">Policy reference →</a> · <a href="docs/APPROVABILITY-PLAN.md">Approvability plan →</a></td></tr>
70
- <tr><td><b>🏛️ Governance evidence</b></td><td>OpenSSF Scorecard, CodeQL, Dependabot, pinned GitHub Actions, CODEOWNERS, and ISO/IEC 42001 AIMS alignment docs are maintained as reviewable project evidence. <a href="docs/security/OPENSSF-SCORECARD.md">Scorecard map →</a> · <a href="docs/governance/ISO-42001-AIMS.md">ISO 42001 alignment →</a></td></tr>
157
+ <tr><td><b>🏛️ Governance evidence</b></td><td>OpenSSF Scorecard, CodeQL, Dependabot, pinned GitHub Actions, CODEOWNERS, and ISO/IEC 42001 AIMS alignment docs are maintained as reviewable project evidence, and every release ships an Evidence Pack the binary produced of itself. <a href="docs/security/OPENSSF-SCORECARD.md">Scorecard map →</a> · <a href="docs/governance/ISO-42001-AIMS.md">ISO 42001 alignment →</a> · <a href="docs/RELEASE-EVIDENCE.md">Release evidence →</a></td></tr>
158
+ <tr><td><b>📐 Open specs</b></td><td><b>PCP-1</b> — the provider-boundary contract (egress containment, credential containment, audit, policy binding) written as a vendor-neutral profile with test procedures, so any agent runtime can run it against its own adapters and publish the result. Not a DvalinCode test file; a checklist anyone can hold us to as well. <a href="docs/spec/PROVIDER-CONFORMANCE.md">Provider Conformance Profile →</a></td></tr>
71
159
  <tr><td><b>🖥️ First-class GUI</b></td><td>Modern web UI with code highlighting, file <code>@</code>-references, <code>/</code> slash commands, Git branch indicator, live token + cost counter, multi-profile LLM config, and a dark / light / system theme switcher.</td></tr>
72
160
  <tr><td><b>🖥️ Terminal or web — one binary</b></td><td>Run it bare for an interactive <b>terminal agent</b> with streaming output, inline approvals, and red/green diffs, or <code>dvalincode serve</code> to host the <b>web GUI</b> for browser/remote use. Both frontends drive the same agent core.</td></tr>
73
161
  <tr><td><b>🖥️ Native desktop app</b></td><td><code>DvalinCode.app</code> — a real dock application (OS-native webview, no Electron) over the same engine. On macOS the one-line installer puts it in <code>/Applications</code> automatically; launch it straight from Launchpad.</td></tr>
@@ -126,6 +214,12 @@ it can touch production repositories.
126
214
 
127
215
  ## 🛡️ Security & Governance
128
216
 
217
+ <p align="center">
218
+ <a href="docs/governance/ISO-42001-AIMS.md"><img src="https://img.shields.io/badge/ISO%2FIEC%2042001-AIMS%20Aligned-0F766E?style=for-the-badge" alt="ISO/IEC 42001 AIMS aligned"></a>
219
+ <a href="docs/EVIDENCE-PACK.md"><img src="https://img.shields.io/badge/Compliance-Evidence%20Pack-2563EB?style=for-the-badge" alt="Compliance evidence pack"></a>
220
+ <a href="docs/security/OPENSSF-SCORECARD.md"><img src="https://img.shields.io/badge/DevSecOps-Native-B91C1C?style=for-the-badge" alt="DevSecOps native"></a>
221
+ </p>
222
+
129
223
  DvalinCode maintains project-level governance evidence for open-source and
130
224
  enterprise review. This is the differentiator for teams where AI coding must
131
225
  pass security approval before it can reach production repositories:
@@ -157,7 +251,7 @@ not claim third-party ISO certification.
157
251
 
158
252
  ---
159
253
 
160
- ## ⭐ What's New in v0.13.0 — Dvalin security engineering
254
+ ## ⭐ What's New in v0.14.0 — Dvalin security engineering
161
255
 
162
256
  - **Home unifies Chat and Cowork** — the GUI now has a single Home workspace
163
257
  with read-only Ask and approval-gated Collaborate intents, while keeping the
@@ -321,53 +415,32 @@ not claim third-party ISO certification.
321
415
 
322
416
  ## 📸 Preview
323
417
 
324
- <p align="center">
325
- <img src="assets/hero.png" alt="DvalinCode UI" width="100%">
326
- </p>
327
-
328
- **Switching modes — each mode has its own sidebar:**
418
+ **A real Dvalin scan of vulnerable code — Security health 22/100 · F, with the
419
+ 10 findings the engines actually reported, located to the line:**
329
420
 
330
421
  <p align="center">
331
- <img src="assets/modes.gif" alt="Mode switching" width="100%">
422
+ <img src="assets/hero.png" alt="Dvalin Security health showing 22/100 F with 4 high and 6 medium findings, and a Findings list locating each eval to a line in the NodeGoat-derived route" width="100%">
332
423
  </p>
333
424
 
334
- **Slash commands & file references in the composer:**
425
+ **The verified result — the three `eval` call sites replaced by a constrained
426
+ numeric parser, one new injection regression test, all four open-source engines
427
+ complete, 0 findings, 100/100 · A:**
335
428
 
336
429
  <p align="center">
337
- <img src="assets/slash.gif" alt="Slash commands and @ file references" width="100%">
430
+ <img src="assets/dvalin-scan-after.jpg" alt="Dvalin verified re-scan showing 100/100 A, zero findings, and the remediation run that produced it" width="100%">
338
431
  </p>
339
432
 
340
- ### 🔒 Governance, from the command line
341
-
342
- **`dvalincode trust` — the install's live security posture (resolved policy, per-boundary enforcement, audit status) that a security review can read directly.** Field semantics and copy-paste recipes: [docs/POLICY-REFERENCE.md](docs/POLICY-REFERENCE.md).
433
+ **Home → Code → Dvalin — the current workspaces:**
343
434
 
344
435
  <p align="center">
345
- <img src="assets/cli-trust.gif" alt="dvalincode trust — live security posture under an org policy" width="100%">
436
+ <img src="assets/modes.gif" alt="DvalinCode switching between Home, Code, and Dvalin" width="100%">
346
437
  </p>
347
438
 
348
- **`dvalincode policy check` — validate `dvalin.policy.json` in CI: schema check, the resolved policy after machine-layer narrowing, and its canonical hash.**
349
-
350
- <p align="center">
351
- <img src="assets/cli-policy.gif" alt="dvalincode policy check — validate and inspect the resolved org policy" width="100%">
352
- </p>
353
-
354
- **Tamper-evident audit — every agent run is a hash-chained, minimized report you can verify offline:**
355
-
356
- <p align="center">
357
- <img src="assets/cli-audit.gif" alt="dvalincode report — run report, then report verify proving the chain intact" width="100%">
358
- </p>
359
-
360
- **Evidence Pack — one command bundles policy, posture, and audit proofs into a single file a reviewer can verify fully offline:**
361
-
362
- <p align="center">
363
- <img src="assets/cli-evidence.gif" alt="dvalincode evidence export and verify — offline-verifiable governance evidence" width="100%">
364
- </p>
365
-
366
- **Project intelligence — `dvalincode scan` maps the workspace before the agent touches it:**
367
-
368
- <p align="center">
369
- <img src="assets/cli-scan.gif" alt="dvalincode scan — project intelligence" width="100%">
370
- </p>
439
+ The scan images above are unedited captures of a real run against the documented
440
+ NodeGoat-derived case: the scanners were run, the model repaired the source, the
441
+ project's tests were run, and the tree was re-scanned. Nothing is staged, and a
442
+ 100/A means the configured engines found nothing — not that the code is proven
443
+ safe.
371
444
 
372
445
  ---
373
446
 
@@ -387,6 +460,17 @@ not claim third-party ISO certification.
387
460
 
388
461
  ## 🚀 Quick Install
389
462
 
463
+ ### Homebrew (macOS / Linux)
464
+
465
+ ```sh
466
+ brew tap arthurpanhku/dvalincode https://github.com/arthurpanhku/dvalincode
467
+ brew install arthurpanhku/dvalincode/dvalincode
468
+ ```
469
+
470
+ Installs the same signed-by-checksum release archive the one-liner does, and
471
+ `brew upgrade` keeps it current. Homebrew never applies the macOS quarantine
472
+ attribute, so this path is not subject to Gatekeeper.
473
+
390
474
  ### macOS / Linux (one-liner)
391
475
 
392
476
  ```sh
@@ -401,8 +485,14 @@ dvalincode # interactive terminal agent
401
485
  dvalincode dvalin . # white-box security scan (GUI-independent)
402
486
  dvalincode serve # start the web GUI, open the browser
403
487
  dvalincode serve --host 0.0.0.0 --no-open # host it on a server for remote/browser use
488
+ echo "inspect src and summarize" | dvalincode run - --output-format stream-json
489
+ dvalincode mcp-serve # task-level stdio MCP server for external agents
404
490
  ```
405
491
 
492
+ Headless `run` and `mcp-serve` keep the same policy and audit chokepoint as
493
+ the interactive clients. See the [unattended recipes](docs/RECIPES-UNATTENDED.md)
494
+ for cron, CI, and external-agent examples.
495
+
406
496
  ### Windows
407
497
 
408
498
  Download `dvalincode-v*-windows-x64.zip` from [Releases](https://github.com/arthurpanhku/dvalincode/releases/latest), unzip, then double-click `start.bat`.
@@ -421,6 +511,18 @@ Grab the archive for your platform from the [Releases page](https://github.com/a
421
511
 
422
512
  Verify against `SHA256SUMS.txt` (included in each release).
423
513
 
514
+ Each release also ships **`dvalincode-v*-evidence.json`** — an Evidence Pack the
515
+ shipped binary produced of itself on the build machine: two real governed runs,
516
+ one allowed and one blocked by policy, with their hash chains. You can check the
517
+ claims on this page before installing anything:
518
+
519
+ ```sh
520
+ dvalincode evidence verify dvalincode-v0.14.0-evidence.json # offline, reads only the file
521
+ ```
522
+
523
+ The pack's checksum is inside `SHA256SUMS.txt`, which is the subject of the
524
+ release's build-provenance attestation. [How it is produced →](docs/RELEASE-EVIDENCE.md)
525
+
424
526
  > **macOS Gatekeeper:** binaries are unsigned. On first run, either clear the quarantine flag with `xattr -dr com.apple.quarantine ~/.dvalincode`, or right-click the binary in Finder → Open → confirm.
425
527
 
426
528
  ### Staying up to date
@@ -566,7 +668,7 @@ RESTORE → COMPACT → COMMAND → BUILD → RUN → SAVE → RESPOND → DONE
566
668
  npm test
567
669
  ```
568
670
 
569
- **229 tests · 40 files · all green.**
671
+ **323 tests · 49 files · all green.**
570
672
 
571
673
  ---
572
674
 
@@ -643,7 +745,13 @@ They represent different outcomes and safety defaults. <b>Home</b> groups read-o
643
745
  <details>
644
746
  <summary><b>Is the shell tool sandboxed?</b></summary>
645
747
  <br>
646
- On macOS, yes — every <code>shell</code> tool invocation is wrapped in <code>sandbox-exec</code> with a profile that <i>denies network access</i> and allows file writes only inside <code>cwd</code>, <code>/tmp</code>, and <code>/var</code>. Linux and Windows sandboxing is planned.
748
+ On macOS, commands use <code>sandbox-exec</code>; on Linux, restrictive network policies use Bubblewrap when installed. Windows has no supported subprocess network sandbox yet, so restrictive policies fail closed instead of silently running unrestricted. The native command runner itself works on all three platforms.
749
+ </details>
750
+
751
+ <details>
752
+ <summary><b>Which operating-system shells are supported?</b></summary>
753
+ <br>
754
+ Linux and macOS commands run through <code>/bin/sh</code>; Windows commands run through the system <code>ComSpec</code> (<code>cmd.exe</code> by default). Full native command lines support pipes, redirects, and conditional operators. The split <code>command</code> + <code>args</code> form quotes executable paths and arguments for the host shell.
647
755
  </details>
648
756
 
649
757
  <details>
@@ -681,7 +789,7 @@ Contributions welcome. The codebase is intentionally small and surgical — see
681
789
  ```sh
682
790
  git clone https://github.com/arthurpanhku/dvalincode
683
791
  cd dvalincode && npm install
684
- npm test # 65/65 ✅
792
+ npm test # 323/323 ✅
685
793
  npm run typecheck
686
794
  ```
687
795
 
@@ -745,3 +853,21 @@ Full source references: [docs/REFERENCES.md](docs/REFERENCES.md)
745
853
  </picture>
746
854
  </a>
747
855
  </p>
856
+
857
+ ---
858
+
859
+ ## 💛 Thanks to Our Contributors
860
+
861
+ <p align="center">
862
+ Every issue, idea, documentation improvement, test, and code contribution helps make DvalinCode better.
863
+ </p>
864
+
865
+ <p align="center">
866
+ <a href="https://github.com/arthurpanhku/dvalincode/graphs/contributors">
867
+ <img src="https://contrib.rocks/image?repo=arthurpanhku/dvalincode" alt="DvalinCode contributors">
868
+ </a>
869
+ </p>
870
+
871
+ <p align="center">
872
+ <sub>Want to join them? Read the <a href="CONTRIBUTING.md">contribution guide</a> and send your first pull request.</sub>
873
+ </p>