swallowkit 1.0.0-beta.19 → 1.0.0-beta.20

package/src/machine/index.ts

@@ -0,0 +1,173 @@
+import { Command, CommanderError } from "commander";
+import { createModelOperation } from "../core/operations/create-model";
+import { runMachineScaffoldOperation } from "../core/operations/scaffold-machine";
+import { loadProjectManifest } from "../core/project/manifest";
+import { validateProject } from "../core/project/validation";
+import { MachineErrorResponse, MachineResponse, MachineSuccessResponse } from "./contracts";
+import { MachineCommandError, toMachineError } from "./errors";
+
+function writeMachineResponse<TData>(response: MachineResponse<TData>): void {
+  process.stdout.write(`${JSON.stringify(response, null, 2)}\n`);
+}
+
+function writeMachineSuccess<TData>(command: string, data: TData): void {
+  const response: MachineSuccessResponse<TData> = {
+    ok: true,
+    command,
+    data,
+  };
+  writeMachineResponse(response);
+}
+
+function writeMachineError(command: string, error: unknown): void {
+  const response: MachineErrorResponse = {
+    ok: false,
+    command,
+    error: toMachineError(error),
+  };
+  writeMachineResponse(response);
+}
+
+async function handleMachineAction<TData>(
+  command: string,
+  action: () => Promise<TData>
+): Promise<void> {
+  try {
+    writeMachineSuccess(command, await action());
+  } catch (error) {
+    writeMachineError(command, error);
+    process.exitCode = 1;
+  }
+}
+
+function createMachineProgram(): Command {
+  const program = new Command();
+  program
+    .name("swallowkit machine")
+    .description("SwallowKit machine-readable CLI for AI and MCP integrations")
+    .showHelpAfterError(false)
+    .configureOutput({
+      writeErr: () => undefined,
+      writeOut: () => undefined,
+    });
+
+  const inspect = new Command("inspect");
+  inspect
+    .command("project")
+    .description("Inspect SwallowKit project metadata")
+    .action(async () => {
+      await handleMachineAction("inspect-project", async () => {
+        const loaded = await loadProjectManifest();
+        return {
+          manifestSource: loaded.source,
+          diagnostics: loaded.diagnostics,
+          manifest: loaded.manifest,
+        };
+      });
+    });
+
+  inspect
+    .command("entities")
+    .description("Inspect SwallowKit entities")
+    .action(async () => {
+      await handleMachineAction("inspect-entities", async () => {
+        const loaded = await loadProjectManifest();
+        return {
+          manifestSource: loaded.source,
+          diagnostics: loaded.diagnostics,
+          entities: loaded.manifest.entities,
+        };
+      });
+    });
+
+  inspect
+    .command("routes")
+    .description("Inspect SwallowKit routes")
+    .action(async () => {
+      await handleMachineAction("inspect-routes", async () => {
+        const loaded = await loadProjectManifest();
+        return {
+          manifestSource: loaded.source,
+          diagnostics: loaded.diagnostics,
+          routes: loaded.manifest.routes,
+        };
+      });
+    });
+
+  const validate = new Command("validate");
+  validate
+    .command("project")
+    .description("Validate SwallowKit project metadata and conventions")
+    .action(async () => {
+      await handleMachineAction("validate-project", async () => validateProject());
+    });
+
+  const generate = new Command("generate");
+  generate
+    .command("model")
+    .description("Generate model templates with deterministic JSON output")
+    .argument("<names...>", "Model names to generate")
+    .option("--models-dir <dir>", "Models directory", "shared/models")
+    .option("--connector <name>", "Associate the models with a configured connector")
+    .option("--overwrite <mode>", "Overwrite policy: always | never", "never")
+    .action(async (names: string[], options: { modelsDir?: string; connector?: string; overwrite?: string }) => {
+      await handleMachineAction("generate-model", async () => {
+        if (options.overwrite !== "always" && options.overwrite !== "never") {
+          throw new MachineCommandError(
+            "invalid-overwrite-mode",
+            `Unsupported overwrite mode: ${options.overwrite}. Use "always" or "never".`
+          );
+        }
+
+        return createModelOperation({
+          names,
+          modelsDir: options.modelsDir,
+          connector: options.connector,
+          overwriteMode: options.overwrite,
+        });
+      });
+    });
+
+  generate
+    .command("scaffold")
+    .description("Generate scaffold artifacts with deterministic JSON output")
+    .argument("<model>", "Model file or model name")
+    .option("--functions-dir <dir>", "Functions directory", "functions")
+    .option("--api-dir <dir>", "API routes directory", "app/api")
+    .option("--api-only", "Generate only API artifacts", false)
+    .action(async (model: string, options: { functionsDir?: string; apiDir?: string; apiOnly?: boolean }) => {
+      await handleMachineAction("generate-scaffold", async () => runMachineScaffoldOperation({
+        model,
+        functionsDir: options.functionsDir,
+        apiDir: options.apiDir,
+        apiOnly: options.apiOnly,
+      }));
+    });
+
+  program.addCommand(inspect);
+  program.addCommand(validate);
+  program.addCommand(generate);
+  return program;
+}
+
+export function isMachineCommand(argv: string[]): boolean {
+  return argv[2] === "machine";
+}
+
+export async function runMachineCli(argv: string[] = process.argv): Promise<void> {
+  const program = createMachineProgram();
+  program.exitOverride();
+
+  try {
+    await program.parseAsync(argv.slice(3), { from: "user" });
+  } catch (error) {
+    if (error instanceof CommanderError) {
+      writeMachineError("machine-parse", new MachineCommandError("invalid-command", error.message));
+      process.exitCode = Number.isFinite(error.exitCode) ? error.exitCode : 1;
+      return;
+    }
+
+    writeMachineError("machine-parse", error);
+    process.exitCode = 1;
+  }
+}

