@monoes/monomindcli 1.10.1 → 1.10.3

package/.claude/commands/monomind/understand.md

@@ -1,6 +1,6 @@
 ---
 name: monomind:understand
-description: "Monomind — Run semantic enrichment on the current project's monograph knowledge graph"
+description: "Monomind — Run semantic enrichment on the current project's monograph knowledge graph. No external plugin needed — the analysis engine ships with monomind."
 ---
 
 # /monomind:understand — Semantic Enrichment
@@ -8,18 +8,25 @@ description: "Monomind — Run semantic enrichment on the current project's mono
 Enriches the current project's monograph knowledge graph with LLM-generated summaries,
 architectural layers, and semantic relationships.
 
-Parse `$ARGUMENTS` for the flags below.
+The analysis engine is built into monomind — no external plugin installation required.
 
 ## Parse Arguments
 
 Parse `$ARGUMENTS` for these optional flags:
 
-- `--dir <path>`    — project directory to analyze (default: current working directory)
-- `--db <path>`     — path to monograph.db (default: `<dir>/.monomind/monograph.db`)
-- `--import`        — import an existing graph.json only (skip running /understand)
-- `--graph <path>`  — explicit path to a UA graph.json file to import
-- `--full`          — force full re-analysis even if graph.json is recent
-- `--dry-run`       — show what would happen without writing to DB
+- `--dir <path>`      — project directory to analyze (default: current working directory)
+- `--db <path>`       — path to monograph.db (default: `<dir>/.monomind/monograph.db`)
+- `--import`          — import an existing graph.json only (skip analysis, run ua-import.mjs)
+- `--graph <path>`    — explicit path to a graph.json to import (implies `--import`)
+- `--full`            — force full re-analysis even if graph.json is recent
+- `--no-llm`          — heuristic-only mode: detect layers from file paths, no API calls
+- `--layers-only`     — skip per-file analysis, only (re-)detect architectural layers
+- `--incremental`     — re-analyze only files changed since the last run (uses git diff)
+- `--onboard`         — generate an ONBOARDING.md guide from the enriched graph
+- `--onboard-out <path>` — where to write the onboarding guide (default: `<dir>/ONBOARDING.md`)
+- `--batch-size <N>`  — files per LLM batch (default: 5, increase for faster analysis)
+- `--max-files <N>`   — stop after N files (0 = all)
+- `--dry-run`         — show what would happen without writing to DB
 
 If no flags, treat any bare path argument as `--dir`.
 
@@ -43,108 +50,142 @@ DB="${ARGUMENTS_db:-$DIR/.monomind/monograph.db}"
 
 ---
 
-## Step 2: Check for existing UA graph.json
+## Step 2: Locate the built-in analysis engine
 
-Look for `$DIR/.understand/knowledge-graph.json`, `$DIR/.understand/graph.json`, and `$DIR/.ua/graph.json` (in that order).
+The `understand-analyze.mjs` script ships with `@monomind/cli`. Find it:
 
-If `--graph <path>` was supplied, use that path instead.
+```bash
+# Try npm root (global install / homebrew)
+GLOBAL_ROOT=$(npm root -g 2>/dev/null)
+SCRIPT="$GLOBAL_ROOT/@monomind/cli/scripts/understand-analyze.mjs"
+
+# If not found globally, try npx resolve
+if [ ! -f "$SCRIPT" ]; then
+  SCRIPT=$(node -e "try{console.log(require.resolve('@monomind/cli/scripts/understand-analyze.mjs'))}catch{}" 2>/dev/null)
+fi
+
+# Fallback: walk up from the running CLI's __dirname
+if [ ! -f "$SCRIPT" ]; then
+  SCRIPT=$(node -e "
+    const {createRequire} = require('module');
+    const r = createRequire(require.resolve('monomind'));
+    try { console.log(r.resolve('@monomind/cli/scripts/understand-analyze.mjs')); } catch {}
+  " 2>/dev/null)
+fi
+```
+
+If the script is still not found:
+> The built-in understand engine (understand-analyze.mjs) was not found.
+> Update monomind: `npm install -g monomind@latest`
 
-**If a graph.json is found AND `--full` was NOT set:**
+And STOP.
+
+---
 
-Report the file age:
+## Step 3: Check for existing graph.json (unless `--full`)
+
+Look for (in order):
+- `$DIR/.understand/knowledge-graph.json`
+- `$DIR/.understand/graph.json`
+- `$DIR/.ua/graph.json`
+
+If `--graph <path>` was supplied, use that path directly.
+
+**If a recent graph.json is found AND `--full` was NOT set:**
+
+Report the file age and jump to **Step 5: Import**:
 ```
 Found graph.json (X hours old) — importing into monograph…
 ```
 
