@beignet/cli 0.0.43 → 0.0.45

package/src/mcp.ts

@@ -1,5 +1,9 @@
+import { open, realpath } from "node:fs/promises";
 import path from "node:path";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import {
+  McpServer,
+  ResourceTemplate,
+} from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { mapApp, projectAppMap } from "./app-map.js";
@@ -10,6 +14,8 @@ import {
   databaseSchemaDialectChoices,
   databaseSchemaTableChoices,
   doctorFixOperationIds,
+  outboxMessageKindChoices,
+  outboxMessageStatusChoices,
   type ProviderPresetName,
   providerPresetChoices,
 } from "./choices.js";
@@ -54,6 +60,12 @@ import {
   makeUpload,
   makeUseCase,
 } from "./make.js";
+import {
+  defaultOperationalCommandTimeoutMs,
+  defaultOperationalResultMaxBytes,
+  isAppRelativeOperationalModulePath,
+  runIsolatedOperationalCommand,
+} from "./operational-process.js";
 import {
   type AddProviderPresetResult,
   addProviderPreset,
@@ -92,6 +104,8 @@ const makeArtifactChoices = [
 ] as const;
 
 const defaultMcpCheckTimeoutMs = 10 * 60 * 1_000;
+const maxMcpOperationalTimeoutMs = 60 * 60 * 1_000;
+const maxMcpGuidanceBytes = 64 * 1024;
 
 type MakeArtifact = (typeof makeArtifactChoices)[number];
 
@@ -185,6 +199,123 @@ const providerAddInputSchema = {
 
 const providerPresetDescription = providerPresetChoices.join(", ");
 
+const operationalTimeoutSchema = z
+  .number()
+  .int()
+  .min(1_000)
+  .max(maxMcpOperationalTimeoutMs)
+  .optional()
+  .describe(
+    "Maximum operation duration in milliseconds. Defaults to 600000 (10 minutes).",
+  );
+
+const operationalModuleSchema = z
+  .string()
+  .min(1)
+  .refine(isAppRelativeOperationalModulePath, {
+    message: "Registry modules must stay inside the Beignet app directory.",
+  })
+  .optional()
+  .describe("Override the configured app-relative central registry module.");
+
+const taskRunInputSchema = {
+  name: z.string().min(1).describe("Registered task name."),
+  input: z.unknown().optional().describe("Input validated by the task schema."),
+  tenant: z
+    .string()
+    .min(1)
+    .optional()
+    .describe(
+      "Tenant id or slug passed to createTaskContext, separate from task input.",
+    ),
+  module: operationalModuleSchema,
+  timeoutMs: operationalTimeoutSchema,
+};
+
+const scheduleRunInputSchema = {
+  name: z.string().min(1).describe("Registered schedule name."),
+  payload: z
+    .unknown()
+    .optional()
+    .describe("Payload validated by the schedule schema."),
+  runId: z.string().min(1).optional().describe("Provider or app run ID."),
+  attempt: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe("One-based provider attempt number."),
+  scheduledAt: z
+    .string()
+    .min(1)
+    .optional()
+    .describe("Provider scheduled timestamp."),
+  triggeredAt: z
+    .string()
+    .min(1)
+    .optional()
+    .describe("Schedule trigger timestamp."),
+  source: z
+    .string()
+    .min(1)
+    .optional()
+    .describe("Provider or app source label."),
+  module: operationalModuleSchema,
+  timeoutMs: operationalTimeoutSchema,
+};
+
+const outboxInspectInputSchema = z.discriminatedUnion("operation", [
+  z.object({
+    operation: z.literal("list"),
+    status: z.enum(outboxMessageStatusChoices).optional(),
+    kind: z.enum(outboxMessageKindChoices).optional(),
+    name: z.string().min(1).optional(),
+    limit: z.number().int().positive().optional(),
+    module: operationalModuleSchema,
+    timeoutMs: operationalTimeoutSchema,
+  }),
+  z.object({
+    operation: z.literal("show"),
+    id: z.string().min(1),
+    module: operationalModuleSchema,
+    timeoutMs: operationalTimeoutSchema,
+  }),
+]);
+
+const outboxRunInputSchema = z.discriminatedUnion("operation", [
+  z.object({
+    operation: z.literal("drain"),
+    batchSize: z.number().int().positive().optional(),
+    module: operationalModuleSchema,
+    timeoutMs: operationalTimeoutSchema,
+  }),
+  z.object({
+    operation: z.literal("requeue"),
+    id: z.string().min(1),
+    availableAt: z.string().min(1).optional(),
+    resetAttempts: z.boolean().optional(),
+    module: operationalModuleSchema,
+    timeoutMs: operationalTimeoutSchema,
+  }),
+  z.object({
+    operation: z.literal("purge"),
+    before: z.string().min(1).optional(),
+    all: z.boolean().optional(),
+    limit: z.number().int().positive().optional(),
+    dryRun: z.boolean().optional(),
+    module: operationalModuleSchema,
+    timeoutMs: operationalTimeoutSchema,
+  }),
+  z.object({
+    operation: z.literal("prune"),
+    before: z.string().min(1),
+    limit: z.number().int().positive().optional(),
+    dryRun: z.boolean().optional(),
+    module: operationalModuleSchema,
+    timeoutMs: operationalTimeoutSchema,
+  }),
+]);
+
 type MakeToolInput = {
   artifact: MakeArtifact;
   name?: string;
@@ -219,6 +350,17 @@ function jsonResult(value: unknown): McpToolResult {
   };
 }
 
+function operationalJsonResult(value: unknown): McpToolResult {
+  const formatted = JSON.stringify(value, null, 2);
+  const text =
+    Buffer.byteLength(formatted) <= defaultOperationalResultMaxBytes
+      ? formatted
+      : JSON.stringify(value);
+  return {
+    content: [{ type: "text", text }],
+  };
+}
+
 function errorResult(error: unknown): McpToolResult {
   return {
     isError: true,
@@ -350,7 +492,8 @@ async function runProviderAddTool(
 }
 
 /**
- * Build the Beignet MCP server with app-map, validation, and generator tools.
+ * Build the Beignet MCP server with app context, validation, generation, and
+ * operational tools.
  * Every tool resolves against the app directory captured at launch.
  */
 export function buildBeignetMcpServer(options: McpServerOptions): McpServer {
@@ -360,6 +503,80 @@ export function buildBeignetMcpServer(options: McpServerOptions): McpServer {
     version: options.version,
   });
 
+  server.registerResource(
+    "app-guidance",
+    "beignet://app/guidance",
+    {
+      title: "Beignet app guidance",
+      description:
+        "The app-local AGENTS.md instructions for working in this Beignet app.",
+      mimeType: "text/markdown",
+    },
+    async (uri) => ({
+      contents: [
+        {
+          uri: uri.href,
+          mimeType: "text/markdown",
+          text: await readAppGuidance(cwd),
+        },
+      ],
+    }),
+  );
+
+  const featureResourceTemplate = new ResourceTemplate(
+    "beignet://app/features/{feature}",
+    {
+      list: async () => {
+        const result = await mapApp({ cwd, strict: true });
+        return {
+          resources: appMapFeatureNames(result).map((feature) => ({
+            name: `${feature} app map`,
+            title: `Beignet feature: ${feature}`,
+            uri: `beignet://app/features/${encodeURIComponent(feature)}`,
+            description:
+              "Source-backed feature projection with direct relationships and diagnostics.",
+            mimeType: "application/json",
+          })),
+        };
+      },
+      complete: {
+        feature: async (value) => {
+          const result = await mapApp({ cwd, strict: true });
+          return appMapFeatureNames(result).filter((feature) =>
+            feature.startsWith(value),
+          );
+        },
+      },
+    },
+  );
+
+  server.registerResource(
+    "feature-app-map",
+    featureResourceTemplate,
+    {
+      title: "Beignet feature app map",
+      description:
+        "A focused source-backed app-map projection for one feature.",
+      mimeType: "application/json",
+    },
+    async (uri, variables) => {
+      const feature = resourceVariable(variables.feature, "feature");
+      const result = await mapApp({ cwd, strict: true });
+      if (!appMapFeatureNames(result).includes(feature)) {
+        throw new Error(`Unknown Beignet feature "${feature}".`);
+      }
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "application/json",
+            text: JSON.stringify(projectAppMap(result, { feature }), null, 2),
+          },
+        ],
+      };
+    },
+  );
+
   server.registerTool(
     "app_map",
     {
@@ -561,6 +778,171 @@ export function buildBeignetMcpServer(options: McpServerOptions): McpServer {
       ),
   );
 
+  server.registerTool(
+    "task_run",
+    {
+      description:
+        "Run one registered app-owned operational task in an isolated process and return exactly the versioned beignet task run <name> --json report. The task input is schema-validated, output is bounded, and cancellation or timeout stops the complete process tree.",
+      inputSchema: taskRunInputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
+      },
+    },
+    async (input, extra) =>
+      safeToolResult(async () =>
+        operationalJsonResult(
+          await runIsolatedOperationalCommand({
+            cwd,
+            request: {
+              command: "task:run",
+              name: input.name,
+              input: input.input,
+              tenant: input.tenant,
+              modulePath: input.module,
+            },
+            signal: extra.signal,
+            timeoutMs: input.timeoutMs ?? defaultOperationalCommandTimeoutMs,
+          }),
+        ),
+      ),
+  );
+
+  server.registerTool(
+    "schedule_run",
+    {
+      description:
+        "Run one registered app-owned schedule in an isolated process and return exactly the versioned beignet schedule run <name> --json report. Payload and run metadata match the CLI; cancellation or timeout stops the complete process tree.",
+      inputSchema: scheduleRunInputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
+      },
+    },
+    async (input, extra) =>
+      safeToolResult(async () =>
+        operationalJsonResult(
+          await runIsolatedOperationalCommand({
+            cwd,
+            request: {
+              command: "schedule:run",
+              name: input.name,
+              payload: input.payload,
+              id: input.runId,
+              attempt: input.attempt,
+              scheduledAt: input.scheduledAt,
+              triggeredAt: input.triggeredAt,
+              source: input.source,
+              modulePath: input.module,
+            },
+            signal: extra.signal,
+            timeoutMs: input.timeoutMs ?? defaultOperationalCommandTimeoutMs,
+          }),
+        ),
+      ),
+  );
+
+  server.registerTool(
+    "outbox_inspect",
+    {
+      description:
+        "Read outbox messages with list or show and return exactly the matching versioned beignet outbox <operation> --json report. Runs in an isolated process with bounded structured output, cancellation, and a timeout.",
+      inputSchema: outboxInspectInputSchema,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+      },
+    },
+    async (input, extra) =>
+      safeToolResult(async () =>
+        operationalJsonResult(
+          await runIsolatedOperationalCommand({
+            cwd,
+            request:
+              input.operation === "list"
+                ? {
+                    command: "outbox:list",
+                    status: input.status,
+                    kind: input.kind,
+                    name: input.name,
+                    limit: input.limit,
+                    modulePath: input.module,
+                  }
+                : {
+                    command: "outbox:show",
+                    id: input.id,
+                    modulePath: input.module,
+                  },
+            signal: extra.signal,
+            timeoutMs: input.timeoutMs ?? defaultOperationalCommandTimeoutMs,
+          }),
+        ),
+      ),
+  );
+
+  server.registerTool(
+    "outbox_run",
+    {
+      description:
+        "Run a state-changing outbox drain, requeue, purge, or prune operation and return exactly the matching versioned beignet outbox <operation> --json report. Purge and prune support dryRun. Runs in an isolated process with bounded structured output, cancellation, and a timeout.",
+      inputSchema: outboxRunInputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
+      },
+    },
+    async (input, extra) =>
+      safeToolResult(async () => {
+        const request =
+          input.operation === "drain"
+            ? {
+                command: "outbox:drain" as const,
+                batchSize: input.batchSize,
+                modulePath: input.module,
+              }
+            : input.operation === "requeue"
+              ? {
+                  command: "outbox:requeue" as const,
+                  id: input.id,
+                  availableAt: input.availableAt,
+                  resetAttempts: input.resetAttempts,
+                  modulePath: input.module,
+                }
+              : input.operation === "purge"
+                ? {
+                    command: "outbox:purge" as const,
+                    before: input.before,
+                    all: input.all,
+                    limit: input.limit,
+                    dryRun: input.dryRun,
+                    modulePath: input.module,
+                  }
+                : {
+                    command: "outbox:prune" as const,
+                    before: input.before,
+                    limit: input.limit,
+                    dryRun: input.dryRun,
+                    modulePath: input.module,
+                  };
+        return operationalJsonResult(
+          await runIsolatedOperationalCommand({
+            cwd,
+            request,
+            signal: extra.signal,
+            timeoutMs: input.timeoutMs ?? defaultOperationalCommandTimeoutMs,
+          }),
+        );
+      }),
+  );
+
   server.registerTool(
     "routes",
     {
@@ -729,6 +1111,79 @@ export function buildBeignetMcpServer(options: McpServerOptions): McpServer {
   return server;
 }
 
+async function readAppGuidance(cwd: string): Promise<string> {
+  const guidancePath = await resolveAppGuidancePath(cwd);
+  if (!guidancePath) {
+    return "# Beignet app guidance\n\nNo app-local AGENTS.md was found. Use the app_map and explain tools before editing, prefer Beignet generators, and run check after changes.\n";
+  }
+
+  let file: Awaited<ReturnType<typeof open>>;
+  file = await open(guidancePath, "r");
+
+  try {
+    const source = Buffer.alloc(maxMcpGuidanceBytes + 1);
+    let bytesRead = 0;
+    while (bytesRead < source.byteLength) {
+      const chunk = await file.read(
+        source,
+        bytesRead,
+        source.byteLength - bytesRead,
+        bytesRead,
+      );
+      if (chunk.bytesRead === 0) break;
+      bytesRead += chunk.bytesRead;
+    }
+    if (bytesRead <= maxMcpGuidanceBytes) {
+      return source.subarray(0, bytesRead).toString("utf8");
+    }
+    return `${source.subarray(0, maxMcpGuidanceBytes).toString("utf8")}\n\n[Guidance truncated at ${maxMcpGuidanceBytes} bytes. Read AGENTS.md directly for the complete file.]\n`;
+  } finally {
+    await file.close();
+  }
+}
+
+async function resolveAppGuidancePath(
+  cwd: string,
+): Promise<string | undefined> {
+  let guidancePath: string;
+  try {
+    guidancePath = await realpath(path.join(cwd, "AGENTS.md"));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw error;
+  }
+
+  const appPath = await realpath(cwd);
+  const relativePath = path.relative(appPath, guidancePath);
+  if (
+    relativePath === ".." ||
+    relativePath.startsWith(`..${path.sep}`) ||
+    path.isAbsolute(relativePath)
+  ) {
+    throw new Error("App guidance must stay inside the Beignet app directory.");
+  }
+  return guidancePath;
+}
+
+function appMapFeatureNames(
+  result: Awaited<ReturnType<typeof mapApp>>,
+): string[] {
+  return result.nodes
+    .filter((node) => node.kind === "feature")
+    .map((node) => node.name)
+    .sort();
+}
+
+function resourceVariable(
+  value: string | string[] | undefined,
+  name: string,
+): string {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`MCP resource variable "${name}" must be one value.`);
+  }
+  return value;
+}
+
 /**
  * Run the Beignet MCP server over stdio until the client disconnects.
  * Stdout belongs to the transport; diagnostics must go to stderr.

package/src/operational-lifecycle.ts

@@ -0,0 +1,56 @@
+export class OperationalCleanupAfterCompletionError extends Error {
+  readonly operationCompleted = true;
+
+  constructor(operation: string, cleanup: string, cause: unknown) {
+    const cleanupError =
+      cause instanceof Error ? cause : new Error(String(cause));
+    super(
+      `${operation} completed, but ${cleanup} failed: ${cleanupError.message}`,
+      { cause: cleanupError },
+    );
+    this.name = "OperationalCleanupAfterCompletionError";
+  }
+}
+
+export function isOperationalCleanupAfterCompletionError(
+  error: unknown,
+): error is OperationalCleanupAfterCompletionError {
+  return error instanceof OperationalCleanupAfterCompletionError;
+}
+
+export async function runWithOperationalCleanup<Result>(options: {
+  operation: string;
+  cleanupLabel: string;
+  run: () => Promise<Result>;
+  cleanup: () => Promise<void>;
+}): Promise<Result> {
+  let operationFailed = false;
+  let operationError: unknown;
+  let result!: Result;
+
+  try {
+    result = await options.run();
+  } catch (error) {
+    operationFailed = true;
+    operationError = error;
+  }
+
+  let cleanupFailed = false;
+  let cleanupError: unknown;
+  try {
+    await options.cleanup();
+  } catch (error) {
+    cleanupFailed = true;
+    cleanupError = error;
+  }
+
+  if (operationFailed) throw operationError;
+  if (cleanupFailed) {
+    throw new OperationalCleanupAfterCompletionError(
+      options.operation,
+      options.cleanupLabel,
+      cleanupError,
+    );
+  }
+  return result;
+}

package/src/operational-path.ts

@@ -0,0 +1,35 @@
+import { realpath } from "node:fs/promises";
+import path from "node:path";
+
+export function isAppRelativeOperationalModulePath(value: string): boolean {
+  if (path.isAbsolute(value) || path.win32.isAbsolute(value)) return false;
+  const normalized = path.posix.normalize(value.replaceAll("\\", "/"));
+  return normalized !== ".." && !normalized.startsWith("../");
+}
+
+export async function resolveAppOperationalModulePath(
+  cwd: string,
+  modulePath: string,
+): Promise<string> {
+  if (!isAppRelativeOperationalModulePath(modulePath)) {
+    throw operationalModuleOutsideAppError();
+  }
+
+  const appPath = await realpath(cwd);
+  const resolvedModulePath = await realpath(path.resolve(cwd, modulePath));
+  const relativePath = path.relative(appPath, resolvedModulePath);
+  if (
+    relativePath === ".." ||
+    relativePath.startsWith(`..${path.sep}`) ||
+    path.isAbsolute(relativePath)
+  ) {
+    throw operationalModuleOutsideAppError();
+  }
+  return resolvedModulePath;
+}
+
+function operationalModuleOutsideAppError(): Error {
+  return new Error(
+    "Registry modules must stay inside the Beignet app directory.",
+  );
+}