forgeos 0.1.0-alpha.0

package/src/forge/cli/workflow.ts

@@ -0,0 +1,424 @@
+import { nodeFileSystem } from "../compiler/fs/index.ts";
+import { join } from "node:path";
+import { createDiagnostic } from "../compiler/diagnostics/create.ts";
+import {
+  FORGE_RUNTIME_NOT_FOUND,
+  FORGE_WORKFLOW_RUN_NOT_FOUND,
+  FORGE_WORKFLOW_UNKNOWN,
+} from "../compiler/diagnostics/codes.ts";
+import type { TableMapEntry } from "../compiler/data-graph/sql/serialize.ts";
+import { GENERATED_DIR } from "../compiler/emitter/constants.ts";
+import { hashStable } from "../compiler/primitives/hash.ts";
+import { stripDeterministicHeader } from "../compiler/primitives/header.ts";
+import { canonicalJson } from "../compiler/primitives/serialize.ts";
+import type { Diagnostic } from "../compiler/types/diagnostic.ts";
+import type { RuntimeGraph } from "../compiler/types/runtime-graph.ts";
+import type { SqlPlan } from "../compiler/data-graph/sql/types.ts";
+import { createDbAdapter, type CreateDbAdapterOptions } from "../runtime/db/factory.ts";
+import type { DbAdapterKind } from "../runtime/db/adapter.ts";
+import { applyMigrations } from "../runtime/db/migrate.ts";
+import { prepareRuntimeEnvironment } from "../runtime/executor.ts";
+import { cancelWorkflowRun } from "../runtime/workflows/cancel.ts";
+import { createWorkflowRun } from "../runtime/workflows/create-run.ts";
+import {
+  getWorkflowSummary,
+  inspectWorkflowRun,
+  listWorkflowRuns,
+  processWorkflowBatch,
+  runWorkerTick,
+} from "../runtime/workflows/process.ts";
+import { loadWorkflowRegistry } from "../runtime/workflows/registry.ts";
+import { retryWorkflowRun } from "../runtime/workflows/retry-run.ts";
+
+export type WorkflowSubcommand =
+  | "list"
+  | "run"
+  | "inspect"
+  | "process"
+  | "retry"
+  | "cancel";
+
+export interface WorkflowCommandOptions {
+  subcommand: WorkflowSubcommand;
+  workspaceRoot: string;
+  db: DbAdapterKind;
+  databaseUrl?: string;
+  json: boolean;
+  once?: boolean;
+  watch?: boolean;
+  limit?: number;
+  workflowName?: string;
+  runId?: number;
+  stepName?: string;
+  input?: unknown;
+  mock?: boolean;
+}
+
+export interface WorkflowCommandResult {
+  ok: boolean;
+  data?: unknown;
+  diagnostics: Diagnostic[];
+  exitCode: 0 | 1;
+}
+
+function readGeneratedJson<T>(workspaceRoot: string, relative: string): T | null {
+  const absolute = join(workspaceRoot, relative);
+  if (!nodeFileSystem.exists(absolute)) {
+    return null;
+  }
+  const raw = stripDeterministicHeader((nodeFileSystem.readText(absolute) ?? ""));
+  return JSON.parse(raw) as T;
+}
+
+function adapterOptions(options: WorkflowCommandOptions): CreateDbAdapterOptions {
+  return {
+    kind: options.db,
+    workspaceRoot: options.workspaceRoot,
+    databaseUrl: options.databaseUrl,
+  };
+}
+
+async function loadRuntimeArtifacts(workspaceRoot: string): Promise<{
+  runtimeGraph: RuntimeGraph | null;
+  tableMap: Record<string, TableMapEntry>;
+  sqlPlan: SqlPlan | null;
+}> {
+  const runtimeGraph = readGeneratedJson<RuntimeGraph>(
+    workspaceRoot,
+    `${GENERATED_DIR}/runtimeGraph.json`,
+  );
+  const dbJson = readGeneratedJson<{ tableMap: Record<string, TableMapEntry> }>(
+    workspaceRoot,
+    `${GENERATED_DIR}/db.json`,
+  );
+  const sqlPlan = readGeneratedJson<SqlPlan>(
+    workspaceRoot,
+    `${GENERATED_DIR}/sqlPlan.json`,
+  );
+
+  return {
+    runtimeGraph,
+    tableMap: dbJson?.tableMap ?? {},
+    sqlPlan,
+  };
+}
+
+export async function runWorkflowCommand(
+  options: WorkflowCommandOptions,
+): Promise<WorkflowCommandResult> {
+  const { runtimeGraph, tableMap, sqlPlan } = await loadRuntimeArtifacts(
+    options.workspaceRoot,
+  );
+
+  if (!runtimeGraph) {
+    return {
+      ok: false,
+      diagnostics: [
+        createDiagnostic({
+          severity: "error",
+          code: FORGE_RUNTIME_NOT_FOUND,
+          message: `missing ${GENERATED_DIR}/runtimeGraph.json; run forge generate first`,
+        }),
+      ],
+      exitCode: 1,
+    };
+  }
+
+  const { adapter, diagnostics: adapterDiagnostics } = await createDbAdapter(
+    adapterOptions(options),
+  );
+
+  if (!adapter) {
+    return {
+      ok: false,
+      diagnostics: adapterDiagnostics,
+      exitCode: 1,
+    };
+  }
+
+  try {
+    if (sqlPlan) {
+      await applyMigrations(adapter, sqlPlan);
+    }
+
+    await prepareRuntimeEnvironment(options.workspaceRoot, {
+      mock: options.mock ?? false,
+      db: adapter,
+    });
+
+    if (options.subcommand === "list") {
+      const { workflows } = loadWorkflowRegistry(options.workspaceRoot);
+      const runs = await listWorkflowRuns(adapter);
+      const summary = await getWorkflowSummary(adapter);
+      return {
+        ok: true,
+        data: { workflows, runs, summary },
+        diagnostics: [],
+        exitCode: 0,
+      };
+    }
+
+    if (options.subcommand === "run") {
+      if (!options.workflowName) {
+        return {
+          ok: false,
+          diagnostics: [
+            createDiagnostic({
+              severity: "error",
+              code: FORGE_WORKFLOW_UNKNOWN,
+              message: "forge workflow run requires a workflow name",
+            }),
+          ],
+          exitCode: 1,
+        };
+      }
+
+      const { workflows } = loadWorkflowRegistry(options.workspaceRoot);
+      const input = options.input ?? {};
+      const idempotencyKey = `${options.workflowName}:manual:${hashStable(canonicalJson(input))}`;
+
+      const result = await createWorkflowRun(adapter, workflows, {
+        workflowName: options.workflowName,
+        input,
+        triggerType: "manual",
+        idempotencyKey,
+      });
+
+      return {
+        ok: true,
+        data: result,
+        diagnostics: [],
+        exitCode: 0,
+      };
+    }
+
+    if (options.subcommand === "inspect") {
+      if (options.runId === undefined) {
+        return {
+          ok: false,
+          diagnostics: [
+            createDiagnostic({
+              severity: "error",
+              code: FORGE_WORKFLOW_RUN_NOT_FOUND,
+              message: "forge workflow inspect requires a run id",
+            }),
+          ],
+          exitCode: 1,
+        };
+      }
+
+      const inspected = await inspectWorkflowRun(adapter, options.runId);
+      if (!inspected.run) {
+        return {
+          ok: false,
+          diagnostics: [
+            createDiagnostic({
+              severity: "error",
+              code: FORGE_WORKFLOW_RUN_NOT_FOUND,
+              message: `workflow run '${options.runId}' not found`,
+            }),
+          ],
+          exitCode: 1,
+        };
+      }
+
+      return {
+        ok: true,
+        data: inspected,
+        diagnostics: [],
+        exitCode: 0,
+      };
+    }
+
+    if (options.subcommand === "retry") {
+      if (options.runId === undefined) {
+        return {
+          ok: false,
+          diagnostics: [
+            createDiagnostic({
+              severity: "error",
+              code: FORGE_WORKFLOW_RUN_NOT_FOUND,
+              message: "forge workflow retry requires a run id",
+            }),
+          ],
+          exitCode: 1,
+        };
+      }
+
+      const retried = await retryWorkflowRun(adapter, options.runId, options.stepName);
+      if (!retried) {
+        return {
+          ok: false,
+          diagnostics: [
+            createDiagnostic({
+              severity: "error",
+              code: FORGE_WORKFLOW_RUN_NOT_FOUND,
+              message: `workflow run '${options.runId}' not found`,
+            }),
+          ],
+          exitCode: 1,
+        };
+      }
+
+      return {
+        ok: true,
+        data: { runId: options.runId, status: "pending" },
+        diagnostics: [],
+        exitCode: 0,
+      };
+    }
+
+    if (options.subcommand === "cancel") {
+      if (options.runId === undefined) {
+        return {
+          ok: false,
+          diagnostics: [
+            createDiagnostic({
+              severity: "error",
+              code: FORGE_WORKFLOW_RUN_NOT_FOUND,
+              message: "forge workflow cancel requires a run id",
+            }),
+          ],
+          exitCode: 1,
+        };
+      }
+
+      const canceled = await cancelWorkflowRun(adapter, options.runId);
+      if (!canceled) {
+        return {
+          ok: false,
+          diagnostics: [
+            createDiagnostic({
+              severity: "error",
+              code: FORGE_WORKFLOW_RUN_NOT_FOUND,
+              message: `workflow run '${options.runId}' not found or not cancelable`,
+            }),
+          ],
+          exitCode: 1,
+        };
+      }
+
+      return {
+        ok: true,
+        data: { runId: options.runId, status: "canceled" },
+        diagnostics: [],
+        exitCode: 0,
+      };
+    }
+
+    if (options.subcommand === "process") {
+      const runBatch = async () => {
+        if (options.once || options.watch) {
+          return runWorkerTick(
+            adapter,
+            options.workspaceRoot,
+            tableMap,
+            runtimeGraph.entries,
+            {
+              limit: options.limit ?? 10,
+              mock: options.mock ?? false,
+            },
+          );
+        }
+        const workflowBatch = await processWorkflowBatch(
+          adapter,
+          options.workspaceRoot,
+          tableMap,
+          {
+            limit: options.limit ?? 10,
+            mock: options.mock ?? false,
+          },
+        );
+        return { workflows: { started: 0, skipped: 0 }, outbox: null, workflowBatch };
+      };
+
+      if (options.watch) {
+        let running = true;
+        const intervalMs = 2_000;
+
+        const shutdown = () => {
+          running = false;
+        };
+        process.once("SIGINT", shutdown);
+        process.once("SIGTERM", shutdown);
+
+        while (running) {
+          const batch = await runBatch();
+          if (!options.json) {
+            const wf = batch.workflowBatch;
+            process.stdout.write(
+              `workflows completed=${wf.completed} failed=${wf.failed} dead=${wf.dead} claimed=${wf.claimed}\n`,
+            );
+          }
+          await new Promise((resolve) => setTimeout(resolve, intervalMs));
+        }
+
+        return { ok: true, data: { watch: true }, diagnostics: [], exitCode: 0 };
+      }
+
+      const batch = await runBatch();
+      return {
+        ok: true,
+        data: batch,
+        diagnostics: [],
+        exitCode: 0,
+      };
+    }
+
+    return {
+      ok: false,
+      diagnostics: [],
+      exitCode: 1,
+    };
+  } finally {
+    await adapter.close();
+  }
+}
+
+export function formatWorkflowJson(result: WorkflowCommandResult): string {
+  return `${JSON.stringify({
+    ok: result.ok,
+    data: result.data,
+    diagnostics: result.diagnostics,
+    exitCode: result.exitCode,
+  })}\n`;
+}
+
+export function formatWorkflowHuman(
+  subcommand: WorkflowSubcommand,
+  result: WorkflowCommandResult,
+): string {
+  if (!result.ok) {
+    return result.diagnostics
+      .map((diagnostic) => `error ${diagnostic.code}: ${diagnostic.message}`)
+      .join("\n")
+      .concat("\n");
+  }
+
+  if (subcommand === "run") {
+    const data = result.data as { created: boolean; run: { id: number } };
+    return `run ${data.run.id} ${data.created ? "created" : "existing"}\n`;
+  }
+
+  if (subcommand === "retry" || subcommand === "cancel") {
+    return `${subcommand} run ${(result.data as { runId: number }).runId}\n`;
+  }
+
+  if (subcommand === "process") {
+    const batch = result.data as {
+      workflowBatch?: {
+        claimed: number;
+        completed: number;
+        failed: number;
+        dead: number;
+      };
+    };
+    const wf = batch.workflowBatch;
+    if (!wf) {
+      return "processed workflow batch\n";
+    }
+    return `claimed=${wf.claimed} completed=${wf.completed} failed=${wf.failed} dead=${wf.dead}\n`;
+  }
+
+  return `${JSON.stringify(result.data, null, 2)}\n`;
+}