-Jump to **Step 4: Import**.
-
-**If no graph.json is found OR `--full` was set:**
+**If `--import` or `--graph` was set:**
+Jump directly to **Step 5: Import**.
 
-Proceed to **Step 3: Run understand analysis**.
+**Otherwise:**
+Proceed to **Step 4: Run analysis**.
 
 ---
 
-## Step 3: Run understand analysis
+## Step 4: Run built-in analysis
 
-Locate the understand plugin. Check these paths in order:
-1. `$UA_PLUGIN_DIR` (if set)
-2. `$HOME/tools/understand-anything/understand-anything-plugin`
-3. Sibling directory: `../understand-anything/understand-anything-plugin` relative to the project root
+Run the built-in engine. Build the command from parsed flags:
 
-If the plugin is NOT found, tell the user:
-> understand plugin not found. Set `UA_PLUGIN_DIR` to its location, or clone it:
-> ```bash
-> git clone https://github.com/nicholasgasior/understand-anything \
->   ~/tools/understand-anything
-> export UA_PLUGIN_DIR=~/tools/understand-anything/understand-anything-plugin
-> ```
-And STOP.
-
-**If found:**
+```bash
+node "$SCRIPT" \
+  --dir "$DIR" \
+  --db "$DB" \
+  [--no-llm]           # if --no-llm was set
+  [--layers-only]      # if --layers-only was set
+  [--incremental]      # if --incremental was set
+  [--onboard]          # if --onboard was set
+  [--onboard-out PATH] # if --onboard-out was set
+  [--dry-run]          # if --dry-run was set
+  [--batch-size N]     # if --batch-size was set
+  [--max-files N]      # if --max-files was set
+```
 
-Use the Agent tool to run the `/understand` skill on `$DIR`.
-The skill produces `.understand/graph.json` in the target directory.
+The script will:
+1. Read all file nodes from the monograph DB
+2. For each file, call the Anthropic API (via `ANTHROPIC_API_KEY`) to get summaries, tags, and complexity
+3. Detect architectural layers (LLM-based if API key available, heuristic fallback otherwise)
+4. Write enrichment data back to `monograph.db` (community_id + properties JSON)
+5. Emit a `graph.json` to `$DIR/.understand/knowledge-graph.json`
 
-Instruct the spawned agent:
-- Project directory: `$DIR`
-- Run the full `/understand` pipeline (project-scanner → file-analyzer → architecture-analyzer → tour-builder)
-- Save the resulting graph.json to `$DIR/.understand/graph.json`
-- Report back when done with node/edge/layer counts
+If `ANTHROPIC_API_KEY` is not set, the script automatically falls back to `--no-llm` mode — heuristic layer detection from file paths, no per-file summaries. Tell the user this happened.
 
-Wait for completion before proceeding.
+Wait for the script to complete before proceeding.
 
 ---
 
-## Step 4: Import graph.json into monograph DB
+## Step 5: Import (only when using an existing graph.json)
 
-Run the import script:
+If jumping here from Step 3 (existing graph.json found):
 
 ```bash
 REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
-node "$REPO_ROOT/scripts/ua-import.mjs" "$GRAPH_JSON" "$DB"
+IMPORT_SCRIPT="$REPO_ROOT/scripts/ua-import.mjs"
+# fallback: alongside understand-analyze.mjs
+[ ! -f "$IMPORT_SCRIPT" ] && IMPORT_SCRIPT="$(dirname $SCRIPT)/../../../scripts/ua-import.mjs"
+node "$IMPORT_SCRIPT" "$GRAPH_JSON" "$DB"
 ```
 
-Where:
-- `$GRAPH_JSON` is the graph.json path (found in Step 2 or produced in Step 3)
-- `$DB` is the monograph.db path
-
-If `--dry-run` was set, instead read graph.json and report what WOULD be written:
-- Number of nodes to enrich / insert
-- Number of edges to add
-- Layers that would become communities
-Do NOT write to the DB.
+If `--dry-run` was set, report what would be imported without writing to the DB.
 
 ---
 
-## Step 5: Report results
+## Step 6: Report results
 
