@venizia/vulcan 0.4.8 → 0.4.9-1

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 (179) hide show
  1. package/base/extensions/vulcan-guards.ts +48 -41
  2. package/base/hooks/antigravity-guards.ts +4 -3
  3. package/base/hooks/codex-guards.ts +17 -6
  4. package/base/hooks/guard-git.ts +8 -8
  5. package/base/hooks/guard-manifest.ts +5 -5
  6. package/base/hooks/guard-outside.ts +8 -8
  7. package/base/hooks/guard-package.ts +6 -6
  8. package/base/hooks/guard-remote-hosts.ts +14 -9
  9. package/base/hooks/guard-scripting.ts +6 -6
  10. package/base/hooks/guard-writes.ts +20 -11
  11. package/base/hooks/post-tool.ts +4 -3
  12. package/base/hooks/prompt-submit.ts +4 -3
  13. package/base/hooks/session-start.ts +5 -3
  14. package/base/hooks/stop.ts +4 -3
  15. package/base/hooks/subagent-start.ts +2 -2
  16. package/base/make/vulcan.mk +1 -4
  17. package/base/skills/build-a-feature/SKILL.md +1 -1
  18. package/base/skills/docs-update/SKILL.md +11 -5
  19. package/base/skills/docs-update/evals/evals.json +1 -1
  20. package/base/skills/docs-writing/SKILL.md +1 -1
  21. package/base/skills/plan-a-change/references/spec-card.md +1 -1
  22. package/base/skills/ship/SKILL.md +1 -1
  23. package/base/skills/visualize-work/SKILL.md +29 -6
  24. package/base/skills/visualize-work/references/spec.md +16 -5
  25. package/package.json +5 -6
  26. package/src/agents/atlas-block.ts +43 -43
  27. package/src/agents/codex-hooks.ts +55 -52
  28. package/src/agents/common/types.ts +1 -1
  29. package/src/agents/detect.ts +19 -16
  30. package/src/agents/exclude.ts +97 -98
  31. package/src/agents/hooks-json.ts +41 -43
  32. package/src/agents/local.ts +46 -43
  33. package/src/agents/prompt.ts +45 -42
  34. package/src/agents/render.ts +203 -201
  35. package/src/agents/resolve.ts +133 -134
  36. package/src/agents/table.ts +12 -8
  37. package/src/cli.ts +3 -1
  38. package/src/commands/add.command.ts +2 -2
  39. package/src/commands/agents.command.ts +11 -17
  40. package/src/commands/clean.command.ts +6 -6
  41. package/src/commands/doctor.command.ts +6 -4
  42. package/src/commands/help.command.ts +11 -9
  43. package/src/commands/init.command.ts +14 -8
  44. package/src/commands/preset.command.ts +2 -2
  45. package/src/commands/profile.command.ts +43 -50
  46. package/src/commands/sync.command.ts +109 -111
  47. package/src/commands/upgrade.command.ts +85 -78
  48. package/src/commands/visualize.command.ts +20 -5
  49. package/src/commands/x.command.ts +55 -50
  50. package/src/common/format.ts +23 -21
  51. package/src/common/index.ts +2 -0
  52. package/src/common/json.ts +8 -5
  53. package/src/common/layout-folder.ts +96 -111
  54. package/src/common/paths.ts +14 -12
  55. package/src/common/record.ts +7 -0
  56. package/src/common/text.ts +7 -0
  57. package/src/config/common/constants.ts +13 -1
  58. package/src/config/common/types.ts +8 -1
  59. package/src/config/loader.ts +53 -48
  60. package/src/config/packages.ts +17 -11
  61. package/src/config/schema.ts +54 -7
  62. package/src/create/add-app.ts +604 -493
  63. package/src/create/add-lib.ts +249 -242
  64. package/src/create/bunfig.ts +26 -23
  65. package/src/create/checks.ts +36 -34
  66. package/src/create/common/constants.ts +1 -0
  67. package/src/create/common/failure.ts +10 -0
  68. package/src/create/common/index.ts +2 -0
  69. package/src/create/common/preset-path.ts +11 -0
  70. package/src/create/common/types.ts +7 -2
  71. package/src/create/diff.ts +21 -23
  72. package/src/create/dockerignore.ts +26 -24
  73. package/src/create/files.ts +7 -5
  74. package/src/create/init-monorepo.ts +78 -80
  75. package/src/create/lib-preset.ts +62 -61
  76. package/src/create/manifest-json.ts +10 -4
  77. package/src/create/names.ts +217 -210
  78. package/src/create/next.ts +27 -24
  79. package/src/create/plan.ts +15 -12
  80. package/src/create/preset-diff.ts +415 -240
  81. package/src/create/preset-menu.ts +40 -34
  82. package/src/create/preset.ts +207 -194
  83. package/src/create/process.ts +80 -71
  84. package/src/create/scratch.ts +49 -48
  85. package/src/create/workspace.ts +423 -398
  86. package/src/doctor/checks.ts +1069 -998
  87. package/src/doctor/makefile.ts +17 -13
  88. package/src/doctor/runner.ts +88 -116
  89. package/src/doctor/skills.ts +97 -95
  90. package/src/doctor/tags.ts +44 -41
  91. package/src/hooks/codex-patch.ts +27 -24
  92. package/src/hooks/command-view.ts +44 -39
  93. package/src/hooks/common/constants.ts +0 -3
  94. package/src/hooks/common/types.ts +15 -1
  95. package/src/hooks/decision.ts +38 -42
  96. package/src/hooks/guard-git.ts +52 -50
  97. package/src/hooks/guard-manifest.ts +58 -55
  98. package/src/hooks/guard-outside.ts +109 -88
  99. package/src/hooks/guard-package.ts +86 -77
  100. package/src/hooks/guard-scripting.ts +20 -15
  101. package/src/hooks/guard-writes.ts +169 -111
  102. package/src/hooks/owner-reply.ts +128 -128
  103. package/src/hooks/post-tool.ts +94 -93
  104. package/src/hooks/project-guards.ts +93 -55
  105. package/src/hooks/project-tmp.ts +27 -24
  106. package/src/hooks/remote-hosts.ts +157 -149
  107. package/src/hooks/session-digest.ts +99 -95
  108. package/src/hooks/shell.ts +519 -500
  109. package/src/hooks/subagent-card.ts +11 -7
  110. package/src/hooks/trusted-scripts.ts +158 -80
  111. package/src/init/common/types.ts +1 -1
  112. package/src/init/scaffold.ts +137 -134
  113. package/src/local/clean.ts +39 -37
  114. package/src/local/format.ts +21 -17
  115. package/src/local/scan.ts +146 -140
  116. package/src/manifest/render.ts +127 -112
  117. package/src/owner/card.ts +51 -46
  118. package/src/owner/profile.ts +100 -96
  119. package/src/owner/reply-switch.ts +9 -6
  120. package/src/owner/shape.ts +72 -70
  121. package/src/owner/survey.ts +175 -164
  122. package/src/owner/view.ts +62 -59
  123. package/src/owner/violations.ts +119 -123
  124. package/src/router.ts +4 -1
  125. package/src/rules/base.ts +15 -11
  126. package/src/rules/common/types.ts +1 -1
  127. package/src/rules/parser.ts +39 -32
  128. package/src/rules/slots.ts +8 -6
  129. package/src/signals/claims.ts +30 -28
  130. package/src/signals/classify.ts +36 -33
  131. package/src/signals/loop.ts +39 -37
  132. package/src/signals/state.ts +80 -85
  133. package/src/skills/frontmatter.ts +28 -28
  134. package/src/sync/agent-files.ts +217 -199
  135. package/src/sync/agent-removal.ts +62 -68
  136. package/src/sync/atlas-block.ts +45 -43
  137. package/src/sync/base-rules.ts +32 -30
  138. package/src/sync/claude-launch.ts +74 -37
  139. package/src/sync/common/constants.ts +4 -0
  140. package/src/sync/common/index.ts +1 -0
  141. package/src/sync/common/symlink.ts +9 -0
  142. package/src/sync/common/types.ts +2 -2
  143. package/src/sync/exclude.ts +77 -69
  144. package/src/sync/local-choice.ts +50 -47
  145. package/src/sync/planner.ts +64 -68
  146. package/src/sync/prune.ts +52 -48
  147. package/src/sync/settings.ts +167 -168
  148. package/src/ui/capability.ts +12 -7
  149. package/src/ui/keyboard.ts +35 -33
  150. package/src/ui/prompt.ts +81 -77
  151. package/src/visualize/assets.ts +379 -195
  152. package/src/visualize/charts.ts +188 -176
  153. package/src/visualize/compare-css.ts +31 -0
  154. package/src/visualize/compare-render.ts +196 -0
  155. package/src/visualize/compare-schema.ts +81 -0
  156. package/src/visualize/compare-validate.ts +126 -0
  157. package/src/visualize/constants.ts +29 -3
  158. package/src/visualize/diagrams.ts +189 -174
  159. package/src/visualize/gate.ts +136 -0
  160. package/src/visualize/grid-span.ts +34 -0
  161. package/src/visualize/icons.ts +9 -4
  162. package/src/visualize/index.ts +2 -0
  163. package/src/visualize/kinds-css.ts +54 -0
  164. package/src/visualize/kinds-render.ts +698 -0
  165. package/src/visualize/kinds-schema.ts +148 -0
  166. package/src/visualize/kinds-validate.ts +186 -0
  167. package/src/visualize/labels-vi.ts +109 -0
  168. package/src/visualize/labels.ts +53 -0
  169. package/src/visualize/layout.ts +112 -92
  170. package/src/visualize/page.ts +140 -114
  171. package/src/visualize/render.ts +158 -114
  172. package/src/visualize/schema.ts +21 -1
  173. package/src/visualize/sections.ts +401 -309
  174. package/src/visualize/sources.ts +270 -0
  175. package/src/visualize/theme.ts +474 -0
  176. package/src/visualize/validate.ts +15 -5
  177. package/src/wiki/anchors.ts +39 -37
  178. package/src/wiki/command.ts +4 -4
  179. package/src/wiki/source-links.ts +49 -49
