@webpresso/agent-kit 0.21.0

package/dist/esm/symlinker/unified-sync.js

@@ -0,0 +1,362 @@
+/**
+ * Unified rule + skill sync.
+ *
+ * Source of truth: catalog (`<pkg>/dist/catalog/agent/{rules,skills}/`) UNION
+ * consumer (`<repo>/agent-{rules,skills}/`). The loader returns a
+ * source-tagged record list; this module projects that list into per-IDE
+ * surfaces according to `DEFAULT_UNIFIED_CONSUMERS`.
+ *
+ * Per-consumer strategy:
+ *   - 'symlink':   relative symlink (file for rules, dir for skills).
+ *   - 'copy':      atomic copy (file for rules, recursive copy for skills).
+ *   - 'transform': apply the consumer's transform function to the record body
+ *                  and atomic-write the result at the target path.
+ *
+ * Prune: any file/dir under a consumer's dir whose name matches the unified
+ * filename pattern but is not in the expected set is removed. This propagates
+ * deletions in `agent-rules/` and `agent-skills/` to per-IDE cleanup.
+ *
+ * `--check` mode (dry-run): produce a list of (target, status) pairs and
+ * return the count of mismatches; perform no writes.
+ */
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, symlinkSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { loadContent } from '#content/loader';
+import { DEFAULT_UNIFIED_CONSUMERS, unifiedRuleFilename, } from './consumers.js';
+/**
+ * Create a symlink with explicit Windows type hint. POSIX ignores the type;
+ * Windows requires it for directory symlinks. Wraps EPERM with a helpful
+ * Developer-Mode pointer.
+ */
+function createSymlinkWithType(target, linkPath, type, label) {
+    try {
+        symlinkSync(target, linkPath, type);
+    }
+    catch (error) {
+        const code = error.code;
+        if (process.platform === 'win32' && code === 'EPERM') {
+            throw new Error(`Cannot create symlink ${label} → ${target}: Windows denied permission. ` +
+                'Enable Developer Mode (Settings → Privacy & security → For developers) ' +
+                'or run this script from an elevated shell.', { cause: error });
+        }
+        throw error;
+    }
+}
+function atomicWriteFile(filePath, content) {
+    mkdirSync(dirname(filePath), { recursive: true });
+    const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+    writeFileSync(tmp, content);
+    renameSync(tmp, filePath);
+}
+function safeRemove(path) {
+    try {
+        const st = lstatSync(path);
+        if (st.isSymbolicLink() || st.isFile()) {
+            unlinkSync(path);
+        }
+        else {
+            rmSync(path, { recursive: true, force: true });
+        }
+    }
+    catch {
+        // already gone
+    }
+}
+export function isSymlinkPointingTo(linkPath, expectedAbs) {
+    try {
+        const st = lstatSync(linkPath);
+        if (!st.isSymbolicLink())
+            return false;
+        const target = readlinkSync(linkPath);
+        const resolved = resolve(dirname(linkPath), target);
+        return resolved === expectedAbs;
+    }
+    catch {
+        return false;
+    }
+}
+function planTargets(records, consumers, consumerRoot) {
+    const out = [];
+    for (const consumer of consumers) {
+        for (const record of records) {
+            if (record.kind !== consumer.acceptsKind)
+                continue;
+            const consumerDirAbs = join(consumerRoot, consumer.dir);
+            let entryName;
+            let targetPath;
+            if (record.kind === 'rule') {
+                entryName = unifiedRuleFilename(consumer, record.slug);
+                targetPath = join(consumerDirAbs, entryName);
+            }
+            else {
+                // skills: dir-shaped
+                entryName = record.slug;
+                targetPath = join(consumerDirAbs, entryName);
+            }
+            out.push({ consumer, record, targetPath, entryName });
+        }
+    }
+    return out;
+}
+/**
+ * Recursively copy a directory tree using only fs primitives.
+ * Mirrors files; subdirectories are created on-demand. Files are atomic-written.
+ */
+function copyDirRecursive(srcDir, destDir) {
+    let writes = 0;
+    mkdirSync(destDir, { recursive: true });
+    for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
+        const srcPath = join(srcDir, entry.name);
+        const destPath = join(destDir, entry.name);
+        if (entry.isDirectory()) {
+            writes += copyDirRecursive(srcPath, destPath);
+        }
+        else if (entry.isFile()) {
+            const srcContent = readFileSync(srcPath);
+            let needsWrite = true;
+            if (existsSync(destPath)) {
+                try {
+                    const existing = readFileSync(destPath);
+                    if (existing.equals(srcContent))
+                        needsWrite = false;
+                }
+                catch {
+                    // fall through to write
+                }
+            }
+            if (needsWrite) {
+                atomicWriteFile(destPath, srcContent);
+                writes++;
+            }
+        }
+    }
+    return writes;
+}
+function dirsEqual(srcDir, destDir) {
+    if (!existsSync(destDir))
+        return false;
+    const srcEntries = readdirSync(srcDir, { withFileTypes: true })
+        .map((e) => e.name)
+        .toSorted();
+    const destEntries = readdirSync(destDir, { withFileTypes: true })
+        .map((e) => e.name)
+        .toSorted();
+    if (srcEntries.length !== destEntries.length)
+        return false;
+    for (let i = 0; i < srcEntries.length; i++) {
+        if (srcEntries[i] !== destEntries[i])
+            return false;
+        const srcSub = join(srcDir, srcEntries[i]);
+        const destSub = join(destDir, srcEntries[i]);
+        const srcStat = lstatSync(srcSub);
+        if (srcStat.isDirectory()) {
+            if (!dirsEqual(srcSub, destSub))
+                return false;
+        }
+        else if (srcStat.isFile()) {
+            const srcContent = readFileSync(srcSub);
+            const destContent = readFileSync(destSub);
+            if (!srcContent.equals(destContent))
+                return false;
+        }
+    }
+    return true;
+}
+/**
+ * Apply a single planned target. Returns 1 on write, 0 if already correct.
+ */
+function applyTarget(plan, check) {
+    const { consumer, record, targetPath } = plan;
+    const sourcePath = record.kind === 'skill' ? dirname(record.filePath) : record.filePath;
+    switch (consumer.strategy) {
+        case 'symlink': {
+            // Use the resolved (real) source path so links survive pnpm version churn.
+            if (isSymlinkPointingTo(targetPath, sourcePath))
+                return { wrote: 0 };
+            if (check)
+                return { wrote: 1, mismatch: 'symlink missing or pointing elsewhere' };
+            mkdirSync(dirname(targetPath), { recursive: true });
+            safeRemove(targetPath);
+            const rel = relative(dirname(targetPath), sourcePath);
+            const symType = record.kind === 'skill' ? 'dir' : 'file';
+            createSymlinkWithType(rel, targetPath, symType, `${consumer.dir}/${plan.entryName}`);
+            return { wrote: 1 };
+        }
+        case 'copy': {
+            if (record.kind === 'skill') {
+                // Compare dir contents; copy if differs.
+                if (dirsEqual(sourcePath, targetPath))
+                    return { wrote: 0 };
+                if (check)
+                    return { wrote: 1, mismatch: 'copied skill dir differs from source' };
+                // Replace existing target if it's a symlink/file; clean recursively if dir.
+                if (existsSync(targetPath)) {
+                    const st = lstatSync(targetPath);
+                    if (st.isSymbolicLink() || st.isFile())
+                        unlinkSync(targetPath);
+                }
+                mkdirSync(targetPath, { recursive: true });
+                copyDirRecursive(sourcePath, targetPath);
+                return { wrote: 1 };
+            }
+            // rule: single file copy with content compare.
+            const sourceBytes = readFileSync(sourcePath);
+            let same = false;
+            if (existsSync(targetPath)) {
+                try {
+                    const existing = readFileSync(targetPath);
+                    same = existing.equals(sourceBytes);
+                }
+                catch {
+                    same = false;
+                }
+            }
+            if (same)
+                return { wrote: 0 };
+            if (check)
+                return { wrote: 1, mismatch: 'copied rule differs from source' };
+            atomicWriteFile(targetPath, sourceBytes);
+            return { wrote: 1 };
+        }
+        case 'transform': {
+            const transform = consumer.transform;
+            if (!transform) {
+                throw new Error(`Unified consumer '${consumer.id}' uses strategy 'transform' but no transform fn was provided.`);
+            }
+            const expected = transform({ record, targetPath });
+            let same = false;
+            if (existsSync(targetPath)) {
+                try {
+                    same = readFileSync(targetPath, 'utf8') === expected;
+                }
+                catch {
+                    same = false;
+                }
+            }
+            if (same)
+                return { wrote: 0 };
+            if (check)
+                return { wrote: 1, mismatch: 'transformed output differs from source' };
+            atomicWriteFile(targetPath, expected);
+            return { wrote: 1 };
+        }
+    }
+}
+/**
+ * Remove entries under each consumer dir that no longer correspond to any
+ * planned record. Only removes entries whose shape matches the consumer's
+ * managed pattern (rule files: `<slug><ext>`; skill dirs: subdirectories).
+ * Real files outside the managed pattern (README.md, .gitkeep) are left alone.
+ */
+function pruneStale(plans, consumers, consumerRoot, check, preserveSkillSlugs) {
+    const expectedByConsumerDir = new Map();
+    for (const plan of plans) {
+        const key = plan.consumer.dir;
+        let set = expectedByConsumerDir.get(key);
+        if (!set) {
+            set = new Set();
+            expectedByConsumerDir.set(key, set);
+        }
+        set.add(plan.entryName);
+    }
+    let removed = 0;
+    const mismatches = [];
+    // Each unique dir gets a single sweep — multiple consumers can share a dir
+    // (e.g. .claude/skills hosts both rules and skills).
+    const dirs = new Set(consumers.map((c) => c.dir));
+    for (const dir of dirs) {
+        const dirAbs = join(consumerRoot, dir);
+        if (!existsSync(dirAbs))
+            continue;
+        const expected = expectedByConsumerDir.get(dir) ?? new Set();
+        const consumersForDir = consumers.filter((c) => c.dir === dir);
+        const acceptsSkill = consumersForDir.some((c) => c.acceptsKind === 'skill');
+        for (const entry of readdirSync(dirAbs, { withFileTypes: true })) {
+            const name = entry.name;
+            if (name === 'README.md' || name === '.gitkeep' || name.startsWith('.'))
+                continue;
+            if (expected.has(name))
+                continue;
+            if (acceptsSkill &&
+                preserveSkillSlugs !== undefined &&
+                preserveSkillSlugs.has(name) &&
+                entry.isDirectory())
+                continue;
+            // Only prune entries that match a managed shape: rule extension OR a
+            // directory (skill).
+            const matchesRulePattern = consumersForDir.some((c) => c.acceptsKind === 'rule' && name.endsWith(c.ruleExtension ?? '.md'));
+            const matchesSkillPattern = consumersForDir.some((c) => c.acceptsKind === 'skill') && entry.isDirectory();
+            // Also handle stale symlinks of either shape.
+            const isLink = entry.isSymbolicLink();
+            if (!matchesRulePattern && !matchesSkillPattern && !isLink)
+                continue;
+            const fullPath = join(dirAbs, name);
+            if (check) {
+                mismatches.push({
+                    consumerId: consumersForDir[0]?.id ?? dir,
+                    targetPath: fullPath,
+                    reason: 'stale entry not in unified record set',
+                });
+                removed++;
+                continue;
+            }
+            safeRemove(fullPath);
+            removed++;
+        }
+    }
+    return { removed, mismatches };
+}
+/**
+ * Main entrypoint. See module docstring.
+ */
+export function runUnifiedSync(options) {
+    const kinds = options.kinds ?? ['rule', 'skill'];
+    const kindSet = new Set(kinds);
+    const consumers = (options.consumers ?? DEFAULT_UNIFIED_CONSUMERS).filter((consumer) => kindSet.has(consumer.acceptsKind));
+    // Realpath both roots so symlink target paths (computed via `relative()`)
+    // stay in a single realm. Without this, on macOS where tmpdir() resolves
+    // through /var → /private/var, the relative path between a non-real
+    // consumer dir and a real catalog file traverses across the symlink
+    // boundary and lands on a non-existent path.
+    const consumerRoot = (() => {
+        if (existsSync(options.consumerRoot)) {
+            mkdirSync(options.consumerRoot, { recursive: true });
+            return realpathSync(options.consumerRoot);
+        }
+        mkdirSync(options.consumerRoot, { recursive: true });
+        return realpathSync(options.consumerRoot);
+    })();
+    const loaded = loadContent({
+        catalogDir: options.catalogDir,
+        consumerRoot,
+        kinds,
+    });
+    const filteredRecords = options.allowedSkillSlugs
+        ? loaded.records.filter((r) => r.kind !== 'skill' || options.allowedSkillSlugs.has(r.slug))
+        : loaded.records;
+    if (loaded.collisions.length > 0) {
+        const lines = loaded.collisions.map((c) => `  - ${c.kind}/${c.slug}: canonical=${c.canonical} consumer=${c.consumer}`);
+        throw new Error(`wp sync: slug collisions between catalog and consumer (rename consumer copy):\n${lines.join('\n')}`);
+    }
+    const plans = planTargets(filteredRecords, consumers, consumerRoot);
+    let fixCount = 0;
+    const mismatches = [];
+    for (const plan of plans) {
+        const result = applyTarget(plan, options.check === true);
+        if (result.wrote > 0) {
+            fixCount += result.wrote;
+            if (options.check === true && result.mismatch !== undefined) {
+                mismatches.push({
+                    consumerId: plan.consumer.id,
+                    targetPath: plan.targetPath,
+                    reason: result.mismatch,
+                });
+            }
+        }
+    }
+    const prune = pruneStale(plans, consumers, consumerRoot, options.check === true, options.preserveSkillSlugs);
+    fixCount += prune.removed;
+    mismatches.push(...prune.mismatches);
+    return { fixCount, mismatches };
+}
+//# sourceMappingURL=unified-sync.js.map