-After import completes, show a summary table:
+After the analysis or import completes, show a summary:
 
 ```
-╔══════════════════════════════════════════╗
-║  /monomind:understand — Enrichment Done  ║
-╠══════════════════════════════════════════╣
-║  DB:              .monomind/monograph.db ║
-║  Nodes enriched:  <N>                    ║
-║  Nodes inserted:  <N>                    ║
-║  Edges added:     <N>                    ║
-║  Communities:     <N> (from UA layers)   ║
-╚══════════════════════════════════════════╝
+╔══════════════════════════════════════════════════╗
+║  /monomind:understand — Enrichment Done           ║
+╠══════════════════════════════════════════════════╣
+║  DB:              .monomind/monograph.db          ║
+║  Nodes enriched:  <N>                             ║
+║  Communities:     <N> (layers detected)           ║
+║  graph.json:      .understand/knowledge-graph.json║
+╚══════════════════════════════════════════════════╝
 ```
 
 Then tell the user:
 > The monograph graph is now enriched with semantic summaries and architectural layers.
 > Open the Monomind control panel and click **Monograph → GRAPH** to see multi-color layers.
-> Each color now represents an architectural layer (API, Service, Data, UI, etc.).
-
-If any nodes were skipped (unresolved edges), report the count but do NOT treat it as an error.
-
-To repeat this command on a schedule, wrap it with `/monomind:repeat`.
+> Each color represents an architectural layer (API, Service, Data, UI, etc.).
+>
+> To re-run with full LLM analysis: `/monomind:understand --full`
+> To only refresh layer detection: `/monomind:understand --layers-only`
+> To run without API calls: `/monomind:understand --no-llm`
+> To re-analyze only changed files: `/monomind:understand --incremental`
+> To generate an onboarding guide: `/monomind:understand --onboard`
 
 ---
 
 ## Error Handling
 
-- If `ua-import.mjs` exits non-zero, show stderr and suggest running `pnpm install` from the monomind root.
-- If graph.json is malformed JSON, report the parse error and suggest re-running `/understand`.
+- If `ANTHROPIC_API_KEY` is not set, automatically use heuristic mode — report this clearly but do NOT stop.
+- If the script exits non-zero, show stderr and suggest `npm install -g monomind@latest`.
+- If monograph.db has no file nodes, tell the user to run `npx monomind monograph build` first.
 - All errors are non-fatal to the main session — report and return cleanly.
+
+To repeat this command on a schedule, wrap it with `/monomind:repeat`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monoes/monomindcli",
-  "version": "1.10.1",
+  "version": "1.10.3",
   "type": "module",
   "description": "Monomind CLI - Enterprise AI agent orchestration with 60+ specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
   "main": "dist/src/index.js",
@@ -69,6 +69,7 @@
     "bin",
     ".claude",
     "bundled-graph",
+    "scripts",
     "README.md"
   ],
   "scripts": {
@@ -111,4 +112,4 @@
     "access": "public",
     "tag": "latest"
   }
-}
+}

package/scripts/deploy-ipfs-node.sh

