@webpresso/agent-kit 0.21.0

package/dist/esm/audit/hook-surface.d.ts

@@ -0,0 +1,82 @@
+/**
+ * `wp audit hook-surface` — enforces the single-rewriter-per-matcher invariant.
+ *
+ * From Anthropic's official hooks docs (May 2026):
+ *   "When multiple PreToolUse hooks return updatedInput to rewrite a tool's
+ *   arguments, the last one to finish wins. Since hooks run in parallel, the
+ *   order is non-deterministic. Avoid having more than one hook modify the
+ *   same tool's input."
+ *
+ * This audit collects hooks from:
+ *   - ~/.claude/settings.json          (user-level)
+ *   - $CLAUDE_PROJECT_DIR/.claude/settings.json  (project-level)
+ *
+ * It classifies each hook as a **rewriter** or a **validator**, then flags any
+ * event+matcher combination that has more than one rewriter registered.
+ *
+ * Known rewriters (hardcoded, expandable):
+ *   - `rtk hook claude` → Bash rewriter
+ *   - any hook path ending in `pretooluse.mjs` that is NOT a passthrough
+ */
+import type { RepoAuditResult } from './repo-guardrails.js';
+/** A normalised hook entry carrying runtime, event, command, and optional matcher. */
+export type HookEntry = {
+    readonly runtime: string;
+    readonly event: string;
+    readonly command: string;
+    readonly matcher?: string;
+};
+/** A drift violation: the same owner+command appears >1 time for the same runtime+event. */
+export type DriftViolation = {
+    readonly key: string;
+    readonly count: number;
+    readonly entries: readonly HookEntry[];
+};
+export interface HookSurfaceViolation {
+    readonly event: string;
+    readonly matcher: string;
+    readonly rewriters: readonly string[];
+    readonly reason: string;
+}
+export interface HookSurfaceDetails {
+    readonly ok: boolean;
+    readonly violations: readonly HookSurfaceViolation[];
+}
+export interface HookSurfaceResult {
+    readonly passed: boolean;
+    readonly kind: 'hook-surface';
+    readonly details: HookSurfaceDetails;
+}
+/**
+ * Determines the canonical owner of a hook command using priority-ordered
+ * pattern matching. Returns one of: 'webpresso', 'context-mode', 'omx',
+ * 'rtk', 'gstack', or 'unknown'.
+ */
+export declare function extractOwner(command: string): string;
+/**
+ * Detects drift violations where the same owner+command appears more than once
+ * for the same runtime+event combination. Cross-owner same-event composition
+ * is NOT a violation — only same-owner/same-command duplication is.
+ *
+ * Pure function — no filesystem I/O.
+ */
+export declare function detectDrift(entries: readonly HookEntry[]): DriftViolation[];
+export interface HookSurfaceOptions {
+    /** Repository root. Falls back to CLAUDE_PROJECT_DIR env var when omitted. */
+    readonly projectDir?: string;
+    /**
+     * Override path to the user-level settings file.
+     * Defaults to ~/.claude/settings.json.
+     * Useful in tests to avoid reading real user settings.
+     */
+    readonly userSettingsPath?: string;
+}
+/**
+ * Run the hook-surface audit.
+ */
+export declare function auditHookSurface(projectDirOrOpts?: string | HookSurfaceOptions): HookSurfaceResult;
+/**
+ * Adapter returning a RepoAuditResult shape for registry integration.
+ */
+export declare function auditHookSurfaceAsRepoResult(projectDirOrOpts?: string | HookSurfaceOptions): RepoAuditResult;
+//# sourceMappingURL=hook-surface.d.ts.map

package/dist/esm/audit/hook-surface.js

