@ontrails/trails 1.0.0-beta.0

package/src/app.ts

@@ -0,0 +1,22 @@
+import { topo } from '@ontrails/core';
+
+import * as addSurface from './trails/add-surface.js';
+import * as addTrail from './trails/add-trail.js';
+import * as addVerify from './trails/add-verify.js';
+import * as create from './trails/create.js';
+import * as createScaffold from './trails/create-scaffold.js';
+import * as guide from './trails/guide.js';
+import * as survey from './trails/survey.js';
+import * as warden from './trails/warden.js';
+
+export const app = topo(
+  'trails',
+  survey,
+  guide,
+  warden,
+  create,
+  createScaffold,
+  addSurface,
+  addVerify,
+  addTrail
+);

package/src/clack.ts

@@ -0,0 +1,89 @@
+/**
+ * Clack-backed input resolver for the Trails CLI.
+ *
+ * This stays at the app layer so @ontrails/cli remains prompt-library agnostic.
+ */
+
+import type { Field, InputResolver, ResolveInputOptions } from '@ontrails/cli';
+import { isInteractive } from '@ontrails/cli';
+import * as clack from '@clack/prompts';
+
+/** Check whether a field still needs input. */
+const needsInput = (field: Field, current: Record<string, unknown>): boolean =>
+  current[field.name] === undefined &&
+  field.required &&
+  field.default === undefined;
+
+/** Build Clack options from field options. */
+const toClackOptions = (field: Field) =>
+  field.options?.map((option) => ({
+    ...(option.hint === undefined ? {} : { hint: option.hint }),
+    label: option.label ?? option.value,
+    value: option.value,
+  })) ?? [];
+
+/** Normalize cancelled prompts to `undefined`. */
+const cancelable = async <T>(value: T | symbol): Promise<T | undefined> =>
+  await (clack.isCancel(value) ? undefined : value);
+
+type FieldResolver = (field: Field) => Promise<unknown>;
+
+const fieldResolvers: Record<Field['type'], FieldResolver> = {
+  boolean: async (field) =>
+    cancelable(
+      await clack.confirm({
+        initialValue: (field.default as boolean | undefined) ?? false,
+        message: field.label,
+      })
+    ),
+  enum: async (field) =>
+    cancelable(
+      await clack.select({
+        message: field.label,
+        options: toClackOptions(field),
+      })
+    ),
+  multiselect: async (field) =>
+    cancelable(
+      await clack.multiselect({
+        initialValues: (field.default as string[] | undefined) ?? [],
+        message: field.label,
+        options: toClackOptions(field),
+      })
+    ),
+  number: async (field) => {
+    const raw = await clack.text({ message: field.label });
+    return clack.isCancel(raw) ? undefined : Number(raw);
+  },
+  string: async (field) =>
+    cancelable(await clack.text({ message: field.label })),
+};
+
+/** Resolve a single field value with Clack. */
+const resolveField = (field: Field): Promise<unknown> => {
+  const resolver = fieldResolvers[field.type];
+  return resolver(field);
+};
+
+/** Fill missing input by prompting with Clack when interactive. */
+export const resolveInputWithClack: InputResolver = async (
+  fields,
+  provided,
+  options?: ResolveInputOptions
+) => {
+  if (!isInteractive(options)) {
+    return provided;
+  }
+
+  const resolved: Record<string, unknown> = { ...provided };
+  for (const field of fields) {
+    if (!needsInput(field, resolved)) {
+      continue;
+    }
+    const value = await resolveField(field);
+    if (value !== undefined) {
+      resolved[field.name] = value;
+    }
+  }
+  return resolved;
+};

package/src/cli.ts

@@ -0,0 +1,14 @@
+import { outputModePreset } from '@ontrails/cli';
+import { blaze } from '@ontrails/cli/commander';
+
+import { app } from './app.js';
+import { resolveInputWithClack } from './clack.js';
+
+// oxlint-disable-next-line require-hook -- CLI entry point
+blaze(app, {
+  description: 'Agent-native, contract-first TypeScript framework',
+  name: 'trails',
+  presets: [outputModePreset()],
+  resolveInput: resolveInputWithClack,
+  version: '0.1.0',
+});

package/src/trails/add-surface.ts

