forgeos 0.1.0-alpha.0

package/src/forge/compiler/runtime-graph/build.ts

@@ -0,0 +1,137 @@
+import { createDiagnostic } from "../diagnostics/create.ts";
+import { hashStable } from "../primitives/hash.ts";
+import { canonicalJson } from "../primitives/serialize.ts";
+import type { AppGraph } from "../types/app-graph.ts";
+import type { RuntimeEntry, RuntimeGraph } from "../types/runtime-graph.ts";
+import { GENERATOR_VERSION } from "../emitter/constants.ts";
+import {
+  RUNTIME_GRAPH_ANALYZER_VERSION,
+  RUNTIME_GRAPH_SCHEMA_VERSION,
+} from "./constants.ts";
+
+const RUNTIME_KINDS = new Set(["command", "action"]);
+
+function stableSortEntries(entries: RuntimeEntry[]): RuntimeEntry[] {
+  return [...entries].sort((a, b) => {
+    if (a.name !== b.name) {
+      return a.name < b.name ? -1 : 1;
+    }
+    if (a.file !== b.file) {
+      return a.file < b.file ? -1 : 1;
+    }
+    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+  });
+}
+
+function moduleIdForFile(
+  moduleGraph: AppGraph["moduleGraph"],
+  file: string,
+): string | null {
+  const node = moduleGraph.nodes.find((candidate) => candidate.file === file);
+  return node?.id ?? null;
+}
+
+function dependenciesForModule(
+  moduleGraph: AppGraph["moduleGraph"],
+  moduleId: string,
+): string[] {
+  const node = moduleGraph.nodes.find((candidate) => candidate.id === moduleId);
+  if (!node) {
+    return [];
+  }
+
+  const deps = node.localImports.map((imp) => imp.toModuleId);
+  return [...new Set(deps)].sort();
+}
+
+function detectDuplicateEntryNames(entries: RuntimeEntry[]): RuntimeGraph["diagnostics"] {
+  const byName = new Map<string, RuntimeEntry[]>();
+
+  for (const entry of entries) {
+    const list = byName.get(entry.name) ?? [];
+    list.push(entry);
+    byName.set(entry.name, list);
+  }
+
+  const diagnostics: RuntimeGraph["diagnostics"] = [];
+
+  for (const [name, group] of byName) {
+    if (group.length <= 1) {
+      continue;
+    }
+
+    for (const entry of group) {
+      diagnostics.push(
+        createDiagnostic({
+          severity: "warning",
+          code: "FORGE_DUP_RUNTIME_ENTRY",
+          message: `duplicate runtime entry name '${name}'`,
+          file: entry.file,
+        }),
+      );
+    }
+  }
+
+  return diagnostics.sort((a, b) => {
+    const fileA = a.file ?? "";
+    const fileB = b.file ?? "";
+    if (fileA !== fileB) {
+      return fileA < fileB ? -1 : 1;
+    }
+    return a.message < b.message ? -1 : a.message > b.message ? 1 : 0;
+  });
+}
+
+export function buildRuntimeGraph(appGraph: AppGraph): RuntimeGraph {
+  const entries: RuntimeEntry[] = [];
+  const diagnostics: RuntimeGraph["diagnostics"] = [];
+
+  for (const symbol of appGraph.symbols) {
+    if (!RUNTIME_KINDS.has(symbol.kind)) {
+      continue;
+    }
+
+    const kind = symbol.kind as "command" | "action";
+    const moduleId = moduleIdForFile(appGraph.moduleGraph, symbol.file);
+
+    if (moduleId === null) {
+      diagnostics.push(
+        createDiagnostic({
+          severity: "warning",
+          code: "FORGE_RUNTIME_UNRESOLVABLE",
+          message: `cannot resolve module for runtime entry '${symbol.qualifiedName}'`,
+          file: symbol.file,
+          span: symbol.span,
+        }),
+      );
+      continue;
+    }
+
+    entries.push({
+      id: symbol.id,
+      kind,
+      name: symbol.name,
+      qualifiedName: symbol.qualifiedName,
+      file: symbol.file,
+      moduleId,
+      runtimeContext: kind,
+      dependencies: dependenciesForModule(appGraph.moduleGraph, moduleId),
+    });
+  }
+
+  const dupDiagnostics = detectDuplicateEntryNames(entries);
+
+  return {
+    schemaVersion: RUNTIME_GRAPH_SCHEMA_VERSION,
+    generatorVersion: GENERATOR_VERSION,
+    analyzerVersion: RUNTIME_GRAPH_ANALYZER_VERSION,
+    inputHash: hashStable(
+      canonicalJson({
+        appInputHash: appGraph.inputHash,
+        analyzerVersion: RUNTIME_GRAPH_ANALYZER_VERSION,
+      }),
+    ),
+    entries: stableSortEntries(entries),
+    diagnostics: [...diagnostics, ...dupDiagnostics],
+  };
+}

