@intentius/chant 0.124.51 → 0.124.54

package/src/cloud-lister/transport.ts

@@ -0,0 +1,118 @@
+/**
+ * behold#1029: the lister's one way onto the network.
+ *
+ * {@link Transport.send} runs, in order: the read-only check
+ * (packages/core/src/cloud-lister/guard.ts), the origin pin, then the fetcher. The pin is
+ * the goal's never-public-cloud rule in code: when a run names its own
+ * endpoint (an emulator), every call must go to that endpoint's origin, so a
+ * URL built wrong can never reach a public cloud host. A test passes its own
+ * {@link Fetcher}; production uses {@link nodeFetcher}, which is node's own
+ * http/https so a cluster's CA and client certificate can be passed
+ * explicitly.
+ */
+
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { assertReadCall, type WireCall } from "./guard";
+
+export interface WireResponse {
+  status: number;
+  headers: Record<string, string>;
+  body: string;
+}
+
+/** TLS material for one target, passed explicitly; nothing is read from the environment. */
+export interface TlsOptions {
+  ca?: string;
+  cert?: string;
+  key?: string;
+  /** Only for a local emulator whose certificate the caller chose not to pin. */
+  insecureSkipVerify?: boolean;
+}
+
+export type Fetcher = (call: WireCall, tls: TlsOptions | undefined) => Promise<WireResponse>;
+
+export class OriginRefused extends Error {
+  constructor(readonly url: string, readonly allowed: string) {
+    super(`chant's cloud lister refused ${url}: this run is pinned to ${allowed}`);
+    this.name = "OriginRefused";
+  }
+}
+
+export interface TransportOptions {
+  fetcher?: Fetcher;
+  /** When set, every call must go to this origin (an explicit endpoint). */
+  pinnedOrigin?: string;
+  tls?: TlsOptions;
+  /** Called with each call that passed the guard, before it is sent (tests record with it). */
+  onSend?: (call: WireCall, operation: string) => void;
+}
+
+export class Transport {
+  readonly calls: Array<{ call: WireCall; operation: string }> = [];
+  private readonly fetcher: Fetcher;
+
+  constructor(private readonly options: TransportOptions = {}) {
+    this.fetcher = options.fetcher ?? nodeFetcher;
+  }
+
+  async send(call: WireCall): Promise<WireResponse> {
+    const operation = assertReadCall(call);
+    if (this.options.pinnedOrigin !== undefined) {
+      const origin = new URL(call.url).origin;
+      if (origin !== new URL(this.options.pinnedOrigin).origin) throw new OriginRefused(call.url, this.options.pinnedOrigin);
+    }
+    this.calls.push({ call, operation });
+    this.options.onSend?.(call, operation);
+    return this.fetcher(call, this.options.tls);
+  }
+}
+
+/** node's http/https, one request, the whole body read as text. */
+export const nodeFetcher: Fetcher = (call, tls) =>
+  new Promise((resolve, reject) => {
+    const url = new URL(call.url);
+    const secure = url.protocol === "https:";
+    const send = secure ? httpsRequest : httpRequest;
+    const req = send(
+      url,
+      {
+        method: call.method,
+        headers: call.headers,
+        ...(secure && tls
+          ? {
+              ...(tls.ca !== undefined ? { ca: tls.ca } : {}),
+              ...(tls.cert !== undefined ? { cert: tls.cert } : {}),
+              ...(tls.key !== undefined ? { key: tls.key } : {}),
+              ...(tls.insecureSkipVerify ? { rejectUnauthorized: false } : {}),
+            }
+          : {}),
+        timeout: 60_000,
+      },
+      (res) => {
+        const chunks: Buffer[] = [];
+        res.on("data", (c: Buffer) => chunks.push(c));
+        res.on("end", () => {
+          const headers: Record<string, string> = {};
+          for (const [k, v] of Object.entries(res.headers)) {
+            if (v !== undefined) headers[k] = Array.isArray(v) ? v.join(", ") : v;
+          }
+          resolve({ status: res.statusCode ?? 0, headers, body: Buffer.concat(chunks).toString("utf8") });
+        });
+        res.on("error", reject);
+      },
+    );
+    req.on("timeout", () => req.destroy(new Error(`timed out: ${call.method} ${call.url}`)));
+    req.on("error", reject);
+    if (call.body !== undefined) req.write(call.body);
+    req.end();
+  });
+
+/** The body parsed as JSON, or `undefined` when it is not JSON. */
+export function jsonBody(res: WireResponse): unknown {
+  try {
+    return res.body === "" ? undefined : JSON.parse(res.body);
+  } catch {
+    return undefined;
+  }
+}

