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

package/dist/tooling/cli/bun.js

@@ -0,0 +1,108 @@
+import { spawn } from 'node:child_process';
+import { lstatSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+const FORWARDED_SIGNALS = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+export class BunRequiredError extends Error {
+    constructor(options) {
+        super('astrale-domain requires Bun to import astrale.config.ts and its Runtime module.', options);
+        this.name = 'BunRequiredError';
+    }
+}
+/** Re-enter the published executable under Bun only when authored TypeScript must be imported. */
+export function runWithBun(executable, argv) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(resolveBunExecutable(process.cwd()), [executable, ...argv], {
+            stdio: 'inherit',
+            // Keep a long-lived development runtime outside the launcher's terminal
+            // process group. The launcher receives Ctrl-C, forwards it exactly once,
+            // and remains alive until Bun finishes provider and Kernel cleanup.
+            detached: isolateDevelopmentProcessGroup(argv),
+        });
+        const handlers = FORWARDED_SIGNALS.map((signal) => [signal, () => child.kill(signal)]);
+        for (const [signal, handler] of handlers)
+            process.on(signal, handler);
+        const cleanup = () => {
+            for (const [signal, handler] of handlers)
+                process.off(signal, handler);
+        };
+        child.once('error', (cause) => {
+            cleanup();
+            reject(new BunRequiredError({ cause }));
+        });
+        child.once('close', (code, signal) => {
+            cleanup();
+            if (signal !== null) {
+                resolve({ status: 'signaled', signal });
+            }
+            else if (code !== null) {
+                resolve({ status: 'exited', code });
+            }
+            else {
+                reject(new Error('Bun closed without an exit code or signal.'));
+            }
+        });
+    });
+}
+export function isolateDevelopmentProcessGroup(argv, platform = process.platform) {
+    return platform !== 'win32' && argv[0] === 'dev';
+}
+/** Prefer the generated project's exact Bun package binary over an ambient executable or shim. */
+export function resolveBunExecutable(cwd) {
+    const projectRequire = createRequire(join(cwd, 'package.json'));
+    let manifestPath;
+    try {
+        manifestPath = projectRequire.resolve('bun/package.json');
+    }
+    catch (cause) {
+        if (isMissingPackage(cause) && !hasBunPackageEntry(projectRequire))
+            return 'bun';
+        throw new BunRequiredError({ cause });
+    }
+    try {
+        const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        const declared = typeof manifest.bin === 'string' ? manifest.bin : manifest.bin?.bun;
+        if (typeof declared !== 'string' || declared.length === 0 || isAbsolute(declared)) {
+            throw new Error('The project-local Bun package has an invalid bun binary declaration.');
+        }
+        const root = dirname(manifestPath);
+        const candidate = resolve(root, declared);
+        const physicalRoot = realpathSync(root);
+        const physicalCandidate = realpathSync(candidate);
+        const fromRoot = relative(physicalRoot, physicalCandidate);
+        if (fromRoot === '' || fromRoot.startsWith('..') || isAbsolute(fromRoot)) {
+            throw new Error('The project-local Bun binary escapes its package directory.');
+        }
+        if (!statSync(physicalCandidate).isFile()) {
+            throw new Error('The project-local Bun binary is not a regular file.');
+        }
+        return physicalCandidate;
+    }
+    catch (cause) {
+        throw new BunRequiredError({ cause });
+    }
+}
+function hasBunPackageEntry(projectRequire) {
+    for (const searchRoot of projectRequire.resolve.paths('bun') ?? []) {
+        try {
+            lstatSync(join(searchRoot, 'bun'));
+            return true;
+        }
+        catch (error) {
+            if (!isMissingEntry(error))
+                throw error;
+        }
+    }
+    return false;
+}
+function isMissingEntry(error) {
+    return (error instanceof Error &&
+        'code' in error &&
+        (error.code === 'ENOENT' ||
+            error.code === 'ENOTDIR'));
+}
+function isMissingPackage(error) {
+    return (error instanceof Error &&
+        'code' in error &&
+        error.code === 'MODULE_NOT_FOUND');
+}

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

@@ -0,0 +1,2 @@
+/** Admit one caller-owned credential without retaining its value outside this command. */
+export declare function loadPrivateCredentialFile(path: string, platform?: NodeJS.Platform): string;

package/dist/tooling/cli/credential.js

