@astrale-os/sdk 0.6.0-beta.4 → 0.6.0-beta.40

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

@@ -0,0 +1,35 @@
+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>;
+/**
+ * Whether a remote-tracking branch of the repository already holds a commit. A Publication records
+ * the commit it was built from, and release-please computes the next number from the pushed
+ * history: publishing a commit nobody pushed risks the same number being computed again (tech
+ * Versioning [.73872]). Nothing when git cannot tell. Reads the local remote-tracking refs only,
+ * never the network.
+ */
+export declare function commitPushed(input: {
+    readonly projectDir: string;
+    readonly sha: string;
+    readonly signal: AbortSignal;
+}): Promise<boolean | undefined>;

package/dist/tooling/cli/commit.js

@@ -0,0 +1,235 @@
+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 }),
+    });
+}
+/**
+ * Whether a remote-tracking branch of the repository already holds a commit. A Publication records
+ * the commit it was built from, and release-please computes the next number from the pushed
+ * history: publishing a commit nobody pushed risks the same number being computed again (tech
+ * Versioning [.73872]). Nothing when git cannot tell. Reads the local remote-tracking refs only,
+ * never the network.
+ */
+export async function commitPushed(input) {
+    if (!SHA.test(input.sha))
+        return undefined;
+    const branches = await git(input.projectDir, input.signal, [
+        'branch',
+        '--remotes',
+        '--contains',
+        input.sha,
+        '--format=%(refname)',
+    ]);
+    return branches === undefined ? undefined : branches.length > 0;
+}
+/**
+ * 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

@@ -0,0 +1,26 @@
+/** A supported immutable deployment, or a configuration refused before provider effects. */
+export type DeployMode = {
+    readonly kind: 'canonical';
+} | {
+    readonly kind: 'refused';
+    readonly refusals: readonly DeployRefusal[];
+};
+export interface DeployRefusal {
+    readonly reason: 'invalid-parameters' | 'missing-namespace' | 'scheduled-triggers' | 'unsupported-adapter';
+    readonly guidance: string;
+}
+export type DeployModeCommand = 'deploy' | 'publish';
+/** Inspect one Environment's deployment contract without building or changing any provider. */
+export declare function selectDeployMode(input: {
+    readonly command: DeployModeCommand;
+    readonly environment: string;
+    readonly definition: {
+        readonly deployment: {
+            readonly adapter: {
+                readonly name: string;
+                readonly deployRelease?: unknown;
+            };
+            readonly parameters: object;
+        };
+    };
+}): DeployMode;

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

@@ -0,0 +1,59 @@
+/** Inspect one Environment's deployment contract without building or changing any provider. */
+export function selectDeployMode(input) {
+    const { adapter, parameters } = input.definition.deployment;
+    const values = parameters;
+    const refusals = [];
+    if (typeof adapter.deployRelease !== 'function') {
+        refusals.push({
+            reason: 'unsupported-adapter',
+            guidance: `Adapter ${adapter.name} must implement configure, placement and deployRelease for immutable deployments.`,
+        });
+    }
+    if (adapter.name === 'cloudflare') {
+        if (values.namespace === undefined) {
+            refusals.push({
+                reason: 'missing-namespace',
+                guidance: 'cloudflare requires namespace: { name, routingDomain }. Use astrale() for managed deployments.',
+            });
+        }
+        const allowed = [
+            'namespace',
+            'secrets',
+            'vars',
+            'maximumRequestBytes',
+            'invocationTimeoutMs',
+            'tokenExchange',
+            'durable',
+            'wrangler',
+            'router',
+        ];
+        const unknown = Reflect.ownKeys(values).filter((key) => typeof key !== 'string' || !allowed.includes(key));
+        if (unknown.length > 0)
+            refusals.push({
+                reason: 'invalid-parameters',
+                guidance: `Cloudflare Environment ${input.environment} declares unknown parameters ${unknown.map(String).join(', ')}.`,
+            });
+        const wrangler = values.wrangler;
+        if (wrangler !== undefined && Object.hasOwn(wrangler, 'triggers')) {
+            refusals.push({
+                reason: 'scheduled-triggers',
+                guidance: 'Immutable deployments run no cron of their own. Remove wrangler.triggers.',
+            });
+        }
+    }
+    if (adapter.name === 'astrale') {
+        const allowed = ['admin', 'secrets', 'vars', 'maximumRequestBytes', 'tokenExchange', 'durable'];
+        const unknown = Reflect.ownKeys(values).filter((key) => typeof key !== 'string' || !allowed.includes(key));
+        if (unknown.length > 0)
+            refusals.push({
+                reason: 'invalid-parameters',
+                guidance: `Astrale Environment ${input.environment} declares unknown parameters ${unknown.map(String).join(', ')}.`,
+            });
+    }
+    return refusals.length === 0
+        ? Object.freeze({ kind: 'canonical' })
+        : Object.freeze({
+            kind: 'refused',
+            refusals: Object.freeze(refusals.map((r) => Object.freeze(r))),
+        });
+}

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

