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

package/src/trails/topo-pin.ts

@@ -0,0 +1,42 @@
+import { Result, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { loadApp } from './load-app.js';
+import {
+  DEFAULT_APP_MODULE,
+  isolatedExampleInput,
+  pinCurrentTopo,
+  topoPinOutput,
+  topoSaveOutput,
+} from './topo-support.js';
+
+export const topoPinTrail = trail('topo.pin', {
+  blaze: async (input, ctx) => {
+    const rootDir = input.rootDir ?? ctx.cwd ?? process.cwd();
+    const app = await loadApp(input.module, rootDir);
+    return Result.ok(pinCurrentTopo(app, { name: input.name, rootDir }));
+  },
+  description: 'Pin the current topo under a durable name',
+  examples: [
+    {
+      input: {
+        ...isolatedExampleInput('topo-pin'),
+        name: 'before-auth-refactor',
+      },
+      name: 'Pin the current topo',
+    },
+  ],
+  input: z.object({
+    module: z
+      .string()
+      .default(DEFAULT_APP_MODULE)
+      .describe('Path to the app module'),
+    name: z.string().describe('Pin name'),
+    rootDir: z.string().optional().describe('Workspace root directory'),
+  }),
+  intent: 'write',
+  output: z.object({
+    pin: topoPinOutput,
+    save: topoSaveOutput,
+  }),
+});

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

@@ -0,0 +1,332 @@
+/**
+ * Read-only topo store consumer helpers.
+ *
+ * Extracted from topo-support.ts so this branch (trl-132) owns its own file,
+ * keeping absorb routing clean across the stack.
+ */
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import type { Topo } from '@ontrails/core';
+import {
+  ConflictError,
+  createTopoStore,
+  InternalError,
+  NotFoundError,
+  Result,
+} from '@ontrails/core';
+import type { TopoSaveRecord } from '@ontrails/core/internal/topo-saves';
+import { listTopoSaves } from '@ontrails/core/internal/topo-saves';
+import {
+  openReadTrailsDb,
+  resolveTrailsDbPath,
+  resolveTrailsDir,
+} from '@ontrails/core/internal/trails-db';
+import { readTrailheadLockData } from '@ontrails/schema';
+
+import type { BriefReport, SurveyListReport } from './topo-reports.js';
+import type { TopoSummaryReport, TopoVerifyReport } from './topo-support.js';
+import { REPORT_CONTRACT_VERSION, REPORT_VERSION } from './topo-constants.js';
+import {
+  createCurrentTopoSave,
+  LOCK_PATH,
+  resolveRootDir,
+} from './topo-support.js';
+
+// ---------------------------------------------------------------------------
+// Internal types
+// ---------------------------------------------------------------------------
+
+interface StoredTrailheadMapEntry {
+  readonly detours?: Readonly<Record<string, readonly string[]>>;
+  readonly kind: 'provision' | 'signal' | 'trail';
+}
+
+interface CurrentTrailDetail {
+  readonly crosses: string[];
+  readonly description: string | null;
+  readonly detours: Readonly<Record<string, readonly string[]>> | null;
+  readonly examples: unknown[];
+  readonly id: string;
+  readonly intent: 'destroy' | 'read' | 'write';
+  readonly kind: string;
+  readonly provisions: string[];
+  readonly safety: string;
+}
+
+interface CurrentProvisionDetail {
+  readonly description: string | null;
+  readonly health: 'available' | 'none';
+  readonly id: string;
+  readonly kind: 'provision';
+  readonly lifetime: 'singleton';
+  readonly usedBy: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Store helpers
+// ---------------------------------------------------------------------------
+
+const topoStoreRef = (saveId: string) => ({ saveId }) as const;
+
+const hasCommittedLock = (trailsDir: string): boolean =>
+  existsSync(join(trailsDir, 'trails.lock')) ||
+  existsSync(join(trailsDir, 'trailhead.lock'));
+
+const readTrailheadEntries = (
+  trailheadMapJson: string
+): readonly StoredTrailheadMapEntry[] =>
+  (
+    JSON.parse(trailheadMapJson) as {
+      readonly entries: readonly StoredTrailheadMapEntry[];
+    }
+  ).entries;
+
+const buildBriefReportFromStore = (
+  app: Topo,
+  store: ReturnType<typeof createTopoStore>,
+  ref: ReturnType<typeof topoStoreRef>,
+  save: TopoSaveRecord
+): BriefReport => {
+  const trails = store.trails.list({ save: ref });
+  const exportRecord = store.exports.get(ref);
+  const trailEntries =
+    exportRecord === undefined
+      ? []
+      : readTrailheadEntries(exportRecord.trailheadMapJson).filter(
+          (entry) => entry.kind === 'trail'
+        );
+
+  return {
+    contractVersion: REPORT_CONTRACT_VERSION,
+    features: {
+      detours: trailEntries.some(
+        (entry) => (Object.keys(entry.detours ?? {}).length ?? 0) > 0
+      ),
+      examples: trails.some((trail) => trail.hasExamples),
+      outputSchemas: trails.some((trail) => trail.hasOutput),
+      provisions: save.provisionCount > 0,
+      signals: save.signalCount > 0,
+    },
+    name: app.name,
+    provisions: save.provisionCount,
+    signals: save.signalCount,
+    trails: save.trailCount,
+    version: REPORT_VERSION,
+  };
+};
+
+const buildSurveyListFromStore = (
+  store: ReturnType<typeof createTopoStore>,
+  ref: ReturnType<typeof topoStoreRef>
+): SurveyListReport => {
+  const trails = store.trails.list({ save: ref });
+  const provisions = store.provisions.list({ save: ref });
+
+  return {
+    count: trails.length,
+    entries: trails.map((trail) => ({
+      examples: trail.exampleCount,
+      id: trail.id,
+      kind: trail.kind,
+      safety: trail.safety,
+    })),
+    provisionCount: provisions.length,
+    provisions: provisions.map((provision) => ({
+      description: provision.description,
+      health: provision.health,
+      id: provision.id,
+      kind: provision.kind,
+      lifetime: provision.lifetime,
+      usedBy: provision.usedBy,
+    })),
+  };
+};
+
+const buildTrailDetailFromStore = (
+  detail: ReturnType<ReturnType<typeof createTopoStore>['trails']['get']>
+): CurrentTrailDetail => ({
+  crosses: [...(detail?.crosses ?? [])],
+  description: detail?.description ?? null,
+  detours: detail?.detours ?? null,
+  examples: [...(detail?.examples ?? [])],
+  id: detail?.id ?? '',
+  intent: detail?.intent ?? 'write',
+  kind: detail?.kind ?? 'trail',
+  provisions: [...(detail?.provisions ?? [])],
+  safety: detail?.safety ?? '-',
+});
+
+const buildProvisionDetailFromStore = (
+  provision: NonNullable<
+    ReturnType<ReturnType<typeof createTopoStore>['provisions']['get']>
+  >
+): CurrentProvisionDetail => ({
+  description: provision.description,
+  health: provision.health,
+  id: provision.id,
+  kind: provision.kind,
+  lifetime: provision.lifetime,
+  usedBy: [...provision.usedBy],
+});
+
+// ---------------------------------------------------------------------------
+// withCurrentTopoStore
+// ---------------------------------------------------------------------------
+
+/**
+ * Run a read callback against the latest topo store state.
+ *
+ * Uses the most recent existing save when available, only creating a new save
+ * when no prior save exists. This avoids unbounded save accumulation from
+ * read-only operations like survey, guide, and show.
+ */
+const withCurrentTopoStore = <T>(
+  app: Topo,
+  rootDir: string,
+  read: (
+    store: ReturnType<typeof createTopoStore>,
+    ref: ReturnType<typeof topoStoreRef>,
+    save: TopoSaveRecord
+  ) => T
+): T => {
+  const dbPath = resolveTrailsDbPath({ rootDir });
+  const existingSave = existsSync(dbPath)
+    ? (() => {
+        const db = openReadTrailsDb({ rootDir });
+        try {
+          return listTopoSaves(db)[0];
+        } finally {
+          db.close();
+        }
+      })()
+    : undefined;
+
+  const save = existingSave ?? createCurrentTopoSave(app, { rootDir });
+  const store = createTopoStore({ rootDir });
+  return read(store, topoStoreRef(save.id), save);
+};
+
+// ---------------------------------------------------------------------------
+// Public read-only consumers
+// ---------------------------------------------------------------------------
+
+export const buildTopoSummary = (
+  app: Topo,
+  options?: { readonly rootDir?: string }
+): TopoSummaryReport => {
+  const rootDir = resolveRootDir(options?.rootDir);
+  const trailsDir = resolveTrailsDir({ rootDir });
+  return withCurrentTopoStore(app, rootDir, (store, ref, save) => ({
+    app: buildBriefReportFromStore(app, store, ref, save),
+    dbPath: resolveTrailsDbPath({ rootDir }),
+    list: buildSurveyListFromStore(store, ref),
+    lockExists: hasCommittedLock(trailsDir),
+    lockPath: LOCK_PATH,
+  }));
+};
+
+export const buildCurrentTopoBrief = (
+  app: Topo,
+  options?: { readonly rootDir?: string }
+): BriefReport => {
+  const rootDir = resolveRootDir(options?.rootDir);
+  return withCurrentTopoStore(app, rootDir, (store, ref, save) =>
+    buildBriefReportFromStore(app, store, ref, save)
+  );
+};
+
+export const buildCurrentTopoList = (
+  app: Topo,
+  options?: { readonly rootDir?: string }
+): SurveyListReport => {
+  const rootDir = resolveRootDir(options?.rootDir);
+  return withCurrentTopoStore(app, rootDir, (store, ref) =>
+    buildSurveyListFromStore(store, ref)
+  );
+};
+
+export const buildCurrentGuideEntries = (
+  app: Topo,
+  options?: { readonly rootDir?: string }
+): readonly {
+  readonly description: string;
+  readonly exampleCount: number;
+  readonly id: string;
+  readonly kind: string;
+}[] => {
+  const rootDir = resolveRootDir(options?.rootDir);
+  return withCurrentTopoStore(app, rootDir, (store, ref) =>
+    store.trails.list({ save: ref }).map((trail) => ({
+      description: trail.description ?? '(no description)',
+      exampleCount: trail.exampleCount,
+      id: trail.id,
+      kind: trail.kind,
+    }))
+  );
+};
+
+export const buildCurrentTopoDetail = (
+  app: Topo,
+  id: string,
+  options?: { readonly rootDir?: string }
+): CurrentProvisionDetail | CurrentTrailDetail | undefined => {
+  const rootDir = resolveRootDir(options?.rootDir);
+  return withCurrentTopoStore(app, rootDir, (store, ref) => {
+    const trail = store.trails.get(id, { save: ref });
+    if (trail !== undefined) {
+      return buildTrailDetailFromStore(trail);
+    }
+
+    const provision = store.provisions.get(id, { save: ref });
+    return provision === undefined
+      ? undefined
+      : buildProvisionDetailFromStore(provision);
+  });
+};
+
+export const verifyCurrentTopo = async (
+  app: Topo,
+  options?: { readonly rootDir?: string }
+): Promise<Result<TopoVerifyReport, Error>> => {
+  const rootDir = resolveRootDir(options?.rootDir);
+  const committedLock = await readTrailheadLockData({
+    dir: resolveTrailsDir({ rootDir }),
+  });
+
+  if (committedLock === null) {
+    return Result.err(
+      new NotFoundError(
+        'No committed trails.lock found. Run `trails topo export` first.'
+      )
+    );
+  }
+
+  const currentHash = withCurrentTopoStore(
+    app,
+    rootDir,
+    (store, ref) => store.exports.get(ref)?.trailheadHash
+  );
+
+  if (currentHash === undefined) {
+    return Result.err(
+      new InternalError('No stored topo export found for the current topo save')
+    );
+  }
+
+  if (committedLock.hash !== currentHash) {
+    return Result.err(
+      new ConflictError(
+        'trails.lock is stale. Run `trails topo export` to refresh it.'
+      )
+    );
+  }
+
+  return Result.ok({
+    committedHash: committedLock.hash,
+    currentHash,
+    lockPath: LOCK_PATH,
+    stale: false,
+  });
+};

package/src/trails/topo-reports.ts

@@ -0,0 +1,221 @@
+import type { Topo, Trail } from '@ontrails/core';
+
+import { REPORT_CONTRACT_VERSION, REPORT_VERSION } from './topo-constants.js';
+
+export interface BriefReport {
+  readonly name: string;
+  readonly version: string;
+  readonly contractVersion: string;
+  readonly features: {
+    readonly provisions: boolean;
+    readonly outputSchemas: boolean;
+    readonly examples: boolean;
+    readonly detours: boolean;
+    readonly signals: boolean;
+  };
+  readonly trails: number;
+  readonly signals: number;
+  readonly provisions: number;
+}
+
+export interface SurveyListReport {
+  readonly count: number;
+  readonly entries: readonly {
+    readonly examples: number;
+    readonly id: string;
+    readonly kind: string;
+    readonly safety: string;
+  }[];
+  readonly provisionCount: number;
+  readonly provisions: readonly {
+    readonly description: string | null;
+    readonly health: 'available' | 'none';
+    readonly id: string;
+    readonly kind: 'provision';
+    readonly lifetime: 'singleton';
+    readonly usedBy: readonly string[];
+  }[];
+}
+
+export interface TrailDetailReport {
+  readonly description: string | null;
+  readonly detours: Trail<unknown, unknown>['detours'] | null;
+  readonly examples: readonly unknown[];
+  readonly crosses: readonly string[];
+  readonly id: string;
+  readonly intent: 'read' | 'write' | 'destroy';
+  readonly kind: string;
+  readonly safety: string;
+  readonly provisions: readonly string[];
+}
+
+const trailHas = (raw: Record<string, unknown>, key: string): boolean => {
+  if (key === 'examples') {
+    return Array.isArray(raw[key]) && (raw[key] as unknown[]).length > 0;
+  }
+  return Boolean(raw[key]);
+};
+
+const detectFeatures = (
+  app: Topo
+): {
+  hasDetours: boolean;
+  hasExamples: boolean;
+  hasOutputSchemas: boolean;
+  hasProvisions: boolean;
+} => {
+  const trails = [...app.trails.values()].map(
+    (item) => item as unknown as Record<string, unknown>
+  );
+  return {
+    hasDetours: trails.some((r) => trailHas(r, 'detours')),
+    hasExamples: trails.some((r) => trailHas(r, 'examples')),
+    hasOutputSchemas: trails.some((r) => trailHas(r, 'output')),
+    hasProvisions: trails.some(
+      (r) =>
+        Array.isArray(r['provisions']) &&
+        (r['provisions'] as unknown[]).length > 0
+    ),
+  };
+};
+
+export const generateBriefReport = (app: Topo): BriefReport => {
+  const { hasDetours, hasExamples, hasOutputSchemas, hasProvisions } =
+    detectFeatures(app);
+
+  return {
+    contractVersion: REPORT_CONTRACT_VERSION,
+    features: {
+      detours: hasDetours,
+      examples: hasExamples,
+      outputSchemas: hasOutputSchemas,
+      provisions: hasProvisions,
+      signals: app.signals.size > 0,
+    },
+    name: app.name,
+    provisions: app.provisions.size,
+    signals: app.signals.size,
+    trails: app.trails.size,
+    version: REPORT_VERSION,
+  };
+};
+
+const safetyLabel = (entry: {
+  intent?: 'read' | 'write' | 'destroy';
+}): string => {
+  if (entry.intent === 'destroy') {
+    return 'destroy';
+  }
+  if (entry.intent === 'write') {
+    return 'write';
+  }
+  if (entry.intent === 'read') {
+    return 'read';
+  }
+  return '-';
+};
+
+const buildProvisionUsage = (
+  app: Topo
+): ReadonlyMap<string, readonly string[]> => {
+  const usage = new Map<string, string[]>();
+
+  for (const trailDef of app.list()) {
+    for (const declaredProvision of trailDef.provisions) {
+      const users = usage.get(declaredProvision.id) ?? [];
+      users.push(trailDef.id);
+      usage.set(declaredProvision.id, users);
+    }
+  }
+
+  return new Map(
+    [...usage.entries()].map(([id, users]) => [id, users.toSorted()] as const)
+  );
+};
+
+const provisionHealthStatus = (provision: {
+  health?: unknown;
+}): 'available' | 'none' =>
+  provision.health === undefined ? 'none' : 'available';
+
+export const formatProvisionDetail = (
+  app: Topo,
+  provisionId: string
+): object => {
+  const item = app.getProvision(provisionId);
+  const usedBy = buildProvisionUsage(app).get(provisionId) ?? [];
+
+  return {
+    description: item?.description ?? null,
+    health: item ? provisionHealthStatus(item) : 'none',
+    id: provisionId,
+    kind: 'provision',
+    lifetime: 'singleton',
+    usedBy,
+  };
+};
+
+const formatProvisionList = (app: Topo): SurveyListReport['provisions'] => {
+  const usage = buildProvisionUsage(app);
+  return app
+    .listProvisions()
+    .map((provision) => ({
+      description: provision.description ?? null,
+      health: provisionHealthStatus(provision),
+      id: provision.id,
+      kind: provision.kind,
+      lifetime: 'singleton' as const,
+      usedBy: usage.get(provision.id) ?? [],
+    }))
+    .toSorted((a, b) => a.id.localeCompare(b.id));
+};
+
+export const generateSurveyList = (app: Topo): SurveyListReport => {
+  const items = app.list();
+  const entries = items.map((item) => {
+    const safety = safetyLabel(
+      item as unknown as { intent?: 'read' | 'write' | 'destroy' }
+    );
+    const examples = Array.isArray(
+      (item as unknown as { examples?: unknown[] }).examples
+    )
+      ? (item as unknown as { examples: unknown[] }).examples.length
+      : 0;
+
+    return {
+      examples,
+      id: item.id,
+      kind: item.kind,
+      safety,
+    };
+  });
+
+  const provisions = formatProvisionList(app);
+
+  return {
+    count: items.length,
+    entries,
+    provisionCount: provisions.length,
+    provisions,
+  };
+};
+
+export const generateTrailDetail = (
+  item: Trail<unknown, unknown>
+): TrailDetailReport => {
+  const safety = safetyLabel(
+    item as unknown as { intent?: 'read' | 'write' | 'destroy' }
+  );
+
+  return {
+    crosses: item.crosses.toSorted(),
+    description: item.description ?? null,
+    detours: item.detours ?? null,
+    examples: item.examples ?? [],
+    id: item.id,
+    intent: item.intent,
+    kind: item.kind,
+    provisions: item.provisions.map((provision) => provision.id).toSorted(),
+    safety,
+  };
+};

package/src/trails/topo-show.ts

@@ -0,0 +1,58 @@
+import { NotFoundError, Result, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { loadApp } from './load-app.js';
+import { buildCurrentTopoDetail } from './topo-read-support.js';
+import { DEFAULT_APP_MODULE } from './topo-support.js';
+
+const trailDetailOutput = z.object({
+  crosses: z.array(z.string()),
+  description: z.unknown().nullable(),
+  detours: z.unknown().nullable(),
+  examples: z.array(z.unknown()),
+  id: z.string(),
+  intent: z.enum(['read', 'write', 'destroy']),
+  kind: z.string(),
+  provisions: z.array(z.string()),
+  safety: z.string(),
+});
+
+const provisionDetailOutput = 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()),
+});
+
+export const topoShowTrail = trail('topo.show', {
+  blaze: async (input, ctx) => {
+    const rootDir = input.rootDir ?? ctx.cwd ?? process.cwd();
+    const app = await loadApp(input.module, rootDir);
+    const detail = buildCurrentTopoDetail(app, input.id, { rootDir });
+    if (detail !== undefined) {
+      return Result.ok(detail);
+    }
+    return Result.err(
+      new NotFoundError(`Trail or provision not found: ${input.id}`)
+    );
+  },
+  description: 'Show detail for a current trail or provision',
+  examples: [
+    {
+      input: { id: 'topo' },
+      name: 'Show current trail detail',
+    },
+  ],
+  input: z.object({
+    id: z.string().describe('Trail or provision ID to inspect'),
+    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.union([trailDetailOutput, provisionDetailOutput]),
+});