@warpgogol/forge 2.7.0 → 2.8.1

package/src/utils/index.ts

@@ -0,0 +1,29 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Barrel export for forge utilities — canonical, autonomous, no @warpgogol/* dependencies.</purpose>
+<non-goals>
+  <item>Do not add non-utility exports here — use the appropriate forge module.</item>
+  <item>Do not re-export from @warpgogol/* packages — this package must remain dependency-free.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Initial utility barrel: fs-atomic, generated-marker, string-utils, fs, hash.</item>
+</CHANGE_SUMMARY>
+*/
+
+export { writeFileAtomic, type WriteFileAtomicOptions } from "./fs-atomic.ts";
+export { writeFileIfChanged } from "./fs-idempotent.ts";
+export {
+  GENERATED_MARKER,
+  hasGeneratedMarker,
+  stripGeneratedMarker,
+  buildGeneratedHeader,
+  isGeneratedMarkerTextCandidate,
+  type GeneratedHeaderInput,
+  type StripGeneratedMarkerResult,
+} from "./generated-marker.ts";
+export { toKebabCase } from "./string-utils.ts";
+export { collectFiles, fileExists, type CollectFilesOptions } from "./fs.ts";
+export { byteHash } from "./hash.ts";
+export { trashPath } from "./fs-trash.ts";
+export { trashSync } from "./fs-trash-sync.ts";

package/src/utils/string-utils.ts

@@ -0,0 +1,19 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Trivial string utilities — inlined from @warpgogol/share to avoid dependency.</purpose>
+<non-goals>
+  <item>Do not add non-string utilities here — use dedicated utility modules.</item>
+  <item>Do not introduce @warpgogol/* imports — this package must remain dependency-free.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Initial inline of toKebabCase from @warpgogol/werkstatt-shared/share/string-utils.</item>
+</CHANGE_SUMMARY>
+*/
+
+export function toKebabCase(value: string): string {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}

package/src/validators/note-frontmatter-validate.ts

