@ontrails/trails 1.0.0-beta.4 → 1.0.0-beta.42

package/src/trails/dev-support.ts

@@ -0,0 +1,360 @@
+import { existsSync, statSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+
+import {
+  openReadTrailsDb,
+  openWriteTrailsDb,
+  deriveTrailsDbPath,
+} from '@ontrails/core';
+import {
+  countPinnedSnapshots,
+  countPrunableSnapshots,
+  countTopoSnapshots,
+  pruneUnpinnedSnapshots,
+} from '@ontrails/topography/backend-support';
+import {
+  DEFAULT_MAX_AGE,
+  DEFAULT_MAX_RECORDS,
+  applyTraceCleanup,
+  countTraceRecords,
+  previewTraceCleanup,
+} from '@ontrails/tracing';
+
+import {
+  removeFileIfPresent,
+  removeRootRelativeFileIfPresent,
+} from '../local-state-io.js';
+
+import { requireTrailRootDir } from './root-dir.js';
+
+export const DEFAULT_TOPO_SNAPSHOT_RETENTION = 50;
+
+const deriveRootDir = (cwd?: string): string => requireTrailRootDir(cwd);
+
+const removeResetFileIfPresent = (
+  rootDir: string,
+  resetPath: string
+): boolean => {
+  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;
+  }
+  return removed.value;
+};
+
+export interface DevStatsReport {
+  readonly db: {
+    readonly exists: boolean;
+    readonly fileSizeBytes: number;
+    readonly path: string;
+  };
+  readonly lock: {
+    readonly exists: boolean;
+    readonly fileSizeBytes: number;
+    readonly path: string;
+  };
+  readonly retention: {
+    readonly snapshots: number;
+    readonly traceAgeMs: number;
+    readonly traces: number;
+  };
+  readonly topo: {
+    readonly pinnedCount: number;
+    readonly prunableSnapshotCount: number;
+    readonly snapshotCount: number;
+  };
+  readonly tracing: {
+    readonly recordCount: number;
+  };
+}
+
+export interface DevCleanReport {
+  readonly dryRun: boolean;
+  readonly remaining: {
+    readonly pinnedCount: number;
+    readonly snapshotCount: number;
+    readonly traceCount: number;
+  };
+  readonly removed: {
+    readonly topoSnapshots: number;
+    readonly traceRecords: number;
+  };
+  readonly retention: {
+    readonly snapshots: number;
+    readonly traceAgeMs: number;
+    readonly traces: number;
+  };
+}
+
+export interface DevResetReport {
+  readonly dryRun: boolean;
+  readonly removedCount: number;
+  readonly removedFiles: readonly string[];
+}
+
+interface DevRetentionOptions {
+  readonly maxAge?: number;
+  readonly maxRecords?: number;
+  readonly rootDir?: string;
+  readonly snapshotRetention?: number;
+}
+
+interface DevCleanupContext {
+  readonly dbPath: string;
+  readonly dryRun: boolean;
+  readonly retention: DevCleanReport['retention'];
+  readonly rootDir: string;
+}
+
+const buildRetention = (options?: DevRetentionOptions) => ({
+  snapshots: options?.snapshotRetention ?? DEFAULT_TOPO_SNAPSHOT_RETENTION,
+  traceAgeMs: options?.maxAge ?? DEFAULT_MAX_AGE,
+  traces: options?.maxRecords ?? DEFAULT_MAX_RECORDS,
+});
+
+const emptyDevClean = (
+  retention: DevCleanReport['retention'],
+  dryRun: boolean
+): DevCleanReport => ({
+  dryRun,
+  remaining: {
+    pinnedCount: 0,
+    snapshotCount: 0,
+    traceCount: 0,
+  },
+  removed: {
+    topoSnapshots: 0,
+    traceRecords: 0,
+  },
+  retention,
+});
+
+const buildLockStats = (lockPath: string): DevStatsReport['lock'] => ({
+  exists: existsSync(lockPath),
+  fileSizeBytes: existsSync(lockPath) ? statSync(lockPath).size : 0,
+  path: lockPath,
+});
+
+const buildDbStats = (
+  dbPath: string,
+  exists: boolean
+): DevStatsReport['db'] => ({
+  exists,
+  fileSizeBytes: exists ? statSync(dbPath).size : 0,
+  path: dbPath,
+});
+
+const emptyDevStats = (
+  dbPath: string,
+  lockPath: string,
+  retention: DevStatsReport['retention']
+): DevStatsReport => ({
+  db: buildDbStats(dbPath, false),
+  lock: buildLockStats(lockPath),
+  retention,
+  topo: {
+    pinnedCount: 0,
+    prunableSnapshotCount: 0,
+    snapshotCount: 0,
+  },
+  tracing: {
+    recordCount: 0,
+  },
+});
+
+const liveDevStats = (
+  db: Parameters<typeof countPinnedSnapshots>[0],
+  dbPath: string,
+  lockPath: string,
+  retention: DevStatsReport['retention']
+): DevStatsReport => ({
+  db: buildDbStats(dbPath, true),
+  lock: buildLockStats(lockPath),
+  retention,
+  topo: {
+    pinnedCount: countPinnedSnapshots(db),
+    prunableSnapshotCount: countPrunableSnapshots(db, {
+      keep: retention.snapshots,
+    }),
+    snapshotCount: countTopoSnapshots(db),
+  },
+  tracing: {
+    recordCount: countTraceRecords(db),
+  },
+});
+
+const deriveDevStatsContext = (options?: DevRetentionOptions) => {
+  const rootDir = deriveRootDir(options?.rootDir);
+  const dbPath = deriveTrailsDbPath({ rootDir });
+  const lockPath = join(rootDir, 'trails.lock');
+  return {
+    dbExists: existsSync(dbPath),
+    dbPath,
+    lockPath,
+    retention: buildRetention(options),
+    rootDir,
+  };
+};
+
+const deriveDevCleanupContext = (
+  options?: DevRetentionOptions & { readonly dryRun?: boolean }
+): DevCleanupContext => {
+  const rootDir = deriveRootDir(options?.rootDir);
+  return {
+    dbPath: deriveTrailsDbPath({ rootDir }),
+    dryRun: options?.dryRun ?? false,
+    retention: buildRetention(options),
+    rootDir,
+  };
+};
+
+const cleanupTraces = (
+  db: Parameters<typeof countPinnedSnapshots>[0],
+  context: DevCleanupContext
+) =>
+  context.dryRun
+    ? previewTraceCleanup(db, {
+        maxAge: context.retention.traceAgeMs,
+        maxRecords: context.retention.traces,
+      })
+    : applyTraceCleanup(db, {
+        maxAge: context.retention.traceAgeMs,
+        maxRecords: context.retention.traces,
+      });
+
+const cleanupTopoSnapshots = (
+  db: Parameters<typeof countPinnedSnapshots>[0],
+  context: DevCleanupContext
+): number =>
+  context.dryRun
+    ? countPrunableSnapshots(db, { keep: context.retention.snapshots })
+    : pruneUnpinnedSnapshots(db, { keep: context.retention.snapshots });
+
+const buildCleanReport = (
+  db: Parameters<typeof countPinnedSnapshots>[0],
+  context: DevCleanupContext
+): DevCleanReport => {
+  const traceReport = cleanupTraces(db, context);
+  const topoRemoved = cleanupTopoSnapshots(db, context);
+  const snapshotCount = countTopoSnapshots(db);
+
+  return {
+    dryRun: context.dryRun,
+    remaining: {
+      pinnedCount: countPinnedSnapshots(db),
+      snapshotCount: context.dryRun
+        ? snapshotCount - topoRemoved
+        : snapshotCount,
+      traceCount: context.dryRun
+        ? traceReport.remaining - traceReport.removedTotal
+        : traceReport.remaining,
+    },
+    removed: {
+      topoSnapshots: topoRemoved,
+      traceRecords: traceReport.removedTotal,
+    },
+    retention: context.retention,
+  };
+};
+
+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 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
+): DevStatsReport => {
+  const { dbExists, dbPath, lockPath, retention, rootDir } =
+    deriveDevStatsContext(options);
+
+  if (!dbExists) {
+    return emptyDevStats(dbPath, lockPath, retention);
+  }
+
+  const db = openReadTrailsDb({ rootDir });
+
+  try {
+    return liveDevStats(db, dbPath, lockPath, retention);
+  } finally {
+    db.close();
+  }
+};
+
+export const cleanDevState = (
+  options?: DevRetentionOptions & { readonly dryRun?: boolean }
+): DevCleanReport => {
+  const context = deriveDevCleanupContext(options);
+  if (!existsSync(context.dbPath)) {
+    return emptyDevClean(context.retention, context.dryRun);
+  }
+
+  const db = context.dryRun
+    ? openReadTrailsDb({ rootDir: context.rootDir })
+    : openWriteTrailsDb({ rootDir: context.rootDir });
+
+  try {
+    return buildCleanReport(db, context);
+  } finally {
+    db.close();
+  }
+};
+
+export const resetDevState = (options?: {
+  readonly dryRun?: boolean;
+  readonly rootDir?: string;
+}): DevResetReport => {
+  const rootDir = deriveRootDir(options?.rootDir);
+  const files = presentResetFiles(rootDir);
+
+  if (options?.dryRun === true) {
+    return {
+      dryRun: true,
+      removedCount: files.length,
+      removedFiles: files,
+    };
+  }
+
+  const removedFiles = files.filter((relativePath) =>
+    removeResetFileIfPresent(rootDir, relativePath)
+  );
+
+  return {
+    dryRun: false,
+    removedCount: removedFiles.length,
+    removedFiles,
+  };
+};