package/dist/esm/telemetry/_endpoint.d.ts

@@ -0,0 +1,3 @@
+export declare const TELEMETRY_ENDPOINT = "https://telemetry.webpresso.dev/v1/setup-tthw";
+export declare const TELEMETRY_TIMEOUT_MS = 3000;
+//# sourceMappingURL=_endpoint.d.ts.map

package/dist/esm/telemetry/_endpoint.js

@@ -0,0 +1,4 @@
+// Telemetry endpoint config — POST only, zero PII collected
+export const TELEMETRY_ENDPOINT = 'https://telemetry.webpresso.dev/v1/setup-tthw';
+export const TELEMETRY_TIMEOUT_MS = 3_000; // never block setup on network
+//# sourceMappingURL=_endpoint.js.map

package/dist/esm/telemetry/setup-tthw.d.ts

@@ -0,0 +1,10 @@
+export interface TthwPayload {
+    readonly event: 'setup-complete';
+    readonly durationMs: number;
+    readonly webpressoVersion: string;
+    readonly os: string;
+    readonly nodeVersion: string;
+}
+export declare function isTelemetryEnabled(env: Record<string, string | undefined>): boolean;
+export declare function reportTthw(payload: TthwPayload): Promise<void>;
+//# sourceMappingURL=setup-tthw.d.ts.map

