@ontrails/trails 1.0.0-beta.14 → 1.0.0-beta.16

package/src/trails/topo.ts

@@ -1,9 +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 { DEFAULT_APP_MODULE } from './topo-support.js';
+import { createIsolatedExampleInput } from './topo-support.js';
 
 const summaryOutput = z.object({
   app: z.object({
@@ -12,37 +14,59 @@ const summaryOutput = z.object({
       detours: z.boolean(),
       examples: z.boolean(),
       outputSchemas: z.boolean(),
-      provisions: z.boolean(),
+      resources: z.boolean(),
       signals: z.boolean(),
     }),
     name: z.string(),
-    provisions: z.number(),
+    resources: z.number(),
     signals: z.number(),
     trails: z.number(),
     version: z.string(),
   }),
   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(),
-      })
-    ),
-    provisionCount: z.number(),
-    provisions: z.array(
-      z.object({
-        description: z.string().nullable(),
-        health: z.enum(['available', 'none']),
-        id: z.string(),
-        kind: z.literal('provision'),
-        lifetime: z.literal('singleton'),
-        usedBy: z.array(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()).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(),
@@ -50,22 +74,31 @@ 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',
     },
   ],
   input: z.object({
-    module: z
-      .string()
-      .default(DEFAULT_APP_MODULE)
-      .describe('Path to the app module'),
+    module: z.string().optional().describe('Path to the app module'),
     rootDir: z.string().optional().describe('Workspace root directory'),
   }),
   intent: 'read',

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,
+  }),
+});

package/src/trails/warden.ts

@@ -1,54 +1,159 @@
 /**
  * `warden` trail -- Governance checks.
  *
- * Thin wrapper around `runWarden` and `formatWardenReport` from @ontrails/warden.
+ * Thin wrapper around the shared @ontrails/warden command surface.
  */
 
 import { Result, trail } from '@ontrails/core';
 import {
-  formatGitHubAnnotations,
-  formatJson,
-  formatSummary,
-  formatWardenReport,
-  runWarden,
+  diagnosticSchema,
+  runWardenCommand,
+  wardenDepthValues,
+  wardenDraftsValues,
+  wardenFailOnValues,
+  wardenFormatValues,
+  wardenLockValues,
 } from '@ontrails/warden';
 import { z } from 'zod';
 
-import { loadApp } from './load-app.js';
+import { resolveTrailRootDir } from './root-dir.js';
 
 // ---------------------------------------------------------------------------
 // Trail definition
 // ---------------------------------------------------------------------------
 
