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

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

@@ -0,0 +1,96 @@
+/**
+ * Stored-export pipeline for topo persistence.
+ *
+ * Extracted from topo-support.ts so this branch (trl-131) owns its own file,
+ * keeping absorb routing clean across the stack.
+ */
+
+import type { Topo } from '@ontrails/core';
+import { InternalError, Result } from '@ontrails/core';
+import type { TopoSaveRecord } from '@ontrails/core/internal/topo-saves';
+import type { StoredTopoExport } from '@ontrails/core/internal/topo-store';
+import {
+  getStoredTopoExport,
+  persistEstablishedTopoSave,
+} from '@ontrails/core/internal/topo-store';
+import {
+  openWriteTrailsDb,
+  resolveTrailsDir,
+} from '@ontrails/core/internal/trails-db';
+import type { TrailheadLock, TrailheadMap } from '@ontrails/schema';
+import { writeTrailheadLock, writeTrailheadMap } from '@ontrails/schema';
+
+import type { TopoExportReport } from './topo-support.js';
+import { currentGitState, resolveRootDir, topoCounts } from './topo-support.js';
+
+const persistAndReadStoredExport = (
+  app: Topo,
+  db: ReturnType<typeof openWriteTrailsDb>,
+  rootDir: string
+): Result<{ save: TopoSaveRecord; storedExport: StoredTopoExport }, Error> => {
+  const saveResult = persistEstablishedTopoSave(db, app, {
+    ...currentGitState(rootDir),
+    ...topoCounts(app),
+  });
+  if (saveResult.isErr()) {
+    return saveResult;
+  }
+
+  const save = saveResult.value;
+  const storedExport = getStoredTopoExport(db, save.id);
+
+  if (storedExport === undefined) {
+    return Result.err(
+      new InternalError(`Missing stored topo export for save "${save.id}"`)
+    );
+  }
+
+  return Result.ok({
+    save,
+    storedExport,
+  });
+};
+
+const writeStoredExportArtifacts = async (
+  storedExport: StoredTopoExport,
+  trailsDir: string
+): Promise<Pick<TopoExportReport, 'hash' | 'lockPath' | 'mapPath'>> => {
+  const mapPath = await writeTrailheadMap(
+    JSON.parse(storedExport.trailheadMapJson) as TrailheadMap,
+    { dir: trailsDir }
+  );
+  const lockPath = await writeTrailheadLock(
+    JSON.parse(storedExport.lockContent) as TrailheadLock,
+    { dir: trailsDir }
+  );
+
+  return {
+    hash: storedExport.trailheadHash,
+    lockPath,
+    mapPath,
+  };
+};
+
+export const exportCurrentTopo = async (
+  app: Topo,
+  options?: { readonly rootDir?: string }
+): Promise<Result<TopoExportReport, Error>> => {
+  const rootDir = resolveRootDir(options?.rootDir);
+  const db = openWriteTrailsDb({ rootDir });
+
+  try {
+    const persisted = persistAndReadStoredExport(app, db, rootDir);
+    if (persisted.isErr()) {
+      return persisted;
+    }
+
+    const { save, storedExport } = persisted.value;
+    const artifacts = await writeStoredExportArtifacts(
+      storedExport,
+      resolveTrailsDir({ rootDir })
+    );
+    return Result.ok({ ...artifacts, save });
+  } finally {
+    db.close();
+  }
+};

package/src/trails/topo-support.ts