package/dist/esm/telemetry/setup-tthw.js

@@ -0,0 +1,34 @@
+import { TELEMETRY_ENDPOINT, TELEMETRY_TIMEOUT_MS } from './_endpoint.js';
+export function isTelemetryEnabled(env) {
+    if (env['WP_TELEMETRY'] === '0')
+        return false;
+    if (env['WP_TELEMETRY'] === '1')
+        return true;
+    if (env['WP_INTERNAL'] === '1')
+        return true;
+    return false;
+}
+export async function reportTthw(payload) {
+    if (process.env['WP_TELEMETRY_DEBUG'] === '1') {
+        console.error('[wp telemetry]', JSON.stringify(payload));
+    }
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), TELEMETRY_TIMEOUT_MS);
+        try {
+            await fetch(TELEMETRY_ENDPOINT, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(payload),
+                signal: controller.signal,
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    catch {
+        // intentionally silent — telemetry must never block or surface errors
+    }
+}
+//# sourceMappingURL=setup-tthw.js.map

package/dist/esm/test/command-builder.d.ts

@@ -0,0 +1,25 @@
+import type { ResolvedTestTarget } from './target-resolver.js';
+export interface CommandConfig {
+    command: string;
+    args: string[];
+    env?: Record<string, string>;
+}
+export type VpRunLogMode = 'interleaved' | 'labeled' | 'grouped';
+export interface TestCommandOptions {
+    watch?: boolean;
+    coverage?: boolean;
+    testNamePattern?: string;
+    mutation?: boolean;
+    workers?: boolean;
+    cache?: boolean;
+    noCache?: boolean;
+    parallel?: boolean;
+    concurrencyLimit?: number;
+    log?: VpRunLogMode;
+    passthrough?: readonly string[];
+}
+export declare function buildTestCommand(target: ResolvedTestTarget, options?: TestCommandOptions): CommandConfig;
+export declare function buildVpTestCommand(filters: readonly string[], options?: TestCommandOptions): CommandConfig;
+export declare function buildVitestCommand(files: readonly string[], options?: TestCommandOptions): CommandConfig;
+export declare function getVpTestTask(options: Pick<TestCommandOptions, 'mutation' | 'workers' | 'watch'>): string;
+//# sourceMappingURL=command-builder.d.ts.map

package/dist/esm/test/command-builder.js

@@ -0,0 +1,98 @@
+export function buildTestCommand(target, options = {}) {
+    if (target.type === 'file') {
+        return buildVitestCommand(target.values, options);
+    }
+    return buildVpTestCommand(target.values, options);
+}
+export function buildVpTestCommand(filters, options = {}) {
+    const task = getVpTestTask(options);
+    const resolvedFilters = filters.map((filter) => formatVpRunFilter(filter, task));
+    const explicitTargets = resolvedFilters.every(isExplicitVpTaskTarget);
+    const args = ['run', ...resolvedFilters];
+    appendVpRunOptions(args, options);
+    if (!explicitTargets) {
+        args.push(task);
+    }
+    const passthrough = buildVitestPassthrough(options);
+    if (passthrough.length > 0) {
+        args.push('--', ...passthrough);
+    }
+    const env = buildVpRunEnv(options);
+    return env ? { command: 'vp', args, env } : { command: 'vp', args };
+}
+export function buildVitestCommand(files, options = {}) {
+    const args = [options.watch ? '--watch' : 'run'];
+    const configFiles = [];
+    const testFiles = [];
+    for (const file of files) {
+        if (isVitestConfigFile(file)) {
+            configFiles.push(file);
+        }
+        else {
+            testFiles.push(file);
+        }
+    }
+    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);
+    }
+    args.push(...buildVitestPassthrough(options), ...testFiles);
+    return { command: 'vitest', args };
+}
+export function getVpTestTask(options) {
+    if (options.mutation)
+        return 'test:mutation';
+    if (options.workers)
+        return 'test:workers';
+    if (options.watch)
+        return 'test:watch';
+    return 'test';
+}
+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 !== undefined) {
+        args.push('--concurrency-limit', String(options.concurrencyLimit));
+    }
+    if (options.log) {
+        args.push('--log', options.log);
+    }
+}
+function buildVpRunEnv(options) {
+    if (options.concurrencyLimit === undefined)
+        return;
+    return { VP_RUN_CONCURRENCY_LIMIT: String(options.concurrencyLimit) };
+}
+function isExplicitVpTaskTarget(target) {
+    return target.includes('#');
+}
+function formatVpRunFilter(filter, task) {
+    if (isExplicitVpTaskTarget(filter)) {
+        return filter;
+    }
+    return filter.startsWith('@') || filter.includes('/') ? `${filter}#${task}` : filter;
+}
+function buildVitestPassthrough(options) {
+    const args = [];
+    if (options.coverage)
+        args.push('--coverage');
+    if (options.testNamePattern)
+        args.push('-t', options.testNamePattern);
+    if (options.passthrough)
+        args.push(...options.passthrough);
+    return args;
+}
+function isVitestConfigFile(file) {
+    return /^vitest(?:\.[\w-]+)?\.config\.(?:ts|mts|cts|js|mjs|cjs)$/u.test(file);
+}
+//# sourceMappingURL=command-builder.js.map

