@voodocs/cli 1.0.5 → 1.0.6

package/CHANGELOG.md

@@ -1,3 +1,41 @@
+## v1.0.6 (2024-12-21)
+
+### 🐛 Bug Fix: Missing Instructions Directory in npm Package
+
+**Problem:** The `voodocs instruct` command failed with "Error: Instructions directory not found" because the `lib/darkarts/instructions/` directory was not included in the npm package.
+
+**Root Cause:** The `instructions/` directory was not listed in the `files` array in `package.json`.
+
+**Fix:** Added `lib/darkarts/instructions/` to the `files` array in `package.json`.
+
+---
+
+### Changes
+
+- Added `lib/darkarts/instructions/` to package.json `files` array
+- Verified that all instruction templates are now included in the package:
+  - `claude.md`
+  - `cursor.md`
+  - `default.md`
+
+---
+
+### Testing
+
+| Test Case | Status |
+|-----------|--------|
+| Instructions directory included in package | ✅ Pass |
+| `voodocs instruct --list-templates` | ✅ Pass |
+| `voodocs instruct --ai cursor` | ✅ Pass |
+
+---
+
+### Upgrade
+
+```bash
+npm install -g @voodocs/cli@1.0.6
+```
+
 ## v1.0.5 (2024-12-21)
 
 ### 🐛 Bug Fix: Instruct Command Import Error

package/lib/cli/__init__.py

@@ -16,7 +16,7 @@ This module provides the command-line interface for VooDocs.
 import click
 from typing import Optional
 
-__version__ = "1.0.5"
+__version__ = "1.0.6"
 
 
 @click.group()

package/lib/darkarts/instructions/claude.md

@@ -0,0 +1,139 @@
+# Claude AI Instructions for Symbolic DarkArts Annotations
+
+**Version:** 2.0  
+**Date:** December 21, 2024
+
+---
+
+## 1. Primary Goal
+
+Your primary goal is to **write and maintain symbolic DarkArts annotations** for all new and existing code. This ensures that our documentation is always up-to-date, accurate, and machine-readable.
+
+---
+
+## 2. Annotation Format: Symbolic DarkArts
+
+**Always use the symbolic DarkArts format.** Do not use the natural language `@voodocs` format.
+
+### Correct Format
+
+```typescript
+/**@darkarts
+⊢{Module purpose}
+∂{Dependencies}
+⚠{Assumptions}
+*/
+
+/**@darkarts
+⊳{Preconditions}
+⊲{Postconditions}
+⊨{Invariants}
+⚡{Side effects / Complexity}
+🔒{Security implications}
+*/
+```
+
+### Incorrect Format (Do Not Use)
+
+```typescript
+/**@voodocs
+module_purpose: "..."
+dependencies: [...]
+*/
+```
+
+---
+
+## 3. Key Rules
+
+1.  **Annotate Everything:** All modules, functions, classes, and interfaces must have a DarkArts annotation block.
+2.  **Use Symbolic Format Only:** Strictly adhere to the symbolic format (`⊢`, `∂`, `⚠`, `⊳`, `⊲`, `⊨`, `⚡`, `🔒`).
+3.  **Use Logic Symbols:** Use mathematical symbols for logic (`∧`, `∨`, `¬`, `∈`, `∃`, `∀`, `⇒`, `⇔`).
+4.  **Be Precise and Concise:** Annotations should be accurate and to the point.
+5.  **Validate Your Work:** After making changes, run `voodocs validate . --recursive` to ensure all annotations are correct.
+
+---
+
+## 4. Symbol Quick Reference
+
+| Symbol | Meaning | Symbol | Meaning |
+|---|---|---|---|
+| `⊢` | Module Purpose | `∧` | And |
+| `∂` | Dependencies | `∨` | Or |
+| `⚠` | Assumptions | `¬` | Not |
+| `⊳` | Preconditions | `∈` | In |
+| `⊲` | Postconditions | `∉` | Not In |
+| `⊨` | Invariants | `∃` | Exists |
+| `⚡` | Side Effects / Complexity | `∀` | For All |
+| `🔒` | Security Implications | `⇒` | Implies |
+| `⇔` | If and Only If | `⊤` | True |
+| `⊥` | False | `∅` | Empty Set |
+| `⊆` | Subset | `∪` | Union |
+| `∩` | Intersection | | |
+
+---
+
+## 5. Workflow
+
+1.  **When writing new code:** Add symbolic DarkArts annotations as you go.
+2.  **When modifying existing code:** Update the corresponding annotations to reflect your changes.
+3.  **Before committing:** Run `voodocs validate . --recursive` to catch any errors.
+4.  **If validation fails:** Run `voodocs fix . --recursive` to automatically fix common issues.
+
+---
+
+## 6. Example: Adding a New Function
+
+If you add a new function `getUserById`, you must add a symbolic annotation block:
+
+```typescript
+/**@darkarts
+⊳{userId must be a valid UUID}
+⊲{
+  Returns a user object if found
+  Returns null if ¬∃ user with that ID
+}
+⊨{Does ¬ modify the database}
+⚡{O(1) lookup}
+*/
+export async function getUserById(userId: string): Promise<User | null> {
+  // ...
+}
+```
+
+---
+
+## 7. Example: Modifying a Module
+
+If you add a new dependency to a module, update the `∂` field:
+
+**Before:**
+```typescript
+/**@darkarts
+⊢{User authentication service}
+∂{jsonwebtoken}
+*/
+```
+
+**After (added bcrypt):**
+```typescript
+/**@darkarts
+⊢{User authentication service}
+∂{
+  jsonwebtoken: For JWT creation
+  bcrypt: For password hashing
+}
+*/
+```
+
+---
+
+## 8. Important Commands
+
+-   **Validate:** `voodocs validate . --recursive`
+-   **Fix:** `voodocs fix . --recursive`
+-   **Generate Docs:** `voodocs generate . ./docs --recursive`
+
+---
+
+By following these instructions, you will help us maintain a high-quality, machine-readable, and self-validating codebase. Thank you for your contribution!

