forgeos 0.1.0-alpha.0

package/src/forge/runtime/runner/run-entry.ts

@@ -0,0 +1,226 @@
+import { join } from "node:path";
+import { createDiagnostic } from "../../compiler/diagnostics/create.ts";
+import {
+  FORGE_DB_ADAPTER_UNAVAILABLE,
+  FORGE_RUNTIME_GUARD_BLOCKED,
+  FORGE_RUNTIME_NOT_FOUND,
+} from "../../compiler/diagnostics/codes.ts";
+import type { TableMapEntry } from "../../compiler/data-graph/sql/serialize.ts";
+import type { Diagnostic } from "../../compiler/types/diagnostic.ts";
+import type { RuntimeEntry } from "../../compiler/types/runtime-graph.ts";
+import { adapterAsTransaction, type DbAdapter } from "../db/adapter.ts";
+import { createGeneratedDbClient } from "../db/generated-client.ts";
+import { createForgeContext, createNoopTelemetryContext, getRuntimeEnvStore } from "../context/create-context.ts";
+import { createAiContext } from "../ai/context.ts";
+import { createRuntimeSecretsBundle } from "../secrets/runtime-bundle.ts";
+import { loadEnvSchema, loadSecretRegistry } from "../secrets/check.ts";
+import type { RuntimeContext } from "../../compiler/types/runtime.ts";
+import { loadActionSubscriptions } from "../outbox/subscriptions.ts";
+import { runCommandWithTransaction } from "./command-transaction.ts";
+import { generateRequestId, generateTraceId } from "../telemetry/correlation.ts";
+import { createTelemetryContext } from "../telemetry/context.ts";
+import type { AuthContext } from "../auth/types.ts";
+import type { LiveSubscriptionManager } from "../live/types.ts";
+
+export interface RunEntryExecutionOptions {
+  json: boolean;
+  mock: boolean;
+  args?: unknown;
+  auth?: AuthContext;
+}
+
+export interface RunEntryRuntime {
+  adapter?: DbAdapter | null;
+  tableMap?: Record<string, TableMapEntry>;
+  workspaceRoot?: string;
+  requestId?: string;
+  auth?: AuthContext;
+  runtimeKind?: RuntimeContext;
+  liveManager?: LiveSubscriptionManager;
+}
+
+export interface ResolvedHandler {
+  invoke: (args: unknown) => Promise<unknown>;
+  usesContext: boolean;
+}
+
+function needsDatabaseHint(
+  entry: RuntimeEntry,
+  resolved: ResolvedHandler,
+  runtime?: RunEntryRuntime,
+): boolean {
+  return (
+    resolved.usesContext &&
+    !runtime?.adapter &&
+    (entry.kind === "command" || entry.kind === "action")
+  );
+}
+
+export function resolveHandlerFromModule(
+  mod: Record<string, unknown>,
+  entryName: string,
+  runtime?: RunEntryRuntime,
+): ResolvedHandler | null {
+  const exported = mod[entryName];
+
+  if (typeof exported === "function") {
+    return {
+      usesContext: false,
+      invoke: async () => (exported as () => unknown)(),
+    };
+  }
+
+  if (
+    exported &&
+    typeof exported === "object" &&
+    "handler" in exported &&
+    typeof (exported as { handler: unknown }).handler === "function"
+  ) {
+    const handler = (exported as {
+      handler: (ctx: unknown, args: unknown) => unknown | Promise<unknown>;
+    }).handler;
+
+    return {
+      usesContext: true,
+      invoke: async (args) => {
+        if (runtime?.adapter && runtime.tableMap) {
+          const tx = adapterAsTransaction(runtime.adapter);
+          const db = createGeneratedDbClient(tx, runtime.tableMap, {
+            auth: runtime.auth,
+          });
+          const workspaceRoot = runtime.workspaceRoot ?? process.cwd();
+          const { subscriptions } = loadActionSubscriptions(workspaceRoot);
+          const traceId = generateTraceId();
+          const telemetry = createTelemetryContext({
+            adapter: runtime.adapter,
+            tx,
+            traceId,
+            requestId: runtime.requestId ?? generateRequestId(),
+            runtime: { kind: "command", name: entryName },
+            bufferInTransaction: false,
+            workspaceRoot,
+          });
+          const runtimeKind = runtime.runtimeKind ?? "command";
+          const ctx = createForgeContext(tx, db, subscriptions, telemetry, runtime.auth ?? { kind: "anonymous" }, {
+            workspaceRoot,
+            runtimeKind,
+          });
+          return handler(ctx, args);
+        }
+
+        const workspaceRoot = runtime?.workspaceRoot ?? process.cwd();
+        const store = getRuntimeEnvStore(workspaceRoot);
+        const bundle = createRuntimeSecretsBundle({
+          store,
+          registry: loadSecretRegistry(workspaceRoot),
+          envSchema: loadEnvSchema(workspaceRoot),
+          runtimeKind: runtime?.runtimeKind ?? "command",
+        });
+
+        const stubTelemetry = createNoopTelemetryContext(generateTraceId());
+        const stubCtx = {
+          db: {},
+          env: store.snapshot(),
+          telemetry: stubTelemetry,
+          auth: runtime?.auth ?? { kind: "anonymous" as const },
+          secrets: bundle.secrets,
+          config: bundle.config,
+          ai: createAiContext({
+            secrets: bundle.secrets,
+            telemetry: stubTelemetry,
+            runtimeKind: runtime?.runtimeKind ?? "command",
+          }),
+          emit: async () => {
+            /* no-op without db */
+          },
+        };
+        return handler(stubCtx, args);
+      },
+    };
+  }
+
+  return null;
+}
+
+export async function executeResolvedEntry(
+  workspaceRoot: string,
+  entry: RuntimeEntry,
+  resolved: ResolvedHandler,
+  options: RunEntryExecutionOptions,
+  runtime?: RunEntryRuntime,
+): Promise<{
+  ok: boolean;
+  result?: unknown;
+  diagnostics: Diagnostic[];
+}> {
+  const diagnostics: Diagnostic[] = [];
+
+  if (
+    entry.kind === "command" &&
+    resolved.usesContext &&
+    runtime?.adapter &&
+    runtime.tableMap
+  ) {
+    const absolutePath = join(workspaceRoot, entry.file);
+    const mod = (await import(absolutePath)) as Record<string, unknown>;
+    const exported = mod[entry.name];
+    const handler = (exported as { handler: (ctx: unknown, args: unknown) => unknown })
+      .handler;
+
+    return runCommandWithTransaction(
+      entry,
+      handler,
+      options.args ?? {},
+      {
+        adapter: runtime.adapter,
+        tableMap: runtime.tableMap,
+        workspaceRoot,
+        requestId: runtime.requestId,
+        auth: options.auth ?? runtime.auth,
+        liveManager: runtime.liveManager,
+      },
+    );
+  }
+
+  try {
+    const result = await resolved.invoke(options.args ?? {});
+    return { ok: true, result, diagnostics };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "handler execution failed";
+    const dbHint = needsDatabaseHint(entry, resolved, runtime);
+    diagnostics.push(
+      createDiagnostic({
+        severity: "error",
+        code: dbHint ? FORGE_DB_ADAPTER_UNAVAILABLE : FORGE_RUNTIME_NOT_FOUND,
+        message: dbHint
+          ? `runtime entry '${entry.name}' needs a database adapter: ${message}`
+          : `runtime entry '${entry.name}' failed: ${message}`,
+        file: entry.file,
+        fixHint: dbHint
+          ? "Start `forge dev` and invoke the HTTP endpoint, or run database-backed entries from a DB-enabled workflow/test."
+          : undefined,
+        suggestedCommands: dbHint
+          ? ["forge dev", "forge dev --once --json"]
+          : undefined,
+      }),
+    );
+    return { ok: false, diagnostics };
+  }
+}
+
+export function guardBlockedDiagnostics(
+  entry: RuntimeEntry,
+  violations: Diagnostic[],
+  baseDiagnostics: Diagnostic[],
+): Diagnostic[] {
+  return [
+    ...baseDiagnostics,
+    ...violations,
+    createDiagnostic({
+      severity: "error",
+      code: FORGE_RUNTIME_GUARD_BLOCKED,
+      message: `runtime entry '${entry.name}' blocked by import guard violations`,
+      file: entry.file,
+    }),
+  ];
+}

