@venizia/vulcan 0.4.9-0 → 0.4.9-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/extensions/vulcan-guards.ts +48 -41
  2. package/base/hooks/antigravity-guards.ts +2 -2
  3. package/base/hooks/codex-guards.ts +15 -5
  4. package/base/hooks/guard-git.ts +8 -8
  5. package/base/hooks/guard-manifest.ts +4 -5
  6. package/base/hooks/guard-outside.ts +8 -8
  7. package/base/hooks/guard-package.ts +5 -6
  8. package/base/hooks/guard-remote-hosts.ts +6 -7
  9. package/base/hooks/guard-scripting.ts +5 -6
  10. package/base/hooks/guard-writes.ts +8 -9
  11. package/base/hooks/post-tool.ts +2 -2
  12. package/base/hooks/prompt-submit.ts +2 -2
  13. package/base/hooks/session-start.ts +3 -3
  14. package/base/hooks/stop.ts +2 -2
  15. package/base/hooks/subagent-start.ts +2 -2
  16. package/base/skills/docs-update/SKILL.md +4 -2
  17. package/base/skills/visualize-work/SKILL.md +9 -0
  18. package/package.json +3 -3
  19. package/src/agents/atlas-block.ts +43 -43
  20. package/src/agents/codex-hooks.ts +45 -43
  21. package/src/agents/detect.ts +19 -16
  22. package/src/agents/exclude.ts +96 -97
  23. package/src/agents/hooks-json.ts +38 -36
  24. package/src/agents/local.ts +46 -43
  25. package/src/agents/prompt.ts +45 -42
  26. package/src/agents/render.ts +201 -195
  27. package/src/agents/resolve.ts +133 -134
  28. package/src/agents/table.ts +12 -8
  29. package/src/commands/add.command.ts +2 -2
  30. package/src/commands/agents.command.ts +11 -17
  31. package/src/commands/clean.command.ts +6 -6
  32. package/src/commands/doctor.command.ts +4 -4
  33. package/src/commands/init.command.ts +12 -8
  34. package/src/commands/preset.command.ts +2 -2
  35. package/src/commands/profile.command.ts +42 -49
  36. package/src/commands/sync.command.ts +109 -111
  37. package/src/commands/upgrade.command.ts +80 -75
  38. package/src/commands/visualize.command.ts +7 -13
  39. package/src/commands/x.command.ts +55 -50
  40. package/src/common/format.ts +23 -21
  41. package/src/common/json.ts +8 -5
  42. package/src/common/layout-folder.ts +94 -91
  43. package/src/common/paths.ts +14 -12
  44. package/src/config/loader.ts +52 -49
  45. package/src/config/packages.ts +14 -11
  46. package/src/config/schema.ts +3 -3
  47. package/src/create/add-app.ts +519 -509
  48. package/src/create/add-lib.ts +237 -240
  49. package/src/create/bunfig.ts +26 -23
  50. package/src/create/checks.ts +36 -34
  51. package/src/create/diff.ts +21 -23
  52. package/src/create/dockerignore.ts +26 -24
  53. package/src/create/files.ts +7 -5
  54. package/src/create/init-monorepo.ts +75 -80
  55. package/src/create/lib-preset.ts +59 -63
  56. package/src/create/manifest-json.ts +10 -4
  57. package/src/create/names.ts +217 -210
  58. package/src/create/next.ts +26 -23
  59. package/src/create/plan.ts +15 -12
  60. package/src/create/preset-diff.ts +301 -303
  61. package/src/create/preset-menu.ts +38 -32
  62. package/src/create/preset.ts +202 -197
  63. package/src/create/process.ts +79 -72
  64. package/src/create/scratch.ts +48 -49
  65. package/src/create/workspace.ts +404 -396
  66. package/src/doctor/checks.ts +1027 -1014
  67. package/src/doctor/makefile.ts +17 -13
  68. package/src/doctor/runner.ts +88 -118
  69. package/src/doctor/skills.ts +97 -95
  70. package/src/doctor/tags.ts +42 -37
  71. package/src/hooks/codex-patch.ts +25 -22
  72. package/src/hooks/command-view.ts +44 -39
  73. package/src/hooks/decision.ts +37 -37
  74. package/src/hooks/guard-git.ts +51 -49
  75. package/src/hooks/guard-manifest.ts +58 -55
  76. package/src/hooks/guard-outside.ts +93 -91
  77. package/src/hooks/guard-package.ts +82 -79
  78. package/src/hooks/guard-scripting.ts +19 -14
  79. package/src/hooks/guard-writes.ts +154 -149
  80. package/src/hooks/owner-reply.ts +127 -127
  81. package/src/hooks/post-tool.ts +94 -93
  82. package/src/hooks/project-guards.ts +65 -62
  83. package/src/hooks/project-tmp.ts +27 -24
  84. package/src/hooks/remote-hosts.ts +153 -130
  85. package/src/hooks/session-digest.ts +98 -101
  86. package/src/hooks/shell.ts +509 -499
  87. package/src/hooks/subagent-card.ts +11 -7
  88. package/src/hooks/trusted-scripts.ts +106 -104
  89. package/src/init/scaffold.ts +135 -132
  90. package/src/local/clean.ts +38 -36
  91. package/src/local/format.ts +21 -17
  92. package/src/local/scan.ts +144 -138
  93. package/src/manifest/render.ts +110 -104
  94. package/src/owner/card.ts +51 -46
  95. package/src/owner/profile.ts +99 -93
  96. package/src/owner/reply-switch.ts +9 -6
  97. package/src/owner/shape.ts +71 -69
  98. package/src/owner/survey.ts +173 -171
  99. package/src/owner/view.ts +62 -59
  100. package/src/owner/violations.ts +119 -123
  101. package/src/rules/base.ts +15 -11
  102. package/src/rules/parser.ts +39 -32
  103. package/src/rules/slots.ts +8 -6
  104. package/src/signals/claims.ts +30 -28
  105. package/src/signals/classify.ts +38 -33
  106. package/src/signals/loop.ts +39 -37
  107. package/src/signals/state.ts +79 -81
  108. package/src/skills/frontmatter.ts +28 -28
  109. package/src/sync/agent-files.ts +217 -199
  110. package/src/sync/agent-removal.ts +56 -59
  111. package/src/sync/atlas-block.ts +45 -43
  112. package/src/sync/base-rules.ts +32 -30
  113. package/src/sync/claude-launch.ts +36 -34
  114. package/src/sync/exclude.ts +77 -69
  115. package/src/sync/local-choice.ts +50 -47
  116. package/src/sync/planner.ts +59 -61
  117. package/src/sync/prune.ts +52 -48
  118. package/src/sync/settings.ts +166 -167
  119. package/src/ui/capability.ts +12 -7
  120. package/src/ui/keyboard.ts +38 -38
  121. package/src/ui/prompt.ts +79 -77
  122. package/src/visualize/assets.ts +33 -24
  123. package/src/visualize/charts.ts +179 -176
  124. package/src/visualize/compare-css.ts +3 -2
  125. package/src/visualize/compare-render.ts +9 -7
  126. package/src/visualize/diagrams.ts +189 -174
  127. package/src/visualize/grid-span.ts +34 -0
  128. package/src/visualize/icons.ts +7 -5
  129. package/src/visualize/kinds-render.ts +50 -45
  130. package/src/visualize/kinds-validate.ts +12 -10
  131. package/src/visualize/labels.ts +21 -17
  132. package/src/visualize/layout.ts +112 -97
  133. package/src/visualize/page.ts +92 -104
  134. package/src/visualize/render.ts +143 -140
  135. package/src/visualize/sections.ts +395 -384
  136. package/src/visualize/sources.ts +2 -2
  137. package/src/visualize/theme.ts +12 -10
  138. package/src/visualize/validate.ts +13 -9
  139. package/src/wiki/anchors.ts +38 -36
  140. package/src/wiki/command.ts +4 -4
  141. package/src/wiki/source-links.ts +46 -44
