@warpgogol/forge 5.2.4 → 5.3.1

package/src/utils/markdown-table.ts

@@ -0,0 +1,121 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-1154: canonical prettier-normal markdown table emitter. Every forge
+emitter routes tables through alignMarkdownTable so generated guides pass
+`prettier --check` in consumer projects without forge depending on prettier.
+Also provides parseMarkdownTable so existing compact tables can be re-aligned
+(idempotency check: parse + re-emit is byte-stable).
+</purpose>
+<non-goals>
+  <item>Do not shell out to prettier — formatting is a pure string transform owned by forge.</item>
+  <item>Do not implement alignment colons (left/center/right) — forge emitters never produce them; parse normalizes them away.</item>
+  <item>Do not do full grapheme segmentation — cell width uses String.length; generated tables are ASCII-heavy (documented limitation).</item>
+</non-goals>
+<KEY_DECISIONS>
+  <item>Separator = dashes repeated to column width (min 3), matching observed prettier output.</item>
+  <item>Escaped pipe inside a cell is a literal, counted as 2 characters of width.</item>
+</KEY_DECISIONS>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1154: initial implementation — alignMarkdownTable + parseMarkdownTable.</item>
+</CHANGE_SUMMARY>
+*/
+
+/** Minimum column width — prettier never emits a separator narrower than `---`. */
+const MIN_COLUMN_WIDTH = 3;
+
+export interface ParsedMarkdownTable {
+  headers: string[];
+  rows: string[][];
+}
+
+/**
+ * Emit a prettier-normal markdown table: every cell is space-padded so all
+ * `|` delimiters align per column, and the separator row is dashes repeated
+ * to each column's width. Column width is max(3, widest cell content).
+ *
+ * Rows may be shorter or longer than headers — missing cells become empty,
+ * extra cells extend the column set.
+ */
+export function alignMarkdownTable(headers: string[], rows: string[][]): string {
+  if (headers.length === 0 && rows.length === 0) return "";
+
+  const columnCount = Math.max(headers.length, ...rows.map((r) => r.length));
+  const widths: number[] = new Array(columnCount).fill(MIN_COLUMN_WIDTH);
+  const track = (cells: string[]) => {
+    for (let i = 0; i < columnCount; i++) {
+      const cell = cells[i] ?? "";
+      if (cell.length > widths[i]) widths[i] = cell.length;
+    }
+  };
+  track(headers);
+  for (const row of rows) track(row);
+
+  const renderRow = (cells: string[]): string => {
+    const parts: string[] = [];
+    for (let i = 0; i < columnCount; i++) {
+      parts.push(` ${(cells[i] ?? "").padEnd(widths[i])} `);
+    }
+    return `|${parts.join("|")}|`;
+  };
+
+  const separator = `|${widths.map((w) => ` ${"-".repeat(w)} `).join("|")}|`;
+
+  const lines: string[] = [renderRow(headers), separator];
+  for (const row of rows) lines.push(renderRow(row));
+  return lines.join("\n");
+}
+
+/** Split a markdown table row on unescaped `|` delimiters; `\|` stays literal. */
+function splitRow(line: string): string[] {
+  const trimmed = line.trim();
+  // Strip optional outer pipes.
+  let inner = trimmed;
+  if (inner.startsWith("|")) inner = inner.slice(1);
+  if (inner.endsWith("|") && !inner.endsWith("\\|")) inner = inner.slice(0, -1);
+
+  const cells: string[] = [];
+  let current = "";
+  for (let i = 0; i < inner.length; i++) {
+    if (inner[i] === "\\" && inner[i + 1] === "|") {
+      current += "\\|";
+      i++;
+    } else if (inner[i] === "|") {
+      cells.push(current.trim());
+      current = "";
+    } else {
+      current += inner[i];
+    }
+  }
+  cells.push(current.trim());
+  return cells;
+}
+
+const SEPARATOR_CELL = /^:?-+:?$/;
+
+/**
+ * Parse a markdown table into headers + rows. Returns null when the input is
+ * not a table (missing separator row). The separator row is detected by
+ * cells matching `:?-+:?` and is dropped — alignment colons are normalized
+ * away on re-emission (forge emitters never produce them).
+ */
+export function parseMarkdownTable(text: string): ParsedMarkdownTable | null {
+  const lines = text
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => l.length > 0);
+  if (lines.length < 2) return null;
+
+  const separatorIndex = lines.findIndex((line, i) => {
+    if (i === 0) return false;
+    const cells = splitRow(line);
+    return cells.length > 0 && cells.every((c) => SEPARATOR_CELL.test(c));
+  });
+  if (separatorIndex !== 1) return null;
+
+  return {
+    headers: splitRow(lines[0]),
+    rows: lines.slice(2).map(splitRow),
+  };
+}

