@ontrails/trails 0.2.0

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

@@ -0,0 +1,323 @@
+/**
+ * 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,
+  TimeoutError,
+} from '@ontrails/core';
+import type {
+  LockManifest,
+  TopoGraph,
+  TopoGraphOverlayRegistration,
+  TopoSnapshot,
+  TrailsLock,
+} from '@ontrails/topography';
+import type { StoredTopoExport } from '@ontrails/topography/backend-support';
+import {
+  annotateTopoGraphForces,
+  carryForwardTopoGraphForces,
+  deriveSourceFingerprint,
+  deriveTopoGraphDiff,
+  deriveTopoGraphHash,
+  isTopoArtifactRegenerationError,
+  readTopoGraph,
+  TRAILS_LOCK_SCHEMA_VERSION,
+  writeTrailsLock,
+} from '@ontrails/topography';
+import {
+  createStoredTopoSnapshot,
+  getStoredTopoExport,
+} from '@ontrails/topography/backend-support';
+
+import { removeRootRelativeFileIfPresent } from '../local-state-io.js';
+
+import type { TopoExportReport } from './topo-support.js';
+import {
+  deriveRootDir,
+  deriveTopoCounts,
+  readGitState,
+} from './topo-support.js';
+
+type OverlaysOption = readonly TopoGraphOverlayRegistration[];
+
+const persistAndReadStoredExport = (
+  app: Topo,
+  db: ReturnType<typeof openWriteTrailsDb>,
+  rootDir: string,
+  options?:
+    | {
+        readonly overlays?: OverlaysOption | undefined;
+      }
+    | undefined
+): Result<
+  { snapshot: TopoSnapshot; storedExport: StoredTopoExport },
+  Error
+> => {
+  const snapshotResult = createStoredTopoSnapshot(db, app, {
+    overlays: options?.overlays,
+    sourceFingerprint: deriveSourceFingerprint(rootDir),
+    ...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 asError = (error: unknown): Error =>
+  error instanceof Error ? error : new Error(String(error));
+
+const readErrorCode = (error: unknown): string | undefined => {
+  if (typeof error !== 'object' || error === null || !('code' in error)) {
+    return undefined;
+  }
+  const { code } = error as { readonly code?: unknown };
+  return typeof code === 'string' ? code : undefined;
+};
+
+const isSqliteLockError = (error: unknown): boolean => {
+  const code = readErrorCode(error);
+  if (code === 'SQLITE_BUSY' || code === 'SQLITE_LOCKED') {
+    return true;
+  }
+  return asError(error).message.match(/database is (locked|busy)/i) !== null;
+};
+
+export const mapTopoExportError = (error: unknown): Error => {
+  if (!isSqliteLockError(error)) {
+    return error instanceof Error
+      ? error
+      : new InternalError('Unable to write topo artifacts');
+  }
+  return new TimeoutError(
+    'Timed out waiting for the Trails topo store lock while compiling artifacts. Another topo write may be running; retry after it finishes.',
+    {
+      cause: asError(error),
+      context: {
+        operation: 'compile',
+        reason: 'sqlite-lock-contention',
+        resource: 'trails.db',
+      },
+    }
+  );
+};
+
+export const deriveCurrentTopoExport = (
+  app: Topo,
+  options?: {
+    readonly rootDir?: string;
+    readonly overlays?: OverlaysOption | undefined;
+  }
+): Result<StoredTopoExport, Error> => {
+  const rootDir = deriveRootDir(options?.rootDir);
+  const db = new Database(':memory:');
+
+  try {
+    const derived = persistAndReadStoredExport(app, db, rootDir, {
+      overlays: options?.overlays,
+    });
+    return derived.isErr() ? derived : Result.ok(derived.value.storedExport);
+  } finally {
+    db.close();
+  }
+};
+
+const readPreviousCommittedTopo = async (
+  rootDir: string
+): Promise<TopoGraph | null> => {
+  try {
+    const rootTopo = await readTopoGraph({ dir: rootDir });
+    return rootTopo ?? readTopoGraph({ dir: deriveTrailsDir({ rootDir }) });
+  } catch (error) {
+    if (isTopoArtifactRegenerationError(error)) {
+      return null;
+    }
+    throw error;
+  }
+};
+
+const prepareStoredExportArtifacts = async (
+  storedExport: StoredTopoExport,
+  rootDir: string,
+  options?: { readonly force?: boolean | undefined }
+): Promise<{
+  readonly hash: string;
+  readonly topoGraph: TopoGraph;
+}> => {
+  const previousTopo = await readPreviousCommittedTopo(rootDir);
+  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);
+
+  return {
+    hash,
+    topoGraph,
+  };
+};
+
+const LEGACY_COMMITTED_ARTIFACTS = [
+  '.trails/topo.lock',
+  '.trails/trails.lock',
+] as const;
+
+const removeLegacyCommittedArtifacts = (
+  rootDir: string
+): Result<void, Error> => {
+  for (const relativePath of LEGACY_COMMITTED_ARTIFACTS) {
+    const removed = removeRootRelativeFileIfPresent(rootDir, relativePath);
+    if (removed.isErr()) {
+      return removed;
+    }
+  }
+
+  return Result.ok();
+};
+
+const writeStoredExportArtifacts = async (
+  storedExport: StoredTopoExport,
+  rootDir: string,
+  options?: { readonly force?: boolean | undefined }
+): Promise<Pick<TopoExportReport, 'hash' | 'lockPath'>> => {
+  const prepared = await prepareStoredExportArtifacts(
+    storedExport,
+    rootDir,
+    options
+  );
+
+  const lockManifest = JSON.parse(
+    storedExport.lockManifestJson
+  ) as LockManifest;
+  // Omit wallclock provenance from the committed artifact so recompiling the
+  // same sources yields byte-identical lock files; the hash never covered it.
+  const { generatedAt: _generatedAt, ...committedTopoGraph } =
+    prepared.topoGraph;
+  const lockPath = await writeTrailsLock(
+    {
+      scope: lockManifest.scope,
+      summary: {
+        entities: prepared.topoGraph.entries.filter(
+          (entry) => entry.kind === 'entity'
+        ).length,
+        resources: prepared.topoGraph.entries.filter(
+          (entry) => entry.kind === 'resource'
+        ).length,
+        signals: prepared.topoGraph.entries.filter(
+          (entry) => entry.kind === 'signal'
+        ).length,
+        trails: prepared.topoGraph.entries.filter(
+          (entry) => entry.kind === 'trail'
+        ).length,
+      },
+      topoGraph: committedTopoGraph,
+      topoGraphHash: prepared.hash,
+      version: TRAILS_LOCK_SCHEMA_VERSION,
+    } as TrailsLock,
+    { dir: rootDir }
+  );
+  const removedLegacyArtifacts = removeLegacyCommittedArtifacts(rootDir);
+  if (removedLegacyArtifacts.isErr()) {
+    throw removedLegacyArtifacts.error;
+  }
+
+  return {
+    hash: prepared.hash,
+    lockPath,
+  };
+};
+
+export const exportCurrentTopo = async (
+  app: Topo,
+  options?: {
+    readonly force?: boolean | undefined;
+    readonly rootDir?: string;
+    readonly overlays?: OverlaysOption | undefined;
+  }
+): Promise<Result<TopoExportReport, Error>> => {
+  const rootDir = deriveRootDir(options?.rootDir);
+  let db: ReturnType<typeof openWriteTrailsDb> | undefined;
+
+  try {
+    const candidate = deriveCurrentTopoExport(app, {
+      overlays: options?.overlays,
+      rootDir,
+    });
+    if (candidate.isErr()) {
+      return candidate;
+    }
+
+    try {
+      await prepareStoredExportArtifacts(candidate.value, rootDir, {
+        force: options?.force,
+      });
+    } catch (error: unknown) {
+      return Result.err(mapTopoExportError(error));
+    }
+
+    db = openWriteTrailsDb({ rootDir });
+    const persisted = persistAndReadStoredExport(app, db, rootDir, {
+      overlays: options?.overlays,
+    });
+    if (persisted.isErr()) {
+      return persisted;
+    }
+
+    const { snapshot, storedExport } = persisted.value;
+    let artifacts: Pick<TopoExportReport, 'hash' | 'lockPath'>;
+    try {
+      artifacts = await writeStoredExportArtifacts(storedExport, rootDir, {
+        force: options?.force,
+      });
+    } catch (error: unknown) {
+      return Result.err(mapTopoExportError(error));
+    }
+    return Result.ok({ ...artifacts, snapshot });
+  } catch (error: unknown) {
+    return Result.err(mapTopoExportError(error));
+  } finally {
+    db?.close();
+  }
+};

package/src/trails/topo-support.ts

@@ -0,0 +1,247 @@
+import { existsSync } from 'node:fs';
+
+import { deriveTrailsDbPath } from '@ontrails/core';
+import type { Topo } from '@ontrails/core';
+import {
+  createTopoSnapshot as persistTopoSnapshot,
+  listTopoSnapshots as readTopoSnapshots,
+  pinTopoSnapshot,
+  unpinTopoSnapshot,
+} from '@ontrails/topography';
+import type { TopoSnapshot } from '@ontrails/topography';
+import { z } from 'zod';
+
+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(),
+  sourceFingerprint: z.string().optional(),
+  trailCount: z.number(),
+});
+
+export const DEFAULT_TOPO_HISTORY_LIMIT = 10;
+export const LOCK_PATH = 'trails.lock';
+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;
+}
+
+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),
+});
+
+// Fresh app leases cache-bust the entry module, so use the process-global
+// symbol registry to preserve this internal authoring marker across module
+// instances. JSON derivation still omits symbol keys from the public example.
+const currentAppExampleSelection = Symbol.for(
+  '@ontrails/trails/current-app-example-selection'
+);
+
+export type CurrentAppExampleSelection = 'app-root' | 'configured-project';
+
+export const markCurrentAppExampleInput = <
+  const TInput extends Record<string, unknown>,
+>(
+  input: TInput,
+  options?: { readonly selection?: CurrentAppExampleSelection }
+): TInput =>
+  ({
+    ...input,
+    [currentAppExampleSelection]: options?.selection ?? 'app-root',
+  }) as TInput;
+
+export const createCurrentAppExampleInput = (options?: {
+  readonly selection?: CurrentAppExampleSelection;
+}): {
+  readonly module: string;
+  readonly rootDir: string;
+} =>
+  markCurrentAppExampleInput(
+    {
+      module: './src/app.ts',
+      rootDir: '.',
+    },
+    options
+  );
+
+export const readCurrentAppExampleSelection = (
+  input: unknown
+): CurrentAppExampleSelection | undefined => {
+  if (typeof input !== 'object' || input === null) {
+    return undefined;
+  }
+  const selection = (
+    input as { readonly [currentAppExampleSelection]?: unknown }
+  )[currentAppExampleSelection];
+  return selection === 'app-root' || selection === 'configured-project'
+    ? selection
+    : undefined;
+};
+
+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 {
+  createCurrentAppExampleInput,
+  removePinnedTopoSnapshot,
+  topoSnapshotOutput,
+} from './topo-support.js';
+import { resolveTrailRootDir } from './root-dir.js';
+
+export const topoUnpinTrail = trail('topo.unpin', {
+  description: 'Remove a named topo pin',
+  examples: [
+    {
+      input: {
+        ...createCurrentAppExampleInput(),
+        dryRun: true,
+        name: 'before-auth-refactor',
+      },
+      name: 'Preview pin removal',
+    },
+  ],
+  implementation: (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,
+      })
+    );
+  },
+  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'] },
+});