@agentrhq/webcmd 0.1.1 → 0.2.0

package/dist/src/observation/retention.test.js

@@ -0,0 +1,118 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { parseByteSize, pruneTraceArtifacts } from './retention.js';
+describe('trace artifact retention', () => {
+    let tmpDir;
+    let tracesDir;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'webcmd-trace-retention-'));
+        tracesDir = path.join(tmpDir, 'profiles', 'default', 'traces');
+        fs.mkdirSync(tracesDir, { recursive: true });
+    });
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it('parses byte budgets with units', () => {
+        expect(parseByteSize(128)).toBe(128);
+        expect(parseByteSize('128')).toBe(128);
+        expect(parseByteSize('2KB')).toBe(2 * 1024);
+        expect(parseByteSize('1.5MB')).toBe(Math.floor(1.5 * 1024 * 1024));
+        expect(parseByteSize('1 GB')).toBe(1024 ** 3);
+        expect(() => parseByteSize('many')).toThrow('Invalid byte size');
+    });
+    it('prunes traces older than the age budget', () => {
+        const now = Date.parse('2026-05-03T00:00:00.000Z');
+        const old = createTraceDir('old', '2026-04-24T00:00:00.000Z');
+        const recent = createTraceDir('recent', '2026-05-02T00:00:00.000Z');
+        const result = pruneTraceArtifacts(tracesDir, {
+            now: () => now,
+            policy: { maxAgeDays: 7, maxCountPerProfile: 20, maxBytesPerProfile: '500MB' },
+            warn: vi.fn(),
+        });
+        expect(result.deleted).toEqual([old]);
+        expect(fs.existsSync(old)).toBe(false);
+        expect(fs.existsSync(recent)).toBe(true);
+    });
+    it('prunes oldest traces over the count budget', () => {
+        const oldest = createTraceDir('oldest', '2026-05-01T00:00:00.000Z');
+        const middle = createTraceDir('middle', '2026-05-02T00:00:00.000Z');
+        const newest = createTraceDir('newest', '2026-05-03T00:00:00.000Z');
+        const result = pruneTraceArtifacts(tracesDir, {
+            now: () => Date.parse('2026-05-03T12:00:00.000Z'),
+            policy: { maxAgeDays: 30, maxCountPerProfile: 2, maxBytesPerProfile: '500MB' },
+            warn: vi.fn(),
+        });
+        expect(result.deleted).toEqual([oldest]);
+        expect(fs.existsSync(oldest)).toBe(false);
+        expect(fs.existsSync(middle)).toBe(true);
+        expect(fs.existsSync(newest)).toBe(true);
+    });
+    it('prunes oldest traces over the byte budget', () => {
+        const oldest = createTraceDir('oldest', '2026-05-01T00:00:00.000Z', 512);
+        const middle = createTraceDir('middle', '2026-05-02T00:00:00.000Z', 64);
+        const newest = createTraceDir('newest', '2026-05-03T00:00:00.000Z', 64);
+        const budget = directorySize(middle) + directorySize(newest) + 1;
+        const result = pruneTraceArtifacts(tracesDir, {
+            now: () => Date.parse('2026-05-03T12:00:00.000Z'),
+            policy: { maxAgeDays: 30, maxCountPerProfile: 20, maxBytesPerProfile: budget },
+            warn: vi.fn(),
+        });
+        expect(result.deleted).toEqual([oldest]);
+        expect(fs.existsSync(oldest)).toBe(false);
+        expect(fs.existsSync(middle)).toBe(true);
+        expect(fs.existsSync(newest)).toBe(true);
+    });
+    it('falls back to directory mtime when receipt is missing', () => {
+        const now = Date.parse('2026-05-03T00:00:00.000Z');
+        const old = createTraceDir('old-no-receipt', undefined);
+        const recent = createTraceDir('recent', '2026-05-02T00:00:00.000Z');
+        const oldDate = new Date('2026-04-20T00:00:00.000Z');
+        fs.utimesSync(old, oldDate, oldDate);
+        const result = pruneTraceArtifacts(tracesDir, {
+            now: () => now,
+            policy: { maxAgeDays: 7, maxCountPerProfile: 20, maxBytesPerProfile: '500MB' },
+            warn: vi.fn(),
+        });
+        expect(result.deleted).toEqual([old]);
+        expect(fs.existsSync(old)).toBe(false);
+        expect(fs.existsSync(recent)).toBe(true);
+    });
+    it('does not delete the protected trace exported by the current run', () => {
+        const old = createTraceDir('oldest', '2026-05-01T00:00:00.000Z');
+        const current = createTraceDir('current', '2026-04-01T00:00:00.000Z', 1024);
+        const result = pruneTraceArtifacts(tracesDir, {
+            now: () => Date.parse('2026-05-03T12:00:00.000Z'),
+            policy: { maxAgeDays: 0, maxCountPerProfile: 0, maxBytesPerProfile: 1 },
+            protectedTraceDirs: [current],
+            warn: vi.fn(),
+        });
+        expect(result.deleted).toEqual([old]);
+        expect(fs.existsSync(old)).toBe(false);
+        expect(fs.existsSync(current)).toBe(true);
+    });
+    function createTraceDir(name, createdAt, payloadBytes = 8) {
+        const dir = path.join(tracesDir, name);
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(path.join(dir, 'trace.jsonl'), 'x'.repeat(payloadBytes), 'utf-8');
+        if (createdAt) {
+            fs.writeFileSync(path.join(dir, 'receipt.json'), JSON.stringify({ createdAt }, null, 2), 'utf-8');
+            const date = new Date(createdAt);
+            fs.utimesSync(dir, date, date);
+        }
+        return dir;
+    }
+});
+function directorySize(dir) {
+    let total = 0;
+    for (const name of fs.readdirSync(dir)) {
+        const item = path.join(dir, name);
+        const stat = fs.lstatSync(item);
+        if (stat.isDirectory())
+            total += directorySize(item);
+        else
+            total += stat.size;
+    }
+    return total;
+}

