@pipemd-core/pipemd 1.0.0

package/dist/templates/agent-decision-tree.md

@@ -0,0 +1,113 @@
+### Agent Decision Tree
+
+You are operating inside a PipeMD context file. The `<!-- pmd: -->` blocks below are live data refreshed by the daemon. This section defines your complete operating workflow — follow it for every task.
+
+---
+
+#### 1. Context Gathering — Read Before You Act
+
+Before writing a single line of code, gather your bearings from the blocks below. They are your fastest, most accurate source of project truth.
+
+| You need… | Read this block | Do NOT run |
+|---|---|---|
+| Project structure, find a file | `tree` | `tree`, `find`, `ls -R` |
+| Architecture / module graph | `arch` | manual file inspection |
+| Dependencies and versions | `deps` | `cat package.json` |
+| Known TODOs, FIXMEs, HACKs | `todos` | `grep -r TODO` |
+| Recent commits (what changed) | `git-log` | `git log` |
+| Current branch, tracking status | `git-branch` | `git status -b` |
+| Changed / staged / untracked files | `git-status` | `git status` |
+| Diff summary (+/- lines) | `diff-stat` | `git diff --stat` |
+| Type errors | `type-check` | `tsc --noEmit` |
+| Lint errors | `lint` | `eslint .` |
+| Test pass/fail summary | `test-summary` | full test run |
+| Crew: who's working, conflicts | `crew` | `pmd crew status` |
+| DB models, routes, components | ecosystem-specific blocks | manual source scan |
+
+If the answer isn't in the blocks — then (and only then) run the appropriate shell command. But check blocks first, always.
+
+---
+
+#### 2. Think Before You Code
+
+Don't assume. Don't hide confusion. Surface tradeoffs before you type.
+
+- **State your plan.** If the task is non-trivial, write a brief plan with verifiable checkpoints:
+  ```
+  1. [Step] → verify: [check]
+  2. [Step] → verify: [check]
+  3. [Step] → verify: [check]
+  ```
+- **Surface assumptions.** If multiple interpretations exist, present them — don't pick silently. If something is unclear, stop and ask.
+- **Define success criteria.** Transform vague tasks into verifiable goals:
+  - "Add validation" → "Write tests for invalid inputs, then make them pass"
+  - "Fix the bug" → "Write a test that reproduces it, then make it pass"
+  - "Refactor X" → "Ensure tests pass before and after"
+- **Plan the smallest change.** Identify the exact feature, its source of truth, and its direct dependencies. No speculative features, no "while I'm here" refactors. If a simpler approach exists, say so.
+
+---
+
+#### 3. Coordinate — Multi-Agent & Crew Protocol
+
+**If a `crew` block is present, you are not alone.** Other agents may be editing the same codebase simultaneously. Follow these rules to avoid conflicts and wasted work.
+
+**Before editing any file:**
+
+1. Read the `crew` block. It lists every active session, their claimed files, and any conflicts.
+2. If the file is claimed by another agent (`⚠️ CONFLICT`), **stop**. Coordinate with that agent or pick different work. Treat conflicts as blocking.
+3. If edit hooks are installed, claims happen automatically on every file edit. If not, claim manually:
+   ```bash
+   pmd crew claim src/auth.ts --note "refactoring login"
+   ```
+4. Post your intent so others can see it:
+   ```bash
+   pmd crew note "rewriting the auth middleware"
+   ```
+
+**Sub-agents and parallel workers:**
+
+- PipeMD uses a **Harness → Coordinator → Worker** hierarchy. Each harness has one coordinator; workers are sub-agents spawned for parallel tasks.
+- If you are a coordinator spawning sub-agents:
+  - Each worker must `pmd crew join --role worker` and export `PMD_SESSION` to get its own session.
+  - Partition work by file or directory to minimize overlap. Assign non-overlapping file sets.
+  - Workers auto-detect their coordinator via process ancestry — no manual linking needed.
+  - Monitor the `crew` block for conflicts between your workers. Resolve immediately.
+- If you are a worker:
+  - Your session is derived from your parent process. Claim only the files assigned to you.
+  - Check the `crew` block before every edit, not just once at start.
+  - Release files when done: `pmd crew release src/auth.ts`.
+
+**Staleness and cleanup:**
+
+- Sessions without a heartbeat for 90 seconds are considered stale. A fresh heartbeat always outranks a dead-PID guess.
+- Clean up when you're done: `pmd crew leave` removes your session entirely.
+
+**Cross-harness coordination:**
+
+- PipeMD is harness-neutral. Claude Code, OpenCode, Gemini, Aider, and Cursor agents all share the same crew ledger.
+- The `crew` block renders the union of all sessions — you see everyone, regardless of their harness.
+- If you see a passive agent (listed but without a crew session), they may not have crew hooks installed. Their edits are uncoordinated — exercise extra caution around their files.
+
+---
+
+#### 4. Edit — Surgical Discipline
+
+- **Match existing code style.** Imports, naming, formatting, conventions — follow what's already there. Don't impose your preferences.
+- **One concern per edit.** If you spot unrelated issues, mention them but don't fix them unless asked.
+- **Never bypass abstractions.** If a file is protected by a service or abstraction layer, use it. Don't modify the underlying file directly.
+- **No logic duplication.** Don't duplicate logic or create parallel states if a source of truth already exists.
+- **No speculative code.** No features beyond what was asked. No abstractions for single-use code. No error handling for impossible scenarios. If you write 200 lines and it could be 50, rewrite it.
+- **Clean up only your own mess.** Remove imports, variables, and functions that your changes made unused. Don't touch pre-existing dead code.
+- **Never edit inside `<!-- pmd: -->` blocks** — your changes are overwritten on the next daemon cycle.
+
+---
+
+#### 5. Verify — Close the Loop
+
+Every change must be verified. Weak success criteria ("make it work") require constant clarification. Strong criteria let you loop independently.
+
+- **Run the project's verification suite.** Check the rules above `<!-- pmd-context -->` or the `deps` block for the correct commands. Typical order: lint → typecheck → test → build.
+- **Re-read the quality blocks.** After your edits, check `type-check` and `lint` blocks for new errors. If active injection is running, validation results appear automatically on your next tool call.
+- **Verify blast radius.** Did your change affect anything beyond the intended scope? Re-read affected blocks to confirm.
+- **Committing?** `git diff --cached` is the only git command you need — staged diffs are not provided by any block. Stage your files, review the diff, then commit.
+- **Release claims.** When done with a file: `pmd crew release src/auth.ts`. When done entirely: `pmd crew leave`.

