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

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'] },
+});

package/src/trails/create.ts

@@ -1,22 +1,29 @@
 /**
- * `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.follow().
+ * via ctx.compose.
  */
 
-import type { FollowFn } from '@ontrails/core';
-import { Result, hike } from '@ontrails/core';
+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';
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
 type Starter = 'empty' | 'entity' | 'hello';
-type Surface = 'cli' | 'mcp';
+type Surface = 'cli' | 'http' | 'mcp';
 
-interface BlazeInput {
+interface CreateInput {
   readonly dir?: string | undefined;
   readonly name: string;
   readonly starter: Starter;
@@ -42,6 +49,18 @@ interface ScaffoldedProject {
   readonly name: string;
 }
 
+interface SurfaceResult {
+  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,
@@ -58,45 +77,34 @@ const buildVerifyInput = (input: VerifyRequest) => ({
   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[]
+const collectSurfaceFiles = async (
+  surfaces: readonly string[],
+  addSurface: (surface: string) => Promise<Result<SurfaceResult, Error>>
 ): 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)
-    );
+    const result = await addSurface(surface);
     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);
 };
 
 const collectVerifyFiles = async (
-  follow: FollowFn,
-  input: VerifyRequest
+  shouldVerify: boolean,
+  addVerify: () => Promise<Result<{ created: string[] }, Error>>
 ): Promise<Result<string[], Error>> => {
-  if (!input.verify) {
+  if (!shouldVerify) {
     return Result.ok([]);
   }
 
-  const result = await follow<{ created: string[] }>(
-    'add.verify',
-    buildVerifyInput(input)
-  );
+  const result = await addVerify();
   return result.isErr()
     ? Result.err(result.error)
     : Result.ok(result.value.created);
@@ -105,48 +113,151 @@ const collectVerifyFiles = async (
 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);
-  }
+  verify: readonly string[],
+  readme: string | null
+): string[] =>
+  readme === null
+    ? [...scaffolded, ...surfaces, ...verify]
+    : [...scaffolded, ...surfaces, ...verify, readme];
 
-  const surfaceResults = await addSurfaceFiles(
-    follow,
-    scaffolded.value.dir,
-    input.surfaces
-  );
-  if (surfaceResults.isErr()) {
-    return Result.err(surfaceResults.error);
-  }
+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
 
-  const verifyFiles = await collectVerifyFiles(follow, input);
-  if (verifyFiles.isErr()) {
-    return Result.err(verifyFiles.error);
+## 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);
   }
 
-  return Result.ok({
-    created: collectCreatedFiles(
-      scaffolded.value.created,
-      surfaceResults.value,
-      verifyFiles.value
-    ),
-    dir: scaffolded.value.dir,
-    name: input.name,
-  });
+  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 = hike('create', {
+export const createTrail = trail('create', {
+  blaze: async (input: CreateInput, ctx) => {
+    if (!hasCompose(ctx)) {
+      return Result.err(new InternalError('create trail requires ctx.compose'));
+    }
+
+    const scaffolded = await ctx.compose<ScaffoldedProject>(
+      'create.scaffold',
+      buildScaffoldInput(input)
+    );
+    if (scaffolded.isErr()) {
+      return scaffolded;
+    }
+
+    const finishCreate = async (): Promise<
+      Result<{ created: string[]; dir: string; name: string }, Error>
+    > => {
+      const surfaceFiles = await collectSurfaceFiles(
+        input.surfaces,
+        (surface) =>
+          ctx.compose<SurfaceResult>(
+            'add.surface',
+            buildSurfaceInput(scaffolded.value.dir, surface)
+          )
+      );
+      if (surfaceFiles.isErr()) {
+        return Result.err(surfaceFiles.error);
+      }
+
+      const verifyFiles = await collectVerifyFiles(input.verify, () =>
+        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,
+          readmeFile.value
+        ),
+        dir: scaffolded.value.dir,
+        name: input.name,
+      });
+    };
+
+    return finishCreate();
+  },
+  composes: ['create.scaffold', 'add.surface', 'add.verify'],
   description: 'Create a new Trails project',
   fields: {
     starter: {
@@ -157,7 +268,7 @@ export const createRoute = hike('create', {
           value: 'hello',
         },
         {
-          hint: '4 trails, hike, event, store',
+          hint: '4 trails, signal, store',
           label: 'Entity CRUD',
           value: 'entity',
         },
@@ -172,25 +283,27 @@ export const createRoute = hike('create', {
           label: 'MCP',
           value: 'mcp',
         },
+        {
+          hint: 'Hono-powered HTTP endpoints',
+          label: 'HTTP',
+          value: 'http',
+        },
       ],
     },
   },
-  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'),
+    name: z
+      .string()
+      .regex(PROJECT_NAME_PATTERN, PROJECT_NAME_MESSAGE)
+      .describe('Project name'),
     starter: z
       .enum(['hello', 'entity', 'empty'])
       .default('hello')
       .describe('Starter trail'),
     surfaces: z
-      .array(z.enum(['cli', 'mcp']))
+      .array(z.enum(['cli', 'http', 'mcp']))
+      .min(1)
       .default(['cli'])
       .describe('Surfaces'),
     verify: z.boolean().default(true).describe('Include testing + warden'),
@@ -200,4 +313,5 @@ export const createRoute = hike('create', {
     dir: z.string(),
     name: z.string(),
   }),
+  permit: { scopes: ['project:write'] },
 });

package/src/trails/deprecate.ts

@@ -0,0 +1,59 @@
+import { trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import {
+  parseLifecycleTarget,
+  setVersionStatusSource,
+  withLifecycleApp,
+} from './version-lifecycle-support.js';
+
+export const deprecateTrail = trail('deprecate', {
+  args: ['target'],
+  blaze: async (input, ctx) =>
+    withLifecycleApp(input, ctx.cwd, async (_app, rootDir) => {
+      const target = parseLifecycleTarget(input.target);
+      if (target.isErr()) {
+        return target;
+      }
+      return setVersionStatusSource(
+        rootDir,
+        target.value,
+        input.archive ? 'archived' : 'deprecated',
+        {
+          migration: input.migration,
+          note: input.note,
+          reason: input.reason,
+          successor: input.successor,
+        }
+      );
+    }),
+  description: 'Mark a historical trail version deprecated or archived',
+  input: z.object({
+    archive: z
+      .boolean()
+      .default(false)
+      .describe('Archive instead of deprecate'),
+    migration: z
+      .array(z.string())
+      .default([])
+      .describe('Migration guidance entries'),
+    module: z.string().optional().describe('Path to the app module'),
+    note: z.string().optional().describe('Deprecation note'),
+    reason: z.string().optional().describe('Archive reason'),
+    rootDir: z.string().optional().describe('Workspace root directory'),
+    successor: z
+      .number()
+      .int()
+      .positive()
+      .optional()
+      .describe('Successor version'),
+    target: z.string().min(1).describe('Historical version target trail.id@N'),
+  }),
+  intent: 'write',
+  output: z.object({
+    file: z.string(),
+    trailId: z.string(),
+    updated: z.boolean(),
+  }),
+  permit: { scopes: ['version:write'] },
+});

package/src/trails/dev-clean.ts

@@ -0,0 +1,82 @@
+import { Result, ValidationError, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import {
+  cleanDevState,
+  DEFAULT_TOPO_SNAPSHOT_RETENTION,
+} from './dev-support.js';
+import { resolveTrailRootDir } from './root-dir.js';
+import { createIsolatedExampleInput } from './topo-support.js';
+
+export const devCleanTrail = trail('dev.clean', {
+  blaze: (input, ctx) => {
+    if (input.dryRun !== true && input.yes !== true) {
+      return Result.err(
+        new ValidationError(
+          'Refusing to clean local state without `--yes` or `--dry-run`.'
+        )
+      );
+    }
+
+    const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
+    if (rootDirResult.isErr()) {
+      return rootDirResult;
+    }
+    const rootDir = rootDirResult.value;
+    return Result.ok(
+      cleanDevState({
+        dryRun: input.dryRun,
+        maxAge: input.traceAgeMs,
+        maxRecords: input.traces,
+        rootDir,
+        snapshotRetention: input.snapshots,
+      })
+    );
+  },
+  description: 'Prune unpinned topo snapshots and old trace records',
+  examples: [
+    {
+      input: {
+        dryRun: true,
+        rootDir: createIsolatedExampleInput('dev-clean').rootDir,
+      },
+      name: 'Preview local cleanup',
+    },
+  ],
+  input: z.object({
+    dryRun: z
+      .boolean()
+      .default(true)
+      .describe('Preview cleanup without changing state'),
+    rootDir: z.string().optional().describe('Workspace root directory'),
+    snapshots: z
+      .number()
+      .default(DEFAULT_TOPO_SNAPSHOT_RETENTION)
+      .describe('Unpinned topo snapshots to retain'),
+    traceAgeMs: z
+      .number()
+      .default(7 * 24 * 60 * 60 * 1000)
+      .describe('Maximum retained trace age in milliseconds'),
+    traces: z.number().default(10_000).describe('Maximum retained trace count'),
+    yes: z.boolean().default(false).describe('Confirm destructive changes'),
+  }),
+  intent: 'destroy',
+  output: z.object({
+    dryRun: z.boolean(),
+    remaining: z.object({
+      pinnedCount: z.number(),
+      snapshotCount: z.number(),
+      traceCount: z.number(),
+    }),
+    removed: z.object({
+      topoSnapshots: z.number(),
+      traceRecords: z.number(),
+    }),
+    retention: z.object({
+      snapshots: z.number(),
+      traceAgeMs: z.number(),
+      traces: z.number(),
+    }),
+  }),
+  permit: { scopes: ['dev:write'] },
+});

package/src/trails/dev-reset.ts

@@ -0,0 +1,50 @@
+import { Result, ValidationError, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { resetDevState } from './dev-support.js';
+import { resolveTrailRootDir } from './root-dir.js';
+import { createIsolatedExampleInput } from './topo-support.js';
+
+export const devResetTrail = trail('dev.reset', {
+  blaze: (input, ctx) => {
+    if (input.dryRun !== true && input.yes !== true) {
+      return Result.err(
+        new ValidationError(
+          'Refusing to reset local state without `--yes` or `--dry-run`.'
+        )
+      );
+    }
+
+    const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
+    if (rootDirResult.isErr()) {
+      return rootDirResult;
+    }
+    const rootDir = rootDirResult.value;
+    return Result.ok(resetDevState({ dryRun: input.dryRun, rootDir }));
+  },
+  description: 'Remove local Trails database artifacts',
+  examples: [
+    {
+      input: {
+        dryRun: true,
+        rootDir: createIsolatedExampleInput('dev-reset').rootDir,
+      },
+      name: 'Preview local reset',
+    },
+  ],
+  input: z.object({
+    dryRun: z
+      .boolean()
+      .default(true)
+      .describe('Preview reset without changing state'),
+    rootDir: z.string().optional().describe('Workspace root directory'),
+    yes: z.boolean().default(false).describe('Confirm destructive changes'),
+  }),
+  intent: 'destroy',
+  output: z.object({
+    dryRun: z.boolean(),
+    removedCount: z.number(),
+    removedFiles: z.array(z.string()),
+  }),
+  permit: { scopes: ['dev:write'] },
+});

package/src/trails/dev-stats.ts

@@ -0,0 +1,72 @@
+import { Result, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import {
+  buildDevStats,
+  DEFAULT_TOPO_SNAPSHOT_RETENTION,
+} from './dev-support.js';
+import { resolveTrailRootDir } from './root-dir.js';
+import { createIsolatedExampleInput } from './topo-support.js';
+
+export const devStatsTrail = trail('dev.stats', {
+  blaze: (input, ctx) => {
+    const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
+    if (rootDirResult.isErr()) {
+      return rootDirResult;
+    }
+    const rootDir = rootDirResult.value;
+    return Result.ok(
+      buildDevStats({
+        maxAge: input.traceAgeMs,
+        maxRecords: input.traces,
+        rootDir,
+        snapshotRetention: input.snapshots,
+      })
+    );
+  },
+  description: 'Show local Trails workspace state and retention',
+  examples: [
+    {
+      input: { rootDir: createIsolatedExampleInput('dev-stats').rootDir },
+      name: 'Show local dev state',
+    },
+  ],
+  input: z.object({
+    rootDir: z.string().optional().describe('Workspace root directory'),
+    snapshots: z
+      .number()
+      .default(DEFAULT_TOPO_SNAPSHOT_RETENTION)
+      .describe('Unpinned topo snapshots to retain'),
+    traceAgeMs: z
+      .number()
+      .default(7 * 24 * 60 * 60 * 1000)
+      .describe('Maximum retained trace age in milliseconds'),
+    traces: z.number().default(10_000).describe('Maximum retained trace count'),
+  }),
+  intent: 'read',
+  output: z.object({
+    db: z.object({
+      exists: z.boolean(),
+      fileSizeBytes: z.number(),
+      path: z.string(),
+    }),
+    lock: z.object({
+      exists: z.boolean(),
+      fileSizeBytes: z.number(),
+      path: z.string(),
+    }),
+    retention: z.object({
+      snapshots: z.number(),
+      traceAgeMs: z.number(),
+      traces: z.number(),
+    }),
+    topo: z.object({
+      pinnedCount: z.number(),
+      prunableSnapshotCount: z.number(),
+      snapshotCount: z.number(),
+    }),
+    tracing: z.object({
+      recordCount: z.number(),
+    }),
+  }),
+});