@@ -0,0 +1,80 @@
+import type { Revision } from '@astrale-os/kernel-dsl/v1/addressing';
+import type { ReleaseDigest } from '@astrale-os/kernel-protocol/release';
+import type { DeploymentCommitV1 } from '../../deployment/address/index.js';
+import type { BuildDigest, DeploymentSecretsState, ReadyReleaseDeployResult, Release } from '../../deployment/index.js';
+export type { DeploymentSecretsState } from '../../deployment/index.js';
+/**
+ * `astrale-domain deploy <environment> --json` on stdout: the one deployment the deploy made or
+ * reused, which CI installs by its URL. Progress and warnings go to stderr. It names no instance
+ * and no version: a deploy numbers nothing and installs nothing.
+ */
+export interface DeployResultV1 {
+    readonly format: 'astrale.deploy-result';
+    readonly version: 1;
+    readonly origin: string;
+    readonly environment: string;
+    /**
+     * The URL `astrale domain install <url>` takes: an immutable deployment's URL, which is also its
+     * issuer.
+     */
+    readonly url: string;
+    /**
+     * The digest of the DomainRelease v4 served at release.json.
+     */
+    readonly release: {
+        readonly digest: ReleaseDigest;
+    };
+    /**
+     * The build digest of the code the deployment runs, as astrale-domain build prints it.
+     */
+    readonly build: {
+        readonly digest: BuildDigest;
+    };
+    readonly schema: {
+        readonly revision: Revision;
+    };
+    readonly deployment: {
+        /** `<adapter name>@<adapter version>` */
+        readonly adapter: string;
+        /**
+         * The provider script that serves this deployment: an immutable deployment's label, which is
+         * also the first label of its URL.
+         */
+        readonly script: string;
+        /**
+         * `created`: a new immutable deployment. `reused`: the immutable deployment of this exact
+         * release already existed.
+         */
+        readonly state: 'created' | 'reused';
+    };
+    /**
+     * Immutable deployments only: the environment's current secrets were `bound` to a new
+     * deployment, or `updated` or left `unchanged` in place on the reused one. A deploy never writes
+     * the secrets of any other deployment.
+     */
+    readonly secrets: {
+        readonly state: DeploymentSecretsState;
+    };
+    /**
+     * The commit the deployment was built from, as its deployment record declares it: the commit of
+     * the deploy that created it. A reused deployment keeps its record, so this can be an earlier
+     * commit than the one the deploy ran from; the label covers the release, never the commit.
+     */
+    readonly commit: DeploymentCommitV1 | null;
+}
+/**
+ * The deploy result of one immutable deployment, from the ready result of the adapter's
+ * `deployRelease`. Its release, build, Schema revision and URL are those the SDK sealed before
+ * deploying; the deployment record the adapter returned must declare exactly that release at that
+ * URL, so the result never names a release the deployment does not serve. Its commit is the
+ * record's, which a reused deployment kept from the deploy that created it.
+ */
+export declare function deployResult(input: {
+    readonly environment: string;
+    readonly adapter: {
+        readonly name: string;
+        readonly version: string;
+    };
+    readonly release: Release;
+    readonly deployment: ReadyReleaseDeployResult;
+}): DeployResultV1;

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

