@intentius/chant 0.124.12 → 0.124.14

package/dist/components/pilots/dynamodb.pilot.js

@@ -0,0 +1,51 @@
+/**
+ * Pilot: DynamoDB table (#555, epic #551).
+ *
+ * Exercises the sticky-apply axis: `cfn-deploy` carries declarative safety
+ * options — `onReplace: "block"` refuses a changeset that would replace the
+ * table (losing data) rather than update it in place, and `stageGsi: true`
+ * stages a GSI change (add → backfill → remove) instead of an in-place
+ * replace. That stickiness lives inside the `cfn-deploy` capability, exposed
+ * as options, not scripted per component — see
+ * capabilities.mdx#stickiness-lives-in-the-capability. `infra` archetype: no
+ * build, apply → verify only. Verify fans out in parallel: the stack wait and
+ * a GSI backfill migration have no ordering dependency on each other.
+ *
+ * The JSON projection of this pilot is authoritative at
+ * ../__fixtures__/dynamodb-infra.json (already schema-validated by
+ * component-schema.test.ts) — this module is the real typed `Component`
+ * authoring form (#560, ../component.ts) that composes to that same
+ * document; see ./pilots.test.ts, which asserts the two never diverge.
+ */
+import { phase } from "../component.js";
+// `cfn-deploy`'s safety fields, kept as a plain literal here: the pilot is
+// agnostic component *data* naming the `cfn-deploy` kind, so it does not import
+// the AWS capability's types (those live in the aws lexicon now). The `onReplace`
+// value must match `cfn-deploy`'s `CfnReplacePolicy` union.
+const cfnSafetyOptions = {
+    onReplace: "block",
+    stageGsi: true,
+};
+export const ordersTable = {
+    name: "orders-table",
+    archetype: "infra",
+    dependsOn: [],
+    deploy: [
+        phase("Apply", [
+            { kind: "cfn-deploy", template: "archive:orders-table.template.json", ...cfnSafetyOptions },
+        ]),
+        phase("Verify", [
+            { kind: "wait-for-stack", stack: "orders-table" },
+            {
+                kind: "run-migration",
+                script: "archive:migrations/backfill-gsi.sql",
+                // A GSI backfill has no clean inverse: once items are re-projected
+                // onto the new index, "rolling back" the migration would mean a
+                // second migration to undo it, not a mechanical compensation the
+                // capability could run automatically — see COMP003
+                // (lint-rules/composition.mdx) for the opt-out convention.
+                noRollback: "GSI backfill is forward-only; undoing it needs a second, hand-written migration, not automatic compensation",
+            },
+        ], { parallel: true }),
+    ],
+};

package/dist/components/pilots/jar-emr.pilot.js

