@ontrails/trails 1.0.0-beta.19 → 1.0.0-beta.21

package/src/release/wayfinder-dogfood-smoke.ts

@@ -0,0 +1,226 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+const repoRoot = resolve(process.cwd());
+const trailsBin = join(repoRoot, 'apps/trails/bin/trails.ts');
+
+type JsonObject = Record<string, unknown>;
+
+export interface WayfinderDogfoodSmokeResult {
+  readonly check: 'wayfinder-dogfood';
+  readonly message: string;
+  readonly passed: true;
+  readonly trailCount: number;
+}
+
+const assertObject = (value: unknown, label: string): JsonObject => {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new Error(`${label} did not return a JSON object`);
+  }
+  return value as JsonObject;
+};
+
+const assertFreshSource = (value: JsonObject, label: string): void => {
+  const freshness = assertObject(value['freshness'], `${label}.freshness`);
+  if (freshness['status'] !== 'fresh') {
+    throw new Error(`${label} did not read fresh artifacts`);
+  }
+  const source = assertObject(value['source'], `${label}.source`);
+  if (source['kind'] !== 'topoGraph') {
+    throw new Error(`${label} did not read the TopoGraph source`);
+  }
+};
+
+const parseJson = (stdout: string, label: string): JsonObject => {
+  try {
+    return assertObject(JSON.parse(stdout) as unknown, label);
+  } catch (error) {
+    throw new Error(`${label} did not produce valid JSON`, { cause: error });
+  }
+};
+
+const runWayfind = (tempRoot: string, args: readonly string[]): JsonObject => {
+  const command = [
+    process.execPath,
+    trailsBin,
+    'wayfind',
+    ...args,
+    '--root-dir',
+    tempRoot,
+    '--json',
+  ];
+  const result = Bun.spawnSync({
+    cmd: command,
+    cwd: repoRoot,
+    env: { ...process.env, NO_COLOR: '1' } as Record<
+      string,
+      string | undefined
+    >,
+    stderr: 'pipe',
+    stdout: 'pipe',
+  });
+  const stdout = result.stdout.toString();
+  const stderr = result.stderr.toString();
+  if (result.exitCode !== 0) {
+    throw new Error(
+      [
+        `Wayfinder dogfood command failed: ${command.join(' ')}`,
+        `exitCode: ${result.exitCode}`,
+        `stdout: ${stdout}`,
+        `stderr: ${stderr}`,
+      ].join('\n')
+    );
+  }
+  return parseJson(stdout, `trails ${args.join(' ')}`);
+};
+
+const assertSearchFindsWayfinder = (search: JsonObject): void => {
+  const { matches } = search;
+  if (!Array.isArray(matches)) {
+    throw new TypeError('wayfind search did not return matches');
+  }
+  const ids = matches
+    .map((match) => assertObject(match, 'wayfind search match')['id'])
+    .filter((id): id is string => typeof id === 'string');
+  if (!ids.includes('wayfind.search')) {
+    throw new Error('wayfind search did not find wayfind.search');
+  }
+};
+
+const assertErrorsFindWayfinder = (errorsResult: JsonObject): void => {
+  const { errors } = errorsResult;
+  if (!Array.isArray(errors)) {
+    throw new TypeError('wayfind errors did not return errors');
+  }
+  const searchEntry = errors
+    .map((entry) => assertObject(entry, 'wayfind errors entry'))
+    .find((entry) => entry['trailId'] === 'wayfind.search');
+  if (searchEntry === undefined) {
+    throw new Error('wayfind errors did not include wayfind.search');
+  }
+  const completeness = assertObject(
+    searchEntry['completeness'],
+    'wayfind errors completeness'
+  );
+  const emitted = assertObject(
+    completeness['emitted'],
+    'wayfind errors emitted completeness'
+  );
+  if (emitted['status'] !== 'unknown') {
+    throw new Error('wayfind errors overclaimed emitted-error completeness');
+  }
+};
+
+const assertAdaptersFindHono = (adaptersResult: JsonObject): void => {
+  const counts = assertObject(
+    adaptersResult['counts'],
+    'wayfind adapters counts'
+  );
+  if (counts['configured'] !== 1 || counts['used'] !== 1) {
+    throw new Error(
+      'wayfind adapters did not report configured/used adapter facts'
+    );
+  }
+  if (counts['observed'] !== 0) {
+    throw new Error('wayfind adapters reported unsupported observed facts');
+  }
+  const { adapters } = adaptersResult;
+  if (!Array.isArray(adapters)) {
+    throw new TypeError('wayfind adapters did not return adapters');
+  }
+  const ids = adapters
+    .map((adapter) => assertObject(adapter, 'wayfind adapters fact')['key'])
+    .filter((key): key is string => typeof key === 'string');
+  if (!ids.includes('@ontrails/hono:http:used')) {
+    throw new Error('wayfind adapters did not find Hono conformance usage');
+  }
+};
+
+const assertContractForSearch = (contractResult: JsonObject): void => {
+  const contract = assertObject(contractResult['contract'], 'contract');
+  if (contract['id'] !== 'wayfind.search') {
+    throw new Error('wayfind contract did not inspect wayfind.search');
+  }
+};
+
+const assertResolvedTarget = (value: JsonObject, label: string): void => {
+  const target = assertObject(value['target'], `${label}.target`);
+  if (target['id'] !== 'wayfind.search') {
+    throw new Error(`${label} did not resolve wayfind.search`);
+  }
+};
+
+export const runWayfinderDogfoodSmoke =
+  async (): Promise<WayfinderDogfoodSmokeResult> => {
+    const tempRoot = await mkdtemp(join(tmpdir(), 'trails-wayfinder-dogfood-'));
+
+    try {
+      const [{ trailsMcpApp }, { exportCurrentTopo }] = await Promise.all([
+        import('../mcp-app.js'),
+        import('../trails/topo-store-support.js'),
+      ]);
+      const exported = await exportCurrentTopo(trailsMcpApp, {
+        rootDir: tempRoot,
+      });
+      if (exported.isErr()) {
+        throw exported.error;
+      }
+
+      const overview = runWayfind(tempRoot, ['overview']);
+      assertFreshSource(overview, 'wayfind overview');
+      const counts = assertObject(
+        overview['counts'],
+        'wayfind overview counts'
+      );
+      const trailCount = counts['trails'];
+      if (typeof trailCount !== 'number' || trailCount < 1) {
+        throw new Error('wayfind overview did not report trail counts');
+      }
+
+      const search = runWayfind(tempRoot, [
+        'search',
+        '--input-json',
+        '{"filters":{"kind":"trail","idPrefix":"wayfind."}}',
+      ]);
+      assertFreshSource(search, 'wayfind search');
+      assertSearchFindsWayfinder(search);
+
+      const errors = runWayfind(tempRoot, [
+        'errors',
+        '--input-json',
+        '{"filters":{"kind":"trail","idPrefix":"wayfind."}}',
+      ]);
+      assertFreshSource(errors, 'wayfind errors');
+      assertErrorsFindWayfinder(errors);
+
+      const adapters = runWayfind(repoRoot, ['adapters']);
+      assertAdaptersFindHono(adapters);
+
+      const contract = runWayfind(tempRoot, ['contract', 'wayfind.search']);
+      assertFreshSource(contract, 'wayfind contract');
+      assertContractForSearch(contract);
+
+      const nearby = runWayfind(tempRoot, ['nearby', 'wayfind.search']);
+      assertFreshSource(nearby, 'wayfind nearby');
+      assertResolvedTarget(nearby, 'wayfind nearby');
+
+      const impact = runWayfind(tempRoot, ['impact', 'wayfind.search']);
+      assertFreshSource(impact, 'wayfind impact');
+      assertResolvedTarget(impact, 'wayfind impact');
+
+      return {
+        check: 'wayfinder-dogfood',
+        message: `Wayfinder dogfood smoke passed: ${String(trailCount)} trails inspected from saved operator topo artifacts.`,
+        passed: true,
+        trailCount,
+      };
+    } finally {
+      await rm(tempRoot, { force: true, recursive: true });
+    }
+  };
+
+if (import.meta.main) {
+  const result = await runWayfinderDogfoodSmoke();
+  console.log(result.message);
+}

