@magic-ingredients/tiny-brain-local 0.10.2 → 0.12.2

package/dist/utils/package-version.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Package Version Utility
+ *
+ * Provides access to the current package version from package.json
+ */
+/**
+ * Get the current package version from package.json
+ * @returns Semantic version string (e.g., "0.11.0")
+ */
+export declare function getPackageVersion(): string;
+//# sourceMappingURL=package-version.d.ts.map

package/dist/utils/package-version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-version.d.ts","sourceRoot":"","sources":["../../src/utils/package-version.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAa1C"}

package/dist/utils/package-version.js

@@ -0,0 +1,26 @@
+/**
+ * Package Version Utility
+ *
+ * Provides access to the current package version from package.json
+ */
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+/**
+ * Get the current package version from package.json
+ * @returns Semantic version string (e.g., "0.11.0")
+ */
+export function getPackageVersion() {
+    const __filename = fileURLToPath(import.meta.url);
+    const __dirname = dirname(__filename);
+    // Navigate from dist/utils/ to package root
+    const packagePath = join(__dirname, '..', '..', 'package.json');
+    try {
+        const packageJson = JSON.parse(readFileSync(packagePath, 'utf-8'));
+        return packageJson.version;
+    }
+    catch (error) {
+        throw new Error(`Failed to read package version: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}
+//# sourceMappingURL=package-version.js.map

package/dist/utils/package-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-version.js","sourceRoot":"","sources":["../../src/utils/package-version.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AAEpC;;;GAGG;AACH,MAAM,UAAU,iBAAiB;IAC/B,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAClD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAEtC,4CAA4C;IAC5C,MAAM,WAAW,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC;IAEhE,IAAI,CAAC;QACH,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC;QACnE,OAAO,WAAW,CAAC,OAAO,CAAC;IAC7B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,mCAAmC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,EAAE,CAAC,CAAC;IACjH,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magic-ingredients/tiny-brain-local",
-  "version": "0.10.2",
+  "version": "0.12.2",
   "description": "Local MCP server implementation for Tiny Brain AI assistant",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,7 +17,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "templates"
   ],
   "scripts": {
     "build": "tsc",
@@ -40,7 +41,7 @@
     "dxt:init": "cd dxt && dxt init"
   },
   "dependencies": {
-    "@magic-ingredients/tiny-brain-core": "^0.10.2",
+    "@magic-ingredients/tiny-brain-core": "^0.12.2",
     "@magic-ingredients/tiny-brain-dashboard": "file:../tiny-brain-dashboard",
     "@modelcontextprotocol/sdk": "^1.0.6",
     "chalk": "^5.3.0",

package/templates/adr/0001-record-architecture-decisions.md

@@ -0,0 +1,223 @@
+---
+adr_number: 1
+title: "Record Architecture Decisions"
+date: 2025-01-15
+status: accepted
+supersedes: null
+superseded_by: null
+tags: [documentation, process, governance]
+decision_makers: [Architecture Team]
+---
+
+# ADR-0001: Record Architecture Decisions
+
+## Status
+
+**accepted** (Date: 2025-01-15)
+
+## Context
+
+As our system grows in complexity, we need a way to capture important architectural decisions along with their context and consequences. Currently, decisions are scattered across:
+- Slack conversations that are difficult to search
+- Meeting notes in various formats
+- Tribal knowledge in team members' heads
+- Code comments that lack context
+
+This creates several problems:
+- New team members struggle to understand why systems are designed the way they are
+- Decisions get revisited repeatedly because rationale is lost
+- Context behind trade-offs is not preserved
+- Impact of changing decisions is unclear
+
+### Background
+
+The Architecture Decision Record (ADR) approach, popularized by Michael Nygard in 2011, provides a lightweight way to document architectural decisions. ADRs are:
+- Short documents (1-2 pages)
+- Stored in version control with the code
+- Immutable once accepted (new decisions supersede old ones)
+- Focused on significant decisions that affect structure, non-functional properties, dependencies, interfaces, or construction techniques
+
+### Constraints
+
+- Must integrate with existing development workflow
+- Should not add significant overhead to decision-making process
+- Needs to be searchable and maintainable
+- Must work well with version control
+- Should be accessible to both technical and non-technical stakeholders
+
+## Decision
+
+We will use Architecture Decision Records (ADRs) to capture significant architectural decisions. Specifically:
+
+- **Format**: Markdown files with YAML frontmatter
+- **Location**: `docs/adr/` directory in the main repository
+- **Naming**: Sequential numbering with kebab-case titles (e.g., `0001-record-architecture-decisions.md`)
+- **Template**: Standardized template covering context, decision, consequences, and alternatives
+- **Lifecycle**: Proposed → Accepted → (Deprecated or Superseded)
+- **Automation**: Claude Code integration for automatic ADR generation
+
+### Implementation Details
+
+1. Create `docs/adr/` directory structure
+2. Establish ADR template and README documentation
+3. Configure Claude Code with ADR creation instructions
+4. Begin documenting all significant new decisions
+5. Gradually backfill critical historical decisions
+
+## Consequences
+
+### Positive Consequences
+
+- **Knowledge preservation**: Decisions and rationale are permanently recorded
+- **Onboarding efficiency**: New team members can quickly understand system evolution
+- **Decision quality**: Forcing documentation encourages thorough consideration of alternatives
+- **Searchability**: Text files in git are easily searchable
+- **Historical context**: Clear record of when and why decisions were made
+- **Reduced decision revisiting**: Clear documentation reduces redundant discussions
+- **AI-friendly**: Claude Code can automatically create and reference ADRs
+
+### Negative Consequences
+
+- **Initial overhead**: Creating first ADRs and establishing process takes time
+- **Discipline required**: Team must commit to writing ADRs for significant decisions
+- **Maintenance burden**: ADRs need periodic review and updates
+- **Process learning curve**: Team needs to learn when and how to write ADRs
+- **Risk of over-documentation**: May be tempted to document trivial decisions
+
+### Neutral Consequences
+
+- **Cultural shift**: Changes team behavior around decision-making
+- **Review process**: ADRs should be reviewed like code changes
+- **Template evolution**: Template and process will likely evolve over time
+- **Tooling needs**: May eventually want better tooling for ADR visualization
+
+## Alternatives Considered
+
+### Alternative 1: Wiki Documentation
+
+**Description:** Use Confluence or similar wiki to document architectural decisions
+
+**Pros:**
+- Rich formatting options
+- Easy to link between documents
+- Built-in search functionality
+- Familiar to most teams
+
+**Cons:**
+- Separate from code repository
+- Not version controlled with code changes
+- Can become outdated easily
+- Requires additional tool/license
+- Less structured format
+
+**Rejection Reason:** ADRs in git are closer to the code, version controlled together, and don't require additional tools. The structured format encourages better decision documentation.
+
+---
+
+### Alternative 2: Code Comments Only
+
+**Description:** Document architectural decisions in code comments or README files
+
+**Pros:**
+- No separate documentation to maintain
+- Close to implementation
+- No new process needed
+- Developers already write comments
+
+**Cons:**
+- Lacks structure and searchability
+- Gets lost in code noise
+- Not suitable for cross-cutting decisions
+- Difficult to find historical context
+- No clear lifecycle management
+
+**Rejection Reason:** Code comments are good for implementation details but poor for capturing architectural rationale, alternatives considered, and consequences. A separate, structured approach is needed.
+
+---
+
+### Alternative 3: Design Documents in Google Docs
+
+**Description:** Write detailed design documents for each major decision
+
+**Pros:**
+- Rich formatting and diagrams
+- Real-time collaboration
+- Comment threads for discussions
+- Familiar tool for most teams
+
+**Cons:**
+- Not version controlled with code
+- Becomes outdated quickly
+- Access control complexity
+- Not searchable from codebase
+- Too heavyweight for many decisions
+- Separate from development workflow
+
+**Rejection Reason:** While design docs are valuable for complex features, ADRs provide a lighter-weight, version-controlled approach for capturing decisions. They complement, rather than replace, design docs.
+
+---
+
+## Validation
+
+### Tests Performed
+
+- Reviewed ADR examples from multiple successful open-source projects
+- Prototyped ADR structure with markdown + YAML frontmatter
+- Tested integration with Claude Code for automatic generation
+- Verified searchability in GitHub and local development
+
+### Metrics Collected
+
+- Time to create ADR from template: ~15-30 minutes for detailed decisions
+- Time for Claude Code to generate ADR: ~2-3 minutes
+- Markdown file size: Typically 2-5KB per ADR
+- Readability score: High (markdown renders well on GitHub)
+
+### Success Criteria
+
+- [x] Template is clear and comprehensive
+- [x] Process integrates with git workflow
+- [x] Documents are easily searchable
+- [x] Format is both human and AI-friendly
+- [x] Can be automatically generated by Claude Code
+- [x] Minimal overhead for decision-makers
+
+## References
+
+- [Original ADR article by Michael Nygard](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)
+- [ADR GitHub Organization](https://adr.github.io/)
+- [Markdown Guide](https://www.markdownguide.org/)
+- [YAML Frontmatter Specification](https://jekyllrb.com/docs/front-matter/)
+- [GitHub's Markdown Rendering](https://docs.github.com/en/get-started/writing-on-github)
+
+## Notes
+
+### Future Considerations
+
+- May want to build visualization tools to show ADR relationships
+- Consider adding ADR linting to CI/CD pipeline
+- Could generate ADR index/table of contents automatically
+- Might want to track ADR metrics (count by status, age, etc.)
+
+### Open Questions
+
+- Should we require ADRs for all decisions or only significant ones? (Answer: Only significant)
+- How often should we review ADRs? (Recommendation: Quarterly)
+- Who approves ADRs? (Answer: Architecture team or tech leads)
+
+### Follow-up Items
+
+- [ ] Train team on ADR process (completed: 2025-01-15)
+- [ ] Document 5-10 historical architectural decisions
+- [ ] Add ADR checklist to project onboarding
+- [ ] Schedule quarterly ADR review sessions
+
+---
+
+**Related ADRs:**
+
+This is the foundational ADR. Future ADRs will reference this one as the basis for the documentation practice.
+
+---
+
+*This ADR serves as both documentation of our ADR process and a template/example for future ADRs.*

package/templates/adr/ADR_CREATION_INSTRUCTIONS.md

@@ -0,0 +1,234 @@
+# ADR Creation Instructions for Claude Code
+
+## When to Create an ADR
+
+Create an ADR automatically when you make decisions about:
+- Architecture patterns (microservices, event-driven, etc.)
+- Technology selection (databases, frameworks, libraries)
+- Infrastructure choices (cloud providers, IaC tools, CI/CD)
+- Security approaches (authentication, authorization)
+- Testing strategies (unit, integration, e2e frameworks)
+- API design (REST vs GraphQL, versioning)
+- Data storage/modeling decisions
+- Deployment strategies
+- Development workflows
+
+## ADR Creation Process
+
+### Step 1: Determine ADR Number
+```bash
+# List existing ADRs and get the highest number
+ls docs/adr/*.md | grep -E '[0-9]{4}' | sort | tail -1
+# Increment by 1 for new ADR number
+```
+
+### Step 2: Gather Information from Context
+
+Extract from conversation:
+- **Decision**: What was decided
+- **Context**: Why we're making this decision
+- **Constraints**: Technical, time, budget, team limitations
+- **Alternatives**: All options discussed (including rejected ones)
+- **Pros/Cons**: Benefits and drawbacks of each option
+- **Validation**: Any tests, prototypes, or benchmarks mentioned
+- **References**: Code, docs, or external resources mentioned
+
+### Step 3: Fill Out Template
+
+Use `docs/adr/adr-template.md` and populate:
+
+**YAML Frontmatter:**
+```yaml
+adr_number: [next sequential number]
+title: "[concise, descriptive title]"
+date: [YYYY-MM-DD - today's date]
+status: proposed  # or accepted if explicitly approved
+supersedes: null  # only if replacing an old ADR
+superseded_by: null
+tags: [relevant, technology, tags]
+decision_makers: [names if mentioned in conversation]
+```
+
+**Content Sections:**
+
+1. **Status**: Use current date and status from frontmatter
+
+2. **Context**:
+   - Summarize the problem/need
+   - List constraints discovered
+   - Include background from conversation
+
+3. **Decision**:
+   - State clearly what was chosen
+   - Include implementation approach
+   - Be specific and actionable
+
+4. **Consequences**:
+   - Positive: All benefits mentioned
+   - Negative: All trade-offs/limitations discussed
+   - Neutral: Workflow changes, dependencies, future work
+
+5. **Alternatives Considered**:
+   - List ALL options discussed (minimum 2-3)
+   - Include pros/cons for each
+   - State specific rejection reasons
+
+6. **Validation**:
+   - List any prototypes built
+   - Include benchmark results
+   - Note success criteria met
+   - Reference test code if created
+
+7. **References**:
+   - Link to relevant code files
+   - Link to documentation
+   - Link to external resources mentioned
+   - Link to related ADRs
+
+8. **Notes**:
+   - Future considerations discussed
+   - Open questions
+   - Follow-up items
+
+### Step 4: File Naming
+
+Format: `NNNN-decision-title-in-kebab-case.md`
+
+Example conversions:
+- "Use PostgreSQL" → `0042-use-postgresql-for-data-storage.md`
+- "Migrate to Kubernetes" → `0043-migrate-to-kubernetes-from-docker-swarm.md`
+- "Implement Event Sourcing" → `0044-implement-event-sourcing-pattern.md`
+
+### Step 5: Save and Confirm
+
+1. Save to `docs/adr/NNNN-title.md`
+2. Tell user: "I've created ADR-NNNN: [title] and saved it to docs/adr/"
+3. Offer to make adjustments if needed
+
+## Quality Checklist
+
+Before finalizing an ADR, verify:
+
+- [ ] All YAML frontmatter fields are filled
+- [ ] Status is appropriate (proposed vs accepted)
+- [ ] Context explains WHY this decision is needed
+- [ ] Decision is clear and specific
+- [ ] At least 2-3 alternatives are documented
+- [ ] Each alternative has pros, cons, and rejection reason
+- [ ] All three consequence types are considered
+- [ ] Validation section has concrete data (not generic)
+- [ ] References are actual links (not placeholders)
+- [ ] No TODO or FIXME comments remain
+- [ ] Markdown formatting is correct
+- [ ] File name matches convention
+- [ ] ADR number is sequential
+
+## Example Workflows
+
+### Workflow 1: Database Selection
+```
+User: "Should we use PostgreSQL or MongoDB?"
+[Discussion of requirements, trade-offs]
+User: "Let's go with PostgreSQL"
+
+Claude:
+1. Recognize this as a database selection decision
+2. Extract all discussed points
+3. Create ADR-NNNN with:
+   - Context: Data requirements, team skills
+   - Decision: PostgreSQL chosen
+   - Alternatives: MongoDB (rejected), MySQL (not discussed but include)
+   - Validation: Any performance tests mentioned
+4. Save and confirm
+```
+
+### Workflow 2: Framework Migration
+```
+User: "We need to migrate from Vue to React"
+[Discussion of reasons, timeline, risks]
+
+Claude:
+1. Recognize this as a framework decision + migration
+2. Note this might supersede an old ADR
+3. Create ADR-NNNN with:
+   - Context: Why migration is needed
+   - Decision: Migrate to React
+   - Alternatives: Stay with Vue, try Svelte
+   - Consequences: Migration cost, team training, etc.
+4. Check if previous Vue ADR exists
+5. Update old ADR status if found
+6. Save and confirm
+```
+
+### Workflow 3: New Architecture Pattern
+```
+User: "Let's implement event sourcing for audit logs"
+
+Claude:
+1. Recognize this as an architecture pattern decision
+2. Create ADR-NNNN with:
+   - Context: Audit requirements, compliance needs
+   - Decision: Implement event sourcing
+   - Alternatives: Traditional logging, database triggers
+   - Implementation: High-level approach
+3. Include in Validation: Need to build proof of concept
+4. Save and confirm
+```
+
+## Common Pitfalls to Avoid
+
+❌ **Don't**: Leave sections empty or with "TODO"
+✅ **Do**: Fill all sections or write "N/A - [reason]"
+
+❌ **Don't**: Write vague decisions like "Use a database"
+✅ **Do**: Be specific "Use PostgreSQL 15+ for transactional data storage"
+
+❌ **Don't**: Only list the chosen alternative
+✅ **Do**: Document all options discussed, even if briefly
+
+❌ **Don't**: Generic consequences like "Better performance"
+✅ **Do**: Specific consequences "Reduces query time by 40% based on benchmark"
+
+❌ **Don't**: Forget to update old ADRs when superseding
+✅ **Do**: Update both old and new ADRs with cross-references
+
+❌ **Don't**: Use present tense ("We are deciding...")
+✅ **Do**: Use past/declarative tense ("We decided..." or "We will use...")
+
+## Template Shortcuts
+
+For common decision types, use these patterns:
+
+### Technology Selection
+```
+Context: Need for [capability], evaluated based on [criteria]
+Decision: Selected [technology] for [use case]
+Alternatives: [Tech A] (rejected: reason), [Tech B] (rejected: reason)
+Validation: [Prototype/benchmark results]
+```
+
+### Migration Decision
+```
+Context: Current [old tech] limitations: [list]
+Decision: Migrate from [old] to [new] over [timeframe]
+Alternatives: Stay with current (rejected: why), [other option]
+Consequences: Migration cost [X], training [Y], benefits [Z]
+```
+
+### Architecture Pattern
+```
+Context: System requirements: [list], current problems: [list]
+Decision: Implement [pattern] for [components]
+Alternatives: [Pattern A] (rejected: why), continue current (rejected: why)
+Validation: Proof of concept in [location]
+```
+
+## Final Notes
+
+- **Trust the conversation**: All the information needed is usually in the discussion
+- **Be comprehensive**: Better to over-document than under-document
+- **Stay objective**: Present facts, not opinions
+- **Be helpful**: Offer to create ADR even if not explicitly requested
+- **Update history**: Keep track of superseded ADRs
+
+When in doubt, ask the user: "Would you like me to create an ADR to document this decision?"