+const wardenInputSchema = z.object({
+  apps: z
+    .array(z.string())
+    .optional()
+    .describe('App names or module paths to govern'),
+  cached: z.boolean().default(false).describe('Alias for --lock cached'),
+  ci: z.boolean().default(false).describe('Use the CI Warden preset'),
+  configPath: z.string().optional().describe('Path to trails.config.ts'),
+  depth: z
+    .enum(wardenDepthValues)
+    .optional()
+    .describe('Cumulative analysis depth'),
+  drafts: z.enum(wardenDraftsValues).optional().describe('Draft state mode'),
+  excludeDrafts: z
+    .boolean()
+    .default(false)
+    .describe('Alias for --drafts exclude'),
+  failOn: z.enum(wardenFailOnValues).optional().describe('Failure threshold'),
+  format: z.enum(wardenFormatValues).optional().describe('Output format'),
+  github: z.boolean().default(false).describe('Alias for --format github'),
+  includeDrafts: z
+    .boolean()
+    .default(false)
+    .describe('Alias for --drafts include'),
+  json: z.boolean().default(false).describe('Alias for --format json'),
+  lock: z.enum(wardenLockValues).optional().describe('Lockfile mode'),
+  noLockMutation: z
+    .boolean()
+    .default(false)
+    .describe('Suppress lockfile mutation'),
+  onlyDrafts: z.boolean().default(false).describe('Alias for --drafts only'),
+  prePush: z.boolean().default(false).describe('Use the pre-push preset'),
+  refresh: z.boolean().default(false).describe('Alias for --lock refresh'),
+  rootDir: z.string().optional().describe('Root directory to scan'),
+  skipLock: z.boolean().default(false).describe('Alias for --lock skip'),
+  strict: z.boolean().default(false).describe('Alias for --fail-on warning'),
+  summary: z.boolean().default(false).describe('Alias for --format summary'),
+});
+
+type WardenTrailInput = z.infer<typeof wardenInputSchema>;
+
+const pushFlag = (args: string[], condition: boolean, flag: string): void => {
+  if (condition) {
+    args.push(flag);
+  }
+};
+
+const pushValue = (
+  args: string[],
+  flag: string,
+  value: string | undefined
+): void => {
+  if (value !== undefined) {
+    args.push(flag, value);
+  }
+};
+
+const pushApps = (
+  args: string[],
+  apps: readonly string[] | undefined
+): void => {
+  if (apps !== undefined && apps.length > 0) {
+    args.push('--apps', apps.join(','));
+  }
+};
+
+export const buildWardenCommandArgs = (
+  input: WardenTrailInput
+): readonly string[] => {
+  const args: string[] = [];
+
+  pushFlag(args, input.prePush, '--pre-push');
+  pushFlag(args, input.ci, '--ci');
+  pushValue(args, '--depth', input.depth);
+  if (input.strict) {
+    args.push('--strict');
+  } else {
+    pushValue(args, '--fail-on', input.failOn);
+  }
+  if (input.github) {
+    args.push('--github');
+  } else if (input.json) {
+    args.push('--json');
+  } else if (input.summary) {
+    args.push('--summary');
+  } else {
+    pushValue(args, '--format', input.format);
+  }
+  if (input.skipLock) {
+    args.push('--skip-lock');
+  } else if (input.refresh) {
+    args.push('--refresh');
+  } else if (input.cached) {
+    args.push('--cached');
+  } else {
+    pushValue(args, '--lock', input.lock);
+  }
+  if (input.onlyDrafts) {
+    args.push('--only-drafts');
+  } else if (input.excludeDrafts) {
+    args.push('--exclude-drafts');
+  } else if (input.includeDrafts) {
+    args.push('--include-drafts');
+  } else {
+    pushValue(args, '--drafts', input.drafts);
+  }
+  pushFlag(args, input.noLockMutation, '--no-lock-mutation');
+  pushValue(args, '--config-path', input.configPath);
+  pushApps(args, input.apps);
+
+  return args;
+};
+
 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
