@aperant/framework 0.6.2

package/dist/__tests__/route-pr-review-skill.test.js

@@ -0,0 +1,132 @@
+/**
+ * Task 22-04-26_add-post-ship-pr-review-auto-suggest-in--kzve — router
+ * carve-out for the `review PR <N>` natural-language path. Validates the
+ * skill-passthrough branch in route.mjs at the `const PR_REVIEW_SIGNAL`
+ * guard: when firstWord === 'review' AND remainingArgs matches the PR
+ * signal regex, route.mjs MUST fall through to the classify envelope
+ * (so the host LLM can pick between apt:review and apt:pr-review via
+ * when_to_use metadata) instead of returning a skill-passthrough to
+ * apt-reviewer.
+ *
+ * Structurally mirrors route-design-skill.test.ts (execSync against the
+ * apt-tools route binary; temp project dir; envelope JSON assertions).
+ */
+import { execSync } from 'node:child_process';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+const APT_TOOLS = resolve(__dirname, '../../bin/apt-tools.mjs');
+function makeProject() {
+    const root = mkdtempSync(join(tmpdir(), 'apt-pr-review-route-'));
+    mkdirSync(join(root, '.aperant'), { recursive: true });
+    writeFileSync(join(root, '.aperant', 'config.json'), JSON.stringify({ initialized: true }));
+    return root;
+}
+function route(cwd, args) {
+    try {
+        const out = execSync(`node ${APT_TOOLS} route . ${args.join(' ')}`, {
+            encoding: 'utf-8',
+            cwd,
+            env: {
+                ...process.env,
+                APT_SUPPRESS_GITIGNORE_DRIFT: '1',
+                // Simulate Claude Code so detectHost() returns a known runtime.
+                // Without this, CI (where CLAUDECODE et al. are unset) hits
+                // route's unknown_host guard on the classify path. Mirrors the
+                // pattern in route-plan-mode.test.ts.
+                CLAUDECODE: '1',
+            },
+        });
+        return { code: 0, out };
+    }
+    catch (err) {
+        const e = err;
+        return { code: e.status ?? 1, out: e.stdout ?? '' };
+    }
+}
+describe('router — review/pr-review carve-out', () => {
+    it('routes "review PR 42" to classify (NOT skill-passthrough apt:review)', () => {
+        const root = makeProject();
+        const { code, out } = route(root, ['--input', '"review PR 42"']);
+        expect(code).toBe(0);
+        const env = JSON.parse(out);
+        expect(env.mode).toBe('classify');
+        expect(env.skill).toBeUndefined();
+        expect(env.classification?.source).toBe('host-model-deferred');
+        rmSync(root, { recursive: true, force: true });
+    });
+    it('routes "review #7" to classify', () => {
+        const root = makeProject();
+        const { code, out } = route(root, ['--input', '"review #7"']);
+        expect(code).toBe(0);
+        const env = JSON.parse(out);
+        expect(env.mode).toBe('classify');
+        expect(env.classification?.source).toBe('host-model-deferred');
+        rmSync(root, { recursive: true, force: true });
+    });
+    it('routes "review pull request 99" to classify', () => {
+        const root = makeProject();
+        const { code, out } = route(root, ['--input', '"review pull request 99"']);
+        expect(code).toBe(0);
+        const env = JSON.parse(out);
+        expect(env.mode).toBe('classify');
+        expect(env.classification?.source).toBe('host-model-deferred');
+        rmSync(root, { recursive: true, force: true });
+    });
+    it('regression: "review src/foo.ts" still passthrough to apt:review', () => {
+        const root = makeProject();
+        const { code, out } = route(root, ['--input', '"review src/foo.ts"']);
+        expect(code).toBe(0);
+        const env = JSON.parse(out);
+        expect(env.mode).toBe('skill-passthrough');
+        expect(env.skill).toBe('review');
+        rmSync(root, { recursive: true, force: true });
+    });
+    it('false-positive guard: "review pr-review usage docs" passthrough to apt:review (no digit)', () => {
+        const root = makeProject();
+        const { code, out } = route(root, ['--input', '"review pr-review usage docs"']);
+        expect(code).toBe(0);
+        const env = JSON.parse(out);
+        expect(env.mode).toBe('skill-passthrough');
+        expect(env.skill).toBe('review');
+        rmSync(root, { recursive: true, force: true });
+    });
+    it('false-positive guard: "review pull request docs" passthrough to apt:review (no digit)', () => {
+        const root = makeProject();
+        const { code, out } = route(root, ['--input', '"review pull request docs"']);
+        expect(code).toBe(0);
+        const env = JSON.parse(out);
+        expect(env.mode).toBe('skill-passthrough');
+        expect(env.skill).toBe('review');
+        rmSync(root, { recursive: true, force: true });
+    });
+    it('false-positive guard: "review pull request template" passthrough to apt:review (no digit)', () => {
+        const root = makeProject();
+        const { code, out } = route(root, ['--input', '"review pull request template"']);
+        expect(code).toBe(0);
+        const env = JSON.parse(out);
+        expect(env.mode).toBe('skill-passthrough');
+        expect(env.skill).toBe('review');
+        rmSync(root, { recursive: true, force: true });
+    });
+    it('false-positive guard: "review the pull request feature" passthrough to apt:review (no digit)', () => {
+        const root = makeProject();
+        const { code, out } = route(root, ['--input', '"review the pull request feature"']);
+        expect(code).toBe(0);
+        const env = JSON.parse(out);
+        expect(env.mode).toBe('skill-passthrough');
+        expect(env.skill).toBe('review');
+        rmSync(root, { recursive: true, force: true });
+    });
+    it('sanity: "pr-review 42" still first-word passthrough to apt:pr-review', () => {
+        const root = makeProject();
+        const { code, out } = route(root, ['--input', '"pr-review 42"']);
+        expect(code).toBe(0);
+        const env = JSON.parse(out);
+        expect(env.mode).toBe('skill-passthrough');
+        expect(env.skill).toBe('pr-review');
+        rmSync(root, { recursive: true, force: true });
+    });
+});
+//# sourceMappingURL=route-pr-review-skill.test.js.map

