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

package/src/trails/topo-support.ts

@@ -0,0 +1,230 @@
+import { existsSync, mkdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  createTopoSnapshot as persistTopoSnapshot,
+  listTopoSnapshots as readTopoSnapshots,
+  pinTopoSnapshot,
+  unpinTopoSnapshot,
+} from '@ontrails/core';
+import type { Topo, TopoSnapshot } from '@ontrails/core';
+import { deriveTrailsDbPath } from '@ontrails/core/internal/trails-db';
+import { z } from 'zod';
+
+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_APP_MODULE = './src/app.ts';
+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));
+
+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 mapPath: string;
+  readonly snapshot: TopoSnapshot;
+}
+
+export interface TopoVerifyReport {
+  readonly committedHash: string;
+  readonly currentHash: string;
+  readonly lockPath: string;
+  readonly stale: false;
+}
+
+export const deriveRootDir = (cwd?: string): string => cwd ?? process.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 = join(tmpdir(), 'ontrails-trails-examples', name);
+  rmSync(rootDir, { force: true, recursive: true });
+  mkdirSync(rootDir, { recursive: true });
+  return {
+    module: EXAMPLE_APP_MODULE,
+    rootDir,
+  };
+};
+
+export const createCurrentTopoSnapshot = (
+  app: Topo,
+  options?: { readonly rootDir?: string }
+): TopoSnapshot => {
+  const rootDir = deriveRootDir(options?.rootDir);
+  const result = persistTopoSnapshot(app, {
+    rootDir,
+    ...buildSnapshotInput(app, rootDir),
+  });
+  if (result.isErr()) {
+    throw result.error;
+  }
+  return result.value;
+};
+
+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,56 @@
+import { Result, ValidationError, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import {
+  createIsolatedExampleInput,
+  removePinnedTopoSnapshot,
+  topoSnapshotOutput,
+} from './topo-support.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 rootDir = input.rootDir ?? ctx.cwd ?? process.cwd();
+    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:delete'] },
+});

package/src/trails/topo-verify.ts

@@ -0,0 +1,25 @@
+import { trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { loadApp } from './load-app.js';
+import { verifyCurrentTopo } from './topo-read-support.js';
+
+export const topoVerifyTrail = trail('topo.verify', {
+  blaze: async (input, ctx) => {
+    const rootDir = input.rootDir ?? ctx.cwd ?? process.cwd();
+    const app = await loadApp(input.module, rootDir);
+    return verifyCurrentTopo(app, { rootDir });
+  },
+  description: 'Verify that the committed lockfile matches 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),
+  }),
+});

package/src/trails/topo.ts

