@webstir-io/webstir 0.1.1 → 0.1.3

package/src/inspect.ts

@@ -0,0 +1,112 @@
+import type { BackendInspectResult } from './backend-inspect.ts';
+import type { DoctorResult } from './doctor.ts';
+import type { FrontendInspectResult } from './frontend-inspect.ts';
+import type { WorkspaceDescriptor } from './types.ts';
+
+import { runBackendInspect } from './backend-inspect.ts';
+import { runDoctor } from './doctor.ts';
+import { runFrontendInspect } from './frontend-inspect.ts';
+
+export interface RunInspectOptions {
+  readonly workspaceRoot: string;
+  readonly env?: Record<string, string | undefined>;
+}
+
+export interface InspectStepResult {
+  readonly id: 'doctor' | 'frontend-inspect' | 'backend-inspect';
+  readonly status: 'completed' | 'skipped' | 'failed';
+  readonly summary: string;
+}
+
+export interface InspectResult {
+  readonly workspace: WorkspaceDescriptor;
+  readonly success: boolean;
+  readonly steps: readonly InspectStepResult[];
+  readonly doctor: DoctorResult;
+  readonly frontend?: FrontendInspectResult['frontend'];
+  readonly backend?: BackendInspectResult;
+}
+
+export async function runInspect(options: RunInspectOptions): Promise<InspectResult> {
+  const steps: InspectStepResult[] = [];
+  const doctor = await runDoctor({
+    workspaceRoot: options.workspaceRoot,
+    env: options.env,
+  });
+  steps.push({
+    id: 'doctor',
+    status: doctor.healthy ? 'completed' : 'failed',
+    summary: doctor.healthy
+      ? 'Workspace diagnosis completed without issues.'
+      : `Workspace diagnosis found ${doctor.issues.length} issue(s).`,
+  });
+
+  let frontendFailed = false;
+  let frontend: FrontendInspectResult['frontend'] | undefined;
+  if (doctor.workspace.mode === 'api') {
+    steps.push({
+      id: 'frontend-inspect',
+      status: 'skipped',
+      summary: 'Skipped for api workspaces.',
+    });
+  } else {
+    try {
+      const result = await runFrontendInspect({
+        workspaceRoot: options.workspaceRoot,
+      });
+      frontend = result.frontend;
+      steps.push({
+        id: 'frontend-inspect',
+        status: 'completed',
+        summary: `${frontend.pages.length} page(s), app shell ${frontend.appShell.exists ? 'present' : 'missing'}.`,
+      });
+    } catch (error) {
+      frontendFailed = true;
+      const message = error instanceof Error ? error.message : String(error);
+      steps.push({
+        id: 'frontend-inspect',
+        status: 'failed',
+        summary: `Frontend inspection failed: ${message}`,
+      });
+    }
+  }
+
+  let backendFailed = false;
+  let backend: BackendInspectResult | undefined;
+  if (doctor.workspace.mode === 'api' || doctor.workspace.mode === 'full') {
+    try {
+      backend = await runBackendInspect({
+        workspaceRoot: options.workspaceRoot,
+        env: options.env,
+      });
+      steps.push({
+        id: 'backend-inspect',
+        status: 'completed',
+        summary: `${backend.manifest.routes?.length ?? 0} route(s), ${backend.manifest.jobs?.length ?? 0} job(s), module ${backend.manifest.name}@${backend.manifest.version}.`,
+      });
+    } catch (error) {
+      backendFailed = true;
+      const message = error instanceof Error ? error.message : String(error);
+      steps.push({
+        id: 'backend-inspect',
+        status: 'failed',
+        summary: `Backend inspection failed: ${message}`,
+      });
+    }
+  } else {
+    steps.push({
+      id: 'backend-inspect',
+      status: 'skipped',
+      summary: `Skipped for ${doctor.workspace.mode} workspaces.`,
+    });
+  }
+
+  return {
+    workspace: doctor.workspace,
+    success: doctor.healthy && !frontendFailed && !backendFailed,
+    steps,
+    doctor,
+    ...(frontend ? { frontend } : {}),
+    ...(backend ? { backend } : {}),
+  };
+}

