@astrale-os/sdk 0.6.0-beta.15 → 0.6.0-beta.16

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

@@ -0,0 +1,88 @@
+import type { DomainSchema } from '@astrale-os/kernel-dsl/v1/schema';
+import type { BumpLevel, Version } from '../../../platform/versioning/index.js';
+import type { RegistryIndex, RegistryPublication } from '../registry/index.js';
+/** One change since the baseline, with the level it alone requires. */
+export interface DiffChangeV1 {
+    /**
+     * The compared member's Key (`issues.astrale.ai:class.Issue.property.priority`), or the Domain's
+     * origin for a change of the whole build or Schema.
+     */
+    readonly subject: string;
+    /**
+     * The compatibility engine's facet (`method.existence`, `property.required`, …), `schema` for a
+     * new Schema revision of equivalent meaning, `build` for new code under the same revision.
+     */
+    readonly facet: string;
+    readonly state: 'missing' | 'changed' | 'added';
+    readonly bump: BumpLevel;
+    /** What differs, such as `optional → required`, when the observation says. */
+    readonly detail?: string;
+}
+/**
+ * `astrale-domain diff --json` on stdout: the version the Project declares, checked against the
+ * highest published stable version up to it (CT30).
+ */
+export interface DiffReportV1 {
+    readonly format: 'astrale.diff-report';
+    readonly version: 1;
+    readonly origin: string;
+    /** `package.json` `version`. */
+    readonly declared: string;
+    /** The declared version already names a Publication: the report is informational. */
+    readonly published: boolean;
+    /** `unregistered`: no Domain of this origin the caller may read; nothing is compared. */
+    readonly registry: 'read' | 'unregistered';
+    /** The highest published stable version up to the declared one, yanked ones included. */
+    readonly baseline?: string;
+    /** The level the changes since the baseline require. */
+    readonly level?: BumpLevel;
+    /** The level after the 0.x rule. */
+    readonly effective?: BumpLevel;
+    /** The smallest version the changes admit, a pre-release such as `2.0.0-0`. */
+    readonly minimum?: string;
+    /** The stable form of the required version, such as `2.0.0`. */
+    readonly next?: string;
+    /** For a refused pre-release, the first pre-release of the required version on its channel. */
+    readonly suggestion?: string;
+    /**
+     * The declared version reaches the minimum, or there is nothing to compare. It judges an
+     * unpublished version: a published stable one is its own baseline and is never accepted, so a
+     * consumer decides on `published || accepted`, the exit status.
+     */
+    readonly accepted: boolean;
+    /** Every change since the baseline, ordered by subject Key then observation; empty for none. */
+    readonly changes: readonly DiffChangeV1[];
+}
+export interface DiffInput {
+    readonly origin: string;
+    readonly declared: Version;
+    /**
+     * Which published versions can be the baseline (AM-23): `diff` compares with the highest stable
+     * version up to the declared one (`<=`, the default); `publish`, which never runs for a published
+     * version, with the highest one below it (`<`).
+     */
+    readonly bound?: '<' | '<=';
+    /** The Schema revision the Project builds now. */
+    readonly revision: string;
+    /** The caller's view of the registry; `undefined` when it holds no readable Domain of `origin`. */
+    readonly index: RegistryIndex | undefined;
+    /** The Schema the Project builds now. */
+    readonly current: () => DomainSchema;
+    /** The build digest of every distinct bundler; read only when the Schema revision is unchanged. */
+    readonly builds: () => Promise<readonly string[]>;
+    /** The Schema a Publication names; read only when its revision differs from the Project's. */
+    readonly published: (publication: RegistryPublication) => Promise<DomainSchema>;
+}
+/**
+ * Compare the Project with the highest published stable version up to the declared one
+ * (`baselineVersion(index, declared, '<=')`, or below it for `publish`, AM-23) and judge the declared version against the
+ * level its changes require (tech Versioning [.21507], [.106102]). The judgement always receives a
+ * level beside its baseline (AM-56): the compatibility engine's when the Schema revision changed,
+ * otherwise patch, the smallest level, which `diff` picks itself when nothing changed at all.
+ */
+export declare function diffReport(input: DiffInput): Promise<DiffReportV1>;
+/**
+ * Decode the bundle a Publication stores and admit it only as that Publication's Schema: the
+ * Domain's origin and the Publication's Schema revision.
+ */
+export declare function publishedSchema(bytes: Uint8Array, publication: RegistryPublication, origin: string): DomainSchema;

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

