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

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

@@ -0,0 +1,329 @@
+/**
+ * Read-only topo store consumer helpers.
+ *
+ * Extracted from topo-support.ts to isolate read-only store consumer helpers,
+ * keeping module boundaries clean.
+ */
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import {
+  ConflictError,
+  createTopoStore,
+  InternalError,
+  listTopoSnapshots,
+  NotFoundError,
+  Result,
+} from '@ontrails/core';
+import type { Topo, TopoSnapshot } from '@ontrails/core';
+import {
+  deriveTrailsDbPath,
+  deriveTrailsDir,
+} from '@ontrails/core/internal/trails-db';
+import { readSurfaceLockData } 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 {
+  createCurrentTopoSnapshot,
+  deriveRootDir,
+  LOCK_PATH,
+} from './topo-support.js';
+
+// ---------------------------------------------------------------------------
+// Internal types
+// ---------------------------------------------------------------------------
+
+interface StoredSurfaceMapEntry {
+  readonly detours?: readonly {
+    readonly on: string;
+    readonly maxAttempts: number;
+  }[];
+  readonly kind: 'resource' | 'signal' | 'trail';
+}
+
+interface CurrentTrailDetail {
+  readonly crosses: string[];
+  readonly description: string | null;
+  readonly detours:
+    | readonly { readonly on: string; readonly maxAttempts: number }[]
+    | null;
+  readonly examples: unknown[];
+  readonly id: string;
+  readonly intent: 'destroy' | 'read' | 'write';
+  readonly kind: string;
+  readonly pattern: string | null;
+  readonly resources: string[];
+  readonly safety: string;
+}
+
+interface CurrentResourceDetail {
+  readonly description: string | null;
+  readonly health: 'available' | 'none';
+  readonly id: string;
+  readonly kind: 'resource';
+  readonly lifetime: 'singleton';
+  readonly usedBy: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Store helpers
+// ---------------------------------------------------------------------------
+
+const topoStoreRef = (snapshotId: string) => ({ snapshotId }) as const;
+
+const hasCommittedLock = (trailsDir: string): boolean =>
+  existsSync(join(trailsDir, 'trails.lock'));
+
+const readSurfaceEntries = (
+  surfaceMapJson: string
+): readonly StoredSurfaceMapEntry[] =>
+  (
+    JSON.parse(surfaceMapJson) as {
+      readonly entries: readonly StoredSurfaceMapEntry[];
+    }
+  ).entries;
+
+const buildBriefReportFromStore = (
+  app: Topo,
+  store: ReturnType<typeof createTopoStore>,
+  ref: ReturnType<typeof topoStoreRef>,
+  snapshot: TopoSnapshot
+): BriefReport => {
+  const trails = store.trails.list({ snapshot: ref });
+  const exportRecord = store.exports.get(ref);
+  const trailEntries =
+    exportRecord === undefined
+      ? []
+      : readSurfaceEntries(exportRecord.surfaceMapJson).filter(
+          (entry) => entry.kind === 'trail'
+        );
+
+  return {
+    contractVersion: REPORT_CONTRACT_VERSION,
+    features: {
+      detours: trailEntries.some((entry) => (entry.detours ?? []).length > 0),
+      examples: trails.some((trail) => trail.hasExamples),
+      outputSchemas: trails.some((trail) => trail.hasOutput),
+      resources: snapshot.resourceCount > 0,
+      signals: snapshot.signalCount > 0,
+    },
+    name: app.name,
+    resources: snapshot.resourceCount,
+    signals: snapshot.signalCount,
+    trails: snapshot.trailCount,
+    version: REPORT_VERSION,
+  };
+};
+
+const buildSurveyListFromStore = (
+  store: ReturnType<typeof createTopoStore>,
+  ref: ReturnType<typeof topoStoreRef>
+): SurveyListReport => {
+  const trails = store.trails.list({ snapshot: ref });
+  const resources = store.resources.list({ snapshot: ref });
+
+  return {
+    count: trails.length,
+    entries: trails.map((trail) => ({
+      examples: trail.exampleCount,
+      id: trail.id,
+      kind: trail.kind,
+      safety: trail.safety,
+    })),
+    resourceCount: resources.length,
+    resources: resources.map((resource) => ({
+      description: resource.description,
+      health: resource.health,
+      id: resource.id,
+      kind: resource.kind,
+      lifetime: resource.lifetime,
+      usedBy: resource.usedBy,
+    })),
+  };
+};
+
+const buildTrailDetailFromStore = (
+  detail: NonNullable<
+    ReturnType<ReturnType<typeof createTopoStore>['trails']['get']>
+  >
+): CurrentTrailDetail => ({
+  crosses: [...detail.crosses],
+  description: detail.description,
+  detours: detail.detours,
+  examples: [...detail.examples],
+  id: detail.id,
+  intent: detail.intent,
+  kind: detail.kind,
+  pattern: detail.pattern,
+  resources: [...detail.resources],
+  safety: detail.safety,
+});
+
+const buildResourceDetailFromStore = (
+  resource: NonNullable<
+    ReturnType<ReturnType<typeof createTopoStore>['resources']['get']>
+  >
+): CurrentResourceDetail => ({
+  description: resource.description,
+  health: resource.health,
+  id: resource.id,
+  kind: resource.kind,
+  lifetime: resource.lifetime,
+  usedBy: [...resource.usedBy],
+});
+
+// ---------------------------------------------------------------------------
+// withCurrentTopoStore
+// ---------------------------------------------------------------------------
+
+/**
+ * Run a read callback against the latest topo store state.
+ *
+ * Uses the most recent existing snapshot when available, only creating a new
+ * snapshot when no prior snapshot exists. This avoids unbounded snapshot
+ * 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>,
+    snapshot: TopoSnapshot
+  ) => T
+): T => {
+  const [existingSnapshot] = listTopoSnapshots({ limit: 1, rootDir });
+  const snapshot =
+    existingSnapshot ?? createCurrentTopoSnapshot(app, { rootDir });
+  const store = createTopoStore({ rootDir });
+  return read(store, topoStoreRef(snapshot.id), snapshot);
+};
+
+// ---------------------------------------------------------------------------
+// Public read-only consumers
+// ---------------------------------------------------------------------------
+
+export const buildTopoSummary = (
+  app: Topo,
+  options?: { readonly rootDir?: string }
+): TopoSummaryReport => {
+  const rootDir = deriveRootDir(options?.rootDir);
+  const trailsDir = deriveTrailsDir({ rootDir });
+  return withCurrentTopoStore(app, rootDir, (store, ref, snapshot) => ({
+    app: buildBriefReportFromStore(app, store, ref, snapshot),
+    dbPath: deriveTrailsDbPath({ rootDir }),
+    list: buildSurveyListFromStore(store, ref),
+    lockExists: hasCommittedLock(trailsDir),
+    lockPath: LOCK_PATH,
+  }));
+};
+
+export const buildCurrentTopoBrief = (
+  app: Topo,
+  options?: { readonly rootDir?: string }
+): BriefReport => {
+  const rootDir = deriveRootDir(options?.rootDir);
+  return withCurrentTopoStore(app, rootDir, (store, ref, snapshot) =>
+    buildBriefReportFromStore(app, store, ref, snapshot)
+  );
+};
+
+export const buildCurrentTopoList = (
+  app: Topo,
+  options?: { readonly rootDir?: string }
+): SurveyListReport => {
+  const rootDir = deriveRootDir(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 = deriveRootDir(options?.rootDir);
+  return withCurrentTopoStore(app, rootDir, (store, ref) =>
+    store.trails.list({ snapshot: 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 }
+): CurrentResourceDetail | CurrentTrailDetail | undefined => {
+  const rootDir = deriveRootDir(options?.rootDir);
+  return withCurrentTopoStore(app, rootDir, (store, ref) => {
+    const trail = store.trails.get(id, { snapshot: ref });
+    if (trail !== undefined) {
+      return buildTrailDetailFromStore(trail);
+    }
+
+    const resource = store.resources.get(id, { snapshot: ref });
+    return resource === undefined
+      ? undefined
+      : buildResourceDetailFromStore(resource);
+  });
+};
+
+export const verifyCurrentTopo = async (
+  app: Topo,
+  options?: { readonly rootDir?: string }
+): Promise<Result<TopoVerifyReport, Error>> => {
+  const rootDir = deriveRootDir(options?.rootDir);
+  const committedLock = await readSurfaceLockData({
+    dir: deriveTrailsDir({ 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)?.surfaceHash
+  );
+
+  if (currentHash === undefined) {
+    return Result.err(
+      new InternalError(
+        'No stored topo export found for the current topo snapshot'
+      )
+    );
+  }
+
+  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,228 @@
+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 resources: boolean;
+    readonly outputSchemas: boolean;
+    readonly examples: boolean;
+    readonly detours: boolean;
+    readonly signals: boolean;
+  };
+  readonly trails: number;
+  readonly signals: number;
+  readonly resources: number;
+}
+
+export interface SurveyListReport {
+  readonly count: number;
+  readonly entries: readonly {
+    readonly examples: number;
+    readonly id: string;
+    readonly kind: string;
+    readonly safety: string;
+  }[];
+  readonly resourceCount: number;
+  readonly resources: readonly {
+    readonly description: string | null;
+    readonly health: 'available' | 'none';
+    readonly id: string;
+    readonly kind: 'resource';
+    readonly lifetime: 'singleton';
+    readonly usedBy: readonly string[];
+  }[];
+}
+
+export interface TrailDetailReport {
+  readonly description: string | null;
+  readonly detours:
+    | readonly { readonly on: string; readonly maxAttempts: number }[]
+    | null;
+  readonly examples: readonly unknown[];
+  readonly crosses: readonly string[];
+  readonly id: string;
+  readonly intent: 'read' | 'write' | 'destroy';
+  readonly kind: string;
+  readonly pattern: string | null;
+  readonly safety: string;
+  readonly resources: readonly string[];
+}
+
+const trailHas = (raw: Record<string, unknown>, key: string): boolean => {
+  if (key === 'examples' || key === 'detours') {
+    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;
+  hasResources: 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')),
+    hasResources: trails.some(
+      (r) =>
+        Array.isArray(r['resources']) &&
+        (r['resources'] as unknown[]).length > 0
+    ),
+  };
+};
+
+export const deriveBriefReport = (app: Topo): BriefReport => {
+  const { hasDetours, hasExamples, hasOutputSchemas, hasResources } =
+    detectFeatures(app);
+
+  return {
+    contractVersion: REPORT_CONTRACT_VERSION,
+    features: {
+      detours: hasDetours,
+      examples: hasExamples,
+      outputSchemas: hasOutputSchemas,
+      resources: hasResources,
+      signals: app.signals.size > 0,
+    },
+    name: app.name,
+    resources: app.resources.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 buildResourceUsage = (
+  app: Topo
+): ReadonlyMap<string, readonly string[]> => {
+  const usage = new Map<string, string[]>();
+
+  for (const trailDef of app.list()) {
+    for (const declaredResource of trailDef.resources) {
+      const users = usage.get(declaredResource.id) ?? [];
+      users.push(trailDef.id);
+      usage.set(declaredResource.id, users);
+    }
+  }
+
+  return new Map(
+    [...usage.entries()].map(([id, users]) => [id, users.toSorted()] as const)
+  );
+};
+
+const resourceHealthStatus = (resource: {
+  health?: unknown;
+}): 'available' | 'none' =>
+  resource.health === undefined ? 'none' : 'available';
+
+export const deriveResourceDetail = (app: Topo, resourceId: string): object => {
+  const item = app.getResource(resourceId);
+  const usedBy = buildResourceUsage(app).get(resourceId) ?? [];
+
+  return {
+    description: item?.description ?? null,
+    health: item ? resourceHealthStatus(item) : 'none',
+    id: resourceId,
+    kind: 'resource',
+    lifetime: 'singleton',
+    usedBy,
+  };
+};
+
+const formatResourceList = (app: Topo): SurveyListReport['resources'] => {
+  const usage = buildResourceUsage(app);
+  return app
+    .listResources()
+    .map((resource) => ({
+      description: resource.description ?? null,
+      health: resourceHealthStatus(resource),
+      id: resource.id,
+      kind: resource.kind,
+      lifetime: 'singleton' as const,
+      usedBy: usage.get(resource.id) ?? [],
+    }))
+    .toSorted((a, b) => a.id.localeCompare(b.id));
+};
+
+export const deriveSurveyList = (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 resources = formatResourceList(app);
+
+  return {
+    count: items.length,
+    entries,
+    resourceCount: resources.length,
+    resources,
+  };
+};
+
+export const deriveTrailDetail = (
+  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.length > 0
+        ? item.detours.map((d) => ({
+            maxAttempts: d.maxAttempts ?? 1,
+            on: d.on.name,
+          }))
+        : null,
+    examples: item.examples ?? [],
+    id: item.id,
+    intent: item.intent,
+    kind: item.kind,
+    pattern: item.pattern ?? null,
+    resources: item.resources.map((resource) => resource.id).toSorted(),
+    safety,
+  };
+};

package/src/trails/topo-show.ts

@@ -0,0 +1,54 @@
+import { NotFoundError, Result, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { loadApp } from './load-app.js';
+import { buildCurrentTopoDetail } from './topo-read-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(),
+  resources: z.array(z.string()),
+  safety: z.string(),
+});
+
+const resourceDetailOutput = z.object({
+  description: z.string().nullable(),
+  health: z.enum(['available', 'none']),
+  id: z.string(),
+  kind: z.literal('resource'),
+  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 resource not found: ${input.id}`)
+    );
+  },
+  description: 'Show detail for a current trail or resource',
+  examples: [
+    {
+      input: { id: 'topo' },
+      name: 'Show current trail detail',
+    },
+  ],
+  input: z.object({
+    id: z.string().describe('Trail or resource ID to inspect'),
+    module: z.string().optional().describe('Path to the app module'),
+    rootDir: z.string().optional().describe('Workspace root directory'),
+  }),
+  intent: 'read',
+  output: z.union([trailDetailOutput, resourceDetailOutput]),
+});

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

@@ -0,0 +1,104 @@
+/**
+ * Stored-export pipeline for topo persistence.
+ *
+ * Extracted from topo-support.ts to isolate store persistence concerns,
+ * keeping module boundaries clean.
+ */
+
+import type { Topo, TopoSnapshot } from '@ontrails/core';
+import { InternalError, Result } from '@ontrails/core';
+import type { StoredTopoExport } from '@ontrails/core/internal/topo-store';
+import {
+  createTopoSnapshot,
+  getStoredTopoExport,
+} from '@ontrails/core/internal/topo-store';
+import {
+  openWriteTrailsDb,
+  deriveTrailsDir,
+} from '@ontrails/core/internal/trails-db';
+import type { SurfaceLock, SurfaceMap } from '@ontrails/schema';
+import { writeSurfaceLock, writeSurfaceMap } from '@ontrails/schema';
+
+import type { TopoExportReport } from './topo-support.js';
+import {
+  deriveRootDir,
+  deriveTopoCounts,
+  readGitState,
+} from './topo-support.js';
+
+const persistAndReadStoredExport = (
+  app: Topo,
+  db: ReturnType<typeof openWriteTrailsDb>,
+  rootDir: string
+): Result<
+  { snapshot: TopoSnapshot; storedExport: StoredTopoExport },
+  Error
+> => {
+  const snapshotResult = createTopoSnapshot(db, app, {
+    ...readGitState(rootDir),
+    ...deriveTopoCounts(app),
+  });
+  if (snapshotResult.isErr()) {
+    return snapshotResult;
+  }
+
+  const snapshot = snapshotResult.value;
+  const storedExport = getStoredTopoExport(db, snapshot.id);
+
+  if (storedExport === undefined) {
+    return Result.err(
+      new InternalError(
+        `Missing stored topo export for snapshot "${snapshot.id}"`
+      )
+    );
+  }
+
+  return Result.ok({
+    snapshot,
+    storedExport,
+  });
+};
+
+const writeStoredExportArtifacts = async (
+  storedExport: StoredTopoExport,
+  trailsDir: string
+): Promise<Pick<TopoExportReport, 'hash' | 'lockPath' | 'mapPath'>> => {
+  const mapPath = await writeSurfaceMap(
+    JSON.parse(storedExport.surfaceMapJson) as SurfaceMap,
+    { dir: trailsDir }
+  );
+  const lockPath = await writeSurfaceLock(
+    JSON.parse(storedExport.lockContent) as SurfaceLock,
+    { dir: trailsDir }
+  );
+
+  return {
+    hash: storedExport.surfaceHash,
+    lockPath,
+    mapPath,
+  };
+};
+
+export const exportCurrentTopo = async (
+  app: Topo,
+  options?: { readonly rootDir?: string }
+): Promise<Result<TopoExportReport, Error>> => {
+  const rootDir = deriveRootDir(options?.rootDir);
+  const db = openWriteTrailsDb({ rootDir });
+
+  try {
+    const persisted = persistAndReadStoredExport(app, db, rootDir);
+    if (persisted.isErr()) {
+      return persisted;
+    }
+
+    const { snapshot, storedExport } = persisted.value;
+    const artifacts = await writeStoredExportArtifacts(
+      storedExport,
+      deriveTrailsDir({ rootDir })
+    );
+    return Result.ok({ ...artifacts, snapshot });
+  } finally {
+    db.close();
+  }
+};