sapper-ai 0.7.0 → 0.8.0

package/dist/cli.d.ts

@@ -1,3 +1,6 @@
 #!/usr/bin/env node
 export declare function runCli(argv?: string[]): Promise<number>;
+type GuardModuleLoader = (modulePath: string) => Promise<Record<string, unknown>>;
+export declare function __setGuardModuleLoaderForTests(loader: GuardModuleLoader | null): void;
+export {};
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAmBA,wBAAsB,MAAM,CAAC,IAAI,GAAE,MAAM,EAA0B,GAAG,OAAO,CAAC,MAAM,CAAC,CAiGpF"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAoBA,wBAAsB,MAAM,CAAC,IAAI,GAAE,MAAM,EAA0B,GAAG,OAAO,CAAC,MAAM,CAAC,CA+HpF;AA4WD,KAAK,iBAAiB,GAAG,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;AASjF,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,GAAG,IAAI,CAErF"}

package/dist/cli.js

@@ -38,6 +38,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runCli = runCli;
+exports.__setGuardModuleLoaderForTests = __setGuardModuleLoaderForTests;
 const node_fs_1 = require("node:fs");
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
@@ -52,6 +53,7 @@ const scan_1 = require("./scan");
 const detect_1 = require("./openclaw/detect");
 const scanner_1 = require("./openclaw/scanner");
 const env_1 = require("./utils/env");