@@ -0,0 +1,154 @@
+import * as bundle from '@astrale-os/kernel-dsl/v1/bundle/transport';
+import { requiredBump } from '@astrale-os/kernel-dsl/v1/schema/compatibility';
+import { revision } from '@astrale-os/kernel-dsl/v1/schema/revision';
+import { baselineVersion, judgeVersion } from '../../../platform/versioning/index.js';
+/**
+ * Compare the Project with the highest published stable version up to the declared one
+ * (`baselineVersion(index, declared, '<=')`, or below it for `publish`, AM-23) and judge the declared version against the
+ * level its changes require (tech Versioning [.21507], [.106102]). The judgement always receives a
+ * level beside its baseline (AM-56): the compatibility engine's when the Schema revision changed,
+ * otherwise patch, the smallest level, which `diff` picks itself when nothing changed at all.
+ */
+export async function diffReport(input) {
+    const identity = {
+        format: 'astrale.diff-report',
+        version: 1,
+        origin: input.origin,
+        declared: input.declared,
+    };
+    if (input.index === undefined) {
+        return Object.freeze({
+            ...identity,
+            published: false,
+            registry: 'unregistered',
+            accepted: true,
+            changes: Object.freeze([]),
+        });
+    }
+    const publications = input.index.publications;
+    const published = publications.some(({ version }) => version === input.declared);
+    // An index entry that is not a canonical version is never a baseline: `baselineVersion` keeps
+    // only canonical stable versions (AM-56), so the registry's strings need no admission here.
+    const index = publications.map(({ version, yanked }) => ({
+        version: version,
+        yanked,
+    }));
+    const baseline = baselineVersion(index, input.declared, input.bound ?? '<=');
+    if (baseline === undefined) {
+        // Without a stable version before it there is nothing to check (tech [.106102]).
+        const verdict = judgeVersion({ declared: input.declared });
+        return Object.freeze({
+            ...identity,
+            published,
+            registry: 'read',
+            accepted: verdict.accepted,
+            changes: Object.freeze([]),
+        });
+    }
+    const publication = publications.find(({ version }) => version === baseline);
+    const { level, changes } = await changesSince(publication, input);
+    const verdict = judgeVersion({ declared: input.declared, previous: baseline, level });
+    return Object.freeze({
+        ...identity,
+        published,
+        registry: 'read',
+        baseline,
+        level,
+        effective: verdict.effective,
+        minimum: verdict.minimum,
+        next: verdict.next,
+        ...(verdict.suggestion === undefined ? {} : { suggestion: verdict.suggestion }),
+        accepted: verdict.accepted,
+        changes,
+    });
+}
+/**
+ * Decode the bundle a Publication stores and admit it only as that Publication's Schema: the
+ * Domain's origin and the Publication's Schema revision.
+ */
+export function publishedSchema(bytes, publication, origin) {
+    const root = bundle.decode(bytes).root;
+    if (root.origin !== origin || revision(root) !== publication.schemaRevision) {
+        throw new TypeError(`The stored bundle of ${origin}@${publication.version} is not that Publication's Schema ${publication.schemaRevision}.`);
+    }
+    return root;
+}
+async function changesSince(publication, input) {
+    if (publication.schemaRevision !== input.revision) {
+        const required = requiredBump(await input.published(publication), input.current());
+        const changes = required.changes.map(change);
+        return {
+            level: required.level,
+            changes: Object.freeze(changes.length > 0
+                ? changes
+                : // A new revision whose meaning the engine finds equivalent, such as descriptions.
+                    [
+                        Object.freeze({
+                            subject: input.origin,
+                            facet: 'schema',
+                            state: 'changed',
+                            bump: 'patch',
+                            detail: 'same meaning',
+                        }),
+                    ]),
+        };
+    }
+    const builds = await input.builds();
+    if (builds.includes(publication.buildDigest)) {
+        // No change at all: same build digest and no row of [.21507] (AM-56).
+        return { level: 'patch', changes: Object.freeze([]) };
+    }
+    // Code only, same Schema revision ([.21507], first row).
+    return {
+        level: 'patch',
+        changes: Object.freeze([
+            Object.freeze({
+                subject: input.origin,
+                facet: 'build',
+                state: 'changed',
+                bump: 'patch',
+                detail: `${publication.buildDigest} → ${builds.length === 0 ? 'none' : builds.join(', ')}`,
+            }),
+        ]),
+    };
+}
+function change({ subject, observation, bump }) {
+    const detail = describe(observation);
+    return Object.freeze({
+        subject: subject.key,
+        facet: observation.facet,
+        // `requiredBump` lists only observations that are not equal.
+        state: observation.state,
+        bump,
+        ...(detail === undefined ? {} : { detail }),
+    });
+}
+const DETAILED_DIFFERENCES = 3;
+const VALUE_LENGTH = 40;
+/** The observation's differences in a few words: `optional → required`, `input/type: "string" → "number"`. */
+function describe(observation) {
+    const differences = observation.differences;
+    if (differences.length === 0)
+        return undefined;
+    const [first] = differences;
+    if (differences.length === 1 &&
+        first.path === '/required' &&
+        typeof first.before === 'boolean' &&
+        typeof first.after === 'boolean') {
+        return first.after ? 'optional → required' : 'required → optional';
+    }
+    const described = differences.slice(0, DETAILED_DIFFERENCES).map((difference) => {
+        const path = difference.path === '' ? '/' : difference.path.slice(1);
+        if (difference.before === undefined)
+            return `${path}: added ${value(difference.after)}`;
+        if (difference.after === undefined)
+            return `${path}: removed ${value(difference.before)}`;
+        return `${path}: ${value(difference.before)} → ${value(difference.after)}`;
+    });
+    const more = differences.length - described.length;
+    return more > 0 ? `${described.join('; ')}; ${more} more` : described.join('; ');
+}
+function value(input) {
+    const text = JSON.stringify(input) ?? String(input);
+    return text.length > VALUE_LENGTH ? `${text.slice(0, VALUE_LENGTH - 1)}…` : text;
+}

