@windyroad/c4 0.2.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "wr-c4",
+  "version": "0.1.0",
+  "description": "C4 architecture diagram generation and validation for Claude Code"
+}

package/bin/install.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const utils = await import(resolve(__dirname, "../../shared/install-utils.mjs"));
+
+const PLUGIN = "wr-c4";
+const DEPS = [];
+
+const flags = utils.parseStandardArgs(process.argv);
+
+if (flags.help) {
+  console.log(`
+Usage: npx @windyroad/c4 [options]
+
+C4 architecture diagram generation and validation
+
+Options:
+  --update     Update this plugin and its skills
+  --uninstall  Remove this plugin
+  --dry-run    Show what would be done without executing
+  --help, -h   Show this help
+`);
+  process.exit(0);
+}
+
+if (flags.dryRun) {
+  utils.setDryRun(true);
+  console.log("[dry-run mode — no commands will be executed]\n");
+}
+
+utils.checkPrerequisites();
+
+if (flags.uninstall) {
+  utils.uninstallPackage(PLUGIN);
+} else if (flags.update) {
+  utils.updatePackage(PLUGIN);
+} else {
+  utils.installPackage(PLUGIN, { deps: DEPS });
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@windyroad/c4",
+  "version": "0.2.0",
+  "description": "C4 architecture diagram generation and validation",
+  "bin": {
+    "windyroad-c4": "./bin/install.mjs"
+  },
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/windyroad/agent-plugins.git",
+    "directory": "packages/c4"
+  },
+  "keywords": [
+    "claude-code",
+    "claude-code-plugin",
+    "ai-agent",
+    "ai-coding"
+  ],
+  "files": [
+    "bin/",
+    "agents/",
+    "hooks/",
+    "skills/",
+    ".claude-plugin/"
+  ]
+}

package/skills/wr:c4/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: wr:c4
+description: Regenerate C4 architecture diagrams (C3 component + C4 code views) from source code
+allowed-tools: Bash(node *)
+---
+
+Run the C4 generator script to regenerate architecture diagrams from source code:
+
+```
+node ${CLAUDE_SKILL_DIR}/scripts/c4-generate.mjs
+```
+
+Report what files changed. Do not commit.
+
+$ARGUMENTS

