@miller-tech/uap 1.0.0 → 1.3.0

package/docs/opencode-integration-quickref.md

@@ -0,0 +1,180 @@
+# OpenCode Integration Quick Reference
+
+## File Structure
+
+```
+.project/
+├── .opencode/
+│   ├── plugin/
+│   │   ├── your-plugin.ts          # Your custom plugin
+│   │   └── index.ts                # Optional: aggregate exports
+│   └── package.json                # Dependencies (add @opencode-ai/plugin)
+└── opencode.json                   # OpenCode configuration
+```
+
+## Plugin Template
+
+```typescript
+import type { Plugin } from '@opencode-ai/plugin';
+import { tool } from '@opencode-ai/plugin';
+
+export const MyPlugin: Plugin = async ({ $, directory }) => {
+  return {
+    // Define tools
+    tool: {
+      my_tool: tool({
+        description: 'What this tool does',
+        args: {
+          param: tool.schema.string().describe('Parameter'),
+        },
+        async execute({ param }) {
+          const result = await $`command ${param}`;
+          return result.stdout.toString();
+        },
+      }),
+    },
+
+    // Optional: Event hooks
+    event: async ({ event }) => {
+      if (event.type === 'session.created') {
+        console.log('Session started');
+      }
+    },
+  };
+};
+```
+
+## Available Hooks
+
+| Hook                                 | Purpose                    | Example                        |
+| ------------------------------------ | -------------------------- | ------------------------------ |
+| `tool`                               | Define new tools           | Custom commands for LLM        |
+| `event.session.created`              | Session initialization     | Load context, initialize state |
+| `event.session.compacting`           | Before context compression | Preserve important data        |
+| `tool.execute.before`                | Before tool runs           | Validate args, log activity    |
+| `tool.execute.after`                 | After tool completes       | Record results, update state   |
+| `tool.definition`                    | Modify tool descriptions   | Add policy constraints         |
+| `experimental.chat.system.transform` | Inject system context      | RAG retrieval, dynamic context |
+| `middleware`                         | Transform messages         | Pre/post processing            |
+
+## Tool Schema Types
+
+```typescript
+// String
+tool.schema.string().describe('Text parameter');
+
+// Number with constraints
+tool.schema.number().min(0).max(100).default(50);
+
+// Enum
+tool.schema.enum(['read', 'write', 'execute']).default('read');
+
+// Array
+tool.schema.array().of(tool.schema.string());
+
+// Optional
+tool.schema.string().optional();
+```
+
+## Common Patterns
+
+### 1. CLI Wrapper
+
+```typescript
+tool({
+  description: 'Run external command',
+  args: { cmd: tool.schema.string() },
+  async execute({ cmd }) {
+    return (await $`${cmd}`.quiet()).stdout.toString();
+  },
+});
+```
+
+### 2. File Operations
+
+```typescript
+import { readFile, writeFile } from 'fs/promises';
+
+tool({
+  description: 'Read project file',
+  args: { path: tool.schema.string() },
+  async execute({ path }) {
+    return await readFile(join(projectDir, path), 'utf-8');
+  },
+});
+```
+
+### 3. Memory Query
+
+```typescript
+tool({
+  description: 'Query persistent memory',
+  args: { query: tool.schema.string() },
+  async execute({ query }) {
+    const result = await $`python3 ./scripts/query.py "${query}"`;
+    return result.stdout.toString().trim();
+  },
+});
+```
+
+### 4. Context Injection (RAG)
+
+```typescript
+middleware: async (input, next) => {
+  const lastMsg = input.messages?.[input.messages.length - 1];
+  if (lastMsg?.role === 'user') {
+    const context = await queryRAG(lastMsg.content);
+    input.messages.push({ role: 'system', content: `<context>${context}</context>` });
+  }
+  return next(input);
+};
+```
+
+## Plugin Examples in This Repo
+
+| Plugin          | File                                      | Purpose                       |
+| --------------- | ----------------------------------------- | ----------------------------- |
+| Commands        | `.opencode/plugin/uap-commands.ts`        | CLI commands as tools         |
+| Skills          | `.opencode/plugin/uap-skills.ts`          | Skill loading system          |
+| Droids          | `.opencode/plugin/uap-droids.ts`          | Specialized agent droids      |
+| Pattern RAG     | `.opencode/plugin/uap-pattern-rag.ts`     | On-demand pattern retrieval   |
+| Task Completion | `.opencode/plugin/uap-task-completion.ts` | Track task outcomes           |
+| Session Hooks   | `.opencode/plugin/uap-session-hooks.ts`   | Session lifecycle events      |
+| Enforcement     | `tools/agents/plugins/uap-enforce.ts`     | Loop detection, budget limits |
+
+## Dependencies
+
+```json
+{
+  "dependencies": {
+    "@opencode-ai/plugin": "1.2.16"
+  }
+}
+```
+
+## Debugging
+
+```bash
+# Check plugin loads
+opencode run "What tools are available?"
+
+# View logs
+tail -f ~/.opencode/logs/*.log
+
+# Test TypeScript syntax
+npx tsc --noEmit .opencode/plugin/your-plugin.ts
+```
+
+## Best Practices
+
+1. **Error Handling**: Always use `.nothrow()` and check exit codes
+2. **Security**: Validate inputs, prevent command injection
+3. **Caching**: Cache expensive operations between tool calls
+4. **Descriptions**: Write clear, comprehensive tool descriptions
+5. **Naming**: Use snake_case, prefix with domain (`mydomain_tool`)
+6. **Context**: Preserve important state across compaction
+7. **Performance**: Use `--quiet` to reduce output noise
+
+## Full Example
+
+See: `.opencode/plugin/uap-commands.ts` for a complete implementation example.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miller-tech/uap",
-  "version": "1.0.0",
+  "version": "1.3.0",
   "description": "Autonomous AI agent memory system with CLAUDE.md protocol enforcement",
   "type": "module",
   "main": "dist/index.js",
