@ontrails/trails 1.0.0-beta.2 → 1.0.0-beta.21

package/src/trails/create-scaffold.ts

@@ -4,12 +4,28 @@
  * Generates package.json, tsconfig, app.ts, starter trails, and .trails/ directory.
  */
 
-import { mkdirSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { resolve } from 'node:path';
 
-import { Result, trail } from '@ontrails/core';
+import { Result, trail, WORKSPACE_GITIGNORE_CONTENT } from '@ontrails/core';
 import { z } from 'zod';
 
+import {
+  applyProjectOperations,
+  planProjectOperations,
+  PROJECT_NAME_MESSAGE,
+  PROJECT_NAME_PATTERN,
+  resolveProjectDir,
+} from '../project-writes.js';
+import type {
+  PlannedProjectOperation,
+  ProjectWriteOperation,
+} from '../project-writes.js';
+import {
+  ontrailsPackageRange,
+  scaffoldDependencyVersions,
+  trailsPackageVersion,
+} from '../versions.js';
+
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
@@ -19,30 +35,63 @@ type Starter = 'empty' | 'entity' | 'hello';
 interface ScaffoldResult {
   readonly created: string[];
   readonly dir: string;
+  readonly dryRun: boolean;
   readonly name: string;
+  readonly plannedOperations: PlannedProjectOperation[];
 }
 
+const frameworkCommandScripts = {
+  add: 'trails add',
+  compile: 'trails compile',
+  completions: 'trails completions',
+  deprecate: 'trails deprecate',
+  diff: 'trails diff',
+  doctor: 'trails doctor',
+  guide: 'trails guide',
+  revise: 'trails revise',
+  run: 'trails run',
+  survey: 'trails survey',
+  topo: 'trails topo',
+  validate: 'trails validate',
+  warden: 'trails warden',
+} as const satisfies Record<string, string>;
+
 // ---------------------------------------------------------------------------
 // Content generators
 // ---------------------------------------------------------------------------
 
 const generatePackageJson = (name: string): string => {
   const deps: Record<string, string> = {
-    '@ontrails/core': 'workspace:*',
-    zod: '^4.0.0',
+    '@ontrails/core': ontrailsPackageRange,
+    zod: scaffoldDependencyVersions.zod,
   };
 
   const pkg: Record<string, unknown> = {
     dependencies: Object.fromEntries(
       Object.entries(deps).toSorted(([a], [b]) => a.localeCompare(b))
     ),
+    devDependencies: Object.fromEntries(
+      Object.entries({
+        '@ontrails/trails': ontrailsPackageRange,
+        '@types/bun': scaffoldDependencyVersions.bunTypes,
+        oxfmt: scaffoldDependencyVersions.oxfmt,
+        oxlint: scaffoldDependencyVersions.oxlint,
+        typescript: scaffoldDependencyVersions.typescript,
+        ultracite: scaffoldDependencyVersions.ultracite,
+      }).toSorted(([a], [b]) => a.localeCompare(b))
+    ),
     name,
-    scripts: {
-      build: 'tsc -b',
-      lint: 'oxlint ./src',
-      test: 'bun test',
-      typecheck: 'tsc --noEmit',
-    },
+    scripts: Object.fromEntries(
+      Object.entries({
+        build: 'tsc -b',
+        'format:check': 'bunx ultracite check .',
+        'format:fix': 'bunx ultracite fix .',
+        lint: 'oxlint ./src',
+        test: 'bun test',
+        typecheck: 'tsc --noEmit',
+        ...frameworkCommandScripts,
+      }).toSorted(([a], [b]) => a.localeCompare(b))
+    ),
     type: 'module',
     version: '0.1.0',
   };
@@ -50,6 +99,18 @@ const generatePackageJson = (name: string): string => {
   return JSON.stringify(pkg, null, 2);
 };
 
+const generateScaffoldProvenance = (starter: Starter): string =>
+  JSON.stringify(
+    {
+      generatedAt: new Date().toISOString(),
+      scaffoldVersion: trailsPackageVersion,
+      schemaVersion: 1,
+      template: starter,
+    },
+    null,
+    2
+  );
+
 const TSCONFIG_CONTENT = JSON.stringify(
   {
     compilerOptions: {
@@ -70,19 +131,99 @@ const TSCONFIG_CONTENT = JSON.stringify(
   2
 );
 
+const TSCONFIG_TESTS_CONTENT = JSON.stringify(
+  {
+    compilerOptions: {
+      noEmit: true,
+      rootDir: '.',
+      types: ['bun'],
+    },
+    exclude: [],
+    extends: './tsconfig.json',
+    include: ['src', '__tests__'],
+  },
+  null,
+  2
+);
+
+const AGENTS_CONTENT = `# AGENTS.md
+
+This is a Trails project. Trails is an agent-native, contract-first TypeScript framework: author a trail once with typed input, Result output, examples, intent, and meta; surface it through CLI, MCP, HTTP, or future WebSocket without rewriting the contract.
+
+## Commands
+
+Use the project scripts first:
+
+\`\`\`bash
+bun install
+bun run build
+bun test
+bun run typecheck
+bun run lint
+bun run format:check
+bun run warden
+bun run survey
+bun run guide
+\`\`\`
+
+## Lexicon
+
+- \`trail\`, not action or handler
+- \`blaze\`, not handler or impl
+- \`topo\`, not registry or collection
+- \`compose\`, not follow
+- \`surface\`, not transport
+- \`resource\`, not service or dependency
+- \`layer\`, for compose-cutting trail wrapping
+
+## Trail Rules
+
+- Blazes return \`Result\`; never throw from trail logic.
+- Use \`Result.ok()\` and \`Result.err()\`; branch with \`isOk()\`, \`isErr()\`, or \`match()\`.
+- Keep trail logic surface-agnostic. Do not import CLI, MCP, HTTP, request, or response types into blazes.
+- Public MCP or HTTP trails declare an \`output\` schema.
+- Trails that compose other trails declare \`composes: [...]\` and invoke them with \`ctx.compose(...)\`.
+- Trails that use infrastructure declare \`resources: [...]\` and access them through the resource helpers.
+- Use \`detours\` for recovery strategies instead of inline retry logic.
+- Prefer examples for happy-path coverage, and add focused tests for edge cases.
+`;
+
+const CLAUDE_CONTENT = `# CLAUDE.md
+
+## Compatibility Shim
+
+Keep shared project guidance in \`./AGENTS.md\`. Only Claude-specific bootstrap notes belong here.
+
+## Agent Instructions
+
+@AGENTS.md
+`;
+
 const GITIGNORE_CONTENT = `node_modules/
 dist/
 *.tsbuildinfo
-.trails/_surface.json
+.trails/cache/
+.trails/state/
+.trails/config.local.js
+.trails/config.local.ts
 `;
 
-const OXLINTRC_CONTENT = JSON.stringify(
-  {
-    extends: ['ultracite'],
+const OXLINT_CONFIG_CONTENT = `import { defineConfig } from 'oxlint';
+import ultracite from 'ultracite/oxlint/core';
+
+export default defineConfig({
+  extends: [ultracite],
+  rules: {
+    'no-warning-comments': [
+      'error',
+      {
+        location: 'start',
+        terms: ['todo:', 'fixme', 'xxx'],
+      },
+    ],
   },
-  null,
-  2
-);
+});
+`;
 
 const OXFMTRC_CONTENT = `{
   // ultracite defaults
@@ -107,7 +248,7 @@ export const hello = trail('hello', {
       name: 'Named greeting',
     },
   ],
-  implementation: (input) => {
+  blaze: (input) => {
     const name = input.name ?? 'world';
     return Result.ok({ message: \`Hello, \${name}!\` });
   },
@@ -117,14 +258,18 @@ export const hello = trail('hello', {
   output: z.object({
     message: z.string(),
   }),
-  readOnly: true,
+  intent: 'read',
 });
 `;
 
 const generateEntityTrails = (): string =>
-  `import { Result, trail } from '@ontrails/core';
+  `import { randomUUID } from 'node:crypto';
+
+import { NotFoundError, Result, trail } from '@ontrails/core';
 import { z } from 'zod';
 
+import { entityStore } from '../store.js';
+
 const entitySchema = z.object({
   id: z.string(),
   name: z.string(),
@@ -139,28 +284,85 @@ export const show = trail('entity.show', {
       name: 'Show entity',
     },
   ],
-  implementation: (input) => {
-    return Result.ok({ id: input.id, name: 'Example' });
+  blaze: (input, ctx) => {
+    const store = entityStore.from(ctx);
+    const entity = store.get(input.id);
+    if (!entity) {
+      return Result.err(new NotFoundError(\`Entity "\${input.id}" not found\`));
+    }
+    return Result.ok(entity);
   },
   input: z.object({ id: z.string() }),
   output: entitySchema,
-  readOnly: true,
+  intent: 'read',
+  resources: [entityStore],
 });
 
 export const add = trail('entity.add', {
   description: 'Add a new entity',
   examples: [
     {
-      expected: { id: '1', name: 'New' },
+      expectedMatch: { name: 'New' },
       input: { name: 'New' },
       name: 'Add entity',
     },
   ],
-  implementation: (input) => {
-    return Result.ok({ id: '1', name: input.name });
+  blaze: (input, ctx) => {
+    const store = entityStore.from(ctx);
+    const entity = { id: randomUUID(), name: input.name };
+    store.add(entity);
+    return Result.ok(entity);
   },
   input: z.object({ name: z.string() }),
   output: entitySchema,
+  intent: 'write',
+  permit: { scopes: ['entity:write'] },
+  resources: [entityStore],
+});
+
+export const list = trail('entity.list', {
+  description: 'List entities',
+  examples: [
+    {
+      expected: { entities: [{ id: '1', name: 'Example' }] },
+      input: {},
+      name: 'List entities',
+    },
+  ],
+  blaze: (_input, ctx) => {
+    const store = entityStore.from(ctx);
+    return Result.ok({ entities: store.list() });
+  },
+  input: z.object({}),
+  output: z.object({
+    entities: z.array(entitySchema),
+  }),
+  intent: 'read',
+  resources: [entityStore],
+});
+
+export const remove = trail('entity.delete', {
+  description: 'Delete an entity by ID',
+  examples: [
+    {
+      expected: { deleted: true, id: '1' },
+      input: { id: '1' },
+      name: 'Delete entity',
+    },
+  ],
+  blaze: (input, ctx) => {
+    const store = entityStore.from(ctx);
+    const deleted = store.delete(input.id);
+    return Result.ok({ deleted, id: input.id });
+  },
+  input: z.object({ id: z.string() }),
+  output: z.object({
+    deleted: z.boolean(),
+    id: z.string(),
+  }),
+  intent: 'destroy',
+  permit: { scopes: ['entity:write'] },
+  resources: [entityStore],
 });
 `;
 
@@ -177,26 +379,26 @@ export const search = trail('search', {
       name: 'Search entities',
     },
   ],
-  implementation: () => {
+  blaze: () => {
     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,
+  intent: 'read',
 });
 `;
 
-const generateOnboardHike = (): string =>
-  `import { Result, hike } from '@ontrails/core';
+const generateOnboardTrail = (): string =>
+  `import { Result, trail } from '@ontrails/core';
 import { z } from 'zod';
 
-export const onboard = hike('entity.onboard', {
+export const onboard = trail('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 });
+  composes: ['entity.add'],
+  blaze: async (input, ctx) => {
+    const result = await ctx.compose('entity.add', { name: input.name });
     if (result.isErr()) {
       return result;
     }
@@ -204,14 +406,16 @@ export const onboard = hike('entity.onboard', {
   },
   input: z.object({ name: z.string() }),
   output: z.object({ onboarded: z.boolean() }),
+  intent: 'write',
+  permit: { scopes: ['entity:write'] },
 });
 `;
 
-const generateEntityEvents = (): string =>
-  `import { event } from '@ontrails/core';
+const generateEntitySignals = (): string =>
+  `import { signal } from '@ontrails/core';
 import { z } from 'zod';
 
-export const entityUpdated = event('entity.updated', {
+export const entityUpdated = signal('entity.updated', {
   description: 'Fired when an entity is updated',
   payload: z.object({
     entityId: z.string(),
@@ -221,21 +425,49 @@ export const entityUpdated = event('entity.updated', {
 `;
 
 const generateStore = (): string =>
-  `/** In-memory store for entities. */
+  `import { Result, resource } from '@ontrails/core';
 
-interface Entity {
+/** In-memory store for entities. */
+
+export interface Entity {
   readonly id: string;
   readonly name: string;
 }
 
-const store = new Map<string, Entity>();
+export interface EntityStore {
+  add(entity: Entity): void;
+  delete(id: string): boolean;
+  get(id: string): Entity | undefined;
+  list(): Entity[];
+}
+
+const defaultEntities: readonly Entity[] = [{ id: '1', name: 'Example' }];
 
-export const getEntity = (id: string): Entity | undefined => store.get(id);
-export const addEntity = (entity: Entity): void => {
-  store.set(entity.id, entity);
+export const createEntityStore = (
+  seed: readonly Entity[] = defaultEntities
+): EntityStore => {
+  const store = new Map(seed.map((entity) => [entity.id, entity] as const));
+  return {
+    add(entity) {
+      store.set(entity.id, entity);
+    },
+    delete(id) {
+      return store.delete(id);
+    },
+    get(id) {
+      return store.get(id);
+    },
+    list() {
+      return Array.from(store.values());
+    },
+  };
 };
-export const deleteEntity = (id: string): boolean => store.delete(id);
-export const listEntities = (): Entity[] => Array.from(store.values());
+
+export const entityStore = resource('entity.store', {
+  description: 'In-memory entity store for the entity starter.',
+  create: () => Result.ok(createEntityStore()),
+  mock: createEntityStore,
+});
 `;
 
 const starterImports: Record<
@@ -248,9 +480,10 @@ const starterImports: Record<
       "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';",
+      "import * as entitySignals from './signals/entity-signals.js';",
+      "import * as store from './store.js';",
     ],
-    modules: ['entity', 'search', 'onboard', 'entityEvents'],
+    modules: ['entity', 'search', 'onboard', 'entitySignals', 'store'],
   },
   hello: {
     imports: ["import * as hello from './trails/hello.js';"],
@@ -260,8 +493,11 @@ const starterImports: Record<
 
 const generateAppTs = (name: string, starter: Starter): string => {
   const { imports, modules } = starterImports[starter];
+  const appNameLiteral = JSON.stringify(name);
   const topoArgs =
-    modules.length > 0 ? `'${name}', ${modules.join(', ')}` : `'${name}'`;
+    modules.length > 0
+      ? `${appNameLiteral}, ${modules.join(', ')}`
+      : appNameLiteral;
 
   return [
     "import { topo } from '@ontrails/core';",
@@ -281,8 +517,8 @@ const starterFileGenerators: Record<Starter, () => [string, string][]> = {
   entity: () => [
     ['src/trails/entity.ts', generateEntityTrails()],
     ['src/trails/search.ts', generateSearchTrail()],
-    ['src/trails/onboard.ts', generateOnboardHike()],
-    ['src/events/entity-events.ts', generateEntityEvents()],
+    ['src/trails/onboard.ts', generateOnboardTrail()],
+    ['src/signals/entity-signals.ts', generateEntitySignals()],
     ['src/store.ts', generateStore()],
   ],
   hello: () => [['src/trails/hello.ts', generateHelloTrail()]],
@@ -294,59 +530,103 @@ const collectScaffoldFiles = (
 ): Map<string, string> =>
   new Map([
     ['package.json', generatePackageJson(name)],
+    ['AGENTS.md', AGENTS_CONTENT],
+    ['CLAUDE.md', CLAUDE_CONTENT],
     ['tsconfig.json', TSCONFIG_CONTENT],
+    ['tsconfig.tests.json', TSCONFIG_TESTS_CONTENT],
     ['.gitignore', GITIGNORE_CONTENT],
-    ['.oxlintrc.json', OXLINTRC_CONTENT],
+    ['oxlint.config.ts', OXLINT_CONFIG_CONTENT],
     ['.oxfmtrc.jsonc', OXFMTRC_CONTENT],
+    ['.trails/.gitignore', WORKSPACE_GITIGNORE_CONTENT],
+    ['.trails/scaffold.json', generateScaffoldProvenance(starter)],
     ['src/app.ts', generateAppTs(name, starter)],
     ...starterFileGenerators[starter](),
   ]);
 
-const writeScaffoldFiles = async (
-  projectDir: string,
+const collectScaffoldOperations = (
   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;
-};
+): ProjectWriteOperation[] =>
+  [...fileMap].map(([path, content]) => ({
+    content,
+    kind: 'write' as const,
+    path,
+  }));
 
 // ---------------------------------------------------------------------------
 // Trail definition
 // ---------------------------------------------------------------------------
 
 export const createScaffold = trail('create.scaffold', {
-  description: 'Scaffold a new Trails project',
-  implementation: async (input) => {
-    const projectDir = resolve(input.dir ?? '.', input.name);
+  blaze: async (input) => {
+    const projectDirResult = resolveProjectDir(input.dir ?? '.', input.name);
+    if (projectDirResult.isErr()) {
+      return projectDirResult;
+    }
+
+    const projectDir = projectDirResult.value;
     const starter = (input.starter ?? 'hello') as Starter;
+    const dryRun = input.dryRun === true;
     const fileMap = collectScaffoldFiles(input.name, starter);
-    const files = await writeScaffoldFiles(projectDir, fileMap);
-    mkdirSync(join(projectDir, '.trails'), { recursive: true });
+    const operations = collectScaffoldOperations(fileMap);
+    const plannedOperations = dryRun
+      ? planProjectOperations(projectDir, operations, { existing: 'preserve' })
+      : await applyProjectOperations(projectDir, operations, {
+          existing: 'preserve',
+        });
+    if (plannedOperations.isErr()) {
+      return Result.err(plannedOperations.error);
+    }
+
+    const created = dryRun
+      ? []
+      : plannedOperations.value
+          .filter((operation) => operation.kind === 'write')
+          .map((operation) => operation.path);
 
     return Result.ok({
-      created: files,
-      dir: projectDir,
+      created,
+      dir: resolve(projectDir),
+      dryRun,
       name: input.name,
+      plannedOperations: plannedOperations.value,
     } satisfies ScaffoldResult);
   },
+  description: 'Scaffold a new Trails project',
   input: z.object({
     dir: z.string().optional().describe('Parent directory'),
-    name: z.string().describe('Project name'),
+    dryRun: z
+      .boolean()
+      .default(false)
+      .describe('Plan scaffold writes without touching the project directory'),
+    name: z
+      .string()
+      .regex(PROJECT_NAME_PATTERN, PROJECT_NAME_MESSAGE)
+      .describe('Project name'),
     starter: z
       .enum(['hello', 'entity', 'empty'])
       .default('hello')
       .describe('Starter trail'),
   }),
-  markers: { internal: true },
+  intent: 'write',
   output: z.object({
-    created: z.array(z.string()),
+    created: z
+      .array(z.string())
+      .describe('Project-relative paths of files written (empty in dry-run)'),
     dir: z.string(),
+    dryRun: z.boolean(),
     name: z.string(),
+    plannedOperations: z.array(
+      z.discriminatedUnion('kind', [
+        z.object({ kind: z.literal('mkdir'), path: z.string() }),
+        z.object({
+          from: z.string(),
+          kind: z.literal('rename'),
+          to: z.string(),
+        }),
+        z.object({ kind: z.literal('write'), path: z.string() }),
+      ])
+    ),
   }),
+  permit: { scopes: ['project:write'] },
+  visibility: 'internal',
 });

package/src/trails/create-versions.ts

@@ -0,0 +1,62 @@
+/**
+ * `create.versions` trail -- Sync generated scaffold dependency versions.
+ *
+ * Derives `apps/trails/src/scaffold-versions.generated.ts` from the root
+ * `package.json` catalog and devDependencies. Graduated from
+ * `scripts/sync-scaffold-versions.ts`.
+ */
+
+import { Result, trail, ValidationError } from '@ontrails/core';
+import { z } from 'zod';
+
+import { syncScaffoldVersions } from '../scaffold-version-sync.js';
+import { resolveTrailRootDir } from './root-dir.js';
+
+const createVersionsInputSchema = z.object({
+  check: z
+    .boolean()
+    .default(false)
+    .describe('Verify the generated file is current instead of writing'),
+  rootDir: z.string().optional().describe('Workspace root directory'),
+});
+
+const createVersionsOutputSchema = z.object({
+  generatedPath: z.string(),
+  mode: z.enum(['check', 'write']),
+  written: z.boolean(),
+});
+
+export const createVersionsTrail = trail('create.versions', {
+  blaze: async (input, ctx) => {
+    const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
+    if (rootDirResult.isErr()) {
+      return rootDirResult;
+    }
+
+    try {
+      return Result.ok(
+        await syncScaffoldVersions({
+          check: input.check,
+          rootDir: rootDirResult.value,
+        })
+      );
+    } catch (error) {
+      return Result.err(
+        new ValidationError(
+          error instanceof Error ? error.message : String(error)
+        )
+      );
+    }
+  },
+  description: 'Sync generated scaffold dependency versions',
+  examples: [
+    {
+      input: { check: true },
+      name: 'Verify generated scaffold versions are current',
+    },
+  ],
+  input: createVersionsInputSchema,
+  intent: 'write',
+  output: createVersionsOutputSchema,
+  permit: { scopes: ['project:write'] },
+});