@astrale-os/sdk 0.6.0-beta.4 → 0.6.0-beta.41

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

@@ -1,7 +1 @@
-import { type ParsedArgs } from './arguments.js';
-import { develop } from './development/develop.js';
 export declare function run(argv: readonly string[]): Promise<number>;
-export declare function executeDevelopmentCommand(parsed: ParsedArgs, input: {
-    readonly configPath: string;
-    readonly projectDir: string;
-}, execute?: typeof develop): Promise<number>;

package/dist/tooling/cli/orchestrate.js

@@ -1,18 +1,22 @@
 import { existsSync } from 'node:fs';
-import { dirname, isAbsolute, join, resolve } from 'node:path';
-import { admitRuntime, compile, resolveRuntime, verifyDeployment, verifyPreflight, } from '../../deployment/index.js';
+import { dirname, join, resolve } from 'node:path';
+import { admitRuntime, compile, resolveRuntime } from '../../deployment/index.js';
 import { packageDomain } from '../packaging/index.js';
+import { runAdapterCommand } from './adapter-command.js';
 import { parseArgs } from './arguments.js';
-import { resolveCompatibleAstrale } from './astrale/version.js';
+import { buildResult, bundleBuild, bundlerCopyWarnings, projectBundlers } from './build.js';
 import { BunRequiredError } from './bun.js';
-import { deprecationWarnings } from './deprecations.js';
-import { develop } from './development/develop.js';
-import { loadDeclaredSecrets } from './dotenv.js';
-import { reconcileEnvironmentRelease } from './environment-release.js';
+import { selectDeployMode } from './deploy-mode.js';
+import { runDiff } from './diff/index.js';
 import { ERROR_USAGE, helpRequest, helpText } from './help.js';
-import { error, info, warn } from './log.js';
-import { importModule, loadProject, runtimeEntrypoint, selectEnvironment } from './project.js';
+import { deployImmutable } from './immutable-deployment.js';
+import { listDeployments, renderDeploymentList } from './list.js';
+import { error, info, progress, warn } from './log.js';
+import { importModule, loadProject, runtimeEntrypoint, selectEnvironment, } from './project.js';
+import { runPublish } from './publish/index.js';
+import { MINIMUM_INSTALLATIONS_CLI_VERSION, openDomainRegistry, RegistryCliError, } from './registry/index.js';
 import { executeTests } from './test.js';