@@ -0,0 +1,142 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Validate frontmatter consistency across a markdown note vault — checks for required fields in YAML frontmatter.</purpose>
+<non-goals>
+  <item>Do not import from @warpgogol/* — this module is portable.</item>
+  <item>Do not implement domain-specific logic beyond frontmatter validation.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0808: initial note.frontmatter.validate command handler.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import type { ForgeCommandResult } from "../types.ts";
+
+interface NoteFrontmatterValidateInput {
+  flags: Record<string, unknown>;
+}
+
+export interface FrontmatterViolation {
+  file: string;
+  field: string;
+  rule: "NOTE-02";
+  message: string;
+}
+
+export interface NoteFrontmatterValidateResult {
+  command: "note.frontmatter.validate";
+  violations: FrontmatterViolation[];
+  count: number;
+}
+
+function collectMarkdownFiles(dir: string, baseDir: string, results: string[]): void {
+  const SKIP_DIRS = new Set(["node_modules", ".git", ".turbo", "dist", ".cache", ".obsidian"]);
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory() && SKIP_DIRS.has(entry.name)) continue;
+    const fullPath = path.join(dir, entry.name);
+    const relPath = path.relative(baseDir, fullPath).replace(/\\/g, "/");
+    if (entry.isDirectory()) {
+      collectMarkdownFiles(fullPath, baseDir, results);
+    } else if (entry.name.endsWith(".md")) {
+      results.push(relPath);
+    }
+  }
+}
+
+export function runNoteFrontmatterValidate(
+  input: NoteFrontmatterValidateInput,
+  context: { workspaceRoot?: string },
+): ForgeCommandResult<NoteFrontmatterValidateResult> {
+  const workspaceRoot = context.workspaceRoot ?? process.cwd();
+  const vaultDir = (input.flags["vault-dir"] as string) ?? "vault";
+  const requiredFields = ((input.flags["fields"] as string) ?? "title")
+    .split(",")
+    .map((f) => f.trim())
+    .filter(Boolean);
+
+  const scanDir = path.join(workspaceRoot, vaultDir);
+
+  if (!fs.existsSync(scanDir)) {
+    return {
+      data: {
+        command: "note.frontmatter.validate",
+        violations: [],
+        count: 0,
+      },
+      exitCode: 0,
+      summary: "note.frontmatter.validate: vault directory not found — 0 violations",
+    };
+  }
+
+  const allMdFiles: string[] = [];
+  collectMarkdownFiles(scanDir, workspaceRoot, allMdFiles);
+
+  const violations: FrontmatterViolation[] = [];
+
+  for (const file of allMdFiles) {
+    const fullPath = path.join(workspaceRoot, file);
+    try {
+      const content = fs.readFileSync(fullPath, "utf8");
+      const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+      if (!fmMatch) {
+        for (const field of requiredFields) {
+          violations.push({
+            file,
+            field,
+            rule: "NOTE-02",
+            message: `File '${file}' has no frontmatter — missing field '${field}'`,
+          });
+        }
+        continue;
+      }
+      let fm: Record<string, unknown> = {};
+      try {
+        fm = parseYaml(fmMatch[1]) as Record<string, unknown>;
+      } catch {
+        for (const field of requiredFields) {
+          violations.push({
+            file,
+            field,
+            rule: "NOTE-02",
+            message: `File '${file}' has malformed frontmatter — missing field '${field}'`,
+          });
+        }
+        continue;
+      }
+      for (const field of requiredFields) {
+        if (!(field in fm) || fm[field] == null || fm[field] === "") {
+          if (field === "title") {
+            const hasH1 = /^\s*#\s+\S/.test(content.slice(fmMatch[0].length));
+            if (hasH1) continue;
+          }
+          violations.push({
+            file,
+            field,
+            rule: "NOTE-02",
+            message: `File '${file}' missing required field '${field}'`,
+          });
+        }
+      }
+    } catch {
+      // skip unreadable files
+    }
+  }
+
+  return {
+    data: {
+      command: "note.frontmatter.validate",
+      violations,
+      count: violations.length,
+    },
+    exitCode: violations.length > 0 ? 1 : 0,
+    summary:
+      violations.length > 0
+        ? `note.frontmatter.validate: ${violations.length} violation(s) found`
+        : "note.frontmatter.validate: OK — 0 violations",
+  };
+}

package/src/validators/note-link-validate.ts

@@ -0,0 +1,145 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Validate wikilink integrity across a markdown note vault — scans [[wikilinks]] and resolves each against the note graph.</purpose>
+<non-goals>
+  <item>Do not import from @warpgogol/* — this module is portable.</item>
+  <item>Do not implement domain-specific logic beyond wikilink resolution.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0808: initial note.link.validate command handler.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import type { ForgeCommandResult } from "../types.ts";
+
+interface NoteLinkValidateInput {
+  flags: Record<string, unknown>;
+}
+
+export interface NoteLinkViolation {
+  file: string;
+  line: number;
+  link: string;
+  rule: "NOTE-01";
+  message: string;
+}
+
+export interface NoteLinkValidateResult {
+  command: "note.link.validate";
+  violations: NoteLinkViolation[];
+  count: number;
+}
+
+function collectMarkdownFiles(dir: string, baseDir: string, results: string[]): void {
+  const SKIP_DIRS = new Set(["node_modules", ".git", ".turbo", "dist", ".cache", ".obsidian"]);
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory() && SKIP_DIRS.has(entry.name)) continue;
+    const fullPath = path.join(dir, entry.name);
+    const relPath = path.relative(baseDir, fullPath).replace(/\\/g, "/");
+    if (entry.isDirectory()) {
+      collectMarkdownFiles(fullPath, baseDir, results);
+    } else if (entry.name.endsWith(".md")) {
+      results.push(relPath);
+    }
+  }
+}
+
+export function runNoteLinkValidate(
+  input: NoteLinkValidateInput,
+  context: { workspaceRoot?: string },
+): ForgeCommandResult<NoteLinkValidateResult> {
+  const workspaceRoot = context.workspaceRoot ?? process.cwd();
+  const vaultDir = (input.flags["vault-dir"] as string) ?? "vault";
+  const pathFilter = input.flags["path"] as string | undefined;
+  const scanDir = pathFilter
+    ? path.join(workspaceRoot, vaultDir, pathFilter)
+    : path.join(workspaceRoot, vaultDir);
+
+  if (!fs.existsSync(scanDir)) {
+    return {
+      data: {
+        command: "note.link.validate",
+        violations: [],
+        count: 0,
+      },
+      exitCode: 0,
+      summary: "note.link.validate: vault directory not found — 0 violations",
+    };
+  }
+
+  const allMdFiles: string[] = [];
+  collectMarkdownFiles(scanDir, workspaceRoot, allMdFiles);
+
+  const noteMap = new Map<string, string>();
+  for (const mdFile of allMdFiles) {
+    const basename = path.basename(mdFile, ".md");
+    noteMap.set(basename, mdFile);
+    const fullPath = path.join(workspaceRoot, mdFile);
+    try {
+      const content = fs.readFileSync(fullPath, "utf8");
+      const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+      if (fmMatch) {
+        try {
+          const fm = parseYaml(fmMatch[1]) as Record<string, unknown>;
+          if (fm.aliases && Array.isArray(fm.aliases)) {
+            for (const alias of fm.aliases) {
+              if (typeof alias === "string") noteMap.set(alias, mdFile);
+            }
+          }
+        } catch {
+          // skip malformed frontmatter
+        }
+      }
+    } catch {
+      // skip unreadable files
+    }
+  }
+
+  const linkRegex = /\[\[([^\]]+?)\]\]/g;
+  const violations: NoteLinkViolation[] = [];
+
+  for (const file of allMdFiles) {
+    const fullPath = path.join(workspaceRoot, file);
+    try {
+      const content = fs.readFileSync(fullPath, "utf8");
+      const lines = content.split(/\r?\n/);
+      for (let i = 0; i < lines.length; i++) {
+        let match: RegExpExecArray | null;
+        linkRegex.lastIndex = 0;
+        while ((match = linkRegex.exec(lines[i])) !== null) {
+          const linkTarget = match[1].split("|")[0].split("#")[0].trim();
+          if (!linkTarget) continue;
+          if (!noteMap.has(linkTarget)) {
+            violations.push({
+              file,
+              line: i + 1,
+              link: match[0],
+              rule: "NOTE-01",
+              message: `Wikilink target '${linkTarget}' not found in vault`,
+            });
+          }
+        }
+      }
+    } catch {
+      // skip unreadable files
+    }
+  }
+
+  return {
+    data: {
+      command: "note.link.validate",
+      violations,
+      count: violations.length,
+    },
+    exitCode: violations.length > 0 ? 1 : 0,
+    summary:
+      violations.length > 0
+        ? `note.link.validate: ${violations.length} violation(s) found`
+        : "note.link.validate: OK — 0 violations",
+  };
+}

package/src/validators/note-orphan-detect.ts

@@ -0,0 +1,146 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Detect orphan notes in a markdown note vault — notes with zero inbound wikilinks.</purpose>
+<non-goals>
+  <item>Do not import from @warpgogol/* — this module is portable.</item>
+  <item>Do not implement domain-specific logic beyond orphan detection.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0808: initial note.orphan.detect command handler.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import type { ForgeCommandResult } from "../types.ts";
+
+interface NoteOrphanDetectInput {
+  flags: Record<string, unknown>;
+}
+
+export interface OrphanReport {
+  file: string;
+  inboundLinks: 0;
+  severity: "warning";
+}
+
+export interface NoteOrphanDetectResult {
+  command: "note.orphan.detect";
+  orphans: OrphanReport[];
+  count: number;
+}
+
+function collectMarkdownFiles(dir: string, baseDir: string, results: string[]): void {
+  const SKIP_DIRS = new Set(["node_modules", ".git", ".turbo", "dist", ".cache", ".obsidian"]);
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory() && SKIP_DIRS.has(entry.name)) continue;
+    const fullPath = path.join(dir, entry.name);
+    const relPath = path.relative(baseDir, fullPath).replace(/\\/g, "/");
+    if (entry.isDirectory()) {
+      collectMarkdownFiles(fullPath, baseDir, results);
+    } else if (entry.name.endsWith(".md")) {
+      results.push(relPath);
+    }
+  }
+}
+
+export function runNoteOrphanDetect(
+  input: NoteOrphanDetectInput,
+  context: { workspaceRoot?: string },
+): ForgeCommandResult<NoteOrphanDetectResult> {
+  const workspaceRoot = context.workspaceRoot ?? process.cwd();
+  const vaultDir = (input.flags["vault-dir"] as string) ?? "vault";
+  const scanDir = path.join(workspaceRoot, vaultDir);
+
+  if (!fs.existsSync(scanDir)) {
+    return {
+      data: {
+        command: "note.orphan.detect",
+        orphans: [],
+        count: 0,
+      },
+      exitCode: 0,
+      summary: "note.orphan.detect: vault directory not found — 0 orphans",
+    };
+  }
+
+  const allMdFiles: string[] = [];
+  collectMarkdownFiles(scanDir, workspaceRoot, allMdFiles);
+
+  const noteMap = new Map<string, string>();
+  for (const mdFile of allMdFiles) {
+    const basename = path.basename(mdFile, ".md");
+    noteMap.set(basename, mdFile);
+    const fullPath = path.join(workspaceRoot, mdFile);
+    try {
+      const content = fs.readFileSync(fullPath, "utf8");
+      const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+      if (fmMatch) {
+        try {
+          const fm = parseYaml(fmMatch[1]) as Record<string, unknown>;
+          if (fm.aliases && Array.isArray(fm.aliases)) {
+            for (const alias of fm.aliases) {
+              if (typeof alias === "string") noteMap.set(alias, mdFile);
+            }
+          }
+        } catch {
+          // skip malformed frontmatter
+        }
+      }
+    } catch {
+      // skip unreadable files
+    }
+  }
+
+  const inboundLinks = new Map<string, number>();
+  for (const mdFile of allMdFiles) {
+    inboundLinks.set(mdFile, 0);
+  }
+
+  const linkRegex = /\[\[([^\]]+?)\]\]/g;
+  for (const file of allMdFiles) {
+    const fullPath = path.join(workspaceRoot, file);
+    try {
+      const content = fs.readFileSync(fullPath, "utf8");
+      let match: RegExpExecArray | null;
+      linkRegex.lastIndex = 0;
+      while ((match = linkRegex.exec(content)) !== null) {
+        const linkTarget = match[1].split("|")[0].split("#")[0].trim();
+        if (!linkTarget) continue;
+        const targetFile = noteMap.get(linkTarget);
+        if (targetFile && targetFile !== file) {
+          inboundLinks.set(targetFile, (inboundLinks.get(targetFile) ?? 0) + 1);
+        }
+      }
+    } catch {
+      // skip unreadable files
+    }
+  }
+
+  const orphans: OrphanReport[] = [];
+  for (const [file, count] of inboundLinks) {
+    if (count === 0) {
+      orphans.push({
+        file,
+        inboundLinks: 0,
+        severity: "warning",
+      });
+    }
+  }
+
+  return {
+    data: {
+      command: "note.orphan.detect",
+      orphans,
+      count: orphans.length,
+    },
+    exitCode: 0,
+    summary:
+      orphans.length > 0
+        ? `note.orphan.detect: ${orphans.length} orphan(s) found`
+        : "note.orphan.detect: OK — 0 orphans",
+  };
+}

package/src/validators/port-validate.ts

@@ -0,0 +1,97 @@
+/*
+<MODULE_CONTRACT>
+<purpose>forge.port.validate — validates that a ported skill or command complies with forge contracts (frontmatter, registry, no project-specific dependencies).</purpose>
+<non-goals>
+  <item>Do not validate all skills — only the named skill or command.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0374: initial forge.port.validate handler.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs";
+import path from "node:path";
+import { FORGE_SKILLS } from "../registry.ts";
+
+interface PortValidateResult {
+  command: string;
+  status: "pass" | "fail";
+  violations: string[];
+}
+
+// RFC-0556: removed @warpgogol/site-kernel-checks and @warpgogol/site-kernel-handoff
+// from this list — os/compass and os/werkstatt no longer import them (handlers inlined).
+// RFC-0776: @warpgogol/site-kernel replaced by @warpgogol/werkstatt/kernel.
+// @warpgogol/werkstatt/kernel remains forbidden for src/ portability.
+const FORBIDDEN_IMPORTS = [
+  "@warpgogol/werkstatt/kernel",
+  "@warpgogol/werkstatt-site/ui",
+  "@warpgogol/werkstatt-shared/share/page",
+];
+
+export function runPortValidate(
+  input: { flags: { name?: string } },
+  context: unknown,
+): PortValidateResult {
+  const ctx = context as { workspaceRoot?: string };
+  const workspaceRoot = ctx?.workspaceRoot ?? process.cwd();
+  const forgeRoot = path.join(workspaceRoot, "packages", "forge");
+  const name = input.flags?.name;
+
+  if (!name) {
+    return {
+      command: "forge.port.validate",
+      status: "fail",
+      violations: ["--name flag is required"],
+    };
+  }
+
+  const violations: string[] = [];
+
+  // Check if skill exists in registry
+  const skillEntry = FORGE_SKILLS.find((s) => s.name === name);
+  if (!skillEntry) {
+    violations.push(`Skill "${name}" not found in forge registry`);
+  }
+
+  // Check for forbidden imports in TypeScript files under the skill/command directory
+  const skillDir = path.join(forgeRoot, "skills");
+  const searchDirs = [
+    path.join(skillDir, "fo", name),
+    path.join(skillDir, "shared", name),
+    path.join(skillDir, "meta", name),
+    path.join(forgeRoot, "os"),
+  ];
+
+  for (const dir of searchDirs) {
+    if (fs.existsSync(dir)) {
+      scanForForbiddenImports(dir, FORBIDDEN_IMPORTS, violations);
+    }
+  }
+
+  return {
+    command: "forge.port.validate",
+    status: violations.length === 0 ? "pass" : "fail",
+    violations,
+  };
+}
+
+function scanForForbiddenImports(dir: string, forbidden: string[], violations: string[]): void {
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      scanForForbiddenImports(fullPath, forbidden, violations);
+    } else if (entry.name.endsWith(".ts") || entry.name.endsWith(".mjs")) {
+      const content = fs.readFileSync(fullPath, "utf8");
+      for (const imp of forbidden) {
+        if (content.includes(imp)) {
+          violations.push(
+            `Forbidden import "${imp}" found in ${path.relative(process.cwd(), fullPath)}`,
+          );
+        }
+      }
+    }
+  }
+}