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

package/dist/tooling/cli/arguments.js

@@ -1,6 +1,19 @@
 import { isAbsolute, normalize } from 'node:path';
+import { acceptVersion } from '../../platform/versioning/index.js';
 import { installCommand } from '../../project/install-command.js';
-export const COMMANDS = ['dev', 'build', 'deploy', 'test', 'lint', 'package', 'upgrade'];
+export const COMMANDS = [
+    'dev',
+    'build',
+    'deploy',
+    'diff',
+    'list',
+    'publish',
+    'test',
+    'lint',
+    'package',
+    'upgrade',
+    'yank',
+];
 /** Parse the frozen `astrale-domain` command grammar without performing effects. */
 export function parseArgs(argv) {
     const [command, ...rest] = argv;
@@ -9,6 +22,8 @@ export function parseArgs(argv) {
     const fix = rest.includes('--fix');
     const deployOnly = rest.includes('--deploy-only');
     const json = rest.includes('--json');
+    const undo = rest.includes('--undo');
+    const allowDirty = rest.includes('--allow-dirty');
     let secretsFile;
     let credentialFile;
     let identity;
@@ -54,7 +69,11 @@ export function parseArgs(argv) {
         else if (argument.startsWith('--suite=')) {
             suite = requiredValue('--suite', argument.slice('--suite='.length));
         }
-        else if (argument === '--fix' || argument === '--deploy-only' || argument === '--json') {
+        else if (argument === '--fix' ||
+            argument === '--deploy-only' ||
+            argument === '--json' ||
+            argument === '--undo' ||
+            argument === '--allow-dirty') {
             continue;
         }
         else if (argument.startsWith('-')) {
@@ -66,9 +85,20 @@ 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 !== 'diff' &&
+        command !== 'list' &&
+        command !== 'publish' &&
+        command !== 'yank') {
+        throw new Error('`--json` is only valid for `build`, `deploy`, `diff`, `list`, `publish` or `yank`.');
     }
+    if (allowDirty && command !== 'publish') {
+        throw new Error('`--allow-dirty` is only valid for `publish`.');
+    }
+    if (undo && command !== 'yank')
+        throw new Error('`--undo` is only valid for `yank`.');
     if (format !== undefined && command !== 'lint') {
         throw new Error('`--format` is only valid for `lint`.');
     }
@@ -80,13 +110,20 @@ export function parseArgs(argv) {
     }
     if (deployOnly && command !== 'dev' && command !== 'deploy')
         refuseDeployOnly(undefined);
-    if (identity !== undefined && command !== 'dev' && command !== 'deploy') {
-        throw new Error('`--as` is only valid for `dev` or `deploy`.');
+    if (identity !== undefined &&
+        command !== 'dev' &&
+        command !== 'deploy' &&
+        command !== 'diff' &&
+        command !== 'list' &&
+        command !== 'publish') {
+        throw new Error('`--as` is only valid for `dev`, `deploy`, `diff`, `list` or `publish`.');
     }
-    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`.');
@@ -116,12 +153,47 @@ export function parseArgs(argv) {
                 ...(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) {
                 throw new Error(`\`${command}\` does not accept positional arguments.`);
             }
             return { command, env: '', ...(json ? { json: true } : {}) };
+        case 'diff':
+            // The version is package.json's: no command takes a version number (tech Versioning).
+            if (positionals.length > 0) {
+                throw new Error('`diff` does not accept positional arguments; it reads package.json.');
+            }
+            return {
+                command: 'diff',
+                env: '',
+                ...(json ? { json: true } : {}),
+                ...(identity === undefined ? {} : { identity }),
+            };
+        case 'publish': {
+            // The version is package.json's: the one positional names the Environment (tech Versioning).
+            if (positionals.length !== 1) {
+                throw new Error('`publish` takes exactly one Environment, e.g. `publish production`; it reads the version from package.json.');
+            }
+            return {
+                command: 'publish',
+                env: positionals[0],
+                ...(json ? { json: true } : {}),
+                ...(allowDirty ? { allowDirty: true } : {}),
+                ...(identity === undefined ? {} : { identity }),
+            };
+        }
         case 'test':
             if (positionals.length > 0) {
                 throw new Error('`test` does not accept positional arguments; use `--environment`.');
@@ -131,6 +203,18 @@ export function parseArgs(argv) {
                 env: environment ?? '',
                 ...(suite === undefined ? {} : { suite }),
             };
+        case 'yank': {
+            if (positionals.length !== 1) {
+                throw new Error('`yank` takes exactly one published version, e.g. `yank 1.5.0`.');
+            }
+            return {
+                command: 'yank',
+                env: '',
+                version: acceptVersion(positionals[0]),
+                ...(undo ? { undo: true } : {}),
+                ...(json ? { json: true } : {}),
+            };
+        }
         case 'lint':
             if (positionals.length > 0)
                 throw new Error('`lint` does not accept positional arguments.');

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

@@ -21,3 +21,15 @@ export declare function deploymentCommit(input: {
     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

@@ -46,6 +46,25 @@ export async function deploymentCommit(input) {
         ...(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.

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

@@ -1,11 +1,10 @@
-import type { LoadedEnvironment } from './project.js';
 /**
  * The deploy mode of one Environment for one command (CT33), chosen by the configuration itself:
  * an unchanged configuration keeps its mode, and so its behaviour, across an SDK upgrade, as long as
  * 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 no deploy of this SDK serves, refused before any effect. Each refusal
@@ -35,32 +34,32 @@ export type LegacyDirectReason =
  | {
     readonly reason: 'no-namespace';
 }
-/**
- * An adapter that declares no `deployRelease` (the contract before adapter interface v2),
- * adapter-astrale's instance mode among them until adapter-astrale implements it.
- */
+/** 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: 'astrale-instance' | 'astrale-signing-identity' | 'mixed-parameters' | 'scheduled-triggers' | 'development-canonical';
+    readonly reason: 'astrale-instance' | 'astrale-signing-identity' | 'mixed-parameters' | 'scheduled-triggers' | 'development-canonical' | 'publish-legacy-direct';
     /** 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';
+/**
+ * The commands that select a deploy mode. `publish` names only an immutable deployment, so it
+ * refuses every Environment that is not canonical (CT33, R-G03).
+ */
+export type DeployModeCommand = 'deploy' | 'dev' | 'publish';
 /**
  * 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. Once adapter-astrale deploys immutable deployments
- * (`deployRelease`), its `instance` and `signingIdentity` are refused before any effect: their one
- * consumer pins an older SDK (AM-72). Until then they select its instance mode, on the legacy path
- * with every adapter that declares no `deployRelease`. 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. `publish` refuses the legacy
+ * direct-mode path: a stable target serves no release, so no version can name it.
  *
  * 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
@@ -70,5 +69,14 @@ export type DeployModeCommand = 'deploy' | 'dev';
 export declare function selectDeployMode(input: {
     readonly command: DeployModeCommand;
     readonly environment: string;
-    readonly definition: LoadedEnvironment;
+    /** The Environment's definition, of which selection reads only the adapter and its parameters. */
+    readonly definition: {
+        readonly deployment: {
+            readonly adapter: {
+                readonly name: string;
+                readonly deployRelease?: unknown;
+            };
+            readonly parameters: object;
+        };
+    };
 }): DeployMode;

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

@@ -2,6 +2,10 @@ 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',
@@ -13,13 +17,13 @@ const CLOUDFLARE_DIRECT_PARAMETERS = [
  * 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. Once adapter-astrale deploys immutable deployments
- * (`deployRelease`), its `instance` and `signingIdentity` are refused before any effect: their one
- * consumer pins an older SDK (AM-72). Until then they select its instance mode, on the legacy path
- * with every adapter that declares no `deployRelease`. 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. `publish` refuses the legacy
+ * direct-mode path: a stable target serves no release, so no version can name it.
  *
  * 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
@@ -37,17 +41,17 @@ export function selectDeployMode(input) {
         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 \`${installCommand(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)) +
+                    '.',
             });
         }
     }
@@ -80,6 +84,14 @@ export function selectDeployMode(input) {
         reasons.push({ reason: 'no-deploy-release' });
     if (refusals.length > 0)
         return Object.freeze({ kind: 'refused', refusals: freeze(refusals) });
+    if (reasons.length > 0 && command === 'publish') {
+        return Object.freeze({
+            kind: 'refused',
+            refusals: freeze([
+                { reason: 'publish-legacy-direct', guidance: publishGuidance(environment, reasons) },
+            ]),
+        });
+    }
     if (reasons.length > 0)
         return Object.freeze({ kind: 'legacy-direct', reasons: freeze(reasons) });
     if (command === 'dev') {
@@ -97,6 +109,48 @@ export function selectDeployMode(input) {
     }
     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>' })`";
+}
+/**
+ * Why a legacy direct-mode Environment cannot be published, and the configuration that makes it
+ * publishable: a version names an immutable deployment's release, which a stable target never
+ * serves.
+ */
+function publishGuidance(environment, reasons) {
+    const deploys = `\`astrale-domain publish ${environment}\` names an immutable deployment's release, and ${environment} deploys`;
+    if (reasons.some(({ reason }) => reason === 'no-deploy-release')) {
+        return (`${deploys} through an adapter without deployRelease, which replaces a stable target in ` +
+            'place and serves no release. Use an adapter that implements deployRelease (adapter ' +
+            "interface v2), such as astrale() on Admin's Services.");
+    }
+    const direct = reasons.flatMap((reason) => reason.reason === 'direct-parameter' ? [reason.parameter] : []);
+    return (`${deploys} on cloudflare()'s legacy direct mode, which serves no release. Deploy it into a ` +
+        'dispatch namespace with cloudflare({ namespace })' +
+        (direct.length === 0 ? '' : ` and remove ${direct.join(', ')}`) +
+        ", or on Admin's Services with astrale().");
+}
 /** 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;

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[];
+};