@ontrails/trails 1.0.0-beta.2 → 1.0.0-beta.22

package/src/trails/topo-pin.ts

@@ -0,0 +1,52 @@
+import { Result, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { tryLoadFreshAppLease } from './load-app.js';
+import { resolveTrailRootDir } from './root-dir.js';
+import {
+  createIsolatedExampleInput,
+  pinCurrentTopoSnapshot,
+  topoSnapshotOutput,
+} from './topo-support.js';
+
+export const topoPinTrail = trail('topo.pin', {
+  blaze: async (input, ctx) => {
+    const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
+    if (rootDirResult.isErr()) {
+      return rootDirResult;
+    }
+    const rootDir = rootDirResult.value;
+    const leaseResult = await tryLoadFreshAppLease(input.module, rootDir);
+    if (leaseResult.isErr()) {
+      return leaseResult;
+    }
+    const lease = leaseResult.value;
+    try {
+      return Result.ok(
+        pinCurrentTopoSnapshot(lease.app, { name: input.name, rootDir })
+      );
+    } finally {
+      lease.release();
+    }
+  },
+  description: 'Pin the current topo under a durable name',
+  examples: [
+    {
+      input: {
+        ...createIsolatedExampleInput('topo-pin'),
+        name: 'before-auth-refactor',
+      },
+      name: 'Pin the current topo',
+    },
+  ],
+  input: z.object({
+    module: z.string().optional().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({
+    snapshot: topoSnapshotOutput,
+  }),
+  permit: { scopes: ['topo:write'] },
+});

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

@@ -0,0 +1,313 @@
+/**
+ * Read-only live topo consumer helpers.
+ *
+ * Extracted from topo-support.ts to isolate read-only topo consumer helpers,
+ * keeping module boundaries clean.
+ */
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import type { Topo, TrailContext } from '@ontrails/core';
+import {
+  ConflictError,
+  deriveTrailsDbPath,
+  deriveTrailsDir,
+  NotFoundError,
+  Result,
+  SURFACE_LAYER_NAMES_KEY,
+  ValidationError,
+} from '@ontrails/core';
+import {
+  deriveTopoGraph,
+  deriveTopoGraphDiff,
+  deriveTopoGraphHash,
+  readLockManifest,
+  readTopoGraph,
+  stripTopoGraphForces,
+} from '@ontrails/topographer';
+import type { TopoGraph } from '@ontrails/topographer';
+
+import type {
+  BriefReport,
+  SignalDetailReport,
+  SurfaceLayerNames,
+  SurveyListReport,
+  TrailDetailReport,
+} from './topo-reports.js';
+import {
+  countTrailExamples,
+  deriveBriefReport,
+  deriveResourceDetail,
+  deriveSignalDetail,
+  deriveSurveyList,
+  deriveTrailDetail,
+} from './topo-reports.js';
+import type { ActivationGraphReport } from './topo-activation.js';
+import { deriveActivationGraph } from './topo-activation.js';
+import type { TopoSummaryReport, TopoValidateReport } from './topo-support.js';
+import { deriveRootDir, LOCK_PATH } from './topo-support.js';
+import { deriveCurrentTopoExport } from './topo-store-support.js';
+
+export type CurrentTrailDetail = TrailDetailReport;
+
+export interface CurrentResourceDetail {
+  readonly description: string | null;
+  readonly health: 'available' | 'none';
+  readonly id: string;
+  readonly kind: 'resource';
+  readonly lifetime: 'singleton';
+  readonly usedBy: readonly string[];
+}
+
+export type CurrentTopoDetail =
+  | CurrentResourceDetail
+  | CurrentTrailDetail
+  | SignalDetailReport;
+
+export interface CurrentTopoMatch {
+  readonly kind: CurrentTopoDetail['kind'];
+  readonly detail: CurrentTopoDetail;
+}
+
+export interface CurrentTopoReadOptions {
+  readonly rootDir?: string | undefined;
+  readonly surfaceLayerNames?: Partial<SurfaceLayerNames> | undefined;
+}
+
+const isStringArray = (value: unknown): value is readonly string[] =>
+  Array.isArray(value) && value.every((item) => typeof item === 'string');
+
+export const readSurfaceLayerNamesFromContext = (
+  ctx: TrailContext
+): Partial<SurfaceLayerNames> => {
+  const value = ctx.extensions?.[SURFACE_LAYER_NAMES_KEY];
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return {};
+  }
+  const raw = value as Record<string, unknown>;
+  return {
+    ...(isStringArray(raw['cli']) ? { cli: raw['cli'] } : {}),
+    ...(isStringArray(raw['http']) ? { http: raw['http'] } : {}),
+    ...(isStringArray(raw['mcp']) ? { mcp: raw['mcp'] } : {}),
+  };
+};
+
+const hasCommittedLock = (trailsDir: string): boolean =>
+  existsSync(join(trailsDir, 'trails.lock'));
+
+// ---------------------------------------------------------------------------
+// Public read-only consumers
+// ---------------------------------------------------------------------------
+
+export const buildTopoSummary = (
+  app: Topo,
+  options?: { readonly rootDir?: string }
+): TopoSummaryReport => {
+  const rootDir = deriveRootDir(options?.rootDir);
+  const trailsDir = deriveTrailsDir({ rootDir });
+  return {
+    app: deriveBriefReport(app),
+    dbPath: deriveTrailsDbPath({ rootDir }),
+    list: deriveSurveyList(app),
+    lockExists: hasCommittedLock(trailsDir),
+    lockPath: LOCK_PATH,
+  };
+};
+
+export const buildCurrentTopoBrief = (
+  app: Topo,
+  _options?: { readonly rootDir?: string }
+): BriefReport => deriveBriefReport(app);
+
+export const buildCurrentTopoList = (
+  app: Topo,
+  _options?: { readonly rootDir?: string }
+): SurveyListReport => deriveSurveyList(app);
+
+export const buildCurrentGuideEntries = (
+  app: Topo,
+  _options?: { readonly rootDir?: string }
+): readonly {
+  readonly description: string;
+  readonly exampleCount: number;
+  readonly id: string;
+  readonly kind: 'trail';
+}[] =>
+  app
+    .list()
+    .map((trail) => ({
+      description: trail.description ?? '(no description)',
+      exampleCount: countTrailExamples(trail),
+      id: trail.id,
+      kind: 'trail' as const,
+    }))
+    .toSorted((a, b) => a.id.localeCompare(b.id));
+
+export const buildCurrentTrailDetail = (
+  app: Topo,
+  id: string,
+  options?: CurrentTopoReadOptions
+): CurrentTrailDetail | undefined => {
+  const trail = app.get(id);
+  return trail === undefined
+    ? undefined
+    : deriveTrailDetail(trail, app, undefined, {
+        surfaceLayerNames: options?.surfaceLayerNames,
+      });
+};
+
+export const buildCurrentResourceDetail = (
+  app: Topo,
+  id: string,
+  _options?: { readonly rootDir?: string }
+): CurrentResourceDetail | undefined =>
+  app.getResource(id) === undefined
+    ? undefined
+    : (deriveResourceDetail(app, id) as CurrentResourceDetail);
+
+export const buildCurrentSignalDetail = (
+  app: Topo,
+  id: string,
+  _options?: { readonly rootDir?: string }
+): SignalDetailReport | undefined => deriveSignalDetail(app, id);
+
+export const buildCurrentTopoDetail = (
+  app: Topo,
+  id: string,
+  options?: CurrentTopoReadOptions
+): CurrentTopoDetail | undefined =>
+  buildCurrentTrailDetail(app, id, options) ??
+  buildCurrentResourceDetail(app, id) ??
+  buildCurrentSignalDetail(app, id);
+
+export const buildCurrentTopoMatches = (
+  app: Topo,
+  id: string,
+  options?: CurrentTopoReadOptions
+): readonly CurrentTopoMatch[] => {
+  const matches: CurrentTopoMatch[] = [];
+  let activationGraph: ActivationGraphReport | undefined;
+  const getActivationGraph = (): ActivationGraphReport =>
+    (activationGraph ??= deriveActivationGraph(app));
+  let topoGraph: ReturnType<typeof deriveTopoGraph> | undefined;
+  const getTopoGraph = (): ReturnType<typeof deriveTopoGraph> =>
+    (topoGraph ??= deriveTopoGraph(app));
+
+  const trail = app.get(id);
+  if (trail !== undefined) {
+    matches.push({
+      detail: deriveTrailDetail(trail, app, getActivationGraph(), {
+        surfaceLayerNames: options?.surfaceLayerNames,
+        topoGraph: getTopoGraph(),
+      }),
+      kind: 'trail',
+    });
+  }
+
+  const resource = buildCurrentResourceDetail(app, id);
+  if (resource !== undefined) {
+    matches.push({ detail: resource, kind: 'resource' });
+  }
+
+  const signal = deriveSignalDetail(app, id, activationGraph);
+  if (signal !== undefined) {
+    matches.push({ detail: signal, kind: 'signal' });
+  }
+
+  return matches;
+};
+
+export const validateCurrentTopo = async (
+  app: Topo,
+  options?: { readonly rootDir?: string }
+): Promise<Result<TopoValidateReport, Error>> => {
+  const rootDir = deriveRootDir(options?.rootDir);
+  let lockManifest: Awaited<ReturnType<typeof readLockManifest>>;
+  try {
+    lockManifest = await readLockManifest({
+      dir: deriveTrailsDir({ rootDir }),
+    });
+  } catch (error) {
+    const message =
+      error instanceof Error
+        ? error.message
+        : 'Unable to read committed trails.lock manifest.';
+    return Result.err(
+      error instanceof Error
+        ? new ValidationError(message, { cause: error })
+        : new ValidationError(message)
+    );
+  }
+
+  if (lockManifest === null) {
+    return Result.err(
+      new NotFoundError(
+        'No committed trails.lock found. Run `trails compile` first.'
+      )
+    );
+  }
+
+  const currentExport = deriveCurrentTopoExport(app, { rootDir });
+  if (currentExport.isErr()) {
+    return currentExport;
+  }
+  const currentTopo = JSON.parse(
+    currentExport.value.topoGraphJson
+  ) as TopoGraph;
+  const currentHash = currentExport.value.topoGraphHash;
+  const topoArtifact = lockManifest.artifacts.find(
+    (artifact) => artifact.role === 'topo' && artifact.path === 'topo.lock'
+  );
+  if (topoArtifact === undefined) {
+    return Result.err(
+      new NotFoundError(
+        'No topo.lock artifact found in trails.lock. Run `trails compile` first.'
+      )
+    );
+  }
+
+  if (topoArtifact.sha256 !== currentHash) {
+    const committedTopo = await readTopoGraph({
+      dir: deriveTrailsDir({ rootDir }),
+    });
+    if (committedTopo !== null) {
+      const committedHash = deriveTopoGraphHash(committedTopo);
+      const forceStrippedHash = deriveTopoGraphHash(
+        stripTopoGraphForces(committedTopo)
+      );
+      if (
+        committedHash === topoArtifact.sha256 &&
+        forceStrippedHash === currentHash
+      ) {
+        return Result.ok({
+          committedHash: topoArtifact.sha256,
+          currentHash,
+          lockPath: LOCK_PATH,
+          stale: false,
+        });
+      }
+    }
+    const breakingSummary =
+      committedTopo === null
+        ? ''
+        : (() => {
+            const diff = deriveTopoGraphDiff(committedTopo, currentTopo);
+            return diff.breaking.length > 0
+              ? ` Breaking changes detected: ${diff.breaking.length}.`
+              : '';
+          })();
+    return Result.err(
+      new ConflictError(
+        `trails.lock is stale. Run \`trails compile\` to refresh it.${breakingSummary}`
+      )
+    );
+  }
+
+  return Result.ok({
+    committedHash: topoArtifact.sha256,
+    currentHash,
+    lockPath: LOCK_PATH,
+    stale: false,
+  });
+};