@ontrails/trails 1.0.0-beta.1 → 1.0.0-beta.11

package/src/trails/survey.ts

@@ -10,6 +10,7 @@ import { Result, trail } from '@ontrails/core';
 import type { DiffResult } from '@ontrails/schema';
 import {
   diffSurfaceMaps,
+  generateOpenApiSpec,
   generateSurfaceMap,
   hashSurfaceMap,
   readSurfaceMap,
@@ -29,15 +30,46 @@ export interface BriefReport {
   readonly version: string;
   readonly contractVersion: string;
   readonly features: {
+    readonly services: boolean;
     readonly outputSchemas: boolean;
     readonly examples: boolean;
     readonly detours: boolean;
-    readonly hikes: boolean;
     readonly events: boolean;
   };
   readonly trails: number;
-  readonly hikes: number;
   readonly events: number;
+  readonly services: number;
+}
+
+export interface SurveyListReport {
+  readonly count: number;
+  readonly entries: readonly {
+    readonly examples: number;
+    readonly id: string;
+    readonly kind: string;
+    readonly safety: string;
+  }[];
+  readonly serviceCount: number;
+  readonly services: readonly {
+    readonly description: string | null;
+    readonly health: 'available' | 'none';
+    readonly id: string;
+    readonly kind: 'service';
+    readonly lifetime: 'singleton';
+    readonly usedBy: readonly string[];
+  }[];
+}
+
+export interface TrailDetailReport {
+  readonly description: string | null;
+  readonly detours: Trail<unknown, unknown>['detours'] | null;
+  readonly examples: readonly unknown[];
+  readonly follow: readonly string[];
+  readonly id: string;
+  readonly intent: 'read' | 'write' | 'destroy';
+  readonly kind: string;
+  readonly safety: string;
+  readonly services: readonly string[];
 }
 
 /** Check if a trail has a specific feature. */
@@ -51,7 +83,12 @@ const trailHas = (raw: Record<string, unknown>, key: string): boolean => {
 /** Detect which features are used across trails. */
 const detectFeatures = (
   app: Topo
-): { hasDetours: boolean; hasExamples: boolean; hasOutputSchemas: boolean } => {
+): {
+  hasDetours: boolean;
+  hasExamples: boolean;
+  hasOutputSchemas: boolean;
+  hasServices: boolean;
+} => {
   const trails = [...app.trails.values()].map(
     (item) => item as unknown as Record<string, unknown>
   );
@@ -59,12 +96,17 @@ const detectFeatures = (
     hasDetours: trails.some((r) => trailHas(r, 'detours')),
     hasExamples: trails.some((r) => trailHas(r, 'examples')),
     hasOutputSchemas: trails.some((r) => trailHas(r, 'output')),
+    hasServices: trails.some(
+      (r) =>
+        Array.isArray(r['services']) && (r['services'] as unknown[]).length > 0
+    ),
   };
 };
 
 /** Generate a compact capability report for the given topo. */
 export const generateBriefReport = (app: Topo): BriefReport => {
-  const { hasDetours, hasExamples, hasOutputSchemas } = detectFeatures(app);
+  const { hasDetours, hasExamples, hasOutputSchemas, hasServices } =
+    detectFeatures(app);
 
   return {
     contractVersion: '2026-03',
@@ -73,11 +115,11 @@ export const generateBriefReport = (app: Topo): BriefReport => {
       detours: hasDetours,
       events: app.events.size > 0,
       examples: hasExamples,
-      hikes: app.hikes.size > 0,
       outputSchemas: hasOutputSchemas,
+      services: hasServices,
     },
-    hikes: app.hikes.size,
     name: app.name,
+    services: app.services.size,
     trails: app.trails.size,
     version: '0.1.0',
   };
@@ -88,23 +130,60 @@ export const generateBriefReport = (app: Topo): BriefReport => {
 // ---------------------------------------------------------------------------
 
 const safetyLabel = (entry: {
-  readOnly?: boolean;
-  destructive?: boolean;
+  intent?: 'read' | 'write' | 'destroy';
 }): string => {
-  if (entry.destructive) {
-    return 'destructive';
+  if (entry.intent === 'destroy') {
+    return 'destroy';
   }
-  if (entry.readOnly) {
-    return 'readOnly';
+  if (entry.intent === 'read') {
+    return 'read';
   }
   return '-';
 };
 
-const formatTrailList = (app: Topo): object => {
+const buildServiceUsage = (
+  app: Topo
+): ReadonlyMap<string, readonly string[]> => {
+  const usage = new Map<string, string[]>();
+
+  for (const trailDef of app.list()) {
+    for (const declaredService of trailDef.services) {
+      const users = usage.get(declaredService.id) ?? [];
+      users.push(trailDef.id);
+      usage.set(declaredService.id, users);
+    }
+  }
+
+  return new Map(
+    [...usage.entries()].map(([id, users]) => [id, users.toSorted()] as const)
+  );
+};
+
+const serviceHealthStatus = (service: {
+  health?: unknown;
+}): 'available' | 'none' =>
+  service.health === undefined ? 'none' : 'available';
+
+const formatServiceList = (app: Topo): SurveyListReport['services'] => {
+  const usage = buildServiceUsage(app);
+  return app
+    .listServices()
+    .map((service) => ({
+      description: service.description ?? null,
+      health: serviceHealthStatus(service),
+      id: service.id,
+      kind: service.kind,
+      lifetime: 'singleton' as const,
+      usedBy: usage.get(service.id) ?? [],
+    }))
+    .toSorted((a, b) => a.id.localeCompare(b.id));
+};
+
+export const generateSurveyList = (app: Topo): SurveyListReport => {
   const items = app.list();
   const entries = items.map((item) => {
     const safety = safetyLabel(
-      item as unknown as { readOnly?: boolean; destructive?: boolean }
+      item as unknown as { intent?: 'read' | 'write' | 'destroy' }
     );
     const examples = Array.isArray(
       (item as unknown as { examples?: unknown[] }).examples
@@ -120,7 +199,14 @@ const formatTrailList = (app: Topo): object => {
     };
   });
 
-  return { count: items.length, entries };
+  const services = formatServiceList(app);
+
+  return {
+    count: items.length,
+    entries,
+    serviceCount: services.length,
+    services,
+  };
 };
 
 /**
@@ -130,18 +216,37 @@ const formatTrailList = (app: Topo): object => {
  * surface-map entry. The two serve different audiences (human display vs
  * machine-diffable surface map) so they are kept separate.
  */
-const formatTrailDetail = (item: Trail<unknown, unknown>): object => {
+export const generateTrailDetail = (
+  item: Trail<unknown, unknown>
+): TrailDetailReport => {
   const safety = safetyLabel(
-    item as unknown as { readOnly?: boolean; destructive?: boolean }
+    item as unknown as { intent?: 'read' | 'write' | 'destroy' }
   );
 
   return {
     description: item.description ?? null,
     detours: item.detours ?? null,
     examples: item.examples ?? [],
+    follow: item.follow.toSorted(),
     id: item.id,
+    intent: item.intent,
     kind: item.kind,
     safety,
+    services: item.services.map((service) => service.id).toSorted(),
+  };
+};
+
+const formatServiceDetail = (app: Topo, serviceId: string): object => {
+  const item = app.getService(serviceId);
+  const usedBy = buildServiceUsage(app).get(serviceId) ?? [];
+
+  return {
+    description: item?.description ?? null,
+    health: item ? serviceHealthStatus(item) : 'none',
+    id: serviceId,
+    kind: 'service',
+    lifetime: 'singleton',
+    usedBy,
   };
 };
 
@@ -184,10 +289,13 @@ const buildSurveyDetail = (
   trailId: string
 ): Result<object, Error> => {
   const item = app.get(trailId);
-  if (!item) {
-    return Result.err(new Error(`Trail not found: ${trailId}`));
+  if (item) {
+    return Result.ok(generateTrailDetail(item as Trail<unknown, unknown>));
+  }
+  if (app.getService(trailId)) {
+    return Result.ok(formatServiceDetail(app, trailId));
   }
-  return Result.ok(formatTrailDetail(item as Trail<unknown, unknown>));
+  return Result.err(new Error(`Trail or service not found: ${trailId}`));
 };
 
 const buildSurveyGenerate = async (
@@ -200,6 +308,55 @@ const buildSurveyGenerate = async (
   return Result.ok({ hash, lockPath, mapPath });
 };
 
+interface SurveyInput {
+  breakingOnly: boolean;
+  brief: boolean;
+  diff?: string | undefined;
+  generate: boolean;
+  openapi: boolean;
+  trailId?: string | undefined;
+}
+
+type SurveyMode = 'brief' | 'detail' | 'diff' | 'generate' | 'list' | 'openapi';
+
+/** Ordered mode checks — first truthy predicate wins, otherwise 'list'. */
+const modeChecks: readonly [(input: SurveyInput) => boolean, SurveyMode][] = [
+  [(i) => i.brief, 'brief'],
+  [(i) => Boolean(i.diff), 'diff'],
+  [(i) => Boolean(i.trailId), 'detail'],
+  [(i) => i.generate, 'generate'],
+  [(i) => i.openapi, 'openapi'],
+];
+
+/** Determine which survey mode was requested, falling back to 'list'. */
+const resolveSurveyMode = (input: SurveyInput): SurveyMode =>
+  modeChecks.find(([predicate]) => predicate(input))?.[1] ?? 'list';
+
+type SurveyHandler = (
+  app: Topo,
+  input: SurveyInput
+) => Result<object, Error> | Promise<Result<object, Error>>;
+
+/** Handlers keyed by survey mode. */
+const surveyHandlers: Record<SurveyMode, SurveyHandler> = {
+  brief: (app) => Result.ok(generateBriefReport(app)),
+  detail: (app, input) => buildSurveyDetail(app, input.trailId ?? ''),
+  diff: (app, input) => buildSurveyDiff(app, input.breakingOnly),
+  generate: (app) => buildSurveyGenerate(app),
+  list: (app) => Result.ok(generateSurveyList(app)),
+  openapi: (app) => Result.ok(generateOpenApiSpec(app)),
+};
+
+/** Dispatch to the appropriate survey sub-command based on input flags. */
+const dispatchSurvey = (
+  app: Topo,
+  input: SurveyInput
+): Result<object, Error> | Promise<Result<object, Error>> => {
+  const mode = resolveSurveyMode(input);
+  const handler = surveyHandlers[mode];
+  return handler(app, input);
+};
+
 // ---------------------------------------------------------------------------
 // Trail definition
 // ---------------------------------------------------------------------------
@@ -217,28 +374,12 @@ export const surveyTrail = trail('survey', {
       input: { brief: true },
       name: 'Brief capability report',
     },
+    {
+      description: 'Generate an OpenAPI 3.1 specification for the topo',
+      input: { openapi: true },
+      name: 'OpenAPI spec',
+    },
   ],
-  implementation: async (input, ctx) => {
-    const app = await loadApp(input.module, ctx.cwd ?? '.');
-
-    if (input.brief) {
-      return Result.ok(generateBriefReport(app));
-    }
-
-    if (input.diff) {
-      return await buildSurveyDiff(app, input.breakingOnly);
-    }
-
-    if (input.trailId) {
-      return buildSurveyDetail(app, input.trailId);
-    }
-
-    if (input.generate) {
-      return await buildSurveyGenerate(app);
-    }
-
-    return Result.ok(formatTrailList(app));
-  },
   input: z.object({
     breakingOnly: z
       .boolean()
@@ -254,8 +395,10 @@ export const surveyTrail = trail('survey', {
       .string()
       .default('./src/app.ts')
       .describe('Path to the app module'),
+    openapi: z.boolean().default(false).describe('Output OpenAPI 3.1 spec'),
     trailId: z.string().optional().describe('Trail ID for detail view'),
   }),
+  intent: 'read',
   output: z.union([
     z.object({
       count: z.number(),
@@ -267,6 +410,17 @@ export const surveyTrail = trail('survey', {
           safety: z.string(),
         })
       ),
+      serviceCount: z.number(),
+      services: z.array(
+        z.object({
+          description: z.string().nullable(),
+          health: z.enum(['available', 'none']),
+          id: z.string(),
+          kind: z.literal('service'),
+          lifetime: z.literal('singleton'),
+          usedBy: z.array(z.string()),
+        })
+      ),
     }),
     z.object({
       contractVersion: z.string(),
@@ -275,11 +429,11 @@ export const surveyTrail = trail('survey', {
         detours: z.boolean(),
         events: z.boolean(),
         examples: z.boolean(),
-        hikes: z.boolean(),
         outputSchemas: z.boolean(),
+        services: z.boolean(),
       }),
-      hikes: z.number(),
       name: z.string(),
+      services: z.number(),
       trails: z.number(),
       version: z.string(),
     }),
@@ -293,15 +447,49 @@ export const surveyTrail = trail('survey', {
       description: z.unknown().nullable(),
       detours: z.unknown().nullable(),
       examples: z.array(z.unknown()),
+      follow: z.array(z.string()),
       id: z.string(),
+      intent: z.enum(['read', 'write', 'destroy']),
       kind: z.string(),
       safety: z.string(),
+      services: z.array(z.string()),
+    }),
+    z.object({
+      description: z.string().nullable(),
+      health: z.enum(['available', 'none']),
+      id: z.string(),
+      kind: z.literal('service'),
+      lifetime: z.literal('singleton'),
+      usedBy: z.array(z.string()),
     }),
     z.object({
       hash: z.string(),
       lockPath: z.string(),
       mapPath: z.string(),
     }),
+    z.object({
+      components: z.object({
+        schemas: z.record(z.string(), z.unknown()),
+      }),
+      info: z.object({
+        description: z.string().optional(),
+        title: z.string(),
+        version: z.string(),
+      }),
+      openapi: z.literal('3.1.0'),
+      paths: z.record(z.string(), z.record(z.string(), z.unknown())),
+      servers: z
+        .array(
+          z.object({
+            description: z.string().optional(),
+            url: z.string(),
+          })
+        )
+        .optional(),
+    }),
   ]),
-  readOnly: true,
+  run: async (input, ctx) => {
+    const app = await loadApp(input.module, ctx.cwd ?? '.');
+    return dispatchSurvey(app, input);
+  },
 });

package/src/trails/warden.ts

@@ -37,38 +37,6 @@ export const wardenTrail = trail('warden', {
       name: 'GitHub Actions annotations',
     },
   ],
-  implementation: 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
-    );
-
-    const report = await runWarden({
-      driftOnly: input.driftOnly,
-      lintOnly: input.lintOnly,
-      rootDir,
-      topo,
-    });
-
-    const formatters: Record<string, (r: typeof report) => string> = {
-      github: formatGitHubAnnotations,
-      json: formatJson,
-      summary: formatSummary,
-      text: formatWardenReport,
-    };
-    const formatter = formatters[input.format] ?? formatWardenReport;
-    const formatted = formatter(report);
-
-    return Result.ok({
-      diagnostics: report.diagnostics,
-      drift: report.drift,
-      errorCount: report.errorCount,
-      formatted,
-      passed: report.passed,
-      warnCount: report.warnCount,
-    });
-  },
   input: z.object({
     driftOnly: z.boolean().default(false).describe('Only run drift detection'),
     format: z
@@ -78,6 +46,7 @@ export const wardenTrail = trail('warden', {
     lintOnly: z.boolean().default(false).describe('Only run lint rules'),
     rootDir: z.string().optional().describe('Root directory to scan'),
   }),
+  intent: 'read',
   output: z.object({
     diagnostics: z.array(
       z.object({
@@ -100,5 +69,36 @@ export const wardenTrail = trail('warden', {
     passed: z.boolean(),
     warnCount: z.number(),
   }),
-  readOnly: true,
+  run: 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
+    );
+
+    const report = await runWarden({
+      driftOnly: input.driftOnly,
+      lintOnly: input.lintOnly,
+      rootDir,
+      topo,
+    });
+
+    const formatters: Record<string, (r: typeof report) => string> = {
+      github: formatGitHubAnnotations,
+      json: formatJson,
+      summary: formatSummary,
+      text: formatWardenReport,
+    };
+    const formatter = formatters[input.format] ?? formatWardenReport;
+    const formatted = formatter(report);
+
+    return Result.ok({
+      diagnostics: report.diagnostics,
+      drift: report.drift,
+      errorCount: report.errorCount,
+      formatted,
+      passed: report.passed,
+      warnCount: report.warnCount,
+    });
+  },
 });