@eddacraft/anvil-kindling-integration 0.1.0

package/dist/retention.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Retention Management (KINDLING-016)
+ *
+ * Handles pruning of old observations and storage statistics.
+ * Works against the abstract IKindlingStore interface.
+ *
+ * Since the abstract store does not expose a direct "delete older than" method,
+ * retention is implemented via a dedicated IRetentionCapableStore interface
+ * that concrete stores can optionally implement.
+ */
+import type { KindlingConfig } from './config.js';
+/**
+ * Extended store interface for stores that support retention operations.
+ *
+ * Not all stores need to implement this. The NoOpKindlingStore does not.
+ * Concrete SQLite or database-backed stores should implement this interface.
+ */
+export interface IRetentionCapableStore {
+    /**
+     * Delete all observations with timestamps older than the given ISO8601 date.
+     *
+     * @param olderThan - ISO8601 datetime cutoff
+     * @returns Number of observations deleted
+     */
+    deleteObservationsOlderThan(olderThan: string): Promise<number>;
+    /**
+     * Get storage statistics.
+     *
+     * @returns Observation count and estimated storage size in bytes
+     */
+    getStats(): Promise<StorageStats>;
+}
+/**
+ * Storage statistics
+ */
+export interface StorageStats {
+    /** Total number of observations in the store */
+    observation_count: number;
+    /** Estimated storage size in bytes */
+    estimated_size_bytes: number;
+}
+/**
+ * Check if a store supports retention operations.
+ */
+export declare function isRetentionCapable(store: unknown): store is IRetentionCapableStore;
+/**
+ * Result of a pruning operation
+ */
+export interface PruneResult {
+    /** Whether pruning was actually performed */
+    pruned: boolean;
+    /** Number of observations deleted (0 if not pruned) */
+    deleted_count: number;
+    /** The cutoff date used */
+    cutoff_date: string;
+    /** Reason if pruning was skipped */
+    skip_reason?: string;
+}
+/**
+ * Prune observations older than the configured retention period.
+ *
+ * If the store does not implement IRetentionCapableStore, this is a no-op
+ * that returns a skip result.
+ *
+ * @param store - The store to prune (must implement IRetentionCapableStore)
+ * @param config - Kindling configuration with retention settings
+ * @returns Prune result
+ */
+export declare function pruneOldObservations(store: unknown, config: KindlingConfig): Promise<PruneResult>;
+/**
+ * Get storage statistics from the store.
+ *
+ * If the store does not implement IRetentionCapableStore, returns zero values.
+ *
+ * @param store - The store to query
+ * @returns Storage statistics
+ */
+export declare function getStorageStats(store: unknown): Promise<StorageStats>;
+//# sourceMappingURL=retention.d.ts.map

package/dist/retention.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retention.d.ts","sourceRoot":"","sources":["../src/retention.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAMlD;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;;OAKG;IACH,2BAA2B,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEhE;;;;OAIG;IACH,QAAQ,IAAI,OAAO,CAAC,YAAY,CAAC,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,gDAAgD;IAChD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,sCAAsC;IACtC,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAMD;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,sBAAsB,CASlF;AAMD;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,6CAA6C;IAC7C,MAAM,EAAE,OAAO,CAAC;IAChB,uDAAuD;IACvD,aAAa,EAAE,MAAM,CAAC;IACtB,2BAA2B;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,oCAAoC;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,cAAc,GACrB,OAAO,CAAC,WAAW,CAAC,CA8BtB;AAMD;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,CAAC,CAS3E"}

package/dist/retention.js

