forgeos 0.1.0-alpha.0

package/src/forge/compiler/diagnostics/create.ts

@@ -0,0 +1,245 @@
+import type { Diagnostic, DiagnosticSeverity } from "../types/diagnostic.ts";
+import type { DiagnosticCode } from "./codes.ts";
+
+export interface DiagnosticInput {
+  severity: DiagnosticSeverity;
+  code: DiagnosticCode | string;
+  message: string;
+  file?: string;
+  span?: { start: number; end: number };
+  fixHint?: string;
+  suggestedCommands?: string[];
+  docs?: string[];
+}
+
+interface DiagnosticGuidance {
+  fixHint: string;
+  suggestedCommands?: string[];
+  docs?: string[];
+}
+
+function defaultGuidanceForCode(code: string): DiagnosticGuidance | null {
+  if (code === "FORGE_DRIFT") {
+    return {
+      fixHint: "Regenerate Forge artifacts and re-run the drift check.",
+      suggestedCommands: ["forge generate", "forge generate --check"],
+      docs: ["AGENTS.md"],
+    };
+  }
+  if (code === "FORGE_IMPACT_GENERATED_DRIFT") {
+    return {
+      fixHint: "Generated artifacts are stale. Run forge generate, then re-run the impact or verify command.",
+      suggestedCommands: ["forge generate", "forge generate --check", "forge verify --changed --json"],
+      docs: ["AGENTS.md", "src/forge/_generated/agentContract.json"],
+    };
+  }
+  if (code === "FORGE_GENERATE_LOCKED") {
+    return {
+      fixHint: "Wait for the active forge generate command to finish. If no Forge process is running, delete .forge/locks/generate.lock and retry.",
+      suggestedCommands: ["forge generate", "forge generate --check", "forge dev --once --json"],
+      docs: ["AGENTS.md"],
+    };
+  }
+  if (code === "FORGE_GUARD_VIOLATION" || code === "FORGE_RUNTIME_GUARD_BLOCKED") {
+    return {
+      fixHint: "Move forbidden side effects into an action/workflow, or replace the package with an allowed adapter for this runtime.",
+      suggestedCommands: ["forge repair diagnose --diagnostic FORGE_GUARD_VIOLATION --json", "forge refactor extract-action <command> --package <package> --dry-run --json"],
+      docs: ["src/forge/_generated/runtimeRules.md", "AGENTS.md"],
+    };
+  }
+  if (code === "FORGE_SECRET_DIRECT_PROCESS_ENV") {
+    return {
+      fixHint: "Use ctx.secrets or ctx.config instead of reading process.env directly from app runtime code.",
+      suggestedCommands: ["forge repair diagnose --diagnostic FORGE_SECRET_DIRECT_PROCESS_ENV --json", "forge refactor replace-process-env <ENV_NAME> --dry-run --json"],
+      docs: ["src/forge/_generated/runtimeRules.md"],
+    };
+  }
+  if (code === "FORGE_AI_FORBIDDEN_CONTEXT") {
+    return {
+      fixHint: "Move AI calls to an action, workflow, endpoint, or server context.",
+      suggestedCommands: ["forge repair diagnose --diagnostic FORGE_AI_FORBIDDEN_CONTEXT --json", "forge inspect ai --json"],
+      docs: ["src/forge/_generated/runtimeRules.md"],
+    };
+  }
+  if (code === "FORGE_QUERY_FORBIDDEN_WRITE" || code === "FORGE_QUERY_FORBIDDEN_SIDE_EFFECT") {
+    return {
+      fixHint: "Keep queries and liveQueries read-only; move writes and side effects to commands/actions.",
+      suggestedCommands: ["forge inspect queries --json", "forge repair diagnose --diagnostic " + code + " --json"],
+      docs: ["src/forge/_generated/runtimeRules.md"],
+    };
+  }
+  if (code.startsWith("FORGE_RLS_")) {
+    return {
+      fixHint: "Inspect generated RLS SQL and validate tenant isolation before applying migrations.",
+      suggestedCommands: ["forge rls check --json", "forge rls print --json"],
+      docs: ["src/forge/_generated/agentContract.json"],
+    };
+  }
+  if (code.startsWith("FORGE_UI_")) {
+    return {
+      fixHint: "Inspect the last UI run and use the UI report as repair input.",
+      suggestedCommands: ["forge ui report last --json", "forge repair diagnose --from-last-ui-run --json"],
+      docs: ["src/forge/_generated/uiTestManifest.json"],
+    };
+  }
+  if (code === "FORGE_VERIFY_SCRIPT_TIMEOUT") {
+    return {
+      fixHint: "Run the timed-out script directly, or use impact-based verification to narrow the check before retrying the full gate.",
+      suggestedCommands: ["forge test plan --changed --json", "forge verify --changed", "forge dev --once --json"],
+      docs: ["AGENTS.md"],
+    };
+  }
+  if (code === "FORGE_TEST_RUN_TIMEOUT") {
+    return {
+      fixHint: "Run the timed-out command directly, or increase the impact test timeout only after checking why it is slow.",
+      suggestedCommands: ["forge test plan --changed --json", "forge test run --changed --timeout-ms 120000 --json"],
+      docs: ["AGENTS.md", ".forge/test-runs/last.json"],
+    };
+  }
+  if (code === "FORGE_TEST_COMMAND_RESOLUTION_FAILED") {
+    return {
+      fixHint: "Fix the local command resolution before retrying. On Windows, install Bun at ~/.bun/bin/bun.exe or set FORGE_BUN to an existing bun.exe.",
+      suggestedCommands: ["forge dev --once --json", "forge test plan --changed --json"],
+      docs: ["AGENTS.md"],
+    };
+  }
+  if (code.startsWith("FORGE_FRONTEND_")) {
+    return {
+      fixHint: "Use the generated frontend bridge and inspect src/forge/_generated/frontendGraph.json before editing UI wiring.",
+      suggestedCommands: ["forge inspect frontend --json", "forge make ui --framework vite --dry-run --json", "forge generate"],
+      docs: ["src/forge/_generated/frontendGraph.json", "AGENTS.md"],
+    };
+  }
+  if (code.startsWith("FORGE_REFACTOR_")) {
+    return {
+      fixHint: "Review the refactor plan, lower the scope if diagnostics are unsafe, and re-run in dry-run mode before applying.",
+      suggestedCommands: ["forge refactor <operation> --dry-run --json", "forge impact --changed --json"],
+      docs: ["AGENTS.md"],
+    };
+  }
+  if (code.startsWith("FORGE_REPAIR_")) {
+    return {
+      fixHint: "Open the repair plan and apply only high-confidence repairs.",
+      suggestedCommands: ["forge repair plan --json", "forge repair apply <repairId> --dry-run --json"],
+      docs: ["AGENTS.md"],
+    };
+  }
+  return null;
+}
+
+export function createDiagnostic(input: DiagnosticInput): Diagnostic {
+  const guidance = defaultGuidanceForCode(input.code);
+  return {
+    severity: input.severity,
+    code: input.code,
+    message: input.message,
+    ...(input.file !== undefined ? { file: input.file } : {}),
+    ...(input.span !== undefined ? { span: input.span } : {}),
+    ...(input.fixHint ?? guidance?.fixHint ? { fixHint: input.fixHint ?? guidance?.fixHint } : {}),
+    ...(input.suggestedCommands ?? guidance?.suggestedCommands
+      ? { suggestedCommands: input.suggestedCommands ?? guidance?.suggestedCommands }
+      : {}),
+    ...(input.docs ?? guidance?.docs ? { docs: input.docs ?? guidance?.docs } : {}),
+  };
+}
+
+export function forgeDupSymbol(
+  qualifiedName: string,
+  file: string,
+): Diagnostic {
+  return createDiagnostic({
+    severity: "warning",
+    code: "FORGE_DUP_SYMBOL",
+    message: `duplicate symbol id for '${qualifiedName}'`,
+    file,
+  });
+}
+
+export function forgeDrift(file: string): Diagnostic {
+  return createDiagnostic({
+    severity: "warning",
+    code: "FORGE_DRIFT",
+    message: `generated file drift detected: ${file}`,
+    file,
+  });
+}
+
+export function forgePkgNoTypes(
+  packageName: string,
+  subpath: string,
+): Diagnostic {
+  return createDiagnostic({
+    severity: "warning",
+    code: "FORGE_PKG_NO_TYPES",
+    message: `no types found for '${packageName}' subpath '${subpath}'`,
+  });
+}
+
+export function forgeGuardViolation(
+  packageName: string,
+  context: string,
+  rationale: string,
+  file: string,
+  span: { start: number; end: number },
+): Diagnostic {
+  return createDiagnostic({
+    severity: "error",
+    code: "FORGE_GUARD_VIOLATION",
+    message: `'${packageName}' is not allowed in '${context}' context: ${rationale}`,
+    file,
+    span,
+    fixHint:
+      context === "command" || context === "query" || context === "liveQuery"
+        ? `Move '${packageName}' usage out of the ${context} path into an action/workflow, then emit an event from the ${context}.`
+        : `Move '${packageName}' usage to a runtime context that allows it, or add a package recipe exception intentionally.`,
+    suggestedCommands:
+      context === "command"
+        ? [`forge refactor extract-action <command> --package ${packageName} --dry-run --json`, "forge repair diagnose --diagnostic FORGE_GUARD_VIOLATION --json"]
+        : ["forge inspect runtime-matrix --json", "forge repair diagnose --diagnostic FORGE_GUARD_VIOLATION --json"],
+    docs: ["src/forge/_generated/runtimeRules.md", "AGENTS.md"],
+  });
+}
+
+export function forgeSandboxLimit(packageName: string): Diagnostic {
+  return createDiagnostic({
+    severity: "warning",
+    code: "FORGE_SANDBOX_LIMIT",
+    message: `sandbox limit exceeded while inspecting '${packageName}'; falling back to static analysis`,
+  });
+}
+
+export function forgeSandboxAbnormal(packageName: string, detail?: string): Diagnostic {
+  const suffix = detail ? ` (${detail})` : "";
+  return createDiagnostic({
+    severity: "warning",
+    code: "FORGE_SANDBOX_ABNORMAL",
+    message: `runtime inspection process exited abnormally for '${packageName}'; falling back to static-only package analysis${suffix}`,
+  });
+}
+
+export function forgeSecretLeak(): Diagnostic {
+  return createDiagnostic({
+    severity: "error",
+    code: "FORGE_SECRET_LEAK",
+    message:
+      "secret leak detected in sandbox inspection result; withholding runtime data",
+  });
+}
+
+export function forgeOrphanedGeneratedFile(file: string): Diagnostic {
+  return createDiagnostic({
+    severity: "error",
+    code: "FORGE_ORPHANED_GENERATED_FILE",
+    message: `orphaned generated file: ${file}`,
+    file,
+  });
+}
+
+export function forgeWriteError(file: string): Diagnostic {
+  return createDiagnostic({
+    severity: "error",
+    code: "FORGE_WRITE_ERROR",
+    message: `failed to write generated file: ${file}`,
+    file,
+  });
+}