package/dist/src/observation/ring-buffer.d.ts

@@ -0,0 +1,22 @@
+export interface RingBufferOptions {
+    maxAgeMs?: number;
+    maxItems?: number;
+    now?: () => number;
+}
+export declare class RingBuffer<T extends {
+    ts: number;
+}> {
+    private readonly maxAgeMs;
+    private readonly maxItems;
+    private readonly now;
+    private items;
+    constructor(opts?: RingBufferOptions);
+    push(item: T): void;
+    values(opts?: {
+        since?: number;
+        until?: number;
+    }): T[];
+    clear(): void;
+    get size(): number;
+    private prune;
+}

package/dist/src/observation/ring-buffer.js

@@ -0,0 +1,45 @@
+export class RingBuffer {
+    maxAgeMs;
+    maxItems;
+    now;
+    items = [];
+    constructor(opts = {}) {
+        this.maxAgeMs = opts.maxAgeMs ?? 120_000;
+        this.maxItems = opts.maxItems ?? 1_000;
+        this.now = opts.now ?? Date.now;
+    }
+    push(item) {
+        this.items.push(item);
+        this.prune();
+    }
+    values(opts = {}) {
+        this.prune();
+        return this.items.filter((item) => {
+            if (opts.since !== undefined && item.ts < opts.since)
+                return false;
+            if (opts.until !== undefined && item.ts > opts.until)
+                return false;
+            return true;
+        });
+    }
+    clear() {
+        this.items = [];
+    }
+    get size() {
+        this.prune();
+        return this.items.length;
+    }
+    prune() {
+        const minTs = this.now() - this.maxAgeMs;
+        if (this.items.length > this.maxItems) {
+            this.items = this.items.slice(this.items.length - this.maxItems);
+        }
+        if (this.maxAgeMs > 0) {
+            const firstKept = this.items.findIndex((item) => item.ts >= minTs);
+            if (firstKept > 0)
+                this.items = this.items.slice(firstKept);
+            else if (firstKept === -1)
+                this.items = [];
+        }
+    }
+}

package/dist/src/observation/ring-buffer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/observation/ring-buffer.test.js

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+import { RingBuffer } from './ring-buffer.js';
+describe('RingBuffer', () => {
+    it('keeps items in event order and filters by time window', () => {
+        let now = 10_000;
+        const buffer = new RingBuffer({ maxAgeMs: 5_000, now: () => now });
+        buffer.push({ ts: 4_000, value: 'old' });
+        buffer.push({ ts: 7_000, value: 'kept' });
+        buffer.push({ ts: 9_000, value: 'new' });
+        expect(buffer.values().map((item) => item.value)).toEqual(['kept', 'new']);
+        expect(buffer.values({ since: 8_000 }).map((item) => item.value)).toEqual(['new']);
+        now = 13_000;
+        expect(buffer.values().map((item) => item.value)).toEqual(['new']);
+    });
+    it('caps by item count', () => {
+        const buffer = new RingBuffer({ maxItems: 2, maxAgeMs: 100_000, now: () => 10 });
+        buffer.push({ ts: 1, value: 1 });
+        buffer.push({ ts: 2, value: 2 });
+        buffer.push({ ts: 3, value: 3 });
+        expect(buffer.values().map((item) => item.value)).toEqual([2, 3]);
+    });
+});

