@intentius/chant 0.22.0 → 0.24.0

package/src/cli/handlers/run.ts

@@ -2,12 +2,13 @@ import { resolve, join, dirname } from "node:path";
 import { existsSync, writeFileSync, mkdirSync, readFileSync } from "node:fs";
 import { createConnection } from "node:net";
 import { spawn as spawnChild, type ChildProcess } from "node:child_process";
-import { loadChantConfig, resolveAutoReleaseDisabled } from "../../config";
+import { loadChantConfig, resolveAutoReleaseDisabled, type ChantConfig } from "../../config";
 import { discoverOps } from "../../op/discover";
 import { loadActivities, loadProfiles } from "../../op/activity-registry";
 import { runOpLocally, findGate, LocalGateUnsupportedError, OpRunFailure } from "../../op/local-executor";
 import { renderHuman, renderJson } from "../../op/local-output";
 import { formatError, formatWarning, formatSuccess, formatBold, formatInfo } from "../format";
+import { resolveCliBuildParams, parseParamFlags } from "../build-params-cli";
 import type { CommandContext } from "../registry";
 import {
   loadTemporalClient,
@@ -27,6 +28,7 @@ import { applyConfigDefaults } from "../../components/config-defaults";
 import { maybeRecordAutoRelease, extractRunDigestFromPhaseOutputs } from "../../components/auto-release";
 import { maybePersistBuildManifest, extractRunManifestFromPhaseOutputs } from "../../components/manifest-persistence";
 import type { DriverComponentResult } from "../../components/driver";
+import type { BuildParamProvenance } from "../../provenance";
 
 function kebabToCamel(s: string): string {
   return s.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase());
@@ -546,8 +548,23 @@ function renderProgress(opName: string, history: WorkflowHistoryRaw): void {
  * (`../../components/driver.ts`) rather than a `*.op.ts` Op. Checked first,
  * mirroring `runGraph`'s `if (ctx.args.components) return
  * runComponentGraph(ctx)` branch (../handlers/graph.ts).
+ *
+ * chant #1116 — `--report` with `--components` is checked and hard-errored
+ * before that dispatch. There is no preview/dry-run mode for the component
+ * driver: unlike the Op path (where `--report` reads a past Temporal run),
+ * `runOpComponents` has never read `ctx.args.report` at all, so the flag was
+ * silently ignored and the command fell through to a real dispatch — observed
+ * live reaching an actual cloud shell-out. Erroring here is the safe minimum
+ * called out on the issue; a real preview is future work.
  */
 export async function runOp(ctx: CommandContext): Promise<number> {
+  if (ctx.args.components && ctx.args.report) {
+    console.error(formatError({
+      message: "--report is not supported with --components",
+      hint: "No preview/dry-run mode exists yet for the component driver (see chant#1116). Omit --report.",
+    }));
+    return 1;
+  }
   if (ctx.args.components) return runOpComponents(ctx);
   if (ctx.args.local && ctx.args.temporal) {
     console.error(formatError({
@@ -669,6 +686,18 @@ async function recordAutoReleasesForRun(
  * Opt out with `--no-release-record` or `chant.config.ts`'s
  * `release.autoRecord: false`; the default is ON. A failed run never reaches
  * this step, so it writes nothing.
+ *
+ * chant #1108 — resolves this invocation's declared build-time parameters
+ * (`chant.config.ts`'s `buildParams`, against `--param`/`--params-file`/a
+ * declared `env` mapping) the exact same way `chant build` does
+ * (`resolveCliBuildParams`, shared with `buildCommand`), BEFORE either the
+ * local or `--temporal` path discovers/imports any `*.component.ts` file.
+ * Before this, `params.*` (`@intentius/chant/params`) was always `{}` under
+ * this command, no matter what a component's `chant.config.ts` declared or a
+ * CI job's environment supplied — see chant #1108. `chant.config.ts` is
+ * loaded once here (with the same defensive fallback the post-run
+ * auto-release check below used to apply itself) and reused for that check,
+ * rather than loaded a second time.
  */
 export async function runOpComponents(ctx: CommandContext): Promise<number> {
   const selector = ctx.args.path;
@@ -680,7 +709,18 @@ export async function runOpComponents(ctx: CommandContext): Promise<number> {
     return 1;
   }
 
-  if (ctx.args.temporal) return runComponentTemporal(ctx, selector);
+  const projectPath = resolve(".");
+  const { config } = await loadChantConfig(projectPath).catch(() => ({ config: {} as ChantConfig }));
+  const paramsResolution = resolveCliBuildParams(config.buildParams, {
+    cli: parseParamFlags(ctx.args.param),
+    paramsFile: ctx.args.paramsFile,
+  });
+  if (!paramsResolution.success) {
+    for (const message of paramsResolution.errors) console.error(message);
+    return 1;
+  }
+
+  if (ctx.args.temporal) return runComponentTemporal(ctx, selector, config, paramsResolution.provenance);
 
   const env = ctx.args.env ?? "local";
   // Seed cross-component/cross-stack outputs from upstream jobs' dumped files
@@ -704,11 +744,12 @@ export async function runOpComponents(ctx: CommandContext): Promise<number> {
   // `undefined` and every `onProgress?.(...)` call in the driver is a no-op —
   // behavior is byte-for-byte unchanged from before this flag existed.
   const onProgress = ctx.args.progressJson ? ndjsonProgressSink() : undefined;
-  const result = await runComponents(resolve("."), selector, {
+  const result = await runComponents(projectPath, selector, {
     env: ctx.args.env,
     componentOutputs: seededOutputs,
     onProgress,
     sandbox: ctx.args.sandbox,
+    buildParams: paramsResolution.provenance,
   });
 
   // Dump the accumulated outputs for a downstream job to seed from. Written
@@ -739,7 +780,6 @@ export async function runOpComponents(ctx: CommandContext): Promise<number> {
   }
 
   if (result.success && result.run) {
-    const { config } = await loadChantConfig(resolve(".")).catch(() => ({ config: {} }));
     const disabled = resolveAutoReleaseDisabled(config, ctx.args.noReleaseRecord);
     await recordAutoReleasesForRun(result.run.results, env, `local-${Date.now()}`, disabled);
   }
@@ -771,8 +811,19 @@ function componentWorkflowId(componentName: string): string {
  * crash and clearable via `chant run signal <name> <signal> --components
  * --temporal` (`runOpSignal` above, extended for components alongside this
  * issue).
+ *
+ * `config`/`buildParams` are resolved once by the caller (`runOpComponents`,
+ * chant #1108) BEFORE this function runs, so `resolveComponentTargets`
+ * below — which discovers/imports the target `*.component.ts` file — sees
+ * `params.*` (`@intentius/chant/params`) already populated, the same
+ * guarantee the local executor path gets.
  */
-async function runComponentTemporal(ctx: CommandContext, selector: string): Promise<number> {
+async function runComponentTemporal(
+  ctx: CommandContext,
+  selector: string,
+  config: ChantConfig,
+  buildParams: BuildParamProvenance[],
+): Promise<number> {
   if (selector === "all") {
     console.error(formatError({
       message: "`chant run --components all --temporal` is not supported",
@@ -782,15 +833,17 @@ async function runComponentTemporal(ctx: CommandContext, selector: string): Prom
   }
 
   const projectPath = resolve(".");
-  const resolved = await resolveComponentTargets(projectPath, selector, ctx.args.sandbox);
+  const resolved = await resolveComponentTargets(projectPath, selector, ctx.args.sandbox, buildParams);
   if (!resolved.success || resolved.targets.length === 0) {
     console.error(formatError({ message: resolved.error ?? `Component "${selector}" not found` }));
     return 1;
   }
   const component = resolved.targets[0];
 
-  // Load config + profile (mirrors runOpTemporal).
-  const { config: chantConfig } = await loadChantConfig(projectPath);
+  // Config + profile (mirrors runOpTemporal). `config` was already loaded by
+  // the caller to resolve build-time parameters (chant #1108); reused here
+  // rather than loading chant.config.ts a second time.
+  const chantConfig = config;
   let profile;
   try {
     profile = resolveProfile(chantConfig as Record<string, unknown>, ctx.args.profile);

package/src/cli/lsp/server.ts

@@ -1,4 +1,4 @@
-import type { LexiconPlugin } from "../../lexicon";
+import type { LexiconPlugin, IntrinsicDef } from "../../lexicon";
 import type { CompletionContext, HoverContext, CodeActionContext } from "../../lsp/types";
 import { computeCapabilities } from "./capabilities";
 import { toLspDiagnostics } from "./diagnostics";
@@ -356,13 +356,18 @@ export class LspServer {
     try {
       const { runLint } = await import("../../lint/engine");
       const rules = [];
+      // chant #1106 — the same active plugins' registered intrinsics, so
+      // EVL001 answers exactly like `fold()` does for a registered,
+      // opted-in call instead of flagging every call as a violation.
+      const intrinsics: IntrinsicDef[] = [];
       for (const plugin of this.plugins) {
         rules.push(...(plugin.lintRules?.() ?? []));
+        intrinsics.push(...(plugin.intrinsics?.() ?? []));
       }
 
       if (rules.length === 0) return [];
 
-      const { diagnostics } = await runLint([filePath], rules);
+      const { diagnostics } = await runLint([filePath], rules, undefined, intrinsics);
       return toLspDiagnostics(diagnostics);
     } catch {
       return [];

package/src/cli/main.test.ts

@@ -270,6 +270,29 @@ describe("parseArgs", () => {
     const result = parseArgs(["build", "src", "--params-file", "./params.json"]);
     expect(result.paramsFile).toBe("./params.json");
   });
+
+  // ── --param=name=value hard error (chant #1118) ──────────────────────────
+  // The joined `--flag=value` form is not supported anywhere in this parser
+  // (see "ignores unknown flags" above) — a dropped --param can silently
+  // change what a build measures/deploys, so this form is rejected loudly
+  // instead of silently accepted as a no-op.
+
+  test("--param=name=value throws instead of silently dropping", () => {
+    expect(() => parseArgs(["build", "src", "--param=tier=production"])).toThrow(/--param=tier=production/);
+  });
+
+  test("--param=name=value error names the working form", () => {
+    expect(() => parseArgs(["build", "src", "--param=tier=production"])).toThrow(/--param name=value/);
+  });
+
+  test("--param= (empty value) also throws", () => {
+    expect(() => parseArgs(["build", "src", "--param="])).toThrow(/--param=/);
+  });
+
+  test("plain --param name=value is unaffected", () => {
+    const result = parseArgs(["build", "src", "--param", "tier=production"]);
+    expect(result.param).toEqual(["tier=production"]);
+  });
 });
 
 // ── resolveCommand tests ──────────────────────────────────────────

package/src/cli/main.ts

@@ -5,7 +5,7 @@ import { isEntryPoint } from "./is-entry-point";
 import { formatSuccess, formatError } from "./format";
 import { loadPlugins, resolveProjectLexicons } from "./plugins";
 import { resolveCommand, type CommandDef, type ParsedArgs } from "./registry";
-import { loadChantConfig } from "../config";
+import { loadChantConfigUpward } from "../config";
 import { ENV_VAR, unknownEnvError } from "../env";
 import { initRuntime } from "../runtime-adapter";
 import { runBuild } from "./handlers/build";
@@ -224,6 +224,16 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.sandbox = true;
     } else if (arg === "--param") {
       (result.param ??= []).push(args[++i]);
+    } else if (arg.startsWith("--param=")) {
+      // chant #1118 — this parser never supports an `--flag=value` joined
+      // form for any value-taking flag (every branch above is an exact `===`
+      // match, so a joined token falls through unrecognized and is silently
+      // dropped — see the "ignores unknown flags" case below). `--param
+      // name=value` (space-separated) is the only accepted form. Rather than
+      // teach the parser joined forms generally, `--param=name=value` is
+      // called out as a hard error instead of a silent no-op: a dropped
+      // `--param` can silently change what a build measures/deploys.
+      throw new Error(`${arg} is not supported. Use --param name=value (space-separated) instead.`);
     } else if (arg === "--params-file") {
       result.paramsFile = args[++i];
     } else if (!arg.startsWith("-")) {
@@ -588,11 +598,15 @@ async function main(): Promise<void> {
   // chant.config itself may branch on the env. (#505)
   if (args.env) process.env[ENV_VAR] = args.env;
 
-  // Initialize runtime adapter early — before plugins or commands run
+  // Initialize runtime adapter early — before plugins or commands run.
+  // chant #1117 — walks up from `args.path` to the project root: for a
+  // subdirectory build/command (`chant build src/<stack> --env prod`) the
+  // declared `environments` almost always live in the root `chant.config.ts`,
+  // not `args.path` itself.
   const projectPath0 = resolve(args.path === "." ? "." : args.path);
   let loadedConfig;
   try {
-    loadedConfig = await loadChantConfig(projectPath0);
+    loadedConfig = await loadChantConfigUpward(projectPath0);
     initRuntime();
   } catch {
     // Config may not exist yet (e.g. `chant init`)

package/src/cli/plugins.ts

@@ -1,5 +1,5 @@
 import { isLexiconPlugin, type LexiconPlugin } from "../lexicon";
-import { loadChantConfig } from "../config";
+import { loadChantConfigUpward } from "../config";
 import { findInfraFiles, detectLexicons } from "../index";
 import { checkConflicts } from "./conflict-check";
 
@@ -96,9 +96,17 @@ export async function loadPlugins(lexiconNames: string[]): Promise<LexiconPlugin
  * that never needed live module exports to begin with. This is strictly
  * better than routing the detection through the sandbox: it removes the
  * execution entirely rather than containing it, at no bundling/spawn cost.
+ *
+ * chant #1117 — walks up from `projectPath` to the project root
+ * (`loadChantConfigUpward`) rather than reading `projectPath` alone: `chant
+ * build src/<stack>` calls this with the stack's own subdirectory, and a
+ * project that declares `lexicons` only in its root `chant.config.ts` (never
+ * detectable by `detectLexicons()`'s import scan alone, e.g. a lexicon that's
+ * loaded but never imported by name in that particular stack's files) would
+ * otherwise silently miss it.
  */
 export async function resolveProjectLexicons(projectPath: string): Promise<string[]> {
-  const { config } = await loadChantConfig(projectPath);
+  const { config } = await loadChantConfigUpward(projectPath);
 
   if (config.lexicons && config.lexicons.length > 0) {
     return config.lexicons;

package/src/components/cli-support.test.ts

@@ -8,16 +8,45 @@
  * rather than going through the CLI arg-parsing/handler dispatch layer.
  */
 
-import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { describe, test, expect, beforeEach, afterEach, vi } from "vitest";
 import { mkdir, writeFile, rm } from "node:fs/promises";
-import { join } from "node:path";
+import { join, dirname, resolve as resolvePath } from "node:path";
+import { fileURLToPath } from "node:url";
 import { tmpdir } from "node:os";
 import Ajv2020 from "ajv/dist/2020";
 import componentSchema from "./component.schema.json";
-import { listComponents, describeComponent, computeComponentGraph, runComponents, findComponentGate } from "./cli-support";
+import {
+  listComponents,
+  describeComponent,
+  computeComponentGraph,
+  runComponents,
+  findComponentGate,
+  resolveComponentTargets,
+  generateComponentsPipeline,
+} from "./cli-support";
 import { CapabilityRegistry, type DeployContext } from "./capability";
 import type { DriverComponent, RunProgressEvent } from "./driver";
 
+// A minimal stand-in for the real gitlab lexicon plugin, satisfying
+// `isLexiconPlugin` (../lexicon.ts) — used only by the `generateComponentsPipeline`
+// buildParams test below, so that test doesn't depend on how `@intentius/
+// chant-lexicon-gitlab`'s own real module resolves under the test runner.
+vi.mock("@intentius/chant-lexicon-gitlab", () => ({
+  gitlab: {
+    name: "gitlab",
+    serializer: { name: "gitlab", rulePrefix: "GL", serialize: () => "" },
+    generate: () => {},
+    validate: () => [],
+    coverage: () => ({ total: 0, covered: 0 }),
+    package: () => "gitlab",
+    generateComponentPipeline: (components: DriverComponent[]) => ({
+      yaml: components.map((c) => c.name).join(","),
+      stages: ["wave-1"],
+      jobs: components.map((c) => ({ jobName: c.name, component: c.name, stage: "wave-1", needs: [] })),
+    }),
+  },
+}));
+
 describe("listComponents", () => {
   let testDir: string;
 
@@ -578,6 +607,195 @@ describe("runComponents", () => {
   });
 });
 
+// ── build-time parameters (chant #1108) ──────────────────────────────────────
+//
+// Before #1108, `discoverComponents`'s callers here never resolved
+// `chant.config.ts`'s declared `buildParams` at all, so a `*.component.ts`
+// file reading `params.<name>` (`@intentius/chant/params`) always saw `{}` —
+// the exact probe from chant#1108's reproduction. These tests lock in that
+// `runComponents`/`resolveComponentTargets`/`generateComponentsPipeline` now
+// forward an already-resolved `buildParams` into discovery, so a component's
+// `params.<name>` read reflects it before any step dispatches.
+
+const thisDir = dirname(fileURLToPath(import.meta.url));
+const paramsModulePath = resolvePath(thisDir, "../params");
+
+describe("runComponents — buildParams (chant #1108)", () => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    testDir = join(tmpdir(), `chant-run-components-buildparams-test-${Date.now()}-${Math.random()}`);
+    await mkdir(testDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  test("the previously-{} case: a component's params.<name> read resolves when buildParams is passed", async () => {
+    await writeFile(
+      join(testDir, "svc.component.ts"),
+      `
+        import { params } from ${JSON.stringify(paramsModulePath)};
+        export const svc = {
+          name: "svc",
+          dependsOn: [],
+          deploy: [{ phase: "Apply", steps: [{ kind: "deploy-thing", tier: params.tier }] }],
+        };
+      `,
+    );
+
+    const capability = fakeCapability("deploy-thing");
+    const registry = new CapabilityRegistry();
+    registry.register(capability);
+
+    const result = await runComponents(testDir, "svc", {
+      registry,
+      buildParams: [{ name: "tier", value: "production", source: "cli" }],
+    });
+
+    expect(result.success).toBe(true);
+    expect(capability.calls[0]?.input).toMatchObject({ tier: "production" });
+  });
+
+  test("without buildParams, params.<name> is undefined (the bug this issue fixes, still true for a caller that resolves none)", async () => {
+    await writeFile(
+      join(testDir, "svc.component.ts"),
+      `
+        import { params } from ${JSON.stringify(paramsModulePath)};
+        export const svc = {
+          name: "svc",
+          dependsOn: [],
+          deploy: [{ phase: "Apply", steps: [{ kind: "deploy-thing", tier: params.tier ?? "unset" }] }],
+        };
+      `,
+    );
+
+    const capability = fakeCapability("deploy-thing");
+    const registry = new CapabilityRegistry();
+    registry.register(capability);
+
+    const result = await runComponents(testDir, "svc", { registry });
+
+    expect(result.success).toBe(true);
+    expect(capability.calls[0]?.input).toMatchObject({ tier: "unset" });
+  });
+
+  test("RunComponentsResult.buildParams echoes back the resolved provenance that was passed in", async () => {
+    await writeFile(
+      join(testDir, "svc.component.ts"),
+      `export const svc = { name: "svc", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "deploy-thing" }] }] };`,
+    );
+
+    const registry = fakeRegistry();
+    const result = await runComponents(testDir, "svc", {
+      registry,
+      buildParams: [{ name: "tier", value: "production", source: "cli" }],
+    });
+
+    expect(result.buildParams).toEqual([{ name: "tier", value: "production", source: "cli" }]);
+  });
+
+  test("selector 'all' also forwards buildParams into discovery", async () => {
+    await writeFile(
+      join(testDir, "svc.component.ts"),
+      `
+        import { params } from ${JSON.stringify(paramsModulePath)};
+        export const svc = { name: "svc", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "deploy-thing", tier: params.tier }] }] };
+      `,
+    );
+
+    const capability = fakeCapability("deploy-thing");
+    const registry = new CapabilityRegistry();
+    registry.register(capability);
+
+    const result = await runComponents(testDir, "all", {
+      registry,
+      buildParams: [{ name: "tier", value: "staging", source: "env" }],
+    });
+
+    expect(result.success).toBe(true);
+    expect(capability.calls[0]?.input).toMatchObject({ tier: "staging" });
+  });
+});
+
+describe("resolveComponentTargets — buildParams (chant #1108)", () => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    testDir = join(tmpdir(), `chant-resolve-targets-buildparams-test-${Date.now()}-${Math.random()}`);
+    await mkdir(testDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  test("forwards buildParams into discovery — the durable (--temporal) path's entrypoint", async () => {
+    await writeFile(
+      join(testDir, "svc.component.ts"),
+      `
+        import { params } from ${JSON.stringify(paramsModulePath)};
+        export const svc = {
+          name: "svc",
+          dependsOn: [],
+          deploy: [{ phase: "Apply", steps: [{ kind: "cfn-deploy", stack: params.env }] }],
+        };
+      `,
+    );
+
+    const result = await resolveComponentTargets(testDir, "svc", undefined, [
+      { name: "env", value: "prod-a", source: "env" },
+    ]);
+
+    expect(result.success).toBe(true);
+    expect((result.targets[0].deploy[0].steps[0] as { stack?: unknown }).stack).toBe("prod-a");
+  });
+});
+
+describe("generateComponentsPipeline — buildParams (chant #1108)", () => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    testDir = join(tmpdir(), `chant-generate-components-buildparams-test-${Date.now()}-${Math.random()}`);
+    await mkdir(testDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  test("forwards buildParams into discovery before synthesizing the pipeline", async () => {
+    await writeFile(
+      join(testDir, "svc.component.ts"),
+      `
+        import { params } from ${JSON.stringify(paramsModulePath)};
+        export const svc = {
+          name: String(params.name),
+          dependsOn: [],
+          deploy: [{ phase: "Apply", steps: [{ kind: "shell" }] }],
+        };
+      `,
+    );
+
+    // Uses the mocked "gitlab" plugin above (see the `vi.mock` at the top of
+    // this file) — proves the component name `discoverComponents` resolved
+    // (via `params.name`) made it all the way through to the synthesized
+    // pipeline, not just to `discover()`'s own return value.
+    const result = await generateComponentsPipeline(
+      testDir,
+      "gitlab",
+      undefined,
+      undefined,
+      [{ name: "name", value: "named-from-params", source: "cli" }],
+    );
+
+    expect(result.success).toBe(true);
+    expect(result.jobs?.map((j) => j.component)).toEqual(["named-from-params"]);
+    expect(result.buildParams).toEqual([{ name: "name", value: "named-from-params", source: "cli" }]);
+  });
+});
+
 describe("runComponents — onProgress (--progress-json wiring, M3)", () => {
   let testDir: string;
 

package/src/components/cli-support.ts

@@ -23,6 +23,7 @@
  */
 
 import { discoverComponents } from "./discover";
+import type { BuildParamProvenance } from "../provenance";
 import { projectToJson, type Archetype } from "./component";
 import {
   resolveComponentGraph,
@@ -185,6 +186,8 @@ export interface GenerateComponentsResult {
   /** Every generated job, for a machine-readable view (`--format json`). */
   jobs?: Array<{ jobName: string; component: string; stage: string; needs: string[] }>;
   error?: string;
+  /** This invocation's resolved build-time parameters (chant #1108) — the generate-mode counterpart of `../cli/commands/build.ts`'s `BuildResult.buildParams`. Empty when the project declares/supplies none. */
+  buildParams?: BuildParamProvenance[];
 }
 
 /**
@@ -221,6 +224,15 @@ export async function generateComponentsPipeline(
   lexicon: GenerateLexicon,
   options?: ComponentPipelineOptions,
   sandbox?: boolean,
+  /**
+   * chant #1108 — this invocation's resolved build-time parameter values
+   * (../cli/handlers/build.ts resolves them, the same sequence `chant build`
+   * runs, BEFORE calling this function), forwarded into discovery so a
+   * `params.<name>` reference inside a discovered `*.component.ts` file
+   * resolves instead of reading `{}`. See `discoverComponents`'s
+   * `buildParams` option (./discover.ts) for the full doc.
+   */
+  buildParams?: BuildParamProvenance[],
 ): Promise<GenerateComponentsResult> {
   const plugin = await loadLexiconPlugin(lexicon);
   if (!plugin?.generateComponentPipeline) {
@@ -230,7 +242,7 @@ export async function generateComponentsPipeline(
     };
   }
 
-  const result = await discoverComponents(path, { sandbox });
+  const result = await discoverComponents(path, { sandbox, buildParams });
   if (result.errors.length > 0) {
     return { success: false, error: result.errors.map((e) => e.message).join("\n") };
   }
@@ -243,7 +255,7 @@ export async function generateComponentsPipeline(
 
   try {
     const { yaml, stages, jobs } = plugin.generateComponentPipeline(driverComponents, options);
-    return { success: true, yaml, stages, jobs };
+    return { success: true, yaml, stages, jobs, buildParams };
   } catch (err) {
     if (err instanceof UnknownDependencyError || err instanceof DependencyCycleError) {
       return { success: false, error: err.message };
@@ -344,6 +356,21 @@ export interface RunComponentsOptions {
    * `--progress-json`, in which case nothing changes.
    */
   onProgress?: (event: RunProgressEvent) => void;
+  /**
+   * chant #1108 — this run's resolved build-time parameter values, resolved
+   * the exact same way `chant build` resolves them
+   * (../cli/build-params-cli.ts's `resolveCliBuildParams`, driven by
+   * `--param`/`--params-file`/a declared `env` mapping/`chant.config.ts`'s
+   * `buildParams` defaults). The CLI handler (../cli/handlers/run.ts)
+   * resolves + logs these BEFORE calling `runComponents`, the same
+   * sequencing `chant build` uses — this function only forwards the
+   * already-resolved values into discovery (`resolveComponentTargets` below,
+   * then `discoverComponents`); it does not resolve them itself, so
+   * `runComponents` stays free of CLI-flag-parsing/formatting concerns.
+   * Default: none — `params.*` stays `{}`, matching every caller (including
+   * every test in `cli-support.test.ts`) that doesn't supply this.
+   */
+  buildParams?: BuildParamProvenance[];
 }
 
 /** Result of `chant run --components <name|all>`. */
@@ -356,6 +383,8 @@ export interface RunComponentsResult {
   error?: string;
   /** Set when a selected component (or one of its `deploy`/`rollback` phases) contains a `gate` the local executor cannot run. */
   gateUnsupported?: { component: string; signalName: string };
+  /** This run's resolved build-time parameters (chant #1108) — the component-driver counterpart of `../cli/commands/build.ts`'s `BuildResult.buildParams`. Present only once the run actually reached dispatch (mirrors `BuildResult.buildParams`, which is likewise absent on an early-error return). */
+  buildParams?: BuildParamProvenance[];
 }
 
 /**
@@ -404,8 +433,10 @@ export async function resolveComponentTargets(
   path: string,
   selector: string,
   sandbox?: boolean,
+  /** chant #1108 — this invocation's resolved build-time parameter values, forwarded into `discoverComponents` so a `params.<name>` reference inside a discovered `*.component.ts` file resolves instead of reading `{}`. See `discoverComponents`'s `buildParams` option (./discover.ts). */
+  buildParams?: BuildParamProvenance[],
 ): Promise<ResolvedComponentTargets> {
-  const result = await discoverComponents(path, { sandbox });
+  const result = await discoverComponents(path, { sandbox, buildParams });
   if (result.errors.length > 0) {
     return { success: false, targets: [], error: result.errors.map((e) => e.message).join("\n") };
   }
@@ -433,7 +464,7 @@ export async function runComponents(
   selector: string,
   options: RunComponentsOptions = {},
 ): Promise<RunComponentsResult> {
-  const resolved = await resolveComponentTargets(path, selector, options.sandbox);
+  const resolved = await resolveComponentTargets(path, selector, options.sandbox, options.buildParams);
   if (!resolved.success) {
     return { success: false, selected: [], error: resolved.error };
   }
@@ -479,7 +510,7 @@ export async function runComponents(
   try {
     if (selector === "all") {
       const run = await runInterpretDriver(resolvedTargets, registry, { env, componentOutputs: seedOutputs, onProgress });
-      return { success: true, run, selected };
+      return { success: true, run, selected, buildParams: options.buildParams };
     }
 
     // Single-component invocation: run just this component, bypassing
@@ -518,7 +549,7 @@ export async function runComponents(
       failedComponent: componentResult.ok ? undefined : componentResult.component,
       componentOutputs,
     };
-    return { success: componentResult.ok, run, selected };
+    return { success: componentResult.ok, run, selected, buildParams: options.buildParams };
   } catch (err) {
     if (err instanceof DriverRunFailure) {
       return { success: false, run: err.result, selected, error: err.message };