@@ -0,0 +1,153 @@
+#!/bin/bash
+#
+# Deploy IPFS Node to Google Cloud
+# Provides free IPFS pinning for your users
+#
+# Usage:
+#   ./deploy-ipfs-node.sh [PROJECT_ID] [ZONE]
+#
+# Example:
+#   ./deploy-ipfs-node.sh my-project us-central1-a
+#
+
+set -e
+
+PROJECT_ID="${1:-$(gcloud config get-value project)}"
+ZONE="${2:-us-central1-a}"
+INSTANCE_NAME="ipfs-node"
+MACHINE_TYPE="e2-medium"  # $25/month, use e2-small for $8/month
+DISK_SIZE="100GB"
+
+echo "╔══════════════════════════════════════════════════════════════╗"
+echo "║  IPFS Node Deployment for Monomind                        ║"
+echo "╚══════════════════════════════════════════════════════════════╝"
+echo ""
+echo "Project: $PROJECT_ID"
+echo "Zone: $ZONE"
+echo "Machine: $MACHINE_TYPE"
+echo "Disk: $DISK_SIZE"
+echo ""
+
+# Create firewall rules
+echo "▶ Creating firewall rules..."
+gcloud compute firewall-rules create ipfs-swarm \
+  --project="$PROJECT_ID" \
+  --allow=tcp:4001,udp:4001 \
+  --target-tags=ipfs-node \
+  --description="IPFS swarm connections" \
+  2>/dev/null || echo "  (firewall rule already exists)"
+
+gcloud compute firewall-rules create ipfs-api \
+  --project="$PROJECT_ID" \
+  --allow=tcp:5001 \
+  --target-tags=ipfs-node \
+  --source-ranges="0.0.0.0/0" \
+  --description="IPFS API (consider restricting)" \
+  2>/dev/null || echo "  (firewall rule already exists)"
+
+gcloud compute firewall-rules create ipfs-gateway \
+  --project="$PROJECT_ID" \
+  --allow=tcp:8080 \
+  --target-tags=ipfs-node \
+  --description="IPFS Gateway" \
+  2>/dev/null || echo "  (firewall rule already exists)"
+
+# Create startup script
+STARTUP_SCRIPT='#!/bin/bash
+set -e
+
+# Install IPFS
+echo "Installing IPFS..."
+wget -q https://dist.ipfs.tech/kubo/v0.24.0/kubo_v0.24.0_linux-amd64.tar.gz
+tar xzf kubo_v0.24.0_linux-amd64.tar.gz
+cd kubo && sudo bash install.sh
+cd .. && rm -rf kubo kubo_v0.24.0_linux-amd64.tar.gz
+
+# Create ipfs user
+sudo useradd -m -s /bin/bash ipfs || true
+
+# Initialize IPFS
+sudo -u ipfs IPFS_PATH=/home/ipfs/.ipfs ipfs init --profile=server
+
+# Configure IPFS for server use
+sudo -u ipfs IPFS_PATH=/home/ipfs/.ipfs ipfs config Addresses.API /ip4/0.0.0.0/tcp/5001
+sudo -u ipfs IPFS_PATH=/home/ipfs/.ipfs ipfs config Addresses.Gateway /ip4/0.0.0.0/tcp/8080
+sudo -u ipfs IPFS_PATH=/home/ipfs/.ipfs ipfs config --json API.HTTPHeaders.Access-Control-Allow-Origin "[\"*\"]"
+sudo -u ipfs IPFS_PATH=/home/ipfs/.ipfs ipfs config --json API.HTTPHeaders.Access-Control-Allow-Methods "[\"PUT\", \"POST\", \"GET\"]"
+
+# Set storage limits (adjust as needed)
+sudo -u ipfs IPFS_PATH=/home/ipfs/.ipfs ipfs config Datastore.StorageMax 80GB
+
+# Create systemd service
+cat > /etc/systemd/system/ipfs.service << EOF
+[Unit]
+Description=IPFS Daemon
+After=network.target
+
+[Service]
+Type=simple
+User=ipfs
+Environment=IPFS_PATH=/home/ipfs/.ipfs
+ExecStart=/usr/local/bin/ipfs daemon --migrate=true
+Restart=on-failure
+RestartSec=10
+
+[Install]
+WantedBy=multi-user.target
+EOF
+
+# Start IPFS
+systemctl daemon-reload
+systemctl enable ipfs
+systemctl start ipfs
+
+echo "IPFS node started successfully!"
+'
+
+# Create instance
+echo "▶ Creating VM instance..."
+gcloud compute instances create "$INSTANCE_NAME" \
+  --project="$PROJECT_ID" \
+  --zone="$ZONE" \
+  --machine-type="$MACHINE_TYPE" \
+  --image-family=ubuntu-2204-lts \
+  --image-project=ubuntu-os-cloud \
+  --boot-disk-size="$DISK_SIZE" \
+  --boot-disk-type=pd-ssd \
+  --tags=ipfs-node \
+  --metadata=startup-script="$STARTUP_SCRIPT"
+
+# Get external IP
+echo ""
+echo "▶ Waiting for instance to start..."
+sleep 30
+
+EXTERNAL_IP=$(gcloud compute instances describe "$INSTANCE_NAME" \
+  --project="$PROJECT_ID" \
+  --zone="$ZONE" \
+  --format='get(networkInterfaces[0].accessConfigs[0].natIP)')
+
+echo ""
+echo "═══════════════════════════════════════════════════════════════"
+echo "                    DEPLOYMENT COMPLETE"
+echo "═══════════════════════════════════════════════════════════════"
+echo ""
+echo "  IPFS Node IP: $EXTERNAL_IP"
+echo ""
+echo "  Endpoints:"
+echo "    API:     http://$EXTERNAL_IP:5001"
+echo "    Gateway: http://$EXTERNAL_IP:8080"
+echo "    Swarm:   /ip4/$EXTERNAL_IP/tcp/4001"
+echo ""
+echo "  Test commands:"
+echo "    curl http://$EXTERNAL_IP:5001/api/v0/id"
+echo "    curl http://$EXTERNAL_IP:8080/ipfs/QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG/readme"
+echo ""
+echo "  Configure Monomind CLI:"
+echo "    export IPFS_API_URL=http://$EXTERNAL_IP:5001"
+echo ""
+echo "  SSH into node:"
+echo "    gcloud compute ssh $INSTANCE_NAME --zone=$ZONE"
+echo ""
+echo "  Monthly cost estimate: ~\$25-54 depending on usage"
+echo ""