guardlink 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -5,6 +5,32 @@ 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.4.0] — 2026-02-27
+
+### Added
+
+- **Workspace**: Multi-repo workspace support — link N service repos into a unified threat model with cross-repo tag resolution, weekly diff tracking, and merged dashboards
+- **Workspace**: `guardlink link-project <repos...> --workspace <name> --registry <url>` — scaffold workspace.yaml in each repo, auto-detect repo names from git/package.json/Cargo.toml, inject cross-repo context into agent instruction files
+- **Workspace**: `guardlink link-project --add <repo> --from <existing>` — add a repo to an existing workspace with sibling auto-discovery
+- **Workspace**: `guardlink link-project --remove <name> --from <existing>` — remove a repo from workspace, update all siblings found on disk
+- **Workspace**: `guardlink merge <files...>` — merge N per-repo report JSONs into a unified MergedReport with tag registry, cross-repo reference resolution, stale/schema warnings, and aggregated stats
+- **Workspace**: `--diff-against <prev.json>` flag on merge for week-over-week risk tracking (assets/threats/mitigations/exposures added/removed, risk trend, unresolved ref changes)
+- **Workspace**: `-o <file>` dashboard HTML output + `--json <file>` merged JSON output + `--summary-only` text mode
+- **CLI**: `guardlink report --format json` — JSON report output with metadata (repo, workspace, commit SHA, schema version)
+- **TUI**: `/workspace` — show workspace config, sibling repos, registries
+- **TUI**: `/link` — link repos with `--add`/`--remove` support
+- **TUI**: `/merge` — merge reports with `--json`, `--diff-against`, `-o` flags
+- **MCP**: `guardlink_workspace_info` tool — returns workspace name, this_repo identity, sibling tag prefixes, and cross-repo annotation rules for agents
+- **Parser**: External reference detection — scans relationship annotations for tags with dot-prefix matching sibling repo names from workspace.yaml, populates `ThreatModel.external_refs`
+- **Types**: `ExternalRef` interface, `ThreatModel.external_refs` field, `ReportMetadata` with repo/workspace/commit_sha/schema_version
+- **CI**: `examples/ci/per-repo-report.yml` — per-repo workflow: validate on PRs (diff + SARIF + PR comment), generate + upload report JSON on push to main
+- **CI**: `examples/ci/workspace-merge.yml` — weekly workspace merge workflow: download all repo artifacts, merge, dashboard, weekly diff, optional GitHub Pages + Slack
+- **Docs**: `docs/WORKSPACE.md` — multi-repo setup guide, workspace.yaml spec, cross-repo annotation rules, merge behavior, CI integration, weekly workflow
+
+### Changed
+
+- **MCP**: Server version bumped to 1.4.0
+
 ## [1.3.0] — 2026-02-27
 
 ### Added

package/README.md

@@ -151,6 +151,7 @@ GuardLink ships an MCP server and behavioral directives for AI coding agents. Af
 | `guardlink_dashboard` | Generate HTML dashboard |
 | `guardlink_sarif` | Export SARIF 2.1.0 |
 | `guardlink_diff` | Compare threat model against a git ref |
+| `guardlink_workspace_info` | Workspace config, sibling repos, tag prefixes for cross-repo annotations |
 
 **Resources:** `guardlink://model`, `guardlink://definitions`, `guardlink://config`
 
@@ -179,6 +180,11 @@ GuardLink ships an MCP server and behavioral directives for AI coding agents. Af
 | `guardlink clear [dir]` | Remove all annotations from source files (with `--dry-run` preview) |
 | `guardlink sync [dir]` | Sync agent instruction files with current threat model |
 | `guardlink unannotated [dir]` | List source files with no annotations |
+| `guardlink link-project <repos...>` | Link repos into a shared workspace for cross-repo threat modeling |
+| `guardlink link-project --add <repo>` | Add a repo to an existing workspace |
+| `guardlink link-project --remove <name>` | Remove a repo from a workspace |
+| `guardlink merge <files...>` | Merge per-repo report JSONs into a unified workspace dashboard |
+| `guardlink report --format json` | Generate report JSON with metadata (repo, workspace, commit SHA) |
 | `guardlink config` | Set AI provider and API key |
 | `guardlink mcp` | Start MCP server for AI agent integration |
 
@@ -282,6 +288,10 @@ jobs:
 
 See [`examples/github-action.yml`](examples/github-action.yml) for a full example with PR comments and SARIF upload.
 
