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

package/src/trails/dev-stats.ts

@@ -1,39 +1,47 @@
 import { Result, trail } from '@ontrails/core';
 import { z } from 'zod';
 
-import { buildDevStats, DEFAULT_TOPO_SAVE_RETENTION } from './dev-support.js';
-import { isolatedExampleInput } from './topo-support.js';
+import {
+  buildDevStats,
+  DEFAULT_TOPO_SNAPSHOT_RETENTION,
+} from './dev-support.js';
+import { resolveTrailRootDir } from './root-dir.js';
+import { createIsolatedExampleInput } from './topo-support.js';
 
 export const devStatsTrail = trail('dev.stats', {
   blaze: (input, ctx) => {
-    const rootDir = input.rootDir ?? ctx.cwd ?? process.cwd();
+    const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
+    if (rootDirResult.isErr()) {
+      return Result.err(rootDirResult.error);
+    }
+    const rootDir = rootDirResult.value;
     return Result.ok(
       buildDevStats({
-        maxAge: input.trackAgeMs,
-        maxRecords: input.tracks,
+        maxAge: input.traceAgeMs,
+        maxRecords: input.traces,
         rootDir,
-        saveRetention: input.saves,
+        snapshotRetention: input.snapshots,
       })
     );
   },
   description: 'Show local Trails workspace state and retention',
   examples: [
     {
-      input: { rootDir: isolatedExampleInput('dev-stats').rootDir },
+      input: { rootDir: createIsolatedExampleInput('dev-stats').rootDir },
       name: 'Show local dev state',
     },
   ],
   input: z.object({
     rootDir: z.string().optional().describe('Workspace root directory'),
-    saves: z
+    snapshots: z
       .number()
-      .default(DEFAULT_TOPO_SAVE_RETENTION)
-      .describe('Unpinned topo saves to retain'),
-    trackAgeMs: z
+      .default(DEFAULT_TOPO_SNAPSHOT_RETENTION)
+      .describe('Unpinned topo snapshots to retain'),
+    traceAgeMs: z
       .number()
       .default(7 * 24 * 60 * 60 * 1000)
-      .describe('Maximum retained track age in milliseconds'),
-    tracks: z.number().default(10_000).describe('Maximum retained track count'),
+      .describe('Maximum retained trace age in milliseconds'),
+    traces: z.number().default(10_000).describe('Maximum retained trace count'),
   }),
   intent: 'read',
   output: z.object({
@@ -48,16 +56,16 @@ export const devStatsTrail = trail('dev.stats', {
       path: z.string(),
     }),
     retention: z.object({
-      saves: z.number(),
-      trackAgeMs: z.number(),
-      tracks: z.number(),
+      snapshots: z.number(),
+      traceAgeMs: z.number(),
+      traces: z.number(),
     }),
     topo: z.object({
-      pinCount: z.number(),
-      prunableSaveCount: z.number(),
-      saveCount: z.number(),
+      pinnedCount: z.number(),
+      prunableSnapshotCount: z.number(),
+      snapshotCount: z.number(),
     }),
-    tracker: z.object({
+    tracing: z.object({
       recordCount: z.number(),
     }),
   }),

package/src/trails/dev-support.ts

@@ -1,38 +1,43 @@
-import { existsSync, rmSync, statSync } from 'node:fs';
+import { existsSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 
-import {
-  countPrunableTopoSaves,
-  countTopoPins,
-  countTopoSaves,
-  pruneUnpinnedTopoSaves,
-} from '@ontrails/core/internal/topo-saves';
 import {
   openReadTrailsDb,
   openWriteTrailsDb,
-  resolveTrailsDbPath,
-  resolveTrailsDir,
-} from '@ontrails/core/internal/trails-db';
+  deriveTrailsDbPath,
+  deriveTrailsDir,
+} from '@ontrails/core';
+import {
+  countPinnedSnapshots,
+  countPrunableSnapshots,
+  countTopoSnapshots,
+  pruneUnpinnedSnapshots,
+} from '@ontrails/topographer/backend-support';
 import {
   DEFAULT_MAX_AGE,
   DEFAULT_MAX_RECORDS,
-  applyTrackCleanup,
-  countTrackRecords,
-  previewTrackCleanup,
-} from '@ontrails/tracker/internal/dev-state';
+  applyTraceCleanup,
+  countTraceRecords,
+  previewTraceCleanup,
+} from '@ontrails/tracing';
+
+import { removeRootRelativeFileIfPresent } from '../local-state-io.js';
 
-import { resolveLockPath } from './topo-support.js';
+import { requireTrailRootDir } from './root-dir.js';
 
-export const DEFAULT_TOPO_SAVE_RETENTION = 50;
+export const DEFAULT_TOPO_SNAPSHOT_RETENTION = 50;
 
-const resolveRootDir = (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 {
@@ -47,16 +52,16 @@ export interface DevStatsReport {
     readonly path: string;
   };
   readonly retention: {
-    readonly saves: number;
-    readonly trackAgeMs: number;
-    readonly tracks: number;
+    readonly snapshots: number;
+    readonly traceAgeMs: number;
+    readonly traces: number;
   };
   readonly topo: {
-    readonly pinCount: number;
-    readonly prunableSaveCount: number;
-    readonly saveCount: number;
+    readonly pinnedCount: number;
+    readonly prunableSnapshotCount: number;
+    readonly snapshotCount: number;
   };
-  readonly tracker: {
+  readonly tracing: {
     readonly recordCount: number;
   };
 }
@@ -64,18 +69,18 @@ export interface DevStatsReport {
 export interface DevCleanReport {
   readonly dryRun: boolean;
   readonly remaining: {
-    readonly pinCount: number;
-    readonly saveCount: number;
-    readonly trackCount: number;
+    readonly pinnedCount: number;
+    readonly snapshotCount: number;
+    readonly traceCount: number;
   };
   readonly removed: {
-    readonly topoSaves: number;
-    readonly trackRecords: number;
+    readonly topoSnapshots: number;
+    readonly traceRecords: number;
   };
   readonly retention: {
-    readonly saves: number;
-    readonly trackAgeMs: number;
-    readonly tracks: number;
+    readonly snapshots: number;
+    readonly traceAgeMs: number;
+    readonly traces: number;
   };
 }
 
@@ -89,7 +94,7 @@ interface DevRetentionOptions {
   readonly maxAge?: number;
   readonly maxRecords?: number;
   readonly rootDir?: string;
-  readonly saveRetention?: number;
+  readonly snapshotRetention?: number;
 }
 
 interface DevCleanupContext {
@@ -100,9 +105,9 @@ interface DevCleanupContext {
 }
 
 const buildRetention = (options?: DevRetentionOptions) => ({
-  saves: options?.saveRetention ?? DEFAULT_TOPO_SAVE_RETENTION,
-  trackAgeMs: options?.maxAge ?? DEFAULT_MAX_AGE,
-  tracks: options?.maxRecords ?? DEFAULT_MAX_RECORDS,
+  snapshots: options?.snapshotRetention ?? DEFAULT_TOPO_SNAPSHOT_RETENTION,
+  traceAgeMs: options?.maxAge ?? DEFAULT_MAX_AGE,
+  traces: options?.maxRecords ?? DEFAULT_MAX_RECORDS,
 });
 
 const emptyDevClean = (
@@ -111,13 +116,13 @@ const emptyDevClean = (
 ): DevCleanReport => ({
   dryRun,
   remaining: {
-    pinCount: 0,
-    saveCount: 0,
-    trackCount: 0,
+    pinnedCount: 0,
+    snapshotCount: 0,
+    traceCount: 0,
   },
   removed: {
-    topoSaves: 0,
-    trackRecords: 0,
+    topoSnapshots: 0,
+    traceRecords: 0,
   },
   retention,
 });
@@ -134,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 = (
@@ -146,17 +151,17 @@ const emptyDevStats = (
   lock: buildLockStats(lockPath),
   retention,
   topo: {
-    pinCount: 0,
-    prunableSaveCount: 0,
-    saveCount: 0,
+    pinnedCount: 0,
+    prunableSnapshotCount: 0,
+    snapshotCount: 0,
   },
-  tracker: {
+  tracing: {
     recordCount: 0,
   },
 });
 
 const liveDevStats = (
-  db: Parameters<typeof countTopoPins>[0],
+  db: Parameters<typeof countPinnedSnapshots>[0],
   dbPath: string,
   lockPath: string,
   retention: DevStatsReport['retention']
@@ -165,20 +170,22 @@ const liveDevStats = (
   lock: buildLockStats(lockPath),
   retention,
   topo: {
-    pinCount: countTopoPins(db),
-    prunableSaveCount: countPrunableTopoSaves(db, { keep: retention.saves }),
-    saveCount: countTopoSaves(db),
+    pinnedCount: countPinnedSnapshots(db),
+    prunableSnapshotCount: countPrunableSnapshots(db, {
+      keep: retention.snapshots,
+    }),
+    snapshotCount: countTopoSnapshots(db),
   },
-  tracker: {
-    recordCount: countTrackRecords(db),
+  tracing: {
+    recordCount: countTraceRecords(db),
   },
 });
 
-const resolveDevStatsContext = (options?: DevRetentionOptions) => {
-  const rootDir = resolveRootDir(options?.rootDir);
-  const dbPath = resolveTrailsDbPath({ rootDir });
-  const trailsDir = resolveTrailsDir({ rootDir });
-  const lockPath = resolveLockPath(trailsDir);
+const deriveDevStatsContext = (options?: DevRetentionOptions) => {
+  const rootDir = deriveRootDir(options?.rootDir);
+  const dbPath = deriveTrailsDbPath({ rootDir });
+  const trailsDir = deriveTrailsDir({ rootDir });
+  const lockPath = join(trailsDir, 'trails.lock');
   return {
     dbExists: existsSync(dbPath),
     dbPath,
@@ -188,72 +195,79 @@ const resolveDevStatsContext = (options?: DevRetentionOptions) => {
   };
 };
 
-const resolveDevCleanupContext = (
+const deriveDevCleanupContext = (
   options?: DevRetentionOptions & { readonly dryRun?: boolean }
 ): DevCleanupContext => {
-  const rootDir = resolveRootDir(options?.rootDir);
+  const rootDir = deriveRootDir(options?.rootDir);
   return {
-    dbPath: resolveTrailsDbPath({ rootDir }),
+    dbPath: deriveTrailsDbPath({ rootDir }),
     dryRun: options?.dryRun ?? false,
     retention: buildRetention(options),
     rootDir,
   };
 };
 
-const cleanupTracks = (
-  db: Parameters<typeof countTopoPins>[0],
+const cleanupTraces = (
+  db: Parameters<typeof countPinnedSnapshots>[0],
   context: DevCleanupContext
 ) =>
   context.dryRun
-    ? previewTrackCleanup(db, {
-        maxAge: context.retention.trackAgeMs,
-        maxRecords: context.retention.tracks,
+    ? previewTraceCleanup(db, {
+        maxAge: context.retention.traceAgeMs,
+        maxRecords: context.retention.traces,
       })
-    : applyTrackCleanup(db, {
-        maxAge: context.retention.trackAgeMs,
-        maxRecords: context.retention.tracks,
+    : applyTraceCleanup(db, {
+        maxAge: context.retention.traceAgeMs,
+        maxRecords: context.retention.traces,
       });
 
-const cleanupTopoSaves = (
-  db: Parameters<typeof countTopoPins>[0],
+const cleanupTopoSnapshots = (
+  db: Parameters<typeof countPinnedSnapshots>[0],
   context: DevCleanupContext
 ): number =>
   context.dryRun
-    ? countPrunableTopoSaves(db, { keep: context.retention.saves })
-    : pruneUnpinnedTopoSaves(db, { keep: context.retention.saves });
+    ? countPrunableSnapshots(db, { keep: context.retention.snapshots })
+    : pruneUnpinnedSnapshots(db, { keep: context.retention.snapshots });
 
 const buildCleanReport = (
-  db: Parameters<typeof countTopoPins>[0],
+  db: Parameters<typeof countPinnedSnapshots>[0],
   context: DevCleanupContext
 ): DevCleanReport => {
-  const trackReport = cleanupTracks(db, context);
-  const topoRemoved = cleanupTopoSaves(db, context);
-  const saveCount = countTopoSaves(db);
+  const traceReport = cleanupTraces(db, context);
+  const topoRemoved = cleanupTopoSnapshots(db, context);
+  const snapshotCount = countTopoSnapshots(db);
 
   return {
     dryRun: context.dryRun,
     remaining: {
-      pinCount: countTopoPins(db),
-      saveCount: context.dryRun ? saveCount - topoRemoved : saveCount,
-      trackCount: context.dryRun
-        ? trackReport.remaining - trackReport.removedTotal
-        : trackReport.remaining,
+      pinnedCount: countPinnedSnapshots(db),
+      snapshotCount: context.dryRun
+        ? snapshotCount - topoRemoved
+        : snapshotCount,
+      traceCount: context.dryRun
+        ? traceReport.remaining - traceReport.removedTotal
+        : traceReport.remaining,
     },
     removed: {
-      topoSaves: topoRemoved,
-      trackRecords: trackReport.removedTotal,
+      topoSnapshots: topoRemoved,
+      traceRecords: traceReport.removedTotal,
     },
     retention: context.retention,
   };
 };
 
 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/tracker.db',
-  '.trails/dev/tracker.db-shm',
-  '.trails/dev/tracker.db-wal',
+  '.trails/dev/tracing.db',
+  '.trails/dev/tracing.db-shm',
+  '.trails/dev/tracing.db-wal',
 ] as const;
 
 const presentResetFiles = (
@@ -265,7 +279,7 @@ export const buildDevStats = (
   options?: DevRetentionOptions
 ): DevStatsReport => {
   const { dbExists, dbPath, lockPath, retention, rootDir } =
-    resolveDevStatsContext(options);
+    deriveDevStatsContext(options);
 
   if (!dbExists) {
     return emptyDevStats(dbPath, lockPath, retention);
@@ -283,7 +297,7 @@ export const buildDevStats = (
 export const cleanDevState = (
   options?: DevRetentionOptions & { readonly dryRun?: boolean }
 ): DevCleanReport => {
-  const context = resolveDevCleanupContext(options);
+  const context = deriveDevCleanupContext(options);
   if (!existsSync(context.dbPath)) {
     return emptyDevClean(context.retention, context.dryRun);
   }
@@ -303,7 +317,7 @@ export const resetDevState = (options?: {
   readonly dryRun?: boolean;
   readonly rootDir?: string;
 }): DevResetReport => {
-  const rootDir = resolveRootDir(options?.rootDir);
+  const rootDir = deriveRootDir(options?.rootDir);
   const files = presentResetFiles(rootDir);
 
   if (options?.dryRun === true) {
@@ -315,7 +329,7 @@ export const resetDevState = (options?: {
   }
 
   const removedFiles = files.filter((relativePath) =>
-    removeIfPresent(join(rootDir, relativePath))
+    removeResetFileIfPresent(rootDir, relativePath)
   );
 
   return {