@@ -0,0 +1,64 @@
+import { acceptDeploymentRecord } from '../../deployment/address/index.js';
+import { addressing, isRelease } from '../../deployment/index.js';
+const SECRETS_BY_STATE = Object.freeze({
+    created: Object.freeze(['bound']),
+    reused: Object.freeze(['updated', 'unchanged']),
+});
+/**
+ * The deploy result of one immutable deployment, from the ready result of the adapter's
+ * `deployRelease`. Its release, build, Schema revision and URL are those the SDK sealed before
+ * deploying; the deployment record the adapter returned must declare exactly that release at that
+ * URL, so the result never names a release the deployment does not serve. Its commit is the
+ * record's, which a reused deployment kept from the deploy that created it.
+ */
+export function deployResult(input) {
+    const { release, deployment } = input;
+    if (!isRelease(release))
+        throw new TypeError('Deploy result requires a sealed Release.');
+    if (deployment.status !== 'ready') {
+        throw new TypeError('Deploy result requires the ready result of deployRelease.');
+    }
+    const record = acceptDeploymentRecord(deployment.record);
+    const { document } = release;
+    expectSame('origin', record.origin, document.origin);
+    expectSame('environment', record.environment, input.environment);
+    expectSame('release digest', record.releaseDigest, document.digest);
+    expectSame('build digest', record.buildDigest, release.buildDigest);
+    expectSame('Schema revision', record.schemaRevision, document.schema.revision);
+    const url = addressing(deployment.url).issuer;
+    expectSame('URL', url, release.url);
+    if (new URL(url).hostname.split('.')[0] !== record.providerScript) {
+        throw new TypeError(`Deployment URL ${url} is not addressed by its provider script ${record.providerScript}.`);
+    }
+    const allowed = Object.hasOwn(SECRETS_BY_STATE, deployment.state)
+        ? SECRETS_BY_STATE[deployment.state]
+        : undefined;
+    if (allowed === undefined)
+        throw new TypeError('Deployment state must be created or reused.');
+    const secrets = deployment.secrets?.state;
+    if (!allowed.includes(secrets)) {
+        throw new TypeError(`A ${deployment.state} deployment has its secrets ${allowed.join(' or ')}, not ${String(secrets)}.`);
+    }
+    return Object.freeze({
+        format: 'astrale.deploy-result',
+        version: 1,
+        origin: document.origin,
+        environment: record.environment,
+        url,
+        release: Object.freeze({ digest: document.digest }),
+        build: Object.freeze({ digest: release.buildDigest }),
+        schema: Object.freeze({ revision: record.schemaRevision }),
+        deployment: Object.freeze({
+            adapter: `${input.adapter.name}@${input.adapter.version}`,
+            script: record.providerScript,
+            state: deployment.state,
+        }),
+        secrets: Object.freeze({ state: secrets }),
+        commit: record.commit,
+    });
+}
+function expectSame(member, declared, expected) {
+    if (declared !== expected) {
+        throw new TypeError(`Deployment declares ${member} ${declared}, not ${expected}.`);
+    }
+}

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

@@ -0,0 +1,7 @@
+import type { Version } from '../../../platform/versioning/index.js';
+/**
+ * The version the author declares for the next release: `package.json` `version` in the Project
+ * directory, as release-please and `npm version` write it (tech Versioning [.21210]). No command
+ * takes a version number.
+ */
+export declare function declaredVersion(projectDir: string): Promise<Version>;

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

