@ontrails/trails 1.0.0-beta.4 → 1.0.0-beta.41

package/src/mcp-options.ts

@@ -0,0 +1,91 @@
+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',
+  '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;
+};

package/src/regrade/config.ts

@@ -0,0 +1,152 @@
+import { loadTrailsConfigValue } from '@ontrails/config';
+import {
+  InternalError,
+  Result,
+  ValidationError,
+  pathScopeSchema,
+} from '@ontrails/core';
+import type { Result as TrailsResult } from '@ontrails/core';
+import { z } from 'zod';
+
+export const regradeConfigSchema = z
+  .object({
+    scope: pathScopeSchema.optional(),
+  })
+  .default({});
+
+export type RegradeConfig = z.output<typeof regradeConfigSchema>;
+
+interface RegradeConfigLoadResult {
+  readonly config?: RegradeConfig;
+  readonly configPath?: string;
+}
+
+interface ResolvableConfig {
+  readonly resolve: (options?: {
+    readonly cwd?: string;
+    readonly env?: Record<string, string | undefined>;
+  }) => unknown;
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const isResultLike = (
+  value: unknown
+): value is {
+  readonly error?: unknown;
+  readonly isErr: () => boolean;
+  readonly isOk: () => boolean;
+  readonly value?: unknown;
+} =>
+  isRecord(value) &&
+  typeof value['isOk'] === 'function' &&
+  typeof value['isErr'] === 'function';
+
+const isResolvableConfig = (value: unknown): value is ResolvableConfig =>
+  isRecord(value) && typeof value['resolve'] === 'function';
+
+const errorMessage = (error: unknown): string =>
+  error instanceof Error ? error.message : String(error);
+
+const extractRegradeConfig = (
+  value: unknown
+): TrailsResult<RegradeConfig | undefined, ValidationError> => {
+  if (!(isRecord(value) && 'regrade' in value)) {
+    return Result.ok();
+  }
+
+  const parsed = regradeConfigSchema.safeParse(value['regrade']);
+  if (parsed.success) {
+    return Result.ok(parsed.data);
+  }
+
+  return Result.err(
+    new ValidationError('Invalid regrade config in Trails config file.', {
+      context: { issues: parsed.error.issues },
+    })
+  );
+};
+
+export const loadRegradeConfig = async ({
+  configPath,
+  env = {},
+  rootDir,
+}: {
+  readonly configPath?: string | undefined;
+  readonly env?: Record<string, string | undefined> | undefined;
+  readonly rootDir: string;
+}): Promise<
+  TrailsResult<RegradeConfigLoadResult, InternalError | ValidationError>
+> => {
+  try {
+    const loaded = await loadTrailsConfigValue({
+      configPath,
+      rootDir,
+    });
+    const exported = loaded.value;
+    if (exported === undefined) {
+      return Result.ok({});
+    }
+
+    if (isResolvableConfig(exported)) {
+      const resolved = await exported.resolve({ cwd: rootDir, env });
+      if (isResultLike(resolved)) {
+        if (resolved.isErr()) {
+          return Result.err(
+            new InternalError(
+              `Failed to resolve regrade config: ${errorMessage(resolved.error)}`
+            )
+          );
+        }
+        const configResult = extractRegradeConfig(resolved.value);
+        if (configResult.isErr()) {
+          return configResult;
+        }
+        return Result.ok({
+          ...(configResult.value === undefined
+            ? {}
+            : { config: configResult.value }),
+          ...(loaded.configPath === undefined
+            ? {}
+            : { configPath: loaded.configPath }),
+        });
+      }
+
+      const configResult = extractRegradeConfig(resolved);
+      if (configResult.isErr()) {
+        return configResult;
+      }
+      return Result.ok({
+        ...(configResult.value === undefined
+          ? {}
+          : { config: configResult.value }),
+        ...(loaded.configPath === undefined
+          ? {}
+          : { configPath: loaded.configPath }),
+      });
+    }
+
+    const configResult = extractRegradeConfig(exported);
+    if (configResult.isErr()) {
+      return configResult;
+    }
+    return Result.ok({
+      ...(configResult.value === undefined
+        ? {}
+        : { config: configResult.value }),
+      ...(loaded.configPath === undefined
+        ? {}
+        : { configPath: loaded.configPath }),
+    });
+  } catch (error) {
+    return Result.err(
+      new InternalError(
+        `Failed to load regrade config: ${errorMessage(error)}`,
+        {
+          cause: error instanceof Error ? error : new Error(String(error)),
+        }
+      )
+    );
+  }
+};