package/src/mcp/run-cli-json.ts

@@ -0,0 +1,46 @@
+import { runCli } from '../cli.ts';
+
+interface CliStream {
+  write(message: string): void;
+}
+
+interface CliIo {
+  readonly stdout: CliStream;
+  readonly stderr: CliStream;
+}
+
+export interface JsonCliResult {
+  readonly exitCode: number;
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly data?: Record<string, unknown>;
+}
+
+export async function runCliJson(args: readonly string[]): Promise<JsonCliResult> {
+  const stdout: string[] = [];
+  const stderr: string[] = [];
+  const io: CliIo = {
+    stdout: {
+      write(message) {
+        stdout.push(message);
+      },
+    },
+    stderr: {
+      write(message) {
+        stderr.push(message);
+      },
+    },
+  };
+
+  const exitCode = await runCli(args, io);
+  const stdoutText = stdout.join('');
+  const stderrText = stderr.join('');
+  const trimmed = stdoutText.trim();
+
+  return {
+    exitCode,
+    stdout: stdoutText,
+    stderr: stderrText,
+    ...(trimmed.length > 0 ? { data: JSON.parse(trimmed) as Record<string, unknown> } : {}),
+  };
+}

package/src/mcp/server.ts

@@ -0,0 +1,307 @@
+import { createRequire } from 'node:module';
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+import { runAgentScaffoldJob, runAgentScaffoldPage, runAgentScaffoldRoute } from '../agent.ts';
+import { runUpdateRouteContract } from '../add-backend.ts';
+import { runBackendInspect } from '../backend-inspect.ts';
+import { runCliJson, type JsonCliResult } from './run-cli-json.ts';
+
+const require = createRequire(import.meta.url);
+const pkg = require('../../package.json') as { version?: string };
+const httpMethodSchema = z.enum(['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS']);
+const routeInteractionSchema = z.enum(['navigation', 'mutation']);
+const sessionModeSchema = z.enum(['optional', 'required']);
+const fragmentModeSchema = z.enum(['replace', 'append', 'prepend']);
+const schemaReferenceSchema = z
+  .object({
+    kind: z.enum(['zod', 'json-schema', 'ts-rest']).optional(),
+    name: z.string().min(1),
+    source: z.string().min(1).optional(),
+  })
+  .strict();
+
+const workspaceSchema = z
+  .object({
+    workspace: z.string().min(1),
+  })
+  .strict();
+
+const scaffoldPageSchema = z
+  .object({
+    workspace: z.string().min(1),
+    name: z.string().min(1),
+  })
+  .strict();
+
+const scaffoldRouteSchema = z
+  .object({
+    workspace: z.string().min(1),
+    name: z.string().min(1),
+    method: httpMethodSchema.optional(),
+    path: z.string().min(1).optional(),
+    summary: z.string().min(1).optional(),
+    description: z.string().min(1).optional(),
+    tags: z.array(z.string().min(1)).optional(),
+    interaction: routeInteractionSchema.optional(),
+  })
+  .strict();
+
+const updateRouteContractSchema = z
+  .object({
+    workspace: z.string().min(1),
+    method: httpMethodSchema,
+    path: z.string().min(1),
+    session: sessionModeSchema.nullable().optional(),
+    sessionWrite: z.boolean().nullable().optional(),
+    formUrlEncoded: z.boolean().nullable().optional(),
+    csrf: z.boolean().nullable().optional(),
+    fragmentTarget: z.string().min(1).nullable().optional(),
+    fragmentSelector: z.string().min(1).nullable().optional(),
+    fragmentMode: fragmentModeSchema.nullable().optional(),
+    paramsSchema: schemaReferenceSchema.nullable().optional(),
+    querySchema: schemaReferenceSchema.nullable().optional(),
+    bodySchema: schemaReferenceSchema.nullable().optional(),
+    headersSchema: schemaReferenceSchema.nullable().optional(),
+    responseSchema: schemaReferenceSchema.nullable().optional(),
+    responseStatus: z.number().int().min(100).max(599).nullable().optional(),
+    responseHeadersSchema: schemaReferenceSchema.nullable().optional(),
+  })
+  .strict();
+
+const scaffoldJobSchema = z
+  .object({
+    workspace: z.string().min(1),
+    name: z.string().min(1),
+    schedule: z.string().min(1).optional(),
+    description: z.string().min(1).optional(),
+    priority: z.union([z.number().int(), z.string().min(1)]).optional(),
+  })
+  .strict();
+
+export function createMcpServer(): McpServer {
+  const server = new McpServer({
+    name: 'webstir',
+    version: getPackageVersion(),
+  });
+
+  server.registerTool(
+    'list_operations',
+    {
+      title: 'List Operations',
+      description: 'List stable Webstir operations and their machine-readable metadata.',
+    },
+    async () => toToolResult(await runCliJson(['operations', '--json'])),
+  );
+
+  server.registerTool(
+    'inspect_workspace',
+    {
+      title: 'Inspect Workspace',
+      description: 'Run unified Webstir inspection for the selected workspace.',
+      inputSchema: workspaceSchema,
+    },
+    async ({ workspace }) =>
+      toToolResult(await runCliJson(['inspect', '--json', '--workspace', workspace])),
+  );
+
+  server.registerTool(
+    'validate_workspace',
+    {
+      title: 'Validate Workspace',
+      description: 'Run doctor and tests for the selected workspace.',
+      inputSchema: workspaceSchema,
+    },
+    async ({ workspace }) =>
+      toToolResult(await runCliJson(['agent', 'validate', '--json', '--workspace', workspace])),
+  );
+
+  server.registerTool(
+    'repair_workspace',
+    {
+      title: 'Repair Workspace',
+      description: 'Apply scaffold-managed repair actions and re-check workspace health.',
+      inputSchema: workspaceSchema,
+    },
+    async ({ workspace }) =>
+      toToolResult(await runCliJson(['agent', 'repair', '--json', '--workspace', workspace])),
+  );
+
+  server.registerTool(
+    'repair_dry_run',
+    {
+      title: 'Repair Dry Run',
+      description: 'Report scaffold-managed repair actions without mutating the workspace.',
+      inputSchema: workspaceSchema,
+    },
+    async ({ workspace }) =>
+      toToolResult(await runCliJson(['repair', '--dry-run', '--json', '--workspace', workspace])),
+  );
+
+  server.registerTool(
+    'scaffold_page',
+    {
+      title: 'Scaffold Page',
+      description: 'Create a frontend page through the stable Webstir scaffold flow.',
+      inputSchema: scaffoldPageSchema,
+    },
+    async (input) =>
+      toStructuredToolResult({
+        command: 'agent',
+        ...(await runAgentScaffoldPage({
+          workspaceRoot: input.workspace,
+          pageName: input.name,
+        })),
+      }),
+  );
+
+  server.registerTool(
+    'scaffold_route',
+    {
+      title: 'Scaffold Route',
+      description: 'Create a backend route through the stable Webstir scaffold flow.',
+      inputSchema: scaffoldRouteSchema,
+    },
+    async (input) =>
+      toStructuredToolResult({
+        command: 'agent',
+        ...(await runAgentScaffoldRoute({
+          workspaceRoot: input.workspace,
+          name: input.name,
+          method: input.method,
+          path: input.path,
+          summary: input.summary,
+          description: input.description,
+          tags: input.tags,
+          interaction: input.interaction,
+        })),
+      }),
+  );
+
+  server.registerTool(
+    'update_route_contract',
+    {
+      title: 'Update Route Contract',
+      description:
+        'Enrich an existing backend route with session, form, fragment, and request or response contract metadata.',
+      inputSchema: updateRouteContractSchema,
+    },
+    async (input) => {
+      const scaffold = await runUpdateRouteContract({
+        workspaceRoot: input.workspace,
+        method: input.method,
+        path: input.path,
+        sessionMode: input.session,
+        sessionWrite: input.sessionWrite,
+        formUrlEncoded: input.formUrlEncoded,
+        formCsrf: input.csrf,
+        fragmentTarget: input.fragmentTarget,
+        fragmentSelector: input.fragmentSelector,
+        fragmentMode: input.fragmentMode,
+        paramsSchema: formatNullableSchemaReference(input.paramsSchema),
+        querySchema: formatNullableSchemaReference(input.querySchema),
+        bodySchema: formatNullableSchemaReference(input.bodySchema),
+        headersSchema: formatNullableSchemaReference(input.headersSchema),
+        responseSchema: formatNullableSchemaReference(input.responseSchema),
+        responseStatus: input.responseStatus,
+        responseHeadersSchema: formatNullableSchemaReference(input.responseHeadersSchema),
+      });
+      const inspect = await runBackendInspect({
+        workspaceRoot: input.workspace,
+      });
+
+      return toStructuredToolResult({
+        command: 'update-route-contract',
+        success: true,
+        scaffold,
+        inspect,
+      });
+    },
+  );
+
+  server.registerTool(
+    'scaffold_job',
+    {
+      title: 'Scaffold Job',
+      description: 'Create a backend job through the stable Webstir scaffold flow.',
+      inputSchema: scaffoldJobSchema,
+    },
+    async (input) =>
+      toStructuredToolResult({
+        command: 'agent',
+        ...(await runAgentScaffoldJob({
+          workspaceRoot: input.workspace,
+          name: input.name,
+          schedule: input.schedule,
+          description: input.description,
+          priority: input.priority,
+        })),
+      }),
+  );
+
+  return server;
+}
+
+export async function runMcpServer(): Promise<void> {
+  const server = createMcpServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+function getPackageVersion(): string {
+  if (typeof pkg.version === 'string' && pkg.version.trim().length > 0) {
+    return pkg.version;
+  }
+
+  throw new Error('Missing version in orchestrator package.json for MCP server.');
+}
+
+function formatSchemaReference(
+  value: z.infer<typeof schemaReferenceSchema> | undefined,
+): string | undefined {
+  if (!value) {
+    return undefined;
+  }
+
+  return `${value.kind ?? 'zod'}:${value.name}${value.source ? `@${value.source}` : ''}`;
+}
+
+function formatNullableSchemaReference(
+  value: z.infer<typeof schemaReferenceSchema> | null | undefined,
+): string | null | undefined {
+  if (value === null) {
+    return null;
+  }
+  return formatSchemaReference(value);
+}
+
+function toStructuredToolResult(data: Record<string, unknown>): {
+  content: Array<{ type: 'text'; text: string }>;
+  structuredContent: Record<string, unknown>;
+  isError?: boolean;
+} {
+  return {
+    content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+    structuredContent: data,
+    ...(data.success === false ? { isError: true } : {}),
+  };
+}
+
+function toToolResult(result: JsonCliResult): {
+  content: Array<{ type: 'text'; text: string }>;
+  structuredContent?: Record<string, unknown>;
+  isError?: boolean;
+} {
+  const text =
+    result.data !== undefined
+      ? JSON.stringify(result.data, null, 2)
+      : [result.stdout.trim(), result.stderr.trim()].filter(Boolean).join('\n\n');
+
+  return {
+    content: [{ type: 'text', text }],
+    ...(result.data !== undefined ? { structuredContent: result.data } : {}),
+    ...(result.exitCode !== 0 ? { isError: true } : {}),
+  };
+}

package/src/operations.ts

@@ -0,0 +1,176 @@
+import type { WorkspaceMode } from './types.ts';
+
+export interface WebstirOperationDescriptor {
+  readonly id:
+    | 'init'
+    | 'refresh'
+    | 'inspect'
+    | 'doctor'
+    | 'repair'
+    | 'enable'
+    | 'add-page'
+    | 'add-test'
+    | 'add-route'
+    | 'add-job'
+    | 'frontend-inspect'
+    | 'backend-inspect'
+    | 'build'
+    | 'publish'
+    | 'watch'
+    | 'test'
+    | 'smoke';
+  readonly summary: string;
+  readonly requiresWorkspace: boolean;
+  readonly mutatesWorkspace: boolean;
+  readonly supportsJson: boolean;
+  readonly stableForMcp: boolean;
+  readonly workspaceModes?: readonly WorkspaceMode[];
+}
+
+const OPERATIONS: readonly WebstirOperationDescriptor[] = [
+  {
+    id: 'init',
+    summary: 'Scaffold a new workspace for the supported Webstir modes.',
+    requiresWorkspace: false,
+    mutatesWorkspace: true,
+    supportsJson: false,
+    stableForMcp: true,
+  },
+  {
+    id: 'refresh',
+    summary: 'Reset and re-scaffold an existing workspace directory.',
+    requiresWorkspace: true,
+    mutatesWorkspace: true,
+    supportsJson: false,
+    stableForMcp: false,
+  },
+  {
+    id: 'inspect',
+    summary: 'Diagnose the workspace and surface stable frontend and backend contract data.',
+    requiresWorkspace: true,
+    mutatesWorkspace: false,
+    supportsJson: true,
+    stableForMcp: true,
+  },
+  {
+    id: 'doctor',
+    summary: 'Diagnose scaffold drift and backend manifest health.',
+    requiresWorkspace: true,
+    mutatesWorkspace: false,
+    supportsJson: true,
+    stableForMcp: true,
+  },
+  {
+    id: 'repair',
+    summary: 'Restore missing scaffold-managed files and wiring.',
+    requiresWorkspace: true,
+    mutatesWorkspace: true,
+    supportsJson: true,
+    stableForMcp: true,
+  },
+  {
+    id: 'enable',
+    summary: 'Opt into an optional framework feature.',
+    requiresWorkspace: true,
+    mutatesWorkspace: true,
+    supportsJson: false,
+    stableForMcp: false,
+  },
+  {
+    id: 'add-page',
+    summary: 'Scaffold a frontend document page.',
+    requiresWorkspace: true,
+    mutatesWorkspace: true,
+    supportsJson: false,
+    stableForMcp: true,
+    workspaceModes: ['spa', 'ssg', 'full'],
+  },
+  {
+    id: 'add-test',
+    summary: 'Scaffold a frontend or backend test file.',
+    requiresWorkspace: true,
+    mutatesWorkspace: true,
+    supportsJson: false,
+    stableForMcp: true,
+  },
+  {
+    id: 'add-route',
+    summary: 'Record a backend route contract in the module manifest.',
+    requiresWorkspace: true,
+    mutatesWorkspace: true,
+    supportsJson: false,
+    stableForMcp: true,
+    workspaceModes: ['api', 'full'],
+  },
+  {
+    id: 'add-job',
+    summary: 'Scaffold a backend job and record it in the module manifest.',
+    requiresWorkspace: true,
+    mutatesWorkspace: true,
+    supportsJson: false,
+    stableForMcp: true,
+    workspaceModes: ['api', 'full'],
+  },
+  {
+    id: 'frontend-inspect',
+    summary: 'Read stable frontend workspace facts such as pages, app shell, and feature flags.',
+    requiresWorkspace: true,
+    mutatesWorkspace: false,
+    supportsJson: true,
+    stableForMcp: true,
+    workspaceModes: ['spa', 'ssg', 'full'],
+  },
+  {
+    id: 'backend-inspect',
+    summary: 'Build the backend and emit manifest metadata for routes and jobs.',
+    requiresWorkspace: true,
+    mutatesWorkspace: false,
+    supportsJson: true,
+    stableForMcp: true,
+    workspaceModes: ['api', 'full'],
+  },
+  {
+    id: 'build',
+    summary: 'Build the current workspace through the canonical providers.',
+    requiresWorkspace: true,
+    mutatesWorkspace: false,
+    supportsJson: false,
+    stableForMcp: true,
+  },
+  {
+    id: 'publish',
+    summary: 'Produce publish-ready artifacts for the current workspace.',
+    requiresWorkspace: true,
+    mutatesWorkspace: false,
+    supportsJson: false,
+    stableForMcp: true,
+  },
+  {
+    id: 'watch',
+    summary: 'Run the long-lived development loop.',
+    requiresWorkspace: true,
+    mutatesWorkspace: false,
+    supportsJson: false,
+    stableForMcp: false,
+  },
+  {
+    id: 'test',
+    summary: 'Build and run frontend and or backend tests for the workspace.',
+    requiresWorkspace: true,
+    mutatesWorkspace: false,
+    supportsJson: false,
+    stableForMcp: true,
+  },
+  {
+    id: 'smoke',
+    summary: 'Run the bounded end-to-end verification flow.',
+    requiresWorkspace: false,
+    mutatesWorkspace: false,
+    supportsJson: false,
+    stableForMcp: true,
+  },
+] as const;
+
+export function listOperations(): readonly WebstirOperationDescriptor[] {
+  return OPERATIONS;
+}

package/src/providers.ts

@@ -1,6 +1,5 @@
 import path from 'node:path';
 import { access } from 'node:fs/promises';
-import { spawn } from 'node:child_process';
 
 import type { BuildProvider, BuildTargetKind } from './types.ts';
 import { monorepoRoot } from './paths.ts';
@@ -11,11 +10,13 @@ let localPackageBuildPromise: Promise<void> | null = null;
 export async function loadProvider(kind: BuildTargetKind): Promise<BuildProvider> {
   await ensureLocalPackageArtifacts();
   if (kind === 'frontend') {
-    const mod = await import('@webstir-io/webstir-frontend') as { frontendProvider: BuildProvider };
+    const mod = (await import('@webstir-io/webstir-frontend')) as {
+      frontendProvider: BuildProvider;
+    };
     return mod.frontendProvider;
   }
 
-  const mod = await import('@webstir-io/webstir-backend') as { backendProvider: BuildProvider };
+  const mod = (await import('@webstir-io/webstir-backend')) as { backendProvider: BuildProvider };
   return mod.backendProvider;
 }
 
@@ -68,21 +69,22 @@ async function runRuntimeCommand(args: readonly string[]): Promise<void> {
     return;
   }
 
-  await new Promise<void>((resolve, reject) => {
-    const child = spawn(resolveRuntimeCommand(), args, {
-      cwd,
-      env: process.env,
-      stdio: 'inherit',
-    });
-
-    child.once('error', reject);
-    child.once('close', (code: number | null) => {
-      if (code === 0) {
-        resolve();
-        return;
-      }
+  try {
+    await Bun.$.cwd(cwd)`${resolveRuntimeCommand()} ${args}`;
+  } catch (error) {
+    const exitCode =
+      typeof error === 'object' &&
+      error !== null &&
+      'exitCode' in error &&
+      typeof error.exitCode === 'number'
+        ? error.exitCode
+        : null;
+    if (exitCode === null) {
+      throw error;
+    }
 
-      reject(new Error(`Command failed with exit code ${code}: ${args.join(' ')}`));
+    throw new Error(`Command failed with exit code ${exitCode}: ${args.join(' ')}`, {
+      cause: error,
     });
-  });
+  }
 }