@webstir-io/webstir 0.1.1 → 0.1.2

package/src/external-workspace.ts

@@ -0,0 +1,178 @@
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { cp, mkdtemp, readFile, writeFile } from 'node:fs/promises';
+
+import { monorepoRoot } from './paths.ts';
+import { resolveRuntimeCommand } from './runtime.ts';
+
+const REPO_LOCAL_PACKAGES = new Map<string, string>([
+  [
+    '@webstir-io/module-contract',
+    path.join(monorepoRoot ?? '', 'packages', 'contracts', 'module-contract'),
+  ],
+  [
+    '@webstir-io/testing-contract',
+    path.join(monorepoRoot ?? '', 'packages', 'contracts', 'testing-contract'),
+  ],
+  [
+    '@webstir-io/webstir-frontend',
+    path.join(monorepoRoot ?? '', 'packages', 'tooling', 'webstir-frontend'),
+  ],
+  [
+    '@webstir-io/webstir-backend',
+    path.join(monorepoRoot ?? '', 'packages', 'tooling', 'webstir-backend'),
+  ],
+  [
+    '@webstir-io/webstir-testing',
+    path.join(monorepoRoot ?? '', 'packages', 'tooling', 'webstir-testing'),
+  ],
+]);
+
+const REPO_LOCAL_TRANSITIVE_DEPENDENCIES = new Map<string, readonly string[]>([
+  ['@webstir-io/webstir-frontend', ['@webstir-io/module-contract']],
+  ['@webstir-io/webstir-backend', ['@webstir-io/module-contract']],
+  ['@webstir-io/webstir-testing', ['@webstir-io/testing-contract']],
+]);
+
+export async function prepareExternalWorkspaceCopy(
+  workspaceRoot: string,
+  tempPrefix: string,
+  options: {
+    readonly forceLocalPackages?: boolean;
+    readonly installStdio?: 'inherit' | 'pipe';
+  } = {},
+): Promise<{ readonly workspaceRoot: string; readonly cleanupRoot: string } | null> {
+  if (!monorepoRoot || !isExternalWorkspace(workspaceRoot)) {
+    return null;
+  }
+
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), tempPrefix));
+  const tempWorkspaceRoot = path.join(tempRoot, path.basename(workspaceRoot));
+  await cp(workspaceRoot, tempWorkspaceRoot, { recursive: true });
+  await materializeRepoLocalWorkspaceDependencies(tempWorkspaceRoot, options);
+
+  return {
+    workspaceRoot: tempWorkspaceRoot,
+    cleanupRoot: tempRoot,
+  };
+}
+
+export async function materializeRepoLocalWorkspaceDependencies(
+  workspaceRoot: string,
+  options: {
+    readonly forceLocalPackages?: boolean;
+    readonly installStdio?: 'inherit' | 'pipe';
+  } = {},
+): Promise<void> {
+  if (!monorepoRoot || !isExternalWorkspace(workspaceRoot)) {
+    return;
+  }
+
+  const packageJsonPath = path.join(workspaceRoot, 'package.json');
+  const packageJson = JSON.parse(await readFile(packageJsonPath, 'utf8')) as {
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+    overrides?: Record<string, string>;
+  };
+  const normalized = normalizeRepoLocalDependencySpecs(packageJson, options);
+  if (!normalized.changed) {
+    return;
+  }
+
+  await writeFile(packageJsonPath, `${JSON.stringify(normalized.packageJson, null, 2)}\n`, 'utf8');
+  const install = spawnSync(resolveRuntimeCommand(), ['install'], {
+    cwd: workspaceRoot,
+    env: process.env,
+    stdio: options.installStdio ?? 'inherit',
+  });
+  if (install.error) {
+    throw install.error;
+  }
+  if (install.status !== 0) {
+    throw new Error(`Failed to install repo-local workspace dependencies for ${workspaceRoot}.`);
+  }
+}
+
+export function isExternalWorkspace(workspaceRoot: string): boolean {
+  if (!monorepoRoot) {
+    return true;
+  }
+
+  const relativeToRepo = path.relative(monorepoRoot, workspaceRoot);
+  return relativeToRepo.startsWith('..') || path.isAbsolute(relativeToRepo);
+}
+
+export function normalizeRepoLocalDependencySpecs(
+  source: {
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+    overrides?: Record<string, string>;
+  },
+  options: {
+    readonly forceLocalPackages?: boolean;
+  } = {},
+): {
+  readonly packageJson: {
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+    overrides?: Record<string, string>;
+  };
+  readonly changed: boolean;
+} {
+  let changed = false;
+  const packageJson = structuredClone(source);
+
+  function setLocalOverride(packageName: string, packageRoot: string): void {
+    packageJson.overrides ??= {};
+    const dependencySpec = `file:${packageRoot}`;
+    if (packageJson.overrides[packageName] === dependencySpec) {
+      return;
+    }
+
+    packageJson.overrides[packageName] = dependencySpec;
+    changed = true;
+  }
+
+  for (const field of ['dependencies', 'devDependencies'] as const) {
+    const entries = packageJson[field];
+    if (!entries) {
+      continue;
+    }
+
+    const localizedPackages = new Set<string>();
+    for (const [packageName, packageRoot] of REPO_LOCAL_PACKAGES) {
+      if (!entries[packageName]) {
+        continue;
+      }
+      if (!options.forceLocalPackages && entries[packageName] !== 'workspace:*') {
+        continue;
+      }
+
+      entries[packageName] = `file:${packageRoot}`;
+      setLocalOverride(packageName, packageRoot);
+      localizedPackages.add(packageName);
+      changed = true;
+    }
+
+    for (const packageName of localizedPackages) {
+      for (const dependencyName of REPO_LOCAL_TRANSITIVE_DEPENDENCIES.get(packageName) ?? []) {
+        const dependencyRoot = REPO_LOCAL_PACKAGES.get(dependencyName);
+        if (!dependencyRoot) {
+          continue;
+        }
+
+        const dependencySpec = `file:${dependencyRoot}`;
+        setLocalOverride(dependencyName, dependencyRoot);
+        if (entries[dependencyName] === dependencySpec) {
+          continue;
+        }
+
+        entries[dependencyName] = dependencySpec;
+        changed = true;
+      }
+    }
+  }
+
+  return { packageJson, changed };
+}

