@ontrails/trails 1.0.0-beta.17 → 1.0.0-beta.19

package/src/trails/create-scaffold.ts

@@ -23,6 +23,7 @@ import type {
 import {
   ontrailsPackageRange,
   scaffoldDependencyVersions,
+  trailsPackageVersion,
 } from '../versions.js';
 
 // ---------------------------------------------------------------------------
@@ -39,6 +40,22 @@ interface ScaffoldResult {
   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
 // ---------------------------------------------------------------------------
@@ -55,6 +72,7 @@ const generatePackageJson = (name: string): string => {
     ),
     devDependencies: Object.fromEntries(
       Object.entries({
+        '@ontrails/trails': ontrailsPackageRange,
         '@types/bun': scaffoldDependencyVersions.bunTypes,
         oxfmt: scaffoldDependencyVersions.oxfmt,
         oxlint: scaffoldDependencyVersions.oxlint,
@@ -63,14 +81,17 @@ const generatePackageJson = (name: string): string => {
       }).toSorted(([a], [b]) => a.localeCompare(b))
     ),
     name,
-    scripts: {
-      build: 'tsc -b',
-      'format:check': 'bunx ultracite check .',
-      'format:fix': 'bunx ultracite fix .',
-      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',
   };
@@ -78,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: {
@@ -98,6 +131,74 @@ 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
@@ -112,6 +213,15 @@ import ultracite from 'ultracite/oxlint/core';
 
 export default defineConfig({
   extends: [ultracite],
+  rules: {
+    'no-warning-comments': [
+      'error',
+      {
+        location: 'start',
+        terms: ['todo:', 'fixme', 'xxx'],
+      },
+    ],
+  },
 });
 `;
 
@@ -153,9 +263,13 @@ export const hello = trail('hello', {
 `;
 
 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(),
@@ -170,28 +284,85 @@ export const show = trail('entity.show', {
       name: 'Show entity',
     },
   ],
-  blaze: (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,
   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',
     },
   ],
-  blaze: (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],
 });
 `;
 
@@ -225,9 +396,9 @@ import { z } from 'zod';
 
 export const onboard = trail('entity.onboard', {
   description: 'Onboard a new entity end-to-end',
-  crosses: ['entity.add'],
+  composes: ['entity.add'],
   blaze: async (input, ctx) => {
-    const result = await ctx.cross('entity.add', { name: input.name });
+    const result = await ctx.compose('entity.add', { name: input.name });
     if (result.isErr()) {
       return result;
     }
@@ -235,6 +406,8 @@ export const onboard = trail('entity.onboard', {
   },
   input: z.object({ name: z.string() }),
   output: z.object({ onboarded: z.boolean() }),
+  intent: 'write',
+  permit: { scopes: ['entity:write'] },
 });
 `;
 
@@ -252,21 +425,49 @@ export const entityUpdated = signal('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<
@@ -280,8 +481,9 @@ const starterImports: Record<
       "import * as search from './trails/search.js';",
       "import * as onboard from './trails/onboard.js';",
       "import * as entitySignals from './signals/entity-signals.js';",
+      "import * as store from './store.js';",
     ],
-    modules: ['entity', 'search', 'onboard', 'entitySignals'],
+    modules: ['entity', 'search', 'onboard', 'entitySignals', 'store'],
   },
   hello: {
     imports: ["import * as hello from './trails/hello.js';"],
@@ -328,11 +530,15 @@ 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],
     ['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](),
   ]);
