@specific.dev/spectest 0.113.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/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.113.0",
+  "version": "0.114.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

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 };
+  });
+}