@setzkasten/cli 0.1.0-rc.4 → 0.1.0-rc.5

package/README.md

@@ -7,6 +7,8 @@ CLI-first tool for font license governance, audit logging, and deterministic pol
 - Writes an append-only event log (`.setzkasten/events.log`)
 - Adds/removes font entries
 - Scans controlled local assets for usage signals
+- Discovers likely license files and computes deterministic `document_hash` values
+- Links license evidence files to existing license instances (`evidence add`)
 - Evaluates policy decisions (`allow`, `warn`, `escalate`)
 - Generates deterministic quote output
 - Provides a migration stub command
@@ -21,11 +23,21 @@ npm install -g @setzkasten/cli
 setzkasten init --name "My Project"
 setzkasten add --font-id inter --family "Inter" --source oss
 setzkasten scan --path . --discover
+setzkasten evidence add --license-id lic_inter_001 --file ./licenses/OFL.txt
 setzkasten policy
 setzkasten quote
 setzkasten migrate
 ```
 
+## License Evidence Workflow
+1. Run `setzkasten scan --path . --discover` to list discovered fonts and likely license files.
+2. Review `result.discovered_license_files` in JSON output (`path`, `document_hash`, `detected_license`, `matched_font_ids`).
+3. Link the local license file to a license instance:
+```bash
+setzkasten evidence add --license-id <license_id> --file <path-to-license-file>
+```
+4. Run `setzkasten policy` to verify BYO evidence state.
+
 ## Data written locally
 - `LICENSE_MANIFEST.json`
 - `.setzkasten/events.log`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@setzkasten/cli",
-  "version": "0.1.0-rc.4",
+  "version": "0.1.0-rc.5",
   "description": "Setzkasten CLI for font license governance and audit trails.",
   "private": false,
   "type": "module",

package/src/index.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import { realpathSync } from "node:fs";
-import { access } from "node:fs/promises";
+import { access, readFile } from "node:fs/promises";
 import path from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
-import { MANIFEST_FILENAME, parseListFlag, slugifyId } from "./lib/core.js";
+import { MANIFEST_FILENAME, parseListFlag, sha256Hex, slugifyId } from "./lib/core.js";
 import { appendProjectEvent } from "./lib/events.js";
 import {
   addFontToManifest,
@@ -13,6 +13,7 @@ import {
   loadManifest,
   removeFontFromManifest,
   saveManifest,
+  upsertLicenseEvidence,
 } from "./lib/manifest-lib.js";
 import { evaluatePolicy } from "./lib/policy.js";
 import { generateQuote } from "./lib/quote.js";
@@ -28,7 +29,8 @@ Commands:
   init      Create ${MANIFEST_FILENAME} and .setzkasten/events.log
   add       Add font entry to manifest
   remove    Remove font entry from manifest
-  scan      Scan local repository usage and optionally discover font files
+  scan      Scan local repository usage and optionally discover font/license files
+  evidence  Attach/update license evidence from local files
   policy    Evaluate policy decision (allow|warn|escalate)
   quote     Generate deterministic quote from license schema data
   migrate   Generate migration stub plan
@@ -37,13 +39,20 @@ Common options:
   --manifest <path>   Explicit path to ${MANIFEST_FILENAME}
 Scan options:
   --path <dir>                 Directory to scan (default: project root)
-  --discover                   Discover existing font files (woff2/woff/ttf/otf/otc)
-  --max-discovered-files <n>   Max discovered files in output (default: 200)
+  --discover                        Discover existing font and license files
+  --max-discovered-files <n>        Max discovered font files in output (default: 200)
+  --max-discovered-license-files <n> Max discovered license files in output (default: 200)
+Evidence options:
+  setzkasten evidence add --license-id <id> --file <path>
+    [--type <type>] [--evidence-id <id>] [--document-name <name>]
+    [--document-url <uri>] [--reference <id>] [--issuer <name>]
+    [--purchased-at <iso-date-time>] [--notes <text>]
 
 Examples:
   setzkasten init --name "Acme Project"
   setzkasten add --font-id inter --family "Inter" --source oss
   setzkasten scan --path . --discover
+  setzkasten evidence add --license-id lic_web_001 --file ./licenses/OFL.txt
   setzkasten policy --fail-on escalate
 `;
 