package/skills/wr:c4/scripts/c4-generate.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+
+/**
+ * c4-generate.mjs — Regenerate C4 architecture diagrams from source code.
+ * Portable, self-contained (no npm deps). Run via: node c4-generate.mjs
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { detectSourceRoot, buildModel, toC3Mermaid, toC4Mermaid, toJson } from "./c4-lib.mjs";
+
+const ROOT = process.cwd();
+const OUT_DIR = path.join(ROOT, "docs", "architecture", "generated");
+const OUT_JSON = path.join(OUT_DIR, "components.json");
+const OUT_MERMAID = path.join(OUT_DIR, "components.mmd");
+const C4_MODEL = path.join(ROOT, "docs", "architecture", "C4_MODEL.md");
+
+const C3_START = "<!-- c3:generated:start -->";
+const C3_END = "<!-- c3:generated:end -->";
+const C4_START = "<!-- c4:generated:start -->";
+const C4_END = "<!-- c4:generated:end -->";
+
+const C4_SCAFFOLD = `# C4 Architecture Model
+
+This repo uses a hybrid C4 approach:
+- C1/C2 are curated for intent and business context.
+- C3/C4 are generated from code to reduce drift.
+
+## C3: Component View (Generated)
+
+${C3_START}
+
+${C3_END}
+
+## C4: Code View (Generated)
+
+File-level dependency diagrams per component. Dashed arrows indicate cross-component imports. Grey nodes are external files.
+
+${C4_START}
+
+${C4_END}
+
+Regenerate: \`/c4\`
+Check freshness: \`/c4-check\`
+`;
+
+function inlineGenerated(startMarker, endMarker, content) {
+  if (!fs.existsSync(C4_MODEL)) return;
+  const doc = fs.readFileSync(C4_MODEL, "utf8");
+  const startIdx = doc.indexOf(startMarker);
+  const endIdx = doc.indexOf(endMarker);
+  if (startIdx === -1 || endIdx === -1) return;
+
+  const before = doc.slice(0, startIdx + startMarker.length);
+  const after = doc.slice(endIdx);
+  const updated = `${before}\n\n${content}\n\n${after}`;
+  fs.writeFileSync(C4_MODEL, updated);
+}
+
+function main() {
+  const srcRoot = detectSourceRoot(ROOT);
+  const model = buildModel(srcRoot);
+  const json = toJson(model);
+  const c3Mermaid = toC3Mermaid(model);
+  const c4Mermaid = toC4Mermaid(model);
+
+  fs.mkdirSync(OUT_DIR, { recursive: true });
+
+  // Create scaffold if C4_MODEL.md doesn't exist
+  if (!fs.existsSync(C4_MODEL)) {
+    fs.mkdirSync(path.dirname(C4_MODEL), { recursive: true });
+    fs.writeFileSync(C4_MODEL, C4_SCAFFOLD);
+  }
+
+  fs.writeFileSync(OUT_JSON, json);
+  fs.writeFileSync(OUT_MERMAID, c3Mermaid);
+  inlineGenerated(C3_START, C3_END, `\`\`\`mermaid\n${c3Mermaid.trimEnd()}\n\`\`\``);
+  inlineGenerated(C4_START, C4_END, c4Mermaid);
+
+  console.log("PASS: C4 artifacts generated:");
+  console.log(`- ${path.relative(ROOT, OUT_JSON)}`);
+  console.log(`- ${path.relative(ROOT, OUT_MERMAID)}`);
+  console.log(`- ${path.relative(ROOT, C4_MODEL)} (C3 + C4 sections updated)`);
+}
+
+main();

package/skills/wr:c4/scripts/c4-lib.mjs

@@ -0,0 +1,259 @@
+/**
+ * c4-lib.mjs — Portable C4 model builder (pure Node.js, no npm deps).
+ * Shared by c4-generate.mjs and c4-check.mjs.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+// ---------------------------------------------------------------------------
+// Source root detection
+// ---------------------------------------------------------------------------
+
+export function detectSourceRoot(projectRoot) {
+  // 1. Try tsconfig.json
+  const tsconfigPath = path.join(projectRoot, "tsconfig.json");
+  if (fs.existsSync(tsconfigPath)) {
+    try {
+      const raw = fs.readFileSync(tsconfigPath, "utf8");
+      // Strip single-line comments for lenient JSON parse
+      const stripped = raw.replace(/\/\/.*$/gm, "");
+      const tsconfig = JSON.parse(stripped);
+      const rootDir = tsconfig?.compilerOptions?.rootDir;
+      if (rootDir) {
+        const candidate = path.resolve(projectRoot, rootDir);
+        if (fs.existsSync(candidate)) return candidate;
+      }
+      const includes = tsconfig?.include;
+      if (Array.isArray(includes) && includes.length > 0) {
+        // Strip glob suffixes like /**/*
+        const first = includes[0].replace(/\/\*.*$/, "");
+        const candidate = path.resolve(projectRoot, first);
+        if (fs.existsSync(candidate)) return candidate;
+      }
+    } catch {
+      // Fall through to probing
+    }
+  }
+
+  // 2. Probe common directories
+  for (const probe of ["app/src", "src", "lib"]) {
+    const candidate = path.join(projectRoot, probe);
+    if (fs.existsSync(candidate)) return candidate;
+  }
+
+  // 3. Fall back to project root
+  const fallback = projectRoot;
+
+  // 4. Verify .ts files exist somewhere
+  if (!hasFilesWithExtension(fallback, ".ts")) {
+    for (const [ext, lang] of [[".py", "Python"], [".go", "Go"], [".rs", "Rust"], [".java", "Java"]]) {
+      if (hasFilesWithExtension(fallback, ext)) {
+        throw new Error(`C4 generation does not yet support ${lang} projects`);
+      }
+    }
+    throw new Error("No TypeScript source files found");
+  }
+
+  return fallback;
+}
+
+function hasFilesWithExtension(dir, ext) {
+  try {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (hasFilesWithExtension(full, ext)) return true;
+      } else if (entry.isFile() && entry.name.endsWith(ext)) {
+        return true;
+      }
+    }
+  } catch {
+    // Directory not readable
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// File walking
+// ---------------------------------------------------------------------------
+
+function walk(dir, out) {
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walk(full, out);
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    if (!entry.name.endsWith(".ts") || entry.name.endsWith(".test.ts")) continue;
+    out.push(full);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Import parsing & resolution
+// ---------------------------------------------------------------------------
+
+function parseImports(text) {
+  const specs = [];
+  const importRe = /import\s+[^"']*?["']([^"']+)["']/g;
+  const dynamicRe = /import\(\s*["']([^"']+)["']\s*\)/g;
+  const requireRe = /require\(\s*["']([^"']+)["']\s*\)/g;
+  let match;
+  while ((match = importRe.exec(text)) !== null) specs.push(match[1]);
+  while ((match = dynamicRe.exec(text)) !== null) specs.push(match[1]);
+  while ((match = requireRe.exec(text)) !== null) specs.push(match[1]);
+  return specs;
+}
+
+function resolveImport(fromFile, spec, srcRoot) {
+  if (!spec.startsWith(".")) return null;
+  const stripped = spec.replace(/\.js$/, "");
+  const base = path.resolve(path.dirname(fromFile), stripped);
+  const candidates = [base, `${base}.ts`, path.join(base, "index.ts")];
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Model building
+// ---------------------------------------------------------------------------
+
+function relToSrc(absPath, srcRoot) {
+  return path.relative(srcRoot, absPath).split(path.sep).join("/");
+}
+
+function componentIdForRel(rel) {
+  const [first] = rel.split("/");
+  if (!first || !rel.includes("/")) return "app";
+  return first;
+}
+
+export function buildModel(srcRoot) {
+  const files = [];
+  walk(srcRoot, files);
+
+  const componentFiles = new Map();
+  const dependencies = new Map();
+  const fileDeps = [];
+
+  for (const absFile of files) {
+    const fromRel = relToSrc(absFile, srcRoot);
+    const fromComp = componentIdForRel(fromRel);
+
+    if (!componentFiles.has(fromComp)) componentFiles.set(fromComp, new Set());
+    componentFiles.get(fromComp).add(fromRel);
+
+    if (!dependencies.has(fromComp)) dependencies.set(fromComp, new Set());
+
+    const text = fs.readFileSync(absFile, "utf8");
+    const specs = parseImports(text);
+    for (const spec of specs) {
+      const resolved = resolveImport(absFile, spec, srcRoot);
+      if (!resolved) continue;
+      const toRel = relToSrc(resolved, srcRoot);
+      const toComp = componentIdForRel(toRel);
+      fileDeps.push({ from: fromRel, to: toRel });
+      if (toComp !== fromComp) dependencies.get(fromComp).add(toComp);
+    }
+  }
+
+  const components = [...componentFiles.keys()]
+    .sort()
+    .map((id) => ({
+      id,
+      name: id === "app" ? "app-entry" : id,
+      kind: "generated",
+      files: [...(componentFiles.get(id) || [])].sort(),
+      depends_on: [...(dependencies.get(id) || [])].sort(),
+    }));
+
+  return {
+    generator_version: "1",
+    source_root: path.relative(process.cwd(), srcRoot).split(path.sep).join("/") || ".",
+    components,
+    fileDeps,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Mermaid generation
+// ---------------------------------------------------------------------------
+
+export function toC3Mermaid(model) {
+  const lines = ["flowchart LR"];
+  for (const component of model.components) {
+    lines.push(`  ${component.id}["${component.name}"]`);
+  }
+  for (const component of model.components) {
+    for (const to of component.depends_on) {
+      lines.push(`  ${component.id} --> ${to}`);
+    }
+  }
+  lines.push("");
+  return `${lines.join("\n")}\n`;
+}
+
+function fileNodeId(relPath) {
+  return relPath.replace(/[/.\\-]/g, "_").replace(/\.ts$/, "");
+}
+
+function fileLabel(relPath) {
+  return path.basename(relPath, ".ts");
+}
+
+export function toC4Mermaid(model) {
+  const sections = [];
+
+  for (const component of model.components) {
+    const lines = ["flowchart LR"];
+    const fileSet = new Set(component.files);
+
+    for (const file of component.files) {
+      lines.push(`  ${fileNodeId(file)}["${fileLabel(file)}"]`);
+    }
+
+    const externalNodes = new Set();
+    const edges = new Set();
+
+    for (const dep of model.fileDeps) {
+      if (!fileSet.has(dep.from)) continue;
+      const edgeKey = `${dep.from}|${dep.to}`;
+      if (edges.has(edgeKey)) continue;
+      edges.add(edgeKey);
+
+      if (fileSet.has(dep.to)) {
+        lines.push(`  ${fileNodeId(dep.from)} --> ${fileNodeId(dep.to)}`);
+      } else {
+        const toCompId = componentIdForRel(dep.to);
+        const toComp = toCompId === "app" ? "app-entry" : toCompId;
+        const extId = fileNodeId(dep.to);
+        if (!externalNodes.has(dep.to)) {
+          externalNodes.add(dep.to);
+          lines.push(`  ${extId}["${toComp}/${fileLabel(dep.to)}"]:::ext`);
+        }
+        lines.push(`  ${fileNodeId(dep.from)} -.-> ${extId}`);
+      }
+    }
+
+    if (externalNodes.size > 0) {
+      lines.push(`  classDef ext fill:#f0f0f0,stroke:#999,stroke-dasharray:5 5`);
+    }
+
+    lines.push("");
+    sections.push(`### ${component.name}\n\n\`\`\`mermaid\n${lines.join("\n")}\n\`\`\``);
+  }
+
+  return sections.join("\n\n");
+}
+
+export function toJson(model) {
+  return `${JSON.stringify(model, null, 2)}\n`;
+}

package/skills/wr:c4-check/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: wr:c4-check
+description: Check whether C4 architecture diagrams are up to date with source code
+allowed-tools: Bash(node *)
+---
+
+Run the C4 check script to verify architecture diagrams are current:
+
+```
+node ${CLAUDE_SKILL_DIR}/scripts/c4-check.mjs
+```
+
+Report PASS or FAIL with details.
+
+$ARGUMENTS

package/skills/wr:c4-check/scripts/c4-check.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+
+/**
+ * c4-check.mjs — Check whether C4 architecture diagrams are up to date.
+ * Portable, self-contained (no npm deps). Run via: node c4-check.mjs
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { detectSourceRoot, buildModel, toJson } from "../../c4/scripts/c4-lib.mjs";
+
+const ROOT = process.cwd();
+const COMPONENTS_FILE = path.join(ROOT, "docs", "architecture", "generated", "components.json");
+const POLICY_FILE = path.join(ROOT, "governance", "architecture-conformance-policy.json");
+
+function main() {
+  const srcRoot = detectSourceRoot(ROOT);
+  const model = buildModel(srcRoot);
+  const freshJson = toJson(model);
+  const failures = [];
+
+  // 1. Compare JSON against existing components.json
+  if (!fs.existsSync(COMPONENTS_FILE)) {
+    failures.push("missing generated architecture model: docs/architecture/generated/components.json");
+  } else {
+    const existingJson = fs.readFileSync(COMPONENTS_FILE, "utf8");
+    if (existingJson !== freshJson) {
+      failures.push("C4 model is stale — run /c4 to regenerate");
+    }
+  }
+
+  // 2. Conformance policy check (if policy file exists)
+  if (fs.existsSync(POLICY_FILE)) {
+    const policy = JSON.parse(fs.readFileSync(POLICY_FILE, "utf8"));
+    const components = new Map();
+    for (const component of model.components) {
+      components.set(component.id, new Set(component.depends_on || []));
+    }
+
+    for (const id of policy.required_components || []) {
+      if (!components.has(id)) {
+        failures.push(`missing required component: ${id}`);
+      }
+    }
+
+    for (const rule of policy.forbidden_dependencies || []) {
+      const deps = components.get(rule.from);
+      if (!deps) {
+        failures.push(`forbidden dependency rule references unknown component: ${rule.from}`);
+        continue;
+      }
+      if (deps.has(rule.to)) {
+        failures.push(
+          `forbidden dependency: ${rule.from} -> ${rule.to}${rule.reason ? ` (${rule.reason})` : ""}`
+        );
+      }
+    }
+
+    for (const rule of policy.required_dependencies || []) {
+      const deps = components.get(rule.from);
+      if (!deps) {
+        failures.push(`required dependency rule references unknown component: ${rule.from}`);
+        continue;
+      }
+      if (!deps.has(rule.to)) {
+        failures.push(
+          `missing required dependency: ${rule.from} -> ${rule.to}${rule.reason ? ` (${rule.reason})` : ""}`
+        );
+      }
+    }
+  }
+
+  if (failures.length > 0) {
+    console.error("FAIL: C4 architecture check:");
+    for (const failure of failures) {
+      console.error(`- ${failure}`);
+    }
+    process.exit(1);
+  }
+
+  console.log("PASS: C4 architecture diagrams are up to date.");
+}
+
+main();