@aporthq/aport-agent-guardrails 1.0.8

package/docs/ADDING_A_FRAMEWORK.md

@@ -0,0 +1,87 @@
+# Adding a new framework
+
+This doc describes how to add a new framework so that **passport and config logic are shared** and only framework-specific steps live in the new code. Goal: **<50 lines of bash** plus a config template.
+
+## 1. Shared layer (no copying)
+
+All frameworks use:
+
+- **`bin/lib/common.sh`** — logging, `ROOT_DIR`, `require_cmd`
+- **`bin/lib/passport.sh`** — `run_passport_wizard` (delegates to `bin/aport-create-passport.sh`)
+- **`bin/lib/config.sh`** — `get_config_dir`, `write_config_template` (creates framework config dir and copies `bin/lib/templates/config.yaml` if present)
+- **`bin/lib/detect.sh`** — optional; add your project files so the dispatcher can detect the framework
+
+Do **not** duplicate passport or config logic in the new framework script.
+
+## 2. Add a framework script (<50 lines)
+
+Create **`bin/frameworks/<name>.sh`** (e.g. `bin/frameworks/myframework.sh`):
+
+1. Source lib: `common.sh`, `passport.sh`, `config.sh`
+2. Call `run_passport_wizard "$@"`
+3. Call `write_config_template <name>` to create the config dir (and optional `config.yaml`)
+4. Print **next steps** (snippet + doc link)
+
+Example (same pattern as LangChain/CrewAI/n8n):
+
+```bash
+#!/usr/bin/env bash
+# MyFramework installer/setup
+
+LIB="$(cd "$(dirname "${BASH_SOURCE[0]:-.}")/../lib" && pwd)"
+source "$LIB/common.sh"
+source "$LIB/passport.sh"
+source "$LIB/config.sh"
+
+run_setup() {
+  log_info "Setting up APort guardrails for MyFramework..."
+  run_passport_wizard "$@"
+  config_dir="$(write_config_template myframework)"
+  echo ""
+  echo "  Next steps (MyFramework):"
+  echo "  1. Config written to: $config_dir"
+  echo "  2. ... (framework-specific snippet)"
+  echo "  See: docs/frameworks/myframework.md"
+  echo ""
+}
+
+run_setup "$@"
+```
+
+Add **`get_config_dir`** support in `bin/lib/config.sh` for your framework name and default path (e.g. `$HOME/.aport/myframework`).
+
+## 3. Add integration directory
+
+Create **`integrations/<name>/`** with:
+
+- **README.md** — What this integration does; where the real implementation lives (e.g. `python/myframework_adapter/`, or “plugin in `extensions/`”).
+- **Middleware / plugin / examples** — Framework-specific code or pointers. Can be stubs that reference the actual package (e.g. `python/langchain_adapter/`).
+
+Optionally add **`bin/lib/templates/<name>.yaml`** if your framework needs a different config template; otherwise the shared `config.yaml` in `bin/lib/templates/` is copied by `write_config_template` for supported frameworks.
+
+## 4. Wire up the dispatcher
+
+- In **`bin/agent-guardrails`**, the dispatcher runs `bin/frameworks/<framework>.sh` when `--framework=<name>` or the first arg is `<name>`. Adding `bin/frameworks/myframework.sh` is enough for `--framework=myframework`.
+- If you want **detection from the project directory**, add your project files (e.g. `myframework.toml`) to **`bin/lib/detect.sh`** in `detect_frameworks_list` / `detect_framework`.
+
+## 5. Add a framework doc and tests
+
+- **`docs/frameworks/<name>.md`** — Setup, config location, suspend (kill switch) = passport status, next steps.
+- **Integration test:** In **`tests/frameworks/<name>/setup.sh`**, run the CLI (e.g. `APORT_FRAMEWORK=myframework` or `--framework=myframework` with non-interactive inputs) and assert the expected config directory and files exist.
+
+## Checklist
+
+- [ ] `bin/frameworks/<name>.sh` &lt;50 lines; only sources lib + wizard + config + next steps
+- [ ] `bin/lib/config.sh`: `get_config_dir` handles `<name>`; `write_config_template` can create its dir (template copy is automatic if `bin/lib/templates/config.yaml` exists)
+- [ ] `integrations/<name>/README.md` (and optional middleware/examples)
+- [ ] `docs/frameworks/<name>.md`
+- [ ] `tests/frameworks/<name>/setup.sh` (run CLI, assert config)
+
+## Reference: existing frameworks
+
+| Framework  | Script (lines) | Integration dir        | Notes                          |
+|-----------|----------------|-------------------------|--------------------------------|
+| OpenClaw  | 19 (delegates) | integrations/openclaw/  | Full installer in `bin/openclaw` |
+| LangChain | 30             | integrations/langchain/ | Python middleware in python/   |
+| CrewAI    | 31             | integrations/crewai/    | Python decorator in python/    |
+| n8n       | 28             | integrations/n8n/        | Custom node / HTTP + credentials |