@@ -0,0 +1,65 @@
+/**
+ * Pilot pair: JAR producer -> EMR consumer, cross-component artifact outputs
+ * (#561, epic #551).
+ *
+ * This is the epic's worked example for cross-component wiring (#551
+ * §"Cross-component outputs", docs/components/composition-and-wiring.mdx
+ * §"Cross-component outputs"): a **producer-library** component
+ * (`jar-lib`) that only builds and publishes an artifact — no apply, no
+ * service — paired with an **infra** consumer (`emr-job`) that submits an
+ * EMR job run against the producer's published S3 URI.
+ *
+ * The wiring itself needs no new machinery: `dependsOn: ["jar-lib"]` orders
+ * the producer first (`resolveComponentGraph`, ../driver.ts), and
+ * `"@jar-lib.publish.uri"` is the same `@<component>.publish.uri|digest|key`
+ * reference form `resolveWiring` (../driver.ts) already resolves generically
+ * from `componentOutputs`, which `runComponentDeploy` already populates from
+ * any step whose output carries `uri`/`digest`/`key` (`findPublishOutput`) —
+ * both landed with #556/#560 and are exercised by ../driver.test.ts's
+ * "wires a cross-component artifact reference" case. What #561 actually adds
+ * is: this pair authored as real typed `Component`s (rather than only the
+ * hand-written JSON fixtures), and a real `emr-start-job-run`/`wait-job`
+ * capability implementation (../verbs/job-submission.ts,
+ * ../verbs/wait-verify.ts) so the pair runs to completion against a mocked
+ * `CloudExecutor` instead of throwing `CapabilityNotImplementedError`.
+ *
+ * The JSON projections of these two components are authoritative at
+ * ../__fixtures__/jar-lib-producer.json and
+ * ../__fixtures__/emr-job-consumer.json (pre-existing, from #560) — this
+ * module is the real typed `Component` authoring form that composes to those
+ * same documents; see ./pilots.test.ts, which asserts the two never diverge.
+ */
+import { phase } from "../component.js";
+/** Producer: a JAR built from a Maven project, published to S3. Publish-only deploy — no apply phase at all, the defining shape of the `producer-library` archetype. */
+export const jarLib = {
+    name: "jar-lib",
+    archetype: "producer-library",
+    dependsOn: [],
+    build: { kind: "jvm-build", context: ".", into: "archive" },
+    deploy: [
+        // → @jar-lib.publish.uri / @jar-lib.publish.digest, resolved by the graph
+        // for any downstream consumer — never known by this component itself.
+        phase("Publish", [{ kind: "publish-artifact", from: "archive", to: "$env.s3" }]),
+    ],
+};
+/** Consumer: an EMR job run reading the producer's published JAR by S3 URI. `dependsOn: ["jar-lib"]` orders the producer first; the graph resolves the reference into the Submit step. */
+export const emrJob = {
+    name: "emr-job",
+    archetype: "infra",
+    dependsOn: ["jar-lib"],
+    deploy: [
+        phase("Submit", [
+            {
+                kind: "emr-start-job-run",
+                jar: "@jar-lib.publish.uri",
+                args: ["--input", "$env.inputPath", "--output", "$env.outputPath"],
+                // A submitted EMR job run has no automatic "undo": stopping a
+                // running/completed job is not the same as reverting whatever it
+                // already wrote, so compensation is a human/runbook decision, not a
+                // mechanical capability rollback — see COMP003 (lint-rules/composition.mdx).
+                noRollback: "a submitted job run has no automatic undo; cancelling it does not revert data it already wrote",
+            },
+        ]),
+        phase("Verify", [{ kind: "wait-job", runId: "@Submit.runId" }]),
+    ],
+};

package/dist/components/pilots/lambda.pilot.js

@@ -0,0 +1,52 @@
+/**
+ * Pilot: image-processor Lambda (#558, epic #551).
+ *
+ * The fourth, deliberately different component #558 asks for, added to prove
+ * the sprawl metric holds beyond the original three pilots (#555): a
+ * container-image AWS Lambda function. `service` archetype, same as ALB/ECS,
+ * but a genuinely different shape on two axes at once:
+ *
+ *  - **apply target**: no CloudFormation stack at all — `lambda-deploy`
+ *    updates a function's code directly (`UpdateFunctionCode` +
+ *    `PublishVersion` + `UpdateAlias`), never a `cfn-deploy` changeset. Every
+ *    prior pilot's apply step was `cfn-deploy`; this is the first pilot whose
+ *    Apply phase contains none.
+ *  - **verify shape**: a single `wait-for-stack`-free health check
+ *    (`health-gate` against the function's alias URL) rather than an ECS
+ *    steady-state poll or a Neo4j quorum probe.
+ *
+ * Reuses `docker-build` + `publish-image` unchanged from the ALB/ECS pilot's
+ * axis (build + promote-by-digest is identical for a container-image Lambda:
+ * https://docs.aws.amazon.com/lambda/latest/dg/images-create.html) — the
+ * `imageRef`/`codeRef` wiring (`@Publish.digest` / `@Publish.uri`) is the same
+ * `@Phase.field` prior-step reference form every pilot already uses. The only
+ * capability this component needed that didn't already exist is `lambda-deploy`
+ * (../verbs/apply.ts) — one new capability, exactly the sprawl metric's bound
+ * for "genuinely novel"; see ../SPRAWL-VALIDATION.md for the full accounting.
+ *
+ * The JSON projection of this pilot is authoritative at
+ * ../__fixtures__/lambda-image-processor.json — this module is the real
+ * typed `Component` authoring form (#560, ../component.ts) that composes to
+ * that same document; see ./pilots.test.ts, which asserts the two never
+ * diverge.
+ */
+import { phase } from "../component.js";
+export const imageProcessor = {
+    name: "image-processor-lambda",
+    archetype: "service",
+    dependsOn: [],
+    build: { kind: "docker-build", context: ".", into: "archive" },
+    deploy: [
+        phase("Publish", [{ kind: "publish-image", from: "archive", to: "$env.registry" }]),
+        phase("Apply", [
+            { kind: "lambda-deploy", functionName: "image-processor", codeRef: "@Publish.uri", alias: "live" },
+        ]),
+        phase("Verify", [{ kind: "health-gate", path: "@Apply.functionArn" }]),
+    ],
+    // No native rollback on lambda-deploy for an alias already repointed at a bad
+    // version — same "no automatic capability rollback" story as the ALB/ECS
+    // pilot's ecs-update-service, except here the capability itself supplies the
+    // best-effort restore (see createLambdaDeployCapability's rollback in
+    // ../verbs/apply.ts) rather than the component declaring its own phase, so
+    // no component-level `rollback` field is needed here.
+};

