@onlooker-community/ecosystem 0.43.2 → 0.43.3

package/scripts/lint/check-managed-blocks.mjs

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+// Managed-block fence checker.
+//
+// Tools like `bd setup` own the text between a `<!-- BEGIN ... -->` and
+// `<!-- END ... -->` marker pair and rewrite it verbatim on every run. Any
+// `markdownlint --fix` we apply inside such a block is silently undone the next
+// time anyone regenerates it. Because CI runs `lint:check` (markdownlint with
+// no `--fix`), that churn lands as a red build that looks unrelated to whatever
+// the person was actually doing.
+//
+// The fix is to fence each block with markdownlint-disable/enable comments
+// placed *outside* the BEGIN/END markers, so the generator cannot clobber them.
+// This script asserts that every managed block in every tracked markdown file
+// carries such a fence, covering the rules the generated text is known to trip.
+//
+// Exit codes:
+//   0  ok
+//   1  one or more unfenced or malformed managed blocks
+//   2  setup/usage error
+//
+// Flags:
+//   --root <path>   override the repo root (used by the tests)
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Rules the `bd`-generated blocks trip. MD034 fires because the generator
+// writes bare URLs where markdownlint wants angle brackets; MD012 because it
+// leaves consecutive blank lines; MD024 because two different `bd` subcommands
+// each emit a "Beads Issue Tracker" heading into the same file.
+const REQUIRED_RULES = ['MD012', 'MD024', 'MD034'];
+
+const BEGIN_MARKER = /^<!--\s*BEGIN\s+\S.*-->\s*$/;
+const END_MARKER = /^<!--\s*END\s+\S.*-->\s*$/;
+const DISABLE_COMMENT = /^<!--\s*markdownlint-disable\s+(.*?)\s*-->\s*$/;
+const ENABLE_COMMENT = /^<!--\s*markdownlint-enable\s+(.*?)\s*-->\s*$/;
+
+function parseArgs(argv) {
+  const args = { root: null };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--root') {
+      args.root = argv[++i];
+      if (!args.root) usageError('--root requires a path');
+    } else {
+      usageError(`unknown argument: ${argv[i]}`);
+    }
+  }
+  return args;
+}
+
+function usageError(message) {
+  process.stderr.write(`check-managed-blocks: ${message}\n`);
+  process.exit(2);
+}
+
+// Minimal .markdownlintignore support, matching the two pattern shapes the file
+// actually uses: a directory prefix ("node_modules/") and a recursive basename
+// glob ("**/CHANGELOG.md"). Anything else is compared literally. Kept
+// deliberately small -- if the ignore file grows richer patterns, reach for a
+// real glob matcher rather than extending this.
+function loadIgnorePatterns(root) {
+  const ignorePath = join(root, '.markdownlintignore');
+  if (!existsSync(ignorePath)) return [];
+  return readFileSync(ignorePath, 'utf8')
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line !== '' && !line.startsWith('#'));
+}
+
+function isIgnored(relPath, patterns) {
+  for (const pattern of patterns) {
+    if (pattern.endsWith('/')) {
+      if (relPath === pattern.slice(0, -1) || relPath.startsWith(pattern)) return true;
+    } else if (pattern.startsWith('**/')) {
+      const basename = pattern.slice(3);
+      if (relPath === basename || relPath.endsWith(`/${basename}`)) return true;
+    } else if (relPath === pattern) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function trackedMarkdownFiles(root) {
+  let stdout;
+  try {
+    stdout = execFileSync('git', ['ls-files', '-z', '*.md'], { cwd: root, encoding: 'utf8' });
+  } catch (err) {
+    usageError(`could not list tracked files under ${root}: ${err.message}`);
+  }
+  return stdout.split('\0').filter((path) => path !== '');
+}
+
+function rulesFrom(match) {
+  return match[1].split(/\s+/).filter((rule) => rule !== '');
+}
+
+function missingRules(declared) {
+  return REQUIRED_RULES.filter((rule) => !declared.includes(rule));
+}
+
+// Walks one file and reports every managed block that is not correctly fenced.
+function checkFile(relPath, contents, errors) {
+  const lines = contents.split('\n');
+
+  for (let i = 0; i < lines.length; i++) {
+    if (!BEGIN_MARKER.test(lines[i])) continue;
+
+    const beginLine = lines[i];
+    const beginNo = i + 1;
+    const label = `${relPath}:${beginNo}`;
+
+    // Locate the matching END before judging the fence, so an unterminated
+    // block is reported as exactly one error rather than cascading.
+    let endIndex = -1;
+    for (let j = i + 1; j < lines.length; j++) {
+      if (BEGIN_MARKER.test(lines[j])) break; // nested/overlapping: stop looking
+      if (END_MARKER.test(lines[j])) {
+        endIndex = j;
+        break;
+      }
+    }
+
+    if (endIndex === -1) {
+      errors.push(`${label}: managed block "${beginLine.trim()}" has no matching <!-- END ... --> marker`);
+      continue;
+    }
+
+    const before = i > 0 ? lines[i - 1] : '';
+    const disable = before.match(DISABLE_COMMENT);
+    if (!disable) {
+      errors.push(
+        `${label}: managed block is not fenced -- the line directly above it must be ` +
+          `"<!-- markdownlint-disable ${REQUIRED_RULES.join(' ')} -->", found ${JSON.stringify(before)}`,
+      );
+    } else {
+      const missing = missingRules(rulesFrom(disable));
+      if (missing.length > 0) {
+        errors.push(`${label}: markdownlint-disable above this block omits ${missing.join(', ')}`);
+      }
+    }
+
+    const after = endIndex + 1 < lines.length ? lines[endIndex + 1] : '';
+    const enable = after.match(ENABLE_COMMENT);
+    if (!enable) {
+      errors.push(
+        `${relPath}:${endIndex + 1}: managed block is not closed -- the line directly below its END marker ` +
+          `must be "<!-- markdownlint-enable ${REQUIRED_RULES.join(' ')} -->", found ${JSON.stringify(after)}`,
+      );
+    } else {
+      const missing = missingRules(rulesFrom(enable));
+      if (missing.length > 0) {
+        errors.push(`${relPath}:${endIndex + 2}: markdownlint-enable below this block omits ${missing.join(', ')}`);
+      }
+    }
+
+    i = endIndex;
+  }
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const here = dirname(fileURLToPath(import.meta.url));
+  const root = resolve(args.root ?? join(here, '..', '..'));
+
+  if (!existsSync(root)) usageError(`root does not exist: ${root}`);
+
+  const ignorePatterns = loadIgnorePatterns(root);
+  const errors = [];
+  let blockCount = 0;
+  let fileCount = 0;
+
+  for (const relPath of trackedMarkdownFiles(root)) {
+    if (isIgnored(relPath, ignorePatterns)) continue;
+
+    const absPath = join(root, relPath);
+    if (!existsSync(absPath)) continue; // staged deletion; nothing to check
+
+    const contents = readFileSync(absPath, 'utf8');
+    if (!contents.includes('<!--')) continue; // fast path: no comments, no markers
+
+    checkFile(relPath, contents, errors);
+
+    const found = (contents.match(new RegExp(BEGIN_MARKER.source, 'gm')) ?? []).length;
+    if (found > 0) {
+      fileCount++;
+      blockCount += found;
+    }
+  }
+
+  for (const e of errors) process.stderr.write(`error: ${e}\n`);
+
+  if (errors.length > 0) {
+    process.stderr.write(
+      `check-managed-blocks: ${errors.length} error(s) across ${blockCount} managed block(s)\n` +
+        'Fence generated blocks so `bd setup` cannot undo `markdownlint --fix`. See ecosystem-55g.\n',
+    );
+    process.exit(1);
+  }
+
+  process.stdout.write(`check-managed-blocks: ok (${blockCount} managed block(s) in ${fileCount} file(s))\n`);
+}
+
+main();

package/test/bats/assayer-events.bats

@@ -89,7 +89,7 @@ AUDIT_ID="01J0000000000000000000AB34"
 }
 
 @test "emission fails on unknown event type" {
-	run assayer_emit_event "assayer.no.such.event" '{"audit_id":"x"}'
+	expect_emission_rejected assayer_emit_event "assayer.no.such.event" '{"audit_id":"x"}'
 	[ "$status" -ne 0 ]
 }
 

package/test/bats/bursar-events.bats

@@ -68,6 +68,6 @@ _validate_latest_event() {
 }
 
 @test "bursar_emit_event returns nonzero for an unknown event type" {
-	run bursar_emit_event "bursar.no_such_event" '{"project_key":"x"}' "$SID"
+	expect_emission_rejected bursar_emit_event "bursar.no_such_event" '{"project_key":"x"}' "$SID"
 	[ "$status" -ne 0 ]
 }

package/test/bats/cartographer-events.bats

@@ -147,7 +147,7 @@ _finding() {
 	_require_cartographer_schema
 	# Guards the direction of the fix: if someone "restores" the old schema,
 	# this is the test that objects.
-	run cartographer_emit_event "cartographer.issue.found" \
+	expect_emission_rejected cartographer_emit_event "cartographer.issue.found" \
 		'{"issue_type":"orphaned_plugin","file_path":"CLAUDE.md","severity":"warning"}'
 	[ "$status" -ne 0 ]
 }
@@ -257,7 +257,7 @@ _finding() {
 }
 
 @test "emission fails on unknown event type" {
-	run cartographer_emit_event "cartographer.no.such.event" '{"audit_id":"x"}'
+	expect_emission_rejected cartographer_emit_event "cartographer.no.such.event" '{"audit_id":"x"}'
 	[ "$status" -ne 0 ]
 }
 

package/test/bats/echo-events.bats

@@ -111,7 +111,7 @@ TEST_ID="01J000000000000000000000TT"
 }
 
 @test "emission fails on unknown event type" {
-	run echo_emit_event "echo.no.such.event" '{"suite_id":"x"}'
+	expect_emission_rejected echo_emit_event "echo.no.such.event" '{"suite_id":"x"}'
 	[ "$status" -ne 0 ]
 }
 

