Skip to content

Commit 97f2e16

Browse files
jonathanpeterwujonathanpeterwu
committed
chore: prepare for v0.3.5 release - fix linting and package.json
1 parent 8747557 commit 97f2e16

139 files changed

Lines changed: 31662 additions & 3471 deletions

File tree

Some content is hidden

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

‎.claude/README.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# Claude Code Integration
2+
3+
This directory contains Claude Code configuration, hooks, and skills for the StackMemory project.
4+
5+
## Structure
6+
7+
```
8+
.claude/
9+
├── claude.json # Main configuration with hooks
10+
├── hooks/ # Hook scripts
11+
│ ├── skill-eval.sh # Shell wrapper for skill evaluation
12+
│ ├── skill-eval.cjs # Node.js skill evaluation engine
13+
│ └── skill-rules.json # Skill detection rules
14+
├── agents/ # Agent definitions
15+
│ ├── code-reviewer.md # Code review agent
16+
│ └── github-workflow.md # Git workflow agent
17+
└── skills/ # Skill definitions
18+
├── code-quality.md # Code quality checks
19+
├── pr-review.md # PR review skill
20+
└── pr-summary.md # PR summary generation
21+
```
22+
23+
## Features
24+
25+
### Hooks
26+
27+
1. **UserPromptSubmit**: Analyzes prompts and suggests relevant skills
28+
2. **PreToolUse**: Prevents editing on main branch
29+
3. **PostToolUse**:
30+
- Auto-formats TypeScript/JavaScript files
31+
- Auto-installs dependencies when package.json changes
32+
- Auto-runs tests when test files change
33+
- Type-checks TypeScript files
34+
35+
### Skills
36+
37+
The skill evaluation engine detects relevant skills based on:
38+
- Keywords in prompts
39+
- File paths mentioned
40+
- Directory mappings
41+
- Intent patterns
42+
- Code content patterns
43+
44+
#### Available Skills
45+
46+
- **frame-management**: Frame stack and context management
47+
- **linear-integration**: Linear API and task sync
48+
- **mcp-server**: Model Context Protocol implementation
49+
- **testing-patterns**: Jest testing infrastructure
50+
- **cli-commands**: CLI command implementation
51+
- **storage-tiers**: 3-tier storage system
52+
- **context-bridge**: Cross-session synchronization
53+
- **task-management**: Task tracking and persistence
54+
- **terminal-ui**: Terminal UI with Ink
55+
- **claude-integration**: Claude Code hooks and integration
56+
- **build-scripts**: Build and deployment scripts
57+
- **documentation**: Documentation and API reference
58+
- **github-actions**: CI/CD workflows
59+
- **code-quality**: Code review and quality checks
60+
- **performance-optimization**: Performance analysis
61+
62+
### Agents
63+
64+
- **code-reviewer**: Reviews code against StackMemory standards
65+
- **github-workflow**: Manages git operations and PRs
66+
67+
## Usage
68+
69+
The hooks and skills are automatically activated when using Claude Code in this project. The skill evaluation engine will analyze your prompts and suggest relevant skills to activate.
70+
71+
### Manual Testing
72+
73+
Test skill evaluation:
74+
```bash
75+
echo '{"prompt": "your test prompt"}' | node .claude/hooks/skill-eval.cjs
76+
```
77+
78+
### Configuration
79+
80+
Edit `skill-rules.json` to:
81+
- Add new skills
82+
- Modify detection patterns
83+
- Adjust confidence scoring
84+
- Update directory mappings
85+
86+
## StackMemory-Specific Patterns
87+
88+
Key patterns enforced by hooks and agents:
89+
90+
1. **ESM Imports**: Always add `.js` extension to relative imports
91+
2. **Context Bridge**: Use `skipContextBridge: true` for CLI operations
92+
3. **Error Handling**: Return `undefined` instead of throwing in getFrame()
93+
4. **Database Paths**: Use project-local `.stackmemory/` not global
94+
5. **Frame Digests**: Keep under 200 tokens
95+
6. **Linear Integration**: Reference tickets in commits (STA-XX)
96+
97+
## Maintenance
98+
99+
- Update `skill-rules.json` when adding new features
100+
- Keep agent definitions in sync with project standards
101+
- Test hooks after major changes

