Skip to content

Commit a80c81d

Browse files
jiten-singh-shahijiten-singh-shahi
authored
feat: hooks adapter, cross-harness compatibility, and install fixes (#16)
* feat: add hooks adapter for cross-harness compatibility - Create hooks-adapter.js to transform Claude Code hooks → Cursor format - Create hook-input.js normalizer for cross-harness input compatibility - Create build-cursor-hooks.js build step (.cursor/hooks.json now generated) - Update 14 hook scripts to use normalizeInput() for both formats - Fix hooks.json to match official Claude Code spec (remove $schema, per-group description; add top-level description, if fields, statusMessage) - Update hooks.schema.json to support all 26 Claude Code events and all 4 hook types (command, http, prompt, agent) * fix: merge hooks into settings.json on install, fix npx command - Install executor now merges hooks into .claude/settings.json instead of copying hooks.json (Claude Code reads hooks from settings, not from a separate hooks.json — that format is plugin-only) - Hook commands remapped from ${CLAUDE_PLUGIN_ROOT} to $CLAUDE_PROJECT_DIR paths, with run-with-flags wrapper stripped for direct install - Fix npx scc → npx scc-universal across all docs and skills (npx resolves by package name, not bin name) * fix: rename bin from scc to scc-universal to avoid npm name conflict The npm package 'scc' (v0.1.3) already exists. Using 'npx scc' would install that package instead of ours. Renamed bin entry to scc-universal so 'npx scc-universal install all' works correctly. Updated all help text and tests to match. * docs: restructure install section with Claude Code vs Cursor targets * fix: update smoke test and CI workflow to use scc-universal npx scc downloads the wrong package (scc@0.1.3). Fixed smoke-test.sh, ci.yml, and package.json postinstall message to use scc-universal. * fix: update CI and smoke test to verify hooks in settings.json Hooks are now merged into .claude/settings.json, not copied as .claude/hooks/hooks.json. Updated CI verification, smoke test, and sf-quickstart skill to check the correct location. * chore: add npm run smoke script for local smoke testing
1 parent 05de038 commit a80c81d

45 files changed

Lines changed: 1080 additions & 396 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.claude-plugin/README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ Salesforce Claude Code (SCC) — production-ready AI agent harness for Salesforc
1515

1616
```bash
1717
npm install -g scc-universal
18-
npx scc install all
18+
npx scc-universal install all
1919
```
2020

2121
### From Source
@@ -24,7 +24,7 @@ npx scc install all
2424
git clone <repo-url> salesforce-claude-code
2525
cd salesforce-claude-code
2626
npm install
27-
npx scc install all
27+
npx scc-universal install all
2828
```
2929

3030
## What's Included

‎.cursor-plugin/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ Salesforce Claude Code (SCC) — production-ready AI agent harness for Salesforc
1515

1616
```bash
1717
npm install -g scc-universal
18-
npx scc install all --target cursor
18+
npx scc-universal install all --target cursor
1919
```
2020

2121
### Local Development

‎.cursor/hooks.json‎

Lines changed: 105 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -1,106 +1,147 @@
11
{
2+
"version": 1,
23
"hooks": {
34
"sessionStart": [
45
{
5-
"command": "node .cursor/hooks/session-start.js",
6-
"event": "sessionStart",
7-
"description": "Display Salesforce project context: detected org, scratch orgs, CLI version"
8-
}
9-
],
10-
"sessionEnd": [
6+
"command": "node scripts/hooks/session-start.js",
7+
"timeout": 15
8+
},
119
{
12-
"command": "node .cursor/hooks/session-end.js",
13-
"event": "sessionEnd",
14-
"description": "Persist session state and evaluate patterns"
10+
"command": "node scripts/hooks/check-platform-docs-age.js",
11+
"timeout": 5
1512
}
1613
],
1714
"beforeShellExecution": [
1815
{
1916
"command": "npx block-no-verify@1.1.2",
20-
"event": "beforeShellExecution",
21-
"description": "Block git hook-bypass flag to protect pre-commit, commit-msg, and pre-push hooks from being skipped"
17+
"failClosed": true
2218
},
2319
{
24-
"command": "node .cursor/hooks/before-shell-execution.js",
25-
"event": "beforeShellExecution",
26-
"description": "Validate SF CLI commands, SFDX deprecation warnings, git push reminder"
27-
}
28-
],
29-
"afterShellExecution": [
20+
"command": "node scripts/hooks/pre-tool-use.js",
21+
"timeout": 10
22+
},
3023
{
31-
"command": "node .cursor/hooks/after-shell-execution.js",
32-
"event": "afterShellExecution",
33-
"description": "PR URL logging, build/deploy completion notice"
34-
}
35-
],
36-
"afterFileEdit": [
24+
"command": "node scripts/hooks/sfdx-validate.js",
25+
"timeout": 10
26+
},
3727
{
38-
"command": "node .cursor/hooks/after-file-edit.js",
39-
"event": "afterFileEdit",
40-
"description": "Quality gate, governor checks, console.log warning, auto-format"
41-
}
42-
],
43-
"beforeReadFile": [
28+
"command": "node scripts/hooks/pre-bash-git-push-reminder.js",
29+
"timeout": 5
30+
},
4431
{
45-
"command": "node .cursor/hooks/before-read-file.js",
46-
"event": "beforeReadFile",
47-
"description": "Warn when reading sensitive files (.env, .key, .pem)"
48-
}
49-
],
50-
"beforeSubmitPrompt": [
32+
"command": "node scripts/hooks/sfdx-scanner-check.js",
33+
"timeout": 45
34+
},
5135
{
52-
"command": "node .cursor/hooks/before-submit-prompt.js",
53-
"event": "beforeSubmitPrompt",
54-
"description": "Detect secrets in prompts (sk-, ghp_, AKIA patterns)"
36+
"command": "node scripts/hooks/pre-bash-tmux-reminder.js",
37+
"timeout": 5
5538
}
5639
],
57-
"subagentStart": [
40+
"preToolUse": [
41+
{
42+
"command": "node scripts/hooks/mcp-health-check.js",
43+
"failClosed": true
44+
},
45+
{
46+
"command": "bash scripts/hooks/learning-observe.sh",
47+
"timeout": 10
48+
},
5849
{
59-
"command": "node .cursor/hooks/subagent-start.js",
60-
"event": "subagentStart",
61-
"description": "Log agent spawning for observability"
50+
"command": "node scripts/hooks/doc-file-warning.js",
51+
"timeout": 5,
52+
"matcher": "Write"
53+
},
54+
{
55+
"command": "node scripts/hooks/suggest-compact.js",
56+
"timeout": 5,
57+
"matcher": "Write"
6258
}
6359
],
64-
"subagentStop": [
60+
"postToolUse": [
6561
{
66-
"command": "node .cursor/hooks/subagent-stop.js",
67-
"event": "subagentStop",
68-
"description": "Log agent completion"
62+
"command": "bash scripts/hooks/learning-observe.sh",
63+
"timeout": 10
6964
}
7065
],
71-
"afterTabFileEdit": [
66+
"afterFileEdit": [
7267
{
73-
"command": "node .cursor/hooks/after-tab-file-edit.js",
74-
"event": "afterTabFileEdit",
75-
"description": "Auto-format Tab edits"
68+
"command": "node scripts/hooks/post-write.js",
69+
"timeout": 10
70+
},
71+
{
72+
"command": "node scripts/hooks/quality-gate.js",
73+
"timeout": 15
74+
},
75+
{
76+
"command": "node scripts/hooks/governor-check.js",
77+
"timeout": 10
78+
},
79+
{
80+
"command": "node scripts/hooks/post-edit-console-warn.js",
81+
"timeout": 10
82+
},
83+
{
84+
"command": "node scripts/hooks/post-edit-format.js",
85+
"timeout": 15
86+
},
87+
{
88+
"command": "node scripts/hooks/post-edit-typecheck.js",
89+
"timeout": 30
7690
}
7791
],
78-
"beforeMCPExecution": [
92+
"afterShellExecution": [
93+
{
94+
"command": "node scripts/hooks/post-bash-build-complete.js",
95+
"timeout": 10
96+
},
7997
{
80-
"command": "node .cursor/hooks/before-mcp-execution.js",
81-
"event": "beforeMCPExecution",
82-
"description": "Log MCP server/tool invocations for observability"
98+
"command": "node scripts/hooks/post-bash-pr-created.js",
99+
"timeout": 10
83100
}
84101
],
85-
"afterMCPExecution": [
102+
"postToolUseFailure": [
86103
{
87-
"command": "node .cursor/hooks/after-mcp-execution.js",
88-
"event": "afterMCPExecution",
89-
"description": "Log MCP result status (OK/FAILED) for observability"
104+
"command": "node scripts/hooks/mcp-health-check.js",
105+
"failClosed": true
90106
}
91107
],
92108
"preCompact": [
93109
{
94-
"command": "node .cursor/hooks/pre-compact.js",
95-
"event": "preCompact",
96-
"description": "Save state before context compaction"
110+
"command": "node scripts/hooks/pre-compact.js",
111+
"timeout": 10
97112
}
98113
],
99114
"stop": [
100115
{
101-
"command": "node .cursor/hooks/stop.js",
102-
"event": "stop",
103-
"description": "Console.log audit, session summary, cost tracking"
116+
"command": "node scripts/hooks/stop-hook.js",
117+
"timeout": 10,
118+
"loop_limit": 3
119+
},
120+
{
121+
"command": "node scripts/hooks/check-console-log.js",
122+
"timeout": 10,
123+
"loop_limit": 3
124+
},
125+
{
126+
"command": "node scripts/hooks/session-end.js",
127+
"timeout": 15,
128+
"loop_limit": 3
129+
},
130+
{
131+
"command": "node scripts/hooks/cost-tracker.js",
132+
"timeout": 10,
133+
"loop_limit": 3
134+
},
135+
{
136+
"command": "node scripts/hooks/evaluate-session.js",
137+
"timeout": 10,
138+
"loop_limit": 3
139+
}
140+
],
141+
"sessionEnd": [
142+
{
143+
"command": "node scripts/hooks/session-end-marker.js",
144+
"timeout": 10
104145
}
105146
]
106147
}

‎.cursor/skills/configure-scc/SKILL.md‎

Lines changed: 20 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -25,9 +25,9 @@ Interactive guide for installing and configuring Salesforce Claude Code.
2525
npm install -g scc-universal
2626

2727
# Install with a profile
28-
npx scc install all # Everything (all agents, skills, rules)
29-
npx scc install apex # Apex-focused development
30-
npx scc install lwc # LWC-focused development
28+
npx scc-universal install all # Everything (all agents, skills, rules)
29+
npx scc-universal install apex # Apex-focused development
30+
npx scc-universal install lwc # LWC-focused development
3131
```
3232

3333
### Profile Details
@@ -41,10 +41,10 @@ npx scc install lwc # LWC-focused development
4141
### Diagnostics
4242

4343
```bash
44-
npx scc doctor # Check for missing/drifted files
45-
npx scc status # View installed components
46-
npx scc repair # Restore drifted files
47-
npx scc uninstall # Remove SCC-managed files
44+
npx scc-universal doctor # Check for missing/drifted files
45+
npx scc-universal status # View installed components
46+
npx scc-universal repair # Restore drifted files
47+
npx scc-universal uninstall # Remove SCC-managed files
4848
```
4949

5050
## Hook Configuration
@@ -110,10 +110,10 @@ CLAUDE_PACKAGE_MANAGER=npm
110110

111111
| Problem | Cause | Fix |
112112
|---------|-------|-----|
113-
| `npx scc install` fails | Node.js < 20 | Upgrade: `nvm install 20` |
114-
| Hooks not firing | SCC not installed in project | Run `npx scc doctor` to check |
115-
| `Permission denied` on hooks | Script not executable | Run `npx scc repair` |
116-
| Skills not loading | Wrong install profile | Run `npx scc install all` |
113+
| `npx scc-universal install` fails | Node.js < 20 | Upgrade: `nvm install 20` |
114+
| Hooks not firing | SCC not installed in project | Run `npx scc-universal doctor` to check |
115+
| `Permission denied` on hooks | Script not executable | Run `npx scc-universal repair` |
116+
| Skills not loading | Wrong install profile | Run `npx scc-universal install all` |
117117
| `sf` command not found | SF CLI not installed | Install: `npm install -g @salesforce/cli` |
118118
| `sf` commands fail with errors | SF CLI version too old | Upgrade: `npm update -g @salesforce/cli` (SCC requires SF CLI v2.x / `sf` not `sfdx`) |
119119
| Hooks slow down session | Too many hooks enabled | Switch to `SCC_HOOK_PROFILE=minimal` |
@@ -122,19 +122,19 @@ CLAUDE_PACKAGE_MANAGER=npm
122122

123123
```bash
124124
# Full diagnostic report
125-
npx scc doctor
125+
npx scc-universal doctor
126126

127127
# See exactly what's installed
128-
npx scc list-installed
128+
npx scc-universal list-installed
129129

130130
# Preview what WOULD be installed (dry run)
131-
npx scc plan apex
131+
npx scc-universal plan apex
132132

133133
# Check state store
134-
npx scc status
134+
npx scc-universal status
135135

136136
# Reset everything and reinstall
137-
npx scc uninstall && npx scc install all
137+
npx scc-universal uninstall && npx scc-universal install all
138138
```
139139

140140
### Upgrading SCC
@@ -144,17 +144,17 @@ npx scc uninstall && npx scc install all
144144
npm install -g scc-universal@latest
145145

146146
# Repair any drifted files after upgrade
147-
npx scc repair
147+
npx scc-universal repair
148148

149149
# Verify upgrade
150-
npx scc doctor
150+
npx scc-universal doctor
151151
```
152152

153153
## Verification
154154

155155
```bash
156156
npm test # Run all validators
157-
npx scc doctor # Check installation health
157+
npx scc-universal doctor # Check installation health
158158
sf --version # Verify SF CLI is installed
159-
npx scc status # Confirm installed components
159+
npx scc-universal status # Confirm installed components
160160
```

‎.cursor/skills/mcp-server-patterns/SKILL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,7 @@ Use **Zod** (or the SDK's preferred schema format) for input validation.
7272

7373
### Official @salesforce/mcp Server
7474

75-
MCP config is auto-installed by `npx scc install` (`.mcp.json` for Claude Code, `.cursor/mcp.json` for Cursor). The official `@salesforce/mcp` server provides these toolsets:
75+
MCP config is auto-installed by `npx scc-universal install` (`.mcp.json` for Claude Code, `.cursor/mcp.json` for Cursor). The official `@salesforce/mcp` server provides these toolsets:
7676

7777
| Toolset | What It Does |
7878
|---------|-------------|

‎.cursor/skills/sf-harness-audit/SKILL.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ ls -la .claude/agents/ 2>/dev/null
2929
ls -la .claude/skills/ 2>/dev/null
3030
```
3131

32-
If using SCC CLI: `npx scc status`
32+
If using SCC CLI: `npx scc-universal status`
3333

3434
### Step 2 — Score Each Category
3535

@@ -110,7 +110,7 @@ SCC Harness Audit
110110
111111
Top Recommendations:
112112
1. [+1.0] Enable strict hook profile: export SCC_HOOK_PROFILE=strict
113-
2. [+0.5] Install all modules: npx scc install all
113+
2. [+0.5] Install all modules: npx scc-universal install all
114114
```
115115

116116
### Step 4 — Actionable Recommendations
@@ -119,11 +119,11 @@ For each gap, provide a specific command to fix it:
119119

120120
| Gap | Fix Command |
121121
|-----|-------------|
122-
| Missing hooks | `npx scc repair` |
123-
| Missing domain rules | `npx scc install all` (or target: `npx scc install apex`, `npx scc install lwc`) |
124-
| Low skill count | `npx scc install all` |
122+
| Missing hooks | `npx scc-universal repair` |
123+
| Missing domain rules | `npx scc-universal install all` (or target: `npx scc-universal install apex`, `npx scc-universal install lwc`) |
124+
| Low skill count | `npx scc-universal install all` |
125125
| Wrong hook profile | `export SCC_HOOK_PROFILE=strict` |
126-
| Drifted files | `npx scc doctor` then `npx scc repair` |
126+
| Drifted files | `npx scc-universal doctor` then `npx scc-universal repair` |
127127

128128
## Examples
129129

0 commit comments

Comments
 (0)