package/src/forge/compiler/diagnostics/index.ts

@@ -0,0 +1,55 @@
+export {
+  FORGE_DUP_SYMBOL,
+  FORGE_DRIFT,
+  FORGE_PKG_NO_TYPES,
+  FORGE_GUARD_VIOLATION,
+  FORGE_SANDBOX_LIMIT,
+  FORGE_SECRET_LEAK,
+  FORGE_ORPHANED_GENERATED_FILE,
+  FORGE_SANDBOX_ABNORMAL,
+  FORGE_DUP_RUNTIME_ENTRY,
+  FORGE_RUNTIME_UNRESOLVABLE,
+  FORGE_RUNTIME_NOT_FOUND,
+  FORGE_RUNTIME_GUARD_BLOCKED,
+  FORGE_DEV_SERVER_ERROR,
+  FORGE_DEV_WATCH_FAILED,
+  FORGE_DEV_INVOKE_FAILED,
+  FORGE_DB_CONNECT_FAILED,
+  FORGE_DB_MIGRATION_FAILED,
+  FORGE_DB_UNSUPPORTED_FIELD_TYPE,
+  FORGE_DB_INVALID_SQL_PLAN,
+  FORGE_DB_TRANSACTION_FAILED,
+  FORGE_DB_OUTBOX_WRITE_FAILED,
+  FORGE_DB_ADAPTER_UNAVAILABLE,
+  FORGE_AI_FORBIDDEN_CONTEXT,
+  FORGE_AI_PROVIDER_UNKNOWN,
+  FORGE_AI_MODEL_MISSING,
+  FORGE_AI_SECRET_MISSING,
+  FORGE_AI_DYNAMIC_PROVIDER,
+  FORGE_AI_GENERATION_FAILED,
+  FORGE_AI_USAGE_UNAVAILABLE,
+  FORGE_LIVEQUERY_WRITE_FORBIDDEN,
+  FORGE_LIVEQUERY_EMIT_FORBIDDEN,
+  FORGE_LIVEQUERY_SECRET_FORBIDDEN,
+  FORGE_LIVEQUERY_AI_FORBIDDEN,
+  FORGE_LIVEQUERY_INTEGRATION_FORBIDDEN,
+  FORGE_LIVEQUERY_POLICY_DENIED,
+  FORGE_LIVEQUERY_UNKNOWN,
+  FORGE_LIVEQUERY_SUBSCRIPTION_FAILED,
+  FORGE_LIVEQUERY_RERUN_FAILED,
+  DIAGNOSTIC_CODES,
+} from "./codes.ts";
+export type { DiagnosticCode } from "./codes.ts";
+export {
+  createDiagnostic,
+  forgeDupSymbol,
+  forgeDrift,
+  forgePkgNoTypes,
+  forgeGuardViolation,
+  forgeSandboxLimit,
+  forgeSandboxAbnormal,
+  forgeSecretLeak,
+  forgeOrphanedGeneratedFile,
+  forgeWriteError,
+} from "./create.ts";
+export type { DiagnosticInput } from "./create.ts";