package/src/cloud-lister/types.ts

@@ -0,0 +1,135 @@
+/**
+ * behold#1029: the cloud lister's output, the "listing result" source shape
+ * of behold#1025's design (https://github.com/INTENTIUS/behold/issues/1025#issuecomment-6430966093,
+ * ruled in #issuecomment-6431259469).
+ *
+ * The ruling puts the index schema's TypeScript types in chant core (Q5), and
+ * chant's `typeListing` (../lifecycle/type-listing.ts, chant#4521) turns a
+ * `ListingResult` into an `IndexDocument`. type-listing.ts reads the shape
+ * loosely (an optional id and facts, any source name); this module is the
+ * lister's exact output, and ../lifecycle/cloud-index.ts hands one to the
+ * other, so the type checker holds them together.
+ *
+ * What the lister fills, per the design and chant#4520's ruled `EngineFacts`:
+ *
+ *  - every resource gets the path-style id the ruling names (Q2),
+ *    `<substrate>/<scopeId>/<location>/<listedType>/<nativeId>` (packages/core/src/cloud-lister/ids.ts);
+ *  - `facts` carries only what a cloud listing can read: `markers` (from tags
+ *    and labels), `cloudIds` and `observedAt`. `ownership`, `ownedBy` and
+ *    `recordVersions` stay absent, because they are relative to an estate or
+ *    stack and a record the lister never reads;
+ *  - properties, tags and every string under them are masked before the
+ *    result exists (packages/core/src/cloud-lister/mask.ts).
+ */
+
+import type { UnobservedReason } from "../observation";
+
+/** The four substrates the lister reads, one per run (ruling Q6). */
+export type Substrate = "aws" | "azure" | "gcp" | "kubernetes";
+
+/** A tag or label filter: every pair must match. */
+export type TagFilter = Readonly<Record<string, string>>;
+
+/**
+ * One run's scope (ruling Q6): one substrate and one account, subscription,
+ * project or cluster, with every location and type the flags name. `"*"`
+ * means every location or every type the inventory API returns.
+ */
+export interface CloudScope {
+  substrate: Substrate;
+  /** AWS account id, Azure subscription id, GCP project id, or a cluster name. */
+  scopeId: string;
+  /** Regions or locations (Kubernetes: namespaces), sorted and deduplicated, or `"*"`. */
+  locations: readonly string[] | "*";
+  /** Types as the inventory API names them, sorted and deduplicated, or `"*"`. */
+  types: readonly string[] | "*";
+  tagFilter?: TagFilter;
+}
+
+/**
+ * What was looked at, per type and location (#1025 "Coverage"). A
+ * (type, location) with no entry is not observed. `"*"` in `listedType` or
+ * `location` means "every": a reader that does not know the wildcard compares
+ * it as a literal, matches nothing, and so reads the entity as not observed,
+ * which is the safe direction.
+ */
+export interface CoverageEntry {
+  listedType: string;
+  location: string;
+  verdict: "listed" | UnobservedReason;
+  detail?: string;
+}
+
+/** Why something was not listed, said once (#1029: "a type it cannot list goes in the notes"). */
+export interface IndexNote {
+  code:
+    | "no-lister"        // the inventory API cannot list this type
+    | "needs-parent"     // the type lists only under a parent identifier
+    | "api-disabled"     // GCP: Cloud Asset API is off on the project; nothing was enabled
+    | "read-failed"      // a call failed after retries
+    | "no-credentials"   // the call was refused for its credentials
+    | "default-types"    // AWS with types "*": a fixed default set was listed
+    | "tag-filter";      // a tag filter narrows every entry to `filtered`
+  message: string;
+  listedType?: string;
+  location?: string;
+  /** A command the person can run themselves (never run by the lister). */
+  command?: string;
+}
+
+/**
+ * A cloud id, kinds as chant#4520 ruled them (`EngineFacts.cloudIds`):
+ * `arn` for an ARN, `import-id` for Cloud Control's identifier (what
+ * `declaredIdentifier` builds and an import takes), `provider-id` for an ARM
+ * id (as returned and once lowercased, since Resource Graph lowercases) or a
+ * GCP asset name, `self-link` for a GCP selfLink, `k8s-uid` for a
+ * Kubernetes UID.
+ */
+export interface CloudId {
+  kind: "import-id" | "arn" | "provider-id" | "self-link" | "k8s-uid";
+  value: string;
+}
+
+/** chant#4520's `EngineFacts.markers`, as read off the live object's tags or labels. */
+export interface MarkerFact {
+  owner?: string;
+  address?: string;
+  encoding: "plain" | "escaped" | "digest";
+  source: "live";
+}
+
+/** The facts a cloud listing can supply (ruling Q1: one nested object). */
+export interface ListedFacts {
+  markers?: MarkerFact;
+  cloudIds: CloudId[];
+  observedAt: string;
+}
+
+/** One listed object (#1025 `ListedResource`, plus the ruled id and facts). */
+export interface ListedResource {
+  /** `<substrate>/<scopeId>/<location>/<listedType>/<nativeId>` (ruling Q2). */
+  id: string;
+  listedType: string;
+  location: string;
+  /** Cloud Control `Identifier`, the ARM id, the asset `name`, `namespace/name` or `name` for Kubernetes. */
+  nativeId: string;
+  cloudIds: CloudId[];
+  tags: Record<string, string>;
+  /** As returned, unnormalized, already masked. */
+  properties: Record<string, unknown>;
+  /** When the call that returned it answered. */
+  observedAt: string;
+  facts: ListedFacts;
+}
+
+/** The lister's whole output for one run (#1025 `ListingResult`). */
+export interface ListingResult {
+  listing: "v1";
+  source: { name: "chant-lister"; version: string };
+  scope: CloudScope;
+  startedAt: string;
+  completedAt: string;
+  resources: ListedResource[];
+  coverage: CoverageEntry[];
+  notes: IndexNote[];
+}