package/dist/esm/test/index.d.ts

@@ -0,0 +1,3 @@
+export { buildTestCommand, buildVitestCommand, buildVpTestCommand, getVpTestTask, type CommandConfig, type TestCommandOptions, type VpRunLogMode, } from './command-builder.js';
+export { looksLikeTestFilePath, resolveTestTarget, type ResolvedTestTarget, type TestTargetInput, type TestTargetType, } from './target-resolver.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/test/index.js

@@ -0,0 +1,3 @@
+export { buildTestCommand, buildVitestCommand, buildVpTestCommand, getVpTestTask, } from './command-builder.js';
+export { looksLikeTestFilePath, resolveTestTarget, } from './target-resolver.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/test/target-resolver.d.ts

@@ -0,0 +1,13 @@
+export type TestTargetType = 'all' | 'file' | 'package';
+export interface ResolvedTestTarget {
+    type: TestTargetType;
+    values: string[];
+}
+export interface TestTargetInput {
+    package?: readonly string[];
+    file?: readonly string[];
+    positional?: readonly string[];
+}
+export declare function looksLikeTestFilePath(target: string): boolean;
+export declare function resolveTestTarget(input: TestTargetInput): ResolvedTestTarget;
+//# sourceMappingURL=target-resolver.d.ts.map