‎.claude/agents/code-reviewer.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
---
2+
name: code-reviewer
3+
description: MUST BE USED PROACTIVELY after writing or modifying any code. Reviews against project standards, TypeScript strict mode, and coding conventions. Checks for anti-patterns, security issues, and performance problems.
4+
model: opus
5+
---
6+
7+
Senior code reviewer ensuring high standards for the StackMemory codebase.
8+
9+
## Core Setup
10+
11+
**When invoked**: Run `git diff` to see recent changes, focus on modified files, begin review immediately.
12+
13+
**Feedback Format**: Organize by priority with specific line references and fix examples.
14+
- **Critical**: Must fix (security, breaking changes, logic errors)
15+
- **Warning**: Should fix (conventions, performance, duplication)
16+
- **Suggestion**: Consider improving (naming, optimization, docs)
17+
18+
## Review Checklist
19+
20+
### TypeScript & Code Style
21+
- **No `any`** - use `unknown` or proper types
22+
- **ESM imports** - ALWAYS add `.js` extension to relative imports
23+
- **Error handling** - Return undefined instead of throwing in getFrame()
24+
- **Null safety** - Filter nulls before use in arrays
25+
26+
### Frame Management Patterns
27+
- **Context Bridge** - Use `skipContextBridge: true` for CLI operations
28+
- **Frame lifecycle** - Always close frames properly
29+
- **Database paths** - Use project-local `.stackmemory/` not global `~/.stackmemory/`
30+
31+
### Testing Requirements
32+
- **Test coverage** - All new features need tests
33+
- **Mock patterns** - Use factories for test data
34+
- **Integration tests** - Test full workflows
35+
36+
### Performance Considerations
37+
- **Async operations** - Don't block with context bridge in sync contexts
38+
- **Token limits** - Keep frame digests under 200 tokens
39+
- **Database queries** - Use indexes and limit results
40+
41+
## StackMemory-Specific Patterns
42+
43+
```typescript
44+
// CORRECT - Skip context bridge for CLI
45+
const frameManager = new FrameManager(db, projectId, {
46+
skipContextBridge: true
47+
});
48+
49+
// CORRECT - ESM imports with .js
50+
import { FrameManager } from './frame-manager.js';
51+
52+
// CORRECT - Error handling
53+
getFrame(id: string): Frame | undefined {
54+
const frame = this.frames.get(id);
55+
if (!frame) {
56+
console.warn(`Frame ${id} not found`);
57+
return undefined;
58+
}
59+
return frame;
60+
}
61+
62+
// CORRECT - Filter nulls
63+
const validFrames = frames.filter((f): f is Frame => f !== null);
64+
```
65+
66+
## Integration Points
67+
68+
- **MCP Server**: Ensure tools follow protocol spec
69+
- **Linear Integration**: Check OAuth flow and error handling
70+
- **Railway Storage**: Validate tier migration logic
71+
- **Claude Hooks**: Test hook execution and error recovery

