@intentius/chant 0.13.1 → 0.15.0

package/dist/components/cli-support.d.ts

@@ -0,0 +1,204 @@
+/**
+ * CLI-facing helpers over component discovery (#560, epic #551) — kept
+ * separate from ../cli/commands/{list,describe}.ts and
+ * ../cli/handlers/graph.ts so those files stay thin dispatchers and the
+ * component-specific report shaping lives alongside the rest of the
+ * component subsystem, the same way ../op/discover.ts's results are shaped
+ * inline by its own CLI callers rather than a `cli` folder inside `op/`.
+ *
+ * Surfaces components in the three places the issue asks for:
+ *  - `chant list --components` — inventory (mirrors `ListEntity`/`listCommand`).
+ *  - `chant describe <name> --components` — one component's full JSON contract
+ *    projection (mirrors `describeCommand`'s effective-config view).
+ *  - `chant graph --components` — dependency order/waves from `dependsOn`
+ *    (mirrors `computeStackGraph`/`runStackGraph`, but reuses
+ *    `resolveComponentGraph` from ../driver.ts since a component's `dependsOn`
+ *    is already a flat name list — no AttrRef-style inference needed).
+ *  - `chant build --components --generate gitlab` — generate mode (#563):
+ *    synthesize CI YAML from the same discovered declarations instead of
+ *    running them, via `generateGitlabPipeline` (../generate-gitlab.ts).
+ *  - `chant run --components <name|all>` — interpret mode (#585): dispatch
+ *    discovered component(s) through the interpret `driver.ts` on the local
+ *    executor, the CLI entrypoint the driver (#556) never had.
+ */
+import { type Archetype } from "./component.js";
+import { type DriverComponent, type DriverRunResult } from "./driver.js";
+import { type ComponentPipelineOptions } from "../lexicon.js";
+import type { CapabilityRegistry } from "./capability.js";
+import { type ChantConfig } from "../config.js";
+/** One component in `chant list --components` output. */
+export interface ListedComponent {
+    name: string;
+    archetype: Archetype;
+    dependsOn: string[];
+    hasBuild: boolean;
+    phases: string[];
+    filePath: string;
+}
+export interface ListComponentsResult {
+    success: boolean;
+    components: ListedComponent[];
+    errors: string[];
+}
+/** Discover components under `path` and shape them for `chant list --components`. */
+export declare function listComponents(path: string): Promise<ListComponentsResult>;
+/** One component's full JSON contract projection, for `chant describe <name> --components`. */
+export interface DescribedComponent {
+    name: string;
+    filePath: string;
+    /** The component's JSON contract projection (validates against component.schema.json). */
+    json: unknown;
+}
+export interface DescribeComponentResult {
+    success: boolean;
+    component: string;
+    described?: DescribedComponent;
+    output: string;
+}
+/** Find and project one named component, for `chant describe <name> --components`. */
+export declare function describeComponent(path: string, name: string): Promise<DescribeComponentResult>;
+/** Dependency order/waves for `chant graph --components`, from every discovered component's `dependsOn`. */
+export interface ComponentGraphResult {
+    success: boolean;
+    order: string[];
+    waves: string[][];
+    edges: Array<{
+        from: string;
+        to: string;
+    }>;
+    error?: string;
+}
+/** Compute the components' dependency graph under `path`, for `chant graph --components`. */
+export declare function computeComponentGraph(path: string): Promise<ComponentGraphResult>;
+/** A generate-mode target lexicon name — any lexicon whose plugin implements `generateComponentPipeline` (currently gitlab; github/forgejo as they add it). */
+export type GenerateLexicon = string;
+/** Result of `chant build --components --generate <lexicon>`. */
+export interface GenerateComponentsResult {
+    success: boolean;
+    /** The synthesized CI YAML, when `success` is true. */
+    yaml?: string;
+    /** Wave-ordered stage names (one entry per wave). */
+    stages?: string[];
+    /** Every generated job, for a machine-readable view (`--format json`). */
+    jobs?: Array<{
+        jobName: string;
+        component: string;
+        stage: string;
+        needs: string[];
+    }>;
+    error?: string;
+}
+/**
+ * Generate mode (#563): discover every `Component` under `path` and
+ * synthesize a thin CI pipeline for `lexicon` that triggers each component's
+ * own composition in dependency order/waves — the same `resolveComponentGraph`
+ * order `chant graph --components`/the interpret driver use. No deploy logic
+ * is inlined into the generated YAML; a cross-cutting change goes through
+ * `options`, never per component. The CI-specific synthesis is contributed by
+ * the target lexicon's `generateComponentPipeline` (#688); core owns only the
+ * generic discovery + graph.
+ */
+export declare function generateComponentsPipeline(path: string, lexicon: GenerateLexicon, options?: ComponentPipelineOptions): Promise<GenerateComponentsResult>;
+/**
+ * Find the first `gate` step anywhere in a component's `deploy`/`rollback`
+ * composition (including nested fan-out phases), mirroring
+ * `../op/local-executor.ts`'s `findGate`. Used as a pre-flight check so
+ * `chant run --components` fails before any step runs — matching
+ * `runOpLocal`'s behavior for Ops — rather than only failing mid-run when the
+ * driver itself reaches the gated phase (`DriverGateUnsupportedError`).
+ */
+export declare function findComponentGate(component: DriverComponent): {
+    signalName: string;
+} | undefined;
+/** Options for `runComponents` (backs `chant run --components <name|all> [--env <env>]`). */
+export interface RunComponentsOptions {
+    /** Target environment name, threaded into every capability's `DeployContext.env` (default: "local"). */
+    env?: string;
+    /** Additional capability plugin package names to load on top of the built-in starter set (see `buildCapabilityRegistry`). */
+    capabilityPlugins?: string[];
+    /**
+     * Pre-built registry to dispatch through, bypassing `buildCapabilityRegistry`
+     * entirely. Real callers (the CLI handler) should leave this unset; it exists
+     * so tests can inject a registry wired to a `MockCloudExecutor` (mirroring
+     * `../components/pilots/pilots-e2e.test.ts`'s `buildRegistry`) instead of the
+     * default starter set, whose non-pilot verbs are still typed stubs that throw
+     * `CapabilityNotImplementedError` (see `./verbs/stub.ts`).
+     */
+    registry?: CapabilityRegistry;
+    /**
+     * Pre-loaded project config to resolve `sbom`/`signing`/`vulnPolicy`
+     * defaults from (#629), bypassing `loadChantConfig` entirely. Real callers
+     * (the CLI handler) should leave this unset — `runComponents` loads
+     * `chant.config.ts`/`chant.config.json` from `path` itself; this exists so
+     * tests can inject a config object directly, the same escape hatch
+     * `registry` above provides for the capability registry.
+     */
+    config?: ChantConfig;
+    /**
+     * Cross-component/cross-stack outputs to seed the run with — keyed by
+     * component name, the same shape `DriverRunResult.componentOutputs` produces.
+     * The CLI populates this from `--seed-outputs` files (an upstream CI job's
+     * dumped outputs), so a single-component run in a downstream job can resolve
+     * `stackOutput()`/`@<name>.publish.*` references to a component that already
+     * ran elsewhere. Merged with, and overridden by, outputs this run produces.
+     */
+    componentOutputs?: Record<string, Record<string, unknown>>;
+}
+/** Result of `chant run --components <name|all>`. */
+export interface RunComponentsResult {
+    success: boolean;
+    /** The driver's run result, when the run reached the driver (even on a failed component). */
+    run?: DriverRunResult;
+    /** Component names actually dispatched to the driver, in run order. */
+    selected: string[];
+    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;
+    };
+}
+/**
+ * Run one named component, or every discovered component (`selector ===
+ * "all"`), through the interpret driver (`../components/driver.ts`) on the
+ * local in-process executor — the CLI entrypoint the driver never had (#585,
+ * follow-up to #556). Discovers the full component set first, then either:
+ *  - `selector === "all"`: resolves the whole set's dependency order/waves
+ *    and dispatches every component through `runInterpretDriver`, matching
+ *    what the generated orchestrator Op will eventually do — the same
+ *    order `chant graph --components` reports.
+ *  - a single name: dispatches just that component via `runComponentDeploy`,
+ *    without requiring the rest of its `dependsOn` graph to be present in
+ *    this invocation. This mirrors generate mode's per-job invocation model
+ *    (`generate-gitlab.ts`) — each CI job triggers exactly one component, and
+ *    cross-job/cross-wave ordering is the CI DAG's (`needs:`) job, not this
+ *    command's; requiring the full graph here would make `chant run
+ *    --components <name>` fail for any component whose `dependsOn` names
+ *    infra outside the discovered set (e.g. a shared stack, per the
+ *    `search-service` pilot), which is exactly the common case.
+ *
+ * Pre-flights every selected component for a `gate` step and fails before any
+ * step runs (`gateUnsupported`), matching `runOpLocal`'s pre-flight
+ * `findGate` check for Ops — gated components need a durable (Temporal)
+ * backend, which is out of scope here (issue #585 scopes Temporal-backed
+ * component execution to what already exists for Ops; the epic tracks
+ * graduating a gated component to `--temporal` separately).
+ */
+/** Result of resolving a `<name|all>` selector against discovered components — shared by the local (`runComponents`) and durable (Temporal codegen, #589) entrypoints. */
+export interface ResolvedComponentTargets {
+    success: boolean;
+    targets: DriverComponent[];
+    error?: string;
+}
+/**
+ * Discover every component under `path` and resolve `selector` (`"all"` or a
+ * single component name) to the `DriverComponent`(s) to run, with no gate
+ * check and no dispatch — just discovery + selection, factored out of
+ * `runComponents` so the durable Temporal entrypoint (`chant run --components
+ * <name> --temporal`, #589) can reuse the exact same selection semantics
+ * without also inheriting the local executor's pre-flight gate rejection
+ * (gates are exactly what the durable path exists to support).
+ */
+export declare function resolveComponentTargets(path: string, selector: string): Promise<ResolvedComponentTargets>;
+export declare function runComponents(path: string, selector: string, options?: RunComponentsOptions): Promise<RunComponentsResult>;
+//# sourceMappingURL=cli-support.d.ts.map

