@warpgogol/forge 2.8.0 → 2.8.2

package/src/index.ts

@@ -0,0 +1,172 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Public entrypoint for @warpgogol/forge — exports ForgeModule types, canonical types, utilities, skill schema, registry, validators, onboarding, and OS modules.</purpose>
+<non-goals>
+  <item>Do not export internal implementation details — only public API.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0374: initial public exports for forge package.</item>
+  <item>Forge autonomy refactor: add canonical types and utils exports.</item>
+</CHANGE_SUMMARY>
+*/
+
+// Canonical types
+export type {
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeCommandTiming,
+  ForgeNextStep,
+  ForgeFlagValue,
+  ForgeFlagSpec,
+  ForgeCommandMetadata,
+  ForgeRegisteredCommandInfo,
+  ForgeCommandDefinition,
+  ForgeCommandScope,
+  Diagnostic,
+  DiagnosticSeverity,
+  DiagnosticEvidence,
+  CheckResult,
+  ForgeLogger,
+  CommandRegistry,
+  ForgeRuntimeContext,
+  ForgeSiteContext,
+  ForgeOutputFormat,
+  GateMetadata,
+  GateSeverity,
+  GatePhase,
+  GateConditional,
+} from "./types.ts";
+
+// Canonical utilities
+export {
+  writeFileAtomic,
+  type WriteFileAtomicOptions,
+  GENERATED_MARKER,
+  hasGeneratedMarker,
+  stripGeneratedMarker,
+  buildGeneratedHeader,
+  isGeneratedMarkerTextCandidate,
+  type GeneratedHeaderInput,
+  type StripGeneratedMarkerResult,
+  toKebabCase,
+  collectFiles,
+  fileExists,
+  type CollectFilesOptions,
+  byteHash,
+} from "./utils/index.ts";
+
+// ForgeModule types
+export type { ForgeModule, ForgeModuleRegistry, ForgePipelineStep } from "./forge-module.ts";
+
+// Skill schema
+export { skillFrontmatterSchema, type SkillFrontmatter } from "./skill-schema.ts";
+
+// Skill registry
+export { FORGE_SKILLS, type ForgeSkillEntry } from "./registry.ts";
+
+// Forge config (RFC-0391)
+export {
+  forgeConfigSchema,
+  forgeBindingsSchema,
+  defaultForgeConfig,
+  loadForgeConfig,
+  resolveForgeRoot,
+  resolveBinding,
+  resolveTerminology,
+  FORGE_CLI_BINDING_DEFAULTS,
+  PM_RUNNER_MAP,
+  resolvePmRunner,
+  applyCliBindingDefaults,
+  resolvePackageManager,
+  type ForgeConfig,
+  type ForgeBindings,
+  type ForgeCliBindingDefault,
+  type ForgePackageManager,
+  type ForgeMigrationAdapter,
+} from "./config/forge-config.ts";
+
+// Stack profiles (RFC-0392, RFC-0638)
+export {
+  stackProfileSchema,
+  loadStackProfile,
+  listStackProfiles,
+  detectStack,
+  type StackProfile,
+  type ProfileFile,
+} from "./profiles/stack-profile.ts";
+
+// Profile domain fields (RFC-0638)
+export {
+  stackProfileDomainFieldsSchema,
+  profileArtifactSchema,
+  profileWorkspaceTypeSchema,
+  profileInvariantSchema,
+  UNIVERSAL_TERMINOLOGY_KEYS,
+  TERMINOLOGY_DEFAULTS,
+  type StackProfileDomainFields,
+  type ProfileArtifact,
+  type ProfileWorkspaceType,
+  type ProfileInvariant,
+} from "./profiles/profile-schema.ts";
+
+// Knowledge module (RFC-0660)
+export {
+  parseKnowledgeFile,
+  serializeKnowledgeFile,
+  knowledgeEntryMetaSchema,
+  type KnowledgeLayer,
+  type KnowledgeEntryStatus,
+  type KnowledgeEntryMeta,
+  type KnowledgeEntry,
+  type LegacySection,
+  type ParseIssue,
+  type ParsedKnowledgeFile,
+} from "./knowledge/index.ts";
+
+// Validators
+export { runSkillValidate } from "./validators/skill-validate.ts";
+export { runPortValidate } from "./validators/port-validate.ts";
+
+// CLI output rendering (RFC-0542)
+export { renderNextSteps, renderIdeRecommendation, generateHelp } from "./cli-output.ts";
+
+// Onboarding
+export { runInit } from "./onboarding/init.ts";
+export { runScaffold } from "./onboarding/scaffold.ts";
+export { runDoctor } from "./onboarding/doctor.ts";
+export { runAgentsGenerate } from "./onboarding/agents-generate.ts";
+export { runScaffoldProject } from "./onboarding/scaffold-project.ts";
+export { scaffoldMemoryLayer, type MemoryScaffoldResult } from "./onboarding/memory-scaffold.ts";
+
+// Migration adapters (RFC-0546)
+export type {
+  MigrationAdapter,
+  AdapterAnalysis,
+  MigrationResult,
+  Conflict,
+} from "./migration-adapters/types.ts";
+export { FORGE_PROTECTED_PATHS, DEFAULT_EXCLUDE_PATTERNS } from "./migration-adapters/types.ts";
+export {
+  nodeTypescriptPnpmAdapter,
+  phaserPnpmAdapter,
+  getAdapters,
+  detectAdapter,
+  detectAdapters,
+} from "./migration-adapters/index.ts";
+
+// OS modules
+export { forgeCoreModule } from "../os/core/core.module.ts";
+export { forgeRfcModule } from "../os/rfc/rfc.module.ts";
+export { forgeWorkflowModule } from "../os/workflow/workflow.module.ts";
+export { forgeNamingModule } from "../os/naming/naming.module.ts";
+export { forgeCompassModule } from "../os/compass/compass.module.ts";
+export { forgeWerkstattModule } from "../os/werkstatt/werkstatt.module.ts";
+export { forgeSpecModule } from "../os/spec/spec.module.ts";
+export { forgeAdrModule } from "../os/adr/adr.module.ts";
+export { forgePlanModule } from "../os/plan/plan.module.ts";
+export { forgeAuditModule } from "../os/audit/audit.module.ts";
+export { forgeMissionModule } from "../os/mission/mission.module.ts";
+export { forgeExplorationModule } from "../os/exploration/exploration.module.ts";
+export { forgeNotesModule } from "../os/notes/notes.module.ts";
+export { forgeProgramModule } from "../os/program/program.module.ts";

