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

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

@@ -5,19 +5,26 @@
  * 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 { Database } from 'bun:sqlite';
+
+import type { Topo } from '@ontrails/core';
 import {
-  openWriteTrailsDb,
   deriveTrailsDir,
-} from '@ontrails/core/internal/trails-db';
-import type { SurfaceLock, SurfaceMap } from '@ontrails/schema';
-import { writeSurfaceLock, writeSurfaceMap } from '@ontrails/schema';
+  InternalError,
+  openWriteTrailsDb,
+  Result,
+} from '@ontrails/core';
+import type {
+  LockManifest,
+  TopoGraph,
+  TopoSnapshot,
+} from '@ontrails/topographer';
+import type { StoredTopoExport } from '@ontrails/topographer/backend-support';
+import { writeLockManifest, writeTopoGraph } from '@ontrails/topographer';
+import {
+  createStoredTopoSnapshot,
+  getStoredTopoExport,
+} from '@ontrails/topographer/backend-support';
 
 import type { TopoExportReport } from './topo-support.js';
 import {
@@ -34,7 +41,7 @@ const persistAndReadStoredExport = (
   { snapshot: TopoSnapshot; storedExport: StoredTopoExport },
   Error
 > => {
-  const snapshotResult = createTopoSnapshot(db, app, {
+  const snapshotResult = createStoredTopoSnapshot(db, app, {
     ...readGitState(rootDir),
     ...deriveTopoCounts(app),
   });
@@ -59,23 +66,40 @@ const persistAndReadStoredExport = (
   });
 };
 
+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
-): Promise<Pick<TopoExportReport, 'hash' | 'lockPath' | 'mapPath'>> => {
-  const mapPath = await writeSurfaceMap(
-    JSON.parse(storedExport.surfaceMapJson) as SurfaceMap,
+): Promise<Pick<TopoExportReport, 'hash' | 'lockPath' | 'topoPath'>> => {
+  const topoPath = await writeTopoGraph(
+    JSON.parse(storedExport.topoGraphJson) as TopoGraph,
     { dir: trailsDir }
   );
-  const lockPath = await writeSurfaceLock(
-    JSON.parse(storedExport.lockContent) as SurfaceLock,
+  const lockPath = await writeLockManifest(
+    JSON.parse(storedExport.lockManifestJson) as LockManifest,
     { dir: trailsDir }
   );
 
   return {
-    hash: storedExport.surfaceHash,
+    hash: storedExport.topoGraphHash,
     lockPath,
-    mapPath,
+    topoPath,
   };
 };
 

package/src/trails/topo-support.ts

@@ -1,18 +1,23 @@
-import { existsSync, mkdirSync, rmSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+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/core';
-import type { Topo, TopoSnapshot } from '@ontrails/core';
-import { deriveTrailsDbPath } from '@ontrails/core/internal/trails-db';
+} 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. */
@@ -27,11 +32,13 @@ export const topoSnapshotOutput = z.object({
   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));
 
+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;
@@ -51,8 +58,8 @@ export interface TopoHistoryReport {
 export interface TopoExportReport {
   readonly hash: string;
   readonly lockPath: string;
-  readonly mapPath: string;
   readonly snapshot: TopoSnapshot;
+  readonly topoPath: string;
 }
 
 export interface TopoVerifyReport {
@@ -62,7 +69,7 @@ export interface TopoVerifyReport {
   readonly stale: false;
 }
 
-export const deriveRootDir = (cwd?: string): string => cwd ?? process.cwd();
+export const deriveRootDir = (cwd?: string): string => requireTrailRootDir(cwd);
 
 const safeGit = (cwd: string, args: readonly string[]): string | undefined => {
   const proc = Bun.spawnSync({
@@ -137,30 +144,13 @@ const buildSnapshotInput = (
 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 });
+  const rootDir = createIsolatedExampleRoot(uniqueExampleRootName(name));
   return {
-    module: EXAMPLE_APP_MODULE,
+    module: writeIsolatedExampleAppModule(rootDir, 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;

package/src/trails/topo-unpin.ts

@@ -6,6 +6,7 @@ import {
   removePinnedTopoSnapshot,
   topoSnapshotOutput,
 } from './topo-support.js';
+import { resolveTrailRootDir } from './root-dir.js';
 
 export const topoUnpinTrail = trail('topo.unpin', {
   blaze: (input, ctx) => {
@@ -17,7 +18,11 @@ export const topoUnpinTrail = trail('topo.unpin', {
       );
     }
 
-    const rootDir = input.rootDir ?? ctx.cwd ?? process.cwd();
+    const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
+    if (rootDirResult.isErr()) {
+      return Result.err(rootDirResult.error);
+    }
+    const rootDir = rootDirResult.value;
     return Result.ok(
       removePinnedTopoSnapshot({
         dryRun: input.dryRun,

package/src/trails/topo-verify.ts

@@ -1,14 +1,27 @@
-import { trail } from '@ontrails/core';
+import { Result, trail } from '@ontrails/core';
 import { z } from 'zod';
 
-import { loadApp } from './load-app.js';
+import { tryLoadFreshAppLease } from './load-app.js';
+import { resolveTrailRootDir } from './root-dir.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 });
+    const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
+    if (rootDirResult.isErr()) {
+      return Result.err(rootDirResult.error);
+    }
+    const rootDir = rootDirResult.value;
+    const leaseResult = await tryLoadFreshAppLease(input.module, rootDir);
+    if (leaseResult.isErr()) {
+      return Result.err(leaseResult.error);
+    }
+    const lease = leaseResult.value;
+    try {
+      return await verifyCurrentTopo(lease.app, { rootDir });
+    } finally {
+      lease.release();
+    }
   },
   description: 'Verify that the committed lockfile matches the current topo',
   input: z.object({

package/src/trails/topo.ts

@@ -1,8 +1,11 @@
 import { Result, trail } from '@ontrails/core';
 import { z } from 'zod';
 
-import { loadApp } from './load-app.js';
+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({
@@ -22,26 +25,48 @@ const summaryOutput = z.object({
   }),
   dbPath: z.string(),
   list: z.object({
+    activation: activationOverviewOutput,
     count: z.number(),
-    entries: z.array(
-      z.object({
-        examples: z.number(),
-        id: z.string(),
-        kind: z.string(),
-        safety: z.string(),
-      })
-    ),
+    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()),
-      })
-    ),
+    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(),
@@ -49,14 +74,26 @@ const summaryOutput = z.object({
 
 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 }));
+    const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
+    if (rootDirResult.isErr()) {
+      return Result.err(rootDirResult.error);
+    }
+    const rootDir = rootDirResult.value;
+    const leaseResult = await tryLoadFreshAppLease(input.module, rootDir);
+    if (leaseResult.isErr()) {
+      return Result.err(leaseResult.error);
+    }
+    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: {},
+      input: createIsolatedExampleInput('topo-summary'),
       name: 'Show the current topo summary',
     },
   ],

package/src/trails/warden-guide.ts

@@ -0,0 +1,121 @@
+import type { FieldOverride } from '@ontrails/core';
+import { Result, trail } from '@ontrails/core';
+import {
+  buildWardenGuideManifest,
+  formatWardenGuide,
+  wardenDepthValues,
+  wardenGuideFormatValues,
+  wardenRuleConcerns,
+  wardenRuleLifecycleStates,
+  wardenRuleScopes,
+  wardenRuleTiers,
+} from '@ontrails/warden';
+import { z } from 'zod';
+
+const wardenGuidanceLinkSchema = z.object({
+  label: z.string(),
+  path: z.string().optional(),
+  url: z.string().optional(),
+});
+
+const wardenGuidanceSchema = z.object({
+  commands: z.array(z.string()).readonly().optional(),
+  docs: z.array(wardenGuidanceLinkSchema).readonly().optional(),
+  relatedRules: z.array(z.string()).readonly().optional(),
+  steps: z.array(z.string()).readonly().optional(),
+  summary: z.string(),
+});
+
+const wardenRuleGuideEntrySchema = z.object({
+  concern: z.enum(wardenRuleConcerns),
+  depth: z.enum(wardenDepthValues),
+  description: z.string(),
+  docs: z.array(wardenGuidanceLinkSchema).readonly(),
+  guidance: wardenGuidanceSchema.optional(),
+  id: z.string(),
+  invariant: z.string(),
+  lifecycle: z.object({
+    retireWhen: z.string().optional(),
+    state: z.enum(wardenRuleLifecycleStates),
+  }),
+  scope: z.enum(wardenRuleScopes),
+  severity: z.enum(['error', 'warn']),
+  tier: z.enum(wardenRuleTiers),
+});
+
+const wardenGuideManifestSchema = z.object({
+  generatedFrom: z.object({
+    package: z.literal('@ontrails/warden'),
+    registries: z.tuple([
+      z.literal('wardenRules'),
+      z.literal('wardenTopoRules'),
+    ]),
+    source: z.literal('builtin-rule-metadata'),
+  }),
+  kind: z.literal('trails-warden-guide-manifest'),
+  ruleCount: z.number(),
+  rules: z.array(wardenRuleGuideEntrySchema).readonly(),
+  version: z.literal(1),
+});
+
+const wardenGuideInputSchema = z.object({
+  guideFormat: z
+    .enum(wardenGuideFormatValues)
+    .default('markdown')
+    .describe('Guide output format'),
+});
+
+const wardenGuideFields = {
+  guideFormat: {
+    aliases: true,
+    options: [
+      {
+        hint: 'Human-readable Warden guide',
+        label: 'Markdown',
+        value: 'markdown',
+      },
+      {
+        hint: 'Compact guidance for agent context',
+        label: 'Agent JSON',
+        value: 'agent-json',
+      },
+      {
+        hint: 'Full structured rule manifest',
+        label: 'Manifest',
+        value: 'manifest',
+      },
+    ],
+  },
+} satisfies Readonly<
+  Record<'guideFormat', FieldOverride & { readonly aliases: true }>
+>;
+
+export const wardenGuideTrail = trail('warden.guide', {
+  blaze: (input) => {
+    const manifest = buildWardenGuideManifest();
+    return Result.ok({
+      format: input.guideFormat,
+      formatted: formatWardenGuide(manifest, input.guideFormat),
+      manifest,
+    });
+  },
+  description: 'Project Warden rule guidance as markdown or JSON',
+  examples: [
+    {
+      input: { guideFormat: 'markdown' },
+      name: 'Markdown guide',
+    },
+    {
+      input: { guideFormat: 'agent-json' },
+      name: 'Agent JSON guide',
+    },
+  ],
+  fields: wardenGuideFields,
+  input: wardenGuideInputSchema,
+  intent: 'read',
+  output: z.object({
+    format: z.enum(wardenGuideFormatValues),
+    formatted: z.string(),
+    manifest: wardenGuideManifestSchema,
+  }),
+});