package/src/forge/compiler/action-subscriptions/build.ts

@@ -0,0 +1,116 @@
+import { createDiagnostic } from "../diagnostics/create.ts";
+import { FORGE_ACTION_EVENT_UNPARSEABLE } from "../diagnostics/codes.ts";
+import { GENERATOR_VERSION } from "../emitter/constants.ts";
+import { hashStable } from "../primitives/hash.ts";
+import { canonicalJson } from "../primitives/serialize.ts";
+import type { AppGraph } from "../types/app-graph.ts";
+import type {
+  ActionSubscription,
+  ActionSubscriptions,
+} from "../types/action-subscriptions.ts";
+import {
+  ACTION_SUBSCRIPTIONS_ANALYZER_VERSION,
+  ACTION_SUBSCRIPTIONS_SCHEMA_VERSION,
+} from "./constants.ts";
+import { parseActionEventFromSlice } from "./parse.ts";
+
+function stableSortSubscriptions(
+  subscriptions: ActionSubscription[],
+): ActionSubscription[] {
+  return [...subscriptions].sort((a, b) => {
+    if (a.eventType !== b.eventType) {
+      return a.eventType < b.eventType ? -1 : 1;
+    }
+    if (a.actionName !== b.actionName) {
+      return a.actionName < b.actionName ? -1 : 1;
+    }
+    if (a.file !== b.file) {
+      return a.file < b.file ? -1 : 1;
+    }
+    return a.symbolId < b.symbolId ? -1 : a.symbolId > b.symbolId ? 1 : 0;
+  });
+}
+
+function buildByEvent(
+  subscriptions: ActionSubscription[],
+): Record<string, ActionSubscription[]> {
+  const byEvent: Record<string, ActionSubscription[]> = {};
+
+  for (const subscription of subscriptions) {
+    const list = byEvent[subscription.eventType] ?? [];
+    list.push(subscription);
+    byEvent[subscription.eventType] = list;
+  }
+
+  for (const eventType of Object.keys(byEvent).sort()) {
+    byEvent[eventType] = stableSortSubscriptions(byEvent[eventType]!);
+  }
+
+  return byEvent;
+}
+
+export function buildActionSubscriptions(appGraph: AppGraph): ActionSubscriptions {
+  const subscriptions: ActionSubscription[] = [];
+  const diagnostics: ActionSubscriptions["diagnostics"] = [];
+
+  for (const symbol of appGraph.symbols) {
+    if (symbol.kind !== "action") {
+      continue;
+    }
+
+    const sourceSlice =
+      typeof symbol.meta.sourceSlice === "string" ? symbol.meta.sourceSlice : "";
+
+    if (sourceSlice.length === 0) {
+      continue;
+    }
+
+    const eventType = parseActionEventFromSlice(sourceSlice);
+    if (eventType === null) {
+      if (/event\s*:/.test(sourceSlice)) {
+        diagnostics.push(
+          createDiagnostic({
+            severity: "warning",
+            code: FORGE_ACTION_EVENT_UNPARSEABLE,
+            message: `cannot parse event subscription for action '${symbol.qualifiedName}'`,
+            file: symbol.file,
+            span: symbol.span,
+          }),
+        );
+      }
+      continue;
+    }
+
+    subscriptions.push({
+      eventType,
+      actionName: symbol.name,
+      exportName: symbol.name,
+      file: symbol.file,
+      symbolId: symbol.id,
+    });
+  }
+
+  const sorted = stableSortSubscriptions(subscriptions);
+
+  return {
+    schemaVersion: ACTION_SUBSCRIPTIONS_SCHEMA_VERSION,
+    generatorVersion: GENERATOR_VERSION,
+    analyzerVersion: ACTION_SUBSCRIPTIONS_ANALYZER_VERSION,
+    inputHash: hashStable(
+      canonicalJson({
+        appInputHash: appGraph.inputHash,
+        analyzerVersion: ACTION_SUBSCRIPTIONS_ANALYZER_VERSION,
+      }),
+    ),
+    subscriptions: sorted,
+    byEvent: buildByEvent(sorted),
+    diagnostics: 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;
+    }),
+  };
+}

package/src/forge/compiler/action-subscriptions/constants.ts

@@ -0,0 +1,2 @@
+export const ACTION_SUBSCRIPTIONS_SCHEMA_VERSION = "0.1.0";
+export const ACTION_SUBSCRIPTIONS_ANALYZER_VERSION = "0.1.0";

package/src/forge/compiler/action-subscriptions/index.ts

@@ -0,0 +1,6 @@
+export { buildActionSubscriptions } from "./build.ts";
+export { parseActionEventFromSlice } from "./parse.ts";
+export {
+  ACTION_SUBSCRIPTIONS_ANALYZER_VERSION,
+  ACTION_SUBSCRIPTIONS_SCHEMA_VERSION,
+} from "./constants.ts";

package/src/forge/compiler/action-subscriptions/parse.ts

@@ -0,0 +1,6 @@
+const EVENT_LITERAL_PATTERN = /event\s*:\s*["']([^"']+)["']/;
+
+export function parseActionEventFromSlice(sourceSlice: string): string | null {
+  const match = sourceSlice.match(EVENT_LITERAL_PATTERN);
+  return match?.[1] ?? null;
+}