package/dist/components/pilots/neo4j-fanout.pilot.js

@@ -0,0 +1,68 @@
+/**
+ * Pilot: Neo4j per-instance fan-out cluster (#555, epic #551).
+ *
+ * Exercises the fan-out axis: one component composing N per-instance
+ * mini-compositions (`cfn-deploy` + `code-deploy` + a health wait), seeded
+ * first, then rolled through the remaining instances one at a time behind a
+ * `wait-cluster-healthy` gate. See composition-and-wiring.mdx#fan-out-is-composition-not-orchestrator-knowledge.
+ *
+ * The JSON projection of this pilot is authoritative at
+ * ../__fixtures__/neo4j-fanout.json (already schema-validated by
+ * component-schema.test.ts) — this module is the real typed `Component`
+ * authoring form (#560, ../component.ts) that composes to that same
+ * document; see ./pilots.test.ts, which asserts the two never diverge.
+ */
+import { gate, phase } from "../component.js";
+const SEED = {
+    index: 0,
+    label: "Seed",
+    template: "archive:neo4j-az0-0.template.json",
+    health: { size: 1 },
+};
+/**
+ * Followers roll one at a time after the seed is healthy. Node 1 carries an
+ * explicit approval gate — composed the same way any other step is, never as
+ * driver knowledge — so a human confirms the seed before the cluster starts
+ * fanning out further; later nodes roll unattended once that first rollout is
+ * trusted.
+ */
+const FOLLOWERS = [
+    {
+        index: 1,
+        label: "Node 1",
+        template: "archive:neo4j-1.template.json",
+        health: { quorum: true },
+        approval: {
+            gate: "approve-neo4j-node-1",
+            description: "Confirm the seed node is healthy before rolling to node 1",
+            timeout: "24h",
+        },
+    },
+    {
+        index: 2,
+        label: "Node 2",
+        template: "archive:neo4j-2.template.json",
+        health: { quorum: true },
+    },
+];
+/** Build one instance's mini-composition phase — the unit that repeats N times for an N-node cluster. */
+function instancePhase(instance) {
+    const steps = [
+        ...(instance.approval ? [gate(instance.approval.gate, instance.approval)] : []),
+        { kind: "cfn-deploy", template: instance.template },
+        { kind: "code-deploy", instance: instance.index, revision: "@Seed.templateUri" },
+        { kind: "wait-cluster-healthy", ...instance.health },
+    ];
+    return phase(instance.label, steps);
+}
+export const neo4jCluster = {
+    name: "neo4j-cluster",
+    archetype: "infra",
+    dependsOn: [],
+    deploy: [
+        instancePhase(SEED),
+        // Array.map over instance configs — the fan-out is authored here, in the
+        // composition, never known by the orchestrator (composition-and-wiring.mdx).
+        ...FOLLOWERS.map(instancePhase),
+    ],
+};

package/dist/components/pilots/project.js