@@ -0,0 +1,69 @@
+import { Result, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { loadApp } from './load-app.js';
+import { buildTopoSummary } from './topo-read-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({
+    count: z.number(),
+    entries: z.array(
+      z.object({
+        examples: z.number(),
+        id: z.string(),
+        kind: z.string(),
+        safety: z.string(),
+      })
+    ),
+    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()),
+      })
+    ),
+  }),
+  lockExists: z.boolean(),
+  lockPath: z.string(),
+});
+
+export const topoTrail = trail('topo', {
+  blaze: async (input, ctx) => {
+    const rootDir = input.rootDir ?? ctx.cwd ?? process.cwd();
+    const app = await loadApp(input.module, rootDir);
+    return Result.ok(buildTopoSummary(app, { rootDir }));
+  },
+  description: 'Show the current topo summary and entry list',
+  examples: [
+    {
+      input: {},
+      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/warden.ts

@@ -23,9 +23,14 @@ import { loadApp } from './load-app.js';
 export const wardenTrail = trail('warden', {
   blaze: async (input, ctx) => {
     const rootDir = input.rootDir ?? ctx.cwd ?? process.cwd();
-    // oxlint-disable-next-line prefer-await-to-then -- catch converts rejection to undefined cleanly
-    const topo = await loadApp('./src/app.ts', rootDir).catch(
-      (): undefined => undefined
+    // oxlint-disable-next-line prefer-await-to-then -- catch preserves graceful degradation
+    const topo = await loadApp(input.module, rootDir).catch(
+      (error: unknown): undefined => {
+        ctx.logger?.warn('Could not load app for topo-aware governance', {
+          error: error instanceof Error ? error.message : String(error),
+        });
+        return undefined;
+      }
     );
 
     const report = await runWarden({
@@ -76,6 +81,10 @@ export const wardenTrail = trail('warden', {
       .default('text')
       .describe('Output format: text, json, github, or summary'),
     lintOnly: z.boolean().default(false).describe('Only run lint rules'),
+    module: z
+      .string()
+      .optional()
+      .describe('App module path (auto-discovered if omitted)'),
     rootDir: z.string().optional().describe('Root directory to scan'),
   }),
   intent: 'read',
@@ -91,6 +100,7 @@ export const wardenTrail = trail('warden', {
     ),
     drift: z
       .object({
+        blockedReason: z.string().optional(),
         committedHash: z.string().nullable(),
         currentHash: z.string(),
         stale: z.boolean(),

package/src/versions.ts

@@ -0,0 +1,43 @@
+interface PackageJson {
+  readonly catalog?: Record<string, string>;
+  readonly dependencies?: Record<string, string>;
+  readonly devDependencies?: Record<string, string>;
+  readonly version?: string;
+}
+
+const readPackageJson = async (url: URL): Promise<PackageJson> =>
+  (await Bun.file(url).json()) as PackageJson;
+
+const appPackageJson = await readPackageJson(
+  new URL('../package.json', import.meta.url)
+);
+const rootPackageJson = await readPackageJson(
+  new URL('../../../package.json', import.meta.url)
+);
+
+const requireVersion = (value: string | undefined, label: string): string => {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(`Missing version for ${label}`);
+  }
+  return value;
+};
+
+const rootCatalog = rootPackageJson.catalog ?? {};
+const rootDevDependencies = rootPackageJson.devDependencies ?? {};
+
+export const trailsPackageVersion = requireVersion(
+  appPackageJson.version,
+  '@ontrails/trails'
+);
+
+export const ontrailsPackageRange = `^${trailsPackageVersion}`;
+
+export const scaffoldDependencyVersions = {
+  bunTypes: requireVersion(rootDevDependencies['@types/bun'], '@types/bun'),
+  commander: requireVersion(rootCatalog['commander'], 'commander'),
+  lefthook: requireVersion(rootDevDependencies['lefthook'], 'lefthook'),
+  oxlint: requireVersion(rootDevDependencies['oxlint'], 'oxlint'),
+  typescript: requireVersion(rootDevDependencies['typescript'], 'typescript'),
+  ultracite: requireVersion(rootDevDependencies['ultracite'], 'ultracite'),
+  zod: requireVersion(rootCatalog['zod'], 'zod'),
+} as const;

package/tsconfig.tests.json

@@ -0,0 +1,10 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "rootDir": ".",
+    "types": ["bun"]
+  },
+  "include": ["src/**/*.test.ts", "src/__tests__/**/*.ts", "__tests__/**/*.ts"],
+  "exclude": []
+}

package/src/trails/add-trailhead.ts

@@ -1,121 +0,0 @@
-/**
- * `add.trailhead` trail -- Add a trailhead to an existing project.
- *
- * Generates the CLI or MCP entry point and updates package.json dependencies.
- */
-
-import { existsSync, mkdirSync } from 'node:fs';
-import { basename, dirname, join, resolve } from 'node:path';
-
-import { Result, trail } from '@ontrails/core';
-import { z } from 'zod';
-
-import { findTopoPath } from './project.js';
-
-const generateCliEntry = (appImportPath: string): string =>
-  `import { trailhead } from '@ontrails/cli/commander';
-
-import { app } from '${appImportPath}';
-
-trailhead(app);
-`;
-
-const generateMcpEntry = (appImportPath: string): string =>
-  `import { trailhead } from '@ontrails/mcp';
-
-import { app } from '${appImportPath}';
-
-await trailhead(app);
-`;
-
-/** Resolve the entry file for a trailhead. */
-const getEntryFile = (trailhead: 'cli' | 'mcp'): string =>
-  trailhead === 'cli' ? 'src/cli.ts' : 'src/mcp.ts';
-
-// ---------------------------------------------------------------------------
-// Trail definition
-// ---------------------------------------------------------------------------
-
-/** Patch deps and optionally bin in a parsed package.json. */
-const patchPkgDeps = (
-  pkg: Record<string, unknown>,
-  trailhead: 'cli' | 'mcp',
-  cwd: string
-): string => {
-  const depName = trailhead === 'cli' ? '@ontrails/cli' : '@ontrails/mcp';
-  const deps = (pkg['dependencies'] ?? {}) as Record<string, string>;
-  deps[depName] = 'workspace:*';
-  if (trailhead === 'cli') {
-    deps['commander'] = '^14.0.0';
-    pkg['bin'] = {
-      [(pkg['name'] as string | undefined) ?? basename(cwd)]: './src/cli.ts',
-    };
-  }
-  pkg['dependencies'] = Object.fromEntries(
-    Object.entries(deps).toSorted(([a], [b]) => a.localeCompare(b))
-  );
-  return depName;
-};
-
-/** Update package.json with trailhead dependency and CLI bin if needed. */
-const updatePkgJsonForTrailhead = async (
-  cwd: string,
-  trailhead: 'cli' | 'mcp'
-): Promise<string> => {
-  const pkgPath = join(cwd, 'package.json');
-  if (!existsSync(pkgPath)) {
-    return trailhead === 'cli' ? '@ontrails/cli' : '@ontrails/mcp';
-  }
-  const pkg = (await Bun.file(pkgPath).json()) as Record<string, unknown>;
-  const depName = patchPkgDeps(pkg, trailhead, cwd);
-  await Bun.write(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
-  return depName;
-};
-
-/** Create the entry file for a trailhead and return the relative path. */
-const writeTrailheadEntry = async (
-  cwd: string,
-  trailhead: 'cli' | 'mcp'
-): Promise<string> => {
-  const entryFile = getEntryFile(trailhead);
-  const fullEntryPath = join(cwd, entryFile);
-  const appImport = (await findTopoPath(cwd)) ?? './app.js';
-  const content =
-    trailhead === 'cli'
-      ? generateCliEntry(appImport)
-      : generateMcpEntry(appImport);
-
-  mkdirSync(dirname(fullEntryPath), { recursive: true });
-  await Bun.write(fullEntryPath, content);
-  return entryFile;
-};
-
-export const addTrailhead = trail('add.trailhead', {
-  blaze: async (input) => {
-    const cwd = resolve(input.dir ?? '.');
-    const { trailhead } = input;
-    const entryFile = getEntryFile(trailhead);
-
-    if (existsSync(join(cwd, entryFile))) {
-      return Result.err(
-        new Error(
-          `${trailhead.toUpperCase()} trailhead already exists. Nothing to do.`
-        )
-      );
-    }
-
-    return Result.ok({
-      created: await writeTrailheadEntry(cwd, trailhead),
-      dependency: await updatePkgJsonForTrailhead(cwd, trailhead),
-    });
-  },
-  description: 'Add a trailhead to an existing project',
-  input: z.object({
-    dir: z.string().optional().describe('Project directory'),
-    trailhead: z.enum(['cli', 'mcp']).describe('Trailhead to add'),
-  }),
-  output: z.object({
-    created: z.string(),
-    dependency: z.string(),
-  }),
-});