@venizia/vulcan 0.4.0 → 0.4.2

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 (141) hide show
  1. package/base/claude/remote-hosts.json +1 -1
  2. package/base/claude/settings.json +75 -3
  3. package/base/hooks/guard-git.ts +55 -0
  4. package/base/hooks/guard-manifest.ts +1 -1
  5. package/base/hooks/guard-outside.ts +66 -0
  6. package/base/hooks/guard-package.ts +3 -2
  7. package/base/hooks/guard-remote-hosts.ts +3 -2
  8. package/base/hooks/guard-writes.ts +1 -1
  9. package/base/hooks/post-tool.ts +36 -0
  10. package/base/hooks/prompt-submit.ts +52 -0
  11. package/base/hooks/stop.ts +38 -0
  12. package/base/hooks/subagent-start.ts +18 -0
  13. package/base/references/delegation-brief.md +63 -0
  14. package/base/references/design-pass.md +39 -0
  15. package/base/references/evidence.md +36 -0
  16. package/base/references/phase-boundaries.md +20 -0
  17. package/base/references/testing.md +89 -0
  18. package/base/rules.md +11 -2
  19. package/base/skills/build-a-feature/SKILL.md +49 -23
  20. package/base/skills/docs-update/SKILL.md +12 -1
  21. package/base/skills/docs-writing/SKILL.md +2 -2
  22. package/base/skills/docs-writing/references/agent-documents.md +53 -0
  23. package/base/skills/fix-a-bug/SKILL.md +84 -0
  24. package/base/skills/fix-a-bug/evals/evals.json +17 -0
  25. package/base/skills/knowledge-sync/SKILL.md +4 -1
  26. package/base/skills/knowledge-sync/knowledge-sync.workflow.js +10 -10
  27. package/base/skills/plan-a-change/SKILL.md +95 -0
  28. package/base/skills/plan-a-change/evals/evals.json +23 -0
  29. package/base/skills/plan-a-change/references/spec-card.md +39 -0
  30. package/base/skills/report-back/SKILL.md +112 -0
  31. package/base/skills/report-back/evals/evals.json +23 -0
  32. package/base/skills/research/SKILL.md +64 -0
  33. package/base/skills/research/evals/evals.json +17 -0
  34. package/base/skills/retro/SKILL.md +69 -0
  35. package/base/skills/retro/evals/evals.json +17 -0
  36. package/base/skills/review-a-change/SKILL.md +90 -0
  37. package/base/skills/review-a-change/evals/evals.json +17 -0
  38. package/base/skills/ship/SKILL.md +82 -0
  39. package/base/skills/ship/evals/evals.json +23 -0
  40. package/base/skills/visualize-work/SKILL.md +87 -0
  41. package/base/skills/visualize-work/evals/evals.json +17 -0
  42. package/base/skills/visualize-work/references/spec.md +65 -0
  43. package/package.json +3 -3
  44. package/src/agents/common/schema.ts +2 -2
  45. package/src/agents/detect.ts +5 -5
  46. package/src/agents/exclude.ts +3 -3
  47. package/src/agents/local.ts +1 -1
  48. package/src/agents/prompt.ts +2 -2
  49. package/src/agents/render.ts +2 -2
  50. package/src/agents/resolve.ts +6 -6
  51. package/src/agents/table.ts +1 -1
  52. package/src/commands/agents.command.ts +4 -4
  53. package/src/commands/clean.command.ts +72 -0
  54. package/src/commands/help.command.ts +11 -0
  55. package/src/commands/index.ts +6 -0
  56. package/src/commands/init.command.ts +4 -1
  57. package/src/commands/profile.command.ts +255 -0
  58. package/src/commands/sync.command.ts +6 -4
  59. package/src/commands/upgrade.command.ts +1 -1
  60. package/src/commands/visualize.command.ts +107 -0
  61. package/src/common/constants.ts +23 -0
  62. package/src/config/common/constants.ts +2 -0
  63. package/src/config/loader.ts +4 -4
  64. package/src/config/packages.ts +1 -1
  65. package/src/config/schema.ts +16 -5
  66. package/src/create/add-app.ts +15 -15
  67. package/src/create/add-lib.ts +7 -7
  68. package/src/create/bunfig.ts +1 -1
  69. package/src/create/dockerignore.ts +4 -4
  70. package/src/create/init-monorepo.ts +3 -1
  71. package/src/create/lib-preset.ts +1 -1
  72. package/src/create/names.ts +7 -6
  73. package/src/create/next.ts +4 -4
  74. package/src/create/preset-menu.ts +4 -4
  75. package/src/create/preset.ts +3 -3
  76. package/src/create/scratch.ts +27 -6
  77. package/src/create/workspace.ts +11 -11
  78. package/src/doctor/checks.ts +231 -45
  79. package/src/doctor/common/constants.ts +4 -0
  80. package/src/doctor/makefile.ts +3 -3
  81. package/src/doctor/runner.ts +16 -1
  82. package/src/doctor/skills.ts +8 -8
  83. package/src/doctor/tags.ts +5 -5
  84. package/src/hooks/common/constants.ts +29 -0
  85. package/src/hooks/common/types.ts +20 -0
  86. package/src/hooks/decision.ts +15 -0
  87. package/src/hooks/guard-git.ts +288 -0
  88. package/src/hooks/guard-manifest.ts +1 -1
  89. package/src/hooks/guard-outside.ts +399 -0
  90. package/src/hooks/guard-package.ts +4 -4
  91. package/src/hooks/guard-writes.ts +5 -5
  92. package/src/hooks/index.ts +6 -0
  93. package/src/hooks/owner-reply.ts +148 -0
  94. package/src/hooks/post-tool.ts +137 -0
  95. package/src/hooks/remote-hosts.ts +25 -23
  96. package/src/hooks/session-digest.ts +24 -4
  97. package/src/hooks/shell.ts +325 -0
  98. package/src/hooks/subagent-card.ts +32 -0
  99. package/src/init/scaffold.ts +6 -6
  100. package/src/local/clean.ts +88 -0
  101. package/src/local/constants.ts +50 -0
  102. package/src/local/format.ts +25 -0
  103. package/src/local/index.ts +4 -0
  104. package/src/local/scan.ts +368 -0
  105. package/src/manifest/render.ts +1 -1
  106. package/src/owner/card.ts +85 -0
  107. package/src/owner/constants.ts +105 -0
  108. package/src/owner/index.ts +8 -0
  109. package/src/owner/profile.ts +123 -0
  110. package/src/owner/schema.ts +147 -0
  111. package/src/owner/shape.ts +388 -0
  112. package/src/owner/survey.ts +289 -0
  113. package/src/owner/view.ts +76 -0
  114. package/src/owner/violations.ts +202 -0
  115. package/src/router.ts +18 -1
  116. package/src/rules/base.ts +1 -1
  117. package/src/rules/parser.ts +5 -5
  118. package/src/signals/claims.ts +71 -0
  119. package/src/signals/classify.ts +132 -0
  120. package/src/signals/constants.ts +88 -0
  121. package/src/signals/index.ts +5 -0
  122. package/src/signals/loop.ts +46 -0
  123. package/src/signals/state.ts +276 -0
  124. package/src/sync/agent-files.ts +4 -4
  125. package/src/sync/agent-removal.ts +6 -6
  126. package/src/sync/atlas-block.ts +1 -1
  127. package/src/sync/base-rules.ts +1 -1
  128. package/src/sync/exclude.ts +9 -9
  129. package/src/sync/local-choice.ts +35 -5
  130. package/src/sync/planner.ts +16 -16
  131. package/src/sync/prune.ts +3 -3
  132. package/src/sync/settings.ts +15 -15
  133. package/src/ui/prompt.ts +3 -3
  134. package/src/visualize/assets.ts +80 -0
  135. package/src/visualize/constants.ts +126 -0
  136. package/src/visualize/index.ts +6 -0
  137. package/src/visualize/layout.ts +107 -0
  138. package/src/visualize/page.ts +211 -0
  139. package/src/visualize/render.ts +161 -0
  140. package/src/visualize/schema.ts +178 -0
  141. package/src/visualize/validate.ts +127 -0