@@ -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,34 +18,6 @@ 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
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
23
  const { commands, trustedScripts } = opts.config.guard.writes;
@@ -86,83 +58,117 @@ const atlasBlockOf = (opts: { config: TResolvedConfig }): { atlas?: Record<strin
86
58
  return Object.keys(block).length === 0 ? {} : { atlas: block };
87
59
  };
88
60
 
89
- /**
90
- * The project manifest (Project Contract v1, C1): data only, rendered from the config with a fixed
91
- * key order, so the committed file is byte-stable and a stale one shows as a diff.
92
- */
93
- export const renderManifest = (opts: { root: string; config: TResolvedConfig }): string => {
94
- const { config } = opts;
95
- const { wiki, changelogs, syncAreas } = config.knowledge;
96
-
97
- const manifest = {
98
- [ManifestConstants.GENERATED_KEY]: ManifestConstants.GENERATED_NOTE,
99
- schemaVersion: ManifestConstants.SCHEMA_VERSION,
100
- name: projectNameOf(opts),
101
- packages: resolvePackages({ config }).map((entry) => ({
102
- name: entry.name,
103
- dir: entry.dir,
104
- path: entry.path,
105
- aliases: entry.aliases,
106
- retired: entry.retired,
107
- ...(entry.kind === undefined ? {} : { kind: entry.kind }),
108
- ...(entry.presetKind === undefined ? {} : { presetKind: entry.presetKind }),
109
- })),
110
- // Where each kind of app goes and the presets that make one: what an agent asked for a new app needs.
111
- ...(config.layout === undefined ? {} : { layout: config.layout }),
112
- ...(config.presets === undefined ? {} : { presets: config.presets }),
113
- knowledge: {
114
- bundle: config.knowledge.bundle,
115
- ...(wiki === undefined ? {} : { wiki }),
116
- ...(changelogs === undefined ? {} : { changelogs }),
117
- ...(syncAreas === undefined ? {} : { syncAreas }),
118
- },
119
- release: {
120
- tagPattern: config.atlas.tagPattern,
121
- ...(config.atlas.legacyTagPatterns === undefined ||
122
- config.atlas.legacyTagPatterns.length === 0
123
- ? {}
124
- : { legacyTagPatterns: config.atlas.legacyTagPatterns }),
125
- ignoreTags: config.atlas.ignoreTags ?? [],
126
- },
127
- rules: { project: ManifestConstants.PROJECT_RULES, base: buildBaseRuleHashes() },
128
- // The sources this project reads knowledge from (atlas, git mode); a project without any carries none.
129
- ...(config.atlas.sources.length === 0 ? {} : { sources: config.atlas.sources }),
130
- // The prebuilt index: the keys a published pair is checked with, and the switch; neither set, nothing is written.
131
- ...atlasBlockOf({ config }),
132
- // The commands and push targets the guards ask about beyond their own list; neither set, nothing is written.
133
- ...guardBlockOf({ config }),
134
- // The remote-host guard reads its policy here; a project without the key has no guard.
135
- ...(config.remoteHosts === undefined ? {} : { remoteHosts: config.remoteHosts }),
136
- // The colour `vulcan visualize` takes for its pages; a project without the key gets the neutral default.
137
- ...(config.theme === undefined ? {} : { theme: config.theme }),
138
- };
139
-
140
- return formatWithBun({
141
- text: `${JSON.stringify(manifest, null, 2)}\n`,
142
- file: ManifestConstants.FILE,
143
- });
144
- };
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
+ }
145
79
 
