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

package/dist/tooling/cli/arguments.js

@@ -0,0 +1,162 @@
+import { isAbsolute, normalize } from 'node:path';
+export const COMMANDS = ['dev', 'build', 'deploy', 'test', 'lint', 'package'];
+/** Parse the frozen `astrale-domain` command grammar without performing effects. */
+export function parseArgs(argv) {
+    const [command, ...rest] = argv;
+    const fix = rest.includes('--fix');
+    const deployOnly = rest.includes('--deploy-only');
+    let sessionFile;
+    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 === '--session-file') {
+            sessionFile = absoluteFilePath('--session-file', rest[++index]);
+        }
+        else if (argument.startsWith('--session-file=')) {
+            sessionFile = absoluteFilePath('--session-file', argument.slice('--session-file='.length));
+        }
+        else if (argument === '--credential-file') {
+            credentialFile = absoluteFilePath('--credential-file', rest[++index]);
+        }
+        else if (argument.startsWith('--credential-file=')) {
+            credentialFile = absoluteFilePath('--credential-file', argument.slice('--credential-file='.length));
+        }
+        else if (argument === '--secrets-file') {
+            secretsFile = absoluteFilePath('--secrets-file', rest[++index]);
+        }
+        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]);
+        }
+        else if (argument.startsWith('--format=')) {
+            format = lintFormat(argument.slice('--format='.length));
+        }
+        else if (argument === '--environment') {
+            environment = requiredValue('--environment', rest[++index]);
+        }
+        else if (argument.startsWith('--environment=')) {
+            environment = requiredValue('--environment', argument.slice('--environment='.length));
+        }
+        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('-')) {
+            throw new Error(`Unknown flag "${argument}".`);
+        }
+        else {
+            cleaned.push(argument);
+        }
+    }
+    if (fix && command !== 'lint')
+        throw new Error('`--fix` is only valid for `lint`.');
+    if (format !== undefined && command !== 'lint') {
+        throw new Error('`--format` is only valid for `lint`.');
+    }
+    if ((sessionFile !== undefined || credentialFile !== undefined || secretsFile !== undefined) &&
+        command !== '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 ((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.');
+    }
+    switch (command) {
+        case 'dev':
+        case 'deploy': {
+            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,
+                env,
+                ...(deployOnly ? { deployOnly: true } : {}),
+                ...(identity === undefined ? {} : { identity }),
+                ...(credentialFile === undefined ? {} : { credentialFile }),
+                ...(sessionFile === undefined ? {} : { sessionFile }),
+                ...(secretsFile === undefined ? {} : { secretsFile }),
+            };
+        }
+        case 'build':
+        case 'package':
+            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: '',
+                ...(fix ? { fix: true } : {}),
+                ...(format ? { format } : {}),
+            };
+        default:
+            throw new Error(command ? `Unknown command "${command}".` : 'Missing command.');
+    }
+}
+function lintFormat(input) {
+    if (input !== 'stylish' && input !== 'json') {
+        throw new Error(`--format must be "stylish" or "json", got "${input ?? ''}"`);
+    }
+    return input;
+}
+function requiredValue(flag, input) {
+    if (!input || input.startsWith('-'))
+        throw new Error(`${flag} needs a value.`);
+    return input;
+}
+function absoluteFilePath(flag, input) {
+    const value = requiredValue(flag, input);
+    if (!isAbsolute(value) || normalize(value) !== value) {
+        throw new Error(`${flag} needs a normalized absolute path, got "${value}"`);
+    }
+    return 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>;

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

@@ -0,0 +1,52 @@
+import { astraleFailure } from './failure.js';
+import { runAstrale } from './process.js';
+/** Resolve and probe a bookmark through the pinned CLI, preserving its TLS trust. */
+export async function resolveAstraleInstanceIssuer(input, dependencies = { run: runAstrale }) {
+    const result = await dependencies.run({
+        executable: input.executable,
+        projectDir: input.projectDir,
+        signal: input.signal,
+        timeoutMs: 30_000,
+        args: ['--ci', '--no-prompt', 'instance', 'status', input.instance, '--bookmarked', '--json'],
+    });
+    if (result.code !== 0)
+        throw astraleFailure('instance status', result);
+    let value;
+    try {
+        value = JSON.parse(result.stdout);
+    }
+    catch {
+        throw new TypeError('Astrale instance status did not return one JSON value.');
+    }
+    if (value === null ||
+        typeof value !== 'object' ||
+        Array.isArray(value) ||
+        !('kind' in value) ||
+        value.kind !== 'bookmark' ||
+        !('state' in value) ||
+        value.state !== 'ready' ||
+        !('issuer' in value) ||
+        typeof value.issuer !== 'string') {
+        throw new TypeError('Astrale instance status returned invalid Kernel identity evidence.');
+    }
+    let issuer;
+    try {
+        issuer = new URL(value.issuer);
+    }
+    catch {
+        throw new TypeError('Astrale instance status returned an invalid Kernel issuer.');
+    }
+    if (!['https:', 'http:'].includes(issuer.protocol) ||
+        issuer.username ||
+        issuer.password ||
+        issuer.search ||
+        issuer.hash) {
+        throw new TypeError('Astrale instance status returned an invalid Kernel issuer.');
+    }
+    // Child Kernels share an origin, but their path-qualified identities remain distinct.
+    const canonical = issuer.href.replace(/\/$/u, '');
+    if (input.expectedIssuer !== undefined && canonical !== input.expectedIssuer) {
+        throw new Error('Installation bookmark changed Kernel; restart pnpm dev to apply it.');
+    }
+    return canonical;
+}

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

@@ -0,0 +1,13 @@
+export interface AstraleProcessResult {
+    readonly code: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+/** Run one exact Kernel CLI executable with bounded output, time, and termination. */
+export declare function runAstrale(input: {
+    readonly executable: string;
+    readonly args: readonly string[];
+    readonly projectDir: string;
+    readonly signal: AbortSignal;
+    readonly timeoutMs: number;
+}): Promise<AstraleProcessResult>;

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

@@ -0,0 +1,94 @@
+import { spawn } from 'node:child_process';
+const OUTPUT_LIMIT = 256 * 1024;
+const TERMINATION_GRACE_MS = 1_000;
+/** Run one exact Kernel CLI executable with bounded output, time, and termination. */
+export function runAstrale(input) {
+    if (input.signal.aborted)
+        return Promise.reject(abortError(input.signal));
+    return new Promise((resolve, reject) => {
+        let child;
+        try {
+            child = spawn(input.executable, [...input.args], {
+                cwd: input.projectDir,
+                stdio: ['pipe', 'pipe', 'pipe'],
+                shell: false,
+                // This owner already forwards cancellation and enforces a deadline. Keep
+                // terminal group signals from killing installation observation/View cleanup.
+                detached: process.platform !== 'win32',
+            });
+            child.stdin.end();
+        }
+        catch (cause) {
+            reject(new Error('Astrale CLI is unavailable.', { cause }));
+            return;
+        }
+        let stdout = '';
+        let stderr = '';
+        let stdoutBytes = 0;
+        let stderrBytes = 0;
+        let settled = false;
+        let termination;
+        let escalation;
+        const abort = () => terminate(input.signal.reason instanceof Error
+            ? input.signal.reason
+            : new Error('Project operation interrupted.'));
+        input.signal.addEventListener('abort', abort, { once: true });
+        const cleanup = () => {
+            clearTimeout(timeout);
+            if (escalation !== undefined)
+                clearTimeout(escalation);
+            input.signal.removeEventListener('abort', abort);
+        };
+        const terminate = (cause) => {
+            if (settled || termination !== undefined)
+                return;
+            termination = cause;
+            child.stdin.destroy();
+            child.kill('SIGTERM');
+            escalation = setTimeout(() => {
+                if (child.exitCode === null && child.signalCode === null)
+                    child.kill('SIGKILL');
+            }, TERMINATION_GRACE_MS);
+        };
+        const timeout = setTimeout(() => terminate(new Error('Astrale CLI command timed out.')), input.timeoutMs);
+        child.stdout.on('data', (chunk) => {
+            stdoutBytes += chunk.byteLength;
+            if (stdoutBytes > OUTPUT_LIMIT) {
+                terminate(new Error('Astrale CLI stdout exceeded the supported limit.'));
+            }
+            else
+                stdout += chunk.toString('utf8');
+        });
+        child.stderr.on('data', (chunk) => {
+            stderrBytes += chunk.byteLength;
+            if (stderrBytes > OUTPUT_LIMIT) {
+                terminate(new Error('Astrale CLI stderr exceeded the supported limit.'));
+            }
+            else
+                stderr += chunk.toString('utf8');
+        });
+        child.once('error', (cause) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            reject(new Error('Astrale CLI could not be started.', { cause }));
+        });
+        child.once('close', (code) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            if (termination !== undefined) {
+                reject(termination);
+                return;
+            }
+            resolve(Object.freeze({ code: code ?? 1, stdout, stderr }));
+        });
+    });
+}
+function abortError(signal) {
+    return signal.reason instanceof Error
+        ? signal.reason
+        : new Error('Project operation interrupted.');
+}

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

