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

package/src/trails/topo-store-support.ts

@@ -7,18 +7,20 @@
 
 import { Database } from 'bun:sqlite';
 
-import type { Topo } from '@ontrails/core';
+import type { CliCommandAliasInput, Topo } from '@ontrails/core';
 import {
   ConflictError,
   deriveTrailsDir,
   InternalError,
   openWriteTrailsDb,
   Result,
+  TimeoutError,
 } from '@ontrails/core';
 import type {
   LockManifest,
   TopoGraph,
   TopoSnapshot,
+  TrailsLock,
 } from '@ontrails/topographer';
 import type { StoredTopoExport } from '@ontrails/topographer/backend-support';
 import {
@@ -27,14 +29,15 @@ import {
   deriveTopoGraphDiff,
   deriveTopoGraphHash,
   readTopoGraph,
-  writeLockManifest,
-  writeTopoGraph,
+  writeTrailsLock,
 } from '@ontrails/topographer';
 import {
   createStoredTopoSnapshot,
   getStoredTopoExport,
 } from '@ontrails/topographer/backend-support';
 
+import { removeRootRelativeFileIfPresent } from '../local-state-io.js';
+
 import type { TopoExportReport } from './topo-support.js';
 import {
   deriveRootDir,
@@ -42,15 +45,21 @@ import {
   readGitState,
 } from './topo-support.js';
 
+type CliAliasesOption = Readonly<
+  Record<string, readonly CliCommandAliasInput[]>
+>;
+
 const persistAndReadStoredExport = (
   app: Topo,
   db: ReturnType<typeof openWriteTrailsDb>,
-  rootDir: string
+  rootDir: string,
+  options?: { readonly cliAliases?: CliAliasesOption | undefined } | undefined
 ): Result<
   { snapshot: TopoSnapshot; storedExport: StoredTopoExport },
   Error
 > => {
   const snapshotResult = createStoredTopoSnapshot(db, app, {
+    cliAliases: options?.cliAliases,
     ...readGitState(rootDir),
     ...deriveTopoCounts(app),
   });
@@ -75,15 +84,58 @@ const persistAndReadStoredExport = (
   });
 };
 
+const asError = (error: unknown): Error =>
+  error instanceof Error ? error : new Error(String(error));
+
+const readErrorCode = (error: unknown): string | undefined => {
+  if (typeof error !== 'object' || error === null || !('code' in error)) {
+    return undefined;
+  }
+  const { code } = error as { readonly code?: unknown };
+  return typeof code === 'string' ? code : undefined;
+};
+
+const isSqliteLockError = (error: unknown): boolean => {
+  const code = readErrorCode(error);
+  if (code === 'SQLITE_BUSY' || code === 'SQLITE_LOCKED') {
+    return true;
+  }
+  return asError(error).message.match(/database is (locked|busy)/i) !== null;
+};
+
+export const mapTopoExportError = (error: unknown): Error => {
+  if (!isSqliteLockError(error)) {
+    return error instanceof Error
+      ? error
+      : new InternalError('Unable to write topo artifacts');
+  }
+  return new TimeoutError(
+    'Timed out waiting for the Trails topo store lock while compiling artifacts. Another topo write may be running; retry after it finishes.',
+    {
+      cause: asError(error),
+      context: {
+        operation: 'compile',
+        reason: 'sqlite-lock-contention',
+        resource: 'trails.db',
+      },
+    }
+  );
+};
+
 export const deriveCurrentTopoExport = (
   app: Topo,
-  options?: { readonly rootDir?: string }
+  options?: {
+    readonly cliAliases?: CliAliasesOption | undefined;
+    readonly rootDir?: string;
+  }
 ): Result<StoredTopoExport, Error> => {
   const rootDir = deriveRootDir(options?.rootDir);
   const db = new Database(':memory:');
 
   try {
-    const projected = persistAndReadStoredExport(app, db, rootDir);
+    const projected = persistAndReadStoredExport(app, db, rootDir, {
+      cliAliases: options?.cliAliases,
+    });
     return projected.isErr()
       ? projected
       : Result.ok(projected.value.storedExport);
@@ -92,12 +144,22 @@ export const deriveCurrentTopoExport = (
   }
 };
 
-const writeStoredExportArtifacts = async (
+const readPreviousCommittedTopo = async (
+  rootDir: string
+): Promise<TopoGraph | null> => {
+  const rootTopo = await readTopoGraph({ dir: rootDir });
+  return rootTopo ?? readTopoGraph({ dir: deriveTrailsDir({ rootDir }) });
+};
+
+const prepareStoredExportArtifacts = async (
   storedExport: StoredTopoExport,
-  trailsDir: string,
+  rootDir: string,
   options?: { readonly force?: boolean | undefined }
-): Promise<Pick<TopoExportReport, 'hash' | 'lockPath' | 'topoPath'>> => {
-  const previousTopo = await readTopoGraph({ dir: trailsDir });
+): Promise<{
+  readonly hash: string;
+  readonly topoGraph: TopoGraph;
+}> => {
+  const previousTopo = await readPreviousCommittedTopo(rootDir);
   const nextTopo = JSON.parse(storedExport.topoGraphJson) as TopoGraph;
   const diff =
     previousTopo === null
@@ -118,57 +180,128 @@ const writeStoredExportArtifacts = async (
       ? topoGraphBase
       : annotateTopoGraphForces(topoGraphBase, diff.breaking);
   const hash = deriveTopoGraphHash(topoGraph);
-  const lockManifest = {
-    ...(JSON.parse(storedExport.lockManifestJson) as LockManifest),
-    artifacts: [
-      {
-        path: 'topo.lock',
-        role: 'topo',
-        sha256: hash,
-      },
-    ],
-  } satisfies LockManifest;
-
-  const topoPath = await writeTopoGraph(topoGraph, { dir: trailsDir });
-  const lockPath = await writeLockManifest(lockManifest, { dir: trailsDir });
 
   return {
     hash,
+    topoGraph,
+  };
+};
+
+const LEGACY_COMMITTED_ARTIFACTS = [
+  '.trails/topo.lock',
+  '.trails/trails.lock',
+] as const;
+
+const removeLegacyCommittedArtifacts = (
+  rootDir: string
+): Result<void, Error> => {
+  for (const relativePath of LEGACY_COMMITTED_ARTIFACTS) {
+    const removed = removeRootRelativeFileIfPresent(rootDir, relativePath);
+    if (removed.isErr()) {
+      return removed;
+    }
+  }
+
+  return Result.ok();
+};
+
+const writeStoredExportArtifacts = async (
+  storedExport: StoredTopoExport,
+  rootDir: string,
+  options?: { readonly force?: boolean | undefined }
+): Promise<Pick<TopoExportReport, 'hash' | 'lockPath'>> => {
+  const prepared = await prepareStoredExportArtifacts(
+    storedExport,
+    rootDir,
+    options
+  );
+
+  const lockManifest = JSON.parse(
+    storedExport.lockManifestJson
+  ) as LockManifest;
+  const lockPath = await writeTrailsLock(
+    {
+      scope: lockManifest.scope,
+      summary: {
+        contours: prepared.topoGraph.entries.filter(
+          (entry) => entry.kind === 'contour'
+        ).length,
+        resources: prepared.topoGraph.entries.filter(
+          (entry) => entry.kind === 'resource'
+        ).length,
+        signals: prepared.topoGraph.entries.filter(
+          (entry) => entry.kind === 'signal'
+        ).length,
+        trails: prepared.topoGraph.entries.filter(
+          (entry) => entry.kind === 'trail'
+        ).length,
+      },
+      topoGraph: prepared.topoGraph,
+      topoGraphHash: prepared.hash,
+      version: 4,
+    } as TrailsLock,
+    { dir: rootDir }
+  );
+  const removedLegacyArtifacts = removeLegacyCommittedArtifacts(rootDir);
+  if (removedLegacyArtifacts.isErr()) {
+    throw removedLegacyArtifacts.error;
+  }
+
+  return {
+    hash: prepared.hash,
     lockPath,
-    topoPath,
   };
 };
 
 export const exportCurrentTopo = async (
   app: Topo,
-  options?: { readonly force?: boolean | undefined; readonly rootDir?: string }
+  options?: {
+    readonly cliAliases?: CliAliasesOption | undefined;
+    readonly force?: boolean | undefined;
+    readonly rootDir?: string;
+  }
 ): Promise<Result<TopoExportReport, Error>> => {
   const rootDir = deriveRootDir(options?.rootDir);
-  const db = openWriteTrailsDb({ rootDir });
+  let db: ReturnType<typeof openWriteTrailsDb> | undefined;
 
   try {
-    const persisted = persistAndReadStoredExport(app, db, rootDir);
+    const candidate = deriveCurrentTopoExport(app, {
+      cliAliases: options?.cliAliases,
+      rootDir,
+    });
+    if (candidate.isErr()) {
+      return candidate;
+    }
+
+    try {
+      await prepareStoredExportArtifacts(candidate.value, rootDir, {
+        force: options?.force,
+      });
+    } catch (error: unknown) {
+      return Result.err(mapTopoExportError(error));
+    }
+
+    db = openWriteTrailsDb({ rootDir });
+    const persisted = persistAndReadStoredExport(app, db, rootDir, {
+      cliAliases: options?.cliAliases,
+    });
     if (persisted.isErr()) {
       return persisted;
     }
 
     const { snapshot, storedExport } = persisted.value;
-    let artifacts: Pick<TopoExportReport, 'hash' | 'lockPath' | 'topoPath'>;
+    let artifacts: Pick<TopoExportReport, 'hash' | 'lockPath'>;
     try {
-      artifacts = await writeStoredExportArtifacts(
-        storedExport,
-        deriveTrailsDir({ rootDir }),
-        { force: options?.force }
-      );
+      artifacts = await writeStoredExportArtifacts(storedExport, rootDir, {
+        force: options?.force,
+      });
     } catch (error: unknown) {
-      return Result.err(
-        error instanceof Error
-          ? error
-          : new InternalError('Unable to write topo artifacts')
-      );
+      return Result.err(mapTopoExportError(error));
     }
     return Result.ok({ ...artifacts, snapshot });
+  } catch (error: unknown) {
+    return Result.err(mapTopoExportError(error));
   } finally {
-    db.close();
+    db?.close();
   }
 };

package/src/trails/topo-support.ts

@@ -33,7 +33,7 @@ export const topoSnapshotOutput = z.object({
 });
 
 export const DEFAULT_TOPO_HISTORY_LIMIT = 10;
-export const LOCK_PATH = '.trails/trails.lock';
+export const LOCK_PATH = 'trails.lock';
 const EXAMPLE_APP_MODULE = fileURLToPath(new URL('../app.ts', import.meta.url));
 
 const uniqueExampleRootName = (name: string): string =>
@@ -59,7 +59,6 @@ export interface TopoExportReport {
   readonly hash: string;
   readonly lockPath: string;
   readonly snapshot: TopoSnapshot;
-  readonly topoPath: string;
 }
 
 export interface TopoValidateReport {

package/src/trails/topo.ts

@@ -1,8 +1,7 @@
 import { Result, trail } 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 { activationOverviewOutput } from './topo-output-schemas.js';
 import { buildTopoSummary } from './topo-read-support.js';
 import { createIsolatedExampleInput } from './topo-support.js';
@@ -73,23 +72,10 @@ const summaryOutput = z.object({
 });
 
 export const topoTrail = trail('topo', {
-  blaze: async (input, 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 Result.ok(buildTopoSummary(lease.app, { rootDir }));
-    } finally {
-      lease.release();
-    }
-  },
+  blaze: async (input, ctx) =>
+    withFreshOperatorApp(input, ctx, ({ lease, rootDir }) =>
+      Result.ok(buildTopoSummary(lease.app, { rootDir }))
+    ),
   description: 'Show the current topo summary and entry list',
   examples: [
     {

package/src/trails/validate.ts

@@ -1,29 +1,18 @@
 import { trail } 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 { validateCurrentTopo } from './topo-read-support.js';
 
 export const validateTrail = trail('validate', {
-  blaze: async (input, 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 validateCurrentTopo(lease.app, { rootDir });
-    } finally {
-      lease.release();
-    }
-  },
-  description: 'Validate that committed topo artifacts match the current topo',
+  blaze: async (input, ctx) =>
+    withFreshOperatorApp(input, ctx, ({ lease, rootDir }) =>
+      validateCurrentTopo(lease.app, {
+        cliAliases: lease.cliAliases,
+        rootDir,
+      })
+    ),
+  description: 'Validate that root trails.lock matches the current topo',
   input: z.object({
     module: z.string().optional().describe('Path to the app module'),
     rootDir: z.string().optional().describe('Workspace root directory'),

package/src/trails/version-lifecycle-support.ts

@@ -7,12 +7,11 @@ import { deriveTopoGraph } from '@ontrails/topographer';
 import type { TopoGraph, TopoGraphForceEntry } from '@ontrails/topographer';
 import { findTrailDefinitions, parse } from '@ontrails/warden/ast';
 
-import { tryLoadFreshAppLease } from './load-app.js';
 import {
   readLifecycleSourceFile,
   writeLifecycleSourceFile,
 } from '../lifecycle-source-io.js';
-import { resolveTrailRootDir } from './root-dir.js';
+import { withFreshAppLease, withOperatorRootDir } from './operator-context.js';
 
 export type LifecycleEntryKind = 'revision' | 'fork';
 export type LifecycleStatusKind = 'deprecated' | 'archived';
@@ -569,7 +568,7 @@ export const reviseTrailSource = (
   );
   const written = writeLifecycleSourceFile(match.value.filePath, nextSource);
   if (written.isErr()) {
-    return Result.err(written.error);
+    return written;
   }
 
   return Result.ok({
@@ -732,7 +731,7 @@ export const setVersionStatusSource = (
   }
   const written = writeLifecycleSourceFile(match.value.filePath, nextSource);
   if (written.isErr()) {
-    return Result.err(written.error);
+    return written;
   }
 
   return Result.ok({
@@ -776,7 +775,7 @@ export const forkVersionEntrySource = (
   }
   const written = writeLifecycleSourceFile(match.value.filePath, nextSource);
   if (written.isErr()) {
-    return Result.err(written.error);
+    return written;
   }
 
   return Result.ok({
@@ -798,21 +797,12 @@ export const withLifecycleApp = async <T>(
     app: Topo,
     rootDir: string
   ) => Result<T, Error> | Promise<Result<T, Error>>
-): Promise<Result<T, Error>> => {
-  const root = resolveTrailRootDir(input.rootDir, cwd);
-  if (root.isErr()) {
-    return root;
-  }
-  const lease = await tryLoadFreshAppLease(input.module, root.value);
-  if (lease.isErr()) {
-    return Result.err(lease.error);
-  }
-  try {
-    return await consume(lease.value.app, root.value);
-  } finally {
-    lease.value.release();
-  }
-};
+): Promise<Result<T, Error>> =>
+  withOperatorRootDir(input, { cwd }, (rootDir) =>
+    withFreshAppLease(input.module, rootDir, (lease) =>
+      consume(lease.app, rootDir)
+    )
+  );
 
 export const findLifecycleTrail = (
   app: Topo,

package/src/trails/warden.ts

@@ -16,6 +16,11 @@ import {
 } from '@ontrails/warden';
 import { z } from 'zod';
 
+import {
+  createIsolatedExampleRoot,
+  writeIsolatedExampleTextFile,
+} from '../local-state-io.js';
+
 import { resolveTrailRootDir } from './root-dir.js';
 
 // ---------------------------------------------------------------------------
@@ -68,6 +73,14 @@ const wardenInputSchema = z.object({
 
 type WardenTrailInput = z.infer<typeof wardenInputSchema>;
 
+const createIsolatedWardenExampleRoot = (name: string): string => {
+  const rootDir = createIsolatedExampleRoot(
+    `warden-${name}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`
+  );
+  writeIsolatedExampleTextFile(rootDir, 'src/clean.ts', 'export {};\n');
+  return rootDir;
+};
+
 const pushFlag = (args: string[], condition: boolean, flag: string): void => {
   if (condition) {
     args.push(flag);
@@ -170,13 +183,18 @@ export const wardenTrail = trail('warden', {
   examples: [
     {
       input: {
+        depth: 'source',
         lock: 'skip',
+        rootDir: createIsolatedWardenExampleRoot('default'),
       },
       name: 'Default warden run',
     },
     {
       input: {
+        depth: 'source',
         format: 'github',
+        lock: 'skip',
+        rootDir: createIsolatedWardenExampleRoot('github'),
       },
       name: 'GitHub Actions annotations',
     },