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

package/src/cli.ts

@@ -1,14 +1,308 @@
-import { outputModePreset } from '@ontrails/cli';
-import { trailhead } from '@ontrails/cli/commander';
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { isAbsolute, join, resolve } from 'node:path';
+
+import {
+  defaultOnResult,
+  devPermitPreset,
+  outputModePreset,
+  permitPreset,
+  tokenPreset,
+  tracePreset,
+  watchPreset,
+} from '@ontrails/cli';
+import type {
+  ActionResultContext,
+  ResolveCliPermitFromToken,
+} from '@ontrails/cli';
+import { createProgram } from '@ontrails/commander';
+import { resolvePermitFromBearerToken } from '@ontrails/permits';
+import { deriveTopoGraph } from '@ontrails/topographer';
 
 import { app } from './app.js';
 import { resolveInputWithClack } from './clack.js';
+import { attachCompletionsInstallCommand } from './run-completions-install.js';
+import { tryRecoverFromRunCollision } from './run-collision.js';
+import { tryExampleRunOutput } from './run-example.js';
+import { tryExamplesRunOutput } from './run-examples.js';
+import { tryQuietRunOutput } from './run-quiet.js';
+import {
+  argvHasTraceFlag,
+  installTraceSink,
+  tryTraceJsonOutput,
+  writeTraceTreeToStderr,
+} from './run-trace.js';
+import type { TraceSession } from './run-trace.js';
+import {
+  argvHasWatchFlag,
+  hashTopoGraphEntry,
+  readRunTrailId,
+  runWatchLoop,
+} from './run-watch.js';
+import { tryWardenOutput } from './run-warden.js';
+import { tryLoadFreshAppLease } from './trails/load-app.js';
+import { resolveRunModulePath } from './trails/run.js';
+import { resolveTrailRootDir } from './trails/root-dir.js';
+import { trailsPackageVersion } from './versions.js';
+
+const buildOnResult =
+  (session: TraceSession | undefined) =>
+  async (ctx: ActionResultContext): Promise<void> => {
+    const recovered = await tryRecoverFromRunCollision(ctx, { graph: app });
+    const resolvedCtx: ActionResultContext =
+      recovered === undefined
+        ? ctx
+        : {
+            ...ctx,
+            input: recovered.isOk()
+              ? (ctx.trail.input.safeParse(ctx.input).data ?? ctx.input)
+              : ctx.input,
+            result: recovered,
+          };
+
+    // `--trace --json` (without `--quiet`) emits a single Result-shaped
+    // envelope on stdout that includes the captured records under
+    // `tracing`. Hand that case off before the regular chain so the
+    // existing handlers do not also write to stdout.
+    if (session !== undefined && tryTraceJsonOutput(resolvedCtx, session)) {
+      return;
+    }
+
+    if (tryExampleRunOutput(resolvedCtx)) {
+      return;
+    }
+    if (tryExamplesRunOutput(resolvedCtx)) {
+      return;
+    }
+    if (await tryQuietRunOutput(resolvedCtx)) {
+      return;
+    }
+    if (tryWardenOutput(resolvedCtx)) {
+      return;
+    }
+    await defaultOnResult(resolvedCtx);
+  };
+
+const traceEnabled = argvHasTraceFlag(process.argv);
+const maybeInstallTraceSession = (): TraceSession | undefined =>
+  traceEnabled ? installTraceSink() : undefined;
+
+const resolveCliPermitFromToken: ResolveCliPermitFromToken = (input) =>
+  resolvePermitFromBearerToken({
+    bearerToken: input.token,
+    configValues: input.configValues,
+    env: process.env as Record<string, string | undefined>,
+    graph: input.graph,
+    missingAuthResourceMessage:
+      '--token requires an auth adapter. Register authResource from @ontrails/permits in your topo.',
+    nullPermitMessage: 'Auth adapter did not produce a permit for --token',
+    requestId: input.requestId,
+    resources: input.resources,
+    surface: 'cli',
+  });
+
+interface WatchRunTarget {
+  readonly app?: string | undefined;
+  readonly id: string;
+  readonly module?: string | undefined;
+  readonly rootDir?: string | undefined;
+}
+
+const readFlagValue = (
+  args: readonly string[],
+  flagName: string
+): string | undefined => {
+  const longFlag = `--${flagName}`;
+  const prefixedFlag = `${longFlag}=`;
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === longFlag) {
+      return args[i + 1];
+    }
+    if (arg?.startsWith(prefixedFlag)) {
+      return arg.slice(prefixedFlag.length);
+    }
+  }
+  return undefined;
+};
+
+const resolveWatchRunTarget = (
+  argv: readonly string[]
+): WatchRunTarget | null => {
+  const args = argv.slice(2);
+  const id = readRunTrailId(args);
+  if (id === undefined) {
+    return null;
+  }
+  return {
+    app: readFlagValue(args, 'app'),
+    id,
+    module: readFlagValue(args, 'module'),
+    rootDir: readFlagValue(args, 'root-dir'),
+  };
+};
+
+/**
+ * Resolve the directory whose source-file events wake the `--watch` loop.
+ * Reruns still depend on the resolved TopoGraph entry hash; this path is
+ * only the cheap filesystem event source.
+ */
+const toWatchSourcePath = (rootDir: string, modulePath: string): string => {
+  if (modulePath.startsWith('file:')) {
+    return fileURLToPath(modulePath);
+  }
+  return isAbsolute(modulePath) ? modulePath : resolve(rootDir, modulePath);
+};
+
+const resolveWatchDirectorySourcePath = async (
+  target: WatchRunTarget | null
+): Promise<string> => {
+  if (target !== null) {
+    const rootDirResult = resolveTrailRootDir(target.rootDir, process.cwd());
+    if (rootDirResult.isErr()) {
+      throw rootDirResult.error;
+    }
+    const moduleResult = await resolveRunModulePath(
+      rootDirResult.value,
+      target.module,
+      target.id,
+      target.app
+    );
+    if (moduleResult.isOk()) {
+      return toWatchSourcePath(rootDirResult.value, moduleResult.value);
+    }
+  }
+  const cwd = process.cwd();
+  const srcDir = join(cwd, 'src');
+  if (existsSync(srcDir)) {
+    return join(srcDir, 'app.ts');
+  }
+  return join(cwd, 'app.ts');
+};
+
+const readWatchTopoGraphEntryHash = async (
+  target: WatchRunTarget | null
+): Promise<string | null> => {
+  if (target === null) {
+    return null;
+  }
+  const rootDirResult = resolveTrailRootDir(target.rootDir, process.cwd());
+  if (rootDirResult.isErr()) {
+    throw rootDirResult.error;
+  }
+  const rootDir = rootDirResult.value;
+  const moduleResult = await resolveRunModulePath(
+    rootDir,
+    target.module,
+    target.id,
+    target.app
+  );
+  if (moduleResult.isErr()) {
+    throw moduleResult.error;
+  }
+  const leaseResult = await tryLoadFreshAppLease(moduleResult.value, rootDir);
+  if (leaseResult.isErr()) {
+    throw leaseResult.error;
+  }
+  const lease = leaseResult.value;
+  try {
+    const topoGraph = deriveTopoGraph(lease.app);
+    const entry = topoGraph.entries.find(
+      (candidate) => candidate.kind === 'trail' && candidate.id === target.id
+    );
+    return entry === undefined ? null : hashTopoGraphEntry(entry);
+  } finally {
+    lease.release();
+  }
+};
+
+const wardenValueFlags = new Set([
+  '--apps',
+  '--config-path',
+  '--depth',
+  '--drafts',
+  '--fail-on',
+  '--format',
+  '--lock',
+  '--root-dir',
+]);
+
+const normalizeWardenArgv = (argv: readonly string[]): string[] => {
+  if (argv[2] !== 'warden') {
+    return [...argv];
+  }
+
+  const normalized = [...argv];
+  let previousFlagConsumesValue = false;
+  for (let index = 3; index < normalized.length; index += 1) {
+    const arg = normalized[index];
+    if (arg === undefined) {
+      continue;
+    }
+
+    if (previousFlagConsumesValue) {
+      previousFlagConsumesValue = false;
+      continue;
+    }
+
+    if (arg === '-a') {
+      normalized[index] = '--apps';
+      previousFlagConsumesValue = true;
+      continue;
+    }
+
+    previousFlagConsumesValue = wardenValueFlags.has(arg);
+  }
+
+  return normalized;
+};
+
+/**
+ * Invoke `surface()` once with an optional fresh trace session.
+ *
+ * When `--trace` is set, a fresh {@link TraceSession} is installed for the
+ * duration of the call and finalized in the `finally` block. Under
+ * `--watch`, this produces a fresh sink (and a fresh stderr tree) per
+ * rerun rather than letting records accumulate in a single
+ * process-lifetime sink.
+ */
+const runSurfaceOnce = async (): Promise<void> => {
+  const session = maybeInstallTraceSession();
+  try {
+    const program = createProgram(app, {
+      description: 'Agent-native, contract-first TypeScript framework',
+      name: 'trails',
+      onResult: buildOnResult(session),
+      presets: [
+        outputModePreset(),
+        tracePreset(),
+        permitPreset(),
+        tokenPreset(),
+        devPermitPreset(),
+        watchPreset(),
+      ],
+      resolveInput: resolveInputWithClack,
+      resolvePermitFromToken: resolveCliPermitFromToken,
+      version: trailsPackageVersion,
+    });
+    attachCompletionsInstallCommand(program);
+    await program.parseAsync(normalizeWardenArgv(process.argv));
+  } finally {
+    if (session !== undefined) {
+      const records = session.finalize();
+      writeTraceTreeToStderr(records);
+    }
+  }
+};
+
+const watchTarget = argvHasWatchFlag(process.argv)
+  ? resolveWatchRunTarget(process.argv)
+  : null;
 
