@warpgogol/forge 2.7.0 → 2.8.1

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/budgets.ts

@@ -0,0 +1,202 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Knowledge layer character budget computation and resolution — pure functions for hot/warm budget enforcement (RFC-0661).</purpose>
+<non-goals>
+  <item>Do not emit warnings or violations — that is handled by SKILL-21 in skill-validate.ts.</item>
+  <item>Do not parse knowledge files — that is handled by parse.ts (RFC-0660).</item>
+  <item>Do not validate budget override shape — that is handled by forge.doctor.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0661: initial budget module with KnowledgeBudgets, LayerBudgetReport, computeLayerBudgets, resolveKnowledgeBudgets.</item>
+</CHANGE_SUMMARY>
+*/
+
+import path from "node:path";
+import { readFileSync } from "node:fs";
+import { parse as parseYaml } from "yaml";
+import type { ParsedKnowledgeFile, KnowledgeLayer } from "./schema.ts";
+
+// ---------------------------------------------------------------------------
+// Types (RFC-0661)
+// ---------------------------------------------------------------------------
+
+export interface KnowledgeBudgets {
+  hot: number; // default 4096 — L2 (learned-principles.md)
+  warm: number; // default 8192 — L1 (fix-patterns.md)
+}
+
+export interface LayerBudgetReport {
+  skill: string;
+  file: string;
+  layer: KnowledgeLayer;
+  activeChars: number;
+  budget: number;
+  exceededBy: number; // 0 when within budget
+  pack?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+
+export const DEFAULT_KNOWLEDGE_BUDGETS: KnowledgeBudgets = {
+  hot: 4096,
+  warm: 8192,
+};
+
+// ---------------------------------------------------------------------------
+// computeLayerBudgets — pure function
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute per-file budget reports for parsed knowledge files.
+ *
+ * - Counts only `status: active` entries (heading + metadata block + body).
+ * - Uses `ParsedKnowledgeFile.layer` to determine which budget applies.
+ * - Skips files with undeterminable layer (null) or L0 (cold, no budget).
+ * - Skips files with parse issues (schema errors are already reported by SKILL-19).
+ *
+ * Pure: no filesystem side effects.
+ */
+export function computeLayerBudgets(
+  files: ParsedKnowledgeFile[],
+  budgets: KnowledgeBudgets,
+  skillNames: Map<string, string>,
+): LayerBudgetReport[] {
+  const reports: LayerBudgetReport[] = [];
+
+  for (const file of files) {
+    // Skip files with undeterminable layer
+    if (file.layer === null) {
+      continue;
+    }
+
+    // Skip cold layer (L0) — no budget by design
+    if (file.layer === "L0") {
+      continue;
+    }
+
+    // Skip files with parse issues — SKILL-19 already reports those
+    if (file.parseIssues.length > 0) {
+      continue;
+    }
+
+    // Skip knowledge-adjacent files (no structured entries)
+    if (file.isKnowledgeAdjacent) {
+      continue;
+    }
+
+    const budget = file.layer === "L2" ? budgets.hot : budgets.warm;
+    const fileName = path.basename(file.path);
+    const skillName = skillNames.get(file.path) ?? path.basename(path.dirname(file.path));
+
+    // Count only active entries: heading + metadata block + body
+    let activeChars = 0;
+    for (const entry of file.entries) {
+      if (entry.meta.status !== "active") {
+        continue;
+      }
+      // Heading: "### K-XXXX: <title>\n"
+      activeChars += `### ${entry.meta.id}: ${entry.title}\n`.length;
+      // Metadata block: ```knowledge-entry\n<yaml>\n```\n
+      const metaYaml = approximateMetaCharCount(entry.meta);
+      activeChars += "```knowledge-entry\n".length;
+      activeChars += metaYaml.length;
+      activeChars += "```\n".length;
+      // Body
+      activeChars += entry.body.length;
+    }
+
+    const exceededBy = Math.max(0, activeChars - budget);
+
+    reports.push({
+      skill: skillName,
+      file: fileName,
+      layer: file.layer,
+      activeChars,
+      budget,
+      exceededBy,
+    });
+  }
+
+  return reports;
+}
+
+// ---------------------------------------------------------------------------
+// resolveKnowledgeBudgets — reads forge.yaml
+// ---------------------------------------------------------------------------
+
+/**
+ * Read effective knowledge budgets from forge.yaml bindings.
+ *
+ * Falls back to defaults (hot: 4096, warm: 8192) when:
+ * - forge.yaml is not found
+ * - bindings.knowledge.budgets is absent
+ * - override values are invalid (non-positive, non-integer)
+ *
+ * Does NOT validate the override shape — forge.doctor handles that separately.
+ */
+export function resolveKnowledgeBudgets(workspaceRoot: string): KnowledgeBudgets {
+  try {
+    const forgeYamlPath = path.join(workspaceRoot, "forge.yaml");
+    const content = readFileSync(forgeYamlPath, "utf8");
+    const config = parseYaml(content) as Record<string, unknown>;
+    const bindings = config?.bindings as Record<string, unknown> | undefined;
+    const knowledge = bindings?.knowledge as Record<string, unknown> | undefined;
+    const budgets = knowledge?.budgets as { hot?: unknown; warm?: unknown } | undefined;
+
+    if (!budgets) {
+      return { ...DEFAULT_KNOWLEDGE_BUDGETS };
+    }
+
+    const hot =
+      typeof budgets.hot === "number" && budgets.hot > 0 && Number.isInteger(budgets.hot)
+        ? budgets.hot
+        : DEFAULT_KNOWLEDGE_BUDGETS.hot;
+    const warm =
+      typeof budgets.warm === "number" && budgets.warm > 0 && Number.isInteger(budgets.warm)
+        ? budgets.warm
+        : DEFAULT_KNOWLEDGE_BUDGETS.warm;
+
+    return { hot, warm };
+  } catch {
+    return { ...DEFAULT_KNOWLEDGE_BUDGETS };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helper: approximate metadata character count for budget measurement
+// ---------------------------------------------------------------------------
+
+/**
+ * Approximate metadata character count for budget purposes.
+ *
+ * This is NOT exact YAML serialization — it produces a line-per-field
+ * approximation that is deterministic and sufficient for character budget
+ * measurement. The RFC explicitly rejects tokenizer-accurate measurement;
+ * this approximation is the documented proxy.
+ */
+function approximateMetaCharCount(meta: ParsedKnowledgeFile["entries"][number]["meta"]): string {
+  const lines: string[] = [];
+  lines.push(`id: ${meta.id}`);
+  lines.push(`layer: ${meta.layer}`);
+  lines.push(`created: ${meta.created}`);
+  if (meta.lastConfirmedAt !== undefined) {
+    lines.push(`lastConfirmedAt: ${meta.lastConfirmedAt ?? "null"}`);
+  }
+  if (meta.confirmations !== undefined) {
+    lines.push(`confirmations: ${meta.confirmations}`);
+  }
+  if (meta.expiresAt !== undefined) {
+    lines.push(`expiresAt: ${meta.expiresAt ?? "null"}`);
+  }
+  if (meta.supersedes !== undefined) {
+    lines.push(`supersedes: [${meta.supersedes.join(", ")}]`);
+  }
+  if (meta.promotedTo !== undefined) {
+    lines.push(`promotedTo: ${meta.promotedTo ?? "null"}`);
+  }
+  lines.push(`status: ${meta.status}`);
+  return lines.join("\n") + "\n";
+}