@cosmicdrift/kumiko-guards 0.363.0 → 0.364.0

package/src/check-security.ts

@@ -0,0 +1,182 @@
+// Security check: `bun audit` over the lockfile of ONE repo.
+//
+// Single-repo by design: audits the bun.lock in the scanned repo's root. A repo without its
+// own bun.lock falls back to the nearest ancestor's (a parent workspace), announced loudly.
+// Critical/high advisories block unless covered by a short-lived exception; so does any
+// exception expiring within EXPIRY_BLOCK_DAYS. Exceptions merge the bundled
+// dependency-security-exceptions.json with an optional file of the same name in the repo root
+// (and in the ancestor holding the lockfile, when that is not the repo root).
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { parseDependencyCli } from "./_lib/dependency-cli";
+import { expiryEndMs, findExpiringSoon, loadExceptionEntries } from "./_lib/dependency-exceptions";
+import {
+  type AuditAdvisory,
+  evaluateSecurity,
+  parseAuditReport,
+  type RawAuditReport,
+  runBunAudit,
+  type SecurityEvaluation,
+  type SecurityException,
+} from "./_lib/security-audit";
+
+export const SECURITY_EXCEPTIONS_FILE = "dependency-security-exceptions.json";
+
+// Block a PR while there is still runway to act, not on the day the advisory re-blocks;
+// the 30-day console warning is invisible in green CI logs.
+export const EXPIRY_BLOCK_DAYS = 14;
+
+export function loadSecurityExceptions(
+  roots: readonly string[],
+  bundledDir?: string,
+): SecurityException[] {
+  return loadExceptionEntries({
+    filename: SECURITY_EXCEPTIONS_FILE,
+    roots,
+    bundledDir,
+    parse: (field) => ({
+      advisory: field("advisory"),
+      package: field("package"),
+      reason: field("reason"),
+      reviewedBy: field("reviewedBy"),
+      expires: field("expires"),
+    }),
+  }).filter((exception) => {
+    const hasDate = expiryEndMs(exception.expires) !== undefined;
+    if (!hasDate) {
+      console.warn(
+        `  WARN: security exception ${exception.advisory} dropped, expires "${exception.expires}" is not a YYYY-MM-DD date. Set expires to a date like 2026-12-31.`,
+      );
+    }
+    return hasDate;
+  });
+}
+
+/** Directory whose bun.lock `bun audit` runs against: the repo root, else the nearest ancestor with one. */
+export function findLockfileDir(repoRoot: string): string | undefined {
+  for (let dir = repoRoot; ; dir = dirname(dir)) {
+    if (existsSync(join(dir, "bun.lock"))) return dir;
+    if (dirname(dir) === dir) return undefined;
+  }
+}
+
+export function shouldBlock(
+  evaluation: Pick<SecurityEvaluation, "blocking">,
+  expiringUrgent: readonly SecurityException[],
+): boolean {
+  return evaluation.blocking.length > 0 || expiringUrgent.length > 0;
+}
+
+function printReport(
+  evaluation: SecurityEvaluation,
+  exceptions: readonly SecurityException[],
+  expiringUrgent: readonly SecurityException[],
+  nowMs: number,
+): void {
+  const { counts, blocking, warnings, suppressed } = evaluation;
+  const total = counts.critical + counts.high + counts.moderate + counts.low + counts.info;
+  console.log(
+    `  ${total} advisories — critical: ${counts.critical}  high: ${counts.high}  moderate: ${counts.moderate}  low: ${counts.low}`,
+  );
+
+  if (blocking.length > 0) {
+    console.error("\n  BLOCKING vulnerabilities:\n");
+    for (const adv of blocking) {
+      console.error(
+        `    [${adv.severity.toUpperCase()}]  ${adv.package}  ${adv.advisoryId}  ${adv.title}`,
+      );
+    }
+  }
+
+  if (warnings.length > 0) {
+    console.log("\n  WARN (moderate, not blocking):");
+    for (const adv of warnings) {
+      console.log(`    [MODERATE]  ${adv.package}  ${adv.advisoryId}  ${adv.title}`);
+    }
+  }
+
+  if (suppressed.length > 0) {
+    console.log(`\n  Suppressed via exception (${suppressed.length}):`);
+    for (const adv of suppressed.slice(0, 10)) {
+      console.log(`    [${adv.severity}]  ${adv.package}  ${adv.advisoryId}`);
+    }
+    if (suppressed.length > 10) console.log(`    … and ${suppressed.length - 10} more`);
+  }
+
+  if (expiringUrgent.length > 0) {
+    console.error(
+      `\n  BLOCKING: security exceptions expire within ${EXPIRY_BLOCK_DAYS} days — bump the dependency or re-review the exception now:`,
+    );
+    for (const ex of expiringUrgent) {
+      console.error(`    ${ex.package}  ${ex.advisory}  expires=${ex.expires}`);
+    }
+  }
+
+  const urgentKeys = new Set(expiringUrgent.map((ex) => `${ex.package}|${ex.advisory}`));
+  const expiringSoon = findExpiringSoon(exceptions, 30, nowMs).filter(
+    (ex) => !urgentKeys.has(`${ex.package}|${ex.advisory}`),
+  );
+  if (expiringSoon.length > 0) {
+    console.log("\n  WARN: security exceptions expire within 30 days — re-review:");
+    for (const ex of expiringSoon) {
+      console.log(`    ${ex.package}  ${ex.advisory}  expires=${ex.expires}`);
+    }
+  }
+
+  if (shouldBlock(evaluation, expiringUrgent)) {
+    console.error(
+      `\n  Fix dependencies or add short-lived exceptions in ${SECURITY_EXCEPTIONS_FILE} in the repo root\n`,
+    );
+  }
+}
+
+export async function runSecurityCheck(options: {
+  readonly repoRoot: string;
+  readonly reportOnly: boolean;
+  readonly runAudit?: (lockfileDir: string) => Promise<RawAuditReport>;
+  readonly exceptions?: readonly SecurityException[];
+  readonly nowMs?: number;
+}): Promise<number> {
+  const nowMs = options.nowMs ?? Date.now();
+  const lockfileDir = findLockfileDir(options.repoRoot);
+  if (lockfileDir === undefined) {
+    console.error(
+      `  security: no bun.lock found in ${options.repoRoot} or any ancestor — nothing to audit. Run bun install to create bun.lock.`,
+    );
+    return 1;
+  }
+  if (lockfileDir !== options.repoRoot) {
+    console.warn(
+      `  WARN: ${options.repoRoot} has no bun.lock — auditing ${lockfileDir}/bun.lock instead (it may cover more than this repo).`,
+    );
+  }
+
+  const exceptions = options.exceptions ?? loadSecurityExceptions([options.repoRoot, lockfileDir]);
+  console.log(`Security audit: scanning ${lockfileDir} …`);
+  const raw = await (options.runAudit ?? runBunAudit)(lockfileDir);
+  const advisories: AuditAdvisory[] = parseAuditReport(raw);
+
+  const evaluation = evaluateSecurity(advisories, exceptions, nowMs);
+  const expiringUrgent = findExpiringSoon(exceptions, EXPIRY_BLOCK_DAYS, nowMs);
+  printReport(evaluation, exceptions, expiringUrgent, nowMs);
+
+  if (options.reportOnly) return 0;
+  return shouldBlock(evaluation, expiringUrgent) ? 1 : 0;
+}
+
+export async function runSecurityCli(
+  argv: readonly string[],
+  cwd: string = process.cwd(),
+): Promise<number> {
+  const invocation = parseDependencyCli("security", argv, cwd);
+  if (!invocation.ok) return invocation.exitCode;
+  try {
+    return await runSecurityCheck({
+      repoRoot: invocation.repoRoot,
+      reportOnly: invocation.reportOnly,
+    });
+  } catch (err) {
+    console.error("Security check failed:", err);
+    return 1;
+  }
+}