package/dist/tooling/cli/help.js

@@ -22,11 +22,14 @@ Commands:
   dev [environment]       Deprecated: use deploy, then astrale domain install.
   build                   Build, verify and print the build digest.
   deploy <environment>    Deploy one Environment; never installs.
+  diff                    Show the changes since the published version and the minimum.
   list                    List the deployments of the Project's Environments.
+  publish <environment>   Deploy, verify and publish the package.json version; never installs.
   test                    Run Project tests, optionally against one Environment.
   lint                    Check Domain source and architecture.
   package                 Prepare public declarations for publication.
   upgrade                 Update Astrale dependencies through pnpm (default: beta).
+  yank <version>          Take a published version out of resolution, or put it back.
 
 Options:
   -h, --help              Show help.
@@ -187,6 +190,79 @@ Behavior:
   takes.
   Exit status: 0 listed, 1 a host could not be listed (with --json, nothing on
   stdout), 2 usage error.
+`,
+    diff: `Show the changes since the last published version and the version they require.
+
+Usage:
+  astrale-domain diff [--as <identity>] [--json]
+
+Options:
+  --as <identity>         Select the Astrale identity that reads the Domain registry.
+  --json                  Print one DiffReportV1 on stdout; the summary goes to stderr.
+  -h, --help              Show help for diff.
+
+Behavior:
+  Reads the declared version from package.json and compares the Domain with the
+  highest published stable version up to it, yanked versions included. The level
+  the changes require is a floor: removing or changing a member is major, adding
+  one minor, anything else (code, descriptions) patch; below 1.0.0 a breaking
+  change raises the minor. Callable authorization is outside the floor: raise the
+  version yourself when you narrow it.
+  When package.json still names a published version, as on a feature branch, the
+  report is informational and exits 0. Otherwise the declared version must reach
+  the minimum: a version that is too low exits 1 and names what requires more, as
+  on a release PR, where Release-As: 2.0.0 or a feat!: commit raises the number.
+  Nothing to compare (no published stable version, or a Domain absent from the
+  registry or not readable by the caller) exits 0.
+  Reads the registry through the Astrale CLI (domain versions) with the caller's
+  own credential, and the stored bundle of the compared version only when its
+  Schema differs. Builds the Domain when the Schema is unchanged, to compare build
+  digests. Deploys, publishes and installs nothing.
+  Exit status: 0 accepted, published or nothing to compare; 1 too low or failed
+  (with --json, a failure prints nothing on stdout); 2 usage error.
+`,
+    publish: `Deploy one Environment, verify it, and publish the version package.json declares.
+
+Usage:
+  astrale-domain publish <environment> [--allow-dirty] [--as <identity>] [--json]
+
+Arguments:
+  environment             Required adapter environment key, usually production.
+
+Options:
+  --allow-dirty           Publish from a working tree with changes, or outside git; the
+                          Publication is marked dirty.
+  --as <identity>         Select the Astrale identity that reads and writes the Domain
+                          registry and deploys.
+  --json                  Print one PublishReportV1 on stdout; progress goes to stderr.
+  -h, --help              Show help for publish.
+
+Behavior:
+  Names one immutable deployment's release with the version in package.json, in
+  this order, deploying only once the registry allows the version:
+  1. Before any effect: refuses an Environment that does not deploy immutable
+     deployments, a working tree with changes or no git commit (unless
+     --allow-dirty), and warns when no remote branch holds the commit; then builds,
+     freezes the configuration, places the deployment and seals its release.
+  2. Reads the version from package.json and the registry through the Astrale CLI.
+     A version already published with this release succeeds without effect; with
+     another release it is refused: a published version never changes.
+  3. Compares with the highest stable version below it, yanked versions included,
+     as diff does, and refuses a version that is too low.
+  4. Deploys the release, or reuses its deployment, as deploy does.
+  5. Verifies that the deployment serves the sealed release, within 60 seconds.
+  6. Asks Admin for the Publication, which Admin creates under the Domain's lock. A
+     version published meanwhile with another release is refused, and this
+     deployment stays a preview. On a platform dispatch namespace the published
+     deployment is then kept from expiry; Admin keeps those of its Services itself.
+  A failure leaves at most a deployment without a version, and says whether a rerun
+  can help: when it can, rerun publish, which reuses it; a refusal Admin repeats
+  (a missing domain_admin right, a release it will not name) names its cause.
+  Admin unavailable or the Domain absent from the registry: nothing is deployed.
+  It never installs the Domain: install the URL it prints with
+  ${installCommand()}.
+  Exit status: 0 published or already published; 1 refused or failed (with --json,
+  a failure prints nothing on stdout); 2 usage error.
 `,
     test: `Run Project tests locally or against one selected Environment.
 