+import { yankPublication, yankSummary } from './yank.js';
 const CONFIG_NAMES = ['astrale.config.ts', 'astrale.config.js', 'astrale.config.mjs'];
 export async function run(argv) {
     const requestedHelp = helpRequest(argv);
@@ -56,10 +60,39 @@ export async function run(argv) {
         error(`No astrale.config.ts found in ${projectDir}.`);
         return 1;
     }
-    if (parsed.command === 'dev') {
-        return executeDevelopmentCommand(parsed, { configPath, projectDir });
-    }
     const project = await loadProject(configPath);
+    if (parsed.command === 'list')
+        return list(parsed, project, projectDir);
+    if (parsed.command === 'adapter') {
+        const lifecycle = deploymentLifecycle(`${parsed.adapter} ${parsed.adapterCommand} interrupted.`);
+        try {
+            return await runAdapterCommand({
+                adapter: parsed.adapter,
+                command: parsed.adapterCommand,
+                environment: parsed.env,
+                definition: selectEnvironment(project, parsed.env),
+                options: parsed.options ?? {},
+                json: parsed.json === true,
+                signal: lifecycle.signal,
+            });
+        }
+        finally {
+            lifecycle.dispose();
+        }
+    }
+    if (parsed.command === 'yank')
+        return yank(parsed, project);
+    if (parsed.command === 'publish') {
+        // A version names an immutable deployment's release: any other Environment is refused before
+        // anything is built (CT33, R-G03).
+        const mode = selectDeployMode({
+            command: 'publish',
+            environment: parsed.env,
+            definition: selectEnvironment(project, parsed.env),
+        });
+        if (refused(mode))
+            return 1;
+    }
     if (parsed.command === 'test') {
         selectEnvironment(project, parsed.env);
         return executeTests({
@@ -67,94 +100,230 @@ export async function run(argv) {
             ...(parsed.suite === undefined ? {} : { suite: parsed.suite }),
         });
     }
-    const build = compile(project.application);
-    for (const warning of deprecationWarnings(build))
-        warn(warning);
+    const build = compile(project.domain);
     const resolved = await resolveRuntime(runtimeEntrypoint(project), (path) => importModule(resolve(dirname(configPath), path)));
     admitRuntime({ runtime: build.runtime }, resolved);
+    if (parsed.command === 'diff') {
+        const lifecycle = deploymentLifecycle('Diff interrupted.');
+        try {
+            return await runDiff({
+                projectDir,
+                build,
+                // The build digests `build` prints, bundled only when the Schema revision is unchanged.
+                builds: async () => {
+                    const digests = [];
+                    for (const source of projectBundlers(project)) {
+                        const bundle = await bundleBuild({
+                            bundler: source.bundler,
+                            projectDir,
+                            build,
+                            runtime: resolved,
+                            signal: lifecycle.signal,
+                        });
+                        digests.push(bundle.digest);
+                    }
+                    return digests;
+                },
+                ...(parsed.identity === undefined ? {} : { identity: parsed.identity }),
+                json: parsed.json === true,
+                signal: lifecycle.signal,
+            });
+        }
+        finally {
+            lifecycle.dispose();
+        }
+    }
+    if (parsed.command === 'publish') {
+        const environment = selectEnvironment(project, parsed.env);
+        const lifecycle = deploymentLifecycle('Publish interrupted.');
+        try {
+            return await runPublish({
+                projectDir,
+                environment: parsed.env,
+                adapter: environment.deployment.adapter,
+                parameters: environment.deployment.parameters,
+                build,
+                runtime: resolved,
+                ...(parsed.identity === undefined ? {} : { identity: parsed.identity }),
+                allowDirty: parsed.allowDirty === true,
+                json: parsed.json === true,
+                signal: lifecycle.signal,
+            });
+        }
+        finally {
+            lifecycle.dispose();
+        }
+    }
     if (parsed.command === 'build') {
-        info(`Built ${build.schema.compiled.root.origin} (${build.schema.compiled.root.revision}).`);
-        return 0;
+        // Every distinct bundler of the Project, and never an Environment, address, key or secret.
+        const lifecycle = deploymentLifecycle();
+        try {
+            const built = [];
+            for (const source of projectBundlers(project)) {
+                built.push({
+                    source,
+                    bundle: await bundleBuild({
+                        bundler: source.bundler,
+                        projectDir,
+                        build,
+                        runtime: resolved,
+                        signal: lifecycle.signal,
+                    }),
+                });
+            }
+            for (const warning of bundlerCopyWarnings(built))
+                warn(warning);
+            const result = buildResult(build, built.map(({ bundle }) => bundle));
+            if (parsed.json === true) {
+                process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+                return 0;
+            }
+            info(`Built ${result.origin} (${result.schema.revision}).`);
+            for (const built of result.builds) {
+                info(`Build: ${built.digest} (${built.bundler.id}@${built.bundler.version})`);
+            }
+            return 0;
+        }
+        finally {
+            lifecycle.dispose();
+        }
     }
     const environment = selectEnvironment(project, parsed.env);
-    const adapter = environment.deployment.adapter;
-    const parameters = environment.deployment.parameters;
+    // The configuration selects the deploy mode, before any effect (CT33).
+    const mode = selectDeployMode({
+        command: 'deploy',
+        environment: parsed.env,
+        definition: environment,
+    });
+    if (refused(mode))
+        return 1;
+    // With `--json`, stdout carries only the DeployResultV1; progress goes to stderr.
+    const report = progress(parsed.json === true);
     const lifecycle = deploymentLifecycle();
     try {
-        const source = await adapter.prepare(parameters, {
+        const deployment = {
             projectDir,
             environment: parsed.env,
-            ...(environment.installation === undefined ? {} : { installation: environment.installation }),
-            mode: 'release',
-            signal: lifecycle.signal,
             build,
             runtime: resolved,
-        });
-        const artifact = verifyPreflight({ build, runtime: resolved, source });
-        const secrets = secretsFor(adapter, parameters, projectDir, resolved.runtime);
-        const installationExecutable = environment.installation === undefined || parsed.deployOnly
-            ? undefined
-            : await resolveCompatibleAstrale({ projectDir, signal: lifecycle.signal });
-        const deployed = await adapter.deploy(parameters, {
-            projectDir,
-            environment: parsed.env,
-            ...(environment.installation === undefined ? {} : { installation: environment.installation }),
             ...(parsed.identity === undefined ? {} : { identity: parsed.identity }),
-            secrets,
-            artifact,
             signal: lifecycle.signal,
+            report,
+        };
+        const deployed = await deployImmutable({
+            ...deployment,
+            adapter: environment.deployment.adapter,
+            parameters: environment.deployment.parameters,
         });
-        const result = verifyDeployment(artifact, deployed);
-        if (result.status === 'failed') {
-            error(`Deployment failed during ${result.phase}: ${result.error.message}`);
+        if (deployed === undefined)
             return 1;
-        }
-        info(`Domain: ${result.release.publication.origin}`);
-        info(`Environment: ${parsed.env}`);
-        info(`Adapter: ${adapter.name}@${adapter.version}`);
-        info(`Deployment: ${result.progress.provider.evidence.deployment}`);
-        if (result.progress.provider.evidence.preflight !== undefined) {
-            info(`Preflight: ${result.progress.provider.evidence.preflight}; public readiness verified`);
-        }
-        info(`Public: ${result.release.addressing.publicUrl}`);
-        info(`Publication: ${result.release.publication.schema.revision} · ${result.release.publication.etag}`);
-        const installed = await reconcileEnvironmentRelease({
-            projectDir,
-            environment: parsed.env,
-            adapter,
-            deployment: result,
-            ...(environment.installation === undefined ? {} : { installation: environment.installation }),
-            deployOnly: parsed.deployOnly ?? false,
-            ...(installationExecutable === undefined ? {} : { installationExecutable }),
+        if (parsed.json === true)
+            process.stdout.write(`${JSON.stringify(deployed, null, 2)}\n`);
+        return 0;
+    }
+    finally {
+        lifecycle.dispose();
+    }
+}
+/**
+ * `astrale-domain list`: the deployments of every Environment, or of the one `--environment`
+ * names, as their hosts keep them for the caller, named by the registry's versions and placed on
+ * the instances each `--instance` says pin them. With `--json`, stdout
+ * carries only the ListResultV1, and only when every host and the registry answered; notices go to
+ * stderr. A registry that cannot be read (no Astrale CLI, one older than the listing's floor, Admin
+ * out of reach, an unreadable index) prints nothing on stdout and exits 1: versions are never
+ * dropped silently (AM-224).
+ */
+async function list(parsed, project, projectDir) {
+    const origin = compile(project.domain).schema.compiled.root.origin;
+    const environments = parsed.env === ''
+        ? Object.entries(project.environments)
+        : [[parsed.env, selectEnvironment(project, parsed.env)]];
+    const lifecycle = deploymentLifecycle();
+    try {
+        const listing = await listDeployments({
+            origin,
+            environments,
             ...(parsed.identity === undefined ? {} : { identity: parsed.identity }),
             signal: lifecycle.signal,
+            registry: (signal) => openDomainRegistry({
+                projectDir,
+                ...(parsed.identity === undefined ? {} : { identity: parsed.identity }),
+                signal,
+                minimum: MINIMUM_INSTALLATIONS_CLI_VERSION,
+            }),
+            ...(parsed.instances === undefined ? {} : { instances: parsed.instances }),
         });
-        if (installed === undefined) {
-            info('Installation: skipped');
+        for (const notice of listing.notices)
+            warn(notice);
+        for (const failure of listing.failures) {
+            error(`Environment ${failure.environment} could not be listed (${failure.adapter}): ` +
+                failure.error.message);
+        }
+        if (listing.registryFailure !== undefined) {
+            const failure = listing.registryFailure;
+            error(failure instanceof RegistryCliError
+                ? `Domain registry: ${failure.code}: ${failure.message}`
+                : `Domain registry: ${failure.message}`);
+            return 1;
         }
-        else {
-            info(`Installation: ${installed.instance} · ${installed.status}`);
+        if (parsed.json === true) {
+            if (listing.failures.length > 0)
+                return 1;
+            process.stdout.write(`${JSON.stringify(listing.result, null, 2)}\n`);
+            return 0;
         }
-        info('Ready: deployment verified');
-        return 0;
+        const failed = listing.failures.length > 0;
+        for (const line of renderDeploymentList(listing.result, failed)) {
+            process.stdout.write(`${line}\n`);
+        }
+        return failed ? 1 : 0;
     }
     finally {
         lifecycle.dispose();
     }
 }
-export function executeDevelopmentCommand(parsed, input, execute = develop) {
-    if (parsed.command !== 'dev')
-        throw new TypeError('Development execution requires the dev command.');
-    return execute({
-        configPath: input.configPath,
-        projectDir: input.projectDir,
-        environment: parsed.env,
-        deployOnly: parsed.deployOnly ?? false,
-        ...(parsed.identity === undefined ? {} : { identity: parsed.identity }),
-        ...(parsed.credentialFile === undefined ? {} : { credentialFile: parsed.credentialFile }),
-        ...(parsed.sessionFile === undefined ? {} : { sessionFile: parsed.sessionFile }),
-        ...(parsed.secretsFile === undefined ? {} : { secretsFile: parsed.secretsFile }),
-    });
+/** Report every refusal of a refused deploy mode, each with what to write instead. */
+function refused(mode) {
+    if (mode.kind !== 'refused')
+        return false;
+    for (const refusal of mode.refusals)
+        error(refusal.guidance);
+    return true;
+}
+/**
+ * `astrale-domain yank <version> [--undo]`: take one published version of the Project's Domain
+ * out of resolution in the Admin registry, or put it back. With `--json`, stdout carries only the
+ * YankReportV1; a refused or failed run prints nothing there.
+ */
+async function yank(parsed, project) {
+    if (parsed.version === undefined)
+        throw new TypeError('`yank` requires a published version.');
+    const origin = compile(project.domain).schema.compiled.root.origin;
+    const lifecycle = deploymentLifecycle('Yank interrupted.');
+    try {
+        const report = await yankPublication({
+            origin,
+            version: parsed.version,
+            undo: parsed.undo === true,
+            projectDir: process.cwd(),
+            signal: lifecycle.signal,
+        });
+        if (parsed.json === true)
+            process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+        else
+            info(yankSummary(report));
+        return 0;
+    }
+    catch (cause) {
+        if (!(cause instanceof RegistryCliError))
+            throw cause;
+        error(`${cause.code}: ${cause.message}`);
+        return 1;
+    }
+    finally {
+        lifecycle.dispose();
+    }
 }
 async function lint(parsed) {
     const { formatLintResult, lintDomain, LinterToolError } = await import('../linter/index.js');
@@ -174,25 +343,12 @@ async function lint(parsed) {
         throw cause;
     }
 }
-function secretsFor(adapter, parameters, projectDir, runtime) {
-    const file = adapter.secretsFile?.(parameters);
-    if (file === undefined)
-        return 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 Object.freeze({});
-    }
-    return Object.freeze(loadDeclaredSecrets(path, file));
-}
 function findConfig(projectDir) {
     return CONFIG_NAMES.map((name) => join(projectDir, name)).find(existsSync);
 }
-function deploymentLifecycle() {
+function deploymentLifecycle(interruption = 'Deployment interrupted.') {
     const controller = new AbortController();
-    const stop = () => controller.abort(new Error('Deployment interrupted.'));
+    const stop = () => controller.abort(new Error(interruption));
     process.once('SIGINT', stop);
     process.once('SIGTERM', stop);
     return Object.freeze({

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

@@ -1,4 +1,4 @@
-import type { Application } from '../../application/index.js';
+import type { DomainDefinition } from '../../application/index.js';
 import type { Requirements } from '../../application/requirements/index.js';
 import type { Routes } from '../../application/routes/index.js';
 import type { Runtime } from '../../application/runtime/index.js';
@@ -7,10 +7,10 @@ import type { Deployment } from '../../deployment/index.js';
 import type { schema } from '../../platform/schema/index.js';
 import type { Project, ProjectEnvironment } from '../../project/index.js';
 import type { Tests } from '../../testing/index.js';
-export type LoadedApplication = Application<schema.DomainSchema, Runtime, Frontend<schema.DomainSchema> | undefined, Routes | undefined, Requirements | undefined>;
+export type LoadedDomainDefinition = DomainDefinition<schema.DomainSchema, Runtime, Frontend<schema.DomainSchema> | undefined, Routes | undefined, Requirements | undefined>;
 export type LoadedDeployment = Deployment<object>;
 export type LoadedEnvironment = ProjectEnvironment<LoadedDeployment>;
-export type LoadedProject = Project<LoadedApplication, Readonly<Record<string, LoadedEnvironment>>, Tests | undefined>;
+export type LoadedProject = Project<LoadedDomainDefinition, Readonly<Record<string, LoadedEnvironment>>, Tests | undefined>;
 export declare function loadProject(path: string): Promise<LoadedProject>;
 export declare function selectEnvironment(project: LoadedProject, name: string): LoadedEnvironment;
 export declare function runtimeEntrypoint(project: LoadedProject): import("../../deployment/index.js").RuntimeReference;

package/dist/tooling/cli/publish/index.d.ts

@@ -0,0 +1,81 @@
+import type { Adapter, Build, Release, ResolvedRuntimeReference } from '../../../deployment/index.js';
+import type { DomainRegistry } from '../registry/index.js';
+export type { PublishReportV1 } from './report.js';
+export interface PublishCommandInput {
+    readonly projectDir: string;
+    readonly environment: string;
+    /** The adapter of a canonical Environment (CT33): `publish` refuses every other one before. */
+    readonly adapter: Adapter<object>;
+    readonly parameters: object;
+    readonly build: Build;
+    readonly runtime: ResolvedRuntimeReference;
+    /** `--as`: the identity that reads and writes the registry and deploys. */
+    readonly identity?: string;
+    /** `--allow-dirty`: publish from a working tree with changes, or outside git. */
+    readonly allowDirty: boolean;
+    readonly json: boolean;
+    readonly signal: AbortSignal;
+}
+/**
+ * What `publish` uses of the Domain registry: the index, the claim of an origin no one has, a
+ * baseline's bundle, the Publication.
+ */
+type PublishRegistry = Pick<DomainRegistry, 'index' | 'claim' | 'bundle' | 'publish'>;
+export interface PublishCommandDependencies {
+    readonly open: (input: {
+        readonly projectDir: string;
+        readonly identity?: string;
+        readonly signal: AbortSignal;
+        /** The first Astrale CLI release that serves every registry command publish may run. */
+        readonly minimum?: string;
+    }) => Promise<PublishRegistry>;
+    /** Step 5: the deployment serves exactly this sealed release at its URL. */
+    readonly verify: (release: Release, signal: AbortSignal) => Promise<void>;
+    /** Whether a remote-tracking branch already holds the commit (tech Versioning [.73872]). */
+    readonly pushed: (input: {
+        readonly projectDir: string;
+        readonly sha: string;
+        readonly signal: AbortSignal;
+    }) => Promise<boolean | undefined>;
+    readonly stdout: (text: string) => void;
+    readonly stderr: (text: string) => void;
+    /** The deadline of step 5; `VERIFY_TIMEOUT_MS` by default. */
+    readonly verifyTimeoutMs?: number;
+}
+/**
+ * Step 5 reads the deployment's `release.json` (at most 1 MiB) and its Bundle (at most 16 MiB)
+ * once the adapter has seen it ready: a deployment that accepts the connection and never answers
+ * is refused after this long, never waited on until the CI job's own timeout.
+ */
+export declare const VERIFY_TIMEOUT_MS = 60000;
+/**
+ * `astrale-domain publish <environment> [--allow-dirty] [--as <identity>] [--json]`: give the
+ * release this tree deploys in one Environment the version `package.json` declares (tech
+ * Versioning [.73345], Registry [.122137]). It deploys bottom-up and names last: the Publication
+ * Admin creates under the Domain's lock is the only switch, so every failure before it leaves at
+ * most a deployment without a version, which a rerun reuses (Registry [.122407]).
+ *
+ * 0. Before any effect: provenance (a dirty tree or no git is refused unless `--allow-dirty`; the
+ *    commit is recorded; an unpushed commit warns), then the plan of the deployment: build,
+ *    configure, placement, label, URL and the sealed release digest.
+ * 1. Read the version from `package.json`.
+ * 2. Read the registry. The version exists: the same release succeeds without effect, another is
+ *    refused. An origin the registry does not hold for this identity is claimed: Admin gives an
+ *    origin no one has to its first claimer, who administers its Domain, and refuses one another
+ *    account holds. A registry that does not answer is refused.
+ * 3. Judge the version against the highest stable version below it (AM-23); refuse a version
+ *    that is too low.
+ * 4. Deploy the release, or reuse its deployment.
+ * 5. Verify that the deployment serves the sealed release.
+ * 6. Ask Admin for the Publication; a version Admin gave another release meanwhile is refused,
+ *    naming the winner's release, and this deployment stays a preview. Any other failure says
+ *    what CT29 says of it: Admin may have created the Publication (a rerun settles it), Admin made
+ *    none and a rerun can help, or Admin refused and a rerun meets the same refusal. Then, when
+ *    the adapter declares `retain` (a host with no registry principal to keep it, CT36), it
+ *    keeps the published deployment. No first-party adapter declares it: Admin's Services and a
+ *    Cloudflare dispatch namespace keep every deployment until its owner retires it.
+ *
+ * Steps 0 to 3 make no deploy call; step 2's claim is the only registry change before step 6.
+ * Never installs.
+ */
+export declare function runPublish(input: PublishCommandInput, dependencies?: PublishCommandDependencies): Promise<number>;