@astrale-os/sdk 0.5.0-beta.98 → 0.6.0-beta.0

package/dist/testing/dataset/references.js

@@ -0,0 +1,56 @@
+import { graph as schemaGraph } from '@astrale-os/kernel-core/schema';
+import { isNodeId } from '../../platform/graph/node/index.js';
+import { Path } from '../../platform/graph/path/index.js';
+import { bundle, schema as schemaApi } from '../../platform/schema/index.js';
+/** Symbolic projection supplies facts; only an explicit Dataset reference supplies identity. */
+export function datasetReferenceNodes(domain) {
+    const result = new Map();
+    const direct = new Set([
+        domain.origin,
+        ...Object.values(domain.dependencies).map(({ origin }) => origin),
+    ]);
+    const sourceBundle = bundle.create(domain.source);
+    for (const source of [sourceBundle.root, ...sourceBundle.closure]) {
+        if (!direct.has(source.origin))
+            continue;
+        const owner = schemaApi.resolve(source);
+        const projection = schemaGraph.project(owner);
+        const allowed = new Set(owner
+            .definitions()
+            .filter(({ ref }) => ref.origin === owner.origin &&
+            ['class', 'function', 'policy', 'view', 'core'].includes(ref.kind))
+            .map(({ ref }) => Path.project(ref).raw));
+        for (const part of [projection.managed, projection.core]) {
+            for (const node of part.graph.nodes) {
+                if (!('as' in node))
+                    continue;
+                const path = part.paths.get(node.as);
+                if (path !== undefined && allowed.has(path))
+                    result.set(path, node);
+            }
+        }
+    }
+    return result;
+}
+/** Serialized reference associations lose their proof and must match the exact projection again. */
+export function decodeDatasetReferences(input, domain, graph) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        throw new TypeError('Dataset references must be an object.');
+    }
+    const entries = Object.entries(input);
+    const projected = entries.length === 0 ? new Map() : datasetReferenceNodes(domain);
+    const identities = new Set();
+    for (const [path, id] of entries) {
+        const expected = projected.get(path);
+        const actual = isNodeId(id) ? graph.nodes.byId(id) : undefined;
+        if (expected === undefined ||
+            actual === undefined ||
+            identities.has(actual.id) ||
+            expected.class !== actual.class ||
+            JSON.stringify(expected.props) !== JSON.stringify(actual.props)) {
+            throw new TypeError(`Dataset reference ${path} does not identify its projected Node.`);
+        }
+        identities.add(actual.id);
+    }
+    return Object.freeze(Object.fromEntries(entries));
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,9 @@
+/** Development and test resources: schema-admitted demo Datasets and their lazy project references. */
+export { DATASET_FORMAT, DATASET_VERSION, DatasetAdmissionError, decodeDataset, defineDataset, encodeDataset, isDataset, } from './dataset/index.js';
+export type { AuthoredDatasetVariables, Dataset, DatasetClasses, DatasetEdgeInput, DatasetEndpoint, DatasetGraph, DatasetInput, DatasetJson, DatasetNode, DatasetNodeInput, DatasetReferences, DatasetReferenceInput, DatasetVariable, DatasetVariableJson, DatasetVariables, DatasetVariablesOf, SchemaOfDataset, } from './dataset/index.js';
+export { loadDataset, loadDatasets } from './load.js';
+export type { DatasetModuleLoader, LoadedDataset } from './load.js';
+export { dataset, isDatasetReference } from './reference.js';
+export type { DatasetReference } from './reference.js';
+export { isTests, tests } from './tests.js';
+export type { Tests, TestsInput } from './tests.js';

package/dist/testing/index.js

@@ -0,0 +1,5 @@
+/** Development and test resources: schema-admitted demo Datasets and their lazy project references. */
+export { DATASET_FORMAT, DATASET_VERSION, DatasetAdmissionError, decodeDataset, defineDataset, encodeDataset, isDataset, } from './dataset/index.js';
+export { loadDataset, loadDatasets } from './load.js';
+export { dataset, isDatasetReference } from './reference.js';
+export { isTests, tests } from './tests.js';

