@ontrails/trails 1.0.0-beta.15 → 1.0.0-beta.16

package/src/trails/dev-support.ts

@@ -1,36 +1,43 @@
-import { existsSync, rmSync, statSync } from 'node:fs';
+import { existsSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 
-import {
-  countPinnedSnapshots,
-  countPrunableSnapshots,
-  countTopoSnapshots,
-  pruneUnpinnedSnapshots,
-} from '@ontrails/core/internal/topo-snapshots';
 import {
   openReadTrailsDb,
   openWriteTrailsDb,
   deriveTrailsDbPath,
   deriveTrailsDir,
-} from '@ontrails/core/internal/trails-db';
+} from '@ontrails/core';
+import {
+  countPinnedSnapshots,
+  countPrunableSnapshots,
+  countTopoSnapshots,
+  pruneUnpinnedSnapshots,
+} from '@ontrails/topographer/backend-support';
 import {
   DEFAULT_MAX_AGE,
   DEFAULT_MAX_RECORDS,
   applyTraceCleanup,
   countTraceRecords,
   previewTraceCleanup,
-} from '@ontrails/tracing/internal/dev-state';
+} from '@ontrails/tracing';
+
+import { removeRootRelativeFileIfPresent } from '../local-state-io.js';
+
+import { requireTrailRootDir } from './root-dir.js';
 
 export const DEFAULT_TOPO_SNAPSHOT_RETENTION = 50;
 
-const deriveRootDir = (cwd?: string): string => cwd ?? process.cwd();
+const deriveRootDir = (cwd?: string): string => requireTrailRootDir(cwd);
 