@@ -66,6 +66,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
+    "@miller-tech/uap": "^1.0.0",
     "@octokit/rest": "^20.0.2",
     "@qdrant/js-client-rest": "^1.11.0",
     "better-sqlite3": "^11.0.0",
@@ -81,6 +82,7 @@
     "ora": "^8.0.1",
     "playwright-core": "^1.58.2",
     "simple-git": "^3.22.0",
+    "ws": "^8.19.0",
     "zod": "^3.23.8"
   },
   "devDependencies": {
@@ -89,6 +91,7 @@
     "@types/inquirer": "^9.0.7",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^20.11.0",
+    "@types/ws": "^8.18.1",
     "@typescript-eslint/eslint-plugin": "^6.19.0",
     "@typescript-eslint/parser": "^6.19.0",
     "@vitest/coverage-v8": "^1.6.1",

package/templates/hooks/session-start.sh

@@ -248,7 +248,8 @@ output+="│ ${GIT_LINE}$(printf ' %.0s' $(seq 1 $((W - 1 - ${#GIT_LINE}))))│"
 output+="├$(printf '─%.0s' $(seq 1 $W))┤"$'\n'
 
 # Active policies
-output+="│ Policies: [ON] IaC Parity  [ON] File Backup$(printf ' %.0s' $(seq 1 $((W - 47))))│"$'\n'
+POLICY_LINE="Policies: [ON] IaC Pipeline  [ON] kubectl Backport  [ON] File Backup"
+output+="│ ${POLICY_LINE}$(printf ' %.0s' $(seq 1 $((W - 1 - ${#POLICY_LINE}))))│"$'\n'
 
 # Memory layers
 L3_STATUS="?"
@@ -282,6 +283,12 @@ output+="### DURING WORK:"$'\n'
 output+="6. ALL file changes MUST use worktree: uap worktree create <slug>"$'\n'
 output+="7. Work in .worktrees/NNN-<slug>/ directory"$'\n'
 output+=""$'\n'
+output+="### IaC PIPELINE ENFORCEMENT (MANDATORY):"$'\n'
+output+="- NEVER run terraform plan/apply/destroy locally. ALL Terraform ops go through CI/CD pipeline."$'\n'
+output+="- kubectl MAY be used to diagnose, test, and verify fixes on clusters."$'\n'
+output+="- ANY kubectl-created resource MUST be backported to Terraform .tf files (import or delete/recreate)."$'\n'
+output+="- 100% IaC parity required. Infrastructure work is NOT DONE until pipeline apply succeeds + kubectl verifies."$'\n'
+output+=""$'\n'
 output+="### BEFORE COMMIT:"$'\n'
 output+="8. Self-review: git diff"$'\n'
 output+="9. Run tests if applicable"$'\n'