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

package/dist/src/trails/warden.js

@@ -1,88 +0,0 @@
-/**
- * `warden` trail -- Governance checks.
- *
- * Thin wrapper around `runWarden` and `formatWardenReport` from @ontrails/warden.
- */
-import { Result, trail } from '@ontrails/core';
-import { formatGitHubAnnotations, formatJson, formatSummary, formatWardenReport, runWarden, } from '@ontrails/warden';
-import { z } from 'zod';
-import { loadApp } from './load-app.js';
-// ---------------------------------------------------------------------------
-// Trail definition
-// ---------------------------------------------------------------------------
-export const wardenTrail = trail('warden', {
-    description: 'Run governance checks (lint + drift)',
-    examples: [
-        {
-            input: {
-                driftOnly: false,
-                lintOnly: false,
-            },
-            name: 'Default warden run',
-        },
-        {
-            input: {
-                format: 'github',
-            },
-            name: 'GitHub Actions annotations',
-        },
-    ],
-    implementation: async (input, ctx) => {
-        const rootDir = input.rootDir ?? ctx.cwd ?? process.cwd();
-        // oxlint-disable-next-line prefer-await-to-then -- catch converts rejection to undefined cleanly
-        const topo = await loadApp('./src/app.ts', rootDir).catch(() => undefined);
-        const report = await runWarden({
-            driftOnly: input.driftOnly,
-            lintOnly: input.lintOnly,
-            rootDir,
-            topo,
-        });
-        const formatters = {
-            github: formatGitHubAnnotations,
-            json: formatJson,
-            summary: formatSummary,
-            text: formatWardenReport,
-        };
-        const formatter = formatters[input.format] ?? formatWardenReport;
-        const formatted = formatter(report);
-        return Result.ok({
-            diagnostics: report.diagnostics,
-            drift: report.drift,
-            errorCount: report.errorCount,
-            formatted,
-            passed: report.passed,
-            warnCount: report.warnCount,
-        });
-    },
-    input: z.object({
-        driftOnly: z.boolean().default(false).describe('Only run drift detection'),
-        format: z
-            .enum(['text', 'json', 'github', 'summary'])
-            .default('text')
-            .describe('Output format: text, json, github, or summary'),
-        lintOnly: z.boolean().default(false).describe('Only run lint rules'),
-        rootDir: z.string().optional().describe('Root directory to scan'),
-    }),
-    output: z.object({
-        diagnostics: z.array(z.object({
-            filePath: z.string(),
-            line: z.number(),
-            message: z.string(),
-            rule: z.string(),
-            severity: z.enum(['error', 'warn']),
-        })),
-        drift: z
-            .object({
-            committedHash: z.string().nullable(),
-            currentHash: z.string(),
-            stale: z.boolean(),
-        })
-            .nullable(),
-        errorCount: z.number(),
-        formatted: z.string(),
-        passed: z.boolean(),
-        warnCount: z.number(),
-    }),
-    readOnly: true,
-});
-//# sourceMappingURL=warden.js.map

package/dist/src/trails/warden.js.map

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

package/dist/tsconfig.tsbuildinfo

@@ -1 +0,0 @@
-{"root":["../src/app.ts","../src/clack.ts","../src/cli.ts","../src/trails/add-surface.ts","../src/trails/add-trail.ts","../src/trails/add-verify.ts","../src/trails/create-scaffold.ts","../src/trails/create.ts","../src/trails/guide.ts","../src/trails/load-app.ts","../src/trails/project.ts","../src/trails/survey.ts","../src/trails/warden.ts","../bin/trails.ts"],"version":"5.9.3"}

package/src/__tests__/create.test.ts

