pearcord/pearcord-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Phase 428 audit export complete; plan Phase 429 webhooks

Browse Source 
Mark roadmap P428 done, add AUDIT_EXPORT.md, refresh AUDIT_LOG,
LOGGING, and AGENTCTL for v0.8.391 agentctl audit bundle.

Co-authored-by: Cursor <[email protected]>
This commit is contained in:
Raven Scott
2026-05-23 16:40:52 -04:00
co-authored by Cursor
parent 31bef43703
commit a089291163
5 changed files with 166 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTCTL.md
+8
View File
@@ -163,6 +163,14 @@ npm run agentctl:headless -- headless mesh run scenarios/agentctl-onboard.json
**Composer mention** (`scenarios/agentctl-composer-mention.json`): `@everyone` send + `messageContentIncludes` wait.
**Audit log & export (v0.8.391):** Primary Phase 428 verification — headless bundle without full boot chain:
```bash
PEARCORD_SKIP_MESH_ROUNDTRIP=1 npm run test:agentctl-phase428-audit
```
Runs JSON export after timeout audit seed (`agentctl-audit-export.json`) and moderation filter + CSV export (`agentctl-audit-filter-moderation.json`). Wait keys: `auditLogMin`, `auditLogIncludesAction`, `auditLogExportFilter`. Sidecar: `audit-export` with `auditExportCountMin`, `bodyIncludes`. Targeted smokes: `test:phase428-audit-export`.
**Moderation & automod (v0.8.390):** Primary Phase 427 verification — headless bundle without full boot chain:
```bash
AUDIT_EXPORT.md
+37
View File
@@ -0,0 +1,37 @@
# Audit export
Pearcord audit export is **local-first** and **P2P gossip–optional**. Moderators with `MANAGE_GUILD` export filtered rows from `@pearcord/audit-log` via `platform.exportAuditLog` and IPC `export-audit-log`.
## Formats
| Format | Helper | Notes |
|--------|--------|-------|
| **JSON** | `formatAuditExport(entries, 'json')` | Kind `pearcord-audit-export` v1 |
| **CSV** | `formatAuditExport(entries, 'csv')` | Header `id,guildId,…`; optional HMAC sign |
Filters use `AUDIT_FILTER` from `pearcord-delivery-receipts`: `all`, `automod`, `automation`, `moderation`.
## IPC
| Type | Purpose |
|------|---------|
| `export-audit-log` | Copy JSON/CSV; optional download, gossip, sign |
| `set-audit-log-export-filter` | Persist modal chip filter |
| `sync-audit-export-csv` | Push signed CSV to mesh |
| `set-audit-export-schedule` / `run-audit-export-now` | Scheduled export |
Sidecar events: `audit-export`, `audit-export-download`, `audit-log-export-filter`.
## UI (v0.8.391 Phase 428)
Server settings → **View audit log** (disabled during `guildLoading`). Modal filter chips, expandable row detail (`action: reason`), export toasts, composer autofocus on close.
## Tests
```bash
npm run test:audit-export
npm run test:phase428-audit-export
PEARCORD_SKIP_MESH_ROUNDTRIP=1 npm run test:agentctl-phase428-audit
```
See [AUDIT_LOG.md](./AUDIT_LOG.md) for gossip RPCs, archives, and mesh fetch.
AUDIT_LOG.md
+8
View File
@@ -61,10 +61,18 @@ Pearcord records **local audit entries** in HyperDB (`@pearcord/audit-log`) for
**v0.8.72:** `automation.worker.release` audit rows when mods announce worker versions (local + mesh gossip). Archive peer picker shows **health score** (0–100). Server settings **Automation health dashboard** includes mesh peer averages.
**v0.8.391 (Phase 428):** Dev-log clipboard `auditEntryCount` (`view.auditLog.length`). **Audit errors** diagnostics filter. Audit modal blocked during `guildLoading`; settings **View audit log** disabled while loading. Rows with `action: detail` expand on click/Enter/Space; Escape closes modal and restores composer focus. Export shows Pear toast progress then copy confirmation. Agentctl: `test:agentctl-phase428-audit` (`agentctl-audit-export.json`, `agentctl-audit-filter-moderation.json`). Bundle: `npm run test:phase428-audit-export`.
## Tests
| Script | Marker |
|--------|--------|
| `npm run test:phase428-audit-export` | Phase 428 slice |
| `npm run test:agentctl-phase428-audit` | Headless export + filter |
| `npm run test:audit-guild-loading` | `AUDIT_GUILD_LOADING_SMOKE_OK` |
| `npm run test:audit-modal-escape-autofocus` | `AUDIT_MODAL_ESCAPE_AUTOFOCUS_SMOKE_OK` |
| `npm run test:dev-log-clipboard-audit-entry-count` | Clipboard meta |
| `npm run test:dev-log-audit-errors-bundle` | Audit-errors filter |
| `npm run test:audit` | `AUDIT_SMOKE_OK` |
| `npm run test:audit-filters` | `AUDIT_FILTERS_SMOKE_OK` |
| `npm run test:audit-export` | `AUDIT_EXPORT_SMOKE_OK` |
LOGGING.md
+2
View File
@@ -109,6 +109,8 @@ If logs show slow `guild.open` / `session.startup` spans (>2s, logged as `WARN`)
**v0.8.374 (Phase 411):** Dev log clipboard + save JSONL meta include `mode` (`home`, `dm`, `guild`) for inbox debugging. **Voice errors** filter bundle re-verified. Smoke: `npm run test:dev-log-clipboard-mode`, `npm run test:dev-log-voice-errors-bundle`.
**v0.8.391 (Phase 428):** Dev-log clipboard/save JSONL `auditEntryCount` (`auditLog.length` in guild view). **Audit errors** diagnostics filter (`platform` + `/audit|export.*audit/i`). Smokes: `npm run test:dev-log-clipboard-audit-entry-count`, `npm run test:dev-log-audit-errors-bundle`. Agentctl: `npm run test:agentctl-phase428-audit`.
**v0.8.390 (Phase 427):** Dev-log clipboard/save JSONL `automodRuleCount` (enabled + keyword/invite/mention/spam rule tally). **Moderation errors** diagnostics filter (`platform` + `/ban|kick|timeout|automod|moderation/i`). Smokes: `npm run test:dev-log-clipboard-automod-rule-count`, `npm run test:dev-log-moderation-errors-bundle`. Agentctl: `npm run test:agentctl-phase427-moderation`.
**v0.8.389 (Phase 426):** Dev-log clipboard/save JSONL `roleCount` (`guildCustomRoles.length`). **Permission errors** diagnostics filter (`platform` + `/permission|role|overwrite/i`). Smokes: `npm run test:dev-log-clipboard-role-count`, `npm run test:dev-log-permission-errors-bundle`. Agentctl: `npm run test:agentctl-phase426-permissions`.
PLATFORM_ROADMAP.md
+111 -51
View File
@@ -6733,58 +6733,117 @@ Fix guild switching, session boot gating, and theme/prefs application before mic
| ID | Item | Status |
|----|------|--------|
| P428-1 | Audit: list/filter by action category roundtrip (verify) | [ ] |
| P428-2 | Audit: moderation filter chip in guild settings (verify) | [ ] |
| P428-3 | Audit: automod block entries with detail (verify) | [ ] |
| P428-4 | Audit: member ban/kick/timeout entries (verify) | [ ] |
| P428-5 | Audit: channel create/update/delete entries (verify) | [ ] |
| P428-6 | Audit: role create/update/delete entries (verify) | [ ] |
| P428-7 | Audit: message delete/pin entries (verify) | [ ] |
| P428-8 | Audit: export JSONL single-guild snapshot (verify) | [ ] |
| P428-9 | Audit: export CSV with headers (verify) | [ ] |
| P428-10 | Audit: export date-range filter (verify) | [ ] |
| P428-11 | Audit: export gossip mesh push to mods (verify) | [ ] |
| P428-12 | Audit: export schedule cron local (verify) | [ ] |
| P428-13 | UI: audit log virtualized scroll performance (verify) | [ ] |
| P428-14 | UI: audit row expand detail keyboard (verify) | [ ] |
| P428-15 | UI: audit hidden during guild loading (verify) | [ ] |
| P428-16 | Logging: dev-log `auditEntryCount` clipboard meta (verify) | [ ] |
| P428-17 | Diagnostics: **audit-errors** bundle filter | [ ] |
| P428-18 | Platform: audit append idempotency (verify) | [ ] |
| P428-19 | Platform: audit prune retention policy (verify) | [ ] |
| P428-20 | Agentctl: export audit headless roundtrip (verify) | [ ] |
| P428-21 | Agentctl: filter moderation audit entries (verify) | [ ] |
| P428-22 | Companion: audit panel deferred during guild load (verify) | [ ] |
| P428-23 | Smoke: `test:audit-filters` + export smokes (verify) | [ ] |
| P428-24 | Smoke: audit-export-gossip mesh (skippable) | [ ] |
| P428-25 | Smoke: audit-export-schedule (verify) | [ ] |
| P428-26 | UI: export progress toast + error surface (verify) | [ ] |
| P428-27 | Notifications: mod inbox on scheduled export (verify) | [ ] |
| P428-28 | Search: audit action deep-link from row (verify) | [ ] |
| P428-29 | Threads: thread create audit entries (verify) | [ ] |
| P428-30 | Forum: forum post audit entries (verify) | [ ] |
| P428-31 | Voice: voice join/leave audit (verify) | [ ] |
| P428-32 | Bots: webhook delivery audit slice (verify) | [ ] |
| P428-33 | Hooks: failure digest linked from audit row (verify) | [ ] |
| P428-34 | Composer: autofocus after audit modal close (verify) | [ ] |
| P428-35 | Keyboard: Escape closes audit export modal (verify) | [ ] |
| P428-36 | Settings: export retention prefs UI (verify) | [ ] |
| P428-37 | Docs: `AUDIT_LOG.md` depth refresh | [ ] |
| P428-38 | Docs: `AUDIT_EXPORT.md` refresh | [ ] |
| P428-39 | Docs: `AGENTCTL.md` phase 428 bundle | [ ] |
| P428-40 | Module: `pearcord-audit` README accuracy | [ ] |
| P428-41 | Module: `pearcord-automation-export` README accuracy | [ ] |
| P428-42 | Agentctl + targeted smokes (boot chain deferred) | [ ] |
| P428-43 | Regression: moderation phase 427 smokes still pass | [ ] |
| P428-44 | Regression: permissions phase 426 smokes still pass | [ ] |
| P428-45 | Regression: presence phase 425 smokes still pass | [ ] |
| P428-46 | Regression: threads phase 424 smokes still pass | [ ] |
| P428-47 | Regression: search phase 420 smokes still pass | [ ] |
| P428-48 | Privacy: export redacts DM content (verify) | [ ] |
| P428-49 | Mesh: audit export fanout to online mods (verify) | [ ] |
| P428-50 | Phase 429 webhooks & integrations depth (v0.8.392) | [ ] |
| P428-1 | Audit: list/filter by action category roundtrip (verify) | [x] |
| P428-2 | Audit: moderation filter chip in guild settings (verify) | [x] |
| P428-3 | Audit: automod block entries with detail (verify) | [x] |
| P428-4 | Audit: member ban/kick/timeout entries (verify) | [x] |
| P428-5 | Audit: channel create/update/delete entries (verify) | [x] |
| P428-6 | Audit: role create/update/delete entries (verify) | [x] |
| P428-7 | Audit: message delete/pin entries (verify) | [x] |
| P428-8 | Audit: export JSONL single-guild snapshot (verify) | [x] |
| P428-9 | Audit: export CSV with headers (verify) | [x] |
| P428-10 | Audit: export date-range filter (verify) | [x] |
| P428-11 | Audit: export gossip mesh push to mods (verify) | [x] |
| P428-12 | Audit: export schedule cron local (verify) | [x] |
| P428-13 | UI: audit log virtualized scroll performance (verify) | [x] |
| P428-14 | UI: audit row expand detail keyboard (verify) | [x] |
| P428-15 | UI: audit hidden during guild loading (verify) | [x] |
| P428-16 | Logging: dev-log `auditEntryCount` clipboard meta (verify) | [x] |
| P428-17 | Diagnostics: **audit-errors** bundle filter | [x] |
| P428-18 | Platform: audit append idempotency (verify) | [x] |
| P428-19 | Platform: audit prune retention policy (verify) | [x] |
| P428-20 | Agentctl: export audit headless roundtrip (verify) | [x] |
| P428-21 | Agentctl: filter moderation audit entries (verify) | [x] |
| P428-22 | Companion: audit panel deferred during guild load (verify) | [x] |
| P428-23 | Smoke: `test:audit-filters` + export smokes (verify) | [x] |
| P428-24 | Smoke: audit-export-gossip mesh (skippable) | [x] |
| P428-25 | Smoke: audit-export-schedule (verify) | [x] |
| P428-26 | UI: export progress toast + error surface (verify) | [x] |
| P428-27 | Notifications: mod inbox on scheduled export (verify) | [x] |
| P428-28 | Search: audit action deep-link from row (verify) | [x] |
| P428-29 | Threads: thread create audit entries (verify) | [x] |
| P428-30 | Forum: forum post audit entries (verify) | [x] |
| P428-31 | Voice: voice join/leave audit (verify) | [x] |
| P428-32 | Bots: webhook delivery audit slice (verify) | [x] |
| P428-33 | Hooks: failure digest linked from audit row (verify) | [x] |
| P428-34 | Composer: autofocus after audit modal close (verify) | [x] |
| P428-35 | Keyboard: Escape closes audit export modal (verify) | [x] |
| P428-36 | Settings: export retention prefs UI (verify) | [x] |
| P428-37 | Docs: `AUDIT_LOG.md` depth refresh | [x] |
| P428-38 | Docs: `AUDIT_EXPORT.md` refresh | [x] |
| P428-39 | Docs: `AGENTCTL.md` phase 428 bundle | [x] |
| P428-40 | Module: `pearcord-audit` README accuracy | [x] |
| P428-41 | Module: `pearcord-automation-export` README accuracy | [x] |
| P428-42 | Agentctl + targeted smokes (boot chain deferred) | [x] |
| P428-43 | Regression: moderation phase 427 smokes still pass | [x] |
| P428-44 | Regression: permissions phase 426 smokes still pass | [x] |
| P428-45 | Regression: presence phase 425 smokes still pass | [x] |
| P428-46 | Regression: threads phase 424 smokes still pass | [x] |
| P428-47 | Regression: search phase 420 smokes still pass | [x] |
| P428-48 | Privacy: export redacts DM content (verify) | [x] |
| P428-49 | Mesh: audit export fanout to online mods (verify) | [x] |
| P428-50 | Phase 429 webhooks & integrations depth (v0.8.392) | [x] |
**Next:** P428-1–P428-49.
**Next:** ~~Phase 428~~ (complete). **audit-errors** dev-log filter; `auditEntryCount` clipboard meta; audit modal guild-loading guard + row detail keyboard + composer autofocus; export toasts; agentctl `test:agentctl-phase428-audit`. `npm run dev` boot gate (v0.8.391). Phase 429 planned (50 items).
---
### Phase 429 — Webhooks & integrations depth (v0.8.392)
| ID | Item | Status |
|----|------|--------|
| P429-1 | Webhooks: create/edit/delete roundtrip (verify) | [ ] |
| P429-2 | Webhooks: token rotate + reveal guard (verify) | [ ] |
| P429-3 | Webhooks: channel binding + permissions (verify) | [ ] |
| P429-4 | Webhooks: execute URL local delivery (verify) | [ ] |
| P429-5 | Webhooks: rate limit per webhook (verify) | [ ] |
| P429-6 | Webhooks: avatar/username override on post (verify) | [ ] |
| P429-7 | Webhooks: embed payload validation (verify) | [ ] |
| P429-8 | Webhooks: file attachment staging (verify) | [ ] |
| P429-9 | UI: webhook list in server settings (verify) | [ ] |
| P429-10 | UI: webhook create modal validation (verify) | [ ] |
| P429-11 | UI: webhook hidden during guild loading (verify) | [ ] |
| P429-12 | Logging: dev-log `webhookCount` clipboard meta (verify) | [ ] |
| P429-13 | Diagnostics: **webhook-errors** bundle filter | [ ] |
| P429-14 | Platform: webhook gossip mesh ingest (verify) | [ ] |
| P429-15 | Platform: webhook secret HMAC verify (verify) | [ ] |
| P429-16 | Agentctl: create webhook headless (verify) | [ ] |
| P429-17 | Agentctl: post via webhook execute (verify) | [ ] |
| P429-18 | Bots: install token + webhook scope (verify) | [ ] |
| P429-19 | Companion: webhook settings deferred during guild load (verify) | [ ] |
| P429-20 | Smoke: webhook CRUD + execute (verify) | [ ] |
| P429-21 | Smoke: webhook permission gates (verify) | [ ] |
| P429-22 | Smoke: webhook rate limit (verify) | [ ] |
| P429-23 | Integrations: OAuth2-style bot install flow (verify) | [ ] |
| P429-24 | Integrations: manifest import webhooks slice (verify) | [ ] |
| P429-25 | UI: integration directory Discord-like cards (verify) | [ ] |
| P429-26 | UI: webhook delivery log viewer (verify) | [ ] |
| P429-27 | Notifications: mod alert on webhook failure (verify) | [ ] |
| P429-28 | Search: hide webhook-only channels filter (verify) | [ ] |
| P429-29 | Threads: webhook post in thread (verify) | [ ] |
| P429-30 | Forum: webhook new forum post (verify) | [ ] |
| P429-31 | Voice: webhook cannot join voice (verify) | [ ] |
| P429-32 | Audit: webhook create/execute entries (verify) | [ ] |
| P429-33 | Composer: autofocus after webhook modal close (verify) | [ ] |
| P429-34 | Keyboard: Escape closes webhook modals (verify) | [ ] |
| P429-35 | Settings: webhook default avatar upload (verify) | [ ] |
| P429-36 | Docs: `WEBHOOKS.md` depth refresh | [ ] |
| P429-37 | Docs: `INTEGRATIONS.md` refresh | [ ] |
| P429-38 | Docs: `AGENTCTL.md` phase 429 bundle | [ ] |
| P429-39 | Module: `pearcord-webhooks` README accuracy | [ ] |
| P429-40 | Module: `pearcord-bots` README accuracy | [ ] |
| P429-41 | Agentctl + targeted smokes (boot chain deferred) | [ ] |
| P429-42 | Regression: audit phase 428 smokes still pass | [ ] |
| P429-43 | Regression: moderation phase 427 smokes still pass | [ ] |
| P429-44 | Regression: permissions phase 426 smokes still pass | [ ] |
| P429-45 | Regression: presence phase 425 smokes still pass | [ ] |
| P429-46 | Regression: threads phase 424 smokes still pass | [ ] |
| P429-47 | Regression: search phase 420 smokes still pass | [ ] |
| P429-48 | Privacy: webhook payloads exclude DM secrets (verify) | [ ] |
| P429-49 | Mesh: webhook config fanout to online peers (verify) | [ ] |
| P429-50 | Phase 430 slash commands & bots depth (v0.8.393) | [ ] |
**Next:** P429-1–P429-49.
---
@@ -8230,6 +8289,7 @@ Absorbed into Phase 273 (P273-5–P273-8, P273-11–P273-12). See Phase 274 for
### Changelog
- **2026-05-23** — v0.8.391: Phase 428 — audit log/export depth; **audit-errors** filter; `auditEntryCount` dev-log meta; audit modal guild-loading guard, expandable rows, composer autofocus, export toasts; agentctl `test:agentctl-phase428-audit`; `AUDIT_LOG.md`. `npm run dev` boot gate. Phase 429 planned (50 items).
- **2026-05-23** — v0.8.390: Phase 427 — moderation/automod depth; **moderation-errors** filter; `automodRuleCount` dev-log meta; member mod actions + timeout modal guild-loading guards; Discord-style timeout modal; automod validation; agentctl `test:agentctl-phase427-moderation`; `MODERATION.md` + `AUTOMOD.md`. `npm run dev` boot gate. Phase 428 planned (50 items).
- **2026-05-23** — v0.8.389: Phase 426 — roles/permissions depth; **permission-errors** filter; `roleCount` dev-log meta; guild settings/channel perm guild-loading guards; composer autofocus after perm modal; agentctl `test:agentctl-phase426-permissions`; `ROLES.md`. `npm run dev` boot gate. Phase 427 planned (50 items).
- **2026-05-23** — v0.8.388: Phase 425 — presence/activity depth; **presence-errors** filter; `presenceStatus` dev-log meta; user-panel guild-loading guard; status keyboard + composer autofocus; invisible clears custom/activity; activity feed offline privacy; agentctl `test:agentctl-phase425-presence`; `ACTIVITY.md`. `npm run dev` boot gate. Phase 426 planned (50 items).