@ontrails/trails 1.0.0-beta.13 → 1.0.0-beta.15

package/.turbo/turbo-lint.log

@@ -1,3 +1,3 @@
 $ oxlint ./src
 Found 0 warnings and 0 errors.
-Finished in 56ms on 18 files with 93 rules using 24 threads.
+Finished in 57ms on 38 files with 93 rules using 24 threads.

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # trails
 
+## 1.0.0-beta.15
+
+### Patch Changes
+
+- 2003fa5: Prepare the Trails CLI for beta.15 release publishing: derive the CLI version from package metadata, scaffold publishable package ranges, add HTTP surface generation, include the scaffold toolchain dependencies, and avoid generating unsupported Warden flags.
+- Updated dependencies [4ad6b25]
+  - @ontrails/core@1.0.0-beta.15
+  - @ontrails/cli@1.0.0-beta.15
+  - @ontrails/tracing@1.0.0-beta.15
+  - @ontrails/warden@1.0.0-beta.15
+  - @ontrails/logging@1.0.0-beta.15
+  - @ontrails/schema@1.0.0-beta.15
+
+## 1.0.0-beta.14
+
+### Minor Changes
+
+- 69057e9: Add hierarchical CLI command trees and structured input, enforce established-only topo exports across trailheads, move developer topo and tracker state onto shared `trails.db` with pins and maintenance flows, and ship schema-derived stores through `@ontrails/store` and its Drizzle runtime.
+
+### Patch Changes
+
+- Updated dependencies [69057e9]
+  - @ontrails/cli@1.0.0-beta.14
+  - @ontrails/core@1.0.0-beta.14
+  - @ontrails/logging@1.0.0-beta.14
+  - @ontrails/schema@1.0.0-beta.14
+  - @ontrails/tracker@1.0.0-beta.14
+  - @ontrails/warden@1.0.0-beta.14
+
 ## 1.0.0-beta.13
 
 ### Patch Changes

package/__tests__/examples.test.ts

@@ -1,6 +1,45 @@
 /* oxlint-disable eslint-plugin-jest/require-hook -- testExamples registers tests at module scope */
+import { afterAll, beforeAll } from 'bun:test';
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
 import { testExamples } from '@ontrails/testing';
 
 import { app } from '../src/app.js';
 
+const trailsWorkspaceDir = resolve(import.meta.dir, '..', '.trails');
+const trailsGitignorePath = join(trailsWorkspaceDir, '.gitignore');
+const trailsWorkspaceSubdirs = ['config', 'dev', 'generated'] as const;
+const trailsGitignore = `# Local config overrides
+config/
+
+# Development state
+dev/
+
+# Generated artifacts
+generated/
+
+# Shared Trails database
+trails.db
+trails.db-shm
+trails.db-wal
+`;
+
+const resetTrailsWorkspace = (): void => {
+  rmSync(trailsWorkspaceDir, { force: true, recursive: true });
+  mkdirSync(trailsWorkspaceDir, { recursive: true });
+  for (const subdir of trailsWorkspaceSubdirs) {
+    mkdirSync(join(trailsWorkspaceDir, subdir), { recursive: true });
+  }
+  writeFileSync(trailsGitignorePath, trailsGitignore);
+};
+
+beforeAll(() => {
+  resetTrailsWorkspace();
+});
+
+afterAll(() => {
+  resetTrailsWorkspace();
+});
+
 testExamples(app);

package/dist/src/app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../src/app.ts"],"names":[],"mappings":"AAWA,eAAO,MAAM,GAAG,+BAUf,CAAC"}
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../src/app.ts"],"names":[],"mappings":"AAsBA,eAAO,MAAM,GAAG,+BAqBf,CAAC"}

package/dist/src/app.js

@@ -4,8 +4,19 @@ 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 devClean from './trails/dev-clean.js';
+import * as devReset from './trails/dev-reset.js';
+import * as devStats from './trails/dev-stats.js';
+import * as draftPromote from './trails/draft-promote.js';
 import * as guide from './trails/guide.js';
 import * as survey from './trails/survey.js';
+import * as topoExport from './trails/topo-export.js';
+import * as topoHistory from './trails/topo-history.js';
+import * as topoPin from './trails/topo-pin.js';
+import * as topoShow from './trails/topo-show.js';
+import * as topoCommand from './trails/topo.js';
+import * as topoUnpin from './trails/topo-unpin.js';
+import * as topoVerify from './trails/topo-verify.js';
 import * as warden from './trails/warden.js';
