@ontrails/trails 1.0.0-beta.0

package/dist/src/trails/survey.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `survey` trail -- Full topo introspection.
+ *
+ * Lists trails, shows detail for individual trails, generates surface maps,
+ * and diffs against previous versions.
+ */
+import type { Topo, Trail } from '@ontrails/core';
+export interface BriefReport {
+    readonly name: string;
+    readonly version: string;
+    readonly contractVersion: string;
+    readonly features: {
+        readonly outputSchemas: boolean;
+        readonly examples: boolean;
+        readonly detours: boolean;
+        readonly hikes: boolean;
+        readonly events: boolean;
+    };
+    readonly trails: number;
+    readonly hikes: number;
+    readonly events: number;
+}
+/** Generate a compact capability report for the given topo. */
+export declare const generateBriefReport: (app: Topo) => BriefReport;
+export declare const surveyTrail: Trail<{
+    breakingOnly: boolean;
+    brief: boolean;
+    generate: boolean;
+    module: string;
+    diff?: string | undefined;
+    trailId?: string | undefined;
+}, object>;
+//# sourceMappingURL=survey.d.ts.map

package/dist/src/trails/survey.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"survey.d.ts","sourceRoot":"","sources":["../../../src/trails/survey.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAmBlD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE;QACjB,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;QAChC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;QAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;QAC1B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;QACxB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;KAC1B,CAAC;IACF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAwBD,+DAA+D;AAC/D,eAAO,MAAM,mBAAmB,GAAI,KAAK,IAAI,KAAG,WAkB/C,CAAC;AA2HF,eAAO,MAAM,WAAW;;;;;;;UAoGtB,CAAC"}

package/dist/src/trails/survey.js

