@webpresso/agent-kit 0.21.0

package/dist/esm/quality-engine/command-builder.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Command Builder
+ *
+ * Pure functions for building lint, typecheck, test, and qa command configurations.
+ * These functions return command objects that can be executed by CLI tools.
+ *
+ * @module
+ */
+import type { ResolvedTarget } from './target-resolver.js';
+/**
+ * Command configuration object.
+ * Can be executed by CLI tools using system-commands or similar.
+ */
+export interface CommandConfig {
+    /** Command to execute (e.g., 'pnpm', 'oxlint', 'vitest') */
+    command: string;
+    /** Command arguments */
+    args: string[];
+    /** Environment variables */
+    env?: Record<string, string>;
+}
+export type VpRunLogMode = 'interleaved' | 'labeled' | 'grouped';
+/**
+ * Convert a CommandConfig to a shell-executable string.
+ */
+export declare function commandConfigToString(config: CommandConfig): string;
+export interface LintOptions {
+    fix?: boolean;
+    fixUnsafe?: boolean;
+}
+/**
+ * Build oxlint command configuration.
+ */
+export declare function buildLintCommand(resolved: ResolvedTarget, options?: LintOptions): CommandConfig;
+/**
+ * Build oxfmt command configuration.
+ */
+export declare function buildFormatCommand(resolved: ResolvedTarget): CommandConfig;
+export interface TypecheckOptions {
+    noCache?: boolean;
+    continue?: boolean;
+    cache?: boolean;
+    concurrencyLimit?: number;
+    log?: VpRunLogMode;
+    parallel?: boolean;
+}
+/**
+ * Build typecheck command configuration.
+ */
+export declare function buildTypecheckCommand(resolved: ResolvedTarget, repoRoot: string, options?: TypecheckOptions): CommandConfig;
+/**
+ * Convert file paths to package filters for typecheck.
+ */
+export declare function filePathsToPackageFilters(filePaths: string[], repoRoot: string, resolveTargetStrict: (target: string, deps: {
+    repoRoot: string;
+}) => ResolvedTarget): string[];
+export interface TestOptions {
+    watch?: boolean;
+    coverage?: boolean;
+    testNamePattern?: string;
+    noCache?: boolean;
+    continue?: boolean;
+    mutation?: boolean;
+    workers?: boolean;
+    json?: boolean;
+    all?: boolean;
+    affected?: boolean;
+    passthrough?: string[];
+    cache?: boolean;
+    concurrencyLimit?: number;
+    log?: VpRunLogMode;
+    parallel?: boolean;
+}
+/**
+ * Get the Vite+ run task name based on test options.
+ */
+export declare function getVpTestTask(options: TestOptions): string;
+/**
+ * Build Vite+ test command configuration for workspace/package targets.
+ */
+export declare function buildVpTestCommand(filters: string[], options?: TestOptions, useJsonReporter?: boolean): CommandConfig;
+/**
+ * Build vitest command configuration for file targets.
+ */
+export declare function buildVitestCommand(files: string[], options: TestOptions, projectRoot?: string): CommandConfig;
+export type CheckType = 'lint' | 'typecheck' | 'test';
+export interface QaOptions {
+    quick?: boolean;
+    continue?: boolean;
+    noCache?: boolean;
+    cache?: boolean;
+    concurrencyLimit?: number;
+    log?: VpRunLogMode;
+}
+/**
+ * Core package checks (always run).
+ */
+export declare const CORE_CHECKS: readonly CheckType[];
+/**
+ * Quick checks (subset for --quick mode).
+ */
+export declare const QUICK_CHECKS: readonly CheckType[];
+/**
+ * Get the list of check types based on options.
+ */
+export declare function getCheckTypes(options: QaOptions): readonly CheckType[];
+/**
+ * Build a combined Vite+ command for package QA.
+ */
+export declare function buildCombinedVpCommand(checkTypes: readonly CheckType[], filters: string[], options: QaOptions): CommandConfig;
+/**
+ * Options as received from CAC (string | string[] for variadic flags).
+ */
+export interface CacRawOptions {
+    package?: string | string[];
+    file?: string | string[];
+    noCache?: boolean;
+    cache?: boolean;
+}
+/**
+ * Normalized options with arrays and boolean flags resolved.
+ */
+export interface NormalizedCommandInputs {
+    targets: string[];
+    options: {
+        package?: string[];
+        file?: string[];
+        noCache?: boolean;
+    };
+}
+/**
+ * Normalize CAC's raw inputs into consistent arrays.
+ *
+ * Handles:
+ * - `--no-cache` → `noCache: true`
+ * - `--package <names...>` as string or string[]
+ * - `--file <paths...>` as string or string[]
+ * - Positional targets merged into --file or --package when both present
+ */
+export declare function normalizeCacInputs(targets: string[] | string | undefined, rawOptions: CacRawOptions): NormalizedCommandInputs;
+//# sourceMappingURL=command-builder.d.ts.map