‎.claude/agents/github-workflow.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
---
2+
name: github-workflow
3+
description: Git workflow agent for commits, branches, and PRs. Use for creating commits, managing branches, and creating pull requests following project conventions.
4+
model: sonnet
5+
---
6+
7+
GitHub workflow assistant for StackMemory project.
8+
9+
## Branch Naming
10+
11+
Format: `{type}/{description}` or `{type}-{linear-id}/{description}`
12+
13+
Examples:
14+
- `feat/railway-storage`
15+
- `fix/context-bridge-hanging`
16+
- `sta-98/storage-tiers`
17+
- `refactor/frame-manager`
18+
19+
## Commit Messages
20+
21+
Use Conventional Commits format with Linear ticket references:
22+
23+
```
24+
<type>[optional scope]: <description> [optional ticket]
25+
26+
[optional body]
27+
```
28+
29+
### Types
30+
- `feat`: New feature
31+
- `fix`: Bug fix
32+
- `docs`: Documentation only
33+
- `refactor`: Code restructuring
34+
- `test`: Test additions/updates
35+
- `perf`: Performance improvements
36+
- `chore`: Maintenance tasks
37+
38+
### Examples
39+
```
40+
feat(storage): implement 3-tier Railway storage system (STA-98)
41+
fix(cli): resolve context commands hanging issue
42+
docs(api): add comprehensive MCP tool documentation
43+
refactor(frame): add skipContextBridge option for CLI ops
44+
test(integration): add Phase 3 integration test suite
45+
perf(context): optimize frame retrieval to <100ms
46+
```
47+
48+
## Creating a Commit
49+
50+
1. Check status and diff:
51+
```bash
52+
git status
53+
git diff --staged
54+
```
55+
56+
2. Stage changes selectively:
57+
```bash
58+
git add -p # Interactive staging
59+
```
60+
61+
3. Create commit with proper format:
62+
```bash
63+
git commit -m "type(scope): description (STA-XX)"
64+
```
65+
66+
## Creating a Pull Request
67+
68+
1. Push branch:
69+
```bash
70+
git push -u origin <branch-name>
71+
```
72+
73+
2. Create PR with comprehensive description:
74+
```bash
75+
gh pr create --title "type(scope): description (STA-XX)" --body "$(cat <<'EOF'
76+
## Summary
77+
- What changed and why
78+
- Linear ticket: STA-XX
79+
80+
## Changes
81+
- Specific file/module changes
82+
- New features/fixes implemented
83+
- Breaking changes (if any)
84+
85+
## Test Plan
86+
- [ ] Unit tests pass
87+
- [ ] Integration tests pass
88+
- [ ] Manual testing completed
89+
- [ ] Performance benchmarks run
90+
91+
## Performance Impact
92+
- Operations: ~XXXms
93+
- Memory: XXX KB
94+
95+
## Documentation
96+
- [ ] API docs updated
97+
- [ ] README updated if needed
98+
EOF
99+
)"
100+
```
101+
102+
## StackMemory-Specific Checks
103+
104+
Before creating PR:
105+
- [ ] ESM imports use `.js` extension
106+
- [ ] Context bridge handled properly in CLI
107+
- [ ] Frame lifecycle managed correctly
108+
- [ ] Tests added for new features
109+
- [ ] Linear ticket referenced
110+
- [ ] Performance measured
111+
- [ ] No TypeScript `any` types

