@tryaura/aura-testkit 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,144 @@
+# `@tryaura/aura-testkit`
+
+Deterministic fake machines for testing Aura plugins and distributions. A test describes a HOME, a
+workspace, and the executables on `PATH`; the testkit materializes them in a temporary directory,
+runs the real CLI against them in process, and hands back output that is stable enough to snapshot.
+
+Nothing in a seeded run reads the surrounding process — not the real home directory, not the real
+`PATH`, and not the ambient environment. A secret in `process.env` is not visible to a command the
+run spawns.
+
+## Seeding a machine
+
+```ts
+import { createSeedBuilder, runCheck } from "@tryaura/aura-testkit";
+
+it("reports a legacy config", async () => {
+  await using seed = await createSeedBuilder()
+    .homeFile(".fixture/config.txt", "legacy=true\n")
+    .workspaceFile("AGENTS.md", "workspace instructions\n")
+    .shim("fixture-agent", [{ args: ["--version"], stdout: "fixture-agent 1.2.3\n" }])
+    .build();
+
+  const result = await runCheck({ distro, seed });
+
+  expect(result.findings).toMatchInlineSnapshot();
+});
+```
+
+`await using` disposes the seed at the end of the block. `seed.cleanup()` does the same thing
+explicitly, and is safe to call more than once.
+
+Seeded paths are relative and must stay inside their root. The seed root is canonicalized, so a
+path a spawned tool resolves is the same string the seed reports.
+
+## Shims
+
+`shim(command, responses)` writes an executable onto the seeded `PATH`. Each response matches one
+shape of invocation exactly, including how many arguments there are. Use `ANY_ARGUMENT` for a
+position whose value a test cannot predict:
+
+```ts
+import { ANY_ARGUMENT, createSeedBuilder } from "@tryaura/aura-testkit";
+
+const seed = await createSeedBuilder()
+  .shim("fixture-agent", [
+    { args: ["--version"], stdout: "fixture-agent 1.2.3\n" },
+    { args: ["mcp", "add", ANY_ARGUMENT], stdout: "added\n" },
+    { args: ["status"], exitCode: 7, stderr: "not ready\n" },
+  ])
+  .build();
+```
+
+The first matching response wins, so declare overlapping ones from most to least specific. An
+invocation nothing matches exits `2` and reports itself on stderr.
+
+Every invocation is recorded, matched or not:
+
+```ts
+await expect(seed.invocations("fixture-agent")).resolves.toEqual([["--version"]]);
+```
+
+Versioned official-app fixtures are also exported for adapter and binary integration tests:
+
+```ts
+import { createClaudeCodeSeed, createCodexSeed, createCursorSeed } from "@tryaura/aura-testkit";
+
+await using seed = await createClaudeCodeSeed({
+  authenticated: true,
+  version: "2.1.233",
+});
+
+await using codexSeed = await createCodexSeed({
+  authenticated: true,
+  version: "0.147.0",
+});
+
+await using cursorSeed = await createCursorSeed({
+  rules: "legacy",
+  version: "3.11.0",
+});
+```
+
+## Running a check
+
+`runCheck` runs `check --json` and returns:
+
+- `report` — the whole JSON document. Assert against this rather than `findings` alone when a test
+  needs to prove a check ran: a check that threw reports no findings and is explained only by
+  `report.diagnostics`.
+- `findings` — shorthand for `report.findings`.
+- `exitCode` — `0`, `1`, or `2`.
+- `diffs` — every change under the fake HOME and workspace, as unified patches whose first line is
+  the entry's permission bits. Permission-only changes, empty directories, and binary files are all
+  visible. The seeded `PATH` directory is not diffed; use `seed.invocations` for what a shim did.
+- `stdout` / `stderr` — captured, with seeded absolute paths replaced by `<HOME>`, `<WORKSPACE>`,
+  `<PATH>`, and `<SEED>`.
+
+When a run produces no readable report, the failure carries the exit code and the CLI's own stderr,
+which is where the actual explanation lives.
+
+## Proving convergence
+
+`expectConvergedTwice` runs a setup or fix callback twice and asserts that the second run reports
+convergence, changes no captured path, and creates no undo-journal entry:
+
+```ts
+import { expectConvergedTwice, runSetup } from "@tryaura/aura-testkit";
+
+const { first, second } = await expectConvergedTwice(seed, () => runSetup({ distro, seed }));
+```
+
+Paths under `agents/.backups/` are excluded from the diff comparisons and asserted separately by
+journal entry name. Convergence is a claim about the machine's configuration, and the journal is
+where a run records what it replaced — it also holds a target-lock directory a run touches whether
+or not it writes anything, so comparing it byte for byte makes the assertion fail on timing.
+
+The helper is test-runner independent and returns both results for additional assertions.
+
+## Running a compiled distribution
+
+`runBinaryCheck` applies the same seed and returns the same result shape while launching a compiled
+Aura executable instead of calling `runCli` in process:
+
+```ts
+import { runBinaryCheck } from "@tryaura/aura-testkit";
+
+const result = await runBinaryCheck({
+  binaryPath: "/absolute/path/to/aura",
+  seed,
+});
+```
+
+The runner invokes `check --json` from the seeded workspace, supplies the seed's HOME and PATH, and
+passes no ambient environment variables to the child. The binary path must be absolute, and `args`
+may not repeat `--json`, `--home`, or `--path` — the runner supplies those and rejects a second one
+rather than letting it parse as a duplicate.
+
+Launch failures, signals, unsupported exit codes, and invalid reports reject with a captured
+transcript. So does a run that hangs: `timeoutMs` (30 seconds by default) bounds how long the child
+may take, after which it is killed and the failure carries whatever it had printed by then.
+
+```ts
+const result = await runBinaryCheck({ binaryPath, seed, timeoutMs: 5_000 });
+```