@@ -0,0 +1,18 @@
+import type { AstraleProcessResult } from './process.js';
+import { resolveAstraleExecutable } from './executable.js';
+export declare const MINIMUM_KERNEL_CLI_VERSION = "1.0.0-beta.48";
+export interface CompatibleAstraleDependencies {
+    readonly resolveExecutable: typeof resolveAstraleExecutable;
+    readonly run: (input: {
+        readonly executable: string;
+        readonly args: readonly string[];
+        readonly projectDir: string;
+        readonly signal: AbortSignal;
+        readonly timeoutMs: number;
+    }) => Promise<AstraleProcessResult>;
+}
+/** Pin and admit one compatible CLI before any configured Kernel installation effect. */
+export declare function resolveCompatibleAstrale(input: {
+    readonly projectDir: string;
+    readonly signal: AbortSignal;
+}, dependencies?: CompatibleAstraleDependencies): Promise<string>;

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

@@ -0,0 +1,55 @@
+import { resolveAstraleExecutable } from './executable.js';
+import { astraleFailure } from './failure.js';
+import { runAstrale } from './process.js';
+export const MINIMUM_KERNEL_CLI_VERSION = '1.0.0-beta.48';
+/** Pin and admit one compatible CLI before any configured Kernel installation effect. */
+export async function resolveCompatibleAstrale(input, dependencies = {
+    resolveExecutable: resolveAstraleExecutable,
+    run: runAstrale,
+}) {
+    const executable = await dependencies.resolveExecutable();
+    const result = await dependencies.run({
+        executable,
+        projectDir: input.projectDir,
+        args: ['--version'],
+        signal: input.signal,
+        timeoutMs: 10_000,
+    });
+    if (result.code !== 0)
+        throw astraleFailure('version', result);
+    const version = result.stdout.trim().replace(/^v/u, '');
+    if (!isCompatible(version)) {
+        const diagnostic = semver(version) === undefined ? '<invalid>' : version;
+        throw new TypeError(`Astrale CLI ${diagnostic} is incompatible; ${MINIMUM_KERNEL_CLI_VERSION} or newer is required.`);
+    }
+    return executable;
+}
+function isCompatible(input) {
+    const value = semver(input);
+    const minimum = semver(MINIMUM_KERNEL_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/tooling/cli/bin.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * Published executable boundary. Configuration-free commands remain in Node;
+ * authored TypeScript Runtime commands are supervised through Bun.
+ */
+export {};

package/dist/tooling/cli/bin.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+/**
+ * Published executable boundary. Configuration-free commands remain in Node;
+ * authored TypeScript Runtime commands are supervised through Bun.
+ */
+import { fileURLToPath } from 'node:url';
+import { BunRequiredError, runWithBun } from './bun.js';
+import { failureMessage, failureStack } from './failure.js';
+import { run } from './run.js';
+const argv = process.argv.slice(2);
+try {
+    await execute(argv);
+}
+catch (cause) {
+    process.stderr.write(`\x1b[31m✗\x1b[0m ${failureMessage(cause)}\n`);
+    const stack = failureStack(cause);
+    if (process.env.DEBUG && stack !== undefined)
+        process.stderr.write(`${stack}\n`);
+    process.exitCode = 1;
+}
+async function execute(argv) {
+    try {
+        process.exitCode = await run(argv);
+    }
+    catch (cause) {
+        if (!(cause instanceof BunRequiredError))
+            throw cause;
+        const outcome = await runWithBun(fileURLToPath(import.meta.url), argv);
+        if (outcome.status === 'exited') {
+            process.exitCode = outcome.code;
+        }
+        else {
+            process.kill(process.pid, outcome.signal);
+        }
+    }
+}

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

@@ -0,0 +1,15 @@
+export declare class BunRequiredError extends Error {
+    constructor(options?: ErrorOptions);
+}
+export type BunOutcome = {
+    readonly status: 'exited';
+    readonly code: number;
+} | {
+    readonly status: 'signaled';
+    readonly signal: NodeJS.Signals;
+};
+/** Re-enter the published executable under Bun only when authored TypeScript must be imported. */
+export declare function runWithBun(executable: string, argv: readonly string[]): Promise<BunOutcome>;
+export declare function isolateDevelopmentProcessGroup(argv: readonly string[], platform?: NodeJS.Platform): boolean;
+/** Prefer the generated project's exact Bun package binary over an ambient executable or shim. */
+export declare function resolveBunExecutable(cwd: string): string;