package/dist/testing/load.d.ts

@@ -0,0 +1,14 @@
+import type { schema } from '../platform/schema/index.js';
+import type { Dataset } from './dataset/index.js';
+import type { DatasetReference } from './reference.js';
+import type { Tests } from './tests.js';
+/** Import one referenced module; tooling owns path resolution against `astrale.config.ts`. */
+export type DatasetModuleLoader = (path: string) => unknown | Promise<unknown>;
+export interface LoadedDataset {
+    readonly reference: DatasetReference;
+    readonly dataset: Dataset;
+}
+/** Load the one default Dataset of a referenced module and prove it targets the exact Schema. */
+export declare function loadDataset(reference: DatasetReference, load: DatasetModuleLoader, source: schema.DomainSchema): Promise<LoadedDataset>;
+/** Load every referenced Dataset of one Tests value in declared order, rejecting duplicate ids. */
+export declare function loadDatasets(value: Tests, load: DatasetModuleLoader, source: schema.DomainSchema): Promise<readonly LoadedDataset[]>;

package/dist/testing/load.js

@@ -0,0 +1,44 @@
+import { isDataset } from './dataset/index.js';
+import { isDatasetReference } from './reference.js';
+import { isTests } from './tests.js';
+/** Load the one default Dataset of a referenced module and prove it targets the exact Schema. */
+export async function loadDataset(reference, load, source) {
+    if (!isDatasetReference(reference)) {
+        throw new TypeError('Dataset reference must be created by dataset(path).');
+    }
+    if (typeof load !== 'function')
+        throw new TypeError('Dataset module loader must be a function.');
+    const loaded = await load(reference.path);
+    if (loaded === null ||
+        typeof loaded !== 'object' ||
+        Array.isArray(loaded) ||
+        !Object.hasOwn(loaded, 'default') ||
+        Object.keys(loaded).some((key) => key !== 'default')) {
+        throw new TypeError(`Dataset module ${reference.path} must export exactly one default Dataset.`);
+    }
+    const dataset = Reflect.get(loaded, 'default');
+    if (!isDataset(dataset)) {
+        throw new TypeError(`Dataset module ${reference.path} default export is not an admitted Dataset.`);
+    }
+    if (dataset.schema !== source) {
+        throw new TypeError(`Dataset ${dataset.id} (${reference.path}) targets Schema ${dataset.schema.origin}, not the exact Application Schema.`);
+    }
+    return Object.freeze({ reference, dataset });
+}
+/** Load every referenced Dataset of one Tests value in declared order, rejecting duplicate ids. */
+export async function loadDatasets(value, load, source) {
+    if (!isTests(value))
+        throw new TypeError('Tests value must be created by tests().');
+    const loaded = [];
+    const ids = new Map();
+    for (const reference of value.datasets) {
+        const entry = await loadDataset(reference, load, source);
+        const previous = ids.get(entry.dataset.id);
+        if (previous !== undefined) {
+            throw new TypeError(`Dataset id ${entry.dataset.id} is defined by both ${previous} and ${reference.path}.`);
+        }
+        ids.set(entry.dataset.id, reference.path);
+        loaded.push(entry);
+    }
+    return Object.freeze(loaded);
+}

package/dist/testing/reference.d.ts

@@ -0,0 +1,11 @@
+/** One stable Dataset module coordinate relative to the project configuration. */
+export interface DatasetReference {
+    readonly kind: 'dataset-reference';
+    readonly path: string;
+}
+/**
+ * Reference one Dataset module lazily. Importing the project configuration never loads the
+ * referenced module; tooling resolves the path against `astrale.config.ts` on demand.
+ */
+export declare function dataset(path: string): DatasetReference;
+export declare function isDatasetReference(input: unknown): input is DatasetReference;

package/dist/testing/reference.js

