@ontrails/trails 0.2.0

package/src/trails/add-trail.ts

@@ -0,0 +1,141 @@
+/**
+ * `add.trail` trail -- Scaffold a new trail file with tests.
+ */
+
+import { resolve } from 'node:path';
+
+import { Result, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import {
+  trailIdToExportName,
+  trailIdToModuleName,
+  TRAIL_ID_MESSAGE,
+  TRAIL_ID_PATTERN,
+  validateTrailId,
+  writeProjectFile,
+} from '../project-writes.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const literal = (value: string): string => JSON.stringify(value);
+
+const deriveExampleMessage = (id: string): string => `${id} completed`;
+
+const generateTrailFile = (
+  id: string,
+  description: string,
+  exampleName: string,
+  intent: 'read' | 'write' | 'destroy'
+): string => {
+  const intentLine =
+    intent === 'write' ? '' : `\n  intent: ${literal(intent)},`;
+  const exampleMessage = deriveExampleMessage(id);
+  const trailName = trailIdToExportName(id);
+
+  return `import { Result, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+export const ${trailName} = trail(${literal(id)}, {
+  implementation: async () => {
+    return Result.ok({ message: ${literal(exampleMessage)} });
+  },
+  description: ${literal(description)},
+  examples: [
+    {
+      expected: { message: ${literal(exampleMessage)} },
+      input: {},
+      name: ${literal(exampleName)},
+    },
+  ],
+  input: z.object({}),${intentLine}
+  output: z.object({ message: z.string() }),
+});
+`;
+};
+
+const generateTestFile = (id: string, exampleName: string): string => {
+  const moduleName = trailIdToModuleName(id);
+  const trailName = trailIdToExportName(id);
+  const exampleMessage = deriveExampleMessage(id);
+  return `import { testTrail } from '@ontrails/testing';
+import { ${trailName} } from '../src/trails/${moduleName}.js';
+
+testTrail(${trailName}, [
+  {
+    description: ${literal(exampleName)},
+    expectValue: { message: ${literal(exampleMessage)} },
+    input: {},
+  },
+]);
+`;
+};
+
+// ---------------------------------------------------------------------------
+// Trail definition
+// ---------------------------------------------------------------------------
+
+export const addTrail = trail('add.trail', {
+  args: ['id'],
+  description: 'Scaffold a new trail with tests and examples',
+  implementation: async (input, ctx) => {
+    const { id } = input;
+    const validated = validateTrailId(id);
+    if (validated.isErr()) {
+      return validated;
+    }
+
+    const moduleName = trailIdToModuleName(validated.value);
+    const cwd = resolve(ctx.cwd ?? '.');
+
+    const files = new Map<string, string>([
+      [
+        `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) {
+      const written = await writeProjectFile(cwd, relativePath, content);
+      if (written.isErr()) {
+        return written;
+      }
+    }
+
+    return Result.ok({ created: [...files.keys()] });
+  },
+  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')
+      .regex(TRAIL_ID_PATTERN, TRAIL_ID_MESSAGE)
+      .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()),
+  }),
+  permit: { scopes: ['project:write'] },
+});

package/src/trails/add-verify.ts

@@ -0,0 +1,252 @@
+/**
+ * `add.verify` trail -- Add testing + warden setup to a project.
+ */
+
+import { existsSync, realpathSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+
+import { findTrailsConfigPaths } from '@ontrails/config';
+import { InternalError, Result, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import {
+  PROJECT_NAME_MESSAGE,
+  PROJECT_NAME_PATTERN,
+  projectPathExists,
+  resolveProjectDir,
+  resolveProjectPath,
+  writeProjectFile,
+} from '../project-writes.js';
+import {
+  ontrailsPackageRange,
+  scaffoldDependencyVersions,
+} from '../versions.js';
+import { resolveOperatorProjectContext } from './project-context.js';
+import { stringifyScaffoldPackageJson } from './scaffold-json.js';
+
+// ---------------------------------------------------------------------------
+// Content generators
+// ---------------------------------------------------------------------------
+
+const generateTestFile = (): string =>
+  `import { testAllEstablished } from '@ontrails/testing/established';
+import { app } from '../src/app.js';
+
+const permitScopes = [
+  ...new Set(
+    app
+      .list()
+      .flatMap((trail) =>
+        trail.permit && trail.permit !== 'public' ? trail.permit.scopes : []
+      )
+  ),
+];
+
+testAllEstablished(app, {
+  ctx: {
+    permit: { id: 'test-permit', scopes: permitScopes },
+  },
+});
+`;
+
+const generateLefthookYml = (): string =>
+  `pre-push:
+  commands:
+    warden:
+      run: bunx trails warden
+`;
+
+/** Add testing and warden devDependencies to package.json when present. */
+const patchVerifyDeps = (pkg: Record<string, unknown>): void => {
+  const devDeps = (pkg['devDependencies'] ?? {}) as Record<string, string>;
+  devDeps['@ontrails/testing'] = ontrailsPackageRange;
+  devDeps['@ontrails/warden'] = ontrailsPackageRange;
+  devDeps['lefthook'] = scaffoldDependencyVersions.lefthook;
+  pkg['devDependencies'] = Object.fromEntries(
+    Object.entries(devDeps).toSorted(([a], [b]) => a.localeCompare(b))
+  );
+};
+
+/** Update package.json in the target project with verify dependencies. */
+const updatePackageJsonForVerify = async (
+  projectDir: string
+): Promise<Result<void, Error>> => {
+  const pkgPathResult = resolveProjectPath(projectDir, 'package.json');
+  if (pkgPathResult.isErr()) {
+    return pkgPathResult;
+  }
+
+  const pkgPath = pkgPathResult.value;
+  if (!existsSync(pkgPath)) {
+    return Result.ok();
+  }
+  const pkg = (await Bun.file(pkgPath).json()) as Record<string, unknown>;
+  patchVerifyDeps(pkg);
+  const written = await writeProjectFile(
+    projectDir,
+    'package.json',
+    stringifyScaffoldPackageJson(pkg)
+  );
+  return written.isErr() ? Result.err(written.error) : Result.ok();
+};
+
+export const resolveCanonicalHookDir = (
+  projectDir: string,
+  appRoot: string,
+  workspaceRoot: string
+): Result<string, Error> => {
+  try {
+    if (realpathSync(appRoot) !== realpathSync(projectDir)) {
+      return Result.ok(projectDir);
+    }
+    return Result.ok(realpathSync(workspaceRoot));
+  } catch (error) {
+    return Result.err(
+      new InternalError('Failed to resolve add.verify hook ownership.', {
+        cause: error instanceof Error ? error : new Error(String(error)),
+        context: { appRoot, projectDir, workspaceRoot },
+      })
+    );
+  }
+};
+
+const canonicalizeProjectedProjectDir = (projectDir: string): string => {
+  const missingSegments: string[] = [];
+  let existingAncestor = resolve(projectDir);
+  while (!existsSync(existingAncestor)) {
+    const parent = dirname(existingAncestor);
+    if (parent === existingAncestor) {
+      return resolve(projectDir);
+    }
+    missingSegments.unshift(basename(existingAncestor));
+    existingAncestor = parent;
+  }
+  return join(realpathSync(existingAncestor), ...missingSegments);
+};
+
+const hasTrailsConfigAncestor = (projectDir: string): boolean => {
+  let current = resolve(projectDir);
+  while (true) {
+    if (findTrailsConfigPaths(current).length > 0) {
+      return true;
+    }
+    const parent = dirname(current);
+    if (parent === current) {
+      return false;
+    }
+    current = parent;
+  }
+};
+
+/** Place the hook at a Config-owned workspace root, never a package-only root. */
+export const resolveVerifyHookDir = async (
+  projectDir: string
+): Promise<Result<string, Error>> => {
+  let contextDir: string;
+  try {
+    contextDir = canonicalizeProjectedProjectDir(projectDir);
+  } catch (error) {
+    return Result.err(
+      new InternalError('Failed to resolve add.verify project context.', {
+        cause: error instanceof Error ? error : new Error(String(error)),
+        context: { projectDir },
+      })
+    );
+  }
+  if (!hasTrailsConfigAncestor(contextDir)) {
+    return Result.ok(projectDir);
+  }
+  const context = await resolveOperatorProjectContext({}, { cwd: contextDir });
+  if (context.isErr()) {
+    return context;
+  }
+  if (context.value.selectedExtent !== 'configured-app') {
+    return Result.ok(projectDir);
+  }
+
+  return resolveCanonicalHookDir(
+    projectDir,
+    context.value.app.rootDir,
+    context.value.projectRoot
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Trail definition
+// ---------------------------------------------------------------------------
+
+export const addVerify = trail('add.verify', {
+  description: 'Add testing and warden verification',
+  implementation: async (input) => {
+    const projectDirResult = resolveProjectDir(input.dir ?? '.', input.name);
+    if (projectDirResult.isErr()) {
+      return projectDirResult;
+    }
+
+    const projectDir = projectDirResult.value;
+    const hookDirResult = await resolveVerifyHookDir(projectDir);
+    if (hookDirResult.isErr()) {
+      return hookDirResult;
+    }
+    const hookDir = hookDirResult.value;
+    const files: string[] = [];
+
+    const writeFile = async (
+      rootDir: string,
+      relativePath: string,
+      content: string
+    ): Promise<Result<void, Error>> => {
+      const exists = projectPathExists(rootDir, relativePath);
+      if (exists.isErr()) {
+        return exists;
+      }
+      if (exists.value) {
+        return Result.ok();
+      }
+
+      const written = await writeProjectFile(rootDir, relativePath, content);
+      if (written.isErr()) {
+        return written;
+      }
+      files.push(written.value);
+      return Result.ok();
+    };
+
+    const testFile = await writeFile(
+      projectDir,
+      '__tests__/examples.test.ts',
+      generateTestFile()
+    );
+    if (testFile.isErr()) {
+      return testFile;
+    }
+
+    const lefthookFile = await writeFile(
+      hookDir,
+      'lefthook.yml',
+      generateLefthookYml()
+    );
+    if (lefthookFile.isErr()) {
+      return lefthookFile;
+    }
+
+    const packageResult = await updatePackageJsonForVerify(projectDir);
+    if (packageResult.isErr()) {
+      return packageResult;
+    }
+
+    return Result.ok({ created: files });
+  },
+  input: z.object({
+    dir: z.string().optional().describe('Parent directory'),
+    name: z
+      .string()
+      .regex(PROJECT_NAME_PATTERN, PROJECT_NAME_MESSAGE)
+      .describe('Project name'),
+  }),
+  output: z.object({
+    created: z.array(z.string()),
+  }),
+  permit: { scopes: ['project:write'] },
+  visibility: 'internal',
+});

package/src/trails/compile.ts

@@ -0,0 +1,118 @@
+import { Result, trail } from '@ontrails/core';
+import type { Topo } from '@ontrails/core';
+import type { TopoGraphOverlayRegistration } from '@ontrails/topography';
+import { z } from 'zod';
+
+import { withFreshAppLease } from './operator-context.js';
+import {
+  assertConfiguredAppBinding,
+  assertObservableProjectApps,
+  compileNeedsAppError,
+  resolveOperatorAppModuleContext,
+  resolveOperatorProjectContext,
+} from './project-context.js';
+import {
+  appProjectSelection,
+  appProjectSelectionSchema,
+} from './project-context-output.js';
+import { exportCurrentTopo } from './topo-store-support.js';
+import type { TopoExportReport } from './topo-support.js';
+import {
+  createCurrentAppExampleInput,
+  topoSnapshotOutput,
+} from './topo-support.js';
+
+export const compileCurrentTopo = async (
+  app: Topo,
+  options?: {
+    readonly force?: boolean | undefined;
+    readonly rootDir?: string;
+    readonly overlays?: readonly TopoGraphOverlayRegistration[] | undefined;
+  }
+): Promise<Result<TopoExportReport, Error>> => exportCurrentTopo(app, options);
+
+const compileTrailInputSchema = z.object({
+  app: z.string().optional().describe('Configured workspace app ID'),
+  force: z
+    .boolean()
+    .optional()
+    .describe('Record graph-only force events for breaking changes'),
+  module: z.string().optional().describe('Path to the app module'),
+  rootDir: z.string().optional().describe('Workspace root directory'),
+});
+
+type CompileTrailInput = z.output<typeof compileTrailInputSchema>;
+
+const compileTrailOutputSchema = z.object({
+  hash: z.string(),
+  lockPath: z.string(),
+  project: appProjectSelectionSchema,
+  snapshot: topoSnapshotOutput,
+});
+
+type CompileTrailOutput = z.output<typeof compileTrailOutputSchema>;
+
+const compileSelectedProject = async (
+  input: CompileTrailInput,
+  cwd: string | undefined
+): Promise<Result<CompileTrailOutput, Error>> => {
+  const contextResult = await resolveOperatorProjectContext(input, { cwd });
+  if (contextResult.isErr()) {
+    return contextResult;
+  }
+  const context = contextResult.value;
+  if (context.selectedExtent === 'workspace') {
+    return Result.err(compileNeedsAppError(context));
+  }
+  const appContext = resolveOperatorAppModuleContext(context);
+  if (appContext.isErr()) {
+    return appContext;
+  }
+  const selectedContext = appContext.value;
+  const observable = await assertObservableProjectApps(context);
+  if (observable.isErr()) {
+    return observable;
+  }
+  return withFreshAppLease(
+    selectedContext.app.modulePath,
+    selectedContext.app.rootDir,
+    async (lease) => {
+      const binding = assertConfiguredAppBinding(
+        selectedContext,
+        lease.app.name
+      );
+      if (binding.isErr()) {
+        return binding;
+      }
+      const compiled = await compileCurrentTopo(lease.app, {
+        force: input.force,
+        overlays: lease.overlays,
+        rootDir: selectedContext.app.rootDir,
+      });
+      return compiled.isErr()
+        ? compiled
+        : Result.ok({
+            ...compiled.value,
+            project: appProjectSelection(selectedContext, lease.app.name),
+          });
+    }
+  );
+};
+
+export const compileTrail = trail('compile', {
+  description: 'Compile the current topo to trails.lock',
+  examples: [
+    {
+      input: createCurrentAppExampleInput({
+        selection: 'configured-project',
+      }),
+      name: 'Compile the current topo to trails.lock',
+    },
+  ],
+  implementation: async (input: CompileTrailInput, ctx) =>
+    compileSelectedProject(input, ctx.cwd),
+  input: compileTrailInputSchema,
+  intent: 'write',
+  output: compileTrailOutputSchema,
+  permit: { scopes: ['topo:write'] },
+});