@ontrails/trails 1.0.0-beta.2 → 1.0.0-beta.21

package/src/trails/adapter-check.ts

@@ -0,0 +1,244 @@
+/**
+ * `adapter.check` trail -- Local adapter authoring readiness checks.
+ */
+
+import { adapterTargetPlacements, checkAdapters } from '@ontrails/adapter-kit';
+import type { AdapterCheckReport } from '@ontrails/adapter-kit';
+import { isPlainObject, Result, trail, ValidationError } from '@ontrails/core';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { z } from 'zod';
+
+import { resolveTrailRootDir } from './root-dir.js';
+
+const adapterCheckInputSchema = z.object({
+  rootDir: z.string().optional().describe('Root directory to scan'),
+});
+
+const adapterPlacementSchema = z.enum(adapterTargetPlacements);
+
+const adapterCheckDiagnosticSchema = z.object({
+  code: z.string().describe('Stable adapter diagnostic code'),
+  message: z.string(),
+  packageJsonPath: z.string(),
+  packageName: z.string().optional(),
+  placement: adapterPlacementSchema.optional(),
+  severity: z.enum(['error', 'warn']),
+  target: z.string().optional(),
+});
+
+const adapterCheckSubjectSchema = z.object({
+  conformanceTestPaths: z.array(z.string()).readonly(),
+  key: z.string(),
+  ownerPackage: z.string(),
+  packageJsonPath: z.string(),
+  packageName: z.string(),
+  packageRoot: z.string(),
+  placement: adapterPlacementSchema,
+  target: z.string(),
+  targetKey: z.string(),
+  testingImport: z.string().optional(),
+});
+
+const adapterTargetSchema = z.object({
+  conformance: z
+    .object({
+      adapterType: z.string(),
+      casesFactory: z.string(),
+      runner: z.string(),
+    })
+    .optional(),
+  key: z.string(),
+  ownerPackage: z.string(),
+  packageJsonPath: z.string(),
+  packageRoot: z.string(),
+  placements: z.array(adapterPlacementSchema).readonly(),
+  supportExportTarget: z.string().optional(),
+  supportImport: z.string().optional(),
+  target: z.string(),
+  testingExportTarget: z.string().optional(),
+  testingImport: z.string().optional(),
+});
+
+const adapterCheckOutputSchema = z.object({
+  diagnostics: z.array(adapterCheckDiagnosticSchema).readonly(),
+  formatted: z.string(),
+  passed: z.boolean(),
+  subjects: z.array(adapterCheckSubjectSchema).readonly(),
+  targets: z.array(adapterTargetSchema).readonly(),
+});
+
+const relativeToRoot = (rootDir: string, path: string): string => {
+  const normalized = relative(rootDir, path).replaceAll('\\', '/');
+  return normalized.length === 0 || normalized.startsWith('..')
+    ? path
+    : normalized;
+};
+
+const workspacePatternsFromManifest = (
+  manifest: Readonly<Record<string, unknown>>
+): readonly string[] => {
+  const { workspaces } = manifest;
+  if (Array.isArray(workspaces)) {
+    return workspaces.filter(
+      (pattern): pattern is string => typeof pattern === 'string'
+    );
+  }
+
+  const packages = isPlainObject(workspaces)
+    ? workspaces['packages']
+    : undefined;
+  return Array.isArray(packages)
+    ? packages.filter(
+        (pattern): pattern is string => typeof pattern === 'string'
+      )
+    : [];
+};
+
+const readWorkspaceManifest = (
+  packageJsonPath: string
+): Result<Readonly<Record<string, unknown>>, ValidationError> => {
+  try {
+    const parsed = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+    return isPlainObject(parsed)
+      ? Result.ok(parsed)
+      : Result.err(
+          new ValidationError(
+            `adapter.check root package.json must contain a JSON object: "${packageJsonPath}"`
+          )
+        );
+  } catch (error) {
+    return Result.err(
+      new ValidationError(
+        `adapter.check could not read root package.json: "${packageJsonPath}"`,
+        error instanceof Error ? { cause: error } : undefined
+      )
+    );
+  }
+};
+
+const validateAdapterCheckRoot = (
+  rootDir: string
+): Result<void, ValidationError> => {
+  if (!existsSync(rootDir)) {
+    return Result.err(
+      new ValidationError(`adapter.check rootDir does not exist: "${rootDir}"`)
+    );
+  }
+
+  if (!statSync(rootDir).isDirectory()) {
+    return Result.err(
+      new ValidationError(
+        `adapter.check rootDir must be a directory: "${rootDir}"`
+      )
+    );
+  }
+
+  const packageJsonPath = join(rootDir, 'package.json');
+  if (!existsSync(packageJsonPath)) {
+    return Result.err(
+      new ValidationError(
+        `adapter.check rootDir must contain a package.json workspace manifest: "${packageJsonPath}"`
+      )
+    );
+  }
+
+  const manifest = readWorkspaceManifest(packageJsonPath);
+  if (manifest.isErr()) {
+    return Result.err(manifest.error);
+  }
+
+  if (workspacePatternsFromManifest(manifest.value).length === 0) {
+    return Result.err(
+      new ValidationError(
+        `adapter.check root package.json must declare workspace packages: "${packageJsonPath}"`
+      )
+    );
+  }
+
+  return Result.ok();
+};
+
+export const formatAdapterCheckReport = (
+  report: AdapterCheckReport,
+  rootDir: string
+): string => {
+  const passed = report.diagnostics.length === 0;
+  const lines = [
+    '## Adapter Check Report',
+    '',
+    `Result: ${passed ? 'PASS' : 'FAIL'}`,
+    `Targets: ${report.targets.length}`,
+    `Adapters: ${report.subjects.length}`,
+    `Diagnostics: ${report.diagnostics.length}`,
+  ];
+
+  if (report.targets.length > 0) {
+    lines.push('', '### Targets');
+    for (const target of report.targets) {
+      lines.push(
+        `- ${target.key} (${target.placements.join(', ')}) from ${relativeToRoot(rootDir, target.packageJsonPath)}`
+      );
+    }
+  }
+
+  if (report.subjects.length > 0) {
+    lines.push('', '### Adapters');
+    for (const subject of report.subjects) {
+      const conformance =
+        subject.conformanceTestPaths.length === 0
+          ? 'no conformance tests'
+          : `${subject.conformanceTestPaths.length} conformance test(s)`;
+      lines.push(
+        `- ${subject.packageName} -> ${subject.targetKey} (${subject.placement}, ${conformance})`
+      );
+    }
+  }
+
+  if (report.diagnostics.length > 0) {
+    lines.push('', '### Diagnostics');
+    for (const diagnostic of report.diagnostics) {
+      lines.push(
+        `- ${diagnostic.severity.toUpperCase()} ${diagnostic.code} ${relativeToRoot(rootDir, diagnostic.packageJsonPath)}: ${diagnostic.message}`
+      );
+    }
+  }
+
+  return lines.join('\n');
+};
+
+export const adapterCheckTrail = trail('adapter.check', {
+  blaze: (input, ctx) => {
+    const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
+    if (rootDirResult.isErr()) {
+      return rootDirResult;
+    }
+
+    const rootDir = rootDirResult.value;
+    const validRoot = validateAdapterCheckRoot(rootDir);
+    if (validRoot.isErr()) {
+      return validRoot;
+    }
+
+    const report = checkAdapters(rootDir);
+
+    return Result.ok({
+      diagnostics: [...report.diagnostics],
+      formatted: formatAdapterCheckReport(report, rootDir),
+      passed: report.diagnostics.length === 0,
+      subjects: [...report.subjects],
+      targets: [...report.targets],
+    });
+  },
+  description: 'Check adapter authoring readiness',
+  examples: [
+    {
+      input: {},
+      name: 'Check adapters in the current workspace',
+    },
+  ],
+  input: adapterCheckInputSchema,
+  intent: 'read',
+  output: adapterCheckOutputSchema,
+  permit: 'public',
+});

