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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (201) hide show
  1. package/CHANGELOG.md +197 -2
  2. package/README.md +27 -0
  3. package/package.json +19 -8
  4. package/src/app.ts +15 -5
  5. package/src/cli.ts +303 -10
  6. package/src/completions.ts +240 -0
  7. package/src/load-app-mirror.ts +160 -0
  8. package/src/local-state-io.ts +153 -0
  9. package/src/project-writes.ts +320 -0
  10. package/src/run-collision.ts +125 -0
  11. package/src/run-completions-install.ts +179 -0
  12. package/src/run-example.ts +149 -0
  13. package/src/run-examples.ts +148 -0
  14. package/src/run-quiet.ts +75 -0
  15. package/src/run-trace.ts +273 -0
  16. package/src/run-warden.ts +39 -0
  17. package/src/run-watch.ts +432 -0
  18. package/src/scaffold-versions.generated.ts +12 -0
  19. package/src/trails/add-surface.ts +45 -23
  20. package/src/trails/add-trail.ts +27 -17
  21. package/src/trails/add-verify.ts +57 -17
  22. package/src/trails/completions-complete.ts +165 -0
  23. package/src/trails/completions.ts +47 -0
  24. package/src/trails/create-scaffold.ts +86 -33
  25. package/src/trails/create.ts +11 -3
  26. package/src/trails/dev-clean.ts +6 -1
  27. package/src/trails/dev-reset.ts +6 -1
  28. package/src/trails/dev-stats.ts +6 -1
  29. package/src/trails/dev-support.ts +29 -17
  30. package/src/trails/draft-promote.ts +289 -80
  31. package/src/trails/guide.ts +54 -34
  32. package/src/trails/load-app.ts +251 -56
  33. package/src/trails/root-dir.ts +21 -0
  34. package/src/trails/run-example.ts +482 -0
  35. package/src/trails/run-examples.ts +141 -0
  36. package/src/trails/run.ts +403 -0
  37. package/src/trails/survey.ts +506 -200
  38. package/src/trails/topo-activation.ts +385 -0
  39. package/src/trails/topo-compile.ts +55 -0
  40. package/src/trails/topo-history.ts +6 -1
  41. package/src/trails/topo-output-schemas.ts +175 -0
  42. package/src/trails/topo-pin.ts +19 -6
  43. package/src/trails/topo-read-support.ts +171 -228
  44. package/src/trails/topo-reports.ts +400 -25
  45. package/src/trails/topo-store-support.ts +43 -19
  46. package/src/trails/topo-support.ts +18 -28
  47. package/src/trails/topo-unpin.ts +6 -1
  48. package/src/trails/topo-verify.ts +18 -5
  49. package/src/trails/topo.ts +60 -23
  50. package/src/trails/warden-guide.ts +121 -0
  51. package/src/trails/warden.ts +137 -56
  52. package/src/versions.ts +3 -18
  53. package/.turbo/turbo-build.log +0 -1
  54. package/.turbo/turbo-lint.log +0 -3
  55. package/.turbo/turbo-typecheck.log +0 -1
  56. package/__tests__/examples.test.ts +0 -45
  57. package/dist/bin/trails.d.ts +0 -3
  58. package/dist/bin/trails.d.ts.map +0 -1
  59. package/dist/bin/trails.js +0 -4
  60. package/dist/bin/trails.js.map +0 -1
  61. package/dist/src/app.d.ts +0 -2
  62. package/dist/src/app.d.ts.map +0 -1
  63. package/dist/src/app.js +0 -22
  64. package/dist/src/app.js.map +0 -1
  65. package/dist/src/clack.d.ts +0 -9
  66. package/dist/src/clack.d.ts.map +0 -1
  67. package/dist/src/clack.js +0 -84
  68. package/dist/src/clack.js.map +0 -1
  69. package/dist/src/cli.d.ts +0 -2
  70. package/dist/src/cli.d.ts.map +0 -1
  71. package/dist/src/cli.js +0 -14
  72. package/dist/src/cli.js.map +0 -1
  73. package/dist/src/trails/add-surface.d.ts +0 -13
  74. package/dist/src/trails/add-surface.d.ts.map +0 -1
  75. package/dist/src/trails/add-surface.js +0 -110
  76. package/dist/src/trails/add-surface.js.map +0 -1
  77. package/dist/src/trails/add-trail.d.ts +0 -12
  78. package/dist/src/trails/add-trail.d.ts.map +0 -1
  79. package/dist/src/trails/add-trail.js +0 -104
  80. package/dist/src/trails/add-trail.js.map +0 -1
  81. package/dist/src/trails/add-trailhead.d.ts +0 -13
  82. package/dist/src/trails/add-trailhead.d.ts.map +0 -1
  83. package/dist/src/trails/add-trailhead.js +0 -88
  84. package/dist/src/trails/add-trailhead.js.map +0 -1
  85. package/dist/src/trails/add-verify.d.ts +0 -10
  86. package/dist/src/trails/add-verify.d.ts.map +0 -1
  87. package/dist/src/trails/add-verify.js +0 -68
  88. package/dist/src/trails/add-verify.js.map +0 -1
  89. package/dist/src/trails/create-scaffold.d.ts +0 -15
  90. package/dist/src/trails/create-scaffold.d.ts.map +0 -1
  91. package/dist/src/trails/create-scaffold.js +0 -295
  92. package/dist/src/trails/create-scaffold.js.map +0 -1
  93. package/dist/src/trails/create.d.ts +0 -18
  94. package/dist/src/trails/create.d.ts.map +0 -1
  95. package/dist/src/trails/create.js +0 -126
  96. package/dist/src/trails/create.js.map +0 -1
  97. package/dist/src/trails/dev-clean.d.ts +0 -9
  98. package/dist/src/trails/dev-clean.d.ts.map +0 -1
  99. package/dist/src/trails/dev-clean.js +0 -66
  100. package/dist/src/trails/dev-clean.js.map +0 -1
  101. package/dist/src/trails/dev-reset.d.ts +0 -6
  102. package/dist/src/trails/dev-reset.d.ts.map +0 -1
  103. package/dist/src/trails/dev-reset.js +0 -39
  104. package/dist/src/trails/dev-reset.js.map +0 -1
  105. package/dist/src/trails/dev-stats.d.ts +0 -7
  106. package/dist/src/trails/dev-stats.d.ts.map +0 -1
  107. package/dist/src/trails/dev-stats.js +0 -61
  108. package/dist/src/trails/dev-stats.js.map +0 -1
  109. package/dist/src/trails/dev-support.d.ts +0 -64
  110. package/dist/src/trails/dev-support.d.ts.map +0 -1
  111. package/dist/src/trails/dev-support.js +0 -181
  112. package/dist/src/trails/dev-support.js.map +0 -1
  113. package/dist/src/trails/draft-promote.d.ts +0 -18
  114. package/dist/src/trails/draft-promote.d.ts.map +0 -1
  115. package/dist/src/trails/draft-promote.js +0 -400
  116. package/dist/src/trails/draft-promote.js.map +0 -1
  117. package/dist/src/trails/guide.d.ts +0 -21
  118. package/dist/src/trails/guide.d.ts.map +0 -1
  119. package/dist/src/trails/guide.js +0 -61
  120. package/dist/src/trails/guide.js.map +0 -1
  121. package/dist/src/trails/load-app.d.ts +0 -12
  122. package/dist/src/trails/load-app.d.ts.map +0 -1
  123. package/dist/src/trails/load-app.js +0 -415
  124. package/dist/src/trails/load-app.js.map +0 -1
  125. package/dist/src/trails/project.d.ts +0 -8
  126. package/dist/src/trails/project.d.ts.map +0 -1
  127. package/dist/src/trails/project.js +0 -54
  128. package/dist/src/trails/project.js.map +0 -1
  129. package/dist/src/trails/survey.d.ts +0 -18
  130. package/dist/src/trails/survey.d.ts.map +0 -1
  131. package/dist/src/trails/survey.js +0 -234
  132. package/dist/src/trails/survey.js.map +0 -1
  133. package/dist/src/trails/topo-constants.d.ts +0 -3
  134. package/dist/src/trails/topo-constants.d.ts.map +0 -1
  135. package/dist/src/trails/topo-constants.js +0 -3
  136. package/dist/src/trails/topo-constants.js.map +0 -1
  137. package/dist/src/trails/topo-export.d.ts +0 -19
  138. package/dist/src/trails/topo-export.d.ts.map +0 -1
  139. package/dist/src/trails/topo-export.js +0 -31
  140. package/dist/src/trails/topo-export.js.map +0 -1
  141. package/dist/src/trails/topo-history.d.ts +0 -20
  142. package/dist/src/trails/topo-history.d.ts.map +0 -1
  143. package/dist/src/trails/topo-history.js +0 -32
  144. package/dist/src/trails/topo-history.js.map +0 -1
  145. package/dist/src/trails/topo-pin.d.ts +0 -17
  146. package/dist/src/trails/topo-pin.d.ts.map +0 -1
  147. package/dist/src/trails/topo-pin.js +0 -31
  148. package/dist/src/trails/topo-pin.js.map +0 -1
  149. package/dist/src/trails/topo-read-support.d.ts +0 -58
  150. package/dist/src/trails/topo-read-support.d.ts.map +0 -1
  151. package/dist/src/trails/topo-read-support.js +0 -167
  152. package/dist/src/trails/topo-read-support.js.map +0 -1
  153. package/dist/src/trails/topo-reports.d.ts +0 -54
  154. package/dist/src/trails/topo-reports.d.ts.map +0 -1
  155. package/dist/src/trails/topo-reports.js +0 -128
  156. package/dist/src/trails/topo-reports.js.map +0 -1
  157. package/dist/src/trails/topo-show.d.ts +0 -23
  158. package/dist/src/trails/topo-show.d.ts.map +0 -1
  159. package/dist/src/trails/topo-show.js +0 -49
  160. package/dist/src/trails/topo-show.js.map +0 -1
  161. package/dist/src/trails/topo-store-support.d.ts +0 -13
  162. package/dist/src/trails/topo-store-support.d.ts.map +0 -1
  163. package/dist/src/trails/topo-store-support.js +0 -55
  164. package/dist/src/trails/topo-store-support.js.map +0 -1
  165. package/dist/src/trails/topo-support.d.ts +0 -76
  166. package/dist/src/trails/topo-support.d.ts.map +0 -1
  167. package/dist/src/trails/topo-support.js +0 -132
  168. package/dist/src/trails/topo-support.js.map +0 -1
  169. package/dist/src/trails/topo-unpin.d.ts +0 -20
  170. package/dist/src/trails/topo-unpin.d.ts.map +0 -1
  171. package/dist/src/trails/topo-unpin.js +0 -44
  172. package/dist/src/trails/topo-unpin.js.map +0 -1
  173. package/dist/src/trails/topo-verify.d.ts +0 -5
  174. package/dist/src/trails/topo-verify.d.ts.map +0 -1
  175. package/dist/src/trails/topo-verify.js +0 -24
  176. package/dist/src/trails/topo-verify.js.map +0 -1
  177. package/dist/src/trails/topo.d.ts +0 -5
  178. package/dist/src/trails/topo.d.ts.map +0 -1
  179. package/dist/src/trails/topo.js +0 -63
  180. package/dist/src/trails/topo.js.map +0 -1
  181. package/dist/src/trails/warden.d.ts +0 -20
  182. package/dist/src/trails/warden.d.ts.map +0 -1
  183. package/dist/src/trails/warden.js +0 -98
  184. package/dist/src/trails/warden.js.map +0 -1
  185. package/dist/src/versions.d.ts +0 -12
  186. package/dist/src/versions.d.ts.map +0 -1
  187. package/dist/src/versions.js +0 -23
  188. package/dist/src/versions.js.map +0 -1
  189. package/dist/tsconfig.tsbuildinfo +0 -1
  190. package/src/__tests__/add-trail.test.ts +0 -97
  191. package/src/__tests__/create.test.ts +0 -415
  192. package/src/__tests__/draft-promote.test.ts +0 -144
  193. package/src/__tests__/guide.test.ts +0 -96
  194. package/src/__tests__/load-app.test.ts +0 -419
  195. package/src/__tests__/survey.test.ts +0 -377
  196. package/src/__tests__/topo-dev.test.ts +0 -426
  197. package/src/__tests__/warden.test.ts +0 -74
  198. package/src/trails/topo-export.ts +0 -35
  199. package/src/trails/topo-show.ts +0 -54
  200. package/tsconfig.json +0 -9
  201. package/tsconfig.tests.json +0 -10