package/dist/src/observation/session.d.ts

@@ -0,0 +1,25 @@
+import type { ObservationEvent, ObservationEventInput, ObservationScope, ObservationStream } from './events.js';
+export declare const DEFAULT_OBSERVATION_WINDOW_MS = 120000;
+export interface ObservationSessionOptions {
+    id?: string;
+    scope: ObservationScope;
+    windowMs?: number;
+    maxEventsPerStream?: number;
+    now?: () => number;
+}
+export declare class ObservationSession {
+    readonly id: string;
+    readonly scope: ObservationScope;
+    readonly startedAt: number;
+    private readonly now;
+    private counter;
+    private readonly buffers;
+    constructor(opts: ObservationSessionOptions);
+    record(input: ObservationEventInput): ObservationEvent;
+    events(opts?: {
+        stream?: ObservationStream;
+        since?: number;
+        until?: number;
+    }): ObservationEvent[];
+}
+export declare function createTraceId(now?: number | (() => number)): string;

package/dist/src/observation/session.js

@@ -0,0 +1,50 @@
+import { RingBuffer } from './ring-buffer.js';
+import { randomBytes } from 'node:crypto';
+export const DEFAULT_OBSERVATION_WINDOW_MS = 120_000;
+export class ObservationSession {
+    id;
+    scope;
+    startedAt;
+    now;
+    counter = 0;
+    buffers;
+    constructor(opts) {
+        this.id = opts.id ?? createTraceId(opts.now?.() ?? Date.now());
+        this.scope = opts.scope;
+        this.now = opts.now ?? Date.now;
+        this.startedAt = this.now();
+        const bufferOpts = {
+            maxAgeMs: opts.windowMs ?? DEFAULT_OBSERVATION_WINDOW_MS,
+            maxItems: opts.maxEventsPerStream ?? 1_000,
+            now: this.now,
+        };
+        this.buffers = {
+            action: new RingBuffer(bufferOpts),
+            network: new RingBuffer(bufferOpts),
+            console: new RingBuffer(bufferOpts),
+            screenshot: new RingBuffer({ ...bufferOpts, maxItems: Math.min(opts.maxEventsPerStream ?? 50, 50) }),
+            state: new RingBuffer({ ...bufferOpts, maxItems: Math.min(opts.maxEventsPerStream ?? 50, 50) }),
+            error: new RingBuffer(bufferOpts),
+        };
+    }
+    record(input) {
+        const event = {
+            ...input,
+            id: input.id ?? `${this.id}-${++this.counter}`,
+            ts: input.ts ?? this.now(),
+        };
+        this.buffers[event.stream].push(event);
+        return event;
+    }
+    events(opts = {}) {
+        const streams = opts.stream ? [opts.stream] : Object.keys(this.buffers);
+        return streams
+            .flatMap((stream) => this.buffers[stream].values({ since: opts.since, until: opts.until }))
+            .sort((a, b) => a.ts - b.ts || a.id.localeCompare(b.id));
+    }
+}
+export function createTraceId(now = Date.now) {
+    const ts = typeof now === 'function' ? now() : now;
+    const rand = randomBytes(4).toString('hex');
+    return `${new Date(ts).toISOString().replace(/[-:.TZ]/g, '').slice(0, 14)}-${rand}`;
+}

package/dist/src/output.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Output formatting: table, JSON, Markdown, CSV, YAML.
+ */
+export interface RenderOptions {
+    fmt?: string;
+    /** True when the user explicitly passed -f on the command line */
+    fmtExplicit?: boolean;
+    columns?: string[];
+    title?: string;
+    elapsed?: number;
+    source?: string;
+    footerExtra?: string;
+}
+export declare function render(data: unknown, opts?: RenderOptions): void;

package/dist/src/output.js