package/src/knowledge/__tests__/promote.test.ts

@@ -0,0 +1,219 @@
+import { describe, it, expect } from "vitest";
+import { normalizeTitle, detectDuplicatePrinciples, planPromotion } from "../promote.ts";
+import type {
+  ParsedKnowledgeFile,
+  KnowledgeEntry,
+  KnowledgeEntryMeta,
+  ParseIssue,
+} from "../schema.ts";
+
+function makeMeta(overrides: Partial<KnowledgeEntryMeta> = {}): KnowledgeEntryMeta {
+  return {
+    id: "K-0001",
+    layer: "L1",
+    created: "2026-01-01",
+    lastConfirmedAt: "2026-01-01",
+    confirmations: 1,
+    status: "active",
+    ...overrides,
+  };
+}
+
+function makeEntry(title: string, meta?: Partial<KnowledgeEntryMeta>): KnowledgeEntry {
+  return { meta: makeMeta(meta), title, body: "", lineStart: 0 };
+}
+
+function makeParsedFile(entries: KnowledgeEntry[], issues: ParseIssue[] = []): ParsedKnowledgeFile {
+  return {
+    path: "qa-log.md",
+    layer: "L1",
+    preamble: "",
+    entries,
+    legacySections: [],
+    isKnowledgeAdjacent: false,
+    parseIssues: issues,
+  };
+}
+
+describe("normalizeTitle", () => {
+  it("lowercases and removes punctuation", () => {
+    expect(normalizeTitle("Hello, World!")).toBe("hello world");
+  });
+
+  it("strips stop words", () => {
+    expect(normalizeTitle("The Quick Brown Fox")).toBe("quick brown fox");
+    expect(normalizeTitle("A Cat on a Mat")).toBe("cat on mat");
+  });
+
+  it("collapses whitespace", () => {
+    expect(normalizeTitle("  Multiple   Spaces  ")).toBe("multiple spaces");
+  });
+
+  it("handles unicode letters", () => {
+    expect(normalizeTitle("Übergröße Straße")).toBe("übergröße straße");
+  });
+
+  it("returns empty for all-stop-word input", () => {
+    expect(normalizeTitle("the a an")).toBe("");
+  });
+});
+
+describe("detectDuplicatePrinciples", () => {
+  it("detects exact title matches across skills", () => {
+    const files = [
+      { skill: "skill-a", parsed: makeParsedFile([makeEntry("Always Check Types")]) },
+      { skill: "skill-b", parsed: makeParsedFile([makeEntry("Always Check Types")]) },
+    ];
+    const dupes = detectDuplicatePrinciples(files);
+    expect(dupes).toHaveLength(1);
+    expect(dupes[0].kind).toBe("exact");
+  });
+
+  it("skips stale and archived entries", () => {
+    const files = [
+      {
+        skill: "skill-a",
+        parsed: makeParsedFile([makeEntry("Same Title", { id: "K-0001", status: "stale" })]),
+      },
+      {
+        skill: "skill-b",
+        parsed: makeParsedFile([makeEntry("Same Title", { id: "K-0002", status: "archived" })]),
+      },
+    ];
+    expect(detectDuplicatePrinciples(files)).toHaveLength(0);
+  });
+
+  it("skips already-promoted entries", () => {
+    const files = [
+      {
+        skill: "skill-a",
+        parsed: makeParsedFile([makeEntry("Title", { id: "K-0001", promotedTo: "shared/K-0002" })]),
+      },
+      { skill: "skill-b", parsed: makeParsedFile([makeEntry("Title", { id: "K-0002" })]) },
+    ];
+    expect(detectDuplicatePrinciples(files)).toHaveLength(0);
+  });
+
+  it("skips linked pairs via supersedes", () => {
+    const files = [
+      {
+        skill: "skill-a",
+        parsed: makeParsedFile([makeEntry("Same Title", { supersedes: ["K-0002"] })]),
+      },
+      { skill: "skill-b", parsed: makeParsedFile([makeEntry("Same Title", { id: "K-0002" })]) },
+    ];
+    expect(detectDuplicatePrinciples(files)).toHaveLength(0);
+  });
+
+  it("skips knowledge-adjacent files", () => {
+    const parsed = makeParsedFile([makeEntry("Title", { id: "K-0001" })]);
+    parsed.isKnowledgeAdjacent = true;
+    const files = [
+      { skill: "skill-a", parsed },
+      { skill: "skill-b", parsed: makeParsedFile([makeEntry("Title", { id: "K-0002" })]) },
+    ];
+    expect(detectDuplicatePrinciples(files)).toHaveLength(0);
+  });
+
+  it("skips files with parse issues", () => {
+    const files = [
+      {
+        skill: "skill-a",
+        parsed: makeParsedFile(
+          [makeEntry("Title", { id: "K-0001" })],
+          [{ line: 1, message: "bad" }],
+        ),
+      },
+      { skill: "skill-b", parsed: makeParsedFile([makeEntry("Title", { id: "K-0002" })]) },
+    ];
+    expect(detectDuplicatePrinciples(files)).toHaveLength(0);
+  });
+
+  it("detects containment when shorter title is substring of longer", () => {
+    const files = [
+      {
+        skill: "skill-a",
+        parsed: makeParsedFile([
+          makeEntry("Always validate input before processing", { id: "K-0001" }),
+        ]),
+      },
+      {
+        skill: "skill-b",
+        parsed: makeParsedFile([
+          makeEntry("Always validate input before processing and after", { id: "K-0002" }),
+        ]),
+      },
+    ];
+    const dupes = detectDuplicatePrinciples(files);
+    expect(dupes).toHaveLength(1);
+    expect(dupes[0].kind).toBe("containment");
+  });
+
+  it("does not detect containment for very short titles", () => {
+    const files = [
+      { skill: "skill-a", parsed: makeParsedFile([makeEntry("Check types", { id: "K-0001" })]) },
+      {
+        skill: "skill-b",
+        parsed: makeParsedFile([makeEntry("Check types and more", { id: "K-0002" })]),
+      },
+    ];
+    expect(detectDuplicatePrinciples(files)).toHaveLength(0);
+  });
+
+  it("returns empty for no duplicates", () => {
+    const files = [
+      { skill: "skill-a", parsed: makeParsedFile([makeEntry("Unique Title A", { id: "K-0001" })]) },
+      { skill: "skill-b", parsed: makeParsedFile([makeEntry("Unique Title B", { id: "K-0002" })]) },
+    ];
+    expect(detectDuplicatePrinciples(files)).toHaveLength(0);
+  });
+});
+
+describe("planPromotion", () => {
+  it("creates shared entry with summed confirmations", () => {
+    const sources = [
+      {
+        skill: "skill-a",
+        file: "qa-log.md",
+        entry: makeEntry("Shared Principle", { id: "K-0001", confirmations: 3 }),
+      },
+      {
+        skill: "skill-b",
+        file: "qa-log.md",
+        entry: makeEntry("Shared Principle", { id: "K-0002", confirmations: 5 }),
+      },
+    ];
+    const plan = planPromotion(
+      sources,
+      { title: "Merged", body: "Combined body" },
+      "K-0099",
+      "2026-08-20",
+    );
+    expect(plan.sharedEntry.meta.id).toBe("K-0099");
+    expect(plan.sharedEntry.meta.layer).toBe("L2");
+    expect(plan.sharedEntry.meta.confirmations).toBe(8);
+    expect(plan.sharedEntry.meta.promotedFrom).toEqual(["skill-a/K-0001", "skill-b/K-0002"]);
+    expect(plan.sharedEntry.title).toBe("Merged");
+    expect(plan.sharedEntry.body).toBe("Combined body");
+  });
+
+  it("creates local pointers for each source", () => {
+    const sources = [
+      { skill: "skill-a", file: "qa-log.md", entry: makeEntry("Title", { id: "K-0001" }) },
+      { skill: "skill-b", file: "learned.md", entry: makeEntry("Title", { id: "K-0002" }) },
+    ];
+    const plan = planPromotion(sources, { title: "M", body: "B" }, "K-0099", "2026-01-01");
+    expect(plan.localPointers).toEqual([
+      { skill: "skill-a", file: "qa-log.md", entryId: "K-0001" },
+      { skill: "skill-b", file: "learned.md", entryId: "K-0002" },
+    ]);
+  });
+
+  it("handles undefined confirmations as zero", () => {
+    const sources = [
+      { skill: "s", file: "f.md", entry: makeEntry("T", { confirmations: undefined }) },
+    ];
+    const plan = planPromotion(sources, { title: "M", body: "B" }, "K-0099", "2026-01-01");
+    expect(plan.sharedEntry.meta.confirmations).toBe(0);
+  });
+});