package/src/trails/add-surface.ts

@@ -1,36 +1,66 @@
 /**
  * `add.surface` trail -- Add a surface to an existing project.
  *
- * Generates the CLI or MCP entry point and updates package.json dependencies.
+ * Generates surface entry points and updates package.json dependencies.
  */
 
-import { existsSync, mkdirSync } from 'node:fs';
-import { basename, dirname, join, resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import { basename, resolve } from 'node:path';
 
 import { Result, trail } from '@ontrails/core';
 import { z } from 'zod';
 
+import {
+  projectPathExists,
+  resolveProjectPath,
+  writeProjectFile,
+} from '../project-writes.js';
+import { ontrailsPackageRange } from '../versions.js';
 import { findTopoPath } from './project.js';
 
+type Surface = 'cli' | 'http' | 'mcp';
+
 const generateCliEntry = (appImportPath: string): string =>
-  `import { blaze } from '@ontrails/cli/commander';
+  `import { devPermitPreset, permitPreset } from '@ontrails/cli';
+import { surface } from '@ontrails/commander';
 
 import { app } from '${appImportPath}';
 
-blaze(app);
+await surface(app, {
+  presets: [permitPreset(), devPermitPreset()],
+});
 `;
 
 const generateMcpEntry = (appImportPath: string): string =>
-  `import { blaze } from '@ontrails/mcp';
+  `import { surface } from '@ontrails/mcp';
+
+import { app } from '${appImportPath}';
+
+await surface(app);
+`;
+
+const generateHttpEntry = (appImportPath: string): string =>
+  `import { surface } from '@ontrails/hono';
 
 import { app } from '${appImportPath}';
 
-await blaze(app);
+await surface(app, { port: 3000 });
 `;
 
+const surfaceEntryFiles = {
+  cli: 'src/cli.ts',
+  http: 'src/http.ts',
+  mcp: 'src/mcp.ts',
+} satisfies Record<Surface, string>;
+
+const surfaceDependencies = {
+  cli: ['@ontrails/cli', '@ontrails/commander'],
+  http: ['@ontrails/hono', '@ontrails/http'],
+  mcp: ['@ontrails/mcp'],
+} satisfies Record<Surface, readonly string[]>;
+
 /** Resolve the entry file for a surface. */
-const getEntryFile = (surface: 'cli' | 'mcp'): string =>
-  surface === 'cli' ? 'src/cli.ts' : 'src/mcp.ts';
+const getEntryFile = (surface: Surface): string => surfaceEntryFiles[surface];
 
 // ---------------------------------------------------------------------------
 // Trail definition
@@ -39,14 +69,15 @@ const getEntryFile = (surface: 'cli' | 'mcp'): string =>
 /** Patch deps and optionally bin in a parsed package.json. */
 const patchPkgDeps = (
   pkg: Record<string, unknown>,
-  surface: 'cli' | 'mcp',
+  surface: Surface,
   cwd: string
 ): string => {
-  const depName = surface === 'cli' ? '@ontrails/cli' : '@ontrails/mcp';
+  const [depName = ''] = surfaceDependencies[surface];
   const deps = (pkg['dependencies'] ?? {}) as Record<string, string>;
-  deps[depName] = 'workspace:*';
+  for (const dependency of surfaceDependencies[surface]) {
+    deps[dependency] = ontrailsPackageRange;
+  }
   if (surface === 'cli') {
-    deps['commander'] = '^14.0.0';
     pkg['bin'] = {
       [(pkg['name'] as string | undefined) ?? basename(cwd)]: './src/cli.ts',
     };
@@ -60,60 +91,82 @@ const patchPkgDeps = (
 /** Update package.json with surface dependency and CLI bin if needed. */
 const updatePkgJsonForSurface = async (
   cwd: string,
-  surface: 'cli' | 'mcp'
-): Promise<string> => {
-  const pkgPath = join(cwd, 'package.json');
+  surface: Surface
+): Promise<Result<string, Error>> => {
+  const pkgPathResult = resolveProjectPath(cwd, 'package.json');
+  if (pkgPathResult.isErr()) {
+    return Result.err(pkgPathResult.error);
+  }
+
+  const pkgPath = pkgPathResult.value;
   if (!existsSync(pkgPath)) {
-    return surface === 'cli' ? '@ontrails/cli' : '@ontrails/mcp';
+    return Result.ok(surfaceDependencies[surface][0] ?? '');
   }
   const pkg = (await Bun.file(pkgPath).json()) as Record<string, unknown>;
   const depName = patchPkgDeps(pkg, surface, cwd);
-  await Bun.write(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
-  return depName;
+  const written = await writeProjectFile(
+    cwd,
+    'package.json',
+    `${JSON.stringify(pkg, null, 2)}\n`
+  );
+  return written.isErr() ? Result.err(written.error) : Result.ok(depName);
 };
 
 /** Create the entry file for a surface and return the relative path. */
 const writeSurfaceEntry = async (
   cwd: string,
-  surface: 'cli' | 'mcp'
-): Promise<string> => {
+  surface: Surface
+): Promise<Result<string, Error>> => {
   const entryFile = getEntryFile(surface);
-  const fullEntryPath = join(cwd, entryFile);
   const appImport = (await findTopoPath(cwd)) ?? './app.js';
-  const content =
-    surface === 'cli'
-      ? generateCliEntry(appImport)
-      : generateMcpEntry(appImport);
-
-  mkdirSync(dirname(fullEntryPath), { recursive: true });
-  await Bun.write(fullEntryPath, content);
-  return entryFile;
+  const generators = {
+    cli: generateCliEntry,
+    http: generateHttpEntry,
+    mcp: generateMcpEntry,
+  } satisfies Record<Surface, (appImportPath: string) => string>;
+  const content = generators[surface](appImport);
+
+  const written = await writeProjectFile(cwd, entryFile, content);
+  return written.isErr() ? Result.err(written.error) : Result.ok(entryFile);
 };
 
 export const addSurface = trail('add.surface', {
-  description: 'Add a surface to an existing project',
-  implementation: async (input) => {
+  blaze: async (input) => {
     const cwd = resolve(input.dir ?? '.');
     const { surface } = input;
     const entryFile = getEntryFile(surface);
+    const entryExists = projectPathExists(cwd, entryFile);
+    if (entryExists.isErr()) {
+      return entryExists;
+    }
+
+    let created: string | null = null;
+    if (!entryExists.value) {
+      const written = await writeSurfaceEntry(cwd, surface);
+      if (written.isErr()) {
+        return written;
+      }
+      created = entryFile;
+    }
 
-    if (existsSync(join(cwd, entryFile))) {
-      return Result.err(
-        new Error(`${surface.toUpperCase()} is already blazed. Nothing to do.`)
-      );
+    const dependency = await updatePkgJsonForSurface(cwd, surface);
+    if (dependency.isErr()) {
+      return dependency;
     }
 
     return Result.ok({
-      created: await writeSurfaceEntry(cwd, surface),
-      dependency: await updatePkgJsonForSurface(cwd, surface),
+      created,
+      dependency: dependency.value,
     });
   },
+  description: 'Add a surface to an existing project',
   input: z.object({
     dir: z.string().optional().describe('Project directory'),
-    surface: z.enum(['cli', 'mcp']).describe('Surface to add'),
+    surface: z.enum(['cli', 'http', 'mcp']).describe('Surface to add'),
   }),
   output: z.object({
-    created: z.string(),
+    created: z.string().nullable(),
     dependency: z.string(),
   }),
+  permit: { scopes: ['project:write'] },
 });

package/src/trails/add-trail.ts

@@ -2,58 +2,73 @@
  * `add.trail` trail -- Scaffold a new trail file with tests.
  */
 
-import { mkdirSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { resolve } from 'node:path';
 
 import { Result, trail } from '@ontrails/core';
 import { z } from 'zod';
 
+import {
+  trailIdToExportName,
+  trailIdToModuleName,
+  TRAIL_ID_MESSAGE,
+  TRAIL_ID_PATTERN,
+  validateTrailId,
+  writeProjectFile,
+} from '../project-writes.js';
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
+const literal = (value: string): string => JSON.stringify(value);
+
+const deriveExampleMessage = (id: string): string => `${id} completed`;
+
 const generateTrailFile = (
   id: string,
-  readOnly: boolean,
-  destructive: boolean
+  description: string,
+  exampleName: string,
+  intent: 'read' | 'write' | 'destroy'
 ): string => {
-  const markers: string[] = [];
-  if (readOnly) {
-    markers.push('  readOnly: true,');
-  }
-  if (destructive) {
-    markers.push('  destructive: true,');
-  }
-  const markerBlock = markers.length > 0 ? `\n${markers.join('\n')}` : '';
+  const intentLine =
+    intent === 'write' ? '' : `\n  intent: ${literal(intent)},`;
+  const exampleMessage = deriveExampleMessage(id);
+  const trailName = trailIdToExportName(id);
 
   return `import { Result, trail } from '@ontrails/core';
 import { z } from 'zod';
 
-export const ${id.replaceAll('.', '_')} = trail('${id}', {
-  description: 'TODO: describe this trail',
+export const ${trailName} = trail(${literal(id)}, {
+  blaze: async () => {
+    return Result.ok({ message: ${literal(exampleMessage)} });
+  },
+  description: ${literal(description)},
   examples: [
     {
+      expected: { message: ${literal(exampleMessage)} },
       input: {},
-      name: 'TODO: add example',
+      name: ${literal(exampleName)},
     },
   ],
-  implementation: async (input) => {
-    return Result.ok({ message: 'TODO' });
-  },
-  input: z.object({}),${markerBlock}
+  input: z.object({}),${intentLine}
   output: z.object({ message: z.string() }),
 });
 `;
 };
 
-const generateTestFile = (id: string): string => {
-  const moduleName = id.replaceAll('.', '-');
-  const trailName = id.replaceAll('.', '_');
+const generateTestFile = (id: string, exampleName: string): string => {
+  const moduleName = trailIdToModuleName(id);
+  const trailName = trailIdToExportName(id);
+  const exampleMessage = deriveExampleMessage(id);
   return `import { testTrail } from '@ontrails/testing';
 import { ${trailName} } from '../src/trails/${moduleName}.js';
 
 testTrail(${trailName}, [
-  { description: 'basic test', input: {}, expectOk: true },
+  {
+    description: ${literal(exampleName)},
+    expectValue: { message: ${literal(exampleMessage)} },
+    input: {},
+  },
 ]);
 `;
 };
@@ -62,42 +77,65 @@ testTrail(${trailName}, [
 // Trail definition
 // ---------------------------------------------------------------------------
 
-/** Write a file, creating parent directories as needed. */
-const writeWithDirs = async (
-  filePath: string,
-  content: string
-): Promise<void> => {
-  mkdirSync(dirname(filePath), { recursive: true });
-  await Bun.write(filePath, content);
-};
-
 export const addTrail = trail('add.trail', {
-  description: 'Scaffold a new trail with tests and examples',
-  implementation: async (input, ctx) => {
+  args: ['id'],
+  blaze: async (input, ctx) => {
     const { id } = input;
-    const moduleName = id.replaceAll('.', '-');
+    const validated = validateTrailId(id);
+    if (validated.isErr()) {
+      return validated;
+    }
+
+    const moduleName = trailIdToModuleName(validated.value);
     const cwd = resolve(ctx.cwd ?? '.');
 
     const files = new Map<string, string>([
       [
         `src/trails/${moduleName}.ts`,
-        generateTrailFile(id, input.readOnly, input.destructive),
+        generateTrailFile(
+          id,
+          input.description,
+          input.exampleName,
+          input.intent
+        ),
+      ],
+      [
+        `__tests__/${moduleName}.test.ts`,
+        generateTestFile(id, input.exampleName),
       ],
-      [`__tests__/${moduleName}.test.ts`, generateTestFile(id)],
     ]);
 
     for (const [relativePath, content] of files) {
-      await writeWithDirs(join(cwd, relativePath), content);
+      const written = await writeProjectFile(cwd, relativePath, content);
+      if (written.isErr()) {
+        return written;
+      }
     }
 
     return Result.ok({ created: [...files.keys()] });
   },
+  description: 'Scaffold a new trail with tests and examples',
   input: z.object({
-    destructive: z.boolean().default(false).describe('Destructive trail'),
-    id: z.string().describe('Trail ID (e.g., entity.update)'),
-    readOnly: z.boolean().default(false).describe('Read-only trail'),
+    description: z
+      .string()
+      .min(1, 'Trail description is required')
+      .describe('Trail description'),
+    exampleName: z
+      .string()
+      .min(1, 'Starter example name is required')
+      .describe('Starter example name'),
+    id: z
+      .string()
+      .min(1, 'Trail ID is required')
+      .regex(TRAIL_ID_PATTERN, TRAIL_ID_MESSAGE)
+      .describe('Trail ID (e.g., entity.update)'),
+    intent: z
+      .enum(['read', 'write', 'destroy'])
+      .default('write')
+      .describe('Trail intent'),
   }),
   output: z.object({
     created: z.array(z.string()),
   }),
+  permit: { scopes: ['project:write'] },
 });