package/src/check-single-runtime-instance.ts

@@ -109,7 +109,7 @@ export const check: RepoCheck = {
         violations.push({
           file: "bun.lock",
           line: 1,
-          message: `bun.lock could not be parsed (${root.name}): ${lock.detail}`,
+          message: `bun.lock could not be parsed (${root.name}): ${lock.detail}. Regenerate bun.lock with bun install.`,
         });
         continue;
       }

package/src/cli.ts

@@ -4,7 +4,11 @@
 // runners already use in their own `if (import.meta.main)` blocks — including
 // flags, which each runner's own *Cli function validates and applies so this
 // bin and the direct `bun run-*.ts` invocation can never drift apart.
+import { DEPENDENCY_CHECK_FLAGS } from "./_lib/dependency-cli";
 import { buildGuardKitInventory, cliFlagsError } from "./_lib/guard-kit";
+import { runLicensesCli } from "./check-licenses";
+import { runOutdatedCli } from "./check-outdated";
+import { runSecurityCli } from "./check-security";
 import { COMMENT_LANG_FLAGS, runCommentLangCli } from "./guard-comment-lang";
 import {
   PUBLIC_EXPORTS_CHANGELOG_FLAGS,
@@ -20,6 +24,9 @@ const SUBCOMMANDS = [
   "checks",
   "comment-lang",
   "public-exports-changelog",
+  "licenses",
+  "security",
+  "outdated",
   "list",
 ] as const;
 type Subcommand = (typeof SUBCOMMANDS)[number];
@@ -30,6 +37,9 @@ const SUBCOMMAND_FLAGS: Record<Subcommand, readonly string[]> = {
   checks: REPO_CHECK_FLAGS,
   "comment-lang": [...COMMENT_LANG_FLAGS, "--base=<ref>"],
   "public-exports-changelog": PUBLIC_EXPORTS_CHANGELOG_FLAGS,
+  licenses: DEPENDENCY_CHECK_FLAGS,
+  security: DEPENDENCY_CHECK_FLAGS,
+  outdated: DEPENDENCY_CHECK_FLAGS,
   list: [],
 };
 
@@ -39,7 +49,7 @@ function isSubcommand(value: string): value is Subcommand {
 
 function printHelp(): void {
   console.log(
-    "Usage: kumiko-guards [guards|ui|checks|comment-lang|public-exports-changelog|list] [flags]",
+    "Usage: kumiko-guards [guards|ui|checks|comment-lang|public-exports-changelog|licenses|security|outdated|list] [flags]",
   );
   console.log();
   for (const sub of SUBCOMMANDS) {
@@ -91,6 +101,17 @@ function printInventory(flags: readonly string[]): void {
   console.log(JSON.stringify(inventory));
 }
 
+const STANDALONE_SUBCOMMANDS: Record<
+  string,
+  (flags: readonly string[]) => number | Promise<number>
+> = {
+  "comment-lang": runCommentLangCli,
+  "public-exports-changelog": runPublicExportsChangelogCli,
+  licenses: (flags) => runLicensesCli(flags),
+  security: (flags) => runSecurityCli(flags),
+  outdated: (flags) => runOutdatedCli(flags),
+};
+
 async function main(): Promise<void> {
   const { subcommand, flags } = parseInvocation(process.argv);
 
@@ -101,14 +122,10 @@ async function main(): Promise<void> {
   }
 
   // Not part of the no-subcommand run: comment-lang needs a baseline or a git base ref,
-  // public-exports-changelog only applies to the kumiko-framework repo.
-  if (subcommand === "comment-lang") {
-    process.exit(runCommentLangCli(flags));
-  }
-
-  if (subcommand === "public-exports-changelog") {
-    process.exit(await runPublicExportsChangelogCli(flags));
-  }
+  // public-exports-changelog only applies to the kumiko-framework repo, and
+  // licenses/security/outdated call the npm registry or `bun audit` (network).
+  const standalone = subcommand === undefined ? undefined : STANDALONE_SUBCOMMANDS[subcommand];
+  if (standalone) process.exit(await standalone(flags));
 
   let failed = 0;
   if (subcommand === undefined || subcommand === "guards") {

package/src/dependency-license-exceptions.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "Exceptions for check-licenses.ts. Each exception needs a reason, a reviewer and an expiry date.",
+  "exceptions": [
+    {
+      "package": "lightningcss",
+      "version": "*",
+      "license": "MPL-2.0",
+      "reason": "Transitive Dependency via Expo/Metro CSS-Tooling. MPL-2.0 ist file-level Copyleft — betrifft nur Modifikationen an lightningcss selbst, nicht unseren Code. Nur als Dependency genutzt, nicht modifiziert.",
+      "reviewedBy": "Marc, 2026-04-15",
+      "expires": "2027-04-15"
+    },
+    {
+      "package": "lightningcss-*",
+      "version": "*",
+      "license": "MPL-2.0",
+      "reason": "Platform-Binaries zu lightningcss (darwin-arm64/darwin-x64/linux-x64-gnu/linux-x64-musl/linux-arm64-gnu/linux-arm64-musl/linux-arm-gnueabihf/android-arm64/freebsd-x64/win32-x64-msvc/win32-arm64-msvc). Wildcard-Match — neue Plattform-Binary kommt automatisch durch ohne weiteren Eintrag.",
+      "reviewedBy": "Marc, 2026-04-26",
+      "expires": "2027-04-26"
+    },
+    {
+      "package": "spdx-exceptions",
+      "version": "*",
+      "license": "CC-BY-3.0",
+      "reason": "Transitive Dep via SPDX-License-Tooling selbst. CC-BY-3.0 deckt nur die SPDX-Exception-Daten (eine Liste von License-IDs), keine Code-Verteilung — wir nutzen das Package nur zur Laufzeit für Dep-Scanning, kein Re-Distribute.",
+      "reviewedBy": "Marc, 2026-05-01",
+      "expires": "2027-05-01"
+    },
+    {
+      "package": "@logdna/tail-file",
+      "version": "*",
+      "license": "SEE LICENSE IN LICENSE",
+      "reason": "License-File ist im Package selbst (LICENSE), npm-metadata zeigt nur den Pointer. Apache-2.0 ist die echte Lizenz (siehe node_modules/@logdna/tail-file/LICENSE). Transitive Dep.",
+      "reviewedBy": "Marc, 2026-05-01",
+      "expires": "2027-05-01"
+    },
+    {
+      "package": "spawndamnit",
+      "version": "*",
+      "license": "SEE LICENSE IN LICENSE",
+      "reason": "Transitive Dep via @changesets/cli. License-File im Package: MIT (Copyright James Kyle, Mitautor von Changesets). npm-metadata zeigt nur den Pointer. Pattern wie @logdna/tail-file.",
+      "reviewedBy": "Marc, 2026-05-06",
+      "expires": "2027-05-06"
+    },
+    {
+      "package": "@cosmicdriftgamestudio/*",
+      "version": "*",
+      "license": "UNLICENSED",
+      "reason": "Eigene private CDGS-Workspace-Packages (kumiko-guards, später kumiko-ai-*, kumiko-designer etc.). UNLICENSED = proprietary, kein Public-License-Risk weil intern in der Org bleibt (GH-Packages access:restricted).",
+      "reviewedBy": "Marc, 2026-05-06",
+      "expires": "2030-05-06"
+    },
+    {
+      "package": "@cosmicdrift/*",
+      "version": "*",
+      "license": "BUSL-1.1",
+      "reason": "Eigene Public-Workspace-Packages (kumiko-framework + 6 weitere). Wir sind der Licensor — BUSL-1.1 ist unser eigener Lizenz-Choice für die public NPM-Pakete. Der License-Check denied BUSL-1.1 als generic-Pattern (für Third-Party-Deps korrekt), aber für eigene Packages ist's der designierte Lizenz.",
+      "reviewedBy": "Marc, 2026-05-06",
+      "expires": "2030-05-06"
+    },
+    {
+      "package": "create-kumiko-app",
+      "version": "*",
+      "license": "BUSL-1.1",
+      "reason": "Unscoped Workspace-Paket — `bun create kumiko-app` resolved zu `bunx create-kumiko-app`, daher KEIN @cosmicdrift/-Scope möglich. Analog zur @cosmicdrift/*-Exception unser eigener Lizenz-Choice; eigene Eintrag weil Wildcard-Pattern unscoped Pakete nicht matched.",
+      "reviewedBy": "Marc, 2026-06-21",
+      "expires": "2030-06-21"
+    },
+    {
+      "package": "khroma",
+      "version": "*",
+      "license": "MIT",
+      "reason": "Transitive dep via mermaid (docs). npm metadata reports license=null; package LICENSE is MIT.",
+      "reviewedBy": "Marc, 2026-07-06",
+      "expires": "2027-07-06"
+    }
+  ]
+}

package/src/dependency-security-exceptions.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "Exceptions file for check-security.ts. Each exception needs reason, reviewer, and expiry (max ~30 days).",
+  "exceptions": []
+}

package/src/guard-agent-docs-drift.ts

@@ -0,0 +1,137 @@
+#!/usr/bin/env bun
+/**
+ * Guard: the generated agent docs under `packages/framework/agents/` must
+ * match what `bun run gen:agent-docs` renders from the current sources
+ * (feature manifest, renderer-web exports, sample recipes), and every
+ * `agents/<file>.md` path the hand-written `packages/framework/AGENTS.md`
+ * points at must exist in that generated set.
+ *
+ * Only the framework repo itself has these files; consumer repos are
+ * `notApplicable`.
+ *
+ * Usage:
+ *   bun guard-agent-docs-drift.ts
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { AGENT_DOCS_DIR, readAgentDocsOnDisk, renderAgentDocs } from "./_lib/agent-docs";
+import {
+  type GuardViolation,
+  type RepoCheck,
+  type RepoCheckOutcome,
+  reportResults,
+  runRepoChecks,
+} from "./_lib/guard-kit";
+import type { RepoRoot } from "./_lib/roots";
+
+const FRAMEWORK_PACKAGE_JSON_REL = "packages/framework/package.json";
+const FRAMEWORK_PACKAGE_NAME = "@cosmicdrift/kumiko-framework";
+const AGENTS_MD_REL = "packages/framework/AGENTS.md";
+const AGENTS_REF_RE = /`agents\/([A-Za-z0-9._/-]+\.md)`/g;
+const REGENERATE_HINT = "run `bun run gen:agent-docs` and commit the result";
+
+function isFrameworkRepo(root: RepoRoot): boolean {
+  const packageJsonPath = join(root.absPath, FRAMEWORK_PACKAGE_JSON_REL);
+  if (!existsSync(packageJsonPath)) return false;
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+    return (
+      typeof parsed === "object" &&
+      parsed !== null &&
+      "name" in parsed &&
+      parsed.name === FRAMEWORK_PACKAGE_NAME
+    );
+  } catch {
+    return false;
+  }
+}
+
+function firstDifferingLine(expected: string, actual: string): number {
+  const expectedLines = expected.split("\n");
+  const actualLines = actual.split("\n");
+  const length = Math.max(expectedLines.length, actualLines.length);
+  for (let index = 0; index < length; index++) {
+    if (expectedLines[index] !== actualLines[index]) return index + 1;
+  }
+  return 1;
+}
+
+function agentsMdReferenceViolations(
+  absPath: string,
+  generated: ReadonlyMap<string, string>,
+): GuardViolation[] {
+  const agentsMdPath = join(absPath, AGENTS_MD_REL);
+  if (!existsSync(agentsMdPath)) return [];
+  const violations: GuardViolation[] = [];
+  const lines = readFileSync(agentsMdPath, "utf-8").split("\n");
+  lines.forEach((text, index) => {
+    for (const match of text.matchAll(AGENTS_REF_RE)) {
+      const key = match[1];
+      if (key === undefined || generated.has(key)) continue;
+      violations.push({
+        file: AGENTS_MD_REL,
+        line: index + 1,
+        message: `references agents/${key}, which is not generated. Fix the reference or add the source (an example needs samples/recipes/<slug>/package.json).`,
+      });
+    }
+  });
+  return violations;
+}
+
+function rootViolations(absPath: string): { violations: GuardViolation[]; fileCount: number } {
+  const generated = renderAgentDocs(absPath);
+  const onDisk = readAgentDocsOnDisk(absPath);
+  const violations: GuardViolation[] = [];
+  for (const [rel, expected] of generated) {
+    const file = `${AGENT_DOCS_DIR}/${rel}`;
+    const actual = onDisk.get(rel);
+    if (actual === undefined) {
+      violations.push({
+        file,
+        line: 1,
+        message: `generated file is missing; ${REGENERATE_HINT}`,
+      });
+    } else if (actual !== expected) {
+      violations.push({
+        file,
+        line: firstDifferingLine(expected, actual),
+        message: `content differs from the generated output; ${REGENERATE_HINT}`,
+      });
+    }
+  }
+  for (const rel of onDisk.keys()) {
+    if (generated.has(rel)) continue;
+    violations.push({
+      file: `${AGENT_DOCS_DIR}/${rel}`,
+      line: 1,
+      message: `stale file no longer produced by the generator; ${REGENERATE_HINT}`,
+    });
+  }
+  violations.push(...agentsMdReferenceViolations(absPath, generated));
+  return { violations, fileCount: generated.size };
+}
+
+export const check: RepoCheck = {
+  name: "agent-docs-drift",
+  hint: "Run `bun run gen:agent-docs` and commit packages/framework/agents/.",
+  run(roots): RepoCheckOutcome {
+    const frameworkRoots = roots.filter(isFrameworkRepo);
+    if (frameworkRoots.length === 0) {
+      return { violations: [], matchedFiles: 0, notApplicable: true };
+    }
+    const violations: GuardViolation[] = [];
+    let matchedFiles = 0;
+    for (const root of frameworkRoots) {
+      const result = rootViolations(root.absPath);
+      violations.push(...result.violations);
+      matchedFiles += result.fileCount;
+    }
+    return { violations, matchedFiles, notApplicable: false };
+  },
+};
+
+if (import.meta.main) {
+  const failed = reportResults(await runRepoChecks([check]));
+  process.exit(failed > 0 ? 1 : 0);
+}