@warpgogol/forge 2.8.0 → 2.8.2

package/os/core/handlers/assets-check.ts

@@ -0,0 +1,122 @@
+/*
+<MODULE_CONTRACT>
+<purpose>forge.assets.check — check for missing, orphaned, and unreferenced assets. Supports --dry-run, --strict, --json, --profile.</purpose>
+<non-goals>
+  <item>Do not implement asset listing logic — that lives in assets-list.ts.</item>
+  <item>Do not import from @warpgogol/* in autonomous modules — os/core/ may import from @warpgogol/*.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0679: initial forge.assets.check handler with missing/orphaned detection, --strict, --dry-run.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type {
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../../src/types.ts";
+import { resolveActiveProfile, resolveLifecycleFlags } from "./profile-resolve.ts";
+import {
+  scanAssets,
+  extractReferences,
+  findMissingAssets,
+  findOrphanedAssets,
+} from "./assets-helpers.ts";
+
+export interface AssetCheckResult {
+  missing: Array<{ path: string; referencedBy: string[] }>;
+  orphaned: Array<{ path: string; type: string }>;
+}
+
+export interface ForgeAssetsCheckResult {
+  command: "forge.assets.check";
+  profileId: string;
+  check: AssetCheckResult;
+  allOk: boolean;
+}
+
+export async function runAssetsCheck(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<ForgeAssetsCheckResult>> {
+  const { workspaceRoot, logger } = context;
+  const { dryRun, profileIdOverride } = resolveLifecycleFlags(input, context);
+  const strict = input.flags["strict"] === true;
+
+  const resolved = resolveActiveProfile(workspaceRoot, context.forgeRoot, profileIdOverride);
+  if (!resolved) {
+    return {
+      data: {
+        command: "forge.assets.check",
+        profileId: "",
+        check: { missing: [], orphaned: [] },
+        allOk: false,
+      },
+      exitCode: 1,
+      summary: "No active profile found. Set `profile` in forge.yaml or use --profile <id>.",
+      nextSteps: [{ action: "Set profile in forge.yaml or use --profile <id>", kind: "required" }],
+    };
+  }
+
+  const { profile } = resolved;
+
+  if (!profile.assets) {
+    return {
+      data: {
+        command: "forge.assets.check",
+        profileId: profile.id,
+        check: { missing: [], orphaned: [] },
+        allOk: true,
+      },
+      exitCode: 0,
+      summary: `Profile ${profile.id} does not declare assets — nothing to check.`,
+    };
+  }
+
+  const assets = await scanAssets(workspaceRoot, profile.assets, { dryRun });
+  const compositionExtensions = profile.artifacts?.flatMap((a) => a.extensions) ?? [];
+  const refMap = await extractReferences(workspaceRoot, profile.assets, compositionExtensions);
+
+  const missing = findMissingAssets(refMap, assets);
+  const orphaned = findOrphanedAssets(assets, refMap);
+
+  const hasMissing = missing.length > 0;
+  const hasOrphaned = orphaned.length > 0;
+  const allOk = !hasMissing && (!hasOrphaned || !strict);
+
+  if (hasMissing) {
+    for (const m of missing) {
+      logger.error(`  missing: ${m.path} (referenced by ${m.referencedBy.join(", ")})`);
+    }
+  }
+  if (hasOrphaned) {
+    for (const o of orphaned) {
+      if (strict) {
+        logger.error(`  orphaned: ${o.path} (${o.type})`);
+      } else {
+        logger.warn(`  orphaned: ${o.path} (${o.type})`);
+      }
+    }
+  }
+
+  if (allOk) {
+    logger.success(`  all assets OK`);
+  }
+
+  const parts: string[] = [];
+  if (hasMissing) parts.push(`${missing.length} missing`);
+  if (hasOrphaned) parts.push(`${orphaned.length} orphaned`);
+  const summary = parts.length === 0 ? "all assets OK" : parts.join(", ");
+
+  return {
+    data: {
+      command: "forge.assets.check",
+      profileId: profile.id,
+      check: { missing, orphaned },
+      allOk,
+    },
+    exitCode: allOk ? 0 : 1,
+    summary: dryRun ? `[dry-run] ${summary}` : summary,
+  };
+}

package/os/core/handlers/assets-helpers.ts

@@ -0,0 +1,174 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Shared asset scanning and reference extraction logic for forge.assets.list and forge.assets.check (RFC-0679).</purpose>
+<non-goals>
+  <item>Do not implement command registration — that lives in core.module.ts.</item>
+  <item>Do not import from @warpgogol/* in autonomous modules — os/core/ may import from @warpgogol/*.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0679: initial shared asset helpers — scanAssets, extractReferences, classifyAssetType.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { readFile, stat } from "node:fs/promises";
+import { join, relative, extname } from "node:path";
+import { loadWorkspaceDeps } from "./workspace-deps.ts";
+import type { ProfileAsset, ProfileAssetType } from "../../../src/profiles/profile-schema.ts";
+
+export interface AssetEntry {
+  path: string;
+  type: string;
+  size: number;
+  hash: string;
+  referencedBy: string[];
+}
+
+export interface AssetReference {
+  path: string;
+  referencedBy: string;
+}
+
+export function classifyAssetType(filePath: string, types: ProfileAssetType[]): string | undefined {
+  const ext = extname(filePath).toLowerCase();
+  return types.find((t) => t.extensions.some((e) => e.toLowerCase() === ext))?.id;
+}
+
+export async function scanAssets(
+  workspaceRoot: string,
+  assetsConfig: ProfileAsset,
+  options: { dryRun?: boolean; typeFilter?: string } = {},
+): Promise<AssetEntry[]> {
+  const { collectFiles, byteHashFile } = await loadWorkspaceDeps();
+  const assetsDir = join(workspaceRoot, assetsConfig.dir);
+  const allFiles = await collectFiles(assetsDir, {
+    ignore: (name) => name.startsWith("-") || name.startsWith("old-") || name === ".DS_Store",
+  });
+
+  const filtered = allFiles
+    .map((abs) => relative(workspaceRoot, abs))
+    .filter((rel) => {
+      if (options.typeFilter) {
+        const type = classifyAssetType(rel, assetsConfig.types);
+        return type === options.typeFilter;
+      }
+      return classifyAssetType(rel, assetsConfig.types) !== undefined;
+    })
+    .sort();
+
+  const entries: AssetEntry[] = [];
+  for (const relPath of filtered) {
+    const absPath = join(workspaceRoot, relPath);
+    let size = 0;
+    let hash = "";
+
+    if (!options.dryRun) {
+      const stats = await stat(absPath);
+      size = stats.size;
+      hash = await byteHashFile(absPath);
+    }
+
+    entries.push({
+      path: relPath,
+      type: classifyAssetType(relPath, assetsConfig.types)!,
+      size,
+      hash,
+      referencedBy: [],
+    });
+  }
+
+  return entries;
+}
+
+export async function extractReferences(
+  workspaceRoot: string,
+  assetsConfig: ProfileAsset,
+  compositionExtensions: string[],
+): Promise<Map<string, string[]>> {
+  const refMap = new Map<string, string[]>();
+
+  const { collectFiles } = await loadWorkspaceDeps();
+  const allFiles = await collectFiles(workspaceRoot, {
+    extensions: compositionExtensions,
+    ignore: (name) =>
+      name.startsWith("-") ||
+      name.startsWith("old-") ||
+      name === "node_modules" ||
+      name === "dist" ||
+      name === ".turbo" ||
+      name === ".cache" ||
+      name === ".git",
+  });
+
+  for (const absPath of allFiles) {
+    const relPath = relative(workspaceRoot, absPath);
+    try {
+      const content = await readFile(absPath, "utf8");
+
+      for (const assetType of assetsConfig.types) {
+        if (!assetType.referencePattern) continue;
+
+        try {
+          const regex = new RegExp(assetType.referencePattern, "g");
+          let match: RegExpExecArray | null;
+          const MAX_MATCHES = 1000;
+          let matchCount = 0;
+
+          while ((match = regex.exec(content)) !== null && matchCount < MAX_MATCHES) {
+            matchCount++;
+            const refPath = match[1] ?? match[0];
+            const normalized = refPath.startsWith("/") ? refPath.slice(1) : refPath;
+
+            const existing = refMap.get(normalized) ?? [];
+            if (!existing.includes(relPath)) {
+              existing.push(relPath);
+            }
+            refMap.set(normalized, existing);
+
+            if (regex.lastIndex === match.index) regex.lastIndex++;
+          }
+        } catch {
+          // Invalid regex — skip this type
+        }
+      }
+    } catch {
+      // Cannot read file — skip
+    }
+  }
+
+  return refMap;
+}
+
+export function mergeReferences(assets: AssetEntry[], refMap: Map<string, string[]>): AssetEntry[] {
+  return assets.map((asset) => {
+    const refs = refMap.get(asset.path) ?? [];
+    return { ...asset, referencedBy: refs };
+  });
+}
+
+export function findMissingAssets(
+  refMap: Map<string, string[]>,
+  assets: AssetEntry[],
+): Array<{ path: string; referencedBy: string[] }> {
+  const assetPaths = new Set(assets.map((a) => a.path));
+  const missing: Array<{ path: string; referencedBy: string[] }> = [];
+
+  for (const [refPath, referencedBy] of refMap) {
+    if (!assetPaths.has(refPath)) {
+      missing.push({ path: refPath, referencedBy });
+    }
+  }
+
+  return missing.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+export function findOrphanedAssets(
+  assets: AssetEntry[],
+  refMap: Map<string, string[]>,
+): Array<{ path: string; type: string }> {
+  const referencedAssetPaths = new Set(refMap.keys());
+  return assets
+    .filter((a) => !referencedAssetPaths.has(a.path))
+    .map((a) => ({ path: a.path, type: a.type }))
+    .sort((a, b) => a.path.localeCompare(b.path));
+}

package/os/core/handlers/assets-list.ts

@@ -0,0 +1,99 @@
+/*
+<MODULE_CONTRACT>
+<purpose>forge.assets.list — list all assets declared in the active stack profile, grouped by type. Supports --dry-run, --type, --json, --profile.</purpose>
+<non-goals>
+  <item>Do not implement asset checking logic — that lives in assets-check.ts.</item>
+  <item>Do not import from @warpgogol/* in autonomous modules — os/core/ may import from @warpgogol/*.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0679: initial forge.assets.list handler with profile resolution, --dry-run, --type filtering.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type {
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../../src/types.ts";
+import { resolveActiveProfile, resolveLifecycleFlags } from "./profile-resolve.ts";
+import {
+  scanAssets,
+  extractReferences,
+  mergeReferences,
+  type AssetEntry,
+} from "./assets-helpers.ts";
+
+export interface ForgeAssetsListResult {
+  command: "forge.assets.list";
+  profileId: string;
+  assets: AssetEntry[];
+}
+
+export async function runAssetsList(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<ForgeAssetsListResult>> {
+  const { workspaceRoot, logger } = context;
+  const { dryRun, profileIdOverride } = resolveLifecycleFlags(input, context);
+  const typeFilter =
+    typeof input.flags["type"] === "string" ? (input.flags["type"] as string) : undefined;
+
+  const resolved = resolveActiveProfile(workspaceRoot, context.forgeRoot, profileIdOverride);
+  if (!resolved) {
+    return {
+      data: {
+        command: "forge.assets.list",
+        profileId: "",
+        assets: [],
+      },
+      exitCode: 1,
+      summary: "No active profile found. Set `profile` in forge.yaml or use --profile <id>.",
+      nextSteps: [{ action: "Set profile in forge.yaml or use --profile <id>", kind: "required" }],
+    };
+  }
+
+  const { profile } = resolved;
+
+  if (!profile.assets) {
+    return {
+      data: {
+        command: "forge.assets.list",
+        profileId: profile.id,
+        assets: [],
+      },
+      exitCode: 0,
+      summary: `Profile ${profile.id} does not declare assets — nothing to list.`,
+    };
+  }
+
+  const assets = await scanAssets(workspaceRoot, profile.assets, {
+    dryRun,
+    typeFilter,
+  });
+
+  const compositionExtensions = profile.artifacts?.flatMap((a) => a.extensions) ?? [];
+  const refMap = await extractReferences(workspaceRoot, profile.assets, compositionExtensions);
+  const assetsWithRefs = mergeReferences(assets, refMap);
+
+  if (dryRun) {
+    logger.info(`[dry-run] forge.assets.list — profile: ${profile.id}`);
+    for (const asset of assetsWithRefs) {
+      logger.info(`  ${asset.type}: ${asset.path}`);
+    }
+  } else {
+    logger.info(`forge.assets.list — profile: ${profile.id}`);
+    for (const asset of assetsWithRefs) {
+      logger.info(`  ${asset.type}: ${asset.path} (${asset.size} bytes, ${asset.hash})`);
+    }
+  }
+
+  return {
+    data: {
+      command: "forge.assets.list",
+      profileId: profile.id,
+      assets: assetsWithRefs,
+    },
+    summary: `${assetsWithRefs.length} asset(s) found${typeFilter ? ` (type: ${typeFilter})` : ""}${dryRun ? " [dry-run]" : ""}`,
+  };
+}

package/os/core/handlers/build.ts

@@ -0,0 +1,155 @@
+/*
+<MODULE_CONTRACT>
+<purpose>forge.build — execute produce commands for all artifacts declared in the active stack profile. Supports --dry-run and --json.</purpose>
+<non-goals>
+  <item>Do not implement dev or validate logic — those are separate handlers.</item>
+  <item>Do not import from @warpgogol/* — this module is portable.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0674: initial forge.build handler with profile resolution, --dry-run, and per-artifact execution.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import type {
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../../src/types.ts";
+import { resolveActiveProfile, resolveLifecycleFlags } from "./profile-resolve.ts";
+
+const execAsync = promisify(exec);
+
+export interface ForgeBuildArtifactResult {
+  id: string;
+  command: string;
+  output?: string;
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+export interface ForgeBuildResult {
+  command: "forge.build";
+  profileId: string;
+  artifacts: ForgeBuildArtifactResult[];
+}
+
+export async function runBuild(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<ForgeBuildResult>> {
+  const { workspaceRoot, logger } = context;
+  const { dryRun, profileIdOverride } = resolveLifecycleFlags(input, context);
+
+  const resolved = resolveActiveProfile(workspaceRoot, context.forgeRoot, profileIdOverride);
+  if (!resolved) {
+    return {
+      data: {
+        command: "forge.build",
+        profileId: "",
+        artifacts: [],
+      },
+      exitCode: 1,
+      summary: "No active profile found. Set `profile` in forge.yaml or use --profile <id>.",
+      nextSteps: [{ action: "Set profile in forge.yaml or use --profile <id>", kind: "required" }],
+    };
+  }
+
+  const { profile } = resolved;
+
+  if (!profile.artifacts || profile.artifacts.length === 0) {
+    return {
+      data: {
+        command: "forge.build",
+        profileId: profile.id,
+        artifacts: [],
+      },
+      exitCode: 1,
+      summary: `Profile ${profile.id} does not declare any artifacts.`,
+      nextSteps: [{ action: `Add artifacts section to profile ${profile.id}`, kind: "required" }],
+    };
+  }
+
+  if (dryRun) {
+    const commands = profile.artifacts
+      .filter((a) => a.produce)
+      .map((a) => ({ artifactId: a.id, command: a.produce!.command, output: a.produce!.output }));
+    logger.info(`[dry-run] forge.build — profile: ${profile.id}`);
+    for (const cmd of commands) {
+      logger.info(`  ${cmd.artifactId}: ${cmd.command}`);
+    }
+    return {
+      data: {
+        command: "forge.build",
+        profileId: profile.id,
+        artifacts: commands.map((c) => ({
+          id: c.artifactId,
+          command: c.command,
+          output: c.output,
+          exitCode: 0,
+          stdout: "",
+          stderr: "",
+        })),
+      },
+      summary: `[dry-run] ${commands.length} produce command(s) resolved`,
+    };
+  }
+
+  const results: ForgeBuildArtifactResult[] = [];
+  let hasFailure = false;
+
+  for (const artifact of profile.artifacts) {
+    if (!artifact.produce) {
+      logger.warn(`Skipping artifact ${artifact.id}: no produce command declared`);
+      results.push({
+        id: artifact.id,
+        command: "",
+        exitCode: 0,
+        stdout: "",
+        stderr: "skipped: no produce command",
+      });
+      continue;
+    }
+
+    const cmd = artifact.produce.command;
+    try {
+      const { stdout, stderr } = await execAsync(cmd, { cwd: workspaceRoot });
+      results.push({
+        id: artifact.id,
+        command: cmd,
+        output: artifact.produce.output,
+        exitCode: 0,
+        stdout,
+        stderr,
+      });
+      logger.success(`  ${artifact.id}: OK`);
+    } catch (err) {
+      const e = err as { code?: number; stdout?: string; stderr?: string; message: string };
+      results.push({
+        id: artifact.id,
+        command: cmd,
+        output: artifact.produce.output,
+        exitCode: e.code ?? 1,
+        stdout: e.stdout ?? "",
+        stderr: e.stderr ?? e.message,
+      });
+      hasFailure = true;
+      logger.error(`  ${artifact.id}: FAILED (exit ${e.code ?? 1})`);
+    }
+  }
+
+  return {
+    data: {
+      command: "forge.build",
+      profileId: profile.id,
+      artifacts: results,
+    },
+    exitCode: hasFailure ? 1 : 0,
+    summary: hasFailure
+      ? `forge.build: ${results.filter((r) => r.exitCode !== 0).length} artifact(s) failed`
+      : `forge.build: all ${results.length} artifact(s) succeeded`,
+  };
+}