+### Multi-Repo CI
+
+For workspace setups, GuardLink provides two additional workflow templates: a per-repo workflow that generates report JSON artifacts on every push, and a workspace merge workflow that runs weekly to combine all repos into a unified dashboard. See the [CI setup guide](examples/ci/README.md) for step-by-step instructions.
+
 ### What CI Catches
 
 - **New route, no annotations:** `guardlink diff` shows "+1 endpoint, 0 mitigations" — the team sees the gap.
@@ -294,6 +304,35 @@ See [`examples/github-action.yml`](examples/github-action.yml) for a full exampl
 
 ---
 
+## Multi-Repo Workspaces
+
+In microservices architectures, a single repo only has part of the security picture. `PaymentService` is defined in `repo-payments`, exposed in `repo-gateway`, mitigated in `repo-auth-lib`. GuardLink workspaces link these repos so the threat model spans service boundaries.
+
+```bash
+# Link three repos into a workspace
+guardlink link-project ./payment-svc ./auth-lib ./api-gateway \
+  --workspace acme-platform
+
+# Each repo gets .guardlink/workspace.yaml + agent files updated with cross-repo context
+# Agents now know about sibling services and use tag prefixes like #payment-svc.refund
+
+# Generate per-repo JSON reports (in each repo or in CI)
+guardlink report --format json -o guardlink-report.json
+
+# Merge all reports into a unified dashboard
+guardlink merge payment-svc.json auth-lib.json api-gateway.json \
+  -o dashboard.html --json merged.json
+
+# Week-over-week diff for security leads
+guardlink merge *.json --diff-against last-week.json --json merged.json
+```
+
+Annotations reference sibling repos by tag prefix — `@flows #request from #api-gateway.router to #payment-svc.refund` — and these references resolve during merge. `guardlink validate` flags them as external refs locally, but they're expected and won't block CI.
+
+For automated weekly dashboards, see the [CI setup guide](examples/ci/README.md). Full workspace documentation: [docs/WORKSPACE.md](docs/WORKSPACE.md).
+
+---
+
 ## 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.

package/dist/cli/index.d.ts

@@ -18,6 +18,8 @@
  *   guardlink mcp                     Start MCP server (stdio) for Claude Code, Cursor, etc.
  *   guardlink tui [dir]               Interactive TUI with slash commands + AI chat
  *   guardlink gal                     Display GAL annotation language quick reference
+ *   guardlink link-project <repos...>  Link repos into a shared workspace
+ *   guardlink merge <files...>         Merge repo reports into unified dashboard
  *
  * @exposes #cli to #path-traversal [high] cwe:CWE-22 -- "User-supplied dir argument resolved via path.resolve"
  * @mitigates #cli against #path-traversal using #path-validation -- "resolve() canonicalizes paths; cwd-relative by design"

package/dist/cli/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG"}

package/dist/cli/index.js

@@ -18,6 +18,8 @@
  *   guardlink mcp                     Start MCP server (stdio) for Claude Code, Cursor, etc.
  *   guardlink tui [dir]               Interactive TUI with slash commands + AI chat
  *   guardlink gal                     Display GAL annotation language quick reference
+ *   guardlink link-project <repos...>  Link repos into a shared workspace
+ *   guardlink merge <files...>         Merge repo reports into unified dashboard
  *
  * @exposes #cli to #path-traversal [high] cwe:CWE-22 -- "User-supplied dir argument resolved via path.resolve"
  * @mitigates #cli against #path-traversal using #path-validation -- "resolve() canonicalizes paths; cwd-relative by design"
@@ -46,6 +48,7 @@ import { generateDashboardHTML } from '../dashboard/index.js';
 import { AGENTS, agentFromOpts, launchAgent, launchAgentInline, buildAnnotatePrompt } from '../agents/index.js';
 import { resolveConfig, saveProjectConfig, saveGlobalConfig, loadProjectConfig, loadGlobalConfig, maskKey, describeConfigSource } from '../agents/config.js';
 import { getReviewableExposures, applyReviewAction, formatExposureForReview, summarizeReview } from '../review/index.js';