@@ -0,0 +1,27 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { acceptVersion } from '../../../platform/versioning/index.js';
+/**
+ * The version the author declares for the next release: `package.json` `version` in the Project
+ * directory, as release-please and `npm version` write it (tech Versioning [.21210]). No command
+ * takes a version number.
+ */
+export async function declaredVersion(projectDir) {
+    const path = join(projectDir, 'package.json');
+    let manifest;
+    try {
+        manifest = JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch (cause) {
+        throw new TypeError(`Cannot read the Domain's version: ${path} is not a readable JSON file.`, {
+            cause,
+        });
+    }
+    const version = typeof manifest === 'object' && manifest !== null && !Array.isArray(manifest)
+        ? manifest.version
+        : undefined;
+    if (typeof version !== 'string') {
+        throw new TypeError(`${path} declares no version. The Domain's version is the package.json version, for example written by npm version minor.`);
+    }
+    return acceptVersion(version);
+}

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

@@ -0,0 +1,30 @@
+import type { Build } from '../../../deployment/index.js';
+import type { DomainRegistry } from '../registry/index.js';
+export type { DiffChangeV1, DiffReportV1 } from './report.js';
+export interface DiffCommandInput {
+    readonly projectDir: string;
+    readonly build: Build;
+    /** The build digest of every distinct bundler of the Project, bundled on demand. */
+    readonly builds: () => Promise<readonly string[]>;
+    readonly identity?: string;
+    readonly json: boolean;
+    readonly signal: AbortSignal;
+}
+export interface DiffCommandDependencies {
+    readonly open: (input: {
+        readonly projectDir: string;
+        readonly identity?: string;
+        readonly signal: AbortSignal;
+    }) => Promise<DomainRegistry>;
+    readonly stdout: (text: string) => void;
+    readonly stderr: (text: string) => void;
+}
+/**
+ * `astrale-domain diff [--as <identity>] [--json]`: the changes since the highest published stable
+ * version up to the declared one, and the smallest version they admit (tech Versioning [.72565]).
+ * On a feature branch the declared version is still the published one and the report is
+ * informational (exit 0); on a release PR an unpublished version that is too low fails (exit 1)
+ * with the [.105820] message. Reads the registry through the Astrale CLI under the caller's own
+ * credential and changes nothing.
+ */
+export declare function runDiff(input: DiffCommandInput, dependencies?: DiffCommandDependencies): Promise<number>;

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

@@ -0,0 +1,58 @@
+import * as bundle from '@astrale-os/kernel-dsl/v1/bundle/transport';
+import { DIM, RED, RESET } from '../log.js';
+import { RegistryCliError, openDomainRegistry } from '../registry/index.js';
+import { declaredVersion } from './declared.js';
+import { diffExitCode, renderDiff } from './render.js';
+import { diffReport, publishedSchema } from './report.js';
+/**
+ * `astrale-domain diff [--as <identity>] [--json]`: the changes since the highest published stable
+ * version up to the declared one, and the smallest version they admit (tech Versioning [.72565]).
+ * On a feature branch the declared version is still the published one and the report is
+ * informational (exit 0); on a release PR an unpublished version that is too low fails (exit 1)
+ * with the [.105820] message. Reads the registry through the Astrale CLI under the caller's own
+ * credential and changes nothing.
+ */
+export async function runDiff(input, dependencies = {
+    open: openDomainRegistry,
+    stdout: (text) => void process.stdout.write(text),
+    stderr: (text) => void process.stderr.write(text),
+}) {
+    const root = input.build.schema.compiled.root;
+    let report;
+    try {
+        const declared = await declaredVersion(input.projectDir);
+        const registry = await dependencies.open({
+            projectDir: input.projectDir,
+            ...(input.identity === undefined ? {} : { identity: input.identity }),
+            signal: input.signal,
+        });
+        report = await diffReport({
+            origin: root.origin,
+            declared,
+            revision: root.revision,
+            index: await registry.index(root.origin),
+            current: () => bundle.decode(input.build.schema.bundle.bytes()).root,
+            builds: input.builds,
+            published: async (publication) => publishedSchema(await registry.bundle(root.origin, publication), publication, root.origin),
+        });
+    }
+    catch (cause) {
+        if (!(cause instanceof RegistryCliError))
+            throw cause;
+        // Nothing on stdout: a JSON consumer reads one report or nothing.
+        dependencies.stderr(`${RED}✗${RESET} Domain registry: ${cause.code}: ${cause.message}\n`);
+        return 1;
+    }
+    const rendered = renderDiff(report);
+    // With --json, stdout carries only the report and the summary moves to stderr, as for deploy.
+    const summary = input.json ? dependencies.stderr : dependencies.stdout;
+    // The sentence takes the progress mark; the member rows below it keep their indentation.
+    for (const line of rendered.summary) {
+        summary(line.startsWith('  ') ? `${line}\n` : `${DIM}›${RESET} ${line}\n`);
+    }
+    if (rendered.refusal.length > 0)
+        dependencies.stderr(`${rendered.refusal.join('\n')}\n`);
+    if (input.json)
+        dependencies.stdout(`${JSON.stringify(report, null, 2)}\n`);
+    return diffExitCode(report);
+}

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

@@ -0,0 +1,15 @@
+import type { DiffReportV1 } from './report.js';
+/**
+ * 0 when the declared version is accepted, already published (the report is then informational:
+ * a feature branch keeps the last published number until its release), or has nothing to compare
+ * with; 1 when an unpublished declared version is too low.
+ */
+export declare function diffExitCode(report: DiffReportV1): 0 | 1;
+/**
+ * The report for a person. `summary` describes the comparison; `refusal` is the [.105820] message
+ * for an unpublished version that is too low (tech Versioning), printed as an error.
+ */
+export declare function renderDiff(report: DiffReportV1): {
+    readonly summary: readonly string[];
+    readonly refusal: readonly string[];
+};