package/src/run-release-check.ts

@@ -0,0 +1,74 @@
+import type { ActionResultContext } from '@ontrails/cli';
+import { deriveOutputMode } from '@ontrails/cli';
+
+interface ReleaseCheckResultValue {
+  readonly formatted: string;
+  readonly passed: boolean;
+}
+
+const isReleaseCheckResultValue = (
+  value: unknown
+): value is ReleaseCheckResultValue => {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+
+  const candidate = value as Record<string, unknown>;
+  return (
+    typeof candidate['formatted'] === 'string' &&
+    typeof candidate['passed'] === 'boolean'
+  );
+};
+
+const wantsStructuredOutput = (ctx: ActionResultContext): boolean =>
+  deriveOutputMode(ctx.flags, ctx.topoName).mode !== 'text';
+
+const readReleaseCheckResultValue = (
+  ctx: ActionResultContext
+): ReleaseCheckResultValue | undefined => {
+  if (ctx.trail.id !== 'release.check' || ctx.result.isErr()) {
+    return undefined;
+  }
+
+  return isReleaseCheckResultValue(ctx.result.value)
+    ? ctx.result.value
+    : undefined;
+};
+
+export const applyReleaseCheckExitCode = (
+  ctx: ActionResultContext
+): boolean => {
+  if (ctx.trail.id !== 'release.check') {
+    return false;
+  }
+
+  if (ctx.result.isErr()) {
+    process.exitCode = 1;
+    return true;
+  }
+
+  const value = readReleaseCheckResultValue(ctx);
+  if (!value) {
+    return false;
+  }
+
+  process.exitCode = value.passed ? 0 : 1;
+  return true;
+};
+
+export const tryReleaseCheckOutput = (ctx: ActionResultContext): boolean => {
+  const value = readReleaseCheckResultValue(ctx);
+  if (!value) {
+    return false;
+  }
+
+  applyReleaseCheckExitCode(ctx);
+  if (wantsStructuredOutput(ctx)) {
+    return false;
+  }
+
+  if (value.formatted.length > 0) {
+    process.stdout.write(`${value.formatted}\n`);
+  }
+  return true;
+};

