@astrale-os/sdk 0.6.0-beta.2 → 0.6.0-beta.21

package/dist/tooling/cli/publish/index.js

@@ -0,0 +1,346 @@
+import * as bundle from '@astrale-os/kernel-dsl/v1/bundle/transport';
+import { RetainRefusal } from '../../../deployment/adapter/index.js';
+import { verifyRelease } from '../../../deployment/verify/readiness/index.js';
+import { commitPushed } from '../commit.js';
+import { declaredVersion } from '../diff/declared.js';
+import { renderDiff } from '../diff/render.js';
+import { diffReport, publishedSchema } from '../diff/report.js';
+import { deployPlannedRelease, planImmutableDeployment, runtimeCommit, } from '../immutable-deployment.js';
+import { DIM, RED, RESET, YELLOW } from '../log.js';
+import { RegistryCliError, openDomainRegistry } from '../registry/index.js';
+import { publishReport } from './report.js';
+/**
+ * Step 5 reads the deployment's `release.json` (at most 1 MiB) and its Bundle (at most 16 MiB)
+ * once the adapter has seen it ready: a deployment that accepts the connection and never answers
+ * is refused after this long, never waited on until the CI job's own timeout.
+ */
+export const VERIFY_TIMEOUT_MS = 60_000;
+const DEFAULT_DEPENDENCIES = Object.freeze({
+    open: openDomainRegistry,
+    verify: async (release, signal) => {
+        await verifyRelease(release, { signal });
+    },
+    pushed: commitPushed,
+    stdout: (text) => void process.stdout.write(text),
+    stderr: (text) => void process.stderr.write(text),
+});
+/**
+ * `astrale-domain publish <environment> [--allow-dirty] [--as <identity>] [--json]`: give the
+ * release this tree deploys in one Environment the version `package.json` declares (tech
+ * Versioning [.73345], Registry [.122137]). It deploys bottom-up and names last: the Publication
+ * Admin creates under the Domain's lock is the only switch, so every failure before it leaves at
+ * most a deployment without a version, which a rerun reuses (Registry [.122407]).
+ *
+ * 0. Before any effect: provenance (a dirty tree or no git is refused unless `--allow-dirty`; the
+ *    commit is recorded; an unpushed commit warns), then the plan of the deployment: build,
+ *    configure, placement, label, URL and the sealed release digest.
+ * 1. Read the version from `package.json`.
+ * 2. Read the registry. The version exists: the same release succeeds without effect, another is
+ *    refused. A Domain absent or unreadable, or a registry that does not answer, is refused.
+ * 3. Judge the version against the highest stable version below it (AM-23); refuse a version
+ *    that is too low.
+ * 4. Deploy the release, or reuse its deployment.
+ * 5. Verify that the deployment serves the sealed release.
+ * 6. Ask Admin for the Publication; a version Admin gave another release meanwhile is refused,
+ *    naming the winner's release, and this deployment stays a preview. Any other failure says
+ *    what CT29 says of it: Admin may have created the Publication (a rerun settles it), Admin made
+ *    none and a rerun can help, or Admin refused and a rerun meets the same refusal. Then, where
+ *    the host has no registry principal to keep it (the platform namespace), `adapter.retain`
+ *    keeps the published deployment (CT36). Admin keeps no mark on its Services' deployments:
+ *    Services keeps every deployment until it is retired.
+ *
+ * Steps 0 to 3 make no deploy call. Never installs.
+ */
+export async function runPublish(input, dependencies = DEFAULT_DEPENDENCIES) {
+    const { build, environment, signal } = input;
+    const root = build.schema.compiled.root;
+    const origin = root.origin;
+    const progress = (line) => (input.json ? dependencies.stderr : dependencies.stdout)(`${DIM}›${RESET} ${line}\n`);
+    const warn = (...lines) => dependencies.stderr(`${YELLOW}!${RESET} ${lines.join('\n  ')}\n`);
+    const refuse = (...lines) => {
+        dependencies.stderr(`${RED}✗${RESET} ${lines.join('\n  ')}\n`);
+        return 1;
+    };
+    const identity = input.identity === undefined ? {} : { identity: input.identity };
+    // 0. Provenance, read before anything is built ([.73872], AM-25).
+    const commit = await runtimeCommit(input.projectDir, input.runtime, signal);
+    if (commit === null) {
+        if (!input.allowDirty) {
+            return refuse(`${origin} is not in a git repository: a Publication records the commit it was built from.`, 'Publish from a commit, or pass --allow-dirty to publish without one.');
+        }
+        warn('Publishing without a commit (--allow-dirty): the Publication is marked dirty.');
+    }
+    else {
+        if (commit.dirty) {
+            if (!input.allowDirty) {
+                return refuse(`The working tree has changes that commit ${commit.sha.slice(0, 7)} does not hold.`, 'Commit them, or pass --allow-dirty to publish a build the commit does not reproduce.');
+            }
+            warn(`Publishing a dirty tree (--allow-dirty): the Publication is marked dirty.`);
+        }
+        if ((await dependencies.pushed({ projectDir: input.projectDir, sha: commit.sha, signal })) ===
+            false) {
+            warn(`Commit ${commit.sha.slice(0, 7)} is on no remote branch. Push it: release-please ` +
+                'computes the next version from the pushed history, and could compute this one again.');
+        }
+    }
+    // 0. The deployment this publish would make, planned without any effect.
+    const plan = await planImmutableDeployment({
+        projectDir: input.projectDir,
+        environment,
+        adapter: input.adapter,
+        parameters: input.parameters,
+        build,
+        runtime: input.runtime,
+        ...identity,
+        commit,
+        signal,
+    });
+    const { release } = plan;
+    const releaseDigest = release.document.digest;
+    // 1. The version the author declares.
+    const declared = await declaredVersion(input.projectDir);
+    const name = `${origin}@${declared}`;
+    // 2. The registry: the version once written never changes; Admin down publishes nothing.
+    let registry;
+    let index;
+    try {
+        registry = await dependencies.open({ projectDir: input.projectDir, ...identity, signal });
+        index = await registry.index(origin);
+    }
+    catch (cause) {
+        if (!(cause instanceof RegistryCliError))
+            throw cause;
+        return refuse(`Domain registry: ${cause.code}: ${cause.message}`, 'Nothing was deployed or published.');
+    }
+    if (index === undefined) {
+        return refuse(`${origin} is not in the Domain registry, or you may not read it: nothing was deployed.`, 'An administrator of the Admin instance registers the Domain and names who may publish it.');
+    }
+    const existing = index.publications.find(({ version }) => version === declared);
+    if (existing !== undefined) {
+        if (existing.releaseDigest !== releaseDigest) {
+            return refuse(`${name} is already published with release ${existing.releaseDigest}, and this tree ` +
+                `deploys release ${releaseDigest} in ${environment}.`, 'A published version never changes: declare a higher version in package.json. Nothing was deployed.');
+        }
+        progress(`${name} already names this release: nothing to deploy or publish.`);
+        if (existing.yanked) {
+            warn(`${name} is yanked; astrale-domain yank ${declared} --undo makes it resolvable again.`);
+        }
+        // A rerun after the Publication but before the adapter's `retain` completes that retention.
+        const kept = await retain(plan, signal);
+        if (kept.state === 'failed')
+            return refuse(...notRetained(name, plan, kept.message));
+        if (kept.state === 'refused')
+            warn(...noLongerKept(name, plan, kept.message));
+        return emit(publishReport({
+            environment,
+            release,
+            version: declared,
+            status: 'unchanged',
+            deployment: 'none',
+            commit,
+        }));
+    }
+    // 3. The version must reach the minimum its changes since the version below it require.
+    let verdict;
+    try {
+        verdict = await diffReport({
+            origin,
+            declared,
+            bound: '<',
+            revision: root.revision,
+            index,
+            current: () => bundle.decode(build.schema.bundle.bytes()).root,
+            builds: async () => [plan.bundle.digest],
+            published: async (publication) => publishedSchema(await registry.bundle(origin, publication), publication, origin),
+        });
+    }
+    catch (cause) {
+        if (!(cause instanceof RegistryCliError))
+            throw cause;
+        return refuse(`Domain registry: ${cause.code}: ${cause.message}`, 'Nothing was deployed or published.');
+    }
+    if (!verdict.accepted) {
+        dependencies.stderr(`${renderDiff(verdict).refusal.join('\n')}\n`);
+        return 1;
+    }
+    // 4. Deploy the release, or reuse its deployment.
+    const deployed = await deployPlannedRelease(plan, { signal, report: progress });
+    if (deployed === undefined)
+        return refuse(`Nothing was published: rerun publish once the deployment succeeds.`);
+    const deployment = deployed.deployment.state === 'created' ? 'created' : 'reused';
+    // 5. The deployment serves exactly the sealed release, within a deadline.
+    try {
+        await verifyWithin(dependencies, release, signal);
+    }
+    catch (cause) {
+        return refuse(`${release.url} does not serve release ${releaseDigest}: ${message(cause)}`, 'Nothing was published: the deployment stays a preview. Rerun publish, which reuses it.');
+    }
+    // 6. The Publication, under the Domain's lock in Admin: the only switch.
+    let published;
+    try {
+        published = await registry.publish({
+            origin,
+            version: declared,
+            url: release.url,
+            releaseDigest,
+            ...(commit === null ? {} : { commit: commit.sha }),
+            dirty: commit === null || commit.dirty,
+        });
+    }
+    catch (cause) {
+        if (cause instanceof RegistryCliError && cause.code === 'PUBLICATION_VERSION_CONFLICT') {
+            return refuse(`${name} was published meanwhile with release ${winnerDigest(cause) ?? 'unknown'}: a version is written once.`, `This deployment stays a preview at ${release.url}. Declare a higher version to publish it.`);
+        }
+        return refuse(...notPublished(name, origin, release.url, cause));
+    }
+    progress(`Published: ${name} · ${published.status}`);
+    const kept = await retain(plan, signal);
+    if (kept.state === 'failed')
+        return refuse(...notRetained(name, plan, kept.message));
+    if (kept.state === 'refused')
+        warn(...noLongerKept(name, plan, kept.message));
+    return emit(publishReport({
+        environment,
+        release,
+        version: declared,
+        status: published.status,
+        deployment,
+        commit,
+    }));
+    function emit(report) {
+        progress(`URL: ${report.url}`);
+        if (input.json)
+            dependencies.stdout(`${JSON.stringify(report, null, 2)}\n`);
+        return 0;
+    }
+}
+/** Step 5 under its deadline: the lifecycle signal still interrupts it first. */
+async function verifyWithin(dependencies, release, signal) {
+    const timeoutMs = dependencies.verifyTimeoutMs ?? VERIFY_TIMEOUT_MS;
+    const deadline = new AbortController();
+    const bound = timeoutMs % 1000 === 0 ? `${timeoutMs / 1000} s` : `${timeoutMs} ms`;
+    const timer = setTimeout(() => deadline.abort(new Error(`no answer within ${bound}`)), timeoutMs);
+    try {
+        await dependencies.verify(release, AbortSignal.any([signal, deadline.signal]));
+    }
+    catch (cause) {
+        if (deadline.signal.aborted && !signal.aborted)
+            throw deadline.signal.reason;
+        throw cause;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * What a failed Publication request leaves, as CT29 says it (AM-216 (4)):
+ * - `unconfirmed`: Admin may have created it. A change whose delivery is unknown, an answer the
+ *   Astrale CLI or the SDK could not read, or a command that did not finish (launch failure,
+ *   time or output bound, interruption). Only a rerun tells, and it is safe: publish is
+ *   idempotent and the rerun reuses the deployment.
+ * - `retryable`: Admin made none, and CT29 says a rerun can help (`details.retryable`).
+ * - `refused`: Admin made none, and the same request meets the same answer until its cause is
+ *   fixed (a missing right, a release Admin will not name, a CLI error before Admin).
+ */
+function notPublished(name, origin, url, cause) {
+    if (!(cause instanceof RegistryCliError) || unconfirmed(cause)) {
+        return [
+            `Admin did not confirm the Publication of ${name} (${described(cause)}); it may have been created.`,
+            `Rerun publish: it reuses the deployment at ${url} and publishes nothing twice.`,
+        ];
+    }
+    if (cause.details?.retryable === true) {
+        return [
+            `Admin made no Publication of ${name}: ${described(cause)}`,
+            `Rerun publish: it reuses the deployment at ${url}.`,
+        ];
+    }
+    return [
+        `Admin refused the Publication of ${name}: ${described(cause)}`,
+        `Nothing was published: the deployment stays a preview at ${url}. A rerun meets the same ` +
+            `refusal until ${remedy(cause, origin)}.`,
+    ];
+}
+/** CT29: a change may have applied, or the answer could not be read. */
+function unconfirmed(error) {
+    const reason = error.details?.reason;
+    return (error.details?.delivery === 'unknown' ||
+        error.code === 'REGISTRY_CLI_FAILED' ||
+        error.code === 'REGISTRY_CLI_PROTOCOL' ||
+        (error.code === 'REGISTRY_UNAVAILABLE' &&
+            (reason === 'response-invalid' || reason === 'client')));
+}
+/** What has to change before the same Publication request can succeed. */
+function remedy(error, origin) {
+    const reason = typeof error.details?.reason === 'string' ? ` (${error.details.reason})` : '';
+    switch (error.code) {
+        case 'REGISTRY_FORBIDDEN':
+            return error.details?.status === 2004
+                ? `this identity holds domain_admin on ${origin} in the Domain registry, which an administrator of the Domain grants`
+                : 'Admin accepts the credential of this identity';
+        case 'REGISTRY_DOMAIN_NOT_FOUND':
+            return `${origin} is in the Domain registry and this identity may read it`;
+        case 'PUBLICATION_RELEASE_MISMATCH':
+            return `the deployment serves a release Admin names for ${origin}${reason}`;
+        case 'PUBLICATION_RELEASE_UNREACHABLE':
+            return `Admin reads the release at the deployment, which this run verified${reason}`;
+        case 'PUBLICATION_VERSION_INVALID':
+            return 'package.json declares a version Admin admits';
+        default:
+            return 'its cause is fixed';
+    }
+}
+function described(cause) {
+    return cause instanceof RegistryCliError ? `${cause.code}: ${cause.message}` : message(cause);
+}
+/**
+ * Keep the published deployment where its host has no registry principal to mark it: the adapter
+ * declares `retain` for the platform namespace only (CT36). Admin's Services keeps every
+ * deployment until it is retired, so adapter-astrale declares none. A `RetainRefusal` (absent or
+ * retired) is `refused`, which no rerun changes; any other rejection `failed`, which a rerun
+ * retries.
+ */
+async function retain(plan, signal) {
+    const { adapter } = plan;
+    if (adapter.retain === undefined)
+        return { state: 'kept' };
+    try {
+        await adapter.retain(plan.parameters, {
+            label: plan.label,
+            signal,
+            ...(plan.identity === undefined ? {} : { identity: plan.identity }),
+        });
+        return { state: 'kept' };
+    }
+    catch (cause) {
+        return { state: cause instanceof RetainRefusal ? 'refused' : 'failed', message: message(cause) };
+    }
+}
+function notRetained(name, plan, cause) {
+    return [
+        `${name} is published, but its deployment ${plan.label} is not kept yet: ${cause}`,
+        'Rerun publish: it publishes nothing again and keeps the deployment.',
+    ];
+}
+/**
+ * The version names a deployment its host can no longer keep (absent or retired): publishing has
+ * nothing left to do, a rerun cannot keep it, and installing the version fails, never silently.
+ */
+function noLongerKept(name, plan, cause) {
+    return [
+        `${name} names deployment ${plan.label}, which its host can no longer keep: ${cause}`,
+        'No rerun keeps it, and installing the version fails; declare a higher version to publish ' +
+            'a new deployment.',
+    ];
+}
+/** The release digest of the Publication that won the version, from the CT29 conflict details. */
+function winnerDigest(error) {
+    const existing = error.details?.existing;
+    const digest = typeof existing === 'object' && existing !== null
+        ? existing.releaseDigest
+        : undefined;
+    return typeof digest === 'string' && /^sha256:[0-9a-f]{64}$/u.test(digest) ? digest : undefined;
+}
+function message(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}

package/dist/tooling/cli/publish/report.d.ts

@@ -0,0 +1,49 @@
+import type { ReleaseDigest } from '@astrale-os/kernel-protocol/release';
+import type { DeploymentCommitV1 } from '../../../deployment/address/index.js';
+import type { BuildDigest, Release } from '../../../deployment/index.js';
+/**
+ * `astrale-domain publish <environment> --json` on stdout (CT30): the version `package.json`
+ * declares, the Publication that now names it, and the immutable deployment whose release it
+ * names. Progress and warnings go to stderr. A publish installs nothing.
+ */
+export interface PublishReportV1 {
+    readonly format: 'astrale.publish-report';
+    readonly version: 1;
+    readonly origin: string;
+    readonly environment: string;
+    readonly publication: {
+        /** `package.json` `version`. */
+        readonly version: string;
+        /**
+         * `created` by this publish, or `unchanged`: the version already named this exact release,
+         * by an earlier run or a concurrent identical one.
+         */
+        readonly status: 'created' | 'unchanged';
+    };
+    /**
+     * What this publish did to the deployment: `created` or `reused` it before asking for the
+     * Publication, or `none` when the version already named this release and nothing was deployed.
+     */
+    readonly deployment: 'created' | 'reused' | 'none';
+    /** The deployment URL the Publication names, which `astrale domain install` takes. */
+    readonly url: string;
+    readonly releaseDigest: ReleaseDigest;
+    readonly buildDigest: BuildDigest;
+    /**
+     * The commit this run published from, as step 0 read it (`sha`, `dirty`, and `base` when a
+     * release tag precedes it), or `null` outside git (`--allow-dirty`). A Publication this run
+     * `created` records its `sha` and `dirty`. On `unchanged` the Publication may record another
+     * commit of the same release (an earlier run, or a concurrent identical publish), and a reused
+     * deployment's own record may name an earlier commit of the same build: `astrale domain
+     * versions` lists what the Publication records.
+     */
+    readonly commit: DeploymentCommitV1 | null;
+}
+export declare function publishReport(input: {
+    readonly environment: string;
+    readonly release: Release;
+    readonly version: string;
+    readonly status: 'created' | 'unchanged';
+    readonly deployment: 'created' | 'reused' | 'none';
+    readonly commit: DeploymentCommitV1 | null;
+}): PublishReportV1;

package/dist/tooling/cli/publish/report.js

@@ -0,0 +1,15 @@
+export function publishReport(input) {
+    const { release } = input;
+    return Object.freeze({
+        format: 'astrale.publish-report',
+        version: 1,
+        origin: release.document.origin,
+        environment: input.environment,
+        publication: Object.freeze({ version: input.version, status: input.status }),
+        deployment: input.deployment,
+        url: release.url,
+        releaseDigest: release.document.digest,
+        buildDigest: release.buildDigest,
+        commit: input.commit,
+    });
+}

package/dist/tooling/cli/registry/client.d.ts

@@ -0,0 +1,114 @@
+import type { Version } from '../../../platform/versioning/index.js';
+import type { RegistryExecutableDependencies } from './executable.js';
+import type { InstanceListing } from './installations.js';
+import type { RegistryProcessInput, RegistryProcessResult } from './process.js';
+export { RegistryCliError } from './error.js';
+/** A `sha256:` digest as the registry stores it. */
+export type RegistryDigest = `sha256:${string}`;
+/**
+ * The Schema Bundle a Publication's deployment serves, as the Astrale CLI admitted it: Admin keeps
+ * no bundle, so the CLI reads it from the deployment's `release.json`, admitted with the
+ * Publication's release digest.
+ */
+export interface RegistryBundle {
+    readonly digest: RegistryDigest;
+    readonly mediaType: string;
+    readonly size: number;
+}
+/** The fields of one CT29 `PublicationSummaryV1` that version checks read. */
+export interface RegistryPublication {
+    readonly version: string;
+    readonly yanked: boolean;
+    readonly releaseDigest: RegistryDigest;
+    readonly buildDigest: RegistryDigest;
+    readonly schemaRevision: string;
+}
+/**
+ * The Publication `publish` asks Admin to create (CT29 `PublishRequestV1`): a version for the
+ * release one deployment serves at its URL. The client never sends the bundle or its
+ * dependencies; Admin re-reads the release at `url` (tech Registry [.119544]).
+ */
+export interface RegistryPublishRequest {
+    readonly origin: string;
+    readonly version: string;
+    /** The deployment URL, which is also the issuer of the release it serves. */
+    readonly url: string;
+    readonly releaseDigest: RegistryDigest;
+    /** The commit the release was built from; absent outside git (`--allow-dirty`). */
+    readonly commit?: string;
+    /** The working tree held changes the commit does not, or no commit could be read. */
+    readonly dirty: boolean;
+}
+/**
+ * What `astrale __domain-registry publish --json` answered (CT29 `PublishResultV1`): `created` by
+ * this call, or `unchanged` when the version already named this release.
+ */
+export interface RegistryPublishResult {
+    readonly status: 'created' | 'unchanged';
+    readonly publication: RegistryPublication & {
+        readonly url: string;
+    };
+}
+/** Every Publication of one Domain the caller may read, as `astrale domain versions` lists it. */
+export interface RegistryIndex {
+    readonly origin: string;
+    readonly publications: readonly RegistryPublication[];
+}
+/**
+ * What `astrale __domain-registry yank <origin>@<version> [--undo] --json` answered (CT29
+ * `YankResultV1`): whether this call changed the yank state, and the state Admin now holds. The
+ * other `PublicationSummaryV1` fields are not read.
+ */
+export interface RegistryYank {
+    readonly status: 'changed' | 'unchanged';
+    readonly publication: {
+        readonly version: Version;
+        readonly yanked: boolean;
+    };
+}
+/** The Admin registry, read and changed through the Astrale CLI with the caller's own credential. */
+export interface DomainRegistry {
+    /** The Domain's index, or `undefined` when it is absent or not readable by the caller. */
+    index(origin: string): Promise<RegistryIndex | undefined>;
+    /** The bundle bytes of one Publication of the index, digest and Schema identity verified. */
+    bundle(origin: string, publication: RegistryPublication): Promise<Uint8Array>;
+    /**
+     * Ask Admin to name one deployed release with a version. Admin decides under the Domain's lock:
+     * an absent version is created, the same release digest answers `unchanged`, another is refused
+     * (`PUBLICATION_VERSION_CONFLICT`). Idempotent, so a rerun after a lost answer is safe.
+     */
+    publish(request: RegistryPublishRequest): Promise<RegistryPublishResult>;
+    /**
+     * Yank one published version, or restore it with `undo`. Idempotent: a version already in the
+     * requested state answers `unchanged`, so a rerun after a lost answer is safe.
+     */
+    yank(origin: string, version: Version, options: {
+        readonly undo: boolean;
+    }): Promise<RegistryYank>;
+    /**
+     * What one instance the CLI knows by that name runs, as its Kernel lists it for the caller
+     * (`astrale domain list -i <instance> --json`, CT24), or why that is unknown. Never throws for a
+     * refusal of that instance: an instance that cannot tell is a partial answer (AM-198).
+     */
+    instance(name: string): Promise<InstanceListing>;
+}
+export interface DomainRegistryDependencies {
+    readonly resolve: (input: {
+        readonly projectDir: string;
+        readonly signal: AbortSignal;
+        readonly minimum?: string;
+    }, dependencies?: RegistryExecutableDependencies) => Promise<string>;
+    readonly run: (input: RegistryProcessInput) => Promise<RegistryProcessResult>;
+}
+/**
+ * Open the Domain registry through one admitted Astrale CLI (CT29 plumbing); the CLI's configured
+ * Admin target answers. Reads and publish run under `--as` when the caller names an identity, a
+ * yank under the CLI's default identity.
+ */
+export declare function openDomainRegistry(input: {
+    readonly projectDir: string;
+    readonly identity?: string;
+    readonly signal: AbortSignal;
+    /** The first CLI release serving every read the command makes (default: the registry). */
+    readonly minimum?: string;
+}, dependencies?: DomainRegistryDependencies): Promise<DomainRegistry>;