@ontrails/trails 0.2.0

package/src/completions.ts

@@ -0,0 +1,431 @@
+/**
+ * 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
+ * Config-owned app identities and live topos for accurate suggestions.
+ */
+
+import {
+  deriveStructuredTrailExamples,
+  RecoverableCompletionError,
+  Result,
+  ValidationError,
+} from '@ontrails/core';
+import { readTrailsProjectIdentity } from '@ontrails/config';
+
+import { tryLoadFreshAppLease } from './trails/load-app.js';
+
+interface CompletionApp {
+  readonly configured: boolean;
+  readonly id: string;
+  readonly modulePath: string | undefined;
+  readonly rootDir: string;
+}
+
+interface UnavailableCompletionApp {
+  readonly appId: string;
+  readonly error: Error;
+}
+
+interface CompletionOwnershipView {
+  readonly owners: ReadonlyMap<string, readonly string[]>;
+  readonly unavailableApps: readonly UnavailableCompletionApp[];
+}
+
+const completionApps = async (
+  workspaceRoot: string,
+  selectedAppId?: string | undefined,
+  selectedModulePath?: string | undefined
+): Promise<readonly CompletionApp[]> => {
+  const identity = await readTrailsProjectIdentity({
+    boundaryDir: workspaceRoot,
+    startDir: workspaceRoot,
+  });
+  return identity.workspace === undefined
+    ? [
+        {
+          configured: false,
+          id: 'standalone',
+          modulePath: selectedModulePath,
+          rootDir: identity.rootDir,
+        },
+      ]
+    : identity.apps
+        .filter(
+          (app) => selectedAppId === undefined || app.id === selectedAppId
+        )
+        .map((app) => ({
+          configured: true,
+          id: app.id,
+          modulePath:
+            app.id === selectedAppId && selectedModulePath !== undefined
+              ? selectedModulePath
+              : app.entry,
+          rootDir: app.rootDir,
+        }));
+};
+
+const completionOwners = async (
+  workspaceRoot: string,
+  trailId?: string | undefined,
+  selectedAppId?: string | undefined,
+  selectedModulePath?: string | undefined
+): Promise<CompletionOwnershipView> => {
+  const owners = new Map<string, string[]>();
+  const unavailableApps: UnavailableCompletionApp[] = [];
+  for (const app of await completionApps(
+    workspaceRoot,
+    selectedAppId,
+    selectedModulePath
+  )) {
+    const loaded = await tryLoadFreshAppLease(app.modulePath, app.rootDir);
+    if (loaded.isErr()) {
+      unavailableApps.push({ appId: app.id, error: loaded.error });
+      continue;
+    }
+    const lease = loaded.value;
+    try {
+      if (app.configured && lease.app.name !== app.id) {
+        unavailableApps.push({
+          appId: app.id,
+          error: new ValidationError(
+            `Configured app "${app.id}" loaded topo "${lease.app.name}" while completing shell input.`
+          ),
+        });
+        continue;
+      }
+      const ids = trailId === undefined ? lease.app.ids() : [trailId];
+      for (const id of ids) {
+        if (lease.app.get(id) === undefined) {
+          continue;
+        }
+        const current = owners.get(id) ?? [];
+        current.push(app.id);
+        owners.set(id, current);
+      }
+    } finally {
+      lease.release();
+    }
+  }
+  return { owners, unavailableApps };
+};
+
+/** 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 word
+  local -a words completion_args
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  words=("\${COMP_WORDS[@]:1:COMP_CWORD}")
+  completion_args=()
+  for word in "\${words[@]}"; do
+    completion_args+=("--args=$word")
+  done
+  COMPREPLY=()
+  while IFS= read -r suggestion; do
+    COMPREPLY+=("$suggestion")
+  done < <(${binName} completions __complete "\${completion_args[@]}" 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 completion_args
+  local output
+  local trail_word
+  trail_words=("\${(@)words[2,CURRENT]}")
+  completion_args=()
+  for trail_word in "\${trail_words[@]}"; do
+    completion_args+=("--args=$trail_word")
+  done
+  output="$(${binName} completions __complete "\${completion_args[@]}" 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 prior_tokens (commandline -opc)
+  set -e prior_tokens[1]
+  set -l completion_args
+  for token in $prior_tokens
+    set -a completion_args "--args=$token"
+  end
+  set -l current_token (commandline -ct)
+  if test (count $current_token) -eq 0
+    set -a completion_args --args=
+  else
+    set -a completion_args "--args=$current_token[1]"
+  end
+  ${binName} completions __complete $completion_args 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=<token>...`.
+ *
+ * @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,
+  selectedAppId?: string | undefined,
+  selectedModulePath?: string | undefined
+): Promise<readonly string[]> => {
+  let owners: ReadonlyMap<string, readonly string[]>;
+  try {
+    const ownership = await completionOwners(
+      workspaceRoot,
+      undefined,
+      selectedAppId,
+      selectedModulePath
+    );
+    ({ owners } = ownership);
+  } catch {
+    return [];
+  }
+  const matching: string[] = [];
+  for (const id of owners.keys()) {
+    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;
+};
+
+/** Return Config-owned app IDs matching a shell prefix. */
+export const renderAppIdCompletions = async (
+  workspaceRoot: string,
+  prefix: string
+): Promise<readonly string[]> => {
+  try {
+    const apps = await completionApps(workspaceRoot);
+    return apps
+      .filter((app) => app.configured && app.id.startsWith(prefix))
+      .map((app) => app.id)
+      .toSorted();
+  } catch {
+    return [];
+  }
+};
+
+// ---------------------------------------------------------------------------
+// Example name completion
+// ---------------------------------------------------------------------------
+
+/**
+ * Return example names for `trailId` matching `prefix`, sorted lexicographically.
+ *
+ * Resolves Config-owned app identity, requires one live owner, loads that app,
+ * 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,
+  selectedAppId?: string | undefined,
+  selectedModulePath?: string | undefined
+): Promise<Result<readonly string[], RecoverableCompletionError>> => {
+  try {
+    const ownership = await completionOwners(
+      workspaceRoot,
+      trailId,
+      selectedAppId,
+      selectedModulePath
+    );
+    const appIds = ownership.owners.get(trailId) ?? [];
+    if (appIds.length === 0 && ownership.unavailableApps.length > 0) {
+      const [firstUnavailable] = ownership.unavailableApps;
+      return Result.err(
+        recoverableCompletionError(
+          'Cannot determine a live owner while completing example names',
+          {
+            trailId,
+            unavailableAppIds: ownership.unavailableApps.map(
+              (app) => app.appId
+            ),
+            workspaceRoot,
+          },
+          firstUnavailable?.error
+        )
+      );
+    }
+    if (appIds.length !== 1) {
+      return Result.ok([]);
+    }
+    const [ownerId] = appIds;
+    const apps = await completionApps(
+      workspaceRoot,
+      selectedAppId,
+      selectedModulePath
+    );
+    const owner = apps.find((app) => app.id === ownerId);
+    if (owner === undefined) {
+      return Result.ok([]);
+    }
+    const leaseResult = await tryLoadFreshAppLease(
+      owner.modulePath,
+      owner.rootDir
+    );
+    if (leaseResult.isErr()) {
+      return Result.err(
+        recoverableCompletionError(
+          'Cannot load app while completing example names',
+          {
+            appId: owner.id,
+            modulePath: owner.modulePath,
+            trailId,
+            workspaceRoot,
+          },
+          leaseResult.error
+        )
+      );
+    }
+    const lease = leaseResult.value;
+    try {
+      if (owner.configured && lease.app.name !== owner.id) {
+        return Result.err(
+          recoverableCompletionError(
+            'Configured app identity does not match its loaded topo while completing example names',
+            {
+              actualAppId: lease.app.name,
+              expectedAppId: owner.id,
+              modulePath: owner.modulePath,
+              trailId,
+              workspaceRoot,
+            }
+          )
+        );
+      }
+      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',
+            {
+              appId: owner.id,
+              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/lifecycle-source-io.ts

@@ -0,0 +1,33 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+
+import { InternalError, Result } from '@ontrails/core';
+
+export const readLifecycleSourceFile = (
+  filePath: string
+): Result<string, Error> => {
+  try {
+    return Result.ok(readFileSync(filePath, 'utf8'));
+  } catch (error: unknown) {
+    return Result.err(
+      error instanceof Error
+        ? error
+        : new InternalError(`Unable to read lifecycle source file ${filePath}`)
+    );
+  }
+};
+
+export const writeLifecycleSourceFile = (
+  filePath: string,
+  source: string
+): Result<void, Error> => {
+  try {
+    writeFileSync(filePath, source);
+    return Result.ok();
+  } catch (error: unknown) {
+    return Result.err(
+      error instanceof Error
+        ? error
+        : new InternalError(`Unable to write lifecycle source file ${filePath}`)
+    );
+  }
+};

package/src/load-app-mirror.ts

@@ -0,0 +1,202 @@
+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 isPathInside = (root: string, target: string): boolean => {
+  const candidate = relative(root, target);
+  return (
+    candidate === '' || (!candidate.startsWith('..') && !isAbsolute(candidate))
+  );
+};
+
+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 } }
+        )
+      );
+
+export const ensureLoadAppMirrorDirectory = (
+  directoryPath: string,
+  mirrorRoot: string
+): TrailsResult<void, Error> => {
+  const root = validateMirrorRoot(mirrorRoot);
+  if (root.isErr()) {
+    return root;
+  }
+
+  const target = resolve(directoryPath);
+  if (!isPathInside(root.value, target)) {
+    return Result.err(
+      new PermissionError(
+        `Refusing to create load-app mirror directory outside "${root.value}"`,
+        { context: { directoryPath: target, mirrorRoot: root.value } }
+      )
+    );
+  }
+
+  try {
+    mkdirSync(target, { recursive: true });
+    return Result.ok();
+  } catch (error) {
+    return Result.err(
+      new InternalError(
+        `Failed to create load-app mirror directory "${target}"`,
+        {
+          cause: asError(error),
+          context: { directoryPath: target, mirrorRoot: root.value },
+        }
+      )
+    );
+  }
+};
+
+/**
+ * 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)}`
+  );