@@ -1,9 +1,9 @@
1
1
  import { existsSync, readFileSync } from 'node:fs';
2
2
  import { basename, join } from 'node:path';
3
- import { formatWithBun } from '../common/index.ts';
4
- import { resolvePackages } from '../config/index.ts';
3
+ import { BunFormatter } from '../common/index.ts';
4
+ import { ProjectPackages } from '../config/index.ts';
5
5
  import type { TResolvedConfig } from '../config/index.ts';
6
- import { readBaseRules } from '../rules/index.ts';
6
+ import { BaseRules } from '../rules/index.ts';
7
7
 
8
8
  export class ManifestConstants {
9
9
  /** Committed; what atlas reads from a project - local or fetched - and nothing else. */
@@ -18,51 +18,29 @@ export class ManifestConstants {
18
18
 
19
19
  const HASH_LENGTH = 8;
20
20
 
21
- /** `@acme/shop-workspace` gives `shop`; a project with no package name takes its directory's. */
22
- export const projectNameOf = (opts: { root: string; config: TResolvedConfig }): string => {
23
- if (opts.config.name !== undefined) {
24
- return opts.config.name;
25
- }
26
-
27
- const file = join(opts.root, 'package.json');
28
- const manifest: { name?: unknown } = existsSync(file)
29
- ? JSON.parse(readFileSync(file, 'utf8'))
30
- : {};
31
- const name = typeof manifest.name === 'string' ? manifest.name : basename(opts.root);
32
-
33
- return name
34
- .replace(/^@[^/]+\//, '')
35
- .replace(/-workspace$/, '')
36
- .toLowerCase();
37
- };
38
-
39
- /** Each base rule's ID with a hash of its row: a sync after an upgrade can say which rules changed. */
40
- export const buildBaseRuleHashes = (): Record<string, string> =>
41
- Object.fromEntries(
42
- Object.entries(readBaseRules()).map(([id, row]) => {
43
- const hash = new Bun.CryptoHasher('sha256').update(row.trim()).digest('hex');
44
-
45
- return [id, hash.slice(0, HASH_LENGTH)];
46
- }),
47
- );
48
-
49
- /** The manifest's `guard` block: what the project adds to guard-writes and guard-git, as data a hook reads without the config. */
21
+ /** The manifest's `guard` block: what the project adds to guard-writes and guard-git, as data a hook reads without the config (the read-only script entries of `trustedScripts` included). */
50
22
  const guardBlockOf = (opts: { config: TResolvedConfig }): { guard?: Record<string, unknown> } => {
51
- const { commands } = opts.config.guard.writes;
23
+ const { commands, trustedScripts } = opts.config.guard.writes;
52
24
  const { askPush } = opts.config.guard.git;
53
- const block = {
25
+ // Only the object entries: a path string is read from the config by the hook, as before.
26
+ const readOnlyScripts = trustedScripts.flatMap((entry) =>
27
+ typeof entry === 'string' ? [] : [{ script: entry.script, readOnly: entry.readOnly }],
28
+ );
29
+ const writes = {
54
30
  ...(commands.length === 0
55
31
  ? {}
56
32
  : {
57
- writes: {
58
- commands: commands.map((command) => ({
59
- rule: command.rule,
60
- what: command.what,
61
- pattern: command.pattern,
62
- ...(command.ignoreCase === true ? { ignoreCase: true } : {}),
63
- })),
64
- },
33
+ commands: commands.map((command) => ({
34
+ rule: command.rule,
35
+ what: command.what,
36
+ pattern: command.pattern,
37
+ ...(command.ignoreCase === true ? { ignoreCase: true } : {}),
38
+ })),
65
39
  }),
40
+ ...(readOnlyScripts.length === 0 ? {} : { readOnlyScripts }),
41
+ };
42
+ const block = {
43
+ ...(Object.keys(writes).length === 0 ? {} : { writes }),
66
44
  ...(askPush.length === 0 ? {} : { git: { askPush } }),
67
45
  };
68
46
 
@@ -80,80 +58,117 @@ const atlasBlockOf = (opts: { config: TResolvedConfig }): { atlas?: Record<strin
80
58
  return Object.keys(block).length === 0 ? {} : { atlas: block };
81
59
  };
82
60
 
83
- /**
84
- * The project manifest (Project Contract v1, C1): data only, rendered from the config with a fixed
85
- * key order, so the committed file is byte-stable and a stale one shows as a diff.
86
- */
87
- export const renderManifest = (opts: { root: string; config: TResolvedConfig }): string => {
88
- const { config } = opts;
89
- const { wiki, changelogs, syncAreas } = config.knowledge;
90
-
91
- const manifest = {
92
- [ManifestConstants.GENERATED_KEY]: ManifestConstants.GENERATED_NOTE,
93
- schemaVersion: ManifestConstants.SCHEMA_VERSION,
94
- name: projectNameOf(opts),
95
- packages: resolvePackages({ config }).map((entry) => ({
96
- name: entry.name,
97
- dir: entry.dir,
98
- path: entry.path,
99
- aliases: entry.aliases,
100
- retired: entry.retired,
101
- ...(entry.kind === undefined ? {} : { kind: entry.kind }),
102
- })),
103
- // Where each kind of app goes and the presets that make one: what an agent asked for a new app needs.
104
- ...(config.layout === undefined ? {} : { layout: config.layout }),
105
- ...(config.presets === undefined ? {} : { presets: config.presets }),
106
- knowledge: {
107
- bundle: config.knowledge.bundle,
108
- ...(wiki === undefined ? {} : { wiki }),
109
- ...(changelogs === undefined ? {} : { changelogs }),
110
- ...(syncAreas === undefined ? {} : { syncAreas }),
111
- },
112
- release: {
113
- tagPattern: config.atlas.tagPattern,
114
- ...(config.atlas.legacyTagPatterns === undefined ||
115
- config.atlas.legacyTagPatterns.length === 0
116
- ? {}
117
- : { legacyTagPatterns: config.atlas.legacyTagPatterns }),
118
- ignoreTags: config.atlas.ignoreTags ?? [],
119
- },
120
- rules: { project: ManifestConstants.PROJECT_RULES, base: buildBaseRuleHashes() },
121
- // The sources this project reads knowledge from (atlas, git mode); a project without any carries none.
122
- ...(config.atlas.sources.length === 0 ? {} : { sources: config.atlas.sources }),
123
- // The prebuilt index: the keys a published pair is checked with, and the switch; neither set, nothing is written.
124
- ...atlasBlockOf({ config }),
125
- // The commands and push targets the guards ask about beyond their own list; neither set, nothing is written.
126
- ...guardBlockOf({ config }),
127
- // The remote-host guard reads its policy here; a project without the key has no guard.
128
- ...(config.remoteHosts === undefined ? {} : { remoteHosts: config.remoteHosts }),
129
- };
130
-
131
- return formatWithBun({
132
- text: `${JSON.stringify(manifest, null, 2)}\n`,
133
- file: ManifestConstants.FILE,
134
- });
135
- };
61
+ export class ProjectManifest {
62
+ /** `@acme/shop-workspace` gives `shop`; a project with no package name takes its directory's. */
63
+ static projectNameOf(opts: { root: string; config: TResolvedConfig }): string {
64
+ if (opts.config.name !== undefined) {
65
+ return opts.config.name;
66
+ }
67
+
68
+ const file = join(opts.root, 'package.json');
69
+ const manifest: { name?: unknown } = existsSync(file)
70
+ ? JSON.parse(readFileSync(file, 'utf8'))
71
+ : {};
72
+ const name = typeof manifest.name === 'string' ? manifest.name : basename(opts.root);
73
+
74
+ return name
75
+ .replace(/^@[^/]+\//, '')
76
+ .replace(/-workspace$/, '')
77
+ .toLowerCase();
78
+ }
136
79
 
137
- /**
138
- * Whether a committed manifest holds what the config renders, apart from the `$generated` note: a
139
- * file written before the note existed is current, a hand-edited one is not.
140
- */
141
- export const isManifestCurrent = (opts: { committed: string; rendered: string }): boolean => {
142
- try {
143
- const strip = (text: string): string => {
144
- const record: Record<string, unknown> = JSON.parse(text);
80
+ /** Each base rule's ID with a hash of its row: a sync after an upgrade can say which rules changed. */
81
+ static buildBaseRuleHashes(): Record<string, string> {
82
+ return Object.fromEntries(
83
+ Object.entries(BaseRules.read()).map(([id, row]) => {
84
+ const hash = new Bun.CryptoHasher('sha256').update(row.trim()).digest('hex');
145
85
 
146
- delete record[ManifestConstants.GENERATED_KEY];
86
+ return [id, hash.slice(0, HASH_LENGTH)];
87
+ }),
88
+ );
89
+ }
147
90
 
148
- return JSON.stringify(record);
91
+ /**
92
+ * The project manifest (Project Contract v1, C1): data only, rendered from the config with a fixed
93
+ * key order, so the committed file is byte-stable and a stale one shows as a diff.
94
+ */
95
+ static render(opts: { root: string; config: TResolvedConfig }): string {
96
+ const { config } = opts;
97
+ const { wiki, changelogs, syncAreas } = config.knowledge;
98
+
99
+ const manifest = {
100
+ [ManifestConstants.GENERATED_KEY]: ManifestConstants.GENERATED_NOTE,
101
+ schemaVersion: ManifestConstants.SCHEMA_VERSION,
102
+ name: ProjectManifest.projectNameOf(opts),
103
+ packages: ProjectPackages.resolve({ config }).map((entry) => ({
104
+ name: entry.name,
105
+ dir: entry.dir,
106
+ path: entry.path,
107
+ aliases: entry.aliases,
108
+ retired: entry.retired,
109
+ ...(entry.kind === undefined ? {} : { kind: entry.kind }),
110
+ ...(entry.presetKind === undefined ? {} : { presetKind: entry.presetKind }),
111
+ })),
112
+ // Where each kind of app goes and the presets that make one: what an agent asked for a new app needs.
113
+ ...(config.layout === undefined ? {} : { layout: config.layout }),
114
+ ...(config.presets === undefined ? {} : { presets: config.presets }),
115
+ knowledge: {
116
+ bundle: config.knowledge.bundle,
117
+ ...(wiki === undefined ? {} : { wiki }),
118
+ ...(changelogs === undefined ? {} : { changelogs }),
119
+ ...(syncAreas === undefined ? {} : { syncAreas }),
120
+ },
121
+ release: {
122
+ tagPattern: config.atlas.tagPattern,
123
+ ...(config.atlas.legacyTagPatterns === undefined ||
124
+ config.atlas.legacyTagPatterns.length === 0
125
+ ? {}
126
+ : { legacyTagPatterns: config.atlas.legacyTagPatterns }),
127
+ ignoreTags: config.atlas.ignoreTags ?? [],
128
+ },
129
+ rules: {
130
+ project: ManifestConstants.PROJECT_RULES,
131
+ base: ProjectManifest.buildBaseRuleHashes(),
132
+ },
133
+ // The sources this project reads knowledge from (atlas, git mode); a project without any carries none.
134
+ ...(config.atlas.sources.length === 0 ? {} : { sources: config.atlas.sources }),
135
+ // The prebuilt index: the keys a published pair is checked with, and the switch; neither set, nothing is written.
136
+ ...atlasBlockOf({ config }),
137
+ // The commands and push targets the guards ask about beyond their own list; neither set, nothing is written.
138
+ ...guardBlockOf({ config }),
139
+ // The remote-host guard reads its policy here; a project without the key has no guard.
140
+ ...(config.remoteHosts === undefined ? {} : { remoteHosts: config.remoteHosts }),
141
+ // The colour `vulcan visualize` takes for its pages; a project without the key gets the neutral default.
142
+ ...(config.theme === undefined ? {} : { theme: config.theme }),
149
143
  };
150
144
 
151
- return strip(opts.committed) === strip(opts.rendered);
152
- } catch (error) {
153
- console.error(
154
- `[isManifestCurrent] unreadable manifest | ${error instanceof Error ? error.message : String(error)}`,
155
- );
145
+ return BunFormatter.format({
146
+ text: `${JSON.stringify(manifest, null, 2)}\n`,
147
+ file: ManifestConstants.FILE,
148
+ });
149
+ }
156
150
 
157
- return false;
151
+ /**
152
+ * Whether a committed manifest holds what the config renders, apart from the `$generated` note: a
153
+ * file written before the note existed is current, a hand-edited one is not.
154
+ */
155
+ static isCurrent(opts: { committed: string; rendered: string }): boolean {
156
+ try {
157
+ const strip = (text: string): string => {
158
+ const record: Record<string, unknown> = JSON.parse(text);
159
+
160
+ delete record[ManifestConstants.GENERATED_KEY];
161
+
162
+ return JSON.stringify(record);
163
+ };
164
+
165
+ return strip(opts.committed) === strip(opts.rendered);
166
+ } catch (error) {
167
+ console.error(
168
+ `[ProjectManifest.isCurrent] unreadable manifest | ${error instanceof Error ? error.message : String(error)}`,
169
+ );
170
+
171
+ return false;
172
+ }
158
173
  }
159
- };
174
+ }
package/src/owner/card.ts CHANGED
@@ -66,55 +66,60 @@ const SECTION_TEXT = (opts: { section: string; view: IOwnerView }): string => {
66
66
  }
67
67
  };
68
68
 
69
- /** The shape every answer to the owner follows, from the resolved view; empty when enforcement is off. */
70
- export const renderOwnerShapeCard = (opts: { view: IOwnerView }): string[] => {
71
- if (opts.view.enforce === OwnerEnforcement.OFF) {
72
- return [];
73
- }
69
+ export class OwnerCard {
70
+ /** The shape every answer to the owner follows, from the resolved view; empty when enforcement is off. */
71
+ static renderShape(opts: { view: IOwnerView }): string[] {
72
+ if (opts.view.enforce === OwnerEnforcement.OFF) {
73
+ return [];
74
+ }
74
75
 
75
- const { view } = opts;
76
+ const { view } = opts;
76
77
 
77
- return [
78
- '## How to answer the owner',
79
- '',
80
- `Every reply, in this order: ${view.shape.map((section) => SECTION_TEXT({ section, view })).join('; ')}.`,
81
- ...(view.absolutePaths ? ['Name a file the owner should open by its full absolute path.'] : []),
82
- ...(view.labelMode === OwnerLabelModes.FREE
83
- ? [
84
- `No label has a fixed word here: write the table header, the status words, the blocked label, the decisions heading and the recommendation in ${view.language}, in the form of address the profile gives.`,
85
- ]
86
- : []),
87
- `Language: ${view.language}. Identifiers stay in backticks. Say what is unverified and what you got wrong, plainly.`,
88
- ];
89
- };
78
+ return [
79
+ '## How to answer the owner',
80
+ '',
81
+ `Every reply, in this order: ${view.shape.map((section) => SECTION_TEXT({ section, view })).join('; ')}.`,
82
+ ...(view.absolutePaths
83
+ ? ['Name a file the owner should open by its full absolute path.']
84
+ : []),
85
+ ...(view.labelMode === OwnerLabelModes.FREE
86
+ ? [
87
+ `No label has a fixed word here: write the table header, the status words, the blocked label, the decisions heading and the recommendation in ${view.language}, in the form of address the profile gives.`,
88
+ ]
89
+ : []),
90
+ `Language: ${view.language}. Identifiers stay in backticks. Say what is unverified and what you got wrong, plainly.`,
91
+ ];
92
+ }
90
93
 
91
- /** What the person told VULCAN about working with them; empty when there is no profile. */
92
- export const renderProfileCard = (opts: { view: IOwnerView }): string[] => {
93
- const { view } = opts;
94
+ /** What the person told VULCAN about working with them; empty when there is no profile. */
95
+ static renderProfile(opts: { view: IOwnerView }): string[] {
96
+ const { view } = opts;
94
97
 
95
- if (view.address === undefined) {
96
- return [];
97
- }
98
+ if (view.address === undefined) {
99
+ return [];
100
+ }
98
101
 
99
- const about = view.about === undefined ? '' : ` In their words: "${plain({ text: view.about })}"`;
102
+ const about =
103
+ view.about === undefined ? '' : ` In their words: "${plain({ text: view.about })}"`;
100
104
 
101
- return [
102
- '## Working with this person',
103
- '',
104
- [
105
- `Reply in ${view.language}.`,
106
- view.address.you === undefined ? '' : `Address them as "${view.address.you}".`,
107
- view.address.self === undefined ? '' : `Refer to yourself as "${view.address.self}".`,
108
- `Formality: ${view.address.formality}. Tone: ${view.tone}. Reports: ${view.reportDetail === 'headline' ? 'headline only' : 'headline plus tables'}.`,
109
- view.habits?.askBeforeReversible === true
110
- ? 'Ask before a reversible choice.'
111
- : 'For a reversible choice state a default and continue.',
112
- view.habits?.proposeCommits === true ? 'Propose commits.' : '',
113
- view.codeTaste === undefined
114
- ? ''
115
- : `Their code taste, in their words: "${plain({ text: view.codeTaste })}".`,
116
- ]
117
- .filter((part) => part !== '')
118
- .join(' ') + about,
119
- ];
120
- };
105
+ return [
106
+ '## Working with this person',
107
+ '',
108
+ [
109
+ `Reply in ${view.language}.`,
110
+ view.address.you === undefined ? '' : `Address them as "${view.address.you}".`,
111
+ view.address.self === undefined ? '' : `Refer to yourself as "${view.address.self}".`,
112
+ `Formality: ${view.address.formality}. Tone: ${view.tone}. Reports: ${view.reportDetail === 'headline' ? 'headline only' : 'headline plus tables'}.`,
113
+ view.habits?.askBeforeReversible === true
114
+ ? 'Ask before a reversible choice.'
115
+ : 'For a reversible choice state a default and continue.',
116
+ view.habits?.proposeCommits === true ? 'Propose commits.' : '',
117
+ view.codeTaste === undefined
118
+ ? ''
119
+ : `Their code taste, in their words: "${plain({ text: view.codeTaste })}".`,
120
+ ]
121
+ .filter((part) => part !== '')
122
+ .join(' ') + about,
123
+ ];
124
+ }
125
+ }
@@ -5,119 +5,123 @@ import { OwnerConstants } from './constants.ts';
5
5
  import { PROFILE_SCHEMA } from './schema.ts';
6
6
  import type { TProfile } from './schema.ts';
7
7
 
8
- export type TProfileRead =
9
- | { ok: true; profile: TProfile | undefined }
10
- | { ok: false; error: string };
11
-
12
- /** A symlink at the profile's place, or at `.agents/local`, would read or write a file outside the project. */
13
- export const linkedAt = (opts: { root: string }): string | undefined =>
14
- [join(opts.root, OwnerConstants.PROFILE_FILE), join(opts.root, '.agents', 'local')].find(
15
- (path) => {
16
- try {
17
- return lstatSync(path).isSymbolicLink();
18
- } catch {
19
- return false;
20
- }
21
- },
22
- );
8
+ type TProfileRead = { ok: true; profile: TProfile | undefined } | { ok: false; error: string };
23
9
 
24
10
  const SYMLINK_ERROR = `${OwnerConstants.PROFILE_FILE} (or .agents/local) is a symlink - it must be a regular file inside the project`;
25
11
 
26
- /** The personal profile of the developer at `root`: absent reads as none, a broken file says what is wrong. */
27
- export const readProfile = (opts: { root: string }): TProfileRead => {
28
- const file = join(opts.root, OwnerConstants.PROFILE_FILE);
29
-
30
- if (linkedAt({ root: opts.root }) !== undefined) {
31
- return { ok: false, error: SYMLINK_ERROR };
12
+ export class OwnerProfile {
13
+ /** A symlink at the profile's place, or at `.agents/local`, would read or write a file outside the project. */
14
+ static linkedAt(opts: { root: string }): string | undefined {
15
+ return [join(opts.root, OwnerConstants.PROFILE_FILE), join(opts.root, '.agents', 'local')].find(
16
+ (path) => {
17
+ try {
18
+ return lstatSync(path).isSymbolicLink();
19
+ } catch {
20
+ return false;
21
+ }
22
+ },
23
+ );
32
24
  }
33
25
 
34
- if (!existsSync(file)) {
35
- return { ok: true, profile: undefined };
36
- }
26
+ /** The personal profile of the developer at `root`: absent reads as none, a broken file says what is wrong. */
27
+ static read(opts: { root: string }): TProfileRead {
28
+ const file = join(opts.root, OwnerConstants.PROFILE_FILE);
37
29
 
38
- let payload: unknown;
30
+ if (OwnerProfile.linkedAt({ root: opts.root }) !== undefined) {
31
+ return { ok: false, error: SYMLINK_ERROR };
32
+ }
39
33
 
40
- try {
41
- payload = JSON.parse(readFileSync(file, 'utf8'));
42
- } catch {
43
- return { ok: false, error: `${OwnerConstants.PROFILE_FILE} is not valid JSON` };
44
- }
34
+ if (!existsSync(file)) {
35
+ return { ok: true, profile: undefined };
36
+ }
45
37
 
46
- const parsed = PROFILE_SCHEMA.safeParse(payload);
38
+ let payload: unknown;
47
39
 
48
- if (parsed.success) {
49
- return { ok: true, profile: parsed.data };
50
- }
40
+ try {
41
+ payload = JSON.parse(readFileSync(file, 'utf8'));
42
+ } catch {
43
+ return { ok: false, error: `${OwnerConstants.PROFILE_FILE} is not valid JSON` };
44
+ }
51
45
 
52
- const issue = parsed.error.issues[0];
53
- const where = issue?.path.join('.') ?? '';
54
-
55
- return {
56
- ok: false,
57
- error: `${OwnerConstants.PROFILE_FILE}: ${where === '' ? '' : `${where}: `}${issue?.message ?? 'not a profile'}`,
58
- };
59
- };
60
-
61
- /**
62
- * Whether git ignores the profile's place: `git check-ignore` decides when the project is a git repository
63
- * (so a later `!` line or a nested ignore file counts); otherwise the `.gitignore` is read for the line.
64
- */
65
- export const profileIsIgnored = (opts: { root: string }): boolean => {
66
- const checked = spawnSync(
67
- 'git',
68
- ['check-ignore', '-q', '--no-index', OwnerConstants.PROFILE_FILE],
69
- { cwd: opts.root, timeout: 5000 },
70
- );
71
-
72
- if (checked.status === 0 || checked.status === 1) {
73
- return checked.status === 0;
74
- }
46
+ const parsed = PROFILE_SCHEMA.safeParse(payload);
75
47
 
76
- const file = join(opts.root, '.gitignore');
77
-
78
- return (
79
- existsSync(file) &&
80
- readFileSync(file, 'utf8')
81
- .split('\n')
82
- .some((line) => ['.agents/local/', '.agents/local', '/.agents/local/'].includes(line.trim()))
83
- );
84
- };
85
-
86
- /** The profile as the file holds it. */
87
- export const renderProfile = (opts: { profile: TProfile }): string =>
88
- `${JSON.stringify(opts.profile, null, 2)}\n`;
89
-
90
- /**
91
- * Saves the profile. It refuses while `.gitignore` is missing or does not list `.agents/local/`, so a
92
- * personal file cannot be written where a commit could pick it up.
93
- */
94
- export const writeProfile = (opts: {
95
- root: string;
96
- profile: unknown;
97
- }): { ok: true } | { ok: false; error: string } => {
98
- const parsed = PROFILE_SCHEMA.safeParse(opts.profile);
99
-
100
- if (!parsed.success) {
101
- return { ok: false, error: parsed.error.issues[0]?.message ?? 'not a profile' };
102
- }
48
+ if (parsed.success) {
49
+ return { ok: true, profile: parsed.data };
50
+ }
51
+
52
+ const issue = parsed.error.issues[0];
53
+ const where = issue?.path.join('.') ?? '';
103
54
 
104
- if (!profileIsIgnored({ root: opts.root })) {
105
55
  return {
106
56
  ok: false,
107
- error: `.gitignore does not list .agents/local/ - run vulcan sync (or add the line) before saving a personal profile`,
57
+ error: `${OwnerConstants.PROFILE_FILE}: ${where === '' ? '' : `${where}: `}${issue?.message ?? 'not a profile'}`,
108
58
  };
109
59
  }
110
60
 
111
- if (linkedAt({ root: opts.root }) !== undefined) {
112
- return { ok: false, error: SYMLINK_ERROR };
61
+ /**
62
+ * Whether git ignores the profile's place: `git check-ignore` decides when the project is a git repository
63
+ * (so a later `!` line or a nested ignore file counts); otherwise the `.gitignore` is read for the line.
64
+ */
65
+ static profileIsIgnored(opts: { root: string }): boolean {
66
+ const checked = spawnSync(
67
+ 'git',
68
+ ['check-ignore', '-q', '--no-index', OwnerConstants.PROFILE_FILE],
69
+ { cwd: opts.root, timeout: 5000 },
70
+ );
71
+
72
+ if (checked.status === 0 || checked.status === 1) {
73
+ return checked.status === 0;
74
+ }
75
+
76
+ const file = join(opts.root, '.gitignore');
77
+
78
+ return (
79
+ existsSync(file) &&
80
+ readFileSync(file, 'utf8')
81
+ .split('\n')
82
+ .some((line) =>
83
+ ['.agents/local/', '.agents/local', '/.agents/local/'].includes(line.trim()),
84
+ )
85
+ );
113
86
  }
114
87
 
115
- const file = join(opts.root, OwnerConstants.PROFILE_FILE);
116
-
117
- mkdirSync(dirname(file), { recursive: true });
118
- writeFileSync(file, renderProfile({ profile: parsed.data }), { mode: 0o600 });
119
- // `mode` applies to a new file only; an existing one keeps its old mode until this.
120
- chmodSync(file, 0o600);
88
+ /** The profile as the file holds it. */
89
+ static render(opts: { profile: TProfile }): string {
90
+ return `${JSON.stringify(opts.profile, null, 2)}\n`;
91
+ }
121
92
 
122
- return { ok: true };
123
- };
93
+ /**
94
+ * Saves the profile. It refuses while `.gitignore` is missing or does not list `.agents/local/`, so a
95
+ * personal file cannot be written where a commit could pick it up.
96
+ */
97
+ static write(opts: {
98
+ root: string;
99
+ profile: unknown;
100
+ }): { ok: true } | { ok: false; error: string } {
101
+ const parsed = PROFILE_SCHEMA.safeParse(opts.profile);
102
+
103
+ if (!parsed.success) {
104
+ return { ok: false, error: parsed.error.issues[0]?.message ?? 'not a profile' };
105
+ }
106
+
107
+ if (!OwnerProfile.profileIsIgnored({ root: opts.root })) {
108
+ return {
109
+ ok: false,
110
+ error: `.gitignore does not list .agents/local/ - run vulcan sync (or add the line) before saving a personal profile`,
111
+ };
112
+ }
113
+
114
+ if (OwnerProfile.linkedAt({ root: opts.root }) !== undefined) {
115
+ return { ok: false, error: SYMLINK_ERROR };
116
+ }
117
+
118
+ const file = join(opts.root, OwnerConstants.PROFILE_FILE);
119
+
120
+ mkdirSync(dirname(file), { recursive: true });
121
+ writeFileSync(file, OwnerProfile.render({ profile: parsed.data }), { mode: 0o600 });
122
+ // `mode` applies to a new file only; an existing one keeps its old mode until this.
123
+ chmodSync(file, 0o600);
124
+
125
+ return { ok: true };
126
+ }
127
+ }
@@ -1,8 +1,11 @@
1
1
  import { OwnerReplySwitch } from './constants.ts';
2
2
 
3
- /**
4
- * Whether the session was started with `VULCAN_OWNER_REPLY=off`: its reader is an agent, so the owner's
5
- * report shape is neither shown nor checked in it. Only the exact value `off` counts.
6
- */
7
- export const isOwnerReplyOff = (opts: { env: Record<string, string | undefined> }): boolean =>
8
- opts.env[OwnerReplySwitch.ENV] === OwnerReplySwitch.OFF;
3
+ export class ReplySwitch {
4
+ /**
5
+ * Whether the session was started with `VULCAN_OWNER_REPLY=off`: its reader is an agent, so the owner's
6
+ * report shape is neither shown nor checked in it. Only the exact value `off` counts.
7
+ */
8
+ static isOwnerOff(opts: { env: Record<string, string | undefined> }): boolean {
9
+ return opts.env[OwnerReplySwitch.ENV] === OwnerReplySwitch.OFF;
10
+ }
11
+ }