@webpresso/agent-kit 0.21.0

package/dist/esm/hooks/pretool-guard/validators/path-contract.js

@@ -0,0 +1,105 @@
+export const BLUEPRINTS_ROOT = 'webpresso/blueprints';
+const DEFAULT_BLUEPRINTS_ROOT = 'blueprints';
+export const TECH_DEBT_ROOT = 'webpresso/tech-debt';
+const DEFAULT_TECH_DEBT_ROOT = 'tech-debt';
+const BLUEPRINT_STATUSES = new Set([
+    'draft',
+    'planned',
+    'parked',
+    'in-progress',
+    'completed',
+    'archived',
+]);
+const KEBAB_CASE_SEGMENT = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+// Both canonical blueprint-root layouts accepted by default.
+const CANONICAL_BLUEPRINTS_ROOTS = [BLUEPRINTS_ROOT, DEFAULT_BLUEPRINTS_ROOT];
+const CANONICAL_TECH_DEBT_ROOTS = [TECH_DEBT_ROOT, DEFAULT_TECH_DEBT_ROOT];
+function normalizePlanningPath(filePath) {
+    return filePath.replace(/\\/g, '/').replace(/^\//, '');
+}
+function matchesRoot(normalized, root) {
+    return normalized === root || normalized.startsWith(`${root}/`);
+}
+/**
+ * Returns true if the path is under any accepted blueprints root.
+ * Pass `blueprintsRoot` to restrict to a single configured root.
+ */
+export function isBlueprintPath(filePath, blueprintsRoot) {
+    const normalized = normalizePlanningPath(filePath);
+    if (blueprintsRoot !== undefined)
+        return matchesRoot(normalized, blueprintsRoot);
+    return CANONICAL_BLUEPRINTS_ROOTS.some((root) => matchesRoot(normalized, root));
+}
+export function getNonCanonicalPlanningPathViolation(filePath, blueprintsRoot, techDebtRoot) {
+    const normalized = normalizePlanningPath(filePath);
+    const bpRoots = blueprintsRoot ? [blueprintsRoot] : CANONICAL_BLUEPRINTS_ROOTS;
+    const tdRoots = techDebtRoot ? [techDebtRoot] : CANONICAL_TECH_DEBT_ROOTS;
+    if (bpRoots.some((r) => matchesRoot(normalized, r)) ||
+        tdRoots.some((r) => matchesRoot(normalized, r))) {
+        return null;
+    }
+    if (!normalized.endsWith('.md'))
+        return null;
+    const parts = normalized.split('/');
+    if (parts.length < 2)
+        return null;
+    const secondSegment = parts[1];
+    if (secondSegment === 'blueprints' ||
+        secondSegment === 'tech-debt' ||
+        secondSegment === 'plan-history') {
+        const bpLabel = blueprintsRoot
+            ? `${blueprintsRoot}/`
+            : `${DEFAULT_BLUEPRINTS_ROOT}/ or ${BLUEPRINTS_ROOT}/`;
+        const tdLabel = techDebtRoot
+            ? `${techDebtRoot}/`
+            : `${DEFAULT_TECH_DEBT_ROOT}/ or ${TECH_DEBT_ROOT}/`;
+        return `Planning markdown must live under ${bpLabel} or ${tdLabel}. Got: ${normalized}`;
+    }
+    if (parts[0] === 'platform') {
+        const expectedBp = blueprintsRoot ?? BLUEPRINTS_ROOT;
+        return `Legacy planning paths under platform/* are no longer supported. Move blueprints to ${expectedBp}/.`;
+    }
+    return null;
+}
+/**
+ * Returns true if the path is the canonical `_overview.md` location for any
+ * accepted blueprints root layout (or the explicitly provided root).
+ */
+export function isCanonicalBlueprintOverviewPath(filePath, blueprintsRoot) {
+    const normalized = normalizePlanningPath(filePath);
+    const roots = blueprintsRoot ? [blueprintsRoot] : CANONICAL_BLUEPRINTS_ROOTS;
+    return roots.some((root) => {
+        const rootParts = root.split('/');
+        const parts = normalized.split('/');
+        const n = rootParts.length;
+        return (parts.length === n + 3 &&
+            parts.slice(0, n).join('/') === root &&
+            BLUEPRINT_STATUSES.has(parts[n] ?? '') &&
+            KEBAB_CASE_SEGMENT.test(parts[n + 1] ?? '') &&
+            parts[n + 2] === '_overview.md');
+    });
+}
+export function getBlueprintPathViolation(filePath, blueprintsRoot) {
+    const normalized = normalizePlanningPath(filePath);
+    if (!isBlueprintPath(normalized, blueprintsRoot))
+        return null;
+    if (normalized.endsWith('/_overview.md') &&
+        !isCanonicalBlueprintOverviewPath(normalized, blueprintsRoot)) {
+        const root = blueprintsRoot ?? BLUEPRINTS_ROOT;
+        return `Blueprint overview files must live at ${root}/<status>/<slug>/_overview.md. Got: ${normalized}`;
+    }
+    const roots = blueprintsRoot ? [blueprintsRoot] : CANONICAL_BLUEPRINTS_ROOTS;
+    for (const root of roots) {
+        const rootParts = root.split('/');
+        const parts = normalized.split('/');
+        const n = rootParts.length;
+        if (parts.length === n + 2 &&
+            parts.slice(0, n).join('/') === root &&
+            BLUEPRINT_STATUSES.has(parts[n] ?? '') &&
+            normalized.endsWith('.md')) {
+            return `Blueprint markdown files cannot live directly under a status directory. Move this file to ${root}/${parts[n]}/<slug>/_overview.md or place supporting docs inside ${root}/${parts[n]}/<slug>/. Got: ${normalized}`;
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=path-contract.js.map

package/dist/esm/hooks/pretool-guard/validators/plan-frontmatter.d.ts

@@ -0,0 +1,13 @@
+import type { ToolInput, ValidationResult } from '#hooks/shared/types';
+interface Violation {
+    field: string;
+    message: string;
+}
+export declare function extractFrontmatterBlock(content: string): string | null;
+export declare function parseFrontmatter(yamlBlock: string): Record<string, unknown> | null;
+export declare function collectFieldViolations(data: Record<string, unknown>): Violation[];
+export declare function countTaskHeadings(content: string): number;
+export declare function detectWrongTaskFormat(content: string): number;
+export declare function validatePlanFrontmatter(input: ToolInput): ValidationResult;
+export {};
+//# sourceMappingURL=plan-frontmatter.d.ts.map

package/dist/esm/hooks/pretool-guard/validators/plan-frontmatter.js

@@ -0,0 +1,121 @@
+import jsYaml from 'js-yaml';
+import { getContent, getFilePath } from '#hooks/shared/types';
+import { getNonCanonicalPlanningPathViolation, isBlueprintPath } from './path-contract.js';
+import { createSkipResult } from './skip-result.js';
+// Keep aligned with webpresso/blueprint planStatusSchema + plan type enum.
+const VALID_TYPES = ['blueprint', 'parent-roadmap'];
+const VALID_STATUSES = ['draft', 'planned', 'parked', 'in-progress', 'completed', 'archived'];
+const VALID_COMPLEXITIES = ['XS', 'S', 'M', 'L', 'XL'];
+function shouldValidatePath(filePath) {
+    const normalized = filePath.startsWith('/') ? filePath.slice(1) : filePath;
+    const nonCanonicalPlanningPath = getNonCanonicalPlanningPathViolation(normalized);
+    const currentPath = isBlueprintPath(normalized);
+    const isOverviewFile = normalized.endsWith('/README.md') || normalized.endsWith('/_overview.md');
+    return !nonCanonicalPlanningPath && currentPath && isOverviewFile;
+}
+export function extractFrontmatterBlock(content) {
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    return match?.[1] ?? null;
+}
+export function parseFrontmatter(yamlBlock) {
+    try {
+        const result = jsYaml.load(yamlBlock);
+        if (typeof result === 'object' && result !== null)
+            return result;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function validateField(value, fieldName, validValues) {
+    if (value === undefined)
+        return { field: fieldName, message: `Missing required field: ${fieldName}` };
+    if (typeof value !== 'string' || !validValues.includes(value)) {
+        return {
+            field: fieldName,
+            message: `Invalid ${fieldName}: "${value}". Valid values: ${validValues.join(', ')}`,
+        };
+    }
+    return null;
+}
+export function collectFieldViolations(data) {
+    const violations = [];
+    const typeViolation = validateField(data.type, 'type', VALID_TYPES);
+    if (typeViolation)
+        violations.push(typeViolation);
+    const statusViolation = validateField(data.status, 'status', VALID_STATUSES);
+    if (statusViolation)
+        violations.push(statusViolation);
+    const complexityViolation = validateField(data.complexity, 'complexity', VALID_COMPLEXITIES);
+    if (complexityViolation)
+        violations.push(complexityViolation);
+    return violations;
+}
+export function countTaskHeadings(content) {
+    return content.match(/^####\s+Task\s+\d+(?:\.\d+)+:/gm)?.length ?? 0;
+}
+export function detectWrongTaskFormat(content) {
+    return content.match(/^###\s+Task\s+\d+(?:\.\d+)+:/gm)?.length ?? 0;
+}
+export function validatePlanFrontmatter(input) {
+    const filePath = getFilePath(input);
+    if (process.env.PLAN_FRONTMATTER_SKIP === '1')
+        return createSkipResult('plan-frontmatter');
+    if (!filePath || !shouldValidatePath(filePath)) {
+        if (filePath) {
+            const planningPathViolation = getNonCanonicalPlanningPathViolation(filePath);
+            if (planningPathViolation)
+                return { validator: 'plan-frontmatter', passed: false, message: planningPathViolation };
+        }
+        return { validator: 'plan-frontmatter', passed: true };
+    }
+    if (input.tool_input?.old_string !== undefined)
+        return { validator: 'plan-frontmatter', passed: true };
+    const content = getContent(input);
+    if (!content)
+        return { validator: 'plan-frontmatter', passed: true };
+    const yamlBlock = extractFrontmatterBlock(content);
+    if (!yamlBlock) {
+        return {
+            validator: 'plan-frontmatter',
+            passed: false,
+            message: 'Missing YAML frontmatter block (expected --- at start of file)',
+        };
+    }
+    const data = parseFrontmatter(yamlBlock);
+    if (!data) {
+        return {
+            validator: 'plan-frontmatter',
+            passed: false,
+            message: 'Invalid YAML in frontmatter block',
+        };
+    }
+    const violations = [...collectFieldViolations(data)];
+    const wrongFormatCount = detectWrongTaskFormat(content);
+    if (wrongFormatCount > 0) {
+        violations.push({
+            field: 'task_format',
+            message: `Found ${wrongFormatCount} task heading(s) with wrong format (use "#### Task X.Y:" not "### Task X.Y:")`,
+        });
+    }
+    if (violations.length > 0) {
+        const preview = violations.slice(0, 4).map((v) => `  ${v.field}: ${v.message}`);
+        const overflow = violations.length > 4 ? `\n  ...and ${violations.length - 4} more issues` : '';
+        return {
+            validator: 'plan-frontmatter',
+            passed: false,
+            message: `Blueprint validation failed:\n${preview.join('\n')}${overflow}`,
+        };
+    }
+    const taskCount = countTaskHeadings(content);
+    if (taskCount === 0) {
+        return {
+            validator: 'plan-frontmatter',
+            passed: true,
+            message: 'Warning: no task headings found (expected "#### Task X.Y:" format)',
+        };
+    }
+    return { validator: 'plan-frontmatter', passed: true };
+}
+//# sourceMappingURL=plan-frontmatter.js.map

package/dist/esm/hooks/pretool-guard/validators/skip-result.d.ts

@@ -0,0 +1,3 @@
+import type { ValidationResult } from '#hooks/shared/types';
+export declare function createSkipResult(validator: string, skipReason?: string): ValidationResult;
+//# sourceMappingURL=skip-result.d.ts.map

package/dist/esm/hooks/pretool-guard/validators/skip-result.js

@@ -0,0 +1,4 @@
+export function createSkipResult(validator, skipReason = 'Bypass enabled via FORBIDDEN_COMMANDS_SKIP=1 — exceptional cases only; restore guardrails immediately after the bypass run') {
+    return { validator, passed: true, skipped: true, skipReason };
+}
+//# sourceMappingURL=skip-result.js.map

package/dist/esm/hooks/pretool-guard/validators/test-quality.d.ts

@@ -0,0 +1,22 @@
+import type { ToolInput, ValidationResult } from '#hooks/shared/types';
+export declare const MUTATION_GAMING_PATTERNS: Array<{
+    pattern: RegExp;
+    description: string;
+    fileLevel?: boolean;
+}>;
+export declare const TAUTOLOGICAL_PATTERNS: Array<{
+    pattern: RegExp;
+    description: string;
+}>;
+export declare function findTautologicalAssertions(content: string): Array<{
+    line: number;
+    pattern: string;
+    match: string;
+}>;
+export declare function findMutationGamingPatterns(content: string, filePath?: string): Array<{
+    line: number;
+    pattern: string;
+    match: string;
+}>;
+export declare function validateTestQuality(input: ToolInput): ValidationResult;
+//# sourceMappingURL=test-quality.d.ts.map

package/dist/esm/hooks/pretool-guard/validators/test-quality.js

@@ -0,0 +1,218 @@
+import { getContent, getFilePath } from '#hooks/shared/types';
+export const MUTATION_GAMING_PATTERNS = [
+    {
+        pattern: /mutation[_-]kill/i,
+        description: 'File name suggests mutation gaming',
+        fileLevel: true,
+    },
+    {
+        pattern: /kill[_-]mutant/i,
+        description: 'File name suggests mutation gaming',
+        fileLevel: true,
+    },
+    {
+        pattern: /for[_-]coverage/i,
+        description: 'File name suggests coverage gaming',
+        fileLevel: true,
+    },
+    {
+        pattern: /increase[_-]mutation/i,
+        description: 'File name suggests mutation gaming',
+        fileLevel: true,
+    },
+    {
+        pattern: /describe\s*\(\s*['"`].*mutation[_-]kill/i,
+        description: 'Test suite name suggests mutation gaming',
+    },
+    {
+        pattern: /describe\s*\(\s*['"`].*kill[_-]mutant/i,
+        description: 'Test suite name suggests mutation gaming',
+    },
+    {
+        pattern: /it\s*\(\s*['"`].*kill\s+(the\s+)?mutant/i,
+        description: 'Test name suggests mutation gaming',
+    },
+    {
+        pattern: /it\s*\(\s*['"`].*for\s+mutation\s+score/i,
+        description: 'Test name suggests mutation gaming',
+    },
+    {
+        pattern: /it\s*\(\s*['"`].*increase\s+(mutation|coverage)/i,
+        description: 'Test name suggests coverage gaming',
+    },
+];
+export const TAUTOLOGICAL_PATTERNS = [
+    {
+        pattern: /expect\s*\(\s*true\s*\)\s*\.toBe\s*\(\s*true\s*\)/,
+        description: 'expect(true).toBe(true)',
+    },
+    {
+        pattern: /expect\s*\(\s*false\s*\)\s*\.toBe\s*\(\s*false\s*\)/,
+        description: 'expect(false).toBe(false)',
+    },
+    {
+        pattern: /expect\s*\(\s*true\s*\)\s*\.toEqual\s*\(\s*true\s*\)/,
+        description: 'expect(true).toEqual(true)',
+    },
+    {
+        pattern: /expect\s*\(\s*false\s*\)\s*\.toEqual\s*\(\s*false\s*\)/,
+        description: 'expect(false).toEqual(false)',
+    },
+    {
+        pattern: /expect\s*\(\s*null\s*\)\s*\.toBe\s*\(\s*null\s*\)/,
+        description: 'expect(null).toBe(null)',
+    },
+    {
+        pattern: /expect\s*\(\s*undefined\s*\)\s*\.toBe\s*\(\s*undefined\s*\)/,
+        description: 'expect(undefined).toBe(undefined)',
+    },
+    {
+        pattern: /expect\s*\(\s*null\s*\)\s*\.toEqual\s*\(\s*null\s*\)/,
+        description: 'expect(null).toEqual(null)',
+    },
+    {
+        pattern: /expect\s*\(\s*undefined\s*\)\s*\.toEqual\s*\(\s*undefined\s*\)/,
+        description: 'expect(undefined).toEqual(undefined)',
+    },
+    {
+        pattern: /expect\s*\(\s*\[\s*\]\s*\)\s*\.toEqual\s*\(\s*\[\s*\]\s*\)/,
+        description: 'expect([]).toEqual([])',
+    },
+    {
+        pattern: /expect\s*\(\s*\{\s*\}\s*\)\s*\.toEqual\s*\(\s*\{\s*\}\s*\)/,
+        description: 'expect({}).toEqual({})',
+    },
+    {
+        pattern: /expect\s*\(\s*true\s*\)\s*\.toBeTruthy\s*\(\s*\)/,
+        description: 'expect(true).toBeTruthy()',
+    },
+    {
+        pattern: /expect\s*\(\s*false\s*\)\s*\.toBeFalsy\s*\(\s*\)/,
+        description: 'expect(false).toBeFalsy()',
+    },
+    {
+        pattern: /expect\s*\(\s*1\s*\)\s*\.toBeTruthy\s*\(\s*\)/,
+        description: 'expect(1).toBeTruthy()',
+    },
+    { pattern: /expect\s*\(\s*0\s*\)\s*\.toBeFalsy\s*\(\s*\)/, description: 'expect(0).toBeFalsy()' },
+    {
+        pattern: /expect\s*\(\s*["'][^"']+["']\s*\)\s*\.toBeTruthy\s*\(\s*\)/,
+        description: 'expect("string").toBeTruthy()',
+    },
+    {
+        pattern: /expect\s*\(\s*["']["']\s*\)\s*\.toBeFalsy\s*\(\s*\)/,
+        description: 'expect("").toBeFalsy()',
+    },
+    {
+        pattern: /expect\s*\(\s*true\s*\)\s*\.toBeDefined\s*\(\s*\)/,
+        description: 'expect(true).toBeDefined()',
+    },
+    {
+        pattern: /expect\s*\(\s*false\s*\)\s*\.toBeDefined\s*\(\s*\)/,
+        description: 'expect(false).toBeDefined()',
+    },
+    {
+        pattern: /expect\s*\(\s*\d+\s*\)\s*\.toBeDefined\s*\(\s*\)/,
+        description: 'expect(number).toBeDefined()',
+    },
+    {
+        pattern: /expect\s*\(\s*["'][^"']*["']\s*\)\s*\.toBeDefined\s*\(\s*\)/,
+        description: 'expect("string").toBeDefined()',
+    },
+    {
+        pattern: /expect\s*\(\s*true\s*\)\s*\.toBeInstanceOf\s*\(\s*Object\s*\)/,
+        description: 'expect(true).toBeInstanceOf(Object)',
+    },
+    {
+        pattern: /expect\s*\(\s*false\s*\)\s*\.toBeInstanceOf\s*\(\s*Object\s*\)/,
+        description: 'expect(false).toBeInstanceOf(Object)',
+    },
+    {
+        pattern: /expect\s*\(\s*\d+\s*\)\s*\.toBeInstanceOf\s*\(\s*Object\s*\)/,
+        description: 'expect(number).toBeInstanceOf(Object)',
+    },
+    {
+        pattern: /expect\s*\(\s*["'][^"']*["']\s*\)\s*\.toBeInstanceOf\s*\(\s*Object\s*\)/,
+        description: 'expect("string").toBeInstanceOf(Object)',
+    },
+];
+export function findTautologicalAssertions(content) {
+    const lines = content.split('\n');
+    const matches = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (!line)
+            continue;
+        for (const { pattern, description } of TAUTOLOGICAL_PATTERNS) {
+            const match = line.match(pattern);
+            if (match)
+                matches.push({ line: i + 1, pattern: description, match: match[0] });
+        }
+    }
+    return matches;
+}
+export function findMutationGamingPatterns(content, filePath) {
+    const matches = [];
+    if (filePath) {
+        for (const { pattern, description, fileLevel } of MUTATION_GAMING_PATTERNS) {
+            if (!fileLevel)
+                continue;
+            const match = filePath.match(pattern);
+            if (match)
+                matches.push({ line: 0, pattern: description, match: match[0] });
+        }
+    }
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (!line)
+            continue;
+        for (const { pattern, description, fileLevel } of MUTATION_GAMING_PATTERNS) {
+            if (fileLevel)
+                continue;
+            const match = line.match(pattern);
+            if (match)
+                matches.push({ line: i + 1, pattern: description, match: match[0] });
+        }
+    }
+    return matches;
+}
+export function validateTestQuality(input) {
+    const filePath = getFilePath(input);
+    const content = getContent(input);
+    if (!content || !filePath)
+        return { validator: 'test-quality', passed: true };
+    if (!/\.test\.(ts|tsx|js|jsx)$/.test(filePath)) {
+        return { validator: 'test-quality', passed: true, skipped: true, skipReason: 'Not a test file' };
+    }
+    if (filePath.includes('test-quality.test.ts')) {
+        return {
+            validator: 'test-quality',
+            passed: true,
+            skipped: true,
+            skipReason: 'Validator self-test',
+        };
+    }
+    const gamingMatches = findMutationGamingPatterns(content, filePath);
+    if (gamingMatches.length > 0) {
+        const examples = gamingMatches
+            .slice(0, 3)
+            .map((m) => (m.line === 0 ? `  File path: ${m.pattern}` : `  Line ${m.line}: ${m.pattern}`));
+        return {
+            validator: 'test-quality',
+            passed: false,
+            message: `Mutation gaming detected:\n${examples.join('\n')}${gamingMatches.length > 3 ? `\n  ...and ${gamingMatches.length - 3} more` : ''}`,
+        };
+    }
+    const matches = findTautologicalAssertions(content);
+    if (matches.length > 0) {
+        const examples = matches.slice(0, 3).map((m) => `  Line ${m.line}: ${m.pattern}`);
+        return {
+            validator: 'test-quality',
+            passed: false,
+            message: `Tautological assertions detected:\n${examples.join('\n')}${matches.length > 3 ? `\n  ...and ${matches.length - 3} more` : ''}`,
+        };
+    }
+    return { validator: 'test-quality', passed: true };
+}
+//# sourceMappingURL=test-quality.js.map

package/dist/esm/hooks/pretool-guard/validators/ux-quality.d.ts

@@ -0,0 +1,3 @@
+import type { ToolInput, ValidationResult } from '#hooks/shared/types';
+export declare function validateUxQuality(input: ToolInput): ValidationResult;
+//# sourceMappingURL=ux-quality.d.ts.map

package/dist/esm/hooks/pretool-guard/validators/ux-quality.js

@@ -0,0 +1,80 @@
+import { getContent, getFilePath } from '#hooks/shared/types';
+const VALIDATOR_NAME = 'ux-quality';
+const ALERT_PATTERN = /\b(?:window\.)?alert\s*\(/g;
+const CATCH_CONSOLE_ERROR_ONLY_PATTERN = /catch\s*(?:\([^)]*\))?\s*\{\s*console\.error\s*\([\s\S]*?\)\s*;?\s*\}/g;
+const USE_QUERY_DESTRUCTURE_PATTERN = /const\s*\{([^}]*)\}\s*=\s*useQuery\s*\(/g;
+const USE_QUERY_ASSIGNMENT_PATTERN = /(?:const|let|var)\s+\w+\s*=\s*useQuery\s*\(/g;
+function getLineNumber(content, index) {
+    return content.slice(0, index).split('\n').length;
+}
+function collectAlertViolations(content) {
+    const violations = [];
+    for (const match of content.matchAll(ALERT_PATTERN)) {
+        const text = match[0] === 'window.alert(' ? 'window.alert()' : 'alert()';
+        violations.push({
+            line: getLineNumber(content, match.index ?? 0),
+            message: `Avoid ${text}; use non-blocking UI feedback instead.`,
+        });
+    }
+    return violations;
+}
+function collectCatchViolations(content) {
+    const violations = [];
+    for (const match of content.matchAll(CATCH_CONSOLE_ERROR_ONLY_PATTERN)) {
+        violations.push({
+            line: getLineNumber(content, match.index ?? 0),
+            message: 'catch block only logs with console.error; add user-facing handling and recovery.',
+        });
+    }
+    return violations;
+}
+function buildMissingFieldsMessage(hasIsPending, hasIsError) {
+    const missing = [hasIsPending ? null : 'isPending', hasIsError ? null : 'isError']
+        .filter((name) => Boolean(name))
+        .join(' and ');
+    return `useQuery destructuring must include ${missing}.`;
+}
+function collectUseQueryViolations(content) {
+    const violations = [];
+    for (const match of content.matchAll(USE_QUERY_DESTRUCTURE_PATTERN)) {
+        const fields = match[1] || '';
+        const hasIsPending = /\bisPending\b/.test(fields);
+        const hasIsError = /\bisError\b/.test(fields);
+        if (!hasIsPending || !hasIsError) {
+            violations.push({
+                line: getLineNumber(content, match.index ?? 0),
+                message: buildMissingFieldsMessage(hasIsPending, hasIsError),
+            });
+        }
+    }
+    for (const match of content.matchAll(USE_QUERY_ASSIGNMENT_PATTERN)) {
+        violations.push({
+            line: getLineNumber(content, match.index ?? 0),
+            message: 'useQuery result must handle isPending and isError states.',
+        });
+    }
+    return violations;
+}
+export function validateUxQuality(input) {
+    const filePath = getFilePath(input);
+    const content = getContent(input);
+    if (!filePath || !content)
+        return { validator: VALIDATOR_NAME, passed: true };
+    if (!/\.(ts|tsx|js|jsx)$/.test(filePath))
+        return { validator: VALIDATOR_NAME, passed: true };
+    const violations = [
+        ...collectAlertViolations(content),
+        ...collectCatchViolations(content),
+        ...collectUseQueryViolations(content),
+    ];
+    if (!violations.length)
+        return { validator: VALIDATOR_NAME, passed: true };
+    const preview = violations.slice(0, 4).map((v) => `  Line ${v.line}: ${v.message}`);
+    const overflow = violations.length > 4 ? `\n  ...and ${violations.length - 4} more` : '';
+    return {
+        validator: VALIDATOR_NAME,
+        passed: false,
+        message: `UX anti-patterns detected:\n${preview.join('\n')}${overflow}`,
+    };
+}
+//# sourceMappingURL=ux-quality.js.map

package/dist/esm/hooks/sessionstart/index.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env bun
+import { WP_ROUTING_BLOCK } from '#hooks/shared/routing-block';
+export { WP_ROUTING_BLOCK };
+export declare const MAX_BYTES: number;
+export declare const TRUNCATION_NOTICE = "\n\n[truncated: file exceeded 200KB limit]";
+type StartInput = Record<string, unknown>;
+type EnvLike = Record<string, string | undefined>;
+/**
+ * Pure function: given a parsed input payload, a working directory, and
+ * environment variables, produce the JSON string that the hook should write
+ * to stdout. Always emits — never returns null. WP_ROUTING_BLOCK is always
+ * prepended; `.agent/routing.md` content is appended when present and non-empty.
+ */
+export declare function buildOutput(_input: StartInput, cwd: string, env: EnvLike): string;
+export declare function main(): Promise<void>;
+//# sourceMappingURL=index.d.ts.map