package/dist/esm/test/target-resolver.js

@@ -0,0 +1,53 @@
+const TEST_FILE_EXTENSIONS = [
+    '.test.ts',
+    '.test.tsx',
+    '.spec.ts',
+    '.spec.tsx',
+    '.test.js',
+    '.test.jsx',
+    '.spec.js',
+    '.spec.jsx',
+    '.ts',
+    '.tsx',
+    '.js',
+    '.jsx',
+    '.mts',
+    '.mjs',
+    '.cts',
+    '.cjs',
+];
+export function looksLikeTestFilePath(target) {
+    const normalized = target.replace(/\\/gu, '/');
+    return (normalized.includes('/') ||
+        TEST_FILE_EXTENSIONS.some((extension) => normalized.endsWith(extension)));
+}
+export function resolveTestTarget(input) {
+    const packageTargets = compact(input.package);
+    const fileTargets = compact(input.file);
+    const positionalTargets = compact(input.positional);
+    if (packageTargets.length > 0 && fileTargets.length > 0) {
+        throw new Error('Choose package targets or file targets, not both.');
+    }
+    if (packageTargets.length > 0) {
+        return { type: 'package', values: packageTargets };
+    }
+    if (fileTargets.length > 0) {
+        return { type: 'file', values: fileTargets };
+    }
+    if (positionalTargets.length === 0) {
+        return { type: 'all', values: [] };
+    }
+    const hasFile = positionalTargets.some(looksLikeTestFilePath);
+    const hasPackage = positionalTargets.some((target) => !looksLikeTestFilePath(target));
+    if (hasFile && hasPackage) {
+        throw new Error('Choose package targets or file targets, not both.');
+    }
+    return {
+        type: hasFile ? 'file' : 'package',
+        values: positionalTargets,
+    };
+}
+function compact(values) {
+    return values?.map((value) => value.trim()).filter((value) => value.length > 0) ?? [];
+}
+//# sourceMappingURL=target-resolver.js.map