package/dist/templates/static-rules.md

@@ -0,0 +1,7 @@
+## Static Rules & Notes
+
+- Content inside `<!-- pmd: -->` blocks is **read-only** — the daemon overwrites it every cycle. Never edit these.
+- Content outside `<!-- pmd: -->` blocks is **yours** — edits persist via bidirectional write-back.
+- PipeMD blocks refresh every few seconds. Trust them — they are cheaper and more current than running shell commands.
+- If blocks are empty or stale, the daemon may be down. Check with `pmd status`.
+- Active injection (`[pmd:…→` messages on tool calls) delivers fresh context automatically — you don't need to re-read the context file between edits.

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@pipemd-core/pipemd",
+  "version": "1.0.0",
+  "description": "The Dynamic Context Harness for AI Coding Agents",
+  "type": "module",
+  "bin": {
+    "pmd": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsup && node scripts/copy-plugins.mjs && node scripts/copy-templates.mjs",
+    "prepare": "pnpm build",
+    "prepublishOnly": "pnpm build",
+    "dev": "tsup --watch",
+    "test:e2e": "bash tests/e2e.sh",
+    "test:bidir": "bash tests/e2e-bidirectional.sh",
+    "test:scripts": "bash tests/e2e-scripts.sh",
+    "test:arch": "bash tests/e2e-architecture.sh",
+    "test:compose": "bash tests/e2e-compose.sh",
+    "test:crew": "bash tests/e2e-crew.sh",
+    "test:inject": "bash tests/e2e-inject.sh",
+    "test:unit": "node tests/test-reverse-inject.mjs",
+    "test": "pnpm test:unit && pnpm test:e2e && pnpm test:bidir && pnpm test:scripts && pnpm test:arch && pnpm test:compose && pnpm test:crew && pnpm test:inject"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist",
+    "scripts",
+    "AI_SETUP_PIPEMD.md",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "author": "PipeMD Contributors",
+  "license": "ISC",
+  "homepage": "https://github.com/pipemd-core/pipemd#readme",
+  "bugs": { "url": "https://github.com/pipemd-core/pipemd/issues" },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pipemd-core/pipemd.git"
+  },
+  "keywords": [
+    "ai",
+    "llm",
+    "claude",
+    "cursor",
+    "aider",
+    "context",
+    "pipe",
+    "named-pipe",
+    "prompt-context"
+  ],
+  "packageManager": "pnpm@10.33.2",
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "chokidar": "^5.0.0",
+    "commander": "^14.0.3",
+    "prompts": "^2.4.2",
+    "yaml": "^2.8.4"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "@types/prompts": "^2.4.9",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3"
+  }
+}