@@ -0,0 +1,57 @@
+import { closeSync, constants, fstatSync, openSync, readSync } from 'node:fs';
+const MAXIMUM_CREDENTIAL_BYTES = 64 * 1024;
+/** Admit one caller-owned credential without retaining its value outside this command. */
+export function loadPrivateCredentialFile(path, platform = process.platform) {
+    if (platform === 'win32') {
+        throw new Error('--credential-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 (errorCode(cause) === 'ENOENT') {
+            throw new Error(`Credential file '${path}' is missing.`, { cause });
+        }
+        if (errorCode(cause) === 'ELOOP') {
+            throw new Error(`Credential 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(`Credential file '${path}' must be a regular file.`);
+        if ((info.mode & 0o077) !== 0) {
+            throw new Error(`Credential file '${path}' must not be accessible by group or other users.`);
+        }
+        if (info.size === 0 || info.size > MAXIMUM_CREDENTIAL_BYTES) {
+            throw new Error(`Credential file '${path}' must contain one bounded credential.`);
+        }
+        const bytes = Buffer.allocUnsafe(info.size + 1);
+        let offset = 0;
+        while (offset < bytes.length) {
+            const read = readSync(descriptor, bytes, offset, bytes.length - offset, null);
+            if (read === 0)
+                break;
+            offset += read;
+        }
+        if (offset !== info.size)
+            throw new Error(`Credential file '${path}' changed while read.`);
+        const credential = bytes.subarray(0, offset).toString('utf8').trim();
+        if (credential.length === 0 || /[\r\n\0]/u.test(credential)) {
+            throw new Error(`Credential file '${path}' must contain exactly one credential.`);
+        }
+        return credential;
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}
+function errorCode(input) {
+    return input !== null && typeof input === 'object' && 'code' in input
+        ? String(Reflect.get(input, 'code'))
+        : undefined;
+}

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

@@ -0,0 +1,25 @@
+import type { Adapter, InstallationTarget, PreparedArtifact } from '../../../deployment/adapter/index.js';
+export interface DevelopmentCandidate {
+    readonly adapter: Adapter<object>;
+    readonly parameters: object;
+    readonly installation?: InstallationTarget;
+    readonly artifact: PreparedArtifact;
+    readonly secrets: Readonly<Record<string, string>>;
+    readonly sources: ReadonlySet<string>;
+}
+/** Rebuild one complete, isolated Environment candidate from authored sources. */
+export declare class DevelopmentCandidateBuilder {
+    #private;
+    constructor(input: {
+        readonly configPath: string;
+        readonly projectDir: string;
+        readonly environment: string;
+        readonly runtimePath: string;
+        readonly overrideSecrets?: Readonly<Record<string, string>>;
+    });
+    prepare(signal: AbortSignal): Promise<DevelopmentCandidate>;
+}
+export declare function discoverRuntimePath(configPath: string): Promise<string>;
+export declare function sameEnvironment(current: DevelopmentCandidate, candidate: DevelopmentCandidate): boolean;
+/** Identify a rebuilt candidate that cannot change provider or installation state. */
+export declare function sameDeploymentCandidate(current: DevelopmentCandidate, candidate: DevelopmentCandidate): boolean;

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

@@ -0,0 +1,176 @@
+import { existsSync } from 'node:fs';
+import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { admitRuntime, compile, resolveRuntime, runtime, verifyPreflight, } from '../../../deployment/index.js';
+import { admitProjectModule } from '../../../project/index.js';
+import { loadDeclaredSecrets } from '../dotenv.js';
+import { selectEnvironment } from '../project.js';
+import { projectImportPlugin } from './project-imports.js';
+import { DevelopmentSources } from './sources.js';
+/** Rebuild one complete, isolated Environment candidate from authored sources. */
+export class DevelopmentCandidateBuilder {
+    #configPath;
+    #projectDir;
+    #environment;
+    #runtimePath;
+    #overrideSecrets;
+    #generation = 0;
+    constructor(input) {
+        this.#configPath = input.configPath;
+        this.#projectDir = input.projectDir;
+        this.#environment = input.environment;
+        this.#runtimePath = input.runtimePath;
+        this.#overrideSecrets = input.overrideSecrets;
+    }
+    async prepare(signal) {
+        throwIfAborted(signal);
+        const directory = join(this.#projectDir, '.astrale', 'development', this.#environment, 'source', String(++this.#generation));
+        await mkdir(directory, { recursive: true });
+        const bridge = join(directory, 'bridge.ts');
+        const sources = new DevelopmentSources(this.#projectDir);
+        sources.record(join(this.#projectDir, 'package.json'));
+        const configImport = moduleSpecifier(dirname(bridge), this.#configPath);
+        const runtimeImport = moduleSpecifier(dirname(bridge), resolve(dirname(this.#configPath), this.#runtimePath));
+        await writeFile(bridge, `export { default as project } from ${JSON.stringify(configImport)}\n` +
+            `export { default as runtime } from ${JSON.stringify(runtimeImport)}\n`);
+        try {
+            const bunRuntime = bun();
+            const built = await bunRuntime.build({
+                entrypoints: [bridge],
+                outdir: directory,
+                naming: 'application.mjs',
+                target: 'bun',
+                format: 'esm',
+                packages: 'bundle',
+                plugins: [projectImportPlugin(this.#projectDir, bunRuntime)],
+                splitting: false,
+                sourcemap: 'inline',
+                metafile: true,
+                throw: false,
+            });
+            throwIfAborted(signal);
+            if (!built.success) {
+                const diagnostics = built.logs.map(({ message, position }) => position === undefined || position === null
+                    ? message
+                    : `${relative(this.#projectDir, position.file)}:${position.line}:${position.column}: ${message}`);
+                throw new Error(['Authored Application rebuild failed.', ...diagnostics].join('\n'));
+            }
+            const output = built.outputs.find((candidate) => candidate.path.endsWith('application.mjs'));
+            if (output === undefined)
+                throw new Error('Authored Application rebuild produced no module.');
+            const loaded = (await import(`${pathToFileURL(output.path).href}?development=${this.#generation}`));
+            if (Object.keys(loaded).some((key) => key !== 'project' && key !== 'runtime')) {
+                throw new TypeError('Development bridge produced unexpected exports.');
+            }
+            const project = admitProjectModule({ default: loaded.project });
+            if ((project.entrypoints?.runtime ?? './runtime.ts') !== this.#runtimePath) {
+                throw new Error('Runtime entrypoint changed; restart pnpm dev to apply it.');
+            }
+            const environment = selectEnvironment(project, this.#environment);
+            const resolved = await resolveRuntime(runtime(this.#runtimePath), async (path) => {
+                if (path !== this.#runtimePath) {
+                    throw new Error('Runtime entrypoint changed; restart pnpm dev to apply it.');
+                }
+                return Object.freeze({ default: loaded.runtime });
+            });
+            const build = compile(project.application);
+            admitRuntime({ runtime: build.runtime }, resolved);
+            const adapter = environment.deployment.adapter;
+            const parameters = environment.deployment.parameters;
+            for (const path of Object.keys(built.metafile?.inputs ?? {}))
+                sources.record(path);
+            const source = await adapter.prepare(parameters, {
+                projectDir: this.#projectDir,
+                environment: this.#environment,
+                ...(environment.installation === undefined
+                    ? {}
+                    : { installation: environment.installation }),
+                mode: 'release',
+                recordSource: sources.record,
+                signal,
+                build,
+                runtime: resolved,
+            });
+            const artifact = verifyPreflight({ build, runtime: resolved, source });
+            const declared = this.#overrideSecrets === undefined
+                ? secretsFor(adapter, parameters, this.#projectDir, resolved.runtime)
+                : { values: this.#overrideSecrets };
+            if (declared.path !== undefined)
+                sources.record(declared.path);
+            return Object.freeze({
+                adapter,
+                parameters,
+                ...(environment.installation === undefined
+                    ? {}
+                    : { installation: environment.installation }),
+                artifact,
+                secrets: declared.values,
+                sources: sources.snapshot(),
+            });
+        }
+        finally {
+            await rm(directory, { recursive: true, force: true });
+        }
+    }
+}
+export async function discoverRuntimePath(configPath) {
+    const loaded = (await import(`${pathToFileURL(configPath).href}?discover=${Date.now()}`));
+    const project = admitProjectModule(loaded);
+    return project.entrypoints?.runtime ?? './runtime.ts';
+}
+export function sameEnvironment(current, candidate) {
+    return (candidate.adapter.name === current.adapter.name &&
+        candidate.adapter.version === current.adapter.version &&
+        candidate.artifact.build.schema.compiled.root.origin ===
+            current.artifact.build.schema.compiled.root.origin &&
+        stable(candidate.parameters) === stable(current.parameters) &&
+        stable(candidate.installation) === stable(current.installation));
+}
+/** Identify a rebuilt candidate that cannot change provider or installation state. */
+export function sameDeploymentCandidate(current, candidate) {
+    return (sameEnvironment(current, candidate) &&
+        candidate.artifact.build.schema.compiled.root.revision ===
+            current.artifact.build.schema.compiled.root.revision &&
+        candidate.artifact.digest === current.artifact.digest &&
+        stable(candidate.secrets) === stable(current.secrets));
+}
+function secretsFor(adapter, parameters, projectDir, selectedRuntime) {
+    const file = adapter.secretsFile?.(parameters);
+    if (file === undefined)
+        return { values: Object.freeze({}) };
+    const path = isAbsolute(file) ? file : join(projectDir, file);
+    if (Object.keys(selectedRuntime.integrations).length === 0 && !existsSync(path)) {
+        return { values: Object.freeze({}) };
+    }
+    return { values: Object.freeze(loadDeclaredSecrets(path, file)), path };
+}
+function bun() {
+    const value = Reflect.get(globalThis, 'Bun');
+    if (value === undefined || typeof value.build !== 'function') {
+        throw new TypeError('Domain development requires the Bun runtime.');
+    }
+    return value;
+}
+function moduleSpecifier(from, target) {
+    const path = relative(from, target).split(sep).join('/');
+    return path.startsWith('.') ? path : `./${path}`;
+}
+function stable(input) {
+    if (input === undefined)
+        return 'undefined';
+    if (input === null || typeof input !== 'object')
+        return JSON.stringify(input);
+    if (Array.isArray(input))
+        return `[${input.map(stable).join(',')}]`;
+    const record = input;
+    return `{${Object.keys(record)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${stable(record[key])}`)
+        .join(',')}}`;
+}
+function throwIfAborted(signal) {
+    if (signal.aborted) {
+        throw signal.reason instanceof Error ? signal.reason : new Error('Development interrupted.');
+    }
+}

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

@@ -0,0 +1,16 @@
+import type { ReadyDeployResult } from '../../../deployment/adapter/index.js';
+import type { InstallationEvidence } from '../installation/index.js';
+import type { DevelopmentCandidate } from './candidate.js';
+export interface DevelopmentDeploymentInput {
+    readonly projectDir: string;
+    readonly environment: string;
+    readonly deployOnly: boolean;
+    readonly identity?: string;
+    readonly credential?: string;
+    readonly installationExecutable?: string;
+}
+/** Commit and verify one complete remote candidate, then reconcile its optional installation. */
+export declare function deployDevelopmentCandidate(candidate: DevelopmentCandidate, input: DevelopmentDeploymentInput, signal: AbortSignal): Promise<{
+    readonly deployment: ReadyDeployResult;
+    readonly installation?: InstallationEvidence;
+}>;

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

@@ -0,0 +1,39 @@
+import { verifyDeployment } from '../../../deployment/index.js';
+import { reconcileEnvironmentRelease } from '../environment-release.js';
+/** Commit and verify one complete remote candidate, then reconcile its optional installation. */
+export async function deployDevelopmentCandidate(candidate, input, signal) {
+    const deployed = await candidate.adapter.deploy(candidate.parameters, {
+        projectDir: input.projectDir,
+        environment: input.environment,
+        ...(candidate.installation === undefined ? {} : { installation: candidate.installation }),
+        ...(input.identity === undefined ? {} : { identity: input.identity }),
+        ...(input.credential === undefined ? {} : { credential: input.credential }),
+        secrets: candidate.secrets,
+        artifact: candidate.artifact,
+        signal,
+    });
+    const verified = verifyDeployment(candidate.artifact, deployed);
+    if (verified.status === 'failed') {
+        throw new Error(`Deployment failed during ${verified.phase}: ${verified.error.message}`, {
+            cause: verified.error,
+        });
+    }
+    const installation = await reconcileEnvironmentRelease({
+        projectDir: input.projectDir,
+        environment: input.environment,
+        adapter: candidate.adapter,
+        deployment: verified,
+        ...(candidate.installation === undefined ? {} : { installation: candidate.installation }),
+        deployOnly: input.deployOnly,
+        ...(input.installationExecutable === undefined
+            ? {}
+            : { installationExecutable: input.installationExecutable }),
+        ...(input.identity === undefined ? {} : { identity: input.identity }),
+        ...(input.credential === undefined ? {} : { credential: input.credential }),
+        signal,
+    });
+    return Object.freeze({
+        deployment: verified,
+        ...(installation === undefined ? {} : { installation }),
+    });
+}

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

@@ -0,0 +1,11 @@
+/** Watch one Project Environment and serialize complete remote deployment generations. */
+export declare function develop(input: {
+    readonly configPath: string;
+    readonly projectDir: string;
+    readonly environment: string;
+    readonly deployOnly: boolean;
+    readonly identity?: string;
+    readonly credentialFile?: string;
+    readonly sessionFile?: string;
+    readonly secretsFile?: string;
+}): Promise<number>;