@webpresso/agent-kit 0.21.0

package/dist/esm/ai-tools/write-file.js

@@ -0,0 +1,165 @@
+import { getErrorMessage } from '#format/errors.js';
+import { isValidRelativePath } from './shared/validate-path.js';
+function validatePath(path) {
+    if (!isValidRelativePath(path)) {
+        return {
+            success: false,
+            output: 'Invalid path: path traversal not allowed',
+            error: 'Path must be relative and cannot contain ".."',
+        };
+    }
+    return null;
+}
+function checkDangerousPatterns(path) {
+    const dangerousPatterns = [/\.env$/i, /credentials/i, /secret/i, /\.pem$/i, /\.key$/i];
+    for (const pattern of dangerousPatterns) {
+        if (pattern.test(path)) {
+            return {
+                success: false,
+                output: `Cannot write to sensitive file: ${path}`,
+                error: 'Writing to credential or secret files is not allowed',
+            };
+        }
+    }
+    return null;
+}
+async function acquireFileLock(storage, path, lockerId) {
+    const locked = await storage.lockFile(path, lockerId).catch(() => false);
+    if (locked) {
+        return null;
+    }
+    const lockInfo = await storage.isLocked(path).catch(() => ({ locked: true }));
+    const lockerInfo = lockInfo.locked && 'lockerId' in lockInfo && typeof lockInfo.lockerId === 'string'
+        ? ` by ${lockInfo.lockerId}`
+        : '';
+    return {
+        success: false,
+        output: `File is currently locked${lockerInfo}`,
+        error: 'File locked',
+    };
+}
+function handleStagedChange(path, content, exists, originalContent, context) {
+    if (!context.pendingChanges) {
+        return {
+            success: false,
+            output: 'Pending changes manager not configured',
+            error: 'No pending changes manager provided in context',
+        };
+    }
+    const change = exists
+        ? context.pendingChanges.addModify(path, originalContent ?? '', content, 'AI agent proposed change')
+        : context.pendingChanges.addCreate(path, content, 'AI agent proposed change');
+    return {
+        success: true,
+        output: exists
+            ? `Staged modification: ${path} (${content.split('\n').length} lines)`
+            : `Staged creation: ${path} (${content.split('\n').length} lines)`,
+        data: {
+            path,
+            changeId: change.id,
+            staged: true,
+            created: !exists,
+        },
+    };
+}
+function performFileWrite(path, content, exists, originalContent, context, toolCallId) {
+    const lineCount = content.split('\n').length;
+    const byteSize = new TextEncoder().encode(content).length;
+    const operation = exists ? 'modify' : 'create';
+    if (context.changeTracker) {
+        context.changeTracker.recordChange({
+            path,
+            before: originalContent,
+            after: content,
+            operation,
+            toolCallId,
+        });
+    }
+    return {
+        success: true,
+        output: exists
+            ? `Updated file: ${path} (${lineCount} lines, ${byteSize} bytes)`
+            : `Created file: ${path} (${lineCount} lines, ${byteSize} bytes)`,
+        data: { path, lineCount, byteSize, created: !exists },
+    };
+}
+function validateInputs(path, context) {
+    const pathCheck = validatePath(path);
+    if (pathCheck)
+        return pathCheck;
+    const dangerousCheck = checkDangerousPatterns(path);
+    if (dangerousCheck)
+        return dangerousCheck;
+    if (!context.storage) {
+        return {
+            success: false,
+            output: 'Storage adapter not configured',
+            error: 'No storage adapter provided in context',
+        };
+    }
+    return null;
+}
+function handleWriteError(error) {
+    const message = getErrorMessage(error);
+    return {
+        success: false,
+        output: `Failed to write file: ${message}`,
+        error: message,
+    };
+}
+async function executeFileWrite(path, content, storage, context) {
+    const exists = await storage.exists(path);
+    const originalContent = exists ? await storage.readFile(path) : null;
+    if (context.pendingChanges) {
+        return handleStagedChange(path, content, exists, originalContent, context);
+    }
+    await storage.writeFile(path, content);
+    const toolCallId = context.toolCallId ?? 'unknown';
+    return performFileWrite(path, content, exists, originalContent, context, toolCallId);
+}
+export const writeFileTool = {
+    name: 'write_file',
+    description: 'Write content to a file at the specified path. Creates the file if it does not exist, or overwrites if it does. Use this to create new files or completely replace existing ones.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            path: {
+                type: 'string',
+                description: 'The relative path to the file to write (e.g., "src/utils/helper.ts")',
+            },
+            content: {
+                type: 'string',
+                description: 'The full content to write to the file',
+            },
+        },
+        required: ['path', 'content'],
+    },
+    async execute(input, context) {
+        const path = input.path;
+        const content = input.content;
+        const lockerId = context.lockerId ?? context.userId ?? 'ai-agent';
+        const validationError = validateInputs(path, context);
+        if (validationError)
+            return validationError;
+        if (!context.storage) {
+            return {
+                success: false,
+                output: 'Storage adapter not configured',
+                error: 'No storage adapter provided in context',
+            };
+        }
+        const lockError = await acquireFileLock(context.storage, path, lockerId);
+        if (lockError)
+            return lockError;
+        try {
+            return await executeFileWrite(path, content, context.storage, context);
+        }
+        catch (error) {
+            return handleWriteError(error);
+        }
+        finally {
+            await context.storage.unlockFile(path, lockerId).catch(() => { });
+        }
+    },
+};
+//# sourceMappingURL=write-file.js.map