package/scripts/C-CPP/architecture/arch.sh

@@ -0,0 +1,229 @@
+#!/usr/bin/env bash
+set -uo pipefail
+# Architecture map — C/C++ module dependencies
+source "$(dirname "$0")/../lib/limit.sh"
+
+: "${MAX_ARCH:=100}"
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+NORMALIZE="$SCRIPT_DIR/normalize.sh"
+[ -f "$NORMALIZE" ] || NORMALIZE="$SCRIPT_DIR/../../Shared/architecture/normalize.sh"
+
+if ! command -v python3 &>/dev/null; then
+  echo "python3 is required for C/C++ architecture extraction"
+  exit 0
+fi
+
+python3 -c "
+import os, re, sys
+from collections import defaultdict
+
+MAX_MODULES = 40
+SKIP_DIRS = {'build', 'cmake-build-debug', 'cmake-build-release', '_deps',
+             'third_party', 'external', '.git', '.pipemd', 'CMakeFiles'}
+
+def module_name(rel_path):
+    rel_path = rel_path.replace(os.sep, '/')
+    parts = rel_path.split('/')
+    filename = os.path.splitext(parts[-1])[0] if parts else ''
+    dirpath = parts[:-1] if len(parts) > 1 else []
+
+    if not dirpath:
+        return filename
+
+    last_dir = dirpath[-1]
+
+    if filename == last_dir:
+        return last_dir
+
+    if len(dirpath) >= 2:
+        parent = dirpath[-2]
+        if parent in ('src', 'lib', 'include', 'app'):
+            return last_dir + '/' + filename
+
+    return last_dir + '/' + filename
+
+def collect_cmake_deps():
+    deps = {}
+    target_sources = {}
+    for root, dirs, fnames in os.walk('.'):
+        dirs[:] = [d for d in dirs if d not in SKIP_DIRS and not d.startswith('.')]
+        if 'CMakeLists.txt' in fnames:
+            cmake_path = os.path.join(root, 'CMakeLists.txt')
+            try:
+                with open(cmake_path, 'r', errors='replace') as f:
+                    content = f.read()
+            except Exception:
+                continue
+
+            content = re.sub(r'#.*', '', content)
+            content = content.replace('\\\n', ' ')
+            content = re.sub(r'\s+', ' ', content)
+
+            for m in re.finditer(r'add_(?:library|executable)\s*\(\s*(\w+)\s+(.*?)(?:\))', content, re.DOTALL):
+                target = m.group(1)
+                sources_str = m.group(2)
+                srcs = []
+                for src_m in re.finditer(r'(\S+\.(?:cpp|cc|cxx|c|h|hpp|hh))', sources_str):
+                    srcs.append(src_m.group(1))
+                if srcs:
+                    target_sources[target.lower()] = srcs
+
+            for m in re.finditer(r'target_link_libraries\s*\(\s*(\w+)\s+(.*?)\)', content, re.DOTALL):
+                target = m.group(1)
+                libs_str = m.group(2)
+                libs = []
+                for lib_m in re.finditer(r'(\w[\w:]*)', libs_str):
+                    lib = lib_m.group(1)
+                    if lib in ('PUBLIC', 'PRIVATE', 'INTERFACE', 'REQUIRED'):
+                        continue
+                    lib_name = lib.split('::')[-1].lower()
+                    libs.append(lib_name)
+                if libs:
+                    deps[target.lower()] = libs
+
+    return deps, target_sources
+
+cmake_deps, cmake_targets = collect_cmake_deps()
+
+include_dirs = ['include', 'inc', 'src', 'lib', '.']
+include_path_cache = {}
+
+def find_include_file(inc_path, source_dir):
+    key = (inc_path, source_dir)
+    if key in include_path_cache:
+        return include_path_cache[key]
+
+    for inc_dir in [source_dir] + include_dirs:
+        full = os.path.join(inc_dir, inc_path)
+        if os.path.isfile(full):
+            include_path_cache[key] = full
+            return full
+
+    for root, dirs, fnames in os.walk('.'):
+        dirs[:] = [d for d in dirs if d not in SKIP_DIRS and not d.startswith('.')]
+        basename = os.path.basename(inc_path)
+        for fn in fnames:
+            if fn == basename:
+                full = os.path.join(root, fn)
+                include_path_cache[key] = full
+                return full
+
+    include_path_cache[key] = None
+    return None
+
+files = []
+for root, dirs, fnames in os.walk('.'):
+    dirs[:] = [d for d in sorted(dirs) if d not in SKIP_DIRS and not d.startswith('.')]
+    for fn in sorted(fnames):
+        if fn.endswith(('.cpp', '.cc', '.cxx', '.c', '.h', '.hpp', '.hxx', '.hh')):
+            if '.test.' not in fn and '.spec.' not in fn:
+                files.append(os.path.join(root, fn))
+    if len(files) >= 300:
+        files = files[:300]
+        break
+
+if not files:
+    sys.exit(0)
+
+module_set = set()
+for fpath in files:
+    rel = os.path.relpath(fpath, '.').replace(os.sep, '/')
+    skip = False
+    for sd in SKIP_DIRS:
+        if '/' + sd + '/' in '/' + rel or rel.startswith(sd + '/'):
+            skip = True
+            break
+    if skip:
+        continue
+    mod = module_name(rel)
+    if mod:
+        module_set.add(mod)
+
+if len(module_set) > MAX_MODULES:
+    module_set = set()
+    for fpath in files:
+        rel = os.path.relpath(fpath, '.').replace(os.sep, '/')
+        parts = rel.split('/')
+        if len(parts) > 2:
+            module_set.add(parts[0] + '/' + parts[1])
+        elif len(parts) == 2:
+            module_set.add(parts[0] if parts[0] in ('src', 'lib', 'include', 'app') else parts[1].rsplit('.', 1)[0])
+        else:
+            module_set.add(os.path.splitext(parts[0])[0])
+
+include_re = re.compile(r'^\\s*#\\s*include\\s*\"([^\"]+)\"', re.MULTILINE)
+
+edges = set()
+
+for fpath in files:
+    rel = os.path.relpath(fpath, '.').replace(os.sep, '/')
+    skip = False
+    for sd in SKIP_DIRS:
+        if '/' + sd + '/' in '/' + rel or rel.startswith(sd + '/'):
+            skip = True
+            break
+    if skip:
+        continue
+
+    src_mod = module_name(rel)
+    if not src_mod or src_mod not in module_set:
+        continue
+
+    try:
+        with open(fpath, 'r', errors='replace') as f:
+            content = f.read()
+    except Exception:
+        continue
+
+    source_dir = os.path.dirname(fpath)
+
+    for m in include_re.finditer(content):
+        inc_path = m.group(1)
+        found = find_include_file(inc_path, source_dir)
+        if found:
+            target_rel = os.path.relpath(found, '.').replace(os.sep, '/')
+            target_mod = module_name(target_rel)
+            if target_mod and target_mod in module_set and target_mod != src_mod:
+                edges.add((src_mod, target_mod))
+        else:
+            inc_dir = os.path.dirname(inc_path)
+            if inc_dir and inc_dir != '.':
+                target_mod = inc_dir.split('/')[-1]
+                if target_mod in module_set and target_mod != src_mod:
+                    edges.add((src_mod, target_mod))
+            else:
+                base = os.path.splitext(os.path.basename(inc_path))[0]
+                if base in module_set and base != src_mod:
+                    edges.add((src_mod, base))
+
+for target, libs in cmake_deps.items():
+    target_mods = []
+    if target in cmake_targets:
+        for src in cmake_targets[target]:
+            src_rel = src.replace(os.sep, '/')
+            mod = module_name(src_rel)
+            if mod and mod in module_set:
+                target_mods.append(mod)
+    if not target_mods:
+        if target in module_set:
+            target_mods = [target]
+        else:
+            for m in module_set:
+                if m.endswith('/' + target) or m == target:
+                    target_mods.append(m)
+                    break
+    for tmod in target_mods:
+        for lib in libs:
+            if lib in module_set:
+                edges.add((tmod, lib))
+            elif any(m.endswith('/' + lib) or m == lib for m in module_set):
+                for m in module_set:
+                    if m.endswith('/' + lib) or m == lib:
+                        edges.add((tmod, m))
+            else:
+                edges.add((tmod, 'ext:' + lib))
+
+for s, d in sorted(edges):
+    sys.stdout.write(s + '\\t' + d + '\\n')
+" | MAX_ARCH="$MAX_ARCH" bash "$NORMALIZE"