@@ -0,0 +1,152 @@
+/**
+ * Output formatting: table, JSON, Markdown, CSV, YAML.
+ */
+import Table from 'cli-table3';
+import yaml from 'js-yaml';
+function normalizeRows(data) {
+    if (Array.isArray(data))
+        return data;
+    if (data && typeof data === 'object')
+        return [data];
+    return [{ value: data }];
+}
+function resolveColumns(rows, opts) {
+    return opts.columns ?? Object.keys(rows[0] ?? {});
+}
+export function render(data, opts = {}) {
+    let fmt = opts.fmt ?? 'table';
+    // Non-TTY auto-downgrade only when format was NOT explicitly passed by user.
+    if (!opts.fmtExplicit) {
+        if (fmt === 'table' && !process.stdout.isTTY)
+            fmt = 'yaml';
+    }
+    if (data === null || data === undefined) {
+        console.log(data);
+        return;
+    }
+    switch (fmt) {
+        case 'json':
+            renderJson(data);
+            break;
+        case 'plain':
+            renderPlain(data, opts);
+            break;
+        case 'md':
+        case 'markdown':
+            renderMarkdown(data, opts);
+            break;
+        case 'csv':
+            renderCsv(data, opts);
+            break;
+        case 'yaml':
+        case 'yml':
+            renderYaml(data);
+            break;
+        default:
+            renderTable(data, opts);
+            break;
+    }
+}
+function renderTable(data, opts) {
+    const rows = normalizeRows(data);
+    if (!rows.length) {
+        console.log('(no data)');
+        return;
+    }
+    const columns = resolveColumns(rows, opts);
+    const header = columns.map(c => capitalize(c));
+    const table = new Table({
+        head: header.map(h => h),
+        style: { head: [], border: [] },
+        wordWrap: true,
+        wrapOnWordBoundary: true,
+    });
+    for (const row of rows) {
+        table.push(columns.map(c => {
+            const v = row[c];
+            return v === null || v === undefined ? '' : String(v);
+        }));
+    }
+    console.log();
+    if (opts.title)
+        console.log(`  ${opts.title}`);
+    console.log(table.toString());
+    const footer = [];
+    footer.push(`${rows.length} items`);
+    if (opts.elapsed !== undefined)
+        footer.push(`${opts.elapsed.toFixed(1)}s`);
+    if (opts.source)
+        footer.push(opts.source);
+    if (opts.footerExtra)
+        footer.push(opts.footerExtra);
+    console.log(footer.join(' | '));
+}
+function renderJson(data) {
+    console.log(JSON.stringify(data, null, 2));
+}
+function renderPlain(data, opts) {
+    const rows = normalizeRows(data);
+    if (!rows.length)
+        return;
+    // Single-row single-field shortcuts for chat-style commands.
+    if (rows.length === 1) {
+        const row = rows[0];
+        const entries = Object.entries(row);
+        if (entries.length === 1) {
+            const [key, value] = entries[0];
+            if (key === 'response' || key === 'content' || key === 'markdown' || key === 'text' || key === 'value') {
+                console.log(String(value ?? ''));
+                return;
+            }
+        }
+    }
+    rows.forEach((row, index) => {
+        const entries = Object.entries(row).filter(([, value]) => value !== undefined && value !== null && String(value) !== '');
+        entries.forEach(([key, value]) => {
+            console.log(`${key}: ${value}`);
+        });
+        if (index < rows.length - 1)
+            console.log('');
+    });
+}
+function renderMarkdown(data, opts) {
+    const rows = normalizeRows(data);
+    if (!rows.length)
+        return;
+    if (rows.length === 1) {
+        const entries = Object.entries(rows[0]);
+        if (entries.length === 1) {
+            const [key, value] = entries[0];
+            if (key === 'content' || key === 'markdown' || key === 'text' || key === 'value') {
+                console.log(String(value ?? ''));
+                return;
+            }
+        }
+    }
+    const columns = resolveColumns(rows, opts);
+    console.log('| ' + columns.join(' | ') + ' |');
+    console.log('| ' + columns.map(() => '---').join(' | ') + ' |');
+    for (const row of rows) {
+        console.log('| ' + columns.map(c => String(row[c] ?? '')).join(' | ') + ' |');
+    }
+}
+function renderCsv(data, opts) {
+    const rows = normalizeRows(data);
+    if (!rows.length)
+        return;
+    const columns = resolveColumns(rows, opts);
+    console.log(columns.join(','));
+    for (const row of rows) {
+        console.log(columns.map(c => {
+            const v = String(row[c] ?? '');
+            return v.includes(',') || v.includes('"') || v.includes('\n') || v.includes('\r')
+                ? `"${v.replace(/"/g, '""')}"` : v;
+        }).join(','));
+    }
+}
+function renderYaml(data) {
+    console.log(yaml.dump(data, { sortKeys: false, lineWidth: 120, noRefs: true }));
+}
+function capitalize(s) {
+    return s.charAt(0).toUpperCase() + s.slice(1);
+}

