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

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

package/src/local-state-io.ts

@@ -0,0 +1,153 @@
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, isAbsolute, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import {
+  deriveSafePath,
+  InternalError,
+  Result,
+  ValidationError,
+} from '@ontrails/core';
+import type { Result as TrailsResult } from '@ontrails/core';
+
+const EXAMPLE_ROOT_PARENT = join(tmpdir(), 'ontrails-trails-examples');
+const EXAMPLE_ROOT_NAME_PATTERN = /^[a-z0-9][a-z0-9._-]*$/u;
+
+const asError = (error: unknown): Error =>
+  error instanceof Error ? error : new Error(String(error));
+
+const resolveExampleRoot = (name: string): TrailsResult<string, Error> => {
+  if (!EXAMPLE_ROOT_NAME_PATTERN.test(name)) {
+    return Result.err(
+      new ValidationError(
+        'Example root name must be lowercase and contain only letters, digits, ".", "_", or "-".',
+        { context: { name } }
+      )
+    );
+  }
+
+  return deriveSafePath(EXAMPLE_ROOT_PARENT, name);
+};
+
+export const createIsolatedExampleRoot = (name: string): string => {
+  const root = resolveExampleRoot(name);
+  if (root.isErr()) {
+    throw root.error;
+  }
+
+  try {
+    rmSync(root.value, { force: true, recursive: true });
+    mkdirSync(root.value, { recursive: true });
+    return root.value;
+  } catch (error) {
+    throw new InternalError(`Failed to recreate example root "${name}"`, {
+      cause: asError(error),
+      context: { name, rootDir: root.value },
+    });
+  }
+};
+
+export const writeIsolatedExampleAppModule = (
+  rootDir: string,
+  sourceModulePath: string
+): string => {
+  if (!isAbsolute(sourceModulePath)) {
+    throw new ValidationError(
+      'Example app source module path must be absolute.',
+      {
+        context: { rootDir, sourceModulePath },
+      }
+    );
+  }
+
+  const modulePath = './src/app.ts';
+  const target = deriveSafePath(rootDir, modulePath);
+  if (target.isErr()) {
+    throw target.error;
+  }
+
+  try {
+    mkdirSync(dirname(target.value), { recursive: true });
+    writeFileSync(
+      target.value,
+      `export { app } from ${JSON.stringify(pathToFileURL(sourceModulePath).href)};\n`
+    );
+    return modulePath;
+  } catch (error) {
+    throw new InternalError('Failed to write isolated example app module', {
+      cause: asError(error),
+      context: { rootDir, sourceModulePath, targetPath: target.value },
+    });
+  }
+};
+
+export const writeIsolatedExampleJsonFile = (
+  rootDir: string,
+  relativePath: string,
+  value: unknown
+): string => {
+  const target = deriveSafePath(rootDir, relativePath);
+  if (target.isErr()) {
+    throw target.error;
+  }
+
+  try {
+    mkdirSync(dirname(target.value), { recursive: true });
+    writeFileSync(target.value, `${JSON.stringify(value, null, 2)}\n`);
+    return relativePath;
+  } catch (error) {
+    throw new InternalError('Failed to write isolated example JSON file', {
+      cause: asError(error),
+      context: { relativePath, rootDir, targetPath: target.value },
+    });
+  }
+};
+
+export const writeIsolatedExampleTextFile = (
+  rootDir: string,
+  relativePath: string,
+  contents: string
+): string => {
+  const target = deriveSafePath(rootDir, relativePath);
+  if (target.isErr()) {
+    throw target.error;
+  }
+
+  try {
+    mkdirSync(dirname(target.value), { recursive: true });
+    writeFileSync(target.value, contents);
+    return relativePath;
+  } catch (error) {
+    throw new InternalError('Failed to write isolated example text file', {
+      cause: asError(error),
+      context: { relativePath, rootDir, targetPath: target.value },
+    });
+  }
+};
+
+export const removeRootRelativeFileIfPresent = (
+  rootDir: string,
+  relativePath: string
+): TrailsResult<boolean, Error> => {
+  const target = deriveSafePath(rootDir, relativePath);
+  if (target.isErr()) {
+    return target;
+  }
+
+  if (!existsSync(target.value)) {
+    return Result.ok(false);
+  }
+
+  try {
+    rmSync(target.value, { force: true });
+    return Result.ok(true);
+  } catch (error) {
+    return Result.err(
+      new InternalError(`Failed to remove local state file "${relativePath}"`, {
+        cause: asError(error),
+        context: { relativePath, rootDir, targetPath: target.value },
+      })
+    );
+  }
+};