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

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

@@ -0,0 +1,174 @@
+/**
+ * Stored-export pipeline for topo persistence.
+ *
+ * Extracted from topo-support.ts to isolate store persistence concerns,
+ * keeping module boundaries clean.
+ */
+
+import { Database } from 'bun:sqlite';
+
+import type { Topo } from '@ontrails/core';
+import {
+  ConflictError,
+  deriveTrailsDir,
+  InternalError,
+  openWriteTrailsDb,
+  Result,
+} from '@ontrails/core';
+import type {
+  LockManifest,
+  TopoGraph,
+  TopoSnapshot,
+} from '@ontrails/topographer';
+import type { StoredTopoExport } from '@ontrails/topographer/backend-support';
+import {
+  annotateTopoGraphForces,
+  carryForwardTopoGraphForces,
+  deriveTopoGraphDiff,
+  deriveTopoGraphHash,
+  readTopoGraph,
+  writeLockManifest,
+  writeTopoGraph,
+} from '@ontrails/topographer';
+import {
+  createStoredTopoSnapshot,
+  getStoredTopoExport,
+} from '@ontrails/topographer/backend-support';
+
+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 = createStoredTopoSnapshot(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,
+  });
+};
+
+export const deriveCurrentTopoExport = (
+  app: Topo,
+  options?: { readonly rootDir?: string }
+): Result<StoredTopoExport, Error> => {
+  const rootDir = deriveRootDir(options?.rootDir);
+  const db = new Database(':memory:');
+
+  try {
+    const projected = persistAndReadStoredExport(app, db, rootDir);
+    return projected.isErr()
+      ? projected
+      : Result.ok(projected.value.storedExport);
+  } finally {
+    db.close();
+  }
+};
+
+const writeStoredExportArtifacts = async (
+  storedExport: StoredTopoExport,
+  trailsDir: string,
+  options?: { readonly force?: boolean | undefined }
+): Promise<Pick<TopoExportReport, 'hash' | 'lockPath' | 'topoPath'>> => {
+  const previousTopo = await readTopoGraph({ dir: trailsDir });
+  const nextTopo = JSON.parse(storedExport.topoGraphJson) as TopoGraph;
+  const diff =
+    previousTopo === null
+      ? undefined
+      : deriveTopoGraphDiff(previousTopo, nextTopo);
+  if (diff !== undefined && diff.breaking.length > 0 && !options?.force) {
+    throw new ConflictError(
+      `Topo contains ${diff.breaking.length} breaking change(s). Add a version entry, revert the change, or rerun with --force.`
+    );
+  }
+
+  const topoGraphBase =
+    previousTopo === null
+      ? nextTopo
+      : carryForwardTopoGraphForces(previousTopo, nextTopo);
+  const topoGraph =
+    diff === undefined || diff.breaking.length === 0
+      ? topoGraphBase
+      : annotateTopoGraphForces(topoGraphBase, diff.breaking);
+  const hash = deriveTopoGraphHash(topoGraph);
+  const lockManifest = {
+    ...(JSON.parse(storedExport.lockManifestJson) as LockManifest),
+    artifacts: [
+      {
+        path: 'topo.lock',
+        role: 'topo',
+        sha256: hash,
+      },
+    ],
+  } satisfies LockManifest;
+
+  const topoPath = await writeTopoGraph(topoGraph, { dir: trailsDir });
+  const lockPath = await writeLockManifest(lockManifest, { dir: trailsDir });
+
+  return {
+    hash,
+    lockPath,
+    topoPath,
+  };
+};
+
+export const exportCurrentTopo = async (
+  app: Topo,
+  options?: { readonly force?: boolean | undefined; 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;
+    let artifacts: Pick<TopoExportReport, 'hash' | 'lockPath' | 'topoPath'>;
+    try {
+      artifacts = await writeStoredExportArtifacts(
+        storedExport,
+        deriveTrailsDir({ rootDir }),
+        { force: options?.force }
+      );
+    } catch (error: unknown) {
+      return Result.err(
+        error instanceof Error
+          ? error
+          : new InternalError('Unable to write topo artifacts')
+      );
+    }
+    return Result.ok({ ...artifacts, snapshot });
+  } finally {
+    db.close();
+  }
+};

package/src/trails/topo-support.ts