package/lib/darkarts/instructions/cursor.md

@@ -0,0 +1,139 @@
+# Cursor AI Instructions for Symbolic DarkArts Annotations
+
+**Version:** 2.0  
+**Date:** December 21, 2024
+
+---
+
+## 1. Primary Goal
+
+Your primary goal is to **write and maintain symbolic DarkArts annotations** for all new and existing code. This ensures that our documentation is always up-to-date, accurate, and machine-readable.
+
+---
+
+## 2. Annotation Format: Symbolic DarkArts
+
+**Always use the symbolic DarkArts format.** Do not use the natural language `@voodocs` format.
+
+### Correct Format
+
+```typescript
+/**@darkarts
+⊢{Module purpose}
+∂{Dependencies}
+⚠{Assumptions}
+*/
+
+/**@darkarts
+⊳{Preconditions}
+⊲{Postconditions}
+⊨{Invariants}
+⚡{Side effects / Complexity}
+🔒{Security implications}
+*/
+```
+
+### Incorrect Format (Do Not Use)
+
+```typescript
+/**@voodocs
+module_purpose: "..."
+dependencies: [...]
+*/
+```
+
+---
+
+## 3. Key Rules
+
+1.  **Annotate Everything:** All modules, functions, classes, and interfaces must have a DarkArts annotation block.
+2.  **Use Symbolic Format Only:** Strictly adhere to the symbolic format (`⊢`, `∂`, `⚠`, `⊳`, `⊲`, `⊨`, `⚡`, `🔒`).
+3.  **Use Logic Symbols:** Use mathematical symbols for logic (`∧`, `∨`, `¬`, `∈`, `∃`, `∀`, `⇒`, `⇔`).
+4.  **Be Precise and Concise:** Annotations should be accurate and to the point.
+5.  **Validate Your Work:** After making changes, run `voodocs validate . --recursive` to ensure all annotations are correct.
+
+---
+
+## 4. Symbol Quick Reference
+
+| Symbol | Meaning | Symbol | Meaning |
+|---|---|---|---|
+| `⊢` | Module Purpose | `∧` | And |
+| `∂` | Dependencies | `∨` | Or |
+| `⚠` | Assumptions | `¬` | Not |
+| `⊳` | Preconditions | `∈` | In |
+| `⊲` | Postconditions | `∉` | Not In |
+| `⊨` | Invariants | `∃` | Exists |
+| `⚡` | Side Effects / Complexity | `∀` | For All |
+| `🔒` | Security Implications | `⇒` | Implies |
+| `⇔` | If and Only If | `⊤` | True |
+| `⊥` | False | `∅` | Empty Set |
+| `⊆` | Subset | `∪` | Union |
+| `∩` | Intersection | | |
+
+---
+
+## 5. Workflow
+
+1.  **When writing new code:** Add symbolic DarkArts annotations as you go.
+2.  **When modifying existing code:** Update the corresponding annotations to reflect your changes.
+3.  **Before committing:** Run `voodocs validate . --recursive` to catch any errors.
+4.  **If validation fails:** Run `voodocs fix . --recursive` to automatically fix common issues.
+
+---
+
+## 6. Example: Adding a New Function
+
+If you add a new function `getUserById`, you must add a symbolic annotation block:
+
+```typescript
+/**@darkarts
+⊳{userId must be a valid UUID}
+⊲{
+  Returns a user object if found
+  Returns null if ¬∃ user with that ID
+}
+⊨{Does ¬ modify the database}
+⚡{O(1) lookup}
+*/
+export async function getUserById(userId: string): Promise<User | null> {
+  // ...
+}
+```
+
+---
+
+## 7. Example: Modifying a Module
+
+If you add a new dependency to a module, update the `∂` field:
+
+**Before:**
+```typescript
+/**@darkarts
+⊢{User authentication service}
+∂{jsonwebtoken}
+*/
+```
+
+**After (added bcrypt):**
+```typescript
+/**@darkarts
+⊢{User authentication service}
+∂{
+  jsonwebtoken: For JWT creation
+  bcrypt: For password hashing
+}
+*/
+```
+
+---
+
+## 8. Important Commands
+
+-   **Validate:** `voodocs validate . --recursive`
+-   **Fix:** `voodocs fix . --recursive`
+-   **Generate Docs:** `voodocs generate . ./docs --recursive`
+
+---
+
+By following these instructions, you will help us maintain a high-quality, machine-readable, and self-validating codebase. Thank you for your contribution!