package/src/forge/compiler/emitter/artifact-kind.ts

@@ -0,0 +1,14 @@
+export type ArtifactKind = "json" | "typescript" | "markdown" | "text";
+
+export function detectArtifactKind(path: string): ArtifactKind {
+  if (path.endsWith(".json")) {
+    return "json";
+  }
+  if (path.endsWith(".ts") || path.endsWith(".tsx")) {
+    return "typescript";
+  }
+  if (path.endsWith(".md")) {
+    return "markdown";
+  }
+  return "text";
+}

package/src/forge/compiler/emitter/barrel.ts

@@ -0,0 +1,44 @@
+import { comparePaths, normalizeNewlines, normalizePath } from "../primitives/index.ts";
+import { BARREL_INDEX_PATH, GENERATED_DIR } from "./constants.ts";
+
+function toBarrelExportPath(filePath: string): string {
+  const normalized = normalizePath(filePath);
+  const generatedPrefix = `${GENERATED_DIR}/`;
+
+  if (!normalized.startsWith(generatedPrefix)) {
+    throw new Error(`barrel export path must live under ${GENERATED_DIR}: ${filePath}`);
+  }
+
+  const relative = normalized.slice(generatedPrefix.length);
+  const withoutExtension = relative.replace(/\.tsx?$/, "");
+  return `./${withoutExtension}`;
+}
+
+/**
+ * Build barrel index.ts body (sorted re-exports, no header).
+ */
+export function buildBarrelIndexBody(exportFilePaths: string[]): string {
+  const candidates = exportFilePaths
+    .map(normalizePath)
+    .filter(
+      (path) =>
+        path.startsWith(`${GENERATED_DIR}/`) &&
+        (path.endsWith(".ts") || path.endsWith(".tsx")) &&
+        !path.endsWith(".d.ts") &&
+        path !== BARREL_INDEX_PATH,
+    );
+
+  const unique = [...new Set(candidates)];
+  unique.sort(comparePaths);
+
+  const lines = unique.map((path) => {
+    const exportPath = toBarrelExportPath(path);
+    return `export * from "${exportPath}";`;
+  });
+
+  if (lines.length === 0) {
+    return normalizeNewlines("// Forge generated barrel\n");
+  }
+
+  return normalizeNewlines(lines.join("\n"));
+}