@@ -0,0 +1,225 @@
+/**
+ * `survey` trail -- Full topo introspection.
+ *
+ * Lists trails, shows detail for individual trails, generates surface maps,
+ * and diffs against previous versions.
+ */
+import { Result, trail } from '@ontrails/core';
+import { diffSurfaceMaps, generateSurfaceMap, hashSurfaceMap, readSurfaceMap, writeSurfaceLock, writeSurfaceMap, } from '@ontrails/schema';
+import { z } from 'zod';
+import { loadApp } from './load-app.js';
+/** Check if a trail has a specific feature. */
+const trailHas = (raw, key) => {
+    if (key === 'examples') {
+        return Array.isArray(raw[key]) && raw[key].length > 0;
+    }
+    return Boolean(raw[key]);
+};
+/** Detect which features are used across trails. */
+const detectFeatures = (app) => {
+    const trails = [...app.trails.values()].map((item) => item);
+    return {
+        hasDetours: trails.some((r) => trailHas(r, 'detours')),
+        hasExamples: trails.some((r) => trailHas(r, 'examples')),
+        hasOutputSchemas: trails.some((r) => trailHas(r, 'output')),
+    };
+};
+/** Generate a compact capability report for the given topo. */
+export const generateBriefReport = (app) => {
+    const { hasDetours, hasExamples, hasOutputSchemas } = detectFeatures(app);
+    return {
+        contractVersion: '2026-03',
+        events: app.events.size,
+        features: {
+            detours: hasDetours,
+            events: app.events.size > 0,
+            examples: hasExamples,
+            hikes: app.hikes.size > 0,
+            outputSchemas: hasOutputSchemas,
+        },
+        hikes: app.hikes.size,
+        name: app.name,
+        trails: app.trails.size,
+        version: '0.1.0',
+    };
+};
+// ---------------------------------------------------------------------------
+// Formatting helpers
+// ---------------------------------------------------------------------------
+const safetyLabel = (entry) => {
+    if (entry.destructive) {
+        return 'destructive';
+    }
+    if (entry.readOnly) {
+        return 'readOnly';
+    }
+    return '-';
+};
+const formatTrailList = (app) => {
+    const items = app.list();
+    const entries = items.map((item) => {
+        const safety = safetyLabel(item);
+        const examples = Array.isArray(item.examples)
+            ? item.examples.length
+            : 0;
+        return {
+            examples,
+            id: item.id,
+            kind: item.kind,
+            safety,
+        };
+    });
+    return { count: items.length, entries };
+};
+/**
+ * Build a human-readable detail view for a single trail.
+ *
+ * Overlaps with `trailToEntry` in `@ontrails/schema` which builds the
+ * surface-map entry. The two serve different audiences (human display vs
+ * machine-diffable surface map) so they are kept separate.
+ */
+const formatTrailDetail = (item) => {
+    const safety = safetyLabel(item);
+    return {
+        description: item.description ?? null,
+        detours: item.detours ?? null,
+        examples: item.examples ?? [],
+        id: item.id,
+        kind: item.kind,
+        safety,
+    };
+};
+const formatDiff = (diff) => ({
+    breaking: diff.breaking,
+    hasBreaking: diff.hasBreaking,
+    info: diff.info,
+    warnings: diff.warnings,
+});
+const buildSurveyDiff = async (app, breakingOnly) => {
+    const currentMap = generateSurfaceMap(app);
+    const previousMap = await readSurfaceMap();
+    if (!previousMap) {
+        return Result.err(new Error('No previous surface map found. Run `trails survey generate` first.'));
+    }
+    const diff = diffSurfaceMaps(previousMap, currentMap);
+    return Result.ok(breakingOnly
+        ? formatDiff({
+            ...diff,
+            entries: diff.breaking,
+            info: [],
+            warnings: [],
+        })
+        : formatDiff(diff));
+};
+const buildSurveyDetail = (app, trailId) => {
+    const item = app.get(trailId);
+    if (!item) {
+        return Result.err(new Error(`Trail not found: ${trailId}`));
+    }
+    return Result.ok(formatTrailDetail(item));
+};
+const buildSurveyGenerate = async (app) => {
+    const surfaceMap = generateSurfaceMap(app);
+    const mapPath = await writeSurfaceMap(surfaceMap);
+    const hash = hashSurfaceMap(surfaceMap);
+    const lockPath = await writeSurfaceLock(hash);
+    return Result.ok({ hash, lockPath, mapPath });
+};
+// ---------------------------------------------------------------------------
+// Trail definition
+// ---------------------------------------------------------------------------
+export const surveyTrail = trail('survey', {
+    description: 'Full topo introspection',
+    examples: [
+        {
+            description: 'Lists all registered trails with safety and surface info',
+            input: {},
+            name: 'List all trails',
+        },
+        {
+            description: 'Quick capability summary with counts and feature flags',
+            input: { brief: true },
+            name: 'Brief capability report',
+        },
+    ],
+    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()
+            .default(false)
+            .describe('Only show breaking changes'),
+        brief: z.boolean().default(false).describe('Quick capability summary'),
+        diff: z.string().optional().describe('Diff against a git ref'),
+        generate: z
+            .boolean()
+            .default(false)
+            .describe('Generate surface map and lock file'),
+        module: z
+            .string()
+            .default('./src/app.ts')
+            .describe('Path to the app module'),
+        trailId: z.string().optional().describe('Trail ID for detail view'),
+    }),
+    output: z.union([
+        z.object({
+            count: z.number(),
+            entries: z.array(z.object({
+                examples: z.number(),
+                id: z.string(),
+                kind: z.string(),
+                safety: z.string(),
+            })),
+        }),
+        z.object({
+            contractVersion: z.string(),
+            events: z.number(),
+            features: z.object({
+                detours: z.boolean(),
+                events: z.boolean(),
+                examples: z.boolean(),
+                hikes: z.boolean(),
+                outputSchemas: z.boolean(),
+            }),
+            hikes: z.number(),
+            name: z.string(),
+            trails: z.number(),
+            version: z.string(),
+        }),
+        z.object({
+            breaking: z.array(z.unknown()),
+            hasBreaking: z.boolean(),
+            info: z.array(z.unknown()),
+            warnings: z.array(z.unknown()),
+        }),
+        z.object({
+            description: z.unknown().nullable(),
+            detours: z.unknown().nullable(),
+            examples: z.array(z.unknown()),
+            id: z.string(),
+            kind: z.string(),
+            safety: z.string(),
+        }),
+        z.object({
+            hash: z.string(),
+            lockPath: z.string(),
+            mapPath: z.string(),
+        }),
+    ]),
+    readOnly: true,
+});
+//# sourceMappingURL=survey.js.map

package/dist/src/trails/survey.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"survey.js","sourceRoot":"","sources":["../../../src/trails/survey.ts"],"names":[],"mappings":"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"}