@@ -0,0 +1,19 @@
+const references = new WeakSet();
+/**
+ * Reference one Dataset module lazily. Importing the project configuration never loads the
+ * referenced module; tooling resolves the path against `astrale.config.ts` on demand.
+ */
+export function dataset(path) {
+    if (typeof path !== 'string' ||
+        path.length === 0 ||
+        path.trim() !== path ||
+        path.includes('\0')) {
+        throw new TypeError('Dataset path must be a non-empty stable module coordinate.');
+    }
+    const reference = Object.freeze({ kind: 'dataset-reference', path });
+    references.add(reference);
+    return reference;
+}
+export function isDatasetReference(input) {
+    return input !== null && typeof input === 'object' && references.has(input);
+}

package/dist/testing/tests.d.ts

@@ -0,0 +1,12 @@
+import type { DatasetReference } from './reference.js';
+/** Development and test resources of one project. Never part of a Build, Release, or install. */
+export interface Tests {
+    readonly kind: 'tests';
+    readonly datasets: readonly DatasetReference[];
+}
+export interface TestsInput {
+    readonly datasets?: readonly DatasetReference[];
+}
+/** Capture the inert test resources of a project; Dataset modules stay unloaded. */
+export declare function tests(input?: TestsInput): Tests;
+export declare function isTests(input: unknown): input is Tests;

package/dist/testing/tests.js

@@ -0,0 +1,31 @@
+import { isDatasetReference } from './reference.js';
+const admittedTests = new WeakSet();
+/** Capture the inert test resources of a project; Dataset modules stay unloaded. */
+export function tests(input = {}) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input))
+        invalid();
+    if (Reflect.ownKeys(input).some((key) => key !== 'datasets'))
+        invalid();
+    const datasets = input.datasets ?? [];
+    if (!Array.isArray(datasets))
+        throw new TypeError('Tests datasets must be an array.');
+    const paths = new Set();
+    for (const reference of datasets) {
+        if (!isDatasetReference(reference)) {
+            throw new TypeError('Tests datasets must contain only references created by dataset(path).');
+        }
+        if (paths.has(reference.path)) {
+            throw new TypeError(`Dataset ${reference.path} is referenced more than once.`);
+        }
+        paths.add(reference.path);
+    }
+    const value = Object.freeze({ kind: 'tests', datasets: Object.freeze([...datasets]) });
+    admittedTests.add(value);
+    return value;
+}
+export function isTests(input) {
+    return input !== null && typeof input === 'object' && admittedTests.has(input);
+}
+function invalid() {
+    throw new TypeError('Tests definition may contain only datasets.');
+}

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

@@ -1,16 +1,19 @@
 import type { LintReportFormat } from '../linter/index.js';
-export declare const COMMANDS: readonly ['dev', 'build', 'deploy', 'lint', 'package'];
+export declare const COMMANDS: readonly ['dev', 'build', 'deploy', 'test', 'lint', 'package', 'upgrade'];
 export type Command = (typeof COMMANDS)[number];
 export interface ParsedArgs {
     readonly command: Command;
     readonly env: string;
     readonly fix?: boolean;
     readonly format?: LintReportFormat;
-    readonly port?: number;
-    readonly host?: string;
-    readonly sessionFile?: string;
+    readonly deployOnly?: boolean;
+    readonly identity?: string;
     readonly credentialFile?: string;
+    readonly suite?: string;
+    readonly sessionFile?: string;
     readonly secretsFile?: string;
+    readonly channel?: string;
+    readonly check?: boolean;
 }
 /** Parse the frozen `astrale-domain` command grammar without performing effects. */
 export declare function parseArgs(argv: readonly string[]): ParsedArgs;

package/dist/tooling/cli/arguments.js

@@ -1,44 +1,27 @@
-import { isIP } from 'node:net';
 import { isAbsolute, normalize } from 'node:path';
