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

package/dist/project/install-command.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The command that installs a deployed URL on an instance, as every SDK refusal and help text
+ * names it. A deploy never installs (DX [.81399], AM-72): `astrale-domain deploy <environment>`
+ * prints a URL, and this command installs it.
+ *
+ * `--direct` sends a URL install to the instance Kernel, which the astrale CLI requires today and
+ * accepts until D13. When the CLI retires it, this is the one SDK text to change; the adapter and
+ * scaffold READMEs and templates repeat it as prose.
+ */
+export declare function installCommand(instance?: string, identity?: string): string;

package/dist/project/install-command.js

@@ -0,0 +1,13 @@
+/**
+ * The command that installs a deployed URL on an instance, as every SDK refusal and help text
+ * names it. A deploy never installs (DX [.81399], AM-72): `astrale-domain deploy <environment>`
+ * prints a URL, and this command installs it.
+ *
+ * `--direct` sends a URL install to the instance Kernel, which the astrale CLI requires today and
+ * accepts until D13. When the CLI retires it, this is the one SDK text to change; the adapter and
+ * scaffold READMEs and templates repeat it as prose.
+ */
+export function installCommand(instance = '<instance>', identity) {
+    return (`astrale domain install <url> --direct -i ${instance}` +
+        (identity === undefined ? '' : ` --as ${identity}`));
+}

package/dist/project/project.d.ts

@@ -1,12 +1,14 @@
 import type { DomainDefinitionIdentity } from '../application/index.js';
-import type { InstallationTarget } from '../deployment/adapter/index.js';
 import type { Tests } from '../testing/index.js';
 export interface ProjectEntrypoints {
     readonly runtime: string;
 }
