heraspec 0.1.13 → 0.1.15

package/dist/core/templates/skills/git-embed/skill.md

@@ -0,0 +1,57 @@
+# Skill: Git Embed
+
+## Purpose
+
+This skill establishes a nested Git repository structure (Monorepo) where the outer (parent) repository physically tracks and stores the source code of an inner (child) repository, without using the standard Git Submodule mechanism. This allows the child repository to retain its own `.git` directory for independent committing and pushing.
+
+## When to Use
+
+- When migrating an existing Git repository to be embedded within a parent Monorepo.
+- When the parent repository needs full direct physical access to the child's source files.
+- When you need to avoid "empty folder" issues caused by standard Git submodules during cloning.
+- When you want to commit and push independently from both the parent root and the child root.
+
+## Step-by-Step Process
+
+### Step 1: Remove Submodule References (If Any)
+- Ensure the inner repository is not tracked as a submodule.
+- Run `git rm -r --cached <child-folder>` from the parent root.
+- Remove `.gitmodules` if it exists: `rm .gitmodules` and `git add .gitmodules` (if tracked).
+
+### Step 2: Temporary `.git` Relocation
+- Move the inner repository's `.git` directory out of the way to prevent Git from treating it as an embedded repo.
+- Run `mv <child-folder>/.git /tmp/<child-name>_git_bak`.
+
+### Step 3: Embed Source Code into Parent
+- Add the inner folder directly to the parent repository.
+- Run `git add <child-folder>/`.
+- Commit the changes: `git commit -m "Embed full source of <child-name> independent of submodule"`.
+
+### Step 4: Restore Independent `.git`
+- Move the inner repository's `.git` directory back to its original location.
+- Run `mv /tmp/<child-name>_git_bak <child-folder>/.git`.
+
+### Step 5: Verification
+- Run `git status` in the parent directory to ensure no submodule links are shown.
+- Navigate into `<child-folder>` and run `git status` to verify the independent repository tracking is intact.
+
+## Required Input
+
+- **Child folder path**: The relative path to the nested repository.
+- **Child name**: A short identifier used for the backup directory.
+
+## Expected Output
+
+- The parent's remote repository will contain all physical files natively without gitlinks.
+- The child folder will retain its `.git` folder for completely independent repository operations.
+
+## Tone & Rules
+
+### Git Rules
+- The child folder's `.gitignore` MUST be preserved, as the parent git will natively respect `.gitignore` rules in subdirectories.
+- Ensure all uncommitted changes in the parent repo are stashed or committed before starting.
+
+### Limitations
+- ❌ DO NOT use `git submodule add` under any circumstances for this skill.
+- ❌ DO NOT delete the inner `.git` folder permanently.
+- ❌ DO NOT use `git subtree` as it creates a different tracking model.

package/dist/core/templates/skills/git-embed-skill.md

@@ -0,0 +1,57 @@
+# Skill: Git Embed
+
+## Purpose
+
+This skill establishes a nested Git repository structure (Monorepo) where the outer (parent) repository physically tracks and stores the source code of an inner (child) repository, without using the standard Git Submodule mechanism. This allows the child repository to retain its own `.git` directory for independent committing and pushing.
+
+## When to Use
+
+- When migrating an existing Git repository to be embedded within a parent Monorepo.
+- When the parent repository needs full direct physical access to the child's source files.
+- When you need to avoid "empty folder" issues caused by standard Git submodules during cloning.
+- When you want to commit and push independently from both the parent root and the child root.
+
+## Step-by-Step Process
+
+### Step 1: Remove Submodule References (If Any)
+- Ensure the inner repository is not tracked as a submodule.
+- Run `git rm -r --cached <child-folder>` from the parent root.
+- Remove `.gitmodules` if it exists: `rm .gitmodules` and `git add .gitmodules` (if tracked).
+
+### Step 2: Temporary `.git` Relocation
+- Move the inner repository's `.git` directory out of the way to prevent Git from treating it as an embedded repo.
+- Run `mv <child-folder>/.git /tmp/<child-name>_git_bak`.
+
+### Step 3: Embed Source Code into Parent
+- Add the inner folder directly to the parent repository.
+- Run `git add <child-folder>/`.
+- Commit the changes: `git commit -m "Embed full source of <child-name> independent of submodule"`.
+
+### Step 4: Restore Independent `.git`
+- Move the inner repository's `.git` directory back to its original location.
+- Run `mv /tmp/<child-name>_git_bak <child-folder>/.git`.
+
+### Step 5: Verification
+- Run `git status` in the parent directory to ensure no submodule links are shown.
+- Navigate into `<child-folder>` and run `git status` to verify the independent repository tracking is intact.
+
+## Required Input
+
+- **Child folder path**: The relative path to the nested repository.
+- **Child name**: A short identifier used for the backup directory.
+
+## Expected Output
+
+- The parent's remote repository will contain all physical files natively without gitlinks.
+- The child folder will retain its `.git` folder for completely independent repository operations.
+
+## Tone & Rules
+
+### Git Rules
+- The child folder's `.gitignore` MUST be preserved, as the parent git will natively respect `.gitignore` rules in subdirectories.
+- Ensure all uncommitted changes in the parent repo are stashed or committed before starting.
+
+### Limitations
+- ❌ DO NOT use `git submodule add` under any circumstances for this skill.
+- ❌ DO NOT delete the inner `.git` folder permanently.
+- ❌ DO NOT use `git subtree` as it creates a different tracking model.

