@ontrails/trails 1.0.0-beta.0

package/src/trails/create-scaffold.ts

@@ -0,0 +1,352 @@
+/**
+ * `create.scaffold` trail -- Creates base project structure.
+ *
+ * Generates package.json, tsconfig, app.ts, starter trails, and .trails/ directory.
+ */
+
+import { mkdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+import { Result, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+type Starter = 'empty' | 'entity' | 'hello';
+
+interface ScaffoldResult {
+  readonly created: string[];
+  readonly dir: string;
+  readonly name: string;
+}
+
+// ---------------------------------------------------------------------------
+// Content generators
+// ---------------------------------------------------------------------------
+
+const generatePackageJson = (name: string): string => {
+  const deps: Record<string, string> = {
+    '@ontrails/core': 'workspace:*',
+    zod: '^4.0.0',
+  };
+
+  const pkg: Record<string, unknown> = {
+    dependencies: Object.fromEntries(
+      Object.entries(deps).toSorted(([a], [b]) => a.localeCompare(b))
+    ),
+    name,
+    scripts: {
+      build: 'tsc -b',
+      lint: 'oxlint ./src',
+      test: 'bun test',
+      typecheck: 'tsc --noEmit',
+    },
+    type: 'module',
+    version: '0.1.0',
+  };
+
+  return JSON.stringify(pkg, null, 2);
+};
+
+const TSCONFIG_CONTENT = JSON.stringify(
+  {
+    compilerOptions: {
+      declaration: true,
+      module: 'ESNext',
+      moduleResolution: 'bundler',
+      noUncheckedIndexedAccess: true,
+      outDir: 'dist',
+      rootDir: 'src',
+      skipLibCheck: true,
+      strict: true,
+      target: 'ESNext',
+      verbatimModuleSyntax: true,
+    },
+    include: ['src'],
+  },
+  null,
+  2
+);
+
+const GITIGNORE_CONTENT = `node_modules/
+dist/
+*.tsbuildinfo
+.trails/_surface.json
+`;
+
+const OXLINTRC_CONTENT = JSON.stringify(
+  {
+    extends: ['ultracite'],
+  },
+  null,
+  2
+);
+
+const OXFMTRC_CONTENT = `{
+  // ultracite defaults
+}
+`;
+
+const generateHelloTrail = (): string =>
+  `import { Result, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+export const hello = trail('hello', {
+  description: 'Say hello',
+  examples: [
+    {
+      expected: { message: 'Hello, world!' },
+      input: {},
+      name: 'Default greeting',
+    },
+    {
+      expected: { message: 'Hello, Trails!' },
+      input: { name: 'Trails' },
+      name: 'Named greeting',
+    },
+  ],
+  implementation: (input) => {
+    const name = input.name ?? 'world';
+    return Result.ok({ message: \`Hello, \${name}!\` });
+  },
+  input: z.object({
+    name: z.string().optional(),
+  }),
+  output: z.object({
+    message: z.string(),
+  }),
+  readOnly: true,
+});
+`;
+
+const generateEntityTrails = (): string =>
+  `import { Result, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+const entitySchema = z.object({
+  id: z.string(),
+  name: z.string(),
+});
+
+export const show = trail('entity.show', {
+  description: 'Show an entity by ID',
+  examples: [
+    {
+      expected: { id: '1', name: 'Example' },
+      input: { id: '1' },
+      name: 'Show entity',
+    },
+  ],
+  implementation: (input) => {
+    return Result.ok({ id: input.id, name: 'Example' });
+  },
+  input: z.object({ id: z.string() }),
+  output: entitySchema,
+  readOnly: true,
+});
+
+export const add = trail('entity.add', {
+  description: 'Add a new entity',
+  examples: [
+    {
+      expected: { id: '1', name: 'New' },
+      input: { name: 'New' },
+      name: 'Add entity',
+    },
+  ],
+  implementation: (input) => {
+    return Result.ok({ id: '1', name: input.name });
+  },
+  input: z.object({ name: z.string() }),
+  output: entitySchema,
+});
+`;
+
+const generateSearchTrail = (): string =>
+  `import { Result, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+export const search = trail('search', {
+  description: 'Search entities by query',
+  examples: [
+    {
+      expected: { results: [] },
+      input: { query: 'test' },
+      name: 'Search entities',
+    },
+  ],
+  implementation: () => {
+    return Result.ok({ results: [] });
+  },
+  input: z.object({ query: z.string() }),
+  output: z.object({
+    results: z.array(z.object({ id: z.string(), name: z.string() })),
+  }),
+  readOnly: true,
+});
+`;
+
+const generateOnboardHike = (): string =>
+  `import { Result, hike } from '@ontrails/core';
+import { z } from 'zod';
+
+export const onboard = hike('entity.onboard', {
+  description: 'Onboard a new entity end-to-end',
+  follows: ['entity.add'],
+  implementation: async (input, ctx) => {
+    const result = await ctx.follow('entity.add', { name: input.name });
+    if (result.isErr()) {
+      return result;
+    }
+    return Result.ok({ onboarded: true });
+  },
+  input: z.object({ name: z.string() }),
+  output: z.object({ onboarded: z.boolean() }),
+});
+`;
+
+const generateEntityEvents = (): string =>
+  `import { event } from '@ontrails/core';
+import { z } from 'zod';
+
+export const entityUpdated = event('entity.updated', {
+  description: 'Fired when an entity is updated',
+  payload: z.object({
+    entityId: z.string(),
+    updatedAt: z.string(),
+  }),
+});
+`;
+
+const generateStore = (): string =>
+  `/** In-memory store for entities. */
+
+interface Entity {
+  readonly id: string;
+  readonly name: string;
+}
+
+const store = new Map<string, Entity>();
+
+export const getEntity = (id: string): Entity | undefined => store.get(id);
+export const addEntity = (entity: Entity): void => {
+  store.set(entity.id, entity);
+};
+export const deleteEntity = (id: string): boolean => store.delete(id);
+export const listEntities = (): Entity[] => Array.from(store.values());
+`;
+
+const starterImports: Record<
+  Starter,
+  { imports: string[]; modules: string[] }
+> = {
+  empty: { imports: [], modules: [] },
+  entity: {
+    imports: [
+      "import * as entity from './trails/entity.js';",
+      "import * as search from './trails/search.js';",
+      "import * as onboard from './trails/onboard.js';",
+      "import * as entityEvents from './events/entity-events.js';",
+    ],
+    modules: ['entity', 'search', 'onboard', 'entityEvents'],
+  },
+  hello: {
+    imports: ["import * as hello from './trails/hello.js';"],
+    modules: ['hello'],
+  },
+};
+
+const generateAppTs = (name: string, starter: Starter): string => {
+  const { imports, modules } = starterImports[starter];
+  const topoArgs =
+    modules.length > 0 ? `'${name}', ${modules.join(', ')}` : `'${name}'`;
+
+  return [
+    "import { topo } from '@ontrails/core';",
+    ...imports,
+    '',
+    `export const app = topo(${topoArgs});`,
+    '',
+  ].join('\n');
+};
+
+// ---------------------------------------------------------------------------
+// File collection and writing
+// ---------------------------------------------------------------------------
+
+const starterFileGenerators: Record<Starter, () => [string, string][]> = {
+  empty: () => [['src/trails/.gitkeep', '']],
+  entity: () => [
+    ['src/trails/entity.ts', generateEntityTrails()],
+    ['src/trails/search.ts', generateSearchTrail()],
+    ['src/trails/onboard.ts', generateOnboardHike()],
+    ['src/events/entity-events.ts', generateEntityEvents()],
+    ['src/store.ts', generateStore()],
+  ],
+  hello: () => [['src/trails/hello.ts', generateHelloTrail()]],
+};
+
+const collectScaffoldFiles = (
+  name: string,
+  starter: Starter
+): Map<string, string> =>
+  new Map([
+    ['package.json', generatePackageJson(name)],
+    ['tsconfig.json', TSCONFIG_CONTENT],
+    ['.gitignore', GITIGNORE_CONTENT],
+    ['.oxlintrc.json', OXLINTRC_CONTENT],
+    ['.oxfmtrc.jsonc', OXFMTRC_CONTENT],
+    ['src/app.ts', generateAppTs(name, starter)],
+    ...starterFileGenerators[starter](),
+  ]);
+
+const writeScaffoldFiles = async (
+  projectDir: string,
+  fileMap: Map<string, string>
+): Promise<string[]> => {
+  const files: string[] = [];
+  for (const [relativePath, content] of fileMap) {
+    const fullPath = join(projectDir, relativePath);
+    mkdirSync(dirname(fullPath), { recursive: true });
+    await Bun.write(fullPath, content);
+    files.push(relativePath);
+  }
+  return files;
+};
+
+// ---------------------------------------------------------------------------
+// Trail definition
+// ---------------------------------------------------------------------------
+
+export const createScaffold = trail('create.scaffold', {
+  description: 'Scaffold a new Trails project',
+  implementation: async (input) => {
+    const projectDir = resolve(input.dir ?? '.', input.name);
+    const starter = (input.starter ?? 'hello') as Starter;
+    const fileMap = collectScaffoldFiles(input.name, starter);
+    const files = await writeScaffoldFiles(projectDir, fileMap);
+    mkdirSync(join(projectDir, '.trails'), { recursive: true });
+
+    return Result.ok({
+      created: files,
+      dir: projectDir,
+      name: input.name,
+    } satisfies ScaffoldResult);
+  },
+  input: z.object({
+    dir: z.string().optional().describe('Parent directory'),
+    name: z.string().describe('Project name'),
+    starter: z
+      .enum(['hello', 'entity', 'empty'])
+      .default('hello')
+      .describe('Starter trail'),
+  }),
+  markers: { internal: true },
+  output: z.object({
+    created: z.array(z.string()),
+    dir: z.string(),
+    name: z.string(),
+  }),
+});

package/src/trails/create.ts

@@ -0,0 +1,203 @@
+/**
+ * `create` route -- Create a new Trails project.
+ *
+ * Composes create.scaffold, add.surface, and add.verify sub-trails
+ * via ctx.follow().
+ */
+
+import type { FollowFn } from '@ontrails/core';
+import { Result, hike } from '@ontrails/core';
+import { z } from 'zod';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+type Starter = 'empty' | 'entity' | 'hello';
+type Surface = 'cli' | 'mcp';
+
+interface BlazeInput {
+  readonly dir?: string | undefined;
+  readonly name: string;
+  readonly starter: Starter;
+  readonly surfaces: readonly Surface[];
+  readonly verify: boolean;
+}
+
+interface ScaffoldRequest {
+  readonly dir?: string | undefined;
+  readonly name: string;
+  readonly starter: Starter;
+}
+
+interface VerifyRequest {
+  readonly dir?: string | undefined;
+  readonly name: string;
+  readonly verify: boolean;
+}
+
+interface ScaffoldedProject {
+  readonly created: string[];
+  readonly dir: string;
+  readonly name: string;
+}
+
+const buildScaffoldInput = (input: ScaffoldRequest) => ({
+  ...(input.dir === undefined ? {} : { dir: input.dir }),
+  name: input.name,
+  starter: input.starter,
+});
+
+const buildSurfaceInput = (dir: string, surface: string) => ({
+  dir,
+  surface,
+});
+
+const buildVerifyInput = (input: VerifyRequest) => ({
+  ...(input.dir === undefined ? {} : { dir: input.dir }),
+  name: input.name,
+});
+
+const scaffoldProject = (
+  follow: FollowFn,
+  input: ScaffoldRequest
+): Promise<Result<ScaffoldedProject, Error>> =>
+  follow('create.scaffold', buildScaffoldInput(input));
+
+const addSurfaceFiles = async (
+  follow: FollowFn,
+  dir: string,
+  surfaces: readonly string[]
+): Promise<Result<string[], Error>> => {
+  const created: string[] = [];
+
+  for (const surface of surfaces) {
+    const result = await follow<{ created: string; dependency: string }>(
+      'add.surface',
+      buildSurfaceInput(dir, surface)
+    );
+    if (result.isErr()) {
+      return Result.err(result.error);
+    }
+    created.push(result.value.created);
+  }
+
+  return Result.ok(created);
+};
+
+const collectVerifyFiles = async (
+  follow: FollowFn,
+  input: VerifyRequest
+): Promise<Result<string[], Error>> => {
+  if (!input.verify) {
+    return Result.ok([]);
+  }
+
+  const result = await follow<{ created: string[] }>(
+    'add.verify',
+    buildVerifyInput(input)
+  );
+  return result.isErr()
+    ? Result.err(result.error)
+    : Result.ok(result.value.created);
+};
+
+const collectCreatedFiles = (
+  scaffolded: readonly string[],
+  surfaces: readonly string[],
+  verify: readonly string[]
+): string[] => [...scaffolded, ...surfaces, ...verify];
+
+const runCreate = async (
+  follow: FollowFn,
+  input: BlazeInput
+): Promise<Result<{ created: string[]; dir: string; name: string }, Error>> => {
+  const scaffolded = await scaffoldProject(follow, input);
+  if (scaffolded.isErr()) {
+    return Result.err(scaffolded.error);
+  }
+
+  const surfaceResults = await addSurfaceFiles(
+    follow,
+    scaffolded.value.dir,
+    input.surfaces
+  );
+  if (surfaceResults.isErr()) {
+    return Result.err(surfaceResults.error);
+  }
+
+  const verifyFiles = await collectVerifyFiles(follow, input);
+  if (verifyFiles.isErr()) {
+    return Result.err(verifyFiles.error);
+  }
+
+  return Result.ok({
+    created: collectCreatedFiles(
+      scaffolded.value.created,
+      surfaceResults.value,
+      verifyFiles.value
+    ),
+    dir: scaffolded.value.dir,
+    name: input.name,
+  });
+};
+
+// ---------------------------------------------------------------------------
+// Route definition
+// ---------------------------------------------------------------------------
+
+export const createRoute = hike('create', {
+  description: 'Create a new Trails project',
+  fields: {
+    starter: {
+      options: [
+        {
+          hint: 'One trail, one example',
+          label: 'Hello world',
+          value: 'hello',
+        },
+        {
+          hint: '4 trails, hike, event, store',
+          label: 'Entity CRUD',
+          value: 'entity',
+        },
+        { hint: 'Just the structure', label: 'Empty', value: 'empty' },
+      ],
+    },
+    surfaces: {
+      options: [
+        { hint: 'Commander-based command line', label: 'CLI', value: 'cli' },
+        {
+          hint: 'Model Context Protocol for agents',
+          label: 'MCP',
+          value: 'mcp',
+        },
+      ],
+    },
+  },
+  follows: ['create.scaffold', 'add.surface', 'add.verify'],
+  implementation: async (input: BlazeInput, ctx) => {
+    if (!ctx.follow) {
+      return Result.err(new Error('create route requires ctx.follow'));
+    }
+    return await runCreate(ctx.follow, input);
+  },
+  input: z.object({
+    dir: z.string().optional().describe('Parent directory'),
+    name: z.string().describe('Project name'),
+    starter: z
+      .enum(['hello', 'entity', 'empty'])
+      .default('hello')
+      .describe('Starter trail'),
+    surfaces: z
+      .array(z.enum(['cli', 'mcp']))
+      .default(['cli'])
+      .describe('Surfaces'),
+    verify: z.boolean().default(true).describe('Include testing + warden'),
+  }),
+  output: z.object({
+    created: z.array(z.string()),
+    dir: z.string(),
+    name: z.string(),
+  }),
+});

package/src/trails/guide.ts

@@ -0,0 +1,104 @@
+/**
+ * `guide` trail -- Runtime guidance.
+ *
+ * Lists trails with descriptions and examples. Detailed guidance is planned for post-v1.
+ */
+
+import type { Topo, Trail } from '@ontrails/core';
+import { Result, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { loadApp } from './load-app.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface GuideEntry {
+  readonly description: string;
+  readonly exampleCount: number;
+  readonly id: string;
+  readonly kind: string;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const toGuideEntries = (app: Topo): GuideEntry[] => {
+  const entries: GuideEntry[] = [];
+
+  for (const item of app.list()) {
+    const raw = item as unknown as Record<string, unknown>;
+    entries.push({
+      description:
+        typeof raw['description'] === 'string'
+          ? raw['description']
+          : '(no description)',
+      exampleCount: Array.isArray(raw['examples'])
+        ? (raw['examples'] as unknown[]).length
+        : 0,
+      id: item.id,
+      kind: item.kind,
+    });
+  }
+
+  return entries;
+};
+
+const toGuideDetail = (item: Trail<unknown, unknown>): object => ({
+  description: item.description ?? null,
+  detours: item.detours ?? null,
+  examples: item.examples ?? [],
+  id: item.id,
+  kind: item.kind,
+});
+
+export const guideTrail = trail('guide', {
+  description: 'Runtime guidance for trails',
+  examples: [
+    {
+      description: 'Lists all trails with descriptions and example counts',
+      input: {},
+      name: 'List trail guidance',
+    },
+  ],
+  implementation: async (input, ctx) => {
+    const app = await loadApp(input.module, ctx.cwd ?? '.');
+
+    if (input.trailId) {
+      const item = app.get(input.trailId);
+      if (!item) {
+        return Result.err(new Error(`Trail not found: ${input.trailId}`));
+      }
+      return Result.ok(toGuideDetail(item as Trail<unknown, unknown>));
+    }
+
+    return Result.ok(toGuideEntries(app));
+  },
+  input: z.object({
+    module: z
+      .string()
+      .default('./src/app.ts')
+      .describe('Path to the app module'),
+    trailId: z.string().optional().describe('Trail ID for detailed guidance'),
+  }),
+  output: z.union([
+    z.array(
+      z.object({
+        description: z.string(),
+        exampleCount: z.number(),
+        id: z.string(),
+        kind: z.string(),
+      })
+    ),
+    z.object({
+      description: z.string().nullable(),
+      detours: z.unknown().nullable(),
+      examples: z.array(z.unknown()),
+      id: z.string(),
+      kind: z.string(),
+    }),
+  ]),
+  readOnly: true,
+});

package/src/trails/load-app.ts

@@ -0,0 +1,37 @@
+import { isAbsolute, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import type { Topo } from '@ontrails/core';
+
+const URL_SCHEME = /^[a-zA-Z][a-zA-Z\d+.-]*:/;
+
+/** Resolve a module path from cwd so CLI defaults behave like shell paths. */
+const resolveModuleSpecifier = (modulePath: string, cwd: string): string => {
+  if (URL_SCHEME.test(modulePath)) {
+    return modulePath;
+  }
+
+  const absolutePath = isAbsolute(modulePath)
+    ? modulePath
+    : resolve(cwd, modulePath);
+  return pathToFileURL(absolutePath).href;
+};
+
+/** Load a Topo export from a module path relative to cwd. */
+export const loadApp = async (
+  modulePath: string,
+  cwd: string
+): Promise<Topo> => {
+  const mod = (await import(resolveModuleSpecifier(modulePath, cwd))) as Record<
+    string,
+    unknown
+  >;
+  const app = (mod['default'] ?? mod['app']) as Topo | undefined;
+  if (!app?.trails) {
+    throw new Error(
+      `Could not find a Topo export in "${modulePath}". ` +
+        "Expected a default or named 'app' export created with topo()."
+    );
+  }
+  return app;
+};