@warpgogol/forge 2.8.0 → 2.8.2

package/os/core/handlers/release-publish.ts

@@ -0,0 +1,211 @@
+/*
+<MODULE_CONTRACT>
+<purpose>forge.release.publish — publish a prepared release to the declared target (local, R2, S3). Supports --dry-run, --json, --profile.</purpose>
+<non-goals>
+  <item>Do not implement release preparation — that lives in release-prepare.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-0680: initial forge.release.publish handler with local/r2/s3 targets, --dry-run, env var validation.</item>
+  <item>RFC-0680 review fix: remove unused readdir import (A-1).</item>
+  <item>RFC-0680 review fix: add S3_ENDPOINT to required env vars (G-1).</item>
+  <item>RFC-0680 review fix: add 30s request timeout on S3Client (G-2).</item>
+</CHANGE_SUMMARY>
+*/
+
+import { readFile, copyFile, mkdir } from "node:fs/promises";
+import { join, basename } from "node:path";
+import type {
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../../src/types.ts";
+import { resolveActiveProfile, resolveLifecycleFlags } from "./profile-resolve.ts";
+import type { ReleaseManifest } from "./release-prepare.ts";
+
+export interface ForgeReleasePublishResult {
+  command: "forge.release.publish";
+  profileId: string;
+  target: string;
+  publishedFiles: Array<{ path: string; targetPath: string }>;
+  manifestPath: string;
+}
+
+function getRequiredEnvVars(target: string): string[] {
+  if (target === "r2") {
+    return ["R2_AXIOM_ACCOUNT_ID", "R2_AXIOM_ACCESS_KEY_ID", "R2_AXIOM_SECRET_ACCESS_KEY"];
+  }
+  if (target === "s3") {
+    return ["S3_BUCKET", "S3_ACCESS_KEY_ID", "S3_SECRET_ACCESS_KEY", "S3_ENDPOINT"];
+  }
+  return [];
+}
+
+export async function runReleasePublish(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<ForgeReleasePublishResult>> {
+  const { workspaceRoot, logger } = context;
+  const { dryRun, profileIdOverride } = resolveLifecycleFlags(input, context);
+
+  const resolved = resolveActiveProfile(workspaceRoot, context.forgeRoot, profileIdOverride);
+  if (!resolved) {
+    return {
+      data: {
+        command: "forge.release.publish",
+        profileId: "",
+        target: "",
+        publishedFiles: [],
+        manifestPath: "",
+      },
+      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.release) {
+    return {
+      data: {
+        command: "forge.release.publish",
+        profileId: profile.id,
+        target: "",
+        publishedFiles: [],
+        manifestPath: "",
+      },
+      exitCode: 1,
+      summary: `Profile ${profile.id} does not declare a release configuration.`,
+    };
+  }
+
+  const releaseConfig = profile.release;
+  const releaseDir = join(workspaceRoot, releaseConfig.outputDir);
+  const manifestPath = join(releaseDir, releaseConfig.manifestName);
+
+  let manifest: ReleaseManifest;
+  try {
+    const raw = await readFile(manifestPath, "utf8");
+    manifest = JSON.parse(raw) as ReleaseManifest;
+  } catch {
+    return {
+      data: {
+        command: "forge.release.publish",
+        profileId: profile.id,
+        target: releaseConfig.target,
+        publishedFiles: [],
+        manifestPath,
+      },
+      exitCode: 1,
+      summary: `No release manifest found at ${manifestPath}. Run \`forge release prepare\` first.`,
+    };
+  }
+
+  const target = releaseConfig.target;
+  const requiredVars = getRequiredEnvVars(target);
+  const missingVars = requiredVars.filter((v) => !process.env[v]);
+
+  if (missingVars.length > 0) {
+    return {
+      data: {
+        command: "forge.release.publish",
+        profileId: profile.id,
+        target,
+        publishedFiles: [],
+        manifestPath,
+      },
+      exitCode: 1,
+      summary: `Missing required environment variables: ${missingVars.join(", ")}`,
+    };
+  }
+
+  const filesToPublish: string[] = [];
+  for (const a of manifest.artifacts) {
+    filesToPublish.push(join(releaseDir, basename(a.path)));
+  }
+  filesToPublish.push(manifestPath);
+
+  if (dryRun) {
+    logger.info(`[dry-run] forge.release.publish — profile: ${profile.id}`);
+    logger.info(`  target: ${target}`);
+    for (const f of filesToPublish) {
+      logger.info(`  file: ${f}`);
+    }
+    return {
+      data: {
+        command: "forge.release.publish",
+        profileId: profile.id,
+        target,
+        publishedFiles: filesToPublish.map((f) => ({
+          path: f,
+          targetPath:
+            target === "local"
+              ? join(releaseDir, "published", basename(f))
+              : `${target}://${basename(f)}`,
+        })),
+        manifestPath,
+      },
+      summary: `[dry-run] Would publish ${filesToPublish.length} file(s) to ${target}`,
+    };
+  }
+
+  const publishedFiles: Array<{ path: string; targetPath: string }> = [];
+
+  if (target === "local") {
+    const publishedDir = join(releaseDir, "published");
+    await mkdir(publishedDir, { recursive: true });
+    for (const f of filesToPublish) {
+      const dst = join(publishedDir, basename(f));
+      await copyFile(f, dst);
+      publishedFiles.push({ path: f, targetPath: dst });
+    }
+  } else if (target === "r2" || target === "s3") {
+    const { S3Client, PutObjectCommand } = await import("@aws-sdk/client-s3");
+    const { readFile: fsReadFile } = await import("node:fs/promises");
+
+    const endpoint =
+      target === "r2"
+        ? `https://${process.env.R2_AXIOM_ACCOUNT_ID}.r2.cloudflarestorage.com`
+        : process.env.S3_ENDPOINT;
+    const bucket = target === "r2" ? releaseConfig.r2?.bucket : process.env.S3_BUCKET;
+    const accessKeyId =
+      target === "r2" ? process.env.R2_AXIOM_ACCESS_KEY_ID : process.env.S3_ACCESS_KEY_ID;
+    const secretAccessKey =
+      target === "r2" ? process.env.R2_AXIOM_SECRET_ACCESS_KEY : process.env.S3_SECRET_ACCESS_KEY;
+    const prefix = target === "r2" ? (releaseConfig.r2?.prefix ?? "") : "";
+
+    const client = new S3Client({
+      endpoint,
+      region: "auto",
+      credentials: { accessKeyId: accessKeyId!, secretAccessKey: secretAccessKey! },
+      requestHandler: { requestTimeout: 30_000 },
+    });
+
+    for (const f of filesToPublish) {
+      const key = prefix ? `${prefix}/${basename(f)}` : basename(f);
+      const body = await fsReadFile(f);
+      await client.send(
+        new PutObjectCommand({
+          Bucket: bucket,
+          Key: key,
+          Body: body,
+        }),
+      );
+      publishedFiles.push({ path: f, targetPath: `${target}://${bucket}/${key}` });
+    }
+  }
+
+  logger.success(`  Published ${publishedFiles.length} file(s) to ${target}`);
+  return {
+    data: {
+      command: "forge.release.publish",
+      profileId: profile.id,
+      target,
+      publishedFiles,
+      manifestPath,
+    },
+    summary: `Published ${publishedFiles.length} file(s) to ${target}`,
+  };
+}

package/os/core/handlers/validate.ts

@@ -0,0 +1,262 @@
+/*
+<MODULE_CONTRACT>
+<purpose>forge.validate — execute validate commands for all artifacts declared in the active stack profile. Supports --dry-run, --json, --artifact filtering, and violation parsing.</purpose>
+<non-goals>
+  <item>Do not implement dev or build 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.validate handler with profile resolution, --dry-run, and per-artifact execution.</item>
+  <item>RFC-0677: extended with --artifact filtering, violation parsing (outputFormat: json/plain), passed/allPassed fields.</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 ValidateViolation {
+  file: string;
+  line?: number;
+  column?: number;
+  severity: "error" | "warning";
+  message: string;
+}
+
+export interface ForgeValidateArtifactResult {
+  id: string;
+  command: string;
+  exitCode: number;
+  passed: boolean;
+  violations: ValidateViolation[];
+  stdout: string;
+  stderr: string;
+}
+
+export interface ForgeValidateResult {
+  command: "forge.validate";
+  profileId: string;
+  artifacts: ForgeValidateArtifactResult[];
+  allPassed: boolean;
+}
+
+export function parseViolations(
+  output: string,
+  outputFormat: "plain" | "json" | undefined,
+  violationPattern: string | undefined,
+): ValidateViolation[] {
+  if (outputFormat === "json") {
+    try {
+      const parsed = JSON.parse(output) as unknown;
+      if (Array.isArray(parsed)) {
+        return parsed
+          .filter((v): v is Record<string, unknown> => typeof v === "object" && v !== null)
+          .map((v) => ({
+            file: String(v["file"] ?? ""),
+            line: typeof v["line"] === "number" ? v["line"] : undefined,
+            column: typeof v["column"] === "number" ? v["column"] : undefined,
+            severity: (v["severity"] === "warning" ? "warning" : "error") as "error" | "warning",
+            message: String(v["message"] ?? ""),
+          }))
+          .filter((v) => v.file || v.message);
+      }
+      return [];
+    } catch {
+      return [];
+    }
+  }
+
+  if (outputFormat === "plain" && violationPattern) {
+    try {
+      const regex = new RegExp(violationPattern, "gm");
+      const violations: ValidateViolation[] = [];
+      let match: RegExpExecArray | null;
+      const MAX_MATCHES = 1000;
+      let matchCount = 0;
+      while ((match = regex.exec(output)) !== null && matchCount < MAX_MATCHES) {
+        matchCount++;
+        const groups = match.groups ?? {};
+        violations.push({
+          file: String(groups["file"] ?? ""),
+          line: groups["line"] ? Number(groups["line"]) : undefined,
+          column: groups["column"] ? Number(groups["column"]) : undefined,
+          severity: (groups["severity"] === "warning" ? "warning" : "error") as "error" | "warning",
+          message: String(groups["message"] ?? match[0]),
+        });
+        if (regex.lastIndex === match.index) regex.lastIndex++;
+      }
+      return violations;
+    } catch {
+      return [];
+    }
+  }
+
+  return [];
+}
+
+export async function runValidate(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<ForgeValidateResult>> {
+  const { workspaceRoot, logger } = context;
+  const { dryRun, profileIdOverride } = resolveLifecycleFlags(input, context);
+  const artifactFilter =
+    typeof input.flags["artifact"] === "string" ? (input.flags["artifact"] as string) : undefined;
+
+  const resolved = resolveActiveProfile(workspaceRoot, context.forgeRoot, profileIdOverride);
+  if (!resolved) {
+    return {
+      data: {
+        command: "forge.validate",
+        profileId: "",
+        artifacts: [],
+        allPassed: 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.artifacts || profile.artifacts.length === 0) {
+    return {
+      data: {
+        command: "forge.validate",
+        profileId: profile.id,
+        artifacts: [],
+        allPassed: false,
+      },
+      exitCode: 1,
+      summary: `Profile ${profile.id} does not declare any artifacts.`,
+      nextSteps: [{ action: `Add artifacts section to profile ${profile.id}`, kind: "required" }],
+    };
+  }
+
+  if (artifactFilter) {
+    const found = profile.artifacts.find((a) => a.id === artifactFilter);
+    if (!found) {
+      return {
+        data: {
+          command: "forge.validate",
+          profileId: profile.id,
+          artifacts: [],
+          allPassed: false,
+        },
+        exitCode: 1,
+        summary: `Artifact ${artifactFilter} not declared in profile ${profile.id}.`,
+        nextSteps: [{ action: `Check artifacts in profile ${profile.id}`, kind: "required" }],
+      };
+    }
+  }
+
+  const artifactsToValidate = artifactFilter
+    ? profile.artifacts.filter((a) => a.id === artifactFilter)
+    : profile.artifacts;
+
+  if (dryRun) {
+    const commands = artifactsToValidate
+      .filter((a) => a.validate)
+      .map((a) => ({ artifactId: a.id, command: a.validate!.command }));
+    logger.info(`[dry-run] forge.validate — profile: ${profile.id}`);
+    for (const cmd of commands) {
+      logger.info(`  ${cmd.artifactId}: ${cmd.command}`);
+    }
+    return {
+      data: {
+        command: "forge.validate",
+        profileId: profile.id,
+        artifacts: commands.map((c) => ({
+          id: c.artifactId,
+          command: c.command,
+          exitCode: 0,
+          passed: true,
+          violations: [],
+          stdout: "",
+          stderr: "",
+        })),
+        allPassed: true,
+      },
+      summary: `[dry-run] ${commands.length} validate command(s) resolved`,
+    };
+  }
+
+  const results: ForgeValidateArtifactResult[] = [];
+
+  for (const artifact of artifactsToValidate) {
+    if (!artifact.validate) {
+      logger.warn(`Skipping artifact ${artifact.id}: no validate command declared`);
+      results.push({
+        id: artifact.id,
+        command: "",
+        exitCode: 0,
+        passed: true,
+        violations: [],
+        stdout: "",
+        stderr: "skipped: no validate command",
+      });
+      continue;
+    }
+
+    const cmd = artifact.validate.command;
+    const outputFormat = artifact.validate.outputFormat;
+    const violationPattern = artifact.validate.violationPattern;
+    try {
+      const { stdout, stderr } = await execAsync(cmd, { cwd: workspaceRoot, timeout: 30_000 });
+      const violations = parseViolations(stdout + "\n" + stderr, outputFormat, violationPattern);
+      results.push({
+        id: artifact.id,
+        command: cmd,
+        exitCode: 0,
+        passed: true,
+        violations,
+        stdout,
+        stderr,
+      });
+      logger.success(`  ${artifact.id}: OK`);
+    } catch (err) {
+      const e = err as { code?: number; stdout?: string; stderr?: string; message: string };
+      const rawStdout = e.stdout ?? "";
+      const rawStderr = e.stderr ?? e.message;
+      const violations = parseViolations(
+        rawStdout + "\n" + rawStderr,
+        outputFormat,
+        violationPattern,
+      );
+      results.push({
+        id: artifact.id,
+        command: cmd,
+        exitCode: e.code ?? 1,
+        passed: false,
+        violations,
+        stdout: rawStdout,
+        stderr: rawStderr,
+      });
+      logger.error(`  ${artifact.id}: FAILED (exit ${e.code ?? 1})`);
+    }
+  }
+
+  const allPassed = results.every((r) => r.passed);
+
+  return {
+    data: {
+      command: "forge.validate",
+      profileId: profile.id,
+      artifacts: results,
+      allPassed,
+    },
+    exitCode: allPassed ? 0 : 1,
+    summary: allPassed
+      ? `forge.validate: all ${results.length} artifact(s) passed`
+      : `forge.validate: ${results.filter((r) => !r.passed).length} artifact(s) failed`,
+  };
+}

package/os/core/handlers/workspace-deps.ts

@@ -0,0 +1,55 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Lazy dynamic-import bridge for @warpgogol/werkstatt/fingerprint and @warpgogol/werkstatt-shared/share/fs. These workspace packages are not published to npm — when forge is installed standalone from npm, they are unavailable and handlers that depend on them must degrade gracefully.</purpose>
+<non-goals>
+  <item>Do not re-export types from @warpgogol/* — only runtime functions.</item>
+  <item>Do not use static imports — that would break npm installs without workspace deps.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0682: extract dynamic-import helper so forge publishes without workspace:* deps.</item>
+</CHANGE_SUMMARY>
+*/
+
+export type CollectFilesFn = (
+  root: string,
+  options?: {
+    extensions?: string[];
+    ignore?: (name: string) => boolean;
+  },
+) => Promise<string[]>;
+
+export type ByteHashFileFn = (filePath: string) => Promise<string>;
+
+interface WorkspaceDeps {
+  collectFiles: CollectFilesFn;
+  byteHashFile: ByteHashFileFn;
+}
+
+let cached: WorkspaceDeps | null = null;
+let loadError: string | null = null;
+
+export async function loadWorkspaceDeps(): Promise<WorkspaceDeps> {
+  if (cached) return cached;
+  if (loadError) throw new Error(loadError);
+
+  try {
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore — workspace dep, may not be installed when forge is used standalone from npm
+    const shareMod = await import("@warpgogol/werkstatt-shared/share/fs");
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore — workspace dep, may not be installed when forge is used standalone from npm
+    const fpMod = await import("@warpgogol/werkstatt/fingerprint");
+    cached = {
+      collectFiles: shareMod.collectFiles as CollectFilesFn,
+      byteHashFile: fpMod.byteHashFile as ByteHashFileFn,
+    };
+    return cached;
+  } catch (err) {
+    loadError =
+      `@warpgogol/werkstatt/fingerprint and @warpgogol/werkstatt-shared/share are required for this command but not installed. ` +
+      `When using forge standalone from npm, install them separately or use forge within the warpgogol workspace. ` +
+      `Error: ${(err as Error).message}`;
+    throw new Error(loadError);
+  }
+}

package/os/core/index.ts

@@ -0,0 +1,13 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Expose the forge core kernel module through a stable package subpath.</purpose>
+<non-goals>
+  <item>Do not implement handler logic.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0374: initial core module barrel.</item>
+</CHANGE_SUMMARY>
+*/
+
+export { forgeCoreModule } from "./core.module.ts";

package/os/exploration/exploration.module.ts

@@ -0,0 +1,90 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Register exploration note commands with the forge kernel registry.</purpose>
+<non-goals>
+  <item>Do not implement handler logic here — delegate to handlers/.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0710: initial forgeExplorationModule registering exploration.list, exploration.show, exploration.archive commands.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { ForgeModule } from "../../src/forge-module.ts";
+
+export const forgeExplorationModule: ForgeModule = {
+  name: "forge-exploration",
+  version: "0.1.0",
+  async register(registry) {
+    const { runExplorationList } = await import("./handlers/list.ts");
+    const { runExplorationShow } = await import("./handlers/show.ts");
+    const { runExplorationArchive } = await import("./handlers/archive.ts");
+
+    registry.registerCommand({
+      name: "exploration.list",
+      description:
+        "List all exploration notes in docs/explorations/. Returns id, title, status, and createdAt for each note. " +
+        "Use --status <status> to filter by status (open, explored, archived). " +
+        "Returns an empty list with exit code 0 if the directory is empty or missing.",
+      scope: "workspace",
+      mutatesState: false,
+      writes: [],
+      reads: ["docs/explorations/*.md"],
+      cacheable: false,
+      flags: {
+        status: {
+          kind: "string",
+          description: "Filter by status (open, explored, archived).",
+        },
+      },
+      execute: runExplorationList,
+    });
+
+    registry.registerCommand({
+      name: "exploration.show",
+      description:
+        "Show the full content of a single exploration note. Use --id <slug> to specify the note slug " +
+        "(kebab-case, lowercase, latin-only). Returns the note's frontmatter and body. " +
+        "Returns exit code 1 if the note is not found.",
+      scope: "workspace",
+      mutatesState: false,
+      writes: [],
+      reads: ["docs/explorations/*.md"],
+      cacheable: false,
+      flags: {
+        id: {
+          kind: "string",
+          required: true,
+          description: "The slug of the exploration note to show (e.g. 'my-idea').",
+        },
+      },
+      execute: runExplorationShow,
+    });
+
+    registry.registerCommand({
+      name: "exploration.archive",
+      description:
+        "Archive an exploration note by setting its status to 'archived'. Use --id <slug> to specify the note. " +
+        "Use --rfc <RFC-XXXX> to add an RFC id to the note's 'related' field. " +
+        "Idempotent — if the note is already archived, returns exit code 0 with no changes. " +
+        "Returns exit code 1 if the note is not found or the slug is invalid (non-kebab-case).",
+      scope: "workspace",
+      mutatesState: true,
+      writes: ["docs/explorations/*.md"],
+      reads: ["docs/explorations/*.md"],
+      cacheable: false,
+      flags: {
+        id: {
+          kind: "string",
+          required: true,
+          description: "The slug of the exploration note to archive (e.g. 'my-idea').",
+        },
+        rfc: {
+          kind: "string",
+          description: "RFC id to add to the note's 'related' field (e.g. 'RFC-0710').",
+        },
+      },
+      execute: runExplorationArchive,
+    });
+  },
+};