package/docs/AGENTS.md.example

@@ -0,0 +1,40 @@
+# OpenClaw Agent Configuration
+
+<!-- This block is auto-installed by `make openclaw-setup` into workspace/AGENTS.md. It instructs the agent to call the guardrail before effectful actions. That is best-effort (LLM may not follow). Deterministic enforcement requires OpenClaw to call the guardrail via a before_tool_call hook or core integration; see docs/OPENCLAW_COMPATIBILITY.md and docs/APORT_OPENCLAW_INTEGRATION_PROPOSAL.md. -->
+
+## Pre-Action Authorization (APort Guardrails) ✅ REQUIRED
+
+**CRITICAL RULE**: Before executing ANY tool that has side effects, you MUST verify authorization through APort Agent Guardrails.
+
+### Required Steps (in order):
+
+1. **Check Passport Status** (guardrail does this first; passport is source of truth)
+   - The guardrail checks passport `status` before any policy. If `status` is not `active` (e.g. `suspended` or `revoked`), it denies with `oap.passport_suspended`. No separate kill-switch file.
+
+2. **Call APort Verification**
+   - Run: `~/.openclaw/.skills/aport-guardrail.sh <tool_name> '<context_json>'`
+   - Context JSON should include: tool parameters, resource identifiers, operation details
+
+3. **Read Decision**
+   - Read `~/.openclaw/decision.json`
+   - If `allow: false`: **STOP EXECUTION**, return denial reasons to user
+   - If `allow: true`: Proceed with tool execution, log receipt ID
+
+4. **Failure Behavior**
+   - APort script fails: DENY (fail-closed for security)
+   - Passport invalid: DENY with clear error message
+
+5. **Never reuse a previous decision**
+   - **Always invoke the tool** when the user requests an action. Do not skip or assume a tool will be denied because a previous invocation was denied.
+   - APort is re-evaluated on every tool call; passport or limits may have changed. When using the APort plugin, it never reuses a cached decision—each call gets a fresh verify.
+
+---
+
+## Effectful Tools (Require Verification)
+
+- **Git Operations**: `git.create_pr`, `git.merge`, `git.push`
+- **System Commands**: `exec.run`, `exec.*`, `system.*`
+- **Messaging**: `message.send`, `messaging.*`
+- **Data Operations**: `database.write`, `data.export`
+
+See full documentation: https://github.com/aporthq/aport-agent-guardrails

package/docs/CODE_REVIEW.md