package/test/bats/emission-report-optout.bats

@@ -0,0 +1,41 @@
+#!/usr/bin/env bats
+
+setup() {
+  source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+  setup_test_env
+
+  PLUGIN_ROOT="${REPO_ROOT}/plugins/warden"
+  export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+  export ONLOOKER_ECOSYSTEM_ROOT="$REPO_ROOT"
+  source "${PLUGIN_ROOT}/scripts/lib/warden-events.sh"
+
+  export ONLOOKER_TEST_REPORT_DIR="${BATS_TEST_TMPDIR}/report"
+  mkdir -p "$ONLOOKER_TEST_REPORT_DIR"
+  REPORT="${ONLOOKER_TEST_REPORT_DIR}/emissions.jsonl"
+}
+
+_valid_payload() {
+  jq -cn '{source_type:"web_fetch", threat_type:"prompt_injection", confidence:0.5}'
+}
+
+# Positive control. Without this, the opt-out test below could pass because
+# nothing writes a report at all, rather than because the helper suppressed it.
+@test "a normal emission does write a report line" {
+  run warden_emit_event "warden.threat.detected" "$(_valid_payload)"
+  [ "$status" -eq 0 ] || return 1
+  [ -s "$REPORT" ]
+}
+
+@test "expect_emission_rejected keeps a deliberate rejection out of the report" {
+  expect_emission_rejected warden_emit_event "warden.bogus.event" "$(_valid_payload)"
+  [ "$status" -ne 0 ] || return 1
+  [ ! -f "$REPORT" ]
+}
+
+@test "expect_emission_rejected restores the report dir afterward" {
+  expect_emission_rejected warden_emit_event "warden.bogus.event" "$(_valid_payload)"
+  [ "$ONLOOKER_TEST_REPORT_DIR" = "${BATS_TEST_TMPDIR}/report" ] || return 1
+  run warden_emit_event "warden.threat.detected" "$(_valid_payload)"
+  [ "$status" -eq 0 ] || return 1
+  [ -s "$REPORT" ]
+}