package/src/scaffold-version-sync.ts

@@ -0,0 +1,183 @@
+/**
+ * Scaffold dependency version derivation for the `create.versions` trail.
+ *
+ * Generates or validates `apps/trails/src/scaffold-versions.generated.ts`
+ * from the root `package.json` catalog and devDependencies, and validates
+ * that generated `@ontrails/*` package pins track the `@ontrails/trails`
+ * version exactly.
+ */
+
+import { resolve } from 'node:path';
+
+import {
+  ontrailsPackageRange as appOntrailsPackageRange,
+  trailsPackageVersion as appTrailsPackageVersion,
+} from './versions.js';
+
+interface RootPackageJson {
+  readonly catalog?: Record<string, string>;
+  readonly devDependencies?: Record<string, string>;
+}
+
+export interface OntrailsPackagePinState {
+  readonly ontrailsPackageRange?: string;
+  readonly trailsPackageVersion?: string;
+}
+
+export interface SyncScaffoldVersionsResult {
+  readonly generatedPath: string;
+  readonly mode: 'check' | 'write';
+  readonly written: boolean;
+}
+
+export const diagnoseOntrailsPackagePin = ({
+  ontrailsPackageRange,
+  trailsPackageVersion,
+}: OntrailsPackagePinState): string | undefined => {
+  if (
+    typeof ontrailsPackageRange !== 'string' ||
+    typeof trailsPackageVersion !== 'string'
+  ) {
+    return (
+      'create.versions: apps/trails/src/versions.ts must export ' +
+      '`ontrailsPackageRange` and `trailsPackageVersion`.'
+    );
+  }
+  if (ontrailsPackageRange !== trailsPackageVersion) {
+    return (
+      'create.versions: scaffolded @ontrails/* packages must be exact ' +
+      `pins for @ontrails/trails (${trailsPackageVersion}); got ` +
+      `${ontrailsPackageRange}.`
+    );
+  }
+  return undefined;
+};
+
+const requireValue = (
+  value: string | undefined,
+  label: string,
+  source: string,
+  rootPackageJsonPath: string
+): string => {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(
+      `create.versions: missing "${label}" under ${source} in ${rootPackageJsonPath}`
+    );
+  }
+  return value;
+};
+
+const loadScaffoldVersions = async (
+  rootPackageJsonPath: string
+): Promise<Record<string, string> & Readonly<Record<string, string>>> => {
+  const rootPkg = (await Bun.file(
+    rootPackageJsonPath
+  ).json()) as RootPackageJson;
+  const catalog = rootPkg.catalog ?? {};
+  const devDeps = rootPkg.devDependencies ?? {};
+
+  return {
+    bunTypes: requireValue(
+      devDeps['@types/bun'],
+      '@types/bun',
+      'devDependencies',
+      rootPackageJsonPath
+    ),
+    commander: requireValue(
+      catalog['commander'],
+      'commander',
+      'catalog',
+      rootPackageJsonPath
+    ),
+    lefthook: requireValue(
+      devDeps['lefthook'],
+      'lefthook',
+      'devDependencies',
+      rootPackageJsonPath
+    ),
+    oxfmt: requireValue(
+      devDeps['oxfmt'],
+      'oxfmt',
+      'devDependencies',
+      rootPackageJsonPath
+    ),
+    oxlint: requireValue(
+      devDeps['oxlint'],
+      'oxlint',
+      'devDependencies',
+      rootPackageJsonPath
+    ),
+    typescript: requireValue(
+      devDeps['typescript'],
+      'typescript',
+      'devDependencies',
+      rootPackageJsonPath
+    ),
+    ultracite: requireValue(
+      devDeps['ultracite'],
+      'ultracite',
+      'devDependencies',
+      rootPackageJsonPath
+    ),
+    zod: requireValue(catalog['zod'], 'zod', 'catalog', rootPackageJsonPath),
+  };
+};
+
+const renderGeneratedFile = (
+  versions: Record<string, string> & Readonly<Record<string, string>>
+): string => {
+  const keys = Object.keys(versions).toSorted();
+  const lines = keys.map((key: string) => `  ${key}: '${versions[key]}',`);
+  return [
+    '// GENERATED FILE — do not edit by hand. Run `bun run scaffold-versions:sync` to regenerate.',
+    '',
+    'export const scaffoldDependencyVersions = {',
+    ...lines,
+    '} as const;',
+    '',
+  ].join('\n');
+};
+
+export const syncScaffoldVersions = async (options: {
+  check: boolean;
+  rootDir: string;
+}): Promise<SyncScaffoldVersionsResult> => {
+  const rootPackageJsonPath = resolve(options.rootDir, 'package.json');
+  const generatedPath = resolve(
+    options.rootDir,
+    'apps/trails/src/scaffold-versions.generated.ts'
+  );
+  const versions = await loadScaffoldVersions(rootPackageJsonPath);
+  const expected = renderGeneratedFile(versions);
+
+  if (options.check) {
+    const generatedFile = Bun.file(generatedPath);
+    const existing = (await generatedFile.exists())
+      ? await generatedFile.text()
+      : undefined;
+    if (existing !== expected) {
+      throw new Error(
+        `create.versions: ${generatedPath} is out of date.\n` +
+          'Run `bun run scaffold-versions:sync` to regenerate.'
+      );
+    }
+  } else {
+    await Bun.write(generatedPath, expected);
+  }
+
+  // Normally quiet because versions.ts derives both exports from one source;
+  // this trips only if future/manual drift breaks that invariant.
+  const diagnostic = diagnoseOntrailsPackagePin({
+    ontrailsPackageRange: appOntrailsPackageRange,
+    trailsPackageVersion: appTrailsPackageVersion,
+  });
+  if (diagnostic !== undefined) {
+    throw new Error(diagnostic);
+  }
+
+  return {
+    generatedPath,
+    mode: options.check ? 'check' : 'write',
+    written: !options.check,
+  };
+};