package/dist/__tests__/route-pr-review-skill.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-pr-review-skill.test.js","sourceRoot":"","sources":["../../src/__tests__/route-pr-review-skill.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/route-runtime-override.test.d.ts

@@ -0,0 +1,18 @@
+/**
+ * route-runtime-override.test.ts — `--runtime <id>` host override flag.
+ *
+ * Closes the D-02 gap where route.mjs's unknown_host error envelope advertised
+ * a `--runtime <id>` override that did not actually exist (PR #59 patched
+ * around it by injecting CLAUDECODE=1 into test envs; commit 36e544fb).
+ *
+ * Asserts:
+ *   1. Env-free invocation + `--runtime claude-code` produces a successful
+ *      route envelope (status=ok) — the override makes free-text routing
+ *      work under a CI-hermetic environment.
+ *   2. Unknown `--runtime` value produces a structured `invalid_runtime_override`
+ *      error envelope (exit code 1).
+ *   3. `--runtime` wins over env-detected host (CLAUDECODE=1 AND
+ *      --runtime codex ⇒ codex capabilities).
+ */
+export {};
+//# sourceMappingURL=route-runtime-override.test.d.ts.map

package/dist/__tests__/route-runtime-override.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-runtime-override.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/route-runtime-override.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG"}

package/dist/__tests__/route-runtime-override.test.js