@@ -214,6 +290,28 @@ Options:
   --fix                   Apply supported fixes.
   --format <format>       Select stylish or json output (default: stylish).
   -h, --help              Show help for lint.
+`,
+    yank: `Take one published version of the Domain out of resolution, or put it back.
+
+Usage:
+  astrale-domain yank <version> [--undo] [--json]
+
+Arguments:
+  version                 One published version of this Project's Domain, e.g. 1.5.0.
+
+Options:
+  --undo                  Let line references choose the version again.
+  --json                  Print one YankReportV1 on stdout.
+  -h, --help              Show help for yank.
+
+Behavior:
+  Changes the version in the Admin registry through the Astrale CLI, with its configured
+  Admin target and identity; yanking requires administering the Domain. A line reference
+  such as @1.5 never chooses a yanked version, and an exact reference installs it with a
+  warning. Installations keep running and the deployment keeps serving: yanking only
+  changes resolution. A version already in the requested state answers unchanged, so a
+  rerun is safe. Exit status: 0 done, 1 refused or failed, 2 usage error; a refused or
+  failed run prints nothing on stdout.
 `,
     package: `Prepare public TypeScript declarations for package publication.
 

package/dist/tooling/cli/immutable-deployment.d.ts

@@ -1,15 +1,71 @@
-import type { Adapter, Build, LegacyAdapter, ResolvedRuntimeReference } from '../../deployment/index.js';
+import type { DeploymentCommitV1, FrozenConfigurationV1 } from '../../deployment/address/index.js';
+import type { Adapter, Build, Bundle, LegacyAdapter, Placement, Release, ResolvedRuntimeReference } from '../../deployment/index.js';
 import type { DeployResultV1 } from './deploy-result.js';
 /**
- * Deploy one canonical Environment (CT33) as the immutable deployment of one sealed release.
+ * Everything the deploy of one canonical Environment derives before its only effectful call: the
+ * Bundle, the Environment's current secrets, the frozen configuration, where the host places the
+ * deployment, its label, the sealed release it serves and the commit it is built from. Planning has
+ * no effect at the host: `placement` only reads, and nothing is created, reused or written.
+ */
+export interface ImmutableDeploymentPlan {
+    readonly projectDir: string;
+    readonly environment: string;
+    readonly adapter: Adapter<object>;
+    readonly parameters: object;
+    readonly identity?: string;
+    readonly bundle: Bundle;
+    readonly secrets: Readonly<Record<string, string>>;
+    readonly configuration: FrozenConfigurationV1;
+    readonly placement: Placement;
+    /** `<line>-<content>`: the deployment's DNS label and provider script. */
+    readonly label: string;
+    /** The `DomainRelease` v4 the deployment serves at its URL, `release.url`. */
+    readonly release: Release;
+    /** The commit this deploy runs from, which a deployment it creates declares. */
+    readonly commit: DeploymentCommitV1 | null;
+}
+/**
+ * Plan the immutable deployment of one canonical Environment (CT33), without any effect.
+ *
+ * The SDK bundles exactly as `astrale-domain build` does, asks the adapter to freeze the
+ * Environment's configuration and say where its host places deployments, derives the deployment
+ * label and URL from them (S3), seals the `DomainRelease` v4 the deployment serves at that URL
+ * (S4a), and reads the commit it is built from. `deploy` deploys the plan at once; `publish`
+ * checks the registry against the sealed release first, and deploys only when it may name it.
+ */
+export declare function planImmutableDeployment(input: {
+    readonly projectDir: string;
+    readonly environment: string;
+    /** A canonical Environment's adapter (CT33), which implements adapter interface v2. */
+    readonly adapter: Adapter<object> | LegacyAdapter<object>;
+    readonly parameters: object;
+    readonly build: Build;
+    readonly runtime: ResolvedRuntimeReference;
+    readonly identity?: string;
+    /** The commit provenance the caller already read (`publish` checks it first); read otherwise. */
+    readonly commit?: DeploymentCommitV1 | null;
+    readonly signal: AbortSignal;
+}): Promise<ImmutableDeploymentPlan>;
+/**
+ * The commit the Project's runtime module is built from, as a deployment declares it (CT18
+ * `commit`): its sha, whether the tree holds changes it does not, and the last release tag before
+ * it. `null` outside git.
+ */
+export declare function runtimeCommit(projectDir: string, runtime: ResolvedRuntimeReference, signal: AbortSignal): Promise<DeploymentCommitV1 | null>;
+/**
+ * Create, or reuse, the immutable deployment a plan describes: the adapter's `deployRelease` is
+ * its only effectful call. The SDK makes no Kernel call, the deploy calls no instance and installs
+ * nothing: `astrale domain install <url>` installs the URL it prints.
  *
- * The SDK derives everything before the adapter's only effectful call: it bundles exactly as
- * `astrale-domain build` does, asks the adapter to freeze the Environment's configuration and say
- * where its host places deployments, derives the deployment label and URL from them (S3), seals
- * the `DomainRelease` v4 the deployment serves at that URL (S4a), and reads the commit it is built
- * from. `deployRelease` then creates that deployment or reuses it. The SDK makes no Kernel call,
- * the deploy calls no instance and installs nothing: `astrale domain install <url>` installs the
- * URL it prints.
+ * Returns the deploy result, or nothing once a failure is reported on stderr.
+ */
+export declare function deployPlannedRelease(plan: ImmutableDeploymentPlan, input: {
+    readonly signal: AbortSignal;
+    readonly report: (line: string) => void;
+}): Promise<DeployResultV1 | undefined>;
+/**
+ * Deploy one canonical Environment (CT33) as the immutable deployment of one sealed release: plan
+ * it without effect, then make the adapter's one effectful call.
  *
  * Returns the deploy result, or nothing once a failure is reported on stderr.
  */