-// oxlint-disable-next-line require-hook -- CLI entry point
-trailhead(app, {
-  description: 'Agent-native, contract-first TypeScript framework',
-  name: 'trails',
-  presets: [outputModePreset()],
-  resolveInput: resolveInputWithClack,
-  version: '0.1.0',
-});
+await (argvHasWatchFlag(process.argv)
+  ? runWatchLoop({
+      readTopoGraphEntryHash: () => readWatchTopoGraphEntryHash(watchTarget),
+      run: runSurfaceOnce,
+      sourcePath: await resolveWatchDirectorySourcePath(watchTarget),
+    })
+  : runSurfaceOnce());

package/src/completions.ts

@@ -0,0 +1,240 @@
+/**
+ * Shell completion infrastructure for the `trails` CLI.
+ *
+ * The completion model is a two-part system:
+ *
+ *  1. A small, static **shell script** registered with the user's shell. The
+ *     script's only job is to invoke the binary's internal completion subcommand
+ *     (`trails completions __complete`) with the partial argv at tab-press time
+ *     and feed the resulting lines back to the shell.
+ *  2. A dynamic **`__complete` trail** that parses the partial argv and emits
+ *     a sorted list of suggestions (e.g. trail IDs).
+ *
+ * This split keeps the shell-side script tiny and standardish (no rich shell
+ * DSL), while the heavy lifting stays in TypeScript where it can reuse the
+ * workspace trail index for accurate, live suggestions.
+ */
+
+import {
+  deriveStructuredTrailExamples,
+  RecoverableCompletionError,
+  Result,
+  ValidationError,
+} from '@ontrails/core';
+import { buildWorkspaceTrailIndex } from '@ontrails/topographer';
+
+import { tryLoadFreshAppLease } from './trails/load-app.js';
+
+/** Shells supported by the completion generator. */
+export type CompletionShell = 'bash' | 'zsh' | 'fish';
+
+type ScriptRenderer = (binName: string) => string;
+
+const renderBashScript: ScriptRenderer = (binName) =>
+  `# ${binName} bash completion
+_${binName}_complete() {
+  local cur words
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  words=("\${COMP_WORDS[@]:1:COMP_CWORD}")
+  COMPREPLY=()
+  while IFS= read -r suggestion; do
+    COMPREPLY+=("$suggestion")
+  done < <(${binName} completions __complete "\${words[@]}" 2>/dev/null)
+  return 0
+}
+complete -F _${binName}_complete ${binName}
+`;
+
+const renderZshScript: ScriptRenderer = (binName) =>
+  `#compdef ${binName}
+# ${binName} zsh completion
+_${binName}_complete() {
+  local -a suggestions trail_words
+  local output
+  trail_words=("\${(@)words[2,CURRENT]}")
+  output="$(${binName} completions __complete "\${trail_words[@]}" 2>/dev/null)"
+  if [[ -n "$output" ]]; then
+    suggestions=("\${(@f)output}")
+    if (( \${#suggestions} )); then
+      compadd -- "\${suggestions[@]}"
+    fi
+  fi
+}
+compdef _${binName}_complete ${binName}
+`;
+
+const renderFishScript: ScriptRenderer = (binName) =>
+  `# ${binName} fish completion
+function __${binName}_complete
+  set -l tokens (commandline -opc) (commandline -ct)
+  set -e tokens[1]
+  ${binName} completions __complete $tokens 2>/dev/null
+end
+complete -c ${binName} -f -a '(__${binName}_complete)'
+`;
+
+const SCRIPT_RENDERERS: Readonly<Record<CompletionShell, ScriptRenderer>> = {
+  bash: renderBashScript,
+  fish: renderFishScript,
+  zsh: renderZshScript,
+};
+
+/** Pattern that `binName` must match — alphanumerics, underscore, hyphen. */
+const BIN_NAME_PATTERN = /^[a-zA-Z0-9_-]+$/;
+
+const recoverableCompletionError = (
+  message: string,
+  context: Record<string, unknown>,
+  cause?: unknown
+): RecoverableCompletionError =>
+  new RecoverableCompletionError(message, {
+    ...(cause instanceof Error ? { cause } : {}),
+    context,
+  });
+
+/**
+ * Render a static shell completion script that delegates dynamic completion
+ * to `<binName> completions __complete <args...>`.
+ *
+ * @param shell - target shell flavor.
+ * @param binName - binary name to register the completion against (typically
+ *   `'trails'`). Used both as the registered command and as the prefix for the
+ *   shell function name. Must match `/^[a-zA-Z0-9_-]+$/` — the value is
+ *   interpolated verbatim into shell source, so any non-trivial input would
+ *   be a shell-injection vector. We validate at the boundary per
+ *   "validate at the boundary, trust internally" (docs/tenets.md).
+ */
+export const renderCompletionScript = (
+  shell: CompletionShell,
+  binName: string
+): Result<string, ValidationError> => {
+  if (!BIN_NAME_PATTERN.test(binName)) {
+    return Result.err(
+      new ValidationError(
+        `renderCompletionScript: binName must match /^[a-zA-Z0-9_-]+$/ (got: ${JSON.stringify(binName)})`
+      )
+    );
+  }
+  return Result.ok(SCRIPT_RENDERERS[shell](binName));
+};
+
+/**
+ * Read trail IDs from the live workspace topo and return those matching
+ * `prefix`, sorted lexicographically. Includes IDs that collide across multiple
+ * apps — the shell only needs the unique set of identifiers, not their owners.
+ *
+ * @param workspaceRoot - workspace root directory used to resolve apps.
+ * @param prefix - prefix to filter by; an empty prefix returns every ID.
+ */
+export const renderTrailIdCompletions = async (
+  workspaceRoot: string,
+  prefix: string
+): Promise<readonly string[]> => {
+  let result: Awaited<ReturnType<typeof buildWorkspaceTrailIndex>>;
+  try {
+    result = await buildWorkspaceTrailIndex({ cwd: workspaceRoot });
+  } catch {
+    return [];
+  }
+  const ids = new Set<string>(Object.keys(result.index));
+  for (const collision of result.collisions) {
+    ids.add(collision.trailId);
+  }
+  const matching: string[] = [];
+  for (const id of ids) {
+    if (id.startsWith(prefix)) {
+      matching.push(id);
+    }
+  }
+  matching.sort((a, b) => {
+    if (a < b) {
+      return -1;
+    }
+    if (a > b) {
+      return 1;
+    }
+    return 0;
+  });
+  return matching;
+};
+
+// ---------------------------------------------------------------------------
+// Example name completion
+// ---------------------------------------------------------------------------
+
+/**
+ * Return example names for `trailId` matching `prefix`, sorted lexicographically.
+ *
+ * Looks the trail up via the workspace index (TRL-404), resolves its owning
+ * app module from the enriched index, loads the app's topo, and reads the
+ * `name` of every structured example.
+ *
+ * Completion is best-effort for shell callers, but this helper preserves
+ * load-time failures as `RecoverableCompletionError` so the internal bridge can
+ * decide whether to suppress them for prompt safety.
+ */
+export const renderTrailExampleCompletions = async (
+  workspaceRoot: string,
+  trailId: string,
+  prefix: string
+): Promise<Result<readonly string[], RecoverableCompletionError>> => {
+  try {
+    const { index } = await buildWorkspaceTrailIndex({ cwd: workspaceRoot });
+    const owner = index[trailId];
+    if (owner === undefined) {
+      return Result.ok([]);
+    }
+    const leaseResult = await tryLoadFreshAppLease(
+      owner.modulePath,
+      workspaceRoot
+    );
+    if (leaseResult.isErr()) {
+      return Result.err(
+        recoverableCompletionError(
+          'Cannot load app while completing example names',
+          { modulePath: owner.modulePath, trailId, workspaceRoot },
+          leaseResult.error
+        )
+      );
+    }
+    const lease = leaseResult.value;
+    try {
+      const target = lease.app.get(trailId);
+      if (target === undefined) {
+        return Result.err(
+          recoverableCompletionError(
+            'Indexed trail was not found in loaded app while completing example names',
+            { modulePath: owner.modulePath, trailId, workspaceRoot }
+          )
+        );
+      }
+      const structured = deriveStructuredTrailExamples(target.examples) ?? [];
+      const matching: string[] = [];
+      for (const example of structured) {
+        if (example.name.startsWith(prefix)) {
+          matching.push(example.name);
+        }
+      }
+      matching.sort((a, b) => {
+        if (a < b) {
+          return -1;
+        }
+        if (a > b) {
+          return 1;
+        }
+        return 0;
+      });
+      return Result.ok(matching);
+    } finally {
+      lease.release();
+    }
+  } catch (error) {
+    return Result.err(
+      recoverableCompletionError(
+        'Cannot resolve workspace while completing example names',
+        { trailId, workspaceRoot },
+        error
+      )
+    );
+  }
+};