package/scripts/C-CPP/lib/limit.sh

@@ -0,0 +1,146 @@
+#!/usr/bin/env bash
+set -uo pipefail
+# limit.sh — Smart output limiter with compact fallbacks
+# TOKEN profile multiplier (override via PMD_TOKEN_PROFILE env var)
+PMD_TOKEN_PROFILE="${PMD_TOKEN_PROFILE:-medium}"
+case "$PMD_TOKEN_PROFILE" in
+  low)    MULT_NUM=1; MULT_DEN=2 ;;
+  medium) MULT_NUM=1; MULT_DEN=1 ;;
+  high)   MULT_NUM=3; MULT_DEN=2 ;;
+  xhigh)  MULT_NUM=2; MULT_DEN=1 ;;
+  unlimited) PMD_UNLIMITED=1 ;;
+  *)      MULT_NUM=1; MULT_DEN=1 ;;
+esac
+
+# Token budget constants (override via PMD_MAX_* env vars, scaled by profile)
+if [ "${PMD_UNLIMITED:-0}" = "1" ]; then
+  MAX_TREE=${PMD_MAX_TREE:-99999}
+  MAX_DEPS=${PMD_MAX_DEPS:-99999}
+  MAX_TODOS=${PMD_MAX_TODOS:-99999}
+  MAX_LOG=${PMD_MAX_LOG:-99999}
+  MAX_BRANCH=${PMD_MAX_BRANCH:-99999}
+  MAX_STATUS=${PMD_MAX_STATUS:-99999}
+  MAX_DIFF=${PMD_MAX_DIFF:-99999}
+  MAX_TYPECHECK=${PMD_MAX_TYPECHECK:-99999}
+  MAX_LINT=${PMD_MAX_LINT:-99999}
+  MAX_TEST=${PMD_MAX_TEST:-99999}
+  MAX_PRISMA=${PMD_MAX_PRISMA:-99999}
+  MAX_EXPRESS=${PMD_MAX_EXPRESS:-99999}
+  MAX_FASTAPI=${PMD_MAX_FASTAPI:-99999}
+  MAX_DJANGO=${PMD_MAX_DJANGO:-99999}
+  MAX_SQLALCHEMY=${PMD_MAX_SQLALCHEMY:-99999}
+  MAX_NEST=${PMD_MAX_NEST:-99999}
+  MAX_NEXTJS=${PMD_MAX_NEXTJS:-99999}
+  MAX_REACT=${PMD_MAX_REACT:-99999}
+  MAX_ANGULAR=${PMD_MAX_ANGULAR:-99999}
+  MAX_CMAKE=${PMD_MAX_CMAKE:-99999}
+  MAX_CLASS=${PMD_MAX_CLASS:-99999}
+  MAX_INTERFACE=${PMD_MAX_INTERFACE:-99999}
+  MAX_INCLUDE=${PMD_MAX_INCLUDE:-99999}
+  MAX_CARGO=${PMD_MAX_CARGO:-99999}
+  MAX_GO_PKGS=${PMD_MAX_GO_PKGS:-99999}
+  MAX_CARGO_FEATURES=${PMD_MAX_CARGO_FEATURES:-99999}
+  MAX_GO_INTERFACES=${PMD_MAX_GO_INTERFACES:-99999}
+  MAX_DOCKER=${PMD_MAX_DOCKER:-99999}
+  MAX_K8S=${PMD_MAX_K8S:-99999}
+  MAX_TF=${PMD_MAX_TF:-99999}
+  MAX_AWS=${PMD_MAX_AWS:-99999}
+  MAX_ARCH=${PMD_MAX_ARCH:-99999}
+  MAX_COMPOSE=${PMD_MAX_COMPOSE:-99999}
+  MAX_CREW=${PMD_MAX_CREW:-99999}
+else
+  MAX_TREE=$(( (${PMD_MAX_TREE:-50} * MULT_NUM) / MULT_DEN ))
+  MAX_DEPS=$(( (${PMD_MAX_DEPS:-40} * MULT_NUM) / MULT_DEN ))
+  MAX_TODOS=$(( (${PMD_MAX_TODOS:-20} * MULT_NUM) / MULT_DEN ))
+  MAX_LOG=$(( (${PMD_MAX_LOG:-20} * MULT_NUM) / MULT_DEN ))
+  MAX_BRANCH=$(( (${PMD_MAX_BRANCH:-20} * MULT_NUM) / MULT_DEN ))
+  MAX_STATUS=$(( (${PMD_MAX_STATUS:-30} * MULT_NUM) / MULT_DEN ))
+  MAX_DIFF=$(( (${PMD_MAX_DIFF:-30} * MULT_NUM) / MULT_DEN ))
+  MAX_TYPECHECK=$(( (${PMD_MAX_TYPECHECK:-30} * MULT_NUM) / MULT_DEN ))
+  MAX_LINT=$(( (${PMD_MAX_LINT:-20} * MULT_NUM) / MULT_DEN ))
+  MAX_TEST=$(( (${PMD_MAX_TEST:-10} * MULT_NUM) / MULT_DEN ))
+  MAX_PRISMA=$(( (${PMD_MAX_PRISMA:-40} * MULT_NUM) / MULT_DEN ))
+  MAX_EXPRESS=$(( (${PMD_MAX_EXPRESS:-30} * MULT_NUM) / MULT_DEN ))
+  MAX_FASTAPI=$(( (${PMD_MAX_FASTAPI:-30} * MULT_NUM) / MULT_DEN ))
+  MAX_DJANGO=$(( (${PMD_MAX_DJANGO:-40} * MULT_NUM) / MULT_DEN ))
+  MAX_SQLALCHEMY=$(( (${PMD_MAX_SQLALCHEMY:-40} * MULT_NUM) / MULT_DEN ))
+  MAX_NEST=$(( (${PMD_MAX_NEST:-30} * MULT_NUM) / MULT_DEN ))
+  MAX_NEXTJS=$(( (${PMD_MAX_NEXTJS:-30} * MULT_NUM) / MULT_DEN ))
+  MAX_REACT=$(( (${PMD_MAX_REACT:-30} * MULT_NUM) / MULT_DEN ))
+  MAX_ANGULAR=$(( (${PMD_MAX_ANGULAR:-30} * MULT_NUM) / MULT_DEN ))
+  MAX_CMAKE=$(( (${PMD_MAX_CMAKE:-40} * MULT_NUM) / MULT_DEN ))
+  MAX_CLASS=$(( (${PMD_MAX_CLASS:-40} * MULT_NUM) / MULT_DEN ))
+  MAX_INTERFACE=$(( (${PMD_MAX_INTERFACE:-30} * MULT_NUM) / MULT_DEN ))
+  MAX_INCLUDE=$(( (${PMD_MAX_INCLUDE:-40} * MULT_NUM) / MULT_DEN ))
+  MAX_CARGO=$(( (${PMD_MAX_CARGO:-40} * MULT_NUM) / MULT_DEN ))
+  MAX_GO_PKGS=$(( (${PMD_MAX_GO_PKGS:-40} * MULT_NUM) / MULT_DEN ))
+  MAX_CARGO_FEATURES=$(( (${PMD_MAX_CARGO_FEATURES:-20} * MULT_NUM) / MULT_DEN ))
+  MAX_GO_INTERFACES=$(( (${PMD_MAX_GO_INTERFACES:-30} * MULT_NUM) / MULT_DEN ))
+  MAX_DOCKER=$(( (${PMD_MAX_DOCKER:-30} * MULT_NUM) / MULT_DEN ))
+  MAX_K8S=$(( (${PMD_MAX_K8S:-20} * MULT_NUM) / MULT_DEN ))
+  MAX_TF=$(( (${PMD_MAX_TF:-40} * MULT_NUM) / MULT_DEN ))
+  MAX_AWS=$(( (${PMD_MAX_AWS:-10} * MULT_NUM) / MULT_DEN ))
+  MAX_ARCH=$(( (${PMD_MAX_ARCH:-100} * MULT_NUM) / MULT_DEN ))
+  MAX_COMPOSE=$(( (${PMD_MAX_COMPOSE:-150} * MULT_NUM) / MULT_DEN ))
+  MAX_CREW=$(( (${PMD_MAX_CREW:-40} * MULT_NUM) / MULT_DEN ))
+fi
+
+TREE_EXCLUDES="${PMD_TREE_EXCLUDES:-node_modules|.git|.pipemd|dist|coverage|build|cmake-build-*|_deps|.cache|compile_commands.json}"
+
+limit_output() {
+  local text="$1"
+  local max="${2:-25}"
+  local fallback="$3"
+  local lines
+  lines=$(echo "$text" | wc -l)
+  if [ "$lines" -le "$max" ]; then
+    echo "$text"
+  else
+    echo "$fallback"
+  fi
+}
+
+limit_tree() {
+  local max="${1:-$MAX_TREE}"
+  local excl="${TREE_EXCLUDES}"
+
+  if command -v tree &>/dev/null; then
+    local out3
+    out3=$(tree -L 3 -I "$excl" --dirsfirst 2>/dev/null)
+    local lines3=$(echo "$out3" | wc -l)
+
+    if [ "$lines3" -le "$max" ]; then
+      echo "$out3"
+      return
+    fi
+
+    local out2
+    out2=$(tree -L 2 -I "$excl" --dirsfirst 2>/dev/null)
+    local lines2=$(echo "$out2" | wc -l)
+
+    if [ "$lines2" -le "$max" ]; then
+      echo "$out2"
+      echo "(${lines3} lines at depth 3, showing depth 2)"
+      return
+    fi
+
+    local out1
+    out1=$(tree -L 1 -I "$excl" --dirsfirst 2>/dev/null)
+    echo "$out1"
+    echo "(${lines3} lines at depth 3, showing depth 1)"
+  else
+    echo "Project structure:"
+    find . -maxdepth 3 \
+      -not -path '*/build/*' \
+      -not -path '*/cmake-build-*/*' \
+      -not -path '*/_deps/*' \
+      -not -path '*/.git/*' \
+      -not -path '*/.pipemd/*' \
+      -not -path '*/.cache/*' \
+      -not -name 'build' \
+      -not -name '.git' \
+      -not -name '.pipemd' \
+      -not -name 'compile_commands.json' \
+      2>/dev/null | head -"$max" | sort
+  fi
+}