package/src/scaffold-versions.generated.ts

@@ -1,4 +1,4 @@
-// GENERATED FILE — do not edit by hand. Run `bun scripts/sync-scaffold-versions.ts` to regenerate.
+// GENERATED FILE — do not edit by hand. Run `bun run scaffold-versions:sync` to regenerate.
 
 export const scaffoldDependencyVersions = {
   bunTypes: '^1.3.11',

package/src/trails/compile.ts

@@ -16,8 +16,19 @@ export const compileCurrentTopo = async (
   options?: { readonly force?: boolean | undefined; readonly rootDir?: string }
 ): Promise<Result<TopoExportReport, Error>> => exportCurrentTopo(app, options);
 
+const compileTrailInputSchema = z.object({
+  force: z
+    .boolean()
+    .optional()
+    .describe('Record graph-only force events for breaking changes'),
+  module: z.string().optional().describe('Path to the app module'),
+  rootDir: z.string().optional().describe('Workspace root directory'),
+});
+
+type CompileTrailInput = z.output<typeof compileTrailInputSchema>;
+
 export const compileTrail = trail('compile', {
-  blaze: async (input, ctx) => {
+  blaze: async (input: CompileTrailInput, ctx) => {
     const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
     if (rootDirResult.isErr()) {
       return rootDirResult;
@@ -44,14 +55,7 @@ export const compileTrail = trail('compile', {
       name: 'Compile the current topo artifacts',
     },
   ],
-  input: z.object({
-    force: z
-      .boolean()
-      .optional()
-      .describe('Record graph-only force events for breaking changes'),
-    module: z.string().optional().describe('Path to the app module'),
-    rootDir: z.string().optional().describe('Workspace root directory'),
-  }),
+  input: compileTrailInputSchema,
   intent: 'write',
   output: z.object({
     hash: z.string(),

package/src/trails/create-versions.ts

@@ -0,0 +1,62 @@
+/**
+ * `create.versions` trail -- Sync generated scaffold dependency versions.
+ *
+ * Derives `apps/trails/src/scaffold-versions.generated.ts` from the root
+ * `package.json` catalog and devDependencies. Graduated from
+ * `scripts/sync-scaffold-versions.ts`.
+ */
+
+import { Result, trail, ValidationError } from '@ontrails/core';
+import { z } from 'zod';
+
+import { syncScaffoldVersions } from '../scaffold-version-sync.js';
+import { resolveTrailRootDir } from './root-dir.js';
+
+const createVersionsInputSchema = z.object({
+  check: z
+    .boolean()
+    .default(false)
+    .describe('Verify the generated file is current instead of writing'),
+  rootDir: z.string().optional().describe('Workspace root directory'),
+});
+
+const createVersionsOutputSchema = z.object({
+  generatedPath: z.string(),
+  mode: z.enum(['check', 'write']),
+  written: z.boolean(),
+});
+
+export const createVersionsTrail = trail('create.versions', {
+  blaze: async (input, ctx) => {
+    const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
+    if (rootDirResult.isErr()) {
+      return rootDirResult;
+    }
+
+    try {
+      return Result.ok(
+        await syncScaffoldVersions({
+          check: input.check,
+          rootDir: rootDirResult.value,
+        })
+      );
+    } catch (error) {
+      return Result.err(
+        new ValidationError(
+          error instanceof Error ? error.message : String(error)
+        )
+      );
+    }
+  },
+  description: 'Sync generated scaffold dependency versions',
+  examples: [
+    {
+      input: { check: true },
+      name: 'Verify generated scaffold versions are current',
+    },
+  ],
+  input: createVersionsInputSchema,
+  intent: 'write',
+  output: createVersionsOutputSchema,
+  permit: { scopes: ['project:write'] },
+});

package/src/trails/guide.ts

@@ -28,12 +28,20 @@ interface GuideEntry {
   readonly kind: 'trail';
 }
 
+const guideTrailInputSchema = z.object({
+  module: z.string().optional().describe('Path to the app module'),
+  rootDir: z.string().optional().describe('Workspace root directory'),
+  trailId: z.string().optional().describe('Trail ID for detailed guidance'),
+});
+
+type GuideTrailInput = z.output<typeof guideTrailInputSchema>;
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
 export const guideTrail = trail('guide', {
-  blaze: async (input, ctx) => {
+  blaze: async (input: GuideTrailInput, ctx) => {
     const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
     if (rootDirResult.isErr()) {
       return rootDirResult;
@@ -80,11 +88,7 @@ export const guideTrail = trail('guide', {
       name: 'List trail guidance',
     },
   ],
-  input: z.object({
-    module: z.string().optional().describe('Path to the app module'),
-    rootDir: z.string().optional().describe('Workspace root directory'),
-    trailId: z.string().optional().describe('Trail ID for detailed guidance'),
-  }),
+  input: guideTrailInputSchema,
   intent: 'read',
   output: z.discriminatedUnion('mode', [
     z.object({