package/dist/esm/audit/_budgets.d.ts

@@ -0,0 +1,28 @@
+export declare const DEFAULT_BUDGETS: {
+    readonly 'codex-skill-listing-total': {
+        readonly max_bytes: 7000;
+    };
+    readonly 'claude-skill-description-each': {
+        readonly max_bytes: 800;
+    };
+    readonly 'agents-md-section-each': {
+        readonly max_bytes: 4096;
+        readonly suggest_compact_at: 0.75;
+    };
+    readonly 'skill-md-total-each': {
+        readonly max_bytes: 16384;
+    };
+};
+export type BudgetKey = keyof typeof DEFAULT_BUDGETS;
+export type BudgetEntry = {
+    max_bytes: number;
+    suggest_compact_at?: number;
+    warn_pct?: number;
+};
+export type ResolvedBudgets = typeof DEFAULT_BUDGETS & Record<string, BudgetEntry>;
+/**
+ * Load budgets from `.agent/.audit-budgets.yaml` if present, merging with defaults.
+ * Unknown keys from the file are accepted; missing keys fall back to defaults.
+ */
+export declare function loadBudgets(cwd: string): ResolvedBudgets;
+//# sourceMappingURL=_budgets.d.ts.map

package/dist/esm/audit/_budgets.js

@@ -0,0 +1,60 @@
+/**
+ * Agent-kit audit budgets — default values and per-repo override loading.
+ *
+ * Consumers may create `.agent/.audit-budgets.yaml` to override the defaults.
+ * Missing keys fall back to `DEFAULT_BUDGETS`.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+const budgetEntrySchema = z.object({
+    max_bytes: z.number().int().positive(),
+    suggest_compact_at: z.number().min(0).max(1).optional(),
+    warn_pct: z.number().min(1).optional(),
+});
+const budgetFileSchema = z.object({
+    budgets: z.record(z.string(), budgetEntrySchema),
+});
+export const DEFAULT_BUDGETS = {
+    'codex-skill-listing-total': { max_bytes: 7000 },
+    'claude-skill-description-each': { max_bytes: 800 },
+    'agents-md-section-each': { max_bytes: 4096, suggest_compact_at: 0.75 },
+    'skill-md-total-each': { max_bytes: 16384 },
+};
+/**
+ * Load budgets from `.agent/.audit-budgets.yaml` if present, merging with defaults.
+ * Unknown keys from the file are accepted; missing keys fall back to defaults.
+ */
+export function loadBudgets(cwd) {
+    const configPath = path.join(cwd, '.agent', '.audit-budgets.yaml');
+    if (!existsSync(configPath)) {
+        return { ...DEFAULT_BUDGETS };
+    }
+    let raw;
+    try {
+        raw = readFileSync(configPath, 'utf8');
+    }
+    catch {
+        return { ...DEFAULT_BUDGETS };
+    }
+    // Lazy import yaml to keep startup fast
+    let parsed;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { parse: parseYaml } = require('yaml');
+        parsed = parseYaml(raw);
+    }
+    catch {
+        return { ...DEFAULT_BUDGETS };
+    }
+    const result = budgetFileSchema.safeParse(parsed);
+    if (!result.success) {
+        return { ...DEFAULT_BUDGETS };
+    }
+    // Merge: file overrides defaults; unknown file keys are included as-is
+    return {
+        ...DEFAULT_BUDGETS,
+        ...result.data.budgets,
+    };
+}
+//# sourceMappingURL=_budgets.js.map

package/dist/esm/audit/absolute-path-policy.d.ts

@@ -0,0 +1,5 @@
+import type { RepoAuditResult, RepoAuditViolation } from './repo-guardrails.js';
+export declare function shouldScanAbsolutePathPolicyPath(relativePath: string): boolean;
+export declare function findAbsolutePathPolicyViolationsInText(relativePath: string, text: string): RepoAuditViolation[];
+export declare function auditAbsolutePathPolicy(rootDirectory?: string): RepoAuditResult;
+//# sourceMappingURL=absolute-path-policy.d.ts.map