package/src/trails/doctor.ts

@@ -0,0 +1,77 @@
+import {
+  deriveTrailsDir,
+  InternalError,
+  isTrailsError,
+  Result,
+  trail,
+} from '@ontrails/core';
+import { readTopoGraph } from '@ontrails/topography';
+import { z } from 'zod';
+
+import {
+  deriveDoctorSummary,
+  withLifecycleApp,
+} from './version-lifecycle-support.js';
+
+const readDoctorForceGraph = async (
+  rootDir: string
+): Promise<Awaited<ReturnType<typeof readTopoGraph>> | undefined> => {
+  try {
+    return await readTopoGraph({ dir: deriveTrailsDir({ rootDir }) });
+  } catch {
+    // Force audit details are supplemental; stale topo locks should not block doctor counts.
+    return undefined;
+  }
+};
+
+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', {
+  description: 'Diagnose trail versioning lifecycle state',
+  implementation: async (input, ctx) =>
+    withLifecycleApp(input, ctx.cwd, async (app, rootDir) => {
+      const forceGraph = await readDoctorForceGraph(rootDir);
+      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));
+      }
+    }),
+  input: z.object({
+    module: z.string().optional().describe('Path to the app module'),
+    rootDir: z.string().optional().describe('Workspace root directory'),
+  }),
+  intent: 'read',
+  output: z.object({
+    archived: z.number(),
+    deprecated: z.number(),
+    forceDetails: z.array(
+      z
+        .object({
+          acceptedAt: z.string(),
+          change: z.enum(['modified', 'removed']),
+          detail: z.string(),
+          id: z.string(),
+          kind: z.enum(['entity', 'trail', 'signal', 'resource']),
+          reason: z.string().optional(),
+          scope: z.enum(['entry', 'graph']),
+          severity: z.literal('breaking'),
+          source: z.literal('trails compile --force'),
+        })
+        .strict()
+    ),
+    forceEvents: z.number(),
+    mode: z.literal('doctor'),
+    trails: z.number(),
+    versioned: z.number(),
+  }),
+});