package/src/forge/compiler/emitter/constants.ts

@@ -0,0 +1,7 @@
+import { GENERATOR_VERSION } from "../package-graph/constants.ts";
+
+export const FORGE_LOCK_SCHEMA_VERSION = "1.0.0";
+export const GENERATED_DIR = "src/forge/_generated";
+export const FORGE_LOCK_PATH = "forge.lock";
+export const BARREL_INDEX_PATH = `${GENERATED_DIR}/index.ts`;
+export { GENERATOR_VERSION };

package/src/forge/compiler/emitter/emit.ts

@@ -0,0 +1,237 @@
+import { join } from "node:path";
+import type { Diagnostic } from "../types/diagnostic.ts";
+import type { EmitFile, EmitMode, EmitPlan } from "../types/emit.ts";
+import { runWithConcurrency } from "../cache/scheduler.ts";
+import { nodeFileSystem } from "../fs/index.ts";
+import type { FileSystem } from "../fs/index.ts";
+import {
+  forgeDrift,
+  forgeOrphanedGeneratedFile,
+  forgeWriteError,
+} from "../diagnostics/create.ts";
+import {
+  hashStable,
+  normalizePath,
+  stableSortByPath,
+  stableSortEmitFiles,
+  stripDeterministicHeader,
+} from "../primitives/index.ts";
+import { buildBarrelIndexBody } from "./barrel.ts";
+import {
+  BARREL_INDEX_PATH,
+  FORGE_LOCK_PATH,
+  GENERATED_DIR,
+} from "./constants.ts";
+import { serializeForgeLock } from "./lock.ts";
+import { render, renderBody, type RenderContext } from "./render.ts";
+import {
+  readTextFileIfExists,
+  removeFileIfExists,
+  writeFileAtomic,
+} from "./write.ts";
+
+export interface EmitOptions {
+  workspaceRoot: string;
+  mode: EmitMode;
+  fs?: FileSystem;
+}
+
+export interface EmitResult {
+  changed: string[];
+  unchanged: string[];
+  removed: string[];
+  wouldChange: string[];
+  warnings: Diagnostic[];
+  errors: Diagnostic[];
+  exitCode: 0 | 1;
+}
+
+function resolveWorkspacePath(workspaceRoot: string, relativePath: string): string {
+  return join(workspaceRoot, normalizePath(relativePath));
+}
+
+function bodiesDiffer(rendered: string, onDisk: string | null): boolean {
+  const renderedBody = stripDeterministicHeader(rendered);
+  if (onDisk === null) {
+    return true;
+  }
+  const diskBody = stripDeterministicHeader(onDisk);
+  return renderedBody !== diskBody;
+}
+
+function buildRenderContext(plan: EmitPlan): RenderContext {
+  return {
+    generatorVersion: plan.lock.generatorVersion,
+    inputHash: plan.lock.inputHash,
+  };
+}
+
+function upsertBarrelFile(files: EmitFile[], exportPaths: string[]): EmitFile[] {
+  const body = buildBarrelIndexBody(exportPaths);
+  const barrel: EmitFile = {
+    path: BARREL_INDEX_PATH,
+    content: body,
+    contentHash: hashStable(body),
+  };
+
+  const withoutBarrel = files.filter((file) => file.path !== BARREL_INDEX_PATH);
+  return stableSortEmitFiles([...withoutBarrel, barrel]);
+}
+
+function preparePlannedFiles(plan: EmitPlan): EmitFile[] {
+  const exportPaths = plan.files.map((file) => file.path);
+  return upsertBarrelFile(plan.files, exportPaths);
+}
+
+async function classifyFile(
+  file: EmitFile,
+  context: RenderContext,
+  workspaceRoot: string,
+  fs: FileSystem = nodeFileSystem,
+): Promise<"changed" | "unchanged"> {
+  const rendered = render(file, context);
+  const absolutePath = resolveWorkspacePath(workspaceRoot, file.path);
+  const onDisk = await readTextFileIfExists(absolutePath, fs);
+  return bodiesDiffer(rendered, onDisk) ? "changed" : "unchanged";
+}
+
+export async function emit(plan: EmitPlan, options: EmitOptions): Promise<EmitResult> {
+  const { workspaceRoot, mode } = options;
+  const fs = options.fs ?? nodeFileSystem;
+  const context = buildRenderContext(plan);
+  const plannedFiles = preparePlannedFiles(plan);
+  const sortedOrphans = stableSortByPath([...plan.orphanedFiles]);
+
+  const changed: string[] = [];
+  const unchanged: string[] = [];
+  const wouldChange: string[] = [];
+  const removed: string[] = [];
+  const warnings: Diagnostic[] = [];
+  const errors: Diagnostic[] = [];
+
+  const classifications = await runWithConcurrency(
+    plannedFiles,
+    8,
+    async (file) => {
+      const rendered = render(file, context);
+      const absolutePath = resolveWorkspacePath(workspaceRoot, file.path);
+      const onDisk = await readTextFileIfExists(absolutePath, fs);
+      return {
+        file,
+        rendered,
+        differs: bodiesDiffer(rendered, onDisk),
+      };
+    },
+  );
+
+  for (const { file, rendered, differs } of classifications) {
+    if (differs) {
+      changed.push(file.path);
+      wouldChange.push(file.path);
+
+      if (mode === "check" || mode === "dry-run") {
+        warnings.push(forgeDrift(file.path));
+        continue;
+      }
+
+      try {
+        const absolutePath = resolveWorkspacePath(workspaceRoot, file.path);
+        await writeFileAtomic(absolutePath, rendered, fs);
+      } catch {
+        errors.push(forgeWriteError(file.path));
+      }
+    } else {
+      unchanged.push(file.path);
+    }
+  }
+
+  for (const orphan of sortedOrphans) {
+    const normalizedOrphan = normalizePath(orphan);
+    if (!normalizedOrphan.startsWith(`${GENERATED_DIR}/`)) {
+      continue;
+    }
+
+    const absoluteOrphan = resolveWorkspacePath(workspaceRoot, normalizedOrphan);
+
+    if (mode === "check") {
+      errors.push(forgeOrphanedGeneratedFile(normalizedOrphan));
+      continue;
+    }
+
+    if (mode === "dry-run") {
+      wouldChange.push(normalizedOrphan);
+      continue;
+    }
+
+    const removedOrphan = await removeFileIfExists(absoluteOrphan, fs);
+    if (removedOrphan) {
+      removed.push(normalizedOrphan);
+    }
+  }
+
+  const lockDiffers = await lockWouldChange(plan, workspaceRoot, fs);
+
+  if (lockDiffers) {
+    wouldChange.push(FORGE_LOCK_PATH);
+    if (mode === "check" || mode === "dry-run") {
+      warnings.push(forgeDrift(FORGE_LOCK_PATH));
+    }
+  }
+
+  if (mode === "write" && errors.length === 0) {
+    const lockContent = serializeForgeLock(plan.lock);
+    const lockAbsolutePath = resolveWorkspacePath(workspaceRoot, FORGE_LOCK_PATH);
+
+    try {
+      if (lockDiffers) {
+        await writeFileAtomic(lockAbsolutePath, lockContent, fs);
+        changed.push(FORGE_LOCK_PATH);
+      } else {
+        unchanged.push(FORGE_LOCK_PATH);
+      }
+    } catch {
+      errors.push(forgeWriteError(FORGE_LOCK_PATH));
+    }
+  }
+
+  const driftFailure =
+    mode === "check" &&
+    (changed.length > 0 || sortedOrphans.length > 0 || lockDiffers);
+  const exitCode: 0 | 1 =
+    errors.length > 0 || driftFailure ? 1 : 0;
+
+  return {
+    changed,
+    unchanged,
+    removed,
+    wouldChange,
+    warnings,
+    errors,
+    exitCode,
+  };
+}
+
+async function lockWouldChange(
+  plan: EmitPlan,
+  workspaceRoot: string,
+  fs: FileSystem = nodeFileSystem,
+): Promise<boolean> {
+  const lockContent = serializeForgeLock(plan.lock);
+  const lockAbsolutePath = resolveWorkspacePath(workspaceRoot, FORGE_LOCK_PATH);
+  const onDisk = await readTextFileIfExists(lockAbsolutePath, fs);
+  return onDisk !== lockContent;
+}
+
+/**
+ * Exposed for tests: classify a single file without writing.
+ */
+export async function classifyPlannedFile(
+  file: EmitFile,
+  context: RenderContext,
+  workspaceRoot: string,
+  fs: FileSystem = nodeFileSystem,
+): Promise<"changed" | "unchanged"> {
+  return classifyFile(file, context, workspaceRoot, fs);
+}
+
+export { render, renderBody, serializeForgeLock, buildBarrelIndexBody };

