@venizia/vulcan 0.4.9-4 → 0.4.9-6

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 (65) hide show
  1. package/base/ci-global.json +13 -0
  2. package/base/claude/events.json +60 -0
  3. package/base/hooks/auto-clean.ts +22 -0
  4. package/base/hooks/event.ts +37 -0
  5. package/base/hooks/session-start.ts +12 -0
  6. package/base/rules.md +1 -1
  7. package/base/skills/retro/SKILL.md +2 -2
  8. package/base/templates/board.html +4697 -0
  9. package/base/templates/ci/github-actions.yml +75 -0
  10. package/base/templates/ci/gitlab-ci.yml +52 -0
  11. package/package.json +3 -3
  12. package/src/board/command.ts +200 -0
  13. package/src/board/common/constants.ts +122 -0
  14. package/src/board/common/index.ts +2 -0
  15. package/src/board/common/types.ts +86 -0
  16. package/src/board/fold.ts +428 -0
  17. package/src/board/github.ts +255 -0
  18. package/src/board/index.ts +6 -0
  19. package/src/board/page.ts +26 -0
  20. package/src/board/settings.ts +106 -0
  21. package/src/ci/affected.ts +176 -0
  22. package/src/ci/command.ts +166 -0
  23. package/src/ci/common/constants.ts +76 -0
  24. package/src/ci/common/index.ts +2 -0
  25. package/src/ci/common/types.ts +37 -0
  26. package/src/ci/git.ts +72 -0
  27. package/src/ci/global.ts +48 -0
  28. package/src/ci/graph.ts +43 -0
  29. package/src/ci/index.ts +7 -0
  30. package/src/ci/workspace.ts +119 -0
  31. package/src/commands/board.command.ts +5 -0
  32. package/src/commands/ci.command.ts +4 -0
  33. package/src/commands/clean.command.ts +3 -5
  34. package/src/commands/event.command.ts +5 -0
  35. package/src/commands/help.command.ts +14 -2
  36. package/src/commands/index.ts +5 -0
  37. package/src/common/constants.ts +11 -0
  38. package/src/config/common/constants.ts +1 -0
  39. package/src/config/schema.ts +108 -0
  40. package/src/doctor/checks.ts +110 -7
  41. package/src/doctor/common/constants.ts +2 -0
  42. package/src/doctor/runner.ts +3 -0
  43. package/src/events/actor.ts +116 -0
  44. package/src/events/command.ts +210 -0
  45. package/src/events/common/constants.ts +149 -0
  46. package/src/events/common/index.ts +2 -0
  47. package/src/events/common/types.ts +53 -0
  48. package/src/events/flow.ts +92 -0
  49. package/src/events/hook.ts +163 -0
  50. package/src/events/index.ts +9 -0
  51. package/src/events/log.ts +166 -0
  52. package/src/events/retention.ts +172 -0
  53. package/src/events/settings.ts +92 -0
  54. package/src/events/text.ts +49 -0
  55. package/src/local/auto-clean-run.ts +99 -0
  56. package/src/local/auto-clean.ts +147 -0
  57. package/src/local/clean.ts +33 -1
  58. package/src/local/constants.ts +37 -1
  59. package/src/local/index.ts +1 -0
  60. package/src/local/scan.ts +297 -31
  61. package/src/manifest/render.ts +52 -0
  62. package/src/router.ts +32 -0
  63. package/src/sync/common/constants.ts +2 -0
  64. package/src/sync/local-choice.ts +3 -3
  65. package/src/sync/planner.ts +10 -1