-export const app = topo('trails', survey, guide, warden, create, createScaffold, addSurface, addVerify, addTrail);
+export const app = topo('trails', survey, topoCommand, topoShow, topoHistory, topoPin, topoUnpin, topoExport, topoVerify, devStats, devClean, devReset, guide, draftPromote, warden, create, createScaffold, addSurface, addVerify, addTrail);
 //# sourceMappingURL=app.js.map

package/dist/src/app.js.map

@@ -1 +1 @@
-{"version":3,"file":"app.js","sourceRoot":"","sources":["../../src/app.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAEtC,OAAO,KAAK,UAAU,MAAM,yBAAyB,CAAC;AACtD,OAAO,KAAK,QAAQ,MAAM,uBAAuB,CAAC;AAClD,OAAO,KAAK,SAAS,MAAM,wBAAwB,CAAC;AACpD,OAAO,KAAK,MAAM,MAAM,oBAAoB,CAAC;AAC7C,OAAO,KAAK,cAAc,MAAM,6BAA6B,CAAC;AAC9D,OAAO,KAAK,KAAK,MAAM,mBAAmB,CAAC;AAC3C,OAAO,KAAK,MAAM,MAAM,oBAAoB,CAAC;AAC7C,OAAO,KAAK,MAAM,MAAM,oBAAoB,CAAC;AAE7C,MAAM,CAAC,MAAM,GAAG,GAAG,IAAI,CACrB,QAAQ,EACR,MAAM,EACN,KAAK,EACL,MAAM,EACN,MAAM,EACN,cAAc,EACd,UAAU,EACV,SAAS,EACT,QAAQ,CACT,CAAC"}
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../../src/app.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAEtC,OAAO,KAAK,UAAU,MAAM,yBAAyB,CAAC;AACtD,OAAO,KAAK,QAAQ,MAAM,uBAAuB,CAAC;AAClD,OAAO,KAAK,SAAS,MAAM,wBAAwB,CAAC;AACpD,OAAO,KAAK,MAAM,MAAM,oBAAoB,CAAC;AAC7C,OAAO,KAAK,cAAc,MAAM,6BAA6B,CAAC;AAC9D,OAAO,KAAK,QAAQ,MAAM,uBAAuB,CAAC;AAClD,OAAO,KAAK,QAAQ,MAAM,uBAAuB,CAAC;AAClD,OAAO,KAAK,QAAQ,MAAM,uBAAuB,CAAC;AAClD,OAAO,KAAK,YAAY,MAAM,2BAA2B,CAAC;AAC1D,OAAO,KAAK,KAAK,MAAM,mBAAmB,CAAC;AAC3C,OAAO,KAAK,MAAM,MAAM,oBAAoB,CAAC;AAC7C,OAAO,KAAK,UAAU,MAAM,yBAAyB,CAAC;AACtD,OAAO,KAAK,WAAW,MAAM,0BAA0B,CAAC;AACxD,OAAO,KAAK,OAAO,MAAM,sBAAsB,CAAC;AAChD,OAAO,KAAK,QAAQ,MAAM,uBAAuB,CAAC;AAClD,OAAO,KAAK,WAAW,MAAM,kBAAkB,CAAC;AAChD,OAAO,KAAK,SAAS,MAAM,wBAAwB,CAAC;AACpD,OAAO,KAAK,UAAU,MAAM,yBAAyB,CAAC;AACtD,OAAO,KAAK,MAAM,MAAM,oBAAoB,CAAC;AAE7C,MAAM,CAAC,MAAM,GAAG,GAAG,IAAI,CACrB,QAAQ,EACR,MAAM,EACN,WAAW,EACX,QAAQ,EACR,WAAW,EACX,OAAO,EACP,SAAS,EACT,UAAU,EACV,UAAU,EACV,QAAQ,EACR,QAAQ,EACR,QAAQ,EACR,KAAK,EACL,YAAY,EACZ,MAAM,EACN,MAAM,EACN,cAAc,EACd,UAAU,EACV,SAAS,EACT,QAAQ,CACT,CAAC"}

package/dist/src/cli.js

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

package/dist/src/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AAEhD,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAEnD,2DAA2D;AAC3D,KAAK,CAAC,GAAG,EAAE;IACT,WAAW,EAAE,mDAAmD;IAChE,IAAI,EAAE,QAAQ;IACd,OAAO,EAAE,CAAC,gBAAgB,EAAE,CAAC;IAC7B,YAAY,EAAE,qBAAqB;IACnC,OAAO,EAAE,OAAO;CACjB,CAAC,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAElD,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAErD,2DAA2D;AAC3D,MAAM,OAAO,CAAC,GAAG,EAAE;IACjB,WAAW,EAAE,mDAAmD;IAChE,IAAI,EAAE,QAAQ;IACd,OAAO,EAAE,CAAC,gBAAgB,EAAE,CAAC;IAC7B,YAAY,EAAE,qBAAqB;IACnC,OAAO,EAAE,oBAAoB;CAC9B,CAAC,CAAC"}

package/dist/src/trails/add-surface.d.ts

@@ -1,13 +1,13 @@
 /**
  * `add.surface` trail -- Add a surface to an existing project.
  *
- * Generates the CLI or MCP entry point and updates package.json dependencies.
+ * Generates surface entry points and updates package.json dependencies.
  */
 export declare const addSurface: import("@ontrails/core").Trail<{
-    surface: "cli" | "mcp";
+    surface: "cli" | "http" | "mcp";
     dir?: string | undefined;
 }, {
     created: string;
     dependency: string;
-}>;
+}, never>;
 //# sourceMappingURL=add-surface.d.ts.map

