@warpgogol/forge 2.7.0 → 2.8.1

package/src/onboarding/workspace-discovery.ts

@@ -0,0 +1,167 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Workspace discovery for nested AGENTS.md generation (RFC-0611).
+Scans the project root for directories containing package.json and auto-detects
+workspace type (app, service, package) by content markers.</purpose>
+<non-goals>
+  <item>Do not scan node_modules, .git, dist, .turbo, .cache, .agents directories.</item>
+  <item>Do not read package.json contents — only check existence for workspace detection.</item>
+  <item>Do not add new workspace-type detection rules without an amending RFC.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0611: initial workspace discovery and type auto-detection.</item>
+  <item>RFC-0640: accept optional workspaceTypes from profile for profile-driven detection, falling back to hardcoded detection when absent.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs";
+import path from "node:path";
+import { hasGeneratedMarker } from "../utils/index.ts";
+import type { ProfileWorkspaceType } from "../profiles/profile-schema.ts";
+
+export type WorkspaceType = "app" | "service" | "package" | string;
+
+export interface WorkspaceDir {
+  path: string;
+  type: WorkspaceType;
+  hasAgentsMd: boolean;
+  isGenerated: boolean;
+}
+
+const SKIP_DIRS = new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  ".turbo",
+  ".cache",
+  ".agents",
+]);
+
+export function detectWorkspaceType(
+  dirPath: string,
+  workspaceTypes?: ProfileWorkspaceType[],
+): WorkspaceType | null {
+  if (!fs.existsSync(path.join(dirPath, "package.json"))) return null;
+
+  // RFC-0640: try profile-driven detection first
+  if (workspaceTypes && workspaceTypes.length > 0) {
+    for (const wt of workspaceTypes) {
+      if (matchesWorkspaceType(dirPath, wt)) {
+        return wt.id;
+      }
+    }
+    // RFC-0640: when workspaceTypes is present, it fully replaces hardcoded detection
+    // Directories matching no profile-declared workspace type are not classified
+    return null;
+  }
+
+  // Fallback: hardcoded detection (software domain)
+  if (
+    fs.existsSync(path.join(dirPath, "astro.config.mjs")) ||
+    fs.existsSync(path.join(dirPath, "astro.config.js")) ||
+    fs.existsSync(path.join(dirPath, "astro.config.ts"))
+  ) {
+    return "app";
+  }
+
+  if (
+    fs.existsSync(path.join(dirPath, "Dockerfile")) ||
+    fs.existsSync(path.join(dirPath, "service.config.yaml")) ||
+    fs.existsSync(path.join(dirPath, "service.config.yml"))
+  ) {
+    return "service";
+  }
+
+  return "package";
+}
+
+function matchesWorkspaceType(dirPath: string, wt: ProfileWorkspaceType): boolean {
+  const { glob: globPattern, contains, packageJsonDep } = wt.detect;
+
+  if (globPattern) {
+    try {
+      const entries = fs.readdirSync(dirPath);
+      const regex = globToRegex(globPattern);
+      if (entries.some((e) => regex.test(e))) return true;
+    } catch {
+      // dir not readable
+    }
+  }
+
+  if (contains) {
+    const filePath = path.join(dirPath, contains);
+    if (fs.existsSync(filePath)) return true;
+  }
+
+  if (packageJsonDep) {
+    try {
+      const pkgJson = JSON.parse(fs.readFileSync(path.join(dirPath, "package.json"), "utf8"));
+      const deps = { ...pkgJson.dependencies, ...pkgJson.devDependencies };
+      if (packageJsonDep in deps) return true;
+    } catch {
+      // package.json not readable
+    }
+  }
+
+  return false;
+}
+
+export function discoverWorkspaces(
+  workspaceRoot: string,
+  workspaceTypes?: ProfileWorkspaceType[],
+): WorkspaceDir[] {
+  const results: WorkspaceDir[] = [];
+
+  function scanDir(dirPath: string, depth: number): void {
+    if (depth > 5) return;
+
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(dirPath, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (SKIP_DIRS.has(entry.name)) continue;
+
+      const childPath = path.join(dirPath, entry.name);
+      const type = detectWorkspaceType(childPath, workspaceTypes);
+
+      if (type !== null) {
+        const agentsMdPath = path.join(childPath, "AGENTS.md");
+        const hasAgentsMd = fs.existsSync(agentsMdPath);
+        let isGenerated = false;
+        if (hasAgentsMd) {
+          try {
+            const content = fs.readFileSync(agentsMdPath, "utf8");
+            isGenerated = hasGeneratedMarker(content);
+          } catch {
+            // unreadable — treat as not generated
+          }
+        }
+
+        results.push({
+          path: path.relative(workspaceRoot, childPath),
+          type,
+          hasAgentsMd,
+          isGenerated,
+        });
+
+        scanDir(childPath, depth + 1);
+      } else {
+        scanDir(childPath, depth + 1);
+      }
+    }
+  }
+
+  scanDir(workspaceRoot, 0);
+  return results;
+}
+
+function globToRegex(pattern: string): RegExp {
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+  return new RegExp(`^${escaped}$`);
+}

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}$`);
+}