@webstir-io/webstir 0.1.1 → 0.1.2

package/src/agent.ts

@@ -0,0 +1,393 @@
+import type { AddCommandResult } from './add.ts';
+import type { AddJobScaffoldOptions, AddRouteScaffoldOptions } from './add-backend.ts';
+import type { BackendInspectResult } from './backend-inspect.ts';
+import type { DoctorResult } from './doctor.ts';
+import type { RepairResult } from './repair.ts';
+import type { TestCommandResult } from './test.ts';
+
+import { runAddPageCommand } from './add.ts';
+import {
+  parseAddJobScaffoldArgs,
+  parseAddRouteScaffoldArgs,
+  runAddJobScaffold,
+  runAddRouteScaffold,
+} from './add-backend.ts';
+import { runBackendInspect } from './backend-inspect.ts';
+import { runDoctor } from './doctor.ts';
+import { runRepair } from './repair.ts';
+import { runTest } from './test.ts';
+
+export type AgentGoal =
+  | 'inspect'
+  | 'validate'
+  | 'repair'
+  | 'scaffold-page'
+  | 'scaffold-route'
+  | 'scaffold-job';
+
+export interface RunAgentOptions {
+  readonly workspaceRoot: string;
+  readonly goal: AgentGoal;
+  readonly rawArgs: readonly string[];
+  readonly positionals: readonly string[];
+  readonly env?: Record<string, string | undefined>;
+}
+
+export interface AgentStepResult {
+  readonly id:
+    | 'doctor'
+    | 'backend-inspect'
+    | 'test'
+    | 'repair'
+    | 'add-page'
+    | 'add-route'
+    | 'add-job';
+  readonly status: 'completed' | 'skipped' | 'failed';
+  readonly summary: string;
+}
+
+export interface AgentResult {
+  readonly workspaceRoot: string;
+  readonly goal: AgentGoal;
+  readonly success: boolean;
+  readonly steps: readonly AgentStepResult[];
+  readonly doctor?: DoctorResult;
+  readonly inspect?: BackendInspectResult;
+  readonly repair?: RepairResult;
+  readonly test?: Pick<TestCommandResult, 'runtime' | 'builtTargets' | 'summary' | 'hadFailures'>;
+  readonly scaffold?: Pick<AddCommandResult, 'subject' | 'target' | 'changes' | 'note'>;
+}
+
+export interface RunAgentScaffoldPageOptions {
+  readonly workspaceRoot: string;
+  readonly pageName: string;
+  readonly env?: Record<string, string | undefined>;
+}
+
+export interface RunAgentScaffoldRouteOptions extends AddRouteScaffoldOptions {
+  readonly env?: Record<string, string | undefined>;
+}
+
+export interface RunAgentScaffoldJobOptions extends AddJobScaffoldOptions {
+  readonly env?: Record<string, string | undefined>;
+}
+
+export async function runAgent(options: RunAgentOptions): Promise<AgentResult> {
+  const steps: AgentStepResult[] = [];
+
+  if (options.goal === 'inspect') {
+    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).`,
+    });
+
+    const backendSupported = doctor.workspace.mode === 'api' || doctor.workspace.mode === 'full';
+    let inspectFailed = false;
+    let inspect: BackendInspectResult | undefined;
+    if (backendSupported) {
+      try {
+        inspect = await runBackendInspect({
+          workspaceRoot: options.workspaceRoot,
+          env: options.env,
+        });
+        steps.push({
+          id: 'backend-inspect',
+          status: 'completed',
+          summary: `${inspect.manifest.routes?.length ?? 0} route(s), ${inspect.manifest.jobs?.length ?? 0} job(s), module ${inspect.manifest.name}@${inspect.manifest.version}.`,
+        });
+      } catch (error) {
+        inspectFailed = true;
+        const message = error instanceof Error ? error.message : String(error);
+        steps.push({
+          id: 'backend-inspect',
+          status: 'failed',
+          summary: `Backend inspection failed: ${message}`,
+        });
+      }
+    }
+
+    return {
+      workspaceRoot: options.workspaceRoot,
+      goal: options.goal,
+      success: doctor.healthy && !inspectFailed,
+      steps,
+      doctor,
+      ...(inspect ? { inspect } : {}),
+    };
+  }
+
+  if (options.goal === 'validate') {
+    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).`,
+    });
+
+    if (!doctor.healthy) {
+      steps.push({
+        id: 'test',
+        status: 'skipped',
+        summary: 'Skipped tests because diagnosis reported issues first.',
+      });
+      return {
+        workspaceRoot: options.workspaceRoot,
+        goal: options.goal,
+        success: false,
+        steps,
+        doctor,
+      };
+    }
+
+    const test = await runTest({
+      workspaceRoot: options.workspaceRoot,
+      rawArgs: [],
+      env: options.env,
+      quietInstall: true,
+    });
+    steps.push({
+      id: 'test',
+      status: test.hadFailures ? 'failed' : 'completed',
+      summary: `${test.summary.passed} passed, ${test.summary.failed} failed.`,
+    });
+
+    return {
+      workspaceRoot: options.workspaceRoot,
+      goal: options.goal,
+      success: !test.hadFailures,
+      steps,
+      doctor,
+      test: {
+        runtime: test.runtime,
+        builtTargets: test.builtTargets,
+        summary: test.summary,
+        hadFailures: test.hadFailures,
+      },
+    };
+  }
+
+  if (options.goal === 'repair') {
+    const initialDoctor = await runDoctor({
+      workspaceRoot: options.workspaceRoot,
+      env: options.env,
+    });
+    steps.push({
+      id: 'doctor',
+      status: initialDoctor.healthy ? 'completed' : 'failed',
+      summary: initialDoctor.healthy
+        ? 'Workspace diagnosis completed without issues.'
+        : `Workspace diagnosis found ${initialDoctor.issues.length} issue(s).`,
+    });
+
+    if (initialDoctor.healthy) {
+      steps.push({
+        id: 'repair',
+        status: 'skipped',
+        summary: 'Skipped repair because the workspace is already healthy.',
+      });
+      return {
+        workspaceRoot: options.workspaceRoot,
+        goal: options.goal,
+        success: true,
+        steps,
+        doctor: initialDoctor,
+      };
+    }
+
+    if (initialDoctor.repair.changes.length === 0) {
+      steps.push({
+        id: 'repair',
+        status: 'skipped',
+        summary: 'No scaffold-managed repair action was available for the reported issues.',
+      });
+      return {
+        workspaceRoot: options.workspaceRoot,
+        goal: options.goal,
+        success: false,
+        steps,
+        doctor: initialDoctor,
+      };
+    }
+
+    const repair = await runRepair({
+      workspaceRoot: options.workspaceRoot,
+      rawArgs: [],
+    });
+    steps.push({
+      id: 'repair',
+      status: 'completed',
+      summary: `Applied ${repair.changes.length} scaffold-managed change(s).`,
+    });
+
+    const finalDoctor = await runDoctor({
+      workspaceRoot: options.workspaceRoot,
+      env: options.env,
+    });
+    steps.push({
+      id: 'doctor',
+      status: finalDoctor.healthy ? 'completed' : 'failed',
+      summary: finalDoctor.healthy
+        ? 'Workspace diagnosis passed after repair.'
+        : `Workspace still has ${finalDoctor.issues.length} issue(s) after repair.`,
+    });
+
+    return {
+      workspaceRoot: options.workspaceRoot,
+      goal: options.goal,
+      success: finalDoctor.healthy,
+      steps,
+      doctor: finalDoctor,
+      repair,
+    };
+  }
+
+  if (options.goal === 'scaffold-page') {
+    const pageName = options.positionals[1];
+    if (!pageName) {
+      throw new Error('Usage: webstir agent scaffold-page <name> --workspace <path>.');
+    }
+
+    return await runAgentScaffoldPage({
+      workspaceRoot: options.workspaceRoot,
+      pageName,
+      env: options.env,
+    });
+  }
+
+  if (options.goal === 'scaffold-route') {
+    return await runAgentScaffoldRoute({
+      workspaceRoot: options.workspaceRoot,
+      ...parseAddRouteScaffoldArgs(stripGoalFromRawArgs(options.rawArgs, options.goal)),
+      env: options.env,
+    });
+  }
+
+  return await runAgentScaffoldJob({
+    workspaceRoot: options.workspaceRoot,
+    ...parseAddJobScaffoldArgs(stripGoalFromRawArgs(options.rawArgs, options.goal)),
+    env: options.env,
+  });
+}
+
+export async function runAgentScaffoldPage(
+  options: RunAgentScaffoldPageOptions,
+): Promise<AgentResult> {
+  const steps: AgentStepResult[] = [];
+  const scaffold = await runAddPageCommand({
+    workspaceRoot: options.workspaceRoot,
+    args: [options.pageName],
+  });
+  steps.push({
+    id: 'add-page',
+    status: 'completed',
+    summary: `Scaffolded page ${scaffold.target}.`,
+  });
+
+  const doctor = await runDoctor({
+    workspaceRoot: options.workspaceRoot,
+    env: options.env,
+  });
+  steps.push({
+    id: 'doctor',
+    status: doctor.healthy ? 'completed' : 'failed',
+    summary: doctor.healthy
+      ? 'Workspace remains healthy after page scaffolding.'
+      : `Workspace diagnosis found ${doctor.issues.length} issue(s) after scaffolding.`,
+  });
+
+  return {
+    workspaceRoot: options.workspaceRoot,
+    goal: 'scaffold-page',
+    success: doctor.healthy,
+    steps,
+    doctor,
+    scaffold,
+  };
+}
+
+export async function runAgentScaffoldRoute(
+  options: RunAgentScaffoldRouteOptions,
+): Promise<AgentResult> {
+  const steps: AgentStepResult[] = [];
+  const scaffold = await runAddRouteScaffold(options);
+  steps.push({
+    id: 'add-route',
+    status: 'completed',
+    summary: `Scaffolded route ${scaffold.target}.`,
+  });
+
+  const inspect = await runBackendInspect({
+    workspaceRoot: options.workspaceRoot,
+    env: options.env,
+  });
+  steps.push({
+    id: 'backend-inspect',
+    status: 'completed',
+    summary: `${inspect.manifest.routes?.length ?? 0} route(s), ${inspect.manifest.jobs?.length ?? 0} job(s), module ${inspect.manifest.name}@${inspect.manifest.version}.`,
+  });
+
+  return {
+    workspaceRoot: options.workspaceRoot,
+    goal: 'scaffold-route',
+    success: true,
+    steps,
+    inspect,
+    scaffold,
+  };
+}
+
+export async function runAgentScaffoldJob(
+  options: RunAgentScaffoldJobOptions,
+): Promise<AgentResult> {
+  const steps: AgentStepResult[] = [];
+  const scaffold = await runAddJobScaffold(options);
+  steps.push({
+    id: 'add-job',
+    status: 'completed',
+    summary: `Scaffolded job ${scaffold.target}.`,
+  });
+
+  const inspect = await runBackendInspect({
+    workspaceRoot: options.workspaceRoot,
+    env: options.env,
+  });
+  steps.push({
+    id: 'backend-inspect',
+    status: 'completed',
+    summary: `${inspect.manifest.routes?.length ?? 0} route(s), ${inspect.manifest.jobs?.length ?? 0} job(s), module ${inspect.manifest.name}@${inspect.manifest.version}.`,
+  });
+
+  return {
+    workspaceRoot: options.workspaceRoot,
+    goal: 'scaffold-job',
+    success: true,
+    steps,
+    inspect,
+    scaffold,
+  };
+}
+
+function stripGoalFromRawArgs(rawArgs: readonly string[], goal: AgentGoal): string[] {
+  const next = [...rawArgs];
+  const goalIndex = next.indexOf(goal);
+  if (goalIndex >= 0) {
+    next.splice(goalIndex, 1);
+  }
+  const jsonIndex = next.indexOf('--json');
+  if (jsonIndex >= 0) {
+    next.splice(jsonIndex, 1);
+  }
+  return next;
+}