package/src/format.ts

@@ -1,11 +1,15 @@
+import type { AgentResult } from './agent.ts';
+import type { FrontendInspectResult } from './frontend-inspect.ts';
 import type { EnableResult } from './enable.ts';
+import type { InspectResult } from './inspect.ts';
+import type { DoctorResult } from './doctor.ts';
 import type { InitResult } from './init.ts';
+import type { WebstirOperationDescriptor } from './operations.ts';
 import type { RefreshResult } from './refresh.ts';
 import type { RepairResult } from './repair.ts';
 import type { BackendInspectResult } from './backend-inspect.ts';
 import type { SmokeResult } from './smoke.ts';
 import type { TestCommandResult } from './test.ts';
-import { formatFailedTests } from './test.ts';
 import type { CommandExecutionResult } from './types.ts';
 
 export function formatBuildSummary(result: CommandExecutionResult): string {
@@ -37,11 +41,21 @@ export function formatEnableSummary(result: EnableResult): string {
 }
 
 export function formatInitSummary(result: InitResult): string {
-  return formatWorkspaceMutationSummary('[webstir] init complete', result.mode, result.workspaceRoot, result.changes);
+  return formatWorkspaceMutationSummary(
+    '[webstir] init complete',
+    result.mode,
+    result.workspaceRoot,
+    result.changes,
+  );
 }
 
 export function formatRefreshSummary(result: RefreshResult): string {
-  return formatWorkspaceMutationSummary('[webstir] refresh complete', result.mode, result.workspaceRoot, result.changes);
+  return formatWorkspaceMutationSummary(
+    '[webstir] refresh complete',
+    result.mode,
+    result.workspaceRoot,
+    result.changes,
+  );
 }
 
 export function formatRepairSummary(result: RepairResult): string {
@@ -65,6 +79,224 @@ export function formatRepairSummary(result: RepairResult): string {
   return lines.join('\n');
 }
 
+export function formatRepairJson(result: RepairResult): string {
+  return JSON.stringify(
+    {
+      command: 'repair',
+      workspaceRoot: result.workspaceRoot,
+      mode: result.mode,
+      dryRun: result.dryRun,
+      changes: result.changes,
+    },
+    null,
+    2,
+  );
+}
+
+export function formatOperationsSummary(operations: readonly WebstirOperationDescriptor[]): string {
+  const lines = ['[webstir] operations', `count: ${operations.length}`];
+
+  for (const operation of operations) {
+    const details = [
+      operation.requiresWorkspace ? 'workspace' : 'no-workspace',
+      operation.mutatesWorkspace ? 'mutates' : 'read-only',
+      operation.supportsJson ? 'json' : 'text',
+      operation.stableForMcp ? 'mcp-ready' : 'manual-only',
+      operation.workspaceModes ? `modes: ${operation.workspaceModes.join(', ')}` : undefined,
+    ].filter(Boolean);
+    lines.push(
+      `  - ${operation.id}: ${operation.summary}${details.length > 0 ? ` (${details.join(', ')})` : ''}`,
+    );
+  }
+
+  return lines.join('\n');
+}
+
+export function formatOperationsJson(operations: readonly WebstirOperationDescriptor[]): string {
+  return JSON.stringify(
+    {
+      command: 'operations',
+      operations,
+    },
+    null,
+    2,
+  );
+}
+
+export function formatDoctorSummary(result: DoctorResult): string {
+  const lines = [
+    '[webstir] doctor complete',
+    `workspace: ${result.workspace.name}`,
+    `mode: ${result.workspace.mode}`,
+    `root: ${result.workspace.root}`,
+    `healthy: ${result.healthy ? 'true' : 'false'}`,
+  ];
+
+  lines.push(`checks: ${result.checks.length}`);
+  for (const check of result.checks) {
+    lines.push(`  - ${check.id}: ${check.status} (${check.summary})`);
+    if (check.detail) {
+      lines.push(`    detail: ${check.detail}`);
+    }
+  }
+
+  if (result.issues.length === 0) {
+    lines.push('issues: none');
+  } else {
+    lines.push(`issues: ${result.issues.length}`);
+    for (const issue of result.issues) {
+      lines.push(`  - ${issue.code}: ${issue.message}`);
+      if (issue.changes && issue.changes.length > 0) {
+        for (const change of issue.changes) {
+          lines.push(`    change: ${change}`);
+        }
+      }
+    }
+  }
+
+  if (result.repair.changes.length > 0) {
+    lines.push(`repair: webstir ${result.repair.command} ${result.repair.args.join(' ')}`);
+  }
+
+  return lines.join('\n');
+}
+
+export function formatDoctorJson(result: DoctorResult): string {
+  return JSON.stringify(
+    {
+      command: 'doctor',
+      workspace: {
+        name: result.workspace.name,
+        mode: result.workspace.mode,
+        root: result.workspace.root,
+      },
+      healthy: result.healthy,
+      checks: result.checks,
+      issues: result.issues,
+      repair: result.repair,
+      ...(result.backend ? { backend: result.backend } : {}),
+    },
+    null,
+    2,
+  );
+}
+
+export function formatFrontendInspectSummary(result: FrontendInspectResult): string {
+  const enabledFeatures = listEnabledFlags(result.frontend.packageJson.enable.known);
+  const lines = [
+    '[webstir] frontend-inspect complete',
+    `workspace: ${result.workspace.name}`,
+    `mode: ${result.workspace.mode}`,
+    `root: ${result.workspace.root}`,
+    `app-shell: ${result.frontend.appShell.exists ? 'present' : 'missing'}`,
+    `frontend-features: ${enabledFeatures.length > 0 ? enabledFeatures.join(', ') : 'none'}`,
+    `pages: ${result.frontend.pages.length}`,
+  ];
+
+  for (const page of result.frontend.pages) {
+    const details = [
+      page.htmlExists ? 'html' : undefined,
+      page.stylesheetExists ? 'css' : undefined,
+      page.scriptExists ? 'script' : undefined,
+    ].filter(Boolean);
+    lines.push(`  - ${page.name}${details.length > 0 ? ` (${details.join(', ')})` : ''}`);
+  }
+
+  lines.push(`content-root: ${result.frontend.content.root}`);
+  lines.push(`content-present: ${result.frontend.content.exists ? 'true' : 'false'}`);
+  lines.push(
+    `content-sidebar-override: ${result.frontend.content.sidebarOverrideExists ? 'true' : 'false'}`,
+  );
+
+  return lines.join('\n');
+}
+
+export function formatFrontendInspectJson(result: FrontendInspectResult): string {
+  return JSON.stringify(
+    {
+      command: 'frontend-inspect',
+      workspace: {
+        name: result.workspace.name,
+        mode: result.workspace.mode,
+        root: result.workspace.root,
+      },
+      frontend: result.frontend,
+    },
+    null,
+    2,
+  );
+}
+
+export function formatInspectSummary(result: InspectResult): string {
+  const lines = [
+    '[webstir] inspect complete',
+    `workspace: ${result.workspace.name}`,
+    `mode: ${result.workspace.mode}`,
+    `root: ${result.workspace.root}`,
+    `success: ${result.success ? 'true' : 'false'}`,
+    `steps: ${result.steps.length}`,
+  ];
+
+  for (const step of result.steps) {
+    lines.push(`  - ${step.id}: ${step.status} (${step.summary})`);
+  }
+
+  return lines.join('\n');
+}
+
+export function formatInspectJson(result: InspectResult): string {
+  return JSON.stringify(
+    {
+      command: 'inspect',
+      workspace: {
+        name: result.workspace.name,
+        mode: result.workspace.mode,
+        root: result.workspace.root,
+      },
+      success: result.success,
+      steps: result.steps,
+      doctor: result.doctor,
+      ...(result.frontend ? { frontend: result.frontend } : {}),
+      ...(result.backend ? { backend: result.backend } : {}),
+    },
+    null,
+    2,
+  );
+}
+
+export function formatAgentSummary(result: AgentResult): string {
+  const lines = [
+    '[webstir] agent complete',
+    `goal: ${result.goal}`,
+    `root: ${result.workspaceRoot}`,
+    `success: ${result.success ? 'true' : 'false'}`,
+    `steps: ${result.steps.length}`,
+  ];
+
+  for (const step of result.steps) {
+    lines.push(`  - ${step.id}: ${step.status} (${step.summary})`);
+  }
+
+  return lines.join('\n');
+}
+
+function listEnabledFlags(flags: object): string[] {
+  return Object.entries(flags)
+    .filter(([, enabled]) => enabled === true)
+    .map(([name]) => name);
+}
+
+export function formatAgentJson(result: AgentResult): string {
+  return JSON.stringify(
+    {
+      command: 'agent',
+      ...result,
+    },
+    null,
+    2,
+  );
+}
+
 export function formatBackendInspectSummary(result: BackendInspectResult): string {
   const lines = [
     '[webstir] backend-inspect complete',
@@ -82,6 +314,12 @@ export function formatBackendInspectSummary(result: BackendInspectResult): strin
     lines.push(`  - ${route.method} ${route.path}${route.name ? ` (${route.name})` : ''}`);
   }
 
+  const views = result.manifest.views ?? [];
+  lines.push(`views: ${views.length}`);
+  for (const view of views) {
+    lines.push(`  - ${view.path}${view.name ? ` (${view.name})` : ''}`);
+  }
+
   const jobs = result.manifest.jobs ?? [];
   lines.push(`jobs: ${jobs.length}`);
   for (const job of jobs) {
@@ -95,9 +333,38 @@ export function formatBackendInspectSummary(result: BackendInspectResult): strin
     lines.push(`  - ${job.name}${details.length > 0 ? ` (${details.join(', ')})` : ''}`);
   }
 
+  const migrations = result.data.migrations;
+  lines.push('data-migrations:');
+  lines.push(`  runner: ${migrations.runnerPresent ? 'present' : 'missing'}`);
+  lines.push(
+    `  directory: ${migrations.migrationsDirectoryPresent ? 'present' : 'missing'} (${migrations.migrationsDirectory})`,
+  );
+  lines.push(`  files: ${migrations.migrationFilesCount}`);
+  lines.push(`  example: ${migrations.exampleMigrationPresent ? 'present' : 'missing'}`);
+  lines.push(`  table-env: ${migrations.tableEnvKey}`);
+  lines.push(`  configured-table: ${migrations.configuredTable}`);
+
   return lines.join('\n');
 }
 
+export function formatBackendInspectJson(result: BackendInspectResult): string {
+  return JSON.stringify(
+    {
+      command: 'backend-inspect',
+      workspace: {
+        name: result.workspace.name,
+        mode: result.workspace.mode,
+        root: result.workspace.root,
+      },
+      buildRoot: result.buildRoot,
+      manifest: result.manifest,
+      data: result.data,
+    },
+    null,
+    2,
+  );
+}
+
 export function formatTestSummary(result: TestCommandResult): string {
   const lines = [
     '[webstir] test complete',
@@ -154,13 +421,9 @@ export function formatAddSummary(
   target: string,
   workspaceRoot: string,
   changes: readonly string[],
-  note?: string
+  note?: string,
 ): string {
-  const lines = [
-    header,
-    `target: ${target}`,
-    `root: ${workspaceRoot}`,
-  ];
+  const lines = [header, `target: ${target}`, `root: ${workspaceRoot}`];
 
   if (changes.length === 0) {
     lines.push('changes: none');
@@ -195,12 +458,12 @@ function formatExecutionSummary(result: CommandExecutionResult): string {
     lines.push(
       `${target.kind}: ${target.result.artifacts.length} artifacts, ` +
         `${target.result.manifest.entryPoints.length} entries, ` +
-        `${target.result.manifest.staticAssets.length} static assets -> ${target.outputRoot}`
+        `${target.result.manifest.staticAssets.length} static assets -> ${target.outputRoot}`,
     );
 
     if (diagnostics.errors > 0 || diagnostics.warnings > 0) {
       lines.push(
-        `${target.kind}: ${diagnostics.errors} error(s), ${diagnostics.warnings} warning(s), ${diagnostics.info} info`
+        `${target.kind}: ${diagnostics.errors} error(s), ${diagnostics.warnings} warning(s), ${diagnostics.info} info`,
       );
     }
   }
@@ -208,17 +471,33 @@ function formatExecutionSummary(result: CommandExecutionResult): string {
   return lines.join('\n');
 }
 
+function formatFailedTests(
+  results: readonly {
+    readonly passed: boolean;
+    readonly file: string;
+    readonly name: string;
+    readonly message?: string | null;
+  }[],
+): string[] {
+  return results
+    .filter((result) => !result.passed)
+    .map(
+      (result) =>
+        `${result.file}: ${result.name}${result.message ? ` — ${firstLine(result.message)}` : ''}`,
+    );
+}
+
+function firstLine(message: string): string {
+  return message.split(/\r?\n/, 1)[0] ?? message;
+}
+
 function formatWorkspaceMutationSummary(
   header: string,
   mode: string,
   workspaceRoot: string,
-  changes: readonly string[]
+  changes: readonly string[],
 ): string {
-  const lines = [
-    header,
-    `mode: ${mode}`,
-    `root: ${workspaceRoot}`,
-  ];
+  const lines = [header, `mode: ${mode}`, `root: ${workspaceRoot}`];
 
   if (changes.length === 0) {
     lines.push('changes: none');

package/src/frontend-inspect.ts

@@ -0,0 +1,32 @@
+import type { FrontendWorkspaceInspectResult } from '@webstir-io/webstir-frontend';
+
+import { inspectFrontendWorkspace } from '@webstir-io/webstir-frontend';
+
+import type { WorkspaceDescriptor } from './types.ts';
+
+import { readWorkspaceDescriptor } from './workspace.ts';
+
+export interface RunFrontendInspectOptions {
+  readonly workspaceRoot: string;
+}
+
+export interface FrontendInspectResult {
+  readonly workspace: WorkspaceDescriptor;
+  readonly frontend: FrontendWorkspaceInspectResult;
+}
+
+export async function runFrontendInspect(
+  options: RunFrontendInspectOptions,
+): Promise<FrontendInspectResult> {
+  const workspace = await readWorkspaceDescriptor(options.workspaceRoot);
+  if (workspace.mode === 'api') {
+    throw new Error(
+      `frontend-inspect only supports spa, ssg, and full workspaces. Received mode "${workspace.mode}".`,
+    );
+  }
+
+  return {
+    workspace,
+    frontend: await inspectFrontendWorkspace(workspace.root),
+  };
+}