@@ -0,0 +1,164 @@
+/**
+ * route-runtime-override.test.ts — `--runtime <id>` host override flag.
+ *
+ * Closes the D-02 gap where route.mjs's unknown_host error envelope advertised
+ * a `--runtime <id>` override that did not actually exist (PR #59 patched
+ * around it by injecting CLAUDECODE=1 into test envs; commit 36e544fb).
+ *
+ * Asserts:
+ *   1. Env-free invocation + `--runtime claude-code` produces a successful
+ *      route envelope (status=ok) — the override makes free-text routing
+ *      work under a CI-hermetic environment.
+ *   2. Unknown `--runtime` value produces a structured `invalid_runtime_override`
+ *      error envelope (exit code 1).
+ *   3. `--runtime` wins over env-detected host (CLAUDECODE=1 AND
+ *      --runtime codex ⇒ codex capabilities).
+ */
+import { execFileSync, spawnSync } from 'node:child_process';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+const APT_TOOLS = resolve(__dirname, '../../bin/apt-tools.mjs');
+/**
+ * Build a clean env that strips every CLI-detection variable the framework
+ * recognizes. Mirrors the list used by host-detect.test.ts so the two specs
+ * stay in sync when a new runtime is added. `extras` is merged last so a
+ * specific test can inject exactly one (or zero) runtime markers.
+ */
+function envFreeShell(extras = {}) {
+    const cleanEnv = {
+        PATH: process.env.PATH,
+        HOME: process.env.HOME,
+        APT_SUPPRESS_GITIGNORE_DRIFT: '1',
+    };
+    const CLI_VARS = [
+        'CLAUDE_CODE_SSE_PORT',
+        'CLAUDE_CONFIG_DIR',
+        'CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS',
+        'CLAUDECODE',
+        'CLAUDE_CODE_ENTRYPOINT',
+        'CODEX_HOME',
+        'CODEX_THREAD_ID',
+        'GEMINI_CONFIG_DIR',
+        'GEMINI_SESSION_ID',
+        'OPENCODE_CONFIG_DIR',
+        'OPENCODE_CONFIG',
+        'OPENCODE_SESSION_ID',
+        'PI_CODING_AGENT',
+        'TERM_PROGRAM',
+        'APERANT_IPC_SOCKET',
+        'APERANT_SPAWN_DEPTH',
+        'CURSOR_TRACE_ID',
+        'CURSOR_CONFIG_DIR',
+        'WINDSURF_CONFIG_DIR',
+        'WINDSURF_SESSION_ID',
+        'KILO_CONFIG_DIR',
+        'KILO_SESSION_ID',
+        'GITHUB_COPILOT_CLI_SESSION',
+        'COPILOT_CLI_SESSION',
+        'GITHUB_COPILOT_TOKEN',
+        'ANTIGRAVITY_CONFIG_DIR',
+        'ANTIGRAVITY_SESSION_ID',
+        'AUGMENT_CONFIG_DIR',
+        'AUGMENT_SESSION_ID',
+        'TRAE_CONFIG_DIR',
+        'TRAE_SESSION_ID',
+        'QWEN_CONFIG_DIR',
+        'QWEN_SESSION_ID',
+        'CLINE_CONFIG_DIR',
+        'CLINE_SESSION_ID',
+        'CODEBUDDY_CONFIG_DIR',
+        'CODEBUDDY_SESSION_ID',
+    ];
+    for (const v of CLI_VARS) {
+        cleanEnv[v] = undefined;
+    }
+    Object.assign(cleanEnv, extras);
+    return cleanEnv;
+}
+function makeProject() {
+    const root = mkdtempSync(join(tmpdir(), 'apt-route-runtime-'));
+    mkdirSync(join(root, '.aperant'), { recursive: true });
+    writeFileSync(join(root, '.aperant', 'config.json'), JSON.stringify({ initialized: true }));
+    return root;
+}
+describe('route --runtime <id> override', () => {
+    let root;
+    beforeEach(() => {
+        root = makeProject();
+    });
+    afterEach(() => {
+        rmSync(root, { recursive: true, force: true });
+    });
+    it('env-free invocation with --runtime claude-code produces a successful envelope', () => {
+        // Simulates a CI runner (no CLI detection env vars) where the raw
+        // route call would otherwise hit the unknown-host guard. The
+        // override recovers the classify path deterministically.
+        const stdout = execFileSync('node', [APT_TOOLS, 'route', '.', '--input', 'fix a typo', '--runtime', 'claude-code'], {
+            encoding: 'utf-8',
+            cwd: root,
+            env: envFreeShell(),
+        });
+        const parsed = JSON.parse(stdout);
+        expect(parsed.status).toBe('ok');
+        // host_capabilities must reflect the override, not the auto-detected
+        // unknown host. Claude Code grants sub_agents + worktrees + structured
+        // prompts — the capability bundle distinguishing it from e.g. codex.
+        expect(parsed.host_capabilities?.sub_agents).toBe(true);
+        expect(parsed.host_capabilities?.worktrees).toBe(true);
+        expect(parsed.host_capabilities?.structured_prompts).toBe(true);
+    });
+    it('unknown --runtime value produces invalid_runtime_override error (exit 1)', () => {
+        const res = spawnSync('node', [APT_TOOLS, 'route', '.', '--input', 'fix a typo', '--runtime', 'not-a-real-cli'], {
+            encoding: 'utf-8',
+            cwd: root,
+            env: envFreeShell(),
+        });
+        expect(res.status).toBe(1);
+        const parsed = JSON.parse(res.stdout);
+        expect(parsed.status).toBe('error');
+        expect(parsed.error_code).toBe('invalid_runtime_override');
+        // Reason must enumerate the supported hosts so callers can fix the typo
+        // without having to dig for the canonical list.
+        expect(parsed.reason).toContain('claude-code');
+        expect(parsed.reason).toContain('codex');
+        expect(parsed.reason).toContain('not-a-real-cli');
+    });
+    it('--runtime wins over auto-detection (CLAUDECODE=1 + --runtime codex ⇒ codex)', () => {
+        // Override must beat env-based detection. Codex's capability bundle
+        // differs from Claude Code's on worktrees (false) and structured
+        // prompts (false), so those flags are the load-bearing assertion.
+        const stdout = execFileSync('node', [APT_TOOLS, 'route', '.', '--input', 'fix a typo', '--runtime', 'codex'], {
+            encoding: 'utf-8',
+            cwd: root,
+            env: envFreeShell({ CLAUDECODE: '1' }),
+        });
+        const parsed = JSON.parse(stdout);
+        expect(parsed.status).toBe('ok');
+        expect(parsed.host_capabilities?.sub_agents).toBe(true); // codex grants this
+        expect(parsed.host_capabilities?.worktrees).toBe(false); // claude-code would be true
+        expect(parsed.host_capabilities?.structured_prompts).toBe(false); // claude-code would be true
+        expect(parsed.host_capabilities?.background_agents).toBe(true); // codex grants this
+    });
+    it('--runtime pi disables sub_agents even when CLAUDECODE=1 is set', () => {
+        // Belt-and-suspenders: overriding to a runtime with a DIFFERENT
+        // capability bundle must fully replace the auto-detected one. Pi's
+        // capabilities are all-false (structured prompts, worktrees,
+        // sub-agents, background, teams), so this is the most contrastive
+        // check against a leaking claude-code detection.
+        const stdout = execFileSync('node', [APT_TOOLS, 'route', '.', '--input', 'fix a typo', '--runtime', 'pi'], {
+            encoding: 'utf-8',
+            cwd: root,
+            env: envFreeShell({ CLAUDECODE: '1' }),
+        });
+        const parsed = JSON.parse(stdout);
+        expect(parsed.status).toBe('ok');
+        expect(parsed.host_capabilities?.sub_agents).toBe(false);
+        expect(parsed.host_capabilities?.worktrees).toBe(false);
+        expect(parsed.host_capabilities?.structured_prompts).toBe(false);
+        expect(parsed.host_capabilities?.background_agents).toBe(false);
+        expect(parsed.host_capabilities?.agent_teams).toBe(false);
+    });
+});
+//# sourceMappingURL=route-runtime-override.test.js.map