-export const COMMANDS = ['dev', 'build', 'deploy', 'lint', 'package'];
+export const COMMANDS = ['dev', 'build', 'deploy', 'test', 'lint', 'package', 'upgrade'];
 /** Parse the frozen `astrale-domain` command grammar without performing effects. */
 export function parseArgs(argv) {
     const [command, ...rest] = argv;
+    if (command === 'upgrade')
+        return parseUpgrade(rest);
     const fix = rest.includes('--fix');
-    let port;
-    let host;
+    const deployOnly = rest.includes('--deploy-only');
     let sessionFile;
-    let credentialFile;
     let secretsFile;
+    let credentialFile;
+    let identity;
+    let suite;
     let format;
     let environment;
     const cleaned = [];
     for (let index = 0; index < rest.length; index += 1) {
         const argument = rest[index];
-        if (argument === '--port') {
-            const value = rest[++index];
-            port = Number(value);
-            if (!Number.isInteger(port) || port <= 0 || port > 65_535) {
-                throw new Error(`--port needs a port number, got "${value}"`);
-            }
-        }
-        else if (argument.startsWith('--port=')) {
-            port = Number(argument.slice('--port='.length));
-            if (!Number.isInteger(port) || port <= 0 || port > 65_535) {
-                throw new Error(`--port needs a port number, got "${argument}"`);
-            }
-        }
-        else if (argument === '--host') {
-            host = normalizeHost(rest[++index]);
-        }
-        else if (argument.startsWith('--host=')) {
-            host = normalizeHost(argument.slice('--host='.length));
-        }
-        else if (argument === '--session-file') {
-            sessionFile = sessionFilePath(rest[++index]);
+        if (argument === '--session-file') {
+            sessionFile = absoluteFilePath('--session-file', rest[++index]);
         }
         else if (argument.startsWith('--session-file=')) {
-            sessionFile = sessionFilePath(argument.slice('--session-file='.length));
+            sessionFile = absoluteFilePath('--session-file', argument.slice('--session-file='.length));
         }
         else if (argument === '--credential-file') {
             credentialFile = absoluteFilePath('--credential-file', rest[++index]);
@@ -52,6 +35,12 @@ export function parseArgs(argv) {
         else if (argument.startsWith('--secrets-file=')) {
             secretsFile = absoluteFilePath('--secrets-file', argument.slice('--secrets-file='.length));
         }
+        else if (argument === '--as') {
+            identity = requiredValue('--as', rest[++index]);
+        }
+        else if (argument.startsWith('--as=')) {
+            identity = requiredValue('--as', argument.slice('--as='.length));
+        }
         else if (argument === '--format') {
             format = lintFormat(rest[++index]);
         }
@@ -64,7 +53,13 @@ export function parseArgs(argv) {
         else if (argument.startsWith('--environment=')) {
             environment = requiredValue('--environment', argument.slice('--environment='.length));
         }
-        else if (argument === '--fix') {
+        else if (argument === '--suite') {
+            suite = requiredValue('--suite', rest[++index]);
+        }
+        else if (argument.startsWith('--suite=')) {
+            suite = requiredValue('--suite', argument.slice('--suite='.length));
+        }
+        else if (argument === '--fix' || argument === '--deploy-only') {
             continue;
         }
         else if (argument.startsWith('-')) {
@@ -79,59 +74,69 @@ export function parseArgs(argv) {
     if (format !== undefined && command !== 'lint') {
         throw new Error('`--format` is only valid for `lint`.');
     }
-    if ((port !== undefined ||
-        host !== undefined ||
-        sessionFile !== undefined ||
-        credentialFile !== undefined ||
-        secretsFile !== undefined) &&
+    if ((sessionFile !== undefined || credentialFile !== undefined || secretsFile !== undefined) &&
         command !== 'dev') {
-        throw new Error('`--port`, `--host`, `--session-file`, `--credential-file`, and `--secrets-file` are only valid for `dev`.');
+        throw new Error('`--session-file`, `--credential-file`, and `--secrets-file` are only valid for `dev`.');
+    }
+    if (identity !== undefined && credentialFile !== undefined) {
+        throw new Error('Choose either `--as` or `--credential-file`, not both.');
     }
-    if (environment !== undefined && !['dev', 'deploy'].includes(command ?? '')) {
-        throw new Error('`--environment` is only valid for dev or deploy.');
+    if ((deployOnly || identity !== undefined) && command !== 'dev' && command !== 'deploy') {
+        throw new Error('`--deploy-only` and `--as` are only valid for `dev` or `deploy`.');
+    }
+    if (environment !== undefined && command !== 'dev' && command !== 'deploy') {
+        if (command !== 'test') {
+            throw new Error('`--environment` is only valid for `dev`, `deploy`, or `test`.');
+        }
+    }
+    if (suite !== undefined && command !== 'test') {
+        throw new Error('`--suite` is only valid for `test`.');
     }
     const positionals = cleaned.filter((argument) => !argument.startsWith('-'));
     if (environment !== undefined && positionals.length > 0) {
-        throw new Error('Choose either a positional environment or `--environment`, not both.');
+        throw new Error('Choose either a positional Environment or `--environment`, not both.');
     }
     switch (command) {
         case 'dev':
-            if (positionals.length > 1)
-                throw new Error('`dev` accepts at most one environment.');
-            return {
-                command: 'dev',
-                env: environment ?? positionals[0] ?? 'dev',
-                ...(port !== undefined ? { port } : {}),
-                ...(host !== undefined ? { host } : {}),
-                ...(sessionFile !== undefined ? { sessionFile } : {}),
-                ...(credentialFile !== undefined ? { credentialFile } : {}),
-                ...(secretsFile !== undefined ? { secretsFile } : {}),
-            };
         case 'deploy': {
-            if (positionals.length > 1)
-                throw new Error('`deploy` accepts exactly one environment.');
-            const env = environment ?? positionals[0];
-            if (!env)
-                throw new Error('`deploy` requires an env key, e.g. `deploy prod`.');
+            if (positionals.length > 1) {
+                throw new Error(`\`${command}\` accepts exactly one Environment.`);
+            }
+            const env = environment ?? positionals[0] ?? (command === 'dev' ? 'development' : undefined);
+            if (!env) {
+                throw new Error(`\`${command}\` requires an Environment, e.g. \`${command} development\`.`);
+            }
             return {
-                command: 'deploy',
+                command,
                 env,
+                ...(deployOnly ? { deployOnly: true } : {}),
+                ...(identity === undefined ? {} : { identity }),
+                ...(credentialFile === undefined ? {} : { credentialFile }),
+                ...(sessionFile === undefined ? {} : { sessionFile }),
+                ...(secretsFile === undefined ? {} : { secretsFile }),
             };
         }
         case 'build':
-            if (positionals.length > 0)
-                throw new Error('`build` does not accept positional arguments.');
-            return { command: 'build', env: 'dev' };
         case 'package':
-            if (positionals.length > 0)
-                throw new Error('`package` does not accept positional arguments.');
-            return { command: 'package', env: 'dev' };
+            if (positionals.length > 0) {
+                throw new Error(`\`${command}\` does not accept positional arguments.`);
+            }
+            return { command, env: '' };
+        case 'test':
+            if (positionals.length > 0) {
+                throw new Error('`test` does not accept positional arguments; use `--environment`.');
+            }
+            return {
+                command: 'test',
+                env: environment ?? '',
+                ...(suite === undefined ? {} : { suite }),
+            };
         case 'lint':
             if (positionals.length > 0)
                 throw new Error('`lint` does not accept positional arguments.');
             return {
                 command: 'lint',
-                env: 'dev',
+                env: '',
                 ...(fix ? { fix: true } : {}),
                 ...(format ? { format } : {}),
             };
@@ -139,50 +144,23 @@ export function parseArgs(argv) {
             throw new Error(command ? `Unknown command "${command}".` : 'Missing command.');
     }
 }
-function normalizeHost(input) {
-    if (!input || input.startsWith('-')) {
-        throw new Error(`--host needs a public URL, got "${input ?? ''}"`);
-    }
-    try {
-        const url = new URL(input);
-        if ((url.protocol !== 'https:' && url.protocol !== 'http:') ||
-            url.username !== '' ||
-            url.password !== '' ||
-            url.pathname !== '/' ||
-            url.search !== '' ||
-            url.hash !== '' ||
-            privateHostname(url.hostname))
-            throw new Error('invalid');
-        return url.origin;
-    }
-    catch {
-        throw new Error(`--host needs a valid URL, got "${input}"`);
-    }
-}
-function privateHostname(input) {
-    const host = input
-        .toLowerCase()
-        .replace(/^\[|\]$/gu, '')
-        .replace(/\.$/u, '');
-    if (host === 'localhost' || host.endsWith('.localhost'))
-        return true;
-    if (isIP(host) === 4) {
-        const parts = host.split('.').map(Number);
-        return (parts[0] === 0 ||
-            parts[0] === 10 ||
-            parts[0] === 127 ||
-            (parts[0] === 169 && parts[1] === 254) ||
-            (parts[0] === 172 && (parts[1] ?? 0) >= 16 && (parts[1] ?? 0) <= 31) ||
-            (parts[0] === 192 && parts[1] === 168));
+function parseUpgrade(args) {
+    let channel = 'beta';
+    let check = false;
+    for (let index = 0; index < args.length; index++) {
+        const argument = args[index];
+        if (argument === '--check')
+            check = true;
+        else if (argument === '--channel' || argument.startsWith('--channel=')) {
+            channel = requiredValue('--channel', argument === '--channel' ? args[++index] : argument.slice(10));
+            if (!/^[A-Za-z][A-Za-z0-9._-]*$/u.test(channel)) {
+                throw new Error('--channel must be a registry dist-tag, such as beta or latest.');
+            }
+        }
+        else
+            throw new Error(`Unknown upgrade argument "${argument}".`);
     }
-    if (isIP(host) !== 6)
-        return false;
-    return (host === '::' ||
-        host === '::1' ||
-        host.startsWith('fc') ||
-        host.startsWith('fd') ||
-        /^fe[89ab]/u.test(host) ||
-        /^::ffff:(?:0|10|127|169\.254|172\.(?:1[6-9]|2\d|3[01])|192\.168)\./u.test(host));
+    return { command: 'upgrade', env: '', channel, check };
 }
 function lintFormat(input) {
     if (input !== 'stylish' && input !== 'json') {
@@ -195,9 +173,6 @@ function requiredValue(flag, input) {
         throw new Error(`${flag} needs a value.`);
     return input;
 }
-function sessionFilePath(input) {
-    return absoluteFilePath('--session-file', input);
-}
 function absoluteFilePath(flag, input) {
     const value = requiredValue(flag, input);
     if (!isAbsolute(value) || normalize(value) !== value) {

package/dist/tooling/cli/astrale/authority.d.ts

@@ -0,0 +1,5 @@
+/** Build one mutually exclusive authority argument set for an Astrale CLI operation. */
+export declare function astraleAuthorityArguments(input: {
+    readonly identity?: string;
+    readonly credential?: string;
+}): readonly string[];

package/dist/tooling/cli/astrale/authority.js

@@ -0,0 +1,11 @@
+/** Build one mutually exclusive authority argument set for an Astrale CLI operation. */
+export function astraleAuthorityArguments(input) {
+    if (input.identity !== undefined && input.credential !== undefined) {
+        throw new TypeError('Astrale authority cannot combine an identity and a credential.');
+    }
+    return input.credential === undefined
+        ? input.identity === undefined
+            ? Object.freeze([])
+            : Object.freeze(['--as', input.identity])
+        : Object.freeze(['--creds', input.credential]);
+}

package/dist/tooling/cli/astrale/executable.d.ts

@@ -0,0 +1,2 @@
+/** Resolve one exact executable for a complete sequence of Kernel CLI operations. */
+export declare function resolveAstraleExecutable(input?: string): Promise<string>;

package/dist/tooling/cli/astrale/executable.js

@@ -0,0 +1,47 @@
+import { constants } from 'node:fs';
+import { access, readFile, realpath } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { delimiter, isAbsolute, join } from 'node:path';
+/** Resolve one exact executable for a complete sequence of Kernel CLI operations. */
+export async function resolveAstraleExecutable(input = 'astrale') {
+    const candidates = isAbsolute(input) ? [input] : await executableCandidates(input);
+    for (const candidate of candidates) {
+        try {
+            await access(candidate, constants.X_OK);
+            return await realpath(candidate);
+        }
+        catch {
+            // Continue through the bounded recorded-install and PATH candidates.
+        }
+    }
+    throw new TypeError('Astrale CLI is unavailable. Install it with the official Astrale installer.');
+}
+async function executableCandidates(input) {
+    const path = (process.env.PATH ?? '')
+        .split(delimiter)
+        .filter(Boolean)
+        .map((directory) => join(directory, input));
+    if (input !== 'astrale')
+        return path;
+    const installed = await recordedInstallation();
+    return installed === undefined ? path : [installed, ...path];
+}
+async function recordedInstallation() {
+    const home = process.env.ASTRALE_HOME ?? join(homedir(), '.astrale');
+    try {
+        const decoded = JSON.parse(await readFile(join(home, 'install.json'), 'utf8'));
+        if (typeof decoded !== 'object' ||
+            decoded === null ||
+            !('method' in decoded) ||
+            decoded.method !== 'script' ||
+            !('bin' in decoded) ||
+            typeof decoded.bin !== 'string' ||
+            !isAbsolute(decoded.bin)) {
+            return undefined;
+        }
+        return decoded.bin;
+    }
+    catch {
+        return undefined;
+    }
+}

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

@@ -0,0 +1,6 @@
+import type { AstraleProcessResult } from './process.js';
+/** Only sanitized CLI diagnostics may be promoted through installation failures. */
+export declare class AstraleCliError extends Error {
+}
+export declare function astraleFailure(command: string, result: AstraleProcessResult): Error;
+export declare function isDomainNotInstalledFailure(stderr: string): boolean;

package/dist/tooling/cli/astrale/failure.js

@@ -0,0 +1,48 @@
+/** Only sanitized CLI diagnostics may be promoted through installation failures. */
+export class AstraleCliError extends Error {
+}
+export function astraleFailure(command, result) {
+    let diagnostic;
+    try {
+        const failure = record(JSON.parse(result.stderr));
+        const error = admittedCode(failure.error);
+        const reason = recordOrUndefined(failure.reason);
+        const reasonCode = admittedCode(reason?.code);
+        diagnostic =
+            error === undefined ? undefined : reasonCode === undefined ? error : `${error}/${reasonCode}`;
+    }
+    catch {
+        // Never forward raw stderr because a credential-bearing command owns it.
+    }
+    return new AstraleCliError(`Astrale CLI ${command} failed${diagnostic === undefined ? '' : ` (${diagnostic})`}.`);
+}
+function admittedCode(input) {
+    return typeof input === 'string' && /^[A-Z][A-Z0-9_]{0,63}$/u.test(input) ? input : undefined;
+}
+function recordOrUndefined(input) {
+    return input !== null && typeof input === 'object' && !Array.isArray(input)
+        ? input
+        : undefined;
+}
+export function isDomainNotInstalledFailure(stderr) {
+    try {
+        const failure = record(JSON.parse(stderr));
+        if (failure.error === 'DOMAIN_NOT_INSTALLED')
+            return true;
+        const reason = failure.reason;
+        return (failure.error === 'RESPONSE_ERROR' &&
+            reason !== null &&
+            typeof reason === 'object' &&
+            !Array.isArray(reason) &&
+            Reflect.get(reason, 'code') === 'SCHEMA_NOT_FOUND');
+    }
+    catch {
+        return false;
+    }
+}
+function record(input) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        throw new TypeError('Expected an object response.');
+    }
+    return input;
+}

package/dist/tooling/cli/astrale/instance.d.ts

@@ -0,0 +1,11 @@
+import { runAstrale } from './process.js';
+/** Resolve and probe a bookmark through the pinned CLI, preserving its TLS trust. */
+export declare function resolveAstraleInstanceIssuer(input: {
+    readonly executable: string;
+    readonly projectDir: string;
+    readonly instance: string;
+    readonly expectedIssuer?: string;
+    readonly signal: AbortSignal;
+}, dependencies?: {
+    readonly run: typeof runAstrale;
+}): Promise<string>;