@@ -339,6 +348,7 @@ async function handleScan(cwd, flags) {
   const scanRoot = path.resolve(cwd, getStringFlag(flags, "path") ?? projectRoot);
   const maxMatchedPaths = Number(getStringFlag(flags, "max-matched-paths") ?? "30");
   const maxDiscoveredFiles = Number(getStringFlag(flags, "max-discovered-files") ?? "200");
+  const maxDiscoveredLicenseFiles = Number(getStringFlag(flags, "max-discovered-license-files") ?? "200");
   const discover = getBooleanFlag(flags, "discover");
 
   const scanResult = await scanProject({
@@ -346,6 +356,7 @@ async function handleScan(cwd, flags) {
     manifest,
     maxMatchedPathsPerFont: Number.isFinite(maxMatchedPaths) ? maxMatchedPaths : 30,
     maxDiscoveredFiles: Number.isFinite(maxDiscoveredFiles) ? maxDiscoveredFiles : 200,
+    maxDiscoveredLicenseFiles: Number.isFinite(maxDiscoveredLicenseFiles) ? maxDiscoveredLicenseFiles : 200,
     discover,
   });
 
@@ -362,6 +373,9 @@ async function handleScan(cwd, flags) {
       discovered_font_files_count: Array.isArray(scanResult.discovered_font_files)
         ? scanResult.discovered_font_files.length
         : 0,
+      discovered_license_files_count: Array.isArray(scanResult.discovered_license_files)
+        ? scanResult.discovered_license_files.length
+        : 0,
       discover_enabled: discover,
       root_path: scanResult.root_path,
     },
@@ -376,6 +390,75 @@ async function handleScan(cwd, flags) {
   return 0;
 }
 
+async function handleEvidenceAdd(cwd, flags) {
+  const manifestPath = resolveManifestPathFromFlag(cwd, flags);
+  const { manifest, manifestPath: resolvedManifestPath, projectRoot } = await loadManifest({
+    cwd,
+    manifestPath,
+  });
+
+  const licenseId = requireStringFlag(flags, "license-id");
+  const documentPath = path.resolve(cwd, requireStringFlag(flags, "file"));
+
+  let documentBuffer;
+  try {
+    documentBuffer = await readFile(documentPath);
+  } catch {
+    throw new Error(`Could not read evidence file at ${documentPath}.`);
+  }
+
+  const upsertResult = upsertLicenseEvidence(manifest, {
+    licenseId,
+    evidenceId: getStringFlag(flags, "evidence-id"),
+    type: getStringFlag(flags, "type") ?? "other",
+    documentHash: sha256Hex(documentBuffer),
+    documentName: getStringFlag(flags, "document-name") ?? path.basename(documentPath),
+    documentPath: path.relative(projectRoot, documentPath),
+    documentUrl: getStringFlag(flags, "document-url"),
+    reference: getStringFlag(flags, "reference"),
+    issuer: getStringFlag(flags, "issuer"),
+    purchasedAt: getStringFlag(flags, "purchased-at"),
+    notes: getStringFlag(flags, "notes"),
+  });
+
+  await saveManifest(resolvedManifestPath, upsertResult.manifest);
+
+  await appendProjectEvent({
+    projectRoot,
+    projectId: getManifestProjectId(upsertResult.manifest),
+    eventType: "manifest.license_ref_added",
+    payload: {
+      action: upsertResult.action,
+      license_id: upsertResult.license_id,
+      evidence_id: upsertResult.evidence.evidence_id,
+      evidence_type: upsertResult.evidence.type,
+      document_hash: upsertResult.evidence.document_hash,
+      document_name: upsertResult.evidence.document_name ?? path.basename(documentPath),
+      file_path: path.relative(projectRoot, documentPath),
+    },
+  });
+
+  printJson({
+    ok: true,
+    command: "evidence",
+    action: "add",
+    manifest_path: resolvedManifestPath,
+    result: upsertResult,
+  });
+
+  return 0;
+}
+
+async function handleEvidence(cwd, flags, positionals) {
+  const action = positionals[0] ?? "add";
+
+  if (action !== "add") {
+    throw new Error(`Unknown evidence action '${action}'. Supported: add`);
+  }
+
+  return handleEvidenceAdd(cwd, flags);
+}
+
 async function handlePolicy(cwd, flags) {
   const manifestPath = resolveManifestPathFromFlag(cwd, flags);
   const { manifest, projectRoot } = await loadManifest({
@@ -490,6 +573,8 @@ export async function runCli(argv = process.argv.slice(2), cwd = process.cwd())
       return handleRemove(cwd, parsed.flags);
     case "scan":
       return handleScan(cwd, parsed.flags);
+    case "evidence":
+      return handleEvidence(cwd, parsed.flags, parsed.positionals);
     case "policy":
       return handlePolicy(cwd, parsed.flags);
     case "quote":

package/src/lib/manifest-lib.js

@@ -16,6 +16,7 @@ const SOURCE_TYPES = new Set(["oss", "byo"]);
 const OFFERING_TYPES = new Set(["commercial", "trial"]);
 const INSTANCE_STATUS = new Set(["active", "expired", "superseded", "revoked"]);
 const ACQUISITION_SOURCES = new Set(["direct_foundry", "reseller", "marketplace", "legacy"]);
+const SHA256_PATTERN = /^[A-Fa-f0-9]{64}$/;
 
 function isObject(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
@@ -164,7 +165,7 @@ function validateEvidence(errors, pathName, value) {
   });
   validateString(errors, `${pathName}.type`, value.type, { minLength: 1 });
   validateString(errors, `${pathName}.document_hash`, value.document_hash, {
-    pattern: /^[A-Fa-f0-9]{64}$/,
+    pattern: SHA256_PATTERN,
   });
 }
 
@@ -322,7 +323,7 @@ function validateLicenseInstance(errors, pathName, value) {
 
   validateString(errors, `${pathName}.status`, value.status, { enum: INSTANCE_STATUS });
 
-  const hasEvidence = validateArray(errors, `${pathName}.evidence`, value.evidence, { minItems: 1 });
+  const hasEvidence = validateArray(errors, `${pathName}.evidence`, value.evidence, { minItems: 0 });
   if (hasEvidence) {
     for (let index = 0; index < value.evidence.length; index += 1) {
       validateEvidence(errors, `${pathName}.evidence[${index}]`, value.evidence[index]);
@@ -556,6 +557,15 @@ function normalizeStringArray(value) {
   return value.filter((entry) => typeof entry === "string");
 }
 
+function normalizeOptionalString(value) {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : undefined;
+}
+
 export function addFontToManifest(manifest, font) {
   const draft = deepClone(manifest);
   const fonts = Array.isArray(draft.fonts) ? draft.fonts : [];
@@ -591,6 +601,137 @@ export function removeFontFromManifest(manifest, fontId) {
   };
 }
 
+export function upsertLicenseEvidence(manifest, input) {
+  const licenseId = normalizeOptionalString(input?.licenseId);
+  if (!licenseId) {
+    throw new Error("licenseId is required.");
+  }
+
+  const documentHash = normalizeOptionalString(input?.documentHash);
+  if (!documentHash || !SHA256_PATTERN.test(documentHash)) {
+    throw new Error("documentHash must be a 64-char sha256 hex string.");
+  }
+
+  const draft = deepClone(manifest);
+  const instances = Array.isArray(draft.license_instances) ? draft.license_instances : [];
+  const instanceIndex = instances.findIndex(
+    (entry) => isObject(entry) && typeof entry.license_id === "string" && entry.license_id === licenseId,
+  );
+
+  if (instanceIndex < 0) {
+    throw new Error(`License instance '${licenseId}' not found in manifest.`);
+  }
+
+  const instance = instances[instanceIndex];
+  const currentEvidence = Array.isArray(instance.evidence) ? instance.evidence : [];
+
+  const evidenceType = normalizeOptionalString(input?.type) ?? "other";
+  const documentName =
+    normalizeOptionalString(input?.documentName) ??
+    normalizeOptionalString(input?.documentPath) ??
+    "license-document";
+  const requestedEvidenceId = normalizeOptionalString(input?.evidenceId);
+
+  if (requestedEvidenceId && !ID_PATTERN.test(requestedEvidenceId)) {
+    throw new Error("evidenceId has invalid format.");
+  }
+
+  const generatedEvidenceId = slugifyId(`${path.parse(documentName).name}-${documentHash.slice(0, 8)}`, "evidence");
+  const evidenceId = requestedEvidenceId ?? generatedEvidenceId;
+
+  const nextEvidence = {
+    evidence_id: evidenceId,
+    type: evidenceType,
+    document_hash: documentHash,
+  };
+
+  const reference = normalizeOptionalString(input?.reference);
+  if (reference) {
+    nextEvidence.reference = reference;
+  }
+
+  const issuer = normalizeOptionalString(input?.issuer);
+  if (issuer) {
+    nextEvidence.issuer = issuer;
+  }
+
+  const documentUrl = normalizeOptionalString(input?.documentUrl);
+  if (documentUrl) {
+    try {
+      new URL(documentUrl);
+    } catch {
+      throw new Error("documentUrl must be a valid URI.");
+    }
+    nextEvidence.document_url = documentUrl;
+  }
+
+  const purchasedAt = normalizeOptionalString(input?.purchasedAt);
+  if (purchasedAt) {
+    nextEvidence.purchased_at = purchasedAt;
+  }
+
+  const notes = normalizeOptionalString(input?.notes);
+  if (notes) {
+    nextEvidence.notes = notes;
+  }
+
+  const normalizedDocumentName = normalizeOptionalString(input?.documentName);
+  if (normalizedDocumentName) {
+    nextEvidence.document_name = normalizedDocumentName;
+  }
+
+  let action = "added";
+  let appliedEvidence = nextEvidence;
+
+  const byIdIndex = currentEvidence.findIndex(
+    (entry) => isObject(entry) && typeof entry.evidence_id === "string" && entry.evidence_id === evidenceId,
+  );
+
+  if (byIdIndex >= 0) {
+    appliedEvidence = {
+      ...currentEvidence[byIdIndex],
+      ...nextEvidence,
+    };
+    currentEvidence[byIdIndex] = appliedEvidence;
+    action = "updated";
+  } else {
+    const byHashIndex = currentEvidence.findIndex(
+      (entry) =>
+        isObject(entry) &&
+        typeof entry.document_hash === "string" &&
+        entry.document_hash.toLowerCase() === documentHash.toLowerCase(),
+    );
+
+    if (byHashIndex >= 0) {
+      const existing = currentEvidence[byHashIndex];
+      appliedEvidence = {
+        ...existing,
+        ...nextEvidence,
+        evidence_id:
+          typeof existing.evidence_id === "string" && existing.evidence_id.length > 0
+            ? existing.evidence_id
+            : evidenceId,
+      };
+      currentEvidence[byHashIndex] = appliedEvidence;
+      action = "updated";
+    } else {
+      currentEvidence.push(nextEvidence);
+      action = "added";
+    }
+  }
+
+  instance.evidence = currentEvidence;
+  instances[instanceIndex] = instance;
+  draft.license_instances = instances;
+
+  return {
+    manifest: draft,
+    action,
+    license_id: licenseId,
+    evidence: appliedEvidence,
+  };
+}
+
 export function getManifestProjectId(manifest) {
   if (!isObject(manifest.project)) {
     throw new Error("manifest.project must be an object.");

package/src/lib/scanner.js

@@ -1,6 +1,6 @@
 import { readdir, readFile, stat } from "node:fs/promises";
 import path from "node:path";
-import { nowIso, slugifyId } from "./core.js";
+import { nowIso, sha256Hex, slugifyId } from "./core.js";
 
 const DEFAULT_IGNORED_DIRS = new Set([
   ".git",
@@ -31,6 +31,8 @@ const TEXT_FILE_EXTENSIONS = new Set([
 ]);
 
 const FONT_FILE_EXTENSIONS = new Set([".woff2", ".woff", ".ttf", ".otf", ".otc"]);
+const LICENSE_FILE_EXTENSIONS = new Set(["", ".txt", ".md", ".pdf", ".rtf", ".html", ".htm"]);
+const LICENSE_FILE_NAME_PATTERN = /(license|licence|eula|ofl|fontlog|copying|copyright)/i;
 
 const STYLE_TOKENS = new Set([
   "regular",
@@ -71,9 +73,26 @@ function shouldDiscoverFontFile(filePath) {
   return FONT_FILE_EXTENSIONS.has(extension);
 }
 
+function shouldDiscoverLicenseFile(filePath) {
+  const extension = path.extname(filePath).toLowerCase();
+  const fileName = path.basename(filePath).toLowerCase();
+
+  if (!LICENSE_FILE_EXTENSIONS.has(extension)) {
+    return false;
+  }
+
+  return LICENSE_FILE_NAME_PATTERN.test(fileName);
+}
+
+function isLikelyTextLicenseFile(filePath) {
+  const extension = path.extname(filePath).toLowerCase();
+  return extension === "" || extension === ".txt" || extension === ".md" || extension === ".html" || extension === ".htm";
+}
+
 async function collectProjectFiles(rootPath) {
   const textFiles = [];
   const fontFiles = [];
+  const licenseFiles = [];
 
   async function walk(dirPath) {
     const entries = await readdir(dirPath, { withFileTypes: true });
@@ -109,6 +128,10 @@ async function collectProjectFiles(rootPath) {
       if (shouldDiscoverFontFile(fullPath)) {
         fontFiles.push(fullPath);
       }
+
+      if (shouldDiscoverLicenseFile(fullPath)) {
+        licenseFiles.push(fullPath);
+      }
     }
   }
 
@@ -117,6 +140,7 @@ async function collectProjectFiles(rootPath) {
   return {
     textFiles,
     fontFiles,
+    licenseFiles,
   };
 }
 
@@ -174,11 +198,103 @@ function discoverFontFiles(rootPath, fontFiles, maxDiscoveredFiles) {
     .slice(0, maxDiscoveredFiles);
 }
 
+function detectLicenseKind(fileName, contentLower) {
+  if (contentLower) {
+    if (
+      contentLower.includes("sil open font license") ||
+      contentLower.includes("ofl version 1.1") ||
+      contentLower.includes("scripts.sil.org/ofl")
+    ) {
+      return "sil_ofl_1_1";
+    }
+
+    if (contentLower.includes("apache license") && contentLower.includes("version 2.0")) {
+      return "apache_2_0";
+    }
+
+    if (contentLower.includes("mit license")) {
+      return "mit";
+    }
+
+    if (contentLower.includes("gnu general public license")) {
+      return "gpl";
+    }
+
+    if (contentLower.includes("mozilla public license")) {
+      return "mpl";
+    }
+
+    if (contentLower.includes("eula") || contentLower.includes("end user license agreement")) {
+      return "eula";
+    }
+  }
+
+  if (fileName.toLowerCase().includes("ofl")) {
+    return "sil_ofl_1_1";
+  }
+
+  if (fileName.toLowerCase().includes("eula")) {
+    return "eula";
+  }
+
+  return null;
+}
+
+function matchFontIdsFromLicenseContent(fonts, contentLower) {
+  if (!contentLower) {
+    return [];
+  }
+
+  return fonts
+    .filter((font) => contentLower.includes(font.family_name.toLowerCase()))
+    .map((font) => font.font_id)
+    .sort((a, b) => a.localeCompare(b));
+}
+
+async function discoverLicenseFiles(rootPath, licenseFiles, fonts, maxDiscoveredLicenseFiles) {
+  const discovered = [];
+
+  for (const filePath of licenseFiles) {
+    let fileBuffer;
+    let fileStat;
+
+    try {
+      fileBuffer = await readFile(filePath);
+      fileStat = await stat(filePath);
+    } catch {
+      continue;
+    }
+
+    const extension = path.extname(filePath).toLowerCase();
+    const fileName = path.basename(filePath);
+    const relativePath = relativeTo(rootPath, filePath);
+    const contentLower =
+      isLikelyTextLicenseFile(filePath) && fileBuffer.length <= 512 * 1024
+        ? fileBuffer.toString("utf8").toLowerCase()
+        : null;
+
+    discovered.push({
+      path: relativePath,
+      extension,
+      file_name: fileName,
+      size_bytes: fileStat.size,
+      document_hash: sha256Hex(fileBuffer),
+      detected_license: detectLicenseKind(fileName, contentLower),
+      matched_font_ids: matchFontIdsFromLicenseContent(fonts, contentLower),
+    });
+  }
+
+  return discovered
+    .sort((a, b) => a.path.localeCompare(b.path))
+    .slice(0, maxDiscoveredLicenseFiles);
+}
+
 export async function scanProject(input) {
   const rootPath = path.resolve(input.rootPath);
   const maxMatchedPathsPerFont = input.maxMatchedPathsPerFont ?? 30;
   const discover = input.discover === true;
   const maxDiscoveredFiles = input.maxDiscoveredFiles ?? 200;
+  const maxDiscoveredLicenseFiles = input.maxDiscoveredLicenseFiles ?? 200;
 
   const fonts = normalizeFonts(input.manifest)
     .map((font) => ({
@@ -187,7 +303,7 @@ export async function scanProject(input) {
     }))
     .filter((font) => font.font_id.length > 0 && font.family_name.length > 0);
 
-  const { textFiles, fontFiles } = await collectProjectFiles(rootPath);
+  const { textFiles, fontFiles, licenseFiles } = await collectProjectFiles(rootPath);
   const matches = new Map();
 
   for (const font of fonts) {
@@ -227,18 +343,38 @@ export async function scanProject(input) {
     }
   }
 
+  const discoveredLicenseFiles = discover
+    ? await discoverLicenseFiles(rootPath, licenseFiles, fonts, maxDiscoveredLicenseFiles)
+    : [];
+
   return {
     scanned_at: nowIso(),
     root_path: rootPath,
     scanned_files_count: textFiles.length,
     font_matches: Object.fromEntries(Array.from(matches.entries())),
     discovered_font_files: discover ? discoverFontFiles(rootPath, fontFiles, maxDiscoveredFiles) : [],
+    discovered_license_files: discoveredLicenseFiles,
   };
 }
 
 export function applyScanResultToManifest(manifest, scanResult) {
   const draft = deepClone(manifest);
   const fonts = Array.isArray(draft.fonts) ? draft.fonts : [];
+  const licenseMatchesByFont = new Map();
+
+  const discoveredLicenseFiles = Array.isArray(scanResult.discovered_license_files)
+    ? scanResult.discovered_license_files
+    : [];
+
+  for (const licenseFile of discoveredLicenseFiles) {
+    const matchedFontIds = Array.isArray(licenseFile.matched_font_ids) ? licenseFile.matched_font_ids : [];
+    for (const fontId of matchedFontIds) {
+      if (!licenseMatchesByFont.has(fontId)) {
+        licenseMatchesByFont.set(fontId, []);
+      }
+      licenseMatchesByFont.get(fontId).push(licenseFile.path);
+    }
+  }
 
   for (const font of fonts) {
     const fontId = typeof font.font_id === "string" ? font.font_id : "";
@@ -250,12 +386,16 @@ export function applyScanResultToManifest(manifest, scanResult) {
     const currentUsage =
       font.usage && typeof font.usage === "object" && !Array.isArray(font.usage) ? font.usage : {};
 
+    const matchedLicensePaths = licenseMatchesByFont.get(fontId) ?? [];
+
     font.usage = {
       ...currentUsage,
       scan: {
         scanned_at: scanResult.scanned_at,
         match_count: match?.match_count ?? 0,
         matched_paths: match?.matched_paths ?? [],
+        license_match_count: matchedLicensePaths.length,
+        license_matched_paths: matchedLicensePaths.slice(0, 30),
       },
     };
   }