@specific.dev/spectest 0.112.0 → 0.114.0

package/README.md

@@ -20,6 +20,34 @@ Pub/Sub integrations are project-owned as of SDK 0.98.0. The former
 Use a local service definition or `serviceGroup()` wrapper; the repository’s
 `examples/google-pubsub` demonstrates this using public SDK APIs.
 
+## Interactive entrypoints (0.114.0)
+
+Choose the links shown in the interactive dashboard and PR preview comment:
+
+```ts
+const env = defineEnvironment({
+  name: "my-app",
+  services: { web, api },
+  interactive: {
+    instructions: "Sign in as demo@example.com and use 000000 as the code",
+    entrypoints: [
+      { name: "App", url: "https://app.test" },
+      { name: "Admin", url: "https://app.test/admin" },
+      { name: "API shell", terminal: "api" },
+    ],
+  },
+});
+```
+
+List order is preserved. URLs must match declared service hostnames and are
+translated to public preview URLs, retaining paths, queries and fragments.
+Terminal targets are typed service names and use dashboard member permissions.
+Entrypoints are display metadata; they do not change exposure or test execution.
+With no entries, the only preview link is **Open environment**. Optional
+`interactive.instructions` is a concise, direct plain-text sign-in description,
+shown in a collapsed **Instructions** section in the dashboard and PR
+comment. Blank instructions are omitted.
+
 
 ## Microphone fixtures and WebSocket fakes (0.103.0)
 

package/dist/daemon.js

@@ -43,6 +43,7 @@ import { isDesktopApp } from "./desktop.js";
 // each easy to restate subtly differently.
 import { buildArgFlags, buildContentKey as computeBuildContentKey, buildTargetFlags, imageTag, isGeneratedDockerignore, pickProjectIgnore, serviceDockerignore as composeServiceDockerignore, unionDockerignore, } from "./harness/build-context.js";
 import { startServices } from "./harness/service-graph.js";
+import { fakeFunctions, fakeFunctionParameters, callFakeFunction } from "./harness/fake-functions.js";
 import { dispatchFake } from "./harness/fake-websocket.js";
 import { casesMetadata as catalogueCases, groupsMetadata as catalogueGroups, } from "./harness/catalogue.js";
 import { summarizeBuildKit } from "./harness/buildkit-progress.js";
@@ -5286,6 +5287,21 @@ export function harnessMethods(state) {
         }),
         projectSetup: async () => exclusive(state, "inFlightProjectSetup", "project-setup already in progress", () => runProjectSetup()),
         interactiveSetup: async () => exclusive(state, "inFlightProjectSetup", "project-setup already in progress", () => runProjectSetup("setupInteractive")),