package/src/forge/compiler/emitter/index.ts

@@ -0,0 +1,24 @@
+export {
+  FORGE_LOCK_SCHEMA_VERSION,
+  GENERATED_DIR,
+  FORGE_LOCK_PATH,
+  BARREL_INDEX_PATH,
+  GENERATOR_VERSION,
+} from "./constants.ts";
+export { detectArtifactKind } from "./artifact-kind.ts";
+export type { ArtifactKind } from "./artifact-kind.ts";
+export { render, renderBody } from "./render.ts";
+export type { RenderContext } from "./render.ts";
+export { serializeForgeLock } from "./lock.ts";
+export { buildBarrelIndexBody } from "./barrel.ts";
+export {
+  readTextFileIfExists,
+  writeFileAtomic,
+  removeFileIfExists,
+} from "./write.ts";
+export {
+  emit,
+  classifyPlannedFile,
+  type EmitOptions,
+  type EmitResult,
+} from "./emit.ts";

package/src/forge/compiler/emitter/lock.ts

@@ -0,0 +1,62 @@
+import type { ForgeLock, ForgeLockEntry } from "../types/lock.ts";
+import type { SecretRequirement } from "../types/capability.ts";
+import {
+  compareBytes,
+  serializeCanonical,
+  stableSortByPath,
+  stableSortStrings,
+} from "../primitives/index.ts";
+
+function compareLockEntries(a: ForgeLockEntry, b: ForgeLockEntry): number {
+  return compareBytes(a.name, b.name);
+}
+
+function compareSecrets(a: SecretRequirement, b: SecretRequirement): number {
+  return compareBytes(a.envVar, b.envVar);
+}
+
+function stableSortLockEntries(entries: ForgeLockEntry[]): ForgeLockEntry[] {
+  return [...entries].sort(compareLockEntries);
+}
+
+function stableSortSecrets(secrets: SecretRequirement[]): SecretRequirement[] {
+  return [...secrets].sort(compareSecrets);
+}
+
+function canonicalizeLockEntry(entry: ForgeLockEntry): ForgeLockEntry {
+  return {
+    name: entry.name,
+    version: entry.version,
+    ...(entry.recipeVersion !== undefined
+      ? { recipeVersion: entry.recipeVersion }
+      : {}),
+    runtimeContexts: stableSortStrings([...entry.runtimeContexts]) as ForgeLockEntry["runtimeContexts"],
+    capabilities: {
+      ...entry.capabilities,
+      secrets: stableSortSecrets([...entry.capabilities.secrets]),
+    },
+    secrets: stableSortSecrets([...entry.secrets]),
+    generatedFiles: stableSortByPath([...entry.generatedFiles]),
+    contentChecksum: entry.contentChecksum,
+  };
+}
+
+/**
+ * Deterministic forge.lock serialization (no deterministic header).
+ */
+export function serializeForgeLock(lock: ForgeLock): string {
+  const canonical: ForgeLock = {
+    schemaVersion: lock.schemaVersion,
+    generatorVersion: lock.generatorVersion,
+    analyzerVersion: lock.analyzerVersion,
+    inputHash: lock.inputHash,
+    lockfileHash: lock.lockfileHash,
+    packageManager: lock.packageManager,
+    ...(lock.recipeVersion !== undefined
+      ? { recipeVersion: lock.recipeVersion }
+      : {}),
+    packages: stableSortLockEntries(lock.packages).map(canonicalizeLockEntry),
+  };
+
+  return serializeCanonical(canonical);
+}