package/src/forge/compiler/runtime-graph/constants.ts

@@ -0,0 +1,5 @@
+/** RuntimeGraph model schema version. */
+export const RUNTIME_GRAPH_SCHEMA_VERSION = "1.0.0";
+
+/** RuntimeGraph command/action analyzer version. */
+export const RUNTIME_GRAPH_ANALYZER_VERSION = "0.1.0";

package/src/forge/compiler/runtime-graph/index.ts

@@ -0,0 +1,5 @@
+export { buildRuntimeGraph } from "./build.ts";
+export {
+  RUNTIME_GRAPH_ANALYZER_VERSION,
+  RUNTIME_GRAPH_SCHEMA_VERSION,
+} from "./constants.ts";

package/src/forge/compiler/sandbox/artifact-sanitize.ts

@@ -0,0 +1,26 @@
+import type { PackageApi } from "../types/package-graph.ts";
+import { canonicalJson } from "../primitives/serialize.ts";
+import { secretLeakScan } from "./secret-scan.ts";
+
+export function packageApiContainsSecretValues(
+  api: PackageApi,
+  knownSecretValues: Iterable<string> = [],
+): boolean {
+  const serialized = canonicalJson(api);
+  return secretLeakScan(serialized, {
+    knownSecretValues,
+    includeHighEntropy: false,
+  }).hasLeak;
+}
+
+/**
+ * Ensures cached/emitted package analysis retains secret names only — never values.
+ */
+export function assertPackageApiSecretSafe(
+  api: PackageApi,
+  knownSecretValues: Iterable<string> = [],
+): void {
+  if (packageApiContainsSecretValues(api, knownSecretValues)) {
+    throw new Error("package api artifact contains secret material");
+  }
+}

package/src/forge/compiler/sandbox/backends/child.ts

@@ -0,0 +1,123 @@
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import type { SandboxLimits } from "../../types/cli.ts";
+import type { Dependency } from "../../types/package-graph.ts";
+import { SANDBOX_KILL_GRACE_MS } from "../limits.ts";
+
+export interface ChildRunResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number | null;
+  timedOut: boolean;
+  oomKilled: boolean;
+  startFailed: boolean;
+}
+
+export interface ChildRunner {
+  run(
+    dep: Dependency,
+    limits: SandboxLimits,
+    env: Record<string, string>,
+  ): Promise<ChildRunResult>;
+}
+
+const INSPECTOR_ENTRY = fileURLToPath(
+  new URL("../inspector-entry.ts", import.meta.url),
+);
+
+function resolveRuntimeExecutable(): string {
+  return process.execPath;
+}
+
+export const defaultChildRunner: ChildRunner = {
+  async run(dep, limits, env) {
+    const executable = resolveRuntimeExecutable();
+    const args = [INSPECTOR_ENTRY, dep.installPath];
+
+    return new Promise<ChildRunResult>((resolve) => {
+      let stdout = "";
+      let stderr = "";
+      let timedOut = false;
+      let oomKilled = false;
+      let startFailed = false;
+      let settled = false;
+
+      const child = spawn(executable, args, {
+        env: {
+          ...env,
+          FORGE_SANDBOX: "1",
+          NODE_OPTIONS: `--max-old-space-size=${limits.memoryMb}`,
+        },
+        stdio: ["ignore", "pipe", "pipe"],
+        windowsHide: true,
+      });
+
+      const killTimer = setTimeout(() => {
+        timedOut = true;
+        child.kill("SIGTERM");
+        setTimeout(() => {
+          if (!child.killed) {
+            child.kill("SIGKILL");
+          }
+        }, SANDBOX_KILL_GRACE_MS);
+      }, limits.timeoutMs);
+
+      child.stdout.on("data", (chunk: Buffer | string) => {
+        stdout += String(chunk);
+      });
+
+      child.stderr.on("data", (chunk: Buffer | string) => {
+        stderr += String(chunk);
+      });
+
+      child.on("error", () => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        clearTimeout(killTimer);
+        startFailed = true;
+        resolve({
+          stdout,
+          stderr,
+          exitCode: null,
+          timedOut,
+          oomKilled,
+          startFailed,
+        });
+      });
+
+      child.on("close", (code, signal) => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        clearTimeout(killTimer);
+        if (signal === "SIGKILL" && timedOut) {
+          // timeout path
+        }
+        if (stderr.includes("heap out of memory") || stderr.includes("ENOMEM")) {
+          oomKilled = true;
+        }
+        resolve({
+          stdout,
+          stderr,
+          exitCode: code,
+          timedOut,
+          oomKilled,
+          startFailed,
+        });
+      });
+    });
+  },
+};
+
+let childRunner: ChildRunner = defaultChildRunner;
+
+export function setChildRunner(runner: ChildRunner | undefined): void {
+  childRunner = runner ?? defaultChildRunner;
+}
+
+export function getChildRunner(): ChildRunner {
+  return childRunner;
+}

