@astrale-os/sdk 0.5.0-beta.13 → 0.5.0-beta.131

package/dist/tooling/cli/development/target-lock.js

@@ -0,0 +1,68 @@
+import { createHash } from 'node:crypto';
+import { mkdir, rmdir } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { acquireDevelopmentLease, DevelopmentLeaseError } from './lease.js';
+export class DevelopmentTargetLockError extends Error {
+    code;
+    name = 'DevelopmentTargetLockError';
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+    }
+}
+/** Exclude local sessions targeting one installed Domain across separate checkouts. */
+export async function acquireDevelopmentTargetLock(input, dependencies = {}) {
+    const coordinate = `${input.issuer}#${input.origin}`;
+    const root = dependencies.root ?? join(tmpdir(), 'astrale-domain-development-targets');
+    const key = createHash('sha256')
+        .update(input.issuer)
+        .update('\0')
+        .update(input.origin)
+        .digest('hex');
+    const directory = join(root, key);
+    await mkdir(root, { recursive: true, mode: 0o700 });
+    let lease;
+    try {
+        lease = await acquireDevelopmentLease({
+            directory,
+            coordinate,
+            ...(dependencies.pid === undefined ? {} : { pid: dependencies.pid }),
+            ...(dependencies.sessionId === undefined ? {} : { sessionId: dependencies.sessionId }),
+            ...(dependencies.processAlive === undefined
+                ? {}
+                : { processAlive: dependencies.processAlive }),
+        });
+    }
+    catch (cause) {
+        if (cause instanceof DevelopmentLeaseError) {
+            throw new DevelopmentTargetLockError('DEVELOPMENT_TARGET_LOCKED', cause.message, { cause });
+        }
+        throw cause;
+    }
+    return Object.freeze({
+        ...lease,
+        async release() {
+            try {
+                await lease.release();
+            }
+            catch (cause) {
+                if (cause instanceof DevelopmentLeaseError) {
+                    throw new DevelopmentTargetLockError('DEVELOPMENT_TARGET_LOCK_LOST', cause.message, {
+                        cause,
+                    });
+                }
+                throw cause;
+            }
+            await rmdir(directory).catch(ignoreNonEmpty);
+            await rmdir(root).catch(ignoreNonEmpty);
+        },
+    });
+}
+function ignoreNonEmpty(cause) {
+    const code = cause !== null && typeof cause === 'object' && 'code' in cause
+        ? String(Reflect.get(cause, 'code'))
+        : undefined;
+    if (!['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes(code ?? ''))
+        throw cause;
+}

package/dist/tooling/cli/development/view.d.ts

@@ -0,0 +1,28 @@
+import type { Release } from '../../../deployment/release/index.js';
+import type { AstraleProcessResult } from '../astrale/process.js';
+export interface DevelopmentViewDependencies {
+    run(input: {
+        readonly executable: string;
+        readonly args: readonly string[];
+        readonly projectDir: string;
+        readonly signal: AbortSignal;
+        readonly timeoutMs: number;
+    }): Promise<AstraleProcessResult>;
+}
+/** Keep one browser tab alive across successful remote deployments. */
+export declare class DevelopmentView {
+    #private;
+    constructor(input: {
+        readonly executable: string;
+        readonly projectDir: string;
+        readonly instance: string;
+        readonly identity?: string;
+        readonly credential?: string;
+        readonly dependencies?: DevelopmentViewDependencies;
+    });
+    /** Require in-place refresh before publishing anything that depends on this CLI feature. */
+    prepare(signal: AbortSignal): Promise<void>;
+    /** Called after each committed deployment; the development loop owns candidate deduplication. */
+    refresh(release: Release, signal: AbortSignal): Promise<string | undefined>;
+    close(signal: AbortSignal): Promise<void>;
+}

package/dist/tooling/cli/development/view.js

@@ -0,0 +1,151 @@
+import { astraleAuthorityArguments } from '../astrale/authority.js';
+import { runAstrale } from '../astrale/process.js';
+/** Keep one browser tab alive across successful remote deployments. */
+export class DevelopmentView {
+    #executable;
+    #projectDir;
+    #instance;
+    #authority;
+    #dependencies;
+    #current;
+    #prepared = false;
+    constructor(input) {
+        this.#executable = input.executable;
+        this.#projectDir = input.projectDir;
+        this.#instance = input.instance;
+        this.#authority = astraleAuthorityArguments({
+            ...(input.identity === undefined ? {} : { identity: input.identity }),
+            ...(input.credential === undefined ? {} : { credential: input.credential }),
+        });
+        this.#dependencies = input.dependencies ?? { run: runAstrale };
+    }
+    /** Require in-place refresh before publishing anything that depends on this CLI feature. */
+    async prepare(signal) {
+        if (this.#prepared)
+            return;
+        const result = await this.#dependencies.run({
+            executable: this.#executable,
+            projectDir: this.#projectDir,
+            signal,
+            timeoutMs: 10_000,
+            args: ['view', '--help'],
+        });
+        if (result.code !== 0 || !result.stdout.includes('--refresh <id>')) {
+            throw new Error('This Astrale CLI cannot refresh development Views. Run astrale update before pnpm dev.');
+        }
+        this.#prepared = true;
+    }
+    /** Called after each committed deployment; the development loop owns candidate deduplication. */
+    async refresh(release, signal) {
+        const frontend = release.build.frontend;
+        if (frontend === undefined) {
+            await this.close(AbortSignal.timeout(30_000));
+            return undefined;
+        }
+        const path = `/:${frontend.entrypoint.origin}:view.${frontend.entrypoint.name}`;
+        const previous = this.#current;
+        if (previous?.path === path) {
+            const refreshed = await this.#dependencies.run({
+                executable: this.#executable,
+                projectDir: this.#projectDir,
+                signal,
+                timeoutMs: 60_000,
+                args: ['--ci', '--no-prompt', 'view', '--refresh', previous.id, '--json'],
+            });
+            if (refreshed.code !== 0)
+                throw new Error('Astrale CLI could not refresh the development View.');
+            return previous.pageUrl;
+        }
+        const next = await this.#open(path, signal);
+        if (previous !== undefined) {
+            try {
+                await this.#close(previous.id, AbortSignal.timeout(30_000));
+            }
+            catch (cause) {
+                try {
+                    await this.#close(next.id, AbortSignal.timeout(30_000));
+                }
+                catch (rollback) {
+                    throw new AggregateError([cause, rollback], 'Astrale View replacement and rollback cleanup failed.');
+                }
+                throw cause;
+            }
+        }
+        this.#current = next;
+        return next.pageUrl;
+    }
+    async close(signal) {
+        const current = this.#current;
+        if (current === undefined)
+            return;
+        await this.#close(current.id, signal);
+        if (this.#current === current) {
+            this.#current = undefined;
+        }
+    }
+    async #open(path, signal) {
+        const result = await this.#dependencies.run({
+            executable: this.#executable,
+            projectDir: this.#projectDir,
+            signal,
+            timeoutMs: 60_000,
+            args: [
+                '--ci',
+                '--no-prompt',
+                'view',
+                path,
+                '--browser',
+                '--instance',
+                this.#instance,
+                '--json',
+                ...this.#authority,
+            ],
+        });
+        if (result.code !== 0)
+            throw new Error('Astrale CLI could not open the development View.');
+        return { ...decodeOpenedView(result.stdout), path };
+    }
+    async #close(id, signal) {
+        const result = await this.#dependencies.run({
+            executable: this.#executable,
+            projectDir: this.#projectDir,
+            signal,
+            timeoutMs: 30_000,
+            args: ['--ci', '--no-prompt', 'view', '--close', id, '--json'],
+        });
+        if (result.code !== 0)
+            throw new Error('Astrale CLI could not close the development View.');
+    }
+}
+function decodeOpenedView(input) {
+    let value;
+    try {
+        value = JSON.parse(input);
+    }
+    catch (cause) {
+        throw new TypeError('Astrale View output is invalid.', { cause });
+    }
+    const session = record(value) ? value.session : undefined;
+    const id = record(session) ? session.id : undefined;
+    const pageUrl = record(session) ? session.pageUrl : undefined;
+    if (typeof id !== 'string' || id.length === 0 || !webUrl(pageUrl)) {
+        throw new TypeError('Astrale View output is invalid.');
+    }
+    return Object.freeze({ id, pageUrl });
+}
+function webUrl(input) {
+    if (typeof input !== 'string' || input.length === 0 || input.length > 2_048)
+        return false;
+    try {
+        const value = new URL(input);
+        return ((value.protocol === 'http:' || value.protocol === 'https:') &&
+            value.username === '' &&
+            value.password === '');
+    }
+    catch {
+        return false;
+    }
+}
+function record(input) {
+    return input !== null && typeof input === 'object' && !Array.isArray(input);
+}

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

