@astrale-os/sdk 0.6.0-beta.3 → 0.6.0-beta.30

package/dist/tooling/cli/help.js

@@ -1,4 +1,6 @@
+import { installCommand } from '../../project/install-command.js';
 import { COMMANDS } from './arguments.js';
+import { MINIMUM_INSTALLATIONS_CLI_VERSION } from './registry/executable.js';
 /** Resolve help without parsing a project or performing any command effects. */
 export function helpRequest(argv) {
     if (!argv.some((argument) => argument === '--help' || argument === '-h'))
@@ -12,24 +14,31 @@ export function helpText(command) {
 export const ERROR_USAGE = `Usage: astrale-domain <command> [options]
 Run "astrale-domain --help" for available commands.
 `;
-const GLOBAL_HELP = `Build, develop, deploy, test, lint, and package Astrale Domains.
+const GLOBAL_HELP = `Build, deploy, list, test, lint, and package Astrale Domains.
 
 Usage:
   astrale-domain <command> [options]
 
 Commands:
-  dev [environment]       Remotely deploy and watch one Project Environment.
-  build                   Build and verify without deploying.
-  deploy <environment>    Deploy and optionally install one Environment.
+  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.
+  <adapter> <command> <environment>
+                          Run a command the Environment's adapter declares for its provider,
+                          such as cloudflare plan production or cloudflare init production.
 
 Options:
   -h, --help              Show help.
 
-Run "astrale-domain <command> --help" for command-specific help.
+Run "astrale-domain <command> --help" for command-specific help. An adapter command that
+does not exist names the commands and options the Environment's adapter declares.
 `;
 const COMMAND_HELP = Object.freeze({
     upgrade: `Update existing Astrale dependencies in a pnpm project or workspace.
@@ -51,88 +60,170 @@ Behavior:
   unchanged with a warning.
   Local links, catalogs, aliases, peers, and overrides are not rewritten.
   Does not load astrale.config.ts, require Bun, run project checks, commit, or deploy.
-  Stop development watchers before upgrading. Review changes and run your project's
-  checks afterwards. Failed installations leave local changes available for repair.
+  Review changes and run your project's checks afterwards. Failed installations leave
+  local changes available for repair.
   For an older SDK without this command: pnpm dlx @astrale-os/sdk@beta upgrade.
 `,
-    dev: `Build, verify, remotely deploy, and watch one Project Environment.
+    build: `Build and verify a Domain without deploying it, and print its build digest.
 
 Usage:
-  astrale-domain dev [environment] [options]
+  astrale-domain build [--json]
+
+Options:
+  --json                  Print one BuildResultV1 document on stdout.
+  -h, --help              Show help for build.
+
+Behavior:
+  Compiles the Domain and verifies that the conventional or configured Runtime
+  module exports the exact Runtime owned by it. Then bundles it once per distinct
+  bundler of the Project's adapters and prints each build digest: the hash of the
+  produced modules, assets, Schema and requirements. It does not select an Environment,
+  load secrets, deploy, or install the Domain, so every Environment whose adapter
+  shares a bundler deploys the code of that one digest.
+`,
+    deploy: `Build, verify, and deploy a Domain through its configured adapter.
+
+Usage:
+  astrale-domain deploy <environment> [--json]
+  astrale-domain deploy --environment <name> [--json]
 
 Arguments:
-  environment             Project Environment name; defaults to development.
+  environment             Required adapter environment key.
 
 Options:
   --environment <name>    Select the environment without a positional argument.
-  --deploy-only           Suppress this run's configured Kernel installation.
-  --as <identity>         Select the Astrale identity for Services and installation calls.
-  --session-file <path>   Write one retained DevelopmentSessionFileV1 snapshot at an
-                          absolute path in a caller-owned private directory.
-  --credential-file <path>
-                          Use one private operator credential for provider and Kernel
-                          calls without exposing it in Project configuration.
-  --secrets-file <path>   Load one private, absolute secrets file for this development
-                          session instead of the adapter-declared secrets file.
-  -h, --help              Show help for dev.
+  --json                  Print one DeployResultV1 on stdout; progress goes to stderr.
+  --as <identity>         Select the Astrale identity for the adapter's provider calls.
+  -h, --help              Show help for deploy.
 
 Behavior:
-  The selected Environment must exist; no other Environment is chosen as a fallback.
-  Builds and verifies the Application, Runtime, frontend, and adapter artifact, then
-  deploys it through the selected Environment. It never starts a local Worker,
-  Vite server, or tunnel. Imported source changes produce serialized remote updates;
-  configuration changes require restarting the command.
-  A shared direct-provider target additionally requires an external single-writer
-  boundary such as a CI/CD concurrency group.
-  The session file is machine-readable and authoritative when requested; human
-  stdout/stderr remains diagnostic. It requires an adapter that reports exact
-  installed Release evidence, so it is rejected for an Environment without an
-  installation and when --deploy-only suppresses installation.
-  A credential file is admitted and read once. Its value is passed only to the
-  deployment adapter, configured Kernel installation, and default View; it never
-  enters Domain Runtime secrets, diagnostics, deployment evidence, or the session
-  file. It is currently unavailable on Windows because private no-reparse file
-  admission is absent.
-  A secrets-file override is read once, passed to the Domain runtime as secrets,
-  never mutates the authored project, and is not watched for later changes. It is
-  also unavailable on Windows because private no-reparse admission is absent.
-
-  Stopping the watcher stops only local build orchestration. The remote deployment
-  and optional Kernel installation remain available.
+  Builds and verifies the Domain and Runtime, rebuilds the Bundle exactly as build
+  does, loads declared secrets, and deploys through the selected adapter. It never
+  installs the Domain: install the URL it prints with
+  ${installCommand()}.
+  Each Environment deploys one immutable release through configure, placement and
+  deployRelease. The SDK seals the release at the deployment URL and records the
+  source commit. Its adapter creates that deployment or reuses it. A new deployment
+  binds the Environment's current secrets; reuse updates only that deployment's
+  secrets. Cloudflare requires a dispatch namespace; astrale() uses Admin's Services.
+  With --json, stdout holds only one DeployResultV1: the deployment's URL, which
+  astrale domain install takes, its digests, adapter and state. Exit status: 0 deployed,
+  1 failed or refused, 2 usage error; a failed run prints nothing on stdout.
 `,
-    build: `Build and verify a Domain without deploying it.
+    list: `List the deployments of the Project's Environments, their versions and where they run.
 
 Usage:
-  astrale-domain build
+  astrale-domain list [--environment <name>] [--instance <name>]... [--json]
 
 Options:
-  -h, --help              Show help for build.
+  --environment <name>    List one Environment instead of every Environment.
+  --instance <name>       Ask this instance what it runs, for INSTALLED ON (repeatable).
+  --json                  Print one ListResultV1 on stdout; notices go to stderr.
+  --as <identity>         Select the Astrale identity for the hosts, the registry and the
+                          instances.
+  -h, --help              Show help for list.
 
 Behavior:
-  Compiles the Application and verifies that the conventional or configured Runtime
-  module exports the exact Runtime owned by it. It does not select an Environment,
-  load secrets, deploy, or install the Domain.
+  Asks the adapter of each Environment that deploys immutable deployments for the
+  deployments its host keeps for the caller, and prints each one's release, its version
+  or name, Environment and state, the instances it is installed on, and the URL ${installCommand()} takes.
+  A deployment is named by the registry's version of its release (1.5.0) or of its build
+  (1.5.0 · staging), else from its record's commit, such as 1.4.2 + 7 commits · a1b2c3d ·
+  staging. Names are computed, never stored, and printed whole.
+  INSTALLED ON names each --instance whose Kernel pins the deployment. ? marks what is
+  unknown: no instance was asked, an instance could not tell (such as one whose Kernel
+  does not list installed releases), or its listing shows only what you can read there;
+  stderr says which and why. An unknown instance is never shown as running nothing; —
+  means every instance asked listed all it runs and none runs it.
+  The registry and the instances are read through the Astrale CLI (${MINIMUM_INSTALLATIONS_CLI_VERSION} or
+  newer) with the caller's identity, only once a deployment is listed.
+  A registry that cannot be read fails the listing; an unknown instance never does.
+  Admin's Services and a Cloudflare dispatch namespace keep deployments until their
+  owner retires them.
+  Listing changes nothing, at any host, registry or instance.
+  An Environment refused by deploy, or whose adapter lists no
+  deployments is reported on stderr and, with --json, under unlisted. A deployment
+  whose record this SDK does not admit is still listed, from what its host knows.
+  With --json, each deployment carries its installedOn and its call target: the path of
+  its node on Admin's Services, for astrale call "<path>.method.setSecret" --admin, or the
+  namespace and script of a dispatch namespace, which the hosting kit
+  (@astrale-os/adapter-cloudflare/hosting) retires; installations says what of
+  INSTALLED ON is unknown.
+  Exit status: 0 listed, 1 a host or the registry could not be read (with --json,
+  nothing on stdout), 2 usage error.
 `,
-    deploy: `Build, verify, and deploy a Domain through its configured adapter.
+    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 deploy <environment>
-  astrale-domain deploy --environment <name>
+  astrale-domain publish <environment> [--allow-dirty] [--as <identity>] [--json]
 
 Arguments:
-  environment             Required adapter environment key.
+  environment             Required adapter environment key, usually production.
 
 Options:
-  --environment <name>    Select the environment without a positional argument.
-  --deploy-only           Suppress this run's configured Kernel installation.
-  --as <identity>         Select the Astrale identity for Services and installation calls.
-  -h, --help              Show help for deploy.
+  --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:
-  Builds and verifies the Application, Runtime, and provider artifact, loads declared
-  secrets, and invokes the selected adapter. It then verifies the resulting Release.
-  When the Environment declares installation, reconciles it after provider readiness.
-  An Environment without installation performs zero Kernel calls.
+  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.
 
@@ -160,6 +251,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

@@ -0,0 +1,83 @@
+import type { DeploymentCommitV1, DeploymentConfiguration } from '../../deployment/address/index.js';
+import type { Adapter, Build, Bundle, Placement, Release, ResolvedRuntimeReference } from '../../deployment/index.js';
+import type { DeployResultV1 } from './deploy-result.js';
+/**
+ * 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: DeploymentConfiguration;
+    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>;
+    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.
+ *
+ * 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.
+ */
+export declare function deployImmutable(input: {
+    readonly projectDir: string;
+    readonly environment: string;
+    /** A canonical Environment's adapter (CT33), which implements adapter interface v2. */
+    readonly adapter: Adapter<object>;
+    readonly parameters: object;
+    readonly build: Build;
+    readonly runtime: ResolvedRuntimeReference;
+    readonly identity?: string;
+    readonly signal: AbortSignal;
+    readonly report: (line: string) => void;
+}): Promise<DeployResultV1 | undefined>;

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

@@ -0,0 +1,135 @@
+import { resolve } from 'node:path';
+import { deploymentContent, deploymentLabel, deploymentLine, deploymentUrl, } from '../../deployment/address/index.js';
+import { assemble } from '../../deployment/index.js';
+import { bundleBuild } from './build.js';
+import { deploymentCommit } from './commit.js';
+import { deployResult } from './deploy-result.js';
+import { error } from './log.js';
+import { environmentSecrets } from './secrets.js';
+/**
+ * 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 async function planImmutableDeployment(input) {
+    const { parameters, environment, build, signal } = input;
+    const adapter = releaseAdapter(input.adapter);
+    const identity = input.identity === undefined ? {} : { identity: input.identity };
+    const bundle = await bundleBuild({
+        bundler: adapter.bundler,
+        projectDir: input.projectDir,
+        build,
+        runtime: input.runtime,
+        signal,
+    });
+    const secrets = environmentSecrets(adapter, parameters, input.projectDir, input.runtime.runtime);
+    const configuration = adapter.configure(parameters, {
+        environment,
+        secrets: Object.freeze(Object.keys(secrets).sort()),
+    });
+    const placement = await adapter.placement(parameters, { environment, signal, ...identity });
+    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 = input.commit !== undefined
+        ? input.commit
+        : await runtimeCommit(input.projectDir, input.runtime, signal);
+    return Object.freeze({
+        projectDir: input.projectDir,
+        environment,
+        adapter,
+        parameters,
+        ...identity,
+        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;
+    }
+    const result = deployResult({ environment, adapter, release, deployment: deployed });
+    input.report(`Domain: ${result.origin}`);
+    input.report(`Environment: ${environment}`);
+    input.report(`Adapter: ${result.deployment.adapter}`);
+    input.report(`Deployment: ${label} · ${result.deployment.state}`);
+    input.report(`URL: ${result.url}`);
+    input.report(`Release: ${release.document.digest}`);
+    input.report(`Build: ${release.buildDigest}`);
+    input.report(secretsLine(label, result.secrets.state));
+    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
+ * secrets are ever written. A value rewritten in place is served once the host propagated it,
+ * which is eventually consistent (about 4 s on Workers for Platforms, AM-114).
+ */
+function secretsLine(label, state) {
+    return state === 'updated'
+        ? `Secrets: updated in place on ${label}; the new values are served once propagated ` +
+            '(eventually consistent, about 4 s)'
+        : `Secrets: ${state}`;
+}
+/** The adapter of a canonical Environment: CT33 selects canonical only beside `deployRelease`. */
+function releaseAdapter(adapter) {
+    if (!('deployRelease' in adapter) || typeof adapter.deployRelease !== 'function') {
+        throw new TypeError(`Adapter ${adapter.name}@${adapter.version} implements no deployRelease and deploys no immutable deployment.`);
+    }
+    return adapter;
+}

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

@@ -1,7 +1,8 @@
 /**
  * `@astrale-os/sdk/cli` — the `astrale-domain` CLI
- * (dev | build | deploy | test | lint | package), explicit dotenv boundary, and admitted
- * development-session file representation.
+ * (build | deploy | diff | list | publish | test | lint | package | upgrade | yank, and the
+ * provider commands adapters declare), its JSON results, the deploy mode each command selects for an Environment (CT33), and the explicit
+ * dotenv boundary.
  *
  * 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,6 +12,13 @@
  * The bin lives at `./bin`.
  */
 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 { AdapterCommandReportV1 } from './adapter-command.js';
+export type { InstallationSourcesV1, InstallationUnknownReason, InstalledOnV1, InstanceSourceV1, 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 { DeployMode, DeployModeCommand, DeployRefusal } from './deploy-mode.js';
 export { loadDeclaredSecrets } from './dotenv.js';
-export { DEVELOPMENT_SESSION_FILE_VERSION, acceptDevelopmentSessionFileV1, } from './development/session-file.js';
-export type { DevelopmentSessionFileV1, DevelopmentSessionPhaseV1, DevelopmentSessionProjectV1, DevelopmentSessionReleaseV1, } from './development/session-file.js';

package/dist/tooling/cli/index.js

@@ -1,7 +1,8 @@
 /**
  * `@astrale-os/sdk/cli` — the `astrale-domain` CLI
- * (dev | build | deploy | test | lint | package), explicit dotenv boundary, and admitted
- * development-session file representation.
+ * (build | deploy | diff | list | publish | test | lint | package | upgrade | yank, and the
+ * provider commands adapters declare), its JSON results, the deploy mode each command selects for an Environment (CT33), and the explicit
+ * dotenv boundary.
  *
  * 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,5 +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';
-export { DEVELOPMENT_SESSION_FILE_VERSION, acceptDevelopmentSessionFileV1, } from './development/session-file.js';

package/dist/tooling/cli/installed-on.d.ts

@@ -0,0 +1,83 @@
+import type { DomainRegistry, InstallationUnknownReason, InstanceInstallation } from './registry/index.js';
+/**
+ * One instance known to pin a deployment (INSTALLÉ SUR, DX [.83795]): an instance named with
+ * `--instance`, as its Kernel lists it (CT24). Admin does not say which instances pin a release
+ * (A15 is deferred, AM-241), so an instance is known only when it is asked.
+ */
+export interface InstalledOnV1 {
+    readonly source: 'instance';
+    /** The instance as `--instance` named it. */
+    readonly instance: string;
+    /** The instance Kernel URL that answered. */
+    readonly kernel: string;
+}
+/**
+ * Where INSTALLÉ SUR comes from and what of it is unknown. An instance whose installations are
+ * unknown is partial, never "not installed" (AM-198); an instance is known only when `--instance`
+ * names it ([.59528], AM-241).
+ */
+export interface InstallationSourcesV1 {
+    /**
+     * True when an instance may run a deployment that no source names: an `--instance` that could
+     * not say or whose listing is itself partial (a Kernel lists only what the caller reads, AM-83,
+     * AM-84), or no `--instance` at all. False only when every `--instance` listed all it runs.
+     */
+    readonly partial: boolean;
+    /** One entry per distinct `--instance`, in argument order. */
+    readonly instances: readonly InstanceSourceV1[];
+}
+/**
+ * One `--instance`: what its Kernel answered, why that is unknown, or that it was not asked. A
+ * `read` listing names the deployments it pins; with `partial` (always, from C7) one it does not
+ * name may still run there.
+ */
+export type InstanceSourceV1 = {
+    readonly instance: string;
+    readonly state: 'read';
+    readonly kernel: string;
+    readonly partial: boolean;
+} | {
+    readonly instance: string;
+    readonly state: 'unknown';
+    readonly reason: InstallationUnknownReason;
+    readonly code: string;
+} | {
+    readonly instance: string;
+    readonly state: 'skipped';
+};
+/** What the sources answered, kept to join each listed deployment to the instances that pin it. */
+export interface InstallationsRead {
+    readonly sources: InstallationSourcesV1;
+    readonly instances: readonly {
+        readonly instance: string;
+        readonly kernel: string;
+        readonly installations: readonly InstanceInstallation[];
+    }[];
+}
+/** Nothing was listed: no source is asked. */
+export declare function skippedInstallations(instances: readonly string[]): InstallationsRead;
+/**
+ * Ask every `--instance` whether it pins a deployment of the origin. An instance that cannot tell
+ * is recorded as unknown, with why, and the listing stays partial for it (AM-198); a refusal's
+ * message is never relayed, only its code. Only a stop of `signal`, the one every registry read
+ * follows, fails it: an interrupted listing is never printed as a partial one.
+ */
+export declare function readInstallations(registry: Pick<DomainRegistry, 'instance'>, origin: string, instances: readonly string[], signal: AbortSignal): Promise<InstallationsRead>;
+/**
+ * The instances known to pin the deployment served at `url`: an installation whose Kernel lists
+ * its pin under that deployment URL runs that deployment, since one immutable deployment has one
+ * URL. In `--instance` argument order.
+ */
+export declare function installedOn(url: string, read: InstallationsRead): readonly InstalledOnV1[];
+/**
+ * The INSTALLED ON cell: the instances known to pin the deployment, then `?` when an instance may
+ * run it unnamed (the notices say which); `—` only when every `--instance` listed all it runs and
+ * none pins it.
+ */
+export declare function installedOnCell(installed: readonly InstalledOnV1[], sources: InstallationSourcesV1): string;
+/**
+ * One line for stderr per source that could not tell, or one when no instance was asked: an
+ * unknown instance is partial, never "not installed" (AM-198). Only codes the CLI reported are
+ * named, never its messages.
+ */
+export declare function installationNotices(sources: InstallationSourcesV1): readonly string[];