@@ -354,7 +560,7 @@ export const createScaffold = trail('create.scaffold', {
   blaze: async (input) => {
     const projectDirResult = resolveProjectDir(input.dir ?? '.', input.name);
     if (projectDirResult.isErr()) {
-      return Result.err(projectDirResult.error);
+      return projectDirResult;
     }
 
     const projectDir = projectDirResult.value;
@@ -363,13 +569,19 @@ export const createScaffold = trail('create.scaffold', {
     const fileMap = collectScaffoldFiles(input.name, starter);
     const operations = collectScaffoldOperations(fileMap);
     const plannedOperations = dryRun
-      ? planProjectOperations(projectDir, operations)
-      : await applyProjectOperations(projectDir, operations);
+      ? planProjectOperations(projectDir, operations, { existing: 'preserve' })
+      : await applyProjectOperations(projectDir, operations, {
+          existing: 'preserve',
+        });
     if (plannedOperations.isErr()) {
       return Result.err(plannedOperations.error);
     }
 
-    const created = dryRun ? [] : [...fileMap.keys()];
+    const created = dryRun
+      ? []
+      : plannedOperations.value
+          .filter((operation) => operation.kind === 'write')
+          .map((operation) => operation.path);
 
     return Result.ok({
       created,
@@ -395,6 +607,7 @@ export const createScaffold = trail('create.scaffold', {
       .default('hello')
       .describe('Starter trail'),
   }),
+  intent: 'write',
   output: z.object({
     created: z
       .array(z.string())
@@ -414,5 +627,6 @@ export const createScaffold = trail('create.scaffold', {
       ])
     ),
   }),
+  permit: { scopes: ['project:write'] },
   visibility: 'internal',
 });

package/src/trails/create.ts

@@ -1,16 +1,19 @@
 /**
- * `create` route -- Create a new Trails project.
+ * `create` trail -- Create a new Trails project.
  *
  * Composes create.scaffold, add.surface, and add.verify sub-trails
- * via ctx.cross.
+ * via ctx.compose.
  */
 
 import { InternalError, Result, trail } from '@ontrails/core';
+import type { TrailContext } from '@ontrails/core';
 import { z } from 'zod';
 
 import {
   PROJECT_NAME_MESSAGE,
   PROJECT_NAME_PATTERN,
+  projectPathExists,
+  writeProjectFile,
 } from '../project-writes.js';
 
 // ---------------------------------------------------------------------------
@@ -47,10 +50,17 @@ interface ScaffoldedProject {
 }
 
 interface SurfaceResult {
-  readonly created: string;
+  readonly created: string | null;
   readonly dependency: string;
 }
 
+type TrailContextWithCompose = TrailContext & {
+  readonly compose: NonNullable<TrailContext['compose']>;
+};
+
+const hasCompose = (ctx: TrailContext): ctx is TrailContextWithCompose =>
+  Boolean(ctx.compose);
+
 const buildScaffoldInput = (input: ScaffoldRequest) => ({
   ...(input.dir === undefined ? {} : { dir: input.dir }),
   name: input.name,
@@ -78,7 +88,9 @@ const collectSurfaceFiles = async (
     if (result.isErr()) {
       return Result.err(result.error);
     }
-    created.push(result.value.created);
+    if (result.value.created !== null) {
+      created.push(result.value.created);
+    }
   }
 
   return Result.ok(created);
@@ -101,26 +113,104 @@ const collectVerifyFiles = async (
 const collectCreatedFiles = (
   scaffolded: readonly string[],
   surfaces: readonly string[],
-  verify: readonly string[]
-): string[] => [...scaffolded, ...surfaces, ...verify];
+  verify: readonly string[],
+  readme: string | null
+): string[] =>
+  readme === null
+    ? [...scaffolded, ...surfaces, ...verify]
+    : [...scaffolded, ...surfaces, ...verify, readme];
+
+const surfaceReadmeLines = {
+  cli: '- `src/cli.ts` - CLI surface entry point',
+  http: '- `src/http.ts` - HTTP surface entry point',
+  mcp: '- `src/mcp.ts` - MCP surface entry point',
+} satisfies Record<Surface, string>;
+
+const starterReadmeLines = {
+  empty:
+    'Starts with an empty `src/trails/` directory for authoring from scratch.',
+  entity:
+    'Includes sample entity trails, a signal, and an in-memory store for exploration.',
+  hello: 'Includes a `hello` trail with examples for the first happy path.',
+} satisfies Record<Starter, string>;
+
+const generateReadme = (input: CreateInput): string => {
+  const surfaceLines = input.surfaces
+    .map((surface) => surfaceReadmeLines[surface])
+    .join('\n');
+  const verificationCommand = input.verify ? 'bun test\n' : '';
+  const verificationStructure = input.verify
+    ? '- `__tests__/examples.test.ts` - examples-as-tests harness\n'
+    : '- Verification files were not generated for this project\n';
+
+  return `# ${input.name}
+
+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.
+
+## Getting Started
+
+\`\`\`bash
+bun install
+${verificationCommand}bun run warden
+bun run survey
+bun run guide
+\`\`\`
+
+## Project Structure
+
+- \`src/app.ts\` - the topo that collects this project's trails
+- \`src/trails/\` - trail definitions
+${surfaceLines}
+${verificationStructure}- \`AGENTS.md\` - project guidance for agents working in this app
+
+## Starter
+
+${starterReadmeLines[input.starter]}
+
+## Next Steps
+
+- Add a trail with \`bun run add\`
+- Run \`bun run warden\` before review
+- Read \`AGENTS.md\` for Trails vocabulary and conventions
+`;
+};
+
+const writeReadme = async (
+  input: CreateInput,
+  dir: string
+): Promise<Result<string | null, Error>> => {
+  const exists = projectPathExists(dir, 'README.md');
+  if (exists.isErr()) {
+    return Result.err(exists.error);
+  }
+  if (exists.value) {
+    return Result.ok(null);
+  }
+
+  const written = await writeProjectFile(
+    dir,
+    'README.md',
+    generateReadme(input)
+  );
+  return written.isErr() ? Result.err(written.error) : Result.ok('README.md');
+};
 
 // ---------------------------------------------------------------------------
-// Route definition
+// Trail definition
 // ---------------------------------------------------------------------------
 
-export const createRoute = trail('create', {
+export const createTrail = trail('create', {
   blaze: async (input: CreateInput, ctx) => {
-    if (!ctx.cross) {
-      return Result.err(new InternalError('create route requires ctx.cross'));
+    if (!hasCompose(ctx)) {
+      return Result.err(new InternalError('create trail requires ctx.compose'));
     }
-    const { cross } = ctx;
 
-    const scaffolded = await cross<ScaffoldedProject>(
+    const scaffolded = await ctx.compose<ScaffoldedProject>(
       'create.scaffold',
       buildScaffoldInput(input)
     );
     if (scaffolded.isErr()) {
-      return Result.err(scaffolded.error);
+      return scaffolded;
     }
 
     const finishCreate = async (): Promise<
@@ -129,7 +219,7 @@ export const createRoute = trail('create', {
       const surfaceFiles = await collectSurfaceFiles(
         input.surfaces,
         (surface) =>
-          cross<SurfaceResult>(
+          ctx.compose<SurfaceResult>(
             'add.surface',
             buildSurfaceInput(scaffolded.value.dir, surface)
           )
@@ -139,17 +229,26 @@ export const createRoute = trail('create', {
       }
 
       const verifyFiles = await collectVerifyFiles(input.verify, () =>
-        cross<{ created: string[] }>('add.verify', buildVerifyInput(input))
+        ctx.compose<{ created: string[] }>(
+          'add.verify',
+          buildVerifyInput(input)
+        )
       );
       if (verifyFiles.isErr()) {
         return Result.err(verifyFiles.error);
       }
 
+      const readmeFile = await writeReadme(input, scaffolded.value.dir);
+      if (readmeFile.isErr()) {
+        return Result.err(readmeFile.error);
+      }
+
       return Result.ok({
         created: collectCreatedFiles(
           scaffolded.value.created,
           surfaceFiles.value,
-          verifyFiles.value
+          verifyFiles.value,
+          readmeFile.value
         ),
         dir: scaffolded.value.dir,
         name: input.name,
@@ -158,7 +257,7 @@ export const createRoute = trail('create', {
 
     return finishCreate();
   },
-  crosses: ['create.scaffold', 'add.surface', 'add.verify'],
+  composes: ['create.scaffold', 'add.surface', 'add.verify'],
   description: 'Create a new Trails project',
   fields: {
     starter: {
@@ -204,6 +303,7 @@ export const createRoute = trail('create', {
       .describe('Starter trail'),
     surfaces: z
       .array(z.enum(['cli', 'http', 'mcp']))
+      .min(1)
       .default(['cli'])
       .describe('Surfaces'),
     verify: z.boolean().default(true).describe('Include testing + warden'),
@@ -213,4 +313,5 @@ export const createRoute = trail('create', {
     dir: z.string(),
     name: z.string(),
   }),
+  permit: { scopes: ['project:write'] },
 });