@ontrails/trails 1.0.0-beta.2 → 1.0.0-beta.22

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/retired-topo-command.ts

@@ -0,0 +1,36 @@
+const retiredTopoCommandReplacements = {
+  check: 'trails validate',
+  compile: 'trails compile',
+  verify: 'trails validate',
+} as const;
+
+export type RetiredTopoCommand = keyof typeof retiredTopoCommandReplacements;
+
+export interface RetiredTopoCommandDiagnostic {
+  readonly attempted: `trails topo ${RetiredTopoCommand}`;
+  readonly message: string;
+  readonly replacement: (typeof retiredTopoCommandReplacements)[RetiredTopoCommand];
+}
+
+const isRetiredTopoCommand = (
+  command: string | undefined
+): command is RetiredTopoCommand =>
+  command !== undefined && command in retiredTopoCommandReplacements;
+
+export const getRetiredTopoCommandDiagnostic = (
+  argv: readonly string[]
+): RetiredTopoCommandDiagnostic | null => {
+  const [command, subcommand] = argv.slice(2);
+  if (command !== 'topo' || !isRetiredTopoCommand(subcommand)) {
+    return null;
+  }
+
+  const replacement = retiredTopoCommandReplacements[subcommand];
+  const attempted = `trails topo ${subcommand}` as const;
+
+  return {
+    attempted,
+    message: `"${attempted}" was retired. Use "${replacement}" instead.\nTopographer artifact commands now live at the top level: "trails compile", "trails validate", and "trails diff". "trails topo" is for topo-store history, pin, and unpin.`,
+    replacement,
+  };
+};

package/src/run-adapter-check.ts