package/src/forge/runtime/secrets/check.ts

@@ -0,0 +1,78 @@
+import { nodeFileSystem } from "../../compiler/fs/index.ts";
+import { join } from "node:path";
+import { GENERATED_DIR } from "../../compiler/emitter/constants.ts";
+import { stripDeterministicHeader } from "../../compiler/primitives/header.ts";
+import type {
+  EnvSchema,
+  SecretRegistry,
+} from "../../compiler/types/secret-registry.ts";
+import { redactSecretValue } from "./env-loader.ts";
+import type { RuntimeEnvStore } from "./types.ts";
+
+export interface SecretsCheckResult {
+  ok: boolean;
+  missing: string[];
+  present: { name: string; redacted: string }[];
+}
+
+export function loadSecretRegistry(workspaceRoot: string): SecretRegistry | null {
+  const absolute = join(workspaceRoot, GENERATED_DIR, "secretRegistry.json");
+  if (!nodeFileSystem.exists(absolute)) {
+    return null;
+  }
+
+  const raw = stripDeterministicHeader((nodeFileSystem.readText(absolute) ?? ""));
+  return JSON.parse(raw) as SecretRegistry;
+}
+
+export function loadEnvSchema(workspaceRoot: string): EnvSchema | null {
+  const absolute = join(workspaceRoot, GENERATED_DIR, "envSchema.json");
+  if (!nodeFileSystem.exists(absolute)) {
+    return null;
+  }
+
+  const raw = stripDeterministicHeader((nodeFileSystem.readText(absolute) ?? ""));
+  return JSON.parse(raw) as EnvSchema;
+}
+
+export function checkSecrets(
+  store: RuntimeEnvStore,
+  registry: SecretRegistry,
+): SecretsCheckResult {
+  const missing: string[] = [];
+  const present: { name: string; redacted: string }[] = [];
+
+  for (const entry of registry.secrets) {
+    const value = store.resolve(entry.name);
+    if (!value || value.length === 0) {
+      if (entry.required) {
+        missing.push(entry.name);
+      }
+      continue;
+    }
+
+    present.push({
+      name: entry.name,
+      redacted: redactSecretValue(value),
+    });
+  }
+
+  return {
+    ok: missing.length === 0,
+    missing: missing.sort(),
+    present: present.sort((a, b) => a.name.localeCompare(b.name)),
+  };
+}
+
+export function countMissingRequiredSecrets(
+  store: RuntimeEnvStore,
+  registry: SecretRegistry,
+): number {
+  return registry.secrets.filter((entry) => {
+    if (!entry.required) {
+      return false;
+    }
+    const value = store.resolve(entry.name);
+    return !value || value.length === 0;
+  }).length;
+}