package/dist/esm/typecheck/index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Stable subpath export: `webpresso/typecheck`.
+ *
+ * Exposes a framework-friendly `runTypecheck` runner that wraps
+ * `tsc --noEmit` either at cwd (no `packages` given) or once per resolved
+ * package path (each becomes `tsc --noEmit -p <pkg>/tsconfig.json`). Mirrors
+ * the semantics of the `wp_typecheck` MCP tool but returns a typed result
+ * directly so external scaffolders can consume it without the MCP transport.
+ */
+export interface TscError {
+    readonly file: string;
+    readonly line: number;
+    readonly code: string;
+    readonly message: string;
+}
+export interface TypecheckResult {
+    readonly passed: boolean;
+    readonly errorCount: number;
+    readonly errors: readonly TscError[];
+    readonly output: string;
+    readonly timedOut?: boolean;
+    readonly aborted?: boolean;
+}
+export interface RunTypecheckOptions {
+    /**
+     * Package paths (relative to cwd). When omitted, runs a single
+     * `tsc --noEmit` at cwd. When provided, runs once per package against
+     * `<pkg>/tsconfig.json`.
+     */
+    readonly packages?: readonly string[];
+    /** Override the resolved project root. */
+    readonly cwd?: string;
+    /** Hard cap on the spawned process(es). Defaults to 10 minutes. */
+    readonly timeoutMs?: number;
+    /** Optional cancellation signal propagated to the child process(es). */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Parse `tsc --noEmit` stdout into structured `{file, line, code, message}`
+ * entries. Lines that don't match the diagnostic format are ignored so
+ * preamble/`tsc` chatter never ends up in the error list.
+ */
+export declare function parseTscOutput(raw: string): TscError[];
+/**
+ * Run typecheck and return structured diagnostics. When `packages` is
+ * provided, runs `tsc --noEmit -p <pkg>/tsconfig.json` once per entry
+ * sequentially and aggregates output; otherwise a single root-level
+ * `tsc --noEmit`. Throws on spawn failures (e.g. tsc missing) — those
+ * indicate a misconfigured environment, not a typecheck verdict.
+ */
+export declare function runTypecheck(options?: RunTypecheckOptions): Promise<TypecheckResult>;
+//# sourceMappingURL=index.d.ts.map