@@ -60,7 +60,7 @@ export const diffBaseRules = (opts: { root: string }): IBaseRuleChange[] => {
60
60
  });
61
61
  }
62
62
 
63
- for (const id of Object.keys(synced).filter(syncedId => installed[syncedId] === undefined)) {
63
+ for (const id of Object.keys(synced).filter((syncedId) => installed[syncedId] === undefined)) {
64
64
  changes.push({
65
65
  id,
66
66
  change: BaseRuleChanges.REMOVED,
@@ -27,11 +27,11 @@ export const shippedSkillNames = (): string[] => {
27
27
  return existsSync(directory)
28
28
  ? readdirSync(directory, { withFileTypes: true })
29
29
  .filter(
30
- entry =>
30
+ (entry) =>
31
31
  entry.isDirectory() &&
32
32
  existsSync(join(directory, entry.name, SyncConstants.SKILL_FILE)),
33
33
  )
34
- .map(entry => entry.name)
34
+ .map((entry) => entry.name)
35
35
  .sort()
36
36
  : [];
37
37
  };
@@ -52,23 +52,23 @@ export const planExclude = (opts: { root: string; agents: string[] }): ISyncActi
52
52
  const path = resolve(opts.root, location);
53
53
  const prefix = git({ root: opts.root, args: ['rev-parse', '--show-prefix'] }) ?? '';
54
54
  const anchored = excludePathsOf({ agents: opts.agents, skillNames: shippedSkillNames() }).map(
55
- group => ({ ...group, paths: group.paths.map(item => `/${prefix}${item.slice(1)}`) }),
55
+ (group) => ({ ...group, paths: group.paths.map((item) => `/${prefix}${item.slice(1)}`) }),
56
56
  );
57
- const candidates = anchored.flatMap(group => group.paths).filter(item => !item.endsWith('/'));
57
+ const candidates = anchored.flatMap((group) => group.paths).filter((item) => !item.endsWith('/'));
58
58
  const tracked = new Set(
59
59
  (
60
60
  git({
61
61
  root: opts.root,
62
- args: ['ls-files', '--', ...candidates.map(item => item.slice(`/${prefix}`.length))],
62
+ args: ['ls-files', '--', ...candidates.map((item) => item.slice(`/${prefix}`.length))],
63
63
  }) ?? ''
64
64
  )
65
65
  .split('\n')
66
- .filter(line => line !== '')
67
- .map(line => `/${prefix}${line}`),
66
+ .filter((line) => line !== '')
67
+ .map((line) => `/${prefix}${line}`),
68
68
  );
69
69
  const groups = anchored
70
- .map(group => ({ ...group, paths: group.paths.filter(item => !tracked.has(item)) }))
71
- .filter(group => group.paths.length > 0);
70
+ .map((group) => ({ ...group, paths: group.paths.filter((item) => !tracked.has(item)) }))
71
+ .filter((group) => group.paths.length > 0);
72
72
  const before = existsSync(path) ? readFileSync(path, 'utf8') : undefined;
73
73
  const merged = mergeExcludeBlock({ text: before, block: renderExcludeBlock({ groups }) });
74
74
 
@@ -1,6 +1,7 @@
1
1
  import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
2
2
  import { dirname, join } from 'node:path';
3
3
  import { LOCAL_AGENTS_FILE, renderLocalChoice } from '../agents/index.ts';
4
+ import { ProjectLayout } from '../common/index.ts';
4
5
  import { SyncStatuses } from './common/index.ts';
5
6
  import type { ISyncAction } from './common/index.ts';
6
7
 
@@ -26,8 +27,8 @@ export const planLocalChoice = (opts: { root: string; agents: string[] }): ISync
26
27
  };
27
28
  };
28
29
 
29
- /** The one line sync adds to a committed `.gitignore`; a project without one is left alone. */
30
- export const planLocalIgnore = (opts: { root: string }): ISyncAction[] => {
30
+ /** One line sync adds to a committed `.gitignore`; a project without one is left alone. */
31
+ const planIgnoreLine = (opts: { root: string; line: string }): ISyncAction[] => {
31
32
  const path = join(opts.root, '.gitignore');
32
33
 
33
34
  if (!existsSync(path)) {
@@ -36,7 +37,7 @@ export const planLocalIgnore = (opts: { root: string }): ISyncAction[] => {
36
37
 
37
38
  const text = readFileSync(path, 'utf8');
38
39
 
39
- if (text.split('\n').some(line => line.trim() === LOCAL_AGENTS_FILE)) {
40
+ if (text.split('\n').some((line) => line.trim() === opts.line)) {
40
41
  return [];
41
42
  }
42
43
 
@@ -44,12 +45,41 @@ export const planLocalIgnore = (opts: { root: string }): ISyncAction[] => {
44
45
  {
45
46
  path,
46
47
  status: SyncStatuses.REPLACED,
47
- note: `added ${LOCAL_AGENTS_FILE}`,
48
+ note: `added ${opts.line}`,
48
49
  apply: () =>
49
50
  writeFileSync(
50
51
  path,
51
- `${text}${text === '' || text.endsWith('\n') ? '' : '\n'}${LOCAL_AGENTS_FILE}\n`,
52
+ `${text}${text === '' || text.endsWith('\n') ? '' : '\n'}${opts.line}\n`,
52
53
  ),
53
54
  },
54
55
  ];
55
56
  };
57
+
58
+ /** The one line sync adds to a committed `.gitignore`; a project without one is left alone. */
59
+ export const planLocalIgnore = (opts: { root: string }): ISyncAction[] =>
60
+ planIgnoreLine({ root: opts.root, line: LOCAL_AGENTS_FILE });
61
+
62
+ /**
63
+ * The project's local workspace: `.agents/local/` is gitignored and holds what an agent creates while
64
+ * it works (scratch, worktrees, clones, cache, prototypes), so nothing lands outside the project.
65
+ */
66
+ export const planLocalWorkspace = (opts: { root: string }): ISyncAction[] => {
67
+ const directory = join(opts.root, ProjectLayout.LOCAL_DIRECTORY);
68
+ const missing = ProjectLayout.LOCAL_LAYOUT.map((entry) => entry.name).filter(
69
+ (name) => !existsSync(join(directory, name)),
70
+ );
71
+
72
+ return [
73
+ ...planIgnoreLine({ root: opts.root, line: `${ProjectLayout.LOCAL_DIRECTORY}/` }),
74
+ {
75
+ path: directory,
76
+ status: missing.length === 0 ? SyncStatuses.UNCHANGED : SyncStatuses.CREATED,
77
+ ...(missing.length === 0 ? {} : { note: `created ${missing.join(', ')}` }),
78
+ apply: () => {
79
+ for (const name of missing) {
80
+ mkdirSync(join(directory, name), { recursive: true });
81
+ }
82
+ },
83
+ },
84
+ ];
85
+ };
@@ -171,11 +171,11 @@ const findSkillDirectories = (opts: { directory: string }): string[] =>
171
171
  existsSync(opts.directory)
172
172
  ? readdirSync(opts.directory, { withFileTypes: true })
173
173
  .filter(
174
- entry =>
174
+ (entry) =>
175
175
  entry.isDirectory() &&
176
176
  existsSync(join(opts.directory, entry.name, SyncConstants.SKILL_FILE)),
177
177
  )
178
- .map(entry => join(opts.directory, entry.name))
178
+ .map((entry) => join(opts.directory, entry.name))
179
179
  // readdir order is the filesystem's: the plan lists skills by name, the same on every machine.
180
180
  .sort()
181
181
  : [];
@@ -208,8 +208,8 @@ const planSkillLinks = (opts: {
208
208
  const stableSkills = join(stableBaseDirectoryOf(opts), SyncConstants.SKILLS_DIRECTORY);
209
209
  const shipped = findSkillDirectories({
210
210
  directory: join(BASE_DIRECTORY, SyncConstants.SKILLS_DIRECTORY),
211
- }).map(source => join(stableSkills, basename(source)));
212
- const shippedNames = new Set(shipped.map(source => basename(source)));
211
+ }).map((source) => join(stableSkills, basename(source)));
212
+ const shippedNames = new Set(shipped.map((source) => basename(source)));
213
213
  const project = opts.withProject
214
214
  ? findSkillDirectories({
215
215
  directory: join(opts.root, '.agents', SyncConstants.SKILLS_DIRECTORY),
@@ -218,14 +218,14 @@ const planSkillLinks = (opts: {
218
218
 
219
219
  // Extend only: a project skill never takes a shipped skill's link; doctor reports the clash.
220
220
  const shadowing: ISyncAction[] = project
221
- .filter(source => shippedNames.has(basename(source)))
222
- .map(source => ({
221
+ .filter((source) => shippedNames.has(basename(source)))
222
+ .map((source) => ({
223
223
  path: source,
224
224
  status: SyncStatuses.SKIPPED,
225
225
  note: "shadows a shipped skill - rename it ('vulcan doctor' reports it)",
226
226
  apply: NO_CHANGE,
227
227
  }));
228
- const sources = [...shipped, ...project.filter(source => !shippedNames.has(basename(source)))];
228
+ const sources = [...shipped, ...project.filter((source) => !shippedNames.has(basename(source)))];
229
229
 
230
230
  const links = sources.map((source): ISyncAction => {
231
231
  const path = join(target, basename(source));
@@ -262,15 +262,15 @@ const planSkillLinks = (opts: {
262
262
  const shippedRoots = [stableSkills, join(BASE_DIRECTORY, SyncConstants.SKILLS_DIRECTORY)];
263
263
  // A link into the project's own skills whose folder the user removed is dead the same way.
264
264
  const projectRoot = join(opts.root, '.agents', SyncConstants.SKILLS_DIRECTORY);
265
- const linked = new Set(sources.map(source => basename(source)));
265
+ const linked = new Set(sources.map((source) => basename(source)));
266
266
  const stale = (existsSync(target) ? readdirSync(target) : [])
267
- .filter(name => !linked.has(name))
268
- .map(name => join(target, name))
269
- .filter(path => isSymlink({ path }) && !existsSync(path))
270
- .map(path => ({ path, destination: readlinkSync(path) }))
267
+ .filter((name) => !linked.has(name))
268
+ .map((name) => join(target, name))
269
+ .filter((path) => isSymlink({ path }) && !existsSync(path))
270
+ .map((path) => ({ path, destination: readlinkSync(path) }))
271
271
  .filter(
272
272
  ({ destination }) =>
273
- shippedRoots.some(root => destination.startsWith(`${root}/`)) ||
273
+ shippedRoots.some((root) => destination.startsWith(`${root}/`)) ||
274
274
  (opts.withProject && destination.startsWith(`${projectRoot}/`)),
275
275
  )
276
276
  .map(({ path, destination }): ISyncAction => ({
@@ -309,8 +309,8 @@ const CLAUDE_SKILLS = join(SyncConstants.CLAUDE_DIRECTORY, SyncConstants.SKILLS_
309
309
  const skillDirectoriesOf = (opts: { agents: string[] }): string[] => [
310
310
  ...new Set(
311
311
  readAgentTable()
312
- .filter(entry => opts.agents.includes(entry.id))
313
- .map(entry => entry.skills.dir),
312
+ .filter((entry) => opts.agents.includes(entry.id))
313
+ .map((entry) => entry.skills.dir),
314
314
  ),
315
315
  ];
316
316
 
@@ -324,7 +324,7 @@ export const planSync = (opts: {
324
324
  ...(opts.agents.includes(CodingAgents.CLAUDE)
325
325
  ? [planClaudeImport({ root: opts.root }), planSettings(opts)]
326
326
  : []),
327
- ...skillDirectoriesOf({ agents: opts.agents }).flatMap(directory =>
327
+ ...skillDirectoriesOf({ agents: opts.agents }).flatMap((directory) =>
328
328
  planSkillLinks({ root: opts.root, directory, withProject: directory === CLAUDE_SKILLS }),
329
329
  ),
330
330
  ...planAgentFiles({ root: opts.root, agents: opts.agents }),
package/src/sync/prune.ts CHANGED
@@ -111,14 +111,14 @@ export const planPrune = (opts: { root: string }): ISyncAction[] => {
111
111
  const staleCommands = [
112
112
  ...new Set(extractHookCommands({ settings: readJson({ path: settingsPath }) })),
113
113
  ].filter(
114
- command => !managed.has(command) && isStaleCommand({ root: opts.root, command, shipped }),
114
+ (command) => !managed.has(command) && isStaleCommand({ root: opts.root, command, shipped }),
115
115
  );
116
116
  const skills = join(directory, SyncConstants.SKILLS_DIRECTORY);
117
117
  // lstat, not stat: a symlinked skills directory leads out of the project and is never walked.
118
118
  const deadLinks = lstatSync(skills, { throwIfNoEntry: false })?.isDirectory()
119
119
  ? readdirSync(skills)
120
- .map(name => join(skills, name))
121
- .filter(path => isDeadLink({ path }))
120
+ .map((name) => join(skills, name))
121
+ .filter((path) => isDeadLink({ path }))
122
122
  : [];
123
123
 
124
124
  return [
@@ -7,9 +7,9 @@ export const isSettingsObject = (opts: { value: unknown }): opts is { value: TSe
7
7
 
8
8
  /** Arrays concatenate without duplicates, so a second sync adds nothing. */
9
9
  const mergeArrays = (opts: { base: unknown[]; overlay: unknown[] }): unknown[] => {
10
- const seen = new Set(opts.base.map(entry => JSON.stringify(entry)));
10
+ const seen = new Set(opts.base.map((entry) => JSON.stringify(entry)));
11
11
 
12
- return [...opts.base, ...opts.overlay.filter(entry => !seen.has(JSON.stringify(entry)))];
12
+ return [...opts.base, ...opts.overlay.filter((entry) => !seen.has(JSON.stringify(entry)))];
13
13
  };
14
14
 
15
15
  /** `overlay` wins key by key; one level deep into the object-of-entries keys (SyncConstants.MERGE_ONE_LEVEL). */
@@ -80,8 +80,8 @@ const toHookEntry = (opts: {
80
80
  /** Every hook command in one event's entries; anything that is not an entry or a command is skipped. */
81
81
  export const extractEntryCommands = (opts: { entries: unknown }): string[] =>
82
82
  Array.isArray(opts.entries)
83
- ? opts.entries.flatMap(entry =>
84
- (toHookEntry({ entry })?.hooks ?? []).flatMap(hook => toHookCommand({ hook }) ?? []),
83
+ ? opts.entries.flatMap((entry) =>
84
+ (toHookEntry({ entry })?.hooks ?? []).flatMap((hook) => toHookCommand({ hook }) ?? []),
85
85
  )
86
86
  : [];
87
87
 
@@ -90,7 +90,7 @@ export const extractHookCommands = (opts: { settings: TSettings | undefined }):
90
90
  const hooks = { value: opts.settings?.[SyncConstants.HOOKS_KEY] };
91
91
 
92
92
  return isSettingsObject(hooks)
93
- ? Object.values(hooks.value).flatMap(entries => extractEntryCommands({ entries }))
93
+ ? Object.values(hooks.value).flatMap((entries) => extractEntryCommands({ entries }))
94
94
  : [];
95
95
  };
96
96
 
@@ -102,14 +102,14 @@ export const removeHookCommands = (opts: {
102
102
  entries: unknown[];
103
103
  commands: Set<string>;
104
104
  }): unknown[] =>
105
- opts.entries.flatMap(entry => {
105
+ opts.entries.flatMap((entry) => {
106
106
  const hookEntry = toHookEntry({ entry });
107
107
 
108
108
  if (hookEntry === undefined) {
109
109
  return [entry];
110
110
  }
111
111
 
112
- const kept = hookEntry.hooks.filter(hook => {
112
+ const kept = hookEntry.hooks.filter((hook) => {
113
113
  const command = toHookCommand({ hook });
114
114
 
115
115
  return command === undefined || !opts.commands.has(command);
@@ -125,11 +125,11 @@ export const removeHookCommands = (opts: {
125
125
  /** `settings` with its keys in `reference`'s order: keys `reference` has keep their place, new keys follow. */
126
126
  const orderKeysLike = (opts: { settings: TSettings; reference: TSettings }): TSettings => {
127
127
  const keys = [
128
- ...Object.keys(opts.reference).filter(key => key in opts.settings),
129
- ...Object.keys(opts.settings).filter(key => !(key in opts.reference)),
128
+ ...Object.keys(opts.reference).filter((key) => key in opts.settings),
129
+ ...Object.keys(opts.settings).filter((key) => !(key in opts.reference)),
130
130
  ];
131
131
 
132
- return Object.fromEntries(keys.map(key => [key, opts.settings[key]]));
132
+ return Object.fromEntries(keys.map((key) => [key, opts.settings[key]]));
133
133
  };
134
134
 
135
135
  /**
@@ -139,7 +139,7 @@ const orderKeysLike = (opts: { settings: TSettings; reference: TSettings }): TSe
139
139
  export const keepKeyOrder = (opts: { settings: TSettings; reference: TSettings }): TSettings => {
140
140
  const ordered = orderKeysLike(opts);
141
141
 
142
- for (const key of Object.keys(ordered).filter(entry =>
142
+ for (const key of Object.keys(ordered).filter((entry) =>
143
143
  SyncConstants.MERGE_ONE_LEVEL.has(entry),
144
144
  )) {
145
145
  const value = { value: ordered[key] };
@@ -169,8 +169,8 @@ export const removeManagedSettings = (opts: {
169
169
  Array.isArray(current.value) &&
170
170
  Array.isArray(managedValue)
171
171
  ) {
172
- const managedEntries = new Set(managedValue.map(entry => toKey({ value: entry })));
173
- const kept = current.value.filter(entry => !managedEntries.has(toKey({ value: entry })));
172
+ const managedEntries = new Set(managedValue.map((entry) => toKey({ value: entry })));
173
+ const kept = current.value.filter((entry) => !managedEntries.has(toKey({ value: entry })));
174
174
 
175
175
  if (kept.length > 0) {
176
176
  remaining[key] = kept;
@@ -199,8 +199,8 @@ export const removeManagedSettings = (opts: {
199
199
  const innerCurrent = inner[innerKey];
200
200
 
201
201
  if (Array.isArray(innerCurrent) && Array.isArray(innerManaged)) {
202
- const managedKeys = new Set(innerManaged.map(entry => toKey({ value: entry })));
203
- const unmatched = innerCurrent.filter(entry => !managedKeys.has(toKey({ value: entry })));
202
+ const managedKeys = new Set(innerManaged.map((entry) => toKey({ value: entry })));
203
+ const unmatched = innerCurrent.filter((entry) => !managedKeys.has(toKey({ value: entry })));
204
204
  // A hand-edited entry no longer matches whole: its managed hooks still go, by command.
205
205
  const kept =
206
206
  key === SyncConstants.HOOKS_KEY
package/src/ui/prompt.ts CHANGED
@@ -25,7 +25,7 @@ export const promptText = async (opts: {
25
25
  ...(opts.defaultValue === undefined
26
26
  ? {}
27
27
  : { placeholder: opts.defaultValue, defaultValue: opts.defaultValue }),
28
- validate: input => opts.validate?.(input ?? ''),
28
+ validate: (input) => opts.validate?.(input ?? ''),
29
29
  }),
30
30
  );
31
31
 
@@ -41,7 +41,7 @@ export const promptSelect = async (opts: {
41
41
  const value = await guardAgainstPipedLines(() =>
42
42
  select({
43
43
  message: opts.message,
44
- options: opts.choices.map(choice => ({
44
+ options: opts.choices.map((choice) => ({
45
45
  value: choice.value,
46
46
  label: choice.label,
47
47
  ...(choice.hint === undefined ? {} : { hint: choice.hint }),
@@ -62,7 +62,7 @@ export const promptMultiselect = async (opts: {
62
62
  const value = await guardAgainstPipedLines(() =>
63
63
  multiselect({
64
64
  message: opts.message,
65
- options: opts.choices.map(choice => ({
65
+ options: opts.choices.map((choice) => ({
66
66
  value: choice.value,
67
67
  label: choice.label,
68
68
  ...(choice.hint === undefined ? {} : { hint: choice.hint }),
@@ -0,0 +1,80 @@
1
+ /** The page's stylesheet: light and dark by variables, no font, no image, final state in print and under reduced motion. */
2
+ export const PAGE_CSS = `:root{--bg:#fbfbfa;--fg:#1c1d1f;--mut:#5b6068;--line:#c9ccd2;--card:#fff;--acc:#0b5cd5;--ok:#17703a;--warn:#8a5a00;--bad:#b3261e;--info:#0b5cd5;--add:#17703a;--rem:#b3261e;color-scheme:light}
3
+ @media (prefers-color-scheme:dark){:root:not([data-theme=light]){--bg:#15171a;--fg:#e8e9eb;--mut:#a3a8b0;--line:#3a3f47;--card:#1e2126;--acc:#6ea8ff;--ok:#5fd18a;--warn:#f0b955;--bad:#ff8a80;--info:#6ea8ff;--add:#5fd18a;--rem:#ff8a80;color-scheme:dark}}
4
+ :root[data-theme=dark]{--bg:#15171a;--fg:#e8e9eb;--mut:#a3a8b0;--line:#3a3f47;--card:#1e2126;--acc:#6ea8ff;--ok:#5fd18a;--warn:#f0b955;--bad:#ff8a80;--info:#6ea8ff;--add:#5fd18a;--rem:#ff8a80;color-scheme:dark}
5
+ *{box-sizing:border-box}
6
+ body{margin:0;background:var(--bg);color:var(--fg);font:16px/1.5 system-ui,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif}
7
+ main{max-width:1100px;margin:0 auto;padding:20px 16px 64px}
8
+ header{display:flex;flex-wrap:wrap;gap:8px 16px;align-items:center;justify-content:space-between}
9
+ h1{font-size:1.6rem;line-height:1.25;margin:0;flex:1 1 320px}
10
+ h2{font-size:1.15rem;margin:32px 0 8px}
11
+ .meta{color:var(--mut);font-size:.9rem;display:flex;flex-wrap:wrap;gap:4px 16px;margin:4px 0 0}
12
+ .chip{display:inline-flex;align-items:center;gap:8px;border:2px solid currentColor;border-radius:999px;padding:2px 12px;font-weight:600;font-size:.9rem}
13
+ .chip i{display:inline-block;width:12px;height:12px;background:currentColor}
14
+ .ok{color:var(--ok)}.ok i{border-radius:50%}
15
+ .warn{color:var(--warn)}.warn i{clip-path:polygon(50% 0,100% 100%,0 100%)}
16
+ .blocked{color:var(--bad)}.blocked i{border-radius:2px}
17
+ .info{color:var(--info)}.info i{transform:rotate(45deg) scale(.8)}
18
+ button{font:inherit;color:var(--fg);background:var(--card);border:1px solid var(--line);border-radius:6px;padding:4px 12px;cursor:pointer}
19
+ button:focus-visible,.node:focus-visible{outline:3px solid var(--acc);outline-offset:2px}
20
+ .verdict{font-size:1.25rem;font-weight:600;margin:16px 0 4px}
21
+ .cap{color:var(--mut);margin:0 0 12px}
22
+ .strip{display:grid;grid-template-columns:repeat(auto-fit,minmax(220px,1fr));gap:8px;margin:16px 0}
23
+ .strip div{background:var(--card);border:1px solid var(--line);border-radius:8px;padding:8px 12px}
24
+ .strip b{display:block;font-size:.8rem;text-transform:uppercase;letter-spacing:.04em;color:var(--mut)}
25
+ .bar{display:flex;flex-wrap:wrap;gap:8px;align-items:center;margin:8px 0}
26
+ .fig{overflow-x:auto;background:var(--card);border:1px solid var(--line);border-radius:8px;padding:8px}
27
+ svg{display:block;max-width:none;color:var(--mut)}
28
+ .node rect{fill:var(--bg);stroke:var(--fg);stroke-width:1.5}
29
+ .node .t{font-size:14px;font-weight:600;fill:var(--fg)}.node .s{font-size:12px;fill:var(--mut)}
30
+ .node.service rect{stroke-width:3}.node.store rect{stroke-dasharray:2 3;stroke-width:2.5}.node.actor rect{rx:32}.node.external rect{stroke-dasharray:8 4}
31
+ .edge path{fill:none;stroke:currentColor;stroke-width:1.8}.edge text{font-size:12px;fill:var(--fg);paint-order:stroke;stroke:var(--card);stroke-width:4px}
32
+ .edge.branch path,.edge.return path{stroke-dasharray:7 5}.edge.fanout path{stroke-width:2.6}.edge.error{color:var(--bad)}.edge.error path{stroke:var(--bad)}marker .bad{fill:var(--bad)}.edge.error path{stroke-dasharray:2 4}
33
+ .flow .edge path{stroke-dasharray:6 6;animation:dash 1s linear infinite}
34
+ @keyframes dash{to{stroke-dashoffset:-12}}
35
+ .focus .node:not(.on),.focus .edge:not(.on){opacity:.22}
36
+ #detail,#stepnote{min-height:1.5em;margin:8px 0 0}
37
+ #stepnote{font-weight:600}
38
+ .legend{display:flex;flex-wrap:wrap;gap:4px 16px;color:var(--mut);font-size:.85rem;margin:8px 0 0}
39
+ .steps{margin:12px 0 0;padding-left:24px}
40
+ .ba{display:grid;grid-template-columns:repeat(auto-fit,minmax(260px,1fr));gap:12px}
41
+ .ba section{background:var(--card);border:1px solid var(--line);border-radius:8px;padding:8px 16px}
42
+ .ba h3{margin:4px 0}.ba ul{margin:0;padding-left:20px}
43
+ .added{color:var(--add);font-weight:600}.removed{color:var(--rem);text-decoration:line-through dashed}
44
+ .tw{overflow-x:auto}
45
+ table{border-collapse:collapse;width:100%;min-width:560px}
46
+ th,td{text-align:left;vertical-align:top;border-bottom:1px solid var(--line);padding:6px 10px}
47
+ th{font-size:.8rem;text-transform:uppercase;letter-spacing:.04em;color:var(--mut)}
48
+ .tag{font-weight:600;white-space:nowrap}
49
+ ol.d{padding-left:24px}ol.d li{margin:8px 0}
50
+ a{color:var(--acc)}
51
+ .present{font-size:1.2em}.present .bar,.present #theme{display:none}
52
+ @media (prefers-reduced-motion:reduce){.flow .edge path{animation:none}}
53
+ @media print{body{background:#fff;color:#000}.bar,#theme{display:none}.fig{overflow:visible}.flow .edge path{animation:none}.focus .node:not(.on),.focus .edge:not(.on){opacity:1}}`;
54
+
55
+ /** The page's script: theme, detail on hover or focus, play and pause, numbered steps. Text is set with textContent only. */
56
+ export const PAGE_JS = `(()=>{
57
+ const d=document,q=(s,r=d)=>r.querySelector(s),qa=(s,r=d)=>[...r.querySelectorAll(s)],root=d.documentElement;
58
+ try{const t=localStorage.getItem('vz-theme');if(t==='dark'||t==='light')root.dataset.theme=t}catch(e){}
59
+ const tb=q('#theme');
60
+ if(tb)tb.onclick=()=>{const dark=root.dataset.theme?root.dataset.theme==='dark':matchMedia('(prefers-color-scheme: dark)').matches,n=dark?'light':'dark';root.dataset.theme=n;try{localStorage.setItem('vz-theme',n)}catch(e){}};
61
+ if(new URLSearchParams(location.search).get('present')==='1')root.classList.add('present');
62
+ const fig=q('.fig'),panel=q('#detail');
63
+ qa('[data-node]').forEach(n=>{const show=()=>{if(panel)panel.textContent=n.dataset.detail};n.addEventListener('mouseenter',show);n.addEventListener('focus',show)});
64
+ const pp=q('#play');
65
+ if(pp&&fig)pp.onclick=()=>{const on=fig.classList.toggle('flow');pp.textContent=on?pp.dataset.pause:pp.dataset.play;pp.setAttribute('aria-pressed',String(on))};
66
+ const raw=q('#steps');
67
+ if(raw&&fig){
68
+ const steps=JSON.parse(raw.textContent),note=q('#stepnote'),prev=q('#prev'),next=q('#next'),all=q('#all');
69
+ let at=-1;
70
+ const show=i=>{at=i;qa('.on',fig).forEach(x=>x.classList.remove('on'));
71
+ if(i<0){fig.classList.remove('focus');note.textContent='';return}
72
+ const s=steps[i];fig.classList.add('focus');
73
+ s.nodes.forEach(id=>q('[data-node="'+id+'"]',fig)?.classList.add('on'));
74
+ s.edges.forEach(id=>q('[data-edge="'+id+'"]',fig)?.classList.add('on'));
75
+ note.textContent=(i+1)+'/'+steps.length+' '+s.title+' - '+s.note};
76
+ if(prev)prev.onclick=()=>show(Math.max(0,at-1));
77
+ if(next)next.onclick=()=>show(Math.min(steps.length-1,at+1));
78
+ if(all)all.onclick=()=>show(-1);
79
+ }
80
+ })();`;
@@ -0,0 +1,126 @@
1
+ export class StatusStates {
2
+ static readonly OK = 'ok';
3
+ static readonly WARN = 'warn';
4
+ static readonly BLOCKED = 'blocked';
5
+ static readonly INFO = 'info';
6
+ static readonly SCHEME_SET = new Set<string>([this.OK, this.WARN, this.BLOCKED, this.INFO]);
7
+ static isValid(value: string): boolean {
8
+ return this.SCHEME_SET.has(value);
9
+ }
10
+ }
11
+
12
+ /** How an edge reads: the main path, a branch, a return, a fan-out or a failure. Never by colour alone. */
13
+ export class EdgeVariants {
14
+ static readonly MAIN = 'main';
15
+ static readonly BRANCH = 'branch';
16
+ static readonly RETURN = 'return';
17
+ static readonly FANOUT = 'fanout';
18
+ static readonly ERROR = 'error';
19
+ static readonly SCHEME_SET = new Set<string>([
20
+ this.MAIN,
21
+ this.BRANCH,
22
+ this.RETURN,
23
+ this.FANOUT,
24
+ this.ERROR,
25
+ ]);
26
+ static isValid(value: string): boolean {
27
+ return this.SCHEME_SET.has(value);
28
+ }
29
+ }
30
+
31
+ export class NodeKinds {
32
+ static readonly STEP = 'step';
33
+ static readonly SERVICE = 'service';
34
+ static readonly STORE = 'store';
35
+ static readonly ACTOR = 'actor';
36
+ static readonly EXTERNAL = 'external';
37
+ static readonly SCHEME_SET = new Set<string>([
38
+ this.STEP,
39
+ this.SERVICE,
40
+ this.STORE,
41
+ this.ACTOR,
42
+ this.EXTERNAL,
43
+ ]);
44
+ static isValid(value: string): boolean {
45
+ return this.SCHEME_SET.has(value);
46
+ }
47
+ }
48
+
49
+ /** What a claim in the evidence table rests on. An analogy is never shown as a fact. */
50
+ export class EvidenceLabels {
51
+ static readonly VERIFIED = 'verified';
52
+ static readonly INFERRED = 'inferred';
53
+ static readonly GUESS = 'guess';
54
+ static readonly SCHEME_SET = new Set<string>([this.VERIFIED, this.INFERRED, this.GUESS]);
55
+ static isValid(value: string): boolean {
56
+ return this.SCHEME_SET.has(value);
57
+ }
58
+ }
59
+
60
+ export class VisualizeLimits {
61
+ static readonly SCHEMA_VERSION = 1;
62
+ /** A figure beyond this is two figures. */
63
+ static readonly MAX_NODES = 25;
64
+ static readonly MAX_EDGES = 40;
65
+ static readonly MAX_GRID = 10;
66
+ static readonly MAX_STEPS = 12;
67
+ static readonly MAX_ROWS_PER_TABLE = 30;
68
+ static readonly MAX_TITLE = 120;
69
+ static readonly MAX_SENTENCE = 300;
70
+ static readonly MAX_LABEL = 60;
71
+ /** An arrow label has to fit the gap between two boxes. */
72
+ static readonly MAX_EDGE_LABEL = 20;
73
+ static readonly MAX_DETAIL = 600;
74
+ /** Typical pages are 20-40 KB; a page past `FAIL_BYTES` is refused: two pages, not one dense one. */
75
+ static readonly WARN_BYTES = 60 * 1024;
76
+ static readonly FAIL_BYTES = 100 * 1024;
77
+ static readonly OUTPUT_DIRECTORY = 'prototypes';
78
+ }
79
+
80
+ /** The words of the page itself, English; a spec may override any of them (see `chrome`). */
81
+ export const DEFAULT_CHROME = {
82
+ asOf: 'As of',
83
+ scope: 'Scope',
84
+ status: 'Status',
85
+ statusStates: {
86
+ ok: 'On track',
87
+ warn: 'Needs attention',
88
+ blocked: 'Blocked',
89
+ info: 'For information',
90
+ },
91
+ healthy: 'Healthy?',
92
+ blockedBy: 'Blocked by',
93
+ changed: 'What changed',
94
+ next: 'What needs action',
95
+ flow: 'How it flows',
96
+ legend: 'Legend',
97
+ play: 'Play',
98
+ pause: 'Pause',
99
+ previous: 'Previous',
100
+ following: 'Next',
101
+ step: 'Step',
102
+ allSteps: 'All steps',
103
+ detail: 'Detail',
104
+ detailHint: 'Hover or focus a box for its detail.',
105
+ before: 'Before',
106
+ after: 'After',
107
+ added: 'added',
108
+ removed: 'removed',
109
+ decisions: 'Decisions needed',
110
+ recommended: 'Recommended',
111
+ changesClaim: 'Changes',
112
+ evidence: 'Evidence',
113
+ claim: 'Claim',
114
+ probe: 'Probe',
115
+ result: 'Result',
116
+ label: 'Basis',
117
+ evidenceLabels: { verified: 'verified', inferred: 'inferred', guess: 'guess' },
118
+ risks: 'Risks',
119
+ risk: 'Risk',
120
+ impact: 'Impact',
121
+ fallback: 'Fallback',
122
+ log: 'Log',
123
+ links: 'Links',
124
+ theme: 'Theme',
125
+ };
126
+ export type TChrome = typeof DEFAULT_CHROME;
@@ -0,0 +1,6 @@
1
+ export * from './constants.ts';
2
+ export * from './schema.ts';
3
+ export * from './validate.ts';
4
+ export * from './layout.ts';
5
+ export * from './page.ts';
6
+ export * from './render.ts';