@@ -0,0 +1,19 @@
+/**
+ * Minimal dotenv parser — the secrets-file boundary.
+ *
+ * `secrets: '.env.<env>'` in an adapter's params points a gitignored file whose
+ * entire contents are secrets. `loadDeclaredSecrets` reads it into a flat
+ * `Record<string,string>` the CLI hands the adapter (injected into the local
+ * runtime in dev, pushed to a secret store in prod). No `process.env` mutation,
+ * no interpolation magic beyond `${VAR}` against earlier keys in the same file.
+ */
+/**
+ * Read + parse a dotenv file the preset explicitly DECLARED (`secrets:`).
+ * Declared-but-absent is a wiring error (the gitignored file was never created
+ * on this machine), so it throws instead of loading `{}` — silently forwarding
+ * nothing surfaces much later as an empty credential at the provider. A file
+ * that exists but holds no keys is legitimate (a domain with no secrets yet).
+ */
+export declare function loadDeclaredSecrets(path: string, declaration: string): Record<string, string>;
+/** Load one explicit development-session secret snapshot without following a leaf symlink. */
+export declare function loadPrivateSecretsFile(path: string, platform?: NodeJS.Platform): Record<string, string>;

package/dist/tooling/cli/dotenv.js

@@ -0,0 +1,85 @@
+/**
+ * Minimal dotenv parser — the secrets-file boundary.
+ *
+ * `secrets: '.env.<env>'` in an adapter's params points a gitignored file whose
+ * entire contents are secrets. `loadDeclaredSecrets` reads it into a flat
+ * `Record<string,string>` the CLI hands the adapter (injected into the local
+ * runtime in dev, pushed to a secret store in prod). No `process.env` mutation,
+ * no interpolation magic beyond `${VAR}` against earlier keys in the same file.
+ */
+import { closeSync, constants, fstatSync, openSync, readFileSync } from 'node:fs';
+function parseDotenv(contents) {
+    const out = {};
+    for (const raw of contents.split('\n')) {
+        const line = raw.trim();
+        if (!line || line.startsWith('#'))
+            continue;
+        const match = /^(?:export\s+)?([A-Za-z_]\w*)\s*=\s*(.*)$/.exec(line);
+        if (!match)
+            continue;
+        const [, key, rawValue] = match;
+        let value = rawValue.trim();
+        // Single quotes mean a LITERAL value (standard dotenv): no `${VAR}`
+        // interpolation, so a secret that legitimately contains a literal `${...}`
+        // (e.g. a password) survives intact instead of being silently blanked.
+        const singleQuoted = value.length >= 2 && value.startsWith("'") && value.endsWith("'");
+        if ((value.length >= 2 && value.startsWith('"') && value.endsWith('"')) || singleQuoted) {
+            value = value.slice(1, -1);
+        }
+        out[key] = singleQuoted
+            ? value
+            : value.replace(/\$\{(\w+)\}/g, (_, name) => out[name] ?? '');
+    }
+    return out;
+}
+/**
+ * Read + parse a dotenv file the preset explicitly DECLARED (`secrets:`).
+ * Declared-but-absent is a wiring error (the gitignored file was never created
+ * on this machine), so it throws instead of loading `{}` — silently forwarding
+ * nothing surfaces much later as an empty credential at the provider. A file
+ * that exists but holds no keys is legitimate (a domain with no secrets yet).
+ */
+export function loadDeclaredSecrets(path, declaration) {
+    let contents;
+    try {
+        contents = readFileSync(path, 'utf-8');
+    }
+    catch (cause) {
+        if (!(cause instanceof Error && 'code' in cause && cause.code === 'ENOENT'))
+            throw cause;
+        throw new Error(`Secrets file '${declaration}' is declared in the preset but missing at ${path}. ` +
+            `Create it (it may be empty) or remove 'secrets:' from the preset.`, { cause });
+    }
+    return parseDotenv(contents);
+}
+/** Load one explicit development-session secret snapshot without following a leaf symlink. */
+export function loadPrivateSecretsFile(path, platform = process.platform) {
+    if (platform === 'win32') {
+        throw new Error('--secrets-file is unavailable on Windows until private no-reparse file admission is supported.');
+    }
+    let descriptor;
+    try {
+        descriptor = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch (cause) {
+        if (cause instanceof Error && 'code' in cause && cause.code === 'ENOENT') {
+            throw new Error(`Secrets file '${path}' is missing.`, { cause });
+        }
+        if (cause instanceof Error && 'code' in cause && cause.code === 'ELOOP') {
+            throw new Error(`Secrets file '${path}' must be a regular file and not a symlink.`, { cause });
+        }
+        throw cause;
+    }
+    try {
+        const info = fstatSync(descriptor);
+        if (!info.isFile())
+            throw new Error(`Secrets file '${path}' must be a regular file.`);
+        if ((info.mode & 0o077) !== 0) {
+            throw new Error(`Secrets file '${path}' must not be accessible by group or other users.`);
+        }
+        return parseDotenv(readFileSync(descriptor, 'utf8'));
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}

package/dist/tooling/cli/environment-release.d.ts

@@ -0,0 +1,21 @@
+import type { Adapter, InstallationTarget, ReadyDeployResult } from '../../deployment/adapter/index.js';
+import type { InstallationEvidence } from './installation/index.js';
+import { writeDeploymentEvidence } from './evidence.js';
+import { reconcileInstallation } from './installation/index.js';
+export interface EnvironmentReleaseDependencies {
+    readonly writeEvidence: typeof writeDeploymentEvidence;
+    readonly reconcileInstallation: typeof reconcileInstallation;
+}
+/** Retain verified provider evidence and reconcile one optional durable Kernel installation. */
+export declare function reconcileEnvironmentRelease(input: {
+    readonly projectDir: string;
+    readonly environment: string;
+    readonly adapter: Adapter<object>;
+    readonly deployment: ReadyDeployResult;
+    readonly installation?: InstallationTarget;
+    readonly deployOnly: boolean;
+    readonly identity?: string;
+    readonly credential?: string;
+    readonly installationExecutable?: string;
+    readonly signal: AbortSignal;
+}, dependencies?: EnvironmentReleaseDependencies): Promise<InstallationEvidence | undefined>;

package/dist/tooling/cli/environment-release.js

@@ -0,0 +1,46 @@
+import { writeDeploymentEvidence } from './evidence.js';
+import { reconcileInstallation } from './installation/index.js';
+/** Retain verified provider evidence and reconcile one optional durable Kernel installation. */
+export async function reconcileEnvironmentRelease(input, dependencies = {
+    writeEvidence: writeDeploymentEvidence,
+    reconcileInstallation,
+}) {
+    try {
+        await dependencies.writeEvidence({
+            projectDir: input.projectDir,
+            environment: input.environment,
+            adapter: input.adapter,
+            deployment: input.deployment,
+        });
+    }
+    catch (cause) {
+        throw new TypeError(`Domain ${input.deployment.release.publication.origin} remains deployed, but its local evidence could not be saved. Kernel installation was not attempted.`, { cause });
+    }
+    if (input.installation === undefined || input.deployOnly)
+        return undefined;
+    if (input.installationExecutable === undefined) {
+        throw new TypeError('A compatible Astrale CLI must be pinned before deploying an installed Environment.');
+    }
+    const installation = await dependencies.reconcileInstallation({
+        projectDir: input.projectDir,
+        target: input.installation,
+        executable: input.installationExecutable,
+        ...(input.identity === undefined ? {} : { identity: input.identity }),
+        ...(input.credential === undefined ? {} : { credential: input.credential }),
+        release: input.deployment.release,
+        signal: input.signal,
+    });
+    try {
+        await dependencies.writeEvidence({
+            projectDir: input.projectDir,
+            environment: input.environment,
+            adapter: input.adapter,
+            deployment: input.deployment,
+            installation,
+        });
+    }
+    catch (cause) {
+        throw new TypeError(`Domain ${installation.origin} remains installed on ${installation.instance}, but its local evidence could not be saved. The installation was not rolled back.`, { cause });
+    }
+    return installation;
+}

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

@@ -0,0 +1,11 @@
+import type { Adapter, ReadyDeployResult } from '../../deployment/adapter/index.js';
+import type { InstallationEvidence } from './installation/index.js';
+export declare const DEPLOYMENT_EVIDENCE_VERSION: 1;
+/** Persist one non-secret, non-authoritative continuity observation atomically. */
+export declare function writeDeploymentEvidence(input: {
+    readonly projectDir: string;
+    readonly environment: string;
+    readonly adapter: Adapter<object>;
+    readonly deployment: ReadyDeployResult;
+    readonly installation?: InstallationEvidence;
+}): Promise<string>;

package/dist/tooling/cli/evidence.js

@@ -0,0 +1,52 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, rename, unlink, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+export const DEPLOYMENT_EVIDENCE_VERSION = 1;
+/** Persist one non-secret, non-authoritative continuity observation atomically. */
+export async function writeDeploymentEvidence(input) {
+    const directory = join(input.projectDir, '.astrale', 'environments', input.environment);
+    const path = join(directory, 'deployment.json');
+    await mkdir(directory, { recursive: true });
+    const provider = input.deployment.progress.provider.evidence;
+    const value = Object.freeze({
+        version: DEPLOYMENT_EVIDENCE_VERSION,
+        environment: input.environment,
+        adapter: Object.freeze({ name: input.adapter.name, version: input.adapter.version }),
+        deployment: Object.freeze({
+            provider: provider.provider,
+            id: provider.deployment,
+            artifact: provider.artifact,
+            issuer: input.deployment.release.addressing.issuer,
+            origin: input.deployment.release.publication.origin,
+            revision: input.deployment.release.publication.schema.revision,
+            etag: input.deployment.release.publication.etag,
+            readiness: 'ready',
+            ...(provider.preflight === undefined ? {} : { preflight: provider.preflight }),
+        }),
+        ...(input.installation === undefined
+            ? {}
+            : {
+                installation: Object.freeze({
+                    instance: input.installation.instance,
+                    origin: input.installation.origin,
+                    issuer: input.installation.issuer,
+                    revision: input.installation.revision,
+                    etag: input.installation.etag,
+                    generation: input.installation.generation,
+                    status: input.installation.status,
+                }),
+            }),
+    });
+    const staging = join(directory, `.deployment-${randomUUID()}.json`);
+    await writeFile(staging, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600, flag: 'wx' });
+    try {
+        await rename(staging, path);
+    }
+    finally {
+        await unlink(staging).catch((cause) => {
+            if (cause.code !== 'ENOENT')
+                throw cause;
+        });
+    }
+    return path;
+}

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

@@ -0,0 +1,2 @@
+export declare function failureMessage(cause: unknown): string;
+export declare function failureStack(cause: unknown): string | undefined;

package/dist/tooling/cli/failure.js

@@ -0,0 +1,13 @@
+export function failureMessage(cause) {
+    if (cause instanceof Error)
+        return cause.message;
+    try {
+        return String(cause);
+    }
+    catch {
+        return 'Unknown error';
+    }
+}
+export function failureStack(cause) {
+    return cause instanceof Error ? cause.stack : undefined;
+}

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

@@ -0,0 +1,8 @@
+import { type Command } from './arguments.js';
+export interface HelpRequest {
+    readonly command?: Command;
+}
+/** Resolve help without parsing a project or performing any command effects. */
+export declare function helpRequest(argv: readonly string[]): HelpRequest | undefined;
+export declare function helpText(command?: Command): string;
+export declare const ERROR_USAGE = "Usage: astrale-domain <command> [options]\nRun \"astrale-domain --help\" for available commands.\n";

package/dist/tooling/cli/help.js

@@ -0,0 +1,152 @@
+import { COMMANDS } from './arguments.js';
+/** Resolve help without parsing a project or performing any command effects. */
+export function helpRequest(argv) {
+    if (!argv.some((argument) => argument === '--help' || argument === '-h'))
+        return undefined;
+    const command = COMMANDS.find((candidate) => candidate === argv[0]);
+    return command === undefined ? Object.freeze({}) : Object.freeze({ command });
+}
+export function helpText(command) {
+    return command === undefined ? GLOBAL_HELP : COMMAND_HELP[command];
+}
+export const ERROR_USAGE = `Usage: astrale-domain <command> [options]
+Run "astrale-domain --help" for available commands.
+`;
+const GLOBAL_HELP = `Build, develop, deploy, test, lint, and package Astrale Domains.
+
+Usage:
+  astrale-domain <command> [options]
+
+Commands:
+  dev [environment]       Remotely deploy and watch one Project Environment.
+  build                   Build and verify without deploying.
+  deploy <environment>    Deploy and optionally install one Environment.
+  test                    Run Project tests, optionally against one Environment.
+  lint                    Check Domain source and architecture.
+  package                 Prepare public declarations for publication.
+
+Options:
+  -h, --help              Show help.
+
+Run "astrale-domain <command> --help" for command-specific help.
+`;
+const COMMAND_HELP = Object.freeze({
+    dev: `Build, verify, remotely deploy, and watch one Project Environment.
+
+Usage:
+  astrale-domain dev [environment] [options]
+
+Arguments:
+  environment             Project Environment name; defaults to development.
+
+Options:
+  --environment <name>    Select the environment without a positional argument.
+  --deploy-only           Suppress this run's configured Kernel installation.
+  --as <identity>         Select the Astrale identity for Services and installation calls.
+  --session-file <path>   Write one retained DevelopmentSessionFileV1 snapshot at an
+                          absolute path in a caller-owned private directory.
+  --credential-file <path>
+                          Use one private operator credential for provider and Kernel
+                          calls without exposing it in Project configuration.
+  --secrets-file <path>   Load one private, absolute secrets file for this development
+                          session instead of the adapter-declared secrets file.
+  -h, --help              Show help for dev.
+
+Behavior:
+  The selected Environment must exist; no other Environment is chosen as a fallback.
+  Builds and verifies the Application, Runtime, frontend, and adapter artifact, then
+  deploys it through the selected Environment. It never starts a local Worker,
+  Vite server, or tunnel. Imported source changes produce serialized remote updates;
+  configuration changes require restarting the command.
+  A shared direct-provider target additionally requires an external single-writer
+  boundary such as a CI/CD concurrency group.
+  The session file is machine-readable and authoritative when requested; human
+  stdout/stderr remains diagnostic. It requires an adapter that reports exact
+  installed Release evidence, so it is rejected for an Environment without an
+  installation and when --deploy-only suppresses installation.
+  A credential file is admitted and read once. Its value is passed only to the
+  deployment adapter, configured Kernel installation, and default View; it never
+  enters Domain Runtime secrets, diagnostics, deployment evidence, or the session
+  file. It is currently unavailable on Windows because private no-reparse file
+  admission is absent.
+  A secrets-file override is read once, passed to the Domain runtime as secrets,
+  never mutates the authored project, and is not watched for later changes. It is
+  also unavailable on Windows because private no-reparse admission is absent.
+
+  Stopping the watcher stops only local build orchestration. The remote deployment
+  and optional Kernel installation remain available.
+`,
+    build: `Build and verify a Domain without deploying it.
+
+Usage:
+  astrale-domain build
+
+Options:
+  -h, --help              Show help for build.
+
+Behavior:
+  Compiles the Application and verifies that the conventional or configured Runtime
+  module exports the exact Runtime owned by it. It does not select an Environment,
+  load secrets, deploy, or install the Domain.
+`,
+    deploy: `Build, verify, and deploy a Domain through its configured adapter.
+
+Usage:
+  astrale-domain deploy <environment>
+  astrale-domain deploy --environment <name>
+
+Arguments:
+  environment             Required adapter environment key.
+
+Options:
+  --environment <name>    Select the environment without a positional argument.
+  --deploy-only           Suppress this run's configured Kernel installation.
+  --as <identity>         Select the Astrale identity for Services and installation calls.
+  -h, --help              Show help for deploy.
+
+Behavior:
+  Builds and verifies the Application, Runtime, and provider artifact, loads declared
+  secrets, and invokes the selected adapter. It then verifies the resulting Release.
+  When the Environment declares installation, reconciles it after provider readiness.
+  An Environment without installation performs zero Kernel calls.
+`,
+    test: `Run Project tests locally or against one selected Environment.
+
+Usage:
+  astrale-domain test [options]
+
+Options:
+  --environment <name>    Select the committed Project Environment exposed to tests as
+                          ASTRALE_PROJECT_ENVIRONMENT.
+  --suite <name>          Select a named Vitest project from vitest.config.ts.
+  -h, --help              Show help for test.
+
+Behavior:
+  Without an Environment, runs the Project-local Vitest suite once. With an
+  Environment, first validates the name against astrale.config.ts, then exposes
+  that exact name to the selected suite. Test definitions remain Project-level;
+  environments never duplicate or override them.
+`,
+    lint: `Check Domain source and architecture.
+
+Usage:
+  astrale-domain lint [options]
+
+Options:
+  --fix                   Apply supported fixes.
+  --format <format>       Select stylish or json output (default: stylish).
+  -h, --help              Show help for lint.
+`,
+    package: `Prepare public TypeScript declarations for package publication.
+
+Usage:
+  astrale-domain package
+
+Options:
+  -h, --help              Show help for package.
+
+Behavior:
+  Normalizes public declaration references in the current package. This command
+  does not load astrale.config.ts and does not require Bun.
+`,
+});