package/dist/esm/quality-engine/command-builder.js

@@ -0,0 +1,285 @@
+/**
+ * Command Builder
+ *
+ * Pure functions for building lint, typecheck, test, and qa command configurations.
+ * These functions return command objects that can be executed by CLI tools.
+ *
+ * @module
+ */
+import { extractPackagePath } from './workspace-config.js';
+/**
+ * Convert a CommandConfig to a shell-executable string.
+ */
+export function commandConfigToString(config) {
+    return [config.command, ...config.args].join(' ');
+}
+/**
+ * Build oxlint command configuration.
+ */
+export function buildLintCommand(resolved, options = {}) {
+    const args = [];
+    // Add paths if any
+    if (resolved.value.length > 0) {
+        args.push(...resolved.value);
+    }
+    else {
+        args.push('.'); // Default to current directory
+    }
+    // Add fix flags
+    if (options.fix) {
+        args.push('--fix');
+    }
+    if (options.fixUnsafe) {
+        args.push('--fix-dangerously');
+    }
+    return {
+        command: 'oxlint',
+        args,
+    };
+}
+/**
+ * Build oxfmt command configuration.
+ */
+export function buildFormatCommand(resolved) {
+    const args = [];
+    // Add paths if any
+    if (resolved.value.length > 0) {
+        args.push(...resolved.value);
+    }
+    else {
+        args.push('.'); // Default to current directory
+    }
+    return {
+        command: 'oxfmt',
+        args,
+    };
+}
+function appendVpRunOptions(args, options) {
+    if (options.noCache) {
+        args.push('--no-cache');
+    }
+    else if (options.cache) {
+        args.push('--cache');
+    }
+    if (options.parallel) {
+        args.push('--parallel');
+    }
+    if (options.concurrencyLimit) {
+        args.push('--concurrency-limit', String(options.concurrencyLimit));
+    }
+    if (options.log) {
+        args.push('--log', options.log);
+    }
+}
+function buildVpRunEnv(options) {
+    if (!options.concurrencyLimit) {
+        return;
+    }
+    return {
+        VP_RUN_CONCURRENCY_LIMIT: String(options.concurrencyLimit),
+    };
+}
+/**
+ * Build typecheck command configuration.
+ */
+export function buildTypecheckCommand(resolved, repoRoot, options = {}) {
+    void repoRoot;
+    const args = ['run'];
+    if (resolved.type === 'package' && resolved.value.length > 0) {
+        args.push(...resolved.value);
+    }
+    appendVpRunOptions(args, options);
+    args.push('typecheck');
+    return {
+        command: 'vp',
+        args,
+        env: buildVpRunEnv(options),
+    };
+}
+/**
+ * Convert file paths to package filters for typecheck.
+ */
+export function filePathsToPackageFilters(filePaths, repoRoot, resolveTargetStrict) {
+    const seen = new Set();
+    const allFilters = [];
+    for (const filePath of filePaths) {
+        const packagePath = extractPackagePath(filePath);
+        if (!packagePath)
+            continue;
+        const packageResolved = resolveTargetStrict(packagePath, { repoRoot });
+        if (packageResolved.type === 'package') {
+            for (const filter of packageResolved.value) {
+                if (!seen.has(filter)) {
+                    seen.add(filter);
+                    allFilters.push(filter);
+                }
+            }
+        }
+    }
+    return allFilters;
+}
+/**
+ * Get the Vite+ run task name based on test options.
+ */
+export function getVpTestTask(options) {
+    if (options.mutation)
+        return 'test:mutation';
+    if (options.workers)
+        return 'test:workers';
+    if (options.watch)
+        return 'test:watch';
+    return 'test';
+}
+/**
+ * Build Vite+ test command configuration for workspace/package targets.
+ */
+export function buildVpTestCommand(filters, options = {}, useJsonReporter) {
+    const task = getVpTestTask(options);
+    const args = ['run', ...filters];
+    appendVpRunOptions(args, options);
+    args.push(task);
+    const extraArgs = [];
+    if (options.coverage)
+        extraArgs.push('--coverage');
+    if (options.testNamePattern)
+        extraArgs.push(`-t '${options.testNamePattern}'`);
+    if (options.passthrough)
+        extraArgs.push(...options.passthrough);
+    if (useJsonReporter) {
+        extraArgs.push('--reporter=default');
+        extraArgs.push('--reporter=json');
+        extraArgs.push('--outputFile=.vite-plus/test-results.json');
+    }
+    if (extraArgs.length > 0) {
+        args.push('--');
+        args.push(...extraArgs);
+    }
+    return {
+        command: 'vp',
+        args,
+        env: buildVpRunEnv(options),
+    };
+}
+/**
+ * Build vitest command configuration for file targets.
+ */
+export function buildVitestCommand(files, options, projectRoot) {
+    const mode = options.watch ? '--watch' : 'run';
+    const args = [mode];
+    const configFiles = [];
+    const testFiles = [];
+    for (const file of files) {
+        if (/^vitest(\.[\w-]+)?\.config\.(ts|mts|cts|js|mjs|cjs)$/.test(file)) {
+            configFiles.push(file);
+            continue;
+        }
+        testFiles.push(file);
+    }
+    // Don't pass --root for file targets — the CWD is already the repo root,
+    // and --root can cause filter path mismatches in multi-project setups.
+    if (projectRoot && testFiles.length === 0) {
+        args.push('--root', projectRoot);
+    }
+    if (configFiles.length > 1) {
+        throw new Error(`Expected at most one vitest config file, received: ${configFiles.join(', ')}`);
+    }
+    const [configFile] = configFiles;
+    if (configFile) {
+        args.push('--config', configFile);
+    }
+    if (options.coverage) {
+        args.push('--coverage');
+    }
+    if (options.testNamePattern) {
+        args.push('-t', options.testNamePattern);
+    }
+    if (options.passthrough?.length) {
+        args.push(...options.passthrough);
+    }
+    // Add file paths directly — buildVitestCommand returns CommandConfig
+    // which is spawned directly (not through a shell), so shell escaping
+    // would inject literal quote characters into the filename.
+    args.push(...testFiles);
+    return {
+        command: 'vitest',
+        args,
+    };
+}
+/**
+ * Core package checks (always run).
+ */
+export const CORE_CHECKS = ['lint', 'typecheck', 'test'];
+/**
+ * Quick checks (subset for --quick mode).
+ */
+export const QUICK_CHECKS = ['lint', 'typecheck'];
+/**
+ * Get the list of check types based on options.
+ */
+export function getCheckTypes(options) {
+    return options.quick ? QUICK_CHECKS : CORE_CHECKS;
+}
+/**
+ * Build a combined Vite+ command for package QA.
+ */
+export function buildCombinedVpCommand(checkTypes, filters, options) {
+    const packageCheckTypes = checkTypes.filter((t) => t !== 'lint');
+    const task = packageCheckTypes.includes('test') ? 'qa' : 'typecheck';
+    const args = ['run', ...filters];
+    appendVpRunOptions(args, options);
+    args.push(task);
+    return {
+        command: 'vp',
+        args,
+        env: buildVpRunEnv(options),
+    };
+}
+/**
+ * Normalize CAC's raw inputs into consistent arrays.
+ *
+ * Handles:
+ * - `--no-cache` → `noCache: true`
+ * - `--package <names...>` as string or string[]
+ * - `--file <paths...>` as string or string[]
+ * - Positional targets merged into --file or --package when both present
+ */
+export function normalizeCacInputs(targets, rawOptions) {
+    let positionalTargets = Array.isArray(targets)
+        ? targets
+        : typeof targets === 'string'
+            ? [targets]
+            : [];
+    // Normalize --no-cache
+    const noCache = rawOptions.noCache || rawOptions.cache === false;
+    // CAC may pass as string or array - normalize to array
+    const packageArr = rawOptions.package
+        ? Array.isArray(rawOptions.package)
+            ? rawOptions.package
+            : [rawOptions.package]
+        : undefined;
+    const fileArr = rawOptions.file
+        ? Array.isArray(rawOptions.file)
+            ? rawOptions.file
+            : [rawOptions.file]
+        : undefined;
+    let finalPackage = packageArr;
+    let finalFile = fileArr;
+    // Merge positional targets into --file or --package when both present
+    if (finalFile && positionalTargets.length > 0) {
+        finalFile = [...finalFile, ...positionalTargets];
+        positionalTargets = [];
+    }
+    if (finalPackage && positionalTargets.length > 0) {
+        finalPackage = [...finalPackage, ...positionalTargets];
+        positionalTargets = [];
+    }
+    return {
+        targets: positionalTargets,
+        options: {
+            package: finalPackage,
+            file: finalFile,
+            noCache: noCache || undefined,
+        },
+    };
+}
+//# sourceMappingURL=command-builder.js.map

