@beignet/cli 0.0.1 → 0.0.4

package/src/outbox.ts

@@ -0,0 +1,249 @@
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import type {
+  DrainOutboxOptions,
+  DrainOutboxResult,
+  OutboxRegistry,
+} from "@beignet/core/outbox";
+import { createJiti } from "jiti";
+import { loadBeignetConfig, normalizePath } from "./config.js";
+
+/**
+ * Options for running one bounded outbox drain pass.
+ */
+export type RunOutboxDrainOptions = {
+  cwd?: string;
+  modulePath?: string;
+  batchSize?: number;
+};
+
+/**
+ * Result returned by `beignet outbox drain`.
+ */
+export type RunOutboxDrainResult = {
+  schemaVersion: 1;
+  cwd: string;
+  modulePath: string;
+  result: DrainOutboxResult;
+  durationMs: number;
+};
+
+type OutboxDrainLogger = {
+  error(message: string, meta?: Record<string, unknown>): unknown;
+};
+
+type OutboxDrainInstrumentation = {
+  record(event: {
+    type: "custom";
+    watcher: string;
+    name: string;
+    label: string;
+    summary: string;
+    requestId?: string;
+    traceId?: string;
+    details: unknown;
+  }): unknown;
+};
+
+type OutboxDrainPorts = {
+  outbox: DrainOutboxOptions["outbox"];
+  eventBus?: DrainOutboxOptions["eventBus"];
+  jobs?: DrainOutboxOptions["jobs"];
+  logger?: OutboxDrainLogger;
+  devtools?: OutboxDrainInstrumentation;
+  instrumentation?: OutboxDrainInstrumentation;
+};
+
+type OutboxDrainContext = {
+  requestId?: string;
+  traceId?: string;
+  ports: OutboxDrainPorts;
+};
+
+type OutboxDrainContextArgs = {
+  registry: OutboxRegistry;
+  batchSize?: number;
+};
+
+type OutboxModule = {
+  outboxRegistry?: unknown;
+  createOutboxDrainContext?: (args: OutboxDrainContextArgs) => unknown;
+  stopOutboxDrainContext?: (
+    ctx: OutboxDrainContext,
+    args: OutboxDrainContextArgs,
+  ) => unknown;
+};
+
+/**
+ * Run one app-owned outbox drain pass from the app's outbox registry.
+ */
+export async function runOutboxDrain(
+  options: RunOutboxDrainOptions = {},
+): Promise<RunOutboxDrainResult> {
+  const cwd = path.resolve(options.cwd ?? process.cwd());
+  const config = await loadBeignetConfig(cwd);
+  const modulePath = normalizePath(options.modulePath ?? config.paths.outbox);
+  const batchSize = options.batchSize;
+  if (batchSize !== undefined) assertPositiveInteger("batchSize", batchSize);
+
+  const startedAt = performance.now();
+  const outboxModule = await loadOutboxModule(cwd, modulePath);
+  const registry = assertOutboxRegistry(
+    outboxModule.outboxRegistry,
+    modulePath,
+  );
+  const contextArgs = { registry, batchSize };
+  const rawContext = outboxModule.createOutboxDrainContext
+    ? await outboxModule.createOutboxDrainContext(contextArgs)
+    : undefined;
+  const ctx = assertOutboxDrainContext(rawContext, modulePath);
+
+  try {
+    // Loaded lazily so CLI commands that never touch the app runtime, such as
+    // `beignet lint`, work without a built @beignet/core.
+    const { drainOutbox } = await import("@beignet/core/outbox");
+    const result = await drainOutbox({
+      outbox: ctx.ports.outbox,
+      registry,
+      eventBus: ctx.ports.eventBus,
+      jobs: ctx.ports.jobs,
+      batchSize,
+      instrumentation: ctx.ports.instrumentation ?? ctx.ports.devtools,
+      instrumentationContext: {
+        requestId: ctx.requestId,
+        traceId: ctx.traceId,
+      },
+      onError(error, message) {
+        ctx.ports.logger?.error("Outbox delivery failed", {
+          error,
+          outboxMessageId: message.id,
+          kind: message.kind,
+          name: message.name,
+          attempts: message.attempts,
+        });
+      },
+    });
+
+    await recordOutboxDrain(ctx, result);
+
+    return {
+      schemaVersion: 1,
+      cwd,
+      modulePath,
+      result,
+      durationMs: Math.round(performance.now() - startedAt),
+    };
+  } finally {
+    await outboxModule.stopOutboxDrainContext?.(ctx, contextArgs);
+  }
+}
+
+async function loadOutboxModule(
+  cwd: string,
+  modulePath: string,
+): Promise<OutboxModule> {
+  const absolutePath = path.join(cwd, modulePath);
+  try {
+    await stat(absolutePath);
+  } catch {
+    throw new Error(
+      `Could not find app outbox registry at ${modulePath}. Create server/outbox.ts or configure paths.outbox in beignet.config.ts.`,
+    );
+  }
+
+  const tsconfigPath = path.join(cwd, "tsconfig.json");
+  const jiti = createJiti(absolutePath, {
+    tsconfigPaths: (await fileExists(tsconfigPath)) ? tsconfigPath : false,
+  });
+
+  return (await jiti.import(absolutePath)) as OutboxModule;
+}
+
+function assertOutboxRegistry(
+  registry: unknown,
+  modulePath: string,
+): OutboxRegistry {
+  if (!isRecord(registry)) {
+    throw new Error(`${modulePath} must export an outboxRegistry.`);
+  }
+
+  const events = registry.events;
+  const jobs = registry.jobs;
+  if (!(events instanceof Map) || !(jobs instanceof Map)) {
+    throw new Error(
+      `${modulePath} outboxRegistry must be created with defineOutboxRegistry(...).`,
+    );
+  }
+
+  return { events, jobs } as unknown as OutboxRegistry;
+}
+
+function assertOutboxDrainContext(
+  ctx: unknown,
+  modulePath: string,
+): OutboxDrainContext {
+  if (!isRecord(ctx) || !isRecord(ctx.ports)) {
+    throw new Error(
+      `${modulePath} must export createOutboxDrainContext that returns an app context with ports.outbox.`,
+    );
+  }
+
+  if (!isOutboxPort(ctx.ports.outbox)) {
+    throw new Error(
+      `${modulePath} createOutboxDrainContext must return ports.outbox.`,
+    );
+  }
+
+  return ctx as OutboxDrainContext;
+}
+
+function isOutboxPort(value: unknown): value is DrainOutboxOptions["outbox"] {
+  return (
+    isRecord(value) &&
+    typeof value.enqueue === "function" &&
+    typeof value.claimBatch === "function" &&
+    typeof value.markDelivered === "function" &&
+    typeof value.markFailed === "function"
+  );
+}
+
+async function recordOutboxDrain(
+  ctx: OutboxDrainContext,
+  result: DrainOutboxResult,
+): Promise<void> {
+  try {
+    await (ctx.ports.instrumentation ?? ctx.ports.devtools)?.record({
+      type: "custom",
+      watcher: "outbox",
+      name: "outbox.drain",
+      label: "Outbox drain",
+      summary: `${result.delivered} delivered, ${result.retried} retried, ${result.deadLettered} dead-lettered`,
+      requestId: ctx.requestId,
+      traceId: ctx.traceId,
+      details: result,
+    });
+  } catch (error) {
+    ctx.ports.logger?.error("Outbox drain instrumentation recording failed", {
+      error,
+    });
+  }
+}
+
+function assertPositiveInteger(name: string, value: number): void {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error(`${name} must be a positive integer.`);
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await readFile(filePath, "utf8");
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/schedule.ts

@@ -0,0 +1,272 @@
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import type {
+  ScheduleDef,
+  ScheduleInstrumentation,
+  ScheduleRunOptions,
+  StandardSchema,
+} from "@beignet/core/schedules";
+import { createJiti } from "jiti";
+import { loadBeignetConfig, normalizePath } from "./config.js";
+
+/**
+ * Options for running one app-owned schedule.
+ */
+export type RunAppScheduleOptions = {
+  name: string;
+  cwd?: string;
+  modulePath?: string;
+  payload?: string | Record<string, unknown>;
+  id?: string;
+  attempt?: number;
+  scheduledAt?: string;
+  triggeredAt?: string;
+  source?: string;
+};
+
+/**
+ * Result returned by `beignet schedule run`.
+ */
+export type RunAppScheduleResult = {
+  schemaVersion: 1;
+  name: string;
+  cwd: string;
+  modulePath: string;
+  run: {
+    id?: string;
+    attempt?: number;
+    scheduledAt?: string;
+    triggeredAt?: string;
+    source: string;
+  };
+  durationMs: number;
+};
+
+type AnyScheduleDef = ScheduleDef<string, StandardSchema, unknown>;
+
+type ScheduleLogger = {
+  error(message: string, meta?: Record<string, unknown>): unknown;
+  warn?(message: string, meta?: Record<string, unknown>): unknown;
+};
+
+type ScheduleContext = {
+  requestId?: string;
+  traceId?: string;
+  ports?: {
+    logger?: ScheduleLogger;
+    devtools?: ScheduleInstrumentation;
+  };
+};
+
+type ScheduleContextArgs = {
+  schedule: AnyScheduleDef;
+  scheduleName: string;
+  run: ScheduleRunOptions<unknown>;
+};
+
+type ScheduleModule = {
+  schedules?: readonly unknown[];
+  createScheduleContext?: (args: ScheduleContextArgs) => unknown;
+  stopScheduleContext?: (ctx: unknown, args: ScheduleContextArgs) => unknown;
+};
+
+/**
+ * Run an app-owned schedule from the app's schedule registry.
+ */
+export async function runAppSchedule(
+  options: RunAppScheduleOptions,
+): Promise<RunAppScheduleResult> {
+  const cwd = path.resolve(options.cwd ?? process.cwd());
+  const config = await loadBeignetConfig(cwd);
+  const modulePath = normalizePath(
+    options.modulePath ?? config.paths.schedules,
+  );
+  const runOptions = buildScheduleRunOptions(options);
+  const startedAt = performance.now();
+  const scheduleModule = await loadScheduleModule(cwd, modulePath);
+  const schedule = findSchedule(
+    scheduleModule.schedules,
+    options.name,
+    modulePath,
+  );
+  const contextArgs = {
+    schedule,
+    scheduleName: schedule.name,
+    run: runOptions,
+  };
+  const ctx = scheduleModule.createScheduleContext
+    ? await scheduleModule.createScheduleContext(contextArgs)
+    : {};
+  const scheduleContext = toScheduleContext(ctx);
+
+  try {
+    // Loaded lazily so CLI commands that never touch the app runtime, such as
+    // `beignet lint`, work without a built @beignet/core.
+    const { createInlineScheduleRunner } = await import(
+      "@beignet/core/schedules"
+    );
+    const runner = createInlineScheduleRunner<unknown>({
+      ctx,
+      instrumentation: scheduleContext.ports?.devtools,
+      instrumentationContext: {
+        requestId: scheduleContext.requestId,
+        traceId: scheduleContext.traceId,
+      },
+      onError({ error }) {
+        scheduleContext.ports?.logger?.error("Schedule failed", {
+          error,
+          scheduleName: schedule.name,
+        });
+      },
+      onHookError({ error, hook }) {
+        scheduleContext.ports?.logger?.warn?.(
+          "Schedule lifecycle hook failed",
+          {
+            error,
+            hook,
+            scheduleName: schedule.name,
+          },
+        );
+      },
+    });
+
+    await runner.run(schedule, runOptions);
+
+    return {
+      schemaVersion: 1,
+      name: schedule.name,
+      cwd,
+      modulePath,
+      run: {
+        id: runOptions.id,
+        attempt: runOptions.attempt,
+        scheduledAt: stringifyDateInput(runOptions.scheduledAt),
+        triggeredAt: stringifyDateInput(runOptions.triggeredAt),
+        source: runOptions.source ?? "beignet-cli",
+      },
+      durationMs: Math.round(performance.now() - startedAt),
+    };
+  } finally {
+    await scheduleModule.stopScheduleContext?.(ctx, contextArgs);
+  }
+}
+
+async function loadScheduleModule(
+  cwd: string,
+  modulePath: string,
+): Promise<ScheduleModule> {
+  const absolutePath = path.join(cwd, modulePath);
+  try {
+    await stat(absolutePath);
+  } catch {
+    throw new Error(
+      `Could not find app schedule registry at ${modulePath}. Create server/schedules.ts or configure paths.schedules in beignet.config.ts.`,
+    );
+  }
+
+  const tsconfigPath = path.join(cwd, "tsconfig.json");
+  const jiti = createJiti(absolutePath, {
+    tsconfigPaths: (await fileExists(tsconfigPath)) ? tsconfigPath : false,
+  });
+
+  return (await jiti.import(absolutePath)) as ScheduleModule;
+}
+
+function buildScheduleRunOptions(
+  options: RunAppScheduleOptions,
+): ScheduleRunOptions<unknown> {
+  const runOptions: ScheduleRunOptions<unknown> = {
+    source: options.source ?? "beignet-cli",
+    triggeredAt: options.triggeredAt ?? new Date().toISOString(),
+  };
+
+  if (options.payload !== undefined) {
+    runOptions.payload = parseSchedulePayloadFlag(options.payload);
+  }
+  if (options.id !== undefined) runOptions.id = options.id;
+  if (options.attempt !== undefined) runOptions.attempt = options.attempt;
+  if (options.scheduledAt !== undefined)
+    runOptions.scheduledAt = options.scheduledAt;
+
+  return runOptions;
+}
+
+function parseSchedulePayloadFlag(
+  input: NonNullable<RunAppScheduleOptions["payload"]>,
+): unknown {
+  if (typeof input !== "string") return input;
+
+  try {
+    return JSON.parse(input) as unknown;
+  } catch (error) {
+    throw new Error(
+      `Invalid --payload JSON: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}
+
+function findSchedule(
+  schedules: readonly unknown[] | undefined,
+  name: string,
+  modulePath: string,
+): AnyScheduleDef {
+  if (!schedules) {
+    throw new Error(
+      `Schedule registry ${modulePath} must export a schedules array.`,
+    );
+  }
+
+  const schedule = schedules.find(
+    (candidate): candidate is AnyScheduleDef =>
+      typeof candidate === "object" &&
+      candidate !== null &&
+      (candidate as AnyScheduleDef).kind === "schedule" &&
+      (candidate as AnyScheduleDef).name === name &&
+      typeof (candidate as AnyScheduleDef).handle === "function",
+  );
+
+  if (!schedule) {
+    const available = schedules
+      .filter(
+        (candidate): candidate is AnyScheduleDef =>
+          typeof candidate === "object" &&
+          candidate !== null &&
+          (candidate as AnyScheduleDef).kind === "schedule" &&
+          typeof (candidate as AnyScheduleDef).name === "string",
+      )
+      .map((candidate) => candidate.name)
+      .sort();
+    throw new Error(
+      available.length > 0
+        ? `Unknown schedule "${name}". Available schedules: ${available.join(", ")}.`
+        : `Unknown schedule "${name}". No schedules were registered in ${modulePath}.`,
+    );
+  }
+
+  return schedule;
+}
+
+function toScheduleContext(ctx: unknown): ScheduleContext {
+  return isRecord(ctx) ? (ctx as ScheduleContext) : {};
+}
+
+function stringifyDateInput(
+  value: ScheduleRunOptions<unknown>["scheduledAt"],
+): string | undefined {
+  if (value === undefined) return undefined;
+  if (value instanceof Date) return value.toISOString();
+  return String(value);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await readFile(filePath, "utf8");
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/task.ts

@@ -0,0 +1,169 @@
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import type { TaskDef } from "@beignet/core/tasks";
+import { createJiti } from "jiti";
+import { loadBeignetConfig, normalizePath } from "./config.js";
+
+/**
+ * Options for running an app-owned operational task.
+ */
+export type RunAppTaskOptions = {
+  name: string;
+  cwd?: string;
+  input?: string | Record<string, unknown>;
+  modulePath?: string;
+};
+
+/**
+ * Result returned by `beignet task run`.
+ */
+export type RunAppTaskResult = {
+  schemaVersion: 1;
+  name: string;
+  cwd: string;
+  modulePath: string;
+  input: unknown;
+  output: unknown;
+  durationMs: number;
+};
+
+type TaskContextArgs = {
+  task: TaskDef;
+  taskName: string;
+  input: unknown;
+};
+
+type TaskModule = {
+  tasks?: readonly unknown[];
+  createTaskContext?: (args: TaskContextArgs) => unknown;
+  stopTaskContext?: (ctx: unknown, args: TaskContextArgs) => unknown;
+};
+
+/**
+ * Run an app-owned operational task from the app's task registry.
+ */
+export async function runAppTask(
+  options: RunAppTaskOptions,
+): Promise<RunAppTaskResult> {
+  const cwd = path.resolve(options.cwd ?? process.cwd());
+  const config = await loadBeignetConfig(cwd);
+  const modulePath = normalizePath(options.modulePath ?? config.paths.tasks);
+  const rawInput = parseTaskInputFlag(options.input);
+  const startedAt = performance.now();
+  const taskModule = await loadTaskModule(cwd, modulePath);
+  const task = findTask(taskModule.tasks, options.name, modulePath);
+  // Loaded lazily so CLI commands that never touch the app runtime, such as
+  // `beignet lint`, work without a built @beignet/core.
+  const { parseTaskInput } = await import("@beignet/core/tasks");
+  const parsedInput = await parseTaskInput(task, rawInput);
+  const contextArgs = {
+    task,
+    taskName: task.name,
+    input: parsedInput,
+  };
+  const ctx = taskModule.createTaskContext
+    ? await taskModule.createTaskContext(contextArgs)
+    : {};
+
+  try {
+    const output = await task.handle({
+      task,
+      input: parsedInput,
+      ctx,
+    });
+
+    return {
+      schemaVersion: 1,
+      name: task.name,
+      cwd,
+      modulePath,
+      input: parsedInput,
+      output,
+      durationMs: Math.round(performance.now() - startedAt),
+    };
+  } finally {
+    await taskModule.stopTaskContext?.(ctx, contextArgs);
+  }
+}
+
+function parseTaskInputFlag(input: RunAppTaskOptions["input"]): unknown {
+  if (input === undefined) return {};
+  if (typeof input !== "string") return input;
+
+  try {
+    return JSON.parse(input) as unknown;
+  } catch (error) {
+    throw new Error(
+      `Invalid --input JSON: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}
+
+async function loadTaskModule(
+  cwd: string,
+  modulePath: string,
+): Promise<TaskModule> {
+  const absolutePath = path.join(cwd, modulePath);
+  try {
+    await stat(absolutePath);
+  } catch {
+    throw new Error(
+      `Could not find app task registry at ${modulePath}. Create it with beignet make task <feature>/<name> or configure paths.tasks in beignet.config.ts.`,
+    );
+  }
+
+  const tsconfigPath = path.join(cwd, "tsconfig.json");
+  const jiti = createJiti(absolutePath, {
+    tsconfigPaths: (await fileExists(tsconfigPath)) ? tsconfigPath : false,
+  });
+
+  return (await jiti.import(absolutePath)) as TaskModule;
+}
+
+function findTask(
+  tasks: readonly unknown[] | undefined,
+  name: string,
+  modulePath: string,
+): TaskDef {
+  if (!tasks) {
+    throw new Error(`Task registry ${modulePath} must export a tasks array.`);
+  }
+
+  const task = tasks.find(
+    (candidate): candidate is TaskDef =>
+      typeof candidate === "object" &&
+      candidate !== null &&
+      (candidate as TaskDef).kind === "task" &&
+      (candidate as TaskDef).name === name &&
+      typeof (candidate as TaskDef).handle === "function",
+  );
+
+  if (!task) {
+    const available = tasks
+      .filter(
+        (candidate): candidate is TaskDef =>
+          typeof candidate === "object" &&
+          candidate !== null &&
+          (candidate as TaskDef).kind === "task" &&
+          typeof (candidate as TaskDef).name === "string",
+      )
+      .map((candidate) => candidate.name)
+      .sort();
+    throw new Error(
+      available.length > 0
+        ? `Unknown task "${name}". Available tasks: ${available.join(", ")}.`
+        : `Unknown task "${name}". No tasks were registered in ${modulePath}.`,
+    );
+  }
+
+  return task;
+}
+
+async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await readFile(filePath, "utf8");
+    return true;
+  } catch {
+    return false;
+  }
+}