@warpgogol/forge 2.8.0 → 2.8.2

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/__tests__/profile-schema.test.ts

@@ -0,0 +1,228 @@
+import { describe, it, expect } from "vitest";
+import {
+  profileInvariantSchema,
+  profileInvariantCheckSchema,
+  profileDevServerSchema,
+  profileReleaseSchema,
+  profilePrerequisiteSchema,
+  profileArtifactSchema,
+  UNIVERSAL_TERMINOLOGY_KEYS,
+  TERMINOLOGY_DEFAULTS,
+} from "../profile-schema.ts";
+
+describe("UNIVERSAL_TERMINOLOGY_KEYS", () => {
+  it("contains expected keys", () => {
+    expect(UNIVERSAL_TERMINOLOGY_KEYS).toContain("artifact");
+    expect(UNIVERSAL_TERMINOLOGY_KEYS).toContain("module");
+    expect(UNIVERSAL_TERMINOLOGY_KEYS).toContain("operator");
+  });
+});
+
+describe("TERMINOLOGY_DEFAULTS", () => {
+  it("has defaults for all universal keys", () => {
+    for (const key of UNIVERSAL_TERMINOLOGY_KEYS) {
+      expect(TERMINOLOGY_DEFAULTS[key]).toBeDefined();
+    }
+  });
+});
+
+describe("profileArtifactSchema", () => {
+  it("accepts minimal artifact with id and extensions", () => {
+    const result = profileArtifactSchema.safeParse({
+      id: "html-pages",
+      extensions: [".html"],
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("accepts artifact with produce and validate", () => {
+    const result = profileArtifactSchema.safeParse({
+      id: "html-pages",
+      extensions: [".html"],
+      produce: { command: "astro build", output: "dist" },
+      validate: { command: "check", outputFormat: "json" },
+      determinism: { hashable: true, inputs: ["src"] },
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects artifact without id", () => {
+    const result = profileArtifactSchema.safeParse({ extensions: [".html"] });
+    expect(result.success).toBe(false);
+  });
+
+  it("accepts artifact with empty extensions array", () => {
+    const result = profileArtifactSchema.safeParse({ id: "test", extensions: [] });
+    expect(result.success).toBe(true);
+  });
+});
+
+describe("profileInvariantCheckSchema", () => {
+  it("accepts filename-pattern kind", () => {
+    const result = profileInvariantCheckSchema.safeParse({
+      kind: "filename-pattern",
+      glob: "*.ts",
+      pattern: "^[a-z-]+\\.ts$",
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("accepts attribute-pattern kind with required fields", () => {
+    const result = profileInvariantCheckSchema.safeParse({
+      kind: "attribute-pattern",
+      elements: ["img"],
+      attribute: "src",
+      pattern: "^/assets/",
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects attribute-pattern without elements", () => {
+    const result = profileInvariantCheckSchema.safeParse({
+      kind: "attribute-pattern",
+      attribute: "src",
+      pattern: "^/assets/",
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects attribute-pattern with empty elements array", () => {
+    const result = profileInvariantCheckSchema.safeParse({
+      kind: "attribute-pattern",
+      elements: [],
+      attribute: "src",
+      pattern: "^/assets/",
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("accepts frontmatter-required with fields", () => {
+    const result = profileInvariantCheckSchema.safeParse({
+      kind: "frontmatter-required",
+      fields: ["title", "created"],
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects frontmatter-required without fields", () => {
+    const result = profileInvariantCheckSchema.safeParse({
+      kind: "frontmatter-required",
+    });
+    expect(result.success).toBe(false);
+  });
+});
+
+describe("profileInvariantSchema", () => {
+  it("accepts valid invariant with id matching pattern", () => {
+    const result = profileInvariantSchema.safeParse({
+      id: "VIDEO-01",
+      rule: "All videos must have captions",
+      severity: "error",
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects id not matching ^[A-Z]+-\\d+$ pattern", () => {
+    const result = profileInvariantSchema.safeParse({
+      id: "video-01",
+      rule: "test",
+      severity: "error",
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects invalid severity", () => {
+    const result = profileInvariantSchema.safeParse({
+      id: "VIDEO-01",
+      rule: "test",
+      severity: "critical",
+    });
+    expect(result.success).toBe(false);
+  });
+});
+
+describe("profileDevServerSchema", () => {
+  it("accepts minimal dev server with command", () => {
+    const result = profileDevServerSchema.safeParse({ command: "astro dev" });
+    expect(result.success).toBe(true);
+  });
+
+  it("accepts dev server with port and timeout", () => {
+    const result = profileDevServerSchema.safeParse({
+      command: "astro dev",
+      port: 4321,
+      readinessTimeout: 5000,
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects empty command", () => {
+    const result = profileDevServerSchema.safeParse({ command: "" });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects negative port", () => {
+    const result = profileDevServerSchema.safeParse({ command: "dev", port: -1 });
+    expect(result.success).toBe(false);
+  });
+});
+
+describe("profileReleaseSchema", () => {
+  it("accepts local release target", () => {
+    const result = profileReleaseSchema.safeParse({
+      target: "local",
+      outputDir: "dist",
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("accepts r2 release target with required fields", () => {
+    const result = profileReleaseSchema.safeParse({
+      target: "r2",
+      outputDir: "dist",
+      r2: { bucket: "my-bucket", accountId: "123" },
+    });
+    expect(result.success).toBe(true);
+    expect(result.success && result.data?.manifestName).toBe("release-manifest.json");
+  });
+
+  it("rejects invalid target", () => {
+    const result = profileReleaseSchema.safeParse({
+      target: "invalid",
+      outputDir: "dist",
+    });
+    expect(result.success).toBe(false);
+  });
+});
+
+describe("profilePrerequisiteSchema", () => {
+  it("accepts minimal prerequisite", () => {
+    const result = profilePrerequisiteSchema.safeParse({
+      id: "ffmpeg",
+      name: "FFmpeg",
+      check: "ffmpeg -version",
+    });
+    expect(result.success).toBe(true);
+    expect(result.success && result.data?.severity).toBe("error");
+  });
+
+  it("accepts warning severity", () => {
+    const result = profilePrerequisiteSchema.safeParse({
+      id: "ffmpeg",
+      name: "FFmpeg",
+      check: "ffmpeg -version",
+      severity: "warning",
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects invalid severity", () => {
+    const result = profilePrerequisiteSchema.safeParse({
+      id: "ffmpeg",
+      name: "FFmpeg",
+      check: "ffmpeg -version",
+      severity: "critical",
+    });
+    expect(result.success).toBe(false);
+  });
+});

package/src/profiles/__tests__/stack-profile.test.ts

@@ -0,0 +1,190 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import {
+  loadStackProfile,
+  listStackProfiles,
+  detectStack,
+  stackProfileSchema,
+} from "../stack-profile.ts";
+import { mkdtemp, rm, writeFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+let tempDir: string;
+
+beforeEach(async () => {
+  tempDir = await mkdtemp(join(tmpdir(), "forge-profile-"));
+});
+
+afterEach(async () => {
+  await rm(tempDir, { recursive: true, force: true });
+});
+
+const validProfileYaml = `
+schema: forge/stack-profile@1
+id: test-stack
+displayName: Test Stack
+detect:
+  anyOf:
+    - package.json
+workspace:
+  dirs:
+    - packages
+  files:
+    - path: package.json
+      content: '{}'
+install: []
+`;
+
+describe("stackProfileSchema", () => {
+  it("accepts a valid minimal profile", () => {
+    const result = stackProfileSchema.safeParse({
+      schema: "forge/stack-profile@1",
+      id: "test",
+      displayName: "Test",
+      detect: { anyOf: ["package.json"] },
+      workspace: { dirs: ["packages"], files: [] },
+      install: [],
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects wrong schema literal", () => {
+    const result = stackProfileSchema.safeParse({
+      schema: "wrong",
+      id: "test",
+      displayName: "Test",
+      detect: { anyOf: ["package.json"] },
+      workspace: { dirs: ["packages"], files: [] },
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects empty anyOf array", () => {
+    const result = stackProfileSchema.safeParse({
+      schema: "forge/stack-profile@1",
+      id: "test",
+      displayName: "Test",
+      detect: { anyOf: [] },
+      workspace: { dirs: ["packages"], files: [] },
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("accepts optional domain fields", () => {
+    const result = stackProfileSchema.safeParse({
+      schema: "forge/stack-profile@1",
+      id: "test",
+      displayName: "Test",
+      detect: { anyOf: ["package.json"] },
+      workspace: { dirs: ["packages"], files: [] },
+      install: [],
+      domain: "software",
+      terminology: { artifact: "module" },
+      register: "business",
+    });
+    expect(result.success).toBe(true);
+  });
+});
+
+describe("loadStackProfile", () => {
+  it("loads a valid YAML profile", async () => {
+    const profilePath = join(tempDir, "test.yaml");
+    await writeFile(profilePath, validProfileYaml, "utf8");
+    const profile = loadStackProfile(profilePath);
+    expect(profile.id).toBe("test-stack");
+    expect(profile.displayName).toBe("Test Stack");
+  });
+
+  it("throws on invalid YAML", async () => {
+    const profilePath = join(tempDir, "bad.yaml");
+    await writeFile(profilePath, "not: valid: yaml: [", "utf8");
+    expect(() => loadStackProfile(profilePath)).toThrow();
+  });
+
+  it("throws on schema validation failure", async () => {
+    const profilePath = join(tempDir, "invalid.yaml");
+    await writeFile(profilePath, "schema: wrong\nid: test\n", "utf8");
+    expect(() => loadStackProfile(profilePath)).toThrow();
+  });
+});
+
+describe("listStackProfiles", () => {
+  it("returns empty array when profiles dir missing", () => {
+    expect(listStackProfiles(join(tempDir, "nonexistent"))).toEqual([]);
+  });
+
+  it("lists all .yaml profiles in the directory", async () => {
+    const profilesDir = join(tempDir, "profiles");
+    await mkdir(profilesDir, { recursive: true });
+    await writeFile(join(profilesDir, "a.yaml"), validProfileYaml, "utf8");
+    await writeFile(
+      join(profilesDir, "b.yaml"),
+      validProfileYaml.replace("test-stack", "test-stack-b"),
+      "utf8",
+    );
+    await writeFile(join(profilesDir, ".hidden.yaml"), validProfileYaml, "utf8");
+
+    const profiles = listStackProfiles(tempDir);
+    expect(profiles).toHaveLength(2);
+    const ids = profiles.map((p) => p.id);
+    expect(ids).toContain("test-stack");
+    expect(ids).toContain("test-stack-b");
+  });
+});
+
+describe("detectStack", () => {
+  it("detects matching profile", async () => {
+    await writeFile(join(tempDir, "package.json"), "{}", "utf8");
+    const profiles = [
+      {
+        schema: "forge/stack-profile@1" as const,
+        id: "a",
+        displayName: "A",
+        detect: { anyOf: ["package.json"] },
+        workspace: { dirs: [], files: [] },
+        install: [],
+      },
+      {
+        schema: "forge/stack-profile@1" as const,
+        id: "b",
+        displayName: "B",
+        detect: { anyOf: ["nonexistent.file"] },
+        workspace: { dirs: [], files: [] },
+        install: [],
+      },
+    ];
+
+    const result = detectStack(tempDir, profiles);
+    expect(result?.id).toBe("a");
+  });
+
+  it("returns null when no profile matches", () => {
+    const profiles = [
+      {
+        schema: "forge/stack-profile@1" as const,
+        id: "x",
+        displayName: "X",
+        detect: { anyOf: ["nonexistent.file"] },
+        workspace: { dirs: [], files: [] },
+        install: [],
+      },
+    ];
+    expect(detectStack(tempDir, profiles)).toBeNull();
+  });
+
+  it("supports glob patterns in detect.anyOf", async () => {
+    await writeFile(join(tempDir, "astro.config.mjs"), "export default {}", "utf8");
+    const profiles = [
+      {
+        schema: "forge/stack-profile@1" as const,
+        id: "astro",
+        displayName: "Astro",
+        detect: { anyOf: ["astro.config.*"] },
+        workspace: { dirs: [], files: [] },
+        install: [],
+      },
+    ];
+    const result = detectStack(tempDir, profiles);
+    expect(result?.id).toBe("astro");
+  });
+});

package/src/profiles/__tests__/terminology-utils.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect } from "vitest";
+import { resolveAllTerminology } from "../terminology-utils.ts";
+import { defaultForgeConfig } from "../../config/forge-config.ts";
+import { TERMINOLOGY_DEFAULTS } from "../profile-schema.ts";
+import type { StackProfile } from "../stack-profile.ts";
+
+function makeProfile(terminology?: Record<string, string>): StackProfile {
+  return {
+    schema: "forge/stack-profile@1",
+    id: "test-profile",
+    displayName: "Test",
+    detect: { anyOf: ["package.json"] },
+    workspace: { dirs: ["packages"], files: [] },
+    install: [],
+    terminology,
+  };
+}
+
+describe("resolveAllTerminology", () => {
+  it("returns universal defaults when no overrides exist", () => {
+    const config = defaultForgeConfig("test");
+    const profile = makeProfile();
+    const result = resolveAllTerminology(config, profile);
+    expect(result.artifact).toBe(TERMINOLOGY_DEFAULTS.artifact);
+    expect(result.operator).toBe(TERMINOLOGY_DEFAULTS.operator);
+  });
+
+  it("profile terminology overrides universal defaults", () => {
+    const config = defaultForgeConfig("test");
+    const profile = makeProfile({ artifact: "widget" });
+    const result = resolveAllTerminology(config, profile);
+    expect(result.artifact).toBe("widget");
+    expect(result.operator).toBe(TERMINOLOGY_DEFAULTS.operator);
+  });
+
+  it("project terminology overrides profile terminology", () => {
+    const config = defaultForgeConfig("test");
+    if (config.bindings) {
+      config.bindings.terminology = { artifact: "project-widget" };
+    }
+    const profile = makeProfile({ artifact: "profile-widget" });
+    const result = resolveAllTerminology(config, profile);
+    expect(result.artifact).toBe("project-widget");
+  });
+
+  it("handles undefined profile", () => {
+    const config = defaultForgeConfig("test");
+    const result = resolveAllTerminology(config, undefined);
+    expect(result.artifact).toBe(TERMINOLOGY_DEFAULTS.artifact);
+  });
+
+  it("handles undefined config bindings", () => {
+    const config = defaultForgeConfig("test");
+    delete config.bindings;
+    const profile = makeProfile({ artifact: "widget" });
+    const result = resolveAllTerminology(config, profile);
+    expect(result.artifact).toBe("widget");
+  });
+
+  it("merges all three layers correctly", () => {
+    const config = defaultForgeConfig("test");
+    if (config.bindings) {
+      config.bindings.terminology = { module: "project-module" };
+    }
+    const profile = makeProfile({ artifact: "profile-artifact", module: "profile-module" });
+    const result = resolveAllTerminology(config, profile);
+    expect(result.artifact).toBe("profile-artifact");
+    expect(result.module).toBe("project-module");
+    expect(result.operator).toBe(TERMINOLOGY_DEFAULTS.operator);
+  });
+});