@ontrails/trails 1.0.0-beta.17 → 1.0.0-beta.19

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

@@ -20,7 +20,7 @@ export const devCleanTrail = trail('dev.clean', {
 
     const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
     if (rootDirResult.isErr()) {
-      return Result.err(rootDirResult.error);
+      return rootDirResult;
     }
     const rootDir = rootDirResult.value;
     return Result.ok(
@@ -78,5 +78,5 @@ export const devCleanTrail = trail('dev.clean', {
       traces: z.number(),
     }),
   }),
-  permit: { scopes: ['dev:clean'] },
+  permit: { scopes: ['dev:write'] },
 });

package/src/trails/dev-reset.ts

@@ -17,7 +17,7 @@ export const devResetTrail = trail('dev.reset', {
 
     const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
     if (rootDirResult.isErr()) {
-      return Result.err(rootDirResult.error);
+      return rootDirResult;
     }
     const rootDir = rootDirResult.value;
     return Result.ok(resetDevState({ dryRun: input.dryRun, rootDir }));
@@ -46,5 +46,5 @@ export const devResetTrail = trail('dev.reset', {
     removedCount: z.number(),
     removedFiles: z.array(z.string()),
   }),
-  permit: { scopes: ['dev:reset'] },
+  permit: { scopes: ['dev:write'] },
 });

package/src/trails/dev-stats.ts