@@ -0,0 +1,13 @@
1
+ {
2
+ "files": [
3
+ "bun.lock",
4
+ "bun.lockb",
5
+ "package.json",
6
+ "bunfig.toml",
7
+ "tsconfig*.json",
8
+ ".configs/**",
9
+ ".github/workflows/**",
10
+ ".gitlab-ci.yml",
11
+ ".gitlab/**"
12
+ ]
13
+ }
@@ -0,0 +1,60 @@
1
+ {
2
+ "hooks": {
3
+ "SessionStart": [
4
+ {
5
+ "hooks": [
6
+ {
7
+ "type": "command",
8
+ "command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/node_modules/@venizia/vulcan/base/hooks/event.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun \"$f\"; fi; exit 0",
9
+ "timeout": 5
10
+ }
11
+ ]
12
+ }
13
+ ],
14
+ "Stop": [
15
+ {
16
+ "hooks": [
17
+ {
18
+ "type": "command",
19
+ "command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/node_modules/@venizia/vulcan/base/hooks/event.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun \"$f\"; fi; exit 0",
20
+ "timeout": 5
21
+ }
22
+ ]
23
+ }
24
+ ],
25
+ "SubagentStop": [
26
+ {
27
+ "hooks": [
28
+ {
29
+ "type": "command",
30
+ "command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/node_modules/@venizia/vulcan/base/hooks/event.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun \"$f\"; fi; exit 0",
31
+ "timeout": 5
32
+ }
33
+ ]
34
+ }
35
+ ],
36
+ "Notification": [
37
+ {
38
+ "hooks": [
39
+ {
40
+ "type": "command",
41
+ "command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/node_modules/@venizia/vulcan/base/hooks/event.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun \"$f\"; fi; exit 0",
42
+ "timeout": 5
43
+ }
44
+ ]
45
+ }
46
+ ],
47
+ "PostToolUse": [
48
+ {
49
+ "matcher": "SendMessage",
50
+ "hooks": [
51
+ {
52
+ "type": "command",
53
+ "command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/node_modules/@venizia/vulcan/base/hooks/event.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun \"$f\"; fi; exit 0",
54
+ "timeout": 5
55
+ }
56
+ ]
57
+ }
58
+ ]
59
+ }
60
+ }
@@ -0,0 +1,22 @@
1
+ /**
2
+ * The automatic clean of `.agents/local/`, started detached by the session-start hook at most once a day
3
+ * (src/local/auto-clean.ts). It removes the safe part only (src/local/auto-clean-run.ts) and writes a stamp with what went.
4
+ * It fails open: nothing waits for it, and an error is a line on a stderr nobody reads.
5
+ */
6
+
7
+ // A module, so the awaits below are top-level; it has no static import, by design.
8
+ export {};
9
+
10
+ try {
11
+ const root = process.argv[2];
12
+
13
+ if (root !== undefined && root !== '') {
14
+ const { AutoCleanRun } = await import('../../src/local/auto-clean-run.ts');
15
+
16
+ AutoCleanRun.run({ root });
17
+ }
18
+ } catch (error) {
19
+ console.error(
20
+ `vulcan: the automatic clean failed (${error instanceof Error ? error.message : String(error)})`,
21
+ );
22
+ }
@@ -0,0 +1,37 @@
1
+ /**
2
+ * Event log hook (SessionStart, Stop, SubagentStop, Notification, PostToolUse on SendMessage): appends one
3
+ * line to the agent event log (src/events/hook.ts) when the manifest says `events.log` is on. It stores
4
+ * names and short labels only - never a message body, the last reply, a command or a file path.
5
+ *
6
+ * It fails OPEN and says nothing on stdout: input it cannot read, a missing module or a write that fails
7
+ * pass with a note on stderr, and the agent is never held. It imports only the events module, no config and
8
+ * no zod, because it runs on every session event. `VULCAN_GUARDS=off` switches it off.
9
+ */
10
+
11
+ // A module, so the awaits below are top-level; it has no static import, by design.
12
+ export {};
13
+
14
+ if (process.env.VULCAN_GUARDS === 'off') {
15
+ process.exit(0);
16
+ }
17
+
18
+ try {
19
+ const { EventHook } = await import('../../src/events/hook.ts');
20
+ const stdin = await Bun.stdin.text();
21
+
22
+ EventHook.run({
23
+ root: process.env.CLAUDE_PROJECT_DIR ?? process.cwd(),
24
+ input: JSON.parse(stdin),
25
+ env: process.env,
26
+ });
27
+ } catch (error) {
28
+ // Input that is not JSON is not echoed: Bun's parse error quotes it.
29
+ const reason =
30
+ error instanceof SyntaxError
31
+ ? 'unreadable input'
32
+ : error instanceof Error
33
+ ? error.message
34
+ : String(error);
35
+
36
+ console.error(`vulcan: the event hook failed (${reason}) - the event is not logged`);
37
+ }
@@ -19,3 +19,15 @@ try {
19
19
  `vulcan: [session-start] could not make TMPDIR the project's temp folder: ${error}`,
20
20
  );
21
21
  }
22
+
23
+ // At most once a day, the safe part of .agents/local/ is cleaned by a process of its own: the session does not wait for it.
24
+ try {
25
+ const { LocalAutoClean } = await import('../../src/local/auto-clean.ts');
26
+ const note = LocalAutoClean.tick({ root: projectRoot });
27
+
28
+ if (note !== undefined) {
29
+ console.error(note);
30
+ }
31
+ } catch (error) {
32
+ console.error(`vulcan: [session-start] the automatic clean was skipped: ${error}`);
33
+ }
package/base/rules.md CHANGED
@@ -74,7 +74,7 @@ An ID the base drops is never reused.
74
74
  | V-C-06 | **Never a silent catch - log it.** Always braces. Early return. `switch` with `default` over a long if-else chain. Strict TypeScript; no `any` where a type exists. | LINT (braces, floating promises) + SOFT |