package/dist/src/output.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/output.test.js

@@ -0,0 +1,53 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
+import { render } from './output.js';
+describe('output TTY detection', () => {
+    const originalIsTTY = process.stdout.isTTY;
+    let logSpy;
+    beforeEach(() => {
+        logSpy = vi.spyOn(console, 'log').mockImplementation(() => { });
+    });
+    afterEach(() => {
+        Object.defineProperty(process.stdout, 'isTTY', { value: originalIsTTY, writable: true });
+        logSpy.mockRestore();
+    });
+    it('outputs YAML in non-TTY when format is default table', () => {
+        Object.defineProperty(process.stdout, 'isTTY', { value: false, writable: true });
+        // commanderAdapter always passes fmt:'table' as default — this must still trigger downgrade
+        render([{ name: 'alice', score: 10 }], { fmt: 'table', columns: ['name', 'score'] });
+        const out = logSpy.mock.calls.map((c) => c[0]).join('\n');
+        expect(out).toContain('name: alice');
+        expect(out).toContain('score: 10');
+    });
+    it('outputs table in TTY when format is default table', () => {
+        Object.defineProperty(process.stdout, 'isTTY', { value: true, writable: true });
+        render([{ name: 'alice', score: 10 }], { fmt: 'table', columns: ['name', 'score'] });
+        const out = logSpy.mock.calls.map((c) => c[0]).join('\n');
+        expect(out).toContain('alice');
+    });
+    it('respects explicit -f json even in non-TTY', () => {
+        Object.defineProperty(process.stdout, 'isTTY', { value: false, writable: true });
+        render([{ name: 'alice' }], { fmt: 'json' });
+        const out = logSpy.mock.calls.map((c) => c[0]).join('\n');
+        expect(JSON.parse(out)).toEqual([{ name: 'alice' }]);
+    });
+    it('shows elapsed time when elapsed is 0', () => {
+        Object.defineProperty(process.stdout, 'isTTY', { value: true, writable: true });
+        render([{ name: 'alice' }], { fmt: 'table', columns: ['name'], elapsed: 0 });
+        const out = logSpy.mock.calls.map((c) => c[0]).join('\n');
+        expect(out).toContain('0.0s');
+    });
+    it('explicit -f table overrides non-TTY auto-downgrade', () => {
+        Object.defineProperty(process.stdout, 'isTTY', { value: false, writable: true });
+        render([{ name: 'alice' }], { fmt: 'table', fmtExplicit: true, columns: ['name'] });
+        const out = logSpy.mock.calls.map((c) => c[0]).join('\n');
+        // Should be table output, not YAML
+        expect(out).not.toContain('name: alice');
+        expect(out).toContain('alice');
+    });
+    it('prints single markdown payloads without wrapping them in a table', () => {
+        render([{ markdown: '# Title\n\nBody' }], { fmt: 'md' });
+        const out = logSpy.mock.calls.map((c) => c[0]).join('\n');
+        expect(out).toBe('# Title\n\nBody');
+        expect(out).not.toContain('| markdown |');
+    });
+});

package/dist/src/package-exports.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/package-exports.test.js

