@intentius/chant-lexicon-terraform 0.124.52 → 0.124.55

package/dist/registry/targets/gitlab.js

@@ -0,0 +1,187 @@
+/**
+ * GitLab's Terraform module registry as a module target (chant#4603).
+ *
+ * The one write is GitLab's documented upload
+ * (docs.gitlab.com/api/packages/terraform-modules/):
+ *
+ *   PUT /projects/:id/packages/terraform/modules/:name/:system/:version/file
+ *
+ * with the archive as the body. The token follows chant's forge target
+ * (core lifecycle/publish-forge.ts `forgeTokenEnv`): the variable the
+ * declaration names, else `GITLAB_TOKEN`, then `CI_JOB_TOKEN`. A job token
+ * goes in `JOB-TOKEN` and any other in `PRIVATE-TOKEN`. The API root is the
+ * declaration's, else `CI_API_V4_URL`, else gitlab.com's; the project is the
+ * declaration's (an id or a full path), else `CI_PROJECT_ID`.
+ *
+ * GitLab lists a version as soon as it is uploaded, so there is no staging
+ * step to hide it: `stage` uploads, and `reveal` reads the version back the
+ * way Terraform and OpenTofu do (discovery, versions, download) with the
+ * lexicon's registry reader, sending `TF_TOKEN_<host>` (chant#4563), else the
+ * upload token, which GitLab also takes as a bearer token on these reads.
+ * `held` downloads the version's archive and compares its content digest, so
+ * a version holding other content is refused and the same content comes back
+ * `present` with nothing sent.
+ *
+ * GitLab's module API has no call to deprecate a version, so a deprecation
+ * stays in the bucket catalog and GitLab shows none. The namespace a GitLab
+ * source names is the project's top-level group (`CI_PROJECT_ROOT_NAMESPACE`
+ * in CI): the declaration's `namespace`, else the context's.
+ */
+import { readCredential } from "@intentius/chant/lifecycle/publish-credentials";
+import { PublishTargetError } from "@intentius/chant/lifecycle/release-publish";
+import { terraformCredential } from "@intentius/chant/terraform/credentials";
+import { createHash } from "node:crypto";
+import { RegistryError, fetchTarball, registryLocation, registryVersions } from "../reader.js";
+import { answerError, checkModuleVersion, contentDigest, defaultPublishFetch, versionHeldError, } from "./module-target.js";
+export const GITLAB_DEFAULT_API = "https://gitlab.com/api/v4";
+/** The variables the upload token is read from, in order. */
+export const gitlabTokenEnv = (o) => (o.tokenEnv ? [o.tokenEnv] : ["GITLAB_TOKEN", "CI_JOB_TOKEN"]);
+/** The API root a target uploads to, without a trailing slash. */
+export const gitlabApi = (o, env) => (o.api ?? env.CI_API_V4_URL ?? GITLAB_DEFAULT_API).replace(/\/+$/, "");
+/** The headers a GitLab token goes in: `JOB-TOKEN` for a CI job token, `PRIVATE-TOKEN` for any other. */
+export const gitlabAuthHeader = (token) => (token.from === "CI_JOB_TOKEN" ? { "job-token": token.value } : { "private-token": token.value });
+/** The upload URL for one version. */
+export function gitlabUploadUrl(api, project, address, version) {
+    const id = /^\d+$/.test(project) ? project : encodeURIComponent(project);
+    return `${api}/projects/${id}/packages/terraform/modules/${encodeURIComponent(address.name)}/${encodeURIComponent(address.system)}/${encodeURIComponent(version)}/file`;
+}
+/** A signed URL's query (GitLab's download link carries a token in it) cut from a message. */
+const withoutQueries = (text) => text.replace(/(https?:\/\/[^\s?]+)\?[^\s)"']*/g, "$1?[query]");
+export function gitlabModuleTarget(options = {}, deps = {}) {
+    const fetch = deps.fetch ?? defaultPublishFetch;
+    const tokenEnv = gitlabTokenEnv(options);
+    const key = `gitlab:${createHash("sha256")
+        .update(JSON.stringify({ project: options.project ?? null, api: options.api ?? null, tokenEnv: options.tokenEnv ?? null, namespace: options.namespace ?? null }))
+        .digest("hex")
+        .slice(0, 16)}`;
+    const where = (env) => {
+        const api = gitlabApi(options, env);
+        let u;
+        try {
+            u = new URL(api);
+        }
+        catch {
+            throw new PublishTargetError("publish-config-invalid", `${api} is not a URL`, "Set the declaration's api, or CI_API_V4_URL, to the API root, such as https://gitlab.example.com/api/v4.");
+        }
+        return { api, host: u.host.toLowerCase(), scheme: (u.protocol === "http:" ? "http" : "https") };
+    };
+    const addressOf = (address) => ({ ...address, namespace: options.namespace ?? address.namespace });
+    const sourceOf = (host, a) => `${host}/${a.namespace}/${a.name}/${a.system}`;
+    const uploadToken = (ctx) => readCredential(ctx.env, tokenEnv, ctx.redactor);
+    const needToken = (ctx) => {
+        const t = uploadToken(ctx);
+        if (!t)
+            throw answerError(ctx, "publish-credentials-missing", `no GitLab token: set ${tokenEnv.join(" or ")}`, "In GitLab CI the job's CI_JOB_TOKEN can upload to its own project; elsewhere use a token with the api scope.");
+        return t;
+    };
+    const projectOf = (env) => {
+        const p = options.project ?? env.CI_PROJECT_ID;
+        if (!p)
+            throw new PublishTargetError("publish-config-invalid", "no GitLab project to upload to", "Name the project (its id or full path) in the declaration, or run in GitLab CI, which sets CI_PROJECT_ID.");
+        return p;
+    };
+    /** The reader's options: the CLIs' token for the host, else the upload token. */
+    const readOptions = (ctx) => {
+        const { host, scheme } = where(ctx.env);
+        const cli = terraformCredential(host, { env: ctx.env });
+        const token = cli?.token ?? uploadToken(ctx)?.value;
+        ctx.redactor.add(token);
+        return { host, scheme, token: token ?? false, ...(deps.registryFetch ? { fetch: deps.registryFetch } : {}) };
+    };
+    const read = async (ctx, run) => {
+        try {
+            return await run();
+        }
+        catch (e) {
+            if (e instanceof RegistryError)
+                throw answerError(ctx, "publish-read-failed", withoutQueries(e.message));
+            throw e;
+        }
+    };
+    const versions = async (address, ctx) => {
+        const o = readOptions(ctx);
+        return read(ctx, () => registryVersions(sourceOf(o.host, addressOf(address)), o));
+    };
+    const held = async (address, version, ctx) => {
+        if (!(await versions(address, ctx)).includes(version))
+            return undefined;
+        const o = readOptions(ctx);
+        const source = sourceOf(o.host, addressOf(address));
+        return read(ctx, async () => {
+            const location = await registryLocation(source, version, o);
+            return { content: contentDigest(await fetchTarball(location, o)) };
+        });
+    };
+    const item = (ctx, present) => {
+        const { host } = where(ctx.env);
+        const a = addressOf(ctx.address);
+        return { name: `${a.namespace}/${a.name}/${a.system} ${ctx.version}`, destination: sourceOf(host, a), digest: ctx.content, ...(present ? { present: true } : {}) };
+    };
+    return {
+        kind: "gitlab",
+        name: "GitLab module registry",
+        destination: gitlabApi(options, process.env),
+        credentialEnv: tokenEnv,
+        key,
+        versions,
+        held,
+        async plan(ctx) {
+            checkModuleVersion(ctx);
+            needToken(ctx);
+            projectOf(ctx.env);
+            return [item(ctx)];
+        },
+        async stage(ctx) {
+            checkModuleVersion(ctx);
+            const token = needToken(ctx);
+            const project = projectOf(ctx.env);
+            const { api, host } = where(ctx.env);
+            const a = addressOf(ctx.address);
+            const source = sourceOf(host, a);
+            const staged = (present) => ({ target: "gitlab", destination: source, items: [item(ctx, present)], state: { project, host, version: ctx.version } });
+            const before = await held(ctx.address, ctx.version, ctx);
+            if (before) {
+                if (before.content !== ctx.content)
+                    throw versionHeldError(source, ctx, before);
+                ctx.log(`${source} ${ctx.version} is already on GitLab with this content; nothing sent`);
+                return staged(true);
+            }
+            const url = gitlabUploadUrl(api, project, a, ctx.version);
+            let res;
+            try {
+                res = await fetch(url, { method: "PUT", headers: { ...gitlabAuthHeader(token), "content-type": "application/octet-stream" }, body: ctx.archive });
+            }
+            catch (e) {
+                throw answerError(ctx, "publish-upload-failed", `PUT ${url}: ${e.message}`);
+            }
+            const text = await res.text().catch(() => "");
+            if (res.ok) {
+                ctx.log(`uploaded ${source} ${ctx.version} to project ${project}`);
+                return staged(false);
+            }
+            if (/already exists/i.test(text)) {
+                // Another run uploaded it between the read and the upload: judge what it holds.
+                const now = await held(ctx.address, ctx.version, ctx);
+                if (now && now.content === ctx.content)
+                    return staged(true);
+                if (now)
+                    throw versionHeldError(source, ctx, now);
+            }
+            if (res.status === 401 || res.status === 403) {
+                throw answerError(ctx, "publish-credentials-refused", `GitLab answered ${res.status} to the upload of ${source} ${ctx.version}: it refused the token in ${token.from}`, token.from === "CI_JOB_TOKEN"
+                    ? "A job token uploads only to its own project; name another project's token in the declaration's tokenEnv."
+                    : `Give the token in ${token.from} the api scope and at least the Developer role on project ${project}.`);
+            }
+            throw answerError(ctx, "publish-upload-failed", `GitLab answered ${res.status} to the upload of ${source} ${ctx.version}: ${withoutQueries(text.slice(0, 300))}`);
+        },
+        async reveal(ctx, staged) {
+            const listed = await versions(ctx.address, ctx);
+            if (!listed.includes(ctx.version)) {
+                throw answerError(ctx, "publish-reveal-missing", `${staged.destination} lists no ${ctx.version} after the upload`, "Check the project's package registry; run the publish again to upload it.");
+            }
+            const o = readOptions(ctx);
+            await read(ctx, () => registryLocation(staged.destination, ctx.version, o));
+            return { target: staged.target, destination: staged.destination, items: staged.items };
+        },
+    };
+}

package/dist/registry/targets/hcp.d.ts

@@ -0,0 +1,29 @@
+import { type ModulePublishTarget, type ModuleTargetDeps } from "./module-target.js";
+/** How an HCP Terraform (or Terraform Enterprise) module target is declared. */
+export interface HcpModuleTargetOptions {
+    /** The organization, which is also the namespace private module sources name. */
+    organization: string;
+    /** The host. Default app.terraform.io; a Terraform Enterprise host otherwise. */
+    host?: string;
+    /** The variable the token is read from first, in place of `TFE_TOKEN`. */
+    tokenEnv?: string;
+    /** How long a reveal waits for the version's status to be `ok`. Default {@link HCP_PARSE_WAIT_MS}. */
+    waitMs?: number;
+    /** How long a reveal waits between reads. Default {@link HCP_POLL_MS}. */
+    pollMs?: number;
+}
+export declare const HCP_DEFAULT_HOST = "app.terraform.io";
+/** How many times a call answered 429 is sent again. */
+export declare const HCP_RATE_RETRIES = 5;
+/** The first backoff after a 429 with no `Retry-After`, doubled on each retry. */
+export declare const HCP_BACKOFF_MS = 1000;
+export declare const HCP_PARSE_WAIT_MS = 120000;
+export declare const HCP_POLL_MS = 2000;
+/** The variables a target names as its credentials: the token variable, and the host's `TF_TOKEN_` form. */
+export declare function hcpTokenEnv(o: Pick<HcpModuleTargetOptions, "tokenEnv" | "host">): string[];
+/** The text of a 404 from a create: the two causes HCP's docs give. */
+export declare const hcpNotFoundText: (org: string, host: string) => string;
+/** How long to wait before the next try after a 429: `Retry-After` in seconds or as a date, else the backoff. */
+export declare function retryDelay(retryAfter: string | null, attempt: number, now: number): number;
+export declare function hcpModuleTarget(options: HcpModuleTargetOptions, deps?: ModuleTargetDeps): ModulePublishTarget<"hcp">;
+//# sourceMappingURL=hcp.d.ts.map

package/dist/registry/targets/hcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hcp.d.ts","sourceRoot":"","sources":["../../../src/registry/targets/hcp.ts"],"names":[],"mappings":"AAkDA,OAAO,EAQL,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EAEtB,MAAM,iBAAiB,CAAC;AAEzB,gFAAgF;AAChF,MAAM,WAAW,sBAAsB;IACrC,iFAAiF;IACjF,YAAY,EAAE,MAAM,CAAC;IACrB,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sGAAsG;IACtG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,eAAO,MAAM,gBAAgB,qBAAqB,CAAC;AACnD,wDAAwD;AACxD,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAClC,kFAAkF;AAClF,eAAO,MAAM,cAAc,OAAO,CAAC;AACnC,eAAO,MAAM,iBAAiB,SAAU,CAAC;AACzC,eAAO,MAAM,WAAW,OAAO,CAAC;AAIhC,4GAA4G;AAC5G,wBAAgB,WAAW,CAAC,CAAC,EAAE,IAAI,CAAC,sBAAsB,EAAE,UAAU,GAAG,MAAM,CAAC,GAAG,MAAM,EAAE,CAG1F;AAED,uEAAuE;AACvE,eAAO,MAAM,eAAe,QAAS,MAAM,QAAQ,MAAM,KAAG,MACiH,CAAC;AAE9K,iHAAiH;AACjH,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAQ1F;AAYD,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,EAAE,IAAI,GAAE,gBAAqB,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAiPxH"}

package/dist/registry/targets/hcp.js

@@ -0,0 +1,310 @@
+/**
+ * HCP Terraform's private module registry as a module target (chant#4604),
+ * on the API flow terragucci#1292's ruling settled for every tier, with no
+ * VCS connection:
+ *
+ *   1. GET  /api/v2/organizations/:org/registry-modules/private/:org/:name/:provider
+ *      and, only when that answers 404,
+ *      POST /api/v2/organizations/:org/registry-modules
+ *           {type: registry-modules, attributes: {name, provider, registry-name: private}}
+ *   2. POST /api/v2/organizations/:org/registry-modules/private/:org/:name/:provider/versions
+ *           {type: registry-module-versions, attributes: {version, commit-sha}}
+ *      whose 201 carries `links.upload`
+ *   3. PUT  <links.upload>, Content-Type: application/octet-stream, the gzip tarball
+ *
+ * (developer.hashicorp.com/terraform/cloud-docs/api-docs/private-registry/modules).
+ * The archive is the one the bucket registry serves and the attestation signs
+ * (terragucci#1290 ruling B), and `commit-sha` carries the revision.
+ *
+ * `stage` makes the three calls. A module already there is not created
+ * again, and a version already there is judged by its content (`held`): the
+ * same content comes back `present` with nothing sent, other content is
+ * refused. HCP lists a version as soon as it is created, so there is nothing
+ * to hide before a reveal; `reveal` reads the module until the version's
+ * status is `ok`, through the contract's `sleep` and `now`, and a version
+ * still parsing when the wait runs out is reported in a line, without failing.
+ *
+ * The token is `TFE_TOKEN` (or the declaration's `tokenEnv`), else the one
+ * Terraform sends the host: `TF_TOKEN_<host>` or a credentials block
+ * (core's terraform/credentials). It goes in `Authorization: Bearer` to the
+ * API host only. The upload link is a signed archivist URL, so the token is
+ * not sent there, as go-tfe's upload sends none.
+ *
+ * Every call is retried on a 429 after `Retry-After`, else with a doubling
+ * backoff, up to {@link HCP_RATE_RETRIES} times; HCP's API allows 30 requests
+ * a second per user. A 404 on a create names the two causes the docs give:
+ * a token whose team lacks the Manage modules permission, or an organization
+ * without the private registry entitlement.
+ *
+ * Deprecation: the HCP docs read for this target (the private registry
+ * modules API and the publish page) give no call to deprecate a version, so
+ * HCP shows none and the bucket catalog carries it. Left for the maintainer
+ * run, as terragucci#1292 left them open: which token types work (team,
+ * user, organization), moving a module between API and VCS publishing, any
+ * archive size ceiling, and whether the upload link wants the token.
+ */
+import { PublishTargetError } from "@intentius/chant/lifecycle/release-publish";
+import { terraformCredential, tokenVariable } from "@intentius/chant/terraform/credentials";
+import { createHash } from "node:crypto";
+import { RegistryError, fetchTarball, registryLocation } from "../reader.js";
+import { compareSemver, parseSemver } from "../semver.js";
+import { answerError, checkModuleVersion, contentDigest, defaultPublishFetch, versionHeldError, } from "./module-target.js";
+export const HCP_DEFAULT_HOST = "app.terraform.io";
+/** How many times a call answered 429 is sent again. */
+export const HCP_RATE_RETRIES = 5;
+/** The first backoff after a 429 with no `Retry-After`, doubled on each retry. */
+export const HCP_BACKOFF_MS = 1000;
+export const HCP_PARSE_WAIT_MS = 120000;
+export const HCP_POLL_MS = 2000;
+const JSON_API = "application/vnd.api+json";
+/** The variables a target names as its credentials: the token variable, and the host's `TF_TOKEN_` form. */
+export function hcpTokenEnv(o) {
+    const host = o.host ?? HCP_DEFAULT_HOST;
+    return [o.tokenEnv ?? "TFE_TOKEN", tokenVariable(host)].filter((v) => !!v);
+}
+/** The text of a 404 from a create: the two causes HCP's docs give. */
+export const hcpNotFoundText = (org, host) => `${host} answered 404 for organization ${org}: either the token's team lacks the Manage modules permission, or the organization has no private module registry entitlement`;
+/** How long to wait before the next try after a 429: `Retry-After` in seconds or as a date, else the backoff. */
+export function retryDelay(retryAfter, attempt, now) {
+    if (retryAfter) {
+        const secs = Number(retryAfter.trim());
+        if (Number.isFinite(secs) && secs >= 0)
+            return secs * 1000;
+        const at = Date.parse(retryAfter);
+        if (Number.isFinite(at))
+            return Math.max(0, at - now);
+    }
+    return HCP_BACKOFF_MS * 2 ** attempt;
+}
+export function hcpModuleTarget(options, deps = {}) {
+    const fetch = deps.fetch ?? defaultPublishFetch;
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const now = deps.now ?? Date.now;
+    const host = (options.host ?? HCP_DEFAULT_HOST).toLowerCase();
+    const org = options.organization;
+    const api = `https://${host}/api/v2`;
+    const tokenEnv = hcpTokenEnv(options);
+    const first = options.tokenEnv ?? "TFE_TOKEN";
+    const key = `hcp:${createHash("sha256")
+        .update(JSON.stringify({ organization: org, host, tokenEnv: options.tokenEnv ?? null }))
+        .digest("hex")
+        .slice(0, 16)}`;
+    const addressOf = (a) => ({ ...a, namespace: org });
+    const sourceOf = (a) => `${host}/${org}/${a.name}/${a.system}`;
+    const moduleUrl = (a) => `${api}/organizations/${encodeURIComponent(org)}/registry-modules/private/${encodeURIComponent(org)}/${encodeURIComponent(a.name)}/${encodeURIComponent(a.system)}`;
+    const token = (ctx) => {
+        const direct = ctx.env[first];
+        const found = direct ? { value: direct, from: first } : (() => {
+            const c = terraformCredential(host, { env: ctx.env });
+            return c ? { value: c.token, from: c.from } : null;
+        })();
+        if (found)
+            ctx.redactor.add(found.value);
+        return found;
+    };
+    const needToken = (ctx) => {
+        const t = token(ctx);
+        if (!t) {
+            throw new PublishTargetError("publish-credentials-missing", `no token for ${host}: set ${tokenEnv.join(" or ")}, or a credentials "${host}" block`, "Use a team token whose team has the Manage modules permission.");
+        }
+        return t;
+    };
+    /** One call, sent again on a 429 up to the limit. `auth` false sends no token (the upload link). */
+    const call = async (ctx, method, url, body, auth = true) => {
+        const headers = {};
+        if (auth)
+            headers.authorization = `Bearer ${needToken(ctx).value}`;
+        if (typeof body === "string")
+            headers["content-type"] = JSON_API;
+        else if (body)
+            headers["content-type"] = "application/octet-stream";
+        if (auth)
+            headers.accept = JSON_API;
+        for (let attempt = 0;; attempt++) {
+            let res;
+            try {
+                res = await fetch(url, { method, headers, ...(body !== undefined ? { body } : {}) });
+            }
+            catch (e) {
+                throw answerError(ctx, "publish-upload-failed", `${method} ${url.split("?")[0]}: ${e.message}`);
+            }
+            const text = await res.text().catch(() => "");
+            if (res.status === 429) {
+                if (attempt >= HCP_RATE_RETRIES) {
+                    throw answerError(ctx, "publish-rate-limited", `${host} answered 429 to ${method} ${url.split("?")[0]} ${attempt + 1} times`, "HCP allows 30 requests a second per user; run the publish again later, and it sends only what is missing.");
+                }
+                const ms = retryDelay(res.headers.get("retry-after"), attempt, now());
+                ctx.log(`${host} answered 429; trying again in ${Math.ceil(ms / 1000)}s`);
+                await sleep(ms);
+                continue;
+            }
+            let json = null;
+            try {
+                json = text ? JSON.parse(text) : null;
+            }
+            catch {
+                json = null;
+            }
+            return { status: res.status, json, text };
+        }
+    };
+    const refusedToken = (ctx, status, what) => {
+        const t = token(ctx);
+        return answerError(ctx, "publish-credentials-refused", `${host} answered ${status} to ${what}: it refused the token from ${t?.from ?? first}`, "Use a team token whose team has the Manage modules permission.");
+    };
+    const failed = (ctx, a, what) => answerError(ctx, "publish-upload-failed", `${host} answered ${a.status} to ${what}: ${a.text.slice(0, 300)}`);
+    /** The module's versions and their statuses, or undefined when HCP answers 404. */
+    const readModule = async (ctx, a) => {
+        const res = await call(ctx, "GET", moduleUrl(a));
+        if (res.status === 404)
+            return undefined;
+        if (res.status === 401 || res.status === 403)
+            throw refusedToken(ctx, res.status, `reading ${sourceOf(a)}`);
+        if (res.status !== 200)
+            throw failed(ctx, res, `reading ${sourceOf(a)}`);
+        const attrs = res.json?.data?.attributes ?? {};
+        const raw = Array.isArray(attrs["version-statuses"]) ? attrs["version-statuses"] : [];
+        return { versions: raw.filter((v) => typeof v.version === "string").map((v) => ({ version: v.version, status: typeof v.status === "string" ? v.status : "" })) };
+    };
+    const versions = async (address, ctx) => {
+        const doc = await readModule({ ...ctx, log: () => { } }, addressOf(address));
+        const vs = (doc?.versions ?? []).map((v) => v.version);
+        return vs.sort((x, y) => {
+            const a = parseSemver(x);
+            const b = parseSemver(y);
+            return a && b ? compareSemver(a, b) : x.localeCompare(y);
+        });
+    };
+    /** The archive of an `ok` version, read the way Terraform reads it: discovery, download, the tarball. */
+    const download = async (ctx, a, version) => {
+        const t = needToken(ctx);
+        const o = { token: t.value, ...(deps.registryFetch ? { fetch: deps.registryFetch } : {}) };
+        try {
+            const location = await registryLocation(sourceOf(a), version, o);
+            // The location is another host (archivist); the API token is not sent there.
+            const bytes = await fetchTarball(location, { credentials: { env: ctx.env }, ...(deps.registryFetch ? { fetch: deps.registryFetch } : {}) });
+            return contentDigest(bytes);
+        }
+        catch (e) {
+            if (e instanceof RegistryError)
+                throw answerError(ctx, "publish-read-failed", e.message.replace(/(https?:\/\/[^\s?]+)\?[^\s)"']*/g, "$1?[query]"));
+            throw e;
+        }
+    };
+    const heldIn = async (ctx, a, version, doc) => {
+        const v = doc?.versions.find((x) => x.version === version);
+        if (!v)
+            return undefined;
+        if (v.status !== "ok")
+            return { content: "", status: v.status || "unknown" };
+        return { content: await download(ctx, a, version) };
+    };
+    const held = async (address, version, ctx) => {
+        const a = addressOf(address);
+        return heldIn(ctx, a, version, await readModule({ ...ctx, log: () => { } }, a));
+    };
+    const item = (ctx, present) => {
+        const a = addressOf(ctx.address);
+        return { name: `${org}/${a.name}/${a.system} ${ctx.version}`, destination: sourceOf(a), digest: ctx.content, ...(present ? { present: true } : {}) };
+    };
+    return {
+        kind: "hcp",
+        name: `HCP Terraform registry (${org})`,
+        destination: `${host}/${org}`,
+        credentialEnv: tokenEnv,
+        key,
+        versions,
+        held,
+        async plan(ctx) {
+            checkModuleVersion(ctx);
+            needToken(ctx);
+            return [item(ctx)];
+        },
+        async stage(ctx) {
+            checkModuleVersion(ctx);
+            needToken(ctx);
+            const a = addressOf(ctx.address);
+            const source = sourceOf(a);
+            const staged = (present) => ({ target: "hcp", destination: source, items: [item(ctx, present)], state: { organization: org, host, version: ctx.version } });
+            // 1. The module, created only when absent.
+            let doc = await readModule(ctx, a);
+            if (!doc) {
+                const res = await call(ctx, "POST", `${api}/organizations/${encodeURIComponent(org)}/registry-modules`, JSON.stringify({ data: { type: "registry-modules", attributes: { name: a.name, provider: a.system, "registry-name": "private" } } }));
+                if (res.status === 404)
+                    throw answerError(ctx, "publish-not-found", hcpNotFoundText(org, host), "Give the token's team the Manage modules permission, and check the organization's plan includes the private registry.");
+                if (res.status === 401 || res.status === 403)
+                    throw refusedToken(ctx, res.status, `creating ${source}`);
+                if (res.status === 422) {
+                    // Another run created it between the read and the create.
+                    doc = await readModule(ctx, a);
+                    if (!doc)
+                        throw failed(ctx, res, `creating ${source}`);
+                }
+                else if (res.status !== 201)
+                    throw failed(ctx, res, `creating ${source}`);
+                else {
+                    ctx.log(`created ${source} in the private registry`);
+                    doc = { versions: [] };
+                }
+            }
+            // A version already there: judged by its content, never sent again.
+            const judge = (h) => {
+                if (h.status) {
+                    throw answerError(ctx, "publish-version-unfinished", `${source} ${ctx.version} is on ${host} with status ${h.status}, so its content can't be read`, h.status === "pending" ? "An earlier run created the version and its upload did not finish; delete the version in HCP Terraform's registry and publish again." : "Look at the version in HCP Terraform's registry; delete it and publish again.");
+                }
+                if (h.content !== ctx.content)
+                    throw versionHeldError(source, ctx, h);
+                ctx.log(`${source} ${ctx.version} is already on ${host} with this content; nothing sent`);
+                return staged(true);
+            };
+            const before = await heldIn(ctx, a, ctx.version, doc);
+            if (before)
+                return judge(before);
+            // 2. The version, carrying the revision.
+            const created = await call(ctx, "POST", `${moduleUrl(a)}/versions`, JSON.stringify({ data: { type: "registry-module-versions", attributes: { version: ctx.version, "commit-sha": ctx.revision || null } } }));
+            if (created.status === 404)
+                throw answerError(ctx, "publish-not-found", hcpNotFoundText(org, host), "Give the token's team the Manage modules permission, and check the organization's plan includes the private registry.");
+            if (created.status === 401 || created.status === 403)
+                throw refusedToken(ctx, created.status, `creating ${source} ${ctx.version}`);
+            if (created.status === 422) {
+                const again = await heldIn(ctx, a, ctx.version, await readModule(ctx, a));
+                if (again)
+                    return judge(again);
+                throw failed(ctx, created, `creating ${source} ${ctx.version}`);
+            }
+            if (created.status !== 201)
+                throw failed(ctx, created, `creating ${source} ${ctx.version}`);
+            const upload = created.json?.data?.links?.upload;
+            if (typeof upload !== "string" || !upload)
+                throw answerError(ctx, "publish-upload-failed", `${host} created ${source} ${ctx.version} and gave no upload link`);
+            // 3. The archive, to the signed upload link, with no token.
+            const put = await call(ctx, "PUT", upload, ctx.archive, false);
+            if (put.status < 200 || put.status >= 300) {
+                throw answerError(ctx, "publish-upload-failed", `the upload of ${source} ${ctx.version} answered ${put.status}: ${put.text.slice(0, 300)}`, "The version exists with status pending; delete it in HCP Terraform's registry and publish again.");
+            }
+            ctx.log(`uploaded ${source} ${ctx.version}`);
+            return staged(false);
+        },
+        async reveal(ctx, staged) {
+            const a = addressOf(ctx.address);
+            const wait = options.waitMs ?? HCP_PARSE_WAIT_MS;
+            const poll = options.pollMs ?? HCP_POLL_MS;
+            const start = now();
+            for (;;) {
+                const doc = await readModule(ctx, a);
+                const status = doc?.versions.find((v) => v.version === ctx.version)?.status;
+                if (status === "ok")
+                    return { target: staged.target, destination: staged.destination, items: staged.items };
+                // The docs name pending and ok; a status that says it failed stops the wait, any other keeps it.
+                if (status && /error|fail/i.test(status)) {
+                    throw answerError(ctx, "publish-reveal-failed", `${staged.destination} ${ctx.version} has status ${status} on ${host}, so HCP did not take the archive`, "Look at the version in HCP Terraform's registry; delete it and publish again.");
+                }
+                if (now() - start >= wait) {
+                    ctx.log(`${staged.destination} ${ctx.version} is still ${status ?? "not listed"} on ${host} after ${Math.round(wait / 1000)}s; HCP lists it once it has parsed the archive`);
+                    return { target: staged.target, destination: staged.destination, items: staged.items };
+                }
+                await sleep(poll);
+            }
+        },
+    };
+}

package/dist/registry/targets/hosted.d.ts

@@ -0,0 +1,62 @@
+/**
+ * What the Artifactory and Nexus module targets share (chant#4605): basic
+ * `user:token` write credentials (terragucci#1299 ruling B), a binary GET of
+ * an uploaded archive, and the wait for a version to be listed after its
+ * upload, since both hosts index an upload after the PUT answers.
+ */
+import { type Credential } from "@intentius/chant/lifecycle/publish-credentials";
+import { PublishTargetError, type PublishContextBase } from "@intentius/chant/lifecycle/release-publish";
+import type { RegistryFetch } from "../reader.js";
+/** Where a target reads its basic credentials. */
+export interface BasicCredentialEnv {
+    /** The variable the token (or password) is read from. */
+    tokenEnv: string;
+    /** The variable the user name is read from, when `user` is not given. */
+    userEnv: string;
+    /** The user name itself, in place of `userEnv`. */
+    user?: string;
+}
+/** A user and token, and the `Authorization` header they make. The header and the token are masked. */
+export interface BasicCredential {
+    user: string;
+    token: Credential;
+    /** `Basic <base64 of user:token>`. */
+    header: string;
+}
+/** The basic credential the environment holds, added to the redactor, or null when either half is missing. */
+export declare function readBasicCredential(ctx: Pick<PublishContextBase, "env" | "redactor">, names: BasicCredentialEnv): BasicCredential | null;
+/** The basic credential, or the refusal naming both variables. */
+export declare function needBasicCredential(ctx: Pick<PublishContextBase, "env" | "redactor">, names: BasicCredentialEnv, host: string, fix: string): BasicCredential;
+/** The global fetch, in the reader's shape. */
+export declare const defaultRegistryFetch: RegistryFetch;
+/** A GET of bytes, with its status. A network failure is a `publish-read-failed`. */
+export declare function getBytes(ctx: Pick<PublishContextBase, "redactor">, fetchFn: RegistryFetch, url: string, authorization?: string): Promise<{
+    status: number;
+    bytes: Uint8Array;
+}>;
+/** How long a reveal waits for the host to list an uploaded version, and how often it asks. */
+export interface ListWait {
+    waitMs: number;
+    pollMs: number;
+    sleep: (ms: number) => Promise<void>;
+    now: () => number;
+}
+export declare const HOSTED_LIST_WAIT_MS = 30000;
+export declare const HOSTED_POLL_MS = 2000;
+/** Reads `list` until it holds `version` or the wait is over; true when it was listed. */
+export declare function waitListed(list: () => Promise<string[]>, version: string, wait: ListWait): Promise<boolean>;
+/** The refusal for a 401 or 403 on an upload, naming the variables, never their values. */
+export declare function writeRefused(ctx: Pick<PublishContextBase, "redactor">, host: string, status: number, what: string, credential: BasicCredential, names: BasicCredentialEnv, fix: string): PublishTargetError;
+/**
+ * The content of the archive a download location holds, as the CLIs would
+ * fetch it: the registry's credential goes along only to the registry's own
+ * host and only when the location has no query (a signed URL carries its own
+ * grant). Refuses a location that answers other than 2xx.
+ */
+export declare function locationContent(ctx: Pick<PublishContextBase, "redactor">, fetchFn: RegistryFetch, location: string, registryHost: string, authorization: string | undefined): Promise<{
+    content: string;
+    revision?: string;
+}>;
+/** The refusal for a download that holds other content than the version staged. */
+export declare const revealMismatch: (ctx: Pick<PublishContextBase, "redactor">, where: string, version: string, got: string, want: string) => PublishTargetError;
+//# sourceMappingURL=hosted.d.ts.map

package/dist/registry/targets/hosted.d.ts.map

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