@specific.dev/spectest 0.31.0 → 0.32.0

package/dist/index.d.ts

@@ -168,58 +168,240 @@ export interface ServiceConfig {
     cgroupns?: string;
 }
 /**
- * The slice of the in-VM world a component's `setup` / `helpers` hooks can
- * reach — beyond what the service definition itself declares. Handed to
- * both hooks (see {@link ServiceSetupContext} / {@link ServiceHelpersContext})
- * so components stop hand-rolling `child_process` docker execs and stop
- * hard-coding control-plane paths like `/workspace`.
+ * Everything test-side code can reach inside the VM, in every
+ * context it runs in: a test body, `spectest env eval`, a project-level
+ * `setup`, and a component's service-level `setup` / `helpers` hooks.
+ *
+ * This is deliberately ONE type. The setup surfaces used to be two
+ * disjoint sets — a component hook could read project files but not mint
+ * a certificate; a project `setup` could mint a certificate but not read
+ * a project file — so bring-up logic got split across files by which
+ * context happened to carry which method. A component is now written
+ * against exactly the primitives an end user has in a test.
+ *
+ * The one member that differs by context is {@link exec}: in a test it
+ * returns a {@link Wrapped} result (its output carries provenance into
+ * the timeline), everywhere else a plain one. See {@link TestContext}.
+ *
+ * `svc` is scoped in a service-level hook: a service's `setup`/`helpers`
+ * can reach its own handle and those of its (transitive) `dependsOn`
+ * services — the ones the DAG guarantees are already up — and reading
+ * any other key throws with the dependency it's missing. Everywhere else
+ * (tests, eval, project `setup`) the whole map is live.
  */
