@warpgogol/forge 2.8.0 → 2.8.2

package/src/profiles/profile-schema.ts

@@ -0,0 +1,350 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Domain-neutral profile schema extensions — optional fields that allow a stack profile to declare its domain model (terminology, artifacts, workspace types, invariants, register) without breaking backward compatibility.</purpose>
+<non-goals>
+  <item>Do not import from @warpgogol/* — this module is portable.</item>
+  <item>Do not define enforcement logic for invariants — that lives in the invariant engine module.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0638: initial domain-neutral profile schema extensions with six optional fields.</item>
+  <item>RFC-0674: add profileDevServerSchema and devServer field for lifecycle commands.</item>
+  <item>RFC-0675: add profileInvariantCheckSchema and check field to profileInvariantSchema for enforcement.</item>
+  <item>RFC-0679: add profileAssetSchema and assets field for asset management commands.</item>
+  <item>RFC-0680: add profileReleaseSchema and release field for release lifecycle commands.</item>
+  <item>RFC-0694: replace html-attribute-pattern with attribute-pattern (elements array) for HTML+JSX support.</item>
+  <item>Add prerequisites field for profile-declared system dependency checks (e.g. FFmpeg).</item>
+  <item>Add templates field for multi-template profiles (e.g. React + HTML).</item>
+  <item>ADR-0043: add scriptDir field for agent-generated script directory convention.</item>
+  <item>RFC-0808: add link-resolution, frontmatter-required, path-exclusion check kinds for note vault validation.</item>
+  <item>Add gitignore-entry and secret-scan check kinds for godot-csharp profile.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+
+// ---------------------------------------------------------------------------
+// Universal terminology key catalog
+// ---------------------------------------------------------------------------
+
+export const UNIVERSAL_TERMINOLOGY_KEYS = [
+  "artifact",
+  "artifactPlural",
+  "module",
+  "source",
+  "output",
+  "verify",
+  "operator",
+] as const;
+
+export const TERMINOLOGY_DEFAULTS: Record<string, string> = {
+  artifact: "artifact",
+  artifactPlural: "artifacts",
+  module: "module",
+  source: "source file",
+  output: "output",
+  verify: "verify",
+  operator: "operator",
+};
+
+// ---------------------------------------------------------------------------
+// Profile artifact schema
+// ---------------------------------------------------------------------------
+
+export const profileArtifactSchema = z.object({
+  id: z.string().min(1),
+  extensions: z.array(z.string().min(1)),
+  produce: z
+    .object({
+      command: z.string().min(1),
+      output: z.string().optional(),
+    })
+    .optional(),
+  validate: z
+    .object({
+      command: z.string().min(1),
+      outputFormat: z.enum(["plain", "json"]).optional(),
+      violationPattern: z.string().optional(),
+    })
+    .optional(),
+  determinism: z
+    .object({
+      hashable: z.boolean(),
+      inputs: z.array(z.string()),
+    })
+    .optional(),
+});
+
+export interface ProfileArtifact {
+  id: string;
+  extensions: string[];
+  produce?: {
+    command: string;
+    output?: string;
+  };
+  validate?: {
+    command: string;
+    outputFormat?: "plain" | "json";
+    violationPattern?: string;
+  };
+  determinism?: {
+    hashable: boolean;
+    inputs: string[];
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Profile workspace type schema
+// ---------------------------------------------------------------------------
+
+export const profileWorkspaceTypeSchema = z.object({
+  id: z.string().min(1),
+  detect: z.object({
+    glob: z.string().optional(),
+    contains: z.string().optional(),
+    packageJsonDep: z.string().optional(),
+  }),
+  skills: z.array(z.string()).optional(),
+  agentsMdTemplate: z.string().optional(),
+});
+
+export interface ProfileWorkspaceType {
+  id: string;
+  detect: {
+    glob?: string;
+    contains?: string;
+    packageJsonDep?: string;
+  };
+  skills?: string[];
+  agentsMdTemplate?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Profile invariant schema
+// ---------------------------------------------------------------------------
+
+export const profileInvariantCheckSchema = z
+  .object({
+    kind: z.enum([
+      "filename-pattern",
+      "file-contains",
+      "file-not-contains",
+      "attribute-pattern",
+      "link-resolution",
+      "frontmatter-required",
+      "path-exclusion",
+      "gitignore-entry",
+      "secret-scan",
+    ]),
+    glob: z.string().optional(),
+    pattern: z.string().optional(),
+    negatedPattern: z.string().optional(),
+    elements: z.array(z.string()).optional(),
+    attribute: z.string().optional(),
+    fields: z.array(z.string()).optional(),
+  })
+  .refine(
+    (v) =>
+      v.kind !== "attribute-pattern" ||
+      (v.elements != null && v.elements.length > 0 && v.attribute != null && v.pattern != null),
+    {
+      message:
+        "elements (non-empty array), attribute, and pattern are required for kind: attribute-pattern",
+    },
+  )
+  .refine((v) => v.kind !== "frontmatter-required" || (v.fields != null && v.fields.length > 0), {
+    message: "fields (non-empty array) is required for kind: frontmatter-required",
+  });
+
+export interface ProfileInvariantCheck {
+  kind:
+    | "filename-pattern"
+    | "file-contains"
+    | "file-not-contains"
+    | "attribute-pattern"
+    | "link-resolution"
+    | "frontmatter-required"
+    | "path-exclusion"
+    | "gitignore-entry"
+    | "secret-scan";
+  glob?: string;
+  pattern?: string;
+  negatedPattern?: string;
+  elements?: string[];
+  attribute?: string;
+  fields?: string[];
+}
+
+export const profileInvariantSchema = z.object({
+  id: z
+    .string()
+    .min(1)
+    .regex(/^[A-Z]+-\d+$/, "Invariant id must match ^[A-Z]+-\\d+$ (e.g. VIDEO-01)"),
+  rule: z.string().min(1),
+  severity: z.enum(["error", "warning"]),
+  check: profileInvariantCheckSchema.optional(),
+});
+
+export interface ProfileInvariant {
+  id: string;
+  rule: string;
+  severity: "error" | "warning";
+  check?: ProfileInvariantCheck;
+}
+
+// ---------------------------------------------------------------------------
+// Profile dev server schema (RFC-0674)
+// ---------------------------------------------------------------------------
+
+export const profileDevServerSchema = z.object({
+  command: z.string().min(1),
+  port: z.number().int().positive().optional(),
+  readinessTimeout: z.number().int().positive().optional(),
+});
+
+export interface ProfileDevServer {
+  command: string;
+  port?: number;
+  readinessTimeout?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Profile asset schema (RFC-0679)
+// ---------------------------------------------------------------------------
+
+export const profileAssetTypeSchema = z.object({
+  id: z.string().min(1),
+  extensions: z.array(z.string().min(1)),
+  referencePattern: z.string().optional(),
+});
+
+export interface ProfileAssetType {
+  id: string;
+  extensions: string[];
+  referencePattern?: string;
+}
+
+export const profileAssetSchema = z.object({
+  dir: z.string().min(1),
+  types: z.array(profileAssetTypeSchema),
+});
+
+export interface ProfileAsset {
+  dir: string;
+  types: ProfileAssetType[];
+}
+
+// ---------------------------------------------------------------------------
+// Profile release schema (RFC-0680)
+// ---------------------------------------------------------------------------
+
+export const profileReleaseSchema = z.object({
+  target: z.enum(["local", "r2", "s3"]),
+  outputDir: z.string().min(1),
+  manifestName: z.string().default("release-manifest.json"),
+  includeArtifacts: z.array(z.string()).optional(),
+  r2: z
+    .object({
+      bucket: z.string().min(1),
+      accountId: z.string().min(1),
+      prefix: z.string().default(""),
+    })
+    .optional(),
+});
+
+export interface ProfileRelease {
+  target: "local" | "r2" | "s3";
+  outputDir: string;
+  manifestName: string;
+  includeArtifacts?: string[];
+  r2?: {
+    bucket: string;
+    accountId: string;
+    prefix: string;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Profile prerequisite schema
+// ---------------------------------------------------------------------------
+
+export const profilePrerequisiteSchema = z.object({
+  id: z.string().min(1),
+  name: z.string().min(1),
+  check: z.string().min(1),
+  installHint: z.string().optional(),
+  severity: z.enum(["error", "warning"]).default("error"),
+});
+
+export interface ProfilePrerequisite {
+  id: string;
+  name: string;
+  check: string;
+  installHint?: string;
+  severity: "error" | "warning";
+}
+
+// ---------------------------------------------------------------------------
+// Profile template schema (multi-template profiles)
+// ---------------------------------------------------------------------------
+
+export const profileTemplateSchema = z.object({
+  id: z.string().min(1),
+  default: z.boolean().optional(),
+  firstWorkspace: z.object({
+    path: z.string().min(1),
+    files: z.array(
+      z.object({
+        path: z.string().min(1),
+        content: z.string(),
+      }),
+    ),
+    install: z.array(z.string()).default([]),
+  }),
+});
+
+export interface ProfileTemplate {
+  id: string;
+  default?: boolean;
+  firstWorkspace: {
+    path: string;
+    files: Array<{ path: string; content: string }>;
+    install: string[];
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Stack profile domain fields
+// ---------------------------------------------------------------------------
+
+export const stackProfileDomainFieldsSchema = z.object({
+  domain: z.string().optional(),
+  terminology: z.record(z.string(), z.string()).optional(),
+  artifacts: z.array(profileArtifactSchema).optional(),
+  workspaceTypes: z.array(profileWorkspaceTypeSchema).optional(),
+  invariants: z.array(profileInvariantSchema).optional(),
+  register: z.enum(["business", "creative"]).optional(),
+  devServer: profileDevServerSchema.optional(),
+  assets: profileAssetSchema.optional(),
+  release: profileReleaseSchema.optional(),
+  prerequisites: z.array(profilePrerequisiteSchema).optional(),
+  templates: z.array(profileTemplateSchema).optional(),
+  scriptDir: z.string().min(1).optional(),
+  rootAgentsMdTemplate: z.string().optional(),
+});
+
+export interface StackProfileDomainFields {
+  domain?: string;
+  terminology?: Record<string, string>;
+  artifacts?: ProfileArtifact[];
+  workspaceTypes?: ProfileWorkspaceType[];
+  invariants?: ProfileInvariant[];
+  register?: "business" | "creative";
+  devServer?: ProfileDevServer;
+  assets?: ProfileAsset;
+  release?: ProfileRelease;
+  prerequisites?: ProfilePrerequisite[];
+  templates?: ProfileTemplate[];
+  scriptDir?: string;
+  rootAgentsMdTemplate?: string;
+}

package/src/profiles/stack-profile.ts

@@ -0,0 +1,188 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Stack profile schema, loader, and detector. Defines what a supported stack looks like and how to detect it in an existing project.</purpose>
+<non-goals>
+  <item>Do not scaffold projects — that is scaffold-project.ts.</item>
+  <item>Do not import from @warpgogol/* — this module is portable.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0392: initial stack profile module with zod schema, listStackProfiles, detectStack.</item>
+  <item>RFC-0638: extended stackProfileSchema with optional domain-neutral fields (domain, terminology, artifacts, workspaceTypes, invariants, register).</item>
+  <item>RFC-0674: add devServer field to stackProfileSchema for lifecycle commands.</item>
+  <item>RFC-0679: add assets field to stackProfileSchema for asset management commands.</item>
+  <item>RFC-0680: add release field to stackProfileSchema for release lifecycle commands.</item>
+  <item>ADR-0043: add scriptDir field for agent-generated script directory convention.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { parse as parseYaml } from "yaml";
+import { stackProfileDomainFieldsSchema, type StackProfileDomainFields } from "./profile-schema.ts";
+
+// ---------------------------------------------------------------------------
+// Schema (forge/stack-profile@1)
+// ---------------------------------------------------------------------------
+
+export const stackProfileSchema = z.object({
+  schema: z.literal("forge/stack-profile@1"),
+  id: z.string().min(1),
+  displayName: z.string().min(1),
+  detect: z.object({
+    anyOf: z.array(z.string()).min(1),
+  }),
+  workspace: z.object({
+    dirs: z.array(z.string()).min(1),
+    files: z.array(
+      z.object({
+        path: z.string().min(1),
+        content: z.string(),
+      }),
+    ),
+  }),
+  install: z.array(z.string()).default([]),
+  firstWorkspace: z
+    .object({
+      path: z.string().min(1),
+      files: z.array(
+        z.object({
+          path: z.string().min(1),
+          content: z.string(),
+        }),
+      ),
+      install: z.array(z.string()).default([]),
+    })
+    .optional(),
+  // RFC-0638: Domain-neutral optional fields
+  domain: stackProfileDomainFieldsSchema.shape.domain,
+  terminology: stackProfileDomainFieldsSchema.shape.terminology,
+  artifacts: stackProfileDomainFieldsSchema.shape.artifacts,
+  workspaceTypes: stackProfileDomainFieldsSchema.shape.workspaceTypes,
+  invariants: stackProfileDomainFieldsSchema.shape.invariants,
+  register: stackProfileDomainFieldsSchema.shape.register,
+  // RFC-0674: Dev server declaration for lifecycle commands
+  devServer: stackProfileDomainFieldsSchema.shape.devServer,
+  // RFC-0679: Asset management declaration
+  assets: stackProfileDomainFieldsSchema.shape.assets,
+  // RFC-0680: Release lifecycle declaration
+  release: stackProfileDomainFieldsSchema.shape.release,
+  // Prerequisites: system-level dependency checks (e.g. FFmpeg)
+  prerequisites: stackProfileDomainFieldsSchema.shape.prerequisites,
+  // Templates: multi-template profiles (e.g. React + HTML)
+  templates: stackProfileDomainFieldsSchema.shape.templates,
+  // ADR-0043: Agent-generated script directory override
+  scriptDir: stackProfileDomainFieldsSchema.shape.scriptDir,
+  // Profile-driven root AGENTS.md template
+  rootAgentsMdTemplate: stackProfileDomainFieldsSchema.shape.rootAgentsMdTemplate,
+});
+
+export interface ProfileFile {
+  path: string;
+  content: string;
+}
+
+export interface StackProfile extends StackProfileDomainFields {
+  schema: "forge/stack-profile@1";
+  id: string;
+  displayName: string;
+  detect: { anyOf: string[] };
+  workspace: {
+    dirs: string[];
+    files: ProfileFile[];
+  };
+  install: string[];
+  firstWorkspace?: {
+    path: string;
+    files: ProfileFile[];
+    install: string[];
+  };
+  prerequisites?: import("./profile-schema.ts").ProfilePrerequisite[];
+  templates?: import("./profile-schema.ts").ProfileTemplate[];
+}
+
+// ---------------------------------------------------------------------------
+// Loader
+// ---------------------------------------------------------------------------
+
+export function loadStackProfile(profilePath: string): StackProfile {
+  const raw = fs.readFileSync(profilePath, "utf8");
+  let parsed: unknown;
+  try {
+    parsed = parseYaml(raw);
+  } catch (err) {
+    throw new Error(`Stack profile at ${profilePath} is not valid YAML: ${(err as Error).message}`);
+  }
+
+  const result = stackProfileSchema.safeParse(parsed);
+  if (!result.success) {
+    const issues = result.error.issues
+      .map((i) => `  - ${i.path.join(".")}: ${i.message}`)
+      .join("\n");
+    throw new Error(`Stack profile at ${profilePath} failed schema validation:\n${issues}`);
+  }
+
+  return result.data as StackProfile;
+}
+
+export function listStackProfiles(forgeRoot: string): StackProfile[] {
+  const profilesDir = path.join(forgeRoot, "profiles");
+  if (!fs.existsSync(profilesDir)) {
+    return [];
+  }
+
+  const entries = fs.readdirSync(profilesDir);
+  const profiles: StackProfile[] = [];
+
+  for (const entry of entries) {
+    if (entry.endsWith(".yaml") && !entry.startsWith(".")) {
+      const profilePath = path.join(profilesDir, entry);
+      profiles.push(loadStackProfile(profilePath));
+    }
+  }
+
+  return profiles;
+}
+
+// ---------------------------------------------------------------------------
+// Detector
+// ---------------------------------------------------------------------------
+
+export function detectStack(projectRoot: string, profiles: StackProfile[]): StackProfile | null {
+  for (const profile of profiles) {
+    if (matchesAnyOf(projectRoot, profile.detect.anyOf)) {
+      return profile;
+    }
+  }
+  return null;
+}
+
+function matchesAnyOf(projectRoot: string, patterns: string[]): boolean {
+  for (const pattern of patterns) {
+    if (globExists(projectRoot, pattern)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function globExists(dir: string, pattern: string): boolean {
+  // Simple glob: support * and *.ext patterns at the root level
+  if (!pattern.includes("*")) {
+    return fs.existsSync(path.join(dir, pattern));
+  }
+
+  try {
+    const entries = fs.readdirSync(dir);
+    const regex = globToRegex(pattern);
+    return entries.some((e) => regex.test(e));
+  } catch {
+    return false;
+  }
+}
+
+function globToRegex(pattern: string): RegExp {
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+  return new RegExp(`^${escaped}$`);
+}

package/src/profiles/terminology-utils.ts

@@ -0,0 +1,36 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Shared terminology resolution utility (RFC-0643). Resolves all terminology keys
+from config + profile, used by both root and nested AGENTS.md generation.</purpose>
+<non-goals>
+  <item>Do not import from @warpgogol/* — this module is portable.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0643: extracted resolveAllTerminology from agents-generate.ts and nested-agents-generate.ts to eliminate duplication.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { UNIVERSAL_TERMINOLOGY_KEYS } from "./profile-schema.ts";
+import { resolveTerminology, type ForgeConfig } from "../config/forge-config.ts";
+import type { StackProfile } from "./stack-profile.ts";
+
+/**
+ * Resolve all terminology keys (universal + profile-specific) from config and profile.
+ * Used by both root AGENTS.md generation and nested AGENTS.md generation.
+ */
+export function resolveAllTerminology(
+  config: ForgeConfig,
+  profile: StackProfile | undefined,
+): Record<string, string> {
+  const terminology: Record<string, string> = {};
+  for (const key of UNIVERSAL_TERMINOLOGY_KEYS) {
+    terminology[key] = resolveTerminology(config, profile?.terminology, key);
+  }
+  if (profile?.terminology) {
+    for (const key of Object.keys(profile.terminology)) {
+      terminology[key] = resolveTerminology(config, profile.terminology, key);
+    }
+  }
+  return terminology;
+}