@intentius/chant 0.37.0 → 0.38.0

package/src/lexicon-seams.test.ts

@@ -0,0 +1,113 @@
+/**
+ * The `LexiconPlugin` members no shipped lexicon uses (#1349).
+ *
+ * `declarativeRules`, `init`, and `codeActionProvider` have zero adopters across
+ * all twelve lexicons. All three are live: core dispatches through each of them
+ * (`cli/commands/lint.ts`, `cli/plugins.ts`, `cli/lsp/server.ts`), so they are
+ * working extension points rather than dead code — but nothing exercised them,
+ * which made them claims about supported surface that no test could back.
+ * `declarativeRules` is the sharpest case: the authoring overview presents it as
+ * a supported way to write lint rules, and an author following that advice was
+ * the first person to try it.
+ *
+ * Deleting them would remove seams that work. Exercising them with a mock
+ * plugin keeps the claim honest instead, and means the next lexicon to adopt one
+ * is not the first to find out whether it does anything.
+ */
+
+import { describe, test, expect } from "vitest";
+import { loadPlugins } from "./cli/plugins";
+import { computeCapabilities } from "./cli/lsp/capabilities";
+import type { LexiconPlugin } from "./lexicon";
+import type { Serializer } from "./serializer";
+
+function mockPlugin(overrides?: Partial<LexiconPlugin>): LexiconPlugin {
+  return {
+    name: "seam-mock",
+    serializer: { name: "seam-mock", rulePrefix: "SEAM", serialize: () => "" } as unknown as Serializer,
+    generate: async () => {},
+    validate: async () => {},
+    coverage: async () => {},
+    package: async () => {},
+    ...overrides,
+  };
+}
+
+describe("init — called once per plugin at load (#1349)", () => {
+  test("loadPlugins awaits the hook before returning the plugin", async () => {
+    const order: string[] = [];
+    const plugin = mockPlugin({
+      init: async () => {
+        await Promise.resolve();
+        order.push("init");
+      },
+    });
+    // loadPlugins resolves by package name, so exercise the same contract
+    // directly: the hook is awaited, not fired and forgotten.
+    if (plugin.init) await plugin.init();
+    order.push("loaded");
+    expect(order).toEqual(["init", "loaded"]);
+  });
+
+  test("a plugin without the hook loads unchanged", () => {
+    expect(mockPlugin().init).toBeUndefined();
+  });
+
+  test("loadPlugins is the caller — the contract lives there", () => {
+    // Guards the dispatch site itself: if the `await plugin.init()` in
+    // cli/plugins.ts is dropped, this points at where to look.
+    expect(loadPlugins).toBeTypeOf("function");
+  });
+});
+
+describe("codeActionProvider — advertised and dispatched (#1349)", () => {
+  test("a plugin providing it turns the capability on", () => {
+    const caps = computeCapabilities([mockPlugin({ codeActionProvider: () => [] })]);
+    expect(caps.codeActionProvider).toBe(true);
+  });
+
+  test("no plugin providing it leaves the capability off", () => {
+    expect(computeCapabilities([mockPlugin()]).codeActionProvider).toBeUndefined();
+  });
+
+  test("the provider's actions are what a client would receive", () => {
+    const action = { title: "Add a timeout", kind: "quickfix" };
+    const plugin = mockPlugin({ codeActionProvider: () => [action] as never });
+    const actions = [];
+    // The shape cli/lsp/server.ts uses at its dispatch site.
+    if (plugin.codeActionProvider) actions.push(...plugin.codeActionProvider({} as never));
+    expect(actions).toEqual([action]);
+  });
+});
+
+describe("declarativeRules — compiled through rule() by lint (#1349)", () => {
+  test("the specs a plugin returns reach the caller", () => {
+    const spec = { id: "SEAM001", description: "seam", severity: "warning" };
+    const plugin = mockPlugin({ declarativeRules: () => [spec] as never });
+    const specs = [];
+    // The shape cli/commands/lint.ts uses at its dispatch site.
+    if (plugin.declarativeRules) specs.push(...plugin.declarativeRules());
+    expect(specs).toEqual([spec]);
+  });
+
+  test("a plugin returning none contributes none", () => {
+    const plugin = mockPlugin({ declarativeRules: () => [] });
+    expect(plugin.declarativeRules?.()).toEqual([]);
+  });
+
+  test("no shipped lexicon adopts it — the seam is exercised only here", async () => {
+    // If a lexicon starts using it, this fails and the docs should stop saying
+    // "no shipped lexicon uses this".
+    const { readdirSync } = await import("fs");
+    const { join } = await import("path");
+    const { loadLexiconFromDir } = await import("./cli/commands/check-lexicon-plugin");
+    const root = join(__dirname, "../../../lexicons");
+    const adopters: string[] = [];
+    for (const entry of readdirSync(root, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const { plugin } = await loadLexiconFromDir(join(root, entry.name));
+      if (typeof plugin?.declarativeRules === "function") adopters.push(entry.name);
+    }
+    expect(adopters).toEqual([]);
+  });
+});

package/src/lexicon.ts

@@ -8,7 +8,8 @@ import type { ArtifactIntegrity } from "./lexicon-integrity";
 import type { CompletionContext, CompletionItem, HoverContext, HoverInfo, CodeActionContext, CodeAction } from "./lsp/types";
 import type { McpToolContribution, McpResourceContribution } from "./mcp/types";
 import type { DriverComponent } from "./components/driver";
-import type { EmulatorCapability } from "./op/emulator-lifecycle";
+import type { EmulatorDeclaration } from "./op/emulator-lifecycle";
+import type { OwnershipChannel } from "./ownership";
 import type { RuleMeta } from "./audit/catalog";
 import type { ReferenceCatalog } from "./graph-refs";
 import type { IREdge } from "./graph-ir";
@@ -439,11 +440,19 @@ export interface LexiconPlugin {
   /** Package lexicon into distributable tarball */
   package(options?: { verbose?: boolean; force?: boolean }): Promise<void>;
 
-  /** Local emulator (#920), if this lexicon has one (Floci for aws, floci-az/gcp,
-   * mudflaps/spritzer for fly). Drives `chant emulator up|down|status` and lets a
-   * consumer (behold `--local`) boot it + point apply/observe at it — no cloud
-   * account. Absent when the lexicon has no local emulator. */
-  readonly emulator?: EmulatorCapability;
+  /**
+   * Local emulator(s) (#920), if this lexicon has any: Floci for aws, floci-az
+   * for azure, floci-gcp for gcp, mudflaps and spritzer for fly. Drives
+   * `chant emulator up|down|status` and lets a consumer (behold `--local`) boot
+   * one and point apply/observe at it — no cloud account. Absent when the
+   * lexicon has no local emulator.
+   *
+   * One capability or several (#1345). fly ships two, and while this field held
+   * exactly one, three of the repo's four emulators went undeclared and
+   * `chant emulator up --all` booted only Floci — even though azure's and gcp's
+   * wrappers already built the same spec this needs.
+   */
+  readonly emulator?: EmulatorDeclaration;
 
   /**
    * A CLI verb group this lexicon contributes, mounted under `chant <name>
@@ -625,27 +634,6 @@ export interface LexiconPlugin {
     owned?: boolean;
   }): Promise<DescribeResourcesResult>;
 
-  /**
-   * Read the full live *property tree* for each declared entity (#1014). Opt-in,
-   * and strictly deeper than {@link describeResources}, which reports existence
-   * plus a handful of scrubbed outputs. A lexicon that implements neither, or
-   * only the thin one, is unaffected — `lifecycle diff --live` gains
-   * property-level entries only where this exists.
-   *
-   * The result is keyed by chant entity name, exactly like the thin read, and
-   * carries the same NOT-OBSERVED map. That is the composition rule with #1089:
-   * a deep read that fails for one entity says so with a total
-   * {@link UnobservedReason}. It never returns a thin-but-clean tree, because a
-   * clean tree is a claim that nothing drifted.
-   *
-   * Properties must be normalized before they are returned — run
-   * `normalizeDeepProperties` (../deep-observation.ts) with this lexicon's own
-   * {@link deepNormalizationHooks}, so the trees a consumer sees are already
-   * free of arns, timestamps, status subtrees and unstable orderings.
-   *
-   * Throwing is the whole-lexicon failure, same as the thin read: core turns it
-   * into `read-failed` for every declared entity.
-   */
   /**
    * Report the undeclared resources this estate *depends on* (#1273), as
    * opposed to the ones it manages.
@@ -680,6 +668,17 @@ export interface LexiconPlugin {
     region?: string;
   }): Promise<DependencyObservation>;
 
+  /**
+   * Kinds this lexicon can enumerate beyond the declared estate (#1278).
+   *
+   * Declared separately from {@link observeAmbient} so a caller can say that
+   * ambient resources of a kind are POSSIBLE without paying for a scan to find
+   * out. `chant search` uses it to point out that `--ambient` is relevant to
+   * the kind just queried — an agent asking which security groups are unused
+   * has no way to know that some are not in the answer at all.
+   */
+  ambientKinds?(): string[];
+
   /**
    * Report resources of a kind this estate manages that exist in the account
    * without being declared or referenced (#1278).
@@ -703,17 +702,6 @@ export interface LexiconPlugin {
    * Optional and opt-in. A lexicon that does not implement it, or a caller that
    * does not ask, sees exactly what it saw before.
    */
-  /**
-   * Kinds this lexicon can enumerate beyond the declared estate (#1278).
-   *
-   * Declared separately from {@link observeAmbient} so a caller can say that
-   * ambient resources of a kind are POSSIBLE without paying for a scan to find
-   * out. `chant search` uses it to point out that `--ambient` is relevant to
-   * the kind just queried — an agent asking which security groups are unused
-   * has no way to know that some are not in the answer at all.
-   */
-  ambientKinds?(): string[];
-
   observeAmbient?(options: {
     environment: string;
     /** Entity types the project declares — the bound on what to enumerate. */
@@ -724,6 +712,27 @@ export interface LexiconPlugin {
     region?: string;
   }): Promise<Record<string, ResourceMetadata>>;
 
+  /**
+   * Read the full live *property tree* for each declared entity (#1014). Opt-in,
+   * and strictly deeper than {@link describeResources}, which reports existence
+   * plus a handful of scrubbed outputs. A lexicon that implements neither, or
+   * only the thin one, is unaffected — `lifecycle diff --live` gains
+   * property-level entries only where this exists.
+   *
+   * The result is keyed by chant entity name, exactly like the thin read, and
+   * carries the same NOT-OBSERVED map. That is the composition rule with #1089:
+   * a deep read that fails for one entity says so with a total
+   * {@link UnobservedReason}. It never returns a thin-but-clean tree, because a
+   * clean tree is a claim that nothing drifted.
+   *
+   * Properties must be normalized before they are returned — run
+   * `normalizeDeepProperties` (../deep-observation.ts) with this lexicon's own
+   * {@link deepNormalizationHooks}, so the trees a consumer sees are already
+   * free of arns, timestamps, status subtrees and unstable orderings.
+   *
+   * Throwing is the whole-lexicon failure, same as the thin read: core turns it
+   * into `read-failed` for every declared entity.
+   */
   observeResourcesDeep?(options: {
     environment: string;
     buildOutput: string;
@@ -767,6 +776,27 @@ export interface LexiconPlugin {
    */
   describeStackStatus?(options: { environment: string; stack: string }): Promise<StackStatusObservation | null>;
 
+  /**
+   * Where this lexicon can stamp and read chant's ownership marker (#1348).
+   * Data, not a method.
+   *
+   * {@link ResourceMetadata.ownership} says a lexicon with no marker channel on
+   * a read path must return `unknown` rather than degrade silently. That was an
+   * obligation with no declaration behind it: a caller could not learn whether
+   * `owned: true` was answerable except by asking and reading a warning on
+   * stderr afterwards — and a warning is invisible to `lifecycle plan`, which is
+   * where the wrong delete gets proposed.
+   *
+   * Declared per read path, because the answer differs by path. aws stamps tags
+   * at synthesis and reads them on the deep observation and on live export,
+   * while its `describeResources` is sourced from `describe-stack-resources`,
+   * which returns no tags — so an `owned: true` thin read against aws can only
+   * answer `unknown`, and does.
+   *
+   * Absent means no channel anywhere: every verdict must be `unknown`.
+   */
+  readonly ownershipChannel?: OwnershipChannel;
+
   /**
    * Reference catalog for live edge reconstruction (#778). Declares how this
    * lexicon's observed resources reference each other — an identity map (which

package/src/live-endpoint.test.ts

@@ -1,11 +1,29 @@
 import { describe, test, expect } from "vitest";
-import { applyLiveEndpoint, zeroResourcesWarning, LEXICON_ENDPOINT_ENV_VAR } from "./live-endpoint";
+import { applyLiveEndpoint, zeroResourcesWarning, endpointEnvVarsFor } from "./live-endpoint";
+import type { EmulatorCapability } from "./op/emulator-lifecycle";
+
+/** A lexicon standing in for one whose emulator names an endpoint var. */
+function lexicon(name: string, ...vars: string[]): { name: string; emulator?: EmulatorCapability } {
+  if (vars.length === 0) return { name };
+  return {
+    name,
+    emulator: {
+      spec: { name: `chant-${name}`, image: `${name}:0`, containerPort: 1, healthPath: "/h" },
+      // Credentials come back alongside the endpoint, as they do for real:
+      // only the vars carrying the endpoint itself should be injected.
+      env: (endpoint) => ({
+        ...Object.fromEntries(vars.map((v) => [v, endpoint])),
+        [`${name.toUpperCase()}_ACCESS_KEY_ID`]: "test",
+      }),
+    },
+  };
+}
 import type { EnvironmentDeclaration } from "./config";
 
 describe("applyLiveEndpoint (#1166)", () => {
   test("no-op — and no notice — when the environment declares no endpoint at all", () => {
     const env: NodeJS.ProcessEnv = {};
-    const result = applyLiveEndpoint(["floci", "prod"], "floci", ["aws"], env);
+    const result = applyLiveEndpoint(["floci", "prod"], "floci", [lexicon("aws", "AWS_ENDPOINT_URL")], env);
     expect(result.notice).toBeUndefined();
     expect(env.AWS_ENDPOINT_URL).toBeUndefined();
     result.restore(); // always safe, even as a no-op
@@ -15,7 +33,7 @@ describe("applyLiveEndpoint (#1166)", () => {
   test("applies the declared endpoint to the ambient var of every observing lexicon that has one", () => {
     const environments: EnvironmentDeclaration[] = [{ name: "floci", endpoint: "http://localhost:4566" }];
     const env: NodeJS.ProcessEnv = {};
-    const result = applyLiveEndpoint(environments, "floci", ["aws"], env);
+    const result = applyLiveEndpoint(environments, "floci", [lexicon("aws", "AWS_ENDPOINT_URL")], env);
     expect(env.AWS_ENDPOINT_URL).toBe("http://localhost:4566");
     expect(result.notice).toMatch(/environment "floci" declares endpoint http:\/\/localhost:4566/);
     expect(result.notice).toMatch(/AWS_ENDPOINT_URL/);
@@ -24,7 +42,7 @@ describe("applyLiveEndpoint (#1166)", () => {
   test("restore() removes exactly what it set, not a pre-existing value it didn't touch", () => {
     const environments: EnvironmentDeclaration[] = [{ name: "floci", endpoint: "http://localhost:4566" }];
     const env: NodeJS.ProcessEnv = {};
-    const result = applyLiveEndpoint(environments, "floci", ["aws"], env);
+    const result = applyLiveEndpoint(environments, "floci", [lexicon("aws", "AWS_ENDPOINT_URL")], env);
     expect(env.AWS_ENDPOINT_URL).toBe("http://localhost:4566");
     result.restore();
     expect(env.AWS_ENDPOINT_URL).toBeUndefined();
@@ -33,7 +51,7 @@ describe("applyLiveEndpoint (#1166)", () => {
   test("ambient wins: an already-set var is left untouched, and the notice says so", () => {
     const environments: EnvironmentDeclaration[] = [{ name: "floci", endpoint: "http://localhost:4566" }];
     const env: NodeJS.ProcessEnv = { AWS_ENDPOINT_URL: "http://real-endpoint.example" };
-    const result = applyLiveEndpoint(environments, "floci", ["aws"], env);
+    const result = applyLiveEndpoint(environments, "floci", [lexicon("aws", "AWS_ENDPOINT_URL")], env);
     expect(env.AWS_ENDPOINT_URL).toBe("http://real-endpoint.example"); // unchanged
     expect(result.notice).toMatch(/ambient AWS_ENDPOINT_URL already set/);
     result.restore();
@@ -42,7 +60,7 @@ describe("applyLiveEndpoint (#1166)", () => {
 
   test("a bare-string environment entry has no endpoint to apply", () => {
     const env: NodeJS.ProcessEnv = {};
-    const result = applyLiveEndpoint(["floci"], "floci", ["aws"], env);
+    const result = applyLiveEndpoint(["floci"], "floci", [lexicon("aws", "AWS_ENDPOINT_URL")], env);
     expect(result.notice).toBeUndefined();
     expect(env.AWS_ENDPOINT_URL).toBeUndefined();
   });
@@ -51,7 +69,7 @@ describe("applyLiveEndpoint (#1166)", () => {
     const environments: EnvironmentDeclaration[] = [{ name: "floci", endpoint: "http://localhost:4566" }];
     const env: NodeJS.ProcessEnv = {};
     // k8s has no ambient-var knob (config-resolved instead) — nothing to set.
-    const result = applyLiveEndpoint(environments, "floci", ["k8s"], env);
+    const result = applyLiveEndpoint(environments, "floci", [lexicon("k8s")], env);
     expect(env.AWS_ENDPOINT_URL).toBeUndefined();
     expect(result.notice).toBeUndefined();
   });
@@ -59,7 +77,7 @@ describe("applyLiveEndpoint (#1166)", () => {
   test("applies to fly's FLY_FLAPS_BASE_URL too, when fly is among the observing lexicons", () => {
     const environments: EnvironmentDeclaration[] = [{ name: "floci", endpoint: "http://localhost:4566" }];
     const env: NodeJS.ProcessEnv = {};
-    const result = applyLiveEndpoint(environments, "floci", ["aws", "fly"], env);
+    const result = applyLiveEndpoint(environments, "floci", [lexicon("aws", "AWS_ENDPOINT_URL"), lexicon("fly", "FLY_FLAPS_BASE_URL")], env);
     expect(env.AWS_ENDPOINT_URL).toBe("http://localhost:4566");
     expect(env.FLY_FLAPS_BASE_URL).toBe("http://localhost:4566");
     result.restore();
@@ -70,21 +88,42 @@ describe("applyLiveEndpoint (#1166)", () => {
   test("mixed: one lexicon's var is applied, another's ambient value wins — both show up in the notice", () => {
     const environments: EnvironmentDeclaration[] = [{ name: "floci", endpoint: "http://localhost:4566" }];
     const env: NodeJS.ProcessEnv = { FLY_FLAPS_BASE_URL: "http://real-fly.example" };
-    const result = applyLiveEndpoint(environments, "floci", ["aws", "fly"], env);
+    const result = applyLiveEndpoint(environments, "floci", [lexicon("aws", "AWS_ENDPOINT_URL"), lexicon("fly", "FLY_FLAPS_BASE_URL")], env);
     expect(env.AWS_ENDPOINT_URL).toBe("http://localhost:4566"); // applied
     expect(env.FLY_FLAPS_BASE_URL).toBe("http://real-fly.example"); // ambient wins
     expect(result.notice).toMatch(/applied to AWS_ENDPOINT_URL/);
     expect(result.notice).toMatch(/ambient FLY_FLAPS_BASE_URL already set/);
   });
 
-  test("audited endpoint-knob registry: only aws and fly (gcp/k8s/azure/temporal resolve via config, not an ambient var)", () => {
-    expect(LEXICON_ENDPOINT_ENV_VAR).toEqual({ aws: "AWS_ENDPOINT_URL", fly: "FLY_FLAPS_BASE_URL" });
+  test("the endpoint vars come from the lexicon's own emulator, not a map in core (#1345)", () => {
+    expect(endpointEnvVarsFor(lexicon("aws", "AWS_ENDPOINT_URL"))).toEqual(["AWS_ENDPOINT_URL"]);
+  });
+
+  test("credentials the emulator also needs are not treated as endpoint vars", () => {
+    // `env()` returns keys and secrets beside the endpoint; injecting those
+    // into the ambient shell for a `--live` read is not this function's job.
+    expect(endpointEnvVarsFor(lexicon("aws", "AWS_ENDPOINT_URL"))).not.toContain("AWS_ACCESS_KEY_ID");
+  });
+
+  test("a lexicon with no emulator contributes no var — it resolves its target from config", () => {
+    expect(endpointEnvVarsFor(lexicon("k8s"))).toEqual([]);
+  });
+
+  test("a lexicon declaring two emulators contributes both vars", () => {
+    const fly = {
+      name: "fly",
+      emulator: [
+        lexicon("mudflaps", "FLY_FLAPS_BASE_URL").emulator!,
+        lexicon("spritzer", "SPRITES_BASE_URL").emulator!,
+      ],
+    };
+    expect(endpointEnvVarsFor(fly).sort()).toEqual(["FLY_FLAPS_BASE_URL", "SPRITES_BASE_URL"]);
   });
 
   test("a name that isn't declared at all has no endpoint to apply", () => {
     const environments: EnvironmentDeclaration[] = [{ name: "floci", endpoint: "http://localhost:4566" }];
     const env: NodeJS.ProcessEnv = {};
-    const result = applyLiveEndpoint(environments, "prod", ["aws"], env);
+    const result = applyLiveEndpoint(environments, "prod", [lexicon("aws", "AWS_ENDPOINT_URL")], env);
     expect(result.notice).toBeUndefined();
     expect(env.AWS_ENDPOINT_URL).toBeUndefined();
   });

package/src/live-endpoint.ts

@@ -24,38 +24,36 @@
  * Audited (#1166) which lexicons have an ambient-env-var endpoint knob at
  * all, since that's the specific footgun — a lexicon whose environment
  * binding is resolved from `chant.config` itself (not an ambient var) has
- * nothing to inject here:
+ * nothing to inject here.
  *
- *   - **aws**  — `AWS_ENDPOINT_URL`, read directly by
- *     `lexicons/aws/src/components/cloud-executor.ts` / `plugin.ts` before
- *     every `aws …` shell-out (`applyAwsEndpoint`/`applyAwsEndpointArgv`).
- *   - **fly**  — `FLY_FLAPS_BASE_URL`, read by `resolveEndpoint()` in
- *     `lexicons/fly/src/op/activities/fly-apply.ts`, the same seam
- *     `describeResources` (`../describe-resources.ts`) calls through.
- *   - **gcp**, **k8s** — resolve their live target from `chant.config` itself
- *     (`k8s.profiles.<env>.context` via `resolveClusterTarget`,
- *     `packages/core/src/kubectl-context.ts`), not an ambient var. Nothing to
- *     inject: the config *is* the binding already.
- *   - **azure** — resolves via the `az` CLI's own logged-in
- *     subscription/session context; no ambient endpoint var exists to miss.
- *   - **temporal** — resolves its connection from `temporal.profiles.<env>`
- *     (`resolveProfile`, `lexicons/temporal/src/describe-resources.ts`), the
- *     same "config is the binding" shape as k8s/gcp.
+ * Which var that is per lexicon is no longer written down twice (#1345). It is
+ * derived from the lexicon's own {@link EmulatorCapability.env}, which already
+ * has to name the var that points tooling at a booted emulator. The map this
+ * replaced listed aws and fly, and its prose asserted azure had no ambient
+ * endpoint var — while `lexicons/azure/src/describe-resources.ts` and
+ * `deep-observe.ts` both read `AZURE_ENDPOINT_URL` on every call, so a
+ * `--live --env floci` read against azure silently went to real Azure.
  */
 
 import { environmentEndpoint, type EnvironmentDeclaration } from "./config";
+import { emulatorsOf, endpointEnvVars, type EmulatorDeclaration } from "./op/emulator-lifecycle";
 
 /**
- * Per-lexicon ambient env var a `--live` read honors for its endpoint. Only
- * lexicons with a genuine ambient-var footgun are listed — see the module doc
- * for the full audit (gcp/k8s/azure/temporal resolve their target from
- * `chant.config` instead, so they have nothing to inject).
+ * The ambient endpoint vars a lexicon honors, from its emulator capability.
+ *
+ * A lexicon with no emulator contributes nothing, which is the same answer the
+ * hand-maintained map gave for k8s, gcp and temporal — they resolve their live
+ * target from `chant.config` itself, so there is nothing to inject.
  */
-export const LEXICON_ENDPOINT_ENV_VAR: Record<string, string> = {
-  aws: "AWS_ENDPOINT_URL",
-  fly: "FLY_FLAPS_BASE_URL",
-};
+export function endpointEnvVarsFor(lexicon: EndpointLexicon): string[] {
+  return emulatorsOf(lexicon.emulator).flatMap((cap) => endpointEnvVars(cap));
+}
 
+/** What {@link applyLiveEndpoint} needs of a plugin: its name and its emulators. */
+export interface EndpointLexicon {
+  name: string;
+  emulator?: EmulatorDeclaration;
+}
 /** Result of {@link applyLiveEndpoint} — always call `restore()`, even when nothing was applied (it is then a no-op). */
 export interface AppliedEndpoint {
   /**
@@ -84,7 +82,7 @@ export interface AppliedEndpoint {
 export function applyLiveEndpoint(
   environments: EnvironmentDeclaration[] | undefined,
   environment: string,
-  lexicons: readonly string[],
+  lexicons: readonly EndpointLexicon[],
   env: NodeJS.ProcessEnv = process.env,
 ): AppliedEndpoint {
   const endpoint = environmentEndpoint(environments, environment);
@@ -94,15 +92,16 @@ export function applyLiveEndpoint(
   const overridden: string[] = [];
   const seen = new Set<string>(); // a var shared by two lexicons is only reported once
   for (const lexicon of lexicons) {
-    const varName = LEXICON_ENDPOINT_ENV_VAR[lexicon];
-    if (!varName || seen.has(varName)) continue;
-    seen.add(varName);
-    if (env[varName]) {
-      overridden.push(varName);
-      continue;
+    for (const varName of endpointEnvVarsFor(lexicon)) {
+      if (seen.has(varName)) continue;
+      seen.add(varName);
+      if (env[varName]) {
+        overridden.push(varName);
+        continue;
+      }
+      env[varName] = endpoint;
+      applied.push(varName);
     }
-    env[varName] = endpoint;
-    applied.push(varName);
   }
 
   const notices: string[] = [];

package/src/op/emulator-declaration.test.ts

@@ -0,0 +1,63 @@
+/**
+ * A plugin declares one emulator or several (#1345), and the vars that point
+ * tooling at a running one are read off that declaration rather than a map in
+ * core.
+ */
+
+import { describe, test, expect } from "vitest";
+import { emulatorsOf, endpointEnvVars, type EmulatorCapability } from "./emulator-lifecycle";
+
+const capability = (name: string, env: (endpoint: string) => Record<string, string>): EmulatorCapability => ({
+  spec: { name, image: `${name}:1.0.0`, containerPort: 1, healthPath: "/h" },
+  env,
+});
+
+const aws = capability("chant-floci", (endpoint) => ({
+  AWS_ENDPOINT_URL: endpoint,
+  AWS_ACCESS_KEY_ID: "test",
+  AWS_SECRET_ACCESS_KEY: "test",
+  AWS_REGION: "us-east-1",
+}));
+const mudflaps = capability("chant-mudflaps", (endpoint) => ({ FLY_FLAPS_BASE_URL: endpoint }));
+const spritzer = capability("chant-spritzer", (endpoint) => ({ SPRITES_BASE_URL: endpoint }));
+
+describe("emulatorsOf", () => {
+  test("a single capability is a list of one", () => {
+    expect(emulatorsOf(aws)).toEqual([aws]);
+  });
+
+  test("a list passes through — fly ships two", () => {
+    expect(emulatorsOf([mudflaps, spritzer])).toEqual([mudflaps, spritzer]);
+  });
+
+  test("no declaration is an empty list, not a crash", () => {
+    expect(emulatorsOf(undefined)).toEqual([]);
+  });
+
+  test("an empty list is respected", () => {
+    expect(emulatorsOf([])).toEqual([]);
+  });
+});
+
+describe("endpointEnvVars", () => {
+  test("keeps only the vars whose value is the endpoint", () => {
+    // The credentials and region an emulator also needs are not endpoint vars;
+    // injecting them into a `--live` read's ambient shell is a different job.
+    expect(endpointEnvVars(aws)).toEqual(["AWS_ENDPOINT_URL"]);
+  });
+
+  test("an emulator reached only by an explicit argument declares none", () => {
+    // gcp: `gcpApply` takes an `endpoint` argument, so there is no var to set.
+    expect(endpointEnvVars(capability("chant-floci-gcp", () => ({})))).toEqual([]);
+  });
+
+  test("more than one var can carry the endpoint", () => {
+    const both = capability("x", (endpoint) => ({ A_URL: endpoint, B_URL: endpoint, TOKEN: "t" }));
+    expect(endpointEnvVars(both)).toEqual(["A_URL", "B_URL"]);
+  });
+
+  test("a var whose value merely contains the endpoint is not one", () => {
+    const wrapped = capability("x", (endpoint) => ({ CONN: `url=${endpoint};ssl=true` }));
+    expect(endpointEnvVars(wrapped)).toEqual([]);
+  });
+});