@@ -6,6 +6,7 @@ import {
6
6
  removePinnedTopoSnapshot,
7
7
  topoSnapshotOutput,
8
8
  } from './topo-support.js';
9
+ import { resolveTrailRootDir } from './root-dir.js';
9
10
 
10
11
  export const topoUnpinTrail = trail('topo.unpin', {
11
12
  blaze: (input, ctx) => {
@@ -17,7 +18,11 @@ export const topoUnpinTrail = trail('topo.unpin', {
17
18
  );
18
19
  }
19
20
 
20
- const rootDir = input.rootDir ?? ctx.cwd ?? process.cwd();
21
+ const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
22
+ if (rootDirResult.isErr()) {
23
+ return Result.err(rootDirResult.error);
24
+ }
25
+ const rootDir = rootDirResult.value;
21
26
  return Result.ok(
22
27
  removePinnedTopoSnapshot({
23
28
  dryRun: input.dryRun,
@@ -1,14 +1,27 @@
1
- import { trail } from '@ontrails/core';
1
+ import { Result, trail } from '@ontrails/core';
2
2
  import { z } from 'zod';
3
3
 
4
- import { loadApp } from './load-app.js';
4
+ import { tryLoadFreshAppLease } from './load-app.js';
5
+ import { resolveTrailRootDir } from './root-dir.js';
5
6
  import { verifyCurrentTopo } from './topo-read-support.js';
6
7
 
7
8
  export const topoVerifyTrail = trail('topo.verify', {
8
9
  blaze: async (input, ctx) => {
9
- const rootDir = input.rootDir ?? ctx.cwd ?? process.cwd();
10
- const app = await loadApp(input.module, rootDir);
11
- return verifyCurrentTopo(app, { rootDir });
10
+ const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
11
+ if (rootDirResult.isErr()) {
12
+ return Result.err(rootDirResult.error);
13
+ }
14
+ const rootDir = rootDirResult.value;
15
+ const leaseResult = await tryLoadFreshAppLease(input.module, rootDir);
16
+ if (leaseResult.isErr()) {
17
+ return Result.err(leaseResult.error);
18
+ }
19
+ const lease = leaseResult.value;
20
+ try {
21
+ return await verifyCurrentTopo(lease.app, { rootDir });
22
+ } finally {
23
+ lease.release();
24
+ }
12
25
  },
13
26
  description: 'Verify that the committed lockfile matches the current topo',
14
27
  input: z.object({
@@ -1,8 +1,11 @@
1
1
  import { Result, trail } from '@ontrails/core';
2
2
  import { z } from 'zod';
3
3
 
4
- import { loadApp } from './load-app.js';
4
+ import { tryLoadFreshAppLease } from './load-app.js';
5
+ import { resolveTrailRootDir } from './root-dir.js';
6
+ import { activationOverviewOutput } from './topo-output-schemas.js';
5
7
  import { buildTopoSummary } from './topo-read-support.js';
8
+ import { createIsolatedExampleInput } from './topo-support.js';
6
9
 
7
10
  const summaryOutput = z.object({
8
11
  app: z.object({
@@ -22,26 +25,48 @@ const summaryOutput = z.object({
22
25
  }),
23
26
  dbPath: z.string(),
24
27
  list: z.object({
28
+ activation: activationOverviewOutput,
25
29
  count: z.number(),
26
- entries: z.array(
27
- z.object({
28
- examples: z.number(),
29
- id: z.string(),
30
- kind: z.string(),
31
- safety: z.string(),
32
- })
33
- ),
30
+ entries: z
31
+ .array(
32
+ z.object({
33
+ activatedBy: z.array(z.string()).readonly(),
34
+ activates: z.array(z.string()).readonly(),
35
+ examples: z.number(),
36
+ id: z.string(),
37
+ kind: z.string(),
38
+ safety: z.string(),
39
+ })
40
+ )
41
+ .readonly(),
34
42
  resourceCount: z.number(),
35
- resources: z.array(
36
- z.object({
37
- description: z.string().nullable(),
38
- health: z.enum(['available', 'none']),
39
- id: z.string(),
40
- kind: z.literal('resource'),
41
- lifetime: z.literal('singleton'),
42
- usedBy: z.array(z.string()),
43
- })
44
- ),
43
+ resources: z
44
+ .array(
45
+ z.object({
46
+ description: z.string().nullable(),
47
+ health: z.enum(['available', 'none']),
48
+ id: z.string(),
49
+ kind: z.literal('resource'),
50
+ lifetime: z.literal('singleton'),
51
+ usedBy: z.array(z.string()).readonly(),
52
+ })
53
+ )
54
+ .readonly(),
55
+ signalCount: z.number(),
56
+ signals: z
57
+ .array(
58
+ z.object({
59
+ consumers: z.array(z.string()).readonly(),
60
+ description: z.string().nullable(),
61
+ examples: z.number(),
62
+ from: z.array(z.string()).readonly(),
63
+ id: z.string(),
64
+ kind: z.literal('signal'),
65
+ payloadSchema: z.boolean(),
66
+ producers: z.array(z.string()).readonly(),
67
+ })
68
+ )
69
+ .readonly(),
45
70
  }),
46
71
  lockExists: z.boolean(),
47
72
  lockPath: z.string(),
@@ -49,14 +74,26 @@ const summaryOutput = z.object({
49
74
 
50
75
  export const topoTrail = trail('topo', {
51
76
  blaze: async (input, ctx) => {
52
- const rootDir = input.rootDir ?? ctx.cwd ?? process.cwd();
53
- const app = await loadApp(input.module, rootDir);
54
- return Result.ok(buildTopoSummary(app, { rootDir }));
77
+ const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
78
+ if (rootDirResult.isErr()) {
79
+ return Result.err(rootDirResult.error);
80
+ }
81
+ const rootDir = rootDirResult.value;
82
+ const leaseResult = await tryLoadFreshAppLease(input.module, rootDir);
83
+ if (leaseResult.isErr()) {
84
+ return Result.err(leaseResult.error);
85
+ }
86
+ const lease = leaseResult.value;
87
+ try {
88
+ return Result.ok(buildTopoSummary(lease.app, { rootDir }));
89
+ } finally {
90
+ lease.release();
91
+ }
55
92
  },
56
93
  description: 'Show the current topo summary and entry list',
57
94
  examples: [
58
95
  {
59
- input: {},
96
+ input: createIsolatedExampleInput('topo-summary'),
60
97
  name: 'Show the current topo summary',
61
98
  },
62
99
  ],
@@ -0,0 +1,121 @@
1
+ import type { FieldOverride } from '@ontrails/core';
2
+ import { Result, trail } from '@ontrails/core';
3
+ import {
4
+ buildWardenGuideManifest,
5
+ formatWardenGuide,
6
+ wardenDepthValues,
7
+ wardenGuideFormatValues,
8
+ wardenRuleConcerns,
9
+ wardenRuleLifecycleStates,
10
+ wardenRuleScopes,
11
+ wardenRuleTiers,
12
+ } from '@ontrails/warden';
13
+ import { z } from 'zod';
14
+
15
+ const wardenGuidanceLinkSchema = z.object({
16
+ label: z.string(),
17
+ path: z.string().optional(),
18
+ url: z.string().optional(),
19
+ });
20
+
21
+ const wardenGuidanceSchema = z.object({
22
+ commands: z.array(z.string()).readonly().optional(),
23
+ docs: z.array(wardenGuidanceLinkSchema).readonly().optional(),
24
+ relatedRules: z.array(z.string()).readonly().optional(),
25
+ steps: z.array(z.string()).readonly().optional(),
26
+ summary: z.string(),
27
+ });
28
+
29
+ const wardenRuleGuideEntrySchema = z.object({
30
+ concern: z.enum(wardenRuleConcerns),
31
+ depth: z.enum(wardenDepthValues),
32
+ description: z.string(),
33
+ docs: z.array(wardenGuidanceLinkSchema).readonly(),
34
+ guidance: wardenGuidanceSchema.optional(),
35
+ id: z.string(),
36
+ invariant: z.string(),
37
+ lifecycle: z.object({
38
+ retireWhen: z.string().optional(),
39
+ state: z.enum(wardenRuleLifecycleStates),
40
+ }),
41
+ scope: z.enum(wardenRuleScopes),
42
+ severity: z.enum(['error', 'warn']),
43
+ tier: z.enum(wardenRuleTiers),
44
+ });
45
+
46
+ const wardenGuideManifestSchema = z.object({
47
+ generatedFrom: z.object({
48
+ package: z.literal('@ontrails/warden'),
49
+ registries: z.tuple([
50
+ z.literal('wardenRules'),
51
+ z.literal('wardenTopoRules'),
52
+ ]),
53
+ source: z.literal('builtin-rule-metadata'),
54
+ }),
55
+ kind: z.literal('trails-warden-guide-manifest'),
56
+ ruleCount: z.number(),
57
+ rules: z.array(wardenRuleGuideEntrySchema).readonly(),
58
+ version: z.literal(1),
59
+ });
60
+
61
+ const wardenGuideInputSchema = z.object({
62
+ guideFormat: z
63
+ .enum(wardenGuideFormatValues)
64
+ .default('markdown')
65
+ .describe('Guide output format'),
66
+ });
67
+
68
+ const wardenGuideFields = {
69
+ guideFormat: {
70
+ aliases: true,
71
+ options: [
72
+ {
73
+ hint: 'Human-readable Warden guide',
74
+ label: 'Markdown',
75
+ value: 'markdown',
76
+ },
77
+ {
78
+ hint: 'Compact guidance for agent context',
79
+ label: 'Agent JSON',
80
+ value: 'agent-json',
81
+ },
82
+ {
83
+ hint: 'Full structured rule manifest',
84
+ label: 'Manifest',
85
+ value: 'manifest',
86
+ },
87
+ ],
88
+ },
89
+ } satisfies Readonly<
90
+ Record<'guideFormat', FieldOverride & { readonly aliases: true }>
91
+ >;
92
+
93
+ export const wardenGuideTrail = trail('warden.guide', {
94
+ blaze: (input) => {
95
+ const manifest = buildWardenGuideManifest();
96
+ return Result.ok({
97
+ format: input.guideFormat,
98
+ formatted: formatWardenGuide(manifest, input.guideFormat),
99
+ manifest,
100
+ });
101
+ },
102
+ description: 'Project Warden rule guidance as markdown or JSON',
103
+ examples: [
104
+ {
105
+ input: { guideFormat: 'markdown' },
106
+ name: 'Markdown guide',
107
+ },
108
+ {
109
+ input: { guideFormat: 'agent-json' },
110
+ name: 'Agent JSON guide',
111
+ },
112
+ ],
113
+ fields: wardenGuideFields,
114
+ input: wardenGuideInputSchema,
115
+ intent: 'read',
116
+ output: z.object({
117
+ format: z.enum(wardenGuideFormatValues),
118
+ formatted: z.string(),
119
+ manifest: wardenGuideManifestSchema,
120
+ }),
121
+ });
@@ -1,59 +1,159 @@
1
1
  /**
2
2
  * `warden` trail -- Governance checks.
3
3
  *
4
- * Thin wrapper around `runWarden` and `formatWardenReport` from @ontrails/warden.
4
+ * Thin wrapper around the shared @ontrails/warden command surface.
5
5
  */
6
6
 
7
7
  import { Result, trail } from '@ontrails/core';
8
8
  import {
9
- formatGitHubAnnotations,
10
- formatJson,
11
- formatSummary,
12
- formatWardenReport,
13
- runWarden,
9
+ diagnosticSchema,
10
+ runWardenCommand,
11
+ wardenDepthValues,
12
+ wardenDraftsValues,
13
+ wardenFailOnValues,
14
+ wardenFormatValues,
15
+ wardenLockValues,
14
16
  } from '@ontrails/warden';
15
17
  import { z } from 'zod';
16
18
 
17
- import { loadApp } from './load-app.js';
19
+ import { resolveTrailRootDir } from './root-dir.js';
18
20
 
19
21
  // ---------------------------------------------------------------------------
20
22
  // Trail definition
21
23
  // ---------------------------------------------------------------------------
22
24
 
25
+ const wardenInputSchema = z.object({
26
+ apps: z
27
+ .array(z.string())
28
+ .optional()
29
+ .describe('App names or module paths to govern'),
30
+ cached: z.boolean().default(false).describe('Alias for --lock cached'),
31
+ ci: z.boolean().default(false).describe('Use the CI Warden preset'),
32
+ configPath: z.string().optional().describe('Path to trails.config.ts'),
33
+ depth: z
34
+ .enum(wardenDepthValues)
35
+ .optional()
36
+ .describe('Cumulative analysis depth'),
37
+ drafts: z.enum(wardenDraftsValues).optional().describe('Draft state mode'),
38
+ excludeDrafts: z
39
+ .boolean()
40
+ .default(false)
41
+ .describe('Alias for --drafts exclude'),
42
+ failOn: z.enum(wardenFailOnValues).optional().describe('Failure threshold'),
43
+ format: z.enum(wardenFormatValues).optional().describe('Output format'),
44
+ github: z.boolean().default(false).describe('Alias for --format github'),
45
+ includeDrafts: z
46
+ .boolean()
47
+ .default(false)
48
+ .describe('Alias for --drafts include'),
49
+ json: z.boolean().default(false).describe('Alias for --format json'),
50
+ lock: z.enum(wardenLockValues).optional().describe('Lockfile mode'),
51
+ noLockMutation: z
52
+ .boolean()
53
+ .default(false)
54
+ .describe('Suppress lockfile mutation'),
55
+ onlyDrafts: z.boolean().default(false).describe('Alias for --drafts only'),
56
+ prePush: z.boolean().default(false).describe('Use the pre-push preset'),
57
+ refresh: z.boolean().default(false).describe('Alias for --lock refresh'),
58
+ rootDir: z.string().optional().describe('Root directory to scan'),
59
+ skipLock: z.boolean().default(false).describe('Alias for --lock skip'),
60
+ strict: z.boolean().default(false).describe('Alias for --fail-on warning'),
61
+ summary: z.boolean().default(false).describe('Alias for --format summary'),
62
+ });
63
+
64
+ type WardenTrailInput = z.infer<typeof wardenInputSchema>;
65
+
66
+ const pushFlag = (args: string[], condition: boolean, flag: string): void => {
67
+ if (condition) {
68
+ args.push(flag);
69
+ }
70
+ };
71
+
72
+ const pushValue = (
73
+ args: string[],
74
+ flag: string,
75
+ value: string | undefined
76
+ ): void => {
77
+ if (value !== undefined) {
78
+ args.push(flag, value);
79
+ }
80
+ };
81
+
82
+ const pushApps = (
83
+ args: string[],
84
+ apps: readonly string[] | undefined
85
+ ): void => {
86
+ if (apps !== undefined && apps.length > 0) {
87
+ args.push('--apps', apps.join(','));
88
+ }
89
+ };
90
+
91
+ export const buildWardenCommandArgs = (
92
+ input: WardenTrailInput
93
+ ): readonly string[] => {
94
+ const args: string[] = [];
95
+
96
+ pushFlag(args, input.prePush, '--pre-push');
97
+ pushFlag(args, input.ci, '--ci');
98
+ pushValue(args, '--depth', input.depth);
99
+ if (input.strict) {
100
+ args.push('--strict');
101
+ } else {
102
+ pushValue(args, '--fail-on', input.failOn);
103
+ }
104
+ if (input.github) {
105
+ args.push('--github');
106
+ } else if (input.json) {
107
+ args.push('--json');
108
+ } else if (input.summary) {
109
+ args.push('--summary');
110
+ } else {
111
+ pushValue(args, '--format', input.format);
112
+ }
113
+ if (input.skipLock) {
114
+ args.push('--skip-lock');
115
+ } else if (input.refresh) {
116
+ args.push('--refresh');
117
+ } else if (input.cached) {
118
+ args.push('--cached');
119
+ } else {
120
+ pushValue(args, '--lock', input.lock);
121
+ }
122
+ if (input.onlyDrafts) {
123
+ args.push('--only-drafts');
124
+ } else if (input.excludeDrafts) {
125
+ args.push('--exclude-drafts');
126
+ } else if (input.includeDrafts) {
127
+ args.push('--include-drafts');
128
+ } else {
129
+ pushValue(args, '--drafts', input.drafts);
130
+ }
131
+ pushFlag(args, input.noLockMutation, '--no-lock-mutation');
132
+ pushValue(args, '--config-path', input.configPath);
133
+ pushApps(args, input.apps);
134
+
135
+ return args;
136
+ };
137
+
23
138
  export const wardenTrail = trail('warden', {
24
139
  blaze: async (input, ctx) => {
25
- const rootDir = input.rootDir ?? ctx.cwd ?? process.cwd();
26
- // oxlint-disable-next-line prefer-await-to-then -- catch preserves graceful degradation
27
- const topo = await loadApp(input.module, rootDir).catch(
28
- (error: unknown): undefined => {
29
- ctx.logger?.warn('Could not load app for topo-aware governance', {
30
- error: error instanceof Error ? error.message : String(error),
31
- });
32
- return undefined;
33
- }
34
- );
35
-
36
- const report = await runWarden({
37
- driftOnly: input.driftOnly,
38
- lintOnly: input.lintOnly,
39
- rootDir,
40
- topo,
140
+ const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
141
+ if (rootDirResult.isErr()) {
142
+ return Result.err(rootDirResult.error);
143
+ }
144
+ const rootDir = rootDirResult.value;
145
+ const result = await runWardenCommand({
146
+ args: buildWardenCommandArgs(input),
147
+ cwd: rootDir,
148
+ env: ctx.env ?? {},
41
149
  });
42
-
43
- const formatters: Record<string, (r: typeof report) => string> = {
44
- github: formatGitHubAnnotations,
45
- json: formatJson,
46
- summary: formatSummary,
47
- text: formatWardenReport,
48
- };
49
- const formatter = formatters[input.format] ?? formatWardenReport;
50
- const formatted = formatter(report);
150
+ const { report } = result;
51
151
 
52
152
  return Result.ok({
53
- diagnostics: report.diagnostics,
153
+ diagnostics: [...report.diagnostics],
54
154
  drift: report.drift,
55
155
  errorCount: report.errorCount,
56
- formatted,
156
+ formatted: result.output,
57
157
  passed: report.passed,
58
158
  warnCount: report.warnCount,
59
159
  });
@@ -62,8 +162,7 @@ export const wardenTrail = trail('warden', {
62
162
  examples: [
63
163
  {
64
164
  input: {
65
- driftOnly: false,
66
- lintOnly: false,
165
+ lock: 'skip',
67
166
  },
68
167
  name: 'Default warden run',
69
168
  },
@@ -74,29 +173,11 @@ export const wardenTrail = trail('warden', {
74
173
  name: 'GitHub Actions annotations',
75
174
  },
76
175
  ],
77
- input: z.object({
78
- driftOnly: z.boolean().default(false).describe('Only run drift detection'),
79
- format: z
80
- .enum(['text', 'json', 'github', 'summary'])
81
- .default('text')
82
- .describe('Output format: text, json, github, or summary'),
83
- lintOnly: z.boolean().default(false).describe('Only run lint rules'),
84
- module: z
85
- .string()
86
- .optional()
87
- .describe('App module path (auto-discovered if omitted)'),
88
- rootDir: z.string().optional().describe('Root directory to scan'),
89
- }),
176
+ input: wardenInputSchema,
90
177
  intent: 'read',
91
178
  output: z.object({
92
179
  diagnostics: z.array(
93
- z.object({
94
- filePath: z.string(),
95
- line: z.number(),
96
- message: z.string(),
97
- rule: z.string(),
98
- severity: z.enum(['error', 'warn']),
99
- })
180
+ diagnosticSchema.extend({ topoName: z.string().optional() })
100
181
  ),
101
182
  drift: z
102
183
  .object({
package/src/versions.ts CHANGED
@@ -1,7 +1,6 @@
1
+ import { scaffoldDependencyVersions } from './scaffold-versions.generated.js';
2
+
1
3
  interface PackageJson {
2
- readonly catalog?: Record<string, string>;
3
- readonly dependencies?: Record<string, string>;
4
- readonly devDependencies?: Record<string, string>;
5
4
  readonly version?: string;
6
5
  }
7
6
 
@@ -11,9 +10,6 @@ const readPackageJson = async (url: URL): Promise<PackageJson> =>
11
10
  const appPackageJson = await readPackageJson(
12
11
  new URL('../package.json', import.meta.url)
13
12
  );
14
- const rootPackageJson = await readPackageJson(
15
- new URL('../../../package.json', import.meta.url)
16
- );
17
13
 
18
14
  const requireVersion = (value: string | undefined, label: string): string => {
19
15
  if (typeof value !== 'string' || value.length === 0) {
@@ -22,9 +18,6 @@ const requireVersion = (value: string | undefined, label: string): string => {
22
18
  return value;
23
19
  };
24
20
 
25
- const rootCatalog = rootPackageJson.catalog ?? {};
26
- const rootDevDependencies = rootPackageJson.devDependencies ?? {};
27
-
28
21
  export const trailsPackageVersion = requireVersion(
29
22
  appPackageJson.version,
30
23
  '@ontrails/trails'
@@ -32,12 +25,4 @@ export const trailsPackageVersion = requireVersion(
32
25
 
33
26
  export const ontrailsPackageRange = `^${trailsPackageVersion}`;
34
27
 
35
- export const scaffoldDependencyVersions = {
36
- bunTypes: requireVersion(rootDevDependencies['@types/bun'], '@types/bun'),
37
- commander: requireVersion(rootCatalog['commander'], 'commander'),
38
- lefthook: requireVersion(rootDevDependencies['lefthook'], 'lefthook'),
39
- oxlint: requireVersion(rootDevDependencies['oxlint'], 'oxlint'),
40
- typescript: requireVersion(rootDevDependencies['typescript'], 'typescript'),
41
- ultracite: requireVersion(rootDevDependencies['ultracite'], 'ultracite'),
42
- zod: requireVersion(rootCatalog['zod'], 'zod'),
43
- } as const;
28
+ export { scaffoldDependencyVersions };
@@ -1 +0,0 @@
1
- $ tsc -b
@@ -1,3 +0,0 @@
1
- $ oxlint ./src
2
- Found 0 warnings and 0 errors.
3
- Finished in 57ms on 38 files with 93 rules using 24 threads.
@@ -1 +0,0 @@
1
- $ tsc --noEmit
@@ -1,45 +0,0 @@
1
- /* oxlint-disable eslint-plugin-jest/require-hook -- testExamples registers tests at module scope */
2
- import { afterAll, beforeAll } from 'bun:test';
3
- import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
4
- import { join, resolve } from 'node:path';
5
-
6
- import { testExamples } from '@ontrails/testing';
7
-
8
- import { app } from '../src/app.js';
9
-
10
- const trailsWorkspaceDir = resolve(import.meta.dir, '..', '.trails');
11
- const trailsGitignorePath = join(trailsWorkspaceDir, '.gitignore');
12
- const trailsWorkspaceSubdirs = ['config', 'dev', 'generated'] as const;
13
- const trailsGitignore = `# Local config overrides
14
- config/
15
-
16
- # Development state
17
- dev/
18
-
19
- # Generated artifacts
20
- generated/
21
-
22
- # Shared Trails database
23
- trails.db
24
- trails.db-shm
25
- trails.db-wal
26
- `;
27
-
28
- const resetTrailsWorkspace = (): void => {
29
- rmSync(trailsWorkspaceDir, { force: true, recursive: true });
30
- mkdirSync(trailsWorkspaceDir, { recursive: true });
31
- for (const subdir of trailsWorkspaceSubdirs) {
32
- mkdirSync(join(trailsWorkspaceDir, subdir), { recursive: true });
33
- }
34
- writeFileSync(trailsGitignorePath, trailsGitignore);
35
- };
36
-
37
- beforeAll(() => {
38
- resetTrailsWorkspace();
39
- });
40
-
41
- afterAll(() => {
42
- resetTrailsWorkspace();
43
- });
44
-
45
- testExamples(app);
@@ -1,3 +0,0 @@
1
- #!/usr/bin/env bun
2
- import '../src/cli.js';
3
- //# sourceMappingURL=trails.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"trails.d.ts","sourceRoot":"","sources":["../../bin/trails.ts"],"names":[],"mappings":";AAEA,OAAO,eAAe,CAAC"}
@@ -1,4 +0,0 @@
1
- #!/usr/bin/env bun
2
- /* oxlint-disable eslint-plugin-jest/require-hook -- CLI bin entrypoints execute at module scope */
3
- import '../src/cli.js';
4
- //# sourceMappingURL=trails.js.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"trails.js","sourceRoot":"","sources":["../../bin/trails.ts"],"names":[],"mappings":";AACA,mGAAmG;AACnG,OAAO,eAAe,CAAC"}
package/dist/src/app.d.ts DELETED
@@ -1,2 +0,0 @@
1
- export declare const app: import("@ontrails/core").Topo;
2
- //# sourceMappingURL=app.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../src/app.ts"],"names":[],"mappings":"AAsBA,eAAO,MAAM,GAAG,+BAqBf,CAAC"}
package/dist/src/app.js DELETED
@@ -1,22 +0,0 @@
1
- import { topo } from '@ontrails/core';
2
- import * as addSurface from './trails/add-surface.js';
3
- import * as addTrail from './trails/add-trail.js';
4
- import * as addVerify from './trails/add-verify.js';
5
- import * as create from './trails/create.js';
6
- import * as createScaffold from './trails/create-scaffold.js';
7
- import * as devClean from './trails/dev-clean.js';
8
- import * as devReset from './trails/dev-reset.js';
9
- import * as devStats from './trails/dev-stats.js';
10
- import * as draftPromote from './trails/draft-promote.js';
11
- import * as guide from './trails/guide.js';
12
- import * as survey from './trails/survey.js';
13
- import * as topoExport from './trails/topo-export.js';
14
- import * as topoHistory from './trails/topo-history.js';
15
- import * as topoPin from './trails/topo-pin.js';
16
- import * as topoShow from './trails/topo-show.js';
17
- import * as topoCommand from './trails/topo.js';
18
- import * as topoUnpin from './trails/topo-unpin.js';
19
- import * as topoVerify from './trails/topo-verify.js';
20
- import * as warden from './trails/warden.js';
21
- export const app = topo('trails', survey, topoCommand, topoShow, topoHistory, topoPin, topoUnpin, topoExport, topoVerify, devStats, devClean, devReset, guide, draftPromote, warden, create, createScaffold, addSurface, addVerify, addTrail);
22
- //# sourceMappingURL=app.js.map
@@ -1 +0,0 @@
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,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"}