@ontrails/trails 1.0.0-beta.18 → 1.0.0-beta.19

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

@@ -7,7 +7,7 @@
 import { existsSync } from 'node:fs';
 import { basename, resolve } from 'node:path';
 
-import { AlreadyExistsError, Result, trail } from '@ontrails/core';
+import { Result, trail } from '@ontrails/core';
 import { z } from 'zod';
 
 import {
@@ -21,11 +21,14 @@ import { findTopoPath } from './project.js';
 type Surface = 'cli' | 'http' | 'mcp';
 
 const generateCliEntry = (appImportPath: string): string =>
-  `import { surface } from '@ontrails/commander';
+  `import { devPermitPreset, permitPreset } from '@ontrails/cli';
+import { surface } from '@ontrails/commander';
 
 import { app } from '${appImportPath}';
 
-await surface(app);
+await surface(app, {
+  presets: [permitPreset(), devPermitPreset()],
+});
 `;
 
 const generateMcpEntry = (appImportPath: string): string =>
@@ -134,29 +137,25 @@ export const addSurface = trail('add.surface', {
     const entryFile = getEntryFile(surface);
     const entryExists = projectPathExists(cwd, entryFile);
     if (entryExists.isErr()) {
-      return Result.err(entryExists.error);
-    }
-
-    if (entryExists.value) {
-      return Result.err(
-        new AlreadyExistsError(
-          `${surface.toUpperCase()} surface already exists. Nothing to do.`
-        )
-      );
+      return entryExists;
     }
 
-    const created = await writeSurfaceEntry(cwd, surface);
-    if (created.isErr()) {
-      return Result.err(created.error);
+    let created: string | null = null;
+    if (!entryExists.value) {
+      const written = await writeSurfaceEntry(cwd, surface);
+      if (written.isErr()) {
+        return written;
+      }
+      created = entryFile;
     }
 
     const dependency = await updatePkgJsonForSurface(cwd, surface);
     if (dependency.isErr()) {
-      return Result.err(dependency.error);
+      return dependency;
     }
 
     return Result.ok({
-      created: created.value,
+      created,
       dependency: dependency.value,
     });
   },
@@ -166,7 +165,8 @@ export const addSurface = trail('add.surface', {
     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

@@ -83,7 +83,7 @@ export const addTrail = trail('add.trail', {
     const { id } = input;
     const validated = validateTrailId(id);
     if (validated.isErr()) {
-      return Result.err(validated.error);
+      return validated;
     }
 
     const moduleName = trailIdToModuleName(validated.value);
@@ -108,7 +108,7 @@ export const addTrail = trail('add.trail', {
     for (const [relativePath, content] of files) {
       const written = await writeProjectFile(cwd, relativePath, content);
       if (written.isErr()) {
-        return Result.err(written.error);
+        return written;
       }
     }
 
@@ -137,4 +137,5 @@ export const addTrail = trail('add.trail', {
   output: z.object({
     created: z.array(z.string()),
   }),
+  permit: { scopes: ['project:write'] },
 });

package/src/trails/add-verify.ts

@@ -10,6 +10,7 @@ import { z } from 'zod';
 import {
   PROJECT_NAME_MESSAGE,
   PROJECT_NAME_PATTERN,
+  projectPathExists,
   resolveProjectDir,
   resolveProjectPath,
   writeProjectFile,
@@ -24,10 +25,24 @@ import {
 // ---------------------------------------------------------------------------
 
 const generateTestFile = (): string =>
-  `import { testAllEstablished } from '@ontrails/testing';
+  `import { testAllEstablished } from '@ontrails/testing/established';
 import { app } from '../src/app.js';
 
-testAllEstablished(app);
+const permitScopes = [
+  ...new Set(
+    app
+      .list()
+      .flatMap((trail) =>
+        trail.permit && trail.permit !== 'public' ? trail.permit.scopes : []
+      )
+  ),
+];
+
+testAllEstablished(app, {
+  ctx: {
+    permit: { id: 'test-permit', scopes: permitScopes },
+  },
+});
 `;
 
 const generateLefthookYml = (): string =>
@@ -79,7 +94,7 @@ export const addVerify = trail('add.verify', {
   blaze: async (input) => {
     const projectDirResult = resolveProjectDir(input.dir ?? '.', input.name);
     if (projectDirResult.isErr()) {
-      return Result.err(projectDirResult.error);
+      return projectDirResult;
     }
 
     const projectDir = projectDirResult.value;
@@ -89,6 +104,14 @@ export const addVerify = trail('add.verify', {
       relativePath: string,
       content: string
     ): Promise<Result<void, Error>> => {
+      const exists = projectPathExists(projectDir, relativePath);
+      if (exists.isErr()) {
+        return Result.err(exists.error);
+      }
+      if (exists.value) {
+        return Result.ok();
+      }
+
       const written = await writeProjectFile(projectDir, relativePath, content);
       if (written.isErr()) {
         return Result.err(written.error);
@@ -102,17 +125,17 @@ export const addVerify = trail('add.verify', {
       generateTestFile()
     );
     if (testFile.isErr()) {
-      return Result.err(testFile.error);
+      return testFile;
     }
 
     const lefthookFile = await writeFile('lefthook.yml', generateLefthookYml());
     if (lefthookFile.isErr()) {
-      return Result.err(lefthookFile.error);
+      return lefthookFile;
     }
 
     const packageResult = await updatePackageJsonForVerify(projectDir);
     if (packageResult.isErr()) {
-      return Result.err(packageResult.error);
+      return packageResult;
     }
 
     return Result.ok({ created: files });
@@ -128,5 +151,6 @@ export const addVerify = trail('add.verify', {
   output: z.object({
     created: z.array(z.string()),
   }),
+  permit: { scopes: ['project:write'] },
   visibility: 'internal',
 });

package/src/trails/{topo-compile.ts → compile.ts}

@@ -1,5 +1,5 @@
-import { Result, trail } from '@ontrails/core';
-import type { Topo } from '@ontrails/core';
+import { trail } from '@ontrails/core';
+import type { Result, Topo } from '@ontrails/core';
 import { z } from 'zod';
 
 import { tryLoadFreshAppLease } from './load-app.js';
@@ -13,23 +13,26 @@ import {
 
 export const compileCurrentTopo = async (
   app: Topo,
-  options?: { readonly rootDir?: string }
+  options?: { readonly force?: boolean | undefined; readonly rootDir?: string }
 ): Promise<Result<TopoExportReport, Error>> => exportCurrentTopo(app, options);
 
-export const topoCompileTrail = trail('topo.compile', {
+export const compileTrail = trail('compile', {
   blaze: async (input, ctx) => {
     const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
     if (rootDirResult.isErr()) {
-      return Result.err(rootDirResult.error);
+      return rootDirResult;
     }
     const rootDir = rootDirResult.value;
     const leaseResult = await tryLoadFreshAppLease(input.module, rootDir);
     if (leaseResult.isErr()) {
-      return Result.err(leaseResult.error);
+      return leaseResult;
     }
     const lease = leaseResult.value;
     try {
-      return await compileCurrentTopo(lease.app, { rootDir });
+      return await compileCurrentTopo(lease.app, {
+        force: input.force,
+        rootDir,
+      });
     } finally {
       lease.release();
     }
@@ -37,11 +40,15 @@ export const topoCompileTrail = trail('topo.compile', {
   description: 'Compile the current topo to .trails artifacts',
   examples: [
     {
-      input: createIsolatedExampleInput('topo-compile'),
+      input: createIsolatedExampleInput('compile'),
       name: 'Compile the current topo artifacts',
     },
   ],
   input: z.object({
+    force: z
+      .boolean()
+      .optional()
+      .describe('Record graph-only force events for breaking changes'),
     module: z.string().optional().describe('Path to the app module'),
     rootDir: z.string().optional().describe('Workspace root directory'),
   }),
@@ -52,4 +59,5 @@ export const topoCompileTrail = trail('topo.compile', {
     snapshot: topoSnapshotOutput,
     topoPath: z.string(),
   }),
+  permit: { scopes: ['topo:write'] },
 });

package/src/trails/completions-complete.ts

@@ -121,7 +121,7 @@ export const completionsCompleteTrail = trail('completions.__complete', {
   blaze: async (input, ctx) => {
     const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
     if (rootDirResult.isErr()) {
-      return Result.err(rootDirResult.error);
+      return rootDirResult;
     }
     const rootDir = rootDirResult.value;