@@ -0,0 +1,119 @@
+/**
+ * `add.surface` trail -- Add a surface to an existing project.
+ *
+ * Generates the CLI or MCP entry point and updates package.json dependencies.
+ */
+
+import { existsSync, mkdirSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+
+import { Result, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { findTopoPath } from './project.js';
+
+const generateCliEntry = (appImportPath: string): string =>
+  `import { blaze } from '@ontrails/cli/commander';
+
+import { app } from '${appImportPath}';
+
+blaze(app);
+`;
+
+const generateMcpEntry = (appImportPath: string): string =>
+  `import { blaze } from '@ontrails/mcp';
+
+import { app } from '${appImportPath}';
+
+await blaze(app);
+`;
+
+/** Resolve the entry file for a surface. */
+const getEntryFile = (surface: 'cli' | 'mcp'): string =>
+  surface === 'cli' ? 'src/cli.ts' : 'src/mcp.ts';
+
+// ---------------------------------------------------------------------------
+// Trail definition
+// ---------------------------------------------------------------------------
+
+/** Patch deps and optionally bin in a parsed package.json. */
+const patchPkgDeps = (
+  pkg: Record<string, unknown>,
+  surface: 'cli' | 'mcp',
+  cwd: string
+): string => {
+  const depName = surface === 'cli' ? '@ontrails/cli' : '@ontrails/mcp';
+  const deps = (pkg['dependencies'] ?? {}) as Record<string, string>;
+  deps[depName] = 'workspace:*';
+  if (surface === 'cli') {
+    deps['commander'] = '^14.0.0';
+    pkg['bin'] = {
+      [(pkg['name'] as string | undefined) ?? basename(cwd)]: './src/cli.ts',
+    };
+  }
+  pkg['dependencies'] = Object.fromEntries(
+    Object.entries(deps).toSorted(([a], [b]) => a.localeCompare(b))
+  );
+  return depName;
+};
+
+/** Update package.json with surface dependency and CLI bin if needed. */
+const updatePkgJsonForSurface = async (
+  cwd: string,
+  surface: 'cli' | 'mcp'
+): Promise<string> => {
+  const pkgPath = join(cwd, 'package.json');
+  if (!existsSync(pkgPath)) {
+    return surface === 'cli' ? '@ontrails/cli' : '@ontrails/mcp';
+  }
+  const pkg = (await Bun.file(pkgPath).json()) as Record<string, unknown>;
+  const depName = patchPkgDeps(pkg, surface, cwd);
+  await Bun.write(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+  return depName;
+};
+
+/** Create the entry file for a surface and return the relative path. */
+const writeSurfaceEntry = async (
+  cwd: string,
+  surface: 'cli' | 'mcp'
+): Promise<string> => {
+  const entryFile = getEntryFile(surface);
+  const fullEntryPath = join(cwd, entryFile);
+  const appImport = (await findTopoPath(cwd)) ?? './app.js';
+  const content =
+    surface === 'cli'
+      ? generateCliEntry(appImport)
+      : generateMcpEntry(appImport);
+
+  mkdirSync(dirname(fullEntryPath), { recursive: true });
+  await Bun.write(fullEntryPath, content);
+  return entryFile;
+};
+
+export const addSurface = trail('add.surface', {
+  description: 'Add a surface to an existing project',
+  implementation: async (input) => {
+    const cwd = resolve(input.dir ?? '.');
+    const { surface } = input;
+    const entryFile = getEntryFile(surface);
+
+    if (existsSync(join(cwd, entryFile))) {
+      return Result.err(
+        new Error(`${surface.toUpperCase()} is already blazed. Nothing to do.`)
+      );
+    }
+
+    return Result.ok({
+      created: await writeSurfaceEntry(cwd, surface),
+      dependency: await updatePkgJsonForSurface(cwd, surface),
+    });
+  },
+  input: z.object({
+    dir: z.string().optional().describe('Project directory'),
+    surface: z.enum(['cli', 'mcp']).describe('Surface to add'),
+  }),
+  output: z.object({
+    created: z.string(),
+    dependency: z.string(),
+  }),
+});

package/src/trails/add-trail.ts

@@ -0,0 +1,103 @@
+/**
+ * `add.trail` trail -- Scaffold a new trail file with tests.
+ */
+
+import { mkdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+import { Result, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const generateTrailFile = (
+  id: string,
+  readOnly: boolean,
+  destructive: boolean
+): string => {
+  const markers: string[] = [];
+  if (readOnly) {
+    markers.push('  readOnly: true,');
+  }
+  if (destructive) {
+    markers.push('  destructive: true,');
+  }
+  const markerBlock = markers.length > 0 ? `\n${markers.join('\n')}` : '';
+
+  return `import { Result, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+export const ${id.replaceAll('.', '_')} = trail('${id}', {
+  description: 'TODO: describe this trail',
+  examples: [
+    {
+      input: {},
+      name: 'TODO: add example',
+    },
+  ],
+  implementation: async (input) => {
+    return Result.ok({ message: 'TODO' });
+  },
+  input: z.object({}),${markerBlock}
+  output: z.object({ message: z.string() }),
+});
+`;
+};
+
+const generateTestFile = (id: string): string => {
+  const moduleName = id.replaceAll('.', '-');
+  const trailName = id.replaceAll('.', '_');
+  return `import { testTrail } from '@ontrails/testing';
+import { ${trailName} } from '../src/trails/${moduleName}.js';
+
+testTrail(${trailName}, [
+  { description: 'basic test', input: {}, expectOk: true },
+]);
+`;
+};
+
+// ---------------------------------------------------------------------------
+// Trail definition
+// ---------------------------------------------------------------------------
+
+/** Write a file, creating parent directories as needed. */
+const writeWithDirs = async (
+  filePath: string,
+  content: string
+): Promise<void> => {
+  mkdirSync(dirname(filePath), { recursive: true });
+  await Bun.write(filePath, content);
+};
+
+export const addTrail = trail('add.trail', {
+  description: 'Scaffold a new trail with tests and examples',
+  implementation: async (input, ctx) => {
+    const { id } = input;
+    const moduleName = id.replaceAll('.', '-');
+    const cwd = resolve(ctx.cwd ?? '.');
+
+    const files = new Map<string, string>([
+      [
+        `src/trails/${moduleName}.ts`,
+        generateTrailFile(id, input.readOnly, input.destructive),
+      ],
+      [`__tests__/${moduleName}.test.ts`, generateTestFile(id)],
+    ]);
+
+    for (const [relativePath, content] of files) {
+      await writeWithDirs(join(cwd, relativePath), content);
+    }
+
+    return Result.ok({ created: [...files.keys()] });
+  },
+  input: z.object({
+    destructive: z.boolean().default(false).describe('Destructive trail'),
+    id: z.string().describe('Trail ID (e.g., entity.update)'),
+    readOnly: z.boolean().default(false).describe('Read-only trail'),
+  }),
+  output: z.object({
+    created: z.array(z.string()),
+  }),
+});

package/src/trails/add-verify.ts

@@ -0,0 +1,87 @@
+/**
+ * `add.verify` trail -- Add testing + warden setup to a project.
+ */
+
+import { existsSync, mkdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+import { Result, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+// ---------------------------------------------------------------------------
+// Content generators
+// ---------------------------------------------------------------------------
+
+const generateTestFile = (): string =>
+  `import { testAll } from '@ontrails/testing';
+import { app } from '../src/app.js';
+
+testAll(app);
+`;
+
+const generateLefthookYml = (): string =>
+  `pre-push:
+  commands:
+    warden:
+      run: bunx trails warden --exit-code
+`;
+
+/** Add testing and warden devDependencies to package.json when present. */
+const patchVerifyDeps = (pkg: Record<string, unknown>): void => {
+  const devDeps = (pkg['devDependencies'] ?? {}) as Record<string, string>;
+  devDeps['@ontrails/testing'] = 'workspace:*';
+  devDeps['@ontrails/warden'] = 'workspace:*';
+  devDeps['lefthook'] = '^2.1.1';
+  pkg['devDependencies'] = Object.fromEntries(
+    Object.entries(devDeps).toSorted(([a], [b]) => a.localeCompare(b))
+  );
+};
+
+/** Update package.json in the target project with verify dependencies. */
+const updatePackageJsonForVerify = async (
+  projectDir: string
+): Promise<void> => {
+  const pkgPath = join(projectDir, 'package.json');
+  if (!existsSync(pkgPath)) {
+    return;
+  }
+  const pkg = (await Bun.file(pkgPath).json()) as Record<string, unknown>;
+  patchVerifyDeps(pkg);
+  await Bun.write(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+};
+
+// ---------------------------------------------------------------------------
+// Trail definition
+// ---------------------------------------------------------------------------
+
+export const addVerify = trail('add.verify', {
+  description: 'Add testing and warden verification',
+  implementation: async (input) => {
+    const projectDir = resolve(input.dir ?? '.', input.name);
+    const files: string[] = [];
+
+    const writeFile = async (
+      relativePath: string,
+      content: string
+    ): Promise<void> => {
+      const fullPath = join(projectDir, relativePath);
+      mkdirSync(dirname(fullPath), { recursive: true });
+      await Bun.write(fullPath, content);
+      files.push(relativePath);
+    };
+
+    await writeFile('__tests__/examples.test.ts', generateTestFile());
+    await writeFile('lefthook.yml', generateLefthookYml());
+    await updatePackageJsonForVerify(projectDir);
+
+    return Result.ok({ created: files });
+  },
+  input: z.object({
+    dir: z.string().optional().describe('Parent directory'),
+    name: z.string().describe('Project name'),
+  }),
+  markers: { internal: true },
+  output: z.object({
+    created: z.array(z.string()),
+  }),
+});