+/**
+ * One Environment of a Project: where and how its deployments are made. It never names an
+ * instance: a deploy installs nothing, and `astrale domain install <url>` installs a deployment.
+ */
 export interface ProjectEnvironment<DeploymentValue = unknown> {
     readonly deployment: DeploymentValue;
-    readonly installation?: InstallationTarget;
 }
 /** The complete independently executable software-product definition in astrale.config.ts. */
 export interface Project<DomainDefinitionValue extends DomainDefinitionIdentity = DomainDefinitionIdentity, EnvironmentsValue extends Readonly<Record<string, ProjectEnvironment>> = Readonly<Record<string, ProjectEnvironment>>, TestsValue extends Tests | undefined = undefined> {

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

@@ -1,16 +1,14 @@
 import type { LintReportFormat } from '../linter/index.js';
-export declare const COMMANDS: readonly ['dev', 'build', 'deploy', 'test', 'lint', 'package', 'upgrade'];
+export declare const COMMANDS: readonly ['dev', 'build', 'deploy', 'list', 'test', 'lint', 'package', 'upgrade'];
 export type Command = (typeof COMMANDS)[number];
 export interface ParsedArgs {
     readonly command: Command;
     readonly env: string;
     readonly fix?: boolean;
     readonly format?: LintReportFormat;
-    readonly deployOnly?: boolean;
     readonly identity?: string;
     readonly credentialFile?: string;
     readonly suite?: string;
-    readonly sessionFile?: string;
     readonly secretsFile?: string;
     readonly channel?: string;
     readonly check?: boolean;

package/dist/tooling/cli/arguments.js

@@ -1,5 +1,15 @@
 import { isAbsolute, normalize } from 'node:path';
-export const COMMANDS = ['dev', 'build', 'deploy', 'test', 'lint', 'package', 'upgrade'];
+import { installCommand } from '../../project/install-command.js';
+export const COMMANDS = [
+    'dev',
+    'build',
+    'deploy',
+    'list',
+    'test',
+    'lint',
+    'package',
+    'upgrade',
+];
 /** Parse the frozen `astrale-domain` command grammar without performing effects. */
 export function parseArgs(argv) {
     const [command, ...rest] = argv;
@@ -8,7 +18,6 @@ export function parseArgs(argv) {
     const fix = rest.includes('--fix');
     const deployOnly = rest.includes('--deploy-only');
     const json = rest.includes('--json');
-    let sessionFile;
     let secretsFile;
     let credentialFile;
     let identity;
@@ -18,13 +27,7 @@ export function parseArgs(argv) {
     const cleaned = [];
     for (let index = 0; index < rest.length; index += 1) {
         const argument = rest[index];
-        if (argument === '--session-file') {
-            sessionFile = absoluteFilePath('--session-file', rest[++index]);
-        }
-        else if (argument.startsWith('--session-file=')) {
-            sessionFile = absoluteFilePath('--session-file', argument.slice('--session-file='.length));
-        }
-        else if (argument === '--credential-file') {
+        if (argument === '--credential-file') {
             credentialFile = absoluteFilePath('--credential-file', rest[++index]);
         }
         else if (argument.startsWith('--credential-file=')) {
@@ -72,26 +75,29 @@ export function parseArgs(argv) {
     }
     if (fix && command !== 'lint')
         throw new Error('`--fix` is only valid for `lint`.');
-    if (json && command !== 'build' && command !== 'deploy') {
-        throw new Error('`--json` is only valid for `build` or `deploy`.');
+    if (json && command !== 'build' && command !== 'deploy' && command !== 'list') {
+        throw new Error('`--json` is only valid for `build`, `deploy` or `list`.');
     }
     if (format !== undefined && command !== 'lint') {
         throw new Error('`--format` is only valid for `lint`.');
     }
-    if ((sessionFile !== undefined || credentialFile !== undefined || secretsFile !== undefined) &&
-        command !== 'dev') {
-        throw new Error('`--session-file`, `--credential-file`, and `--secrets-file` are only valid for `dev`.');
+    if ((credentialFile !== undefined || secretsFile !== undefined) && command !== 'dev') {
+        throw new Error('`--credential-file` and `--secrets-file` are only valid for `dev`.');
     }
     if (identity !== undefined && credentialFile !== undefined) {
         throw new Error('Choose either `--as` or `--credential-file`, not both.');
     }
-    if ((deployOnly || identity !== undefined) && command !== 'dev' && command !== 'deploy') {
-        throw new Error('`--deploy-only` and `--as` are only valid for `dev` or `deploy`.');
+    if (deployOnly && command !== 'dev' && command !== 'deploy')
+        refuseDeployOnly(undefined);
+    if (identity !== undefined && command !== 'dev' && command !== 'deploy' && command !== 'list') {
+        throw new Error('`--as` is only valid for `dev`, `deploy` or `list`.');
     }
-    if (environment !== undefined && command !== 'dev' && command !== 'deploy') {
-        if (command !== 'test') {
-            throw new Error('`--environment` is only valid for `dev`, `deploy`, or `test`.');
-        }
+    if (environment !== undefined &&
+        command !== 'dev' &&
+        command !== 'deploy' &&
+        command !== 'list' &&
+        command !== 'test') {
+        throw new Error('`--environment` is only valid for `dev`, `deploy`, `list` or `test`.');
     }
     if (suite !== undefined && command !== 'test') {
         throw new Error('`--suite` is only valid for `test`.');
@@ -110,17 +116,28 @@ export function parseArgs(argv) {
             if (!env) {
                 throw new Error(`\`${command}\` requires an Environment, e.g. \`${command} development\`.`);
             }
+            if (deployOnly)
+                refuseDeployOnly(command, env);
             return {
                 command,
                 env,
                 ...(json ? { json: true } : {}),
-                ...(deployOnly ? { deployOnly: true } : {}),
                 ...(identity === undefined ? {} : { identity }),
                 ...(credentialFile === undefined ? {} : { credentialFile }),
-                ...(sessionFile === undefined ? {} : { sessionFile }),
                 ...(secretsFile === undefined ? {} : { secretsFile }),
             };
         }
+        case 'list':
+            // Every Environment of the Project, or the one `--environment` names.
+            if (positionals.length > 0) {
+                throw new Error('`list` does not accept positional arguments; use `--environment`.');
+            }
+            return {
+                command: 'list',
+                env: environment ?? '',
+                ...(json ? { json: true } : {}),
+                ...(identity === undefined ? {} : { identity }),
+            };
         case 'build':
         case 'package':
             if (positionals.length > 0) {
@@ -149,6 +166,18 @@ export function parseArgs(argv) {
             throw new Error(command ? `Unknown command "${command}".` : 'Missing command.');
     }
 }
+/**
+ * `--deploy-only` suppressed the installation a deploy used to make. A deploy never installs
+ * (DX [.81399], AM-72), so the flag is refused before any effect, naming the commands that
+ * replace it. Its only consumer pins an SDK older than this refusal.
+ */
+function refuseDeployOnly(command, environment) {
+    const refusal = '`--deploy-only` is no longer accepted: a deploy never installs.';
+    if (command === undefined || environment === undefined)
+        throw new Error(refusal);
+    throw new Error(`${refusal} Run \`astrale-domain ${command} ${environment}\` without it, then install the ` +
+        `URL it prints with \`${installCommand()}\`.`);
+}
 function parseUpgrade(args) {
     let channel = 'beta';
     let check = false;

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

@@ -0,0 +1,23 @@
+import type { DeploymentCommitV1 } from '../../deployment/address/index.js';
+/**
+ * The commit provenance a canonical deploy declares in its deployment record (CT18 `commit`): the
+ * commit of the repository the Project lives in, whether the working tree holds changes that
+ * commit does not, and the last release of the Domain before it, as `git describe` finds it.
+ *
+ * - `dirty` covers tracked changes and untracked files, over the whole working tree; ignored files
+ *   never count. Unlike `git describe --dirty`, an untracked file counts, since a build can import
+ *   it.
+ * - `base` is the nearest release tag of the package the Domain is released from: the
+ *   release-please package that holds the Domain's runtime module (see {@link releaseTagPrefixes}).
+ *   The tag prefix is stripped, and a tag whose rest is not a canonical SemVer version is left
+ *   out, so the record never carries a base a deployment name would refuse (AM-57). A Domain no
+ *   release line holds declares no base: it is never given another package's version.
+ * - Outside a git repository, without git, or in a repository whose commits are not SHA-1, the
+ *   deploy declares no commit (`null`); a deploy never fails for want of provenance.
+ */
+export declare function deploymentCommit(input: {
+    readonly projectDir: string;
+    /** The Domain's runtime module, as the Project's `entrypoints.runtime` resolves it. */
+    readonly runtimeModule: string;
+    readonly signal: AbortSignal;
+}): Promise<DeploymentCommitV1 | null>;

package/dist/tooling/cli/commit.js

@@ -0,0 +1,216 @@
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { isVersion } from '../../platform/versioning/version.js';
+/** A commit as `DeploymentCommitV1` holds it: the full SHA-1 git prints, in lower case. */
+const SHA = /^[0-9a-f]{40}$/u;
+/** `git describe --long` output: `<tag>-<commits since the tag>-g<abbreviated commit>`. */
+const DESCRIBED = /^(?<tag>.+)-(?<distance>\d+)-g[0-9a-f]+$/u;
+/** A tag prefix this module can hand to `git describe --match` without escaping a glob. */
+const LITERAL_PREFIX = /^[^*?[\]\\\s]*$/u;
+/** The configuration files release-please reads at a repository root, the dotted name first. */
+const RELEASE_PLEASE_CONFIGS = ['.release-please-config.json', 'release-please-config.json'];
+const GIT_TIMEOUT_MS = 30_000;
+/**
+ * The commit provenance a canonical deploy declares in its deployment record (CT18 `commit`): the
+ * commit of the repository the Project lives in, whether the working tree holds changes that
+ * commit does not, and the last release of the Domain before it, as `git describe` finds it.
+ *
+ * - `dirty` covers tracked changes and untracked files, over the whole working tree; ignored files
+ *   never count. Unlike `git describe --dirty`, an untracked file counts, since a build can import
+ *   it.
+ * - `base` is the nearest release tag of the package the Domain is released from: the
+ *   release-please package that holds the Domain's runtime module (see {@link releaseTagPrefixes}).
+ *   The tag prefix is stripped, and a tag whose rest is not a canonical SemVer version is left
+ *   out, so the record never carries a base a deployment name would refuse (AM-57). A Domain no
+ *   release line holds declares no base: it is never given another package's version.
+ * - Outside a git repository, without git, or in a repository whose commits are not SHA-1, the
+ *   deploy declares no commit (`null`); a deploy never fails for want of provenance.
+ */
+export async function deploymentCommit(input) {
+    const head = await git(input.projectDir, input.signal, ['rev-parse', '--verify', 'HEAD']);
+    if (head === undefined || !SHA.test(head))
+        return null;
+    const status = await git(input.projectDir, input.signal, [
+        'status',
+        '--porcelain',
+        '--untracked-files=normal',
+    ]);
+    if (status === undefined)
+        return null;
+    const prefixes = await releaseTagPrefixes(input);
+    const base = prefixes === undefined ? undefined : await describedBase(input, prefixes);
+    return Object.freeze({
+        sha: head,
+        dirty: status.length > 0,
+        ...(base === undefined ? {} : { base }),
+    });
+}
+/**
+ * The prefixes of the release tags of the package the Domain is released from, or nothing when
+ * no release line holds the Domain.
+ *
+ * In a repository with a release-please configuration at its root, that package is the configured
+ * package whose path is the nearest one holding the runtime module's directory, unless one of its
+ * `exclude-paths` holds it. Its tags are named as release-please names them: `<component>`, its
+ * `tag-separator` (`-`) and `v` before the version, without the component when
+ * `include-component-in-tag` is false and without the `v` when `include-v-in-tag` is false; the
+ * component is the package's `component`, else its unscoped `package-name`, else the unscoped name
+ * in its `package.json`. Root-level options are the packages' defaults, as in release-please.
+ *
+ * Without a configuration, the tags are those `npm version` writes (`v<version>`) and
+ * `<name>-v<version>`, where the name is the unscoped one in the Project's `package.json`.
+ */
+async function releaseTagPrefixes(input) {
+    const root = await git(input.projectDir, input.signal, ['rev-parse', '--show-toplevel']);
+    if (root === undefined)
+        return undefined;
+    const config = await releasePleaseConfig(root);
+    if (config === undefined) {
+        const name = unscoped(await packageName(input.projectDir));
+        return literal(['v', ...(name === undefined ? [] : [`${name}-v`])]);
+    }
+    // Git names the module's directory relative to its repository, symbolic links resolved.
+    const located = await git(dirname(input.runtimeModule), input.signal, [
+        'rev-parse',
+        '--show-toplevel',
+        '--show-prefix',
+    ]);
+    const [moduleRoot, prefix = ''] = located?.split('\n') ?? [];
+    if (moduleRoot !== root)
+        return undefined;
+    const path = prefix.replace(/\/$/u, '');
+    const found = releasePackage(config, path);
+    if (found === undefined)
+        return undefined;
+    const option = (key) => found.options[key] ?? config[key];
+    const v = option('include-v-in-tag') === false ? '' : 'v';
+    if (option('include-component-in-tag') === false)
+        return literal([v]);
+    const separator = option('tag-separator') ?? '-';
+    const component = option('component') ??
+        unscoped(option('package-name')) ??
+        unscoped(await packageName(join(root, found.path)));
+    if (typeof component !== 'string' || component.length === 0 || typeof separator !== 'string') {
+        return undefined;
+    }
+    return literal([`${component}${separator}${v}`]);
+}
+/**
+ * The configured package that holds `path` (relative to the repository root, `''` for the root),
+ * the nearest one first, or nothing when none holds it or its `exclude-paths` do.
+ */
+function releasePackage(config, path) {
+    const packages = config.packages;
+    if (packages === null || typeof packages !== 'object' || Array.isArray(packages))
+        return undefined;
+    let found;
+    for (const [key, options] of Object.entries(packages)) {
+        if (options === null || typeof options !== 'object' || Array.isArray(options))
+            continue;
+        const packagePath = key === '.' ? '' : key.replace(/^\.\//u, '').replace(/\/$/u, '');
+        if (!holds(packagePath, path))
+            continue;
+        if (found === undefined || packagePath.length > found.path.length) {
+            found = { path: packagePath, options: options };
+        }
+    }
+    if (found === undefined)
+        return undefined;
+    const excluded = found.options['exclude-paths'] ?? config['exclude-paths'];
+    if (Array.isArray(excluded)) {
+        for (const exclusion of excluded) {
+            if (typeof exclusion !== 'string')
+                continue;
+            const relative = exclusion.replace(/^\.\//u, '').replace(/\/$/u, '');
+            if (holds(found.path === '' ? relative : `${found.path}/${relative}`, path))
+                return undefined;
+        }
+    }
+    return found;
+}
+/** Whether the directory `outer` holds `inner`, both relative to the repository root. */
+function holds(outer, inner) {
+    return outer === '' || inner === outer || inner.startsWith(`${outer}/`);
+}
+/** The canonical version and distance of the nearest tag with one of these prefixes, or nothing. */
+async function describedBase(input, prefixes) {
+    const described = await git(input.projectDir, input.signal, [
+        'describe',
+        '--tags',
+        '--long',
+        '--abbrev=40',
+        ...prefixes.flatMap((prefix) => ['--match', `${prefix}[0-9]*`]),
+        'HEAD',
+    ]);
+    const match = described === undefined ? null : DESCRIBED.exec(described);
+    if (match?.groups === undefined)
+        return undefined;
+    const tag = match.groups.tag;
+    const distance = Number(match.groups.distance);
+    const version = prefixes
+        .filter((prefix) => tag.startsWith(prefix))
+        .map((prefix) => tag.slice(prefix.length))
+        .find((rest) => isVersion(rest));
+    if (version === undefined || !Number.isSafeInteger(distance))
+        return undefined;
+    return Object.freeze({ version, distance });
+}
+/** The repository's release-please configuration, if its root has one that is a JSON object. */
+async function releasePleaseConfig(root) {
+    for (const name of RELEASE_PLEASE_CONFIGS) {
+        const config = await readJson(join(root, name));
+        if (config !== undefined)
+            return config;
+    }
+    return undefined;
+}
+/** The `name` of the `package.json` in a directory, if it has one. */
+async function packageName(directory) {
+    return (await readJson(join(directory, 'package.json')))?.name;
+}
+/** A package name without its npm scope, as release-please makes a component of it. */
+function unscoped(name) {
+    if (typeof name !== 'string' || name.length === 0)
+        return undefined;
+    return name.startsWith('@') ? name.slice(name.indexOf('/') + 1) || undefined : name;
+}
+/** The prefixes, unless one would be read as a glob by `git describe --match`. */
+function literal(prefixes) {
+    return prefixes.every((prefix) => LITERAL_PREFIX.test(prefix)) ? prefixes : undefined;
+}
+async function readJson(path) {
+    let value;
+    try {
+        value = JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+/**
+ * Run one read-only git command in a directory and return its trimmed stdout, or nothing when git
+ * is missing or the command fails. An interrupted deploy still stops here.
+ */
+function git(cwd, signal, args) {
+    signal.throwIfAborted();
+    return new Promise((resolve, reject) => {
+        execFile('git', [...args], {
+            cwd,
+            // Never take the index lock: a deploy only reads the repository.
+            env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' },
+            signal,
+            timeout: GIT_TIMEOUT_MS,
+            windowsHide: true,
+        }, (error, stdout) => {
+            if (signal.aborted) {
+                reject(signal.reason);
+                return;
+            }
+            resolve(error === null ? stdout.trim() : undefined);
+        });
+    });
+}

package/dist/tooling/cli/deploy-mode.d.ts

@@ -5,11 +5,15 @@ import type { LoadedEnvironment } from './project.js';
  * that mode still has a consumer (AM-16, AM-72).
  *
  * - `canonical`: an immutable deployment of one sealed release through the adapter's
- *   `deployRelease`, with a key generated for it, and zero Kernel calls.
+ *   `deployRelease`, with a key generated for it, and no call to any instance.
  * - `legacy-direct`: today's stable target, replaced in place through `prepare` and `deploy`, which
  *   serves a v3 Publication only. Its `reasons` name what selected it.
- * - `refused`: a shape whose only consumer pins an older SDK, refused before any effect. Each
- *   refusal carries the configuration or command to write instead.
+ * - `refused`: a shape no deploy of this SDK serves, refused before any effect. Each refusal
+ *   carries the configuration or command to write instead.
+ *
+ * A deploy never installs, so two shapes are refused before a mode is selected at all: an
+ * Environment that declares `installation` by `defineProject`, and `--deploy-only` by the
+ * command-line parser (AM-72).
  */
 export type DeployMode = {
     readonly kind: 'canonical';
@@ -31,28 +35,28 @@ export type LegacyDirectReason =
  | {
     readonly reason: 'no-namespace';
 }
-/** An adapter that declares no `deployRelease` (the contract before adapter interface v2). */
+/** An adapter that declares no `deployRelease`: the contract before adapter interface v2. */
  | {
     readonly reason: 'no-deploy-release';
 };
 export type CloudflareDirectParameter = 'route' | 'workerName' | 'identityIssuer' | 'addressing' | 'signingIdentity';
 export interface DeployRefusal {
-    readonly reason: 'installation' | 'deploy-only' | 'astrale-instance' | 'astrale-signing-identity' | 'mixed-parameters' | 'scheduled-triggers' | 'development-canonical';
+    readonly reason: 'astrale-instance' | 'astrale-signing-identity' | 'mixed-parameters' | 'scheduled-triggers' | 'development-canonical';
     /** The configuration or command to write instead, for the author. */
     readonly guidance: string;
 }
 /** The commands that select a deploy mode. `publish` refuses every Environment that is not canonical. */
 export type DeployModeCommand = 'deploy' | 'dev';
 /**
- * Select the deploy mode of one Environment (CT33). It reads the configuration and the command line
+ * Select the deploy mode of one Environment (CT33). It reads the configuration and the command
  * only, and has no effect.
  *
- * A refusal wins over every other reason: an `installation` field, `--deploy-only`, and
- * adapter-astrale `instance` or `signingIdentity` reach only the SDK, whose one consumer of them
- * pins an older SDK, so they are refused before any effect (AM-72). Otherwise the Environment is on
- * the legacy direct-mode path when adapter-cloudflare names a direct-mode parameter or no
- * `namespace`, or when its adapter declares no `deployRelease`. Everything else is canonical, except
- * under `dev`, which serves the legacy direct-mode path only.
+ * A refusal wins over every other reason. adapter-astrale deploys immutable deployments only
+ * (`deployRelease`): its removed instance mode's `instance` and `signingIdentity` are refused
+ * before any effect, since their one consumer pins an older SDK (AM-72). Otherwise the Environment
+ * is on the legacy direct-mode path when adapter-cloudflare names a direct-mode parameter or no
+ * `namespace`, or when its adapter declares no `deployRelease`. Everything else is canonical,
+ * except under `dev`, which serves the legacy direct-mode path only.
  *
  * Within canonical adapter-cloudflare (with `namespace`), a direct-mode parameter is refused
  * rather than silently selecting either mode, and so is `wrangler.triggers`: an immutable
@@ -63,5 +67,4 @@ export declare function selectDeployMode(input: {
     readonly command: DeployModeCommand;
     readonly environment: string;
     readonly definition: LoadedEnvironment;
-    readonly deployOnly: boolean;
 }): DeployMode;

package/dist/tooling/cli/deploy-mode.js

@@ -1,6 +1,11 @@
+import { installCommand } from '../../project/install-command.js';
 /** The adapter names of the first-party adapters whose parameters CT33 classifies. */
 const CLOUDFLARE = 'cloudflare';
 const ASTRALE = 'astrale';
+/** The one Environment adapter-astrale deploys without an explicit organisation (AM-7). */
+const DEVELOPMENT = 'development';
+/** The parameters that named the stable Service of adapter-astrale's removed instance mode. */
+const ASTRALE_SERVICE_PARAMETERS = ['serviceKey', 'name'];
 const CLOUDFLARE_DIRECT_PARAMETERS = [
     'route',
     'workerName',
@@ -9,15 +14,15 @@ const CLOUDFLARE_DIRECT_PARAMETERS = [
     'signingIdentity',
 ];
 /**
- * Select the deploy mode of one Environment (CT33). It reads the configuration and the command line
+ * Select the deploy mode of one Environment (CT33). It reads the configuration and the command
  * only, and has no effect.
  *
- * A refusal wins over every other reason: an `installation` field, `--deploy-only`, and
- * adapter-astrale `instance` or `signingIdentity` reach only the SDK, whose one consumer of them
- * pins an older SDK, so they are refused before any effect (AM-72). Otherwise the Environment is on
- * the legacy direct-mode path when adapter-cloudflare names a direct-mode parameter or no
- * `namespace`, or when its adapter declares no `deployRelease`. Everything else is canonical, except
- * under `dev`, which serves the legacy direct-mode path only.
+ * A refusal wins over every other reason. adapter-astrale deploys immutable deployments only
+ * (`deployRelease`): its removed instance mode's `instance` and `signingIdentity` are refused
+ * before any effect, since their one consumer pins an older SDK (AM-72). Otherwise the Environment
+ * is on the legacy direct-mode path when adapter-cloudflare names a direct-mode parameter or no
+ * `namespace`, or when its adapter declares no `deployRelease`. Everything else is canonical,
+ * except under `dev`, which serves the legacy direct-mode path only.
  *
  * Within canonical adapter-cloudflare (with `namespace`), a direct-mode parameter is refused
  * rather than silently selecting either mode, and so is `wrangler.triggers`: an immutable
@@ -30,41 +35,22 @@ export function selectDeployMode(input) {
     const parameters = definition.deployment.parameters;
     const refusals = [];
     const reasons = [];
-    const installation = definition.installation;
-    if (installation !== undefined) {
-        refusals.push({
-            reason: 'installation',
-            guidance: `Environment ${environment} declares installation, and a deploy no longer installs. ` +
-                'Remove `installation` from the Environment, run ' +
-                `\`astrale-domain deploy ${environment}\`, then install the URL it prints with ` +
-                `\`astrale domain install <url> -i ${installation.instance}` +
-                `${installation.identity === undefined ? '' : ` --as ${installation.identity}`}\`.`,
-        });
-    }
-    if (input.deployOnly) {
-        refusals.push({
-            reason: 'deploy-only',
-            guidance: '`--deploy-only` is no longer accepted: a deploy never installs. Run ' +
-                `\`astrale-domain ${command} ${environment}\` without it, then ` +
-                '`astrale domain install <url> -i <instance>`.',
-        });
-    }
-    if (adapter.name === ASTRALE) {
+    const releases = 'deployRelease' in adapter && typeof adapter.deployRelease === 'function';
+    if (adapter.name === ASTRALE && releases) {
         if (declares(parameters, 'instance')) {
             refusals.push({
                 reason: 'astrale-instance',
-                guidance: `astrale({ instance: '${String(parameters.instance)}' }) deployed through that ` +
-                    "instance's Services, which no longer hosts deployments. Remove `instance`: " +
-                    `\`astrale-domain deploy ${environment}\` makes an immutable deployment on Admin's ` +
-                    'Services, and `astrale domain install <url> -i ' +
-                    `${String(parameters.instance)}\` installs it.`,
+                guidance: astraleInstanceGuidance(parameters, environment),
             });
         }
         if (declares(parameters, 'signingIdentity')) {
             refusals.push({
                 reason: 'astrale-signing-identity',
                 guidance: 'astrale({ signingIdentity }) is no longer accepted: each deployment gets a signing key ' +
-                    'generated when it is deployed. Remove `signingIdentity`.',
+                    'generated when it is deployed. Remove `signingIdentity`' +
+                    // With `instance`, its own refusal already names the organisation.
+                    (declares(parameters, 'instance') ? '' : organizationGuidance(parameters, environment)) +
+                    '.',
             });
         }
     }
@@ -93,9 +79,8 @@ export function selectDeployMode(input) {
             reasons.push(...direct.map((parameter) => ({ reason: 'direct-parameter', parameter })), { reason: 'no-namespace' });
         }
     }
-    if (!('deployRelease' in adapter) || typeof adapter.deployRelease !== 'function') {
+    if (!releases)
         reasons.push({ reason: 'no-deploy-release' });
-    }
     if (refusals.length > 0)
         return Object.freeze({ kind: 'refused', refusals: freeze(refusals) });
     if (reasons.length > 0)
@@ -108,13 +93,37 @@ export function selectDeployMode(input) {
                     reason: 'development-canonical',
                     guidance: `\`astrale-domain dev\` serves only legacy direct-mode Environments, and ${environment} ` +
                         `deploys immutable deployments. Run \`astrale-domain deploy ${environment}\`, then ` +
-                        '`astrale domain install <url> -i <instance>`.',
+                        `\`${installCommand()}\`.`,
                 },
             ]),
         });
     }
     return Object.freeze({ kind: 'canonical' });
 }
+/**
+ * How an adapter-astrale Environment of the removed instance mode deploys now: without `instance`
+ * (nor `serviceKey` and `name`, which named its stable Service), outside development on a line its
+ * named organisation holds (AM-7), then installed by URL on the instance it used to deploy through.
+ */
+function astraleInstanceGuidance(parameters, environment) {
+    const instance = String(parameters.instance);
+    const service = ASTRALE_SERVICE_PARAMETERS.filter((name) => declares(parameters, name));
+    const removed = service.length === 0
+        ? 'Remove `instance`'
+        : `Remove \`instance\` with ${service.map((name) => `\`${name}\``).join(' and ')}, ` +
+            `which named its stable Service`;
+    const organization = organizationGuidance(parameters, environment);
+    return (`astrale({ instance: '${instance}' }) deployed through that instance's Services, which no ` +
+        `longer hosts deployments. ${removed}${organization}: \`astrale-domain deploy ${environment}\` ` +
+        `makes an immutable deployment on Admin's Services, and \`${installCommand(instance)}\` ` +
+        'installs it.');
+}
+/** Outside development, an adapter-astrale Environment names the organisation of its line (AM-7). */
+function organizationGuidance(parameters, environment) {
+    return environment === DEVELOPMENT || declares(parameters, 'organization')
+        ? ''
+        : ", and name the organisation that holds the deployment line in `astrale({ organization: '<Identity id>' })`";
+}
 /** A parameter is declared when its value is not `undefined`, as optional adapter parameters read. */
 function declares(parameters, name) {
     return Object.hasOwn(parameters, name) && parameters[name] !== undefined;