@@ -0,0 +1,192 @@
+# Staff-Level Code Review: APort Agent Guardrails
+
+**Aligned with:** [FRAMEWORK_SUPPORT_PLAN.md](launch/FRAMEWORK_SUPPORT_PLAN.md)  
+**Reviewer lens:** Staff Engineer, infra, security. No sugarcoating.  
+**Date:** 2026-02-17  
+
+**Verification:** The "FIXED" items below are present in the current codebase (evaluator.ts fail-closed, res.ok, per-invocation decision file, realpath, chmod 600, toolToPackId in adapters, CrewAI cache, CI Jest, Python cursor choice, docs). See [2026-02-18-staff-review.md](reviews/2026-02-18-staff-review.md) for re-verification, **security re-score (100/100)**, and any outstanding findings.
+
+---
+
+## Executive summary
+
+The codebase delivers a multi-framework guardrail (Node + Python, OpenClaw/Cursor/LangChain/CrewAI) with a shared passport wizard and evaluator. **Production-critical bugs exist** (fail-open when misconfigured, `verifySync` API path/body wrong for full policy pack). Duplication (DRY), unused code, and inconsistent docs hold the score down. With the fixes and improvements below, reaching **100/100** is achievable.
+
+**Overall score: 62/100**
+
+---
+
+## 1. Bugs
+
+| # | Severity | Location | Description |
+|---|----------|----------|-------------|
+| B1 | **Critical** | — | **FIXED.** Evaluator (Node and Python) is now **fail-closed by default**: when no passport path or guardrail script is found, returns `{ allow: false, reasons: [{ code: 'oap.misconfigured', ... }] }`. Legacy allow behavior: set `fail_open_when_missing_config: true` in config or `APORT_FAIL_OPEN_WHEN_MISSING_CONFIG=1`. |
+| B2 | **High** | `packages/core/src/core/evaluator.ts` `verifySync()` | **Wrong API path and body for full policy pack** — **FIXED.** `verifySync` now uses `pathId = isFullPolicyPack(policy) ? IN_BODY_PACK_ID : packId` in the URL and sets `body.context.policy_id` accordingly. |
+| B3 | Medium | — | **FIXED.** Python LangChain and CrewAI use `decision.get("allow", False)`. |
+| B4 | Low | — | **FIXED.** Cursor `activate()`/`deactivate()` documented as “Reserved for future VS Code extension.” |
+
+---
+
+## 2. Performance issues
+
+| # | Location | Description |
+|---|----------|-------------|
+| P1 | — | **FIXED.** Node CrewAI uses a module-level cached Evaluator (`getCrewaiEvaluator()`). |
+| P2 | — | **FIXED.** Python CrewAI uses `_get_crewai_evaluator()` (module-level cached Evaluator). |
+| P3 | `packages/core/src/core/evaluator.ts` `verifySync()` (L284–298) | Sync API path writes two temp files and spawns `node -e` to run async fetch. Overhead per call (disk I/O, process spawn). Acceptable as a bridge but should be documented; consider a native sync HTTP client or worker thread in the future. |
+
+---
+
+## 3. Incorrect or inadequate documentation
+
+| # | Location | Issue |
+|---|----------|--------|
+| D1 | — | **FIXED.** README documents fail-closed and `fail_open_when_missing_config` / env. |
+| D2 | — | **FIXED.** JSDoc on `verifySync` describes sync bridge (temp files + spawn). |
+| D3 | — | **FIXED.** Framework adapter files have “Reserved for programmatic use; CLI dispatch is bin/agent-guardrails (bash).” |
+| D4 | — | **FIXED.** docs/frameworks/cursor.md documents hook script path and guardrail resolution. |
+| D5 | — | **FIXED.** FRAMEWORK_SUPPORT_PLAN and DEPLOYMENT_READINESS updated (fail-closed, cursor stubs). |
+| D6 | — | **FIXED.** `build_tool_context` in Python core `__all__` and exported. |
+
+---
+
+## 4. Unused code
+
+| # | Location | Description |
+|---|----------|-------------|
+| U1 | — | **Documented.** cli.ts comment: “Real dispatch is bash: bin/agent-guardrails; reserved for future programmatic use.” |
+| U2 | — | **Documented.** Framework adapters have “Reserved for programmatic use; CLI uses bin/agent-guardrails.” |
+| U3 | — | **Documented.** base.ts comment references CLI. |
+| U4 | — | **Deprecated.** src/evaluator.js has @deprecated notice; use @aporthq/aport-agent-guardrails-core. |
+| U5 | — | **Documented.** integrations/README.md points to packages; stub files kept for compatibility. |
+| U6 | — | **Documented.** Cursor activate/deactivate documented as reserved for future VS Code extension. |
+
+---
+
+## 5. Slop / junior-level code
+
+| # | Location | Issue |
+|---|----------|--------|
+| S1 | — | **FIXED.** Single `expandUser()` in `packages/core/src/core/pathUtils.ts`; config, passport, evaluator import it. |
+| S2 | — | **FIXED.** Single source: `tool-pack-mapping.json` in packages/core (and copy in Python). Node: `toolPackMapping.ts` loads JSON and exports `toolToPackId`; Python: `tool_pack_mapping.py` loads same JSON. Evaluator and adapters use it. |
+| S3 | — | **FIXED.** Single source: `default-passport-paths.json` in packages/core (and copy in Python). Node: `defaultPassportPaths.ts`; Python: `default_passport_paths.py`. bin/lib/config.sh comment references the JSON. |
+| S4 | — | **FIXED.** Adapters derive pack ID from tool name (toolToPackId / tool_to_pack_id); pass capability per tool. Previously: Hardcoded `capability: 'system.command.execute.v1'` (or equivalent). The evaluator already maps tool name → pack ID internally; the passed “policy” is only used for IN_BODY. The hardcoded capability is misleading (suggests all tools are evaluated as exec). Either derive from tool name in the adapter or document that the evaluator ignores this for path selection. |
+| S5 | — | **FIXED.** Catch blocks have brief comments (malformed decision, invalid passport, temp cleanup). |
+| S6 | — | **FIXED.** Python `_call_api_sync` validates agent_id/passport before building body. |
+
+---
+
+## 6. Criteria-based score (20+ criteria)
+
+Each criterion scored 0–5 (0 = absent/bad, 5 = excellent). Total raw sum then normalized to 0–100.
+
+| # | Criterion | Score | Notes |
+|----|-----------|-------|--------|
+| 1 | **DRY (Don’t Repeat Yourself)** | 2 | expandUser x3, toolToPackId x2, default paths x3, buildToolContext vs build_tool_context. |
+| 2 | **Separation of concerns** | 3 | Evaluator does config load + path resolution + API + local; could split resolver, API client, local runner. |
+| 3 | **Single source of truth** | 2 | Passport paths, tool→pack mapping, and “what is the CLI” spread across bash, TS, Python. |
+| 4 | **Fail-safe default (security)** | 1 | Default is fail-open when config/passport missing. Must be fail-closed or explicitly configurable. |
+| 5 | **Input validation** | 3 | Some validation (e.g. passport empty, context shape); API body construction in verifySync not fully aligned with API spec. |
+| 6 | **Error handling** | 2 | Silent catch, generic messages; no structured error codes or logging strategy. |
+| 7 | **Test coverage** | 3 | Core and LangChain have unit tests; CrewAI/Cursor minimal; no E2E for Node. |
+| 8 | **Documentation (code)** | 2 | JSDoc/docstrings partial; fail-open and verifySync bridge undocumented. |
+| 9 | **Documentation (user)** | 4 | README and framework docs improved; deployment readiness doc is clear. |
+| 10 | **API consistency (Node vs Python)** | 4 | Verify/verifySync and context shape aligned; minor differences (e.g. exception types). |
+| 11 | **Dependency hygiene** | 4 | Reasonable; no obvious bloat. |
+| 12 | **No dead code** | 1 | cli.ts, framework adapters, src/evaluator.js, cursor activate/deactivate. |
+| 13 | **Performance awareness** | 2 | New Evaluator per call in CrewAI; sync bridge spawns process; no caching documented. |
+| 14 | **Security (secrets)** | 4 | API key from config/env; temp files for sync path not obviously world-readable but not explicitly restricted. |
+| 15 | **Security (injection)** | 4 | Context passed as JSON; no obvious shell/command injection in TS; bash scripts use jq. |
+| 16 | **Maintainability** | 3 | Structure is clear; duplication and unused code increase maintenance cost. |
+| 17 | **Naming and clarity** | 4 | Names generally clear; some abbreviations (ctx, packId). |
+| 18 | **Logging and observability** | 2 | Little structured logging; audit in bash only. |
+| 19 | **Configuration** | 4 | Config file + env; framework-specific paths documented. |
+| 20 | **Versioning and compatibility** | 4 | OAP v1.0 referenced; version in packages. |
+| 21 | **Accessibility of public API** | 3 | build_tool_context not in __all__; cursor exports unused stubs. |
+| 22 | **Alignment with plan** | 3 | FRAMEWORK_SUPPORT_PLAN says “no stubs”; cursor has stubs. Implementation status table is otherwise accurate. |
+
+**Raw sum:** 67 / 110 → **Normalized to 100:** 67 × (100/110) ≈ **61**. Rounded up with partial credit: **62/100**.
+
+---
+
+## 7. How to get to 100/100
+
+### 7.1 Critical (must fix)
+
+1. **Fail-closed by default**  
+   When no passport path or no guardrail script is found, return `{ allow: false, reasons: [{ code: 'oap.misconfigured', message: '...' }] }`. Add a config/env option (e.g. `fail_open_when_missing_config: true`) for backward compatibility and document it. Update tests and DEPLOYMENT_READINESS.
+
+2. **Fix verifySync API path and body**  
+   In `packages/core/src/core/evaluator.ts` `verifySync()`:  
+   - Compute `pathId = isFullPolicyPack(policy) ? IN_BODY_PACK_ID : packId`.  
+   - Use `pathId` in the URL.  
+   - Set `body.context.policy_id` to `pathId !== IN_BODY_PACK_ID ? pathId : (policy?.id ?? '')`.  
+   Add a unit test that verifies IN_BODY request shape when policy is full pack.
+
+### 7.2 High (should fix)
+
+3. **Remove or implement dead code**  
+   - Either remove `packages/core/src/cli.ts` or make it delegate to the same flow as the bash CLI.  
+   - Remove or document `packages/core/src/frameworks/*.ts` adapters (and base class if unused).  
+   - Remove or deprecate `src/evaluator.js` with a clear note.  
+   - Cursor: remove `activate`/`deactivate` from exports or implement them and remove TODO.
+
+4. **DRY: shared path and tool→pack logic**  
+   - Single `expandUser` (or path helper) in Node core; use it from config, passport, evaluator.  
+   - Single source for default passport paths (e.g. one JSON or TS constant imported by evaluator and documented for bash).  
+   - Single source for tool→pack mapping: e.g. export `toolToPackId` from core and use in adapters; or maintain a JSON map and generate/read from both Node and Python.
+
+5. **Performance: reuse Evaluator in CrewAI**  
+   - Node: allow passing an optional `Evaluator` instance into `beforeToolCall`, or use a module-level cached Evaluator (with clear lifecycle).  
+   - Python: same (cached evaluator or injectable).  
+   - Document that creating one Evaluator per flow is recommended.
+
+6. **Documentation**  
+   - Document fail-open vs fail-closed and the new option.  
+   - Document verifySync sync bridge (temp files, spawn).  
+   - Add `build_tool_context` to Python core `__all__`.  
+   - Update FRAMEWORK_SUPPORT_PLAN to mention cursor stubs and fail-open behavior until fixed.
+
+### 7.3 Medium (improves score)
+
+7. **Python middleware**  
+   Use `decision.get("allow", False)` (or explicit check) when key is missing.
+
+8. **Logging**  
+   Replace silent catch blocks with at least debug-level logging or a single “evaluator_error” code path.
+
+9. **Integration stubs**  
+   Remove `integrations/langchain/middleware.ts` and `integrations/crewai/decorator.py` if redundant; point docs to the real packages.
+
+10. **Tests**  
+    - Add test for verifySync with full policy pack (IN_BODY path and body shape).  
+    - Add E2E or integration test for Node LangChain/CrewAI with real config.
+
+### 7.4 Polish (100/100)
+
+11. **Structured errors**  
+    Define error codes (e.g. `oap.misconfigured`, `oap.api_error`) and use them consistently; consider a small error hierarchy.
+
+12. **Observability**  
+    Optional audit/log callback or event in the Node evaluator (mirroring bash audit.log) for production debugging.
+
+13. **Cursor hook path**  
+    Document that the hook must run from the npm package root (or from a path where `bin/aport-guardrail-bash.sh` is available).
+
+14. **Plan and docs**  
+    After fixes, set FRAMEWORK_SUPPORT_PLAN and DEPLOYMENT_READINESS to “fail-closed by default” and “no dead code in shipped packages.”
+
+---
+
+## 8. Summary table
+
+| Category        | Count | Severity / impact |
+|----------------|-------|-------------------|
+| Bugs           | 4     | 1 critical, 1 high, 2 medium/low |
+| Performance    | 3     | Evaluator per call; sync bridge overhead |
+| Doc issues     | 6     | Fail-open, verifySync, unused code, __all__ |
+| Unused code    | 6     | cli.ts, adapters, evaluator.js, stubs |
+| Slop / junior  | 6     | DRY, tool→pack, paths, silent catch |
+| Criteria score | 22    | 62/100 overall |
+
+**Path to 100:** Fix B1 (fail-closed), B2 (verifySync), remove or implement dead code (U1–U6), DRY (expandUser, toolToPackId, paths), CrewAI Evaluator reuse, document behavior and API, add tests and logging. Then re-score; remaining points are polish (errors, observability, plan alignment).