package/dist/index.d.ts

@@ -0,0 +1,306 @@
+import { CheckReport, CheckReport as CheckReport$1, CliDistro, CliExitCode, ReportFinding } from "@tryaura/aura-cli";
+import { Environment } from "@tryaura/aura-sdk";
+//#region src/types.d.ts
+/**
+ * Matches any single argument in that position.
+ *
+ * Arity still has to match, so a response stays an exact description of one shape of invocation —
+ * this only frees the positions whose value a test cannot predict, such as a temporary path.
+ */
+declare const ANY_ARGUMENT: unique symbol;
+/** One argument a shim matches on: an exact value, or {@link ANY_ARGUMENT}. */
+type ShimArgument = string | typeof ANY_ARGUMENT;
+/**
+ * One invocation a PATH shim knows how to answer.
+ *
+ * The first response whose arguments match wins, so order declarations from most to least specific
+ * when they overlap through {@link ANY_ARGUMENT}.
+ */
+interface ShimResponse {
+  readonly args: readonly ShimArgument[];
+  /** Defaults to zero. */
+  readonly exitCode?: number | undefined;
+  readonly stderr?: string | undefined;
+  readonly stdout?: string | undefined;
+}
+/** Materialized fake machine state owned by one test. */
+interface TestSeed {
+  readonly homeDir: string;
+  readonly pathDir: string;
+  readonly workspaceDir: string;
+  /** Removes the whole temporary seed. Safe to call more than once. */
+  readonly cleanup: () => Promise<void>;
+  /** Disposes through `await using`, which is the leak-proof way to own a seed. */
+  readonly [Symbol.asyncDispose]: () => Promise<void>;
+  /**
+   * Every invocation of one seeded shim, in the order it happened.
+   *
+   * Records invocations no response matched too, which is what turns "the shim answered `exit 2`"
+   * into "the adapter asked for arguments no response declares". Empty for a command that was never
+   * run, or was never seeded.
+   */
+  readonly invocations: (command: string) => Promise<readonly (readonly string[])[]>;
+}
+/** The directories a seed materialized, for file content that has to name one. */
+interface SeedRoots {
+  readonly homeDir: string;
+  readonly workspaceDir: string;
+}
+/**
+ * File content, or a function producing it from the directories the seed materialized.
+ *
+ * Those directories are temporary and only exist once `build` has run, so a fixture whose content
+ * has to contain one — a config keyed by workspace path, an absolute import — would otherwise have
+ * to write that file itself, outside the builder, and hand-roll the cleanup-on-failure and
+ * duplicate-path checks `build` already does.
+ */
+type SeedContent = string | ((roots: SeedRoots) => string);
+/** Fluent description of files and executables to materialize for a test. */
+interface TestSeedBuilder {
+  homeFile(path: string, content: SeedContent): TestSeedBuilder;
+  shim(command: string, responses: readonly ShimResponse[]): TestSeedBuilder;
+  workspaceFile(path: string, content: SeedContent): TestSeedBuilder;
+  build(): Promise<TestSeed>;
+}
+interface RunCheckOptions {
+  /** Check-command flags other than `--json`, which the runner always supplies. */
+  readonly args?: readonly string[] | undefined;
+  readonly distro: CliDistro;
+  readonly seed: TestSeed;
+}
+/** Options for running a compiled Aura distribution against a deterministic seed. */
+interface RunBinaryCheckOptions {
+  /** Check-command flags other than `--json`, `--home`, and `--path`, which the runner rejects. */
+  readonly args?: readonly string[] | undefined;
+  /** Absolute path to the compiled distribution executable. */
+  readonly binaryPath: string;
+  readonly seed: TestSeed;
+  /**
+   * How long the compiled run may take before it is killed. Defaults to 30 seconds.
+   *
+   * A run that outlives this fails with the output it had produced by then, which is the only thing
+   * that distinguishes a binary that hung from a test runner that gave up on it.
+   */
+  readonly timeoutMs?: number | undefined;
+}
+type TestFileDiffStatus = "added" | "modified" | "removed";
+/**
+ * One stable, snapshot-ready change under the fake HOME or workspace.
+ *
+ * The seeded PATH directory is deliberately not diffed: its shims would be permanent noise in every
+ * snapshot. Use {@link TestSeed.invocations} to assert on what a shim did instead.
+ */
+interface TestFileDiff {
+  /**
+   * Unified diff of the entry, whose first line is always its permission bits.
+   *
+   * Carrying the mode inside the patch is what makes a permission-only fix visible: without it a
+   * `chmod` that changes nothing else would diff as no change at all.
+   */
+  readonly patch: string;
+  readonly path: string;
+  readonly status: TestFileDiffStatus;
+}
+/** Captured result of running the distribution's check command in process. */
+interface TestRunResult {
+  readonly diffs: readonly TestFileDiff[];
+  readonly exitCode: CliExitCode;
+  /** Shorthand for `report.findings`. */
+  readonly findings: readonly ReportFinding[];
+  /**
+   * The whole `check --json` document.
+   *
+   * Assert against this rather than {@link TestRunResult.findings} alone when a test needs to prove
+   * a check actually ran: a check that threw reports no findings and is explained only by
+   * `report.diagnostics`.
+   */
+  readonly report: CheckReport$1;
+  readonly stderr: string;
+  readonly stdout: string;
+}
+//#endregion
+//#region src/binary-runner.d.ts
+/** Runs a compiled Aura distribution's `check --json` command against one deterministic seed. */
+declare function runBinaryCheck(options: RunBinaryCheckOptions): Promise<TestRunResult>;
+//#endregion
+//#region src/runner.d.ts
+/** Runs `check --json` without reading process state and returns snapshot-ready output. */
+declare function runCheck(options: RunCheckOptions): Promise<TestRunResult>;
+//#endregion
+//#region src/setup-runner.d.ts
+interface RunSetupOptions {
+  /** Setup-command flags other than `--yes`, which the runner always supplies. */
+  readonly args?: readonly string[] | undefined;
+  readonly distro: CliDistro;
+  /** Extra variables visible to the run, such as a skill-directory token. `PATH` stays seeded. */
+  readonly environmentVariables?: Readonly<Record<string, string>> | undefined;
+  readonly seed: TestSeed;
+}
+/** What one headless `setup --yes` run printed and changed. */
+interface SetupRunResult {
+  readonly diffs: readonly TestFileDiff[];
+  readonly exitCode: number;
+  readonly stderr: string;
+  readonly stdout: string;
+}
+/**
+ * Runs `setup --yes` in-process against a seed and returns snapshot-ready output.
+ *
+ * `--yes` because this boundary has no terminal: every question resolves to the default the wizard
+ * would have proposed, which is exactly what the acceptance tests need to prove about converge and
+ * end-on-green behaviour. Interactive keypress flows are covered by the CLI's own engine tests.
+ */
+declare function runSetup(options: RunSetupOptions): Promise<SetupRunResult>;
+//#endregion
+//#region src/convergence.d.ts
+/** The common result surface returned by the testkit's setup and check runners. */
+interface ConvergenceRunResult {
+  readonly diffs: readonly TestFileDiff[];
+  readonly exitCode: number;
+  readonly stderr: string;
+  readonly stdout: string;
+}
+interface ConvergedTwiceResult<Result extends ConvergenceRunResult> {
+  readonly first: Result;
+  readonly second: Result;
+}
+/**
+ * Runs one converge boundary twice and proves the second pass had no work to plan or journal.
+ *
+ * Throws framework-independent errors so distributions can use this helper from any test runner.
+ */
+declare function expectConvergedTwice<Result extends ConvergenceRunResult>(seed: TestSeed, run: () => Promise<Result>): Promise<ConvergedTwiceResult<Result>>;
+//#endregion
+//#region src/filesystem.d.ts
+interface DirectoryEntry {
+  readonly kind: "directory";
+  readonly mode: number;
+}
+interface FileEntry {
+  readonly kind: "file";
+  readonly mode: number;
+  readonly text: string;
+}
+/** A file whose bytes are not UTF-8 text, recorded by shape so a change is still visible. */
+interface BinaryEntry {
+  readonly byteLength: number;
+  readonly digest: string;
+  readonly kind: "binary";
+  readonly mode: number;
+}
+interface SymlinkEntry {
+  readonly kind: "symlink";
+  readonly target: string;
+}
+type TreeEntry = BinaryEntry | DirectoryEntry | FileEntry | SymlinkEntry;
+type FilesystemSnapshot = ReadonlyMap<string, TreeEntry>;
+declare function captureFilesystem(seed: TestSeed): Promise<FilesystemSnapshot>;
+//#endregion
+//#region src/seed.d.ts
+/** Starts a fluent description of one isolated fake machine. */
+declare function createSeedBuilder(): TestSeedBuilder;
+//#endregion
+//#region src/http.d.ts
+/**
+ * The network policy every testkit runner injects: loopback servers only.
+ *
+ * A test run is hermetic by construction — a distribution that registers a real skill directory
+ * must not make its integration tests reach that host. Mock servers listen on `127.0.0.1`, which
+ * this passes straight through to the kernel's own client, caps and all.
+ */
+declare const loopbackOnlyHttpGet: Environment["httpGet"];
+//#endregion
+//#region src/mock-directory.d.ts
+/** One listing a mock directory advertises in its `index.json`. */
+interface MockDirectoryListing {
+  readonly description: string;
+  readonly id: string;
+  readonly name: string;
+  readonly version: string;
+}
+/** One file of a mock skill's content response. */
+interface MockDirectoryFile {
+  readonly content: string;
+  readonly path: string;
+}
+/** One request the mock directory served, for asserting what a run sent — and did not send. */
+interface MockDirectoryRequest {
+  readonly authorization: string | undefined;
+  readonly method: string;
+  readonly path: string;
+}
+/** A running mock skill directory. Dispose it, or `close` it, when the test is done. */
+interface MockDirectory extends AsyncDisposable {
+  readonly close: () => Promise<void>;
+  readonly requests: readonly MockDirectoryRequest[];
+  /** Loopback base URL, ready to be used as a skill directory `url`. */
+  readonly url: string;
+}
+interface MockDirectoryBuilder {
+  /** Serves the listing plus a content response of exactly these files. */
+  readonly skill: (listing: MockDirectoryListing, files: readonly MockDirectoryFile[]) => MockDirectoryBuilder;
+  /** Appends a raw entry to a skill's `files` array — hostile paths, symlinks, junk. */
+  readonly rawFileEntry: (skillId: string, entry: unknown) => MockDirectoryBuilder;
+  /** Replaces a skill's content response with an oversized opaque payload. */
+  readonly payloadBytes: (skillId: string, bytes: number) => MockDirectoryBuilder;
+  /** Requires `Authorization: Bearer <token>` on every request; anything else gets 401. */
+  readonly requireToken: (token: string) => MockDirectoryBuilder;
+  readonly build: () => Promise<MockDirectory>;
+}
+/** A local `node:http` skill directory speaking the standard protocol, one call per scenario. */
+declare function createMockDirectoryBuilder(): MockDirectoryBuilder;
+//#endregion
+//#region src/fixtures/claude-code.d.ts
+/** One version inside the adapter's supported range and one past its ceiling. */
+type ClaudeCodeFixtureVersion = "2.1.233" | "3.0.0";
+interface ClaudeCodeSeedOptions {
+  readonly authenticated: boolean;
+  /** Whether the fixture includes literals used by credential-redaction tests. Defaults to true. */
+  readonly inlineSecrets?: boolean | undefined;
+  readonly version: ClaudeCodeFixtureVersion;
+}
+/** The `claude` executable's answers, for composing multi-app seeds on one builder. */
+declare function claudeCodeShimResponses(options: ClaudeCodeSeedOptions): readonly ShimResponse[];
+/** Builds documented Claude Code global and project configuration against an exact CLI version. */
+declare function createClaudeCodeSeed(options: ClaudeCodeSeedOptions): Promise<TestSeed>;
+//#endregion
+//#region src/fixtures/codex.d.ts
+/** Verified versions plus the first version outside the adapter's supported range. */
+type CodexFixtureVersion = "0.146.0" | "0.147.0" | "0.148.0";
+/**
+ * Which project instruction files the workspace ships.
+ *
+ * `"root"` seeds the repository-root `AGENTS.md` alone. `"nested"` adds a Git marker and a second
+ * `AGENTS.md` inside {@link CODEX_NESTED_PACKAGE}, so a scan invoked from that package walks the
+ * same two levels Codex does. `"override"` adds the root `AGENTS.override.md` that Codex prefers
+ * over the `AGENTS.md` beside it.
+ */
+type CodexProjectInstructions = "nested" | "override" | "root";
+/** Workspace-relative directory the `"nested"` layout puts its second `AGENTS.md` in. */
+declare const CODEX_NESTED_PACKAGE = "packages/app";
+interface CodexSeedOptions {
+  readonly authenticated: boolean;
+  /** Project instruction layout. Omitted means the workspace ships none. */
+  readonly projectInstructions?: CodexProjectInstructions | undefined;
+  /** Record the workspace under `[projects]` in `config.toml`; omitted means no entry at all. */
+  readonly projectTrust?: "trusted" | "untrusted" | undefined;
+  readonly version: CodexFixtureVersion;
+}
+/** The `codex` executable's answers, for composing multi-app seeds on one builder. */
+declare function codexShimResponses(options: Pick<CodexSeedOptions, "authenticated" | "version">): readonly ShimResponse[];
+/** Builds one documented Codex configuration against an exact CLI version. */
+declare function createCodexSeed(options: CodexSeedOptions): Promise<TestSeed>;
+//#endregion
+//#region src/fixtures/cursor.d.ts
+type CursorFixtureVersion = "3.11.0" | "4.0.0";
+type CursorRulesFixture = "current" | "legacy";
+interface CursorSeedOptions {
+  readonly rules: CursorRulesFixture;
+  readonly version: CursorFixtureVersion;
+}
+/** The `cursor` executable's answers, for composing multi-app seeds on one builder. */
+declare function cursorShimResponses(options: Pick<CursorSeedOptions, "version">): readonly ShimResponse[];
+/** Builds documented Cursor rule and MCP configuration against an exact editor version. */
+declare function createCursorSeed(options: CursorSeedOptions): Promise<TestSeed>;
+//#endregion
+export { ANY_ARGUMENT, CODEX_NESTED_PACKAGE, type CheckReport, type ClaudeCodeFixtureVersion, type ClaudeCodeSeedOptions, type CodexFixtureVersion, type CodexProjectInstructions, type CodexSeedOptions, type ConvergedTwiceResult, type ConvergenceRunResult, type CursorFixtureVersion, type CursorRulesFixture, type CursorSeedOptions, type FilesystemSnapshot, type MockDirectory, type MockDirectoryBuilder, type MockDirectoryFile, type MockDirectoryListing, type MockDirectoryRequest, type RunBinaryCheckOptions, type RunCheckOptions, type RunSetupOptions, type SetupRunResult, type ShimArgument, type ShimResponse, type TestFileDiff, type TestFileDiffStatus, type TestRunResult, type TestSeed, type TestSeedBuilder, captureFilesystem, claudeCodeShimResponses, codexShimResponses, createClaudeCodeSeed, createCodexSeed, createCursorSeed, createMockDirectoryBuilder, createSeedBuilder, cursorShimResponses, expectConvergedTwice, loopbackOnlyHttpGet, runBinaryCheck, runCheck, runSetup };