package/src/utils/sync-fs.ts

@@ -0,0 +1,43 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-1152 (Wave 2a): sync ambient filesystem shim for forge helpers that cannot
+take the async WorkspaceIO port without a signature ripple (module-evaluation
+consts like FORGE_SKILLS, sync validators). Centralizes ambient sync fs so
+migrated modules stop importing node:fs directly — the excluded ambient layer
+stays the default for the standalone forge CLI.
+</purpose>
+<non-goals>
+  <item>Do not add async variants — async codepaths use resolveIo from utils/io.ts.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<KEY_DECISIONS>
+  <item>Sync helpers stay ambient — WorkspaceIO is async-only; forcing async would ripple signatures across the forge CLI surface.</item>
+</KEY_DECISIONS>
+<CHANGE_SUMMARY>
+  <item>RFC-1152 Wave 2a: initial sync fs shim for forge ambient layer.</item>
+</CHANGE_SUMMARY>
+*/
+
+export type { Dirent, Stats } from "node:fs";
+export {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  appendFileSync,
+  mkdirSync,
+  readdirSync,
+  statSync,
+  lstatSync,
+  rmSync,
+  cpSync,
+  renameSync,
+  unlinkSync,
+  copyFileSync,
+  realpathSync,
+  chmodSync,
+} from "node:fs";
+export { execSync, execFileSync } from "node:child_process";
+// Async process primitives for the forge ambient layer — os/ handlers spawn
+// git/npm/pnpm; these stay ambient (identical to execSync carve-out).
+export { exec, execFile, spawn } from "node:child_process";

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

@@ -11,7 +11,7 @@
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs";
+import * as fs from "../utils/sync-fs.ts";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
 import type { ForgeCommandResult } from "../types.ts";

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

@@ -11,7 +11,7 @@
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs";
+import * as fs from "../utils/sync-fs.ts";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
 import type { ForgeCommandResult } from "../types.ts";

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

@@ -11,7 +11,7 @@
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs";
+import * as fs from "../utils/sync-fs.ts";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
 import type { ForgeCommandResult } from "../types.ts";

package/src/validators/port-validate.ts

@@ -10,7 +10,7 @@
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs";
+import * as fs from "../utils/sync-fs.ts";
 import path from "node:path";
 import { FORGE_SKILLS } from "../registry.ts";
 

package/src/validators/skill-validate.ts

@@ -1,6 +1,6 @@
 /*
 <MODULE_CONTRACT>
-<purpose>forge.skill.validate — validates all forge skills and declared pack skills against frontmatter contract and invariants SKILL-01..SKILL-21.</purpose>
+<purpose>forge.skill.validate — validates all forge skills and declared pack skills against frontmatter contract and invariants SKILL-01..SKILL-22.</purpose>
 <non-goals>
   <item>Do not validate third-party skills — only forge-managed skills in packages/forge/skills/ and declared pack skills.</item>
 </non-goals>
@@ -19,7 +19,7 @@ Sweep batch 2: real KEY_DECISIONS on 10 files, expanded purposes (CONTRACT-02/PU
 </CHANGE_SUMMARY>
 */
 
-import fs from "node:fs";
+import * as fs from "../utils/sync-fs.ts";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
 import { skillFrontmatterSchema } from "../skill-schema.ts";
@@ -135,6 +135,19 @@ export function runSkillValidate(_input: unknown, context: unknown): SkillValida
       continue;
     }
 