@@ -0,0 +1,251 @@
+/**
+ * `wp audit hook-surface` — enforces the single-rewriter-per-matcher invariant.
+ *
+ * From Anthropic's official hooks docs (May 2026):
+ *   "When multiple PreToolUse hooks return updatedInput to rewrite a tool's
+ *   arguments, the last one to finish wins. Since hooks run in parallel, the
+ *   order is non-deterministic. Avoid having more than one hook modify the
+ *   same tool's input."
+ *
+ * This audit collects hooks from:
+ *   - ~/.claude/settings.json          (user-level)
+ *   - $CLAUDE_PROJECT_DIR/.claude/settings.json  (project-level)
+ *
+ * It classifies each hook as a **rewriter** or a **validator**, then flags any
+ * event+matcher combination that has more than one rewriter registered.
+ *
+ * Known rewriters (hardcoded, expandable):
+ *   - `rtk hook claude` → Bash rewriter
+ *   - any hook path ending in `pretooluse.mjs` that is NOT a passthrough
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+// ---------------------------------------------------------------------------
+// Owner extraction
+// ---------------------------------------------------------------------------
+/**
+ * Determines the canonical owner of a hook command using priority-ordered
+ * pattern matching. Returns one of: 'webpresso', 'context-mode', 'omx',
+ * 'rtk', 'gstack', or 'unknown'.
+ */
+export function extractOwner(command) {
+    if (/\bwp[-_][a-z]/.test(command))
+        return 'webpresso';
+    if (command.includes('context-mode'))
+        return 'context-mode';
+    if (/omx|oh-my-codex/.test(command))
+        return 'omx';
+    if (/\brtk\b/.test(command))
+        return 'rtk';
+    if (/gstack|check-gstack/.test(command))
+        return 'gstack';
+    return 'unknown';
+}
+// ---------------------------------------------------------------------------
+// Drift detection
+// ---------------------------------------------------------------------------
+/**
+ * Detects drift violations where the same owner+command appears more than once
+ * for the same runtime+event combination. Cross-owner same-event composition
+ * is NOT a violation — only same-owner/same-command duplication is.
+ *
+ * Pure function — no filesystem I/O.
+ */
+export function detectDrift(entries) {
+    const byKey = new Map();
+    for (const entry of entries) {
+        const owner = extractOwner(entry.command);
+        const key = `${entry.runtime}:${entry.event}:${owner}:${entry.command.trim()}`;
+        const existing = byKey.get(key);
+        if (existing) {
+            existing.push(entry);
+        }
+        else {
+            byKey.set(key, [entry]);
+        }
+    }
+    const violations = [];
+    for (const [key, group] of byKey) {
+        if (group.length > 1) {
+            violations.push({ key, count: group.length, entries: group });
+        }
+    }
+    return violations;
+}
+// ---------------------------------------------------------------------------
+// Rewriter detection
+// ---------------------------------------------------------------------------
+/**
+ * Returns true if the hook command is a known rewriter — i.e. it can return
+ * `updatedInput` and mutate the tool's arguments.
+ *
+ * Validators only return `permissionDecision` or `additionalContext` and are
+ * safe to stack on the same matcher.
+ */
+function isRewriter(command) {
+    // RTK rewrites Bash input — canonical rewriter
+    if (command.includes('rtk hook claude'))
+        return true;
+    // context-mode pretooluse hook rewrites input unless explicitly passthrough.
+    // We cannot read the hook's internals, so we flag any pretooluse.mjs
+    // binding conservatively.
+    if (command.endsWith('pretooluse.mjs'))
+        return true;
+    if (command.includes('/pretooluse.mjs'))
+        return true;
+    return false;
+}
+// ---------------------------------------------------------------------------
+// Settings file parsing
+// ---------------------------------------------------------------------------
+function readSettingsFile(filePath) {
+    if (!existsSync(filePath)) {
+        return { source: filePath, hooks: {} };
+    }
+    let raw;
+    try {
+        raw = readFileSync(filePath, 'utf8');
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return {
+            source: filePath,
+            hooks: {},
+            parseError: `Could not read ${filePath}: ${msg}`,
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return {
+            source: filePath,
+            hooks: {},
+            parseError: `Could not parse ${filePath}: ${msg}`,
+        };
+    }
+    if (!parsed || typeof parsed !== 'object') {
+        return { source: filePath, hooks: {} };
+    }
+    const record = parsed;
+    // Claude Code settings.json wraps hooks under { "hooks": { Event: [...] } }
+    const raw_hooks = record['hooks'];
+    if (raw_hooks && typeof raw_hooks === 'object' && !Array.isArray(raw_hooks)) {
+        return { source: filePath, hooks: raw_hooks };
+    }
+    return { source: filePath, hooks: {} };
+}
+function resolveSettingsPaths(projectDir, userSettingsOverride) {
+    const paths = [];
+    // User-level: ~/.claude/settings.json (or override for tests)
+    const userSettings = userSettingsOverride ?? path.join(os.homedir(), '.claude', 'settings.json');
+    paths.push(userSettings);
+    // Project-level: $CLAUDE_PROJECT_DIR/.claude/settings.json
+    const projectRoot = projectDir ?? process.env['CLAUDE_PROJECT_DIR'];
+    if (projectRoot) {
+        paths.push(path.join(projectRoot, '.claude', 'settings.json'));
+    }
+    return paths;
+}
+function collectRewriters(settings) {
+    const entries = [];
+    for (const { source, hooks } of settings) {
+        for (const [event, groups] of Object.entries(hooks)) {
+            if (!Array.isArray(groups))
+                continue;
+            for (const group of groups) {
+                const matcher = group.matcher ?? '*';
+                const hookEntries = group.hooks ?? [];
+                for (const hook of hookEntries) {
+                    const command = hook.command;
+                    if (typeof command !== 'string' || command.trim() === '')
+                        continue;
+                    if (isRewriter(command)) {
+                        entries.push({ event, matcher, command, source });
+                    }
+                }
+            }
+        }
+    }
+    return entries;
+}
+function buildViolations(rewriters) {
+    // Group by event+matcher
+    const byKey = new Map();
+    for (const entry of rewriters) {
+        const key = `${entry.event}\0${entry.matcher}`;
+        const existing = byKey.get(key);
+        if (existing) {
+            existing.push(entry);
+        }
+        else {
+            byKey.set(key, [entry]);
+        }
+    }
+    const violations = [];
+    for (const [key, entries] of byKey) {
+        if (entries.length <= 1)
+            continue;
+        const [event, matcher] = key.split('\0');
+        const commands = entries.map((e) => e.command);
+        violations.push({
+            event,
+            matcher,
+            rewriters: commands,
+            reason: `${entries.length} rewriters registered on ${event}/${matcher}: ` +
+                commands.map((c) => JSON.stringify(c)).join(', ') +
+                '. Since hooks run in parallel, the last updatedInput wins non-deterministically. ' +
+                'Keep at most one rewriter per event+matcher combination.',
+        });
+    }
+    return violations;
+}
+/**
+ * Run the hook-surface audit.
+ */
+export function auditHookSurface(projectDirOrOpts) {
+    const opts = typeof projectDirOrOpts === 'string'
+        ? { projectDir: projectDirOrOpts }
+        : (projectDirOrOpts ?? {});
+    const settingsPaths = resolveSettingsPaths(opts.projectDir, opts.userSettingsPath);
+    const settings = settingsPaths.map(readSettingsFile);
+    const parseErrors = settings.flatMap((s) => (s.parseError ? [s.parseError] : []));
+    const rewriters = collectRewriters(settings);
+    const violations = buildViolations(rewriters);
+    const passed = violations.length === 0 && parseErrors.length === 0;
+    // Promote parse errors to violations so they surface in the output
+    const errorViolations = parseErrors.map((msg) => ({
+        event: 'parse-error',
+        matcher: '',
+        rewriters: [],
+        reason: msg,
+    }));
+    const allViolations = [...errorViolations, ...violations];
+    return {
+        passed,
+        kind: 'hook-surface',
+        details: {
+            ok: passed,
+            violations: allViolations,
+        },
+    };
+}
+/**
+ * Adapter returning a RepoAuditResult shape for registry integration.
+ */
+export function auditHookSurfaceAsRepoResult(projectDirOrOpts) {
+    const result = auditHookSurface(projectDirOrOpts);
+    const violations = result.details.violations.map((v) => ({
+        message: v.reason,
+    }));
+    return {
+        ok: result.passed,
+        title: 'Hook surface audit',
+        checked: result.details.violations.length,
+        violations,
+    };
+}
+//# sourceMappingURL=hook-surface.js.map

package/dist/esm/audit/memory-rotation.d.ts

@@ -0,0 +1,31 @@
+import type { RepoAuditResult, RepoAuditViolation } from './repo-guardrails.js';
+export interface RotationLogEntry {
+    timestamp: string;
+    sectionSlug: string;
+    sourcePath: string;
+    archivedTo: string;
+    reason: string;
+}
+export interface RotationEvent extends RotationLogEntry {
+    acked: boolean;
+    daysAgo: number;
+}
+export interface MemoryRotationResult {
+    violations: RepoAuditViolation[];
+    recentEvents: RotationEvent[];
+    checked: number;
+    pass: boolean;
+}
+export interface MemoryRotationOptions {
+    windowDays?: number;
+    strict?: boolean;
+}
+/**
+ * Audit memory rotation log.
+ */
+export declare function auditMemoryRotation(cwd: string, options?: MemoryRotationOptions): MemoryRotationResult;
+/**
+ * Adapter to return a RepoAuditResult shape for registry integration.
+ */
+export declare function auditMemoryRotationAsRepoResult(cwd: string, options?: MemoryRotationOptions): RepoAuditResult;
+//# sourceMappingURL=memory-rotation.d.ts.map

package/dist/esm/audit/memory-rotation.js

@@ -0,0 +1,137 @@
+/**
+ * `wp audit memory-rotation` — surfaces recent rotation events from
+ * `.agent/.rotation-log.jsonl`.
+ *
+ * Each line in the log is a JSON object describing a section that was
+ * rotated out of agent memory. This audit surfaces events from the last
+ * N days (default 30) and checks for unacknowledged rotations.
+ *
+ * With `--strict`, fails if any rotation lacks `last_rotation_acked`
+ * within 30 days.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { getSurfacePath, NotInGitRepoError } from '#paths/state-root.js';
+const DEFAULT_WINDOW_DAYS = 30;
+function parseRotationLog(logPath) {
+    if (!existsSync(logPath))
+        return [];
+    let raw;
+    try {
+        raw = readFileSync(logPath, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const entries = [];
+    for (const line of raw.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (!isRotationEntry(parsed))
+                continue;
+            entries.push(parsed);
+        }
+        catch {
+            // skip malformed lines
+        }
+    }
+    return entries;
+}
+function isRotationEntry(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const obj = value;
+    return (typeof obj['timestamp'] === 'string' &&
+        typeof obj['sectionSlug'] === 'string' &&
+        typeof obj['sourcePath'] === 'string' &&
+        typeof obj['archivedTo'] === 'string' &&
+        typeof obj['reason'] === 'string');
+}
+/**
+ * Check if a rotation entry has been acknowledged. We look for a
+ * `last_rotation_acked` field in the corresponding memory.merge.yaml.
+ * For simplicity, we check if a file at `<sourcePath>.ack` or the
+ * `sourcePath` itself contains an `acked:` marker. Consumers can set
+ * this via their memory management tooling.
+ *
+ * Currently: check if the sourcePath file has a `last_rotation_acked:` key.
+ */
+function isRotationAcked(entry, cwd) {
+    const absPath = path.isAbsolute(entry.sourcePath)
+        ? entry.sourcePath
+        : path.join(cwd, entry.sourcePath);
+    if (!existsSync(absPath))
+        return false;
+    try {
+        const content = readFileSync(absPath, 'utf8');
+        return content.includes('last_rotation_acked:');
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Audit memory rotation log.
+ */
+export function auditMemoryRotation(cwd, options = {}) {
+    const windowDays = options.windowDays ?? DEFAULT_WINDOW_DAYS;
+    const strict = options.strict ?? false;
+    const logPath = (() => {
+        try {
+            return getSurfacePath('audit/rotation-log.jsonl', 'repo', cwd);
+        }
+        catch (err) {
+            if (err instanceof NotInGitRepoError)
+                return path.join(cwd, '.agent', '.rotation-log.jsonl');
+            throw err;
+        }
+    })();
+    const allEntries = parseRotationLog(logPath);
+    const now = Date.now();
+    const windowMs = windowDays * 24 * 60 * 60 * 1000;
+    const recentEvents = [];
+    for (const entry of allEntries) {
+        const entryTime = new Date(entry.timestamp).getTime();
+        if (Number.isNaN(entryTime))
+            continue;
+        const ageMs = now - entryTime;
+        if (ageMs > windowMs)
+            continue;
+        const daysAgo = Math.floor(ageMs / (24 * 60 * 60 * 1000));
+        const acked = isRotationAcked(entry, cwd);
+        recentEvents.push({ ...entry, acked, daysAgo });
+    }
+    const violations = [];
+    if (strict) {
+        for (const event of recentEvents) {
+            if (!event.acked) {
+                violations.push({
+                    file: event.sourcePath,
+                    message: `Unacknowledged rotation: section '${event.sectionSlug}' rotated ${event.daysAgo}d ago (${event.timestamp}). Set last_rotation_acked in ${event.sourcePath}.`,
+                });
+            }
+        }
+    }
+    return {
+        violations,
+        recentEvents,
+        checked: recentEvents.length,
+        pass: violations.length === 0,
+    };
+}
+/**
+ * Adapter to return a RepoAuditResult shape for registry integration.
+ */
+export function auditMemoryRotationAsRepoResult(cwd, options = {}) {
+    const result = auditMemoryRotation(cwd, options);
+    return {
+        ok: result.pass,
+        title: 'Memory rotation audit',
+        checked: result.checked,
+        violations: result.violations,
+    };
+}
+//# sourceMappingURL=memory-rotation.js.map

package/dist/esm/audit/memory-unified.d.ts

@@ -0,0 +1,3 @@
+import type { RepoAuditResult } from './repo-guardrails.js';
+export declare function auditMemoryUnified(cwd: string): Promise<RepoAuditResult>;
+//# sourceMappingURL=memory-unified.d.ts.map

package/dist/esm/audit/memory-unified.js

@@ -0,0 +1,46 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+const AGENTS_MD_IMPORT = '@AGENTS.md';
+export async function auditMemoryUnified(cwd) {
+    const claudeMdPath = join(cwd, 'CLAUDE.md');
+    const violations = [];
+    if (!existsSync(claudeMdPath)) {
+        // No CLAUDE.md at all — warn but don't fail
+        return {
+            ok: true,
+            title: 'memory unified',
+            checked: 0,
+            violations: [],
+        };
+    }
+    let content;
+    try {
+        content = readFileSync(claudeMdPath, 'utf-8');
+    }
+    catch {
+        violations.push({
+            file: 'CLAUDE.md',
+            message: `[warn] failed to read CLAUDE.md`,
+        });
+        return {
+            ok: true,
+            title: 'memory unified',
+            checked: 1,
+            violations,
+        };
+    }
+    if (!content.includes(AGENTS_MD_IMPORT)) {
+        violations.push({
+            file: 'CLAUDE.md',
+            message: `[warn] CLAUDE.md does not contain \`${AGENTS_MD_IMPORT}\` import — add \`@AGENTS.md\` to unify agent memory across IDEs`,
+        });
+    }
+    // Warns only — always ok:true so this never gates CI alone
+    return {
+        ok: true,
+        title: 'memory unified',
+        checked: 1,
+        violations,
+    };
+}
+//# sourceMappingURL=memory-unified.js.map

package/dist/esm/audit/open-source-licenses.d.ts

@@ -0,0 +1,4 @@
+import type { RepoAuditResult } from './repo-guardrails.js';
+export declare function auditOpenSourceLicenses(rootDirectory?: string): RepoAuditResult;
+export declare function listThirdPartySkillSlugs(rootDirectory?: string): string[];
+//# sourceMappingURL=open-source-licenses.d.ts.map