@@ -0,0 +1,220 @@
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+import { deriveTrailsDbPath } from '@ontrails/core';
+import type { Topo } from '@ontrails/core';
+import {
+  createTopoSnapshot as persistTopoSnapshot,
+  listTopoSnapshots as readTopoSnapshots,
+  pinTopoSnapshot,
+  unpinTopoSnapshot,
+} from '@ontrails/topographer';
+import type { TopoSnapshot } from '@ontrails/topographer';
+import { z } from 'zod';
+
+import {
+  createIsolatedExampleRoot,
+  writeIsolatedExampleAppModule,
+} from '../local-state-io.js';
+
+import { requireTrailRootDir } from './root-dir.js';
+import type { BriefReport, SurveyListReport } from './topo-reports.js';
+
+/** Output schema for a topo snapshot record. Shared across topo trails. */
+export const topoSnapshotOutput = z.object({
+  createdAt: z.string(),
+  gitDirty: z.boolean(),
+  gitSha: z.string().optional(),
+  id: z.string(),
+  pinnedAs: z.string().optional(),
+  resourceCount: z.number(),
+  signalCount: z.number(),
+  trailCount: z.number(),
+});
+
+export const DEFAULT_TOPO_HISTORY_LIMIT = 10;
+export const LOCK_PATH = '.trails/trails.lock';
+const EXAMPLE_APP_MODULE = fileURLToPath(new URL('../app.ts', import.meta.url));
+
+const uniqueExampleRootName = (name: string): string =>
+  `${name}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+
+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 pinnedCount: number;
+  readonly snapshotCount: number;
+  readonly snapshots: TopoSnapshot[];
+}
+
+export interface TopoExportReport {
+  readonly hash: string;
+  readonly lockPath: string;
+  readonly snapshot: TopoSnapshot;
+  readonly topoPath: string;
+}
+
+export interface TopoValidateReport {
+  readonly committedHash: string;
+  readonly currentHash: string;
+  readonly lockPath: string;
+  readonly stale: false;
+}
+
+export const deriveRootDir = (cwd?: string): string => requireTrailRootDir(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 readGitState = (
+  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 deriveTopoCounts = (
+  app: Topo
+): Pick<TopoSnapshot, 'resourceCount' | 'signalCount' | 'trailCount'> => ({
+  resourceCount: app.resources.size,
+  signalCount: app.signals.size,
+  trailCount: app.trails.size,
+});
+
+const emptyTopoHistory = (
+  dbPath: string,
+  limit: number
+): TopoHistoryReport => ({
+  dbPath,
+  limit,
+  pinnedCount: 0,
+  snapshotCount: 0,
+  snapshots: [],
+});
+
+const collectTopoHistory = (
+  dbPath: string,
+  limit: number,
+  snapshots: readonly TopoSnapshot[]
+): TopoHistoryReport => ({
+  dbPath,
+  limit,
+  pinnedCount: snapshots.filter((snapshot) => snapshot.pinnedAs !== undefined)
+    .length,
+  snapshotCount: snapshots.length,
+  snapshots: snapshots.slice(0, limit),
+});
+
+const buildSnapshotInput = (
+  app: Topo,
+  rootDir: string
+): {
+  readonly gitDirty: boolean;
+  readonly gitSha?: string;
+  readonly resourceCount: number;
+  readonly signalCount: number;
+  readonly trailCount: number;
+} => ({
+  ...readGitState(rootDir),
+  ...deriveTopoCounts(app),
+});
+
+export const createIsolatedExampleInput = (
+  name: string
+): { readonly module: string; readonly rootDir: string } => {
+  const rootDir = createIsolatedExampleRoot(uniqueExampleRootName(name));
+  return {
+    module: writeIsolatedExampleAppModule(rootDir, EXAMPLE_APP_MODULE),
+    rootDir,
+  };
+};
+
+export const listTopoHistory = (options?: {
+  readonly limit?: number;
+  readonly rootDir?: string;
+}): TopoHistoryReport => {
+  const rootDir = deriveRootDir(options?.rootDir);
+  const limit = options?.limit ?? DEFAULT_TOPO_HISTORY_LIMIT;
+  const dbPath = deriveTrailsDbPath({ rootDir });
+  if (!existsSync(dbPath)) {
+    return emptyTopoHistory(dbPath, limit);
+  }
+
+  return collectTopoHistory(dbPath, limit, readTopoSnapshots({ rootDir }));
+};
+
+export const pinCurrentTopoSnapshot = (
+  app: Topo,
+  input: { readonly name: string; readonly rootDir?: string }
+): { readonly snapshot: TopoSnapshot } => {
+  const rootDir = deriveRootDir(input.rootDir);
+  const created = persistTopoSnapshot(app, {
+    rootDir,
+    ...buildSnapshotInput(app, rootDir),
+  });
+  if (created.isErr()) {
+    throw created.error;
+  }
+
+  const snapshot = pinTopoSnapshot(created.value.id, input.name, {
+    rootDir,
+  });
+  if (snapshot === undefined) {
+    throw new Error(`Missing topo snapshot "${created.value.id}" to pin`);
+  }
+
+  return { snapshot };
+};
+
+export const removePinnedTopoSnapshot = (input: {
+  readonly dryRun: boolean;
+  readonly name: string;
+  readonly rootDir?: string;
+}): {
+  readonly dryRun: boolean;
+  readonly removed: boolean;
+  readonly snapshot?: TopoSnapshot;
+} => {
+  const rootDir = deriveRootDir(input.rootDir);
+  if (!existsSync(deriveTrailsDbPath({ rootDir }))) {
+    return { dryRun: input.dryRun, removed: false };
+  }
+
+  if (input.dryRun) {
+    const snapshot = readTopoSnapshots({ pinned: true, rootDir }).find(
+      (candidate) => candidate.pinnedAs === input.name
+    );
+    return snapshot === undefined
+      ? { dryRun: true, removed: false }
+      : { dryRun: true, removed: false, snapshot };
+  }
+
+  const snapshot = unpinTopoSnapshot(input.name, { rootDir });
+  return {
+    dryRun: false,
+    removed: snapshot !== undefined,
+    ...(snapshot === undefined ? {} : { snapshot }),
+  };
+};

package/src/trails/topo-unpin.ts

@@ -0,0 +1,61 @@
+import { Result, ValidationError, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import {
+  createIsolatedExampleInput,
+  removePinnedTopoSnapshot,
+  topoSnapshotOutput,
+} from './topo-support.js';
+import { resolveTrailRootDir } from './root-dir.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 rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
+    if (rootDirResult.isErr()) {
+      return rootDirResult;
+    }
+    const rootDir = rootDirResult.value;
+    return Result.ok(
+      removePinnedTopoSnapshot({
+        dryRun: input.dryRun,
+        name: input.name,
+        rootDir,
+      })
+    );
+  },
+  description: 'Remove a named topo pin',
+  examples: [
+    {
+      input: {
+        ...createIsolatedExampleInput('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(),
+    removed: z.boolean(),
+    snapshot: topoSnapshotOutput.optional(),
+  }),
+  permit: { scopes: ['topo:write'] },
+});

package/src/trails/topo.ts

@@ -0,0 +1,106 @@
+import { Result, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { tryLoadFreshAppLease } from './load-app.js';
+import { resolveTrailRootDir } from './root-dir.js';
+import { activationOverviewOutput } from './topo-output-schemas.js';
+import { buildTopoSummary } from './topo-read-support.js';
+import { createIsolatedExampleInput } 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(),
+      resources: z.boolean(),
+      signals: z.boolean(),
+    }),
+    name: z.string(),
+    resources: z.number(),
+    signals: z.number(),
+    trails: z.number(),
+    version: z.string(),
+  }),
+  dbPath: z.string(),
+  list: z.object({
+    activation: activationOverviewOutput,
+    count: z.number(),
+    entries: z
+      .array(
+        z.object({
+          activatedBy: z.array(z.string()).readonly(),
+          activates: z.array(z.string()).readonly(),
+          examples: z.number(),
+          id: z.string(),
+          kind: z.string(),
+          safety: z.string(),
+        })
+      )
+      .readonly(),
+    resourceCount: z.number(),
+    resources: z
+      .array(
+        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()).readonly(),
+        })
+      )
+      .readonly(),
+    signalCount: z.number(),
+    signals: z
+      .array(
+        z.object({
+          consumers: z.array(z.string()).readonly(),
+          description: z.string().nullable(),
+          examples: z.number(),
+          from: z.array(z.string()).readonly(),
+          id: z.string(),
+          kind: z.literal('signal'),
+          payloadSchema: z.boolean(),
+          producers: z.array(z.string()).readonly(),
+        })
+      )
+      .readonly(),
+  }),
+  lockExists: z.boolean(),
+  lockPath: z.string(),
+});
+
+export const topoTrail = trail('topo', {
+  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(buildTopoSummary(lease.app, { rootDir }));
+    } finally {
+      lease.release();
+    }
+  },
+  description: 'Show the current topo summary and entry list',
+  examples: [
+    {
+      input: createIsolatedExampleInput('topo-summary'),
+      name: 'Show the current topo summary',
+    },
+  ],
+  input: z.object({
+    module: z.string().optional().describe('Path to the app module'),
+    rootDir: z.string().optional().describe('Workspace root directory'),
+  }),
+  intent: 'read',
+  output: summaryOutput,
+});

package/src/trails/validate.ts

@@ -0,0 +1,38 @@
+import { trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { tryLoadFreshAppLease } from './load-app.js';
+import { resolveTrailRootDir } from './root-dir.js';
+import { validateCurrentTopo } from './topo-read-support.js';
+
+export const validateTrail = trail('validate', {
+  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 await validateCurrentTopo(lease.app, { rootDir });
+    } finally {
+      lease.release();
+    }
+  },
+  description: 'Validate that committed topo artifacts match the current topo',
+  input: z.object({
+    module: z.string().optional().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),
+  }),
+});