-    );
-
-    const report = await runWarden({
-      driftOnly: input.driftOnly,
-      lintOnly: input.lintOnly,
-      rootDir,
-      topo,
+    const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
+    if (rootDirResult.isErr()) {
+      return Result.err(rootDirResult.error);
+    }
+    const rootDir = rootDirResult.value;
+    const result = await runWardenCommand({
+      args: buildWardenCommandArgs(input),
+      cwd: rootDir,
+      env: ctx.env ?? {},
     });
-
-    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);
+    const { report } = result;
 
     return Result.ok({
-      diagnostics: report.diagnostics,
+      diagnostics: [...report.diagnostics],
       drift: report.drift,
       errorCount: report.errorCount,
-      formatted,
+      formatted: result.output,
       passed: report.passed,
       warnCount: report.warnCount,
     });
@@ -57,8 +162,7 @@ export const wardenTrail = trail('warden', {
   examples: [
     {
       input: {
-        driftOnly: false,
-        lintOnly: false,
+        lock: 'skip',
       },
       name: 'Default warden run',
     },
@@ -69,25 +173,11 @@ export const wardenTrail = trail('warden', {
       name: 'GitHub Actions annotations',
     },
   ],
-  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'),
-  }),
+  input: wardenInputSchema,
   intent: 'read',
   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']),
-      })
+      diagnosticSchema.extend({ topoName: z.string().optional() })
     ),
     drift: z
       .object({

package/src/versions.ts

@@ -0,0 +1,28 @@
+import { scaffoldDependencyVersions } from './scaffold-versions.generated.js';
+
+interface PackageJson {
+  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 requireVersion = (value: string | undefined, label: string): string => {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(`Missing version for ${label}`);
+  }
+  return value;
+};
+
+export const trailsPackageVersion = requireVersion(
+  appPackageJson.version,
+  '@ontrails/trails'
+);
+
+export const ontrailsPackageRange = `^${trailsPackageVersion}`;
+
+export { scaffoldDependencyVersions };

package/.turbo/turbo-build.log

@@ -1 +0,0 @@
-$ tsc -b

package/.turbo/turbo-lint.log

@@ -1,3 +0,0 @@
-$ oxlint ./src
-Found 0 warnings and 0 errors.
-Finished in 16ms on 37 files with 93 rules using 24 threads.

package/.turbo/turbo-typecheck.log

@@ -1 +0,0 @@
-$ tsc --noEmit

package/__tests__/examples.test.ts

@@ -1,20 +0,0 @@
-/* oxlint-disable eslint-plugin-jest/require-hook -- testExamples registers tests at module scope */
-import { afterAll, beforeAll } from 'bun:test';
-import { rmSync } from 'node:fs';
-import { resolve } from 'node:path';
-
-import { testExamples } from '@ontrails/testing';
-
-import { app } from '../src/app.js';
-
-const trailsWorkspaceDir = resolve(import.meta.dir, '..', '.trails');
-
-beforeAll(() => {
-  rmSync(trailsWorkspaceDir, { force: true, recursive: true });
-});
-
-afterAll(() => {
-  rmSync(trailsWorkspaceDir, { force: true, recursive: true });
-});
-
-testExamples(app);

package/dist/bin/trails.d.ts

@@ -1,3 +0,0 @@
-#!/usr/bin/env bun
-import '../src/cli.js';
-//# sourceMappingURL=trails.d.ts.map

package/dist/bin/trails.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"trails.d.ts","sourceRoot":"","sources":["../../bin/trails.ts"],"names":[],"mappings":";AAEA,OAAO,eAAe,CAAC"}

package/dist/bin/trails.js

@@ -1,4 +0,0 @@
-#!/usr/bin/env bun
-/* oxlint-disable eslint-plugin-jest/require-hook -- CLI bin entrypoints execute at module scope */
-import '../src/cli.js';
-//# sourceMappingURL=trails.js.map

package/dist/bin/trails.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"trails.js","sourceRoot":"","sources":["../../bin/trails.ts"],"names":[],"mappings":";AACA,mGAAmG;AACnG,OAAO,eAAe,CAAC"}

package/dist/src/app.d.ts

@@ -1,2 +0,0 @@
-export declare const app: import("@ontrails/core").Topo;
-//# sourceMappingURL=app.d.ts.map

package/dist/src/app.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../src/app.ts"],"names":[],"mappings":"AAsBA,eAAO,MAAM,GAAG,+BAqBf,CAAC"}

package/dist/src/app.js

@@ -1,22 +0,0 @@
-import { topo } from '@ontrails/core';
-import * as addTrailhead from './trails/add-trailhead.js';
-import * as addTrail from './trails/add-trail.js';
-import * as addVerify from './trails/add-verify.js';
-import * as create from './trails/create.js';
-import * as createScaffold from './trails/create-scaffold.js';
-import * as devClean from './trails/dev-clean.js';
-import * as devReset from './trails/dev-reset.js';
-import * as devStats from './trails/dev-stats.js';
-import * as draftPromote from './trails/draft-promote.js';
-import * as guide from './trails/guide.js';
-import * as survey from './trails/survey.js';
-import * as topoExport from './trails/topo-export.js';
-import * as topoHistory from './trails/topo-history.js';
-import * as topoPin from './trails/topo-pin.js';
-import * as topoShow from './trails/topo-show.js';
-import * as topoCommand from './trails/topo.js';
-import * as topoUnpin from './trails/topo-unpin.js';
-import * as topoVerify from './trails/topo-verify.js';
-import * as warden from './trails/warden.js';
-export const app = topo('trails', survey, topoCommand, topoShow, topoHistory, topoPin, topoUnpin, topoExport, topoVerify, devStats, devClean, devReset, guide, draftPromote, warden, create, createScaffold, addTrailhead, addVerify, addTrail);
-//# sourceMappingURL=app.js.map