package/docs/DEPLOYMENT_READINESS.md

@@ -0,0 +1,81 @@
+# Deployment readiness — what’s production vs roadmap
+
+**Purpose:** Single source of truth for what is safe to deploy today vs what is stub, partial, or planned. Use this for launch checklists, automation (e.g. OpenClaw Agent), and support.
+
+**Related:** [USER_STORIES.md](launch/USER_STORIES.md) (acceptance criteria and test coverage), [FRAMEWORK_ROADMAP.md](FRAMEWORK_ROADMAP.md) (supported frameworks and install). For plan-vs-reality alignment (TypeScript core and Node adapters), see [FRAMEWORK_SUPPORT_PLAN.md § Implementation status](launch/FRAMEWORK_SUPPORT_PLAN.md#implementation-status-current-vs-plan).
+
+---
+
+## What `npx @aporthq/aport-agent-guardrails langchain` (or crewai) actually does
+
+When you run **`npx @aporthq/aport-agent-guardrails`** and choose **LangChain** or **CrewAI**, the **Node** CLI runs only the **bash** framework script (`bin/frameworks/langchain.sh` or `crewai.sh`). That script:
+
+1. Runs the **shared passport wizard** (same as OpenClaw/Cursor).
+2. Writes **framework-specific config** (e.g. `~/.aport/langchain/config.yaml`).
+3. Prints **next steps** (install Python package and run `aport-langchain setup` or `aport-crewai setup`).
+
+It does **not** run Python or install any pip package. The **guardrail** (the code that blocks tool calls when policy denies) is provided by:
+
+- **Python:** `pip install aport-agent-guardrails-langchain` / `aport-agent-guardrails-crewai` (on PyPI). **Node:** `@aporthq/aport-agent-guardrails`, `-core`, `-langchain`, `-crewai`, `-cursor` — published to npm via **release CI** on tag push (see [RELEASE.md](RELEASE.md)).
+
+---
+
+## 1. Safe to deploy today
+
+Everything below is **ready to deploy**: CI (`.github/workflows/release.yml`) publishes to npm and PyPI on tag push; tests and docs are in place.
+
+| Area | What works | Notes |
+|------|------------|--------|
+| **Release CI** | `.github/workflows/release.yml` on push of tag `v*` | Builds workspace packages; publishes **root** + **core**, **langchain**, **crewai**, **cursor** to npm; publishes **Python** to PyPI; creates GitHub Release. Version check (tag vs root package.json) before publish. n8n package not published yet (coming soon). |
+| **Root npm package** | `@aporthq/aport-agent-guardrails` | CLI: `bin/agent-guardrails`, framework installers (bash), docs. Published by CI on tag. |
+| **Node/TypeScript core** | `packages/core` — evaluator (API + local bash, native fetch in sync path), config (YAML), passport, pathUtils | Fail-closed by default when passport/script missing; `fail_open_when_missing_config` or `APORT_FAIL_OPEN_WHEN_MISSING_CONFIG=1` for legacy. Jest tests (config, passport, evaluator). Published by CI on tag as `@aporthq/aport-agent-guardrails-core`. |
+| **Node LangChain adapter** | `packages/langchain` — `APortGuardrailCallback`, `GuardrailViolationError` | Jest tests (allow/deny, error shape). Published by CI as `@aporthq/aport-agent-guardrails-langchain`. |
+| **Node CrewAI adapter** | `packages/crewai` — `beforeToolCall`, `registerAPortGuardrail`, `withAPortGuardrail` | Feature parity with Python. Published by CI as `@aporthq/aport-agent-guardrails-crewai`. |
+| **Node Cursor package** | `packages/cursor` — `Evaluator`, `getHookPath()` | Re-exports core; runtime is bash hook from CLI. Published by CI as `@aporthq/aport-agent-guardrails-cursor`. |
+| **OpenClaw plugin + wizard** | `bin/openclaw`, `extensions/openclaw-aport/`, passport wizard, local/API evaluator | Full setup: config, plugin install, skill wrappers. Deterministic `before_tool_call` enforcement. |
+| **Bash guardrail** | `bin/aport-guardrail-bash.sh`, `bin/aport-create-passport.sh` | OAP v1.0 wizard, fail-closed guardrail, audit + decision chain. Used by OpenClaw plugin and Cursor hook. |
+| **Cursor hook** | `bin/frameworks/cursor.sh`, `bin/aport-cursor-hook.sh` | Installer writes `~/.cursor/hooks.json`; hook enforces policy; unit + integration tests. User must restart Cursor after install. |
+| **Python LangChain adapter** | `python/langchain_adapter`, `aport-agent-guardrails-langchain` (PyPI), `aport-langchain setup` | Callback handler, shared evaluator, examples, E2E in CI. Published by CI to PyPI. |
+| **Python CrewAI adapter** | `python/crewai_adapter`, `aport-agent-guardrails-crewai` (PyPI), `aport-crewai setup` | Before-tool-call hook, decorator, shared evaluator, examples, E2E in CI. Published by CI to PyPI. |
+| **Dispatcher CLI** | `bin/agent-guardrails`, `bin/lib/detect.sh`, `bin/frameworks/*.sh` | Framework detection, `--framework=`, shared wizard/config; delegates to OpenClaw full installer or framework scripts. |
+| **Docs** | `docs/frameworks/*.md`, README, RELEASE.md, FRAMEWORK_ROADMAP.md | Guardrails vs Core, setup and library usage per framework (Python and Node). |
+
+---
+
+## 2. Not deploy-ready (stub, partial, or missing)
+
+| Area | Current state | Impact |
+|------|----------------|--------|
+| **n8n integration** | **Coming soon.** CLI accepts `--framework=n8n` (runs wizard + config only); **@aporthq/aport-agent-guardrails-n8n is not published to npm** until the custom node is ready. Docs and `docs/frameworks/n8n.md` state coming soon. | Custom node and runtime not yet implemented. |
+| **Framework installers (LangChain/CrewAI/n8n)** | `bin/frameworks/langchain.sh`, `crewai.sh`, `n8n.sh` run wizard + write config only; they do **not** run `pip install` or install n8n nodes | User must manually install Python or Node adapter and run framework setup. |
+| **Python CLI (`aport`)** | `python/aport_guardrails/cli.py` — prints next-step commands per framework; does not run wizard | Python-only users run the printed commands (npx or pip) for full setup. |
+| **Shared bash refactor** | Wizard/config logic still largely in `bin/openclaw`; `bin/lib/passport.sh` re-calls `aport-create-passport.sh` | Story B “<50-line framework scripts” holds for langchain/crewai/n8n scripts; OpenClaw path remains the full installer. |
+
+---
+
+## 3. Alignment with USER_STORIES.md
+
+- **Stories A–E** describe the **bash dispatcher**, **shared lib**, **Python adapters** (LangChain, CrewAI), and **Cursor**. Implementation status is accurate: detection, `--framework=`, wizard, config, Python packages, Cursor hook, and tests are in place.
+- **Node/TypeScript:** Core, langchain, crewai, and cursor are **implemented** and **ready to deploy**: CI publishes them to npm on tag push. Core and langchain have Jest unit tests; crewai and cursor have feature parity with Python. n8n is **coming soon** (CLI runs wizard + config only; package not published).
+
+---
+
+## 4. Recommended wording for docs and support
+
+- **OpenClaw:** “Production-ready: plugin, wizard, local/API, full installer.”
+- **Cursor:** “Production-ready: hook installer and script; restart Cursor after install.”
+- **LangChain / CrewAI:** “Production-ready **via Python packages**: `pip install aport-agent-guardrails-langchain` (or crewai) and `aport-<framework> setup`. The one-line CLI (`npx @aporthq/aport-agent-guardrails langchain`) runs the passport wizard and writes config; you still install the Python package and run setup yourself.”
+- **n8n:** "Coming soon. CLI accepts --framework=n8n (wizard + config only). Custom node and runtime integration in progress."
+- **Node/TypeScript packages:** “Core, LangChain, CrewAI, and Cursor packages are ready to deploy; CI publishes them to npm on tag push. Install with `npm install @aporthq/aport-agent-guardrails-core` (and `-langchain`, `-crewai`, `-cursor` as needed).”
+
+---
+
+## 5. Optional improvements (not blocking deploy)
+
+1. **Framework installers** that install or verify the relevant package (e.g. `pip install aport-agent-guardrails-langchain` or check and prompt).
+2. **n8n:** Deliver custom node (and credentials schema); until then n8n remains coming soon.
+3. **Python CLI:** Wire `aport setup` to the same wizard/flow as the bash CLI or document that full setup is via `npx @aporthq/aport-agent-guardrails` + framework-specific pip/setup.
+4. **Integration/E2E tests** for Node packages (optional; unit tests for core and langchain are in place).
+
+
+**Production-ready today:** OpenClaw, Cursor, Python LangChain/CrewAI, **and** the Node CLI + Node packages (root, core, langchain, crewai, cursor) — all deployed via CI on tag push.