package/test/bats/governor-events.bats

@@ -233,6 +233,6 @@ AID="bats-agent-000"
 }
 
 @test "governor_emit_event returns nonzero for unknown event type" {
-	run governor_emit_event "governor.no_such_event" '{"session_id":"x"}'
+	expect_emission_rejected governor_emit_event "governor.no_such_event" '{"session_id":"x"}'
 	[ "$status" -ne 0 ]
 }

package/test/bats/inspector-events.bats

@@ -146,7 +146,7 @@ _validate_latest_event() {
 }
 
 @test "emission rejects an unknown event type" {
-	run inspector_emit_event "inspector.no.such.event" '{"file_path":"x"}'
+	expect_emission_rejected inspector_emit_event "inspector.no.such.event" '{"file_path":"x"}'
 	[ "$status" -ne 0 ]
 }
 

package/test/bats/librarian-session-end.bats

@@ -329,7 +329,7 @@ _scan_complete() {
   source "${PLUGIN_ROOT}/scripts/lib/librarian-emit.sh"
   mkdir -p "$(dirname "$ONLOOKER_EVENTS_LOG")"
 
-  librarian_emit "librarian.scan.complete" "sess-bad" \
+  expect_emission_rejected librarian_emit "librarian.scan.complete" "sess-bad" \
     '{"outcome":"gave_up","duration_ms":5}'
 
   # A refused payload never reaches the log, so the file may not exist at all.

package/test/bats/lineage-events.bats

@@ -71,11 +71,11 @@ _validate_latest_event() {
 	local p
 	p=$(jq -n --arg pk "$PK" --arg sid "$SID" \
 		'{project_key:$pk, session_id:$sid, file_path:"x", tool:"NotebookEdit", operation:"edit"}')
-	run lineage_emit_event "lineage.change.recorded" "$p" "$SID"
+	expect_emission_rejected lineage_emit_event "lineage.change.recorded" "$p" "$SID"
 	[ "$status" -ne 0 ]
 }
 
 @test "lineage_emit_event returns nonzero for an unknown event type" {
-	run lineage_emit_event "lineage.no_such_event" '{"project_key":"x"}' "$SID"
+	expect_emission_rejected lineage_emit_event "lineage.no_such_event" '{"project_key":"x"}' "$SID"
 	[ "$status" -ne 0 ]
 }

package/test/bats/tribunal-events.bats

@@ -204,6 +204,6 @@ JUDGE_ID="01J000000000000000000000JJ"
 }
 
 @test "emission fails loudly on bogus event_type (schema rejects)" {
-	run tribunal_emit_event "tribunal.no.such.event" '{"task_id":"x"}'
+	expect_emission_rejected tribunal_emit_event "tribunal.no.such.event" '{"task_id":"x"}'
 	[ "$status" -ne 0 ]
 }

