@warpgogol/forge 2.8.0 → 2.8.2

package/src/migration-adapters/__tests__/registry.test.ts

@@ -0,0 +1,131 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { getAdapters, detectAdapter, detectAdapters } from "../registry.ts";
+import { nodeTypescriptPnpmAdapter } from "../node-typescript-pnpm/index.ts";
+import { phaserPnpmAdapter } from "../phaser-pnpm/index.ts";
+import { mkdtemp, rm, writeFile } 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-registry-"));
+});
+
+afterEach(async () => {
+  await rm(tempDir, { recursive: true, force: true });
+});
+
+describe("getAdapters", () => {
+  it("returns built-in adapters", () => {
+    const adapters = getAdapters();
+    expect(adapters).toHaveLength(2);
+    const ids = adapters.map((a) => a.id);
+    expect(ids).toContain("node-typescript-pnpm");
+    expect(ids).toContain("phaser-pnpm");
+  });
+
+  it("returns built-in adapters even with undefined config", () => {
+    const adapters = getAdapters(undefined);
+    expect(adapters).toHaveLength(2);
+  });
+});
+
+describe("detectAdapter", () => {
+  it("detects node-typescript-pnpm when package.json + tsconfig.json + pnpm-lock.yaml exist", async () => {
+    await writeFile(join(tempDir, "package.json"), '{"name":"test"}', "utf8");
+    await writeFile(join(tempDir, "tsconfig.json"), "{}", "utf8");
+    await writeFile(join(tempDir, "pnpm-lock.yaml"), "", "utf8");
+
+    const adapter = detectAdapter(tempDir);
+    expect(adapter?.id).toBe("node-typescript-pnpm");
+  });
+
+  it("detects phaser-pnpm when phaser is in dependencies", async () => {
+    await writeFile(
+      join(tempDir, "package.json"),
+      '{"name":"game","dependencies":{"phaser":"^3.0.0"}}',
+      "utf8",
+    );
+    await writeFile(join(tempDir, "pnpm-lock.yaml"), "", "utf8");
+
+    const adapter = detectAdapter(tempDir);
+    expect(adapter?.id).toBe("phaser-pnpm");
+  });
+
+  it("returns null when no adapter matches", () => {
+    const adapter = detectAdapter(tempDir);
+    expect(adapter).toBeNull();
+  });
+
+  it("returns first matching adapter when multiple match", async () => {
+    await writeFile(
+      join(tempDir, "package.json"),
+      '{"name":"game","dependencies":{"phaser":"^3.0.0"}}',
+      "utf8",
+    );
+    await writeFile(join(tempDir, "tsconfig.json"), "{}", "utf8");
+    await writeFile(join(tempDir, "pnpm-lock.yaml"), "", "utf8");
+
+    const adapter = detectAdapter(tempDir);
+    expect(adapter).toBeDefined();
+  });
+});
+
+describe("detectAdapters", () => {
+  it("returns all matching adapters", async () => {
+    await writeFile(
+      join(tempDir, "package.json"),
+      '{"name":"game","dependencies":{"phaser":"^3.0.0"}}',
+      "utf8",
+    );
+    await writeFile(join(tempDir, "tsconfig.json"), "{}", "utf8");
+    await writeFile(join(tempDir, "pnpm-lock.yaml"), "", "utf8");
+
+    const adapters = detectAdapters(tempDir);
+    expect(adapters.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it("returns empty array when nothing matches", () => {
+    expect(detectAdapters(tempDir)).toEqual([]);
+  });
+});
+
+describe("built-in adapter analyze", () => {
+  it("nodeTypescriptPnpmAdapter.analyze derives bindings from scripts", async () => {
+    await writeFile(
+      join(tempDir, "package.json"),
+      JSON.stringify({
+        name: "@scope/my-app",
+        scripts: {
+          build: "tsc",
+          test: "vitest",
+          typecheck: "tsc --noEmit",
+        },
+      }),
+      "utf8",
+    );
+
+    const analysis = nodeTypescriptPnpmAdapter.analyze(tempDir);
+    expect(analysis.packageManager).toBe("pnpm");
+    expect(analysis.appName).toBe("my-app");
+    expect(analysis.bindings.test).toBe("vitest");
+    expect(analysis.bindings.scopedBuild).toBe("tsc");
+    expect(analysis.placement).toBe("apps");
+  });
+
+  it("phaserPnpmAdapter.analyze detects phaser stack", async () => {
+    await writeFile(
+      join(tempDir, "package.json"),
+      JSON.stringify({
+        name: "my-game",
+        dependencies: { phaser: "^3.0.0" },
+      }),
+      "utf8",
+    );
+
+    const analysis = phaserPnpmAdapter.analyze(tempDir);
+    expect(analysis.stack).toContain("phaser");
+    expect(analysis.appName).toBe("my-game");
+  });
+});

package/src/migration-adapters/__tests__/types.test.ts

@@ -0,0 +1,86 @@
+import { describe, it, expect } from "vitest";
+import {
+  FORGE_PROTECTED_PATHS,
+  DEFAULT_EXCLUDE_PATTERNS,
+  type MigrationAdapter,
+  type AdapterAnalysis,
+  type MigrationResult,
+  type Conflict,
+} from "../types.ts";
+
+describe("FORGE_PROTECTED_PATHS", () => {
+  it("contains forge.yaml", () => {
+    expect(FORGE_PROTECTED_PATHS).toContain("forge.yaml");
+  });
+
+  it("contains .agents", () => {
+    expect(FORGE_PROTECTED_PATHS).toContain(".agents");
+  });
+
+  it("contains docs/rfcs", () => {
+    expect(FORGE_PROTECTED_PATHS).toContain("docs/rfcs");
+  });
+
+  it("contains PREFERENCES.md", () => {
+    expect(FORGE_PROTECTED_PATHS).toContain("PREFERENCES.md");
+  });
+});
+
+describe("DEFAULT_EXCLUDE_PATTERNS", () => {
+  it("excludes node_modules", () => {
+    expect(DEFAULT_EXCLUDE_PATTERNS).toContain("node_modules");
+  });
+
+  it("excludes dist", () => {
+    expect(DEFAULT_EXCLUDE_PATTERNS).toContain("dist");
+  });
+
+  it("excludes .git", () => {
+    expect(DEFAULT_EXCLUDE_PATTERNS).toContain(".git");
+  });
+
+  it("excludes .cache", () => {
+    expect(DEFAULT_EXCLUDE_PATTERNS).toContain(".cache");
+  });
+
+  it("excludes .turbo", () => {
+    expect(DEFAULT_EXCLUDE_PATTERNS).toContain(".turbo");
+  });
+});
+
+describe("type contracts", () => {
+  it("MigrationAdapter interface has required methods", () => {
+    const adapter: MigrationAdapter = {
+      id: "test",
+      detect: () => true,
+      analyze: (): AdapterAnalysis => ({
+        stack: ["typescript"],
+        packageManager: "pnpm",
+        bindings: { typecheck: null, test: null, scopedBuild: null },
+        placement: "apps",
+        appName: "test",
+        excludePatterns: [],
+        gitHistory: false,
+      }),
+      migrate: (): MigrationResult => ({
+        filesCopied: [],
+        filesSkipped: [],
+        conflicts: [],
+        workspaceUpdated: false,
+      }),
+      postSetup: () => {},
+    };
+    expect(adapter.id).toBe("test");
+    expect(adapter.detect("/")).toBe(true);
+  });
+
+  it("Conflict type has required fields", () => {
+    const conflict: Conflict = {
+      path: "src/file.ts",
+      sourceExists: true,
+      forgeExists: true,
+      resolution: "source-wins",
+    };
+    expect(conflict.resolution).toBe("source-wins");
+  });
+});

package/src/migration-adapters/git-utils.ts

@@ -0,0 +1,71 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Shared git utilities for migration adapters — git init and git history transfer via format-patch + git am (RFC-0547).</purpose>
+<non-goals>
+  <item>Do not import from @warpgogol/* — this module is portable.</item>
+  <item>Do not implement adapter-specific logic — only shared git operations.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0547: extract shared postSetup git logic from duplicated adapter implementations.</item>
+  <item>Replace fs.rmSync with trashSync for patch directory cleanup (trash bin for LLM-initiated deletions).</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { trashSync } from "../utils/fs-trash-sync.ts";
+import type { AdapterAnalysis } from "./types.ts";
+
+export function runPostSetup(
+  sourceDir: string,
+  targetDir: string,
+  analysis: AdapterAnalysis,
+): void {
+  const gitDir = path.join(targetDir, ".git");
+
+  if (analysis.gitHistory) {
+    try {
+      const patchDir = path.join(targetDir, ".forge-migration-patches");
+      fs.mkdirSync(patchDir, { recursive: true });
+      execFileSync("git", ["-C", sourceDir, "format-patch", "--all", "-o", patchDir], {
+        stdio: "pipe",
+      });
+      execFileSync("git", ["init"], { cwd: targetDir, stdio: "pipe" });
+      execFileSync("git", ["config", "user.email", "forge@warpgogol.dev"], {
+        cwd: targetDir,
+        stdio: "pipe",
+      });
+      execFileSync("git", ["config", "user.name", "Forge Migration"], {
+        cwd: targetDir,
+        stdio: "pipe",
+      });
+      const patches = fs
+        .readdirSync(patchDir)
+        .filter((f) => f.endsWith(".patch"))
+        .sort();
+      if (patches.length > 0) {
+        for (const patch of patches) {
+          execFileSync("git", ["am", path.join(patchDir, patch)], {
+            cwd: targetDir,
+            stdio: "pipe",
+          });
+        }
+      }
+      trashSync(patchDir);
+      return;
+    } catch (err) {
+      console.warn(
+        `forge: git history transfer failed, falling back to clean git init: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      if (!fs.existsSync(gitDir)) {
+        execFileSync("git", ["init"], { cwd: targetDir, stdio: "pipe" });
+      }
+    }
+  } else {
+    if (!fs.existsSync(gitDir)) {
+      execFileSync("git", ["init"], { cwd: targetDir, stdio: "pipe" });
+    }
+  }
+}

package/src/migration-adapters/ignored-files.ts

@@ -0,0 +1,221 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Discover and categorize git-ignored/untracked files in a source project for interactive transfer selection during onboarding.</purpose>
+<non-goals>
+  <item>Do not import from @warpgogol/* — this module is portable.</item>
+  <item>Do not copy files — discovery and categorization only.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Initial: discoverIgnoredFiles function that scans source for git-ignored files, categorizes them by type (config, data, runtime-state, cache, other), and returns sized categories for operator selection.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+
+export type IgnoredFileCategoryId = "config" | "data" | "runtime-state" | "cache" | "other";
+
+export interface IgnoredFileCategory {
+  id: IgnoredFileCategoryId;
+  label: string;
+  description: string;
+  paths: string[];
+  totalSizeBytes: number;
+  fileCount: number;
+}
+
+interface CategoryDef {
+  id: IgnoredFileCategoryId;
+  label: string;
+  description: string;
+  matchers: ((relPath: string) => boolean)[];
+}
+
+const CONFIG_MATCHERS: ((p: string) => boolean)[] = [
+  (p) => p === ".env" || p.startsWith(".env."),
+  (p) => p.endsWith(".key") || p.endsWith(".pem") || p.endsWith(".crt"),
+  (p) => p === ".secret" || p.startsWith("secret"),
+  (p) => p.startsWith("secrets/"),
+  (p) => p.includes("/.env") || p.includes("/.env."),
+  (p) => p === ".envrc" || p.startsWith(".envrc."),
+];
+
+const DATA_MATCHERS: ((p: string) => boolean)[] = [
+  (p) => p.startsWith(".input/") || p.includes("/.input/"),
+  (p) => p.startsWith("input/") || p.includes("/input/"),
+  (p) => p.startsWith("inputs/") || p.includes("/inputs/"),
+  (p) => p.startsWith("data/") || p.includes("/data/"),
+  (p) => p.startsWith("assets/") || p.includes("/assets/"),
+  (p) => p.startsWith("batches/") || p.includes("/batches/"),
+  (p) => p.endsWith(".db") || p.endsWith(".sqlite") || p.endsWith(".sqlite3"),
+  (p) => p.endsWith(".ndjson") && !p.startsWith("bordbuch/"),
+];
+
+const RUNTIME_STATE_MATCHERS: ((p: string) => boolean)[] = [
+  (p) => p.startsWith("storage/") || p.includes("/storage/"),
+  (p) => p.startsWith(".state/") || p.includes("/.state/"),
+  (p) => p.startsWith("state/") || p.includes("/state/"),
+  (p) => p.endsWith(".log"),
+];
+
+const CACHE_MATCHERS: ((p: string) => boolean)[] = [
+  (p) => p.startsWith(".cache/") || p.includes("/.cache/"),
+  (p) => p.startsWith("cache/") || p.includes("/cache/"),
+  (p) => p.includes(".playwright") || p.includes("browser-profile"),
+  (p) => p.endsWith(".tmp") || p.startsWith(".tmp"),
+];
+
+const CATEGORY_DEFS: CategoryDef[] = [
+  {
+    id: "config",
+    label: "Configuration & secrets",
+    description:
+      "Environment files, API keys, certificates, and local configuration needed for the project to run.",
+    matchers: CONFIG_MATCHERS,
+  },
+  {
+    id: "data",
+    label: "Data & inputs",
+    description: "Input data, datasets, databases, and batch files used by the project.",
+    matchers: DATA_MATCHERS,
+  },
+  {
+    id: "runtime-state",
+    label: "Runtime state",
+    description: "Crawlee state, logs, and other runtime artifacts from previous executions.",
+    matchers: RUNTIME_STATE_MATCHERS,
+  },
+  {
+    id: "cache",
+    label: "Caches",
+    description: "Browser profiles, temporary files, and build caches that can be regenerated.",
+    matchers: CACHE_MATCHERS,
+  },
+  {
+    id: "other",
+    label: "Other ignored files",
+    description: "Files matched by .gitignore that don't fit into any standard category.",
+    matchers: [],
+  },
+];
+
+const CATEGORY_PRIORITY: Record<IgnoredFileCategoryId, number> = {
+  config: 0,
+  data: 1,
+  "runtime-state": 2,
+  cache: 3,
+  other: 4,
+};
+
+function categorizePath(relPath: string): CategoryDef {
+  const normalized = relPath.replace(/\\/g, "/");
+  for (const def of CATEGORY_DEFS) {
+    if (def.matchers.some((m) => m(normalized))) {
+      return def;
+    }
+  }
+  return CATEGORY_DEFS[CATEGORY_DEFS.length - 1];
+}
+
+function getDirStats(dirPath: string): { size: number; count: number } {
+  let size = 0;
+  let count = 0;
+  try {
+    const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(dirPath, entry.name);
+      if (entry.isDirectory()) {
+        const sub = getDirStats(fullPath);
+        size += sub.size;
+        count += sub.count;
+      } else if (entry.isFile()) {
+        try {
+          size += fs.statSync(fullPath).size;
+          count++;
+        } catch {
+          // File may have been removed
+        }
+      }
+    }
+  } catch {
+    // Directory may have been removed
+  }
+  return { size, count };
+}
+
+function getPathSize(fullPath: string): { sizeBytes: number; fileCount: number } {
+  try {
+    const stat = fs.statSync(fullPath);
+    if (stat.isDirectory()) {
+      const { size, count } = getDirStats(fullPath);
+      return { sizeBytes: size, fileCount: count };
+    }
+    return { sizeBytes: stat.size, fileCount: 1 };
+  } catch {
+    return { sizeBytes: 0, fileCount: 0 };
+  }
+}
+
+export function discoverIgnoredFiles(sourceDir: string): IgnoredFileCategory[] {
+  const hasGit = fs.existsSync(path.join(sourceDir, ".git"));
+  let ignoredPaths: string[] = [];
+
+  if (hasGit) {
+    try {
+      const output = execFileSync("git", ["-C", sourceDir, "status", "--ignored", "--porcelain"], {
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+        timeout: 30_000,
+      });
+      ignoredPaths = output
+        .split("\n")
+        .filter((l) => l.startsWith("!! "))
+        .map((l) => l.slice(3).trim())
+        .filter((p) => p.length > 0);
+    } catch {
+      // git command failed — return empty
+      return [];
+    }
+  }
+
+  if (ignoredPaths.length === 0) {
+    return [];
+  }
+
+  const categoryMap = new Map<IgnoredFileCategoryId, IgnoredFileCategory>();
+
+  for (const relPath of ignoredPaths) {
+    const fullPath = path.join(sourceDir, relPath);
+    const def = categorizePath(relPath);
+    const { sizeBytes, fileCount } = getPathSize(fullPath);
+
+    if (!categoryMap.has(def.id)) {
+      categoryMap.set(def.id, {
+        id: def.id,
+        label: def.label,
+        description: def.description,
+        paths: [],
+        totalSizeBytes: 0,
+        fileCount: 0,
+      });
+    }
+
+    const cat = categoryMap.get(def.id)!;
+    cat.paths.push(relPath);
+    cat.totalSizeBytes += sizeBytes;
+    cat.fileCount += fileCount;
+  }
+
+  return Array.from(categoryMap.values()).sort(
+    (a, b) => CATEGORY_PRIORITY[a.id] - CATEGORY_PRIORITY[b.id],
+  );
+}
+
+export function formatSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GB`;
+}

package/src/migration-adapters/index.ts

@@ -0,0 +1,21 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Barrel export for migration-adapter module (RFC-0546).</purpose>
+<non-goals>
+  <item>Do not re-export implementation details — only public types and registry functions.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0546: initial barrel export for migration-adapters.</item>
+</CHANGE_SUMMARY>
+*/
+
+export type { MigrationAdapter, AdapterAnalysis, MigrationResult, Conflict } from "./types.ts";
+
+export { FORGE_PROTECTED_PATHS, DEFAULT_EXCLUDE_PATTERNS } from "./types.ts";
+
+export { nodeTypescriptPnpmAdapter } from "./node-typescript-pnpm/index.ts";
+export { phaserPnpmAdapter } from "./phaser-pnpm/index.ts";
+export { getAdapters, detectAdapter, detectAdapters } from "./registry.ts";
+export { discoverIgnoredFiles, formatSize } from "./ignored-files.ts";
+export type { IgnoredFileCategory, IgnoredFileCategoryId } from "./ignored-files.ts";