@ontrails/trails 1.0.0-beta.24 → 1.0.0-beta.29

package/src/run-completions-install.ts

@@ -100,7 +100,7 @@ export const runCompletionsInstall = async (
 ): Promise<Result<CompletionsInstallResult, Error>> => {
   const shellResult = resolveTargetShell(options);
   if (shellResult.isErr()) {
-    return Result.err(shellResult.error);
+    return shellResult;
   }
 
   const shell = shellResult.value;
@@ -111,7 +111,7 @@ export const runCompletionsInstall = async (
     options.binName ?? COMPLETIONS_BIN_NAME
   );
   if (scriptResult.isErr()) {
-    return Result.err(scriptResult.error);
+    return scriptResult;
   }
 
   let existed: boolean;

package/src/run-schema.ts

@@ -0,0 +1,41 @@
+import type { CliCommand } from '@ontrails/cli';
+import { deriveCliSchema, findCliSchemaCommand } from '@ontrails/cli';
+import type { Command } from 'commander';
+
+const normalizeCommandPath = (path: readonly string[] | undefined): string[] =>
+  (path ?? []).flatMap((segment) =>
+    segment
+      .trim()
+      .split(/\s+/)
+      .filter((part) => part.length > 0)
+  );
+
+const writeJson = (value: unknown): void => {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+};
+
+export const attachSchemaCommand = (
+  program: Command,
+  commands: readonly CliCommand[]
+): void => {
+  const schema = deriveCliSchema(commands);
+  program
+    .command('schema [command...]')
+    .description('Inspect accepted CLI command contracts as JSON')
+    .action((commandPath: string[] | undefined) => {
+      const path = normalizeCommandPath(commandPath);
+      if (path.length === 0) {
+        writeJson(schema);
+        return;
+      }
+
+      const command = findCliSchemaCommand(schema, path);
+      if (command === undefined) {
+        process.stderr.write(`Unknown CLI command: ${path.join(' ')}\n`);
+        process.exitCode = 1;
+        return;
+      }
+
+      writeJson({ command });
+    });
+};

package/src/run-wayfind-outline.ts

@@ -0,0 +1,166 @@
+import { deriveOutputMode, output } from '@ontrails/cli';
+import type { ActionResultContext } from '@ontrails/cli';
+import { outlineOutputSchema } from '@ontrails/wayfinder';
+import type { OutlineFeature, OutlineOutput } from '@ontrails/wayfinder';
+
+const includesFeature = (
+  outline: OutlineOutput,
+  feature: OutlineFeature
+): boolean => outline.features.included.includes(feature);
+
+const formatLine = (
+  line: number,
+  kind: string,
+  name: string,
+  suffix = ''
+): string => `${line.toString().padStart(4, ' ')}: ${kind} ${name}${suffix}`;
+
+const appendGraphCount = (lines: string[], outline: OutlineOutput): void => {
+  if (
+    includesFeature(outline, 'graph') &&
+    outline.counts.graphMatches !== undefined
+  ) {
+    lines.push(`  graph matches: ${outline.counts.graphMatches.toString()}`);
+  }
+};
+
+const appendDiagnosticCount = (
+  lines: string[],
+  outline: OutlineOutput
+): void => {
+  if (
+    includesFeature(outline, 'diagnostics') &&
+    outline.counts.diagnostics > 0
+  ) {
+    lines.push(`  diagnostics: ${outline.counts.diagnostics.toString()}`);
+  }
+};
+
+const appendSourceDeclarations = (
+  lines: string[],
+  outline: OutlineOutput
+): void => {
+  if (!includesFeature(outline, 'source')) {
+    return;
+  }
+  const declarations = outline.source?.declarations ?? [];
+  if (declarations.length === 0) {
+    return;
+  }
+  lines.push('');
+  for (const declaration of declarations.slice(0, 40)) {
+    lines.push(
+      formatLine(declaration.line, declaration.kind, declaration.name)
+    );
+  }
+};
+
+type TrailOutline = NonNullable<OutlineOutput['trails']>[number];
+
+const contractFactLabel = (
+  contracts: TrailOutline['contracts']
+): string | undefined => {
+  if (contracts === undefined) {
+    return undefined;
+  }
+  if (contracts.input && contracts.output) {
+    return 'input+output';
+  }
+  if (contracts.input) {
+    return 'input';
+  }
+  if (contracts.output) {
+    return 'output';
+  }
+  return 'no schemas';
+};
+
+const exampleCountLabel = (count: number): string =>
+  `${count.toString()} ${count === 1 ? 'example' : 'examples'}`;
+
+const trailFactSuffix = (trail: TrailOutline): string => {
+  const facts = [
+    trail.graph?.intent,
+    contractFactLabel(trail.contracts),
+    trail.graph === undefined
+      ? undefined
+      : exampleCountLabel(trail.graph.exampleCount),
+  ].filter((fact): fact is string => fact !== undefined);
+
+  return facts.length === 0 ? '' : ` (${facts.join(', ')})`;
+};
+
+const appendTrails = (lines: string[], outline: OutlineOutput): void => {
+  if (!includesFeature(outline, 'trails')) {
+    return;
+  }
+  const trails = outline.trails ?? [];
+  if (trails.length === 0) {
+    return;
+  }
+  lines.push('');
+  for (const trail of trails) {
+    lines.push(
+      formatLine(trail.line, 'trail', trail.id, trailFactSuffix(trail))
+    );
+  }
+};
+
+const appendApps = (lines: string[], outline: OutlineOutput): void => {
+  if (!includesFeature(outline, 'apps')) {
+    return;
+  }
+  const apps = outline.apps ?? [];
+  if (apps.length === 0) {
+    return;
+  }
+  lines.push('');
+  for (const app of apps) {
+    lines.push(formatLine(app.line, 'app', app.name, ` (${app.callee})`));
+  }
+};
+
+const appendDiagnostics = (lines: string[], outline: OutlineOutput): void => {
+  if (!includesFeature(outline, 'diagnostics')) {
+    return;
+  }
+  for (const diagnostic of outline.diagnostics ?? []) {
+    lines.push(
+      `  ${diagnostic.severity}: ${diagnostic.code}: ${diagnostic.message}`
+    );
+  }
+};
+
+export const formatWayfindOutlineText = (outline: OutlineOutput): string => {
+  const lines = [
+    outline.file,
+    `  trails: ${outline.counts.trails.toString()}`,
+    `  apps: ${outline.counts.apps.toString()}`,
+    `  declarations: ${outline.counts.declarations.toString()}`,
+  ];
+
+  appendGraphCount(lines, outline);
+  appendDiagnosticCount(lines, outline);
+  appendSourceDeclarations(lines, outline);
+  appendTrails(lines, outline);
+  appendApps(lines, outline);
+  appendDiagnostics(lines, outline);
+
+  return lines.join('\n');
+};
+
+export const tryWayfindOutlineOutput = (ctx: ActionResultContext): boolean => {
+  if (ctx.trail.id !== 'wayfind.outline' || ctx.result.isErr()) {
+    return false;
+  }
+  const { mode } = deriveOutputMode(ctx.flags, ctx.topoName);
+  if (mode !== 'text') {
+    return false;
+  }
+  const parsed = outlineOutputSchema.safeParse(ctx.result.value);
+  if (!parsed.success) {
+    return false;
+  }
+  output(formatWayfindOutlineText(parsed.data), mode);
+  return true;
+};

package/src/trails/adapter-check.ts

@@ -145,7 +145,7 @@ const validateAdapterCheckRoot = (
 
   const manifest = readWorkspaceManifest(packageJsonPath);
   if (manifest.isErr()) {
-    return Result.err(manifest.error);
+    return manifest;
   }
 
   if (workspacePatternsFromManifest(manifest.value).length === 0) {

package/src/trails/add-surface.ts

@@ -96,7 +96,7 @@ const updatePkgJsonForSurface = async (
 ): Promise<Result<string, Error>> => {
   const pkgPathResult = resolveProjectPath(cwd, 'package.json');
   if (pkgPathResult.isErr()) {
-    return Result.err(pkgPathResult.error);
+    return pkgPathResult;
   }
 
   const pkgPath = pkgPathResult.value;

package/src/trails/add-verify.ts

@@ -70,7 +70,7 @@ const updatePackageJsonForVerify = async (
 ): Promise<Result<void, Error>> => {
   const pkgPathResult = resolveProjectPath(projectDir, 'package.json');
   if (pkgPathResult.isErr()) {
-    return Result.err(pkgPathResult.error);
+    return pkgPathResult;
   }
 
   const pkgPath = pkgPathResult.value;
@@ -107,7 +107,7 @@ export const addVerify = trail('add.verify', {
     ): Promise<Result<void, Error>> => {
       const exists = projectPathExists(projectDir, relativePath);
       if (exists.isErr()) {
-        return Result.err(exists.error);
+        return exists;
       }
       if (exists.value) {
         return Result.ok();
@@ -115,7 +115,7 @@ export const addVerify = trail('add.verify', {
 
       const written = await writeProjectFile(projectDir, relativePath, content);
       if (written.isErr()) {
-        return Result.err(written.error);
+        return written;
       }
       files.push(written.value);
       return Result.ok();

package/src/trails/compile.ts

@@ -1,9 +1,8 @@
 import { trail } from '@ontrails/core';
-import type { Result, Topo } from '@ontrails/core';
+import type { CliCommandAliasInput, Result, Topo } from '@ontrails/core';
 import { z } from 'zod';
 
-import { tryLoadFreshAppLease } from './load-app.js';
-import { resolveTrailRootDir } from './root-dir.js';
+import { withFreshOperatorApp } from './operator-context.js';
 import { exportCurrentTopo } from './topo-store-support.js';
 import type { TopoExportReport } from './topo-support.js';
 import {
@@ -13,7 +12,13 @@ import {
 
 export const compileCurrentTopo = async (
   app: Topo,
-  options?: { readonly force?: boolean | undefined; readonly rootDir?: string }
+  options?: {
+    readonly cliAliases?:
+      | Readonly<Record<string, readonly CliCommandAliasInput[]>>
+      | undefined;
+    readonly force?: boolean | undefined;
+    readonly rootDir?: string;
+  }
 ): Promise<Result<TopoExportReport, Error>> => exportCurrentTopo(app, options);
 
 const compileTrailInputSchema = z.object({
@@ -28,31 +33,19 @@ const compileTrailInputSchema = z.object({
 type CompileTrailInput = z.output<typeof compileTrailInputSchema>;
 
 export const compileTrail = trail('compile', {
-  blaze: async (input: CompileTrailInput, ctx) => {
-    const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
-    if (rootDirResult.isErr()) {
-      return rootDirResult;
-    }
-    const rootDir = rootDirResult.value;
-    const leaseResult = await tryLoadFreshAppLease(input.module, rootDir);
-    if (leaseResult.isErr()) {
-      return leaseResult;
-    }
-    const lease = leaseResult.value;
-    try {
-      return await compileCurrentTopo(lease.app, {
+  blaze: async (input: CompileTrailInput, ctx) =>
+    withFreshOperatorApp(input, ctx, ({ lease, rootDir }) =>
+      compileCurrentTopo(lease.app, {
+        cliAliases: lease.cliAliases,
         force: input.force,
         rootDir,
-      });
-    } finally {
-      lease.release();
-    }
-  },
-  description: 'Compile the current topo to .trails artifacts',
+      })
+    ),
+  description: 'Compile the current topo to trails.lock',
   examples: [
     {
       input: createIsolatedExampleInput('compile'),
-      name: 'Compile the current topo artifacts',
+      name: 'Compile the current topo to trails.lock',
     },
   ],
   input: compileTrailInputSchema,
@@ -61,7 +54,6 @@ export const compileTrail = trail('compile', {
     hash: z.string(),
     lockPath: z.string(),
     snapshot: topoSnapshotOutput,
-    topoPath: z.string(),
   }),
   permit: { scopes: ['topo:write'] },
 });

package/src/trails/create-scaffold.ts

@@ -1,12 +1,13 @@
 /**
  * `create.scaffold` trail -- Creates base project structure.
  *
- * Generates package.json, tsconfig, app.ts, starter trails, and .trails/ directory.
+ * Generates package.json, tsconfig, app.ts, starter trails, and scaffold provenance.
  */
 
 import { resolve } from 'node:path';
 
-import { Result, trail, WORKSPACE_GITIGNORE_CONTENT } from '@ontrails/core';
+import { Result, trail } from '@ontrails/core';
+import type { Result as TrailsResult } from '@ontrails/core';
 import { z } from 'zod';
 
 import {
@@ -168,7 +169,7 @@ bun run guide
 - \`compose\`, not follow
 - \`surface\`, not transport
 - \`resource\`, not service or dependency
-- \`layer\`, for compose-cutting trail wrapping
+- \`layer\`, for cross-cutting trail wrapping
 
 ## Trail Rules
 
@@ -196,10 +197,7 @@ Keep shared project guidance in \`./AGENTS.md\`. Only Claude-specific bootstrap
 const GITIGNORE_CONTENT = `node_modules/
 dist/
 *.tsbuildinfo
-.trails/cache/
-.trails/state/
-.trails/config.local.js
-.trails/config.local.ts
+trails.config.local.*
 `;
 
 const OXLINT_CONFIG_CONTENT = `import { defineConfig } from 'oxlint';
@@ -552,7 +550,6 @@ const collectScaffoldFiles = (
     ['.gitignore', GITIGNORE_CONTENT],
     ['oxlint.config.ts', OXLINT_CONFIG_CONTENT],
     ['.oxfmtrc.jsonc', OXFMTRC_CONTENT],
-    ['.trails/.gitignore', WORKSPACE_GITIGNORE_CONTENT],
     ['.trails/scaffold.json', generateScaffoldProvenance(starter)],
     ['src/app.ts', generateAppTs(name, starter)],
     ...starterFileGenerators[starter](),
@@ -583,13 +580,16 @@ export const createScaffold = trail('create.scaffold', {
     const dryRun = input.dryRun === true;
     const fileMap = collectScaffoldFiles(input.name, starter);
     const operations = collectScaffoldOperations(fileMap);
-    const plannedOperations = dryRun
-      ? planProjectOperations(projectDir, operations, { existing: 'preserve' })
-      : await applyProjectOperations(projectDir, operations, {
-          existing: 'preserve',
-        });
+    const plannedOperations: TrailsResult<PlannedProjectOperation[], Error> =
+      dryRun
+        ? planProjectOperations(projectDir, operations, {
+            existing: 'preserve',
+          })
+        : await applyProjectOperations(projectDir, operations, {
+            existing: 'preserve',
+          });
     if (plannedOperations.isErr()) {
-      return Result.err(plannedOperations.error);
+      return plannedOperations;
     }
 
     const created = dryRun

package/src/trails/create.ts

@@ -86,7 +86,7 @@ const collectSurfaceFiles = async (
   for (const surface of surfaces) {
     const result = await addSurface(surface);
     if (result.isErr()) {
-      return Result.err(result.error);
+      return result;
     }
     if (result.value.created !== null) {
       created.push(result.value.created);
@@ -181,7 +181,7 @@ const writeReadme = async (
 ): Promise<Result<string | null, Error>> => {
   const exists = projectPathExists(dir, 'README.md');
   if (exists.isErr()) {
-    return Result.err(exists.error);
+    return exists;
   }
   if (exists.value) {
     return Result.ok(null);
@@ -225,7 +225,7 @@ export const createTrail = trail('create', {
           )
       );
       if (surfaceFiles.isErr()) {
-        return Result.err(surfaceFiles.error);
+        return surfaceFiles;
       }
 
       const verifyFiles = await collectVerifyFiles(input.verify, () =>
@@ -235,12 +235,12 @@ export const createTrail = trail('create', {
         )
       );
       if (verifyFiles.isErr()) {
-        return Result.err(verifyFiles.error);
+        return verifyFiles;
       }
 
       const readmeFile = await writeReadme(input, scaffolded.value.dir);
       if (readmeFile.isErr()) {
-        return Result.err(readmeFile.error);
+        return readmeFile;
       }
 
       return Result.ok({

package/src/trails/dev-support.ts

@@ -1,11 +1,10 @@
 import { existsSync, statSync } from 'node:fs';
-import { join } from 'node:path';
+import { isAbsolute, join } from 'node:path';
 
 import {
   openReadTrailsDb,
   openWriteTrailsDb,
   deriveTrailsDbPath,
-  deriveTrailsDir,
 } from '@ontrails/core';
 import {
   countPinnedSnapshots,
@@ -21,7 +20,10 @@ import {
   previewTraceCleanup,
 } from '@ontrails/tracing';
 
-import { removeRootRelativeFileIfPresent } from '../local-state-io.js';
+import {
+  removeFileIfPresent,
+  removeRootRelativeFileIfPresent,
+} from '../local-state-io.js';
 
 import { requireTrailRootDir } from './root-dir.js';
 
@@ -31,9 +33,17 @@ const deriveRootDir = (cwd?: string): string => requireTrailRootDir(cwd);
 
 const removeResetFileIfPresent = (
   rootDir: string,
-  relativePath: string
+  resetPath: string
 ): boolean => {
-  const removed = removeRootRelativeFileIfPresent(rootDir, relativePath);
+  if (isAbsolute(resetPath)) {
+    const removed = removeFileIfPresent(resetPath);
+    if (removed.isErr()) {
+      throw removed.error;
+    }
+    return removed.value;
+  }
+
+  const removed = removeRootRelativeFileIfPresent(rootDir, resetPath);
   if (removed.isErr()) {
     throw removed.error;
   }
@@ -139,7 +149,7 @@ const buildDbStats = (
 ): DevStatsReport['db'] => ({
   exists,
   fileSizeBytes: exists ? statSync(dbPath).size : 0,
-  path: '.trails/state/trails.db',
+  path: dbPath,
 });
 
 const emptyDevStats = (
@@ -184,8 +194,7 @@ const liveDevStats = (
 const deriveDevStatsContext = (options?: DevRetentionOptions) => {
   const rootDir = deriveRootDir(options?.rootDir);
   const dbPath = deriveTrailsDbPath({ rootDir });
-  const trailsDir = deriveTrailsDir({ rootDir });
-  const lockPath = join(trailsDir, 'trails.lock');
+  const lockPath = join(rootDir, 'trails.lock');
   return {
     dbExists: existsSync(dbPath),
     dbPath,
@@ -256,24 +265,35 @@ const buildCleanReport = (
   };
 };
 
-const RESET_FILES = [
-  '.trails/state/trails.db',
-  '.trails/state/trails.db-shm',
-  '.trails/state/trails.db-wal',
-  // Legacy paths (pre-state migration) — cleaned for one cycle so upgrading
-  // workspaces do not leave stale DB sidecars at old locations.
-  '.trails/trails.db',
-  '.trails/trails.db-shm',
-  '.trails/trails.db-wal',
-  '.trails/dev/tracing.db',
-  '.trails/dev/tracing.db-shm',
-  '.trails/dev/tracing.db-wal',
+const dbSidecarPaths = (basePath: string): readonly string[] => [
+  basePath,
+  `${basePath}-shm`,
+  `${basePath}-wal`,
+];
+
+const legacyRepoPath = (...segments: readonly string[]) => segments.join('/');
+const legacyDbName = (...segments: readonly string[]) => segments.join('.');
+
+const legacyResetFiles = [
+  // Legacy paths (pre-state migration) cleaned for one cycle so upgrading
+  // workspaces do not leave stale DB sidecars at old repo-local locations.
+  ...dbSidecarPaths(legacyRepoPath('.trails', 'state', 'trails.db')),
+  ...dbSidecarPaths(legacyRepoPath('.trails', legacyDbName('trails', 'db'))),
+  ...dbSidecarPaths(legacyRepoPath('.trails', 'dev', 'tracing.db')),
 ] as const;
 
-const presentResetFiles = (
-  rootDir: string
-): readonly (typeof RESET_FILES)[number][] =>
-  RESET_FILES.filter((relativePath) => existsSync(join(rootDir, relativePath)));
+const currentResetFiles = (rootDir: string): readonly string[] => {
+  const dbPath = deriveTrailsDbPath({ rootDir });
+  return dbSidecarPaths(dbPath);
+};
+
+const resetFileExists = (rootDir: string, resetPath: string): boolean =>
+  existsSync(isAbsolute(resetPath) ? resetPath : join(rootDir, resetPath));
+
+const presentResetFiles = (rootDir: string): readonly string[] =>
+  [...currentResetFiles(rootDir), ...legacyResetFiles].filter((resetPath) =>
+    resetFileExists(rootDir, resetPath)
+  );
 
 export const buildDevStats = (
   options?: DevRetentionOptions

package/src/trails/doctor.ts

@@ -1,4 +1,10 @@
-import { deriveTrailsDir, Result, trail } from '@ontrails/core';
+import {
+  deriveTrailsDir,
+  InternalError,
+  isTrailsError,
+  Result,
+  trail,
+} from '@ontrails/core';
 import { readTopoGraph } from '@ontrails/topographer';
 import { z } from 'zod';
 
@@ -18,11 +24,26 @@ const readDoctorForceGraph = async (
   }
 };
 
+const toDoctorSummaryError = (error: unknown): InternalError =>
+  error instanceof Error
+    ? new InternalError('Unable to derive doctor summary', { cause: error })
+    : new InternalError(`Unable to derive doctor summary: ${String(error)}`);
+
 export const doctorTrail = trail('doctor', {
   blaze: async (input, ctx) =>
     withLifecycleApp(input, ctx.cwd, async (app, rootDir) => {
       const forceGraph = await readDoctorForceGraph(rootDir);
-      return Result.ok(deriveDoctorSummary(app, { forceGraph }));
+      try {
+        return Result.ok(deriveDoctorSummary(app, { forceGraph }));
+      } catch (error) {
+        // deriveTopoGraph throws ValidationError on invalid topos; doctor must
+        // report that diagnosis instead of letting the pipeline redact it to a
+        // generic internal error.
+        if (isTrailsError(error)) {
+          return Result.err(error);
+        }
+        return Result.err(toDoctorSummaryError(error));
+      }
     }),
   description: 'Diagnose trail versioning lifecycle state',
   input: z.object({

package/src/trails/draft-promote.ts

@@ -571,7 +571,7 @@ const planRelativeImports = (
       operations
     );
     if (changed.isErr()) {
-      return Result.err(changed.error);
+      return changed;
     }
     if (changed.value) {
       updatedSourceFiles.add(filePath);
@@ -593,7 +593,7 @@ const rewritePromotionState = async (
   const initialFiles = collectTsFiles(rootDir);
   const sourcesResult = await readSourceFiles(initialFiles);
   if (sourcesResult.isErr()) {
-    return Result.err(sourcesResult.error);
+    return sourcesResult;
   }
   const sources = sourcesResult.value;
   const operations: ProjectWriteOperation[] = [];
@@ -608,14 +608,14 @@ const rewritePromotionState = async (
     operations
   );
   if (rewritten.isErr()) {
-    return Result.err(rewritten.error);
+    return rewritten;
   }
 
   const renamesResult = input.renameFiles
     ? collectFileRenames(initialFiles, sources)
     : Result.ok([] as FileRename[]);
   if (renamesResult.isErr()) {
-    return Result.err(renamesResult.error);
+    return renamesResult;
   }
 
   const valid = validateRenameTargets(renamesResult.value);
@@ -637,14 +637,14 @@ const rewritePromotionState = async (
     operations
   );
   if (importUpdates.isErr()) {
-    return Result.err(importUpdates.error);
+    return importUpdates;
   }
 
   const plannedOperations = input.dryRun
     ? planProjectOperations(rootDir, operations)
     : await applyProjectOperations(rootDir, operations);
   if (plannedOperations.isErr()) {
-    return Result.err(plannedOperations.error);
+    return plannedOperations;
   }
   return Result.ok({
     plannedOperations: plannedOperations.value,
@@ -837,7 +837,7 @@ const promoteDraftState = async (
 
   const rewriteResult = await rewritePromotionState(rootDirResult.value, input);
   if (rewriteResult.isErr()) {
-    return Result.err(rewriteResult.error);
+    return rewriteResult;
   }
 
   const { renames, updatedSourceFiles } = rewriteResult.value;