package/src/forge/compiler/sandbox/backends/docker.ts

@@ -0,0 +1,173 @@
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import type { SandboxLimits } from "../../types/cli.ts";
+import type { Dependency } from "../../types/package-graph.ts";
+import { DEFAULT_SANDBOX_PIDS_LIMIT, SANDBOX_KILL_GRACE_MS } from "../limits.ts";
+
+export interface DockerRunResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number | null;
+  timedOut: boolean;
+  oomKilled: boolean;
+  startFailed: boolean;
+  dockerUnavailable: boolean;
+}
+
+export interface DockerRunner {
+  run(
+    dep: Dependency,
+    limits: SandboxLimits,
+    env: Record<string, string>,
+  ): Promise<DockerRunResult>;
+}
+
+const INSPECTOR_ENTRY = fileURLToPath(
+  new URL("../inspector-entry.ts", import.meta.url),
+);
+
+const DEFAULT_DOCKER_IMAGE = "oven/bun:1";
+
+function buildDockerArgs(
+  dep: Dependency,
+  limits: SandboxLimits,
+  env: Record<string, string>,
+): string[] {
+  const args = [
+    "run",
+    "--rm",
+    "--network",
+    "none",
+    "--read-only",
+    "--memory",
+    `${limits.memoryMb}m`,
+    "--pids-limit",
+    String(DEFAULT_SANDBOX_PIDS_LIMIT),
+    "--cap-drop",
+    "ALL",
+    "-v",
+    `${dep.installPath}:/pkg:ro`,
+    "-v",
+    `${INSPECTOR_ENTRY}:/inspector-entry.ts:ro`,
+  ];
+
+  for (const [key, value] of Object.entries(env)) {
+    args.push("-e", `${key}=${value}`);
+  }
+
+  args.push(
+    process.env.FORGE_SANDBOX_DOCKER_IMAGE ?? DEFAULT_DOCKER_IMAGE,
+    "bun",
+    "run",
+    "/inspector-entry.ts",
+    "/pkg",
+  );
+
+  return args;
+}
+
+export const defaultDockerRunner: DockerRunner = {
+  async run(dep, limits, env) {
+    const args = buildDockerArgs(dep, limits, env);
+
+    return new Promise<DockerRunResult>((resolve) => {
+      let stdout = "";
+      let stderr = "";
+      let timedOut = false;
+      let oomKilled = false;
+      let startFailed = false;
+      let dockerUnavailable = false;
+      let settled = false;
+
+      const child = spawn("docker", args, {
+        stdio: ["ignore", "pipe", "pipe"],
+        windowsHide: true,
+      });
+
+      const killTimer = setTimeout(() => {
+        timedOut = true;
+        child.kill("SIGTERM");
+        setTimeout(() => {
+          if (!child.killed) {
+            child.kill("SIGKILL");
+          }
+        }, SANDBOX_KILL_GRACE_MS);
+      }, limits.timeoutMs);
+
+      child.stdout.on("data", (chunk: Buffer | string) => {
+        stdout += String(chunk);
+      });
+
+      child.stderr.on("data", (chunk: Buffer | string) => {
+        stderr += String(chunk);
+      });
+
+      child.on("error", (error: NodeJS.ErrnoException) => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        clearTimeout(killTimer);
+        startFailed = true;
+        dockerUnavailable = error.code === "ENOENT";
+        resolve({
+          stdout,
+          stderr,
+          exitCode: null,
+          timedOut,
+          oomKilled,
+          startFailed,
+          dockerUnavailable,
+        });
+      });
+
+      child.on("close", (code) => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        clearTimeout(killTimer);
+        if (
+          stderr.includes("OOM") ||
+          stderr.includes("out of memory") ||
+          stderr.includes("Cannot allocate memory")
+        ) {
+          oomKilled = true;
+        }
+        resolve({
+          stdout,
+          stderr,
+          exitCode: code,
+          timedOut,
+          oomKilled,
+          startFailed,
+          dockerUnavailable: false,
+        });
+      });
+    });
+  },
+};
+
+let dockerRunner: DockerRunner = defaultDockerRunner;
+
+export function setDockerRunner(runner: DockerRunner | undefined): void {
+  dockerRunner = runner ?? defaultDockerRunner;
+}
+
+export function getDockerRunner(): DockerRunner {
+  return dockerRunner;
+}
+
+export function dockerRunFlags(limits: SandboxLimits): string[] {
+  return [
+    "--network",
+    "none",
+    "--read-only",
+    "--memory",
+    `${limits.memoryMb}m`,
+    "--pids-limit",
+    String(DEFAULT_SANDBOX_PIDS_LIMIT),
+    "--cap-drop",
+    "ALL",
+  ];
+}

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

