@ontrails/trails 0.2.0

package/src/local-state-io.ts

@@ -0,0 +1,129 @@
+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 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 },
+      })
+    );
+  }
+};
+
+export const removeFileIfPresent = (
+  path: string
+): TrailsResult<boolean, Error> => {
+  if (!existsSync(path)) {
+    return Result.ok(false);
+  }
+
+  try {
+    rmSync(path, { force: true });
+    return Result.ok(true);
+  } catch (error) {
+    return Result.err(
+      new InternalError(`Failed to remove local state file "${path}"`, {
+        cause: asError(error),
+        context: { path },
+      })
+    );
+  }
+};

package/src/mcp-app.ts

@@ -0,0 +1,42 @@
+import { topo } from '@ontrails/core';
+import {
+  wayfindAdaptersTrail,
+  wayfindContractTrail,
+  wayfindDescribeTrail,
+  wayfindErrorsTrail,
+  wayfindExamplesTrail,
+  wayfindOverlayTrail,
+  wayfindImpactTrail,
+  wayfindNearbyTrail,
+  wayfindOverviewTrail,
+  wayfindResourcesTrail,
+  wayfindSearchTrail,
+  wayfindSurfacesTrail,
+  wayfindTrailsTrail,
+} from '@ontrails/topography';
+
+import { operatorApp } from './app.js';
+import { wayfindDiffTrail } from './trails/wayfind.js';
+import { wayfindOutlineTrail } from './trails/wayfind-outline.js';
+
+const operatorTrails = Object.fromEntries(
+  operatorApp.list().map((trailItem) => [trailItem.id, trailItem])
+);
+
+export const trailsMcpApp = topo('trails', operatorTrails, {
+  wayfindAdaptersTrail,
+  wayfindContractTrail,
+  wayfindDescribeTrail,
+  wayfindDiffTrail,
+  wayfindErrorsTrail,
+  wayfindExamplesTrail,
+  wayfindImpactTrail,
+  wayfindNearbyTrail,
+  wayfindOutlineTrail,
+  wayfindOverlayTrail,
+  wayfindOverviewTrail,
+  wayfindResourcesTrail,
+  wayfindSearchTrail,
+  wayfindSurfacesTrail,
+  wayfindTrailsTrail,
+});

package/src/mcp-options.ts

@@ -0,0 +1,92 @@
+import type {
+  CreateServerOptions,
+  McpSurfaceTrailheadMap,
+} from '@ontrails/mcp';
+
+import { trailsOverlays } from './app.js';
+
+export const trailsMcpIncludedTrails = [
+  'adapter.check',
+  'add.surface',
+  'add.trail',
+  'compile',
+  'create',
+  'create.adapter',
+  'deprecate',
+  'dev.clean',
+  'dev.reset',
+  'dev.stats',
+  'doctor',
+  'draft.promote',
+  'guide',
+  'adjust.regrade',
+  'apply.regrade',
+  'audit.regrade',
+  'check.regrade',
+  'list.regrades',
+  'plan.regrade',
+  'preview.regrade',
+  'release.check',
+  'release.smoke',
+  'revise',
+  'run',
+  'run.example',
+  'run.examples',
+  'survey',
+  'survey.brief',
+  'survey.diff',
+  'survey.resource',
+  'survey.signal',
+  'survey.surfaces',
+  'survey.trail',
+  'topo',
+  'topo.history',
+  'topo.pin',
+  'topo.unpin',
+  'validate',
+  'warden',
+  'warden.guide',
+  'wayfind.adapters',
+  'wayfind.contract',
+  'wayfind.diff',
+  'wayfind.errors',
+  'wayfind.examples',
+  'wayfind.impact',
+  'wayfind.nearby',
+  'wayfind.overview',
+  'wayfind.search',
+  'wayfind.trails',
+] as const;
+
+export const trailsMcpTrailheads = {
+  inspect: {
+    description:
+      'Inspect saved topo structure, resources, signals, surfaces, and diffs.',
+    mcp: { loading: 'deferred' },
+    trails: [
+      'survey',
+      'topo',
+      'guide',
+      'survey.brief',
+      'survey.diff',
+      'survey.resource',
+      'survey.signal',
+      'survey.surfaces',
+      'survey.trail',
+      'topo.history',
+    ],
+  },
+} satisfies McpSurfaceTrailheadMap;
+
+export const trailsMcpSurfaceOptions = {
+  description:
+    'Trails framework operator surface. Use MCP resources for cold context, direct tools for high-signal work, and the inspect trailhead for saved topo reads.',
+  include: trailsMcpIncludedTrails,
+  mcpResources: { examples: true, graph: true, surfaceMap: true },
+  name: 'trails',
+  // The overlay authors the lockable `inspect` default; the call-site map
+  // below is the runtime override-in-context with richer metadata
+  // (description, deferred loading) over the same member selectors.
+  overlays: trailsOverlays,
+  trailheads: trailsMcpTrailheads,
+} satisfies CreateServerOptions;

