@astrale-os/adapter-astrale 0.5.0-beta.13 → 0.5.0-beta.130

package/README.md

@@ -8,4 +8,59 @@ During the SDK beta program, install the beta package set explicitly:
 npm install @astrale-os/sdk@beta @astrale-os/adapter-astrale@beta
 ```
 
-Bare installs return to stable releases when the package set is promoted and npm `latest` advances.
+One adapter value configures one Project Environment:
+
+```ts
+export default defineProject({
+  application,
+  environments: {
+    development: {
+      deployment: astrale({ secrets: '.env.dev' }),
+      installation: { instance: 'customer-development' },
+    },
+    preview: {
+      deployment: astrale({ instance: 'customer-development' }),
+    },
+  },
+})
+```
+
+For an installed Environment, the adapter deploys through the Services Domain on
+`installation.instance`; the generic Project orchestrator then reconciles the ready Release onto
+that same Kernel. An Environment without installation must provide `astrale({ instance })` and
+performs no Kernel installation calls. Declaring both coordinates is permitted only when they are
+equal.
+
+`astrale-domain dev <environment>` and `astrale-domain deploy <environment>` use the same remote
+provider path. The adapter starts no local Worker, Vite server, or tunnel. Stopping a watcher retains
+the remote Service, stable issuer, secrets, and optional installation. `--deploy-only` suppresses
+only the generic installation stage for that invocation.
+
+The adapter sends provider-neutral deployment material: Services receives no Schema revision,
+Publication identity, issuer, or callable inventory. It admits exact Services evidence, assembles
+the expected Release from the local Build, and verifies the live Publication before returning.
+Public HTTPS readiness is cancellable and bounded to ten minutes, allowing a new managed
+hostname's certificate to propagate. It returns immediately once verification succeeds;
+certificate verification is never disabled. A timeout retains the provider deployment so
+retrying the same Environment reuses its Service rather than allocating another hostname.
+For a bundled frontend, readiness also verifies the exact browser-file generation on its View
+routes. A frontend-only change does not need a Schema revision or Kernel reinstall. HTML responses
+are not cached, so a refreshed View cannot reuse a browser-cached document naming retired assets.
+Provider deletion and consumer installation remain independent lifecycle operations.
+
+Services is also the cross-machine serialization boundary for one managed Service. Its graph
+operation receipt admits one deployment at a time, and provider promotion is conditional on the
+observed Cloudflare digest. The SDK separately locks the Project Environment inside one checkout
+and the resolved `Kernel issuer + Domain origin` across local checkouts, including bookmark aliases;
+neither local lease is
+the distributed safety mechanism.
+
+For an installed Environment with a frontend, development opens the default installed View and
+reports its page URL. Each successful update refreshes that same local View session in place;
+stopping closes the View session while retaining the Service and Domain installation. The existing
+private `--credential-file` flag authenticates provider, installation, and View calls without
+placing the credential in Project configuration or evidence.
+
+Automation may add `--session-file /private/path/development-session.json`. The SDK exclusively
+creates that non-existent path inside a caller-owned private directory and retains one atomic,
+versioned `DevelopmentSessionFileV1` snapshot. It never contains secrets.

package/dist/adapter.d.ts

@@ -1,17 +1,9 @@
-import type { ArtifactSource, PrepareContext, WatchContext, WatchHandle } from '@astrale-os/sdk/deployment/adapter';
-import { signingIdentity } from '@astrale-os/adapter-cloudflare/build';
+import type { Deployment } from '@astrale-os/sdk/deployment';
+import type { ArtifactSource, PrepareContext } from '@astrale-os/sdk/deployment/adapter';
+import type { AstraleDeployDependencies } from './deploy/deploy.js';
 import type { AstraleParams } from './params.js';
-import { callAstrale, runAstrale } from './cli.js';
-import { ensureServices } from './prerequisite.js';
-import { waitForReadiness } from './service/readiness.js';
-export interface AstraleDependencies {
+export interface AstraleDependencies extends AstraleDeployDependencies {
     prepare(parameters: AstraleParams, context: PrepareContext): Promise<ArtifactSource>;
-    watch(parameters: AstraleParams, context: WatchContext): Promise<WatchHandle>;
-    ensureServices: typeof ensureServices;
-    callAstrale: typeof callAstrale;
-    runAstrale: typeof runAstrale;
-    waitForReadiness: typeof waitForReadiness;
-    signingIdentity: typeof signingIdentity;
 }
-export declare function astrale(environments: Readonly<Record<string, AstraleParams>>): import("@astrale-os/sdk/deployment/adapter").Adapter<AstraleParams>;
-export declare function astraleWithDependencies(environments: Readonly<Record<string, AstraleParams>>, dependencies: AstraleDependencies): import("@astrale-os/sdk/deployment/adapter").Adapter<AstraleParams>;
+export declare function astrale(parameters?: AstraleParams): Deployment<AstraleParams>;
+export declare function astraleWithDependencies(parameters: AstraleParams, dependencies: AstraleDependencies): Deployment<AstraleParams>;

package/dist/adapter.js

@@ -1,276 +1,54 @@
-import { cloudflare } from '@astrale-os/adapter-cloudflare';
-import { signingIdentity, signingIdentitySecrets } from '@astrale-os/adapter-cloudflare/build';
-import { defineAdapter } from '@astrale-os/sdk/deployment/adapter';
-import { addressing, assemble } from '@astrale-os/sdk/deployment/release';
+import { verifyWorkerFrontend } from '@astrale-os/adapter-cloudflare/build';
+import { signingIdentity } from '@astrale-os/adapter-cloudflare/identity';
+import { defineAdapter, defineDeployment } from '@astrale-os/sdk/deployment/adapter';
+import { verifyReadiness } from '@astrale-os/sdk/deployment/verify';
 import { createRequire } from 'node:module';
-import { callAstrale, identityArguments, runAstrale } from './cli.js';
-import { ensureServices, ServicesPrerequisiteError } from './prerequisite.js';
-import { serviceName, servicePath, servicesDeployMethod } from './service/addressing.js';
-import { deploymentPayload } from './service/artifact.js';
-import { waitForReadiness } from './service/readiness.js';
-const SERVICES_ORIGIN = 'services.astrale.ai';
-const NONE = Object.freeze({ kind: 'none' });
+import { callAstrale } from './cli/commands/call.js';
+import { installDomain } from './cli/commands/install-domain.js';
+import { introspectDomain } from './cli/commands/introspect.js';
+import { requireCliVersion } from './cli/commands/version.js';
+import { resolveCliExecutable } from './cli/executable.js';
+import { deployAstrale } from './deploy/deploy.js';
+import { ensureServices } from './deploy/ensure-services.js';
+import { waitForReadiness } from './deploy/readiness.js';
+import { prepareAstrale } from './prepare/prepare.js';
 const packageVersion = createRequire(import.meta.url)('../package.json')
     .version;
-const local = cloudflare({ internal: {} });
-export function astrale(environments) {
-    return astraleWithDependencies(environments, {
-        prepare: (parameters, context) => local.prepare(cloudflareParameters(parameters, false), context),
-        watch: (parameters, context) => local.watch(cloudflareParameters(parameters, true), context),
+export function astrale(parameters = {}) {
+    return astraleWithDependencies(parameters, {
+        prepare: prepareAstrale,
         ensureServices,
         callAstrale,
-        runAstrale,
-        waitForReadiness,
+        introspectDomain,
+        installDomain,
+        requireCliVersion,
+        resolveCliExecutable,
+        waitForReadiness: (release, signal, worker) => waitForReadiness(release, signal, async (release, options) => {
+            await verifyReadiness(release, options);
+            await verifyWorkerFrontend(release, worker, options);
+        }),
         signingIdentity,
     });
 }
-export function astraleWithDependencies(environments, dependencies) {
-    return defineAdapter({
+export function astraleWithDependencies(parameters, dependencies) {
+    const adapter = defineAdapter({
         name: 'astrale',
         version: packageVersion,
-        environments,
-        prepare: dependencies.prepare,
-        watch: dependencies.watch,
-        async deploy(parameters, context) {
-            if (parameters.instance === undefined) {
-                return failed('prerequisite', progress(), new TypeError('Astrale deployment requires an instance.'));
-            }
-            let secrets;
-            let signing;
-            try {
-                signing = await dependencies.signingIdentity({
-                    projectDir: context.projectDir,
-                    source: parameters.signingIdentity,
-                    origin: context.artifact.build.schema.compiled.root.origin,
-                    mode: 'deploy',
-                });
-                secrets = signingIdentitySecrets(context.secrets, signing);
-            }
-            catch (cause) {
-                return failed('prerequisite', progress(), cause);
-            }
-            const instance = parameters.instance;
-            const servicesOrigin = parameters.servicesOrigin ?? SERVICES_ORIGIN;
-            const identity = identityArguments(parameters.identity);
-            let prerequisite;
-            try {
-                const evidence = await dependencies.ensureServices({
-                    projectDir: context.projectDir,
-                    instance,
-                    servicesOrigin,
-                    identity,
-                    run: dependencies.runAstrale,
-                });
-                prerequisite =
-                    evidence.state === 'installed'
-                        ? Object.freeze({ kind: 'applied', evidence })
-                        : NONE;
-            }
-            catch (cause) {
-                const prerequisite = cause instanceof ServicesPrerequisiteError && cause.mutation === 'installed'
-                    ? Object.freeze({
-                        kind: 'applied',
-                        evidence: Object.freeze({ origin: servicesOrigin, state: 'installed' }),
-                    })
-                    : cause instanceof ServicesPrerequisiteError && cause.mutation === 'unknown'
-                        ? Object.freeze({ kind: 'unknown' })
-                        : NONE;
-                return failed('prerequisite', progress({ prerequisite }), cause);
-            }
-            const origin = context.artifact.build.schema.compiled.root.origin;
-            const name = parameters.name ?? serviceName(origin);
-            let payload;
-            try {
-                payload = deploymentPayload(context.artifact, { origin, name, vars: parameters.vars });
-            }
-            catch (cause) {
-                return failed('provider', progress({ prerequisite }), cause);
-            }
-            let deployed;
-            try {
-                deployed = await dependencies.callAstrale({
-                    projectDir: context.projectDir,
-                    instance,
-                    path: servicesDeployMethod(servicesOrigin),
-                    identity,
-                    data: payload,
-                });
-            }
-            catch (cause) {
-                return failed('provider', progress({ prerequisite, provider: { kind: 'unknown' } }), cause);
-            }
-            const expectedPath = servicePath(origin);
-            let observation;
-            try {
-                observation = deployedService(deployed, expectedPath);
-            }
-            catch (cause) {
-                return failed('provider', progress({
-                    prerequisite,
-                    provider: { kind: 'partial' },
-                }), cause);
-            }
-            const url = observation.url;
-            const applied = Object.freeze({
-                kind: 'applied',
-                evidence: Object.freeze({
-                    provider: 'astrale',
-                    deployment: observation.digest,
-                    artifact: context.artifact.digest,
-                }),
-            });
-            if (url === undefined) {
-                return failed('addressing', progress({ prerequisite, provider: applied }), new Error('Astrale Services deployment returned no URL.'));
-            }
-            let selected;
-            try {
-                selected = addressing(url);
-            }
-            catch (cause) {
-                return failed('addressing', progress({ prerequisite, provider: applied }), cause);
-            }
-            const provider = Object.freeze({
-                kind: 'applied',
-                evidence: Object.freeze({ ...applied.evidence, issuer: selected.issuer }),
-            });
-            let configuration = NONE;
-            const secretNames = [signing.binding, ...Object.keys(context.secrets).sort()];
-            const configured = [];
-            if (secretNames.length > 0) {
-                try {
-                    for (const secret of secretNames) {
-                        await dependencies.callAstrale({
-                            projectDir: context.projectDir,
-                            instance,
-                            path: `${servicePath(origin)}::setSecret`,
-                            identity,
-                            data: { name: secret, value: secrets[secret] },
-                        });
-                        configured.push(secret);
-                    }
-                    configuration = Object.freeze({
-                        kind: 'applied',
-                        evidence: Object.freeze({ names: secretNames }),
-                    });
-                }
-                catch (cause) {
-                    const configuration = configured.length === 0
-                        ? { kind: 'unknown' }
-                        : {
-                            kind: 'partial',
-                            evidence: Object.freeze({ names: Object.freeze([...configured]) }),
-                        };
-                    return failed('configuration', progress({ prerequisite, provider, configuration }), cause);
-                }
+        admit(parameters, context) {
+            const deploymentInstance = parameters.instance;
+            const installationInstance = context.installation?.instance;
+            if (deploymentInstance === undefined && installationInstance === undefined) {
+                throw new TypeError(`Astrale Environment ${context.environment} requires installation.instance or astrale({ instance }).`);
             }
-            let release;
-            try {
-                release = assemble(context.artifact.build, selected);
+            if (deploymentInstance !== undefined &&
+                installationInstance !== undefined &&
+                deploymentInstance !== installationInstance) {
+                throw new TypeError(`Astrale Environment ${context.environment} deployment and installation instances must match.`);
             }
-            catch (cause) {
-                return failed('release', progress({ prerequisite, provider, configuration }), cause);
-            }
-            try {
-                await dependencies.waitForReadiness(release);
-            }
-            catch (cause) {
-                return failed('readiness', progress({ prerequisite, provider, configuration }), cause, release);
-            }
-            let installation;
-            try {
-                await dependencies.runAstrale({
-                    projectDir: context.projectDir,
-                    input: [
-                        'domain',
-                        'install',
-                        url,
-                        '--direct',
-                        '-i',
-                        instance,
-                        '--allow-identity-override',
-                        '--json',
-                        '--timeout',
-                        '240000',
-                        ...identity,
-                    ],
-                });
-                installation = Object.freeze({
-                    kind: 'applied',
-                    evidence: Object.freeze({ instance, origin }),
-                });
-            }
-            catch (cause) {
-                return failed('installation', progress({ prerequisite, provider, configuration, installation: { kind: 'unknown' } }), cause, release);
-            }
-            return Object.freeze({
-                status: 'ready',
-                phase: 'complete',
-                progress: Object.freeze({
-                    ...progress({ prerequisite, configuration, installation }),
-                    provider,
-                }),
-                release,
-            });
         },
+        prepare: dependencies.prepare,
+        deploy: (parameters, context) => deployAstrale(parameters, context, dependencies),
         secretsFile: (parameters) => parameters.secrets,
     });
-}
-function cloudflareParameters(parameters, watch) {
-    return Object.freeze({
-        ...(parameters.port === undefined ? {} : { port: parameters.port }),
-        ...(watch && parameters.host !== undefined ? { host: parameters.host } : {}),
-        ...(parameters.vars === undefined ? {} : { vars: parameters.vars }),
-        ...(parameters.signingIdentity === undefined
-            ? {}
-            : { signingIdentity: parameters.signingIdentity }),
-    });
-}
-function deployedService(input, expectedPath) {
-    if (input === null || typeof input !== 'object' || Array.isArray(input))
-        invalidDeployment();
-    const value = input;
-    if (value.error !== undefined && value.error !== null)
-        invalidDeployment();
-    if (value.state !== 'ready') {
-        throw new TypeError('Astrale Services deployment did not report ready provider state.');
-    }
-    if (value.path !== expectedPath) {
-        throw new TypeError('Astrale Services deployment returned a different Service path.');
-    }
-    if (typeof value.digest !== 'string' || value.digest.length === 0) {
-        throw new TypeError('Astrale Services deployment returned an invalid provider digest.');
-    }
-    let url;
-    if (typeof value.url === 'string') {
-        try {
-            url = new URL(value.url).href.replace(/\/$/u, '');
-        }
-        catch {
-            // Addressing admission below retains the successful provider effect.
-        }
-    }
-    return Object.freeze({
-        ...(url === undefined ? {} : { url }),
-        digest: value.digest,
-    });
-}
-function invalidDeployment() {
-    throw new TypeError('Astrale Services deployment returned invalid provider evidence.');
-}
-function progress(input = {}) {
-    return Object.freeze({
-        prerequisite: input.prerequisite ?? NONE,
-        provider: input.provider ?? NONE,
-        configuration: input.configuration ?? NONE,
-        installation: input.installation ?? NONE,
-    });
-}
-function failed(phase, deploymentProgress, cause, release) {
-    return Object.freeze({
-        status: 'failed',
-        phase,
-        progress: deploymentProgress,
-        error: cause instanceof Error ? cause : new Error(String(cause)),
-        ...(release === undefined ? {} : { release }),
-    });
+    return defineDeployment(adapter, parameters);
 }

package/dist/cli/commands/call.d.ts

@@ -0,0 +1,9 @@
+export declare function callAstrale(input: {
+    readonly executable: string;
+    readonly projectDir: string;
+    readonly instance: string;
+    readonly path: string;
+    readonly identity: readonly string[];
+    readonly data: unknown;
+    readonly signal: AbortSignal;
+}): Promise<unknown>;

package/dist/cli/commands/call.js

@@ -0,0 +1,27 @@
+import { CliProcessError } from '../error.js';
+import { decodeJson } from '../json.js';
+import { runCliProcess } from '../process.js';
+export async function callAstrale(input) {
+    const result = await runCliProcess({
+        executable: input.executable,
+        projectDir: input.projectDir,
+        args: [
+            '--ci',
+            '--no-prompt',
+            'call',
+            input.path,
+            '-i',
+            input.instance,
+            '--json',
+            '--timeout',
+            '240000',
+            ...input.identity,
+        ],
+        stdin: JSON.stringify(input.data),
+        signal: input.signal,
+        timeoutMs: 250_000,
+    });
+    if (!result.ok)
+        throw new CliProcessError('command', `call ${input.path}`, result.failure);
+    return decodeJson(result.stdout, `astrale call ${input.path} success`);
+}

package/dist/cli/commands/install-domain.d.ts

@@ -0,0 +1,10 @@
+export declare function installDomain(input: {
+    readonly executable: string;
+    readonly projectDir: string;
+    readonly instance: string;
+    readonly target: string;
+    readonly direct: boolean;
+    readonly allowIdentityOverride?: boolean;
+    readonly identity: readonly string[];
+    readonly signal: AbortSignal;
+}): Promise<unknown>;

package/dist/cli/commands/install-domain.js

@@ -0,0 +1,29 @@
+import { CliProcessError } from '../error.js';
+import { decodeJson } from '../json.js';
+import { runCliProcess } from '../process.js';
+export async function installDomain(input) {
+    const result = await runCliProcess({
+        executable: input.executable,
+        projectDir: input.projectDir,
+        args: [
+            '--ci',
+            '--no-prompt',
+            'domain',
+            'install',
+            input.target,
+            ...(input.direct ? ['--direct'] : []),
+            '-i',
+            input.instance,
+            ...(input.allowIdentityOverride ? ['--allow-identity-override'] : []),
+            '--json',
+            '--timeout',
+            '240000',
+            ...input.identity,
+        ],
+        signal: input.signal,
+        timeoutMs: 250_000,
+    });
+    if (!result.ok)
+        throw new CliProcessError('command', 'domain install', result.failure);
+    return decodeJson(result.stdout, 'astrale domain install success');
+}

package/dist/cli/commands/introspect.d.ts

@@ -0,0 +1,8 @@
+export declare function introspectDomain(input: {
+    readonly executable: string;
+    readonly projectDir: string;
+    readonly instance: string;
+    readonly origin: string;
+    readonly identity: readonly string[];
+    readonly signal: AbortSignal;
+}): Promise<unknown>;

package/dist/cli/commands/introspect.js

@@ -0,0 +1,27 @@
+import { CliProcessError } from '../error.js';
+import { decodeJson } from '../json.js';
+import { runCliProcess } from '../process.js';
+export async function introspectDomain(input) {
+    const result = await runCliProcess({
+        executable: input.executable,
+        projectDir: input.projectDir,
+        args: [
+            '--ci',
+            '--no-prompt',
+            'introspect',
+            input.origin,
+            '-i',
+            input.instance,
+            '--json',
+            '--timeout',
+            '60000',
+            ...input.identity,
+        ],
+        signal: input.signal,
+        timeoutMs: 70_000,
+    });
+    if (!result.ok) {
+        throw new CliProcessError('command', `introspect ${input.origin}`, result.failure);
+    }
+    return decodeJson(result.stdout, `astrale introspect ${input.origin} success`);
+}

package/dist/cli/commands/version.d.ts

@@ -0,0 +1,6 @@
+export declare const MINIMUM_ASTRALE_CLI_VERSION = "1.0.0-beta.48";
+export declare function requireCliVersion(input: {
+    readonly executable: string;
+    readonly projectDir: string;
+    readonly signal: AbortSignal;
+}): Promise<string>;

package/dist/cli/commands/version.js

@@ -0,0 +1,50 @@
+import { CliProcessError } from '../error.js';
+import { runCliProcess } from '../process.js';
+export const MINIMUM_ASTRALE_CLI_VERSION = '1.0.0-beta.48';
+export async function requireCliVersion(input) {
+    const result = await runCliProcess({
+        executable: input.executable,
+        projectDir: input.projectDir,
+        args: ['--version'],
+        signal: input.signal,
+        timeoutMs: 10_000,
+        stdoutLimit: 256,
+        stderrLimit: 4_096,
+    });
+    if (!result.ok)
+        throw new CliProcessError('command', 'version', result.failure);
+    const version = result.stdout.trim().replace(/^v/u, '');
+    if (!isCompatible(version)) {
+        throw new TypeError(`Astrale CLI ${version || '<invalid>'} is incompatible; ${MINIMUM_ASTRALE_CLI_VERSION} or newer is required.`);
+    }
+    return version;
+}
+function isCompatible(input) {
+    const value = semver(input);
+    const minimum = semver(MINIMUM_ASTRALE_CLI_VERSION);
+    if (value === undefined)
+        return false;
+    for (let index = 0; index < 3; index += 1) {
+        if (value.core[index] > minimum.core[index])
+            return true;
+        if (value.core[index] < minimum.core[index])
+            return false;
+    }
+    if (value.prerelease === undefined)
+        return true;
+    if (minimum.prerelease === undefined)
+        return false;
+    if (value.prerelease.name !== minimum.prerelease.name) {
+        return value.prerelease.name.localeCompare(minimum.prerelease.name) > 0;
+    }
+    return value.prerelease.number >= minimum.prerelease.number;
+}
+function semver(input) {
+    const match = /^(\d+)\.(\d+)\.(\d+)(?:-([a-z]+)\.(\d+))?$/u.exec(input);
+    if (match === null)
+        return undefined;
+    return {
+        core: [Number(match[1]), Number(match[2]), Number(match[3])],
+        ...(match[4] === undefined ? {} : { prerelease: { name: match[4], number: Number(match[5]) } }),
+    };
+}

package/dist/cli/diagnostic.d.ts

@@ -0,0 +1,6 @@
+export type PublicResponseDiagnostic = Readonly<{
+    code: number;
+    message?: string;
+}>;
+/** Admit only the CLI's bounded, caller-safe public response projection. */
+export declare function publicResponseDiagnostic(input: Readonly<Record<string, unknown>> | undefined): PublicResponseDiagnostic | undefined;

package/dist/cli/diagnostic.js

@@ -0,0 +1,28 @@
+const MAXIMUM_RESPONSE_MESSAGE_LENGTH = 1_024;
+/** Admit only the CLI's bounded, caller-safe public response projection. */
+export function publicResponseDiagnostic(input) {
+    if (input?.error !== 'RESPONSE_ERROR' || !publicResponseCode(input.code))
+        return undefined;
+    return Object.freeze({
+        code: input.code,
+        ...(publicResponseMessage(input.message) ? { message: input.message } : {}),
+    });
+}
+function publicResponseCode(input) {
+    return Number.isSafeInteger(input) && input >= 1_000 && input <= 9_999;
+}
+function publicResponseMessage(input) {
+    if (typeof input !== 'string' ||
+        input.length === 0 ||
+        input.length > MAXIMUM_RESPONSE_MESSAGE_LENGTH ||
+        input.trim() !== input ||
+        input.normalize('NFC') !== input) {
+        return false;
+    }
+    for (const character of input) {
+        const point = character.codePointAt(0);
+        if (point <= 0x1f || point === 0x7f)
+            return false;
+    }
+    return true;
+}

package/dist/cli/error.d.ts

@@ -0,0 +1,7 @@
+export type CliProcessFailureKind = 'cancelled' | 'timeout' | 'output-limit' | 'spawn' | 'protocol' | 'command';
+export declare class CliProcessError extends Error {
+    readonly kind: CliProcessFailureKind;
+    readonly command: string;
+    readonly diagnostic?: Readonly<Record<string, unknown>> | undefined;
+    constructor(kind: CliProcessFailureKind, command: string, diagnostic?: Readonly<Record<string, unknown>> | undefined, options?: ErrorOptions);
+}

package/dist/cli/error.js

@@ -0,0 +1,29 @@
+import { publicResponseDiagnostic } from './diagnostic.js';
+export class CliProcessError extends Error {
+    kind;
+    command;
+    diagnostic;
+    constructor(kind, command, diagnostic, options) {
+        const code = diagnosticCode(diagnostic);
+        const message = publicResponseDiagnostic(diagnostic)?.message;
+        super(`Astrale CLI ${command} failed: ${kind}${code}.` +
+            (message === undefined ? '' : ` ${message}`), options);
+        this.kind = kind;
+        this.command = command;
+        this.diagnostic = diagnostic;
+        this.name = 'CliProcessError';
+    }
+}
+function diagnosticCode(diagnostic) {
+    const error = safeCode(diagnostic?.error);
+    const responseCode = publicResponseDiagnostic(diagnostic)?.code;
+    const reason = diagnostic?.reason;
+    const reasonCode = reason !== null && typeof reason === 'object' && !Array.isArray(reason)
+        ? safeCode(reason.code)
+        : undefined;
+    const value = [error, responseCode, reasonCode].filter((part) => part !== undefined).join('/');
+    return value.length === 0 ? '' : ` (${value})`;
+}
+function safeCode(value) {
+    return typeof value === 'string' && /^[A-Z][A-Z0-9_]{0,127}$/u.test(value) ? value : undefined;
+}

package/dist/cli/executable.d.ts

@@ -0,0 +1,2 @@
+/** Resolve the exact CLI executable once so a session cannot drift with PATH. */
+export declare function resolveCliExecutable(input?: string): Promise<string>;