75
75
  | V-C-07 | **A function name opens with its verb** - `generate` `build` `to` `is` `has` `assert` `extract` `enrich` `get` `resolve`. `is*` returns a boolean and leaves the branch to the caller; `assert*` throws and returns `void`, so the code after it needs none - reach for `assert*` when every caller would throw on `false` anyway. `has*` is the ownership question (`hasBucket`, never `isBucketExists`). That list is for UTILITY functions; service methods lean on a wider set. **Arrow functions, not `function` declarations** (do not churn existing ones). State plus the operations on it live in a class with static members - the `LoggerFactory` shape - never module-level `let` plus exported arrows. | SOFT |
76
76
  | V-C-08 | **Enumerable strings are a const class plus `TConstValue`,** never a raw string-literal union. When something validates against such a class, it carries `static readonly SCHEME_SET = new Set([...])` over its values and `static isValid(value: string): boolean` reading it, so a runtime check exists wherever a value crosses a boundary (`IsolationLevels` in connectors is the model; a subclass redeclares `SCHEME_SET` with `...Parent.SCHEME_SET` first); a class nothing validates against needs neither. The `T`/`I` prefix follows the declaration keyword: `type` gets `T`, `interface` gets `I`; an interface turned into a type alias is renamed, and no tool catches it - grep both directions. | SOFT |
77
- | V-C-09 | **Comments state only a constraint the code cannot show** - one to three lines; no history, no dates, no decision notes, no restating the code - the one exception is the `// SHORTCUT:` marker of V-B-07. Most code needs none. | SOFT |
77
+ | V-C-09 | **Comments state only a lasting fact the code cannot show** - a constraint, an external contract, a non-obvious invariant; one to three lines; no history, no dates, no decision or review notes, no restating the code. An exported declaration may carry a short JSDoc: one summary line, `@param`/`@returns` without `{type}`. Machine directives stay. The one other exception is the `// SHORTCUT:` marker of V-B-07. Most code needs none; remove a meaningless comment in the lines you touch. | SOFT |
78
78
  | V-C-10 | **No explicit cast in new code.** `as X`, `as any`, `as unknown as X` and `as never` assert nothing; they silence the compiler where the type is wrong. Fix the type instead: a generic on the setter, a narrower parameter, a typed helper, `satisfies`. A pre-existing cast is removed when the line is touched, never copied. Generic parameters are full words (`ApplicationType`, `TDocument`), never `App` or `TDoc` (V-C-04). | SOFT |
79
79
  | V-C-11 | **SIMPLE FIRST, in code and in prose.** Fewest concepts, plainest words, smallest surface. Complexity must buy correctness, speed or safety the simple version cannot, and the artifact says what it bought. Something a reader cannot follow in one pass is a defect even when it works. Fix the root cause with the smallest change; never layer an abstraction on a misdiagnosed problem. Small means the code holds only what the task needs - not golfed: no clever one-liners to save lines, and no code for a need nobody has yet. | SOFT |
80
80
  | V-C-12 | **Consistent, never self-invented.** Before writing anything new - a constant, file, binding key, error shape - find the nearest precedent in this repo and copy its shape. Binding keys are namespaced (`controllers.X`, `services.X`, `repositories.X`, `datasources.X`). Every scope is one folder with nested `common/{types,constants}.ts` and an index barrel (`inversion` is the model). A second style for something that already has one is a defect. | SOFT |
@@ -48,7 +48,7 @@ Classify before proposing anything, in this order:
48
48
  | Rule | A judgement call no program can make | One line in the rules, through the admission bar below |
49
49
  | Skill edit | The skill led the agent wrong, or left a step out | The smallest edit to the skill, and its eval |
50
50
  | Knowledge fact | The agent lacked a fact the project could state | A line in the knowledge bundle (`knowledge-sync` skill) |
51
- | Out of scope | The proposal was considered and rejected | One file in `.agents/out-of-scope/`: the reasons, the date, what would reopen it |
51
+ | Rejected | The proposal was considered and rejected | A note in the issue or pull request where it was rejected: the reasons, the date, what would reopen it |
52
52
  | Nothing | A rule already exists and was loaded; the lapse was one-off | Say so: "nothing, the rule exists" |
53
53
 
54
54
  The admission bar for a rule or a skill line: an observed failure with a date; a mechanical violation
@@ -64,6 +64,6 @@ change installed without a pick is how good work gets blocked. Ask once, with a
64
64
  ## 5. Apply what was picked
65
65
 
66
66
  Only the owner's picks, each through its own path: a check through `build-a-feature`, a rule or skill line
67
- through the admission bar, a knowledge fact through `knowledge-sync`, a rejection as an out-of-scope file.
67
+ through the admission bar, a knowledge fact through `knowledge-sync`, a rejection as a note in the issue or pull request where it was rejected.
68
68
  Open an issue only for a pick. Report with `report-back`: what was applied, what was left, and the state of
69
69
  the previous retro's items.