-export interface ComponentContext {
+export interface SpectestContext<S extends ServicesMap = ServicesMap, F extends FakesMap = FakesMap> {
     /**
      * Absolute path of the extracted project root inside the VM — the
      * directory the user's repo lands in, with `spectest/` directly under
-     * it. Use this (never a hard-coded path) to locate project files a
-     * component consumes, e.g. `supabase/migrations/**`.
+     * it. Use this (never a hard-coded path, and never `import.meta.url` —
+     * that only reaches files under `spectest/`) to locate project files:
+     * a manifest set, `supabase/migrations/**`, a fixture.
      */
     projectRoot: string;
     /** Read a project file as UTF-8. Relative paths resolve against
      *  {@link projectRoot}; absolute paths are read as-is. */
     readProjectFile(path: string): Promise<string>;
     /**
-     * Run a command inside a service container (a raw `docker exec` — not
-     * recorded on any test timeline, result is plain, not
-     * provenance-wrapped). Pass an **array** for exact argv with no shell
-     * (`["psql", "-f", "-"]`), or a **string** to run via `sh -lc`.
-     * `opts.stdin` is piped to the process — the natural way to feed a SQL
-     * file to `psql -f -` or a manifest to `kubectl apply -f -`.
+     * Run a command inside a service container. Pass an **array** for exact
+     * argv with no shell (`["psql", "-f", "-"]`), or a **string** to run via
+     * `sh -lc`. `opts.stdin` is piped to the process — the natural way to
+     * feed a SQL file to `psql -f -` or a manifest to `kubectl apply -f -`.
      *
      * Never throws on non-zero exit — inspect `exitCode` yourself.
+     *
+     * In a test this is the instrumented variant (recorded on the timeline,
+     * result {@link Wrapped}); in `setup`/`helpers` there is no timeline, so
+     * the result is a plain {@link ExecResult}.
+     */
+    exec(service: string, command: string | string[], opts?: ExecOpts): Promise<ExecResult>;
+    /**
+     * Instrumented `fetch`. In a test each call is recorded on the timeline
+     * and resolves to a {@link WrappedResponse}: reads carry provenance so
+     * `expect(res.status)` / `expect(await res.json())` nest under the HTTP
+     * call. Because the status-line accessors are {@link Carrier}s, a raw
+     * `res.status === 200` is a *type error* — use `res.status.unwrap()` /
+     * `res.unwrap().status`, or assert via `expect`. Outside a test the
+     * result is wrapped the same way, just with no timeline to link to.
+     *
+     * (The plain global `fetch` is wrapped the same way at runtime but keeps
+     * the standard `Response` type, so prefer `ctx.fetch` for honestly-typed
+     * results.)
+     */
+    fetch: SpectestFetch;
+    /**
+     * Per-service helper namespaces, keyed by service name. Only services
+     * whose definition ships a `helpers` factory appear here; the value at
+     * `ctx.svc.<name>` is exactly the record that factory returned. For a
+     * `postgres(...)` service that ships `{ client }`, tests do
+     * `await ctx.svc.db.client\`SELECT 1\``.
+     *
+     * In a service-level `setup`/`helpers` hook only the service itself and
+     * its transitive `dependsOn` are reachable (see {@link SpectestContext}).
+     */
+    readonly svc: ServiceHandlesFor<S>;
+    /**
+     * Per-fake helper namespaces, keyed by fake name. Each is the record
+     * of functions the fake's `helpers` factory returned (or `{ state }`
+     * when it ships none — tests never touch a fake's private state
+     * directly). Those functions read/mutate the fake's state internally;
+     * the state itself is in-process and lives across the fork along with
+     * the rest of daemon memory, so calls in a child test see the fork's
+     * own copy as mutated by its ancestors. In a test every helper call is
+     * recorded as a step and its return value tracked, so assertions on it
+     * nest under the call in the timeline.
+     *
+     * Strongly typed against the project's fakes map when fakes are
+     * declared in `defineEnvironment({ ..., fakes })`: `ctx.fakes.stripe`
+     * is exactly the helpers record `defineFake`'s `helpers` factory
+     * returned — no cast. (Falls back to a loose record only when the
+     * environment declares no fakes.)
+     */
+    readonly fakes: FakeHandlesFor<F>;
+    /**
+     * Poll a predicate until it returns a truthy value, then return that
+     * value. In a test it records one `wait` event for the whole loop (with
+     * attempt count, total duration, and the description) instead of one
+     * event per probe — useful for "wait until pod Running"-style checks
+     * where the intermediate states are noise. In `setup` there's no
+     * timeline; it's just the loop you'd otherwise hand-roll.
+     *
+     * - `null`, `undefined`, or `false` from `fn` mean "not yet" — wait
+     *   `intervalMs` and try again.
+     * - Anything else is the success value and is returned, tagged with
+     *   the wait event's seq. Downstream `expect(...)` on it links to
+     *   the wait (one logical step), not to N suppressed HTTP calls.
+     * - Throws from `fn` propagate out immediately; the wait event is
+     *   still recorded (with `error` set) so the timeline reflects the
+     *   abort.
+     * - Defaults: `timeoutMs = 30_000`, `intervalMs = 1_000`.
+     *
+     * Side-effect calls inside `fn` (fetch, ctx.svc.* helpers, etc.)
+     * don't show up on the event log — the recorder is paused for the
+     * duration. Use `ctx.poll` for read-only observation, not for
+     * stateful work you want recorded.
+     */
+    poll<T>(description: string, fn: () => T | null | undefined | false | Promise<T | null | undefined | false>, opts?: {
+        timeoutMs?: number;
+        intervalMs?: number;
+    }): Promise<Wrapped<T>>;
+    /**
+     * Register a DNS name so the rest of this context (and anything
+     * downstream of it) can reach it. `{ ingress: true }` points the name at
+     * the daemon (a fake / TLS proxy); `{ service }` points it at a
+     * container's live IP; a `*.suffix` wildcard (e.g. `"*.example.com"`)
+     * routes a whole domain — the natural fit for k3s Ingress hosts.
+     *
+     * Answered by spectest-resolver, so it works for VM-host/test code,
+     * `ctx.browser()`, and peer containers (Docker forwards unknown names to
+     * the host resolver). It does NOT land in any container's `/etc/hosts`.
+     * The registration mutates in-daemon state, so from a test it's isolated
+     * to that test's fork (like fake state); from `setup` it's captured by
+     * the warm-template snapshot and every test inherits it.
+     *
+     * ```ts
+     * await ctx.svc.k8s.apply(ingressFor("foo.example.com"));
+     * await ctx.dnsName("foo.example.com", { service: "k8s" });
+     * const res = await ctx.fetch("http://foo.example.com");
+     * ```
+     */
+    dnsName(hostname: string, target: DnsTarget): Promise<void>;
+    /**
+     * Mint a leaf certificate from the in-VM root CA and return the PEMs.
+     *
+     * The value-returning counterpart to the `certificates` service field
+     * (see {@link ServiceConfig.certificates}): that one hands a
+     * certificate to a container before it boots, this one hands it to
+     * *you* — for loading into a Kubernetes `kubernetes.io/tls` Secret,
+     * posting to a control-plane API that provisions TLS endpoints, or
+     * driving a client-certificate handshake.
+     *
+     * The returned `ca` is the same root the whole environment already
+     * trusts (`ctx.fetch`, `ctx.browser()`, every service container), so a
+     * server configured with these PEMs verifies cleanly — no
+     * `rejectUnauthorized: false`, no `sslmode=require` downgrade.
+     * Wildcards (`*.example.com`) are allowed in `hostnames`.
+     *
+     * ```ts
+     * const { cert, key } = await ctx.certificate(["*.apps.test"]);
+     * await ctx.svc.k8s.apply(`
+     * apiVersion: v1
+     * kind: Secret
+     * metadata: { name: apps-tls, namespace: default }
+     * type: kubernetes.io/tls
+     * stringData:
+     *   tls.crt: |
+     * ${cert.replace(/^/gm, "    ")}
+     *   tls.key: |
+     * ${key.replace(/^/gm, "    ")}
+     * `);
+     * ```
+     */
+    certificate(hostnames: readonly string[]): Promise<CertificateMaterial>;
+    /**
+     * Start a real container on `spectest-net` at runtime — a peer machine
+     * with its own IP, reachable like any boot service. Returns once the
+     * container is up and its `readyCheck` (if any) has passed.
+     *
+     * Started from a test, the new container is part of that test's
+     * post-state snapshot, so a `dependsOn` child inherits it (same PID,
+     * same data) while siblings, which fork from the parent's earlier
+     * snapshot, never see it — the same isolation fake `state` and
+     * {@link dnsName} get. Started from `setup`, it's captured into the
+     * warm template and every test inherits it. Reach it by `name`
+     * (single-label, via the resolver) or by any `hostnames` you pass; map a
+     * multi-label name onto it with `ctx.dnsName(host, { service: name })`.
+     *
+     * The image is pulled on first use (fast through the host cache). See
+     * {@link RuntimeServiceSpec}.
+     *
+     * ```ts
+     * const { name } = await ctx.startService({
+     *   name: `db-${crypto.randomUUID().slice(0, 8)}`,
+     *   image: { type: "registry", reference: "postgres:16-alpine" },
+     *   env: { POSTGRES_PASSWORD: "secret" },
+     *   readyCheck: { type: "exec", command: "pg_isready -h 127.0.0.1 -p 5432" },
+     * });
+     * const sql = new Bun.SQL(`postgres://postgres:secret@${name}:5432/postgres`);
+     * ```
      */
-    exec(service: string, command: string | string[], opts?: ComponentExecOpts): Promise<ExecResult>;
+    startService(spec: RuntimeServiceSpec): Promise<RuntimeServiceHandle>;
+    /** Stop and remove a runtime service started via {@link startService}
+     *  (no-op if it's already gone). */
+    stopService(name: string): Promise<void>;
 }
 /**
- * Options for {@link ComponentContext.exec} — the same set
- * {@link TestContext.exec} takes, deliberately aliased rather than
- * redeclared: the two surfaces drifted once (the component one grew
- * `stdin`/`timeoutMs`, the test one silently ignored them), and an alias
- * makes that impossible to repeat.
+ * @deprecated Use {@link SpectestContext} — component hooks and test
+ * bodies now receive the same capabilities. Kept as an alias so existing
+ * component code keeps compiling.
+ */
+export type ComponentContext = SpectestContext;
+/**
+ * Options for {@link SpectestContext.exec} — one type for every context,
+ * deliberately aliased rather than redeclared: the surfaces drifted once
+ * (the component one grew `stdin`/`timeoutMs`, the test one silently
+ * ignored them), and an alias makes that impossible to repeat.
  *
- * The one behavioural difference is the `timeoutMs` default: a component
- * exec runs during boot, where nothing else bounds it, so it defaults to
- * 120 s. A test-context exec has no default — the enclosing test's own
- * timeout is the ceiling there.
+ * The one behavioural difference is the `timeoutMs` default: a
+ * service-level `setup`/`helpers` exec runs during boot, where nothing
+ * else bounds it, so it defaults to 120 s. Elsewhere there is no default —
+ * in a test the enclosing test's own timeout is the ceiling, and a
+ * project `setup` runs unbounded (it routinely waits on rollouts).
  */
 export type ComponentExecOpts = ExecOpts;
-/** What a service's `setup` hook receives. */
-export interface ServiceSetupContext<H extends Record<string, any> = Record<string, never>> extends ComponentContext {
+/** What a service's `setup` hook receives: the full
+ *  {@link SpectestContext} plus the service's own name and helpers. */
+export interface ServiceSetupContext<H extends Record<string, any> = Record<string, never>> extends SpectestContext {
     /** The service's key in the services map (container + DNS name). */
     name: string;
     /** The record the service's `helpers` factory returned (cached — setup
      *  and tests share one instance), or `{}` when it ships none. */
     helpers: H;
 }
-/** What a service's `helpers` factory receives. */
-export interface ServiceHelpersContext extends ComponentContext {
+/** What a service's `helpers` factory receives: the full
+ *  {@link SpectestContext} plus the service's own name. Note `ctx.svc`
+ *  here reaches the service's `dependsOn` only — never itself, since this
+ *  hook is what builds that handle. */
+export interface ServiceHelpersContext extends SpectestContext {
     /** The service's key in the services map (container + DNS name). */
     name: string;
 }
@@ -638,25 +820,13 @@ export type TestFn<T = void, P = undefined, S extends ServicesMap = ServicesMap,
  * `ctx.svc` only includes services with a `client` factory, each typed
  * as the factory's output (e.g. a Bun SQL pool for `postgres(...)`).
  */
-export interface TestContext<P = undefined, S extends ServicesMap = ServicesMap, F extends FakesMap = FakesMap> {
-    /**
-     * Instrumented `fetch`, exposed on `ctx`. Each call is recorded on the
-     * test timeline and resolves to a {@link WrappedResponse}: reads carry
-     * provenance so `expect(res.status)` / `expect(await res.json())` nest
-     * under the HTTP call. Because the status-line accessors are
-     * {@link Carrier}s, a raw `res.status === 200` is a *type error* — use
-     * `res.status.unwrap()` / `res.unwrap().status`, or assert via `expect`.
-     *
-     * (The plain global `fetch` is wrapped the same way at runtime but keeps
-     * the standard `Response` type, so prefer `ctx.fetch` for honestly-typed
-     * results.)
-     */
-    fetch: SpectestFetch;
-    /** Run `sh -lc <command>` inside a service container. The result is
-     *  {@link Wrapped}, so `res.stdout` is a `Carrier<string>` — assert via
-     *  `expect(res.stdout)` or recover the raw string with `res.stdout.unwrap()`.
-     *  (In `setup`/`eval` the result is wrapped too, just without a timeline
-     *  link, so `.unwrap()` works there the same way.)
+export interface TestContext<P = undefined, S extends ServicesMap = ServicesMap, F extends FakesMap = FakesMap> extends Omit<SpectestContext<S, F>, "exec"> {
+    /** Run a command inside a service container — a string via `sh -lc`,
+     *  or an array as exact argv. The result is {@link Wrapped}, so
+     *  `res.stdout` is a `Carrier<string>` — assert via `expect(res.stdout)`
+     *  or recover the raw string with `res.stdout.unwrap()`. (This is the
+     *  one place {@link SpectestContext.exec} differs: in `setup`/`helpers`
+     *  there's no timeline to link to, so the result is plain.)
      *
      *  The full run is also captured as an asciicast and replayed in the
      *  web UI — one recording per call, with output timestamped as it
@@ -671,7 +841,7 @@ export interface TestContext<P = undefined, S extends ServicesMap = ServicesMap,
      *  prefixing it with `cd <dir> && ` — the cwd is kept off the command
      *  string, so the timeline sidebar shows just the command and the
      *  directory surfaces in the detail view. */
-    exec(service: string, command: string, opts?: ExecOpts): Promise<Wrapped<ExecResult>>;
+    exec(service: string, command: string | string[], opts?: ExecOpts): Promise<Wrapped<ExecResult>>;
     /**
      * Run a command inside a service container under a PTY and record the
      * full terminal session as an asciicast for replay in the web UI.
@@ -755,140 +925,6 @@ export interface TestContext<P = undefined, S extends ServicesMap = ServicesMap,
      * the parent returned nothing.
      */
     readonly parent: P;
-    /**
-     * Per-service helper namespaces, keyed by service name. Only services
-     * whose definition ships a `helpers` factory appear here; the value at
-     * `ctx.svc.<name>` is exactly the record that factory returned. For a
-     * `postgres(...)` service that ships `{ client }`, tests do
-     * `await ctx.svc.db.client\`SELECT 1\``.
-     */
-    readonly svc: ServiceHandlesFor<S>;
-    /**
-     * Per-fake helper namespaces, keyed by fake name. Each is the record
-     * of functions the fake's `helpers` factory returned (or `{ state }`
-     * when it ships none — tests never touch a fake's private state
-     * directly). Those functions read/mutate the fake's state internally;
-     * the state itself is in-process and lives across the fork along with
-     * the rest of daemon memory, so calls in a child test see the fork's
-     * own copy as mutated by its ancestors. Every helper call is recorded
-     * as a step and its return value tracked, so assertions on it nest
-     * under the call in the timeline.
-     *
-     * Strongly typed against the project's fakes map when fakes are
-     * declared in `defineEnvironment({ ..., fakes })`: `ctx.fakes.stripe`
-     * is exactly the helpers record `defineFake`'s `helpers` factory
-     * returned — no cast. (Falls back to a loose record only when the
-     * environment declares no fakes.)
-     */
-    readonly fakes: FakeHandlesFor<F>;
-    /**
-     * Poll a predicate until it returns a truthy value, then return that
-     * value. Records one `wait` event for the whole loop (with attempt
-     * count, total duration, and the description) instead of one event
-     * per probe — useful for "wait until pod Running"-style checks where
-     * the intermediate states are noise.
-     *
-     * - `null`, `undefined`, or `false` from `fn` mean "not yet" — wait
-     *   `intervalMs` and try again.
-     * - Anything else is the success value and is returned, tagged with
-     *   the wait event's seq. Downstream `expect(...)` on it links to
-     *   the wait (one logical step), not to N suppressed HTTP calls.
-     * - Throws from `fn` propagate out immediately; the wait event is
-     *   still recorded (with `error` set) so the timeline reflects the
-     *   abort.
-     * - Defaults: `timeoutMs = 30_000`, `intervalMs = 1_000`.
-     *
-     * Side-effect calls inside `fn` (fetch, ctx.svc.* helpers, etc.)
-     * don't show up on the event log — the recorder is paused for the
-     * duration. Use `ctx.poll` for read-only observation, not for
-     * stateful work you want recorded.
-     */
-    poll<T>(description: string, fn: () => T | null | undefined | false | Promise<T | null | undefined | false>, opts?: {
-        timeoutMs?: number;
-        intervalMs?: number;
-    }): Promise<Wrapped<T>>;
-    /**
-     * Register a DNS name at runtime so the rest of this test (and anything
-     * downstream of it) can reach it. `{ ingress: true }` points the name at
-     * the daemon (a fake / TLS proxy); `{ service }` points it at a
-     * container's live IP; a `*.suffix` wildcard (e.g. `"*.example.com"`)
-     * routes a whole domain — the natural fit for k3s Ingress hosts a test
-     * applies on the fly.
-     *
-     * Answered by spectest-resolver, so it works for VM-host/test code,
-     * `ctx.browser()`, and peer containers (Docker forwards unknown names to
-     * the host resolver). It does NOT land in any container's `/etc/hosts`.
-     * The registration mutates in-daemon state, so it's isolated to this
-     * test's fork — like fake state.
-     *
-     * ```ts
-     * await ctx.svc.k8s.apply(ingressFor("foo.example.com"));
-     * await ctx.dnsName("foo.example.com", { service: "k8s" });
-     * const res = await ctx.fetch("http://foo.example.com");
-     * ```
-     */
-    dnsName(hostname: string, target: DnsTarget): Promise<void>;
-    /**
-     * Mint a leaf certificate from the in-VM root CA and return the PEMs.
-     *
-     * The value-returning counterpart to the `certificates` service field
-     * (see {@link ServiceConfig.certificates}): that one hands a
-     * certificate to a container before it boots, this one hands it to
-     * *you* — for loading into a Kubernetes `kubernetes.io/tls` Secret,
-     * posting to a control-plane API that provisions TLS endpoints, or
-     * driving a client-certificate handshake.
-     *
-     * The returned `ca` is the same root the whole environment already
-     * trusts (`ctx.fetch`, `ctx.browser()`, every service container), so a
-     * server configured with these PEMs verifies cleanly — no
-     * `rejectUnauthorized: false`, no `sslmode=require` downgrade.
-     * Wildcards (`*.example.com`) are allowed in `hostnames`.
-     *
-     * ```ts
-     * const { cert, key } = await ctx.certificate(["*.apps.test"]);
-     * await ctx.svc.k8s.apply(`
-     * apiVersion: v1
-     * kind: Secret
-     * metadata: { name: apps-tls, namespace: default }
-     * type: kubernetes.io/tls
-     * stringData:
-     *   tls.crt: |
-     * ${cert.replace(/^/gm, "    ")}
-     *   tls.key: |
-     * ${key.replace(/^/gm, "    ")}
-     * `);
-     * ```
-     */
-    certificate(hostnames: readonly string[]): Promise<CertificateMaterial>;
-    /**
-     * Start a real container on `spectest-net` at runtime — a peer machine
-     * with its own IP, reachable like any boot service. Returns once the
-     * container is up and its `readyCheck` (if any) has passed.
-     *
-     * The new container is part of this test's post-state snapshot, so a
-     * `dependsOn` child inherits it (same PID, same data) while siblings,
-     * which fork from the parent's earlier snapshot, never see it — the same
-     * isolation fake `state` and {@link dnsName} get. Reach it by `name`
-     * (single-label, via the resolver) or by any `hostnames` you pass; map a
-     * multi-label name onto it with `ctx.dnsName(host, { service: name })`.
-     *
-     * The image is pulled on first use (fast through the host cache). See
-     * {@link RuntimeServiceSpec}.
-     *
-     * ```ts
-     * const { name } = await ctx.startService({
-     *   name: `db-${crypto.randomUUID().slice(0, 8)}`,
-     *   image: { type: "registry", reference: "postgres:16-alpine" },
-     *   env: { POSTGRES_PASSWORD: "secret" },
-     *   readyCheck: { type: "exec", command: "pg_isready -h 127.0.0.1 -p 5432" },
-     * });
-     * const sql = new Bun.SQL(`postgres://postgres:secret@${name}:5432/postgres`);
-     * ```
-     */
-    startService(spec: RuntimeServiceSpec): Promise<RuntimeServiceHandle>;
-    /** Stop and remove a runtime service started via {@link startService}
-     *  (no-op if it's already gone). */
-    stopService(name: string): Promise<void>;
 }
 export interface ExecResult {
     stdout: string;
@@ -1103,42 +1139,16 @@ export interface Project<S extends ServicesMap = ServicesMap, F extends FakesMap
     tests?: TestSuite<S, F>;
 }
 /**
- * Slim context handed to the project-level `setup` hook. Same shape as
- * `TestContext` but pared down — no testName, no parent, no recording
- * surfaces (browser, terminal, poll). If you need polling inside setup,
- * write a plain loop: setup runs outside the test timeline so there's
- * nothing to record into.
+ * Context handed to the project-level `setup` hook: the full
+ * {@link SpectestContext}, minus only what a timeline gives a test
+ * (testName, parent, browser/mobile/terminal). Everything a test can do
+ * to the environment — exec, fetch, `svc`/`fakes` helpers, `poll`,
+ * `dnsName`, `certificate`, `startService`, and project-file access via
+ * `projectRoot`/`readProjectFile` — is available here too, and whatever it
+ * produces is captured into the warm-template snapshot, so every test
+ * inherits it without re-running.
  */
-export interface ProjectSetupContext<S extends ServicesMap = ServicesMap, F extends FakesMap = FakesMap> {
-    fetch: SpectestFetch;
-    exec(service: string, command: string, opts?: ExecOpts): Promise<Wrapped<ExecResult>>;
-    readonly svc: ServiceHandlesFor<S>;
-    /** Same surface tests see — fakes are already up by setup time. Typed
-     * against the declared fakes map (see {@link TestContext.fakes}). */
-    readonly fakes: FakeHandlesFor<F>;
-    /**
-     * Register a DNS name (see {@link TestContext.dnsName}). Useful here to
-     * wire a wildcard like `"*.example.com"` to a k3s cluster once, before
-     * any test runs — it's captured into the warm-template snapshot, so every
-     * test inherits the route without re-registering.
-     */
-    dnsName(hostname: string, target: DnsTarget): Promise<void>;
-    /**
-     * Mint a leaf certificate from the in-VM root CA (see
-     * {@link TestContext.certificate}). Minted here it's captured into the
-     * warm-template snapshot, so every test inherits whatever you seeded it
-     * into — the fit for a cluster-wide TLS Secret applied once at setup.
-     */
-    certificate(hostnames: readonly string[]): Promise<CertificateMaterial>;
-    /**
-     * Start a runtime service (see {@link TestContext.startService}). Started
-     * here, it's captured into the warm-template snapshot and inherited by
-     * every test — use it for backing instances that should exist before any
-     * test runs but aren't worth a boot-time `services` entry.
-     */
-    startService(spec: RuntimeServiceSpec): Promise<RuntimeServiceHandle>;
-    /** Stop a runtime service (see {@link TestContext.stopService}). */
-    stopService(name: string): Promise<void>;
+export interface ProjectSetupContext<S extends ServicesMap = ServicesMap, F extends FakesMap = FakesMap> extends SpectestContext<S, F> {
 }
 export type ProjectSetupFn<S extends ServicesMap = ServicesMap, F extends FakesMap = FakesMap> = (ctx: ProjectSetupContext<S, F>) => void | Promise<void>;
 /**
@@ -1240,6 +1250,30 @@ export interface DefinedEnvironment<S extends ServicesMap, F extends FakesMap =
  * matchers like `.toBe(...)` disappear.
  */
 export type Ctx<E> = E extends DefinedEnvironment<infer S, infer F> ? TestContext<unknown, S, F> : never;
+/**
+ * The `ctx` type a `setup` hook receives for an environment — the
+ * {@link Ctx} counterpart for bring-up code. Use it to type the deploy /
+ * seed helpers a project's `setup` calls, instead of hand-rolling a
+ * structural `{ exec, certificate }` interface:
+ *
+ * ```ts
+ * const env = defineEnvironment({ ... });
+ * export type AppSetupCtx = SetupCtx<typeof env>;
+ *
+ * async function deployPlatform(ctx: AppSetupCtx) {
+ *   const manifests = await ctx.readProjectFile("deploy/platform.yaml");
+ *   const { cert, key } = await ctx.certificate(["*.apps.test"]);
+ *   await ctx.svc.k8s.apply(manifests);
+ * }
+ * ```
+ *
+ * A service-level `setup`/`helpers` hook gets the same capabilities plus
+ * its own `name`/`helpers` — see {@link ServiceSetupContext}. Since
+ * {@link ProjectSetupContext} is a {@link SpectestContext}, a helper typed
+ * with `SetupCtx` also accepts a service `setup` ctx, so one function can
+ * serve both.
+ */
+export type SetupCtx<E> = E extends DefinedEnvironment<infer S, infer F> ? ProjectSetupContext<S, F> : never;
 /**
  * Define an environment and get back a builder you can hang tests off.
  * The builder's `.test(...)` returns test cases typed against the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",