package/src/forge/runtime/secrets/create-context.ts

@@ -0,0 +1,138 @@
+import {
+  FORGE_ENV_UNKNOWN_REQUIRED,
+  FORGE_SECRET_FORBIDDEN_CONTEXT,
+  FORGE_SECRET_MISSING,
+} from "../../compiler/diagnostics/codes.ts";
+import type { RuntimeContext } from "../../compiler/types/runtime.ts";
+import type {
+  ConfigContext,
+  CreateConfigContextOptions,
+  CreateSecretsContextOptions,
+  SecretsContext,
+} from "./types.ts";
+
+const SECRETS_FORBIDDEN: RuntimeContext[] = [
+  "command",
+  "client",
+  "query",
+  "liveQuery",
+];
+
+function forgeError(code: string, message: string): never {
+  const error = new Error(message);
+  (error as Error & { code: string }).code = code;
+  throw error;
+}
+
+export function secretsForbiddenInContext(runtimeKind: RuntimeContext): boolean {
+  return SECRETS_FORBIDDEN.includes(runtimeKind);
+}
+
+export function createSecretsContext(
+  options: CreateSecretsContextOptions,
+): SecretsContext {
+  const { store, registryNames, runtimeKind, requiredSecrets = [] } = options;
+
+  if (secretsForbiddenInContext(runtimeKind)) {
+    return {
+      get(name: string): string {
+        forgeError(
+          FORGE_SECRET_FORBIDDEN_CONTEXT,
+          `ctx.secrets.get('${name}') is forbidden in '${runtimeKind}' context`,
+        );
+      },
+      optional(_name: string): string | undefined {
+        return undefined;
+      },
+      has(_name: string): boolean {
+        return false;
+      },
+    };
+  }
+
+  function resolve(name: string): string | undefined {
+    return store.resolve(name);
+  }
+
+  return {
+    get(name: string): string {
+      const value = resolve(name);
+      if (value !== undefined && value.length > 0) {
+        return value;
+      }
+
+      const required =
+        requiredSecrets.find((entry) => entry.name === name)?.required ??
+        registryNames.has(name);
+
+      if (required) {
+        forgeError(
+          FORGE_SECRET_MISSING,
+          `required secret '${name}' is not set`,
+        );
+      }
+
+      forgeError(FORGE_SECRET_MISSING, `secret '${name}' is not set`);
+    },
+    optional(name: string): string | undefined {
+      const value = resolve(name);
+      return value && value.length > 0 ? value : undefined;
+    },
+    has(name: string): boolean {
+      const value = resolve(name);
+      return value !== undefined && value.length > 0;
+    },
+  };
+}
+
+export function createConfigContext(options: CreateConfigContextOptions): ConfigContext {
+  const { store, schema, runtimeKind } = options;
+  const schemaByName = new Map(schema.map((entry) => [entry.name, entry]));
+
+  function resolve(name: string): string | undefined {
+    return store.resolve(name);
+  }
+
+  return {
+    get(name: string): string {
+      const entry = schemaByName.get(name);
+      const value = resolve(name);
+
+      if (value !== undefined && value.length > 0) {
+        if (
+          entry?.kind === "secret" &&
+          secretsForbiddenInContext(runtimeKind) &&
+          runtimeKind === "command"
+        ) {
+          forgeError(
+            FORGE_SECRET_FORBIDDEN_CONTEXT,
+            `secret config '${name}' is not allowed in '${runtimeKind}' context`,
+          );
+        }
+        return value;
+      }
+
+      if (entry?.required) {
+        forgeError(
+          FORGE_ENV_UNKNOWN_REQUIRED,
+          `required config '${name}' is not set`,
+        );
+      }
+
+      forgeError(FORGE_ENV_UNKNOWN_REQUIRED, `config '${name}' is not set`);
+    },
+    optional(name: string): string | undefined {
+      const entry = schemaByName.get(name);
+      if (
+        entry?.kind === "secret" &&
+        secretsForbiddenInContext(runtimeKind) &&
+        runtimeKind === "command"
+      ) {
+        return undefined;
+      }
+
+      const value = resolve(name);
+      return value && value.length > 0 ? value : undefined;
+    },
+  };
+}