package/dist/tooling/cli/immutable-deployment.js

@@ -7,19 +7,15 @@ import { deployResult } from './deploy-result.js';
 import { error } from './log.js';
 import { environmentSecrets } from './secrets.js';
 /**
- * Deploy one canonical Environment (CT33) as the immutable deployment of one sealed release.
+ * Plan the immutable deployment of one canonical Environment (CT33), without any effect.
  *
- * The SDK derives everything before the adapter's only effectful call: it bundles exactly as
- * `astrale-domain build` does, asks the adapter to freeze the Environment's configuration and say
- * where its host places deployments, derives the deployment label and URL from them (S3), seals
- * the `DomainRelease` v4 the deployment serves at that URL (S4a), and reads the commit it is built
- * from. `deployRelease` then creates that deployment or reuses it. The SDK makes no Kernel call,
- * the deploy calls no instance and installs nothing: `astrale domain install <url>` installs the
- * URL it prints.
- *
- * Returns the deploy result, or nothing once a failure is reported on stderr.
+ * The SDK bundles exactly as `astrale-domain build` does, asks the adapter to freeze the
+ * Environment's configuration and say where its host places deployments, derives the deployment
+ * label and URL from them (S3), seals the `DomainRelease` v4 the deployment serves at that URL
+ * (S4a), and reads the commit it is built from. `deploy` deploys the plan at once; `publish`
+ * checks the registry against the sealed release first, and deploys only when it may name it.
  */