@@ -1,349 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import {
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  rmSync,
-  writeFileSync,
-} from 'node:fs';
-import { tmpdir } from 'node:os';
-import { basename, dirname, join } from 'node:path';
-
-import { Result } from '@ontrails/core';
-
-import { addSurface } from '../trails/add-surface.js';
-import { addVerify } from '../trails/add-verify.js';
-import { createRoute } from '../trails/create.js';
-import { createScaffold } from '../trails/create-scaffold.js';
-import { isInsideProject } from '../trails/project.js';
-
-type Starter = 'empty' | 'entity' | 'hello';
-type Surface = 'cli' | 'mcp';
-
-const makeTempProject = (): string =>
-  join(
-    tmpdir(),
-    `trails-blaze-test-${Date.now()}-${Math.random().toString(36).slice(2)}`
-  );
-
-const readJson = (dir: string, relativePath: string): Record<string, unknown> =>
-  JSON.parse(readFileSync(join(dir, relativePath), 'utf8')) as Record<
-    string,
-    unknown
-  >;
-
-const readText = (dir: string, relativePath: string): string =>
-  readFileSync(join(dir, relativePath), 'utf8');
-
-const expectPaths = (
-  dir: string,
-  relativePaths: readonly string[],
-  expected: boolean
-): void => {
-  for (const relativePath of relativePaths) {
-    expect(existsSync(join(dir, relativePath))).toBe(expected);
-  }
-};
-
-const expectContainsAll = (
-  content: string,
-  snippets: readonly string[]
-): void => {
-  for (const snippet of snippets) {
-    expect(content).toContain(snippet);
-  }
-};
-
-const expectOk = <T>(result: Result<T, Error>): T => {
-  if (result.isErr()) {
-    throw result.error;
-  }
-  return result.value;
-};
-
-const expectErr = <T>(result: Result<T, Error>): Error => {
-  if (result.isOk()) {
-    throw new Error('Expected error result');
-  }
-  return result.error;
-};
-
-const runFollow = async (
-  id: string,
-  input: unknown
-): Promise<Result<unknown, Error>> => {
-  switch (id) {
-    case 'create.scaffold': {
-      return await createScaffold.implementation(input as never, {} as never);
-    }
-    case 'add.surface': {
-      return await addSurface.implementation(input as never, {} as never);
-    }
-    case 'add.verify': {
-      return await addVerify.implementation(input as never, {} as never);
-    }
-    default: {
-      return Result.err(new Error(`Unknown follow target: ${id}`));
-    }
-  }
-};
-
-const runBlaze = (
-  projectDir: string,
-  overrides?: Partial<{
-    starter: Starter;
-    surfaces: readonly Surface[];
-    verify: boolean;
-  }>
-) =>
-  createRoute.implementation(
-    {
-      dir: dirname(projectDir),
-      name: basename(projectDir),
-      starter: overrides?.starter ?? 'hello',
-      surfaces: [...(overrides?.surfaces ?? ['cli'])],
-      verify: overrides?.verify ?? true,
-    },
-    { follow: runFollow } as never
-  );
-
-const setupMinimalProject = (dir: string): void => {
-  mkdirSync(join(dir, 'src'), { recursive: true });
-  mkdirSync(join(dir, '.trails'), { recursive: true });
-  writeFileSync(
-    join(dir, 'src', 'app.ts'),
-    "import { topo } from '@ontrails/core';\nexport const app = topo('test');\n"
-  );
-  writeFileSync(
-    join(dir, 'package.json'),
-    JSON.stringify(
-      { dependencies: { '@ontrails/core': 'workspace:*' }, name: 'test' },
-      null,
-      2
-    )
-  );
-};
-
-const assertDefaultProjectFiles = (dir: string): void => {
-  expectPaths(
-    dir,
-    [
-      'package.json',
-      'tsconfig.json',
-      '.gitignore',
-      '.oxlintrc.json',
-      '.oxfmtrc.jsonc',
-      'src/app.ts',
-      '.trails',
-      'src/cli.ts',
-      'src/trails/hello.ts',
-      '__tests__/examples.test.ts',
-      'lefthook.yml',
-    ],
-    true
-  );
-};
-
-const assertCliPackage = (dir: string): void => {
-  const pkg = readJson(dir, 'package.json');
-  expect(pkg['name']).toBe(basename(dir));
-
-  const deps = pkg['dependencies'] as Record<string, string>;
-  expect(deps['@ontrails/core']).toBe('workspace:*');
-  expect(deps['@ontrails/cli']).toBe('workspace:*');
-  expect(deps['commander']).toBeDefined();
-
-  const devDeps = pkg['devDependencies'] as Record<string, string>;
-  expect(devDeps['@ontrails/testing']).toBe('workspace:*');
-  expect(devDeps['@ontrails/warden']).toBe('workspace:*');
-};
-
-const assertHelloApp = (dir: string): void => {
-  expectContainsAll(readText(dir, 'src/app.ts'), [
-    'topo',
-    `'${basename(dir)}'`,
-    'hello',
-  ]);
-  expectContainsAll(readText(dir, 'src/trails/hello.ts'), [
-    "import { Result, trail } from '@ontrails/core'",
-    'return Result.ok({ message:',
-  ]);
-};
-
-const assertEntityStarter = (dir: string): void => {
-  expectPaths(
-    dir,
-    [
-      'src/trails/entity.ts',
-      'src/trails/search.ts',
-      'src/trails/onboard.ts',
-      'src/events/entity-events.ts',
-      'src/store.ts',
-    ],
-    true
-  );
-  expectPaths(dir, ['src/trails/hello.ts'], false);
-  expectContainsAll(readText(dir, 'src/app.ts'), [
-    "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'",
-  ]);
-  expectContainsAll(readText(dir, 'src/trails/entity.ts'), [
-    "import { Result, trail } from '@ontrails/core'",
-    'return Result.ok({ id: input.id, name:',
-    "return Result.ok({ id: '1', name: input.name })",
-  ]);
-  expectContainsAll(readText(dir, 'src/trails/search.ts'), [
-    "import { Result, trail } from '@ontrails/core'",
-    'return Result.ok({ results: [] })',
-  ]);
-  expectContainsAll(readText(dir, 'src/trails/onboard.ts'), [
-    "import { Result, hike } from '@ontrails/core'",
-    'return Result.ok({ onboarded: true })',
-  ]);
-};
-
-const assertMcpSurface = (dir: string): void => {
-  expectPaths(dir, ['src/mcp.ts'], true);
-  expectPaths(dir, ['src/cli.ts'], false);
-  expectContainsAll(readText(dir, 'src/mcp.ts'), [
-    "import { blaze } from '@ontrails/mcp'",
-    'await blaze(app)',
-  ]);
-
-  const deps = readJson(dir, 'package.json')['dependencies'] as Record<
-    string,
-    string
-  >;
-  expect(deps['@ontrails/mcp']).toBe('workspace:*');
-  expect(deps['@ontrails/cli']).toBeUndefined();
-};
-
-const assertVerifySkipped = (dir: string): void => {
-  expectPaths(dir, ['__tests__/examples.test.ts', 'lefthook.yml'], false);
-  expect(readJson(dir, 'package.json')['devDependencies']).toBeUndefined();
-};
-
-const assertEmptyStarter = (dir: string): void => {
-  expectPaths(dir, ['src/trails/.gitkeep'], true);
-  expectPaths(dir, ['src/trails/hello.ts'], false);
-  const appContent = readText(dir, 'src/app.ts');
-  expect(appContent).toContain(`topo('${basename(dir)}')`);
-  expect(appContent).not.toContain('import * as');
-};
-
-const withTempProject = async (
-  assertion: (dir: string) => Promise<void>
-): Promise<void> => {
-  const dir = makeTempProject();
-  try {
-    await assertion(dir);
-  } finally {
-    rmSync(dir, { force: true, recursive: true });
-  }
-};
-
-describe('trails blaze', () => {
-  describe('create mode', () => {
-    test('generates project structure with defaults', async () => {
-      await withTempProject(async (dir) => {
-        expectOk(await runBlaze(dir));
-        assertDefaultProjectFiles(dir);
-        assertCliPackage(dir);
-        assertHelloApp(dir);
-      });
-    });
-
-    test('generates with entity starter', async () => {
-      await withTempProject(async (dir) => {
-        expectOk(await runBlaze(dir, { starter: 'entity' }));
-        assertEntityStarter(dir);
-      });
-    });
-
-    test('generates with MCP surface', async () => {
-      await withTempProject(async (dir) => {
-        expectOk(await runBlaze(dir, { surfaces: ['mcp'] }));
-        assertMcpSurface(dir);
-      });
-    });
-
-    test('skips verification when verify is false', async () => {
-      await withTempProject(async (dir) => {
-        expectOk(await runBlaze(dir, { verify: false }));
-        assertVerifySkipped(dir);
-      });
-    });
-
-    test('generates with empty starter', async () => {
-      await withTempProject(async (dir) => {
-        expectOk(await runBlaze(dir, { starter: 'empty' }));
-        assertEmptyStarter(dir);
-      });
-    });
-  });
-
-  describe('add-surface mode', () => {
-    test('adds MCP to existing project', async () => {
-      await withTempProject(async (dir) => {
-        setupMinimalProject(dir);
-        const result = expectOk(
-          await addSurface.implementation({ dir, surface: 'mcp' }, {} as never)
-        );
-
-        expect(result.created).toBe('src/mcp.ts');
-        expect(result.dependency).toBe('@ontrails/mcp');
-        expectPaths(dir, ['src/mcp.ts'], true);
-        expectContainsAll(readText(dir, 'src/mcp.ts'), [
-          "import { blaze } from '@ontrails/mcp'",
-        ]);
-        const deps = readJson(dir, 'package.json')['dependencies'] as Record<
-          string,
-          string
-        >;
-        expect(deps['@ontrails/mcp']).toBe('workspace:*');
-      });
-    });
-
-    test('detects already-blazed surface', async () => {
-      await withTempProject(async (dir) => {
-        mkdirSync(join(dir, 'src'), { recursive: true });
-        mkdirSync(join(dir, '.trails'), { recursive: true });
-        writeFileSync(join(dir, 'src', 'mcp.ts'), 'existing content');
-
-        const error = expectErr(
-          await addSurface.implementation({ dir, surface: 'mcp' }, {} as never)
-        );
-        expect(error.message).toBe('MCP is already blazed. Nothing to do.');
-      });
-    });
-  });
-});
-
-describe('isInsideProject', () => {
-  test('detects .trails directory', async () => {
-    await withTempProject(async (dir) => {
-      mkdirSync(join(dir, '.trails'), { recursive: true });
-      expect(await isInsideProject(dir)).toBe(true);
-    });
-  });
-
-  test('detects topo in src/', async () => {
-    await withTempProject(async (dir) => {
-      mkdirSync(join(dir, 'src'), { recursive: true });
-      writeFileSync(
-        join(dir, 'src', 'app.ts'),
-        "import { topo } from '@ontrails/core';\nexport const app = topo('app');\n"
-      );
-      expect(await isInsideProject(dir)).toBe(true);
-    });
-  });
-
-  test('returns false for empty directory', async () => {
-    await withTempProject(async (dir) => {
-      mkdirSync(dir, { recursive: true });
-      expect(await isInsideProject(dir)).toBe(false);
-    });
-  });
-});