@@ -0,0 +1,12 @@
+/**
+ * Re-exports the real `projectToJson` (#560, ../component.ts) under the
+ * pilots' original import path. Prior to #560, this module held its own
+ * "intentionally dumb" projection over the stopgap `authoring-shape.ts`
+ * (#555); now that the real typed `Component` authoring form exists, its
+ * `projectToJson` (which also fills in `archetype` via `inferArchetype` when
+ * a pilot doesn't set one explicitly) is the single implementation. Kept as a
+ * re-export, rather than inlining `../component`'s import into every pilot
+ * test, so `./pilots.test.ts`/`./pilots-e2e.test.ts`/`../driver.test.ts`
+ * don't need their import paths touched by this migration.
+ */
+export { projectToJson } from "../component.js";

package/dist/components/pr-pipeline.js

@@ -0,0 +1,134 @@
+/**
+ * The jobs of a generated pull-request pipeline (#3183): a plan job on every
+ * pull request and an apply job on every push to the target branch.
+ *
+ * Each forge's generator (the github, gitlab and forgejo lexicons) adds its
+ * own triggers, permissions and artifact handling; the commands and the
+ * values they read from the forge live here so the three cannot disagree.
+ *
+ * - The plan job runs `chant components pr-plan` against the pull request's
+ *   target commit. It posts the note and the `chant/plan` status and writes
+ *   nothing to `chant/lifecycle`, since it runs the pull request's code.
+ * - The apply job runs `chant components pr-apply` against the commit the
+ *   push replaced, finds the pull request that merged the pushed commit
+ *   through the forge, and applies only when an approval stands for the
+ *   digest it plans. With `requireReview` (the default) the approver must
+ *   also have approved the pull request on the forge. It needs write access
+ *   to `chant/lifecycle`, to record the pending fact when the gate stops it.
+ *   One apply runs at a time per environment.
+ *
+ * The apply job passes `--resume` (#3543) with a record path outside the
+ * report directory, and each forge keeps that file in its CI cache under a
+ * key that names the environment, the member and the pushed commit
+ * (`prApplyRecordKey`). A re-run of a failed apply job restores it and
+ * finishes the approved set under the same approval; the record itself is
+ * checked against the pull request's gate, the commit, the selection and
+ * the ledger before it counts (`pr-apply --resume`, #3464).
+ *
+ * Measuring the push from the commit it replaced works for merge commits,
+ * squash merges and rebase merges alike, and every job measures from the
+ * merge base of that commit and its own head (`resolveMergeBase`).
+ *
+ * In a workspace member (#3465) both commands run in the member's directory
+ * and pass `--member <name>`, so the member's gate (`pr-<number>-<member>`),
+ * note and statuses stay apart from every other member's on the same pull
+ * request. They still measure the whole change: a file outside the member
+ * that one of its units reaches selects that unit.
+ */
+import { PR_APPLY_GATE } from "../pr-loop.js";
+/** Where both jobs write their reports, kept as a CI artifact. */
+export const PR_LOOP_REPORT_DIR = ".chant/pr";
+/**
+ * The attempt record the apply job resumes from (#3543), relative to the
+ * directory the job runs in. It sits outside `PR_LOOP_REPORT_DIR`, so the
+ * report artifact never carries it: it holds the outputs the members read.
+ */
+export const PR_APPLY_RECORD = ".chant/pr-resume/pr-apply.json";
+/**
+ * The image the pull-request pipeline runs in when the caller sets none. The
+ * full `node` image has git, which both jobs measure the change with;
+ * `PR_LOOP_SETUP` adds OpenTofu on top of it. A caller who sets `image`
+ * brings both and gets no setup lines.
+ */
+export const PR_LOOP_IMAGE = "node:22";
+/** Installs OpenTofu into `PR_LOOP_IMAGE`. */
+export const PR_LOOP_SETUP = [
+    "command -v tofu >/dev/null 2>&1 || (curl -fsSL https://get.opentofu.org/install-opentofu.sh -o /tmp/install-opentofu.sh && sh /tmp/install-opentofu.sh --install-method standalone)",
+];
+/** The setup lines for a pipeline running in `image`: the install when it is the default image, none otherwise. */
+export function prLoopSetup(image) {
+    return image === PR_LOOP_IMAGE ? PR_LOOP_SETUP : [];
+}
+/**
+ * The two jobs for `forge`. `member` is the workspace member the pipeline is
+ * generated for; the commands then run in its directory, so `--output` is
+ * relative to it.
+ */
+export function prLoopJobs(forge, env, options = {}, member) {
+    const gate = options.gate ?? PR_APPLY_GATE;
+    const common = [
+        "--env", env, "--gate", gate, "--output", PR_LOOP_REPORT_DIR, "--forge", forge,
+        ...(member ? ["--member", member] : []),
+    ];
+    const github = forge !== "gitlab";
+    const token = github ? { GITHUB_TOKEN: "${{ github.token }}" } : {};
+    return [
+        {
+            jobName: "plan",
+            command: ["chant", "components", "pr-plan", "--base", '"$BASE_SHA"', "--pr", '"$PR_NUMBER"', ...common].join(" "),
+            env: github
+                ? { BASE_SHA: "${{ github.event.pull_request.base.sha }}", PR_NUMBER: "${{ github.event.pull_request.number }}", ...token }
+                : { BASE_SHA: "$CI_MERGE_REQUEST_DIFF_BASE_SHA", PR_NUMBER: "$CI_MERGE_REQUEST_IID" },
+        },
+        {
+            jobName: "apply",
+            command: [
+                "chant", "components", "pr-apply", "--base", '"$BASE_SHA"', ...common,
+                ...(options.requireReview === false ? [] : ["--require-review"]),
+                "--resume", PR_APPLY_RECORD,
+            ].join(" "),
+            env: github ? { BASE_SHA: "${{ github.event.before }}", ...token } : { BASE_SHA: "$CI_COMMIT_BEFORE_SHA" },
+            ...(github ? {} : { setup: [gitlabBaseFallback(options.branch)] }),
+        },
+    ];
+}
+/**
+ * The concurrency group (GitHub, Forgejo) or resource group (GitLab) that
+ * keeps one apply at a time per environment, and per member in a workspace.
+ *
+ * A member's group is `chant-apply.<member>.<env>`. Member names hold only
+ * lower-case letters, digits and `-`, so the first `.` ends the member and no
+ * two member and environment pairs share a group: member `a` with environment
+ * `b-c` is `chant-apply.a.b-c`, and member `a-b` with environment `c` is
+ * `chant-apply.a-b.c`. The `.` after `chant-apply` keeps a member's groups
+ * apart from a single project's `chant-apply-<env>`.
+ */
+export function prApplyGroup(env, member) {
+    return member ? `chant-apply.${member}.${env}` : `chant-apply-${env}`;
+}
+/**
+ * The cache key the apply job keeps its attempt record under (#3543), with
+ * `commit` the forge's expression for the pushed commit. A push of another
+ * commit never restores a record, and the environment and member keep each
+ * pipeline's record apart. The pull request and the gate digest are not in
+ * the key, since neither is known before the job runs; `pr-apply --resume`
+ * refuses a record made for another pull request, gate or digest.
+ */
+export function prApplyRecordKey(env, commit, member) {
+    return `${prApplyGroup(env, member)}-${commit}`;
+}
+/**
+ * GitLab sets `CI_COMMIT_BEFORE_SHA` to forty zeros on a branch's first push.
+ * The line replaces it with the merge request's diff base when the pipeline
+ * has one, and otherwise with the merge base of the target branch and the
+ * pushed commit, or the pushed commit's parent when that is the commit itself.
+ */
+export function gitlabBaseFallback(branch) {
+    const target = branch ? JSON.stringify(branch) : "$CI_DEFAULT_BRANCH";
+    return ('if [ -z "$BASE_SHA" ] || [ "$BASE_SHA" = "0000000000000000000000000000000000000000" ]; then ' +
+        'BASE_SHA="${CI_MERGE_REQUEST_DIFF_BASE_SHA:-}"; ' +
+        'if [ -z "$BASE_SHA" ]; then ' +
+        `git fetch origin ${target} && BASE_SHA="$(git merge-base FETCH_HEAD "$CI_COMMIT_SHA")"; ` +
+        'if [ "$BASE_SHA" = "$CI_COMMIT_SHA" ]; then BASE_SHA="$(git rev-parse "$CI_COMMIT_SHA^")"; fi; ' +
+        "fi; fi; export BASE_SHA");
+}