-export async function deployImmutable(input) {
+export async function planImmutableDeployment(input) {
     const { parameters, environment, build, signal } = input;
     const adapter = releaseAdapter(input.adapter);
     const identity = input.identity === undefined ? {} : { identity: input.identity };
@@ -39,25 +35,59 @@ export async function deployImmutable(input) {
     const origin = build.schema.compiled.root.origin;
     const label = deploymentLabel(deploymentLine({ origin, environment, addressing: placement.addressing }), deploymentContent(bundle.digest, configuration));
     const release = assemble(build, bundle.digest, deploymentUrl(label, placement.routingDomain));
-    const commit = await deploymentCommit({
-        projectDir: input.projectDir,
-        // The configuration sits in the Project directory, and names its runtime relative to it.
-        runtimeModule: resolve(input.projectDir, input.runtime.reference.path),
-        signal,
-    });
-    const deployed = await adapter.deployRelease(parameters, {
+    const commit = input.commit !== undefined
+        ? input.commit
+        : await runtimeCommit(input.projectDir, input.runtime, signal);
+    return Object.freeze({
         projectDir: input.projectDir,
         environment,
+        adapter,
+        parameters,
         ...identity,
-        secrets,
         bundle,
+        secrets,
         configuration,
         placement,
         label,
         release,
         commit,
+    });
+}
+/**
+ * The commit the Project's runtime module is built from, as a deployment declares it (CT18
+ * `commit`): its sha, whether the tree holds changes it does not, and the last release tag before
+ * it. `null` outside git.
+ */
+export function runtimeCommit(projectDir, runtime, signal) {
+    return deploymentCommit({
+        projectDir,
+        // The configuration sits in the Project directory, and names its runtime relative to it.
+        runtimeModule: resolve(projectDir, runtime.reference.path),
         signal,
     });
+}
+/**
+ * Create, or reuse, the immutable deployment a plan describes: the adapter's `deployRelease` is
+ * its only effectful call. The SDK makes no Kernel call, the deploy calls no instance and installs
+ * nothing: `astrale domain install <url>` installs the URL it prints.
+ *
+ * Returns the deploy result, or nothing once a failure is reported on stderr.
+ */
+export async function deployPlannedRelease(plan, input) {
+    const { adapter, environment, label, release } = plan;
+    const deployed = await adapter.deployRelease(plan.parameters, {
+        projectDir: plan.projectDir,
+        environment,
+        ...(plan.identity === undefined ? {} : { identity: plan.identity }),
+        secrets: plan.secrets,
+        bundle: plan.bundle,
+        configuration: plan.configuration,
+        placement: plan.placement,
+        label,
+        release,
+        commit: plan.commit,
+        signal: input.signal,
+    });
     if (deployed.status !== 'ready') {
         error(`Deployment failed during ${deployed.phase}: ${deployed.error.message}`);
         return undefined;
@@ -74,6 +104,16 @@ export async function deployImmutable(input) {
     input.report('Ready: deployment verified');
     return result;
 }
+/**
+ * Deploy one canonical Environment (CT33) as the immutable deployment of one sealed release: plan
+ * it without effect, then make the adapter's one effectful call.
+ *
+ * Returns the deploy result, or nothing once a failure is reported on stderr.
+ */
+export async function deployImmutable(input) {
+    const plan = await planImmutableDeployment(input);
+    return deployPlannedRelease(plan, { signal: input.signal, report: input.report });
+}
 /**
  * What the deploy did to the secrets of the one deployment it made or reused: `bound` to the new
  * deployment, or `updated` or left `unchanged` in place on the reused one. No other deployment's

package/dist/tooling/cli/index.d.ts

@@ -1,7 +1,8 @@
 /**
  * `@astrale-os/sdk/cli` — the `astrale-domain` CLI
- * (dev | build | deploy | list | test | lint | package), its JSON results, and the explicit dotenv
- * boundary. `dev` is deprecated and lives in `legacy/development/`.
+ * (dev | build | deploy | diff | list | publish | test | lint | package | yank), its JSON results,
+ * the deploy mode each command selects for an Environment (CT33), and the explicit dotenv boundary.
+ * `dev` is deprecated and lives in `legacy/development/`.
  *
  * Node-only: the CLI imports `node:fs`/`node:module`/`node:url` and runs under
  * Bun (it imports the project's `astrale.config.ts` directly). This subpath is
@@ -13,5 +14,10 @@
 export { run } from './run.js';
 export type { BuildResultV1 } from './build.js';
 export type { DeployResultV1, DeploymentSecretsState } from './deploy-result.js';
+export type { DiffChangeV1, DiffReportV1 } from './diff/index.js';
 export type { ListedDeploymentV1, ListResultV1, UnlistedEnvironmentV1 } from './list.js';
+export type { PublishReportV1 } from './publish/index.js';
+export type { YankReportV1 } from './yank.js';
+export { selectDeployMode } from './deploy-mode.js';
+export type { CloudflareDirectParameter, DeployMode, DeployModeCommand, DeployRefusal, LegacyDirectReason, } from './deploy-mode.js';
 export { loadDeclaredSecrets } from './dotenv.js';

package/dist/tooling/cli/index.js

@@ -1,7 +1,8 @@
 /**
  * `@astrale-os/sdk/cli` — the `astrale-domain` CLI
- * (dev | build | deploy | list | test | lint | package), its JSON results, and the explicit dotenv
- * boundary. `dev` is deprecated and lives in `legacy/development/`.
+ * (dev | build | deploy | diff | list | publish | test | lint | package | yank), its JSON results,
+ * the deploy mode each command selects for an Environment (CT33), and the explicit dotenv boundary.
+ * `dev` is deprecated and lives in `legacy/development/`.
  *
  * Node-only: the CLI imports `node:fs`/`node:module`/`node:url` and runs under
  * Bun (it imports the project's `astrale.config.ts` directly). This subpath is
@@ -11,4 +12,7 @@
  * The bin lives at `./bin`.
  */
 export { run } from './run.js';
+// The domain-publish Action asks the selection `publish` makes before it runs it, to skip an
+// Environment that is not canonical with a notice instead of failing on its refusal.
+export { selectDeployMode } from './deploy-mode.js';
 export { loadDeclaredSecrets } from './dotenv.js';