package/dist/esm/quality-engine/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Quality Engine
+ *
+ * Shared logic for lint, test, typecheck, and qa commands.
+ * Provides target resolution, log path generation, and command building.
+ *
+ * @module
+ */
+export * from './target-resolver.js';
+export * from './log-paths.js';
+export * from './workspace-config.js';
+export * from './command-builder.js';
+export * from './package-import-rules.js';
+export * from './test-classification.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/quality-engine/index.js

@@ -0,0 +1,16 @@
+/**
+ * Quality Engine
+ *
+ * Shared logic for lint, test, typecheck, and qa commands.
+ * Provides target resolution, log path generation, and command building.
+ *
+ * @module
+ */
+// Re-export all public APIs
+export * from './target-resolver.js';
+export * from './log-paths.js';
+export * from './workspace-config.js';
+export * from './command-builder.js';
+export * from './package-import-rules.js';
+export * from './test-classification.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/quality-engine/log-paths.d.ts

@@ -0,0 +1,44 @@
+import { type ResolvedTarget } from './target-resolver.js';
+export interface GenerateLogPathOptions {
+    context?: string;
+    logsDir?: string;
+    includeDateFolder?: boolean;
+    now?: Date;
+}
+export interface ExtractLogContextOptions {
+    packageContext?: (filters: string[]) => string | undefined;
+    fileContext?: (files: string[]) => string | undefined;
+}
+/**
+ * Generate a timestamped log file path for quality commands.
+ *
+ * Log naming convention:
+ *   logs/DD-MM-YYYY/HH-MM-SS_command[-context].log
+ *
+ * Examples:
+ *   logs/12-02-2026/14-23-45_lint.log              # Full workspace lint
+ *   logs/12-02-2026/14-25-30_lint-cli2.log         # Package-scoped lint
+ *   logs/12-02-2026/14-30-08_test-1770922337.log   # File-scoped test (unix timestamp)
+ *   logs/12-02-2026/19-52-00_typecheck.log         # Full workspace typecheck
+ *
+ * @param command - The quality command being run
+ * @param options - Configuration options
+ * @returns Relative path to log file (e.g., "logs/12-02-2026/14-23-45_test.log")
+ */
+export declare function generateLogPath(command: 'test' | 'lint' | 'typecheck' | 'qa' | 'build', options?: GenerateLogPathOptions): string;
+export declare function extractPackageLogContext(filter: string): string | undefined;
+export declare function defaultPackageLogContext(filters: string[]): string | undefined;
+/**
+ * Extract context string from resolved target for log naming.
+ *
+ * Context extraction rules:
+ * - Full workspace (no targets): No context suffix
+ * - Package scope: Use package name(s) - "cli2" or "cli2-config"
+ * - File scope: Use unix timestamp (paths too complex to encode)
+ * - QA command: No context (always full workspace)
+ *
+ * @param resolved - Resolved command target
+ * @returns Context string for log filename, or undefined for no context
+ */
+export declare function extractLogContext(resolved: ResolvedTarget, options?: ExtractLogContextOptions): string | undefined;
+//# sourceMappingURL=log-paths.d.ts.map