package/src/mcp/index.ts

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+
+import * as path from "path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio";
+import * as z from "zod/v4";
+import type { MachineResponse } from "../machine/contracts";
+
+interface MachineSuccessPayload<TData> {
+  ok: true;
+  command: string;
+  data: TData;
+}
+
+type MachineCliRunner = (args: string[]) => Promise<{ stdout: string; stderr: string; exitCode: number }>;
+type ToolContentResult = { content: Array<{ type: "text"; text: string }> };
+type ToolDefinition = {
+  name: string;
+  description: string;
+  inputSchema: z.ZodTypeAny;
+  handler: (input: any) => Promise<ToolContentResult>;
+};
+
+function resolveMachineCliEntrypoint(): string {
+  return path.resolve(__dirname, "..", "cli", "index.js");
+}
+
+async function defaultMachineCliRunner(args: string[]): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+  const { execa } = await import("execa");
+  const result = await execa(process.execPath, [resolveMachineCliEntrypoint(), "machine", ...args], {
+    reject: false,
+  });
+
+  return {
+    stdout: result.stdout,
+    stderr: result.stderr,
+    exitCode: result.exitCode ?? 0,
+  };
+}
+
+async function executeMachineCommand<TData>(
+  args: string[],
+  runMachineCli: MachineCliRunner
+): Promise<MachineSuccessPayload<TData>> {
+  const result = await runMachineCli(args);
+
+  let parsed: MachineResponse<TData>;
+  try {
+    parsed = JSON.parse(result.stdout) as MachineResponse<TData>;
+  } catch {
+    throw new Error(result.stderr || result.stdout || "Machine CLI returned invalid JSON.");
+  }
+
+  if (!parsed.ok) {
+    throw new Error(parsed.error.message);
+  }
+
+  return parsed;
+}
+
+function jsonTextContent(value: unknown): { content: Array<{ type: "text"; text: string }> } {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(value, null, 2),
+      },
+    ],
+  };
+}
+
+export function buildSwallowKitToolDefinitions(
+  runMachineCli: MachineCliRunner = defaultMachineCliRunner
+): ToolDefinition[] {
+  return [
+    {
+      name: "swallowkit_inspect_project",
+      description: "Return framework-owned SwallowKit project metadata.",
+      inputSchema: z.object({}),
+      handler: async () => {
+      const response = await executeMachineCommand(["inspect", "project"], runMachineCli);
+      return jsonTextContent(response.data);
+      },
+    },
+    {
+      name: "swallowkit_inspect_entities",
+      description: "Return SwallowKit entities, schema metadata, and connector/auth annotations.",
+      inputSchema: z.object({}),
+      handler: async () => {
+      const response = await executeMachineCommand(["inspect", "entities"], runMachineCli);
+      return jsonTextContent(response.data);
+      },
+    },
+    {
+      name: "swallowkit_inspect_routes",
+      description: "Return BFF and Functions route metadata understood by SwallowKit.",
+      inputSchema: z.object({}),
+      handler: async () => {
+      const response = await executeMachineCommand(["inspect", "routes"], runMachineCli);
+      return jsonTextContent(response.data);
+      },
+    },
+    {
+      name: "swallowkit_validate_project",
+      description: "Validate project metadata, generated artifacts, and framework conventions.",
+      inputSchema: z.object({}),
+      handler: async () => {
+      const response = await executeMachineCommand(["validate", "project"], runMachineCli);
+      return jsonTextContent(response.data);
+      },
+    },
+    {
+      name: "swallowkit_generate_model",
+      description: "Generate SwallowKit model templates through the official generator.",
+      inputSchema: z.object({
+        names: z.array(z.string()).min(1),
+        modelsDir: z.string().optional(),
+        connector: z.string().optional(),
+        overwrite: z.enum(["always", "never"]).optional(),
+      }),
+      handler: async ({ names, modelsDir, connector, overwrite }: { names: string[]; modelsDir?: string; connector?: string; overwrite?: "always" | "never" }) => {
+      const response = await executeMachineCommand(["generate", "model", ...names, ...(modelsDir ? ["--models-dir", modelsDir] : []), ...(connector ? ["--connector", connector] : []), "--overwrite", overwrite || "never"], runMachineCli);
+      return jsonTextContent(response.data);
+      },
+    },
+    {
+      name: "swallowkit_scaffold_model",
+      description: "Generate SwallowKit scaffold artifacts through the official generator.",
+      inputSchema: z.object({
+        model: z.string(),
+        functionsDir: z.string().optional(),
+        apiDir: z.string().optional(),
+        apiOnly: z.boolean().optional(),
+      }),
+      handler: async ({ model, functionsDir, apiDir, apiOnly }: { model: string; functionsDir?: string; apiDir?: string; apiOnly?: boolean }) => {
+      const args = ["generate", "scaffold", model];
+      if (functionsDir) {
+        args.push("--functions-dir", functionsDir);
+      }
+      if (apiDir) {
+        args.push("--api-dir", apiDir);
+      }
+      if (apiOnly) {
+        args.push("--api-only");
+      }
+
+      const response = await executeMachineCommand(args, runMachineCli);
+      return jsonTextContent(response.data);
+      },
+    },
+  ];
+}
+
+export function createSwallowKitMcpServer(runMachineCli: MachineCliRunner = defaultMachineCliRunner): McpServer {
+  const server = new McpServer({
+    name: "swallowkit-mcp",
+    version: process.env.npm_package_version || "0.0.0",
+  });
+
+  for (const tool of buildSwallowKitToolDefinitions(runMachineCli)) {
+    server.registerTool(
+      tool.name,
+      {
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+      },
+      tool.handler
+    );
+  }
+
+  return server;
+}
+
+export async function runMcpServer(): Promise<void> {
+  const server = createSwallowKitMcpServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+if (require.main === module) {
+  void runMcpServer().catch((error) => {
+    console.error(error);
+    process.exitCode = 1;
+  });
+}