package/scripts/C-CPP/project/class-diagram.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+set -uo pipefail
+# Class diagram — Mermaid classDiagram from C++ headers
+source "$(dirname "$0")/../lib/limit.sh"
+
+if ! command -v python3 &>/dev/null; then
+  echo "python3 is required for C++ class diagram extraction"
+  exit 0
+fi
+
+HEADERS=$(find . -type f \( -name "*.h" -o -name "*.hpp" -o -name "*.hxx" \) \
+  -not -path "*/build/*" -not -path "*/.git/*" -not -path "*/cmake-build-*/*" \
+  -not -path "*/_deps/*" -not -path "*/third_party/*" -not -path "*/external/*" \
+  2>/dev/null | head -30)
+
+if [ -z "$HEADERS" ]; then
+  echo "No C++ headers found"
+  exit 0
+fi
+
+echo "$HEADERS" | PMDMAX="${MAX_CLASS:-20}" python3 -c "
+import sys, os, re
+
+MAX = int(os.environ.get('PMDMAX', '20'))
+
+headers = []
+for line in sys.stdin:
+    line = line.strip()
+    if line and os.path.isfile(line):
+        headers.append(line)
+
+if not headers:
+    print('No C++ headers found')
+    sys.exit(0)
+
+classes = {}
+
+class_re = re.compile(r'^\s*(?:class|struct)\s+([A-Za-z_]\w*)\s*(?::\s*(.*?))?\s*\{', re.MULTILINE)
+virt_re  = re.compile(r'^\s*virtual\s+([~]?[\w:&<>, ]+?)\s+\w+\s*\([^)]*\)\s*(?:const)?\s*=\s*0\s*;')
+base_re  = re.compile(r'(?:public|protected|private)\s+([A-Za-z_]\w*)')
+
+for hdr in headers:
+    try:
+        with open(hdr, 'r', errors='replace') as f:
+            content = f.read()
+    except Exception:
+        continue
+
+    content = re.sub(r'//.*', '', content)
+    content = re.sub(r'/\*.*?\*/', '', content, flags=re.DOTALL)
+
+    for m in class_re.finditer(content):
+        name = m.group(1)
+        if name in classes:
+            continue
+        bases_str = m.group(2) or ''
+        bases = [b.strip() for b in base_re.findall(bases_str)]
+
+        start = m.end()
+        depth = 1
+        end = start
+        while end < len(content) and depth > 0:
+            if content[end] == '{':
+                depth += 1
+            elif content[end] == '}':
+                depth -= 1
+            end += 1
+
+        body = content[start:end]
+
+        methods = []
+        for vm in virt_re.finditer(body):
+            methods.append(vm.group(1).strip() + '()')
+
+        classes[name] = {'bases': bases, 'methods': methods[:5], 'file': os.path.basename(hdr)}
+
+if not classes:
+    print('No class/struct definitions found in headers')
+    sys.exit(0)
+
+lines = ['classDiagram']
+count = 0
+for name in sorted(classes.keys(), key=lambda n: (len(classes[n]['bases']), n)):
+    info = classes[name]
+    if count >= MAX:
+        break
+    count += 1
+    lines.append(f'    class {name} {{')
+    for m in info['methods']:
+        lines.append(f'        {m}')
+    lines.append('    }')
+    for base in info['bases']:
+        lines.append(f'    {base} <|-- {name}')
+
+print('\n'.join(lines))
+"