@@ -0,0 +1,81 @@
+/**
+ * Retention Management (KINDLING-016)
+ *
+ * Handles pruning of old observations and storage statistics.
+ * Works against the abstract IKindlingStore interface.
+ *
+ * Since the abstract store does not expose a direct "delete older than" method,
+ * retention is implemented via a dedicated IRetentionCapableStore interface
+ * that concrete stores can optionally implement.
+ */
+// =============================================================================
+// Type Guard
+// =============================================================================
+/**
+ * Check if a store supports retention operations.
+ */
+export function isRetentionCapable(store) {
+    if (store === null || typeof store !== 'object') {
+        return false;
+    }
+    const candidate = store;
+    return (typeof candidate['deleteObservationsOlderThan'] === 'function' &&
+        typeof candidate['getStats'] === 'function');
+}
+/**
+ * Prune observations older than the configured retention period.
+ *
+ * If the store does not implement IRetentionCapableStore, this is a no-op
+ * that returns a skip result.
+ *
+ * @param store - The store to prune (must implement IRetentionCapableStore)
+ * @param config - Kindling configuration with retention settings
+ * @returns Prune result
+ */
+export async function pruneOldObservations(store, config) {
+    if (!config.enabled) {
+        return {
+            pruned: false,
+            deleted_count: 0,
+            cutoff_date: '',
+            skip_reason: 'Kindling is disabled',
+        };
+    }
+    if (!isRetentionCapable(store)) {
+        return {
+            pruned: false,
+            deleted_count: 0,
+            cutoff_date: '',
+            skip_reason: 'Store does not support retention operations',
+        };
+    }
+    const cutoffDate = new Date();
+    cutoffDate.setDate(cutoffDate.getDate() - config.retention.days);
+    const cutoffIso = cutoffDate.toISOString();
+    const deletedCount = await store.deleteObservationsOlderThan(cutoffIso);
+    return {
+        pruned: true,
+        deleted_count: deletedCount,
+        cutoff_date: cutoffIso,
+    };
+}
+// =============================================================================
+// Statistics
+// =============================================================================
+/**
+ * Get storage statistics from the store.
+ *
+ * If the store does not implement IRetentionCapableStore, returns zero values.
+ *
+ * @param store - The store to query
+ * @returns Storage statistics
+ */
+export async function getStorageStats(store) {
+    if (!isRetentionCapable(store)) {
+        return {
+            observation_count: 0,
+            estimated_size_bytes: 0,
+        };
+    }
+    return store.getStats();
+}

package/dist/sensitive-data-validator.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Sensitive Data Validation (KINDLING-015)
+ *
+ * Validates and redacts sensitive data from observations before they
+ * are persisted to Kindling. This is a defense-in-depth layer on top of
+ * the `containsSensitiveData` check in observation-contract.ts.
+ *
+ * Patterns detected:
+ * - API keys (sk-*, ghp_*, AKIA*)
+ * - Long hex tokens (40+ characters)
+ * - Email addresses
+ * - Password-like values
+ *
+ * @see observation-contract.ts for the base containsSensitiveData utility
+ */
+import { type Observation } from './observation-contract.js';
+/**
+ * Result of sensitive data validation
+ */
+export interface SensitiveDataValidationResult {
+    /** Whether any sensitive data was detected */
+    hasSensitiveData: boolean;
+    /** Detailed issues found */
+    issues: string[];
+}
+/**
+ * Validate that an observation does not contain sensitive data.
+ *
+ * Uses the contract-level `containsSensitiveData` check plus additional
+ * pattern matching for known credential formats.
+ *
+ * @param observation - The observation to validate
+ * @returns Validation result with issues if sensitive data found
+ */
+export declare function validateNoSensitiveData(observation: Observation): SensitiveDataValidationResult;
+/**
+ * Deep-clone an observation and redact all known sensitive patterns from
+ * string values. This operates on the JSON serialization to catch values
+ * regardless of nesting depth.
+ *
+ * The returned observation is safe to persist.
+ *
+ * @param observation - The observation to redact
+ * @returns A new observation with sensitive values replaced
+ */
+export declare function redactSensitiveFields(observation: Observation): Observation;
+//# sourceMappingURL=sensitive-data-validator.d.ts.map

package/dist/sensitive-data-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sensitive-data-validator.d.ts","sourceRoot":"","sources":["../src/sensitive-data-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAyB,KAAK,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAyEpF;;GAEG;AACH,MAAM,WAAW,6BAA6B;IAC5C,8CAA8C;IAC9C,gBAAgB,EAAE,OAAO,CAAC;IAC1B,4BAA4B;IAC5B,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,WAAW,GAAG,6BAA6B,CA+B/F;AAMD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,WAAW,GAAG,WAAW,CAW3E"}

package/dist/sensitive-data-validator.js

