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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/trails",
-  "version": "1.0.0-beta.13",
+  "version": "1.0.0-beta.14",
   "bin": {
     "trails": "./bin/trails.ts"
   },
@@ -14,15 +14,16 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.1.0",
-    "@ontrails/cli": "^1.0.0-beta.12",
-    "@ontrails/core": "^1.0.0-beta.12",
-    "@ontrails/logging": "^1.0.0-beta.12",
-    "@ontrails/schema": "^1.0.0-beta.12",
-    "@ontrails/warden": "^1.0.0-beta.12",
+    "@ontrails/cli": "^1.0.0-beta.13",
+    "@ontrails/core": "^1.0.0-beta.13",
+    "@ontrails/logging": "^1.0.0-beta.13",
+    "@ontrails/schema": "^1.0.0-beta.13",
+    "@ontrails/tracker": "^1.0.0-beta.13",
+    "@ontrails/warden": "^1.0.0-beta.13",
     "commander": "^14.0.3",
     "zod": "^4.3.5"
   },
   "devDependencies": {
-    "@ontrails/testing": "^1.0.0-beta.12"
+    "@ontrails/testing": "^1.0.0-beta.13"
   }
 }

package/src/__tests__/draft-promote.test.ts

@@ -0,0 +1,144 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { join, resolve } from 'node:path';
+
+import type { Result } from '@ontrails/core';
+import { ValidationError } from '@ontrails/core';
+
+import { draftPromoteTrail } from '../trails/draft-promote.js';
+
+const repoTempDir = (): string =>
+  join(
+    resolve(import.meta.dir, '../..'),
+    '.tmp-tests',
+    `draft-promote-${Date.now()}-${Math.random().toString(36).slice(2)}`
+  );
+
+const expectOk = <T>(result: Result<T, Error>): T => {
+  if (result.isErr()) {
+    throw result.error;
+  }
+  return result.value;
+};
+
+const expectErr = <E extends Error>(result: Result<unknown, E>): E => {
+  if (result.isOk()) {
+    throw new Error('expected result to be an error');
+  }
+  return result.error;
+};
+
+const writeDraftPromoteFixture = (dir: string): void => {
+  mkdirSync(join(dir, 'src'), { recursive: true });
+
+  writeFileSync(
+    join(dir, 'src', 'app.ts'),
+    `import { topo } from '@ontrails/core';
+import { draftPrepare } from './_draft.prepare.js';
+import { exportTrail } from './export.js';
+
+export const app = topo('draft-test', { draftPrepare, exportTrail });
+`
+  );
+
+  writeFileSync(
+    join(dir, 'src', '_draft.prepare.ts'),
+    `import { Result, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+export const draftPrepare = trail('_draft.entity.prepare', {
+  blaze: async () => Result.ok({ ready: true }),
+  input: z.object({}),
+  output: z.object({ ready: z.boolean() }),
+});
+`
+  );
+
+  writeFileSync(
+    join(dir, 'src', 'export.ts'),
+    `import { Result, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+export const exportTrail = trail('entity.export', {
+  blaze: async () => Result.ok({ exported: true }),
+  crosses: ['_draft.entity.prepare'],
+  input: z.object({}),
+  output: z.object({ exported: z.boolean() }),
+});
+`
+  );
+};
+
+const expectDraftPromoteResults = (dir: string): void => {
+  expect(existsSync(join(dir, 'src', '_draft.prepare.ts'))).toBe(false);
+  expect(existsSync(join(dir, 'src', 'prepare.ts'))).toBe(true);
+  expect(readFileSync(join(dir, 'src', 'prepare.ts'), 'utf8')).toContain(
+    "trail('entity.prepare'"
+  );
+  expect(readFileSync(join(dir, 'src', 'export.ts'), 'utf8')).toContain(
+    "crosses: ['entity.prepare']"
+  );
+  expect(readFileSync(join(dir, 'src', 'app.ts'), 'utf8')).toContain(
+    "from './prepare.js'"
+  );
+};
+
+describe('draft.promote', () => {
+  test('promotes draft ids, renames files, and updates imports', async () => {
+    const dir = repoTempDir();
+
+    try {
+      writeDraftPromoteFixture(dir);
+
+      const result = expectOk(
+        await draftPromoteTrail.blaze(
+          {
+            fromId: '_draft.entity.prepare',
+            renameFiles: true,
+            rootDir: dir,
+            toId: 'entity.prepare',
+          },
+          { cwd: dir } as never
+        )
+      );
+
+      expect(result.promotedEstablished).toBe(true);
+      expect(result.remainingDraftIds).toEqual([]);
+      expect(result.updatedFiles).toEqual(
+        expect.arrayContaining(['src/app.ts', 'src/export.ts'])
+      );
+      expect(result.renamedFiles).toEqual([
+        {
+          from: 'src/_draft.prepare.ts',
+          to: 'src/prepare.ts',
+        },
+      ]);
+      expectDraftPromoteResults(dir);
+    } finally {
+      rmSync(dir, { force: true, recursive: true });
+    }
+  });
+
+  test('returns ValidationError when rootDir does not exist', async () => {
+    const error = expectErr(
+      await draftPromoteTrail.blaze(
+        {
+          fromId: '_draft.entity.prepare',
+          renameFiles: true,
+          rootDir: join(repoTempDir(), 'missing'),
+          toId: 'entity.prepare',
+        },
+        { cwd: process.cwd() } as never
+      )
+    );
+
+    expect(error).toBeInstanceOf(ValidationError);
+    expect(error.message).toContain('rootDir does not exist');
+  });
+});