package/src/api-watch.ts

@@ -15,12 +15,12 @@ export interface ApiWatchSession {
 export async function runApiWatch(
   workspace: WorkspaceDescriptor,
   options: WatchOptions,
-  io: WatchIo
+  io: WatchIo,
 ): Promise<void> {
   const session = await startApiWatchSession(workspace, options, io);
 
   io.stdout.write(
-    `[webstir] watch starting\nworkspace: ${workspace.name}\nmode: ${workspace.mode}\nurl: ${session.origin}\n`
+    `[webstir] watch starting\nworkspace: ${workspace.name}\nmode: ${workspace.mode}\nurl: ${session.origin}\n`,
   );
 
   const stopSignal = createStopSignal();
@@ -35,9 +35,12 @@ export async function runApiWatch(
 export async function startApiWatchSession(
   workspace: WorkspaceDescriptor,
   options: WatchOptions,
-  io: WatchIo
+  io: WatchIo,
 ): Promise<ApiWatchSession> {
-  const runtimeEnv = createWorkspaceRuntimeEnv(workspace.root, 'build', options.env);
+  const runtimeEnv = {
+    ...createWorkspaceRuntimeEnv(workspace.root, 'build', options.env),
+    WEBSTIR_FRONTEND_DEV_SERVER: '1',
+  };
   const runtime = new BackendRuntimeSupervisor({
     workspaceRoot: workspace.root,
     buildRoot: path.join(workspace.root, 'build', 'backend'),

package/src/backend-inspect.ts

@@ -1,10 +1,17 @@
 import type { ModuleManifest } from '@webstir-io/module-contract';
 import type { WorkspaceDescriptor } from './types.ts';
 
+import path from 'node:path';
+import { existsSync } from 'node:fs';
+import { readdir } from 'node:fs/promises';
+
 import { loadProvider } from './providers.ts';
 import { createWorkspaceRuntimeEnv } from './runtime.ts';
 import { readWorkspaceDescriptor } from './workspace.ts';
 
+const MIGRATIONS_TABLE_ENV_KEY = 'DATABASE_MIGRATIONS_TABLE';
+const DEFAULT_MIGRATIONS_TABLE = '_webstir_migrations';
+
 export interface RunBackendInspectOptions {
   readonly workspaceRoot: string;
   readonly env?: Record<string, string | undefined>;
@@ -14,12 +21,34 @@ export interface BackendInspectResult {
   readonly workspace: WorkspaceDescriptor;
   readonly buildRoot: string;
   readonly manifest: ModuleManifest;
+  readonly data: BackendDataInspectResult;
+}
+
+export interface BackendDataInspectResult {
+  readonly migrations: BackendMigrationInspectResult;
 }
 
-export async function runBackendInspect(options: RunBackendInspectOptions): Promise<BackendInspectResult> {
+export interface BackendMigrationInspectResult {
+  readonly runnerPresent: boolean;
+  readonly runnerPath: string;
+  readonly migrationsDirectoryPresent: boolean;
+  readonly migrationsDirectory: string;
+  readonly migrationFilesCount: number;
+  readonly migrationFiles: readonly string[];
+  readonly exampleMigrationPresent: boolean;
+  readonly tableEnvKey: typeof MIGRATIONS_TABLE_ENV_KEY;
+  readonly configuredTable: string;
+  readonly defaultTable: typeof DEFAULT_MIGRATIONS_TABLE;
+}
+
+export async function runBackendInspect(
+  options: RunBackendInspectOptions,
+): Promise<BackendInspectResult> {
   const workspace = await readWorkspaceDescriptor(options.workspaceRoot);
   if (workspace.mode !== 'api' && workspace.mode !== 'full') {
-    throw new Error(`backend-inspect only supports api and full workspaces. Received mode "${workspace.mode}".`);
+    throw new Error(
+      `backend-inspect only supports api and full workspaces. Received mode "${workspace.mode}".`,
+    );
   }
 
   const provider = await loadProvider('backend');
@@ -41,5 +70,44 @@ export async function runBackendInspect(options: RunBackendInspectOptions): Prom
     workspace,
     buildRoot: resolvedWorkspace.buildRoot,
     manifest,
+    data: await inspectBackendData(workspace.root, options.env),
+  };
+}
+
+async function inspectBackendData(
+  workspaceRoot: string,
+  env: Record<string, string | undefined> | undefined,
+): Promise<BackendDataInspectResult> {
+  return {
+    migrations: await inspectMigrations(workspaceRoot, env),
+  };
+}
+
+async function inspectMigrations(
+  workspaceRoot: string,
+  env: Record<string, string | undefined> | undefined,
+): Promise<BackendMigrationInspectResult> {
+  const runtimeEnv = env ?? process.env;
+  const runnerPath = path.join('src', 'backend', 'db', 'migrate.ts');
+  const migrationsDirectory = path.join('src', 'backend', 'db', 'migrations');
+  const absoluteRunnerPath = path.join(workspaceRoot, runnerPath);
+  const absoluteMigrationsDirectory = path.join(workspaceRoot, migrationsDirectory);
+  const migrationFiles = existsSync(absoluteMigrationsDirectory)
+    ? (await readdir(absoluteMigrationsDirectory))
+        .filter((file) => /\.[cm]?[jt]s$/.test(file))
+        .sort()
+    : [];
+
+  return {
+    runnerPresent: existsSync(absoluteRunnerPath),
+    runnerPath,
+    migrationsDirectoryPresent: existsSync(absoluteMigrationsDirectory),
+    migrationsDirectory,
+    migrationFilesCount: migrationFiles.length,
+    migrationFiles,
+    exampleMigrationPresent: migrationFiles.includes('0001-example.ts'),
+    tableEnvKey: MIGRATIONS_TABLE_ENV_KEY,
+    configuredTable: runtimeEnv[MIGRATIONS_TABLE_ENV_KEY] ?? DEFAULT_MIGRATIONS_TABLE,
+    defaultTable: DEFAULT_MIGRATIONS_TABLE,
   };
 }

package/src/backend-runtime.ts

@@ -148,19 +148,27 @@ export class BackendRuntimeSupervisor {
 
     let ready = false;
 
-    exitPromise.then((code) => {
-      if (!ready) {
-        return;
-      } else if (!processRecord.expectedExit && !this.isStopping && this.current === processRecord) {
-        this.io.stderr.write(`[webstir] backend runtime exited unexpectedly with code ${code ?? 'null'}.\n`);
-      }
-    }).finally(() => {
-      if (this.current === processRecord) {
-        this.current = undefined;
-      }
-      stdoutReader.close();
-      stderrReader.close();
-    });
+    exitPromise
+      .then((code) => {
+        if (!ready) {
+          return;
+        } else if (
+          !processRecord.expectedExit &&
+          !this.isStopping &&
+          this.current === processRecord
+        ) {
+          this.io.stderr.write(
+            `[webstir] backend runtime exited unexpectedly with code ${code ?? 'null'}.\n`,
+          );
+        }
+      })
+      .finally(() => {
+        if (this.current === processRecord) {
+          this.current = undefined;
+        }
+        stdoutReader.close();
+        stderrReader.close();
+      });
 
     try {
       await waitForRuntimeReady(port, exitPromise);
@@ -232,7 +240,7 @@ function normalizeDisplayHost(host: string): string {
 
 async function waitForRuntimeReady(
   port: number,
-  exitPromise: Promise<number | null>
+  exitPromise: Promise<number | null>,
 ): Promise<void> {
   const abortController = new AbortController();
 

package/src/build.ts

@@ -1,6 +1,4 @@
-import type {
-  CommandExecutionResult,
-} from './types.ts';
+import type { CommandExecutionResult } from './types.ts';
 import { runCommand, type RunCommandOptions } from './execute.ts';
 
 export type RunBuildOptions = RunCommandOptions;