@@ -0,0 +1,76 @@
+import type { ActionResultContext } from '@ontrails/cli';
+import { deriveOutputMode } from '@ontrails/cli';
+
+interface AdapterCheckResultValue {
+  readonly formatted: string;
+  readonly passed: boolean;
+}
+
+const isAdapterCheckResultValue = (
+  value: unknown
+): value is AdapterCheckResultValue => {
+  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 isAdapterCheckTrail = (ctx: ActionResultContext): boolean =>
+  ctx.trail.id === 'adapter.check';
+
+const readAdapterCheckResultValue = (
+  ctx: ActionResultContext
+): AdapterCheckResultValue | undefined => {
+  if (!isAdapterCheckTrail(ctx) || ctx.result.isErr()) {
+    return undefined;
+  }
+
+  return isAdapterCheckResultValue(ctx.result.value)
+    ? ctx.result.value
+    : undefined;
+};
+
+export const applyAdapterCheckExitCode = (
+  ctx: ActionResultContext
+): boolean => {
+  if (!isAdapterCheckTrail(ctx)) {
+    return false;
+  }
+
+  if (ctx.result.isErr()) {
+    process.exitCode = 1;
+    return true;
+  }
+
+  const value = readAdapterCheckResultValue(ctx);
+  if (!value) {
+    return false;
+  }
+
+  process.exitCode = value.passed ? 0 : 1;
+  return true;
+};
+
+export const tryAdapterCheckOutput = (ctx: ActionResultContext): boolean => {
+  const value = readAdapterCheckResultValue(ctx);
+  if (!value) {
+    return false;
+  }
+
+  applyAdapterCheckExitCode(ctx);
+  if (wantsStructuredOutput(ctx)) {
+    return false;
+  }
+
+  if (value.formatted.length > 0) {
+    process.stdout.write(`${value.formatted}\n`);
+  }
+  return true;
+};

package/src/run-collision.ts

@@ -0,0 +1,126 @@
+/**
+ * CLI-surface bridge for the `run` trail's collision UX.
+ *
+ * The `run` trail is surface-agnostic: when a trail id collides across two or
+ * more workspace apps and no `--app` override is provided, the trail returns
+ * `Result.err(AmbiguousError)` with the candidate app names in `error.context`.
+ *
+ * The CLI surface decides whether to prompt the user (TTY) or surface the
+ * error verbatim (non-TTY). This module owns that surface decision so the
+ * trail itself never reads `process.stdin.isTTY` or imports a prompt library.
+ */
+
+import type { ActionResultContext } from '@ontrails/cli';
+import { AmbiguousError, executeTrail, isPlainObject } from '@ontrails/core';
+import type { Result, Topo } from '@ontrails/core';
+import * as clack from '@clack/prompts';
+
+/** Runtime dependencies the wrapper resolves through; injectable for tests. */
+export interface RunCollisionDeps {
+  readonly graph: Topo;
+  readonly isTTY?: () => boolean;
+  readonly promptForApp?: (
+    candidates: readonly string[],
+    trailId: string
+  ) => Promise<string | undefined>;
+}
+
+const defaultIsTTY = (): boolean => process.stdin.isTTY === true;
+
+const defaultPromptForApp = async (
+  candidates: readonly string[],
+  trailId: string
+): Promise<string | undefined> => {
+  const choice = await clack.select({
+    message: `Trail ID '${trailId}' is exposed by multiple apps. Choose one:`,
+    options: candidates.map((appName) => ({
+      label: appName,
+      value: appName,
+    })),
+  });
+  return clack.isCancel(choice) ? undefined : (choice as string);
+};
+
+const isAmbiguousCollision = (
+  ctx: ActionResultContext
+): ctx is ActionResultContext & {
+  readonly result: { readonly error: AmbiguousError };
+} =>
+  ctx.trail.id === 'run' &&
+  ctx.result.isErr() &&
+  ctx.result.error instanceof AmbiguousError;
+
+const readCandidates = (error: AmbiguousError): readonly string[] => {
+  const ctx = error.context;
+  if (!isPlainObject(ctx)) {
+    return [];
+  }
+  const raw = ctx['candidates'];
+  if (!Array.isArray(raw)) {
+    return [];
+  }
+  return raw.filter((entry): entry is string => typeof entry === 'string');
+};
+
+const readTrailId = (error: AmbiguousError): string | undefined => {
+  const ctx = error.context;
+  if (!isPlainObject(ctx)) {
+    return;
+  }
+  const raw = ctx['trailId'];
+  return typeof raw === 'string' ? raw : undefined;
+};
+
+const hasAppOverride = (input: unknown): boolean =>
+  isPlainObject(input) && typeof input['app'] === 'string';
+
+const mergeAppOverride = (
+  input: unknown,
+  app: string
+): Record<string, unknown> => ({
+  ...(isPlainObject(input) ? input : {}),
+  app,
+});
+
+/**
+ * Try to recover from an ambiguous-trail-id collision on the run trail.
+ *
+ * Returns the re-execution result when a TTY prompt yielded a chosen app, or
+ * `undefined` when there is nothing to recover (non-TTY, non-collision, or the
+ * user cancelled). The caller forwards `undefined` to the default result
+ * handler, which surfaces the error verbatim and maps it to exit code 1.
+ */
+export const tryRecoverFromRunCollision = async (
+  ctx: ActionResultContext,
+  deps: RunCollisionDeps
+): Promise<Result<unknown, Error> | undefined> => {
+  if (!isAmbiguousCollision(ctx)) {
+    return;
+  }
+  if (hasAppOverride(ctx.input)) {
+    return;
+  }
+
+  const isTTY = deps.isTTY ?? defaultIsTTY;
+  if (!isTTY()) {
+    return;
+  }
+
+  const { error } = ctx.result;
+  const candidates = readCandidates(error);
+  const trailId = readTrailId(error);
+  if (candidates.length === 0 || trailId === undefined) {
+    return;
+  }
+
+  const promptForApp = deps.promptForApp ?? defaultPromptForApp;
+  const chosen = await promptForApp(candidates, trailId);
+  if (chosen === undefined) {
+    return;
+  }
+
+  return await executeTrail(ctx.trail, mergeAppOverride(ctx.input, chosen), {
+    ctx: ctx.permit === undefined ? {} : { permit: ctx.permit },
+    topo: deps.graph,
+  });
+};

package/src/run-completions-install.ts

@@ -0,0 +1,179 @@
+/**
+ * CLI bridge for installing shell completion scripts.
+ *
+ * This is intentionally not a trail: it resolves CLI-local defaults such as
+ * `$SHELL` and the user's home directory, then writes to the user's completion
+ * directory. The surface-agnostic trail remains `completions`, which renders a
+ * script string for any caller.
+ */
+
+import { mkdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+import {
+  projectPublicSurfaceError,
+  Result,
+  ValidationError,
+} from '@ontrails/core';
+import type { Command } from 'commander';
+
+import { renderCompletionScript } from './completions.js';
+import type { CompletionShell } from './completions.js';
+
+export const COMPLETIONS_BIN_NAME = 'trails';
+
+const SHELLS = new Set<CompletionShell>(['bash', 'fish', 'zsh']);
+
+const INSTALL_PATH_BY_SHELL: Readonly<Record<CompletionShell, string>> = {
+  bash: '.local/share/bash-completion/completions/trails',
+  fish: '.config/fish/completions/trails.fish',
+  zsh: '.local/share/zsh/site-functions/_trails',
+};
+
+export interface CompletionsInstallOptions {
+  readonly binName?: string | undefined;
+  readonly homeDir?: string | undefined;
+  readonly shell?: string | undefined;
+  readonly shellEnv?: string | undefined;
+}
+
+export interface CompletionsInstallResult {
+  readonly created: boolean;
+  readonly message: string;
+  readonly path: string;
+  readonly shell: CompletionShell;
+}
+
+interface StdoutLike {
+  write(chunk: string): unknown;
+}
+
+export interface AttachCompletionsInstallOptions {
+  readonly binName?: string | undefined;
+  readonly homeDir?: string | undefined;
+  readonly shellEnv?: string | undefined;
+  readonly stdout?: StdoutLike | undefined;
+}
+
+const isCompletionShell = (value: string): value is CompletionShell =>
+  SHELLS.has(value as CompletionShell);
+
+const detectShellFromEnv = (shellEnv: string): CompletionShell | null => {
+  if (shellEnv.length === 0) {
+    return null;
+  }
+  const slashIndex = shellEnv.lastIndexOf('/');
+  const base = slashIndex === -1 ? shellEnv : shellEnv.slice(slashIndex + 1);
+  return isCompletionShell(base) ? base : null;
+};
+
+const unsupportedShellMessage =
+  'Could not detect shell from $SHELL. Pass --shell with one of: bash, zsh, fish.';
+
+const resolveTargetShell = (input: {
+  readonly shell?: string | undefined;
+  readonly shellEnv?: string | undefined;
+}): Result<CompletionShell, ValidationError> => {
+  if (input.shell !== undefined) {
+    if (isCompletionShell(input.shell)) {
+      return Result.ok(input.shell);
+    }
+    return Result.err(
+      new ValidationError(
+        `Unsupported shell "${input.shell}". Pass one of: bash, zsh, fish.`
+      )
+    );
+  }
+  const envValue = input.shellEnv ?? process.env['SHELL'] ?? '';
+  const detected = detectShellFromEnv(envValue);
+  return detected === null
+    ? Result.err(new ValidationError(unsupportedShellMessage))
+    : Result.ok(detected);
+};
+
+const fileExists = async (path: string): Promise<boolean> =>
+  await Bun.file(path).exists();
+
+export const runCompletionsInstall = async (
+  options: CompletionsInstallOptions = {}
+): Promise<Result<CompletionsInstallResult, Error>> => {
+  const shellResult = resolveTargetShell(options);
+  if (shellResult.isErr()) {
+    return Result.err(shellResult.error);
+  }
+
+  const shell = shellResult.value;
+  const home = options.homeDir ?? homedir();
+  const path = join(home, INSTALL_PATH_BY_SHELL[shell]);
+  const scriptResult = renderCompletionScript(
+    shell,
+    options.binName ?? COMPLETIONS_BIN_NAME
+  );
+  if (scriptResult.isErr()) {
+    return Result.err(scriptResult.error);
+  }
+
+  let existed: boolean;
+  try {
+    existed = await fileExists(path);
+    await mkdir(dirname(path), { recursive: true });
+    await Bun.write(path, scriptResult.value);
+  } catch (error) {
+    return Result.err(
+      error instanceof Error ? error : new Error(String(error))
+    );
+  }
+  const created = !existed;
+
+  return Result.ok({
+    created,
+    message: created
+      ? `Installed ${shell} completions to ${path}. Run \`exec $SHELL\` or restart your shell to activate.`
+      : `Updated ${shell} completions at ${path}.`,
+    path,
+    shell,
+  });
+};
+
+const handleCliError = (error: unknown): void => {
+  const err = error instanceof Error ? error : new Error(String(error));
+  const projection = projectPublicSurfaceError('cli', err);
+  process.stderr.write(`Error: ${projection.message}\n`);
+  process.exit(projection.code);
+};
+
+const findCompletionsCommand = (program: Command): Command | undefined =>
+  program.commands.find((command) => command.name() === 'completions');
+
+export const attachCompletionsInstallCommand = (
+  program: Command,
+  options: AttachCompletionsInstallOptions = {}
+): void => {
+  const completionsCommand =
+    findCompletionsCommand(program) ??
+    program
+      .command('completions')
+      .description('Render and install shell completion scripts');
+
+  completionsCommand
+    .command('install')
+    .description('Install a shell completion script for the trails CLI')
+    .option(
+      '-s, --shell <shell>',
+      'Target shell; auto-detected from $SHELL when omitted.'
+    )
+    .action(async (flags: { readonly shell?: string | undefined }) => {
+      const result = await runCompletionsInstall({
+        binName: options.binName,
+        homeDir: options.homeDir,
+        shell: flags.shell,
+        shellEnv: options.shellEnv,
+      });
+      if (result.isErr()) {
+        handleCliError(result.error);
+        return;
+      }
+      (options.stdout ?? process.stdout).write(`${result.value.message}\n`);
+    });
+};