package/src/forge/runtime/secrets/env-loader.ts

@@ -0,0 +1,94 @@
+import { nodeFileSystem } from "../../compiler/fs/index.ts";
+import { join } from "node:path";
+import type { RuntimeEnvStore } from "./types.ts";
+
+export interface LoadEnvFilesOptions {
+  workspaceRoot: string;
+  /** Additional files after defaults; later files override earlier ones (before process.env). */
+  envFiles?: string[];
+}
+
+export interface LoadedEnvResult {
+  store: RuntimeEnvStore;
+}
+
+function parseEnvFile(content: string): Record<string, string> {
+  const values: Record<string, string> = {};
+
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (line.length === 0 || line.startsWith("#")) {
+      continue;
+    }
+
+    const eq = line.indexOf("=");
+    if (eq <= 0) {
+      continue;
+    }
+
+    const key = line.slice(0, eq).trim();
+    let value = line.slice(eq + 1).trim();
+
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+
+    values[key] = value;
+  }
+
+  return values;
+}
+
+/**
+ * Load env files with precedence at resolve time:
+ * process.env overrides .env.local overrides .env (defaults).
+ */
+export function loadEnvFiles(options: LoadEnvFilesOptions): LoadedEnvResult {
+  const workspaceRoot = options.workspaceRoot.replace(/\\/g, "/");
+  const defaultFiles = [".env", ".env.local"];
+  const extra = options.envFiles ?? [];
+  const ordered = [...defaultFiles, ...extra];
+
+  const loadedFiles: string[] = [];
+  const merged: Record<string, string> = {};
+
+  for (const file of ordered) {
+    const absolute = join(workspaceRoot, file);
+    if (!nodeFileSystem.exists(absolute)) {
+      continue;
+    }
+
+    loadedFiles.push(file);
+    const parsed = parseEnvFile((nodeFileSystem.readText(absolute) ?? ""));
+    Object.assign(merged, parsed);
+  }
+
+  const store: RuntimeEnvStore = {
+    loadedFiles,
+    resolve(name: string): string | undefined {
+      if (process.env[name] !== undefined) {
+        return process.env[name];
+      }
+      return merged[name];
+    },
+    snapshot(): Record<string, string | undefined> {
+      const snapshot: Record<string, string | undefined> = { ...merged };
+      for (const key of Object.keys(process.env)) {
+        snapshot[key] = process.env[key];
+      }
+      return snapshot;
+    },
+  };
+
+  return { store };
+}
+
+export function redactSecretValue(value: string): string {
+  if (value.length <= 4) {
+    return "***";
+  }
+  return `${value.slice(0, 4)}***`;
+}