+const setup_1 = require("./guard/setup");
 async function runCli(argv = process.argv.slice(2)) {
     if (argv[0] === '--help' || argv[0] === '-h') {
         printUsage();
@@ -96,6 +98,30 @@ async function runCli(argv = process.argv.slice(2)) {
         }
         return runOpenClawWizard();
     }
+    if (argv[0] === 'setup') {
+        if (argv[1] === '--help' || argv[1] === '-h') {
+            printUsage();
+            return 0;
+        }
+        const parsed = parseSetupArgs(argv.slice(1));
+        if (!parsed) {
+            printUsage();
+            return 1;
+        }
+        return runSetupCommand(parsed);
+    }
+    if (argv[0] === 'guard') {
+        if (argv[1] === '--help' || argv[1] === '-h') {
+            printUsage();
+            return 0;
+        }
+        const parsed = parseGuardArgs(argv.slice(1));
+        if (!parsed) {
+            printUsage();
+            return 1;
+        }
+        return runGuardCommand(parsed);
+    }
     if (argv[0] === 'harden') {
         const parsed = parseHardenArgs(argv.slice(1));
         if (!parsed) {
@@ -152,6 +178,15 @@ Usage:
   sapper-ai harden            Plan recommended setup changes (no writes)
   sapper-ai harden --apply    Apply recommended project changes
   sapper-ai harden --include-system   Include system changes (home directory)
+  sapper-ai setup             Register Claude Code hooks for Skill Guard
+  sapper-ai setup --remove    Remove only sapper-ai Skill Guard hooks
+  sapper-ai setup --status    Show current Skill Guard hook registration status
+  sapper-ai guard scan        Run SessionStart guard scan hook
+  sapper-ai guard check       Run UserPromptSubmit guard check hook
+  sapper-ai guard dismiss <name>   Dismiss warning by skill name
+  sapper-ai guard rescan      Clear guard cache, then scan again
+  sapper-ai guard cache list  Show guard cache entries
+  sapper-ai guard cache clear Clear guard cache entries
   sapper-ai mcp wrap-config   Wrap MCP servers to run behind sapperai-proxy (defaults to Claude Code config)
   sapper-ai mcp unwrap-config Undo MCP wrapping
   sapper-ai quarantine list   List quarantined files
@@ -295,6 +330,239 @@ function parseHardenArgs(argv) {
         mcpVersion,
     };
 }
+function parseSetupArgs(argv) {
+    if (argv.length === 0) {
+        return { command: 'setup_register' };
+    }
+    if (argv.length > 1) {
+        return null;
+    }
+    if (argv[0] === '--remove') {
+        return { command: 'setup_remove' };
+    }
+    if (argv[0] === '--status') {
+        return { command: 'setup_status' };
+    }
+    return null;
+}
+function printSetupStatus() {
+    const status = (0, setup_1.getStatus)();
+    console.log('Skill Guard setup status:');
+    console.log(`  Claude directory: ${displayPath(status.claudeDirPath)} ${status.claudeDirExists ? '(found)' : '(missing)'}`);
+    console.log(`  Settings file: ${displayPath(status.settingsPath)} ${status.settingsExists ? '(found)' : '(missing)'}`);
+    for (const commandStatus of status.commands) {
+        const state = commandStatus.registered ? 'registered' : 'not registered';
+        console.log(`  ${commandStatus.event}: ${state} (${commandStatus.matchCount})`);
+    }
+}
+async function runSetupCommand(args) {
+    if (args.command === 'setup_status') {
+        printSetupStatus();
+        return 0;
+    }
+    if (args.command === 'setup_register') {
+        const result = (0, setup_1.registerHooks)();
+        if (!result.ok) {
+            console.error(`Claude directory not found: ${displayPath(result.status.claudeDirPath)}`);
+            return 1;
+        }
+        if (result.action === 'already_registered') {
+            console.log('Skill Guard hooks are already registered.');
+            return 0;
+        }
+        console.log(`Registered Skill Guard hooks in ${displayPath(result.status.settingsPath)}.`);
+        return 0;
+    }
+    const result = (0, setup_1.removeHooks)();
+    if (!result.ok) {
+        console.error(`Claude directory not found: ${displayPath(result.status.claudeDirPath)}`);
+        return 1;
+    }
+    if (result.removedCount === 0) {
+        console.log('No sapper-ai Skill Guard hooks were registered.');
+        return 0;
+    }
+    console.log(`Removed ${result.removedCount} sapper-ai Skill Guard hook(s).`);
+    return 0;
+}
+function parseGuardArgs(argv) {
+    const subcommand = argv[0];
+    if (!subcommand) {
+        return null;
+    }
+    if (subcommand === 'scan') {
+        return argv.length === 1 ? { command: 'guard_scan' } : null;
+    }
+    if (subcommand === 'check') {
+        return argv.length === 1 ? { command: 'guard_check' } : null;
+    }
+    if (subcommand === 'dismiss') {
+        if (argv.length !== 2)
+            return null;
+        const name = argv[1]?.trim();
+        if (!name)
+            return null;
+        return { command: 'guard_dismiss', name };
+    }
+    if (subcommand === 'rescan') {
+        return argv.length === 1 ? { command: 'guard_rescan' } : null;
+    }
+    if (subcommand === 'cache') {
+        if (argv.length !== 2)
+            return null;
+        if (argv[1] === 'list')
+            return { command: 'guard_cache_list' };
+        if (argv[1] === 'clear')
+            return { command: 'guard_cache_clear' };
+        return null;
+    }
+    return null;
+}
+function resolveNamedExport(moduleExports, names, label) {
+    for (const name of names) {
+        const candidate = moduleExports[name];
+        if (typeof candidate === 'function') {
+            return candidate;
+        }
+    }
+    throw new Error(`Missing export for ${label}`);
+}
+const defaultGuardModuleLoader = async (modulePath) => {
+    const fullModulePath = `./guard/${modulePath}`;
+    return (await Promise.resolve(`${fullModulePath}`).then(s => __importStar(require(s))));
+};
+let guardModuleLoader = defaultGuardModuleLoader;
+function __setGuardModuleLoaderForTests(loader) {
+    guardModuleLoader = loader ?? defaultGuardModuleLoader;
+}
+async function loadGuardModule(modulePath) {
+    if (modulePath.includes('..')) {
+        throw new Error(`Invalid guard module path: ${modulePath}`);
+    }
+    return guardModuleLoader(modulePath);
+}
+function toExitCode(value) {
+    if (typeof value === 'number' && Number.isInteger(value)) {
+        return value;
+    }
+    if (isObject(value) && typeof value.exitCode === 'number' && Number.isInteger(value.exitCode)) {
+        return value.exitCode;
+    }
+    return 0;
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+async function runGuardScanHook() {
+    const moduleExports = await loadGuardModule('hooks/guardScan');
+    const hook = resolveNamedExport(moduleExports, ['guardScan', 'runGuardScan', 'default'], 'guard scan hook');
+    const result = await hook();
+    return toExitCode(result);
+}
+async function runGuardCheckHook() {
+    const moduleExports = await loadGuardModule('hooks/guardCheck');
+    const hook = resolveNamedExport(moduleExports, ['guardCheck', 'runGuardCheck', 'default'], 'guard check hook');
+    const result = await hook();
+    return toExitCode(result);
+}
+async function createGuardClassInstance(modulePath, classNames) {
+    const moduleExports = await loadGuardModule(modulePath);
+    const Constructor = resolveNamedExport(moduleExports, classNames, modulePath);
+    const GuardConstructor = Constructor;
+    return new GuardConstructor();
+}
+async function clearGuardCache() {
+    const scanCache = await createGuardClassInstance('ScanCache', ['ScanCache', 'default']);
+    const clearMethod = scanCache.clear;
+    if (typeof clearMethod !== 'function') {
+        throw new Error('ScanCache.clear() is not available');
+    }
+    await clearMethod.call(scanCache);
+}
+async function listGuardCacheEntries() {
+    const scanCache = await createGuardClassInstance('ScanCache', ['ScanCache', 'default']);
+    const listMethod = scanCache.list;
+    if (typeof listMethod !== 'function') {
+        throw new Error('ScanCache.list() is not available');
+    }
+    const listResult = await listMethod.call(scanCache);
+    return Array.isArray(listResult) ? listResult : [];
+}
+async function dismissGuardWarning(name) {
+    const warningStore = await createGuardClassInstance('WarningStore', ['WarningStore', 'default']);
+    const dismissMethod = warningStore.dismiss;
+    if (typeof dismissMethod !== 'function') {
+        throw new Error('WarningStore.dismiss() is not available');
+    }
+    return dismissMethod.call(warningStore, name);
+}
+function printGuardCacheList(entries) {
+    if (entries.length === 0) {
+        console.log('Guard cache is empty.');
+        return;
+    }
+    console.log('Guard cache entries:');
+    for (const entry of entries) {
+        if (!isObject(entry)) {
+            console.log(`  - ${String(entry)}`);
+            continue;
+        }
+        const nestedEntry = isObject(entry.entry) ? entry.entry : undefined;
+        const pathValue = typeof entry.path === 'string'
+            ? entry.path
+            : nestedEntry && typeof nestedEntry.path === 'string'
+                ? nestedEntry.path
+                : undefined;
+        const skillName = typeof entry.skillName === 'string'
+            ? entry.skillName
+            : nestedEntry && typeof nestedEntry.skillName === 'string'
+                ? nestedEntry.skillName
+                : undefined;
+        const path = typeof pathValue === 'string' ? displayPath(pathValue) : undefined;
+        const hash = typeof entry.contentHash === 'string' ? entry.contentHash.slice(0, 12) : undefined;
+        const display = [skillName, path, hash].filter(Boolean).join(' | ');
+        if (display.length > 0) {
+            console.log(`  - ${display}`);
+            continue;
+        }
+        console.log(`  - ${JSON.stringify(entry)}`);
+    }
+}
+function toErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+async function runGuardCommand(args) {
+    try {
+        if (args.command === 'guard_scan') {
+            return runGuardScanHook();
+        }
+        if (args.command === 'guard_check') {
+            return runGuardCheckHook();
+        }
+        if (args.command === 'guard_dismiss') {
+            await dismissGuardWarning(args.name);
+            console.log(`Dismissed warning for "${args.name}".`);
+            return 0;
+        }
+        if (args.command === 'guard_rescan') {
+            await clearGuardCache();
+            console.log('Guard cache cleared.');
+            return runGuardScanHook();
+        }
+        if (args.command === 'guard_cache_list') {
+            const entries = await listGuardCacheEntries();
+            printGuardCacheList(entries);
+            return 0;
+        }
+        await clearGuardCache();
+        console.log('Guard cache cleared.');
+        return 0;
+    }
+    catch (error) {
+        console.error(`Guard command failed: ${toErrorMessage(error)}`);
+        return 1;
+    }
+}
 function parseMcpArgs(argv) {
     const subcommand = argv[0];
     const rest = argv.slice(1);

package/dist/guard/ScanCache.d.ts

@@ -0,0 +1,42 @@
+import type { ScanCacheEntry, ScanCacheVerificationResult } from './types';
+export interface ScanCacheOptions {
+    filePath?: string;
+    homeDir?: string;
+    keyPath?: string;
+    hostName?: string;
+    userId?: string;
+    readFileFn?: (filePath: string, encoding: BufferEncoding) => Promise<string>;
+    writeFileFn?: (filePath: string, content: string) => Promise<void>;
+    readBufferFileFn?: (filePath: string) => Promise<Buffer>;
+    writeBufferFileFn?: (filePath: string, content: Buffer) => Promise<void>;
+    randomBytesFn?: (size: number) => Buffer;
+}
+export declare class ScanCache {
+    private readonly cachePath;
+    private readonly hmacKeyPath;
+    private readonly readFileFn;
+    private readonly writeFileFn;
+    private readonly readBufferFileFn;
+    private readonly writeBufferFileFn;
+    private readonly randomBytesFn;
+    private state;
+    private hmacKey;
+    constructor(options?: ScanCacheOptions);
+    has(contentHash: string): Promise<boolean>;
+    get(contentHash: string): Promise<ScanCacheEntry | null>;
+    set(contentHash: string, entry: ScanCacheEntry): Promise<void>;
+    list(): Promise<Array<{
+        contentHash: string;
+        entry: ScanCacheEntry;
+    }>>;
+    clear(): Promise<void>;
+    verify(): Promise<ScanCacheVerificationResult>;
+    private loadState;
+    private normalizeState;
+    private createEmptyState;
+    private persist;
+    private computeHmac;
+    private getOrCreateHmacKey;
+    private readExistingHmacKey;
+}
+//# sourceMappingURL=ScanCache.d.ts.map

package/dist/guard/ScanCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScanCache.d.ts","sourceRoot":"","sources":["../../src/guard/ScanCache.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,cAAc,EAAE,2BAA2B,EAAE,MAAM,SAAS,CAAA;AAiB1E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IAC5E,WAAW,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAClE,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IACxD,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACxE,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAA;CACzC;AA8GD,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAQ;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAiE;IAC5F,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAsD;IAClF,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAuC;IACxE,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAsD;IACxF,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA0B;IAExD,OAAO,CAAC,KAAK,CAAiC;IAC9C,OAAO,CAAC,OAAO,CAAsB;gBAEzB,OAAO,GAAE,gBAAqB;IAoBpC,GAAG,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAK1C,GAAG,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAaxD,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAa9D,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,cAAc,CAAA;KAAE,CAAC,CAAC;IAatE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAMtB,MAAM,IAAI,OAAO,CAAC,2BAA2B,CAAC;YActC,SAAS;IAkBvB,OAAO,CAAC,cAAc;YA0BR,gBAAgB;YAShB,OAAO;YAmBP,WAAW;YAMX,kBAAkB;YAiBlB,mBAAmB;CAWlC"}

package/dist/guard/ScanCache.js

@@ -0,0 +1,261 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScanCache = void 0;
+const promises_1 = require("node:fs/promises");
+const node_crypto_1 = require("node:crypto");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const fs_1 = require("../utils/fs");
+const SCAN_CACHE_VERSION = 2;
+const SCAN_CACHE_DIR = '.sapper-ai';
+const SCAN_CACHE_FILE = 'scan-cache.json';
+const HMAC_KEY_FILE = 'hmac-key';
+const HMAC_KEY_BYTES = 32;
+const SHA256_HEX_LENGTH = 64;
+const PRIVATE_FILE_MODE = 0o600;
+const DANGEROUS_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+function createEntryMap() {
+    return Object.create(null);
+}
+function isHexDigest(value) {
+    return value.length === SHA256_HEX_LENGTH && /^[0-9a-f]+$/i.test(value);
+}
+function hmacEqual(left, right) {
+    if (!isHexDigest(left) || !isHexDigest(right) || left.length !== right.length) {
+        return false;
+    }
+    return (0, node_crypto_1.timingSafeEqual)(Buffer.from(left, 'hex'), Buffer.from(right, 'hex'));
+}
+function sortEntries(entries) {
+    const ordered = createEntryMap();
+    for (const hash of Object.keys(entries).sort()) {
+        if (DANGEROUS_KEYS.has(hash)) {
+            continue;
+        }
+        const entry = entries[hash];
+        if (!entry) {
+            continue;
+        }
+        ordered[hash] = {
+            path: entry.path,
+            skillName: entry.skillName,
+            decision: entry.decision,
+            risk: entry.risk,
+            reasons: [...entry.reasons],
+            scannedAt: entry.scannedAt,
+        };
+    }
+    return ordered;
+}
+function normalizeEntry(entry) {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+        return null;
+    }
+    const value = entry;
+    const decision = value.decision === 'suspicious' ? 'suspicious' : value.decision === 'safe' ? 'safe' : null;
+    if (decision === null) {
+        return null;
+    }
+    if (typeof value.path !== 'string' || value.path.length === 0) {
+        return null;
+    }
+    if (typeof value.skillName !== 'string' || value.skillName.length === 0) {
+        return null;
+    }
+    if (typeof value.risk !== 'number' || !Number.isFinite(value.risk)) {
+        return null;
+    }
+    if (!Array.isArray(value.reasons) || value.reasons.some((reason) => typeof reason !== 'string')) {
+        return null;
+    }
+    if (typeof value.scannedAt !== 'string' || value.scannedAt.length === 0) {
+        return null;
+    }
+    return {
+        path: value.path,
+        skillName: value.skillName,
+        decision,
+        risk: value.risk,
+        reasons: [...value.reasons],
+        scannedAt: value.scannedAt,
+    };
+}
+function normalizeEntries(entries) {
+    if (!entries || typeof entries !== 'object' || Array.isArray(entries)) {
+        return createEntryMap();
+    }
+    const normalized = createEntryMap();
+    for (const [hash, entry] of Object.entries(entries)) {
+        if (DANGEROUS_KEYS.has(hash)) {
+            continue;
+        }
+        const safeEntry = normalizeEntry(entry);
+        if (!safeEntry) {
+            continue;
+        }
+        normalized[hash] = safeEntry;
+    }
+    return normalized;
+}
+class ScanCache {
+    constructor(options = {}) {
+        this.state = null;
+        this.hmacKey = null;
+        const homePath = options.homeDir ?? (0, node_os_1.homedir)();
+        this.cachePath = options.filePath ?? (0, node_path_1.join)(homePath, SCAN_CACHE_DIR, SCAN_CACHE_FILE);
+        this.hmacKeyPath = options.keyPath ?? (0, node_path_1.join)(homePath, SCAN_CACHE_DIR, HMAC_KEY_FILE);
+        this.readFileFn = options.readFileFn ?? promises_1.readFile;
+        this.writeFileFn =
+            options.writeFileFn ?? ((filePath, content) => (0, fs_1.atomicWriteFile)(filePath, content, { mode: PRIVATE_FILE_MODE }));
+        this.readBufferFileFn = options.readBufferFileFn ?? ((filePath) => (0, promises_1.readFile)(filePath));
+        this.writeBufferFileFn =
+            options.writeBufferFileFn ??
+                (async (filePath, content) => {
+                    await (0, fs_1.ensureDir)((0, node_path_1.dirname)(filePath));
+                    await (0, promises_1.writeFile)(filePath, content, { mode: PRIVATE_FILE_MODE });
+                });
+        this.randomBytesFn = options.randomBytesFn ?? node_crypto_1.randomBytes;
+    }
+    async has(contentHash) {
+        const state = await this.loadState();
+        return Object.prototype.hasOwnProperty.call(state.entries, contentHash);
+    }
+    async get(contentHash) {
+        const state = await this.loadState();
+        const entry = state.entries[contentHash];
+        if (!entry) {
+            return null;
+        }
+        return {
+            ...entry,
+            reasons: [...entry.reasons],
+        };
+    }
+    async set(contentHash, entry) {
+        const state = await this.loadState();
+        state.entries[contentHash] = {
+            path: entry.path,
+            skillName: entry.skillName,
+            decision: entry.decision,
+            risk: entry.risk,
+            reasons: [...entry.reasons],
+            scannedAt: entry.scannedAt,
+        };
+        await this.persist(state);
+    }
+    async list() {
+        const state = await this.loadState();
+        return Object.keys(state.entries)
+            .sort()
+            .map((contentHash) => ({
+            contentHash,
+            entry: {
+                ...state.entries[contentHash],
+                reasons: [...state.entries[contentHash].reasons],
+            },
+        }));
+    }
+    async clear() {
+        const state = await this.loadState();
+        state.entries = createEntryMap();
+        await this.persist(state);
+    }
+    async verify() {
+        const state = await this.loadState();
+        const expectedHmac = await this.computeHmac(state.entries);
+        if (state.version === SCAN_CACHE_VERSION && hmacEqual(state.hmac, expectedHmac)) {
+            return { valid: true };
+        }
+        state.version = SCAN_CACHE_VERSION;
+        state.entries = createEntryMap();
+        await this.persist(state);
+        return { valid: false };
+    }
+    async loadState() {
+        if (this.state) {
+            return this.state;
+        }
+        try {
+            const raw = await this.readFileFn(this.cachePath, 'utf8');
+            const parsed = JSON.parse(raw);
+            const data = this.normalizeState(parsed);
+            this.state = data;
+            return data;
+        }
+        catch {
+            const empty = await this.createEmptyState();
+            this.state = empty;
+            return empty;
+        }
+    }
+    normalizeState(raw) {
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+            return {
+                version: SCAN_CACHE_VERSION,
+                hmac: '',
+                entries: createEntryMap(),
+            };
+        }
+        const record = raw;
+        const entries = normalizeEntries(record.entries);
+        const hmac = typeof record.hmac === 'string' ? record.hmac : '';
+        const version = typeof record.version === 'number' ? record.version : SCAN_CACHE_VERSION;
+        return {
+            version,
+            hmac,
+            entries,
+        };
+    }
+    async createEmptyState() {
+        const entries = createEntryMap();
+        return {
+            version: SCAN_CACHE_VERSION,
+            hmac: await this.computeHmac(entries),
+            entries,
+        };
+    }
+    async persist(state) {
+        const sorted = sortEntries(state.entries);
+        state.entries = sorted;
+        state.version = SCAN_CACHE_VERSION;
+        state.hmac = await this.computeHmac(sorted);
+        const payload = JSON.stringify({
+            version: state.version,
+            hmac: state.hmac,
+            entries: state.entries,
+        }, null, 2);
+        await this.writeFileFn(this.cachePath, `${payload}\n`);
+    }
+    async computeHmac(entries) {
+        const key = await this.getOrCreateHmacKey();
+        const canonicalEntries = JSON.stringify(sortEntries(entries));
+        return (0, node_crypto_1.createHmac)('sha256', key).update(canonicalEntries).digest('hex');
+    }
+    async getOrCreateHmacKey() {
+        if (this.hmacKey) {
+            return this.hmacKey;
+        }
+        const existing = await this.readExistingHmacKey();
+        if (existing) {
+            this.hmacKey = existing;
+            return existing;
+        }
+        const generated = this.randomBytesFn(HMAC_KEY_BYTES);
+        await this.writeBufferFileFn(this.hmacKeyPath, generated);
+        this.hmacKey = Buffer.from(generated);
+        return this.hmacKey;
+    }
+    async readExistingHmacKey() {
+        try {
+            const existing = await this.readBufferFileFn(this.hmacKeyPath);
+            if (existing.length === HMAC_KEY_BYTES) {
+                return Buffer.from(existing);
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+exports.ScanCache = ScanCache;

package/dist/guard/WarningStore.d.ts

@@ -0,0 +1,33 @@
+import type { DismissedWarning, SkillWarning } from './types';
+export interface WarningStoreOptions {
+    filePath?: string;
+    homeDir?: string;
+    now?: () => number;
+    readFileFn?: (filePath: string, encoding: BufferEncoding) => Promise<string>;
+    writeFileFn?: (filePath: string, content: string) => Promise<void>;
+}
+export declare class WarningStore {
+    private readonly filePath;
+    private readonly now;
+    private readonly readFileFn;
+    private readonly writeFileFn;
+    private state;
+    constructor(options?: WarningStoreOptions);
+    addPending(warning: SkillWarning): Promise<void>;
+    getPending(): Promise<SkillWarning[]>;
+    getAcknowledged(): Promise<SkillWarning[]>;
+    getDismissed(): Promise<DismissedWarning[]>;
+    isDismissed(skillName: string, contentHash: string): Promise<boolean>;
+    acknowledge(skillName: string, skillPath?: string): Promise<number>;
+    acknowledgeAll(warnings: SkillWarning[]): Promise<number>;
+    dismiss(skillName: string): Promise<number>;
+    clearPending(): Promise<void>;
+    replacePending(warnings: SkillWarning[]): Promise<void>;
+    private normalizeInputWarning;
+    private isDismissedInState;
+    private loadState;
+    private normalizeState;
+    private createEmptyState;
+    private persist;
+}
+//# sourceMappingURL=WarningStore.d.ts.map

package/dist/guard/WarningStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WarningStore.d.ts","sourceRoot":"","sources":["../../src/guard/WarningStore.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAc7D,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAClB,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IAC5E,WAAW,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACnE;AAgJD,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAQ;IACjC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAc;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAiE;IAC5F,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAsD;IAClF,OAAO,CAAC,KAAK,CAAiC;gBAElC,OAAO,GAAE,mBAAwB;IASvC,UAAU,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBhD,UAAU,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;IAKrC,eAAe,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;IAK1C,YAAY,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAK3C,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKrE,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA0BnE,cAAc,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAmCzD,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAmB3C,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAM7B,cAAc,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA0B7D,OAAO,CAAC,qBAAqB;IAQ7B,OAAO,CAAC,kBAAkB;YAIZ,SAAS;IAkBvB,OAAO,CAAC,cAAc;IAsBtB,OAAO,CAAC,gBAAgB;YASV,OAAO;CAgBtB"}