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

package/src/__tests__/topo-dev.test.ts

@@ -0,0 +1,424 @@
+/* oxlint-disable max-statements */
+
+import { describe, expect, test } from 'bun:test';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { join, resolve } from 'node:path';
+
+import type { Result } from '@ontrails/core';
+import { openReadTrailsDb } from '@ontrails/core/internal/trails-db';
+import { createDevStore } from '@ontrails/tracker';
+
+import { devCleanTrail } from '../trails/dev-clean.js';
+import { devResetTrail } from '../trails/dev-reset.js';
+import { devStatsTrail } from '../trails/dev-stats.js';
+import { guideTrail } from '../trails/guide.js';
+import { surveyTrail } from '../trails/survey.js';
+import { topoExportTrail } from '../trails/topo-export.js';
+import { topoHistoryTrail } from '../trails/topo-history.js';
+import { topoPinTrail } from '../trails/topo-pin.js';
+import { topoShowTrail } from '../trails/topo-show.js';
+import { topoTrail } from '../trails/topo.js';
+import { topoUnpinTrail } from '../trails/topo-unpin.js';
+import { topoVerifyTrail } from '../trails/topo-verify.js';
+
+const repoTempDir = (): string =>
+  join(
+    resolve(import.meta.dir, '../..'),
+    '.tmp-tests',
+    `topo-dev-${Date.now()}-${Math.random().toString(36).slice(2)}`
+  );
+
+const expectOk = <T>(result: Result<T, Error>): T => {
+  if (result.isErr()) {
+    throw result.error;
+  }
+  return result.value;
+};
+
+const expectErr = <E extends Error>(result: Result<unknown, E>): E => {
+  if (result.isOk()) {
+    throw new Error('expected result to be an error');
+  }
+  return result.error;
+};
+
+const moduleInput = { module: './src/app.ts' } as const;
+
+const writeAppFixture = (dir: string): void => {
+  mkdirSync(join(dir, 'src'), { recursive: true });
+  writeFileSync(
+    join(dir, 'src', 'app.ts'),
+    `import { Result, provision, topo, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+const hello = trail('hello', {
+  blaze: async (input) => Result.ok({ message: \`Hello, \${input.name ?? 'world'}!\` }),
+  crosses: ['goodbye'],
+  examples: [{ input: {}, name: 'Default greeting' }],
+  input: z.object({ name: z.string().optional() }),
+  intent: 'read',
+  output: z.object({ message: z.string() }),
+  provisions: [
+    provision('db.main', {
+      create: () => Result.ok({ source: 'factory' }),
+    }),
+  ],
+});
+
+const goodbye = trail('goodbye', {
+  blaze: async () => Result.ok({ ok: true }),
+  input: z.object({}),
+  intent: 'write',
+  output: z.object({ ok: z.boolean() }),
+});
+
+const [dbMain] = hello.provisions;
+if (!dbMain) {
+  throw new Error('expected hello to declare db.main');
+}
+
+export const app = topo('fixture-app', { dbMain, goodbye, hello });
+`
+  );
+};
+
+describe('topo and dev trails', () => {
+  test('topo surfaces current summary, detail, and export/verify flow', async () => {
+    const dir = repoTempDir();
+
+    try {
+      writeAppFixture(dir);
+
+      const summary = expectOk(
+        await topoTrail.blaze(moduleInput, { cwd: dir } as never)
+      );
+      expect(summary.app.name).toBe('fixture-app');
+      expect(summary.list.count).toBe(2);
+      expect(summary.list.provisionCount).toBe(1);
+      expect(summary.lockExists).toBe(false);
+
+      const detail = expectOk(
+        await topoShowTrail.blaze({ ...moduleInput, id: 'hello' }, {
+          cwd: dir,
+        } as never)
+      );
+      expect(detail.id).toBe('hello');
+      expect(detail.provisions).toEqual(['db.main']);
+
+      const exportResult = expectOk(
+        await topoExportTrail.blaze(moduleInput, { cwd: dir } as never)
+      );
+      expect(exportResult.hash).toHaveLength(64);
+      expect(existsSync(join(dir, '.trails', '_trailhead.json'))).toBe(true);
+      expect(existsSync(join(dir, '.trails', 'trails.lock'))).toBe(true);
+      expect(
+        JSON.parse(readFileSync(join(dir, '.trails', 'trails.lock'), 'utf8'))
+      ).toMatchObject({
+        hash: exportResult.hash,
+        version: 1,
+      });
+
+      writeFileSync(
+        join(dir, '.trails', 'trailhead.lock'),
+        readFileSync(join(dir, '.trails', 'trails.lock'), 'utf8')
+      );
+      rmSync(join(dir, '.trails', 'trails.lock'));
+
+      const legacySummary = expectOk(
+        await topoTrail.blaze(moduleInput, { cwd: dir } as never)
+      );
+      expect(legacySummary.lockExists).toBe(true);
+
+      const verifyResult = expectOk(
+        await topoVerifyTrail.blaze(moduleInput, { cwd: dir } as never)
+      );
+      expect(verifyResult.stale).toBe(false);
+
+      writeFileSync(join(dir, '.trails', 'trailhead.lock'), 'stale\n');
+      const verifyError = expectErr(
+        await topoVerifyTrail.blaze(moduleInput, { cwd: dir } as never)
+      );
+      expect(verifyError.message).toContain('trails.lock is stale');
+    } finally {
+      rmSync(dir, { force: true, recursive: true });
+    }
+  });
+
+  test('survey and guide read current topo state through the shared topo store', async () => {
+    const dir = repoTempDir();
+
+    try {
+      writeAppFixture(dir);
+
+      const surveyList = expectOk(
+        await surveyTrail.blaze({ module: './src/app.ts' }, {
+          cwd: dir,
+        } as never)
+      );
+      expect(surveyList).toMatchObject({
+        count: 2,
+        provisionCount: 1,
+      });
+
+      const surveyBrief = expectOk(
+        await surveyTrail.blaze({ brief: true, module: './src/app.ts' }, {
+          cwd: dir,
+        } as never)
+      );
+      expect(surveyBrief).toMatchObject({
+        features: {
+          examples: true,
+          outputSchemas: true,
+          provisions: true,
+        },
+        name: 'fixture-app',
+        trails: 2,
+      });
+
+      const surveyDetail = expectOk(
+        await surveyTrail.blaze({ module: './src/app.ts', trailId: 'hello' }, {
+          cwd: dir,
+        } as never)
+      );
+      expect(surveyDetail).toMatchObject({
+        id: 'hello',
+        provisions: ['db.main'],
+      });
+
+      const guideList = expectOk(
+        await guideTrail.blaze({ module: './src/app.ts' }, {
+          cwd: dir,
+        } as never)
+      );
+      expect(guideList).toEqual([
+        {
+          description: '(no description)',
+          exampleCount: 0,
+          id: 'goodbye',
+          kind: 'trail',
+        },
+        {
+          description: '(no description)',
+          exampleCount: 1,
+          id: 'hello',
+          kind: 'trail',
+        },
+      ]);
+
+      const guideDetail = expectOk(
+        await guideTrail.blaze({ module: './src/app.ts', trailId: 'hello' }, {
+          cwd: dir,
+        } as never)
+      );
+      expect(guideDetail).toMatchObject({
+        description: null,
+        examples: [
+          {
+            input: {},
+            name: 'Default greeting',
+          },
+        ],
+        id: 'hello',
+        kind: 'trail',
+      });
+    } finally {
+      rmSync(dir, { force: true, recursive: true });
+    }
+  });
+
+  test('pinning, history, unpinning, and dev maintenance work against shared trails.db', async () => {
+    const dir = repoTempDir();
+
+    try {
+      writeAppFixture(dir);
+
+      const firstPin = expectOk(
+        await topoPinTrail.blaze({ ...moduleInput, name: 'before-auth' }, {
+          cwd: dir,
+        } as never)
+      );
+      expect(firstPin.pin.name).toBe('before-auth');
+      expect(firstPin.pin.saveId).toBe(firstPin.save.id);
+
+      const firstExport = expectOk(
+        await topoExportTrail.blaze(moduleInput, { cwd: dir } as never)
+      );
+      const secondExport = expectOk(
+        await topoExportTrail.blaze(moduleInput, { cwd: dir } as never)
+      );
+      expect(firstExport.hash).toBe(secondExport.hash);
+      expect(
+        JSON.parse(readFileSync(join(dir, '.trails', 'trails.lock'), 'utf8'))
+      ).toMatchObject({
+        hash: secondExport.hash,
+        version: 1,
+      });
+
+      const projectionDb = openReadTrailsDb({ rootDir: dir });
+      try {
+        const pinnedRows = projectionDb
+          .query<{ count: number }, [string]>(
+            'SELECT COUNT(*) as count FROM topo_trails WHERE save_id = ?'
+          )
+          .get(firstPin.save.id);
+        const exportedRows = projectionDb
+          .query<{ count: number }, [string]>(
+            'SELECT COUNT(*) as count FROM topo_trails WHERE save_id = ?'
+          )
+          .get(firstExport.save.id);
+        const projectedSaves = projectionDb
+          .query<{ count: number }, []>(
+            'SELECT COUNT(DISTINCT save_id) as count FROM topo_trails'
+          )
+          .get();
+        const cachedSchemas = projectionDb
+          .query<{ count: number }, []>(
+            'SELECT COUNT(*) as count FROM topo_schemas'
+          )
+          .get();
+
+        expect(pinnedRows?.count).toBe(2);
+        expect(exportedRows?.count).toBe(2);
+        expect(projectedSaves?.count).toBe(3);
+        expect(cachedSchemas?.count).toBeGreaterThanOrEqual(9);
+      } finally {
+        projectionDb.close();
+      }
+
+      const store = createDevStore({ rootDir: dir });
+      try {
+        store.write({
+          attrs: {},
+          endedAt: Date.now() - 1000,
+          id: 'track-1',
+          kind: 'trail',
+          name: 'hello',
+          rootId: 'track-1',
+          startedAt: Date.now() - 10_000,
+          status: 'ok',
+          traceId: 'trace-1',
+          trailId: 'hello',
+          trailhead: 'cli',
+        });
+        store.write({
+          attrs: {},
+          endedAt: Date.now() - 500,
+          id: 'track-2',
+          kind: 'trail',
+          name: 'goodbye',
+          rootId: 'track-2',
+          startedAt: Date.now() - 20_000,
+          status: 'err',
+          traceId: 'trace-2',
+          trailId: 'goodbye',
+          trailhead: 'cli',
+        });
+      } finally {
+        store.close();
+      }
+
+      const history = expectOk(
+        await topoHistoryTrail.blaze({}, { cwd: dir } as never)
+      );
+      expect(history.pinCount).toBe(1);
+      expect(history.saveCount).toBeGreaterThanOrEqual(3);
+      expect(history.pins[0]?.saveId).toBe(firstPin.save.id);
+      expect(
+        history.saves.some((save) => save.id === secondExport.save.id)
+      ).toBe(true);
+
+      const stats = expectOk(
+        await devStatsTrail.blaze({}, { cwd: dir } as never)
+      );
+      expect(stats.topo.pinCount).toBe(1);
+      expect(stats.tracker.recordCount).toBe(2);
+
+      const cleanPreview = expectOk(
+        await devCleanTrail.blaze({ dryRun: true, saves: 0, trackAgeMs: 0 }, {
+          cwd: dir,
+        } as never)
+      );
+      expect(cleanPreview.dryRun).toBe(true);
+      expect(cleanPreview.removed.topoSaves).toBeGreaterThanOrEqual(2);
+      expect(cleanPreview.removed.trackRecords).toBe(2);
+
+      const cleanResult = expectOk(
+        await devCleanTrail.blaze(
+          { dryRun: false, saves: 0, trackAgeMs: 0, yes: true },
+          { cwd: dir } as never
+        )
+      );
+      expect(cleanResult.removed.trackRecords).toBe(2);
+      expect(cleanResult.remaining.pinCount).toBe(1);
+
+      const unpinPreview = expectOk(
+        await topoUnpinTrail.blaze({ dryRun: true, name: 'before-auth' }, {
+          cwd: dir,
+        } as never)
+      );
+      expect(unpinPreview.dryRun).toBe(true);
+      expect(unpinPreview.pin?.name).toBe('before-auth');
+
+      const unpinResult = expectOk(
+        await topoUnpinTrail.blaze(
+          { dryRun: false, name: 'before-auth', yes: true },
+          { cwd: dir } as never
+        )
+      );
+      expect(unpinResult.removed).toBe(true);
+
+      const resetPreview = expectOk(
+        await devResetTrail.blaze({ dryRun: true }, { cwd: dir } as never)
+      );
+      expect(resetPreview.dryRun).toBe(true);
+      expect(resetPreview.removedFiles).toContain('.trails/trails.db');
+
+      const resetResult = expectOk(
+        await devResetTrail.blaze({ dryRun: false, yes: true }, {
+          cwd: dir,
+        } as never)
+      );
+      expect(resetResult.removedFiles).toContain('.trails/trails.db');
+      expect(existsSync(join(dir, '.trails', 'trails.db'))).toBe(false);
+      expect(
+        readFileSync(join(dir, '.trails', 'trails.lock'), 'utf8').length
+      ).toBeGreaterThan(0);
+    } finally {
+      rmSync(dir, { force: true, recursive: true });
+    }
+  });
+
+  test('dev clean stays side-effect free when no local state exists', async () => {
+    const dir = repoTempDir();
+
+    try {
+      mkdirSync(dir, { recursive: true });
+
+      const preview = expectOk(
+        await devCleanTrail.blaze({ dryRun: true }, { cwd: dir } as never)
+      );
+      expect(preview.dryRun).toBe(true);
+      expect(preview.removed.topoSaves).toBe(0);
+      expect(preview.removed.trackRecords).toBe(0);
+      expect(existsSync(join(dir, '.trails', 'trails.db'))).toBe(false);
+
+      const applied = expectOk(
+        await devCleanTrail.blaze({ dryRun: false, yes: true }, {
+          cwd: dir,
+        } as never)
+      );
+      expect(applied.dryRun).toBe(false);
+      expect(applied.removed.topoSaves).toBe(0);
+      expect(applied.removed.trackRecords).toBe(0);
+      expect(existsSync(join(dir, '.trails', 'trails.db'))).toBe(false);
+    } finally {
+      rmSync(dir, { force: true, recursive: true });
+    }
+  });
+});