package/dist/src/app.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"app.js","sourceRoot":"","sources":["../../src/app.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAEtC,OAAO,KAAK,YAAY,MAAM,2BAA2B,CAAC;AAC1D,OAAO,KAAK,QAAQ,MAAM,uBAAuB,CAAC;AAClD,OAAO,KAAK,SAAS,MAAM,wBAAwB,CAAC;AACpD,OAAO,KAAK,MAAM,MAAM,oBAAoB,CAAC;AAC7C,OAAO,KAAK,cAAc,MAAM,6BAA6B,CAAC;AAC9D,OAAO,KAAK,QAAQ,MAAM,uBAAuB,CAAC;AAClD,OAAO,KAAK,QAAQ,MAAM,uBAAuB,CAAC;AAClD,OAAO,KAAK,QAAQ,MAAM,uBAAuB,CAAC;AAClD,OAAO,KAAK,YAAY,MAAM,2BAA2B,CAAC;AAC1D,OAAO,KAAK,KAAK,MAAM,mBAAmB,CAAC;AAC3C,OAAO,KAAK,MAAM,MAAM,oBAAoB,CAAC;AAC7C,OAAO,KAAK,UAAU,MAAM,yBAAyB,CAAC;AACtD,OAAO,KAAK,WAAW,MAAM,0BAA0B,CAAC;AACxD,OAAO,KAAK,OAAO,MAAM,sBAAsB,CAAC;AAChD,OAAO,KAAK,QAAQ,MAAM,uBAAuB,CAAC;AAClD,OAAO,KAAK,WAAW,MAAM,kBAAkB,CAAC;AAChD,OAAO,KAAK,SAAS,MAAM,wBAAwB,CAAC;AACpD,OAAO,KAAK,UAAU,MAAM,yBAAyB,CAAC;AACtD,OAAO,KAAK,MAAM,MAAM,oBAAoB,CAAC;AAE7C,MAAM,CAAC,MAAM,GAAG,GAAG,IAAI,CACrB,QAAQ,EACR,MAAM,EACN,WAAW,EACX,QAAQ,EACR,WAAW,EACX,OAAO,EACP,SAAS,EACT,UAAU,EACV,UAAU,EACV,QAAQ,EACR,QAAQ,EACR,QAAQ,EACR,KAAK,EACL,YAAY,EACZ,MAAM,EACN,MAAM,EACN,cAAc,EACd,YAAY,EACZ,SAAS,EACT,QAAQ,CACT,CAAC"}

package/dist/src/clack.d.ts

@@ -1,9 +0,0 @@
-/**
- * Clack-backed input resolver for the Trails CLI.
- *
- * This stays at the app gate so @ontrails/cli remains prompt-library agnostic.
- */
-import type { InputResolver } from '@ontrails/cli';
-/** Fill missing input by prompting with Clack when interactive. */
-export declare const resolveInputWithClack: InputResolver;
-//# sourceMappingURL=clack.d.ts.map

package/dist/src/clack.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"clack.d.ts","sourceRoot":"","sources":["../../src/clack.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAS,aAAa,EAAuB,MAAM,eAAe,CAAC;AAmF/E,mEAAmE;AACnE,eAAO,MAAM,qBAAqB,EAAE,aAoBnC,CAAC"}