+    // SKILL-22: `triggers` is reserved by agent-IDE skill loaders (Devin CLI,
+    // Windsurf) for invocation modes — a phrase list parses to zero valid
+    // modes and the skill is dropped from discovery entirely. Intent-routing
+    // phrases belong in `triggerPhrases`.
+    if (fm["triggers"] !== undefined) {
+      violations.push({
+        skill: entry.name,
+        rule: "SKILL-22",
+        message:
+          "forbidden 'triggers' key — agent-IDE loaders reserve it for invocation modes (user/model); rename to 'triggerPhrases'",
+      });
+    }
+
     // SKILL-01: Frontmatter parses against Zod schema
     // SKILL-12: concerns must be one of the four-level enum (RFC-0523)
     const parsed = skillFrontmatterSchema.safeParse(fm);
@@ -253,29 +266,29 @@ export function runSkillValidate(_input: unknown, context: unknown): SkillValida
       warnings.push(...checkSkill21Budgets(parsedFiles, budgets, entry.name));
     }
 
-    // SKILL-16: triggers field format and category restriction (RFC-0548)
-    if (parsed.data.triggers) {
+    // SKILL-16: triggerPhrases field format and category restriction (RFC-0548)
+    if (parsed.data.triggerPhrases) {
       if (entry.category !== "fo") {
         violations.push({
           skill: entry.name,
           rule: "SKILL-16",
-          message: `triggers field is only allowed on fo-category skills (got '${entry.category}') — intent-to-skill routing is for fo-skills only`,
+          message: `triggerPhrases field is only allowed on fo-category skills (got '${entry.category}') — intent-to-skill routing is for fo-skills only`,
         });
       }
-      for (const trigger of parsed.data.triggers) {
-        if (trigger.length < 5 || trigger.length > 100) {
+      for (const phrase of parsed.data.triggerPhrases) {
+        if (phrase.length < 5 || phrase.length > 100) {
           violations.push({
             skill: entry.name,
             rule: "SKILL-16",
-            message: `triggers entry '${trigger.slice(0, 50)}' must be 5-100 characters (got ${trigger.length})`,
+            message: `triggerPhrases entry '${phrase.slice(0, 50)}' must be 5-100 characters (got ${phrase.length})`,
           });
         }
       }
-      if (parsed.data.triggers.length > 5) {
+      if (parsed.data.triggerPhrases.length > 5) {
         violations.push({
           skill: entry.name,
           rule: "SKILL-16",
-          message: `triggers array must have at most 5 entries (got ${parsed.data.triggers.length})`,
+          message: `triggerPhrases array must have at most 5 entries (got ${parsed.data.triggerPhrases.length})`,
         });
       }
     }
@@ -337,6 +350,18 @@ export function runSkillValidate(_input: unknown, context: unknown): SkillValida
       continue;
     }
 
+    // SKILL-22: `triggers` is reserved by agent-IDE skill loaders — see the
+    // forge-skill path for rationale. Pack skills must use `triggerPhrases`.
+    if (fm["triggers"] !== undefined) {
+      violations.push({
+        skill: entry.name,
+        pack: entry.pack,
+        rule: "SKILL-22",
+        message:
+          "forbidden 'triggers' key — agent-IDE loaders reserve it for invocation modes (user/model); rename to 'triggerPhrases'",
+      });
+    }
+
     const parsed = skillFrontmatterSchema.safeParse(fm);
     if (!parsed.success) {
       for (const issue of parsed.error.issues) {
@@ -437,14 +462,14 @@ export function runSkillValidate(_input: unknown, context: unknown): SkillValida
       warnings.push(...checkSkill21Budgets(parsedFiles, budgets, entry.name, entry.pack));
     }
 
-    // SKILL-16: triggers field format (RFC-0548) — pack skills may not use triggers
-    if (parsed.data.triggers) {
+    // SKILL-16: triggerPhrases field format (RFC-0548) — pack skills may not declare them
+    if (parsed.data.triggerPhrases) {
       violations.push({
         skill: entry.name,
         pack: entry.pack,
         rule: "SKILL-16",
         message:
-          "triggers field is only allowed on forge fo-category skills — pack skills may not declare triggers",
+          "triggerPhrases field is only allowed on forge fo-category skills — pack skills may not declare triggerPhrases",
       });
     }