optimal-cli 1.0.1 → 1.1.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "optimal-cli",
+  "description": "Optimal CLI plugin marketplace — unified skills for financial analytics, content marketing, and infrastructure",
+  "owner": {
+    "name": "Carlos Lenis",
+    "email": "95986651+clenisa@users.noreply.github.com"
+  },
+  "plugins": [
+    {
+      "name": "optimal-cli",
+      "description": "Unified CLI skills for Optimal's financial analytics, content marketing, and infrastructure operations. 29 skills across finance, CMS, newsletters, social media, transactions, budgets, and infrastructure.",
+      "category": "development",
+      "source": ".",
+      "homepage": "https://github.com/clenisa/optimal-cli"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "optimal-cli",
+  "description": "Unified CLI skills for Optimal's financial analytics, content marketing, and infrastructure operations.",
+  "version": "0.1.0",
+  "author": {
+    "name": "Carlos Lenis",
+    "email": "95986651+clenisa@users.noreply.github.com"
+  },
+  "keywords": ["finance", "fpa", "newsletter", "cms", "kanban", "cli"]
+}

package/.env.example

@@ -0,0 +1,17 @@
+# Kanban Board (OptimalOS Supabase)
+OPTIMAL_SUPABASE_URL=https://hbfalrpswysryltysonm.supabase.co
+OPTIMAL_SUPABASE_SERVICE_KEY=
+
+# ReturnPro Financial Data
+RETURNPRO_SUPABASE_URL=https://vvutttwunexshxkmygik.supabase.co
+RETURNPRO_SUPABASE_SERVICE_KEY=
+
+# Strapi CMS
+STRAPI_URL=https://strapi.op-hub.com
+STRAPI_API_TOKEN=
+
+# Content Generation
+GROQ_API_KEY=
+GROQ_MODEL=llama-3.3-70b-versatile
+NEWSAPI_KEY=
+NEWSAPI_QUERY=south florida commercial real estate

package/CLAUDE.md

@@ -0,0 +1,67 @@
+# optimal-cli — Agent Context
+
+## What This Is
+A Claude Code plugin monorepo consolidating 10 Optimal repos into CLI skills.
+All mutations go through skills — frontends in apps/ are read-only dashboards.
+
+## Tech Stack
+- Language: TypeScript (strict, ESM)
+- Package Manager: pnpm workspaces
+- CLI Framework: Commander.js (bin/optimal.ts)
+- Database: Supabase (two instances)
+  - ReturnPro: vvutttwunexshxkmygik.supabase.co (financial data)
+  - OptimalOS: hbfalrpswysryltysonm.supabase.co (kanban board, transactions)
+- CMS: Strapi v5 at https://strapi.op-hub.com/api
+- AI: Groq (Llama 3.3 70B) for content generation
+
+## Commands
+pnpm build — compile TypeScript
+pnpm lint — type-check
+tsx bin/optimal.ts <command> — run CLI
+
+## Project Structure
+skills/ — .md skill files (agent-facing WHAT)
+lib/ — TypeScript modules (implementation HOW)
+agents/ — subagent definitions
+hooks/ — Claude Code hooks
+bin/optimal.ts — CLI entry point
+apps/ — read-only Next.js frontends
+supabase/ — consolidated migrations
+
+## Conventions
+- Skills in skills/*.md with frontmatter: name, description
+- Every skill logs execution to cli_task_logs via lib/kanban.ts
+- lib/ functions are single source of truth — skills and CLI both call them
+- Never run SQL manually — use migration files + supabase db push --linked
+- Environment variables in .env at repo root
+- Package manager: pnpm (never npm or yarn)
+- Git email: 95986651+clenisa@users.noreply.github.com
+
+## Supabase Tables (Kanban — OptimalOS Instance)
+| Table | Purpose |
+|-------|---------|
+| cli_projects | Project groupings |
+| cli_tasks | Kanban cards with agent assignment, blocking deps, skill refs |
+| cli_task_logs | Audit trail of agent activity |
+
+## Supabase Tables (Financial — ReturnPro Instance)
+| Table | Purpose |
+|-------|---------|
+| stg_financials_raw | Staged financial data (amount is TEXT, CAST before math) |
+| confirmed_income_statements | Confirmed GL accounts |
+| dim_account | Account code → ID lookup |
+| dim_client | Client name → ID lookup |
+| dim_master_program | Master program lookup |
+| dim_program_id | Program ID lookup |
+
+## Environment Variables
+OPTIMAL_SUPABASE_URL=https://hbfalrpswysryltysonm.supabase.co
+OPTIMAL_SUPABASE_SERVICE_KEY=...
+RETURNPRO_SUPABASE_URL=https://vvutttwunexshxkmygik.supabase.co
+RETURNPRO_SUPABASE_SERVICE_KEY=...
+STRAPI_URL=https://strapi.op-hub.com
+STRAPI_API_TOKEN=...
+GROQ_API_KEY=...
+GROQ_MODEL=llama-3.3-70b-versatile
+NEWSAPI_KEY=...
+NEWSAPI_QUERY=south florida commercial real estate

package/COMMANDS.md

@@ -0,0 +1,264 @@
+# Optimal CLI — Full Command Reference
+
+## Global Options
+
+All commands support:
+- `-V, --version` — Show version number
+- `-h, --help` — Show help
+
+---
+
+## Config Commands
+
+### `optimal config push`
+Push local `~/.openclaw/openclaw.json` to cloud storage.
+
+```bash
+optimal config push --agent <name>
+```
+
+**Options:**
+- `--agent <name>` (required) — Agent name (e.g., oracle, opal, kimklaw)
+
+**Example:**
+```bash
+optimal config push --agent oracle
+# ✓ Config pushed for oracle
+#   ID: abc-123
+#   Version: 2026-03-05T12:00:00Z
+```
+
+---
+
+### `optimal config pull`
+Pull config from cloud and save to local `~/.openclaw/openclaw.json`.
+
+```bash
+optimal config pull --agent <name>
+```
+
+**Options:**
+- `--agent <name>` (required) — Agent name to pull config for
+
+**Example:**
+```bash
+optimal config pull --agent oracle
+# ✓ Config pulled for oracle
+#   Version: 2026-03-05T12:00:00Z
+#   Updated: 2026-03-05T12:00:00Z
+# 
+# Saved to: ~/.openclaw/openclaw.json
+```
+
+---
+
+### `optimal config list`
+List all saved agent configs in cloud storage.
+
+```bash
+optimal config list
+```
+
+**Example:**
+```bash
+optimal config list
+# | Agent   | Version              | Updated              |
+# |---------|----------------------|----------------------|
+# | oracle  | 2026-03-05T10:00:00Z | 2026-03-05T10:00:00Z |
+# | opal    | 2026-03-04T08:30:00Z | 2026-03-04T08:30:00Z |
+# | kimklaw | 2026-03-05T11:15:00Z | 2026-03-05T11:15:00Z |
+# 
+# Total: 3 configs
+```
+
+---
+
+### `optimal config diff`
+Compare local config with cloud version.
+
+```bash
+optimal config diff --agent <name>
+```
+
+**Options:**
+- `--agent <name>` (required) — Agent name to compare
+
+**Example:**
+```bash
+optimal config diff --agent oracle
+# Differences found:
+#   • Top-level keys differ
+#   • Version mismatch: local=2026.2.25, cloud=2026.3.1
+# 
+# Local updated: 2026-03-05T10:00:00Z
+# Cloud updated: 2026-03-05T12:00:00Z
+```
+
+---
+
+### `optimal config sync`
+Two-way sync: push if local is newer, pull if cloud is newer.
+
+```bash
+optimal config sync --agent <name>
+```
+
+**Options:**
+- `--agent <name>` (required) — Agent name to sync
+
+**Example:**
+```bash
+optimal config sync --agent oracle
+# ✓ pushed
+#   Local is newer - pushed to cloud (version 2026-03-05T12:00:00Z)
+```
+
+---
+
+## Board Commands
+
+### `optimal board view`
+Display the kanban board.
+
+```bash
+optimal board view [options]
+```
+
+**Options:**
+- `-p, --project <slug>` — Project slug (default: optimal-cli-refactor)
+- `-s, --status <status>` — Filter by status
+
+**Example:**
+```bash
+optimal board view
+# | Status      | P | Title                | Agent   | Skill       |
+# |-------------|---|----------------------|---------|-------------|
+# | in_progress | 1 | Build CLI            | oracle  | config-sync |
+# | ready       | 2 | Test migrations      | kimklaw | db-migrate  |
+```
+
+---
+
+### `optimal board create`
+Create a new task.
+
+```bash
+optimal board create --title "Task name" [options]
+```
+
+**Options:**
+- `-t, --title <title>` (required) — Task title
+- `-p, --project <slug>` — Project slug (default: optimal-cli-refactor)
+- `-d, --description <desc>` — Task description
+- `--priority <n>` — Priority 1-4 (default: 3)
+- `--skill <ref>` — Skill reference
+- `--labels <labels>` — Comma-separated labels
+
+**Example:**
+```bash
+optimal board create --title "Fix bug" --priority 1 --skill config-sync
+```
+
+---
+
+### `optimal board update`
+Update a task.
+
+```bash
+optimal board update --id <uuid> [options]
+```
+
+**Options:**
+- `--id <uuid>` (required) — Task UUID
+- `-s, --status <status>` — New status
+- `-a, --agent <name>` — Assign to agent
+- `--priority <n>` — New priority
+- `-m, --message <msg>` — Log message
+
+**Example:**
+```bash
+optimal board update --id abc-123 --status done --agent oracle
+```
+
+---
+
+## Database Migration Commands
+
+### `optimal migrate push`
+Run Supabase migrations.
+
+```bash
+optimal migrate push --target <returnpro|optimalos> [options]
+```
+
+**Options:**
+- `--target <target>` (required) — Target: returnpro or optimalos
+- `--dry-run` — Preview without applying
+
+---
+
+### `optimal migrate pending`
+List pending migration files.
+
+```bash
+optimal migrate pending --target <returnpro|optimalos>
+```
+
+---
+
+### `optimal migrate create`
+Create a new migration file.
+
+```bash
+optimal migrate create --target <returnpro|optimalos> --name <name>
+```
+
+---
+
+## Environment Setup
+
+### Required for Config Sync
+
+```bash
+# ~/.optimal/.env
+OPTIMAL_SUPABASE_URL=https://hbfalrpswysryltysonm.supabase.co
+OPTIMAL_SUPABASE_SERVICE_KEY=eyJhbGciOiJIUzI1NiIs...
+```
+
+### Required for Financial Commands
+
+```bash
+RETURNPRO_SUPABASE_URL=https://vvutttwunexshxkmygik.supabase.co
+RETURNPRO_SUPABASE_SERVICE_KEY=sb_secret_...
+```
+
+### Required for CMS Commands
+
+```bash
+STRAPI_URL=https://strapi.op-hub.com
+STRAPI_API_TOKEN=your_token_here
+```
+
+---
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error |
+| 2 | Missing required option |
+| 3 | Authentication failed |
+
+---
+
+## Troubleshooting
+
+### "No config found at ~/.openclaw/openclaw.json"
+Run `optimal config pull --agent <name>` to download a config first.
+
+### "Missing OPTIMAL_SUPABASE_SERVICE_KEY"
+Set the environment variable in `~/.optimal/.env`.
+
+### "Table does not exist"
+Run the migration SQL in Supabase SQL Editor (see README.md).

package/PUBLISH.md

@@ -0,0 +1,70 @@
+# Publishing @clenisa/optimal-cli to NPM
+
+## Option 1: Login and Publish (Interactive)
+
+```bash
+cd /root/.openclaw/workspace/optimal-cli
+npm login
+# Follow prompts (username, password, 2FA)
+npm publish --access public
+```
+
+## Option 2: Using Access Token (Automated)
+
+1. Go to https://www.npmjs.com/settings/clenisa/tokens
+2. Create "Automation" token
+3. Add to `~/.npmrc`:
+
+```bash
+echo "//registry.npmjs.org/:_authToken=npm_YOUR_TOKEN_HERE" > ~/.npmrc
+```
+
+4. Then publish:
+
+```bash
+cd /root/.openclaw/workspace/optimal-cli
+npm publish --access public
+```
+
+## Option 3: GitHub Actions (Recommended)
+
+Add this `.github/workflows/publish.yml`:
+
+```yaml
+name: Publish to NPM
+on:
+  push:
+    tags:
+      - 'v*'
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v2
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+      - run: pnpm install
+      - run: pnpm build
+      - run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+Then add `NPM_TOKEN` secret in GitHub repo settings.
+
+## Post-Publish Verification
+
+```bash
+# Check package
+npm view @clenisa/optimal-cli
+
+# Install globally
+npm install -g @clenisa/optimal-cli
+
+# Test
+optimal --version
+optimal config list
+```

package/agents/content-ops.md

@@ -42,7 +42,7 @@ The content-ops agent follows a **generate-review-publish-deploy** pipeline. Con
 2. Claim task          updateTask(taskId, { status: 'in_progress', assigned_agent: 'content-ops' })
 3. Log start           logActivity(taskId, { agent: 'content-ops', action: 'task_claimed', message: 'Starting...' })
 4. Execute skill       Run the skill referenced in task.skill_ref
-5. Log result          logActivity({actor, 'content-ops', { success, message, metadata })
+5. Log result          logSkillExecution(skillName, 'content-ops', { success, message, metadata })
 6. Complete/review     updateTask(taskId, { status: 'done' }) or { status: 'review' } if human approval needed
 7. Repeat              Loop back to step 1
 ```
@@ -150,7 +150,7 @@ while (true) {
   try {
     const result = await executeSkill(task.skill_ref, task.metadata)
 
-    await logActivity({actor, 'content-ops', {
+    await logSkillExecution(task.skill_ref, 'content-ops', {
       success: true,
       message: result.message,
       metadata: result

package/agents/financial-ops.md

@@ -43,7 +43,7 @@ The financial-ops agent follows a strict **upload-then-verify** pattern. Every d
 3. Log start           logActivity(taskId, { agent: 'financial-ops', action: 'task_claimed', message: 'Starting...' })
 4. Execute skill       Run the skill referenced in task.skill_ref
 5. Post-action audit   If the skill mutated data, run /audit-financials automatically
-6. Log result          logActivity({actor, 'financial-ops', { success, message, metadata })
+6. Log result          logSkillExecution(skillName, 'financial-ops', { success, message, metadata })
 7. Complete task        updateTask(taskId, { status: 'done' })
 8. Repeat              Loop back to step 1
 ```
@@ -124,7 +124,7 @@ while (true) {
       })
     }
 
-    await logActivity({actor, 'financial-ops', {
+    await logSkillExecution(task.skill_ref, 'financial-ops', {
       success: true,
       message: result.message,
       metadata: result

package/agents/infra-ops.md

@@ -33,7 +33,7 @@ The infra-ops agent follows a **check-then-act** pattern. It verifies system hea
 3. Log start           logActivity(taskId, { agent: 'infra-ops', action: 'task_claimed', message: 'Starting...' })
 4. Execute skill       Run the skill referenced in task.skill_ref
 5. Post-deploy check   If the skill was a deploy, run /health-check to verify
-6. Log result          logActivity({actor, 'infra-ops', { success, message, metadata })
+6. Log result          logSkillExecution(skillName, 'infra-ops', { success, message, metadata })
 7. Complete task        updateTask(taskId, { status: 'done' })
 8. Repeat              Loop back to step 1
 ```
@@ -118,7 +118,7 @@ while (true) {
     // Execute the primary skill
     const result = await executeSkill(task.skill_ref, task.metadata)
 
-    await logActivity({actor, 'infra-ops', {
+    await logSkillExecution(task.skill_ref, 'infra-ops', {
       success: true,
       message: result.message,
       metadata: result