package/src/load-app-mirror.ts

@@ -0,0 +1,160 @@
+import { mkdirSync, rmSync } from 'node:fs';
+import {
+  basename,
+  dirname,
+  isAbsolute,
+  join,
+  parse as parsePath,
+  relative,
+  resolve,
+} from 'node:path';
+
+import {
+  deriveSafePath,
+  InternalError,
+  PermissionError,
+  Result,
+  ValidationError,
+} from '@ontrails/core';
+// Result is imported as a value for factories above; this alias keeps returned
+// Result types readable without colliding with the value import.
+import type { Result as TrailsResult } from '@ontrails/core';
+
+export const LOAD_APP_MIRROR_PARENT_DIRNAME = '.trails-tmp';
+
+export const LOAD_APP_MIRROR_ENTRY_PREFIX = 'load-app-fresh-';
+
+const asError = (error: unknown): Error =>
+  error instanceof Error ? error : new Error(String(error));
+
+const validateMirrorRoot = (
+  mirrorRoot: string
+): TrailsResult<string, PermissionError> => {
+  const resolved = resolve(mirrorRoot);
+  const mirrorParent = dirname(resolved);
+
+  return basename(mirrorParent) === LOAD_APP_MIRROR_PARENT_DIRNAME &&
+    basename(resolved).startsWith(LOAD_APP_MIRROR_ENTRY_PREFIX)
+    ? Result.ok(resolved)
+    : Result.err(
+        new PermissionError(
+          `Refusing to write or remove non-load-app mirror path "${mirrorRoot}"`,
+          { context: { mirrorRoot: resolved } }
+        )
+      );
+};
+
+const resolveAbsoluteSourcePath = (
+  sourcePath: string
+): TrailsResult<string, ValidationError> =>
+  isAbsolute(sourcePath)
+    ? Result.ok(sourcePath)
+    : Result.err(
+        new ValidationError(
+          `Load-app mirror source path must be absolute: "${sourcePath}"`,
+          { context: { sourcePath } }
+        )
+      );
+
+/**
+ * Convert an absolute source path to the deterministic location inside a
+ * load-app fresh mirror.
+ */
+export const resolveLoadAppMirrorFilePath = (
+  sourcePath: string,
+  mirrorRoot: string
+): TrailsResult<string, Error> => {
+  const root = validateMirrorRoot(mirrorRoot);
+  if (root.isErr()) {
+    return root;
+  }
+
+  const source = resolveAbsoluteSourcePath(sourcePath);
+  if (source.isErr()) {
+    return source;
+  }
+
+  const mirrorRelativePath = relative(
+    parsePath(source.value).root,
+    source.value
+  );
+  return deriveSafePath(root.value, mirrorRelativePath);
+};
+
+/**
+ * Copy a source file into its load-app fresh mirror by raw bytes.
+ *
+ * @remarks
+ * Reading via `.bytes()` rather than `.text()` preserves binary payloads
+ * (`.wasm`, `.node`, compiled assets) that may sit alongside source files in
+ * the app's graph. Text decoding would corrupt them on the way through the
+ * mirror.
+ */
+export const writeLoadAppMirrorFile = async (
+  sourcePath: string,
+  mirrorRoot: string
+): Promise<TrailsResult<string, Error>> => {
+  const mirrorPath = resolveLoadAppMirrorFilePath(sourcePath, mirrorRoot);
+  if (mirrorPath.isErr()) {
+    return mirrorPath;
+  }
+
+  try {
+    mkdirSync(dirname(mirrorPath.value), { recursive: true });
+    const bytes = await Bun.file(sourcePath).bytes();
+    await Bun.write(mirrorPath.value, bytes);
+    return Result.ok(mirrorPath.value);
+  } catch (error) {
+    return Result.err(
+      new InternalError(`Failed to mirror load-app file "${sourcePath}"`, {
+        cause: asError(error),
+        context: { mirrorPath: mirrorPath.value, mirrorRoot, sourcePath },
+      })
+    );
+  }
+};
+
+export const removeLoadAppMirrorRoot = (
+  mirrorRoot: string
+): TrailsResult<void, Error> => {
+  const root = validateMirrorRoot(mirrorRoot);
+  if (root.isErr()) {
+    return root;
+  }
+
+  try {
+    rmSync(root.value, { force: true, recursive: true });
+    return Result.ok();
+  } catch (error) {
+    return Result.err(
+      new InternalError(`Failed to remove load-app mirror "${mirrorRoot}"`, {
+        cause: asError(error),
+        context: { mirrorRoot: root.value },
+      })
+    );
+  }
+};
+
+/**
+ * Best-effort cleanup for process-exit and stale-sweep paths.
+ *
+ * This intentionally suppresses validation and filesystem failures because the
+ * caller is already abandoning a temporary mirror and cleanup must not turn
+ * into an application-load failure.
+ */
+export const removeLoadAppMirrorRootQuietly = (mirrorRoot: string): void => {
+  try {
+    removeLoadAppMirrorRoot(mirrorRoot);
+  } catch {
+    // Best-effort cleanup must never become the failure path.
+  }
+};
+
+export const createLoadAppMirrorRootPath = (cwd: string): string =>
+  join(
+    resolve(cwd),
+    LOAD_APP_MIRROR_PARENT_DIRNAME,
+    `${LOAD_APP_MIRROR_ENTRY_PREFIX}${Date.now()}-${Math.random()
+      .toString(36)
+      .slice(2)}`
+  );