@@ -0,0 +1,135 @@
+/**
+ * Sensitive Data Validation (KINDLING-015)
+ *
+ * Validates and redacts sensitive data from observations before they
+ * are persisted to Kindling. This is a defense-in-depth layer on top of
+ * the `containsSensitiveData` check in observation-contract.ts.
+ *
+ * Patterns detected:
+ * - API keys (sk-*, ghp_*, AKIA*)
+ * - Long hex tokens (40+ characters)
+ * - Email addresses
+ * - Password-like values
+ *
+ * @see observation-contract.ts for the base containsSensitiveData utility
+ */
+import { containsSensitiveData } from './observation-contract.js';
+import { createDebugger } from './utils/debug.js';
+const debug = createDebugger('kindling');
+// =============================================================================
+// Sensitive Patterns
+// =============================================================================
+/**
+ * Known sensitive value patterns and their replacement strings
+ */
+const SENSITIVE_PATTERNS = [
+    {
+        name: 'openai-api-key',
+        pattern: /sk-[a-zA-Z0-9]{20,}/g,
+        replacement: '[REDACTED:api-key]',
+    },
+    {
+        name: 'github-pat',
+        pattern: /ghp_[a-zA-Z0-9]{36,}/g,
+        replacement: '[REDACTED:github-token]',
+    },
+    {
+        name: 'github-fine-grained-pat',
+        pattern: /github_pat_[a-zA-Z0-9_]{36,}/g,
+        replacement: '[REDACTED:github-token]',
+    },
+    {
+        name: 'aws-access-key',
+        pattern: /AKIA[0-9A-Z]{16}/g,
+        replacement: '[REDACTED:aws-key]',
+    },
+    {
+        name: 'aws-secret-key',
+        pattern: /(?<=aws_secret_access_key\s*[=:]\s*)[^\s"',]+/gi,
+        replacement: '[REDACTED:aws-secret]',
+    },
+    {
+        name: 'hex-token',
+        pattern: /\b[0-9a-fA-F]{40,}\b/g,
+        replacement: '[REDACTED:token]',
+    },
+    {
+        name: 'email',
+        pattern: /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g,
+        replacement: '[REDACTED:email]',
+    },
+    {
+        name: 'password-value',
+        pattern: /(?<=(?:password|passwd|pwd)\s*[=:]\s*["']?)[^\s"',]+/gi,
+        replacement: '[REDACTED:password]',
+    },
+    {
+        name: 'bearer-token',
+        pattern: /(?<=Bearer\s+)[a-zA-Z0-9._~+/=-]{20,}/gi,
+        replacement: '[REDACTED:bearer-token]',
+    },
+    {
+        name: 'npm-token',
+        pattern: /npm_[a-zA-Z0-9]{36,}/g,
+        replacement: '[REDACTED:npm-token]',
+    },
+];
+/**
+ * Validate that an observation does not contain sensitive data.
+ *
+ * Uses the contract-level `containsSensitiveData` check plus additional
+ * pattern matching for known credential formats.
+ *
+ * @param observation - The observation to validate
+ * @returns Validation result with issues if sensitive data found
+ */
+export function validateNoSensitiveData(observation) {
+    const issues = [];
+    // Run the contract-level check first
+    const contractCheck = containsSensitiveData(observation);
+    if (contractCheck.hasSensitiveData) {
+        issues.push(...contractCheck.issues);
+    }
+    // Run additional pattern checks against the serialized payload
+    const serialized = JSON.stringify(observation);
+    for (const { name, pattern } of SENSITIVE_PATTERNS) {
+        // Reset lastIndex for global regex patterns
+        pattern.lastIndex = 0;
+        if (pattern.test(serialized)) {
+            issues.push(`Sensitive pattern detected: ${name}`);
+        }
+    }
+    if (issues.length > 0) {
+        debug('sensitive data detected in observation', {
+            issueCount: issues.length,
+            patterns: issues,
+        });
+    }
+    return {
+        hasSensitiveData: issues.length > 0,
+        issues,
+    };
+}
+// =============================================================================
+// Redaction
+// =============================================================================
+/**
+ * Deep-clone an observation and redact all known sensitive patterns from
+ * string values. This operates on the JSON serialization to catch values
+ * regardless of nesting depth.
+ *
+ * The returned observation is safe to persist.
+ *
+ * @param observation - The observation to redact
+ * @returns A new observation with sensitive values replaced
+ */
+export function redactSensitiveFields(observation) {
+    debug('redacting sensitive fields from observation', { kind: observation.kind });
+    let serialized = JSON.stringify(observation);
+    for (const { pattern, replacement } of SENSITIVE_PATTERNS) {
+        // Reset lastIndex for global regex patterns
+        pattern.lastIndex = 0;
+        serialized = serialized.replace(pattern, replacement);
+    }
+    return JSON.parse(serialized);
+}

package/dist/status.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Kindling Status Utility (KINDLING-014)
+ *
+ * Provides a decoupled status summary for Kindling integration.
+ * Returns observation counts, database size, and retention config
+ * without coupling to any specific CLI framework.
+ *
+ * Usage:
+ *   const status = await getKindlingStatus(config, store);
+ *   // => { enabled: true, observationCount: 42, dbSizeBytes: 81920, ... }
+ */
+/**
+ * Kindling status summary returned by getKindlingStatus()
+ */
+export interface KindlingStatus {
+    /** Whether Kindling is enabled in config */
+    enabled: boolean;
+    /** Total number of observations stored (undefined if disabled) */
+    observationCount?: number;
+    /** Database file size in bytes (undefined if disabled or no DB) */
+    dbSizeBytes?: number;
+    /** Configured retention period in days (undefined if disabled) */
+    retentionDays?: number;
+    /** ISO8601 timestamp of the most recent observation (undefined if none) */
+    lastObservationAt?: string;
+}
+/**
+ * Minimal config shape needed for status checks.
+ * This avoids importing from config.ts (built by other agent).
+ */
+export interface KindlingStatusConfig {
+    enabled: boolean;
+    database?: string;
+    retention?: {
+        days?: number;
+    };
+}
+/**
+ * Minimal store interface for status queries.
+ * Implementations can be KindlingService, a direct SQLite handle, or a mock.
+ */
+export interface KindlingStatusStore {
+    /**
+     * Count all observations in the store.
+     * Returns 0 if the store is empty.
+     */
+    countObservations(): Promise<number>;
+    /**
+     * Get the database file size in bytes.
+     * Returns 0 if the database does not exist or cannot be read.
+     */
+    getDatabaseSizeBytes(): Promise<number>;
+    /**
+     * Get the timestamp of the most recent observation.
+     * Returns undefined if no observations exist.
+     */
+    getLastObservationTimestamp(): Promise<string | undefined>;
+}
+/**
+ * Get Kindling integration status.
+ *
+ * If store is not provided or config is disabled, returns a minimal
+ * disabled status. This function never throws -- it handles errors
+ * gracefully and returns partial information.
+ *
+ * @param config - Kindling configuration (at minimum, { enabled: boolean })
+ * @param store - Optional store interface for querying observation data
+ * @returns KindlingStatus summary
+ *
+ * @example
+ * ```typescript
+ * import { getKindlingStatus } from './status.js';
+ *
+ * // Disabled (no store needed)
+ * const status = await getKindlingStatus({ enabled: false });
+ * // => { enabled: false }
+ *
+ * // Enabled with store
+ * const status = await getKindlingStatus(
+ *   { enabled: true, retention: { days: 90 } },
+ *   myStore,
+ * );
+ * // => { enabled: true, observationCount: 42, dbSizeBytes: 81920,
+ * //      retentionDays: 90, lastObservationAt: '2026-02-15T...' }
+ * ```
+ */
+export declare function getKindlingStatus(config: KindlingStatusConfig, store?: KindlingStatusStore): Promise<KindlingStatus>;
+/**
+ * Format a KindlingStatus as a human-readable string.
+ * Useful for CLI output without coupling to a specific formatter.
+ *
+ * @example
+ * ```typescript
+ * const status = await getKindlingStatus(config, store);
+ * console.log(formatKindlingStatus(status));
+ * // Kindling: enabled
+ * // Observations: 42
+ * // Database size: 80 KB
+ * // Retention: 90 days
+ * // Last observation: 2026-02-15T10:30:00.000Z
+ * ```
+ */
+export declare function formatKindlingStatus(status: KindlingStatus): string;
+//# sourceMappingURL=status.d.ts.map

package/dist/status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../src/status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,4CAA4C;IAC5C,OAAO,EAAE,OAAO,CAAC;IAEjB,kEAAkE;IAClE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,kEAAkE;IAClE,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,2EAA2E;IAC3E,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAMD;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE;QACV,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;CACH;AAMD;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAErC;;;OAGG;IACH,oBAAoB,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAExC;;;OAGG;IACH,2BAA2B,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CAC5D;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,oBAAoB,EAC5B,KAAK,CAAC,EAAE,mBAAmB,GAC1B,OAAO,CAAC,cAAc,CAAC,CA4BzB;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CA4BnE"}

package/dist/status.js

@@ -0,0 +1,136 @@
+/**
+ * Kindling Status Utility (KINDLING-014)
+ *
+ * Provides a decoupled status summary for Kindling integration.
+ * Returns observation counts, database size, and retention config
+ * without coupling to any specific CLI framework.
+ *
+ * Usage:
+ *   const status = await getKindlingStatus(config, store);
+ *   // => { enabled: true, observationCount: 42, dbSizeBytes: 81920, ... }
+ */
+// =============================================================================
+// Status Function
+// =============================================================================
+/**
+ * Get Kindling integration status.
+ *
+ * If store is not provided or config is disabled, returns a minimal
+ * disabled status. This function never throws -- it handles errors
+ * gracefully and returns partial information.
+ *
+ * @param config - Kindling configuration (at minimum, { enabled: boolean })
+ * @param store - Optional store interface for querying observation data
+ * @returns KindlingStatus summary
+ *
+ * @example
+ * ```typescript
+ * import { getKindlingStatus } from './status.js';
+ *
+ * // Disabled (no store needed)
+ * const status = await getKindlingStatus({ enabled: false });
+ * // => { enabled: false }
+ *
+ * // Enabled with store
+ * const status = await getKindlingStatus(
+ *   { enabled: true, retention: { days: 90 } },
+ *   myStore,
+ * );
+ * // => { enabled: true, observationCount: 42, dbSizeBytes: 81920,
+ * //      retentionDays: 90, lastObservationAt: '2026-02-15T...' }
+ * ```
+ */
+export async function getKindlingStatus(config, store) {
+    // Fast path: disabled
+    if (!config.enabled) {
+        return { enabled: false };
+    }
+    // Enabled but no store available
+    if (!store) {
+        return {
+            enabled: true,
+            retentionDays: config.retention?.days,
+        };
+    }
+    // Enabled with store -- query for status data
+    const [observationCount, dbSizeBytes, lastObservationAt] = await Promise.all([
+        safeCall(() => store.countObservations(), 0),
+        safeCall(() => store.getDatabaseSizeBytes(), 0),
+        safeCall(() => store.getLastObservationTimestamp(), undefined),
+    ]);
+    return {
+        enabled: true,
+        observationCount,
+        dbSizeBytes,
+        retentionDays: config.retention?.days,
+        lastObservationAt,
+    };
+}
+// =============================================================================
+// Formatting Utilities
+// =============================================================================
+/**
+ * Format a KindlingStatus as a human-readable string.
+ * Useful for CLI output without coupling to a specific formatter.
+ *
+ * @example
+ * ```typescript
+ * const status = await getKindlingStatus(config, store);
+ * console.log(formatKindlingStatus(status));
+ * // Kindling: enabled
+ * // Observations: 42
+ * // Database size: 80 KB
+ * // Retention: 90 days
+ * // Last observation: 2026-02-15T10:30:00.000Z
+ * ```
+ */
+export function formatKindlingStatus(status) {
+    const lines = [];
+    lines.push(`Kindling: ${status.enabled ? 'enabled' : 'disabled'}`);
+    if (!status.enabled) {
+        return lines.join('\n');
+    }
+    if (status.observationCount !== undefined) {
+        lines.push(`Observations: ${status.observationCount.toLocaleString()}`);
+    }
+    if (status.dbSizeBytes !== undefined) {
+        lines.push(`Database size: ${formatBytes(status.dbSizeBytes)}`);
+    }
+    if (status.retentionDays !== undefined) {
+        lines.push(`Retention: ${status.retentionDays} days`);
+    }
+    if (status.lastObservationAt) {
+        lines.push(`Last observation: ${status.lastObservationAt}`);
+    }
+    else if (status.observationCount === 0) {
+        lines.push('Last observation: none');
+    }
+    return lines.join('\n');
+}
+// =============================================================================
+// Internal Helpers
+// =============================================================================
+/**
+ * Call an async function and return a fallback value on error.
+ * Ensures getKindlingStatus never throws.
+ */
+async function safeCall(fn, fallback) {
+    try {
+        return await fn();
+    }
+    catch {
+        return fallback;
+    }
+}
+/**
+ * Format bytes into a human-readable string.
+ */
+function formatBytes(bytes) {
+    if (bytes === 0)
+        return '0 B';
+    const units = ['B', 'KB', 'MB', 'GB'];
+    const k = 1024;
+    const i = Math.min(Math.floor(Math.log(bytes) / Math.log(k)), units.length - 1);
+    const value = bytes / Math.pow(k, i);
+    return `${value < 10 ? value.toFixed(1) : Math.round(value)} ${units[i]}`;
+}

package/dist/utils/debug.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Minimal debug logging utility for kindling-integration package
+ *
+ * Self-contained to avoid dependency on @eddacraft/anvil-core
+ */
+type DebugNamespace = 'kindling';
+export declare function createDebugger(_namespace: DebugNamespace): (message: string, data?: unknown) => void;
+export {};
+//# sourceMappingURL=debug.d.ts.map

package/dist/utils/debug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../../src/utils/debug.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,KAAK,cAAc,GAAG,UAAU,CAAC;AAsDjC,wBAAgB,cAAc,CAC5B,UAAU,EAAE,cAAc,GACzB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAE3C"}

package/dist/utils/debug.js

@@ -0,0 +1,55 @@
+/**
+ * Minimal debug logging utility for kindling-integration package
+ *
+ * Self-contained to avoid dependency on @eddacraft/anvil-core
+ */
+function isDebugEnabled() {
+    const anvilDebug = process.env.ANVIL_DEBUG;
+    const debug = process.env.DEBUG;
+    if (anvilDebug === '1' || anvilDebug === 'true') {
+        return true;
+    }
+    if (debug) {
+        if (debug.includes('anvil:*') || debug.includes('anvil:kindling')) {
+            return true;
+        }
+    }
+    return false;
+}
+function sanitizeForLog(value) {
+    let sanitized = value.replace(/\b(sk-|ghp_|ghu_)[A-Za-z0-9_-]+/g, '[REDACTED]');
+    sanitized = sanitized.replace(/Bearer\s+[A-Za-z0-9_.+/=-]+/g, 'Bearer [REDACTED]');
+    sanitized = sanitized.replace(/\b[0-9a-fA-F]{40,}\b/g, '[REDACTED]');
+    sanitized = sanitized.replace(/\b[A-Za-z0-9+/]{20,}={0,3}\b/g, '[REDACTED]');
+    return sanitized;
+}
+function debugLog(namespace, message, data) {
+    if (!isDebugEnabled()) {
+        return;
+    }
+    const timestamp = new Date().toISOString();
+    const prefix = `[${timestamp}] [anvil:${namespace}]`;
+    const sanitizedMessage = sanitizeForLog(message);
+    /* eslint-disable no-console -- debug utility */
+    if (data !== undefined) {
+        if (data instanceof Error) {
+            console.debug(`${prefix} ${sanitizedMessage}:`, sanitizeForLog(data.message));
+            if (data.stack) {
+                console.debug(`${prefix} Stack:`, sanitizeForLog(data.stack));
+            }
+        }
+        else if (typeof data === 'string') {
+            console.debug(`${prefix} ${sanitizedMessage}:`, sanitizeForLog(data));
+        }
+        else {
+            console.debug(`${prefix} ${sanitizedMessage}:`, data);
+        }
+    }
+    else {
+        console.debug(`${prefix} ${sanitizedMessage}`);
+    }
+    /* eslint-enable no-console */
+}
+export function createDebugger(_namespace) {
+    return (message, data) => debugLog('kindling', message, data);
+}