@@ -0,0 +1,112 @@
+/**
+ * Regression tests for package exports.
+ *
+ * Ensures adapter files use @agentrhq/webcmd public package imports
+ * (not fragile relative paths) and that all declared exports resolve
+ * to real files.
+ */
+import { describe, it, expect } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { builtinModules } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import ts from 'typescript';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '..');
+const CLIS_DIR = path.join(ROOT, 'clis');
+/** Recursively collect all JS adapter files in a directory. */
+function collectAdapterFiles(dir, opts) {
+    const results = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            results.push(...collectAdapterFiles(full, opts));
+        }
+        else if (entry.name.endsWith('.js') && !entry.name.endsWith('.d.js')) {
+            if (opts?.excludeTests && (entry.name.endsWith('.test.js') || entry.name.startsWith('test-')))
+                continue;
+            results.push(full);
+        }
+    }
+    return results;
+}
+const ALLOWED_BARE_IMPORTS = new Set([
+    '@agentrhq/webcmd',
+    ...builtinModules.flatMap((name) => name.startsWith('node:')
+        ? [name, name.slice(5)]
+        : [name, `node:${name}`]),
+]);
+function isAllowedImport(specifier) {
+    return specifier.startsWith('./')
+        || specifier.startsWith('../')
+        || specifier.startsWith('/')
+        || specifier.startsWith('@agentrhq/webcmd/')
+        || ALLOWED_BARE_IMPORTS.has(specifier);
+}
+/** Forbidden relative import patterns that should have been replaced.
+ * Uses (?:\.\./)+ to catch any depth of ../ traversal.
+ * Covers: import/export from, vi.mock(), vi.importActual(). */
+const FORBIDDEN_PATTERNS = [
+    /(?:from|mock|importActual)\s*\(?['"](?:\.\.\/)+src\//,
+    /(?:from|mock|importActual)\s*\(?['"](?:\.\.\/)+browser\//,
+    /(?:from|mock|importActual)\s*\(?['"](?:\.\.\/)+download\//,
+    /(?:from|mock|importActual)\s*\(?['"](?:\.\.\/)+pipeline\//,
+];
+describe('adapter imports use package exports', () => {
+    const adapterFiles = collectAdapterFiles(CLIS_DIR);
+    const runtimeAdapterFiles = collectAdapterFiles(CLIS_DIR, { excludeTests: true });
+    it('found adapter files to check', () => {
+        expect(adapterFiles.length).toBeGreaterThan(100);
+    });
+    it('no adapter uses relative imports to src/, browser/, download/, or pipeline/', () => {
+        const violations = [];
+        for (const file of adapterFiles) {
+            const content = fs.readFileSync(file, 'utf-8');
+            for (const pattern of FORBIDDEN_PATTERNS) {
+                if (pattern.test(content)) {
+                    const rel = path.relative(ROOT, file);
+                    const match = content.match(pattern)?.[0];
+                    violations.push(`${rel}: ${match}`);
+                }
+            }
+        }
+        expect(violations).toEqual([]);
+    });
+    it('non-test adapters only import node builtins, relative modules, or webcmd public APIs', () => {
+        const violations = [];
+        for (const file of runtimeAdapterFiles) {
+            const source = fs.readFileSync(file, 'utf-8');
+            const module = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.JS);
+            for (const stmt of module.statements) {
+                if (!ts.isImportDeclaration(stmt) && !ts.isExportDeclaration(stmt))
+                    continue;
+                const specifier = stmt.moduleSpecifier?.getText(module).slice(1, -1);
+                if (specifier && !isAllowedImport(specifier)) {
+                    violations.push({
+                        file: path.relative(ROOT, file),
+                        specifier,
+                    });
+                }
+            }
+        }
+        expect(violations).toEqual([]);
+    });
+});
+describe('package.json exports resolve to real files', () => {
+    const pkgJson = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf-8'));
+    const exports = pkgJson.exports;
+    it('has exports defined', () => {
+        expect(Object.keys(exports).length).toBeGreaterThan(5);
+    });
+    for (const [exportPath, target] of Object.entries(exports)) {
+        it(`export "${exportPath}" → ${target} has a source file`, () => {
+            // Export targets point to dist/ (compiled). Verify the source .ts exists.
+            // dist/src/foo.js → src/foo.ts
+            const sourcePath = target
+                .replace(/^\.\/dist\//, './')
+                .replace(/\.js$/, '.ts');
+            const fullPath = path.join(ROOT, sourcePath);
+            expect(fs.existsSync(fullPath), `Missing source: ${sourcePath}`).toBe(true);
+        });
+    }
+});

package/dist/src/package-paths.d.ts

@@ -0,0 +1,8 @@
+export interface PackageJsonLike {
+    bin?: string | Record<string, string>;
+    main?: string;
+}
+export declare function findPackageRoot(startFile: string, fileExists?: (candidate: string) => boolean): string;
+export declare function getBuiltEntryCandidates(packageRoot: string, readFile?: (filePath: string) => string): string[];
+export declare function getCliManifestPath(clisDir: string): string;
+export declare function getFetchAdaptersScriptPath(packageRoot: string): string;