package/src/app.ts

@@ -5,14 +5,36 @@ import * as addTrail from './trails/add-trail.js';
 import * as addVerify from './trails/add-verify.js';
 import * as create from './trails/create.js';
 import * as createScaffold from './trails/create-scaffold.js';
+import * as devClean from './trails/dev-clean.js';
+import * as devReset from './trails/dev-reset.js';
+import * as devStats from './trails/dev-stats.js';
+import * as draftPromote from './trails/draft-promote.js';
 import * as guide from './trails/guide.js';
 import * as survey from './trails/survey.js';
+import * as topoExport from './trails/topo-export.js';
+import * as topoHistory from './trails/topo-history.js';
+import * as topoPin from './trails/topo-pin.js';
+import * as topoShow from './trails/topo-show.js';
+import * as topoCommand from './trails/topo.js';
+import * as topoUnpin from './trails/topo-unpin.js';
+import * as topoVerify from './trails/topo-verify.js';
 import * as warden from './trails/warden.js';
 
 export const app = topo(
   'trails',
   survey,
+  topoCommand,
+  topoShow,
+  topoHistory,
+  topoPin,
+  topoUnpin,
+  topoExport,
+  topoVerify,
+  devStats,
+  devClean,
+  devReset,
   guide,
+  draftPromote,
   warden,
   create,
   createScaffold,

package/src/trails/dev-clean.ts

@@ -0,0 +1,73 @@
+import { Result, ValidationError, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { cleanDevState, DEFAULT_TOPO_SAVE_RETENTION } from './dev-support.js';
+import { isolatedExampleInput } from './topo-support.js';
+
+export const devCleanTrail = trail('dev.clean', {
+  blaze: (input, ctx) => {
+    if (input.dryRun !== true && input.yes !== true) {
+      return Result.err(
+        new ValidationError(
+          'Refusing to clean local state without `--yes` or `--dry-run`.'
+        )
+      );
+    }
+
+    const rootDir = input.rootDir ?? ctx.cwd ?? process.cwd();
+    return Result.ok(
+      cleanDevState({
+        dryRun: input.dryRun,
+        maxAge: input.trackAgeMs,
+        maxRecords: input.tracks,
+        rootDir,
+        saveRetention: input.saves,
+      })
+    );
+  },
+  description: 'Prune unpinned topo saves and old track records',
+  examples: [
+    {
+      input: {
+        dryRun: true,
+        rootDir: isolatedExampleInput('dev-clean').rootDir,
+      },
+      name: 'Preview local cleanup',
+    },
+  ],
+  input: z.object({
+    dryRun: z
+      .boolean()
+      .default(true)
+      .describe('Preview cleanup without changing state'),
+    rootDir: z.string().optional().describe('Workspace root directory'),
+    saves: z
+      .number()
+      .default(DEFAULT_TOPO_SAVE_RETENTION)
+      .describe('Unpinned topo saves to retain'),
+    trackAgeMs: 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'),
+    yes: z.boolean().default(false).describe('Confirm destructive changes'),
+  }),
+  intent: 'destroy',
+  output: z.object({
+    dryRun: z.boolean(),
+    remaining: z.object({
+      pinCount: z.number(),
+      saveCount: z.number(),
+      trackCount: z.number(),
+    }),
+    removed: z.object({
+      topoSaves: z.number(),
+      trackRecords: z.number(),
+    }),
+    retention: z.object({
+      saves: z.number(),
+      trackAgeMs: z.number(),
+      tracks: z.number(),
+    }),
+  }),
+});

package/src/trails/dev-reset.ts

@@ -0,0 +1,44 @@
+import { Result, ValidationError, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { resetDevState } from './dev-support.js';
+import { isolatedExampleInput } from './topo-support.js';
+
+export const devResetTrail = trail('dev.reset', {
+  blaze: (input, ctx) => {
+    if (input.dryRun !== true && input.yes !== true) {
+      return Result.err(
+        new ValidationError(
+          'Refusing to reset local state without `--yes` or `--dry-run`.'
+        )
+      );
+    }
+
+    const rootDir = input.rootDir ?? ctx.cwd ?? process.cwd();
+    return Result.ok(resetDevState({ dryRun: input.dryRun, rootDir }));
+  },
+  description: 'Remove local Trails database artifacts',
+  examples: [
+    {
+      input: {
+        dryRun: true,
+        rootDir: isolatedExampleInput('dev-reset').rootDir,
+      },
+      name: 'Preview local reset',
+    },
+  ],
+  input: z.object({
+    dryRun: z
+      .boolean()
+      .default(true)
+      .describe('Preview reset without changing state'),
+    rootDir: z.string().optional().describe('Workspace root directory'),
+    yes: z.boolean().default(false).describe('Confirm destructive changes'),
+  }),
+  intent: 'destroy',
+  output: z.object({
+    dryRun: z.boolean(),
+    removedCount: z.number(),
+    removedFiles: z.array(z.string()),
+  }),
+});

package/src/trails/dev-stats.ts

@@ -0,0 +1,64 @@
+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';
+
+export const devStatsTrail = trail('dev.stats', {
+  blaze: (input, ctx) => {
+    const rootDir = input.rootDir ?? ctx.cwd ?? process.cwd();
+    return Result.ok(
+      buildDevStats({
+        maxAge: input.trackAgeMs,
+        maxRecords: input.tracks,
+        rootDir,
+        saveRetention: input.saves,
+      })
+    );
+  },
+  description: 'Show local Trails workspace state and retention',
+  examples: [
+    {
+      input: { rootDir: isolatedExampleInput('dev-stats').rootDir },
+      name: 'Show local dev state',
+    },
+  ],
+  input: z.object({
+    rootDir: z.string().optional().describe('Workspace root directory'),
+    saves: z
+      .number()
+      .default(DEFAULT_TOPO_SAVE_RETENTION)
+      .describe('Unpinned topo saves to retain'),
+    trackAgeMs: 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'),
+  }),
+  intent: 'read',
+  output: z.object({
+    db: z.object({
+      exists: z.boolean(),
+      fileSizeBytes: z.number(),
+      path: z.string(),
+    }),
+    lock: z.object({
+      exists: z.boolean(),
+      fileSizeBytes: z.number(),
+      path: z.string(),
+    }),
+    retention: z.object({
+      saves: z.number(),
+      trackAgeMs: z.number(),
+      tracks: z.number(),
+    }),
+    topo: z.object({
+      pinCount: z.number(),
+      prunableSaveCount: z.number(),
+      saveCount: z.number(),
+    }),
+    tracker: z.object({
+      recordCount: z.number(),
+    }),
+  }),
+});