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

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

package/src/project-writes.ts

@@ -0,0 +1,320 @@
+import { existsSync, mkdirSync, renameSync } from 'node:fs';
+import { dirname, relative, resolve } from 'node:path';
+
+import {
+  DRAFT_ID_PREFIX,
+  deriveSafePath,
+  InternalError,
+  Result,
+  ValidationError,
+} from '@ontrails/core';
+import type { Result as TrailsResult } from '@ontrails/core';
+
+export const PROJECT_NAME_PATTERN = /^[a-z0-9][a-z0-9._-]*$/u;
+export const PROJECT_NAME_MESSAGE =
+  'Project name must start with a lowercase letter or digit and contain only lowercase letters, digits, ".", "_", or "-".';
+
+export const TRAIL_ID_PATTERN =
+  /^(?:_draft\.)?[a-z][a-z0-9]*(?:\.[a-z][a-z0-9]*)*$/u;
+export const TRAIL_ID_MESSAGE =
+  'Trail ID must be lowercase dotted segments, optionally prefixed with "_draft.", with each non-draft segment starting with a letter and containing only letters or digits.';
+
+const asError = (error: unknown): Error =>
+  error instanceof Error ? error : new Error(String(error));
+
+export type PlannedProjectOperation =
+  | { readonly kind: 'mkdir'; readonly path: string }
+  | { readonly kind: 'rename'; readonly from: string; readonly to: string }
+  | { readonly kind: 'write'; readonly path: string };
+
+export type ProjectWriteOperation =
+  | { readonly kind: 'mkdir'; readonly path: string }
+  | { readonly kind: 'rename'; readonly from: string; readonly to: string }
+  | {
+      readonly content: string | Uint8Array;
+      readonly kind: 'write';
+      readonly path: string;
+    };
+
+export const validateProjectName = (
+  name: string
+): TrailsResult<string, ValidationError> =>
+  PROJECT_NAME_PATTERN.test(name)
+    ? Result.ok(name)
+    : Result.err(new ValidationError(PROJECT_NAME_MESSAGE));
+
+export const validateTrailId = (
+  trailId: string
+): TrailsResult<string, ValidationError> =>
+  TRAIL_ID_PATTERN.test(trailId)
+    ? Result.ok(trailId)
+    : Result.err(new ValidationError(TRAIL_ID_MESSAGE));
+
+export const trailIdToModuleName = (trailId: string): string =>
+  trailId.startsWith(DRAFT_ID_PREFIX)
+    ? `${DRAFT_ID_PREFIX}${trailId.slice(DRAFT_ID_PREFIX.length).replaceAll('.', '-')}`
+    : trailId.replaceAll('.', '-');
+
+export const trailIdToExportName = (trailId: string): string =>
+  trailId.replaceAll('.', '_');
+
+export const resolveProjectDir = (
+  parentDir: string,
+  projectName: string
+): TrailsResult<string, Error> => {
+  const validated = validateProjectName(projectName);
+  if (validated.isErr()) {
+    return validated;
+  }
+
+  return deriveSafePath(resolve(parentDir), validated.value);
+};
+
+export const resolveProjectPath = (
+  projectDir: string,
+  relativePath: string
+): TrailsResult<string, Error> => deriveSafePath(projectDir, relativePath);
+
+export const projectPathExists = (
+  projectDir: string,
+  pathWithinProject: string
+): TrailsResult<boolean, Error> => {
+  const target = resolveProjectPath(projectDir, pathWithinProject);
+  if (target.isErr()) {
+    return target;
+  }
+
+  return Result.ok(existsSync(target.value));
+};
+
+/** Write a generated project-relative file and return the relative path. */
+export const writeProjectFile = async (
+  projectDir: string,
+  relativePath: string,
+  content: string | Uint8Array
+): Promise<TrailsResult<string, Error>> => {
+  const target = resolveProjectPath(projectDir, relativePath);
+  if (target.isErr()) {
+    return target;
+  }
+
+  try {
+    mkdirSync(dirname(target.value), { recursive: true });
+    await Bun.write(target.value, content);
+    return Result.ok(relativePath);
+  } catch (error) {
+    return Result.err(
+      new InternalError(`Failed to write project file "${relativePath}"`, {
+        cause: asError(error),
+        context: { projectDir, relativePath },
+      })
+    );
+  }
+};
+
+/** Write an already-derived path that must stay contained under the project. */
+export const writeContainedProjectPath = async (
+  projectDir: string,
+  pathWithinProject: string,
+  content: string | Uint8Array
+): Promise<TrailsResult<string, Error>> => {
+  const target = resolveProjectPath(projectDir, pathWithinProject);
+  if (target.isErr()) {
+    return target;
+  }
+
+  try {
+    mkdirSync(dirname(target.value), { recursive: true });
+    await Bun.write(target.value, content);
+    return Result.ok(target.value);
+  } catch (error) {
+    return Result.err(
+      new InternalError(
+        `Failed to write contained project path "${pathWithinProject}"`,
+        {
+          cause: asError(error),
+          context: { pathWithinProject, projectDir },
+        }
+      )
+    );
+  }
+};
+
+export const renameContainedProjectPath = (
+  projectDir: string,
+  fromPath: string,
+  toPath: string
+): TrailsResult<void, Error> => {
+  const from = resolveProjectPath(projectDir, fromPath);
+  if (from.isErr()) {
+    return Result.err(from.error);
+  }
+
+  const to = resolveProjectPath(projectDir, toPath);
+  if (to.isErr()) {
+    return Result.err(to.error);
+  }
+
+  try {
+    renameSync(from.value, to.value);
+    return Result.ok();
+  } catch (error) {
+    return Result.err(
+      new InternalError(
+        `Failed to rename contained project path "${fromPath}"`,
+        {
+          cause: asError(error),
+          context: { fromPath, projectDir, toPath },
+        }
+      )
+    );
+  }
+};
+
+const toProjectRelativePath = (
+  projectDir: string,
+  pathWithinProject: string
+): TrailsResult<string, Error> => {
+  const target = resolveProjectPath(projectDir, pathWithinProject);
+  if (target.isErr()) {
+    return target;
+  }
+
+  return Result.ok(
+    relative(resolve(projectDir), target.value).replaceAll('\\', '/')
+  );
+};
+
+export const planProjectOperation = (
+  projectDir: string,
+  operation: ProjectWriteOperation
+): TrailsResult<PlannedProjectOperation, Error> => {
+  switch (operation.kind) {
+    case 'mkdir': {
+      const path = toProjectRelativePath(projectDir, operation.path);
+      return path.isErr()
+        ? path
+        : Result.ok({ kind: 'mkdir', path: path.value });
+    }
+    case 'rename': {
+      const from = toProjectRelativePath(projectDir, operation.from);
+      if (from.isErr()) {
+        return from;
+      }
+      const to = toProjectRelativePath(projectDir, operation.to);
+      return to.isErr()
+        ? to
+        : Result.ok({ from: from.value, kind: 'rename', to: to.value });
+    }
+    case 'write': {
+      const path = toProjectRelativePath(projectDir, operation.path);
+      return path.isErr()
+        ? path
+        : Result.ok({ kind: 'write', path: path.value });
+    }
+    default: {
+      return Result.err(
+        new InternalError('Unknown project operation kind', {
+          context: { operation },
+        })
+      );
+    }
+  }
+};
+
+export const planProjectOperations = (
+  projectDir: string,
+  operations: readonly ProjectWriteOperation[]
+): TrailsResult<PlannedProjectOperation[], Error> => {
+  const planned: PlannedProjectOperation[] = [];
+  for (const operation of operations) {
+    const result = planProjectOperation(projectDir, operation);
+    if (result.isErr()) {
+      return Result.err(result.error);
+    }
+    planned.push(result.value);
+  }
+  return Result.ok(planned);
+};
+
+const applyProjectOperation = async (
+  projectDir: string,
+  operation: ProjectWriteOperation
+): Promise<TrailsResult<void, Error>> => {
+  switch (operation.kind) {
+    case 'mkdir': {
+      const target = resolveProjectPath(projectDir, operation.path);
+      if (target.isErr()) {
+        return Result.err(target.error);
+      }
+      try {
+        mkdirSync(target.value, { recursive: true });
+        return Result.ok();
+      } catch (error) {
+        return Result.err(
+          new InternalError(
+            `Failed to create project directory "${operation.path}"`,
+            {
+              cause: asError(error),
+              context: { projectDir, relativePath: operation.path },
+            }
+          )
+        );
+      }
+    }
+    case 'rename': {
+      return renameContainedProjectPath(
+        projectDir,
+        operation.from,
+        operation.to
+      );
+    }
+    case 'write': {
+      const target = resolveProjectPath(projectDir, operation.path);
+      if (target.isErr()) {
+        return Result.err(target.error);
+      }
+      try {
+        mkdirSync(dirname(target.value), { recursive: true });
+        await Bun.write(target.value, operation.content);
+        return Result.ok();
+      } catch (error) {
+        return Result.err(
+          new InternalError(
+            `Failed to write project file "${operation.path}"`,
+            {
+              cause: asError(error),
+              context: { projectDir, relativePath: operation.path },
+            }
+          )
+        );
+      }
+    }
+    default: {
+      return Result.err(
+        new InternalError('Unknown project operation kind', {
+          context: { operation },
+        })
+      );
+    }
+  }
+};
+
+export const applyProjectOperations = async (
+  projectDir: string,
+  operations: readonly ProjectWriteOperation[]
+): Promise<TrailsResult<PlannedProjectOperation[], Error>> => {
+  const planned = planProjectOperations(projectDir, operations);
+  if (planned.isErr()) {
+    return Result.err(planned.error);
+  }
+
+  for (const operation of operations) {
+    const applied = await applyProjectOperation(projectDir, operation);
+    if (applied.isErr()) {
+      return Result.err(applied.error);
+    }
+  }
+
+  return planned;
+};

package/src/run-collision.ts

@@ -0,0 +1,125 @@
+/**
+ * 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), {
+    topo: deps.graph,
+  });
+};