@voodocs/cli 0.1.0

package/LICENSE

@@ -0,0 +1,37 @@
+VooDocs Commercial License
+
+Copyright (c) 2025 3vilEnterprises
+
+All rights reserved.
+
+This software and associated documentation files (the "Software") are proprietary
+and confidential to 3vilEnterprises.
+
+NOTICE: This Software is licensed, not sold. By installing, copying, or otherwise
+using the Software, you agree to be bound by the terms of this license.
+
+GRANT OF LICENSE: Subject to the terms and conditions of this license and payment
+of applicable fees, 3vilEnterprises grants you a limited, non-exclusive,
+non-transferable license to use the Software.
+
+RESTRICTIONS: You may not:
+- Modify, adapt, translate, reverse engineer, decompile, or disassemble the Software
+- Remove or alter any proprietary notices or labels on the Software
+- Distribute, sublicense, lease, rent, loan, or otherwise transfer the Software
+- Use the Software for any unlawful purpose
+
+TERMINATION: This license is effective until terminated. Your rights under this
+license will terminate automatically without notice if you fail to comply with
+any term of this license.
+
+DISCLAIMER: THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+
+LIMITATION OF LIABILITY: IN NO EVENT SHALL 3VILENTERPRISES BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
+OR OTHER DEALINGS IN THE SOFTWARE.
+
+For licensing inquiries, please contact: contact@3vil.enterprises
+For more information, visit: https://voodocs.com

package/README.md