package/dist/esm/quality-engine/log-paths.js

@@ -0,0 +1,73 @@
+import { getPackageShortName } from './target-resolver.js';
+import { join } from 'node:path';
+/**
+ * Generate a timestamped log file path for quality commands.
+ *
+ * Log naming convention:
+ *   logs/DD-MM-YYYY/HH-MM-SS_command[-context].log
+ *
+ * Examples:
+ *   logs/12-02-2026/14-23-45_lint.log              # Full workspace lint
+ *   logs/12-02-2026/14-25-30_lint-cli2.log         # Package-scoped lint
+ *   logs/12-02-2026/14-30-08_test-1770922337.log   # File-scoped test (unix timestamp)
+ *   logs/12-02-2026/19-52-00_typecheck.log         # Full workspace typecheck
+ *
+ * @param command - The quality command being run
+ * @param options - Configuration options
+ * @returns Relative path to log file (e.g., "logs/12-02-2026/14-23-45_test.log")
+ */
+export function generateLogPath(command, options = {}) {
+    const { context, logsDir = 'logs', includeDateFolder = true, now = new Date() } = options;
+    // Date folder: DD-MM-YYYY
+    const dateFolder = [
+        String(now.getDate()).padStart(2, '0'),
+        String(now.getMonth() + 1).padStart(2, '0'),
+        now.getFullYear(),
+    ].join('-');
+    // Time prefix: HH-MM-SS
+    const timePrefix = [
+        String(now.getHours()).padStart(2, '0'),
+        String(now.getMinutes()).padStart(2, '0'),
+        String(now.getSeconds()).padStart(2, '0'),
+    ].join('-');
+    // Filename: HH-MM-SS_command[-context].log
+    const contextSuffix = context ? `-${context}` : '';
+    const filename = `${timePrefix}_${command}${contextSuffix}.log`;
+    return includeDateFolder ? join(logsDir, dateFolder, filename) : join(logsDir, filename);
+}
+export function extractPackageLogContext(filter) {
+    const packageName = filter.replace(/^--filter=/, '').trim();
+    if (!packageName) {
+        return undefined;
+    }
+    return getPackageShortName(packageName);
+}
+export function defaultPackageLogContext(filters) {
+    const packages = filters
+        .map((filter) => extractPackageLogContext(filter))
+        .filter((value) => Boolean(value));
+    return packages.length > 0 ? packages.join('-') : undefined;
+}
+/**
+ * Extract context string from resolved target for log naming.
+ *
+ * Context extraction rules:
+ * - Full workspace (no targets): No context suffix
+ * - Package scope: Use package name(s) - "cli2" or "cli2-config"
+ * - File scope: Use unix timestamp (paths too complex to encode)
+ * - QA command: No context (always full workspace)
+ *
+ * @param resolved - Resolved command target
+ * @returns Context string for log filename, or undefined for no context
+ */
+export function extractLogContext(resolved, options = {}) {
+    const { packageContext = defaultPackageLogContext, fileContext = () => String(Date.now()) } = options;
+    if (resolved.type === 'package' && resolved.value.length > 0) {
+        return packageContext(resolved.value);
+    }
+    if (resolved.type === 'file' && resolved.value.length > 0) {
+        return fileContext(resolved.value);
+    }
+    return undefined;
+}
+//# sourceMappingURL=log-paths.js.map