+import { populateMetadata, mergeReports, formatMergeSummary, diffMergedReports, formatDiffSummary, linkProject, addToWorkspace, removeFromWorkspace } from '../workspace/index.js';
 import gradient from 'gradient-string';
 const program = new Command();
 const ASCII_LOGO = `
@@ -266,9 +269,10 @@ program
     .description('Generate a threat model report with Mermaid diagram')
     .argument('[dir]', 'Project directory to scan', '.')
     .option('-p, --project <n>', 'Project name', 'unknown')
-    .option('-o, --output <file>', 'Write report to file (default: threat-model.md)')
+    .option('-o, --output <file>', 'Write report to file')
+    .option('-f, --format <fmt>', 'Output format: md, json, or both (default: md)', 'md')
     .option('--diagram-only', 'Output only the Mermaid diagram, no report wrapper')
-    .option('--json', 'Also output threat-model.json alongside the report')
+    .option('--json', 'Also output threat-model.json alongside the report (legacy; prefer --format)')
     .action(async (dir, opts) => {
     const root = resolve(dir);
     const { model, diagnostics } = await parseProject({ root, project: opts.project });
@@ -278,9 +282,11 @@ program
         printDiagnostics(errors);
         console.error(`Fix errors above before generating report.\n`);
     }
+    // Enrich with provenance metadata (git SHA, branch, workspace, schema version)
+    const enrichedModel = populateMetadata(model, root);
     if (opts.diagramOnly) {
         // Just output Mermaid
-        const mermaid = generateMermaid(model);
+        const mermaid = generateMermaid(enrichedModel);
         if (opts.output) {
             const { writeFile } = await import('node:fs/promises');
             await writeFile(opts.output, mermaid + '\n');
@@ -289,19 +295,23 @@ program
         else {
             console.log(mermaid);
         }
+        return;
     }
-    else {
-        // Full report
-        const report = generateReport(model);
-        const outFile = opts.output || 'threat-model.md';
-        const { writeFile } = await import('node:fs/promises');
-        await writeFile(resolve(root, outFile), report + '\n');
-        console.error(`✓ Wrote threat model report to ${outFile}`);
-        if (opts.json) {
-            const jsonFile = outFile.replace(/\.md$/, '.json');
-            await writeFile(resolve(root, jsonFile), JSON.stringify(model, null, 2) + '\n');
-            console.error(`✓ Wrote threat model JSON to ${jsonFile}`);
-        }
+    const { writeFile } = await import('node:fs/promises');
+    const wantJson = opts.format === 'json' || opts.format === 'both' || opts.json;
+    const wantMd = opts.format === 'md' || opts.format === 'both' || opts.json;
+    if (wantMd) {
+        const report = generateReport(enrichedModel);
+        const mdFile = opts.output || (opts.format === 'md' ? 'threat-model.md' : 'threat-model.md');
+        await writeFile(resolve(root, mdFile), report + '\n');
+        console.error(`✓ Wrote threat model report to ${mdFile}`);
+    }
+    if (wantJson) {
+        const jsonFile = opts.output && opts.format === 'json'
+            ? opts.output
+            : (opts.output || 'threat-model').replace(/\.md$/, '') + '.json';
+        await writeFile(resolve(root, jsonFile), JSON.stringify(enrichedModel, null, 2) + '\n');
+        console.error(`✓ Wrote threat model JSON to ${jsonFile} (schema v${enrichedModel.metadata?.schema_version})`);
     }
 });
 // ─── diff ────────────────────────────────────────────────────────────
@@ -971,6 +981,224 @@ program
     console.error(`✓ Dashboard generated: ${outFile}`);
     console.error(`  Open in browser to view. Toggle ☀️/🌙 for light/dark mode.`);
 });
+// ─── link-project ────────────────────────────────────────────────────
+program
+    .command('link-project')
+    .description('Link repos into a shared workspace for cross-repo threat modeling')
+    .argument('[repos...]', 'Repo directories to link (fresh setup: 2+ paths)')
+    .option('-w, --workspace <n>', 'Workspace name (fresh link only)', 'workspace')
+    .option('-r, --registry <url>', 'GitHub/GitLab org base URL (e.g. github.com/unstructured)')
+    .option('--add <path>', 'Add a new repo to an existing workspace (provide path to new repo)')
+    .option('--remove <name>', 'Remove a repo from the workspace by name')
+    .option('--from <path>', 'Existing workspace repo to read config from (used with --add or --remove)')
+    .action(async (repos, opts) => {
+    let result;
+    if (opts.remove) {
+        // ── Remove mode: remove a repo from an existing workspace ──
+        if (!opts.from) {
+            console.error('⚠ --remove requires --from <existing-workspace-repo-path>');
+            console.error('  Example: guardlink link-project --remove payment-svc --from ./api-gateway');
+            process.exit(1);
+        }
+        console.error(`Removing "${opts.remove}" from workspace...`);
+        console.error(`  Reference repo: ${opts.from}`);
+        console.error('');
+        result = removeFromWorkspace({
+            repoName: opts.remove,
+            existingRepoPath: opts.from,
+        });
+        for (const name of result.updated) {
+            console.error(`  ↻ ${name} — workspace.yaml updated`);
+        }
+        for (const f of result.agentFilesUpdated) {
+            if (f.includes('(cleaned)'))
+                console.error(`  🧹 ${f}`);
+        }
+        for (const s of result.skipped) {
+            console.error(`  ✗ ${s.name} — ${s.reason}`);
+        }
+        console.error('');
+        if (result.updated.length > 0) {
+            console.error(`✓ Removed "${opts.remove}", updated ${result.updated.length} remaining repo(s)`);
+            console.error('');
+            console.error('Next steps:');
+            console.error('  1. Review and commit changes in each updated repo');
+        }
+        else if (result.skipped.length > 0) {
+            process.exit(1);
+        }
+    }
+    else if (opts.add) {
+        // ── Add mode: add a new repo to an existing workspace ──
+        if (!opts.from) {
+            console.error('⚠ --add requires --from <existing-workspace-repo-path>');
+            console.error('  Example: guardlink link-project --add ./new-service --from ./api-gateway');
+            process.exit(1);
+        }
+        console.error(`Adding repo to existing workspace...`);
+        console.error(`  New repo:      ${opts.add}`);
+        console.error(`  From workspace: ${opts.from}`);
+        console.error('');
+        result = addToWorkspace({
+            newRepoPath: opts.add,
+            existingRepoPath: opts.from,
+            registry: opts.registry,
+        });
+        // Report results
+        for (const name of result.initialized) {
+            console.error(`  ⚡ ${name} — auto-initialized (no prior guardlink setup)`);
+        }
+        for (const name of result.linked) {
+            console.error(`  ✓ ${name} — linked to workspace`);
+        }
+        for (const name of result.updated) {
+            console.error(`  ↻ ${name} — workspace.yaml updated`);
+        }
+        for (const s of result.skipped) {
+            console.error(`  ✗ ${s.name} — skipped: ${s.reason}`);
+        }
+        console.error('');
+        if (result.linked.length > 0 || result.updated.length > 0) {
+            const total = result.linked.length + result.updated.length;
+            console.error(`✓ ${result.linked.length} repo(s) added, ${result.updated.length} existing repo(s) updated`);
+            if (result.agentFilesUpdated.length > 0) {
+                console.error(`  ↻ Updated ${result.agentFilesUpdated.length} agent instruction file(s)`);
+            }
+            // Warn about repos not found on disk
+            // (they're in workspace.yaml but we couldn't locate their directory)
+            console.error('');
+            console.error('Next steps:');
+            console.error('  1. Review and commit changes in each updated repo');
+            console.error('  2. Add "guardlink report --format json" to the new repo\'s CI');
+            console.error('  3. Run "guardlink merge" with all repo reports');
+        }
+        else {
+            console.error('✗ No repos were added. Check the paths provided.');
+            process.exit(1);
+        }
+    }
+    else {
+        // ── Fresh link mode: link N repos together ──
+        if (repos.length < 2) {
+            console.error('⚠ Fresh linking requires at least 2 repo paths.');
+            console.error('  To add a repo to an existing workspace, use:');
+            console.error('  guardlink link-project --add <new-repo> --from <existing-repo>');
+            process.exit(1);
+        }
+        console.error(`Linking ${repos.length} repos into workspace "${opts.workspace}"...`);
+        console.error('');
+        result = linkProject({
+            workspace: opts.workspace,
+            repoPaths: repos,
+            registry: opts.registry,
+        });
+        for (const name of result.initialized) {
+            console.error(`  ⚡ ${name} — auto-initialized (no prior guardlink setup)`);
+        }
+        for (const name of result.linked) {
+            console.error(`  ✓ ${name} — workspace.yaml written, agent files updated`);
+        }
+        for (const s of result.skipped) {
+            console.error(`  ✗ ${s.name} — skipped: ${s.reason}`);
+        }
+        console.error('');
+        if (result.linked.length > 0) {
+            console.error(`✓ Linked ${result.linked.length} repo(s) into "${opts.workspace}"`);
+            if (result.agentFilesUpdated.length > 0) {
+                console.error(`  ↻ Updated ${result.agentFilesUpdated.length} agent instruction file(s)`);
+            }
+            console.error('');
+            console.error('Next steps:');
+            console.error('  1. Review and commit .guardlink/workspace.yaml in each repo');
+            console.error('  2. Add "guardlink report --format json -o guardlink-report.json" to each repo\'s CI');
+            console.error('  3. Use "guardlink merge" to combine reports into a unified dashboard');
+        }
+        else {
+            console.error('✗ No repos were linked. Check the paths provided.');
+            process.exit(1);
+        }
+    }
+});
+// ─── merge ───────────────────────────────────────────────────────────
+program
+    .command('merge')
+    .description('Merge multiple repo report JSONs into a unified workspace threat model')
+    .argument('<files...>', 'Report JSON file paths (glob supported)')
+    .option('-o, --output <file>', 'Output file for merged dashboard HTML (default: workspace-dashboard.html)')
+    .option('--json <file>', 'Also write merged report JSON to this file')
+    .option('--diff-against <file>', 'Compare against a previous merged JSON for weekly summary')
+    .option('-w, --workspace <name>', 'Workspace name (auto-detected from reports if not set)')
+    .option('--summary-only', 'Print only the text summary, skip dashboard generation')
+    .action(async (files, opts) => {
+    const { writeFile, readFile } = await import('node:fs/promises');
+    const { resolve: resolvePath } = await import('node:path');
+    // Resolve file paths (support globs via shell expansion — files already expanded by shell)
+    const resolvedFiles = files.map(f => resolvePath(f));
+    if (resolvedFiles.length === 0) {
+        console.error('✗ No report files provided.');
+        process.exit(1);
+    }
+    console.error(`Merging ${resolvedFiles.length} report(s)...`);
+    // Run merge
+    const merged = await mergeReports(resolvedFiles, {
+        workspace: opts.workspace,
+    });
+    const t = merged.totals;
+    // Print summary to stderr
+    console.error('');
+    console.error(`✓ ${merged.workspace} — ${t.repos_loaded}/${t.repos} repos loaded`);
+    console.error(`  ${t.annotations} annotations | ${t.assets} assets | ${t.threats} threats | ${t.controls} controls`);
+    console.error(`  ${t.mitigations} mitigations | ${t.exposures} exposures | ${t.unmitigated_exposures} unmitigated`);
+    console.error(`  ${t.flows} flows | ${t.external_refs_resolved} refs resolved | ${t.external_refs_unresolved} unresolved`);
+    // Print warnings
+    for (const w of merged.warnings) {
+        const icon = w.level === 'error' ? '✗' : w.level === 'warning' ? '⚠' : 'ℹ';
+        console.error(`  ${icon} ${w.message}`);
+    }
+    console.error('');
+    // Write merged JSON
+    if (opts.json) {
+        const jsonPath = resolvePath(opts.json);
+        await writeFile(jsonPath, JSON.stringify(merged, null, 2) + '\n');
+        console.error(`✓ Wrote merged JSON to ${opts.json}`);
+    }
+    // Diff against previous
+    if (opts.diffAgainst) {
+        try {
+            const prevRaw = await readFile(resolvePath(opts.diffAgainst), 'utf-8');
+            const previous = JSON.parse(prevRaw);
+            const diff = diffMergedReports(merged, previous);
+            const diffMd = formatDiffSummary(diff, merged.workspace);
+            // Write diff markdown
+            const diffFile = (opts.json || 'workspace-merge').replace(/\.json$/, '') + '-weekly-diff.md';
+            await writeFile(resolvePath(diffFile), diffMd + '\n');
+            console.error(`✓ Wrote weekly diff to ${diffFile}`);
+            // Also print a compact version to stderr
+            const riskIcon = diff.risk_delta === 'increased' ? '🔴'
+                : diff.risk_delta === 'decreased' ? '🟢' : '⚪';
+            console.error(`  ${riskIcon} Risk ${diff.risk_delta} since last merge`);
+            if (diff.new_unmitigated > 0)
+                console.error(`  🔴 +${diff.new_unmitigated} new unmitigated exposure(s)`);
+            if (diff.resolved_unmitigated > 0)
+                console.error(`  🟢 ${diff.resolved_unmitigated} exposure(s) now mitigated`);
+            if (diff.mitigations_removed > 0)
+                console.error(`  ⚠️  ${diff.mitigations_removed} mitigation(s) removed`);
+            console.error('');
+        }
+        catch (err) {
+            console.error(`⚠ Could not diff against ${opts.diffAgainst}: ${err instanceof Error ? err.message : err}`);
+        }
+    }
+    // Generate dashboard HTML (unless --summary-only)
+    if (!opts.summaryOnly) {
+        const html = generateDashboardHTML(merged.model);
+        const outFile = opts.output || 'workspace-dashboard.html';
+        await writeFile(resolvePath(outFile), html);
+        console.error(`✓ Wrote workspace dashboard to ${outFile}`);
+    }
+    // Print full markdown summary to stdout (pipeable)
+    console.log(formatMergeSummary(merged));
+});
 // ─── mcp ─────────────────────────────────────────────────────────────
 program
     .command('mcp')