@@ -0,0 +1,51 @@
+export {
+  inspectExports,
+  type SandboxInspectOptions,
+  type SandboxInspectResult,
+} from "./inspect.ts";
+export {
+  DEFAULT_SANDBOX_MEMORY_MB,
+  DEFAULT_SANDBOX_PIDS_LIMIT,
+  DEFAULT_SANDBOX_TIMEOUT_MS,
+  SANDBOX_KILL_GRACE_MS,
+  clampSandboxLimits,
+  defaultSandboxLimits,
+} from "./limits.ts";
+export { scrubEnv, isSecretEnvKey, type ScrubEnvOptions } from "./scrub-env.ts";
+export {
+  secretLeakScan,
+  type SecretScanOptions,
+  type SecretScanResult,
+} from "./secret-scan.ts";
+export {
+  assertJsonSerializable,
+  parseRuntimeExportShape,
+  sanitizeRuntimeExportShape,
+  serializeRuntimeExportShape,
+} from "./serialize.ts";
+export {
+  assertPackageApiSecretSafe,
+  packageApiContainsSecretValues,
+} from "./artifact-sanitize.ts";
+export {
+  emptyRuntimeExportShape,
+  type RuntimeEntrypointShape,
+  type RuntimeExportEntry,
+  type RuntimeExportKind,
+  type RuntimeExportShape,
+} from "./types.ts";
+export {
+  defaultChildRunner,
+  getChildRunner,
+  setChildRunner,
+  type ChildRunner,
+  type ChildRunResult,
+} from "./backends/child.ts";
+export {
+  defaultDockerRunner,
+  dockerRunFlags,
+  getDockerRunner,
+  setDockerRunner,
+  type DockerRunner,
+  type DockerRunResult,
+} from "./backends/docker.ts";

package/src/forge/compiler/sandbox/inspect.ts