package/src/components/capability-plugin-loader.ts

@@ -27,6 +27,7 @@ import type { CapabilityPlugin } from "./capability-plugin";
 import { isCapabilityPlugin } from "./capability-plugin";
 import { starterCapabilityPlugin } from "./starter-plugin";
 import { isRegistryBackendConsumer, type RegistryLoginBackend } from "./verbs/publish-image";
+import { isEngineOutputSourceConsumer, type EngineOutputSource } from "./verbs/member-outputs";
 import { isStorageBackendConsumer, type ArtifactStorageBackend } from "./verbs/publish-artifact";
 
 /** Thrown when a dynamically-imported capability package does not satisfy `CapabilityPlugin` — the "malformed capability package" case #559 asks doctor/validation to detect. */
@@ -171,6 +172,8 @@ export function registerCapabilityPlugins(
   for (const plugin of plugins) backends.push(...(plugin.registryBackends?.() ?? []));
   const storage: ArtifactStorageBackend[] = [];
   for (const plugin of plugins) storage.push(...(plugin.storageBackends?.() ?? []));
+  const engines: EngineOutputSource[] = [];
+  for (const plugin of plugins) engines.push(...(plugin.engineOutputSources?.() ?? []));
 
   for (const plugin of plugins) {
     for (const capability of plugin.capabilities()) {
@@ -179,6 +182,7 @@ export function registerCapabilityPlugins(
       let bound = capability;
       if (isRegistryBackendConsumer(bound)) bound = bound.withRegistryBackends(backends) as typeof bound;
       if (isStorageBackendConsumer(bound)) bound = bound.withStorageBackends(storage) as typeof bound;
+      if (isEngineOutputSourceConsumer(bound)) bound = bound.withEngineOutputSources(engines) as typeof bound;
       registry.register(bound);
     }
   }

package/src/components/capability-plugin.ts

@@ -34,6 +34,7 @@ import { fileURLToPath } from "node:url";
 import type { Capability } from "./capability";
 import type { RegistryLoginBackend } from "./verbs/publish-image";
 import type { ArtifactStorageBackend } from "./verbs/publish-artifact";
+import type { EngineOutputSource } from "./verbs/member-outputs";
 
 /**
  * Manifest for a packaged capability plugin — the capability-side analogue
@@ -104,6 +105,15 @@ export interface CapabilityPlugin {
    */
   storageBackends?(): ArtifactStorageBackend[];
 
+  /**
+   * Engine output sources this plugin contributes to core's `member-outputs`
+   * verb (#4455): how another workspace member's outputs are read, applied
+   * and planned, for the member kinds the source names (terraform:
+   * `choudoufu`; pulumi: `pulumi`). Like `registryBackends`, not capabilities, so several
+   * engines may contribute.
+   */
+  engineOutputSources?(): EngineOutputSource[];
+
   /** Optional initialization hook, called once after load (mirrors `LexiconPlugin.init`). */
   init?(): void | Promise<void>;
 }

package/src/components/capability.ts

@@ -12,6 +12,7 @@
  * Cloud implementations are a later phase (see epic #551, issue #554).
  */
 
+import type { PlanShape } from "./covered-round";
 import type { ReleaseIdentity } from "../telemetry-attribution";
 import type { ChangeSetPart } from "../change-set";
 
@@ -117,6 +118,14 @@ export interface CapabilityPlan {
    * targeted plan covers that plan and no other.
    */
   targets?: string[];
+  /**
+   * What the plan does, without values (#4419): the resources it touches,
+   * their actions and replacement, and the inputs it was made without. A
+   * pull request's apply compares the shape of a plan made after an upstream
+   * applied with this one (`coveredRound`) to decide whether the first
+   * approval covers it. Absent, core derives the shape from `changeSet`.
+   */
+  shape?: PlanShape;
 }
 
 /**
@@ -199,6 +208,235 @@ export interface Capability<In = unknown, Out = unknown> {
    * why. Unset refuses too, with a reason that names the verb.
    */
   readonly targets?: TargetSupport;
+  /**
+   * Optional (#4435, ws-107): why this capability will not plan and apply
+   * `members` as one group, or `undefined` when it will. Core asks before
+   * anything is planned, so the answer must come from the declaration and
+   * the files alone, never from a plan. A fallback with
+   * {@link GroupFallback.drop} leaves only those members out: core forms
+   * the group again from the rest and asks again (#4419 ruling 1). A
+   * capability with `planGroup` and no `groupFallback` takes every group
+   * core forms.
+   */
+  groupFallback?(ctx: GroupContext, members: readonly GroupMember<In>[]): Promise<GroupFallback | undefined>;
+  /**
+   * Optional (#4447): reads between this capability's components that core
+   * cannot see in their declarations, such as a Terraform root's
+   * `terraform_remote_state` block. Core asks once per capability, before
+   * groups form, with every component of the change whose step this
+   * capability takes (`ctx.components` in plan order, no `input`), and adds
+   * each read to the reads it joins, orders and splits groups by, and to
+   * the group reads the report names. The answer must come from the
+   * declaration and the files alone. A read naming a component outside
+   * `members` is ignored; a throw counts as no reads.
+   */
+  groupReads?(ctx: GroupContext, members: readonly GroupMember<In>[]): Promise<ReportedGroupRead[]>;
+  /**
+   * Optional (#4466): reads between this capability's steps that sit in the
+   * files a step names rather than in its wiring, such as a CloudFormation
+   * template's `Fn::ImportValue` of an export another stack's template
+   * declares. Core asks once, after discovery and before the order is
+   * derived, with every step of this kind in the project. Each read becomes
+   * a `stackOutput()` reference at {@link DeclaredRead.at} in the reader's
+   * step and a `dependsOn` on the upstream, so it orders the reader after
+   * the upstream, is listed under `unknownInputs` while the upstream's plan
+   * cannot say the value, and holds the reader for a round, like a read the
+   * declaration states. A place the declaration already fills is left as it
+   * is. The answer must come from the declaration and the files alone; a
+   * throw counts as no reads.
+   */
+  declaredReads?(ctx: DeclaredReadsContext, members: readonly DeclaredReadMember[]): Promise<DeclaredRead[]> | DeclaredRead[];
+  /**
+   * Optional (#4435, ws-107): plan `members` as one, in one call. Declared
+   * together with `runGroup`; a capability with only one of the two never
+   * gets a group. Throwing makes every member plan-failed.
+   */
+  planGroup?(ctx: GroupContext, members: readonly GroupMember<In>[]): Promise<CapabilityGroupPlan>;
+  /**
+   * Optional (#4435, ws-107): apply the group `planGroup` planned, in one
+   * call, and say how each member's part ended. It should not throw: a throw
+   * reads as every member `failed`, or every member `not-started` when the
+   * error is a moved plan ({@link isPlanMovedError}).
+   */
+  runGroup?(ctx: GroupContext, run: GroupRun, members: readonly GroupMember<In>[]): Promise<CapabilityGroupOutcome>;
+}
+
+/**
+ * What a group's calls share (ws-107): the run's environment and variables,
+ * and the group's components in apply order. Each member's own context is
+ * {@link GroupMember.ctx}.
+ */
+export interface GroupContext {
+  env: string;
+  vars?: Record<string, unknown>;
+  /** The group's components, upstreams first. */
+  components: string[];
+}
+
+/**
+ * A read of one group member's output by another (ws-107). Core leaves the
+ * value out of the reader's `input` (it is `undefined` at `at`) and the
+ * capability wires it inside its own apply.
+ */
+export interface GroupRead {
+  /** Where in the reader's step input the value goes, as a JSON Pointer. */
+  at: string;
+  /** `<component>.<output>`, as `PrMember.reads` and `unknownInputs` name it. */
+  ref: string;
+  /** The member whose output it is. */
+  component: string;
+  output: string;
+}
+
+/**
+ * A read of one component by another that a capability reports through
+ * `groupReads` (#4447), with no place in the reader's step input.
+ */
+export interface ReportedGroupRead {
+  /** The component that reads. */
+  reader: string;
+  /** The component whose output it reads. */
+  upstream: string;
+  /** The read as the report names it, e.g. `data.terraform_remote_state.network`. */
+  ref: string;
+  /**
+   * The upstream output read, when the capability knows it. Without it the
+   * read counts as known at plan only when the upstream's plan knows every
+   * output it names.
+   */
+  output?: string;
+}
+
+/** What `declaredReads` is asked with (#4466). */
+export interface DeclaredReadsContext {
+  /** The project root, which a step's relative file paths are read against. */
+  root: string;
+}
+
+/** One step a capability's `declaredReads` is asked about (#4466). */
+export interface DeclaredReadMember {
+  component: string;
+  /** Which of the component's steps of this kind, counting from 0 in declaration order. */
+  index: number;
+  /** The step as declared, without `kind`, wiring unresolved. */
+  step: Record<string, unknown>;
+}
+
+/**
+ * A read `declaredReads` found (#4466): `reader`'s step `index` reads
+ * `upstream`'s output `output`. Core puts `{ stackOutput: { stack:
+ * upstream, name: output } }` at `at` in that step, so the read is named
+ * `<upstream>.<output>` wherever reads are.
+ */
+export interface DeclaredRead {
+  reader: string;
+  /** The reader's step, as {@link DeclaredReadMember.index}. Default 0. */
+  index?: number;
+  upstream: string;
+  output: string;
+  /** Where in the reader's step the reference goes, as a JSON Pointer. */
+  at: string;
+}
+
+/** One component of a group, as core hands it to the capability (ws-107). */
+export interface GroupMember<In = unknown> {
+  component: string;
+  /** The component's one step as declared, without `kind`, wiring unresolved. */
+  step: Record<string, unknown>;
+  /**
+   * The step's input resolved against the outputs from outside the group.
+   * Each {@link GroupRead} is `undefined` here. Absent in `groupFallback`,
+   * which is asked before any output is read.
+   */
+  input?: In;
+  /** The member's reads of other members, sorted by `ref`. */
+  reads: GroupRead[];
+  /**
+   * The component's `dependsOn` as declared (#4447): an order with no read,
+   * which a capability that applies the group in one call has to keep or
+   * refuse.
+   */
+  dependsOn?: string[];
+  /**
+   * The member's own context: `component`, `targets`, `carried` and `carry`
+   * as for a single step. `unresolvedInputs` names only components outside
+   * the group. In `runGroup`, `plans` holds this member's plan.
+   */
+  ctx: DeployContext;
+}
+
+/**
+ * Why a set of components does not run as one group (ws-107). `kind` is a
+ * short stable word the report keys on; `reason` is one line for a person.
+ * Core's own kinds are `steps`, `split` and `cycle`; a capability names its
+ * own. A capability's `off` is recorded and not printed in the note.
+ *
+ * Without `drop`, the fallback is every member's and the group dissolves.
+ * With `drop`, only the members it names leave, each with its own `kind`
+ * and `reason` or else the fallback's; core forms the group again from the
+ * rest by its own rules (`split`, `steps`, `cycle`, and a set of one is no
+ * group) and asks again for each set that changed (#4419 ruling 1). A
+ * `drop` that names no member of the group dissolves it.
+ */
+export interface GroupFallback {
+  kind: string;
+  reason: string;
+  /** The members to leave out, when not the whole group. */
+  drop?: GroupDrop[];
+}
+
+/** A member a {@link GroupFallback} leaves out of its group (#4419 ruling 1). */
+export interface GroupDrop {
+  component: string;
+  /** Default: the fallback's `kind`. */
+  kind?: string;
+  /** Default: the fallback's `reason`. */
+  reason?: string;
+}
+
+/** What `planGroup` returns (ws-107). */
+export interface CapabilityGroupPlan {
+  /**
+   * One plan per member, by component: what `plan` would give for that
+   * member, with `planDigest` before the group is folded in. Core folds the
+   * group digest into each `planDigest` and its change-set part. `artifact`
+   * on these is ignored; the group's artifact is below.
+   */
+  members: Record<string, CapabilityPlan>;
+  /** The capability's digest of what the group adds to its members' plans. */
+  digest: string;
+  /** Handed back to `runGroup` in {@link GroupRun}. Core never reads it. */
+  artifact?: unknown;
+}
+
+/** What core hands `runGroup` (ws-107): the plan that was approved. */
+export interface GroupRun {
+  artifact?: unknown;
+  /** The group digest core bound: the capability's digest with the members folded in. */
+  digest: string;
+  /** Each member's plan as bound into the change set, by component. */
+  plans: Record<string, CapabilityPlan>;
+}
+
+/**
+ * How one member's part of a group apply ended (ws-107). `partial`: some of
+ * its planned changes applied. `not-started`: the apply stopped before its
+ * part began. `no-changes`: it planned none.
+ */
+export type GroupMemberStatus = "applied" | "partial" | "failed" | "not-started" | "no-changes";
+
+export interface GroupMemberOutcome {
+  status: GroupMemberStatus;
+  /** What the member exposes now, as `run`'s outputs: set for `applied` and `no-changes`. */
+  outputs?: Record<string, unknown>;
+  error?: string;
+}
+
+/** What `runGroup` returns (ws-107): every member's outcome, by component. */
+export interface CapabilityGroupOutcome {
+  members: Record<string, GroupMemberOutcome>;
+  /** An error no member's part names. */
+  error?: string;
 }
 
 /** A capability's relationship to rollback — see `Capability.rollbackPolicy`. */