package/dist/core/templates/skills/integration-test/skill.md

@@ -0,0 +1,118 @@
+# Skill: Integration Testing (Cross-Cutting)
+
+## Purpose
+
+This skill is used to create integration tests that verify how different components work together. Integration tests check interactions between modules, services, databases, and external APIs.
+
+## When to Use
+
+- When testing component interactions
+- When testing API endpoints
+- When testing database operations
+- When testing service integrations
+- When verifying data flow between components
+- When testing with real dependencies (not mocks)
+
+## Step-by-Step Process
+
+### Step 1: Identify Integration Points
+- Map component dependencies
+- Identify external services and APIs
+- List database operations
+- Determine integration boundaries
+- Identify critical integration paths
+
+### Step 2: Set Up Test Environment
+- Configure test database
+- Set up test services/mocks for external APIs
+- Configure test environment variables
+- Prepare test data fixtures
+- Set up cleanup procedures
+
+### Step 3: Write Integration Tests
+- Create test files for integration scenarios
+- Test component interactions
+- Test API endpoints with real requests
+- Test database operations
+- Test error handling across components
+- Use test fixtures for consistent data
+
+### Step 4: Run and Verify
+- Run integration tests
+- Verify test isolation (tests don't affect each other)
+- Check test execution time
+- Ensure proper cleanup after tests
+- Verify tests pass consistently
+
+### Step 5: Maintain Tests
+- Update tests when interfaces change
+- Keep test data synchronized
+- Document test scenarios
+- Monitor test execution time
+
+## Required Input
+
+- **Components**: List of components to integrate
+- **APIs**: API endpoints to test
+- **Database schema**: Database structure for testing
+- **External services**: External services to mock or use
+- **Test data**: Sample data for testing
+
+## Expected Output
+
+- Integration test files
+- Test scenarios covering integration paths
+- Test fixtures and setup code
+- Passing integration test suite
+- Documentation of integration test scenarios
+
+## Tone & Rules
+
+### Test Scope
+- Test real interactions between components
+- Use real databases (test database)
+- Mock external services that can't be controlled
+- Test error propagation across boundaries
+
+### Test Data
+- Use consistent test fixtures
+- Clean up test data after tests
+- Use transactions for database tests when possible
+- Isolate tests to prevent interference
+
+### Performance
+- Integration tests are slower than unit tests
+- Run integration tests separately from unit tests
+- Use test database (not production)
+- Consider test execution time
+
+### Limitations
+- ❌ DO NOT use production database
+- ❌ DO NOT test with real external APIs in CI (use mocks)
+- ❌ DO NOT write tests that depend on test execution order
+- ❌ DO NOT skip cleanup (tests must be isolated)
+- ❌ DO NOT test implementation details
+
+## Available Templates
+
+- `templates/integration-test-template.js` - JavaScript integration test template
+- `templates/integration-test-template.php` - PHP integration test template
+- `templates/integration-test-template.py` - Python integration test template
+
+## Available Scripts
+
+- `scripts/setup-test-db.sh` - Set up test database
+- `scripts/seed-test-data.sh` - Seed test data
+
+## Examples
+
+See `examples/` directory for reference:
+- `good-integration-test/` - Well-structured integration tests
+- `bad-integration-test/` - Examples to avoid
+
+## Links to Other Skills
+
+- **unit-test**: Use unit tests before integration tests
+- **e2e-test**: Use for end-to-end user scenarios
+- **documents**: Use to document integration test strategy
+

package/dist/core/templates/skills/integration-test-skill.md

@@ -1,118 +1,118 @@
-# Skill: Integration Testing (Cross-Cutting)
-
-## Purpose
-
-This skill is used to create integration tests that verify how different components work together. Integration tests check interactions between modules, services, databases, and external APIs.
-
-## When to Use
-
-- When testing component interactions
-- When testing API endpoints
-- When testing database operations
-- When testing service integrations
-- When verifying data flow between components
-- When testing with real dependencies (not mocks)
-
-## Step-by-Step Process
-
-### Step 1: Identify Integration Points
-- Map component dependencies
-- Identify external services and APIs
-- List database operations
-- Determine integration boundaries
-- Identify critical integration paths
-
-### Step 2: Set Up Test Environment
-- Configure test database
-- Set up test services/mocks for external APIs
-- Configure test environment variables
-- Prepare test data fixtures
-- Set up cleanup procedures
-
-### Step 3: Write Integration Tests
-- Create test files for integration scenarios
-- Test component interactions
-- Test API endpoints with real requests
-- Test database operations
-- Test error handling across components
-- Use test fixtures for consistent data
-
-### Step 4: Run and Verify
-- Run integration tests
-- Verify test isolation (tests don't affect each other)
-- Check test execution time
-- Ensure proper cleanup after tests
-- Verify tests pass consistently
-
-### Step 5: Maintain Tests
-- Update tests when interfaces change
-- Keep test data synchronized
-- Document test scenarios
-- Monitor test execution time
-
-## Required Input
-
-- **Components**: List of components to integrate
-- **APIs**: API endpoints to test
-- **Database schema**: Database structure for testing
-- **External services**: External services to mock or use
-- **Test data**: Sample data for testing
-
-## Expected Output
-
-- Integration test files
-- Test scenarios covering integration paths
-- Test fixtures and setup code
-- Passing integration test suite
-- Documentation of integration test scenarios
-
-## Tone & Rules
-
-### Test Scope
-- Test real interactions between components
-- Use real databases (test database)
-- Mock external services that can't be controlled
-- Test error propagation across boundaries
-
-### Test Data
-- Use consistent test fixtures
-- Clean up test data after tests
-- Use transactions for database tests when possible
-- Isolate tests to prevent interference
-
-### Performance
-- Integration tests are slower than unit tests
-- Run integration tests separately from unit tests
-- Use test database (not production)
-- Consider test execution time
-
-### Limitations
-- ❌ DO NOT use production database
-- ❌ DO NOT test with real external APIs in CI (use mocks)
-- ❌ DO NOT write tests that depend on test execution order
-- ❌ DO NOT skip cleanup (tests must be isolated)
-- ❌ DO NOT test implementation details
-
-## Available Templates
-
-- `templates/integration-test-template.js` - JavaScript integration test template
-- `templates/integration-test-template.php` - PHP integration test template
-- `templates/integration-test-template.py` - Python integration test template
-
-## Available Scripts
-
-- `scripts/setup-test-db.sh` - Set up test database
-- `scripts/seed-test-data.sh` - Seed test data
-
-## Examples
-
-See `examples/` directory for reference:
-- `good-integration-test/` - Well-structured integration tests
-- `bad-integration-test/` - Examples to avoid
-
-## Links to Other Skills
-
-- **unit-test**: Use unit tests before integration tests
-- **e2e-test**: Use for end-to-end user scenarios
-- **documents**: Use to document integration test strategy
-
+# Skill: Integration Testing (Cross-Cutting)
+
+## Purpose
+
+This skill is used to create integration tests that verify how different components work together. Integration tests check interactions between modules, services, databases, and external APIs.
+
+## When to Use
+
+- When testing component interactions
+- When testing API endpoints
+- When testing database operations
+- When testing service integrations
+- When verifying data flow between components
+- When testing with real dependencies (not mocks)
+
+## Step-by-Step Process
+
+### Step 1: Identify Integration Points
+- Map component dependencies
+- Identify external services and APIs
+- List database operations
+- Determine integration boundaries
+- Identify critical integration paths
+
+### Step 2: Set Up Test Environment
+- Configure test database
+- Set up test services/mocks for external APIs
+- Configure test environment variables
+- Prepare test data fixtures
+- Set up cleanup procedures
+
+### Step 3: Write Integration Tests
+- Create test files for integration scenarios
+- Test component interactions
+- Test API endpoints with real requests
+- Test database operations
+- Test error handling across components
+- Use test fixtures for consistent data
+
+### Step 4: Run and Verify
+- Run integration tests
+- Verify test isolation (tests don't affect each other)
+- Check test execution time
+- Ensure proper cleanup after tests
+- Verify tests pass consistently
+
+### Step 5: Maintain Tests
+- Update tests when interfaces change
+- Keep test data synchronized
+- Document test scenarios
+- Monitor test execution time
+
+## Required Input
+
+- **Components**: List of components to integrate
+- **APIs**: API endpoints to test
+- **Database schema**: Database structure for testing
+- **External services**: External services to mock or use
+- **Test data**: Sample data for testing
+
+## Expected Output
+
+- Integration test files
+- Test scenarios covering integration paths
+- Test fixtures and setup code
+- Passing integration test suite
+- Documentation of integration test scenarios
+
+## Tone & Rules
+
+### Test Scope
+- Test real interactions between components
+- Use real databases (test database)
+- Mock external services that can't be controlled
+- Test error propagation across boundaries
+
+### Test Data
+- Use consistent test fixtures
+- Clean up test data after tests
+- Use transactions for database tests when possible
+- Isolate tests to prevent interference
+
+### Performance
+- Integration tests are slower than unit tests
+- Run integration tests separately from unit tests
+- Use test database (not production)
+- Consider test execution time
+
+### Limitations
+- ❌ DO NOT use production database
+- ❌ DO NOT test with real external APIs in CI (use mocks)
+- ❌ DO NOT write tests that depend on test execution order
+- ❌ DO NOT skip cleanup (tests must be isolated)
+- ❌ DO NOT test implementation details
+
+## Available Templates
+
+- `templates/integration-test-template.js` - JavaScript integration test template
+- `templates/integration-test-template.php` - PHP integration test template
+- `templates/integration-test-template.py` - Python integration test template
+
+## Available Scripts
+
+- `scripts/setup-test-db.sh` - Set up test database
+- `scripts/seed-test-data.sh` - Seed test data
+
+## Examples
+
+See `examples/` directory for reference:
+- `good-integration-test/` - Well-structured integration tests
+- `bad-integration-test/` - Examples to avoid
+
+## Links to Other Skills
+
+- **unit-test**: Use unit tests before integration tests
+- **e2e-test**: Use for end-to-end user scenarios
+- **documents**: Use to document integration test strategy
+

package/dist/core/templates/skills/knowledge/README.md

@@ -0,0 +1,63 @@
+# HeRaSpec Knowledge Base
+
+Pre-analyzed profiles for frameworks, APIs, and platforms. When a skill (like `sourcecode-analyzer`) is invoked, it checks this knowledge base first to avoid redundant analysis.
+
+## Structure
+
+```
+knowledge/
+├── index.json              ← Registry of all built-in entries
+├── frameworks/             ← CMS/Framework architecture profiles
+│   └── <runtime>/<framework>/<cms>/
+│       ├── profile.json    ← Metadata, match signals, key features
+│       └── structure.md    ← Pre-analyzed architecture report
+├── apis/                   ← Third-party API profiles (Shopify, QuickBooks, ...)
+│   └── <provider>/
+│       ├── profile.json
+│       └── <analysis-files>
+├── platforms/              ← Platform/infra knowledge (AWS, Vercel, ...)
+│   └── <platform>/
+│       ├── profile.json
+│       └── <analysis-files>
+└── custom/                 ← User's custom knowledge (NEVER touched by CLI)
+    ├── index.json          ← Custom registry
+    └── ...                 ← User-managed entries
+```
+
+## Categories
+
+| Category | Purpose | Example |
+|----------|---------|---------|
+| `frameworks` | CMS/Framework architecture profiles | Laravel/Botble, WordPress, Perfex CRM |
+| `apis` | Third-party API specifications | Shopify API, QuickBooks API |
+| `platforms` | Deployment/infrastructure knowledge | AWS, Vercel, Docker patterns |
+
+## How Matching Works
+
+Each entry in `index.json` has `matchSignals` — conditions checked against the current project:
+
+| Signal Type | Description | Example |
+|-------------|-------------|---------|
+| `file-contains` | File exists AND contains string | `composer.json` contains `"botble"` |
+| `directory-exists` | Directory exists in project | `platform/core` exists |
+
+Each matched signal = +1 score. If `score >= minMatchScore`, the knowledge is considered a match.
+
+## How Skills Use Knowledge
+
+1. Skill reads `heraspec/knowledge/index.json`
+2. Matches project against entries using signals
+3. If matched: loads pre-analyzed report as baseline, focuses on project-specific delta
+4. If no match: performs full analysis from scratch
+
+## Custom Knowledge
+
+Users can add project-specific knowledge in `heraspec/knowledge/custom/`:
+
+1. Create entry directory under `custom/`
+2. Add to `custom/index.json`
+3. The CLI will **never** modify or delete anything in `custom/`
+
+## Updating Knowledge
+
+Run `heraspec init` to update built-in knowledge to the latest version. Custom entries are preserved.