package/src/forge/runtime/secrets/runtime-bundle.ts

@@ -0,0 +1,47 @@
+import type { RuntimeContext } from "../../compiler/types/runtime.ts";
+import type { RuntimeEnvStore } from "./types.ts";
+import {
+  createConfigContext,
+  createSecretsContext,
+} from "./create-context.ts";
+import type { ConfigContext, SecretsContext } from "./types.ts";
+import type { EnvSchema, SecretRegistry } from "../../compiler/types/secret-registry.ts";
+
+export interface RuntimeSecretsBundle {
+  secrets: SecretsContext;
+  config: ConfigContext;
+  store: RuntimeEnvStore;
+}
+
+export function createRuntimeSecretsBundle(input: {
+  store: RuntimeEnvStore;
+  registry: SecretRegistry | null;
+  envSchema: EnvSchema | null;
+  runtimeKind: RuntimeContext;
+}): RuntimeSecretsBundle {
+  const registryNames = new Set(
+    input.registry?.secrets.map((entry) => entry.name) ?? [],
+  );
+
+  const secrets = createSecretsContext({
+    store: input.store,
+    registryNames,
+    runtimeKind: input.runtimeKind,
+    requiredSecrets: input.registry?.secrets.map((entry) => ({
+      name: entry.name,
+      required: entry.required,
+    })),
+  });
+
+  const config = createConfigContext({
+    store: input.store,
+    schema: input.envSchema?.variables ?? [],
+    runtimeKind: input.runtimeKind,
+  });
+
+  return {
+    secrets,
+    config,
+    store: input.store,
+  };
+}

package/src/forge/runtime/secrets/types.ts

