docs: add reporting governance install guide
This commit is contained in:
Eve
492
plugins/reporting-governance/INSTALL.md
Normal file
492
plugins/reporting-governance/INSTALL.md
Normal file
@@ -0,0 +1,492 @@
|
||||
# @openclaw/plugin-reporting-governance Installation Guide for AI Agents
|
||||
|
||||
> Goal: let another AI agent install, verify, and consume the current package **without guessing**.
|
||||
|
||||
This guide is intentionally narrow and aligned to the package's **current** state:
|
||||
|
||||
- package name: `@openclaw/plugin-reporting-governance`
|
||||
- version: `0.1.0-mainline`
|
||||
- package root in this repo: `plugins/reporting-governance/`
|
||||
- current public API is controlled by `package.json#exports`
|
||||
- current proof path is the **watchdog reference chain** and its package smoke/tests
|
||||
|
||||
---
|
||||
|
||||
## 1. What this package is right now
|
||||
|
||||
This package is a **pre-1.0 reporting-governance plugin slice**.
|
||||
|
||||
It currently gives you:
|
||||
|
||||
- a real npm package boundary
|
||||
- a narrow public JS export surface
|
||||
- package-owned capability/profile/schema artifacts
|
||||
- runnable adapter entrypoints for the OpenClaw watchdog reference chain
|
||||
- smoke and test coverage proving:
|
||||
- tarball packing works
|
||||
- clean-consumer install works
|
||||
- public exports/bin work
|
||||
- watchdog/orchestrator truth model stays honest
|
||||
|
||||
It does **not** yet give you:
|
||||
|
||||
- a stable 1.0 API
|
||||
- a full production installer
|
||||
- a generalized governance framework for every runtime decision
|
||||
- permission to deep-import arbitrary `src/*` files
|
||||
|
||||
---
|
||||
|
||||
## 2. Prerequisites
|
||||
|
||||
Assume the following before installing:
|
||||
|
||||
### Required
|
||||
|
||||
- **Node.js**: modern Node with ESM + `node --test` support
|
||||
- the repo runtime shown during this task is Node `v22.22.1`
|
||||
- safest assumption: use Node 20+; Node 22 is known-good here
|
||||
- **npm** available in PATH
|
||||
- access to this repo or to a tarball produced from `plugins/reporting-governance/`
|
||||
|
||||
### For repo-local verification
|
||||
|
||||
If working inside this repository, assume:
|
||||
|
||||
- repo root contains the package at `plugins/reporting-governance/`
|
||||
- package dependencies can be installed with `npm --prefix plugins/reporting-governance install`
|
||||
|
||||
### For clean-consumer verification
|
||||
|
||||
You need:
|
||||
|
||||
- permission to create a temporary directory
|
||||
- ability to run `npm pack` and `npm install <tarball>`
|
||||
|
||||
### What you do **not** need to assume
|
||||
|
||||
Do **not** assume:
|
||||
|
||||
- an OpenClaw daemon is running
|
||||
- Telegram credentials are configured
|
||||
- live sender delivery is available
|
||||
- cron is installed or configured
|
||||
- repo-root wrapper scripts are the package API
|
||||
|
||||
The current smoke/tests are intentionally built so that dry-run/pending states are acceptable and truthful.
|
||||
|
||||
---
|
||||
|
||||
## 3. Install paths: choose the right mode
|
||||
|
||||
There are two practical install modes.
|
||||
|
||||
### Mode A — work in this repo/package directly
|
||||
|
||||
Use this when you are validating or developing the package in-place.
|
||||
|
||||
Package directory:
|
||||
|
||||
```bash
|
||||
cd /home/alice/.openclaw/workspace/.worktrees/reporting-governance-plugin
|
||||
npm --prefix plugins/reporting-governance install
|
||||
```
|
||||
|
||||
### Mode B — install as a packed dependency into a clean consumer
|
||||
|
||||
Use this when you need proof that the package works through its shipped boundary only.
|
||||
|
||||
From repo root:
|
||||
|
||||
```bash
|
||||
cd /home/alice/.openclaw/workspace/.worktrees/reporting-governance-plugin/plugins/reporting-governance
|
||||
npm pack
|
||||
```
|
||||
|
||||
That produces a tarball like:
|
||||
|
||||
```text
|
||||
openclaw-plugin-reporting-governance-0.1.0-mainline.tgz
|
||||
```
|
||||
|
||||
Then in a separate consumer directory:
|
||||
|
||||
```bash
|
||||
mkdir -p /tmp/reporting-governance-consumer
|
||||
cd /tmp/reporting-governance-consumer
|
||||
npm init -y
|
||||
npm install /home/alice/.openclaw/workspace/.worktrees/reporting-governance-plugin/plugins/reporting-governance/openclaw-plugin-reporting-governance-0.1.0-mainline.tgz
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Exact install steps for the current repo state
|
||||
|
||||
## A. Repo-local install
|
||||
|
||||
From repo root:
|
||||
|
||||
```bash
|
||||
cd /home/alice/.openclaw/workspace/.worktrees/reporting-governance-plugin
|
||||
npm --prefix plugins/reporting-governance install
|
||||
```
|
||||
|
||||
Expected result:
|
||||
|
||||
- installs package dependencies declared in `plugins/reporting-governance/package.json`
|
||||
- creates/updates `plugins/reporting-governance/node_modules/`
|
||||
- does **not** mean the package is globally installed
|
||||
|
||||
## B. Repo-local smoke run
|
||||
|
||||
From repo root:
|
||||
|
||||
```bash
|
||||
cd /home/alice/.openclaw/workspace/.worktrees/reporting-governance-plugin
|
||||
npm --prefix plugins/reporting-governance run smoke
|
||||
```
|
||||
|
||||
What this currently does:
|
||||
|
||||
- runs `node ./scripts/package-smoke.mjs --compact`
|
||||
- creates a temporary workspace unless `--workspace` is supplied
|
||||
- generates a profile artifact from `profiles-src/strict-manager-mode.yaml`
|
||||
- runs the orchestrator adapter in `dryRun: true`
|
||||
- returns JSON only
|
||||
|
||||
Current success shape to expect:
|
||||
|
||||
- top-level `ok: true`
|
||||
- `tool: "reporting-governance-package-smoke"`
|
||||
- `orchestrator.ok: true`
|
||||
- `orchestrator.dispatchedCount: 1`
|
||||
- `orchestrator.pendingCount: 1`
|
||||
- `orchestrator.notificationCount: 1`
|
||||
|
||||
Do **not** require a final external delivery ack for this smoke path.
|
||||
|
||||
## C. Full package test run
|
||||
|
||||
From repo root:
|
||||
|
||||
```bash
|
||||
cd /home/alice/.openclaw/workspace/.worktrees/reporting-governance-plugin
|
||||
npm --prefix plugins/reporting-governance test
|
||||
```
|
||||
|
||||
This currently runs the package's declared `node --test` suite, including:
|
||||
|
||||
- package structure
|
||||
- descriptor entrypoint resolution
|
||||
- policy evaluator
|
||||
- compatibility preflight
|
||||
- profile artifact / generator
|
||||
- decision runner / decision store
|
||||
- governance contract integration
|
||||
- watchdog chain integration
|
||||
- orchestrator execution
|
||||
- runtime-integrated flow
|
||||
- exports boundary enforcement
|
||||
- packed consumer install smoke
|
||||
|
||||
## D. Clean-consumer install proof
|
||||
|
||||
If you specifically need install proof through the distributed tarball boundary:
|
||||
|
||||
```bash
|
||||
cd /home/alice/.openclaw/workspace/.worktrees/reporting-governance-plugin/plugins/reporting-governance
|
||||
npm pack
|
||||
mkdir -p /tmp/reporting-governance-consumer
|
||||
cd /tmp/reporting-governance-consumer
|
||||
npm init -y
|
||||
npm install /home/alice/.openclaw/workspace/.worktrees/reporting-governance-plugin/plugins/reporting-governance/openclaw-plugin-reporting-governance-0.1.0-mainline.tgz
|
||||
```
|
||||
|
||||
Then verify public exports:
|
||||
|
||||
```bash
|
||||
node --input-type=module --eval '
|
||||
import * as plugin from "@openclaw/plugin-reporting-governance";
|
||||
import { runOrchestratorAdapter } from "@openclaw/plugin-reporting-governance/adapters/orchestrator";
|
||||
process.stdout.write(JSON.stringify({
|
||||
packageName: plugin.packageName,
|
||||
hasRunWatchdogChain: typeof plugin.runWatchdogChain,
|
||||
hasRunOrchestratorAdapter: typeof runOrchestratorAdapter
|
||||
}, null, 2));
|
||||
'
|
||||
```
|
||||
|
||||
Expected shape:
|
||||
|
||||
```json
|
||||
{
|
||||
"packageName": "@openclaw/plugin-reporting-governance",
|
||||
"hasRunWatchdogChain": "function",
|
||||
"hasRunOrchestratorAdapter": "function"
|
||||
}
|
||||
```
|
||||
|
||||
Then verify the installed bin:
|
||||
|
||||
```bash
|
||||
./node_modules/.bin/reporting-governance-package-smoke --compact
|
||||
```
|
||||
|
||||
Expected shape:
|
||||
|
||||
- valid JSON output
|
||||
- `ok: true`
|
||||
- `orchestrator.ok: true`
|
||||
|
||||
---
|
||||
|
||||
## 5. Exact verification commands
|
||||
|
||||
Use these commands exactly for the current package state.
|
||||
|
||||
### Minimal smoke
|
||||
|
||||
```bash
|
||||
npm --prefix plugins/reporting-governance run smoke
|
||||
```
|
||||
|
||||
### Full package suite
|
||||
|
||||
```bash
|
||||
npm --prefix plugins/reporting-governance test
|
||||
```
|
||||
|
||||
### Focused pack/install/export proof
|
||||
|
||||
```bash
|
||||
node --test plugins/reporting-governance/test/exports-boundary.integration.test.mjs plugins/reporting-governance/test/packed-consumer-install.smoke.test.mjs
|
||||
```
|
||||
|
||||
### Focused runtime proof
|
||||
|
||||
```bash
|
||||
node --test plugins/reporting-governance/test/watchdog-chain.integration.test.mjs plugins/reporting-governance/test/runtime-integrated.integration.test.mjs
|
||||
```
|
||||
|
||||
### Public export probe in current repo
|
||||
|
||||
```bash
|
||||
node --input-type=module --eval '
|
||||
import * as plugin from "./plugins/reporting-governance/src/index.mjs";
|
||||
process.stdout.write(JSON.stringify({
|
||||
packageName: plugin.packageName,
|
||||
packageVersion: plugin.packageVersion,
|
||||
hasEvaluatePolicyPack: typeof plugin.evaluatePolicyPack,
|
||||
hasRunWatchdogChain: typeof plugin.runWatchdogChain
|
||||
}, null, 2));
|
||||
'
|
||||
```
|
||||
|
||||
Note: this last command is a **repo-source probe**, not proof of package export boundaries. Use the consumer/tarball tests for boundary proof.
|
||||
|
||||
---
|
||||
|
||||
## 6. Safe import/use map
|
||||
|
||||
These are the **safe public JS entrypoints** today, because they are declared in `package.json#exports`.
|
||||
|
||||
### Root export
|
||||
|
||||
```js
|
||||
import {
|
||||
packageName,
|
||||
packageVersion,
|
||||
evaluatePolicyPack,
|
||||
evaluatePolicies,
|
||||
planDecisionExecution,
|
||||
executeGovernanceContract,
|
||||
executeRuntimeIntegratedGovernance,
|
||||
runCompatibilityPreflight,
|
||||
createRuntimeBinding,
|
||||
runWatchdogAdapter,
|
||||
runDispatcherAdapter,
|
||||
runBridgeSupervisorAdapter,
|
||||
runSenderBindingAdapter,
|
||||
runOrchestratorAdapter,
|
||||
runWatchdogChain,
|
||||
createDecisionRecordArtifact,
|
||||
createDecisionRecordFileName,
|
||||
createFileDecisionStore,
|
||||
validateDecisionRecordArtifact,
|
||||
} from '@openclaw/plugin-reporting-governance';
|
||||
```
|
||||
|
||||
### Adapter barrel
|
||||
|
||||
```js
|
||||
import {
|
||||
runWatchdogAdapter,
|
||||
runDispatcherAdapter,
|
||||
runBridgeSupervisorAdapter,
|
||||
runSenderBindingAdapter,
|
||||
runOrchestratorAdapter,
|
||||
} from '@openclaw/plugin-reporting-governance/adapters';
|
||||
```
|
||||
|
||||
### Declared leaf adapter subpaths
|
||||
|
||||
```js
|
||||
import { runWatchdogAdapter } from '@openclaw/plugin-reporting-governance/adapters/watchdog';
|
||||
import { runDispatcherAdapter } from '@openclaw/plugin-reporting-governance/adapters/dispatcher';
|
||||
import { runBridgeSupervisorAdapter } from '@openclaw/plugin-reporting-governance/adapters/bridge-supervisor';
|
||||
import { runSenderBindingAdapter } from '@openclaw/plugin-reporting-governance/adapters/sender-binding';
|
||||
import { runOrchestratorAdapter } from '@openclaw/plugin-reporting-governance/adapters/orchestrator';
|
||||
```
|
||||
|
||||
### Declared script-like subpath
|
||||
|
||||
```js
|
||||
import '@openclaw/plugin-reporting-governance/package-smoke';
|
||||
```
|
||||
|
||||
This subpath points to the package smoke script entry file, but in most cases you should prefer the CLI/bin or npm script rather than importing it as a library dependency.
|
||||
|
||||
---
|
||||
|
||||
## 7. Unsafe imports: do not assume these are supported
|
||||
|
||||
Do **not** treat these as stable package API:
|
||||
|
||||
```js
|
||||
import '.../src/core/policy-evaluator.mjs';
|
||||
import '.../src/storage/profile-artifact.mjs';
|
||||
import '.../src/adapters/runtime-binding.mjs';
|
||||
```
|
||||
|
||||
And do **not** do this from a consumer:
|
||||
|
||||
```js
|
||||
import '@openclaw/plugin-reporting-governance/src/storage/profile-artifact.mjs';
|
||||
```
|
||||
|
||||
Current tests explicitly enforce that some deep paths are **not exported**, including:
|
||||
|
||||
- `@openclaw/plugin-reporting-governance/src/storage/profile-artifact.mjs`
|
||||
- `@openclaw/plugin-reporting-governance/src/adapters/runtime-binding.mjs`
|
||||
|
||||
If you need a capability that exists only behind private files, treat it as **not yet public**.
|
||||
|
||||
---
|
||||
|
||||
## 8. Current boundaries and what not to assume
|
||||
|
||||
Another AI agent should keep these boundaries explicit.
|
||||
|
||||
### Do not assume stable API beyond declared exports
|
||||
|
||||
This is still:
|
||||
|
||||
- version `0.1.0-mainline`
|
||||
- pre-1.0
|
||||
- surface-tightening
|
||||
|
||||
### Do not assume full runtime enforcement
|
||||
|
||||
Current strongest path is:
|
||||
|
||||
```text
|
||||
watchdog -> queue -> dispatcher -> bridge -> sender binding -> pending/blocked/acked truth
|
||||
```
|
||||
|
||||
This does **not** mean every governance decision in the project is already wired into generalized runtime interception.
|
||||
|
||||
### Do not assume external send success
|
||||
|
||||
The package is intentionally honest about partial completion. In current smoke/integration flows, a result that stays pending is often the **correct** result.
|
||||
|
||||
### Do not assume repo-private files are package API
|
||||
|
||||
Files existing under `src/`, `storage/`, or package-local docs do not automatically become public imports.
|
||||
|
||||
### Do not assume docs/ or state/ are shipped in tarball
|
||||
|
||||
The tarball tests explicitly reject obvious junk in the packed artifact, including:
|
||||
|
||||
- nested `.tgz`
|
||||
- `state/`
|
||||
- `docs/`
|
||||
- `node_modules/`
|
||||
|
||||
So if you need something at runtime, confirm it ships in `files` and/or is reachable through declared exports.
|
||||
|
||||
---
|
||||
|
||||
## 9. Where to use this package safely
|
||||
|
||||
Use it safely in these ways today:
|
||||
|
||||
### Safe use case A — verification/CI
|
||||
|
||||
Use the package to prove:
|
||||
|
||||
- package export boundaries
|
||||
- tarball installability
|
||||
- profile artifact generation path
|
||||
- watchdog notification truth behavior
|
||||
|
||||
### Safe use case B — reference runtime composition
|
||||
|
||||
Use `runOrchestratorAdapter(...)` or `runWatchdogChain(...)` as the current package-home entry to the OpenClaw watchdog reference chain.
|
||||
|
||||
### Safe use case C — governance core experiments behind root exports
|
||||
|
||||
Use root-exported functions such as:
|
||||
|
||||
- `evaluatePolicyPack(...)`
|
||||
- `planDecisionExecution(...)`
|
||||
- `executeGovernanceContract(...)`
|
||||
- `executeRuntimeIntegratedGovernance(...)`
|
||||
- `runCompatibilityPreflight(...)`
|
||||
|
||||
Only if you accept the current pre-1.0 compatibility posture.
|
||||
|
||||
### Avoid for now
|
||||
|
||||
Avoid treating it as:
|
||||
|
||||
- a fully generalized governance SDK
|
||||
- a production deployment installer
|
||||
- a stable long-term public API without version pinning and revalidation
|
||||
|
||||
---
|
||||
|
||||
## 10. Recommended reading order for an AI agent
|
||||
|
||||
If you need to understand before changing anything:
|
||||
|
||||
1. `plugins/reporting-governance/package.json`
|
||||
2. `plugins/reporting-governance/README.md`
|
||||
3. this file: `plugins/reporting-governance/INSTALL.md`
|
||||
4. `plugins/reporting-governance/src/reference/openclaw-watchdog-chain.md`
|
||||
5. `plugins/reporting-governance/test/exports-boundary.integration.test.mjs`
|
||||
6. `plugins/reporting-governance/test/packed-consumer-install.smoke.test.mjs`
|
||||
7. `plugins/reporting-governance/test/runtime-integrated.integration.test.mjs`
|
||||
|
||||
That order keeps you aligned to actual shipped boundary + actual verification.
|
||||
|
||||
---
|
||||
|
||||
## 11. One-command checklist for current repo state
|
||||
|
||||
From repo root:
|
||||
|
||||
```bash
|
||||
npm --prefix plugins/reporting-governance install && npm --prefix plugins/reporting-governance test && npm --prefix plugins/reporting-governance run smoke
|
||||
```
|
||||
|
||||
Interpretation:
|
||||
|
||||
- if install succeeds
|
||||
- and tests pass
|
||||
- and smoke returns `ok: true`
|
||||
|
||||
then the current package is installed and verified at the level this repo currently promises.
|
||||
|
||||
That is the correct claim.
|
||||
|
||||
A stronger claim such as "production-ready installer complete" would be inaccurate.
|
||||
@@ -103,6 +103,12 @@ npm --prefix plugins/reporting-governance test
|
||||
npm --prefix plugins/reporting-governance run smoke
|
||||
```
|
||||
|
||||
若你是另一個 AI agent，要照目前 package 真實邊界安裝/驗證，請直接讀：
|
||||
|
||||
- `plugins/reporting-governance/INSTALL.md`
|
||||
|
||||
這份文件會對齊目前 `exports`、smoke、tarball install test、以及「哪些不能假設」的邊界。
|
||||
|
||||
#### 當作程式依賴使用
|
||||
|
||||
優先只依賴：
|
||||
@@ -180,6 +186,10 @@ Run tests:
|
||||
npm test
|
||||
```
|
||||
|
||||
For an exact AI-agent-facing install/verify flow, read:
|
||||
|
||||
- `plugins/reporting-governance/INSTALL.md`
|
||||
|
||||
### Practical install/use guidance
|
||||
|
||||
Use public exports only:
|
||||
|
||||
Reference in New Issue
Block a user