@miller-tech/uap 1.0.0

package/package.json

@@ -0,0 +1,113 @@
+{
+  "name": "@miller-tech/uap",
+  "version": "1.0.0",
+  "description": "Autonomous AI agent memory system with CLAUDE.md protocol enforcement",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "uap": "./dist/bin/cli.js",
+    "uap-tool-calls": "./dist/bin/tool-calls.js",
+    "uap-tool-call-test": "./tools/agents/scripts/tool_call_test.py",
+    "uap-tool-call-wrapper": "./tools/agents/scripts/tool_call_wrapper.py",
+    "uap-template-verify": "./tools/agents/scripts/chat_template_verifier.py",
+    "llama-optimize": "./dist/bin/llama-server-optimize.js",
+    "generate-lora-data": "./tools/agents/scripts/generate_lora_training_data.py",
+    "uap-policy": "./dist/bin/policy.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/bin/cli.js",
+    "test": "vitest",
+    "test:coverage": "vitest --coverage",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "format": "prettier --write src/**/*.ts",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run build && npm test",
+    "install:web": "bash scripts/install-web.sh",
+    "install:desktop": "bash scripts/install-desktop.sh",
+    "install:all": "bash scripts/install.sh",
+    "install:cloakbrowser": "tsx scripts/install-cloakbrowser.ts",
+    "postinstall": "echo '\n✨ Run: npx universal-agent-protocol init --interactive'",
+    "update-uap": "bash scripts/update-uap-compliance.sh",
+    "verify-uap": "bash scripts/verify-compliance.sh",
+    "check-claude": "bash scripts/verify-compliance.sh"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "factory-ai",
+    "opencode",
+    "forgecode",
+    "vscode",
+    "ai-agent",
+    "context",
+    "memory",
+    "worktree",
+    "cli"
+  ],
+  "author": "Miller Tech",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DammianMiller/universal-agent-protocol.git"
+  },
+  "homepage": "https://github.com/DammianMiller/universal-agent-protocol#readme",
+  "bugs": {
+    "url": "https://github.com/DammianMiller/universal-agent-protocol/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@octokit/rest": "^20.0.2",
+    "@qdrant/js-client-rest": "^1.11.0",
+    "better-sqlite3": "^11.0.0",
+    "chalk": "^5.3.0",
+    "cloakbrowser": "^0.3.16",
+    "commander": "^12.1.0",
+    "dexie": "^4.0.8",
+    "execa": "^9.6.1",
+    "glob": "^10.3.10",
+    "handlebars": "^4.7.8",
+    "inquirer": "^9.2.12",
+    "js-yaml": "^4.1.0",
+    "ora": "^8.0.1",
+    "playwright-core": "^1.58.2",
+    "simple-git": "^3.22.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.8",
+    "@types/chalk": "^2.2.4",
+    "@types/inquirer": "^9.0.7",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^20.11.0",
+    "@typescript-eslint/eslint-plugin": "^6.19.0",
+    "@typescript-eslint/parser": "^6.19.0",
+    "@vitest/coverage-v8": "^1.6.1",
+    "eslint": "^8.56.0",
+    "fake-indexeddb": "^6.0.0",
+    "prettier": "^3.2.4",
+    "tsx": "^4.21.0",
+    "typescript": "^5.3.3",
+    "vitest": "^1.2.0"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "benchmark-results",
+    "templates",
+    "tools/agents",
+    "scripts/install-cloakbrowser.ts",
+    "scripts/convert-policy-to-claude.ts",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/scripts/README.md

@@ -0,0 +1,161 @@
+# Setup Scripts
+
+This directory contains automated setup and installation scripts for UAP.
+
+## Scripts
+
+### `setup.sh` - Complete Setup
+
+```bash
+npm run setup
+```
+
+Performs a comprehensive setup including:
+
+- ✅ Dependency checking (Node.js, npm, git, npx)
+- ✅ Optional dependency recommendations (Docker, Python, pre-commit)
+- ✅ npm install (if node_modules missing)
+- ✅ TypeScript build
+- ✅ Git hooks configuration:
+  - `pre-commit` - Secrets detection, linting
+  - `commit-msg` - Conventional commits validation
+  - `pre-push` - Test execution before push
+- ✅ GitHub PR template (if gh CLI available)
+
+### `install-web.sh` - Web Platform Setup
+
+```bash
+npm run install:web
+```
+
+Installs UAP for web platform usage (claude.ai, Factory.AI):
+
+- Installs CLI globally or from GitHub
+- Initializes web platform configuration
+- Sets up for web-based AI assistants
+
+### `install-desktop.sh` - Desktop Setup
+
+```bash
+npm run install:desktop
+```
+
+Installs UAP for desktop usage:
+
+- Installs CLI globally or from GitHub
+- Detects Docker for local Qdrant
+- Initializes desktop platform configuration
+- Provides setup guidance
+
+## Usage
+
+### Quick Setup
+
+```bash
+# Install UAP globally
+npm install -g universal-agent-protocol
+
+# Run comprehensive setup
+npm run setup
+
+# Initialize in your project
+uap init
+```
+
+### Platform-Specific Setup
+
+```bash
+# For web platforms (claude.ai, Factory.AI)
+npm run install:web
+
+# For desktop (Claude Code, opencode)
+npm run install:desktop
+```
+
+## Git Hooks
+
+The `setup.sh` script configures three git hooks:
+
+### Pre-commit Hook
+
+- **Purpose**: Prevent secrets from being committed
+- **Checks**:
+  - Scans for API keys, passwords, tokens in code
+  - Runs linter with zero warnings allowed
+- **Bypass**: `git commit --no-verify`
+
+### Commit-msg Hook
+
+- **Purpose**: Enforce conventional commits format
+- **Validates**: `type(scope): description` format
+- **Types**: feat, fix, docs, style, refactor, test, chore, perf, ci, build, revert
+- **Bypass**: Confirm with 'y' when prompted
+
+### Pre-push Hook
+
+- **Purpose**: Ensure tests pass before pushing
+- **Runs**: `npm test`
+- **Bypass**: None (tests must pass)
+
+## Troubleshooting
+
+### Hooks not executing
+
+```bash
+# Make hooks executable
+chmod +x .git/hooks/*
+
+# Verify hooks exist
+ls -la .git/hooks/ | grep -v sample
+```
+
+### Setup script fails
+
+```bash
+# Check Node.js version
+node --version  # Should be >= 18.0.0
+
+# Check npm
+npm --version
+
+# Clear and reinstall
+rm -rf node_modules package-lock.json
+npm install
+```
+
+### Manual hook installation
+
+If automatic setup fails, manually create hooks:
+
+```bash
+# Pre-commit
+cat > .git/hooks/pre-commit << 'EOF'
+#!/bin/bash
+npm run lint -- --max-warnings=0
+exit $?
+EOF
+chmod +x .git/hooks/pre-commit
+
+# Commit-msg
+cat > .git/hooks/commit-msg << 'EOF'
+#!/bin/bash
+# Conventional commits validation
+exit 0
+EOF
+chmod +x .git/hooks/commit-msg
+```
+
+## Best Practices
+
+1. **Always run `npm run setup`** after cloning or updating UAP
+2. **Review generated hooks** before committing
+3. **Keep hooks in sync** with project requirements
+4. **Document custom hooks** in project README
+5. **Test hooks** with `git commit --no-verify` first
+
+## Security Notes
+
+- Git hooks run locally and cannot access remote repositories
+- Pre-commit hook only scans TypeScript/JavaScript/JSON files
+- Secrets detection is best-effort (not exhaustive)
+- Always use environment variables for sensitive data

package/templates/CLAUDE.template.md

@@ -0,0 +1,10 @@
+<!-- CLAUDE.md v2.3.0 - 34 Model Outcome Success Optimizations + Hooks Enforcement -->
+<!-- Optimizations #22-27: Template Compression, Structured Iteration, Inline Domain Knowledge, Early Impossibility Exit, Conditional Context, Remove Emphasis Theater -->
+<!-- Optimizations #28-34: Mandatory Verifier Loop, Decoder-First Gate, Context Stripping, Environment Check, Schema Diff, State Protection, Conditional Domain -->
+
+<!-- ENFORCEMENT_CHECKS: SESSION_START,DECISION_LOOP,MANDATORY_WORKTREE,PARALLEL_REVIEW,SCHEMA_DIFF,GATES,RTK_INCLUDES,PATTERN_ROUTER,VALIDATE_PLAN -->
+<!-- TEMPLATE_VERSION: 2.3.0 -->
+<!-- LAST_VALIDATED: 2026-03-09 -->
+
+@hooks-session-start.md
+@PreCompact.md

package/templates/CLAUDE_ARCHITECTURE.template.md

@@ -0,0 +1,103 @@
+# Architecture Guide Template
+
+**Version**: {{VERSION}}
+**Branch**: {{DEFAULT_BRANCH}}
+**Last Updated**: {{STRUCTURE_DATE}}
+
+---
+
+## Cluster Topology
+
+{{#if HAS_MULTI_CLUSTER}}
+This project operates multiple dedicated clusters - **one concern per cluster**.
+
+| Cluster | Context | Purpose | Services |
+|---------|---------|---------|----------|
+{{#each CLUSTERS}}
+| **{{name}}** | `{{context}}` | {{purpose}} | {{services}} |
+{{/each}}
+{{else}}
+Single cluster deployment.
+
+### Cluster Commands
+
+```bash
+kubectl config use-context {{MAIN_CLUSTER_CONTEXT}}
+```
+{{/if}}
+
+---
+
+## Cross-Cluster Communication Rules
+
+{{#if HAS_MULTI_CLUSTER}}
+**CRITICAL**: Always use public HTTPS URLs for cross-cluster communication.
+
+### Do's and Don'ts
+
+| ✅ DO | ❌ DON'T |
+|-------|----------|
+| Use public HTTPS URLs | Use cluster-internal DNS across clusters |
+| Use service accounts for auth | Use internal IPs for cross-cluster |
+
+### Whitelisted URLs
+{{#each WHITELISTED_URLS}}
+- `{{this}}`
+{{/each}}
+{{/if}}
+
+---
+
+## Technology Stack
+
+| Layer | Technology | Version |
+|-------|------------|---------|
+{{#each TECH_STACK}}
+| **{{layer}}** | {{technology}} | {{version}} |
+{{/each}}
+
+---
+
+## High Availability
+
+| Component | Configuration |
+|-----------|---------------|
+{{#each HA_CONFIG}}
+| **{{component}}** | {{configuration}} |
+{{/each}}
+
+---
+
+## Infrastructure as Code Policy
+
+### Two-Phase Infrastructure Workflow
+
+```
+PHASE 1: LOCAL PROOF (ALLOWED - NO SECRETS)
+  - Read-only operations
+  - terraform plan (via pipeline for secrets)
+
+PHASE 2: IaC PARITY (MANDATORY - VIA PIPELINE)
+  - Translate manual changes to Terraform/K8s YAML
+  - Deploy via pipeline
+  - Delete manual/ephemeral resources
+```
+
+### Secrets
+
+**ALL secrets are stored in GitHub Actions secrets.** Operations requiring secrets MUST use pipelines.
+
+---
+
+## Service URLs
+
+{{#each SERVICE_URLS}}
+| {{name}} | {{url}} |
+{{/each}}
+
+---
+
+## See Also
+
+- `docs/ARCHITECTURE-OVERVIEW.md` - Detailed architecture
+- `.factory/compliance_rules.yaml` - Architecture constraints (if applicable)

package/templates/CLAUDE_CODING.template.md

@@ -0,0 +1,127 @@
+# Coding Standards Template
+
+**Version**: 1.0.0
+**Last Updated**: {{STRUCTURE_DATE}}
+
+---
+
+## Core Principles
+
+1. **State assumptions** before writing code
+2. **Verify correctness** -- do not claim it
+3. **Handle error paths**, not just the happy path
+4. **Do not import complexity** you do not need
+5. **Produce code you would want to debug at 3am**
+
+---
+
+## Pre-Commit Checklist
+
+- [ ] Functions <= 30 lines
+- [ ] Self-documenting names
+- [ ] Error paths handled explicitly
+- [ ] No debug prints or commented-out code
+- [ ] Consistent with surrounding code style
+- [ ] No hardcoded values that should be constants
+- [ ] Imports are minimal
+
+---
+
+{{#if HAS_MULTI_TENANCY}}
+
+## Multi-Tenancy
+
+All database queries must include organization scope.
+
+### Correct Patterns
+
+```sql
+-- ✅ Organization-scoped query
+SELECT * FROM products WHERE owner_id = $1;
+```
+
+### Incorrect Patterns
+
+```sql
+-- ❌ Cross-tenant access
+SELECT * FROM products;
+```
+
+{{/if}}
+
+---
+
+## Security
+
+### Secrets
+
+Never hardcode secrets. Use environment variables.
+
+```typescript
+// ✅ Correct
+const dbPassword = process.env.DB_PASSWORD;
+
+// ❌ Wrong
+const dbPassword = 'hardcoded_password';
+```
+
+### Input Validation
+
+Always validate and sanitize inputs.
+
+```typescript
+// ✅ Parameterized queries
+db.query('SELECT * FROM users WHERE id = $1', [userId]);
+```
+
+---
+
+## Error Handling
+
+Log with context for debugging.
+
+```typescript
+// ✅ Correct
+logger.error('Failed to fetch', {
+  error: error.message,
+  correlationId: req.id,
+});
+```
+
+---
+
+## Testing
+
+### Running Tests
+
+```bash
+{{TEST_COMMAND}}
+```
+
+---
+
+## Code Quality Tools
+
+```bash
+{{LINT_COMMAND}}
+```
+
+---
+
+## Naming Conventions
+
+| Type      | Convention           | Example           |
+| --------- | -------------------- | ----------------- |
+| Variables | camelCase            | `userName`        |
+| Constants | SCREAMING_SNAKE_CASE | `MAX_RETRY_COUNT` |
+| Functions | camelCase            | `getUserById`     |
+| Classes   | PascalCase           | `UserService`     |
+| Files     | kebab-case           | `user-service.ts` |
+| Database  | snake_case           | `user_accounts`   |
+
+---
+
+## See Also
+
+- `CLAUDE_WORKFLOWS.md` - Task workflows and testing
+- `.factory/skills/code-reviewer/` - Code review checklists (if applicable)

package/templates/CLAUDE_DROIDS.template.md

@@ -0,0 +1,109 @@
+# Droids and Skills Guide Template
+
+**Version**: 1.0.0
+**Last Updated**: {{STRUCTURE_DATE}}
+
+---
+
+## Available Droids
+
+Droids are specialized AI agents for specific tasks.
+
+### Language Specialists
+
+| Droid            | Purpose                               |
+| ---------------- | ------------------------------------- |
+| `cpp-pro`        | C++ development, RAII, STL, templates |
+| `python-pro`     | Python, async/await, decorators       |
+| `javascript-pro` | JavaScript/TypeScript, ES6+, async    |
+
+### Review Droids
+
+| Droid                    | Purpose                   | Blocks PR     |
+| ------------------------ | ------------------------- | ------------- |
+| `security-code-reviewer` | OWASP, secrets, injection | CRITICAL/HIGH |
+| `code-quality-reviewer`  | Naming, complexity, style | CRITICAL only |
+| `performance-reviewer`   | Algorithms, N+1, caching  | Advisory      |
+| `test-coverage-reviewer` | Test gaps, brittle tests  | Advisory      |
+
+### Utility Droids
+
+| Droid                  | Purpose                             |
+| ---------------------- | ----------------------------------- |
+| `worktree-manager`     | Git worktree lifecycle, PR creation |
+| `git-summarizer`       | Repository context for reviewers    |
+| `release-notes-writer` | Generate release notes from commits |
+| `project-analyzer`     | Extract project metadata            |
+
+---
+
+## Available Skills
+
+Skills provide domain-specific guidance.
+
+{{#each SKILLS}}
+| `{{name}}` | {{purpose}} |
+{{/each}}
+
+---
+
+## Agent Routing
+
+| Task Type             | Route To                 |
+| --------------------- | ------------------------ |
+| Security review       | `security-code-reviewer` |
+| Performance analysis  | `performance-reviewer`   |
+| Code quality          | `code-quality-reviewer`  |
+| C++ code              | `cpp-pro`                |
+| Python code           | `python-pro`             |
+| JavaScript/TypeScript | `javascript-pro`         |
+
+---
+
+## Parallel Execution
+
+When safe, run independent droids in parallel:
+
+```bash
+# Before PR - run all reviewers
+Task(subagent_type: "security-code-reviewer", prompt: "Audit: <files>")
+Task(subagent_type: "code-quality-reviewer", prompt: "Review: <files>")
+```
+
+---
+
+## Multi-Agent Coordination
+
+**Skip for single-agent sessions.** Only activate when multiple agents work concurrently.
+
+```bash
+# Check for overlaps
+uap agent overlaps --resource "<files-or-directories>"
+```
+
+| Risk Level        | Action                        |
+| ----------------- | ----------------------------- |
+| `none`            | Proceed immediately           |
+| `low`             | Proceed, note merge order     |
+| `medium`          | Announce, coordinate sections |
+| `high`/`critical` | Wait or split work            |
+
+---
+
+## Invoking Droids
+
+```bash
+# Via Task tool
+Task(subagent_type: "python-pro", prompt: "Refactor this code: <code>")
+
+# Via Skill tool
+Skill(skill: "openobserve-expert")
+```
+
+---
+
+## See Also
+
+- `.factory/droids/` - Droid definitions
+- `.factory/skills/` - Skill definitions
+- `CLAUDE_WORKFLOWS.md` - Review protocols