package/dist/esm/audit/absolute-path-policy.js

@@ -0,0 +1,97 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+const SKIP_DIRS = new Set([
+    '.git',
+    'node_modules',
+    '.agent',
+    '.agents',
+    '.claude',
+    '.codex',
+    '.cursor',
+    '.gemini',
+    '.omc',
+    '.omx',
+    '.opencode',
+    '.windsurf',
+    'dist',
+    'coverage',
+    'playwright-report',
+    'test-results',
+    'docs',
+    'catalog',
+    'blueprints',
+    'logs',
+    'reports',
+    'fixtures',
+    '__fixtures__',
+    'test-fixtures',
+]);
+const SCAN_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.mts', '.cts']);
+const TEST_FILE_MARKERS = ['.test.', '.spec.', '.integration.test.'];
+const HARD_CODED_RELATIVE_FILESYSTEM_PATH_PATTERNS = [
+    /(?:[A-Za-z_$][\w$]*\.)?(?:resolve|join)\s*\(\s*(?:import\.meta\.dirname|__dirname|process\.cwd\(\))\s*,\s*["'](?:\.\.?\/)+/u,
+    /(?:[A-Za-z_$][\w$]*\.)?(?:resolve|join)\s*\(\s*(?:import\.meta\.dirname|__dirname|process\.cwd\(\))\s*,\s*["']\.\.?["']/u,
+    /new\s+URL\(\s*["'](?:\.\.?\/)+[^"']*["']\s*,\s*import\.meta\.url\s*\)/u,
+];
+export function shouldScanAbsolutePathPolicyPath(relativePath) {
+    const normalized = relativePath.replace(/\\/gu, '/');
+    if (TEST_FILE_MARKERS.some((marker) => normalized.includes(marker)))
+        return false;
+    if (normalized.endsWith('.d.ts'))
+        return false;
+    const extensionIndex = normalized.lastIndexOf('.');
+    const extension = extensionIndex === -1 ? '' : normalized.slice(extensionIndex);
+    return SCAN_EXTENSIONS.has(extension);
+}
+export function findAbsolutePathPolicyViolationsInText(relativePath, text) {
+    const violations = [];
+    const lines = text.split('\n');
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index] ?? '';
+        const trimmed = line.trimStart();
+        if (trimmed.startsWith('//') || trimmed.startsWith('/*') || trimmed.startsWith('*'))
+            continue;
+        if (!HARD_CODED_RELATIVE_FILESYSTEM_PATH_PATTERNS.some((pattern) => pattern.test(line))) {
+            continue;
+        }
+        violations.push({
+            file: relativePath,
+            message: `hardcoded relative filesystem path at line ${index + 1}; derive an absolute path from an explicit repo/package/runtime anchor instead`,
+        });
+    }
+    return violations;
+}
+export function auditAbsolutePathPolicy(rootDirectory = process.cwd()) {
+    const root = resolve(rootDirectory);
+    const violations = [];
+    const walk = (directory) => {
+        let checked = 0;
+        for (const entry of readdirSync(directory)) {
+            if (SKIP_DIRS.has(entry))
+                continue;
+            const fullPath = join(directory, entry);
+            const stat = statSync(fullPath);
+            if (stat.isDirectory()) {
+                checked += walk(fullPath);
+                continue;
+            }
+            if (!stat.isFile())
+                continue;
+            const relativePath = relative(root, fullPath).replace(/\\/gu, '/');
+            if (!shouldScanAbsolutePathPolicyPath(relativePath))
+                continue;
+            checked += 1;
+            const text = readFileSync(fullPath, 'utf8');
+            violations.push(...findAbsolutePathPolicyViolationsInText(relativePath, text));
+        }
+        return checked;
+    };
+    const checked = walk(root);
+    return {
+        ok: violations.length === 0,
+        title: 'absolute path policy',
+        checked,
+        violations,
+    };
+}
+//# sourceMappingURL=absolute-path-policy.js.map

package/dist/esm/audit/agent-cost.d.ts

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

package/dist/esm/audit/agent-cost.js

@@ -0,0 +1,111 @@
+import { execSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+function hasFilesWithExtension(root, ext) {
+    try {
+        const out = execSync(`find . \\( -path ./node_modules -o -path ./.git -o -path ./dist -o -path ./build \\) -prune -o -name "*.${ext}" -print -quit`, { cwd: root, encoding: 'utf-8', timeout: 3000, stdio: ['pipe', 'pipe', 'ignore'] });
+        return out.trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+function readJson(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+        return parsed !== null && typeof parsed === 'object'
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function isLspDisabled(pluginKey) {
+    // Check user-global settings first, then fall back to false (assume not disabled).
+    const homeDir = process.env['HOME'] ?? process.env['USERPROFILE'] ?? '';
+    const globalSettings = homeDir ? readJson(join(homeDir, '.claude', 'settings.json')) : null;
+    const plugins = globalSettings?.['enabledPlugins'];
+    if (plugins !== null && typeof plugins === 'object') {
+        const pluginsMap = plugins;
+        const fullKey = `${pluginKey}@claude-plugins-official`;
+        if (fullKey in pluginsMap)
+            return pluginsMap[fullKey] === false;
+    }
+    return false;
+}
+export async function auditAgentCost(cwd) {
+    const violations = [];
+    let checked = 0;
+    // ─── Check 1: .claudeignore present ───────────────────────────────────────
+    checked++;
+    if (!existsSync(join(cwd, '.claudeignore'))) {
+        violations.push({
+            file: '.claudeignore',
+            message: 'Missing .claudeignore — Claude Code will traverse node_modules, dist, and build ' +
+                'artifacts during autonomous exploration. Create .claudeignore (gitignore syntax) ' +
+                'with node_modules/, .webpresso/, .wrangler/, packages/*/dist/ etc. ' +
+                'Typical savings: 30–40% fewer input tokens per session.',
+        });
+    }
+    // ─── Check 2: effortLevel in project .claude/settings.json ────────────────
+    checked++;
+    const settings = readJson(join(cwd, '.claude', 'settings.json'));
+    if (settings === null) {
+        violations.push({
+            file: '.claude/settings.json',
+            message: '.claude/settings.json not found. Consider creating it with "effortLevel": "medium" ' +
+                'to cap thinking token spend for this project. ' +
+                'The global ~/.claude/settings.json default may be "xhigh" (max thinking tokens). ' +
+                'Override per-session with /effort high when planning.',
+        });
+    }
+    else if (!('effortLevel' in settings)) {
+        violations.push({
+            file: '.claude/settings.json',
+            message: 'effortLevel not set in project settings — inherits from ~/.claude/settings.json. ' +
+                'If the global setting is "xhigh", every request in this project runs max thinking tokens. ' +
+                'Add "effortLevel": "medium" here to scope the budget. Override with /effort high per-session.',
+        });
+    }
+    // ─── Check 3: LSP plugins for languages absent from the repo ──────────────
+    const lspChecks = [
+        { plugin: 'rust-analyzer-lsp', ext: 'rs', lang: 'Rust' },
+        { plugin: 'gopls-lsp', ext: 'go', lang: 'Go' },
+    ];
+    for (const { plugin, ext, lang } of lspChecks) {
+        checked++;
+        if (!hasFilesWithExtension(cwd, ext) && !isLspDisabled(plugin)) {
+            violations.push({
+                message: `No .${ext} (${lang}) files found — ${plugin} is likely unused. ` +
+                    `Disable it in ~/.claude/settings.json: "${plugin}@claude-plugins-official": false. ` +
+                    `LSP tool schemas inject into every session system prompt (~1–3K tokens each).`,
+            });
+        }
+    }
+    // ─── Check 4: .ignore present (OpenCode / ripgrep) ───────────────────────
+    // OpenCode uses ripgrep and respects .gitignore automatically for build
+    // artifacts. But tracked directories (e.g. blueprints/completed/) need
+    // a separate .ignore (ripgrep-native) to be excluded from agent sessions.
+    checked++;
+    if (!existsSync(join(cwd, '.ignore'))) {
+        violations.push({
+            file: '.ignore',
+            message: 'Missing .ignore — OpenCode uses ripgrep and respects .gitignore for build artifacts, ' +
+                'but tracked directories (e.g. webpresso/blueprints/completed/) are still traversed. ' +
+                'Create .ignore with any large tracked dirs to exclude from agent sessions. ' +
+                'Does not affect git. See: opencode.ai/docs/tools/#ignore-patterns',
+        });
+    }
+    // Advisory audit — violations are warnings, not blocking errors.
+    // Cost config is a recommendation, not a hard correctness gate.
+    return {
+        ok: true,
+        title: 'agent cost config',
+        checked,
+        violations,
+    };
+}
+//# sourceMappingURL=agent-cost.js.map

package/dist/esm/audit/agents.d.ts

@@ -0,0 +1,3 @@
+import type { RepoAuditResult } from './repo-guardrails.js';
+export declare function auditAgents(rootDirectory?: string): RepoAuditResult;
+//# sourceMappingURL=agents.d.ts.map