guardlink 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to GuardLink CLI will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] — 2026-02-21
+
+Initial public release of GuardLink.
+
+### Added
+
+- **Parser**: 16 annotation types, 25+ comment styles, v1 backward compatibility
+- **Parser**: External reference support (cwe, capec, owasp), severity levels
+- **Analyzer**: Coverage statistics, dangling ref detection, duplicate ID detection
+- **Analyzer**: SARIF 2.1.0 export for GitHub/GitLab Security tab
+- **Analyzer**: Suggestion engine with 14 patterns for common security scenarios
+- **Diff**: Threat model comparison between git refs, change classification
+- **Report**: Markdown report with executive summary and Mermaid DFD diagram
+- **Report**: Compact diagram mode for high-exposure codebases
+- **Init**: Project initialization with multi-agent support (Claude Code, Cursor, Windsurf, Cline, Codex, GitHub Copilot)
+- **Init**: Behavioral directive injection for automatic annotation by AI agents
+- **MCP**: 12 tools (parse, validate, status, suggest, lookup, threat_report, threat_reports, annotate, report, dashboard, sarif, diff) and 3 resources
+- **CLI**: 12 commands (init, parse, status, validate, report, diff, sarif, mcp, threat-report, annotate, dashboard, scan)
+- **TUI**: Interactive terminal interface with command palette, autocomplete, and inline help
+- **Dashboard**: HTML threat model dashboard with exposure explorer, file tree, and threat report viewer
+- **Agents**: Unified agent launcher (Claude Code, Cursor, Windsurf, Cline, Codex, Gemini CLI) with config resolution chain
+- **Threat Reports**: AI-powered threat analysis using STRIDE, DREAD, PASTA, and other frameworks
+- **CI**: --strict flag on validate, --fail-on-new on diff for CI gates

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 BugB Technologies
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,344 @@
+# GuardLink
+
+[![npm version](https://img.shields.io/npm/v/guardlink.svg)](https://www.npmjs.com/package/guardlink)
+[![CI](https://github.com/Bugb-Technologies/guardlink/actions/workflows/ci.yml/badge.svg)](https://github.com/Bugb-Technologies/guardlink/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node.js 18+](https://img.shields.io/badge/node-18%2B-green.svg)](https://nodejs.org)
+[![Spec: CC-BY-4.0](https://img.shields.io/badge/spec-CC--BY--4.0-orange.svg)](docs/SPEC.md)
+
+**Security annotations that live in your code. Your threat model updates when your code changes.**
+
+> **This repository is secured by GuardLink.** Run `guardlink status .` to see 152 annotations across 12 assets, 13 threats, and 10 controls — maintained by AI agents, validated in CI.
+
+```javascript
+// @asset PaymentService (#payments) -- "Handles card transactions"
+// @threat SQL_Injection (#sqli) [critical] cwe:CWE-89
+
+// @mitigates #payments against #sqli using #prepared-stmts
+app.post('/charge', async (req, res) => {
+  const result = await db.query('SELECT * FROM cards WHERE id = $1', [req.body.id]);
+});
+
+// @exposes #payments to #idor [P1] cwe:CWE-639 -- "No ownership check"
+app.get('/receipts/:id', async (req, res) => {
+  const receipt = await db.query('SELECT * FROM receipts WHERE id = $1', [req.params.id]);
+});
+```
+
+---
+
+## Install
+
+```bash
+npm install -g guardlink
+```
+
+Requires Node.js 18+.
+
+## Quick Start
+
+```bash
+# Initialize in your project (detects your AI agent automatically)
+guardlink init
+
+# Let your AI coding agent annotate, or write annotations manually
+# Then validate
+guardlink validate .
+
+# See your security posture
+guardlink status .
+```
+
+```
+Assets:        3    Mitigations:  4
+Threats:       8    Exposures:    6  (3 unmitigated)
+Controls:      5    Coverage:     62%
+```
+
+```bash
+# Generate a full threat model report
+guardlink report .
+
+# Interactive HTML dashboard
+guardlink dashboard .
+
+# AI threat analysis (STRIDE, DREAD, PASTA, etc.)
+guardlink threat-report stride --claude-code
+
+# Interactive TUI with slash commands
+guardlink
+```
+
+---
+
+## Why GuardLink
+
+Threat models rot. Teams do a session at the start of a project, someone creates a Confluence page, and it's stale by the next sprint. SAST scanners find 200 things with no context about what matters. Pen test reports sit in shared drives. The root cause is always the same: **security knowledge lives outside the code**.
+
+GuardLink fixes this at three levels:
+
+**1. Annotations in code.** Security decisions are structured comments next to the code they describe. When a developer writes a parameterized query, `@mitigates #api against #sqli using #prepared-stmts` lives right above it. When the code changes, the annotation is right there to update. The threat model *is* the code.
+
+**2. AI agents maintain it.** GuardLink integrates with AI coding agents through MCP and behavioral directives. When your agent writes a route handler, it adds `@exposes` and `@mitigates` annotations automatically. The threat model maintains itself because the thing writing the code also writes the security context.
+
+**3. CI enforces it.** `guardlink validate` fails on syntax errors. `guardlink diff --fail-on-new` blocks PRs that introduce unmitigated exposures. `guardlink sarif` exports to GitHub's Security tab. The threat model becomes a quality gate, not a checkbox.
+
+```
+Developer writes code
+       ↓
+AI agent adds security annotations
+       ↓
+CI validates on every PR
+       ↓
+Team reviews security posture in the diff
+       ↓
+Threat model is always current, always enforced
+```
+
+---
+
+## AI Agent Integration
+
+GuardLink ships an MCP server and behavioral directives for AI coding agents. After `guardlink init`, your agent treats security annotations like type safety — adding them by default when writing security-relevant code.
+
+`guardlink init` detects your agent and configures two things:
+
+**MCP server** — tools to read the threat model, validate annotations, suggest annotations, and query threats by keyword. The agent can ask "what threats affect #api?" before writing code that touches the API.
+
+**Behavioral directive** — a rule injected into your agent's instruction file (CLAUDE.md, .cursorrules, etc.) that says: *when writing code that handles routes, auth, database access, file I/O, or external services, add GuardLink annotations.*
+
+### Supported Agents
+
+| Agent | Config File | MCP Support |
+|-------|------------|-------------|
+| Claude Code | `CLAUDE.md` + `.mcp.json` | ✅ Full |
+| Cursor | `.cursorrules` + `.cursor/mcp.json` | ✅ Full |
+| Windsurf | `.windsurfrules` + `.windsurf/mcp.json` | ✅ Full |
+| Cline | `.clinerules` + `.cline/mcp.json` | ✅ Full |
+| Codex | `AGENTS.md` | Directive only |
+| GitHub Copilot | `.github/copilot-instructions.md` | Directive only |
+
+### MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `guardlink_parse` | Full threat model as JSON |
+| `guardlink_validate` | Check for errors and dangling references |
+| `guardlink_status` | Coverage summary |
+| `guardlink_suggest` | Suggest annotations for a code snippet |
+| `guardlink_lookup` | Query threats, controls, flows by keyword |
+| `guardlink_threat_report` | AI threat report (STRIDE, DREAD, etc.) |
+| `guardlink_annotate` | Build annotation prompt for the agent |
+| `guardlink_report` | Generate markdown report |
+| `guardlink_dashboard` | Generate HTML dashboard |
+| `guardlink_sarif` | Export SARIF 2.1.0 |
+| `guardlink_diff` | Compare threat model against a git ref |
+
+**Resources:** `guardlink://model`, `guardlink://definitions`, `guardlink://config`
+
+---
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `guardlink init [dir]` | Initialize project with definitions, config, and agent integration |
+| `guardlink parse [dir]` | Parse all annotations, output ThreatModel JSON |
+| `guardlink status [dir]` | Coverage summary: assets, threats, mitigations, exposures |
+| `guardlink validate [dir]` | Check for syntax errors, dangling refs, duplicate IDs |
+| `guardlink validate --strict` | Also fail on unmitigated exposures |
+| `guardlink scan [dir]` | Find unannotated security-relevant functions |
+| `guardlink report [dir]` | Markdown threat model with Mermaid architecture diagram |
+| `guardlink dashboard [dir]` | Interactive HTML threat model dashboard |
+| `guardlink diff --from <ref>` | Compare threat models between git refs |
+| `guardlink diff --fail-on-new` | Exit 1 if new unmitigated exposures found |
+| `guardlink sarif [dir]` | Export unmitigated exposures as SARIF 2.1.0 |
+| `guardlink threat-report [fw]` | AI threat report (stride/dread/pasta/attacker/rapid/general) |
+| `guardlink threat-reports` | List saved AI threat reports |
+| `guardlink annotate [prompt]` | Launch a coding agent to add annotations |
+| `guardlink config` | Set AI provider and API key |
+| `guardlink mcp` | Start MCP server for AI agent integration |
+
+---
+
+## Annotation Reference
+
+GuardLink annotations go in comments in any language. The parser supports `//`, `#`, `--`, `/* */`, `""" """`, and 25+ comment styles.
+
+### Definitions (shared, in `.guardlink/definitions.js`)
+
+```javascript
+// @asset App.API (#api) -- "Express REST API serving mobile and web clients"
+// @threat SQL_Injection (#sqli) [critical] cwe:CWE-89 -- "Unsanitized input reaches SQL query"
+// @control Parameterized_Queries (#prepared-stmts) -- "All queries use bound parameters"
+```
+
+### Relationships (in source files, next to the code)
+
+```python
+# @mitigates #api against #sqli using #prepared-stmts -- "All queries parameterized"
+# @exposes #api to #xss [P1] cwe:CWE-79 -- "User bio rendered without escaping"
+# @accepts #info-disclosure on #api -- "Health endpoint is intentionally public"
+# @transfers #sqli from #api to #database -- "DB handles untrusted input"
+```
+
+### Data Flow & Architecture
+
+```go
+// @flow #api -> #database via "PostgreSQL wire protocol"
+// @boundary #api <-> #cdn -- "TLS termination point"
+// @handles pii on #api -- "Processes user email and address"
+// @handles secrets on #auth -- "Manages JWT signing keys"
+```
+
+### Operational
+
+```rust
+// @audit #api by "PenTest Corp" on 2025-03-15 -- "Annual penetration test"
+// @validates #input-validation on #api using "Jest integration tests"
+// @assumes #api -- "Rate limiting handled by API gateway"
+// @owns #api by "backend-team"
+```
+
+### All Annotation Types
+
+| Verb | Purpose | Example |
+|------|---------|---------|
+| `@asset` | Define a component | `@asset UserService (#users)` |
+| `@threat` | Define a threat | `@threat XSS (#xss) [high] cwe:CWE-79` |
+| `@control` | Define a security control | `@control WAF (#waf)` |
+| `@mitigates` | Control protects asset against threat | `@mitigates #api against #sqli using #prepared-stmts` |
+| `@exposes` | Asset vulnerable to threat | `@exposes #api to #xss [P1]` |
+| `@accepts` | Risk acknowledged | `@accepts #dos on #api -- "By design"` |
+| `@transfers` | Risk moved between assets | `@transfers #sqli from #api to #db` |
+| `@flow` | Data flow between assets | `@flow #api -> #db via "SQL"` |
+| `@boundary` | Trust boundary | `@boundary #api <-> #external` |
+| `@handles` | Data classification | `@handles pii on #users` |
+| `@audit` | Security audit record | `@audit #api by "Firm" on 2025-01-01` |
+| `@validates` | Control verification | `@validates #auth on #api using "tests"` |
+| `@assumes` | Security assumption | `@assumes #api -- "Behind VPN"` |
+| `@owns` | Component ownership | `@owns #api by "team-backend"` |
+| `@shield` | AI exclusion zone | `@shield #api requires #auth-check` |
+
+Severity: `[critical]`/`[P0]`, `[high]`/`[P1]`, `[medium]`/`[P2]`, `[low]`/`[P3]`. External refs: `cwe:CWE-89`, `capec:CAPEC-66`, `owasp:A03`.
+
+---
+
+## CI Integration
+
+### GitHub Actions
+
+```yaml
+name: GuardLink
+on: [pull_request]
+
+jobs:
+  guardlink:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+
+      - uses: actions/setup-node@v4
+        with: { node-version: '20' }
+
+      - run: npm install -g guardlink
+
+      - name: Validate annotations
+        run: guardlink validate .
+
+      - name: Threat model diff
+        run: guardlink diff --from origin/main --to HEAD
+
+      - name: Export SARIF
+        run: guardlink sarif . -o guardlink.sarif
+
+      - uses: github/codeql-action/upload-sarif@v3
+        with: { sarif_file: guardlink.sarif }
+```
+
+See [`examples/github-action.yml`](examples/github-action.yml) for a full example with PR comments and SARIF upload.
+
+### What CI Catches
+
+- **New route, no annotations:** `guardlink diff` shows "+1 endpoint, 0 mitigations" — the team sees the gap.
+- **Agent annotated properly:** diff shows "+1 asset, +2 mitigations, +1 exposure (IDOR)" — team reviews.
+- **Control removed:** diff shows "-1 mitigation, +1 unmitigated exposure" — `--fail-on-new` blocks the PR.
+
+### SARIF
+
+`guardlink sarif` exports unmitigated exposures as SARIF 2.1.0. Upload to GitHub Advanced Security and every `@exposes` appears as a code scanning alert with file, line, severity, and CWE.
+
+---
+
+## Real-World Results
+
+We tested GuardLink + Claude Code on [vuln-node.js-express.js-app](https://github.com/SirAppSec/vuln-node.js-express.js-app), a deliberately vulnerable Express.js application with 37 documented vulnerability types.
+
+**In 6 minutes, with no human intervention:**
+
+- 143 annotations across 6 route files
+- 29 distinct threats identified with CWE mappings
+- 66 unmitigated exposures documented with file:line precision
+- 27 of 37 known vulnerabilities detected (73% recall, 81% with partial matches)
+- Architecture: 8 assets, 3 data flows, Mermaid diagram with risk heat map
+- Cost: ~$0.50 in Haiku tokens
+
+A scanner gives you a list of findings. GuardLink gives you a threat model — assets, threats, controls, data flows, trust boundaries, and the relationships between them. Every exposure traceable to a line of code. Every mitigation documented next to the control it implements. And because it's all in code comments, it updates when the code changes.
+
+---
+
+## Library API
+
+```typescript
+import { parseProject } from 'guardlink/parser';
+import { generateReport } from 'guardlink/report';
+import { diffModels } from 'guardlink/diff';
+import { generateSarif } from 'guardlink/analyzer';
+import type { ThreatModel } from 'guardlink';
+
+const { model } = await parseProject({ root: '.', project: 'my-app' });
+
+const markdown = generateReport(model);
+const diff = diffModels(oldModel, newModel);
+const sarif = generateSarif(model, '.');
+```
+
+---
+
+## Specification
+
+GuardLink is an open specification. The annotation grammar, threat model schema, and conformance levels are defined in the [GuardLink Specification](docs/SPEC.md).
+
+Anyone can build conformant parsers, analyzers, or integrations. This CLI is the reference implementation.
+
+| Level | Name | Capabilities |
+|-------|------|-------------|
+| L1 | Parser | Parse all 16 annotation types, produce ThreatModel JSON |
+| L2 | Analyzer | Coverage stats, unmitigated detection, dangling ref detection |
+| L3 | CI/CD | Threat model diffs, change classification, SARIF export |
+| L4 | AI-Integrated | MCP server, suggestion engine, agent behavioral directives |
+
+This implementation is **Level 4** conformant.
+
+---
+
+## Heritage
+
+GuardLink builds on the annotation grammar created by [ThreatSpec](https://github.com/threatspec/threatspec) (2015–2020) by Fraser Scott — the first tool to propose continuous threat modeling through code annotations. The core verbs (`@mitigates`, `@exposes`, `@transfers`, `@accepts`) originate from that work.
+
+We extend the specification with severity levels, external references (CWE/CAPEC/OWASP), data flow and trust boundary annotations, data classification, a structured JSON schema, SARIF export, MCP integration for AI agents, and CI/CD enforcement tooling. ThreatSpec had the right idea. Our contribution is making it work in a world where AI writes most of the code.
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE). The GuardLink specification is published under CC-BY-4.0.
+
+---
+
+Built by [BugB Technologies](https://bugb.io).

package/dist/agents/config.d.ts

@@ -0,0 +1,46 @@
+/**
+ * GuardLink Agents — Unified LLM configuration resolution.
+ *
+ * Resolution order (highest to lowest priority):
+ *   1. Explicit flags (--api-key, --provider, --model) — CLI only, never persisted
+ *   2. GUARDLINK_LLM_KEY + GUARDLINK_LLM_PROVIDER env vars
+ *   3. Provider-specific env vars (ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.)
+ *   4. Project config: .guardlink/config.json
+ *   5. Global config: ~/.config/guardlink/config.json
+ *
+ * Replaces the fragmented tui-config.json / CLI flag / env var resolution.
+ */
+import type { LLMConfig, LLMProvider } from '../analyze/llm.js';
+interface SavedConfig {
+    provider?: LLMProvider;
+    model?: string;
+    apiKey?: string;
+}
+/**
+ * Resolve LLM configuration using the unified priority chain.
+ *
+ * @param root  - Project root directory (for project-level config)
+ * @param flags - Explicit CLI flags (highest priority, never persisted)
+ */
+export declare function resolveConfig(root: string, flags?: {
+    provider?: string;
+    model?: string;
+    apiKey?: string;
+}): LLMConfig | null;
+/** Save config to project-level .guardlink/config.json */
+export declare function saveProjectConfig(root: string, cfg: SavedConfig): void;
+/** Save config to global ~/.config/guardlink/config.json */
+export declare function saveGlobalConfig(cfg: SavedConfig): void;
+/** Load project config (new or legacy path) */
+export declare function loadProjectConfig(root: string): SavedConfig | null;
+/** Load global config */
+export declare function loadGlobalConfig(): SavedConfig | null;
+/** Mask an API key for display: sk-ant-***...***xyz */
+export declare function maskKey(key: string): string;
+/** Describe the source of the resolved config */
+export declare function describeConfigSource(root: string, flags?: {
+    provider?: string;
+    apiKey?: string;
+}): string;
+export {};
+//# sourceMappingURL=config.d.ts.map

package/dist/agents/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/agents/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAIhE,UAAU,WAAW;IACnB,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAgDD;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7D,SAAS,GAAG,IAAI,CAmDlB;AAiCD,0DAA0D;AAC1D,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,IAAI,CAEtE;AAED,4DAA4D;AAC5D,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAEvD;AAED,+CAA+C;AAC/C,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAGlE;AAED,yBAAyB;AACzB,wBAAgB,gBAAgB,IAAI,WAAW,GAAG,IAAI,CAErD;AAID,uDAAuD;AACvD,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAG3C;AAED,iDAAiD;AACjD,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7C,MAAM,CAcR"}

package/dist/agents/config.js

@@ -0,0 +1,189 @@
+/**
+ * GuardLink Agents — Unified LLM configuration resolution.
+ *
+ * Resolution order (highest to lowest priority):
+ *   1. Explicit flags (--api-key, --provider, --model) — CLI only, never persisted
+ *   2. GUARDLINK_LLM_KEY + GUARDLINK_LLM_PROVIDER env vars
+ *   3. Provider-specific env vars (ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.)
+ *   4. Project config: .guardlink/config.json
+ *   5. Global config: ~/.config/guardlink/config.json
+ *
+ * Replaces the fragmented tui-config.json / CLI flag / env var resolution.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+const DEFAULT_MODELS = {
+    anthropic: 'claude-sonnet-4-5-20250929',
+    openai: 'gpt-4o',
+    openrouter: 'anthropic/claude-sonnet-4-5-20250929',
+    deepseek: 'deepseek-chat',
+};
+const CONFIG_FILE = 'config.json';
+const LEGACY_CONFIG_FILE = 'tui-config.json';
+// ─── Config file paths ───────────────────────────────────────────────
+/** Project-level config: <root>/.guardlink/config.json */
+function projectConfigPath(root) {
+    return join(root, '.guardlink', CONFIG_FILE);
+}
+/** Legacy project config: <root>/.guardlink/tui-config.json */
+function legacyConfigPath(root) {
+    return join(root, '.guardlink', LEGACY_CONFIG_FILE);
+}
+/** Global config: ~/.config/guardlink/config.json */
+function globalConfigPath() {
+    return join(homedir(), '.config', 'guardlink', CONFIG_FILE);
+}
+// ─── Read/write helpers ──────────────────────────────────────────────
+function readJsonFile(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+function writeJsonFile(path, data) {
+    const dir = join(path, '..');
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    writeFileSync(path, JSON.stringify(data, null, 2) + '\n');
+}
+// ─── Unified resolution ──────────────────────────────────────────────
+/**
+ * Resolve LLM configuration using the unified priority chain.
+ *
+ * @param root  - Project root directory (for project-level config)
+ * @param flags - Explicit CLI flags (highest priority, never persisted)
+ */
+export function resolveConfig(root, flags) {
+    // 1. Explicit flags
+    if (flags?.apiKey && flags?.provider) {
+        const provider = flags.provider;
+        return {
+            provider,
+            model: flags.model || DEFAULT_MODELS[provider] || 'gpt-4o',
+            apiKey: flags.apiKey,
+        };
+    }
+    // 2. GUARDLINK_LLM_KEY + GUARDLINK_LLM_PROVIDER
+    const guardlinkKey = process.env.GUARDLINK_LLM_KEY;
+    const guardlinkProvider = process.env.GUARDLINK_LLM_PROVIDER;
+    if (guardlinkKey) {
+        const provider = guardlinkProvider || detectProviderFromKey(guardlinkKey);
+        if (provider) {
+            return {
+                provider,
+                model: flags?.model || DEFAULT_MODELS[provider],
+                apiKey: guardlinkKey,
+            };
+        }
+    }
+    // 3. Provider-specific env vars
+    const envConfig = resolveFromEnv(flags?.model);
+    if (envConfig)
+        return envConfig;
+    // 4. Project config: .guardlink/config.json (+ legacy tui-config.json)
+    const projectCfg = readJsonFile(projectConfigPath(root))
+        || readJsonFile(legacyConfigPath(root));
+    if (projectCfg?.provider && projectCfg?.apiKey) {
+        return {
+            provider: projectCfg.provider,
+            model: flags?.model || projectCfg.model || DEFAULT_MODELS[projectCfg.provider],
+            apiKey: projectCfg.apiKey,
+        };
+    }
+    // 5. Global config: ~/.config/guardlink/config.json
+    const globalCfg = readJsonFile(globalConfigPath());
+    if (globalCfg?.provider && globalCfg?.apiKey) {
+        return {
+            provider: globalCfg.provider,
+            model: flags?.model || globalCfg.model || DEFAULT_MODELS[globalCfg.provider],
+            apiKey: globalCfg.apiKey,
+        };
+    }
+    return null;
+}
+/** Resolve from provider-specific env vars (ANTHROPIC_API_KEY, etc.) */
+function resolveFromEnv(modelOverride) {
+    const checks = [
+        ['ANTHROPIC_API_KEY', 'anthropic'],
+        ['OPENAI_API_KEY', 'openai'],
+        ['OPENROUTER_API_KEY', 'openrouter'],
+        ['DEEPSEEK_API_KEY', 'deepseek'],
+    ];
+    for (const [envVar, provider] of checks) {
+        const key = process.env[envVar];
+        if (key) {
+            return {
+                provider,
+                model: modelOverride || DEFAULT_MODELS[provider],
+                apiKey: key,
+            };
+        }
+    }
+    return null;
+}
+/** Heuristic: detect provider from API key prefix */
+function detectProviderFromKey(key) {
+    if (key.startsWith('sk-ant-'))
+        return 'anthropic';
+    if (key.startsWith('sk-or-'))
+        return 'openrouter';
+    if (key.startsWith('sk-'))
+        return 'openai'; // OpenAI uses sk- prefix
+    return null; // Can't detect — need GUARDLINK_LLM_PROVIDER
+}
+// ─── Save/load for `guardlink config` and `/model` ──────────────────
+/** Save config to project-level .guardlink/config.json */
+export function saveProjectConfig(root, cfg) {
+    writeJsonFile(projectConfigPath(root), cfg);
+}
+/** Save config to global ~/.config/guardlink/config.json */
+export function saveGlobalConfig(cfg) {
+    writeJsonFile(globalConfigPath(), cfg);
+}
+/** Load project config (new or legacy path) */
+export function loadProjectConfig(root) {
+    return readJsonFile(projectConfigPath(root))
+        || readJsonFile(legacyConfigPath(root));
+}
+/** Load global config */
+export function loadGlobalConfig() {
+    return readJsonFile(globalConfigPath());
+}
+// ─── Display helpers ─────────────────────────────────────────────────
+/** Mask an API key for display: sk-ant-***...***xyz */
+export function maskKey(key) {
+    if (key.length <= 12)
+        return '***';
+    return key.slice(0, 7) + '•'.repeat(8) + key.slice(-3);
+}
+/** Describe the source of the resolved config */
+export function describeConfigSource(root, flags) {
+    if (flags?.apiKey && flags?.provider)
+        return 'CLI flags';
+    if (process.env.GUARDLINK_LLM_KEY)
+        return 'GUARDLINK_LLM_KEY env var';
+    if (process.env.ANTHROPIC_API_KEY)
+        return 'ANTHROPIC_API_KEY env var';
+    if (process.env.OPENAI_API_KEY)
+        return 'OPENAI_API_KEY env var';
+    if (process.env.OPENROUTER_API_KEY)
+        return 'OPENROUTER_API_KEY env var';
+    if (process.env.DEEPSEEK_API_KEY)
+        return 'DEEPSEEK_API_KEY env var';
+    const pc = readJsonFile(projectConfigPath(root));
+    if (pc && Object.keys(pc).length > 0 && pc.provider)
+        return `.guardlink/${CONFIG_FILE}`;
+    const lc = readJsonFile(legacyConfigPath(root));
+    if (lc && Object.keys(lc).length > 0 && lc.provider)
+        return `.guardlink/${LEGACY_CONFIG_FILE} (legacy)`;
+    const gc = readJsonFile(globalConfigPath());
+    if (gc && Object.keys(gc).length > 0 && gc.provider)
+        return `~/.config/guardlink/${CONFIG_FILE}`;
+    return 'none';
+}
+//# sourceMappingURL=config.js.map

package/dist/agents/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/agents/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAWlC,MAAM,cAAc,GAAgC;IAClD,SAAS,EAAE,4BAA4B;IACvC,MAAM,EAAE,QAAQ;IAChB,UAAU,EAAE,sCAAsC;IAClD,QAAQ,EAAE,eAAe;CAC1B,CAAC;AAEF,MAAM,WAAW,GAAG,aAAa,CAAC;AAClC,MAAM,kBAAkB,GAAG,iBAAiB,CAAC;AAE7C,wEAAwE;AAExE,0DAA0D;AAC1D,SAAS,iBAAiB,CAAC,IAAY;IACrC,OAAO,IAAI,CAAC,IAAI,EAAE,YAAY,EAAE,WAAW,CAAC,CAAC;AAC/C,CAAC;AAED,+DAA+D;AAC/D,SAAS,gBAAgB,CAAC,IAAY;IACpC,OAAO,IAAI,CAAC,IAAI,EAAE,YAAY,EAAE,kBAAkB,CAAC,CAAC;AACtD,CAAC;AAED,qDAAqD;AACrD,SAAS,gBAAgB;IACvB,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,CAAC,CAAC;AAC9D,CAAC;AAED,wEAAwE;AAExE,SAAS,YAAY,CAAC,IAAY;IAChC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;IACjD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,aAAa,CAAC,IAAY,EAAE,IAAiB;IACpD,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC7B,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1D,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;AAC5D,CAAC;AAED,wEAAwE;AAExE;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAC3B,IAAY,EACZ,KAA8D;IAE9D,oBAAoB;IACpB,IAAI,KAAK,EAAE,MAAM,IAAI,KAAK,EAAE,QAAQ,EAAE,CAAC;QACrC,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAuB,CAAC;QAC/C,OAAO;YACL,QAAQ;YACR,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,cAAc,CAAC,QAAQ,CAAC,IAAI,QAAQ;YAC1D,MAAM,EAAE,KAAK,CAAC,MAAM;SACrB,CAAC;IACJ,CAAC;IAED,gDAAgD;IAChD,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC;IACnD,MAAM,iBAAiB,GAAG,OAAO,CAAC,GAAG,CAAC,sBAAiD,CAAC;IACxF,IAAI,YAAY,EAAE,CAAC;QACjB,MAAM,QAAQ,GAAG,iBAAiB,IAAI,qBAAqB,CAAC,YAAY,CAAC,CAAC;QAC1E,IAAI,QAAQ,EAAE,CAAC;YACb,OAAO;gBACL,QAAQ;gBACR,KAAK,EAAE,KAAK,EAAE,KAAK,IAAI,cAAc,CAAC,QAAQ,CAAC;gBAC/C,MAAM,EAAE,YAAY;aACrB,CAAC;QACJ,CAAC;IACH,CAAC;IAED,gCAAgC;IAChC,MAAM,SAAS,GAAG,cAAc,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IAC/C,IAAI,SAAS;QAAE,OAAO,SAAS,CAAC;IAEhC,uEAAuE;IACvE,MAAM,UAAU,GAAG,YAAY,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;WACnD,YAAY,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC;IAC1C,IAAI,UAAU,EAAE,QAAQ,IAAI,UAAU,EAAE,MAAM,EAAE,CAAC;QAC/C,OAAO;YACL,QAAQ,EAAE,UAAU,CAAC,QAAQ;YAC7B,KAAK,EAAE,KAAK,EAAE,KAAK,IAAI,UAAU,CAAC,KAAK,IAAI,cAAc,CAAC,UAAU,CAAC,QAAQ,CAAC;YAC9E,MAAM,EAAE,UAAU,CAAC,MAAM;SAC1B,CAAC;IACJ,CAAC;IAED,oDAAoD;IACpD,MAAM,SAAS,GAAG,YAAY,CAAC,gBAAgB,EAAE,CAAC,CAAC;IACnD,IAAI,SAAS,EAAE,QAAQ,IAAI,SAAS,EAAE,MAAM,EAAE,CAAC;QAC7C,OAAO;YACL,QAAQ,EAAE,SAAS,CAAC,QAAQ;YAC5B,KAAK,EAAE,KAAK,EAAE,KAAK,IAAI,SAAS,CAAC,KAAK,IAAI,cAAc,CAAC,SAAS,CAAC,QAAQ,CAAC;YAC5E,MAAM,EAAE,SAAS,CAAC,MAAM;SACzB,CAAC;IACJ,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED,wEAAwE;AACxE,SAAS,cAAc,CAAC,aAAsB;IAC5C,MAAM,MAAM,GAA4B;QACtC,CAAC,mBAAmB,EAAE,WAAW,CAAC;QAClC,CAAC,gBAAgB,EAAE,QAAQ,CAAC;QAC5B,CAAC,oBAAoB,EAAE,YAAY,CAAC;QACpC,CAAC,kBAAkB,EAAE,UAAU,CAAC;KACjC,CAAC;IACF,KAAK,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI,MAAM,EAAE,CAAC;QACxC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAChC,IAAI,GAAG,EAAE,CAAC;YACR,OAAO;gBACL,QAAQ;gBACR,KAAK,EAAE,aAAa,IAAI,cAAc,CAAC,QAAQ,CAAC;gBAChD,MAAM,EAAE,GAAG;aACZ,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,qDAAqD;AACrD,SAAS,qBAAqB,CAAC,GAAW;IACxC,IAAI,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC;QAAE,OAAO,WAAW,CAAC;IAClD,IAAI,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,YAAY,CAAC;IAClD,IAAI,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC;QAAE,OAAO,QAAQ,CAAC,CAAE,yBAAyB;IACtE,OAAO,IAAI,CAAC,CAAE,6CAA6C;AAC7D,CAAC;AAED,uEAAuE;AAEvE,0DAA0D;AAC1D,MAAM,UAAU,iBAAiB,CAAC,IAAY,EAAE,GAAgB;IAC9D,aAAa,CAAC,iBAAiB,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC;AAC9C,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,gBAAgB,CAAC,GAAgB;IAC/C,aAAa,CAAC,gBAAgB,EAAE,EAAE,GAAG,CAAC,CAAC;AACzC,CAAC;AAED,+CAA+C;AAC/C,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,OAAO,YAAY,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;WACvC,YAAY,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC;AAC5C,CAAC;AAED,yBAAyB;AACzB,MAAM,UAAU,gBAAgB;IAC9B,OAAO,YAAY,CAAC,gBAAgB,EAAE,CAAC,CAAC;AAC1C,CAAC;AAED,wEAAwE;AAExE,uDAAuD;AACvD,MAAM,UAAU,OAAO,CAAC,GAAW;IACjC,IAAI,GAAG,CAAC,MAAM,IAAI,EAAE;QAAE,OAAO,KAAK,CAAC;IACnC,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACzD,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,oBAAoB,CAClC,IAAY,EACZ,KAA8C;IAE9C,IAAI,KAAK,EAAE,MAAM,IAAI,KAAK,EAAE,QAAQ;QAAE,OAAO,WAAW,CAAC;IACzD,IAAI,OAAO,CAAC,GAAG,CAAC,iBAAiB;QAAE,OAAO,2BAA2B,CAAC;IACtE,IAAI,OAAO,CAAC,GAAG,CAAC,iBAAiB;QAAE,OAAO,2BAA2B,CAAC;IACtE,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc;QAAE,OAAO,wBAAwB,CAAC;IAChE,IAAI,OAAO,CAAC,GAAG,CAAC,kBAAkB;QAAE,OAAO,4BAA4B,CAAC;IACxE,IAAI,OAAO,CAAC,GAAG,CAAC,gBAAgB;QAAE,OAAO,0BAA0B,CAAC;IACpE,MAAM,EAAE,GAAG,YAAY,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC;IACjD,IAAI,EAAE,IAAI,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,QAAQ;QAAE,OAAO,cAAc,WAAW,EAAE,CAAC;IACxF,MAAM,EAAE,GAAG,YAAY,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC;IAChD,IAAI,EAAE,IAAI,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,QAAQ;QAAE,OAAO,cAAc,kBAAkB,WAAW,CAAC;IACxG,MAAM,EAAE,GAAG,YAAY,CAAC,gBAAgB,EAAE,CAAC,CAAC;IAC5C,IAAI,EAAE,IAAI,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,QAAQ;QAAE,OAAO,uBAAuB,WAAW,EAAE,CAAC;IACjG,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/agents/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * GuardLink Agents — Shared agent registry.
+ *
+ * Used by CLI, TUI, and MCP to identify and resolve coding agents
+ * (Claude Code, Codex, Cursor, Windsurf, Gemini, clipboard).
+ */
+export interface AgentEntry {
+    id: string;
+    name: string;
+    cmd: string | null;
+    app: string | null;
+    flag: string;
+}
+export declare const AGENTS: readonly AgentEntry[];
+/** Parse --agent flags from a raw args string (TUI slash commands). */
+export declare function parseAgentFlag(args: string): {
+    agent: AgentEntry | null;
+    cleanArgs: string;
+};
+/** Resolve agent from Commander option booleans (CLI commands). */
+export declare function agentFromOpts(opts: Record<string, any>): AgentEntry | null;
+export { launchAgentForeground, launchAgentIDE, launchAgent, copyToClipboard } from './launcher.js';
+export { buildAnnotatePrompt } from './prompts.js';
+//# sourceMappingURL=index.d.ts.map