@@ -12,7 +12,7 @@ export const devStatsTrail = trail('dev.stats', {
   blaze: (input, ctx) => {
     const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
     if (rootDirResult.isErr()) {
-      return Result.err(rootDirResult.error);
+      return rootDirResult;
     }
     const rootDir = rootDirResult.value;
     return Result.ok(

package/src/trails/doctor.ts

@@ -0,0 +1,56 @@
+import { deriveTrailsDir, Result, trail } from '@ontrails/core';
+import { readTopoGraph } from '@ontrails/topographer';
+import { z } from 'zod';
+
+import {
+  deriveDoctorSummary,
+  withLifecycleApp,
+} from './version-lifecycle-support.js';
+
+const readDoctorForceGraph = async (
+  rootDir: string
+): Promise<Awaited<ReturnType<typeof readTopoGraph>> | undefined> => {
+  try {
+    return await readTopoGraph({ dir: deriveTrailsDir({ rootDir }) });
+  } catch {
+    // Force audit details are supplemental; stale topo locks should not block doctor counts.
+    return undefined;
+  }
+};
+
+export const doctorTrail = trail('doctor', {
+  blaze: async (input, ctx) =>
+    withLifecycleApp(input, ctx.cwd, async (app, rootDir) => {
+      const forceGraph = await readDoctorForceGraph(rootDir);
+      return Result.ok(deriveDoctorSummary(app, { forceGraph }));
+    }),
+  description: 'Diagnose trail versioning lifecycle state',
+  input: z.object({
+    module: z.string().optional().describe('Path to the app module'),
+    rootDir: z.string().optional().describe('Workspace root directory'),
+  }),
+  intent: 'read',
+  output: z.object({
+    archived: z.number(),
+    deprecated: z.number(),
+    forceDetails: z.array(
+      z
+        .object({
+          acceptedAt: z.string(),
+          change: z.enum(['modified', 'removed']),
+          detail: z.string(),
+          id: z.string(),
+          kind: z.enum(['contour', 'trail', 'signal', 'resource']),
+          reason: z.string().optional(),
+          scope: z.enum(['entry', 'graph']),
+          severity: z.literal('breaking'),
+          source: z.literal('trails compile --force'),
+        })
+        .strict()
+    ),
+    forceEvents: z.number(),
+    mode: z.literal('doctor'),
+    trails: z.number(),
+    versioned: z.number(),
+  }),
+});

package/src/trails/draft-promote.ts

@@ -945,4 +945,5 @@ export const draftPromoteTrail = trail('draft.promote', {
     ),
     updatedFiles: z.array(z.string()),
   }),
+  permit: { scopes: ['version:write'] },
 });

package/src/trails/guide.ts

@@ -36,12 +36,12 @@ export const guideTrail = trail('guide', {
   blaze: async (input, ctx) => {
     const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
     if (rootDirResult.isErr()) {
-      return Result.err(rootDirResult.error);
+      return rootDirResult;
     }
     const rootDir = rootDirResult.value;
     const leaseResult = await tryLoadFreshAppLease(input.module, rootDir);
     if (leaseResult.isErr()) {
-      return Result.err(leaseResult.error);
+      return leaseResult;
     }
     const lease = leaseResult.value;
 

package/src/trails/revise.ts

@@ -0,0 +1,53 @@
+import { Result, ValidationError, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import {
+  findLifecycleTrail,
+  forkVersionEntrySource,
+  parseLifecycleTarget,
+  reviseTrailSource,
+  withLifecycleApp,
+} from './version-lifecycle-support.js';
+
+export const reviseTrail = trail('revise', {
+  args: ['target'],
+  blaze: async (input, ctx) =>
+    withLifecycleApp(input, ctx.cwd, async (app, rootDir) => {
+      const target = parseLifecycleTarget(input.target);
+      if (target.isErr()) {
+        return target;
+      }
+      if (target.value.version !== undefined) {
+        return input.as === 'fork'
+          ? forkVersionEntrySource(rootDir, target.value)
+          : Result.err(
+              new ValidationError(
+                'Revising a specific historical entry requires --as fork'
+              )
+            );
+      }
+      const found = findLifecycleTrail(app, target.value.trailId);
+      if (found.isErr()) {
+        return found;
+      }
+      return reviseTrailSource(rootDir, found.value, input.as);
+    }),
+  description: 'Scaffold the next trail version entry',
+  input: z.object({
+    as: z
+      .enum(['revision', 'fork'])
+      .default('revision')
+      .describe('Version entry shape to scaffold'),
+    module: z.string().optional().describe('Path to the app module'),
+    rootDir: z.string().optional().describe('Workspace root directory'),
+    target: z.string().min(1).describe('Trail target, optionally trail.id@N'),
+  }),
+  intent: 'write',
+  output: z.object({
+    file: z.string(),
+    trailId: z.string(),
+    updated: z.boolean(),
+    warnings: z.array(z.string()).optional(),
+  }),
+  permit: { scopes: ['version:write'] },
+});

package/src/trails/run-example.ts

@@ -10,7 +10,7 @@ import {
   run,
   trail,
 } from '@ontrails/core';
-import type { StructuredTrailExample, Topo } from '@ontrails/core';
+import type { BasePermit, StructuredTrailExample, Topo } from '@ontrails/core';
 import { z } from 'zod';
 
 import { tryLoadFreshAppLease } from './load-app.js';
@@ -350,7 +350,8 @@ const determineMode = (
 const buildComparisonEnvelope = async (
   app: Topo,
   trailId: string,
-  exampleName: string
+  exampleName: string,
+  permit: BasePermit | undefined
 ): Promise<Result<RunExampleComparison, Error>> => {
   const exampleResult = findExample(app, trailId, exampleName);
   if (exampleResult.isErr()) {
@@ -358,7 +359,9 @@ const buildComparisonEnvelope = async (
   }
   const example = exampleResult.value;
   const mode = determineMode(example);
-  const executed = await run(app, trailId, example.input);
+  const executed = await run(app, trailId, example.input, {
+    ctx: permit === undefined ? {} : { permit },
+  });
   const actual = projectActual(executed);
 
   if (mode === 'error') {
@@ -425,7 +428,7 @@ export const runExampleTrail = trail('run.example', {
   blaze: async (input, ctx) => {
     const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
     if (rootDirResult.isErr()) {
-      return Result.err(rootDirResult.error);
+      return rootDirResult;
     }
     const rootDir = rootDirResult.value;
     const moduleResolution = await resolveRunModulePath(
@@ -435,7 +438,7 @@ export const runExampleTrail = trail('run.example', {
       input.app
     );
     if (moduleResolution.isErr()) {
-      return Result.err(moduleResolution.error);
+      return moduleResolution;
     }
 
     const leaseResult = await tryLoadFreshAppLease(
@@ -443,7 +446,7 @@ export const runExampleTrail = trail('run.example', {
       rootDir
     );
     if (leaseResult.isErr()) {
-      return Result.err(leaseResult.error);
+      return leaseResult;
     }
     const lease = leaseResult.value;
 
@@ -451,7 +454,8 @@ export const runExampleTrail = trail('run.example', {
       return await buildComparisonEnvelope(
         lease.app,
         input.id,
-        input.exampleName
+        input.exampleName,
+        ctx.permit
       );
     } finally {
       lease.release();
@@ -479,4 +483,5 @@ export const runExampleTrail = trail('run.example', {
   }),
   intent: 'write',
   output: runExampleComparisonSchema,
+  permit: { scopes: ['trails:run'] },
 });

package/src/trails/run-examples.ts

@@ -89,7 +89,7 @@ export const runExamplesTrail = trail('run.examples', {
   blaze: async (input, ctx) => {
     const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
     if (rootDirResult.isErr()) {
-      return Result.err(rootDirResult.error);
+      return rootDirResult;
     }
     const rootDir = rootDirResult.value;
     const moduleResolution = await resolveRunModulePath(
@@ -99,7 +99,7 @@ export const runExamplesTrail = trail('run.examples', {
       input.app
     );
     if (moduleResolution.isErr()) {
-      return Result.err(moduleResolution.error);
+      return moduleResolution;
     }
 
     const leaseResult = await tryLoadFreshAppLease(
@@ -107,7 +107,7 @@ export const runExamplesTrail = trail('run.examples', {
       rootDir
     );
     if (leaseResult.isErr()) {
-      return Result.err(leaseResult.error);
+      return leaseResult;
     }
     const lease = leaseResult.value;
 

package/src/trails/run.ts

@@ -322,7 +322,7 @@ export const runTrail = trail('run', {
   blaze: async (input, ctx) => {
     const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
     if (rootDirResult.isErr()) {
-      return Result.err(rootDirResult.error);
+      return rootDirResult;
     }
     const rootDir = rootDirResult.value;
 
@@ -334,18 +334,20 @@ export const runTrail = trail('run', {
       input.app
     );
     if (moduleResolution.isErr()) {
-      return Result.err(moduleResolution.error);
+      return moduleResolution;
     }
     const modulePath = moduleResolution.value;
 
     const leaseResult = await tryLoadFreshAppLease(modulePath, rootDir);
     if (leaseResult.isErr()) {
-      return Result.err(leaseResult.error);
+      return leaseResult;
     }
     const lease = leaseResult.value;
 
     try {
-      const result = await run(lease.app, input.id, input.input);
+      const result = await run(lease.app, input.id, input.input, {
+        ctx: ctx.permit === undefined ? {} : { permit: ctx.permit },
+      });
       if (result.isErr()) {
         return Result.err(result.error);
       }
@@ -400,4 +402,5 @@ export const runTrail = trail('run', {
   }),
   intent: 'write',
   output: innerTrailResultSchema,
+  permit: { scopes: ['trails:run'] },
 });