package/src/__tests__/guide.test.ts

@@ -1,91 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-
-import type { AnyTrail } from '@ontrails/core';
-import { trail, topo, Result } from '@ontrails/core';
-import { z } from 'zod';
-
-// ---------------------------------------------------------------------------
-// Test fixtures
-// ---------------------------------------------------------------------------
-
-const helloTrail = trail('hello', {
-  description: 'Say hello',
-  detours: {
-    NotFoundError: ['search'],
-  },
-  examples: [
-    {
-      expected: { message: 'Hello, world!' },
-      input: {},
-      name: 'Default greeting',
-    },
-    {
-      expected: { message: 'Hello, Trails!' },
-      input: { name: 'Trails' },
-      name: 'Named greeting',
-    },
-  ],
-  implementation: (input) => {
-    const name = input.name ?? 'world';
-    return Result.ok({ message: `Hello, ${name}!` });
-  },
-  input: z.object({ name: z.string().optional() }),
-  output: z.object({ message: z.string() }),
-  readOnly: true,
-});
-
-const app = topo('test-app', { hello: helloTrail });
-
-// ---------------------------------------------------------------------------
-// Tests
-// ---------------------------------------------------------------------------
-
-describe('trails guide', () => {
-  test('lists trails with descriptions', () => {
-    const items = app.list();
-    expect(items.length).toBe(1);
-
-    const [hello] = items;
-    expect(hello).toBeDefined();
-    expect(hello?.id).toBe('hello');
-
-    expect((hello as AnyTrail).description).toBe('Say hello');
-  });
-
-  test('trail detail includes examples', () => {
-    const item = app.get('hello') as AnyTrail;
-    expect(item).toBeDefined();
-    expect(item.examples).toBeDefined();
-    expect(item.examples?.length).toBe(2);
-    expect(item.examples?.[0]?.name).toBe('Default greeting');
-  });
-
-  test('JSON output for trail is valid', () => {
-    const t = app.get('hello') as AnyTrail;
-    expect(t).toBeDefined();
-
-    const json = JSON.stringify({
-      description: t.description,
-      detours: t.detours,
-      examples: t.examples,
-      id: t.id,
-      kind: t.kind,
-    });
-
-    const parsed = JSON.parse(json) as Record<string, unknown>;
-    expect(parsed['id']).toBe('hello');
-    expect(parsed['kind']).toBe('trail');
-    expect(parsed['description']).toBe('Say hello');
-  });
-
-  test('non-existent trail returns undefined from topo', () => {
-    const item = app.get('does-not-exist');
-    expect(item).toBeUndefined();
-  });
-
-  test('detours are accessible on trail', () => {
-    const t = app.get('hello') as AnyTrail;
-    expect(t).toBeDefined();
-    expect(t.detours?.['NotFoundError']).toEqual(['search']);
-  });
-});

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

@@ -1,15 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import { resolve } from 'node:path';
-
-import { loadApp } from '../trails/load-app.js';
-
-describe('loadApp', () => {
-  test('resolves relative module paths from cwd', async () => {
-    // import.meta.dir is src/__tests__/, go up two to get apps/trails/
-    const cwd = resolve(import.meta.dir, '../..');
-    const app = await loadApp('./src/app.ts', cwd);
-
-    expect(app.name).toBe('trails');
-    expect(app.get('survey')).toBeDefined();
-  });
-});