package/dist/src/trails/warden.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `warden` trail -- Governance checks.
+ *
+ * Thin wrapper around `runWarden` and `formatWardenReport` from @ontrails/warden.
+ */
+export declare const wardenTrail: import("@ontrails/core").Trail<{
+    driftOnly: boolean;
+    format: "text" | "github" | "json" | "summary";
+    lintOnly: boolean;
+    rootDir?: string | undefined;
+}, {
+    diagnostics: readonly import("@ontrails/warden").WardenDiagnostic[];
+    drift: import("@ontrails/warden").DriftResult | null;
+    errorCount: number;
+    formatted: string;
+    passed: boolean;
+    warnCount: number;
+}>;
+//# sourceMappingURL=warden.d.ts.map

package/dist/src/trails/warden.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"warden.d.ts","sourceRoot":"","sources":["../../../src/trails/warden.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAkBH,eAAO,MAAM,WAAW;;;;;;;;;;;;EAiFtB,CAAC"}

package/dist/src/trails/warden.js

@@ -0,0 +1,88 @@
+/**
+ * `warden` trail -- Governance checks.
+ *
+ * Thin wrapper around `runWarden` and `formatWardenReport` from @ontrails/warden.
+ */
+import { Result, trail } from '@ontrails/core';
+import { formatGitHubAnnotations, formatJson, formatSummary, formatWardenReport, runWarden, } from '@ontrails/warden';
+import { z } from 'zod';
+import { loadApp } from './load-app.js';
+// ---------------------------------------------------------------------------
+// Trail definition
+// ---------------------------------------------------------------------------
+export const wardenTrail = trail('warden', {
+    description: 'Run governance checks (lint + drift)',
+    examples: [
+        {
+            input: {
+                driftOnly: false,
+                lintOnly: false,
+            },
+            name: 'Default warden run',
+        },
+        {
+            input: {
+                format: 'github',
+            },
+            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);
+        const report = await runWarden({
+            driftOnly: input.driftOnly,
+            lintOnly: input.lintOnly,
+            rootDir,
+            topo,
+        });
+        const formatters = {
+            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
+            .enum(['text', 'json', 'github', 'summary'])
+            .default('text')
+            .describe('Output format: text, json, github, or summary'),
+        lintOnly: z.boolean().default(false).describe('Only run lint rules'),
+        rootDir: z.string().optional().describe('Root directory to scan'),
+    }),
+    output: z.object({
+        diagnostics: z.array(z.object({
+            filePath: z.string(),
+            line: z.number(),
+            message: z.string(),
+            rule: z.string(),
+            severity: z.enum(['error', 'warn']),
+        })),
+        drift: z
+            .object({
+            committedHash: z.string().nullable(),
+            currentHash: z.string(),
+            stale: z.boolean(),
+        })
+            .nullable(),
+        errorCount: z.number(),
+        formatted: z.string(),
+        passed: z.boolean(),
+        warnCount: z.number(),
+    }),
+    readOnly: true,
+});
+//# sourceMappingURL=warden.js.map

package/dist/src/trails/warden.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"warden.js","sourceRoot":"","sources":["../../../src/trails/warden.ts"],"names":[],"mappings":"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"}

package/dist/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["../src/app.ts","../src/clack.ts","../src/cli.ts","../src/trails/add-surface.ts","../src/trails/add-trail.ts","../src/trails/add-verify.ts","../src/trails/create-scaffold.ts","../src/trails/create.ts","../src/trails/guide.ts","../src/trails/load-app.ts","../src/trails/project.ts","../src/trails/survey.ts","../src/trails/warden.ts","../bin/trails.ts"],"version":"5.9.3"}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@ontrails/trails",
+  "version": "1.0.0-beta.0",
+  "bin": {
+    "trails": "./bin/trails.ts"
+  },
+  "type": "module",
+  "scripts": {
+    "build": "tsc -b",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint ./src",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.1.0",
+    "@ontrails/cli": "workspace:*",
+    "@ontrails/core": "workspace:*",
+    "@ontrails/logging": "workspace:*",
+    "@ontrails/schema": "workspace:*",
+    "@ontrails/warden": "workspace:*",
+    "commander": "catalog:",
+    "zod": "catalog:"
+  },
+  "devDependencies": {
+    "@ontrails/testing": "workspace:*"
+  }
+}