146
- /**
147
- * Whether a committed manifest holds what the config renders, apart from the `$generated` note: a
148
- * file written before the note existed is current, a hand-edited one is not.
149
- */
150
- export const isManifestCurrent = (opts: { committed: string; rendered: string }): boolean => {
151
- try {
152
- const strip = (text: string): string => {
153
- 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');
154
85
 
155
- delete record[ManifestConstants.GENERATED_KEY];
86
+ return [id, hash.slice(0, HASH_LENGTH)];
87
+ }),
88
+ );
89
+ }
156
90
 
157
- 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 }),
158
143
  };
159
144
 
160
- return strip(opts.committed) === strip(opts.rendered);
161
- } catch (error) {
162
- console.error(
163
- `[isManifestCurrent] unreadable manifest | ${error instanceof Error ? error.message : String(error)}`,
164
- );
145
+ return BunFormatter.format({
146
+ text: `${JSON.stringify(manifest, null, 2)}\n`,
147
+ file: ManifestConstants.FILE,
148
+ });
149
+ }
150
+
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);
165
159
 
166
- return false;
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
+ }
167
173
  }
168
- };
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
+ }
@@ -7,115 +7,121 @@ import type { TProfile } from './schema.ts';
7
7
 
8
8
  type TProfileRead = { ok: true; profile: TProfile | undefined } | { ok: false; error: string };
9
9
 
10
- /** A symlink at the profile's place, or at `.agents/local`, would read or write a file outside the project. */
11
- export const linkedAt = (opts: { root: string }): string | undefined =>
12
- [join(opts.root, OwnerConstants.PROFILE_FILE), join(opts.root, '.agents', 'local')].find(
13
- (path) => {
14
- try {
15
- return lstatSync(path).isSymbolicLink();
16
- } catch {
17
- return false;
18
- }
19
- },
20
- );
21
-
22
10
  const SYMLINK_ERROR = `${OwnerConstants.PROFILE_FILE} (or .agents/local) is a symlink - it must be a regular file inside the project`;