package/src/knowledge/__tests__/serialize.test.ts

@@ -0,0 +1,192 @@
+import { describe, it, expect } from "vitest";
+import { serializeKnowledgeFile } from "../serialize.ts";
+import type { ParsedKnowledgeFile, KnowledgeEntryMeta } from "../schema.ts";
+
+function makeMeta(overrides: Partial<KnowledgeEntryMeta> = {}): KnowledgeEntryMeta {
+  return {
+    id: "entry-001",
+    layer: "L1",
+    created: "2026-01-01",
+    lastConfirmedAt: "2026-01-01",
+    confirmations: 1,
+    status: "active",
+    ...overrides,
+  };
+}
+
+describe("serializeKnowledgeFile", () => {
+  it("serializes empty parsed file to single newline", () => {
+    const parsed: ParsedKnowledgeFile = {
+      path: "test.md",
+      layer: "L1",
+      preamble: "",
+      entries: [],
+      legacySections: [],
+      isKnowledgeAdjacent: false,
+      parseIssues: [],
+    };
+    expect(serializeKnowledgeFile(parsed)).toBe("\n");
+  });
+
+  it("serializes preamble only", () => {
+    const parsed: ParsedKnowledgeFile = {
+      path: "test.md",
+      layer: "L1",
+      preamble: "# My Knowledge File",
+      entries: [],
+      legacySections: [],
+      isKnowledgeAdjacent: false,
+      parseIssues: [],
+    };
+    expect(serializeKnowledgeFile(parsed)).toBe("# My Knowledge File\n");
+  });
+
+  it("serializes a single entry with meta and body", () => {
+    const parsed: ParsedKnowledgeFile = {
+      path: "test.md",
+      layer: "L1",
+      preamble: "",
+      entries: [
+        {
+          meta: makeMeta(),
+          title: "First Principle",
+          body: "This is the body text.",
+          lineStart: 0,
+        },
+      ],
+      legacySections: [],
+      isKnowledgeAdjacent: false,
+      parseIssues: [],
+    };
+    const result = serializeKnowledgeFile(parsed);
+    expect(result).toContain("### entry-001: First Principle");
+    expect(result).toContain("```knowledge-entry");
+    expect(result).toContain("id: entry-001");
+    expect(result).toContain("layer: L1");
+    expect(result).toContain("status: active");
+    expect(result).toContain("This is the body text.");
+    expect(result).toContain("```");
+  });
+
+  it("omits undefined meta fields", () => {
+    const parsed: ParsedKnowledgeFile = {
+      path: "test.md",
+      layer: "L1",
+      preamble: "",
+      entries: [
+        {
+          meta: makeMeta({ supersedes: undefined, promotedTo: undefined, expiresAt: undefined }),
+          title: "Minimal",
+          body: "",
+          lineStart: 0,
+        },
+      ],
+      legacySections: [],
+      isKnowledgeAdjacent: false,
+      parseIssues: [],
+    };
+    const result = serializeKnowledgeFile(parsed);
+    expect(result).not.toContain("supersedes");
+    expect(result).not.toContain("promotedTo");
+    expect(result).not.toContain("expiresAt");
+  });
+
+  it("serializes array meta values as inline arrays", () => {
+    const parsed: ParsedKnowledgeFile = {
+      path: "test.md",
+      layer: "L1",
+      preamble: "",
+      entries: [
+        {
+          meta: makeMeta({ supersedes: ["old-001", "old-002"] }),
+          title: "Merged",
+          body: "",
+          lineStart: 0,
+        },
+      ],
+      legacySections: [],
+      isKnowledgeAdjacent: false,
+      parseIssues: [],
+    };
+    const result = serializeKnowledgeFile(parsed);
+    expect(result).toContain("supersedes: [old-001, old-002]");
+  });
+
+  it("serializes empty array as []", () => {
+    const parsed: ParsedKnowledgeFile = {
+      path: "test.md",
+      layer: "L1",
+      preamble: "",
+      entries: [
+        {
+          meta: makeMeta({ supersedes: [] }),
+          title: "Empty",
+          body: "",
+          lineStart: 0,
+        },
+      ],
+      legacySections: [],
+      isKnowledgeAdjacent: false,
+      parseIssues: [],
+    };
+    const result = serializeKnowledgeFile(parsed);
+    expect(result).toContain("supersedes: []");
+  });
+
+  it("serializes null meta value as null", () => {
+    const parsed: ParsedKnowledgeFile = {
+      path: "test.md",
+      layer: "L1",
+      preamble: "",
+      entries: [
+        {
+          meta: makeMeta({ promotedTo: null }),
+          title: "Null",
+          body: "",
+          lineStart: 0,
+        },
+      ],
+      legacySections: [],
+      isKnowledgeAdjacent: false,
+      parseIssues: [],
+    };
+    const result = serializeKnowledgeFile(parsed);
+    expect(result).toContain("promotedTo: null");
+  });
+
+  it("serializes legacy sections", () => {
+    const parsed: ParsedKnowledgeFile = {
+      path: "test.md",
+      layer: "L1",
+      preamble: "",
+      entries: [],
+      legacySections: [{ text: "## Old Section\n\nSome content", lineStart: 0 }],
+      isKnowledgeAdjacent: false,
+      parseIssues: [],
+    };
+    const result = serializeKnowledgeFile(parsed);
+    expect(result).toContain("## Old Section");
+    expect(result).toContain("Some content");
+  });
+
+  it("collapses excessive newlines to max two", () => {
+    const parsed: ParsedKnowledgeFile = {
+      path: "test.md",
+      layer: "L1",
+      preamble: "preamble",
+      entries: [
+        {
+          meta: makeMeta(),
+          title: "Title",
+          body: "body",
+          lineStart: 0,
+        },
+      ],
+      legacySections: [],
+      isKnowledgeAdjacent: false,
+      parseIssues: [],
+    };
+    const result = serializeKnowledgeFile(parsed);
+    expect(result).not.toMatch(/\n{3,}/);
+  });
+});