‎.claude/claude.json‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
{
2+
"includeCoAuthoredBy": true,
3+
"env": {
4+
"INSIDE_CLAUDE_CODE": "1",
5+
"BASH_DEFAULT_TIMEOUT_MS": "420000",
6+
"BASH_MAX_TIMEOUT_MS": "420000"
7+
},
8+
"hooks": {
9+
"UserPromptSubmit": [
10+
{
11+
"hooks": [
12+
{
13+
"type": "command",
14+
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/skill-eval.sh",
15+
"timeout": 5
16+
}
17+
]
18+
}
19+
],
20+
"PreToolUse": [
21+
{
22+
"matcher": "Edit|MultiEdit|Write",
23+
"hooks": [
24+
{
25+
"type": "command",
26+
"command": "# Prevent editing on main branch\n[ \"$(git branch --show-current)\" != \"main\" ] || { echo '{\"block\": true, \"message\": \"Cannot edit files on main branch. Create a feature branch first.\"}' >&2; exit 2; }",
27+
"timeout": 5
28+
}
29+
]
30+
}
31+
],
32+
"PostToolUse": [
33+
{
34+
"matcher": "Edit|MultiEdit|Write",
35+
"hooks": [
36+
{
37+
"type": "command",
38+
"command": "# Auto-format JS/TS files with Prettier\nif [[ \"$CLAUDE_TOOL_INPUT_FILE_PATH\" =~ \\.(js|jsx|ts|tsx)$ ]]; then\n file_path=\"${CLAUDE_TOOL_INPUT_FILE_PATH}\"\n # Use prettier if available\n if command -v npx &>/dev/null && [ -f \"$CLAUDE_PROJECT_DIR/package.json\" ]; then\n cd \"$CLAUDE_PROJECT_DIR\" && npx prettier --write \"$file_path\" 2>&1\n exit_code=$?\n if [ $exit_code -ne 0 ]; then\n echo '{\"feedback\": \"Formatting failed. Check file for syntax errors.\"}' >&2\n exit 1\n else\n echo '{\"feedback\": \"Formatting applied.\", \"suppressOutput\": true}'\n fi\n fi\nfi",
39+
"timeout": 30
40+
}
41+
]
42+
},
43+
{
44+
"matcher": "Edit|MultiEdit|Write",
45+
"hooks": [
46+
{
47+
"type": "command",
48+
"command": "# Auto-install dependencies when package.json changes\nif [[ \"$CLAUDE_TOOL_INPUT_FILE_PATH\" =~ package\\.json$ ]]; then\n echo '{\"feedback\": \"Installing dependencies...\"}' >&2\n cd \"$CLAUDE_PROJECT_DIR\" && npm install >/dev/null 2>&1 && echo '{\"feedback\": \"Dependencies installed.\", \"suppressOutput\": true}' || {\n echo '{\"feedback\": \"Failed to install dependencies.\"}' >&2\n exit 1\n }\nfi",
49+
"timeout": 60
50+
}
51+
]
52+
},
53+
{
54+
"matcher": "Edit|MultiEdit|Write",
55+
"hooks": [
56+
{
57+
"type": "command",
58+
"command": "# Auto-run tests when test files change\nif [[ \"$CLAUDE_TOOL_INPUT_FILE_PATH\" =~ \\.test\\.(js|jsx|ts|tsx)$ ]]; then\n echo '{\"feedback\": \"Running tests...\"}' >&2\n cd \"$CLAUDE_PROJECT_DIR\" && npm test -- --findRelatedTests \"${CLAUDE_TOOL_INPUT_FILE_PATH}\" --passWithNoTests 2>&1 | tail -30\n exit_code=${PIPESTATUS[0]}\n if [ $exit_code -eq 0 ]; then\n echo '{\"feedback\": \"Tests passed.\"}'\n else\n echo '{\"feedback\": \"Tests failed. See output above.\"}' >&2\n fi\nfi",
59+
"timeout": 90
60+
}
61+
]
62+
},
63+
{
64+
"matcher": "Edit|MultiEdit|Write",
65+
"hooks": [
66+
{
67+
"type": "command",
68+
"command": "# Type-check TypeScript files\nif [[ \"$CLAUDE_TOOL_INPUT_FILE_PATH\" =~ \\.(ts|tsx)$ ]] && [ -f \"$CLAUDE_PROJECT_DIR/tsconfig.json\" ]; then\n echo '{\"feedback\": \"Checking TypeScript types...\"}' >&2\n cd \"$CLAUDE_PROJECT_DIR\" && output=$(npx tsc --noEmit 2>&1)\n exit_code=$?\n if [ $exit_code -eq 0 ]; then\n echo '{\"feedback\": \"No TypeScript errors.\", \"suppressOutput\": true}'\n else\n errors=$(echo \"$output\" | grep -A 2 \"error TS\" | head -30)\n if [ -n \"$errors\" ]; then\n echo '{\"feedback\": \"TypeScript found type errors:\"}' >&2\n echo \"$errors\" >&2\n fi\n fi\n # Non-blocking\n exit 0\nfi",
69+
"timeout": 30
70+
}
71+
]
72+
}
73+
]
74+
}
75+
}

0 commit comments

Comments
 (0)