package/src/mcp.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env bun
+/* oxlint-disable eslint-plugin-jest/require-hook -- MCP stdio entrypoints execute at module scope */
+import { surface } from '@ontrails/mcp';
+
+import { trailsMcpApp } from './mcp-app.js';
+import { trailsMcpSurfaceOptions } from './mcp-options.js';
+
+await surface(trailsMcpApp, trailsMcpSurfaceOptions);

package/src/project-writes.ts

@@ -0,0 +1,377 @@
+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;
+    };
+
+interface ProjectOperationOptions {
+  readonly existing?: 'overwrite' | 'preserve';
+}
+
+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 from;
+  }
+
+  const to = resolveProjectPath(projectDir, toPath);
+  if (to.isErr()) {
+    return to;
+  }
+
+  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 },
+        })
+      );
+    }
+  }
+};
+
+const shouldApplyProjectOperation = (
+  projectDir: string,
+  operation: ProjectWriteOperation,
+  options: ProjectOperationOptions
+): TrailsResult<boolean, Error> => {
+  if (options.existing !== 'preserve' || operation.kind === 'rename') {
+    return Result.ok(true);
+  }
+
+  const { path } = operation;
+  const target = resolveProjectPath(projectDir, path);
+  if (target.isErr()) {
+    return target;
+  }
+
+  return Result.ok(!existsSync(target.value));
+};
+
+const selectProjectOperations = (
+  projectDir: string,
+  operations: readonly ProjectWriteOperation[],
+  options: ProjectOperationOptions
+): TrailsResult<ProjectWriteOperation[], Error> => {
+  const selected: ProjectWriteOperation[] = [];
+  for (const operation of operations) {
+    const shouldApply = shouldApplyProjectOperation(
+      projectDir,
+      operation,
+      options
+    );
+    if (shouldApply.isErr()) {
+      return shouldApply;
+    }
+    if (shouldApply.value) {
+      selected.push(operation);
+    }
+  }
+
+  return Result.ok(selected);
+};
+
+export const planProjectOperations = (
+  projectDir: string,
+  operations: readonly ProjectWriteOperation[],
+  options: ProjectOperationOptions = {}
+): TrailsResult<PlannedProjectOperation[], Error> => {
+  const selected = selectProjectOperations(projectDir, operations, options);
+  if (selected.isErr()) {
+    return selected;
+  }
+
+  const planned: PlannedProjectOperation[] = [];
+  for (const operation of selected.value) {
+    const result = planProjectOperation(projectDir, operation);
+    if (result.isErr()) {
+      return result;
+    }
+    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 target;
+      }
+      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 target;
+      }
+      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[],
+  options: ProjectOperationOptions = {}
+): Promise<TrailsResult<PlannedProjectOperation[], Error>> => {
+  const selected = selectProjectOperations(projectDir, operations, options);
+  if (selected.isErr()) {
+    return selected;
+  }
+
+  const planned = planProjectOperations(projectDir, selected.value);
+  if (planned.isErr()) {
+    return planned;
+  }
+
+  for (const operation of selected.value) {
+    const applied = await applyProjectOperation(projectDir, operation);
+    if (applied.isErr()) {
+      return applied;
+    }
+  }
+
+  return planned;
+};