package/lib/darkarts/instructions/default.md

@@ -0,0 +1,139 @@
+# AI Instructions for Symbolic DarkArts Annotations
+
+**Version:** 2.0  
+**Date:** December 21, 2024
+
+---
+
+## 1. Primary Goal
+
+Your primary goal is to **write and maintain symbolic DarkArts annotations** for all new and existing code. This ensures that our documentation is always up-to-date, accurate, and machine-readable.
+
+---
+
+## 2. Annotation Format: Symbolic DarkArts
+
+**Always use the symbolic DarkArts format.** Do not use the natural language `@voodocs` format.
+
+### Correct Format
+
+```typescript
+/**@darkarts
+⊢{Module purpose}
+∂{Dependencies}
+⚠{Assumptions}
+*/
+
+/**@darkarts
+⊳{Preconditions}
+⊲{Postconditions}
+⊨{Invariants}
+⚡{Side effects / Complexity}
+🔒{Security implications}
+*/
+```
+
+### Incorrect Format (Do Not Use)
+
+```typescript
+/**@voodocs
+module_purpose: "..."
+dependencies: [...]
+*/
+```
+
+---
+
+## 3. Key Rules
+
+1.  **Annotate Everything:** All modules, functions, classes, and interfaces must have a DarkArts annotation block.
+2.  **Use Symbolic Format Only:** Strictly adhere to the symbolic format (`⊢`, `∂`, `⚠`, `⊳`, `⊲`, `⊨`, `⚡`, `🔒`).
+3.  **Use Logic Symbols:** Use mathematical symbols for logic (`∧`, `∨`, `¬`, `∈`, `∃`, `∀`, `⇒`, `⇔`).
+4.  **Be Precise and Concise:** Annotations should be accurate and to the point.
+5.  **Validate Your Work:** After making changes, run `voodocs validate . --recursive` to ensure all annotations are correct.
+
+---
+
+## 4. Symbol Quick Reference
+
+| Symbol | Meaning | Symbol | Meaning |
+|---|---|---|---|
+| `⊢` | Module Purpose | `∧` | And |
+| `∂` | Dependencies | `∨` | Or |
+| `⚠` | Assumptions | `¬` | Not |
+| `⊳` | Preconditions | `∈` | In |
+| `⊲` | Postconditions | `∉` | Not In |
+| `⊨` | Invariants | `∃` | Exists |
+| `⚡` | Side Effects / Complexity | `∀` | For All |
+| `🔒` | Security Implications | `⇒` | Implies |
+| `⇔` | If and Only If | `⊤` | True |
+| `⊥` | False | `∅` | Empty Set |
+| `⊆` | Subset | `∪` | Union |
+| `∩` | Intersection | | |
+
+---
+
+## 5. Workflow
+
+1.  **When writing new code:** Add symbolic DarkArts annotations as you go.
+2.  **When modifying existing code:** Update the corresponding annotations to reflect your changes.
+3.  **Before committing:** Run `voodocs validate . --recursive` to catch any errors.
+4.  **If validation fails:** Run `voodocs fix . --recursive` to automatically fix common issues.
+
+---
+
+## 6. Example: Adding a New Function
+
+If you add a new function `getUserById`, you must add a symbolic annotation block:
+
+```typescript
+/**@darkarts
+⊳{userId must be a valid UUID}
+⊲{
+  Returns a user object if found
+  Returns null if ¬∃ user with that ID
+}
+⊨{Does ¬ modify the database}
+⚡{O(1) lookup}
+*/
+export async function getUserById(userId: string): Promise<User | null> {
+  // ...
+}
+```
+
+---
+
+## 7. Example: Modifying a Module
+
+If you add a new dependency to a module, update the `∂` field:
+
+**Before:**
+```typescript
+/**@darkarts
+⊢{User authentication service}
+∂{jsonwebtoken}
+*/
+```
+
+**After (added bcrypt):**
+```typescript
+/**@darkarts
+⊢{User authentication service}
+∂{
+  jsonwebtoken: For JWT creation
+  bcrypt: For password hashing
+}
+*/
+```
+
+---
+
+## 8. Important Commands
+
+-   **Validate:** `voodocs validate . --recursive`
+-   **Fix:** `voodocs fix . --recursive`
+-   **Generate Docs:** `voodocs generate . ./docs --recursive`
+
+---
+
+By following these instructions, you will help us maintain a high-quality, machine-readable, and self-validating codebase. Thank you for your contribution!

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voodocs/cli",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "AI-Native Documentation System with Validation - The only documentation tool that validates your annotations and guarantees accuracy",
   "main": "voodocs_cli.py",
   "bin": {
@@ -58,6 +58,7 @@
     "lib/darkarts/context/",
     "lib/darkarts/core/",
     "lib/darkarts/validation/",
+    "lib/darkarts/instructions/",
     "lib/darkarts/exceptions.py",
     "lib/darkarts/telemetry.py",
     "lib/darkarts/parsers/typescript/dist/",