package/dist/components/cli-support.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-support.d.ts","sourceRoot":"","sources":["../../src/components/cli-support.ts"],"names":[],"mappings":"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"}

package/dist/components/component.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Typed `Component` authoring form — Phase 2 (#560, epic #551).
+ *
+ * This is the real authoring frontend the docs (component-contract.mdx,
+ * composition-and-wiring.mdx) describe and that `pilots/authoring-shape.ts`
+ * (#555's stopgap) explicitly deferred to this issue. It mirrors
+ * `component.schema.json` field-for-field, so `projectToJson` stays a
+ * structural no-op — the interesting content lives in each component's
+ * composition, not in a bespoke serializer.
+ *
+ * See https://intentius.io/chant/components/component-contract/ and
+ * https://intentius.io/chant/components/composition-and-wiring/.
+ */
+/** Mirrors `$defs.Archetype` in component.schema.json. */
+export type Archetype = "service" | "infra" | "producer-library";
+/** Mirrors `$defs.StackOutputReference`. */
+export interface StackOutputReference {
+    stackOutput: {
+        stack: string;
+        name: string;
+    };
+}
+/**
+ * Mirrors `$defs.WiringValue` — a literal, or one of the reference forms
+ * (`$env.*`, `@Phase.field`, `@<component>.publish.uri|digest|key`, or a
+ * `{ stackOutput }` object), all resolved by the graph rather than by
+ * orchestrator code. Loosened to `string` for the literal/`$env`/prior-step/
+ * artifact-reference forms since they share one representation; only
+ * `stackOutput` needs its own shape.
+ */
+export type Wiring = string | StackOutputReference;
+/** Mirrors `$defs.BuildSpec`. */
+export interface BuildSpec {
+    /** Build capability verb, keyed by artifact type, e.g. "docker-build", "zip-package", "jvm-build". */
+    kind: string;
+    /** Build context path (e.g. a Docker build context directory). */
+    context?: string;
+    /** Build output always lands in the self-contained BuildArchive. */
+    into?: "archive";
+    /**
+     * Optional component-level SBOM authoring hint (#606, epic #551 follow-up
+     * to #564/#568) — not itself a `generate-sbom` step (that is composed
+     * explicitly in `deploy`/build tooling, see
+     * ../verbs/sbom.ts's `GenerateSbomInput`); this is metadata an authoring
+     * frontend or generator can read when deciding whether/how to compose
+     * that step for this component. Rides `BuildSpec`'s existing
+     * `additionalProperties: true` in component.schema.json — no schema change
+     * needed for this extension.
+     */
+    sbom?: {
+        /** Preferred SBOM format for this component, overriding `chant.config.ts`'s project-wide `sbom.format` default (see ../../config.ts's `resolveSbomFormat`). */
+        format?: "spdx" | "cyclonedx";
+        /** Set true to skip SBOM generation for this component even where a project default would otherwise include it. `generate-sbom` is never invoked implicitly — this only documents intent for whatever composes the component's build phase. */
+        optOut?: boolean;
+    };
+    [extra: string]: unknown;
+}
+/**
+ * Mirrors `$defs.Step` — one capability invocation, the leaf unit of a
+ * composition. `kind` selects the capability (a verb, e.g. "cfn-deploy",
+ * "publish-image", "ecs-update-service"); the remaining properties are that
+ * capability's typed input. `kind: "gate"` is reserved for `Gate` below, not
+ * a capability — use `gate()` to author one.
+ */
+export interface Step {
+    kind: string;
+    /** Reference to a published image digest, typically `"@Publish.digest"`. */
+    imageRef?: Wiring;
+    /** Reference to a published JAR/artifact location, e.g. `"@jar-lib.publish.uri"`. */
+    jar?: Wiring;
+    /** Reference to a published revision/bundle location for host/code-delivery capabilities. */
+    revision?: Wiring;
+    /** Named inputs passed into an apply step; each may be a literal or any wiring reference. */
+    inputs?: Record<string, Wiring>;
+    [param: string]: unknown;
+}
+/** Mirrors `$defs.Gate` — pauses the composition for an external signal (typically human approval). */
+export interface Gate {
+    kind: "gate";
+    signalName: string;
+    /** Duration string bounding the wait, e.g. "48h". Default: "48h". */
+    timeout?: string;
+    /** Human-readable description of the action required to unblock this gate. */
+    description?: string;
+}
+/**
+ * Mirrors `$defs.Phase` — one named phase of a deploy composition. A step may
+ * itself be a nested `Phase`, which is how a fan-out unit becomes a mini-
+ * composition (see composition-and-wiring.mdx).
+ */
+export interface Phase {
+    phase: string;
+    steps: Array<Step | Gate | Phase>;
+    /** Run all steps in this phase concurrently instead of sequentially. */
+    parallel?: boolean;
+    /** Compensation phases for this phase, executed in reverse order on failure. */
+    onFailure?: Phase[];
+}
+/**
+ * The typed `Component` authoring form — projects 1:1 to the JSON contract
+ * (component.schema.json). `archetype` is optional on both sides: when
+ * omitted here, `projectToJson` infers it structurally (see
+ * `inferArchetype`) so the JSON projection always carries an explicit value,
+ * matching how the merged fixtures are authored.
+ */
+export interface Component {
+    name: string;
+    /** Optional explicit archetype hint; inferred from the composition shape when omitted (see `inferArchetype`). */
+    archetype?: Archetype;
+    /** Other component names that must complete before this one runs. Ordering only — no logic. */
+    dependsOn: string[];
+    /** Optional: source -> BuildArchive. Omitted entirely for config-only / infra components. */
+    build?: BuildSpec;
+    /** The component's own composition over shared capabilities. */
+    deploy: Phase[];
+    /** Optional standalone verify phases, for components that separate verification from `deploy`. */
+    verify?: Phase[];
+    /** Optional explicit compensation phases, executed in reverse order on terminal failure of `deploy`. */
+    rollback?: Phase[];
+    /**
+     * Optional: the live lexicon entity/resource name(s) this component owns,
+     * when they differ from `name` (#598). `chant components status --live`
+     * joins the release ledger against live evidence by name; components and
+     * lexicon entities are different namespaces in general (see
+     * `../lifecycle/status.ts`), so a component whose deploy composition
+     * targets an entity/resource declared under a different name must say so
+     * explicitly here. A component that owns several entities (e.g. a fan-out
+     * cluster with one stack per node) may list them all — live evidence is
+     * aggregated across every name. Omitted entirely (the common case for the
+     * pilot components) falls back to `[name]`, preserving the original
+     * name == entity join with no behavior change.
+     */
+    liveNames?: string[];
+}
+/** Author a named phase. `steps` may mix capability `Step`s, `Gate`s, and nested `Phase`s (fan-out). */
+export declare function phase(name: string, steps: Array<Step | Gate | Phase>, opts?: {
+    parallel?: boolean;
+}): Phase;
+/** Author a gate step — pauses the composition for an external signal (typically human approval). */
+export declare function gate(signalName: string, opts?: {
+    timeout?: string;
+    description?: string;
+}): Gate;
+/**
+ * Author a cross-stack output reference — the TypeScript-side equivalent of
+ * the JSON contract's `{ stackOutput: { stack, name } }` (schema
+ * `StackOutputReference`), e.g. `stackOutput("shared-alb", "ListenerArn")`.
+ * Resolved by `chant graph --stacks`, never by orchestrator code.
+ */
+export declare function stackOutput(stack: string, name: string): StackOutputReference;
+/**
+ * Infer a component's archetype from the shape of its composition, when no
+ * explicit `archetype` is authored — matching the archetype table in
+ * component-contract.mdx:
+ *  - **producer-library**: has a `build`, and every step across `deploy` is a
+ *    publish-family step (or a gate) — build -> publish only, no apply.
+ *  - **service**: has a `build` and at least one non-publish, non-gate step
+ *    (an apply/verify step) — build -> publish -> apply -> verify.
+ *  - **infra**: no `build` — apply -> verify only.
+ *
+ * This is a structural heuristic, not a capability-registry lookup (see
+ * `BUILD_ONLY_HINT`/`isPublishStep` above): it only needs to distinguish
+ * "nothing but publish" from "something else happens after publish", which
+ * every merged pilot/fixture satisfies without consulting the registry.
+ */
+export declare function inferArchetype(component: Pick<Component, "build" | "deploy">): Archetype;
+/**
+ * Project a typed `Component` to its plain-JSON contract form
+ * (component.schema.json). Field names already match the schema 1:1, so
+ * projection is mechanical: a deep `JSON.parse(JSON.stringify())` round-trip
+ * (dropping `undefined` optional fields) plus filling in `archetype` via
+ * `inferArchetype` when the author didn't supply one explicitly. Kept
+ * intentionally dumb beyond that inference — the schema/fixtures stay the
+ * source of truth for shape, not this function.
+ */
+export declare function projectToJson(component: Component): unknown;
+/** Runtime type guard: true if `value` looks like a `Component` (has the required `name`/`dependsOn`/`deploy` shape). Used by discovery to pick exported `Component` values out of a `*.component.ts` module without requiring a class/marker symbol. */
+export declare function isComponent(value: unknown): value is Component;
+//# sourceMappingURL=component.d.ts.map

package/dist/components/component.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../../src/components/component.ts"],"names":[],"mappings":"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"}

package/dist/components/config-defaults.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Config-defaults pass (#629, epic #551 follow-up to #606/#622/#626) — the
+ * missing link between `chant.config.ts`'s `sbom`/`signing`/`vulnPolicy`
+ * sections and the steps that actually consume them.
+ *
+ * Before this module, `resolveSigningDefaults`/`resolveVulnPolicy`
+ * (../config.ts) were never called anywhere in the `chant run --components`
+ * path, and `resolveSbomFormat` was only ever called in post-hoc display
+ * code. A component author had to hand-code `format`/`keyless`/`oidcIssuer`/
+ * `policy` into every `generate-sbom`/`sign`/`attest-provenance`/`verify`/
+ * `vuln-gate` step, even when the project already declared a project-wide
+ * default in `chant.config.ts` — the config sections were decorative.
+ *
+ * `applyConfigDefaults` walks a `DriverComponent`'s `deploy` composition
+ * (including nested fan-out phases and `onFailure` compensation phases) and
+ * returns a new component with each recognized step's config-driven fields
+ * filled in *only where the step didn't already set them* — per-step value
+ * wins over config wins over the capability's own built-in default, the
+ * precedence every one of the `resolve*` docstrings in ../config.ts already
+ * claims. This module is the caller that finally makes that claim true.
+ *
+ * Kept entirely outside `./driver.ts`: the driver stays capability-agnostic
+ * (it dispatches by `kind` and knows nothing about `sbom`/`signing`/
+ * `vulnPolicy`) — this pass transforms the component's plain-data composition
+ * *before* it ever reaches the driver, the same "resolve config, then hand a
+ * capability-agnostic caller a fully-formed input" convention `resolveSbomFormat`'s
+ * own docstring already describes for its callers.
+ */
+import type { ChantConfig } from "../config.js";
+import type { DriverComponent } from "./driver.js";
+/**
+ * Return `component` with `chant.config.ts`'s `sbom`/`signing`/`vulnPolicy`
+ * defaults filled into its `deploy` (and `rollback`, which shares the same
+ * `DriverPhase[]` shape and can equally carry a `verify`/`vuln-gate` step)
+ * composition, wherever a step didn't already specify the value itself.
+ * Non-destructive: returns a new component/phase/step tree, never mutates
+ * `component` in place, so a caller holding the original discovered
+ * `DriverComponent` (e.g. for `chant describe`) is unaffected.
+ */
+export declare function applyConfigDefaults(component: DriverComponent, config: ChantConfig): DriverComponent;
+//# sourceMappingURL=config-defaults.d.ts.map

package/dist/components/config-defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-defaults.d.ts","sourceRoot":"","sources":["../../src/components/config-defaults.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,OAAO,KAAK,EAAE,eAAe,EAAuC,MAAM,UAAU,CAAC;AAkGrF;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,eAAe,EAAE,MAAM,EAAE,WAAW,GAAG,eAAe,CAMpG"}

package/dist/components/discover.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Component discovery — Phase 2 (#560, epic #551).
+ *
+ * Mirrors chant's existing declarable discovery
+ * (`../discovery/index.ts`'s `discover()`, built on `findInfraFiles`) as
+ * closely as a structurally distinct type allows, and borrows its
+ * file-suffix convention from Op discovery
+ * (`../op/discover.ts`'s `discoverOps()`, `*.op.ts`): a component is any
+ * `Component`-shaped value (see `./component.ts`'s `isComponent`) exported
+ * (by any export name, not just `default`) from a `*.component.ts` file.
+ *
+ * Why a dedicated convention rather than folding into `discover()`:
+ * `Declarable` (`../declarable.ts`) is a lexicon-resource marker —
+ * `{ lexicon, entityType, kind, [DECLARABLE_MARKER]: true }` — and a
+ * `Component` has none of that shape (no `lexicon`, and its `deploy`
+ * composition is data the capability driver interprets, not a serializable
+ * lexicon resource). Reusing `collectEntities`/`isDeclarable` would mean
+ * either stretching the `Declarable` marker to cover an unrelated shape or
+ * silently ignoring components during the existing walk. A parallel,
+ * purpose-built collector keeps both conventions simple: `*.ts` + the
+ * `Declarable` marker for resources, `*.component.ts` + the `Component`
+ * shape for components — exactly how `*.op.ts` is already a parallel,
+ * purpose-built convention for Ops.
+ *
+ * Filename convention (`*.component.ts`) is documented here rather than
+ * inferred from export shape alone so a project can `grep` for its
+ * components the same way it can for `*.op.ts` files, and so discovery does
+ * not have to import (and risk side-effecting) every `.ts` file in the
+ * project looking for stray `Component`-shaped objects.
+ */
+import { DiscoveryError } from "../errors.js";
+import { type Component } from "./component.js";
+/** One discovered component, paired with the file it was exported from. */
+export interface DiscoveredComponent {
+    component: Component;
+    /** The export name the component was found under (informational; components are keyed by their own `.name`, not this). */
+    exportName: string;
+    filePath: string;
+}
+export interface ComponentDiscoveryResult {
+    /** Discovered components, keyed by `component.name` (the schema identity), not by export name or file. */
+    components: Map<string, DiscoveredComponent>;
+    /** Every `*.component.ts` file that was scanned. */
+    sourceFiles: string[];
+    errors: DiscoveryError[];
+}
+/**
+ * Discover every `Component` declared under `path`: scan for `*.component.ts`
+ * files, import each, and collect every export whose value satisfies
+ * `isComponent` (any export name — not just `default` — so a file may
+ * declare several related components, matching how a resource file can
+ * export several `Declarable`s). Duplicate `component.name` across files (or
+ * within one file) is a discovery error, matching `collectEntities`'s
+ * duplicate-export handling and `discoverOps`'s duplicate-Op-name handling —
+ * except the identity compared is the schema-level `name` field, since two
+ * different export bindings could otherwise declare the same component name
+ * and silently collide at deploy time.
+ */
+export declare function discoverComponents(path: string): Promise<ComponentDiscoveryResult>;
+//# sourceMappingURL=discover.d.ts.map

package/dist/components/discover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../../src/components/discover.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAMH,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAe,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AAE1D,2EAA2E;AAC3E,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,SAAS,CAAC;IACrB,0HAA0H;IAC1H,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,wBAAwB;IACvC,0GAA0G;IAC1G,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IAC7C,oDAAoD;IACpD,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,MAAM,EAAE,cAAc,EAAE,CAAC;CAC1B;AAuDD;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,CAAC,CA+CxF"}

package/dist/components/driver-output.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Renderers for `chant run --components` (#585) — the interpret driver's CLI
+ * output. Mirrors `../op/local-output.ts`'s `renderHuman`/`renderJson` pair
+ * for Ops: both consume the same `DriverRunResult` (`./driver.ts`);
+ * `renderDriverHuman` is the default (logs to stderr), `renderDriverJson`
+ * prints the machine-readable result as JSON on stdout and nothing else.
+ */
+import type { DriverRunResult } from "./driver.js";
+type Writer = (line: string) => void;
+/**
+ * Render an interpret-driver run result as human-readable progress. Defaults
+ * to stderr so stdout stays clean for piping (the `--json` renderer owns
+ * stdout). Groups records by component, then by phase, matching the driver's
+ * own wave/phase/step nesting.
+ */
+export declare function renderDriverHuman(result: DriverRunResult, write?: Writer): void;
+/** Render an interpret-driver run result as JSON on stdout (and nothing else on stdout). */
+export declare function renderDriverJson(result: DriverRunResult, write?: Writer): void;
+export {};
+//# sourceMappingURL=driver-output.d.ts.map

package/dist/components/driver-output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver-output.d.ts","sourceRoot":"","sources":["../../src/components/driver-output.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAoB,MAAM,UAAU,CAAC;AAElE,KAAK,MAAM,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;AAsBrC;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,eAAe,EAAE,KAAK,GAAE,MAAe,GAAG,IAAI,CA2BvF;AAED,4FAA4F;AAC5F,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,eAAe,EAAE,KAAK,GAAE,MAAe,GAAG,IAAI,CAEtF"}