@@ -0,0 +1,143 @@
+import type { Diagnostic } from "../types/diagnostic.ts";
+import type { SandboxLimits } from "../types/cli.ts";
+import type { Dependency } from "../types/package-graph.ts";
+import {
+  forgeSandboxAbnormal,
+  forgeSandboxLimit,
+  forgeSecretLeak,
+} from "../diagnostics/create.ts";
+import { getChildRunner } from "./backends/child.ts";
+import { getDockerRunner } from "./backends/docker.ts";
+import { clampSandboxLimits } from "./limits.ts";
+import { scrubEnv, type ScrubEnvOptions } from "./scrub-env.ts";
+import { secretLeakScan } from "./secret-scan.ts";
+import {
+  assertJsonSerializable,
+  parseRuntimeExportShape,
+  serializeRuntimeExportShape,
+} from "./serialize.ts";
+import {
+  emptyRuntimeExportShape,
+  type RuntimeExportShape,
+} from "./types.ts";
+
+export interface SandboxInspectOptions extends ScrubEnvOptions {
+  knownSecretValues?: Iterable<string>;
+}
+
+export interface SandboxInspectResult {
+  shape: RuntimeExportShape;
+  diagnostics: Diagnostic[];
+  runtimeUsed: boolean;
+}
+
+interface BackendRunOutcome {
+  stdout: string;
+  timedOut: boolean;
+  oomKilled: boolean;
+  startFailed: boolean;
+  abnormalExit: boolean;
+}
+
+export async function inspectExports(
+  dep: Dependency,
+  limitsInput: SandboxLimits,
+  options: SandboxInspectOptions = {},
+): Promise<SandboxInspectResult> {
+  const limits = clampSandboxLimits(limitsInput);
+  const diagnostics: Diagnostic[] = [];
+
+  if (limits.backend === "none") {
+    return {
+      shape: emptyRuntimeExportShape(),
+      diagnostics,
+      runtimeUsed: false,
+    };
+  }
+
+  const scrubbedEnv = scrubEnv(process.env, options);
+
+  let outcome: BackendRunOutcome;
+  if (limits.backend === "docker") {
+    const result = await getDockerRunner().run(dep, limits, scrubbedEnv);
+    outcome = {
+      stdout: result.stdout,
+      timedOut: result.timedOut,
+      oomKilled: result.oomKilled,
+      startFailed: result.startFailed || result.dockerUnavailable,
+      abnormalExit:
+        result.exitCode !== 0 &&
+        !result.timedOut &&
+        !result.oomKilled &&
+        !result.startFailed,
+    };
+  } else {
+    const result = await getChildRunner().run(dep, limits, scrubbedEnv);
+    outcome = {
+      stdout: result.stdout,
+      timedOut: result.timedOut,
+      oomKilled: result.oomKilled,
+      startFailed: result.startFailed,
+      abnormalExit:
+        result.exitCode !== 0 &&
+        !result.timedOut &&
+        !result.oomKilled &&
+        !result.startFailed,
+    };
+  }
+
+  if (outcome.timedOut || outcome.oomKilled) {
+    diagnostics.push(forgeSandboxLimit(dep.name));
+    return {
+      shape: emptyRuntimeExportShape(),
+      diagnostics,
+      runtimeUsed: false,
+    };
+  }
+
+  if (outcome.startFailed || outcome.abnormalExit) {
+    diagnostics.push(
+      forgeSandboxAbnormal(dep.name, "process exited abnormally"),
+    );
+    return {
+      shape: emptyRuntimeExportShape(),
+      diagnostics,
+      runtimeUsed: false,
+    };
+  }
+
+  let shape: RuntimeExportShape;
+  try {
+    shape = parseRuntimeExportShape(outcome.stdout.trim());
+    assertJsonSerializable(shape);
+  } catch {
+    diagnostics.push(
+      forgeSandboxAbnormal(dep.name, "invalid sandbox output"),
+    );
+    return {
+      shape: emptyRuntimeExportShape(),
+      diagnostics,
+      runtimeUsed: false,
+    };
+  }
+
+  const serialized = serializeRuntimeExportShape(shape);
+  const leak = secretLeakScan(serialized, {
+    knownSecretValues: options.knownSecretValues,
+  });
+
+  if (leak.hasLeak) {
+    diagnostics.push(forgeSecretLeak());
+    return {
+      shape: emptyRuntimeExportShape(),
+      diagnostics,
+      runtimeUsed: false,
+    };
+  }
+
+  return {
+    shape,
+    diagnostics,
+    runtimeUsed: shape.entrypoints.some((ep) => ep.exports.length > 0),
+  };
+}