@intentius/chant 0.44.14 → 0.46.0

package/src/testing.test.ts

@@ -0,0 +1,261 @@
+import { describe, test, expect, beforeEach, afterEach, vi } from "vitest";
+import { mkdir, writeFile, rm } from "node:fs/promises";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { createMockPlugin } from "@intentius/chant-test-utils";
+import { deployStack, testEnvName, TeardownIncompleteError } from "./testing";
+import type { ActivityFn } from "./op/activity-registry";
+import type { TeardownExecution } from "./lexicon";
+
+/** A minimal deployable project: one declarable, mock lexicon, marker on. */
+async function writeProject(
+  dir: string,
+  config: Record<string, unknown> = {},
+): Promise<void> {
+  await mkdir(dir, { recursive: true });
+  await writeFile(
+    join(dir, "chant.config.json"),
+    JSON.stringify({
+      lexicons: ["mock"],
+      ownership: { stack: "harness-fixture" },
+      environments: ["dev", { name: "test-*", endpoint: "http://localhost:9999" }],
+      ...config,
+    }),
+  );
+  await writeFile(
+    join(dir, "app.infra.ts"),
+    `export const bucket = {
+  lexicon: "mock",
+  entityType: "Mock::Bucket",
+  [Symbol.for("chant.declarable")]: true,
+};
+`,
+  );
+}
+
+describe("testEnvName", () => {
+  test("prefixes test-, slugs the suite, appends a nonce", () => {
+    const name = testEnvName("My Fancy Suite!");
+    expect(name).toMatch(/^test-my-fancy-suite-[a-z0-9]{6}$/);
+  });
+
+  test("two calls never collide", () => {
+    expect(testEnvName("s")).not.toBe(testEnvName("s"));
+  });
+
+  test("an all-symbol suite still produces a legal name", () => {
+    expect(testEnvName("!!!")).toMatch(/^test-suite-[a-z0-9]{6}$/);
+  });
+});
+
+describe("deployStack", () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = join(tmpdir(), `chant-testing-fixture-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  });
+
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  const harness = (nativeApply: ActivityFn, overrides: Record<string, unknown> = {}) => ({
+    dir,
+    suite: "unit",
+    plugins: [createMockPlugin({ name: "mock" })],
+    activities: new Map([["nativeApply", nativeApply]]),
+    profiles: {},
+    applyTargets: { mock: "cloudformation" },
+    ...overrides,
+  });
+
+  test("deploy returns outputs, entities, and a nonce'd test env", async () => {
+    await writeProject(dir);
+    const nativeApply = vi.fn(async (_args: Record<string, unknown>) => ({ applied: 1, pruned: 0, notAttempted: 0 }));
+
+    const stack = await deployStack(harness(nativeApply));
+
+    expect(stack.env).toMatch(/^test-unit-[a-z0-9]{6}$/);
+    expect(stack.entities.has("bucket")).toBe(true);
+    const output = stack.outputs.get("mock");
+    expect(output).toBeDefined();
+    const primary = typeof output === "string" ? output : output!.primary;
+    expect(JSON.parse(primary).resources.bucket).toEqual({ type: "Mock::Bucket" });
+
+    // The apply was additive, targeted at this env, over the written output.
+    expect(nativeApply).toHaveBeenCalledTimes(1);
+    const args = nativeApply.mock.calls[0][0] as Record<string, unknown>;
+    expect(args.target).toBe("cloudformation");
+    expect(args.env).toBe(stack.env);
+    expect(args.deleteMode).toBe("never");
+    expect(JSON.parse(readFileSync(args.output as string, "utf-8")).resources.bucket).toBeDefined();
+  });
+
+  test("the declared test-* endpoint is applied during the deploy", async () => {
+    await writeProject(dir);
+    let seenDuringApply: string | undefined;
+    const nativeApply = vi.fn(async (_args: Record<string, unknown>) => {
+      seenDuringApply = process.env.MOCK_ENDPOINT_URL;
+      return { applied: 1, pruned: 0, notAttempted: 0 };
+    });
+    const plugin = createMockPlugin({
+      name: "mock",
+      emulator: {
+        spec: { name: "chant-mock", image: "mock:1", containerPort: 1, healthPath: "/health" },
+        env: (endpoint: string) => ({ MOCK_ENDPOINT_URL: endpoint }),
+      },
+    });
+
+    delete process.env.MOCK_ENDPOINT_URL;
+    await deployStack(harness(nativeApply, { plugins: [plugin] }));
+
+    expect(seenDuringApply).toBe("http://localhost:9999");
+    // Scoped to the run — nothing leaks into the suite's own process env.
+    expect(process.env.MOCK_ENDPOINT_URL).toBeUndefined();
+  });
+
+  test("an ambient endpoint var wins over the declared endpoint", async () => {
+    await writeProject(dir);
+    let seenDuringApply: string | undefined;
+    const nativeApply = vi.fn(async (_args: Record<string, unknown>) => {
+      seenDuringApply = process.env.MOCK_ENDPOINT_URL;
+      return { applied: 1, pruned: 0, notAttempted: 0 };
+    });
+    const plugin = createMockPlugin({
+      name: "mock",
+      emulator: {
+        spec: { name: "chant-mock", image: "mock:1", containerPort: 1, healthPath: "/health" },
+        env: (endpoint: string) => ({ MOCK_ENDPOINT_URL: endpoint }),
+      },
+    });
+
+    process.env.MOCK_ENDPOINT_URL = "http://ambient:1234";
+    try {
+      await deployStack(harness(nativeApply, { plugins: [plugin] }));
+    } finally {
+      delete process.env.MOCK_ENDPOINT_URL;
+    }
+    expect(seenDuringApply).toBe("http://ambient:1234");
+  });
+
+  test("destroy sweeps exactly the nonce'd env, marker-scoped", async () => {
+    await writeProject(dir);
+    const nativeApply = vi.fn(async (_args: Record<string, unknown>) => ({ applied: 1, pruned: 0, notAttempted: 0 }));
+    const teardownOwned = vi.fn(async (args: { environment: string; marker: { stack: string; env?: string } }) => ({
+      candidates: [
+        {
+          name: "bucket",
+          type: "Mock::Bucket",
+          marker: { stack: args.marker.stack, env: args.marker.env! },
+        },
+      ],
+    }));
+    const executeTeardown = vi.fn(
+      async (): Promise<TeardownExecution> => ({
+        outcomes: [{ name: "bucket", outcome: "deleted" }],
+      }),
+    );
+    const plugin = createMockPlugin({ name: "mock", teardownOwned, executeTeardown });
+
+    const stack = await deployStack(harness(nativeApply, { plugins: [plugin] }));
+    const report = await stack.destroy();
+
+    expect(teardownOwned).toHaveBeenCalledWith({
+      environment: stack.env,
+      marker: { stack: "harness-fixture", env: stack.env },
+    });
+    expect(report.environment).toBe(stack.env);
+    expect(report.stack).toBe("harness-fixture");
+    expect(report.outcomes).toEqual([
+      expect.objectContaining({ name: "bucket", outcome: "deleted" }),
+    ]);
+  });
+
+  test("teardown holes surface as a thrown TeardownIncompleteError", async () => {
+    await writeProject(dir);
+    const nativeApply = vi.fn(async (_args: Record<string, unknown>) => ({ applied: 1, pruned: 0, notAttempted: 0 }));
+    const teardownOwned = vi.fn(async () => ({
+      candidates: [],
+      holes: [{ name: "bucket", reason: "read-failed" as const, detail: "connection refused" }],
+    }));
+    const plugin = createMockPlugin({ name: "mock", teardownOwned, executeTeardown: async () => ({ outcomes: [] }) });
+
+    const stack = await deployStack(harness(nativeApply, { plugins: [plugin] }));
+    const err = await stack.destroy().then(
+      () => undefined,
+      (e: unknown) => e,
+    );
+
+    expect(err).toBeInstanceOf(TeardownIncompleteError);
+    expect((err as TeardownIncompleteError).message).toContain("hole");
+    expect((err as TeardownIncompleteError).report.plan.holes).toHaveLength(1);
+  });
+
+  test("a failed delete surfaces as a thrown TeardownIncompleteError", async () => {
+    await writeProject(dir);
+    const nativeApply = vi.fn(async (_args: Record<string, unknown>) => ({ applied: 1, pruned: 0, notAttempted: 0 }));
+    const teardownOwned = vi.fn(async (args: { marker: { stack: string; env?: string } }) => ({
+      candidates: [{ name: "bucket", type: "Mock::Bucket", marker: { stack: args.marker.stack, env: args.marker.env! } }],
+    }));
+    const executeTeardown = vi.fn(
+      async (): Promise<TeardownExecution> => ({
+        outcomes: [{ name: "bucket", outcome: "failed", detail: "still in use" }],
+      }),
+    );
+    const plugin = createMockPlugin({ name: "mock", teardownOwned, executeTeardown });
+
+    const stack = await deployStack(harness(nativeApply, { plugins: [plugin] }));
+    const err = await stack.destroy().then(
+      () => undefined,
+      (e: unknown) => e,
+    );
+
+    expect(err).toBeInstanceOf(TeardownIncompleteError);
+    expect((err as TeardownIncompleteError).message).toContain("still in use");
+  });
+
+  test("a failed apply rejects with the local executor's failure", async () => {
+    await writeProject(dir);
+    const nativeApply = vi.fn(async (_args: Record<string, unknown>) => {
+      throw new Error("emulator not reachable");
+    });
+
+    await expect(deployStack(harness(nativeApply, { profiles: { longInfra: { retry: { maximumAttempts: 1 } } } })))
+      .rejects.toThrow(/deploy-test-unit/);
+    expect(nativeApply).toHaveBeenCalled();
+  });
+
+  test("an environment the project does not declare is refused with the test-* hint", async () => {
+    await writeProject(dir, { environments: ["dev", "prod"] });
+    const nativeApply = vi.fn(async (_args: Record<string, unknown>) => ({ applied: 1, pruned: 0, notAttempted: 0 }));
+
+    await expect(deployStack(harness(nativeApply))).rejects.toThrow(/"test-\*" pattern/);
+    expect(nativeApply).not.toHaveBeenCalled();
+  });
+
+  test("an explicit env overrides the derived name", async () => {
+    await writeProject(dir);
+    const nativeApply = vi.fn(async (_args: Record<string, unknown>) => ({ applied: 1, pruned: 0, notAttempted: 0 }));
+
+    const stack = await deployStack(harness(nativeApply, { env: "test-pinned" }));
+
+    expect(stack.env).toBe("test-pinned");
+  });
+
+  test("a project without ownership.stack is refused before anything deploys", async () => {
+    await writeProject(dir, { ownership: undefined });
+    const nativeApply = vi.fn(async (_args: Record<string, unknown>) => ({ applied: 1, pruned: 0, notAttempted: 0 }));
+
+    await expect(deployStack(harness(nativeApply))).rejects.toThrow(/ownership\.stack/);
+    expect(nativeApply).not.toHaveBeenCalled();
+  });
+
+  test("a project whose outputs have no apply target is refused loudly", async () => {
+    await writeProject(dir);
+    const nativeApply = vi.fn(async (_args: Record<string, unknown>) => ({ applied: 1, pruned: 0, notAttempted: 0 }));
+
+    await expect(deployStack(harness(nativeApply, { applyTargets: {} }))).rejects.toThrow(/nothing to deploy/);
+    expect(nativeApply).not.toHaveBeenCalled();
+  });
+});

package/src/testing.ts

@@ -0,0 +1,338 @@
+/**
+ * `@intentius/chant/testing` (#1224) — the live-stack test harness.
+ *
+ * A vitest suite deploys a real instance of its project once, asserts against
+ * it, and tears it down — emulator-locally on a dev machine, real-cloud in CI,
+ * with the same suite text. One call composes machinery that already exists:
+ *
+ * - **build** — the same programmatic path `chant build` takes: config
+ *   resolution (`buildParams` + the ownership marker) mirrored from the CLI,
+ *   then `build()` over the project's own serializers.
+ * - **apply** — an additive `nativeApply` per built lexicon output, run
+ *   in-process through the local Op executor (`runOpLocally`). `deleteMode`
+ *   is `"never"`: a test deploy creates and updates, nothing else.
+ * - **destroy** — #1222's marker-scoped teardown (`executeTeardown`), called
+ *   in-process for exactly this suite's environment. Stateless by design:
+ *   a crashed suite's environment is recovered by calling destroy again (or
+ *   `chant lifecycle teardown <env> --yes`).
+ *
+ * ## Isolation
+ *
+ * Every deploy targets its own environment: `test-<suite>-<nonce>` by default
+ * ({@link testEnvName}), so parallel CI jobs never collide. The environment
+ * is the teardown key — everything the deploy stamps carries the ownership
+ * marker `{ stack, env }`, and `destroy()` selects on that identity and
+ * nothing else. A project that declares `environments` must legalize the
+ * dynamic names with a pattern entry (#1221):
+ *
+ * ```ts
+ * environments: ["dev", "prod", { name: "test-*", endpoint: "http://localhost:4566" }]
+ * ```
+ *
+ * ## Emulators
+ *
+ * The harness is emulator-aware the same way `--live` reads are (#1166): the
+ * target environment's declared `endpoint` is injected into each lexicon's
+ * ambient endpoint variable (`AWS_ENDPOINT_URL`, …) for the apply and the
+ * teardown — unless the variable is already set. Ambient always wins, so the
+ * env vars `chant emulator up --json` reports (#920) take precedence when
+ * exported, and a CI job pointing the identical suite at a real account just
+ * leaves both unset.
+ */
+
+import { basename, join, resolve } from "node:path";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { build } from "./build";
+import type { Declarable } from "./declarable";
+import type { SerializerResult } from "./serializer";
+import {
+  loadChantConfigUpward,
+  resolveOwnershipStack,
+  type ChantConfig,
+} from "./config";
+import { resolveBuildParams, type BuildParamValue } from "./build-params";
+import { ENV_VAR, unknownEnvError } from "./env";
+import { applyLiveEndpoint } from "./live-endpoint";
+import { loadPlugins, resolveProjectLexicons, collectBuildRootContributors } from "./cli/plugins";
+import type { LexiconPlugin } from "./lexicon";
+import type { OwnershipMarker } from "./ownership";
+import { runOpLocally } from "./op/local-executor";
+import { loadActivities, loadProfiles, type ActivityFn, type ActivityProfile } from "./op/activity-registry";
+import type { OpConfig, ActivityStep } from "./op/types";
+import { executeTeardown, type TeardownReport } from "./lifecycle/teardown";
+
+/**
+ * Which `nativeApply` target deploys each lexicon's built output. Only these
+ * lexicons have a native apply mechanism; an output from any other lexicon
+ * (helm values, a CI pipeline file, …) is returned to the caller but not
+ * applied — deploying it is not what a live-stack test means by "deploy".
+ */
+const APPLY_TARGETS: Record<string, string> = {
+  aws: "cloudformation",
+  k8s: "kubectl",
+  azure: "arm",
+  gcp: "gcp",
+  fly: "fly",
+};
+
+export interface DeployStackOptions {
+  /** The chant project directory (where the infra source lives). */
+  dir: string;
+  /**
+   * Explicit environment name. Overrides the default `test-<suite>-<nonce>`
+   * derivation — for a shared long-lived test environment, or a test that
+   * needs a deterministic name. Must be legal for the project's declared
+   * `environments`, exactly as `--env` would be.
+   */
+  env?: string;
+  /**
+   * Suite name folded into the default environment name. Defaults to the
+   * project directory's basename.
+   */
+  suite?: string;
+  /** Build parameters, exactly as `--param name=value` flags would supply them. */
+  params?: Record<string, BuildParamValue>;
+  /**
+   * Loaded lexicon plugins. Defaults to loading the project's own declared/
+   * detected lexicons — pass this only to substitute test doubles.
+   */
+  plugins?: LexiconPlugin[];
+  /** Activity implementations for the apply. Defaults to the real registry. */
+  activities?: Map<string, ActivityFn>;
+  /** Activity profiles (timeouts/retries). Defaults to the lexicon-declared table. */
+  profiles?: Record<string, ActivityProfile>;
+  /**
+   * Extra lexicon-name → `nativeApply` target entries, merged over the
+   * built-in map (aws → cloudformation, k8s → kubectl, azure → arm,
+   * gcp → gcp, fly → fly). A seam for tests and out-of-tree lexicons.
+   */
+  applyTargets?: Record<string, string>;
+}
+
+/** The handle a suite holds between `beforeAll` and `afterAll`. */
+export interface DeployedStack {
+  /** The built outputs, keyed by lexicon — what was deployed. */
+  outputs: Map<string, string | SerializerResult>;
+  /** The discovered entities, keyed by name. */
+  entities: Map<string, Declarable>;
+  /** The environment this deploy targeted — the teardown key. */
+  env: string;
+  /**
+   * Tear down everything carrying this suite's marker `{ stack, env }`.
+   * Throws {@link TeardownIncompleteError} when any candidate failed to
+   * delete or the plan had holes — an environment that cannot be called
+   * clean is a test failure, never a silent leak. Safe to call again:
+   * teardown is stateless, and a second call over a clean environment
+   * plans nothing.
+   */
+  destroy(): Promise<TeardownReport>;
+}
+
+/**
+ * Thrown by {@link DeployedStack.destroy} when the environment cannot be
+ * called clean: candidates still `failed` after the retry pass, or the plan
+ * had holes (#1089 — parts of the estate could not be read, so "nothing
+ * left" would be a claim about what was readable, not about the environment).
+ * Carries the full report for diagnosis.
+ */
+export class TeardownIncompleteError extends Error {
+  constructor(public readonly report: TeardownReport) {
+    const failed = report.outcomes.filter((o) => o.outcome === "failed");
+    const parts: string[] = [];
+    if (failed.length > 0) {
+      parts.push(
+        `${failed.length} candidate(s) failed to delete: ` +
+          failed.map((o) => `${o.lexicon}/${o.name}${o.detail ? ` (${o.detail})` : ""}`).join(", "),
+      );
+    }
+    if (report.plan.holes.length > 0) {
+      parts.push(
+        `${report.plan.holes.length} hole(s) — resources chant may own but could not read: ` +
+          report.plan.holes.map((h) => `${h.lexicon}/${h.name} (${h.reason})`).join(", "),
+      );
+    }
+    super(`teardown of "${report.environment}" is incomplete — ${parts.join("; ")}`);
+    this.name = "TeardownIncompleteError";
+  }
+}
+
+/**
+ * The default environment name for one suite run: `test-<suite>-<nonce>`.
+ * The `test-` prefix is what a project's `"test-*"` pattern entry (#1221)
+ * legalizes; the nonce keeps parallel CI jobs of the same suite apart.
+ */
+export function testEnvName(suite: string): string {
+  const slug =
+    suite
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "")
+      .slice(0, 24)
+      .replace(/-+$/, "") || "suite";
+  const nonce = Math.random().toString(36).slice(2, 8).padEnd(6, "0");
+  return `test-${slug}-${nonce}`;
+}
+
+/** JSON output starts with a brace/bracket; everything else is written as YAML. */
+function outputExtension(content: string): string {
+  const head = content.trimStart();
+  return head.startsWith("{") || head.startsWith("[") ? ".json" : ".yaml";
+}
+
+/**
+ * Write each lexicon's built output to a scratch directory and return the
+ * primary file path per lexicon. Secondary files (a multi-file serializer
+ * result) land beside the primary under their own names.
+ */
+function writeOutputs(outputs: Map<string, string | SerializerResult>, env: string): Map<string, string> {
+  const dir = mkdtempSync(join(tmpdir(), `chant-testing-${env}-`));
+  const paths = new Map<string, string>();
+  for (const [lexicon, output] of outputs) {
+    const primary = typeof output === "string" ? output : output.primary;
+    const path = join(dir, `${lexicon}${outputExtension(primary)}`);
+    writeFileSync(path, primary);
+    if (typeof output !== "string" && output.files) {
+      for (const [name, content] of Object.entries(output.files)) {
+        writeFileSync(join(dir, basename(name)), content);
+      }
+    }
+    paths.set(lexicon, path);
+  }
+  return paths;
+}
+
+/**
+ * Deploy a live instance of the project in `dir` for one test suite.
+ *
+ * Build (the CLI's own config resolution: `buildParams`, ownership marker,
+ * build roots) + additive apply (one `nativeApply` per built output with a
+ * native mechanism, via the local Op executor). Returns the handle the suite
+ * holds: outputs, entities, the environment name, and `destroy`.
+ *
+ * The ownership marker stamped on every resource is `{ stack: ownership.stack,
+ * env: <this deploy's environment> }` — the marker env always follows the
+ * suite environment, whatever `ownership.env` in config says, because the
+ * marker is the only thing `destroy()` selects on. A project with no
+ * `ownership.stack` is refused up front: a deploy that stamps nothing is a
+ * deploy nothing can sweep.
+ *
+ * Failures are thrown, never returned: build errors, unresolved parameters,
+ * an illegal environment name, and a failed apply (the local executor's
+ * `OpRunFailure`) all reject the returned promise.
+ */
+export async function deployStack(options: DeployStackOptions): Promise<DeployedStack> {
+  const dir = resolve(options.dir);
+  const { config, configPath } = await loadChantConfigUpward(dir);
+
+  const env = options.env ?? testEnvName(options.suite ?? basename(dir));
+  const envError = unknownEnvError(env, config.environments);
+  if (envError) {
+    throw new Error(
+      `${envError} The harness derives per-run environment names — declare a "test-*" pattern entry ` +
+        `in chant.config.ts's environments to legalize them (#1221).`,
+    );
+  }
+
+  const stack = resolveOwnershipStack(config);
+  if (stack === undefined) {
+    throw new Error(
+      `${dir}: this project declares no ownership.stack — the harness's destroy() is marker-scoped ` +
+        `and would have nothing to select on. Set ownership: { stack: "<name>" } in chant.config.ts.`,
+    );
+  }
+  const marker: OwnershipMarker = { stack, env };
+
+  const plugins = options.plugins ?? (await loadPlugins(await resolveProjectLexicons(dir)));
+
+  // Build parameters, resolved as `chant build --param ...` resolves them.
+  // A project whose config maps `env` to a build parameter gets this deploy's
+  // environment automatically, unless the caller passed one explicitly.
+  const cli: Record<string, string> = {};
+  for (const [name, value] of Object.entries(options.params ?? {})) cli[name] = String(value);
+  if (config.buildParams && "env" in config.buildParams && !("env" in cli)) cli.env = env;
+  const resolution = resolveBuildParams(config.buildParams, { cli, env: process.env });
+  if (resolution.errors.length > 0) {
+    throw new Error(`${dir}: build parameters did not resolve —\n  ${resolution.errors.join("\n  ")}`);
+  }
+
+  const projectRoot = configPath ? resolve(configPath, "..") : dir;
+  const configRecord = config as unknown as Record<string, unknown>;
+
+  // Env-aware source branches on env() (#505) during discovery — scope the
+  // variable to the build and restore whatever the shell had.
+  const priorEnv = process.env[ENV_VAR];
+  let result;
+  try {
+    process.env[ENV_VAR] = env;
+    result = await build(dir, plugins.map((p) => p.serializer), undefined, {
+      ownership: marker,
+      config: configRecord,
+      lexicons: plugins.map((p) => p.name),
+      intrinsics: plugins.flatMap((p) => p.intrinsics?.() ?? []),
+      buildParams: resolution.provenance,
+      buildRoots: collectBuildRootContributors(plugins, configRecord, projectRoot),
+    });
+  } finally {
+    if (priorEnv === undefined) delete process.env[ENV_VAR];
+    else process.env[ENV_VAR] = priorEnv;
+  }
+  if (result.errors.length > 0) {
+    const messages = result.errors.map((e) => e.message);
+    throw new Error(`${dir}: build failed —\n  ${messages.join("\n  ")}`);
+  }
+
+  // One additive apply step per built output with a native mechanism.
+  const targets = { ...APPLY_TARGETS, ...options.applyTargets };
+  const paths = writeOutputs(result.outputs, env);
+  const steps: ActivityStep[] = [];
+  for (const [lexicon, path] of paths) {
+    const target = targets[lexicon];
+    if (!target) continue;
+    steps.push({
+      kind: "activity",
+      fn: "nativeApply",
+      args: { target, env, output: path, deleteMode: "never" },
+      profile: "longInfra",
+    });
+  }
+  if (steps.length === 0) {
+    throw new Error(
+      `${dir}: nothing to deploy — no built output has a native apply target ` +
+        `(built: ${[...result.outputs.keys()].join(", ") || "none"}; targets exist for: ${Object.keys(targets).join(", ")}).`,
+    );
+  }
+  const op: OpConfig = {
+    name: `deploy-${env}`,
+    overview: `test harness deploy of ${dir} into ${env}`,
+    phases: [{ name: "Deploy", steps }],
+  };
+
+  const activities = options.activities ?? (await loadActivities(plugins.map((p) => p.name)));
+  const profiles = options.profiles ?? (await loadProfiles());
+
+  // The environment's declared endpoint (#1166) applies to the deploy the way
+  // it applies to a --live read — and ambient always wins, so exported
+  // `chant emulator up --json` vars take precedence.
+  const applied = applyLiveEndpoint(config.environments, env, plugins);
+  try {
+    await runOpLocally(op, activities, profiles);
+  } finally {
+    applied.restore();
+  }
+
+  const destroy = async (): Promise<TeardownReport> => {
+    const endpointForTeardown = applyLiveEndpoint(config.environments, env, plugins);
+    let report: TeardownReport;
+    try {
+      report = await executeTeardown({ environment: env, stack, plugins });
+    } finally {
+      endpointForTeardown.restore();
+    }
+    const failed = report.outcomes.some((o) => o.outcome === "failed");
+    if (failed || report.plan.holes.length > 0) throw new TeardownIncompleteError(report);
+    return report;
+  };
+
+  return { outputs: result.outputs, entities: result.entities, env, destroy };
+}

package/src/yaml.test.ts

@@ -10,6 +10,21 @@ describe("emitYAML", () => {
     expect(emitYAML(undefined, 0)).toBe("null");
   });
 
+  test("an undefined object value drops the key, an explicit null keeps it (#1371)", () => {
+    // Matches `JSON.stringify`: `{ a: undefined }` is `{}`; an unset optional
+    // build parameter passed straight into a resource must not ship as
+    // `a: null`.
+    expect(emitYAML({ a: undefined, b: 1 }, 0)).toBe("\nb: 1");
+    expect(emitYAML({ a: null, b: 1 }, 0)).toBe("\na: null\nb: 1");
+    expect(emitYAML({ a: undefined }, 0)).toBe("{}");
+    expect(emitYAML({ spec: { baseImageArn: undefined, name: "x" } }, 0)).toBe("\nspec:\n  name: x");
+  });
+
+  test("an undefined inside an array-item object drops the key; a bare undefined element is null", () => {
+    expect(emitYAML([{ a: undefined, b: 1 }, { c: undefined, d: 2, e: 3 }], 0)).toBe("\n- b: 1\n- d: 2\n  e: 3");
+    expect(emitYAML([undefined, 1], 0)).toBe("\n- null\n- 1");
+  });
+
   test("booleans", () => {
     expect(emitYAML(true, 0)).toBe("true");
     expect(emitYAML(false, 0)).toBe("false");

package/src/yaml.ts

@@ -19,9 +19,26 @@
  *   with `\n` so the caller can append it after a key.
  * - Tagged values `{ tag, value }` emit `!tag [...]` or `!tag scalar`.
  */
+/**
+ * An object's entries minus those whose value is `undefined`. An `undefined`
+ * property is "not supplied" in TypeScript (a declared-but-unset optional
+ * build parameter, `{ x: cond ? v : undefined }`), which `JSON.stringify`
+ * already omits; the YAML emitter must agree, or the same source ships
+ * `key: null` under `-o out.yaml` and no key at all under `-o out.json`. An
+ * explicit `null` is a value and is kept (chant #1371).
+ */
+function definedEntries(obj: Record<string, unknown>): [string, unknown][] {
+  return Object.entries(obj).filter(([, val]) => val !== undefined);
+}
+
 export function emitYAML(value: unknown, indent: number): string {
   const prefix = "  ".repeat(indent);
 
+  // `undefined` only reaches here as a top-level value or an array element —
+  // an object entry whose value is `undefined` is dropped below, the same way
+  // `JSON.stringify` omits it. A bare `undefined` renders as `null` for the
+  // same reason `JSON.stringify([undefined])` is `[null]`: YAML has no way to
+  // say "absent" in a sequence slot.
   if (value === null || value === undefined) {
     return "null";
   }
@@ -74,7 +91,7 @@ export function emitYAML(value: unknown, indent: number): string {
     for (const item of value) {
       if (typeof item === "object" && item !== null && !Array.isArray(item)) {
         // Object items in arrays
-        const entries = Object.entries(item as Record<string, unknown>);
+        const entries = definedEntries(item as Record<string, unknown>);
         if (entries.length > 0) {
           const [firstKey, firstVal] = entries[0];
           const firstEmitted = emitYAML(firstVal, indent + 2);
@@ -111,7 +128,7 @@ export function emitYAML(value: unknown, indent: number): string {
       return `${obj.tag} ${emitYAML(obj.value, indent)}`;
     }
 
-    const entries = Object.entries(obj);
+    const entries = definedEntries(obj);
     if (entries.length === 0) return "{}";
     const lines: string[] = [];
     for (const [key, val] of entries) {