@@ -0,0 +1,274 @@
+import { existsSync, mkdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import type { Topo } from '@ontrails/core';
+import type {
+  TopoPinRecord,
+  TopoSaveRecord,
+} from '@ontrails/core/internal/topo-saves';
+import {
+  getTopoPin,
+  listTopoPins,
+  listTopoSaves,
+  pinTopoSave,
+  unpinTopoSave,
+} from '@ontrails/core/internal/topo-saves';
+import { persistEstablishedTopoSave } from '@ontrails/core/internal/topo-store';
+import {
+  openReadTrailsDb,
+  openWriteTrailsDb,
+  resolveTrailsDbPath,
+} from '@ontrails/core/internal/trails-db';
+import { z } from 'zod';
+
+import type { BriefReport, SurveyListReport } from './topo-reports.js';
+
+/** Output schema for a topo save record. Shared across topo trails. */
+export const topoSaveOutput = z.object({
+  createdAt: z.string(),
+  gitDirty: z.boolean(),
+  gitSha: z.string().optional(),
+  id: z.string(),
+  provisionCount: z.number(),
+  signalCount: z.number(),
+  trailCount: z.number(),
+});
+
+/** Output schema for a topo pin record. Shared across topo trails. */
+export const topoPinOutput = z.object({
+  createdAt: z.string(),
+  name: z.string(),
+  saveId: z.string(),
+});
+
+export const DEFAULT_APP_MODULE = './src/app.ts';
+export const DEFAULT_TOPO_HISTORY_LIMIT = 10;
+export const LOCK_PATH = '.trails/trails.lock';
+export const LEGACY_LOCK_PATH = '.trails/trailhead.lock';
+
+/** Resolve the lockfile path, preferring the current name with legacy fallback. */
+export const resolveLockPath = (trailsDir: string): string => {
+  const primary = join(trailsDir, 'trails.lock');
+  if (existsSync(primary)) {
+    return primary;
+  }
+  const legacy = join(trailsDir, 'trailhead.lock');
+  return existsSync(legacy) ? legacy : primary;
+};
+const EXAMPLE_APP_MODULE = fileURLToPath(new URL('../app.ts', import.meta.url));
+
+export interface TopoSummaryReport {
+  readonly app: BriefReport;
+  readonly dbPath: string;
+  readonly list: SurveyListReport;
+  readonly lockExists: boolean;
+  readonly lockPath: string;
+}
+
+export interface TopoHistoryReport {
+  readonly dbPath: string;
+  readonly limit: number;
+  readonly pinCount: number;
+  readonly pins: TopoPinRecord[];
+  readonly saveCount: number;
+  readonly saves: TopoSaveRecord[];
+}
+
+export interface TopoExportReport {
+  readonly hash: string;
+  readonly lockPath: string;
+  readonly mapPath: string;
+  readonly save: TopoSaveRecord;
+}
+
+export interface TopoVerifyReport {
+  readonly committedHash: string;
+  readonly currentHash: string;
+  readonly lockPath: string;
+  readonly stale: false;
+}
+
+export const resolveRootDir = (cwd?: string): string => cwd ?? process.cwd();
+
+const safeGit = (cwd: string, args: readonly string[]): string | undefined => {
+  const proc = Bun.spawnSync({
+    cmd: ['git', '-C', cwd, ...args],
+    stderr: 'ignore',
+    stdout: 'pipe',
+  });
+  if (!proc.success) {
+    return undefined;
+  }
+  const text = Buffer.from(proc.stdout).toString('utf8').trim();
+  return text.length === 0 ? undefined : text;
+};
+
+export const currentGitState = (
+  rootDir: string
+): { readonly gitDirty: boolean; readonly gitSha?: string } => {
+  const gitSha = safeGit(rootDir, ['rev-parse', 'HEAD']);
+  const status = safeGit(rootDir, ['status', '--porcelain']);
+  return {
+    gitDirty: (status?.length ?? 0) > 0,
+    ...(gitSha === undefined ? {} : { gitSha }),
+  };
+};
+
+export const topoCounts = (
+  app: Topo
+): Pick<TopoSaveRecord, 'provisionCount' | 'signalCount' | 'trailCount'> => ({
+  provisionCount: app.provisions.size,
+  signalCount: app.signals.size,
+  trailCount: app.trails.size,
+});
+
+const emptyTopoHistory = (
+  dbPath: string,
+  limit: number
+): TopoHistoryReport => ({
+  dbPath,
+  limit,
+  pinCount: 0,
+  pins: [],
+  saveCount: 0,
+  saves: [],
+});
+
+const collectedTopoHistory = (
+  dbPath: string,
+  limit: number,
+  pins: readonly TopoPinRecord[],
+  allSaves: readonly TopoSaveRecord[]
+): TopoHistoryReport => ({
+  dbPath,
+  limit,
+  pinCount: pins.length,
+  pins: [...pins],
+  saveCount: allSaves.length,
+  saves: allSaves.slice(0, limit),
+});
+
+const removeTopoPinWithDb = (
+  input: { readonly dryRun: boolean; readonly name: string },
+  pin: TopoPinRecord,
+  db: Parameters<typeof unpinTopoSave>[0]
+): {
+  readonly dryRun: boolean;
+  readonly pin?: TopoPinRecord;
+  readonly removed: boolean;
+} =>
+  input.dryRun
+    ? { dryRun: true, pin, removed: false }
+    : { dryRun: false, pin, removed: unpinTopoSave(db, input.name) };
+
+export const isolatedExampleInput = (
+  name: string
+): { readonly module: string; readonly rootDir: string } => {
+  const rootDir = join(tmpdir(), 'ontrails-trails-examples', name);
+  rmSync(rootDir, { force: true, recursive: true });
+  mkdirSync(rootDir, { recursive: true });
+  return {
+    module: EXAMPLE_APP_MODULE,
+    rootDir,
+  };
+};
+
+export const createCurrentTopoSave = (
+  app: Topo,
+  options?: { readonly rootDir?: string }
+): TopoSaveRecord => {
+  const rootDir = resolveRootDir(options?.rootDir);
+  const db = openWriteTrailsDb({ rootDir });
+
+  try {
+    const result = persistEstablishedTopoSave(db, app, {
+      ...currentGitState(rootDir),
+      ...topoCounts(app),
+    });
+    if (result.isErr()) {
+      throw result.error;
+    }
+    return result.value;
+  } finally {
+    db.close();
+  }
+};
+
+export const listTopoHistory = (options?: {
+  readonly limit?: number;
+  readonly rootDir?: string;
+}): TopoHistoryReport => {
+  const rootDir = resolveRootDir(options?.rootDir);
+  const limit = options?.limit ?? DEFAULT_TOPO_HISTORY_LIMIT;
+  const dbPath = resolveTrailsDbPath({ rootDir });
+  if (!existsSync(dbPath)) {
+    return emptyTopoHistory(dbPath, limit);
+  }
+  const db = openReadTrailsDb({ rootDir });
+
+  try {
+    return collectedTopoHistory(
+      dbPath,
+      limit,
+      listTopoPins(db),
+      listTopoSaves(db)
+    );
+  } finally {
+    db.close();
+  }
+};
+
+export const pinCurrentTopo = (
+  app: Topo,
+  input: { readonly name: string; readonly rootDir?: string }
+): { readonly pin: TopoPinRecord; readonly save: TopoSaveRecord } => {
+  const rootDir = resolveRootDir(input.rootDir);
+  const db = openWriteTrailsDb({ rootDir });
+
+  try {
+    const result = persistEstablishedTopoSave(db, app, {
+      ...currentGitState(rootDir),
+      ...topoCounts(app),
+    });
+    if (result.isErr()) {
+      throw result.error;
+    }
+    const pin = pinTopoSave(db, {
+      name: input.name,
+      saveId: result.value.id,
+    });
+    return { pin, save: result.value };
+  } finally {
+    db.close();
+  }
+};
+
+export const removeTopoPin = (input: {
+  readonly dryRun: boolean;
+  readonly name: string;
+  readonly rootDir?: string;
+}): {
+  readonly dryRun: boolean;
+  readonly pin?: TopoPinRecord;
+  readonly removed: boolean;
+} => {
+  const rootDir = resolveRootDir(input.rootDir);
+  if (!existsSync(resolveTrailsDbPath({ rootDir }))) {
+    return { dryRun: input.dryRun, removed: false };
+  }
+  const db = input.dryRun
+    ? openReadTrailsDb({ rootDir })
+    : openWriteTrailsDb({ rootDir });
+
+  try {
+    const pin = getTopoPin(db, input.name);
+    if (pin === undefined) {
+      return { dryRun: input.dryRun, removed: false };
+    }
+    return removeTopoPinWithDb(input, pin, db);
+  } finally {
+    db.close();
+  }
+};

package/src/trails/topo-unpin.ts

@@ -0,0 +1,51 @@
+import { Result, ValidationError, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import {
+  isolatedExampleInput,
+  removeTopoPin,
+  topoPinOutput,
+} from './topo-support.js';
+
+export const topoUnpinTrail = trail('topo.unpin', {
+  blaze: (input, ctx) => {
+    if (input.dryRun !== true && input.yes !== true) {
+      return Result.err(
+        new ValidationError(
+          'Refusing to remove a pin without `--yes` or `--dry-run`.'
+        )
+      );
+    }
+
+    const rootDir = input.rootDir ?? ctx.cwd ?? process.cwd();
+    return Result.ok(
+      removeTopoPin({ dryRun: input.dryRun, name: input.name, rootDir })
+    );
+  },
+  description: 'Remove a named topo pin',
+  examples: [
+    {
+      input: {
+        ...isolatedExampleInput('topo-unpin'),
+        dryRun: true,
+        name: 'before-auth-refactor',
+      },
+      name: 'Preview pin removal',
+    },
+  ],
+  input: z.object({
+    dryRun: z
+      .boolean()
+      .default(true)
+      .describe('Preview the removal without changing state'),
+    name: z.string().describe('Pin name'),
+    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(),
+    pin: topoPinOutput.optional(),
+    removed: z.boolean(),
+  }),
+});

package/src/trails/topo-verify.ts

@@ -0,0 +1,29 @@
+import { trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { loadApp } from './load-app.js';
+import { verifyCurrentTopo } from './topo-read-support.js';
+import { DEFAULT_APP_MODULE } from './topo-support.js';
+
+export const topoVerifyTrail = trail('topo.verify', {
+  blaze: async (input, ctx) => {
+    const rootDir = input.rootDir ?? ctx.cwd ?? process.cwd();
+    const app = await loadApp(input.module, rootDir);
+    return verifyCurrentTopo(app, { rootDir });
+  },
+  description: 'Verify that the committed lockfile matches the current topo',
+  input: z.object({
+    module: z
+      .string()
+      .default(DEFAULT_APP_MODULE)
+      .describe('Path to the app module'),
+    rootDir: z.string().optional().describe('Workspace root directory'),
+  }),
+  intent: 'read',
+  output: z.object({
+    committedHash: z.string(),
+    currentHash: z.string(),
+    lockPath: z.string(),
+    stale: z.literal(false),
+  }),
+});

package/src/trails/topo.ts

@@ -0,0 +1,73 @@
+import { Result, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { loadApp } from './load-app.js';
+import { buildTopoSummary } from './topo-read-support.js';
+import { DEFAULT_APP_MODULE } from './topo-support.js';
+
+const summaryOutput = z.object({
+  app: z.object({
+    contractVersion: z.string(),
+    features: z.object({
+      detours: z.boolean(),
+      examples: z.boolean(),
+      outputSchemas: z.boolean(),
+      provisions: z.boolean(),
+      signals: z.boolean(),
+    }),
+    name: z.string(),
+    provisions: z.number(),
+    signals: z.number(),
+    trails: z.number(),
+    version: z.string(),
+  }),
+  dbPath: z.string(),
+  list: z.object({
+    count: z.number(),
+    entries: z.array(
+      z.object({
+        examples: z.number(),
+        id: z.string(),
+        kind: z.string(),
+        safety: z.string(),
+      })
+    ),
+    provisionCount: z.number(),
+    provisions: z.array(
+      z.object({
+        description: z.string().nullable(),
+        health: z.enum(['available', 'none']),
+        id: z.string(),
+        kind: z.literal('provision'),
+        lifetime: z.literal('singleton'),
+        usedBy: z.array(z.string()),
+      })
+    ),
+  }),
+  lockExists: z.boolean(),
+  lockPath: z.string(),
+});
+
+export const topoTrail = trail('topo', {
+  blaze: async (input, ctx) => {
+    const rootDir = input.rootDir ?? ctx.cwd ?? process.cwd();
+    const app = await loadApp(input.module, rootDir);
+    return Result.ok(buildTopoSummary(app, { rootDir }));
+  },
+  description: 'Show the current topo summary and entry list',
+  examples: [
+    {
+      input: {},
+      name: 'Show the current topo summary',
+    },
+  ],
+  input: z.object({
+    module: z
+      .string()
+      .default(DEFAULT_APP_MODULE)
+      .describe('Path to the app module'),
+    rootDir: z.string().optional().describe('Workspace root directory'),
+  }),
+  intent: 'read',
+  output: summaryOutput,
+});

package/src/trails/warden.ts

@@ -91,6 +91,7 @@ export const wardenTrail = trail('warden', {
     ),
     drift: z
       .object({
+        blockedReason: z.string().optional(),
         committedHash: z.string().nullable(),
         currentHash: z.string(),
         stale: z.boolean(),