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

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

@@ -1,27 +1,36 @@
-import { existsSync } from 'node:fs';
-import { mkdir, rm, rmdir, writeFile } from 'node:fs/promises';
-import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
-import { pathToFileURL } from 'node:url';
-import { admitRuntime, compile, isDeployment, resolveRuntime, verifyPreflight, } from '../../../deployment/index.js';
-import { addressing, assemble } from '../../../deployment/release/index.js';
-import { loadDeclaredSecrets, loadPrivateSecretsFile } from '../dotenv.js';
+import { rm, rmdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { resolveAstraleInstanceIssuer } from '../astrale/instance.js';
+import { resolveCompatibleAstrale } from '../astrale/version.js';
+import { loadPrivateCredentialFile } from '../credential.js';
+import { loadPrivateSecretsFile } from '../dotenv.js';
 import { error, info } from '../log.js';
+import { DevelopmentCandidateBuilder, discoverRuntimePath, sameDeploymentCandidate, sameEnvironment, } from './candidate.js';
+import { deployDevelopmentCandidate } from './deployment.js';
 import { DevelopmentLifecycle } from './lifecycle.js';
 import { acquireProjectLock } from './project-lock.js';
 import { LatestRebuild } from './rebuild.js';
-import { DevelopmentSessionFileError, DevelopmentSessionFileWriter } from './session-file.js';
+import { developmentReleaseEvidence } from './release-evidence.js';
+import { reportDevelopmentDeployment } from './report.js';
+import { DevelopmentSessionFileWriter } from './session-file.js';
 import { watchSources } from './source-watch.js';
-/** Run one complete provider-neutral development session until interruption. */
+import { acquireDevelopmentTargetLock } from './target-lock.js';
+import { DevelopmentView } from './view.js';
+/** Watch one Project Environment and serialize complete remote deployment generations. */
 export async function develop(input) {
     const lifecycle = new DevelopmentLifecycle();
     let sessionFile;
     let lock;
-    let session;
+    let targetLock;
+    let view;
+    let installationExecutable;
+    let installationIssuer;
     let sourceWatch;
     let rebuild;
+    let current;
+    let lastEvidence;
     let failure;
-    let failed = false;
-    let watcherFailure;
+    const cleanup = [];
     try {
         if (input.sessionFile !== undefined) {
             sessionFile = await DevelopmentSessionFileWriter.create(input.sessionFile);
@@ -33,103 +42,108 @@ export async function develop(input) {
         const overrideSecrets = input.secretsFile === undefined
             ? undefined
             : Object.freeze(loadPrivateSecretsFile(input.secretsFile));
+        const credential = input.credentialFile === undefined
+            ? undefined
+            : loadPrivateCredentialFile(input.credentialFile);
         const runtimePath = await discoverRuntimePath(input.configPath);
-        const builder = new ProjectBuilder({ ...input, runtimePath, overrideSecrets });
-        let current = await builder.prepare(lifecycle.signal);
-        let sessionEvidence;
-        let placementReady = false;
-        let rebuildActive = false;
-        let updatePrevious;
-        let placementSequence = 0;
-        const publishSessionPhase = async () => {
-            if (sessionFile === undefined || sessionEvidence === undefined)
-                return;
-            await sessionFile.transition(placementReady ? (rebuildActive ? 'updating' : 'ready') : 'recovering', sessionEvidence);
-        };
-        const adapter = current.adapter;
-        const parameters = current.parameters;
-        let restartReported = false;
-        info(`Domain: ${current.artifact.build.schema.compiled.root.origin}`);
-        session = await adapter.develop(parameters, {
-            projectDir: input.projectDir,
-            environment: input.environment,
-            artifact: current.artifact,
-            secrets: current.secrets,
-            overrides: input.overrides,
-            signal: lifecycle.signal,
-            async onRecovering() {
-                placementReady = false;
-                await publishSessionPhase();
-            },
-            async onPlacement(placement) {
-                if (sessionFile !== undefined) {
-                    sessionEvidence = coherentSessionEvidence(updatePrevious === undefined ? [current.artifact] : [current.artifact, updatePrevious], placement);
-                    placementReady = true;
-                    placementSequence += 1;
-                    await publishSessionPhase();
-                }
-                info(`Public: ${placement.releaseUrl}`);
-                if (placement.localUrl !== undefined)
-                    info(`Runtime: ${placement.localUrl}`);
-            },
+        const builder = new DevelopmentCandidateBuilder({
+            ...input,
+            runtimePath,
+            overrideSecrets,
         });
+        current = await builder.prepare(lifecycle.signal);
+        if (credential !== undefined && current.installation?.identity !== undefined) {
+            throw new TypeError('--credential-file cannot be combined with the Environment installation identity.');
+        }
+        if (sessionFile !== undefined && (current.installation === undefined || input.deployOnly)) {
+            throw new TypeError('--session-file requires an Environment installation that is active for this development session.');
+        }
+        info(`Domain: ${current.artifact.build.schema.compiled.root.origin}`);
+        if (current.installation !== undefined && !input.deployOnly) {
+            installationExecutable = await resolveCompatibleAstrale({
+                projectDir: input.projectDir,
+                signal: lifecycle.signal,
+            });
+            installationIssuer = await resolveAstraleInstanceIssuer({
+                executable: installationExecutable,
+                projectDir: input.projectDir,
+                instance: current.installation.instance,
+                signal: lifecycle.signal,
+            });
+            targetLock = await acquireDevelopmentTargetLock({
+                issuer: installationIssuer,
+                origin: current.artifact.build.schema.compiled.root.origin,
+            });
+            view = new DevelopmentView({
+                executable: installationExecutable,
+                projectDir: input.projectDir,
+                instance: current.installation.instance,
+                ...(credential === undefined
+                    ? { identity: input.identity ?? current.installation.identity }
+                    : { credential }),
+            });
+            if (current.artifact.build.frontend !== undefined)
+                await view.prepare(lifecycle.signal);
+        }
+        const first = await deployDevelopmentCandidate(current, { ...input, credential, installationExecutable }, lifecycle.signal);
+        lastEvidence =
+            first.installation === undefined ? undefined : developmentReleaseEvidence(first.installation);
+        await sessionFile?.transition('ready', lastEvidence);
+        reportDevelopmentDeployment(first.deployment, first.installation, current.adapter, input);
+        await refreshView(view, first.deployment.release, lifecycle.signal);
+        let restartReported = false;
         rebuild = new LatestRebuild({
             async prepare(_ignored, signal) {
-                rebuildActive = true;
-                await publishSessionPhase();
+                info(`Rebuilding: ${input.environment}`);
+                if (lastEvidence !== undefined)
+                    await sessionFile?.transition('updating', lastEvidence);
                 return builder.prepare(signal);
             },
-            async commit(candidate) {
-                if (candidate.adapter.name !== adapter.name ||
-                    candidate.adapter.version !== adapter.version ||
-                    stable(candidate.parameters) !== stable(parameters)) {
+            async commit(candidate, signal) {
+                if (!sameEnvironment(current, candidate)) {
                     restartReported = true;
-                    throw new Error('Adapter configuration changed; restart pnpm dev to apply it.');
+                    throw new Error('Project Environment configuration changed; restart pnpm dev to apply it.');
                 }
-                const previous = current;
-                const beforePlacement = placementSequence;
-                updatePrevious = previous.artifact;
-                current = candidate;
-                try {
-                    await session.update({ artifact: candidate.artifact, secrets: candidate.secrets });
-                    if (sessionFile !== undefined) {
-                        if (placementSequence === beforePlacement || sessionEvidence === undefined) {
-                            throw new DevelopmentSessionFileError('SESSION_FILE_EVIDENCE_INCOHERENT', 'Development adapter completed an update without reporting installed Release evidence.');
-                        }
-                        assertEvidenceMatches(candidate.artifact, sessionEvidence);
-                    }
-                    rebuildActive = false;
-                    await publishSessionPhase();
+                if (sameDeploymentCandidate(current, candidate)) {
+                    current = candidate;
+                    await sessionFile?.transition('ready', lastEvidence);
                     sourceWatch?.update(candidate.sources);
-                    info(`Updated ${candidate.artifact.build.schema.compiled.root.revision}.`);
-                }
-                catch (cause) {
-                    current = previous;
-                    if (sessionFile !== undefined &&
-                        sessionEvidence !== undefined &&
-                        !evidenceMatches(previous.artifact, sessionEvidence)) {
-                        throw new DevelopmentSessionFileError('SESSION_FILE_EVIDENCE_INCOHERENT', 'Development adapter rejected an update without restoring prior installed Release evidence.', { cause });
-                    }
-                    throw cause;
+                    return;
                 }
-                finally {
-                    updatePrevious = undefined;
+                if (installationIssuer !== undefined && candidate.installation !== undefined) {
+                    await resolveAstraleInstanceIssuer({
+                        executable: installationExecutable,
+                        projectDir: input.projectDir,
+                        instance: candidate.installation.instance,
+                        expectedIssuer: installationIssuer,
+                        signal,
+                    });
                 }
+                if (candidate.artifact.build.frontend !== undefined)
+                    await view?.prepare(signal);
+                const deployed = await deployDevelopmentCandidate(candidate, { ...input, credential, installationExecutable }, signal);
+                current = candidate;
+                lastEvidence =
+                    deployed.installation === undefined
+                        ? undefined
+                        : developmentReleaseEvidence(deployed.installation);
+                await sessionFile?.transition('ready', lastEvidence);
+                sourceWatch?.update(candidate.sources);
+                info(`Updated: ${candidate.artifact.build.schema.compiled.root.revision}`);
+                reportDevelopmentDeployment(deployed.deployment, deployed.installation, candidate.adapter, input);
+                await refreshView(view, deployed.deployment.release, signal);
             },
             async failed(cause) {
-                rebuildActive = false;
-                if (cause instanceof DevelopmentSessionFileError) {
-                    watcherFailure = cause;
-                    lifecycle.stop(cause);
-                    return;
-                }
                 error(cause instanceof Error ? cause.message : String(cause));
+                if (lastEvidence === undefined)
+                    return;
                 try {
-                    await publishSessionPhase();
+                    await sessionFile?.transition('recovering', lastEvidence);
                 }
                 catch (sessionCause) {
-                    watcherFailure = sessionCause;
-                    lifecycle.stop(sessionCause);
+                    const terminal = new AggregateError([cause, sessionCause], 'Development rebuild failed and session evidence could not be recovered.');
+                    failure ??= terminal;
+                    lifecycle.stop(terminal);
                 }
             },
         });
@@ -142,46 +156,38 @@ export async function develop(input) {
                 if (restartReported)
                     return;
                 restartReported = true;
-                error('Adapter configuration changed; restart pnpm dev to apply it.');
+                error('Project Environment configuration changed; restart pnpm dev to apply it.');
             },
             onError: (cause) => {
-                watcherFailure = cause;
+                failure = cause;
                 lifecycle.stop(cause);
             },
         });
-        const placement = session.current();
-        info(`Ready: watching for changes (${placement.releaseUrl}).`);
-        const completed = await Promise.race([
-            session.finished.then(() => 'session'),
-            lifecycle.stopped.then(() => 'signal'),
-        ]);
-        if (completed === 'session' && !lifecycle.signal.aborted) {
-            throw new Error('Development provider stopped unexpectedly.');
-        }
-        if (watcherFailure !== undefined)
-            throw watcherFailure;
+        info('Ready: watching for remote deployments');
+        // Edits made while the first build/deployment was in flight predate this watcher.
+        // Catch up once; artifact deduplication prevents an unchanged second deployment.
+        rebuild.invalidate();
+        await lifecycle.stopped;
     }
     catch (cause) {
-        failed = true;
         failure = cause;
     }
     lifecycle.stop(failure);
-    const cleanup = [];
     try {
-        await sessionFile?.transition('stopping');
+        await sessionFile?.transition('stopping', lastEvidence);
     }
     catch (cause) {
-        failed = true;
         failure ??= cause;
     }
     for (const operation of [
         () => sourceWatch?.stop(),
         () => rebuild?.stop(failure),
-        () => session?.stop(),
+        () => view?.close(AbortSignal.timeout(30_000)),
         () => rm(join(input.projectDir, '.astrale', 'development', input.environment, 'source'), {
             recursive: true,
             force: true,
         }),
+        () => targetLock?.release(),
         () => lock?.release(),
     ]) {
         try {
@@ -205,13 +211,13 @@ export async function develop(input) {
         }
     }
     try {
-        await sessionFile?.transition(failed || cleanup.length > 0 ? 'failed' : 'stopped');
+        await sessionFile?.transition(failure === undefined && cleanup.length === 0 ? 'stopped' : 'failed');
     }
     catch (cause) {
         cleanup.push(cause);
     }
     lifecycle.dispose();
-    if (failed) {
+    if (failure !== undefined) {
         if (cleanup.length > 0)
             error(new AggregateError(cleanup, 'Development cleanup failed.').message);
         throw failure;
@@ -220,185 +226,15 @@ export async function develop(input) {
         throw new AggregateError(cleanup, 'Development cleanup failed.');
     return 0;
 }
-function coherentSessionEvidence(artifacts, placement) {
-    const evidence = placement.installedRelease;
-    if (evidence === undefined) {
-        throw new DevelopmentSessionFileError('SESSION_FILE_EVIDENCE_INCOHERENT', '--session-file requires an adapter that reports exact installed Release evidence.');
-    }
-    let issuer;
-    try {
-        issuer = new URL(placement.releaseUrl).origin;
-    }
-    catch (cause) {
-        throw new DevelopmentSessionFileError('SESSION_FILE_EVIDENCE_INCOHERENT', 'Development adapter reported an invalid Release URL.', { cause });
-    }
-    if (placement.releaseUrl !== issuer) {
-        throw new DevelopmentSessionFileError('SESSION_FILE_EVIDENCE_INCOHERENT', 'Development adapter reported a non-canonical Release URL.');
-    }
-    let matches = false;
+async function refreshView(view, release, signal) {
+    if (view === undefined)
+        return;
     try {
-        matches = artifacts.some((artifact) => evidenceMatches(artifact, evidence));
+        const pageUrl = await view.refresh(release, signal);
+        if (pageUrl !== undefined)
+            info(`View: ${pageUrl}`);
     }
     catch (cause) {
-        throw new DevelopmentSessionFileError('SESSION_FILE_EVIDENCE_INCOHERENT', 'Development adapter reported invalid installed Release evidence.', { cause });
-    }
-    if (evidence.issuer !== issuer || !matches) {
-        throw new DevelopmentSessionFileError('SESSION_FILE_EVIDENCE_INCOHERENT', 'Development adapter installed Release evidence does not match the current artifact and placement.');
-    }
-    return evidence;
-}
-function assertEvidenceMatches(artifact, evidence) {
-    if (!evidenceMatches(artifact, evidence)) {
-        throw new DevelopmentSessionFileError('SESSION_FILE_EVIDENCE_INCOHERENT', 'Development adapter installed Release evidence does not match the committed artifact.');
-    }
-}
-function evidenceMatches(artifact, evidence) {
-    const root = artifact.build.schema.compiled.root;
-    const release = assemble(artifact.build, addressing(evidence.issuer));
-    return (evidence.origin === root.origin &&
-        evidence.revision === root.revision &&
-        evidence.etag === release.publication.etag);
-}
-class ProjectBuilder {
-    #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 configImport = moduleSpecifier(dirname(bridge), this.#configPath);
-        const runtimeImport = moduleSpecifier(dirname(bridge), resolve(dirname(this.#configPath), this.#runtimePath));
-        await writeFile(bridge, `export { default as deployment } from ${JSON.stringify(configImport)}\n` +
-            `export { default as runtime } from ${JSON.stringify(runtimeImport)}\n`);
-        try {
-            const built = await bun().build({
-                entrypoints: [bridge],
-                outdir: directory,
-                naming: 'application.mjs',
-                target: 'bun',
-                format: 'esm',
-                packages: 'external',
-                splitting: false,
-                sourcemap: 'inline',
-                metafile: true,
-            });
-            throwIfAborted(signal);
-            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 !== 'deployment' && key !== 'runtime')) {
-                throw new TypeError('Development bridge produced unexpected exports.');
-            }
-            const deployment = loaded.deployment;
-            if (!isDeployment(deployment)) {
-                throw new TypeError('astrale.config.ts default export must be created by deploy().');
-            }
-            const admitted = deployment;
-            const resolved = await resolveRuntime(admitted.entrypoint, 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(admitted.application);
-            admitRuntime({ runtime: build.runtime }, resolved);
-            const adapter = admitted.adapter;
-            const parameters = adapter.parameters(this.#environment);
-            const source = await adapter.prepare(parameters, {
-                projectDir: this.#projectDir,
-                environment: this.#environment,
-                mode: 'development',
-                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 };
-            const sources = new Set();
-            for (const path of Object.keys(built.metafile?.inputs ?? {})) {
-                const absolute = isAbsolute(path) ? path : resolve(this.#projectDir, path);
-                if (!absolute.startsWith(`${resolve(this.#projectDir)}${sep}`))
-                    continue;
-                if (absolute.includes(`${sep}.astrale${sep}`))
-                    continue;
-                sources.add(absolute);
-            }
-            if (declared.path !== undefined)
-                sources.add(declared.path);
-            return Object.freeze({
-                adapter,
-                parameters,
-                artifact,
-                secrets: declared.values,
-                sources,
-            });
-        }
-        finally {
-            await rm(directory, { recursive: true, force: true });
-        }
-    }
-}
-async function discoverRuntimePath(configPath) {
-    const loaded = (await import(`${pathToFileURL(configPath).href}?discover=${Date.now()}`));
-    if (Object.keys(loaded).length !== 1 || !Object.hasOwn(loaded, 'default')) {
-        throw new TypeError('astrale.config.ts must export exactly one default Deployment.');
-    }
-    if (!isDeployment(loaded.default)) {
-        throw new TypeError('Default export must be created by deploy().');
-    }
-    return loaded.default.entrypoint.path;
-}
-function secretsFor(adapter, parameters, projectDir, runtime) {
-    const file = adapter.secretsFile?.(parameters);
-    if (file === undefined)
-        return { values: Object.freeze({}) };
-    const path = isAbsolute(file) ? file : join(projectDir, file);
-    // An Integration-free Runtime has no Providers and therefore no author-owned
-    // environment secrets. Adapter-owned secrets, such as the signing identity,
-    // are resolved separately by the adapter and must not make this file required.
-    if (Object.keys(runtime.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 === 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.');
+        error(`View unavailable: ${cause instanceof Error ? cause.message : String(cause)}`);
     }
 }

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

@@ -0,0 +1,18 @@
+export declare class DevelopmentLeaseError extends Error {
+    readonly code: 'DEVELOPMENT_LEASE_LOCKED' | 'DEVELOPMENT_LEASE_LOST';
+    readonly name = "DevelopmentLeaseError";
+    constructor(code: 'DEVELOPMENT_LEASE_LOCKED' | 'DEVELOPMENT_LEASE_LOST', message: string, options?: ErrorOptions);
+}
+export interface DevelopmentLease {
+    readonly path: string;
+    readonly recovered: boolean;
+    release(): Promise<void>;
+}
+/** One fail-closed filesystem lease engine for every local development coordinate. */
+export declare function acquireDevelopmentLease(input: {
+    readonly directory: string;
+    readonly coordinate: string;
+    readonly pid?: number;
+    readonly sessionId?: string;
+    readonly processAlive?: (pid: number) => boolean;
+}): Promise<DevelopmentLease>;