@@ -0,0 +1,153 @@
+# VooDocs - AI-Native Documentation System
+
+[![NPM Version](https://img.shields.io/npm/v/@voodocs/cli.svg)](https://www.npmjs.com/package/@voodocs/cli)
+[![License](https://img.shields.io/npm/l/@voodocs/cli.svg)](https://voodocs.com/terms)
+[![Support](https://img.shields.io/badge/support-priority-blue.svg)](https://voodocs.com/support)
+
+**VooDocs** is a revolutionary AI-native documentation system that transforms how software is documented, tested, and specified. It teaches AI coding assistants (like Cursor and Claude Code) to write precise, machine-readable specifications in `@voodocs` annotations using the **DarkArtsAI language** - the mathematical and logical notation that AI naturally understands. These annotations are then automatically translated into human-readable documentation, automated tests, and API specifications.
+
+This is the future of software development: **AI documents your code in its native language, VooDocs translates it for humans.**
+
+## How It Works
+
+1.  **Install**: Add VooDocs to your project with `npm install -g @voodocs/cli`
+2.  **Instruct**: Run `voodocs instruct` to generate AI instructions for your coding assistant
+3.  **Code**: Your AI assistant (Cursor, Claude Code, etc.) automatically adds `@voodocs` annotations as it writes code
+4.  **Generate**: Run `voodocs generate` to produce:
+    - **Markdown Documentation**: Beautiful, human-readable docs
+    - **Automated Tests**: Comprehensive test suites (pytest, unittest, Jest)
+    - **API Specifications**: OpenAPI 3.0 and GraphQL schemas
+
+## Quick Start
+
+### 1. Installation
+
+Install the CLI globally using `npm` or `pnpm`:
+
+```bash
+npm install -g @voodocs/cli
+```
+
+### 2. Initialize Your Project
+
+Navigate to your project directory and initialize VooDocs:
+
+```bash
+voodocs init
+```
+
+This will prompt you for your API key and set up the configuration.
+
+### 3. Generate AI Instructions
+
+Create instructions for your AI coding assistant:
+
+```bash
+voodocs instruct
+```
+
+This creates a `VOODOCS_INSTRUCTIONS.md` file. Provide this to your AI assistant (add to `.cursorrules`, Claude project instructions, etc.).
+
+### 4. Let AI Document Your Code
+
+As you code with your AI assistant, it will automatically add `@voodocs` annotations:
+
+```typescript
+/**@voodocs
+module_purpose: "User authentication service with JWT token generation"
+dependencies: [
+    "bcrypt: Password hashing",
+    "jsonwebtoken: JWT token generation"
+]
+assumptions: [
+    "Database connection is established",
+    "User model exists with email and password fields"
+]
+security_model: "Passwords hashed with bcrypt, tokens expire in 24h"
+*/
+```
+
+### 5. Generate Documentation
+
+Run the generate command to create documentation, tests, and API specs:
+
+```bash
+# Generate everything
+voodocs generate ./src
+
+# Generate only documentation
+voodocs generate ./src --docs-only
+
+# Generate only tests
+voodocs generate ./src --tests-only
+```
+
+## Core Commands
+
+- `voodocs init`: Configure your API key and activate your license
+- `voodocs instruct`: Generate instructions for your AI assistant
+- `voodocs generate <path>`: Generate docs, tests, and API specs from annotations
+- `voodocs status`: Check your current license status and usage
+- `voodocs upgrade`: Get information on upgrading your plan
+
+## The DarkArts Language
+
+Voodocs uses the **DarkArts language** - a mathematical and logical notation system that represents how AI naturally thinks about code. Instead of forcing AI to write verbose human documentation, Voodocs lets AI express concepts precisely using:
+
+- **Mathematical notation**: ∀, ∃, ∈, ⇒, ⇔
+- **Formal logic**: Preconditions, postconditions, invariants
+- **Declarative relationships**: What IS, not what to DO
+- **Conditional reasoning**: Case-based specifications
+
+VooDocs then translates this precise, machine-readable format into natural language documentation that humans can easily understand.
+
+## Why Voodocs?
+
+- **AI-First Workflow**: Designed for modern AI-assisted development. Your AI documents as it codes.
+- **Single Source of Truth**: Code annotations drive docs, tests, and specs - always in sync.
+- **Massive Time Savings**: Eliminate manual documentation work entirely.
+- **Higher Code Quality**: Formal specifications lead to more robust and reliable code.
+- **Precision**: Mathematical notation is unambiguous - no more vague documentation.
+
+## Example Annotation
+
+```typescript
+/**@voodocs
+preconditions: [
+    "user must be authenticated",
+    "user must have 'admin' role",
+    "Database connection must be active"
+]
+postconditions: [
+    "returns true ⇔ user is admin ∧ MFA enabled",
+    "returns false ⇔ user lacks admin role ∨ MFA disabled ∨ any error",
+    "∀ errors: function returns false (fail-safe behavior)"
+]
+security_implications: [
+    "CRITICAL: Gates all admin functionality",
+    "Fail-safe design: errors → deny access"
+]
+complexity: "O(1) - Single database query with indexed lookup"
+*/
+export async function isAdmin(userId: string): Promise<boolean> {
+  // implementation
+}
+```
+
+## Licensing
+
+Voodocs is a commercial product. A valid API key is required to use the software. We offer:
+
+- **Free Tier**: For hobbyists and students
+- **Pro Plan**: For professional developers
+- **Enterprise**: For teams and organizations
+
+For more details, see our [Pricing Page](https://voodocs.com/pricing).
+
+## Support
+
+Need help? Visit our [Support Center](https://voodocs.com/support) or email us at [support@voodocs.com](mailto:support@voodocs.com).
+
+---
+
+**DarkArt Intelligence** 🚀

package/USAGE.md

@@ -0,0 +1,314 @@
+# VooDocs Usage Guide
+
+**Version**: v0.1.0
+
+This guide provides a comprehensive overview of VooDocs, its commands, and best practices for using it in your projects.
+
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [CLI Commands](#cli-commands)
+  - [init](#init)
+  - [instruct](#instruct)
+  - [generate](#generate)
+  - [status](#status)
+  - [watch](#watch)
+  - [validate](#validate)
+  - [check](#check)
+  - [export](#export)
+- [Configuration](#configuration)
+- [Writing Annotations](#writing-annotations)
+  - [Annotation Syntax](#annotation-syntax)
+  - [Annotation Fields](#annotation-fields)
+  - [DarkArts Language](#darkarts-language)
+- [Examples](#examples)
+  - [Python Example](#python-example)
+  - [TypeScript Example](#typescript-example)
+- [CI/CD Integration](#cicd-integration)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Installation
+
+Install the VooDocs CLI globally using `npm` or `pnpm`:
+
+```bash
+npm install -g @voodocs/cli
+```
+
+This will make the `voodocs` command available in your terminal.
+
+---
+
+## Quick Start
+
+1.  **Initialize VooDocs** in your project:
+    ```bash
+    voodocs init
+    ```
+    This will create a `.voodocs/config.json` file.
+
+2.  **Generate AI Instructions** for your coding assistant:
+    ```bash
+    voodocs instruct
+    ```
+    This creates a `VOODOCS_INSTRUCTIONS.md` file. Provide this to your AI assistant (e.g., add to `.cursorrules`).
+
+3.  **Start Coding** with `@voodocs` annotations. Your AI assistant will help you write them.
+
+4.  **Generate Documentation**:
+    ```bash
+    voodocs generate src/
+    ```
+    This will generate docs, tests, and API specs in the `voodocs-output/` directory.
+
+---
+
+## CLI Commands
+
+### `init`
+
+Initialize VooDocs in a project. Creates a `.voodocs/config.json` file.
+
+**Usage**:
+```bash
+voodocs init [--project-name <name>] [--language <lang>]
+```
+
+**Arguments**:
+- `--project-name`: The name of the project (defaults to current directory name).
+- `--language`: The primary language of the project (`python`, `typescript`, `javascript`).
+
+If arguments are not provided, `init` will run in interactive mode.
+
+### `instruct`
+
+Generate AI assistant instructions.
+
+**Usage**:
+```bash
+voodocs instruct [--assistant <name>] [--output <file>]
+```
+
+**Arguments**:
+- `--assistant`: The AI assistant to generate instructions for (`cursor`, `claude`, `copilot`, `windsurf`, `generic`).
+- `--output`: The output file path (defaults to `.cursorrules`, `.claude/instructions.md`, etc.).
+
+### `generate`
+
+Generate docs, tests, and API specs from annotations.
+
+**Usage**:
+```bash
+voodocs generate <path> [--output <dir>] [--docs-only] [--tests-only] [--api-only] [--verbose]
+```
+
+**Arguments**:
+- `<path>`: The path to the source code to process.
+- `--output`: The output directory (defaults to `./voodocs-output`).
+- `--docs-only`: Generate only documentation.
+- `--tests-only`: Generate only tests.
+- `--api-only`: Generate only API specs.
+- `--verbose`: Show detailed output.
+
+### `status`
+
+Show project status and statistics.
+
+**Usage**:
+```bash
+voodocs status [<path>]
+```
+
+**Output**:
+- Annotation coverage percentage
+- Quality score (0-100)
+- Breakdown of annotated vs. unannotated functions/classes
+
+### `watch`
+
+Watch files and automatically regenerate documentation on changes.
+
+**Usage**:
+```bash
+voodocs watch <path> [--interval <seconds>]
+```
+
+**Arguments**:
+- `<path>`: The path to watch for changes.
+- `--interval`: The watch interval in seconds (defaults to 2).
+
+### `validate`
+
+Validate annotation quality and correctness.
+
+**Usage**:
+```bash
+voodocs validate <path> [--strict] [--format <fmt>]
+```
+
+**Arguments**:
+- `<path>`: The path to validate.
+- `--strict`: Treat warnings as errors.
+- `--format`: Output format (`text` or `json`).
+
+### `check`
+
+Check annotation coverage and quality (for CI/CD).
+
+**Usage**:
+```bash
+voodocs check <path> [--min-coverage <pct>] [--min-quality <pct>]
+```
+
+**Arguments**:
+- `<path>`: The path to check.
+- `--min-coverage`: The minimum required annotation coverage (0-100).
+- `--min-quality`: The minimum required quality score (0-100).
+
+Exits with code 1 if checks fail.
+
+### `export`
+
+Export documentation to different formats.
+
+**Usage**:
+```bash
+voodocs export <file> --format <fmt> [--output <file>]
+```
+
+**Arguments**:
+- `<file>`: The Markdown documentation file to export.
+- `--format`: The export format (`html` or `pdf`).
+- `--output`: The output file path.
+
+---
+
+## Configuration
+
+VooDocs is configured via the `.voodocs/config.json` file. The following options are available:
+
+```json
+{
+  "project_name": "my-project",
+  "language": "python",
+  "version": "0.1.0",
+  "output_dir": "./voodocs-output",
+  "test_framework": "pytest",
+  "api_format": "openapi",
+  "exclude_patterns": [
+    "**/test_*.py",
+    "**/node_modules/**"
+  ],
+  "include_patterns": [],
+  "annotation_coverage_threshold": 50
+}
+```
+
+---
+
+## Writing Annotations
+
+### Annotation Syntax
+
+**Python**:
+```python
+def my_function(x):
+    """
+    @voodocs
+    preconditions: ["x > 0"]
+    postconditions: ["result > 0"]
+    """
+    return x + 1
+```
+
+**TypeScript/JavaScript**:
+```typescript
+/**
+ * @voodocs
+ * preconditions: ["x > 0"]
+ * postconditions: ["result > 0"]
+ */
+function myFunction(x: number): number {
+  return x + 1;
+}
+```
+
+### Annotation Fields
+
+| Field | Description |
+|---|---|
+| `module_purpose` | High-level purpose of the module. |
+| `dependencies` | Key dependencies of the module. |
+| `assumptions` | Assumptions made by the module. |
+| `preconditions` | Conditions that must be true before a function is called. |
+| `postconditions` | Conditions that must be true after a function returns. |
+| `invariants` | Conditions that must always be true for a class. |
+| `complexity` | Time and space complexity of an algorithm. |
+| `error_cases` | How the function behaves in error scenarios. |
+| `security_model` | Security implications and threat model. |
+| `thread_safety` | Thread safety guarantees. |
+| `state_transitions` | How the state of a class changes. |
+| `examples` | Example usage of the function. |
+
+### DarkArts Language
+
+The DarkArts language is a formal notation used in annotations. It includes:
+
+- **Logical Operators**: `∧` (and), `∨` (or), `¬` (not), `⇒` (implies), `⇔` (if and only if)
+- **Quantifiers**: `∀` (for all), `∃` (there exists)
+- **Set Theory**: `∈` (in), `∉` (not in), `⊂` (subset), `∪` (union), `∩` (intersection)
+- **Mathematical Symbols**: `ℝ` (reals), `ℤ` (integers), `ℕ` (naturals), `∞` (infinity)
+
+---
+
+## Examples
+
+See the `examples/` directory for complete examples in Python and TypeScript.
+
+---
+
+## CI/CD Integration
+
+Use the `voodocs check` command in your CI/CD pipeline to enforce documentation standards.
+
+**GitHub Actions Example**:
+```yaml
+name: VooDocs Check
+
+on: [push, pull_request]
+
+jobs:
+  voodocs-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 16
+      - run: npm install -g @voodocs/cli
+      - run: voodocs check . --min-coverage 80 --min-quality 70
+```
+
+---
+
+## Troubleshooting
+
+**Problem**: `voodocs: command not found`
+**Solution**: Make sure you have installed the CLI globally (`npm install -g @voodocs/cli`) and that your `npm` global bin directory is in your `PATH`.
+
+**Problem**: TypeScript parser not working.
+**Solution**: The TypeScript parser is built automatically on `postinstall`. If it fails, you can build it manually:
+```bash
+# Navigate to the VooDocs installation directory
+cd $(npm root -g)/@voodocs/cli
+
+# Build the parser
+npm run build-ts-parser
+```
+
+For more help, visit our [support page](https://voodocs.com/support).