@@ -0,0 +1,31 @@
+import type { RuntimeContext } from "../../compiler/types/runtime.ts";
+
+export interface SecretsContext {
+  get(name: string): string;
+  optional(name: string): string | undefined;
+  has(name: string): boolean;
+}
+
+export interface ConfigContext {
+  get(name: string): string;
+  optional(name: string): string | undefined;
+}
+
+export interface RuntimeEnvStore {
+  loadedFiles: string[];
+  resolve(name: string): string | undefined;
+  snapshot(): Record<string, string | undefined>;
+}
+
+export interface CreateSecretsContextOptions {
+  store: RuntimeEnvStore;
+  registryNames: Set<string>;
+  runtimeKind: RuntimeContext;
+  requiredSecrets?: { name: string; required: boolean }[];
+}
+
+export interface CreateConfigContextOptions {
+  store: RuntimeEnvStore;
+  schema: { name: string; kind: "secret" | "config"; required: boolean }[];
+  runtimeKind: RuntimeContext;
+}

package/src/forge/runtime/telemetry/buffer.ts

@@ -0,0 +1,87 @@
+import type { DbAdapter, DbTransaction } from "../db/adapter.ts";
+import type { ForgeTelemetryEnvelope } from "./types.ts";
+import { scrubEnvelopePayload } from "./scrubber.ts";
+
+type QueryTarget = DbTransaction | DbAdapter;
+
+async function runQuery(
+  target: QueryTarget,
+  sql: string,
+  params: unknown[],
+) {
+  return target.query(sql, params);
+}
+
+export async function insertTelemetryEvent(
+  target: QueryTarget,
+  envelope: ForgeTelemetryEnvelope,
+): Promise<number> {
+  const { value } = scrubEnvelopePayload(envelope as unknown as Record<string, unknown>);
+  const eventName =
+    typeof value.event === "object" &&
+    value.event !== null &&
+    "name" in value.event
+      ? String((value.event as { name: unknown }).name)
+      : undefined;
+
+  const result = await runQuery(
+    target,
+    `INSERT INTO _forge_telemetry_events (trace_id, event_type, payload, status)
+     VALUES ($1, $2, $3::jsonb, 'pending')
+     RETURNING id`,
+    [value.traceId, eventName ?? value.type, JSON.stringify(value)],
+  );
+
+  const id = Number(result.rows[0]?.id);
+  if (!Number.isFinite(id)) {
+    throw new Error("telemetry insert did not return id");
+  }
+  return id;
+}
+
+export async function recordExceptionOutsideTx(
+  adapter: DbAdapter,
+  error: unknown,
+  traceId: string,
+  runtime: ForgeTelemetryEnvelope["runtime"],
+  correlation: {
+    requestId?: string;
+    deliveryId?: string;
+    workflow?: ForgeTelemetryEnvelope["workflow"];
+  } = {},
+): Promise<void> {
+  const message = error instanceof Error ? error.message : String(error);
+  const stack = error instanceof Error ? error.stack : undefined;
+  const name = error instanceof Error ? error.name : undefined;
+
+  const envelope: ForgeTelemetryEnvelope = {
+    schemaVersion: "0.1",
+    type: "exception",
+    traceId,
+    requestId: correlation.requestId,
+    environment: resolveEnvironment(),
+    runtime,
+    ...(correlation.workflow ? { workflow: correlation.workflow } : {}),
+    ...(correlation.deliveryId
+      ? { outbox: { deliveryId: correlation.deliveryId } }
+      : {}),
+    exception: { name, message, stack },
+    createdAt: new Date().toISOString(),
+  };
+
+  await insertTelemetryEvent(adapter, envelope);
+}
+
+function resolveEnvironment(): ForgeTelemetryEnvelope["environment"] {
+  const raw = process.env.FORGE_ENV ?? process.env.NODE_ENV ?? "dev";
+  if (raw === "production" || raw === "prod") {
+    return "prod";
+  }
+  if (raw === "test") {
+    return "test";
+  }
+  if (raw === "preview") {
+    return "preview";
+  }
+  return "dev";
+}