package/dist/esm/quality-engine/package-import-rules.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Package Import Rules
+ *
+ * Pure shared detection logic for identifying duplicate shared-function definitions.
+ * No hook-specific types or Claude runtime dependencies.
+ *
+ * Consumed by:
+ * - hook validators (thin adapters)
+ * - CI scripts (future)
+ *
+ * @module
+ */
+/** Single shared function definition */
+export interface SharedFunction {
+    /** Function name to detect */
+    name: string;
+    /** Package to import from */
+    package: string;
+    /** Subpath export (e.g., 'string', 'date'); empty string means package root */
+    source: string;
+    /** Category for grouping */
+    category: 'string' | 'date' | 'duration' | 'format' | 'id' | 'error' | 'validation';
+}
+/** Structured blocked result for machine parsing */
+export interface BlockedResult {
+    /** Function name that was duplicated */
+    functionName: string;
+    /** Suggested import statement */
+    suggestion: string;
+    /** Package to import from */
+    package: string;
+    /** Source module path */
+    source: string;
+    /** Human-readable message */
+    message: string;
+}
+export type PackageImportProfile = 'generic' | 'webpresso';
+export interface PackageImportRuleOptions {
+    profile?: PackageImportProfile;
+}
+export declare const SHARED_FUNCTION_PROFILES: Record<PackageImportProfile, SharedFunction[]>;
+/**
+ * Default generic shared function registry. Product-specific rules must opt into
+ * a profile explicitly instead of leaking through the generic surface.
+ */
+export declare const SHARED_FUNCTIONS: SharedFunction[];
+/** Set of function names for O(1) lookup in the default generic profile */
+export declare const SHARED_FUNCTION_NAMES: Set<string>;
+export declare function getSharedFunctions(profile?: PackageImportProfile): SharedFunction[];
+export declare function getSharedFunctionNames(profile?: PackageImportProfile): Set<string>;
+/**
+ * Extracts function definitions from TypeScript code content.
+ * Detects:
+ * - Function declarations: `function capitalize(...)`
+ * - Const arrow functions: `const capitalize = (...)`
+ * - Const function expressions: `const capitalize = function(...)`
+ */
+export declare function extractFunctionDefinitions(content: string): string[];
+/**
+ * Finds duplicate functions that exist in shared packages.
+ * Pure function — accepts file content string, returns matching registry entries.
+ */
+export declare function findDuplicateFunctions(fileContent: string, options?: PackageImportRuleOptions): SharedFunction[];
+/**
+ * Creates a blocked result for a duplicate function.
+ * Returns a plain object suitable for use by CI scripts and hook adapters.
+ */
+export declare function createBlockedResult(sharedFunc: SharedFunction): BlockedResult;
+//# sourceMappingURL=package-import-rules.d.ts.map