package/src/__tests__/load-app.test.ts

@@ -1,8 +1,37 @@
 import { describe, expect, test } from 'bun:test';
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
 import { resolve } from 'node:path';
 
 import { loadApp } from '../trails/load-app.js';
 
+const writeLoadAppFixture = (cwd: string, name: string): void => {
+  writeFileSync(
+    resolve(cwd, 'src/app.ts'),
+    `export const app = {
+  name: '${name}',
+  trails: new Map(),
+  signals: new Map(),
+  provisions: new Map()
+};`
+  );
+};
+
+const assertLoadAppCaching = async (cwd: string): Promise<void> => {
+  writeLoadAppFixture(cwd, 'first');
+
+  const first = await loadApp('./src/app.ts', cwd);
+
+  writeLoadAppFixture(cwd, 'second');
+
+  const cached = await loadApp('./src/app.ts', cwd);
+  const fresh = await loadApp('./src/app.ts', cwd, { fresh: true });
+
+  expect(first.name).toBe('first');
+  expect(cached.name).toBe('first');
+  expect(fresh.name).toBe('second');
+};
+
 describe('loadApp', () => {
   test('resolves relative module paths from cwd', async () => {
     // import.meta.dir is src/__tests__/, go up two to get apps/trails/
@@ -12,4 +41,18 @@ describe('loadApp', () => {
     expect(app.name).toBe('trails');
     expect(app.get('survey')).toBeDefined();
   });
+
+  test('can bypass module caching with fresh loading', async () => {
+    const cwd = resolve(
+      tmpdir(),
+      `trails-load-app-${Date.now()}-${Math.random().toString(36).slice(2)}`
+    );
+
+    try {
+      mkdirSync(resolve(cwd, 'src'), { recursive: true });
+      await assertLoadAppCaching(cwd);
+    } finally {
+      rmSync(cwd, { force: true, recursive: true });
+    }
+  });
 });

package/src/__tests__/survey.test.ts

@@ -1,4 +1,12 @@
 import { describe, expect, test } from 'bun:test';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { join, resolve } from 'node:path';
 
 import { Result, provision, topo, trail } from '@ontrails/core';
 import {
@@ -13,6 +21,7 @@ import {
   generateBriefReport,
   generateSurveyList,
   generateTrailDetail,
+  surveyTrail,
 } from '../trails/survey.js';
 import type {
   BriefReport,
@@ -68,6 +77,49 @@ const app = topo('test-app', {
   hello: helloTrail,
 });
 
+const expectOk = <T>(result: Result<T, Error>): T => {
+  if (result.isErr()) {
+    throw result.error;
+  }
+  return result.value;
+};
+
+const writeSurveyAppFixture = (dir: string): void => {
+  mkdirSync(join(dir, 'src'), { recursive: true });
+  writeFileSync(
+    join(dir, 'src', 'app.ts'),
+    `import { Result, provision, topo, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+const hello = trail('hello', {
+  blaze: async (input) => Result.ok({ message: \`Hello, \${input.name ?? 'world'}!\` }),
+  input: z.object({ name: z.string().optional() }),
+  intent: 'read',
+  output: z.object({ message: z.string() }),
+  provisions: [
+    provision('db.main', {
+      create: () => Result.ok({ source: 'factory' }),
+    }),
+  ],
+});
+
+const [dbMain] = hello.provisions;
+if (!dbMain) {
+  throw new Error('expected hello to declare db.main');
+}
+
+export const app = topo('survey-fixture', { dbMain, hello });
+`
+  );
+};
+
+const repoTempDir = (): string =>
+  join(
+    resolve(import.meta.dir, '../..'),
+    '.tmp-tests',
+    `trails-survey-${Date.now()}-${Math.random().toString(36).slice(2)}`
+  );
+
 // ---------------------------------------------------------------------------
 // Tests
 // ---------------------------------------------------------------------------
@@ -86,6 +138,7 @@ describe('trails survey', () => {
     const trailheadMap = generateTrailheadMap(app);
     const hello = trailheadMap.entries.find((e) => e.id === 'hello');
     expect(hello).toBeDefined();
+    expect(hello?.cli?.path).toEqual(['hello']);
     expect(hello?.kind).toBe('trail');
     expect(hello?.intent).toBe('read');
     expect(hello?.exampleCount).toBe(1);
@@ -214,3 +267,35 @@ describe('trails survey provisions section', () => {
     });
   });
 });
+
+describe('trails survey generate', () => {
+  test('delegates to topo export and writes a structured lock', async () => {
+    const dir = repoTempDir();
+
+    try {
+      writeSurveyAppFixture(dir);
+
+      const generated = expectOk(
+        await surveyTrail.blaze({ generate: true, module: './src/app.ts' }, {
+          cwd: dir,
+        } as never)
+      ) as {
+        readonly hash: string;
+        readonly lockPath: string;
+        readonly mapPath: string;
+      };
+
+      expect(generated.hash).toHaveLength(64);
+      expect(existsSync(join(dir, '.trails', '_trailhead.json'))).toBe(true);
+      expect(existsSync(join(dir, '.trails', 'trails.lock'))).toBe(true);
+      expect(
+        JSON.parse(readFileSync(join(dir, '.trails', 'trails.lock'), 'utf8'))
+      ).toMatchObject({
+        hash: generated.hash,
+        version: 1,
+      });
+    } finally {
+      rmSync(dir, { force: true, recursive: true });
+    }
+  });
+});