-const removeIfPresent = (filePath: string): boolean => {
-  if (!existsSync(filePath)) {
-    return false;
+const removeResetFileIfPresent = (
+  rootDir: string,
+  relativePath: string
+): boolean => {
+  const removed = removeRootRelativeFileIfPresent(rootDir, relativePath);
+  if (removed.isErr()) {
+    throw removed.error;
   }
-  rmSync(filePath, { force: true });
-  return true;
+  return removed.value;
 };
 
 export interface DevStatsReport {
@@ -132,7 +139,7 @@ const buildDbStats = (
 ): DevStatsReport['db'] => ({
   exists,
   fileSizeBytes: exists ? statSync(dbPath).size : 0,
-  path: '.trails/trails.db',
+  path: '.trails/state/trails.db',
 });
 
 const emptyDevStats = (
@@ -250,6 +257,11 @@ 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',
@@ -317,7 +329,7 @@ export const resetDevState = (options?: {
   }
 
   const removedFiles = files.filter((relativePath) =>
-    removeIfPresent(join(rootDir, relativePath))
+    removeResetFileIfPresent(rootDir, relativePath)
   );
 
   return {

package/src/trails/draft-promote.ts

@@ -1,5 +1,12 @@
-import { existsSync, renameSync, statSync } from 'node:fs';
-import { basename, dirname, join, relative } from 'node:path';
+import { existsSync, statSync } from 'node:fs';
+import {
+  basename,
+  dirname,
+  isAbsolute,
+  join,
+  relative,
+  resolve,
+} from 'node:path';
 
 import {
   Result,
@@ -11,15 +18,24 @@ import {
 import type { Topo } from '@ontrails/core';
 import {
   DRAFT_FILE_PREFIX,
-  findStringLiterals,
   isDraftMarkedFile,
-  parse,
   stripDraftFileMarkers,
 } from '@ontrails/warden';
+import { findStringLiterals, parse } from '@ontrails/warden/ast';
 import { z } from 'zod';
 
-import { loadFreshAppLease } from './load-app.js';
+import {
+  applyProjectOperations,
+  planProjectOperations,
+} from '../project-writes.js';
+import type {
+  PlannedProjectOperation,
+  ProjectWriteOperation,
+} from '../project-writes.js';
+import type { FreshAppLease } from './load-app.js';
+import { tryLoadFreshAppLease } from './load-app.js';
 import { findTopoPath } from './project.js';
+import { resolveTrailRootDir } from './root-dir.js';
 
 interface PromotionEdit {
   readonly end: number;
@@ -177,6 +193,7 @@ const toProjectModulePath = (sourceImport: string): string =>
     : sourceImport;
 
 interface PromotionRewriteState {
+  readonly plannedOperations: PlannedProjectOperation[];
   readonly renames: FileRename[];
   readonly updatedSourceFiles: Set<string>;
 }
@@ -240,7 +257,22 @@ const resolveValidatedPromotionRoot = (
     return validation;
   }
 
-  const rootDir = input.rootDir ?? ctx.cwd ?? process.cwd();
+  let rootDir: string;
+  if (input.rootDir === undefined) {
+    const cwdResult = resolveTrailRootDir(undefined, ctx.cwd);
+    if (cwdResult.isErr()) {
+      return cwdResult;
+    }
+    rootDir = resolve(cwdResult.value);
+  } else if (isAbsolute(input.rootDir)) {
+    rootDir = resolve(input.rootDir);
+  } else {
+    const cwdResult = resolveTrailRootDir(undefined, ctx.cwd);
+    if (cwdResult.isErr()) {
+      return cwdResult;
+    }
+    rootDir = resolve(cwdResult.value, input.rootDir);
+  }
   const rootValidation = validatePromotionRoot(rootDir);
   if (rootValidation.isErr()) {
     return rootValidation;
@@ -249,27 +281,83 @@ const resolveValidatedPromotionRoot = (
   return Result.ok(rootDir);
 };
 
-const rewritePromotedSourceFiles = async (
+type SourceFileMap = Map<string, string>;
+type WriteProjectOperation = Extract<
+  ProjectWriteOperation,
+  { readonly kind: 'write' }
+>;
+
+const pushWriteOperation = (
+  operations: ProjectWriteOperation[],
+  operation: WriteProjectOperation
+): void => {
+  for (let index = operations.length - 1; index >= 0; index -= 1) {
+    const existing = operations[index];
+    if (
+      existing?.kind === 'rename' &&
+      (existing.from === operation.path || existing.to === operation.path)
+    ) {
+      break;
+    }
+    if (existing?.kind === 'write' && existing.path === operation.path) {
+      operations[index] = operation;
+      return;
+    }
+  }
+
+  operations.push(operation);
+};
+
+const readSourceFiles = async (
+  filePaths: readonly string[]
+): Promise<Result<SourceFileMap, Error>> => {
+  const sources = new Map<string, string>();
+  for (const filePath of filePaths) {
+    try {
+      sources.set(filePath, await Bun.file(filePath).text());
+    } catch (error) {
+      return Result.err(
+        new ValidationError(
+          `Cannot read source file "${filePath}"`,
+          error instanceof Error ? { cause: error } : undefined
+        )
+      );
+    }
+  }
+  return Result.ok(sources);
+};
+
+const planPromotedSourceFiles = (
   filePaths: readonly string[],
+  sources: SourceFileMap,
   fromId: string,
   toId: string,
-  updatedSourceFiles: Set<string>
-): Promise<void> => {
+  updatedSourceFiles: Set<string>,
+  operations: ProjectWriteOperation[]
+): Result<void, Error> => {
   for (const filePath of filePaths) {
-    const sourceCode = await Bun.file(filePath).text();
+    const sourceCode = sources.get(filePath);
+    if (sourceCode === undefined) {
+      return Result.err(
+        new ValidationError(`Cannot read source file "${filePath}"`)
+      );
+    }
+
     const replaced = replaceIdLiterals(sourceCode, filePath, fromId, toId);
     if (!replaced.changed) {
       continue;
     }
 
-    await Bun.write(filePath, replaced.nextSource);
+    sources.set(filePath, replaced.nextSource);
+    pushWriteOperation(operations, {
+      content: replaced.nextSource,
+      kind: 'write',
+      path: filePath,
+    });
     updatedSourceFiles.add(filePath);
   }
-};
 
-const hasDraftIdsInFile = async (filePath: string): Promise<boolean> => {
-  const sourceCode = await Bun.file(filePath).text();
-  return hasDraftIds(sourceCode, filePath);
+  return Result.ok();
 };
 
 const buildPromotableFileRename = (
@@ -293,9 +381,10 @@ const buildPromotableFileRename = (
   return Result.ok({ from: filePath, to: nextPath });
 };
 
-const collectPromotableFileRename = async (
-  filePath: string
-): Promise<Result<FileRename | null, Error>> => {
+const collectPromotableFileRename = (
+  filePath: string,
+  sourceCode: string
+): Result<FileRename | null, Error> => {
   if (!isDraftMarkedFile(filePath)) {
     return Result.ok(null);
   }
@@ -305,7 +394,7 @@ const collectPromotableFileRename = async (
     return Result.ok(null);
   }
 
-  if (await hasDraftIdsInFile(filePath)) {
+  if (hasDraftIds(sourceCode, filePath)) {
     return Result.ok(null);
   }
 
@@ -337,12 +426,19 @@ const validateRenameTargets = (
   return Result.ok();
 };
 
-const collectFileRenames = async (
-  filePaths: readonly string[]
-): Promise<Result<FileRename[], Error>> => {
+const collectFileRenames = (
+  filePaths: readonly string[],
+  sources: SourceFileMap
+): Result<FileRename[], Error> => {
   const renames: FileRename[] = [];
   for (const filePath of filePaths) {
-    const renameResult = await collectPromotableFileRename(filePath);
+    const sourceCode = sources.get(filePath);
+    if (sourceCode === undefined) {
+      return Result.err(
+        new ValidationError(`Cannot read source file "${filePath}"`)
+      );
+    }
+    const renameResult = collectPromotableFileRename(filePath, sourceCode);
     if (renameResult.isErr()) {
       return renameResult;
     }
@@ -353,26 +449,6 @@ const collectFileRenames = async (
   return Result.ok(renames);
 };
 
-const collectAndApplyFileRenames = async (
-  filePaths: readonly string[]
-): Promise<Result<FileRename[], Error>> => {
-  const collected = await collectFileRenames(filePaths);
-  if (collected.isErr()) {
-    return collected;
-  }
-
-  const renames = collected.value;
-  const valid = validateRenameTargets(renames);
-  if (valid.isErr()) {
-    return valid;
-  }
-
-  for (const r of renames) {
-    renameSync(r.from, r.to);
-  }
-  return Result.ok(renames);
-};
-
 const applyRenameEffects = (
   updatedSourceFiles: Set<string>,
   renames: readonly FileRename[]
@@ -384,6 +460,30 @@ const applyRenameEffects = (
   }
 };
 
+const applySourceRenameEffects = (
+  sources: SourceFileMap,
+  renames: readonly FileRename[]
+): void => {
+  for (const rename of renames) {
+    const sourceCode = sources.get(rename.from);
+    if (sourceCode === undefined) {
+      continue;
+    }
+    sources.delete(rename.from);
+    sources.set(rename.to, sourceCode);
+  }
+};
+
+const applyFilePathRenames = (
+  filePaths: readonly string[],
+  renames: readonly FileRename[]
+): string[] => {
+  const renamedBySource = new Map(
+    renames.map((rename) => [rename.from, rename.to])
+  );
+  return filePaths.map((filePath) => renamedBySource.get(filePath) ?? filePath);
+};
+
 const applyRelativeImportRename = (
   sourceCode: string,
   filePath: string,
@@ -429,69 +529,128 @@ const rewriteRelativeImportsForFile = (
   return { changed, sourceCode: nextSourceCode };
 };
 
-const updateRelativeImportsForFile = async (
+const planRelativeImportsForFile = (
   filePath: string,
-  renames: readonly FileRename[]
-): Promise<boolean> => {
-  const sourceCode = await Bun.file(filePath).text();
+  renames: readonly FileRename[],
+  sources: SourceFileMap,
+  operations: ProjectWriteOperation[]
+): Result<boolean, Error> => {
+  const sourceCode = sources.get(filePath);
+  if (sourceCode === undefined) {
+    return Result.err(
+      new ValidationError(`Cannot read source file "${filePath}"`)
+    );
+  }
+
   const updated = rewriteRelativeImportsForFile(filePath, renames, sourceCode);
   if (updated.changed) {
-    await Bun.write(filePath, updated.sourceCode);
-    return true;
+    sources.set(filePath, updated.sourceCode);
+    pushWriteOperation(operations, {
+      content: updated.sourceCode,
+      kind: 'write',
+      path: filePath,
+    });
+    return Result.ok(true);
   }
 
-  return false;
+  return Result.ok(false);
 };
 
-const updateRelativeImports = async (
+const planRelativeImports = (
   filePaths: readonly string[],
-  renames: readonly FileRename[]
-): Promise<string[]> => {
-  const updatedFiles = new Set<string>();
-
+  renames: readonly FileRename[],
+  sources: SourceFileMap,
+  updatedSourceFiles: Set<string>,
+  operations: ProjectWriteOperation[]
+): Result<void, Error> => {
   for (const filePath of filePaths) {
-    const changed = await updateRelativeImportsForFile(filePath, renames);
-    if (changed) {
-      updatedFiles.add(filePath);
+    const changed = planRelativeImportsForFile(
+      filePath,
+      renames,
+      sources,
+      operations
+    );
+    if (changed.isErr()) {
+      return Result.err(changed.error);
+    }
+    if (changed.value) {
+      updatedSourceFiles.add(filePath);
     }
   }
 
-  return [...updatedFiles].toSorted();
+  return Result.ok();
 };
 
 const rewritePromotionState = async (
   rootDir: string,
   input: {
+    readonly dryRun?: boolean | undefined;
     readonly fromId: string;
     readonly renameFiles: boolean;
     readonly toId: string;
   }
 ): Promise<Result<PromotionRewriteState, Error>> => {
   const initialFiles = collectTsFiles(rootDir);
+  const sourcesResult = await readSourceFiles(initialFiles);
+  if (sourcesResult.isErr()) {
+    return Result.err(sourcesResult.error);
+  }
+  const sources = sourcesResult.value;
+  const operations: ProjectWriteOperation[] = [];
   const updatedSourceFiles = new Set<string>();
 
-  await rewritePromotedSourceFiles(
+  const rewritten = planPromotedSourceFiles(
     initialFiles,
+    sources,
     input.fromId,
     input.toId,
-    updatedSourceFiles
+    updatedSourceFiles,
+    operations
   );
+  if (rewritten.isErr()) {
+    return Result.err(rewritten.error);
+  }
 
   const renamesResult = input.renameFiles
-    ? await collectAndApplyFileRenames(initialFiles)
+    ? collectFileRenames(initialFiles, sources)
     : Result.ok([] as FileRename[]);
   if (renamesResult.isErr()) {
     return Result.err(renamesResult.error);
   }
 
+  const valid = validateRenameTargets(renamesResult.value);
+  if (valid.isErr()) {
+    return valid;
+  }
+
+  for (const rename of renamesResult.value) {
+    operations.push({ from: rename.from, kind: 'rename', to: rename.to });
+  }
+
   applyRenameEffects(updatedSourceFiles, renamesResult.value);
-  for (const f of await updateRelativeImports(
-    collectTsFiles(rootDir),
-    renamesResult.value
-  )) {
-    updatedSourceFiles.add(f);
+  applySourceRenameEffects(sources, renamesResult.value);
+  const importUpdates = planRelativeImports(
+    applyFilePathRenames(initialFiles, renamesResult.value),
+    renamesResult.value,
+    sources,
+    updatedSourceFiles,
+    operations
+  );
+  if (importUpdates.isErr()) {
+    return Result.err(importUpdates.error);
+  }
+
+  const plannedOperations = input.dryRun
+    ? planProjectOperations(rootDir, operations)
+    : await applyProjectOperations(rootDir, operations);
+  if (plannedOperations.isErr()) {
+    return Result.err(plannedOperations.error);
   }
-  return Result.ok({ renames: renamesResult.value, updatedSourceFiles });
+  return Result.ok({
+    plannedOperations: plannedOperations.value,
+    renames: renamesResult.value,
+    updatedSourceFiles,
+  });
 };
 
 const resolvePromotionAppModule = async (
@@ -523,7 +682,7 @@ const resolvePromotionAppModule = async (
 type LeaseAttempt =
   | {
       readonly ok: true;
-      readonly lease: Awaited<ReturnType<typeof loadFreshAppLease>>;
+      readonly lease: FreshAppLease;
     }
   | { readonly ok: false; readonly loadError: string };
 
@@ -531,12 +690,11 @@ const tryAcquireLease = async (
   appModule: string,
   rootDir: string
 ): Promise<LeaseAttempt> => {
-  try {
-    return { lease: await loadFreshAppLease(appModule, rootDir), ok: true };
-  } catch (error) {
-    const loadError = error instanceof Error ? error.message : String(error);
-    return { loadError, ok: false };
+  const loaded = await tryLoadFreshAppLease(appModule, rootDir);
+  if (loaded.isErr()) {
+    return { loadError: loaded.error.message, ok: false };
   }
+  return { lease: loaded.value, ok: true };
 };
 
 const withVerifiedApp = async <T>(
@@ -572,19 +730,33 @@ const toUpdatedFiles = (rootDir: string, updatedSourceFiles: Set<string>) =>
     .toSorted()
     .map((filePath) => toRelativeOutputPath(rootDir, filePath));
 
+const buildUnverifiedPromotionMessage = (
+  loadError: string | null,
+  dryRun: boolean
+): string => {
+  if (dryRun) {
+    return 'Promotion plan is valid. Re-run without dryRun to apply it.';
+  }
+
+  return loadError === null
+    ? 'Promotion rewrote source files, but no topo entrypoint could be loaded for verification.'
+    : `Promotion rewrote source files, but verification failed: ${loadError}`;
+};
+
 const buildUnverifiedPromotionResult = (
   rootDir: string,
   loadError: string | null,
   renames: readonly FileRename[],
   updatedSourceFiles: Set<string>,
-  appModule: string | null
+  appModule: string | null,
+  plannedOperations: readonly PlannedProjectOperation[],
+  dryRun: boolean
 ) =>
   Result.ok({
     appModule,
-    message:
-      loadError === null
-        ? 'Promotion rewrote source files, but no topo entrypoint could be loaded for verification.'
-        : `Promotion rewrote source files, but verification failed: ${loadError}`,
+    dryRun,
+    message: buildUnverifiedPromotionMessage(loadError, dryRun),
+    plannedOperations,
     promotedEstablished: false,
     remainingDraftIds: [],
     renamedFiles: toRenamedFiles(rootDir, renames),
@@ -598,6 +770,7 @@ const buildVerifiedPromotionResult = (
   renames: readonly FileRename[],
   updatedSourceFiles: Set<string>,
   appModule: string | null,
+  plannedOperations: readonly PlannedProjectOperation[],
   toId: string
 ) => {
   const blockingFinding = analysis.findings.find(
@@ -606,11 +779,13 @@ const buildVerifiedPromotionResult = (
 
   return Result.ok({
     appModule,
+    dryRun: false,
     message:
       blockingFinding?.message ??
       (promotedEstablished
         ? `Promoted "${toId}" is now established.`
         : `Promoted "${toId}" could not be verified as established.`),
+    plannedOperations,
     promotedEstablished,
     remainingDraftIds: [...analysis.declaredDraftIds].toSorted(),
     renamedFiles: toRenamedFiles(rootDir, renames),
@@ -624,6 +799,7 @@ const buildVerifiedPromotionResultFromApp = (
   renames: readonly FileRename[],
   updatedSourceFiles: Set<string>,
   appModule: string | null,
+  plannedOperations: readonly PlannedProjectOperation[],
   toId: string
 ) => {
   const analysis = deriveDraftReport(loadedApp);
@@ -638,6 +814,7 @@ const buildVerifiedPromotionResultFromApp = (
     renames,
     updatedSourceFiles,
     appModule,
+    plannedOperations,
     toId
   );
 };
@@ -645,6 +822,7 @@ const buildVerifiedPromotionResultFromApp = (
 const promoteDraftState = async (
   input: {
     readonly appModule?: string | undefined;
+    readonly dryRun?: boolean | undefined;
     readonly fromId: string;
     readonly renameFiles: boolean;
     readonly rootDir?: string | undefined;
@@ -664,6 +842,18 @@ const promoteDraftState = async (
 
   const { renames, updatedSourceFiles } = rewriteResult.value;
   const appModule = await resolvePromotionAppModule(input, rootDirResult.value);
+  if (input.dryRun === true) {
+    return buildUnverifiedPromotionResult(
+      rootDirResult.value,
+      null,
+      renames,
+      updatedSourceFiles,
+      appModule,
+      rewriteResult.value.plannedOperations,
+      true
+    );
+  }
+
   const { load, value } = await withVerifiedApp(
     appModule,
     rootDirResult.value,
@@ -674,6 +864,7 @@ const promoteDraftState = async (
         renames,
         updatedSourceFiles,
         appModule,
+        rewriteResult.value.plannedOperations,
         input.toId
       )
   );
@@ -685,7 +876,9 @@ const promoteDraftState = async (
       load.loadError,
       renames,
       updatedSourceFiles,
-      appModule
+      appModule,
+      rewriteResult.value.plannedOperations,
+      false
     )
   );
 };
@@ -712,6 +905,10 @@ export const draftPromoteTrail = trail('draft.promote', {
       .string()
       .optional()
       .describe('Optional app module to verify after promotion'),
+    dryRun: z
+      .boolean()
+      .default(false)
+      .describe('Plan promotion rewrites without touching source files'),
     fromId: z.string().describe('Draft id to promote'),
     renameFiles: z
       .boolean()
@@ -725,7 +922,19 @@ export const draftPromoteTrail = trail('draft.promote', {
   intent: 'write',
   output: z.object({
     appModule: z.string().nullable(),
+    dryRun: z.boolean(),
     message: z.string(),
+    plannedOperations: z.array(
+      z.discriminatedUnion('kind', [
+        z.object({ kind: z.literal('mkdir'), path: z.string() }),
+        z.object({
+          from: z.string(),
+          kind: z.literal('rename'),
+          to: z.string(),
+        }),
+        z.object({ kind: z.literal('write'), path: z.string() }),
+      ])
+    ),
     promotedEstablished: z.boolean(),
     remainingDraftIds: z.array(z.string()),
     renamedFiles: z.array(