package/dist/__tests__/route-runtime-override.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-runtime-override.test.js","sourceRoot":"","sources":["../../src/__tests__/route-runtime-override.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/route-skill-discover.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * route-skill-discover.test.ts — router-0.3.0 filesystem scan.
+ *
+ * Unit tests for the discoverSkills() fn. Covers trust-boundary
+ * containment (AC-T-1 prep), malformed-frontmatter drop behavior, and
+ * deterministic ordering.
+ */
+export {};
+//# sourceMappingURL=route-skill-discover.test.d.ts.map

package/dist/__tests__/route-skill-discover.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-skill-discover.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/route-skill-discover.test.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/__tests__/route-skill-discover.test.js

@@ -0,0 +1,163 @@
+/**
+ * route-skill-discover.test.ts — router-0.3.0 filesystem scan.
+ *
+ * Unit tests for the discoverSkills() fn. Covers trust-boundary
+ * containment (AC-T-1 prep), malformed-frontmatter drop behavior, and
+ * deterministic ordering.
+ */
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { discoverSkills } from '../cli/route/skill-discover.mjs';
+const FAT_FRONTMATTER = `---
+name: apt:demo
+description: Demo skill
+stage: plan
+intent: implement
+when_to_use: "When demoing."
+user_invocable: true
+internal: false
+spawns_agent: false
+agent_name: null
+allowed-tools: "Read"
+argument-hint: "apt:demo"
+gates: []
+default_execution_mode: auto
+execution_modes:
+  - auto
+  - step
+---
+<objective>demo</objective>
+<your_environment></your_environment>
+<state_files></state_files>
+<process>
+## 1. A
+## 2. B
+</process>
+`;
+describe('discoverSkills', () => {
+    let root;
+    beforeEach(() => {
+        root = mkdtempSync(join(tmpdir(), 'apt-discover-'));
+    });
+    afterEach(() => {
+        rmSync(root, { recursive: true, force: true });
+    });
+    function makeSkill(dir, slug, frontmatter = FAT_FRONTMATTER) {
+        const skillDir = join(dir, `apt-${slug}`);
+        mkdirSync(skillDir, { recursive: true });
+        writeFileSync(join(skillDir, 'SKILL.md'), frontmatter.replace('apt:demo', `apt:${slug}`));
+    }
+    it('discovers every apt-<slug>/SKILL.md under a trusted root', () => {
+        const trusted = join(root, 'skills');
+        mkdirSync(trusted);
+        makeSkill(trusted, 'alpha');
+        makeSkill(trusted, 'beta');
+        const res = discoverSkills({ targetDir: root, trustedSkillSources: [trusted] });
+        expect(res.skills.map((s) => s.name).sort()).toEqual(['apt:alpha', 'apt:beta']);
+        expect(res.dropped).toHaveLength(0);
+    });
+    it('drops skills that live outside every trusted root', () => {
+        const trusted = join(root, 'trusted');
+        const rogue = join(root, 'junk-skills');
+        mkdirSync(trusted);
+        mkdirSync(rogue);
+        makeSkill(trusted, 'safe');
+        makeSkill(rogue, 'evil');
+        const res = discoverSkills({ targetDir: root, trustedSkillSources: [trusted] });
+        const names = res.skills.map((s) => s.name);
+        expect(names).toContain('apt:safe');
+        expect(names).not.toContain('apt:evil');
+        // Because /junk-skills isn't in scanned roots, the rogue SKILL.md
+        // is never read at all — it doesn't appear in `dropped` either.
+        // The trust boundary is enforced by scanning only trusted roots.
+        expect(res.scanned_roots).toEqual([trusted]);
+    });
+    it('drops skills with malformed frontmatter and logs them', () => {
+        const trusted = join(root, 'skills');
+        mkdirSync(trusted);
+        makeSkill(trusted, 'good');
+        // A skill whose frontmatter is missing the fat keys
+        const badDir = join(trusted, 'apt-bad');
+        mkdirSync(badDir);
+        writeFileSync(join(badDir, 'SKILL.md'), `---
+name: apt:bad
+description: bad
+---
+<objective>x</objective>
+`);
+        const res = discoverSkills({ targetDir: root, trustedSkillSources: [trusted] });
+        expect(res.skills.map((s) => s.name)).toEqual(['apt:good']);
+        expect(res.dropped).toHaveLength(1);
+        expect(res.dropped[0].reason).toBe('malformed_frontmatter');
+        // Dropped log was appended
+        const logPath = join(root, '.aperant', 'logs', 'route-dropped.jsonl');
+        const logged = readFileSync(logPath, 'utf-8');
+        expect(logged).toMatch(/apt-bad\/SKILL\.md/);
+        expect(logged).toMatch(/malformed_frontmatter/);
+    });
+    it('is deterministic — two calls on the same input return identical records', () => {
+        const trusted = join(root, 'skills');
+        mkdirSync(trusted);
+        makeSkill(trusted, 'zeta');
+        makeSkill(trusted, 'alpha');
+        makeSkill(trusted, 'middle');
+        const a = discoverSkills({ targetDir: root, trustedSkillSources: [trusted] });
+        const b = discoverSkills({ targetDir: root, trustedSkillSources: [trusted] });
+        expect(JSON.stringify(a.skills)).toBe(JSON.stringify(b.skills));
+        // And sorted by name
+        const names = a.skills.map((s) => s.name);
+        expect(names).toEqual([...names].sort());
+    });
+    it('ignores top-level apt-*.md files (they are agent defs, not skills)', () => {
+        const trusted = join(root, 'skills');
+        mkdirSync(trusted);
+        makeSkill(trusted, 'real');
+        writeFileSync(join(trusted, 'apt-planner.md'), '# agent def — not a skill');
+        const res = discoverSkills({ targetDir: root, trustedSkillSources: [trusted] });
+        expect(res.skills.map((s) => s.name)).toEqual(['apt:real']);
+    });
+    it('returns empty output silently when no trusted roots exist', () => {
+        const res = discoverSkills({
+            targetDir: root,
+            trustedSkillSources: [join(root, 'nonexistent')],
+        });
+        expect(res.skills).toEqual([]);
+        expect(res.dropped).toEqual([]);
+        expect(res.scanned_roots).toEqual([]);
+    });
+    it('SEC-002: a symlinked SKILL.md pointing outside the trusted root is rejected', () => {
+        // Attack vector: inside the trusted root, create a real apt-escaped/
+        // directory (which walkSkillRoot will traverse), then place a symlink
+        // SKILL.md that points to a SKILL.md file outside the trusted root.
+        // Without realpathSync, pathInsideAnyRoot would see the symlink path
+        // (inside the root) and accept it. With realpathSync it resolves to the
+        // external target and correctly rejects it.
+        const outside = mkdtempSync(join(tmpdir(), 'apt-sec002-outside-'));
+        try {
+            const trusted = join(root, 'skills');
+            mkdirSync(trusted);
+            // Plant the attacker's real SKILL.md in the outside dir.
+            const externalSkillFile = join(outside, 'SKILL.md');
+            writeFileSync(externalSkillFile, FAT_FRONTMATTER.replace('apt:demo', 'apt:escaped'));
+            // Create a real skill directory inside the trusted root.
+            const skillDir = join(trusted, 'apt-escaped');
+            mkdirSync(skillDir);
+            // Create a symlink SKILL.md inside the trusted dir that points
+            // to the external file — this is the actual attack vector.
+            symlinkSync(externalSkillFile, join(skillDir, 'SKILL.md'));
+            const res = discoverSkills({ targetDir: root, trustedSkillSources: [trusted] });
+            const names = res.skills.map((s) => s.name);
+            // The skill loaded via the symlinked SKILL.md must NOT be accepted —
+            // realpathSync resolves the symlink to the external path.
+            expect(names).not.toContain('apt:escaped');
+            // It should appear in dropped as outside_allowlist.
+            expect(res.dropped.some((d) => d.reason === 'outside_allowlist')).toBe(true);
+        }
+        finally {
+            rmSync(outside, { recursive: true, force: true });
+        }
+    });
+});
+//# sourceMappingURL=route-skill-discover.test.js.map

package/dist/__tests__/route-skill-discover.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-skill-discover.test.js","sourceRoot":"","sources":["../../src/__tests__/route-skill-discover.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/route-trust-boundary.test.d.ts

@@ -0,0 +1,10 @@
+/**
+ * route-trust-boundary.test.ts — router-0.3.0 trusted_skill_sources allowlist.
+ *
+ * Covers AC-T-1: a malicious apt-<slug>/SKILL.md outside every configured
+ * trusted root is NEVER visible in the router envelope. Also exercises the
+ * sanity path — explicitly allowlisting a root makes it visible (proves
+ * the allowlist actually works and isn't a dead check).
+ */
+export {};
+//# sourceMappingURL=route-trust-boundary.test.d.ts.map

package/dist/__tests__/route-trust-boundary.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-trust-boundary.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/route-trust-boundary.test.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}