+        fakeFunctions: async (params) => exclusive(state, "inFlightTest", "a test or eval is already running", async () => {
+            const name = requireString(params, "fake");
+            const fake = FAKES.get(name);
+            if (!fake)
+                throw notFound(`Unknown fake: ${name}`);
+            await ensureFakeHelpers(name);
+            if (params.member === undefined)
+                return { functions: fakeFunctions(fake.helpers), parameters: fakeFunctionParameters(fake.helpers) };
+            const member = requireString(params, "member");
+            if (params.expressions !== undefined)
+                return callFakeFunction(fake.helpers, member, [], [], params.expressions);
+            if (!Array.isArray(params.args))
+                throw badRequest("args must be a JSON array");
+            return callFakeFunction(fake.helpers, member, params.args, params.omitted_args);
+        }),
         eval: async (params) => {
             const code = requireString(params, "code");
             return exclusive(state, "inFlightTest", "a test or eval is already running", () => {

package/dist/harness/fake-functions.d.ts

@@ -0,0 +1,18 @@
+/** Only own data properties are callable. Discovery never invokes getters. */
+export declare function fakeFunctions(helpers: Record<string, unknown>): string[];
+export declare function fakeFunctionParameters(helpers: Record<string, unknown>): {
+    [k: string]: import("./function-parameters.js").FunctionParameter[] | null;
+};
+/** Use the raw helpers: the test wrappers intentionally discard annotations
+ * when there is no recorder. Preserve both the value and its presentation. */
+export declare function callFakeFunction(helpers: Record<string, unknown>, member: string, args: unknown[], omittedArgs?: number[], expressions?: string[]): Promise<{
+    result: {} | null;
+    annotation: import("../annotate.js").RenderAnnotation | null;
+    error: null;
+    duration_ms: number;
+} | {
+    result: null;
+    annotation: null;
+    error: string;
+    duration_ms: number;
+}>;

package/dist/harness/fake-functions.js

@@ -0,0 +1,82 @@
+import { parse } from "acorn";
+import { functionParameters } from "./function-parameters.js";
+import { readAnnotation } from "../annotate.js";
+import { deepUnwrap } from "../inspect.js";
+import { safeSerialize } from "../recorder.js";
+import { runUninstrumented } from "./instrumentation-scope.js";
+/** Only own data properties are callable. Discovery never invokes getters. */
+export function fakeFunctions(helpers) {
+    return Object.getOwnPropertyNames(helpers).filter((name) => typeof Object.getOwnPropertyDescriptor(helpers, name)?.value === "function").sort();
+}
+export function fakeFunctionParameters(helpers) {
+    return Object.fromEntries(fakeFunctions(helpers).map(name => [name,
+        functionParameters(Object.getOwnPropertyDescriptor(helpers, name).value),
+    ]));
+}
+/** Use the raw helpers: the test wrappers intentionally discard annotations
+ * when there is no recorder. Preserve both the value and its presentation. */
+export async function callFakeFunction(helpers, member, args, omittedArgs = [], expressions) {
+    const fn = Object.getOwnPropertyDescriptor(helpers, member)?.value;
+    if (typeof fn !== "function")
+        throw new Error(`Unknown fake function: ${member}`);
+    if (!Array.isArray(omittedArgs) || omittedArgs.some(i => !Number.isInteger(i) || i < 0 || i >= args.length || args[i] !== null))
+        throw new Error("omitted_args must contain indices of null argument placeholders");
+    const omitted = new Set(omittedArgs);
+    const actualArgs = args.map((value, i) => omitted.has(i) ? undefined : value);
+    const start = Date.now();
+    try {
+        const value = await runUninstrumented(() => Reflect.apply(fn, helpers, expressions === undefined ? actualArgs : evaluateArguments(fn, expressions)));
+        const annotated = readAnnotation(value);
+        return {
+            result: safeSerialize(deepUnwrap(annotated ? annotated.value : value)) ?? null,
+            annotation: annotated?.annotation ?? null,
+            error: null,
+            duration_ms: Date.now() - start,
+        };
+    }
+    catch (error) {
+        return { result: null, annotation: null,
+            error: error instanceof Error ? error.message : String(error), duration_ms: Date.now() - start };
+    }
+}
+/** Expressions execute only in the environment, never in either dashboard.
+ * Compile every field before evaluating any, so a syntax error cannot partially
+ * execute the call. Keep actual JS values (undefined, Date, functions, etc.). */
+function evaluateArguments(fn, expressions) {
+    if (!Array.isArray(expressions) || expressions.some(source => typeof source !== "string"))
+        throw new Error("expressions must be an array of JavaScript expressions");
+    const parameters = functionParameters(fn);
+    const label = (index) => parameters?.[index]?.name ?? `Argument ${index + 1}`;
+    const withLabel = (index, action) => {
+        try {
+            return action();
+        }
+        catch (error) {
+            throw new Error(`${label(index)}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    };
+    const compiled = expressions.map((source, index) => withLabel(index, () => {
+        if (!source.trim())
+            return null;
+        const expression = `(${source}\n)`;
+        const program = parse(expression, { ecmaVersion: "latest" });
+        if (program.body.length !== 1 || program.body[0].type !== "ExpressionStatement")
+            throw new Error("Enter a single JavaScript expression.");
+        return new Function(`"use strict"; return ${expression};`);
+    }));
+    // Preserve interior omissions but avoid inventing trailing arguments.
+    while (compiled.length && compiled.at(-1) === null)
+        compiled.pop();
+    const args = [];
+    compiled.forEach((evaluate, index) => withLabel(index, () => {
+        const value = evaluate ? evaluate() : undefined;
+        if (parameters?.[index]?.rest) {
+            if (!Array.isArray(value))
+                throw new Error("Enter an array expression for the remaining arguments.");
+            args.push(...value);
+        }
+        else
+            args.push(value);
+    }));
+    return args;
+}

package/dist/harness/function-parameters.d.ts

@@ -0,0 +1,9 @@
+export interface FunctionParameter {
+    name: string;
+    has_default: boolean;
+    rest: boolean;
+    destructured: boolean;
+}
+/** Parse runtime JavaScript, never execute it (including default expressions).
+ * Null means opaque/unparseable, while [] means a known zero-argument helper. */
+export declare function functionParameters(fn: Function): FunctionParameter[] | null;

package/dist/harness/function-parameters.js

@@ -0,0 +1,42 @@
+import { parse } from "acorn";
+/** Parse runtime JavaScript, never execute it (including default expressions).
+ * Null means opaque/unparseable, while [] means a known zero-argument helper. */
+export function functionParameters(fn) {
+    const source = Function.prototype.toString.call(fn);
+    if (source.length > 256_000)
+        return null;
+    // Function/arrow expressions and object methods have different grammar.
+    for (const method of [false, true]) {
+        const text = method ? `({${source}})` : `(${source})`;
+        try {
+            const program = parse(text, { ecmaVersion: "latest", sourceType: "module" });
+            const statement = program.body[0];
+            if (statement?.type !== "ExpressionStatement")
+                continue;
+            let expression = statement.expression;
+            if (method) {
+                if (expression.type !== "ObjectExpression")
+                    continue;
+                const properties = expression.properties;
+                if (properties.length !== 1 || properties[0]?.type !== "Property")
+                    continue;
+                expression = properties[0].value;
+            }
+            if (expression.type !== "FunctionExpression" && expression.type !== "ArrowFunctionExpression")
+                continue;
+            return expression.params.map((parameter) => {
+                const rest = parameter.type === "RestElement";
+                let binding = rest ? parameter.argument : parameter;
+                const has_default = binding.type === "AssignmentPattern";
+                if (binding.type === "AssignmentPattern")
+                    binding = binding.left;
+                return {
+                    name: binding.type === "Identifier" ? binding.name : text.slice(binding.start, binding.end),
+                    has_default, rest, destructured: binding.type !== "Identifier",
+                };
+            });
+        }
+        catch { /* Native/bound functions and unsupported syntax stay opaque. */ }
+    }
+    return null;
+}

package/dist/harness/protocol.d.ts

@@ -23,7 +23,7 @@
 /** Protocol version this build speaks. Must match `PROTOCOL_VERSION` in protocol.rs. */
 export declare const PROTOCOL_VERSION = 1;
 /** Methods either side can send. */
-export type Method = "hello" | "load" | "loadTests" | "fingerprint" | "bootstrap" | "interactiveSetup" | "run" | "eval" | "setRecordSecrets" | "teardown" | "shutdown" | "createArtifact" | "completeArtifact" | "progress" | "step";
+export type Method = "hello" | "load" | "loadTests" | "fingerprint" | "bootstrap" | "interactiveSetup" | "run" | "fakeFunctions" | "eval" | "setRecordSecrets" | "teardown" | "shutdown" | "createArtifact" | "completeArtifact" | "progress" | "step";
 /** Methods this build knows how to dispatch. A method outside this set still
  *  *parses* — it is answered with an error, never dropped. */
 export declare const KNOWN_METHODS: ReadonlySet<string>;

package/dist/harness/protocol.js

@@ -32,6 +32,7 @@ export const KNOWN_METHODS = new Set([
     "bootstrap",
     "interactiveSetup",
     "run",
+    "fakeFunctions",
     "eval",
     "setRecordSecrets",
     "teardown",

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export type { Phone, PhoneOptions, CallOptions, SpeechOptions } from "./phone.js";
 import type { Phone, PhoneOptions } from "./phone.js";
 import type { Android, AndroidApp } from "./android.js";
+import { type InteractiveEntrypoint, type InteractiveEntrypoints } from "./interactive.js";
+export type { InteractiveEntrypoint, InteractiveEntrypoints } from "./interactive.js";
 export type { Android, AndroidApp, AndroidElement, AndroidRecordingOptions } from "./android.js";
 import { strict as nodeAssert } from "node:assert";
 export type { Carrier, Wrapped, WrappedObject, WrappedArray, WrappedHeaders, WrappedBuffer, WrappedBinaryView, WrappedBytes, WrappedBlob, WrappedFile, WrappedFormData, WrappedStream, WrappedReader, WrappedBYOBReader, WrappedReadResult, WrappedResponse, Provenanced, SpectestFetch, SpectestRequestInit, Unwrap, } from "./inspect.js";
@@ -69,6 +71,11 @@ export interface EnvironmentConfig<S extends ServicesMap = ServicesMap> {
     services: S;
     /** Sandbox timeout in seconds (default 1h). */
     timeoutSecs?: number;
+    /** Display metadata only; entrypoints retain their author-declared order. */
+    interactive?: {
+        entrypoints: InteractiveEntrypoint[];
+        instructions?: string;
+    };
 }
 /**
  * The shape that ends up in the JSON config the control plane and Rust
@@ -1717,6 +1724,15 @@ export interface EnvironmentInput<SI extends InputServicesMap, F extends FakesMa
     /** Services and/or service groups, keyed by name. See
      *  {@link EnvironmentConfig.services} and {@link ServiceGroup}. */
     services: SI;
+    /** Links highlighted in the dashboard and PR previews, in list order.
+     * URL entries target declared service hostnames; terminal entries name services. */
+    interactive?: {
+        entrypoints?: InteractiveEntrypoints<keyof NoInfer<ExpandServices<SI>> & string>;
+        /** Concise, direct plain-text sign-in instructions shown in the dashboard
+         * and a collapsed PR comment section. Example: "Sign in as demo@example.com
+         * and use 000000 as the code". */
+        instructions?: string;
+    };
     /** Sandbox timeout in seconds (default 1h). */
     timeoutSecs?: number;
     /** Fake servers — see {@link defineFake}. Keyed by stable name; the key

package/dist/index.js

@@ -1,3 +1,4 @@
+import { resolveEntrypoints } from "./interactive.js";
 // Spectest SDK. The user's single `spectest/index.ts` calls
 // `defineEnvironment({ name, services })` once, defines test cases via
 // the returned `env.test(...)`, and default-exports `env.project([...])`.
@@ -422,10 +423,9 @@ export function defineFake(opts) {
  * produces the file's default export.
  */
 export function defineEnvironment(input) {
-    // Split fakes off the wire config and expand service groups; only
-    // { name, services, timeoutSecs } — with plain, fully-expanded services —
-    // is stored as `config` and shipped to the control plane.
-    const { fakes, services: rawServices, ...rest } = input;
+    // Split fakes off the wire config, expand service groups, and validate
+    // interactive destinations against the final service names.
+    const { fakes, interactive, services: rawServices, ...rest } = input;
     const expanded = expandServiceGroups(rawServices);
     for (const [key, svc] of Object.entries(expanded)) {
         for (const build of svc.imageBuilds ?? [])
@@ -440,6 +440,15 @@ export function defineEnvironment(input) {
         services: expanded,
     };
     validateEnvironmentConfig(config);
+    if (interactive?.instructions !== undefined && typeof interactive.instructions !== "string") {
+        throw new Error("interactive.instructions must be a string");
+    }
+    if (interactive?.entrypoints !== undefined || interactive?.instructions !== undefined) {
+        config.interactive = {
+            entrypoints: interactive.entrypoints === undefined ? [] : resolveEntrypoints(interactive.entrypoints, config.services),
+            ...(interactive.instructions === undefined ? {} : { instructions: interactive.instructions }),
+        };
+    }
     if (fakes)
         validateFakes(config, fakes);
     // Every test created via this env's `.test(...)` is registered here. A

package/dist/interactive.d.ts

@@ -0,0 +1,18 @@
+/** One destination highlighted in interactive environments and PR previews. */
+export type InteractiveEntrypoint<Service extends string = string> = {
+    name: string;
+} & ({
+    url: string;
+    terminal?: never;
+} | {
+    terminal: Service;
+    url?: never;
+});
+/** Display order is exactly the order of this list. */
+export type InteractiveEntrypoints<Service extends string = string> = readonly InteractiveEntrypoint<Service>[];
+export declare function resolveEntrypoints(entries: InteractiveEntrypoints, services: Record<string, {
+    hostnames?: readonly string[];
+    tls?: readonly {
+        hostname: string;
+    }[];
+}>): InteractiveEntrypoint[];

package/dist/interactive.js

@@ -0,0 +1,39 @@
+export function resolveEntrypoints(entries, services) {
+    if (!Array.isArray(entries))
+        throw new Error("interactive.entrypoints must be a list");
+    const names = new Set();
+    return entries.map((entry, index) => {
+        const fail = (reason) => { throw new Error(`interactive.entrypoints[${index}]: ${reason}`); };
+        if (!entry || typeof entry.name !== "string" || !entry.name.trim())
+            fail("name must be a non-empty string");
+        const { name } = entry;
+        if (names.has(name))
+            fail(`duplicate name ${JSON.stringify(name)}`);
+        names.add(name);
+        if ((entry.url !== undefined) === (entry.terminal !== undefined))
+            fail("specify exactly one of url or terminal");
+        if (entry.terminal !== undefined) {
+            if (typeof entry.terminal !== "string" || !Object.hasOwn(services, entry.terminal)) {
+                fail("terminal must name a declared service");
+            }
+            return { name, terminal: entry.terminal };
+        }
+        if (typeof entry.url !== "string")
+            return fail("expected an absolute HTTP or HTTPS URL");
+        let url;
+        try {
+            url = new URL(entry.url);
+        }
+        catch {
+            return fail("expected an absolute HTTP or HTTPS URL");
+        }
+        if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.port) {
+            fail("use an HTTP or HTTPS service URL without credentials or a non-default port");
+        }
+        const declared = Object.values(services).some((service) => [...(service.hostnames ?? []), ...(service.tls ?? []).map((tls) => tls.hostname)]
+            .some((host) => !host.startsWith("*.") && host.toLowerCase() === url.hostname));
+        if (!declared)
+            fail(`hostname ${JSON.stringify(url.hostname)} is not a declared service endpoint`);
+        return { name, url: url.href };
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.112.0",
+  "version": "0.114.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",
@@ -55,6 +55,7 @@
   "dependencies": {
     "@kubernetes/client-node": "^1.0.0",
     "@xterm/headless": "^5.5.0",
+    "acorn": "8.18.0",
     "dns-packet": "^5.6.1",
     "playwright-core": "^1.61.1",
     "ws": "^8.20.1"

package/src/daemon.ts

@@ -93,6 +93,7 @@ import {
   unionDockerignore,
 } from "./harness/build-context.js";
 import { startServices } from "./harness/service-graph.js";
+import { fakeFunctions, fakeFunctionParameters, callFakeFunction } from "./harness/fake-functions.js";
 import { dispatchFake } from "./harness/fake-websocket.js";
 import {
   casesMetadata as catalogueCases,
@@ -6332,6 +6333,19 @@ export function harnessMethods(state: RouteState): MethodTable {
         () => runProjectSetup("setupInteractive"),
       ),
 
+    fakeFunctions: async (params) => exclusive(state, "inFlightTest", "a test or eval is already running", async () => {
+      const name = requireString(params, "fake");
+      const fake = FAKES.get(name);
+      if (!fake) throw notFound(`Unknown fake: ${name}`);
+      await ensureFakeHelpers(name);
+      if (params.member === undefined) return { functions: fakeFunctions(fake.helpers!), parameters: fakeFunctionParameters(fake.helpers!) };
+      const member = requireString(params, "member");
+      if (params.expressions !== undefined)
+        return callFakeFunction(fake.helpers!, member, [], [], params.expressions as string[]);
+      if (!Array.isArray(params.args)) throw badRequest("args must be a JSON array");
+      return callFakeFunction(fake.helpers!, member, params.args, params.omitted_args as number[] | undefined);
+    }),
+
     eval: async (params) => {
       const code = requireString(params, "code");
       return exclusive(state, "inFlightTest", "a test or eval is already running", () => {

package/src/fake-functions.test.ts

@@ -0,0 +1,62 @@
+import { expect, test } from "bun:test";
+import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+test("daemon dispatch discovers cached helpers, preserves annotations and excludes concurrent evals", async () => {
+  const root = await mkdtemp(join(tmpdir(), "spectest-fake-functions-"));
+  try {
+    await mkdir(join(root, "spectest"));
+    await writeFile(join(root, "spectest/index.ts"), `
+      import { defineEnvironment, defineFake, annotate } from ${JSON.stringify(new URL("./index.ts", import.meta.url).href)};
+      const env = defineEnvironment({ name: "helpers", services: {}, fakes: {
+        mail: defineFake({ name: "mail", hostnames: ["mail.test"], handler: () => new Response("ok"), helpers: () => {
+          let count = 0;
+          return {
+            receipt(amount) { count += amount; return annotate({ subject: "Receipt " + count }, "email"); },
+            async wait() { await globalThis.gate; return count; },
+          };
+        } }),
+      }});
+      export default env.project({});
+    `);
+    const script = `
+      import { strict as assert } from "node:assert";
+      import { METHODS } from ${JSON.stringify(new URL("./daemon.ts", import.meta.url).href)};
+      await METHODS.load({});
+      {
+        const discovery = await METHODS.fakeFunctions({fake:"mail"});
+        assert.deepEqual(discovery.functions, ["receipt", "wait"]);
+        assert.deepEqual(discovery.parameters.receipt, [{ name: "amount", has_default: false, rest: false, destructured: false }]);
+        assert.deepEqual(discovery.parameters.wait, []);
+      }
+      await assert.rejects(METHODS.fakeFunctions({fake:"missing"}), /Unknown fake/);
+      await assert.rejects(METHODS.fakeFunctions({fake:"mail", member:"receipt", args:{}}), /JSON array/);
+      for (const count of [1, 2]) {
+        const result = await METHODS.fakeFunctions({fake:"mail", member:"receipt", expressions:["2 - 1"]});
+        assert.equal(result.result.subject, "Receipt " + count);
+        assert.equal(result.annotation.kind, "email");
+        assert.equal(result.annotation.message.subject, result.result.subject);
+      }
+      let release;
+      globalThis.gate = new Promise(r => release = r);
+      const pending = METHODS.fakeFunctions({fake:"mail", member:"wait", expressions:[]});
+      await assert.rejects(METHODS.eval({code:"export default 1"}), /already running/);
+      await assert.rejects(METHODS.fakeFunctions({fake:"mail"}), /already running/);
+      release();
+      assert.equal((await pending).result, 2);
+      {
+        const discovery = await METHODS.fakeFunctions({fake:"mail"});
+        assert.deepEqual(discovery.functions, ["receipt", "wait"]);
+        assert.deepEqual(discovery.parameters.receipt, [{ name: "amount", has_default: false, rest: false, destructured: false }]);
+        assert.deepEqual(discovery.parameters.wait, []);
+      }
+      process.exit(0);
+    `;
+    const child = Bun.spawn([process.execPath, "--eval", script], {
+      env: { ...process.env, SPECTEST_APP_DIR: root }, stdout: "pipe", stderr: "pipe",
+    });
+    const [code, stdout, stderr] = await Promise.all([child.exited, new Response(child.stdout).text(), new Response(child.stderr).text()]);
+    expect(code, stdout + stderr).toBe(0);
+  } finally { await rm(root, { recursive: true, force: true }); }
+}, 20000);

package/src/harness/fake-functions.test.ts

@@ -0,0 +1,77 @@
+import { expect, test } from "bun:test";
+import { annotate } from "../annotate.js";
+import { fakeFunctions, callFakeFunction } from "./fake-functions.js";
+
+test("discovery includes only own data functions and never runs getters", async () => {
+  const helpers = Object.create({ inherited() { throw new Error("no"); } });
+  Object.defineProperties(helpers, {
+    getter: { get() { throw new Error("no"); } },
+    value: { value: 42 },
+    own: { value() {} },
+  });
+  expect(fakeFunctions(helpers)).toEqual(["own"]);
+  for (const name of ["getter", "inherited", "constructor", "toString", "missing", "value"])
+    await expect(callFakeFunction(helpers, name, [])).rejects.toThrow("Unknown fake function");
+});
+
+test("calls preserve receiver, arguments, live state, and async return values", async () => {
+  const helpers = { count: 0, async add(value: { amount: number }) { this.count += value.amount; return this.count; } };
+  expect((await callFakeFunction(helpers, "add", [{ amount: 3 }])).result).toBe(3);
+  expect((await callFakeFunction(helpers, "add", [{ amount: 2 }])).result).toBe(5);
+});
+
+test("email and chat annotations survive separately from the raw value", async () => {
+  const value = { subject: "Receipt", html: "<p>Paid</p>" };
+  const helpers = {
+    email: () => annotate(value, "email"),
+    chat: async () => annotate({ original: 1 }, "chat", [{ side: "other", text: "Hello" }]),
+    empty() {},
+    fail() { throw new Error("declined"); },
+    async reject() { throw new Error("offline"); },
+  };
+  const email = await callFakeFunction(helpers, "email", []);
+  expect(email.result).toEqual(value);
+  expect(email.annotation).toEqual({ kind: "email", message: value });
+  const chat = await callFakeFunction(helpers, "chat", []);
+  expect(chat.result).toEqual({ original: 1 });
+  expect(chat.annotation?.kind).toBe("chat");
+  expect((await callFakeFunction(helpers, "empty", [])).result).toBeNull();
+  expect((await callFakeFunction(helpers, "fail", [])).error).toBe("declined");
+  expect((await callFakeFunction(helpers, "reject", [])).error).toBe("offline");
+});
+
+test("evaluates JavaScript expressions with defaults, rest and non-JSON values", async () => {
+  const helpers = {
+    values(label = "default", ...items: unknown[]) { return [label, ...items]; },
+    inspect(date: Date, callback: (n: number) => number) { return [date.getUTCFullYear(), callback(4)]; },
+    count(...items: unknown[]) { return items.length; },
+  };
+  const call = (member: string, expressions: string[]) => callFakeFunction(helpers, member, [], [], expressions);
+  expect((await call("values", ["'123'", "[1 + 2, { ok: true }, null]"])).result).toEqual(["123", 3, { ok: true }, null]);
+  expect((await call("values", ["", "[false]"])).result).toEqual(["default", false]);
+  expect((await call("values", ["undefined", ""])).result).toEqual(["default"]);
+  expect((await call("inspect", ["new Date('2026-01-01')", "n => n * 2"])).result).toEqual([2026, 8]);
+  expect((await call("count", [""])).result).toBe(0);
+  expect((await call("values", ["'x'", "42"])).error).toContain("items: Enter an array expression");
+});
+
+test("rejects invalid expressions before evaluating fields or invoking a helper", async () => {
+  let calls = 0;
+  const helpers = { send(to: unknown, body: unknown) { calls++; return [to, body]; } };
+  const globals = globalThis as typeof globalThis & { expressionCalls?: number };
+  globals.expressionCalls = 0;
+  try {
+    const call = (expressions: string[]) => callFakeFunction(helpers, "send", [], [], expressions);
+    expect((await call(["++globalThis.expressionCalls", "{broken"])).error).toContain("body:");
+    expect(globals.expressionCalls).toBe(0);
+    expect((await call(["1); globalThis.expressionCalls++; (2", "''"])).error).toContain("to:");
+    expect((await call(["unquotedMissingName", "''"])).error).toContain("to:");
+    expect(calls).toBe(0);
+    await expect(callFakeFunction(helpers, "missing", [], [], ["++globalThis.expressionCalls"])).rejects.toThrow("Unknown fake function");
+    expect(globals.expressionCalls).toBe(0);
+    expect((await call(["++globalThis.expressionCalls", "'hello' // trailing comment"])).result).toEqual([1, "hello"]);
+    expect(globals.expressionCalls).toBe(1);
+    expect(calls).toBe(1);
+    expect((await callFakeFunction({ max: Math.max }, "max", [], [], ["1 + 2", "10"])).result).toBe(10);
+  } finally { delete globals.expressionCalls; }
+});

package/src/harness/fake-functions.ts

@@ -0,0 +1,78 @@
+import { parse } from "acorn";
+import { functionParameters } from "./function-parameters.js";
+import { readAnnotation } from "../annotate.js";
+import { deepUnwrap } from "../inspect.js";
+import { safeSerialize } from "../recorder.js";
+import { runUninstrumented } from "./instrumentation-scope.js";
+
+/** Only own data properties are callable. Discovery never invokes getters. */
+export function fakeFunctions(helpers: Record<string, unknown>): string[] {
+  return Object.getOwnPropertyNames(helpers).filter((name) =>
+    typeof Object.getOwnPropertyDescriptor(helpers, name)?.value === "function",
+  ).sort();
+}
+
+export function fakeFunctionParameters(helpers: Record<string, unknown>) {
+  return Object.fromEntries(fakeFunctions(helpers).map(name => [name,
+    functionParameters(Object.getOwnPropertyDescriptor(helpers, name)!.value),
+  ]));
+}
+
+/** Use the raw helpers: the test wrappers intentionally discard annotations
+ * when there is no recorder. Preserve both the value and its presentation. */
+export async function callFakeFunction(helpers: Record<string, unknown>, member: string, args: unknown[], omittedArgs: number[] = [], expressions?: string[]) {
+  const fn = Object.getOwnPropertyDescriptor(helpers, member)?.value;
+  if (typeof fn !== "function") throw new Error(`Unknown fake function: ${member}`);
+  if (!Array.isArray(omittedArgs) || omittedArgs.some(i => !Number.isInteger(i) || i < 0 || i >= args.length || args[i] !== null))
+    throw new Error("omitted_args must contain indices of null argument placeholders");
+  const omitted = new Set(omittedArgs);
+  const actualArgs = args.map((value, i) => omitted.has(i) ? undefined : value);
+  const start = Date.now();
+  try {
+    const value = await runUninstrumented(() => Reflect.apply(fn, helpers,
+      expressions === undefined ? actualArgs : evaluateArguments(fn, expressions)));
+    const annotated = readAnnotation(value);
+    return {
+      result: safeSerialize(deepUnwrap(annotated ? annotated.value : value)) ?? null,
+      annotation: annotated?.annotation ?? null,
+      error: null,
+      duration_ms: Date.now() - start,
+    };
+  } catch (error) {
+    return { result: null, annotation: null,
+      error: error instanceof Error ? error.message : String(error), duration_ms: Date.now() - start };
+  }
+}
+
+/** Expressions execute only in the environment, never in either dashboard.
+ * Compile every field before evaluating any, so a syntax error cannot partially
+ * execute the call. Keep actual JS values (undefined, Date, functions, etc.). */
+function evaluateArguments(fn: Function, expressions: string[]): unknown[] {
+  if (!Array.isArray(expressions) || expressions.some(source => typeof source !== "string"))
+    throw new Error("expressions must be an array of JavaScript expressions");
+  const parameters = functionParameters(fn);
+  const label = (index: number) => parameters?.[index]?.name ?? `Argument ${index + 1}`;
+  const withLabel = <T>(index: number, action: () => T): T => {
+    try { return action(); }
+    catch (error) { throw new Error(`${label(index)}: ${error instanceof Error ? error.message : String(error)}`); }
+  };
+  const compiled = expressions.map((source, index) => withLabel(index, () => {
+    if (!source.trim()) return null;
+    const expression = `(${source}\n)`;
+    const program = parse(expression, { ecmaVersion: "latest" });
+    if (program.body.length !== 1 || program.body[0].type !== "ExpressionStatement")
+      throw new Error("Enter a single JavaScript expression.");
+    return new Function(`"use strict"; return ${expression};`);
+  }));
+  // Preserve interior omissions but avoid inventing trailing arguments.
+  while (compiled.length && compiled.at(-1) === null) compiled.pop();
+  const args: unknown[] = [];
+  compiled.forEach((evaluate, index) => withLabel(index, () => {
+    const value = evaluate ? evaluate() : undefined;
+    if (parameters?.[index]?.rest) {
+      if (!Array.isArray(value)) throw new Error("Enter an array expression for the remaining arguments.");
+      args.push(...value);
+    } else args.push(value);
+  }));
+  return args;
+}

package/src/harness/function-parameters.test.ts

@@ -0,0 +1,45 @@
+import { expect, test } from "bun:test";
+import { functionParameters } from "./function-parameters.js";
+import { callFakeFunction, fakeFunctionParameters } from "./fake-functions.js";
+
+const p = (name: string, has_default = false, rest = false, destructured = false) => ({ name, has_default, rest, destructured });
+
+test("reads runtime names from methods, arrows, async and generator functions", () => {
+  const methods = { send(to: string, subject: string, text: string) {}, async load(id: number) {}, *items(limit = 3) {} };
+  expect(fakeFunctionParameters(methods)).toEqual({ send: [p("to"), p("subject"), p("text")], load: [p("id")], items: [p("limit", true)] });
+  expect(functionParameters(value => value)).toEqual([p("value")]);
+  expect(functionParameters(async value => value)).toEqual([p("value")]);
+  expect(functionParameters(function named(ångström: string) {})).toEqual([p("ångström")]);
+  expect(functionParameters(() => 42)).toEqual([]);
+});
+
+test("handles nested defaults, commas, comments and patterns without evaluating anything", () => {
+  let calls = 0;
+  const fn = (first = (++calls, /[,)]/), /* not,a,param */ second = (x = [1, 2]) => x,
+    third = `a,${[1, 2].join(",")}`, { to, subject: title } = { to: "a", subject: "b" }, [a, b] = [1, 2], ...rest: unknown[]) => {};
+  const result = functionParameters(fn)!;
+  expect(result.map(v => [v.has_default, v.rest, v.destructured])).toEqual([
+    [true, false, false], [true, false, false], [true, false, false], [true, false, true], [true, false, true], [false, true, false],
+  ]);
+  expect(result.slice(0, 3).map(v => v.name)).toEqual(["first", "second", "third"]);
+  expect(result[3].name).toContain("to");
+  expect(result[3].name).toContain("subject");
+  expect(result[4].name).toMatch(/^\[/);
+  expect(result[5].name).toBe("rest");
+  expect(calls).toBe(0);
+});
+
+test("opaque functions stay unknown and user-supplied toString is never called", () => {
+  const fn = (name: string) => name;
+  Object.defineProperty(fn, "toString", { get() { throw new Error("do not inspect"); } });
+  expect(functionParameters(fn)).toEqual([p("name")]);
+  expect(functionParameters(fn.bind(null))).toBeNull();
+  expect(functionParameters(Math.max)).toBeNull();
+});
+
+test("omitted slots trigger defaults while explicit null and later arguments are preserved", async () => {
+  const helpers = { send(to = "default", text: unknown, ...extra: unknown[]) { return [to, text, ...extra]; } };
+  expect((await callFakeFunction(helpers, "send", [null, "123", false, { ok: true }], [0])).result).toEqual(["default", "123", false, { ok: true }]);
+  expect((await callFakeFunction(helpers, "send", [null, "text"])).result).toEqual([null, "text"]);
+  for (const omitted of [[-1], [2], [0.5], [1]]) await expect(callFakeFunction(helpers, "send", [null, "text"], omitted)).rejects.toThrow("omitted_args");
+});

package/src/harness/function-parameters.ts

@@ -0,0 +1,43 @@
+import { parse, type Node, type Expression, type Pattern, type FunctionExpression, type ArrowFunctionExpression } from "acorn";
+
+export interface FunctionParameter {
+  name: string;
+  has_default: boolean;
+  rest: boolean;
+  destructured: boolean;
+}
+
+/** Parse runtime JavaScript, never execute it (including default expressions).
+ * Null means opaque/unparseable, while [] means a known zero-argument helper. */
+export function functionParameters(fn: Function): FunctionParameter[] | null {
+  const source = Function.prototype.toString.call(fn);
+  if (source.length > 256_000) return null;
+  // Function/arrow expressions and object methods have different grammar.
+  for (const method of [false, true]) {
+    const text = method ? `({${source}})` : `(${source})`;
+    try {
+      const program = parse(text, { ecmaVersion: "latest", sourceType: "module" });
+      const statement = program.body[0];
+      if (statement?.type !== "ExpressionStatement") continue;
+      let expression: Node = statement.expression;
+      if (method) {
+        if (expression.type !== "ObjectExpression") continue;
+        const properties = (expression as Extract<Expression, { type: "ObjectExpression" }>).properties;
+        if (properties.length !== 1 || properties[0]?.type !== "Property") continue;
+        expression = properties[0].value;
+      }
+      if (expression.type !== "FunctionExpression" && expression.type !== "ArrowFunctionExpression") continue;
+      return (expression as FunctionExpression | ArrowFunctionExpression).params.map((parameter) => {
+        const rest = parameter.type === "RestElement";
+        let binding: Pattern = rest ? parameter.argument : parameter;
+        const has_default = binding.type === "AssignmentPattern";
+        if (binding.type === "AssignmentPattern") binding = binding.left;
+        return {
+          name: binding.type === "Identifier" ? binding.name : text.slice(binding.start, binding.end),
+          has_default, rest, destructured: binding.type !== "Identifier",
+        };
+      });
+    } catch { /* Native/bound functions and unsupported syntax stay opaque. */ }
+  }
+  return null;
+}

package/src/harness/protocol.ts

@@ -34,6 +34,7 @@ export type Method =
   | "bootstrap"
   | "interactiveSetup"
   | "run"
+  | "fakeFunctions"
   | "eval"
   | "setRecordSecrets"
   | "teardown"
@@ -54,6 +55,7 @@ export const KNOWN_METHODS: ReadonlySet<string> = new Set<Method>([
   "bootstrap",
   "interactiveSetup",
   "run",
+  "fakeFunctions",
   "eval",
   "setRecordSecrets",
   "teardown",

package/src/index.ts

@@ -1,6 +1,8 @@
 export type { Phone, PhoneOptions, CallOptions, SpeechOptions } from "./phone.js";
 import type { Phone, PhoneOptions } from "./phone.js";
 import type { Android, AndroidApp } from "./android.js";
+import { resolveEntrypoints, type InteractiveEntrypoint, type InteractiveEntrypoints } from "./interactive.js";
+export type { InteractiveEntrypoint, InteractiveEntrypoints } from "./interactive.js";
 export type { Android, AndroidApp, AndroidElement, AndroidRecordingOptions } from "./android.js";
 // Spectest SDK. The user's single `spectest/index.ts` calls
 // `defineEnvironment({ name, services })` once, defines test cases via
@@ -245,6 +247,8 @@ export interface EnvironmentConfig<S extends ServicesMap = ServicesMap> {
   services: S;
   /** Sandbox timeout in seconds (default 1h). */
   timeoutSecs?: number;
+  /** Display metadata only; entrypoints retain their author-declared order. */
+  interactive?: { entrypoints: InteractiveEntrypoint[]; instructions?: string };
 }
 
 /**
@@ -2481,6 +2485,15 @@ export interface EnvironmentInput<
   /** Services and/or service groups, keyed by name. See
    *  {@link EnvironmentConfig.services} and {@link ServiceGroup}. */
   services: SI;
+  /** Links highlighted in the dashboard and PR previews, in list order.
+   * URL entries target declared service hostnames; terminal entries name services. */
+  interactive?: {
+    entrypoints?: InteractiveEntrypoints<keyof NoInfer<ExpandServices<SI>> & string>;
+    /** Concise, direct plain-text sign-in instructions shown in the dashboard
+     * and a collapsed PR comment section. Example: "Sign in as demo@example.com
+     * and use 000000 as the code". */
+    instructions?: string;
+  };
   /** Sandbox timeout in seconds (default 1h). */
   timeoutSecs?: number;
   /** Fake servers — see {@link defineFake}. Keyed by stable name; the key
@@ -2591,10 +2604,9 @@ export function defineEnvironment<
   F extends FakesMap = FakesMap,
 >(input: EnvironmentInput<SI, F>): DefinedEnvironment<ExpandServices<SI>, F> {
   type S = ExpandServices<SI>;
-  // Split fakes off the wire config and expand service groups; only
-  // { name, services, timeoutSecs } — with plain, fully-expanded services —
-  // is stored as `config` and shipped to the control plane.
-  const { fakes, services: rawServices, ...rest } = input;
+  // Split fakes off the wire config, expand service groups, and validate
+  // interactive destinations against the final service names.
+  const { fakes, interactive, services: rawServices, ...rest } = input;
   const expanded = expandServiceGroups(rawServices);
   for (const [key, svc] of Object.entries(expanded)) {
     for (const build of svc.imageBuilds ?? []) validateServiceImage(`${key} image ${build.reference}`, build.image);
@@ -2608,6 +2620,15 @@ export function defineEnvironment<
     services: expanded as S,
   };
   validateEnvironmentConfig(config);
+  if (interactive?.instructions !== undefined && typeof interactive.instructions !== "string") {
+    throw new Error("interactive.instructions must be a string");
+  }
+  if (interactive?.entrypoints !== undefined || interactive?.instructions !== undefined) {
+    config.interactive = {
+      entrypoints: interactive.entrypoints === undefined ? [] : resolveEntrypoints(interactive.entrypoints, config.services),
+      ...(interactive.instructions === undefined ? {} : { instructions: interactive.instructions }),
+    };
+  }
   if (fakes) validateFakes(config, fakes);
 
   // Every test created via this env's `.test(...)` is registered here. A

package/src/interactive-setup.test.ts

@@ -16,7 +16,10 @@ for (const withHook of [false, true]) {
       await writeFile(entry, `
         import { defineEnvironment } from ${JSON.stringify(new URL("./index.ts", import.meta.url).href)};
         export const calls = [];
-        const env = defineEnvironment({ name: "seed", services: {
+        const env = defineEnvironment({ name: "seed", interactive: {
+          entrypoints: [{ name: "App shell", terminal: "app" }],
+          instructions: "Sign in as demo@example.com and use 000000 as the code",
+        }, services: {
           app: { image: { type: "registry", reference: "busybox" },
             helpers: () => ({ label: "typed helper" }) },
         }});
@@ -43,7 +46,9 @@ for (const withHook of [false, true]) {
         import { METHODS } from ${JSON.stringify(new URL("./daemon.ts", import.meta.url).href)};
         import { calls } from ${JSON.stringify(entry)};
         const nativeFetch = globalThis.fetch;
-        await METHODS.load({});
+        const loaded = await METHODS.load({});
+        assert.deepEqual(loaded.environment.interactive.entrypoints, [{ name: "App shell", terminal: "app" }]);
+        assert.equal(loaded.environment.interactive.instructions, "Sign in as demo@example.com and use 000000 as the code");
         assert.equal((await METHODS.health({})).setupInteractive, ${withHook});
         await METHODS.projectSetup({});
         assert.deepEqual(calls, ["baseline"]);

package/src/interactive.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, test } from "bun:test";
+import { defineEnvironment, serviceGroup, type InteractiveEntrypoints } from "./index.js";
+
+const services = {
+  web: { image: { type: "registry" as const, reference: "nginx" }, tls: [{ hostname: "app.test", port: 80 }] },
+  api: { image: { type: "registry" as const, reference: "nginx" }, hostnames: ["api.test"] },
+};
+
+describe("interactive entrypoints", () => {
+  test("instructions survive serialization without any entrypoints", () => {
+    const instructions = "Sign in as demo@example.com and use 000000 as the code";
+    const env = defineEnvironment({ name: "app", services, interactive: { instructions } });
+    expect(JSON.parse(JSON.stringify(env.project().environment)).interactive).toEqual({ entrypoints: [], instructions });
+  });
+
+  test("instructions must be a string", () => {
+    const invalid = () => defineEnvironment({ name: "app", services, interactive: {
+      // @ts-expect-error instructions are plain text
+      instructions: 123,
+    } });
+    expect(invalid).toThrow("interactive.instructions must be a string");
+  });
+  test("keeps mixed destinations in list order on the project wire config", () => {
+    const env = defineEnvironment({ name: "app", services, interactive: { entrypoints: [
+      { name: "Website", url: "https://app.test/admin?tab=users#invite" },
+      { name: "2", terminal: "api" },
+      { name: "1", url: "http://api.test/docs" },
+    ] } });
+    const config = JSON.parse(JSON.stringify(env.project().environment));
+    expect(config.interactive.entrypoints).toEqual([
+      { name: "Website", url: "https://app.test/admin?tab=users#invite" },
+      { name: "2", terminal: "api" },
+      { name: "1", url: "http://api.test/docs" },
+    ]);
+    expect(env.project().tests).toBeUndefined();
+  });
+
+  test("omitting entrypoints leaves existing projects unchanged", () => {
+    expect(defineEnvironment({ name: "app", services }).config.interactive).toBeUndefined();
+  });
+
+  test("terminal destinations can name expanded service-group members", () => {
+    const stack = serviceGroup({ primary: "api", services: () => ({ api: services.api, worker: services.web }) });
+    const env = defineEnvironment({ name: "app", services: { stack }, interactive: {
+      entrypoints: [{ name: "Worker shell", terminal: "stack-worker" }],
+    } });
+    expect(env.config.interactive?.entrypoints).toEqual([{ name: "Worker shell", terminal: "stack-worker" }]);
+  });
+
+  test.each([null, { App: "https://app.test" }])("requires a list: %j", (entries) => {
+    expect(() => defineEnvironment({ name: "app", services, interactive: {
+      entrypoints: entries as unknown as InteractiveEntrypoints<"web" | "api">,
+    } })).toThrow("must be a list");
+  });
+
+  test("terminal service names are checked statically and at runtime", () => {
+    const invalid = () => defineEnvironment({ name: "app", services, interactive: { entrypoints: [
+      // @ts-expect-error terminal targets must be declared services
+      { name: "Shell", terminal: "missing" },
+    ] } });
+    expect(invalid).toThrow("terminal must name a declared service");
+  });
+
+  test.each([
+    [{ name: "App", url: "https://external.test" }],
+    [{ name: "App", url: "/relative" }],
+    [{ name: "App", url: "javascript:alert(1)" }],
+    [{ name: "App", url: "https://user:pass@app.test" }],
+    [{ name: "App", url: "https://app.test:8443" }],
+    [{ name: "App", url: "https://app.test", terminal: "web" }],
+    [{ name: "App" }],
+    [{ name: "", terminal: "web" }],
+    [{ name: "Same", terminal: "web" }, { name: "Same", terminal: "api" }],
+  ])("rejects invalid destinations %j", (...entries) => {
+    expect(() => defineEnvironment({ name: "app", services, interactive: {
+      entrypoints: entries as unknown as InteractiveEntrypoints<"web" | "api">,
+    } })).toThrow("interactive.entrypoints");
+  });
+});

package/src/interactive.ts

@@ -0,0 +1,41 @@
+/** One destination highlighted in interactive environments and PR previews. */
+export type InteractiveEntrypoint<Service extends string = string> = { name: string } & (
+  | { url: string; terminal?: never }
+  | { terminal: Service; url?: never }
+);
+
+/** Display order is exactly the order of this list. */
+export type InteractiveEntrypoints<Service extends string = string> = readonly InteractiveEntrypoint<Service>[];
+
+export function resolveEntrypoints(
+  entries: InteractiveEntrypoints,
+  services: Record<string, { hostnames?: readonly string[]; tls?: readonly { hostname: string }[] }>,
+): InteractiveEntrypoint[] {
+  if (!Array.isArray(entries)) throw new Error("interactive.entrypoints must be a list");
+  const names = new Set<string>();
+  return entries.map((entry, index) => {
+    const fail = (reason: string): never => { throw new Error(`interactive.entrypoints[${index}]: ${reason}`); };
+    if (!entry || typeof entry.name !== "string" || !entry.name.trim()) fail("name must be a non-empty string");
+    const { name } = entry;
+    if (names.has(name)) fail(`duplicate name ${JSON.stringify(name)}`);
+    names.add(name);
+    if ((entry.url !== undefined) === (entry.terminal !== undefined)) fail("specify exactly one of url or terminal");
+    if (entry.terminal !== undefined) {
+      if (typeof entry.terminal !== "string" || !Object.hasOwn(services, entry.terminal)) {
+        fail("terminal must name a declared service");
+      }
+      return { name, terminal: entry.terminal };
+    }
+    if (typeof entry.url !== "string") return fail("expected an absolute HTTP or HTTPS URL");
+    let url: URL;
+    try { url = new URL(entry.url); } catch { return fail("expected an absolute HTTP or HTTPS URL"); }
+    if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.port) {
+      fail("use an HTTP or HTTPS service URL without credentials or a non-default port");
+    }
+    const declared = Object.values(services).some((service) =>
+      [...(service.hostnames ?? []), ...(service.tls ?? []).map((tls) => tls.hostname)]
+        .some((host) => !host.startsWith("*.") && host.toLowerCase() === url.hostname));
+    if (!declared) fail(`hostname ${JSON.stringify(url.hostname)} is not a declared service endpoint`);
+    return { name, url: url.href };
+  });
+}