package/dist/src/trails/add-surface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"add-surface.d.ts","sourceRoot":"","sources":["../../../src/trails/add-surface.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAwFH,eAAO,MAAM,UAAU;;;;;;EA0BrB,CAAC"}
+{"version":3,"file":"add-surface.d.ts","sourceRoot":"","sources":["../../../src/trails/add-surface.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAqHH,eAAO,MAAM,UAAU;;;;;;SA4BrB,CAAC"}

package/dist/src/trails/add-surface.js

@@ -1,37 +1,56 @@
 /**
  * `add.surface` trail -- Add a surface to an existing project.
  *
- * Generates the CLI or MCP entry point and updates package.json dependencies.
+ * Generates surface entry points 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 { ontrailsPackageRange, scaffoldDependencyVersions, } from '../versions.js';
 import { findTopoPath } from './project.js';
-const generateCliEntry = (appImportPath) => `import { blaze } from '@ontrails/cli/commander';
+const generateCliEntry = (appImportPath) => `import { surface } from '@ontrails/cli/commander';
 
 import { app } from '${appImportPath}';
 
-blaze(app);
+await surface(app);
 `;
-const generateMcpEntry = (appImportPath) => `import { blaze } from '@ontrails/mcp';
+const generateMcpEntry = (appImportPath) => `import { surface } from '@ontrails/mcp';
 
 import { app } from '${appImportPath}';
 
-await blaze(app);
+await surface(app);
 `;
+const generateHttpEntry = (appImportPath) => `import { surface } from '@ontrails/hono';
+
+import { app } from '${appImportPath}';
+
+await surface(app, { port: 3000 });
+`;
+const surfaceEntryFiles = {
+    cli: 'src/cli.ts',
+    http: 'src/http.ts',
+    mcp: 'src/mcp.ts',
+};
+const surfaceDependencies = {
+    cli: ['@ontrails/cli'],
+    http: ['@ontrails/hono', '@ontrails/http'],
+    mcp: ['@ontrails/mcp'],
+};
 /** Resolve the entry file for a surface. */
-const getEntryFile = (surface) => surface === 'cli' ? 'src/cli.ts' : 'src/mcp.ts';
+const getEntryFile = (surface) => surfaceEntryFiles[surface];
 // ---------------------------------------------------------------------------
 // Trail definition
 // ---------------------------------------------------------------------------
 /** Patch deps and optionally bin in a parsed package.json. */
 const patchPkgDeps = (pkg, surface, cwd) => {
-    const depName = surface === 'cli' ? '@ontrails/cli' : '@ontrails/mcp';
+    const [depName = ''] = surfaceDependencies[surface];
     const deps = (pkg['dependencies'] ?? {});
-    deps[depName] = 'workspace:*';
+    for (const dependency of surfaceDependencies[surface]) {
+        deps[dependency] = ontrailsPackageRange;
+    }
     if (surface === 'cli') {
-        deps['commander'] = '^14.0.0';
+        deps['commander'] = scaffoldDependencyVersions.commander;
         pkg['bin'] = {
             [pkg['name'] ?? basename(cwd)]: './src/cli.ts',
         };
@@ -43,7 +62,7 @@ const patchPkgDeps = (pkg, surface, cwd) => {
 const updatePkgJsonForSurface = async (cwd, surface) => {
     const pkgPath = join(cwd, 'package.json');
     if (!existsSync(pkgPath)) {
-        return surface === 'cli' ? '@ontrails/cli' : '@ontrails/mcp';
+        return surfaceDependencies[surface][0] ?? '';
     }
     const pkg = (await Bun.file(pkgPath).json());
     const depName = patchPkgDeps(pkg, surface, cwd);
@@ -55,34 +74,37 @@ const writeSurfaceEntry = async (cwd, surface) => {
     const entryFile = getEntryFile(surface);
     const fullEntryPath = join(cwd, entryFile);
     const appImport = (await findTopoPath(cwd)) ?? './app.js';
-    const content = surface === 'cli'
-        ? generateCliEntry(appImport)
-        : generateMcpEntry(appImport);
+    const generators = {
+        cli: generateCliEntry,
+        http: generateHttpEntry,
+        mcp: generateMcpEntry,
+    };
+    const content = generators[surface](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',
-    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(),
-    }),
-    run: async (input) => {
+    blaze: 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.err(new Error(`${surface.toUpperCase()} surface already exists. Nothing to do.`));
         }
         return Result.ok({
             created: await writeSurfaceEntry(cwd, surface),
             dependency: await updatePkgJsonForSurface(cwd, surface),
         });
     },
+    description: 'Add a surface to an existing project',
+    input: z.object({
+        dir: z.string().optional().describe('Project directory'),
+        surface: z.enum(['cli', 'http', 'mcp']).describe('Surface to add'),
+    }),
+    output: z.object({
+        created: z.string(),
+        dependency: z.string(),
+    }),
 });
 //# sourceMappingURL=add-surface.js.map

package/dist/src/trails/add-surface.js.map

@@ -1 +1 @@
-{"version":3,"file":"add-surface.js","sourceRoot":"","sources":["../../../src/trails/add-surface.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"add-surface.js","sourceRoot":"","sources":["../../../src/trails/add-surface.ts"],"names":[],"mappings":"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"}

package/dist/src/trails/add-trail.d.ts

@@ -2,9 +2,11 @@
  * `add.trail` trail -- Scaffold a new trail file with tests.
  */
 export declare const addTrail: import("@ontrails/core").Trail<{
+    description: string;
+    exampleName: string;
     id: string;
     intent: "read" | "write" | "destroy";
 }, {
     created: string[];
-}>;
+}, never>;
 //# sourceMappingURL=add-trail.d.ts.map

package/dist/src/trails/add-trail.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"add-trail.d.ts","sourceRoot":"","sources":["../../../src/trails/add-trail.ts"],"names":[],"mappings":"AAAA;;GAEG;AA+DH,eAAO,MAAM,QAAQ;;;;;EA4BnB,CAAC"}
+{"version":3,"file":"add-trail.d.ts","sourceRoot":"","sources":["../../../src/trails/add-trail.ts"],"names":[],"mappings":"AAAA;;GAEG;AA4EH,eAAO,MAAM,QAAQ;;;;;;;SAmDnB,CAAC"}

package/dist/src/trails/add-trail.js

@@ -8,35 +8,44 @@ import { z } from 'zod';
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
-const generateTrailFile = (id, intent) => {
+const literal = (value) => JSON.stringify(value);
+const deriveExampleMessage = (id) => `${id} completed`;
+const generateTrailFile = (id, description, exampleName, intent) => {
     const intentLine = intent === 'write' ? '' : `\n  intent: '${intent}',`;
+    const exampleMessage = deriveExampleMessage(id);
     return `import { Result, trail } from '@ontrails/core';
 import { z } from 'zod';
 
 export const ${id.replaceAll('.', '_')} = trail('${id}', {
-  description: 'TODO: describe this trail',
+  blaze: async () => {
+    return Result.ok({ message: ${literal(exampleMessage)} });
+  },
+  description: ${literal(description)},
   examples: [
     {
+      expected: { message: ${literal(exampleMessage)} },
       input: {},
-      name: 'TODO: add example',
+      name: ${literal(exampleName)},
     },
   ],
-  run: async (input) => {
-    return Result.ok({ message: 'TODO' });
-  },
   input: z.object({}),${intentLine}
   output: z.object({ message: z.string() }),
 });
 `;
 };
-const generateTestFile = (id) => {
+const generateTestFile = (id, exampleName) => {
     const moduleName = id.replaceAll('.', '-');
     const trailName = id.replaceAll('.', '_');
+    const exampleMessage = deriveExampleMessage(id);
     return `import { testTrail } from '@ontrails/testing';
 import { ${trailName} } from '../src/trails/${moduleName}.js';
 
 testTrail(${trailName}, [
-  { description: 'basic test', input: {}, expectOk: true },
+  {
+    description: ${literal(exampleName)},
+    expectValue: { message: ${literal(exampleMessage)} },
+    input: {},
+  },
 ]);
 `;
 };
@@ -49,29 +58,47 @@ const writeWithDirs = async (filePath, content) => {
     await Bun.write(filePath, content);
 };
 export const addTrail = trail('add.trail', {
-    description: 'Scaffold a new trail with tests and examples',
-    input: z.object({
-        id: z.string().describe('Trail ID (e.g., entity.update)'),
-        intent: z
-            .enum(['read', 'write', 'destroy'])
-            .default('write')
-            .describe('Trail intent'),
-    }),
-    output: z.object({
-        created: z.array(z.string()),
-    }),
-    run: async (input, ctx) => {
+    args: ['id'],
+    blaze: async (input, ctx) => {
         const { id } = input;
         const moduleName = id.replaceAll('.', '-');
         const cwd = resolve(ctx.cwd ?? '.');
         const files = new Map([
-            [`src/trails/${moduleName}.ts`, generateTrailFile(id, input.intent)],
-            [`__tests__/${moduleName}.test.ts`, generateTestFile(id)],
+            [
+                `src/trails/${moduleName}.ts`,
+                generateTrailFile(id, input.description, input.exampleName, input.intent),
+            ],
+            [
+                `__tests__/${moduleName}.test.ts`,
+                generateTestFile(id, input.exampleName),
+            ],
         ]);
         for (const [relativePath, content] of files) {
             await writeWithDirs(join(cwd, relativePath), content);
         }
         return Result.ok({ created: [...files.keys()] });
     },
+    description: 'Scaffold a new trail with tests and examples',
+    input: z.object({
+        description: z
+            .string()
+            .min(1, 'Trail description is required')
+            .describe('Trail description'),
+        exampleName: z
+            .string()
+            .min(1, 'Starter example name is required')
+            .describe('Starter example name'),
+        id: z
+            .string()
+            .min(1, 'Trail ID is required')
+            .describe('Trail ID (e.g., entity.update)'),
+        intent: z
+            .enum(['read', 'write', 'destroy'])
+            .default('write')
+            .describe('Trail intent'),
+    }),
+    output: z.object({
+        created: z.array(z.string()),
+    }),
 });
 //# sourceMappingURL=add-trail.js.map

package/dist/src/trails/add-trail.js.map

@@ -1 +1 @@
-{"version":3,"file":"add-trail.js","sourceRoot":"","sources":["../../../src/trails/add-trail.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"add-trail.js","sourceRoot":"","sources":["../../../src/trails/add-trail.ts"],"names":[],"mappings":"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"}

package/dist/src/trails/add-trailhead.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `add.trailhead` trail -- Add a trailhead to an existing project.
+ *
+ * Generates the CLI or MCP entry point and updates package.json dependencies.
+ */
+export declare const addTrailhead: import("@ontrails/core").Trail<{
+    trailhead: "cli" | "mcp";
+    dir?: string | undefined;
+}, {
+    created: string;
+    dependency: string;
+}, never>;
+//# sourceMappingURL=add-trailhead.d.ts.map

package/dist/src/trails/add-trailhead.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"add-trailhead.d.ts","sourceRoot":"","sources":["../../../src/trails/add-trailhead.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAwFH,eAAO,MAAM,YAAY;;;;;;SA4BvB,CAAC"}

package/dist/src/trails/add-trailhead.js

@@ -0,0 +1,88 @@
+/**
+ * `add.trailhead` trail -- Add a trailhead 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) => `import { surface } from '@ontrails/cli/commander';
+
+import { app } from '${appImportPath}';
+
+await surface(app);
+`;
+const generateMcpEntry = (appImportPath) => `import { surface } from '@ontrails/mcp';
+
+import { app } from '${appImportPath}';
+
+await surface(app);
+`;
+/** Resolve the entry file for a trailhead. */
+const getEntryFile = (trailhead) => trailhead === 'cli' ? 'src/cli.ts' : 'src/mcp.ts';
+// ---------------------------------------------------------------------------
+// Trail definition
+// ---------------------------------------------------------------------------
+/** Patch deps and optionally bin in a parsed package.json. */
+const patchPkgDeps = (pkg, trailhead, cwd) => {
+    const depName = trailhead === 'cli' ? '@ontrails/cli' : '@ontrails/mcp';
+    const deps = (pkg['dependencies'] ?? {});
+    deps[depName] = 'workspace:*';
+    if (trailhead === 'cli') {
+        deps['commander'] = '^14.0.0';
+        pkg['bin'] = {
+            [pkg['name'] ?? basename(cwd)]: './src/cli.ts',
+        };
+    }
+    pkg['dependencies'] = Object.fromEntries(Object.entries(deps).toSorted(([a], [b]) => a.localeCompare(b)));
+    return depName;
+};
+/** Update package.json with trailhead dependency and CLI bin if needed. */
+const updatePkgJsonForTrailhead = async (cwd, trailhead) => {
+    const pkgPath = join(cwd, 'package.json');
+    if (!existsSync(pkgPath)) {
+        return trailhead === 'cli' ? '@ontrails/cli' : '@ontrails/mcp';
+    }
+    const pkg = (await Bun.file(pkgPath).json());
+    const depName = patchPkgDeps(pkg, trailhead, cwd);
+    await Bun.write(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+    return depName;
+};
+/** Create the entry file for a trailhead and return the relative path. */
+const writeTrailheadEntry = async (cwd, trailhead) => {
+    const entryFile = getEntryFile(trailhead);
+    const fullEntryPath = join(cwd, entryFile);
+    const appImport = (await findTopoPath(cwd)) ?? './app.js';
+    const content = trailhead === 'cli'
+        ? generateCliEntry(appImport)
+        : generateMcpEntry(appImport);
+    mkdirSync(dirname(fullEntryPath), { recursive: true });
+    await Bun.write(fullEntryPath, content);
+    return entryFile;
+};
+export const addTrailhead = trail('add.trailhead', {
+    blaze: async (input) => {
+        const cwd = resolve(input.dir ?? '.');
+        const { trailhead } = input;
+        const entryFile = getEntryFile(trailhead);
+        if (existsSync(join(cwd, entryFile))) {
+            return Result.err(new Error(`${trailhead.toUpperCase()} trailhead already exists. Nothing to do.`));
+        }
+        return Result.ok({
+            created: await writeTrailheadEntry(cwd, trailhead),
+            dependency: await updatePkgJsonForTrailhead(cwd, trailhead),
+        });
+    },
+    description: 'Add a trailhead to an existing project',
+    input: z.object({
+        dir: z.string().optional().describe('Project directory'),
+        trailhead: z.enum(['cli', 'mcp']).describe('Trailhead to add'),
+    }),
+    output: z.object({
+        created: z.string(),
+        dependency: z.string(),
+    }),
+});
+//# sourceMappingURL=add-trailhead.js.map

package/dist/src/trails/add-trailhead.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"add-trailhead.js","sourceRoot":"","sources":["../../../src/trails/add-trailhead.ts"],"names":[],"mappings":"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"}

package/dist/src/trails/add-verify.d.ts

@@ -6,5 +6,5 @@ export declare const addVerify: import("@ontrails/core").Trail<{
     dir?: string | undefined;
 }, {
     created: string[];
-}>;
+}, never>;
 //# sourceMappingURL=add-verify.d.ts.map

package/dist/src/trails/add-verify.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"add-verify.d.ts","sourceRoot":"","sources":["../../../src/trails/add-verify.ts"],"names":[],"mappings":"AAAA;;GAEG;AAsDH,eAAO,MAAM,SAAS;;;;;EA8BpB,CAAC"}
+{"version":3,"file":"add-verify.d.ts","sourceRoot":"","sources":["../../../src/trails/add-verify.ts"],"names":[],"mappings":"AAAA;;GAEG;AA2DH,eAAO,MAAM,SAAS;;;;;SA8BpB,CAAC"}