23
11
 
24
- /** The personal profile of the developer at `root`: absent reads as none, a broken file says what is wrong. */
25
- export const readProfile = (opts: { root: string }): TProfileRead => {
26
- const file = join(opts.root, OwnerConstants.PROFILE_FILE);
27
-
28
- if (linkedAt({ root: opts.root }) !== undefined) {
29
- 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
+ );
30
24
  }
31
25
 
32
- if (!existsSync(file)) {
33
- return { ok: true, profile: undefined };
34
- }
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);
35
29
 
36
- let payload: unknown;
30
+ if (OwnerProfile.linkedAt({ root: opts.root }) !== undefined) {
31
+ return { ok: false, error: SYMLINK_ERROR };
32
+ }
37
33
 
38
- try {
39
- payload = JSON.parse(readFileSync(file, 'utf8'));
40
- } catch {
41
- return { ok: false, error: `${OwnerConstants.PROFILE_FILE} is not valid JSON` };
42
- }
34
+ if (!existsSync(file)) {
35
+ return { ok: true, profile: undefined };
36
+ }
43
37
 
44
- const parsed = PROFILE_SCHEMA.safeParse(payload);
38
+ let payload: unknown;
45
39
 
46
- if (parsed.success) {
47
- return { ok: true, profile: parsed.data };
48
- }
40
+ try {
41
+ payload = JSON.parse(readFileSync(file, 'utf8'));
42
+ } catch {
43
+ return { ok: false, error: `${OwnerConstants.PROFILE_FILE} is not valid JSON` };
44
+ }
49
45
 
50
- const issue = parsed.error.issues[0];
51
- const where = issue?.path.join('.') ?? '';
52
-
53
- return {
54
- ok: false,
55
- error: `${OwnerConstants.PROFILE_FILE}: ${where === '' ? '' : `${where}: `}${issue?.message ?? 'not a profile'}`,
56
- };
57
- };
58
-
59
- /**
60
- * Whether git ignores the profile's place: `git check-ignore` decides when the project is a git repository
61
- * (so a later `!` line or a nested ignore file counts); otherwise the `.gitignore` is read for the line.
62
- */
63
- export const profileIsIgnored = (opts: { root: string }): boolean => {
64
- const checked = spawnSync(
65
- 'git',
66
- ['check-ignore', '-q', '--no-index', OwnerConstants.PROFILE_FILE],
67
- { cwd: opts.root, timeout: 5000 },
68
- );
69
-
70
- if (checked.status === 0 || checked.status === 1) {
71
- return checked.status === 0;
72
- }
46
+ const parsed = PROFILE_SCHEMA.safeParse(payload);
73
47
 
74
- const file = join(opts.root, '.gitignore');
75
-
76
- return (
77
- existsSync(file) &&
78
- readFileSync(file, 'utf8')
79
- .split('\n')
80
- .some((line) => ['.agents/local/', '.agents/local', '/.agents/local/'].includes(line.trim()))
81
- );
82
- };
83
-
84
- /** The profile as the file holds it. */
85
- export const renderProfile = (opts: { profile: TProfile }): string =>
86
- `${JSON.stringify(opts.profile, null, 2)}\n`;
87
-
88
- /**
89
- * Saves the profile. It refuses while `.gitignore` is missing or does not list `.agents/local/`, so a
90
- * personal file cannot be written where a commit could pick it up.
91
- */
92
- export const writeProfile = (opts: {
93
- root: string;
94
- profile: unknown;
95
- }): { ok: true } | { ok: false; error: string } => {
96
- const parsed = PROFILE_SCHEMA.safeParse(opts.profile);
97
-
98
- if (!parsed.success) {
99
- return { ok: false, error: parsed.error.issues[0]?.message ?? 'not a profile' };
100
- }
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('.') ?? '';
101
54
 
102
- if (!profileIsIgnored({ root: opts.root })) {
103
55
  return {
104
56
  ok: false,
105
- 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'}`,
106
58
  };
107
59
  }
108
60
 
109
- if (linkedAt({ root: opts.root }) !== undefined) {
110
- 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
+ );
111
86
  }
112
87
 
113
- const file = join(opts.root, OwnerConstants.PROFILE_FILE);
114
-
115
- mkdirSync(dirname(file), { recursive: true });
116
- writeFileSync(file, renderProfile({ profile: parsed.data }), { mode: 0o600 });
117
- // `mode` applies to a new file only; an existing one keeps its old mode until this.
118
- 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
+ }
119
92
 
120
- return { ok: true };
121
- };
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
+ }