package/test/bats/warden-events.bats

@@ -80,6 +80,6 @@ _validate_latest_event() {
 	# warden.* type must be rejected so typos never reach the log.
 	local p
 	p=$(jq -n '{source_type:"web_fetch", threat_type:"prompt_injection", confidence:0.5}')
-	run warden_emit_event "warden.bogus.event" "$p"
+	expect_emission_rejected warden_emit_event "warden.bogus.event" "$p"
 	[ "$status" -ne 0 ]
 }

package/test/bus-coverage.json

@@ -0,0 +1,131 @@
+{
+  "expected": [
+    "assayer.audit.complete",
+    "assayer.audit.started",
+    "assayer.claim.contradicted",
+    "assayer.claim.unverified",
+    "bursar.rollup.skipped",
+    "bursar.rollup.surfaced",
+    "bursar.session.recorded",
+    "cartographer.audit.complete",
+    "cartographer.issue.found",
+    "cartographer.issue.resolved",
+    "compass.check.passed",
+    "compass.check.skipped",
+    "counsel.brief.generated",
+    "curator.finding.broken_index",
+    "curator.finding.date_decayed",
+    "curator.finding.orphaned_memory",
+    "curator.finding.path_broken",
+    "curator.scan.complete",
+    "curator.scan.started",
+    "echo.improvement.detected",
+    "echo.regression.detected",
+    "echo.suite.complete",
+    "echo.suite.started",
+    "governor.budget.exceeded",
+    "governor.budget.warning",
+    "governor.call.recorded",
+    "governor.child.allocated",
+    "governor.child.returned",
+    "governor.gate.checked",
+    "governor.ledger.write_failed",
+    "governor.lock.stale_cleared",
+    "governor.session.complete",
+    "historian.chunk.dropped",
+    "historian.chunk.sanitized",
+    "historian.embedder.unavailable",
+    "historian.indexing.complete",
+    "historian.indexing.started",
+    "historian.retrieval.complete",
+    "historian.retrieval.started",
+    "historian.retrieval.surfaced",
+    "inspector.check.failed",
+    "inspector.check.passed",
+    "inspector.check.skipped",
+    "inspector.run.completed",
+    "librarian.candidate.dropped",
+    "librarian.candidate.proposed",
+    "librarian.proposal.accepted",
+    "librarian.proposal.rejected",
+    "librarian.scan.complete",
+    "librarian.scan.started",
+    "librarian.tombstone.created",
+    "lineage.change.recorded",
+    "lineage.query.answered",
+    "memory.recalled",
+    "onlooker.artifact.ready",
+    "session.compact",
+    "session.end",
+    "session.prompt",
+    "session.start",
+    "skill.invoked",
+    "task.complete",
+    "task.start",
+    "tool.agent.spawn",
+    "tool.file.read",
+    "tool.shell.exec",
+    "tribunal.actor.complete",
+    "tribunal.actor.start",
+    "tribunal.consensus.reached",
+    "tribunal.dissent.recorded",
+    "tribunal.gate.blocked",
+    "tribunal.gate.passed",
+    "tribunal.iteration.start",
+    "tribunal.judge.start",
+    "tribunal.jury.empaneled",
+    "tribunal.meta.complete",
+    "tribunal.meta.start",
+    "tribunal.session.complete",
+    "tribunal.session.start",
+    "tribunal.verdict",
+    "warden.gate.blocked",
+    "warden.threat.cleared",
+    "warden.threat.detected"
+  ],
+  "excluded": {
+    "archivist.compact.complete": "archivist-extract.sh (the PreCompact hook) never calls archivist_emit_event with this type; only onlooker.artifact.ready is wired up",
+    "archivist.compact.started": "archivist-extract.sh (the PreCompact hook) never calls archivist_emit_event with this type; only onlooker.artifact.ready is wired up",
+    "archivist.extract.complete": "archivist-extract.sh only emits onlooker.artifact.ready; no code path emits archivist.extract.complete yet",
+    "archivist.inject.complete": "archivist-inject.sh (the SessionStart hook) has no archivist_emit_event call at all",
+    "archivist.inject.started": "archivist-inject.sh (the SessionStart hook) has no archivist_emit_event call at all",
+    "compass.check.canceled": "compass has no implementation yet; design phase",
+    "compass.check.failed": "compass has no implementation yet; design phase",
+    "compass.check.overridden": "compass has no implementation yet; design phase",
+    "curator.finding.acknowledged": "curator check deferred; see plugins/curator/README.md",
+    "curator.finding.contradiction": "curator check deferred; see plugins/curator/README.md",
+    "curator.finding.redundant_pair": "curator check deferred; see plugins/curator/README.md",
+    "curator.finding.resolved": "curator check deferred; see plugins/curator/README.md",
+    "curator.finding.symbol_missing": "curator check deferred; see plugins/curator/README.md",
+    "curator.finding.unused_low_signal": "curator check deferred; see plugins/curator/README.md",
+    "curator.finding.url_unchecked": "curator check deferred; see plugins/curator/README.md",
+    "historian.config.warning": "no config-validation-warning branch exists in historian-config.sh; nothing in the plugin emits this type yet",
+    "historian.prune.complete": "historian/README.md lists retention-sweep pruning under Status as deferred to a follow-up landing",
+    "historian.purge.complete": "historian/README.md lists manual purge under Status as deferred to a follow-up landing",
+    "librarian.proposal.merged": "librarian-cli.sh only implements the accept/reject subcommands; the merge-into-X resolution from docs/design.md has no code path",
+    "librarian.proposal.superseded": "librarian-cli.sh only implements the accept/reject subcommands; the supersede-X resolution from docs/design.md has no code path",
+    "meridian.hint.delivered": "plugin lives in another repo",
+    "meridian.hint.generated": "plugin lives in another repo",
+    "meridian.lesson.curated": "plugin lives in another repo",
+    "meridian.outcome.recorded": "plugin lives in another repo",
+    "meridian.playbook.updated": "plugin lives in another repo",
+    "meridian.reliance.measured": "plugin lives in another repo",
+    "onlooker.session.summary": "emitted by the agent, not this repo",
+    "oracle.calibration.complete": "plugin lives in another repo",
+    "oracle.calibration.requested": "plugin lives in another repo",
+    "prompt_rule.applied": "prompt_rules_emit in scripts/lib/prompt-rules.sh writes straight to $ONLOOKER_EVENTS_LOG via jq, bypassing onlooker-event.mjs, so it never reaches the schema-validating emitter this harness observes even though test/bats/prompt-rules.bats exercises it",
+    "prompt_rule.matched": "prompt_rules_emit in scripts/lib/prompt-rules.sh writes straight to $ONLOOKER_EVENTS_LOG via jq, bypassing onlooker-event.mjs, so it never reaches the schema-validating emitter this harness observes even though test/bats/prompt-rules.bats exercises it",
+    "relay.handoff.captured": "plugin lives in another repo",
+    "relay.handoff.injected": "plugin lives in another repo",
+    "scribe.capture.complete": "no scribe_emit_event call for this type exists anywhere in plugins/scribe; only scribe.distill.complete and onlooker.artifact.ready are wired up",
+    "scribe.distill.complete": "the emit call in scripts/lib/scribe-distill.sh is real, but test/bats/scribe-extract.bats only drives the min_turns skip path, which returns before reaching it",
+    "sentinel.allowed": "plugin lives in another repo",
+    "sentinel.blocked": "plugin lives in another repo",
+    "sentinel.reviewed": "plugin lives in another repo",
+    "task.fail": "mapTaskHookInput in scripts/lib/onlooker-event.mjs only derives task.start/task.complete from TaskCreated/TaskCompleted; no branch distinguishes a failed task",
+    "tool.agent.complete": "the Agent/PostToolUse branch in onlooker-event.mjs is real, but test/bats/tool-history-tracker.bats only drives Read and failing-Bash tool inputs, never Agent",
+    "tool.file.edit": "the Edit branch in onlooker-event.mjs is real, but test/bats/tool-history-tracker.bats never drives an Edit tool input",
+    "tool.file.write": "the Write branch in onlooker-event.mjs is real, but test/bats/tool-history-tracker.bats never drives a Write tool input",
+    "tool.web.fetch": "the WebFetch branch in onlooker-event.mjs is real, but test/bats/tool-history-tracker.bats never drives a WebFetch tool input"
+  }
+}

package/test/helpers/setup.bash

@@ -68,3 +68,25 @@ load_validate_path() {
     "$ONLOOKER_COMPACT_TRACKERS_DIR" \
     "$ONLOOKER_METRICS_DIR"
 }
+
+# Run a command that is expected to fail schema validation, without recording
+# the deliberate rejection in the suite-wide emission report.
+#
+# The report exists so a payload that drifts from the schema turns CI red. A
+# test that deliberately emits an invalid payload would otherwise write a
+# valid:false line indistinguishable from real drift, making the gate
+# permanently red from intentional tests. Unsetting the report directory for
+# the duration keeps the negative test honest — it still asserts the emitter
+# rejects — without polluting the gate.
+#
+# Sets $status and $output exactly as bats' `run` does.
+#
+# Usage: expect_emission_rejected <command> [args...]
+expect_emission_rejected() {
+  local saved="${ONLOOKER_TEST_REPORT_DIR:-}"
+  unset ONLOOKER_TEST_REPORT_DIR
+  run "$@"
+  if [ -n "$saved" ]; then
+    export ONLOOKER_TEST_REPORT_DIR="$saved"
+  fi
+}