@astrale-os/sdk 0.6.0-beta.3 → 0.6.0-beta.30

package/dist/tooling/cli/arguments.js

@@ -1,41 +1,43 @@
-import { isAbsolute, normalize } from 'node:path';
-export const COMMANDS = ['dev', 'build', 'deploy', 'test', 'lint', 'package', 'upgrade'];
+import { acceptVersion } from '../../platform/versioning/index.js';
+import { installCommand } from '../../project/install-command.js';
+export const COMMANDS = [
+    'build',
+    'deploy',
+    'diff',
+    'list',
+    'publish',
+    'test',
+    'lint',
+    'package',
+    'upgrade',
+    'yank',
+];
+/** An adapter name or one of its command and option names, as `defineAdapter` admits them. */
+const PROVIDER_NAME = /^[a-z][a-z0-9-]{0,31}$/u;
 /** Parse the frozen `astrale-domain` command grammar without performing effects. */
 export function parseArgs(argv) {
     const [command, ...rest] = argv;
     if (command === 'upgrade')
         return parseUpgrade(rest);
+    if (command !== undefined && !COMMANDS.includes(command)) {
+        const provider = parseAdapterCommand(command, rest);
+        if (provider !== undefined)
+            return provider;
+    }
     const fix = rest.includes('--fix');
     const deployOnly = rest.includes('--deploy-only');
-    let sessionFile;
-    let secretsFile;
-    let credentialFile;
+    const json = rest.includes('--json');
+    const undo = rest.includes('--undo');
+    const allowDirty = rest.includes('--allow-dirty');
     let identity;
     let suite;
     let format;
     let environment;
+    const instances = [];
     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') {
+        if (argument === '--as') {
             identity = requiredValue('--as', rest[++index]);
         }
         else if (argument.startsWith('--as=')) {
@@ -53,13 +55,24 @@ export function parseArgs(argv) {
         else if (argument.startsWith('--environment=')) {
             environment = requiredValue('--environment', argument.slice('--environment='.length));
         }
+        else if (command === 'list' && argument === '--instance') {
+            // Only `list` asks instances; elsewhere `--instance` stays unknown, as deploy removed it.
+            instances.push(requiredValue('--instance', rest[++index]));
+        }
+        else if (command === 'list' && argument.startsWith('--instance=')) {
+            instances.push(requiredValue('--instance', argument.slice('--instance='.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') {
+        else if (argument === '--fix' ||
+            argument === '--deploy-only' ||
+            argument === '--json' ||
+            argument === '--undo' ||
+            argument === '--allow-dirty') {
             continue;
         }
         else if (argument.startsWith('-')) {
@@ -71,23 +84,37 @@ export function parseArgs(argv) {
     }
     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 (json &&
+        command !== 'build' &&
+        command !== 'deploy' &&
+        command !== 'diff' &&
+        command !== 'list' &&
+        command !== 'publish' &&
+        command !== 'yank') {
+        throw new Error('`--json` is only valid for `build`, `deploy`, `diff`, `list`, `publish`, `yank` or an adapter command.');
     }
-    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 (allowDirty && command !== 'publish') {
+        throw new Error('`--allow-dirty` is only valid for `publish`.');
     }
-    if (identity !== undefined && credentialFile !== undefined) {
-        throw new Error('Choose either `--as` or `--credential-file`, not both.');
+    if (undo && command !== 'yank')
+        throw new Error('`--undo` is only valid for `yank`.');
+    if (format !== undefined && command !== 'lint') {
+        throw new Error('`--format` is only valid for `lint`.');
     }
-    if ((deployOnly || identity !== undefined) && command !== 'dev' && command !== 'deploy') {
-        throw new Error('`--deploy-only` and `--as` are only valid for `dev` or `deploy`.');
+    if (deployOnly && command !== 'deploy')
+        refuseDeployOnly(undefined);
+    if (identity !== undefined &&
+        command !== 'deploy' &&
+        command !== 'diff' &&
+        command !== 'list' &&
+        command !== 'publish') {
+        throw new Error('`--as` is only valid for `deploy`, `diff`, `list` or `publish`.');
     }
-    if (environment !== undefined && command !== 'dev' && command !== 'deploy') {
-        if (command !== 'test') {
-            throw new Error('`--environment` is only valid for `dev`, `deploy`, or `test`.');
-        }
+    if (environment !== undefined &&
+        command !== 'deploy' &&
+        command !== 'list' &&
+        command !== 'test') {
+        throw new Error('`--environment` is only valid for `deploy`, `list` or `test`.');
     }
     if (suite !== undefined && command !== 'test') {
         throw new Error('`--suite` is only valid for `test`.');
@@ -97,31 +124,65 @@ export function parseArgs(argv) {
         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);
+            const env = environment ?? positionals[0];
             if (!env) {
                 throw new Error(`\`${command}\` requires an Environment, e.g. \`${command} development\`.`);
             }
+            if (deployOnly)
+                refuseDeployOnly(command, env);
             return {
                 command,
                 env,
-                ...(deployOnly ? { deployOnly: true } : {}),
+                ...(json ? { json: true } : {}),
                 ...(identity === undefined ? {} : { identity }),
-                ...(credentialFile === undefined ? {} : { credentialFile }),
-                ...(sessionFile === undefined ? {} : { sessionFile }),
-                ...(secretsFile === undefined ? {} : { secretsFile }),
             };
         }
+        case 'list':
+            // Every Environment of the Project, or the one `--environment` names.
+            if (positionals.length > 0) {
+                throw new Error('`list` does not accept positional arguments; use `--environment`.');
+            }
+            return {
+                command: 'list',
+                env: environment ?? '',
+                ...(json ? { json: true } : {}),
+                ...(identity === undefined ? {} : { identity }),
+                ...(instances.length === 0 ? {} : { instances: [...new Set(instances)] }),
+            };
         case 'build':
         case 'package':
             if (positionals.length > 0) {
                 throw new Error(`\`${command}\` does not accept positional arguments.`);
             }
-            return { command, env: '' };
+            return { command, env: '', ...(json ? { json: true } : {}) };
+        case 'diff':
+            // The version is package.json's: no command takes a version number (tech Versioning).
+            if (positionals.length > 0) {
+                throw new Error('`diff` does not accept positional arguments; it reads package.json.');
+            }
+            return {
+                command: 'diff',
+                env: '',
+                ...(json ? { json: true } : {}),
+                ...(identity === undefined ? {} : { identity }),
+            };
+        case 'publish': {
+            // The version is package.json's: the one positional names the Environment (tech Versioning).
+            if (positionals.length !== 1) {
+                throw new Error('`publish` takes exactly one Environment, e.g. `publish production`; it reads the version from package.json.');
+            }
+            return {
+                command: 'publish',
+                env: positionals[0],
+                ...(json ? { json: true } : {}),
+                ...(allowDirty ? { allowDirty: true } : {}),
+                ...(identity === undefined ? {} : { identity }),
+            };
+        }
         case 'test':
             if (positionals.length > 0) {
                 throw new Error('`test` does not accept positional arguments; use `--environment`.');
@@ -131,6 +192,18 @@ export function parseArgs(argv) {
                 env: environment ?? '',
                 ...(suite === undefined ? {} : { suite }),
             };
+        case 'yank': {
+            if (positionals.length !== 1) {
+                throw new Error('`yank` takes exactly one published version, e.g. `yank 1.5.0`.');
+            }
+            return {
+                command: 'yank',
+                env: '',
+                version: acceptVersion(positionals[0]),
+                ...(undo ? { undo: true } : {}),
+                ...(json ? { json: true } : {}),
+            };
+        }
         case 'lint':
             if (positionals.length > 0)
                 throw new Error('`lint` does not accept positional arguments.');
@@ -144,6 +217,63 @@ export function parseArgs(argv) {
             throw new Error(command ? `Unknown command "${command}".` : 'Missing command.');
     }
 }
+/**
+ * `--deploy-only` suppressed the installation a deploy used to make. A deploy never installs
+ * (DX [.81399], AM-72), so the flag is refused before any effect, naming the commands that
+ * replace it. Its only consumer pins an SDK older than this refusal.
+ */
+function refuseDeployOnly(command, environment) {
+    const refusal = '`--deploy-only` is no longer accepted: a deploy never installs.';
+    if (command === undefined || environment === undefined)
+        throw new Error(refusal);
+    throw new Error(`${refusal} Run \`astrale-domain ${command} ${environment}\` without it, then install the ` +
+        `URL it prints with \`${installCommand()}\`.`);
+}
+/**
+ * `astrale-domain <adapter> <command> <environment> [--<option> <value>]... [--json]`: a provider
+ * command, routed once the Project is loaded to the adapter of that Environment. Anything that is
+ * not exactly an adapter name, a command and an Environment is no command at all (undefined).
+ */
+function parseAdapterCommand(adapter, args) {
+    if (!PROVIDER_NAME.test(adapter))
+        return undefined;
+    const positionals = [];
+    const options = {};
+    let json = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === '--json') {
+            json = true;
+            continue;
+        }
+        if (!argument.startsWith('-')) {
+            positionals.push(argument);
+            continue;
+        }
+        const equals = argument.indexOf('=');
+        const name = argument.slice(2, equals === -1 ? undefined : equals);
+        if (!argument.startsWith('--') || !PROVIDER_NAME.test(name)) {
+            throw new Error(`Unknown flag "${argument}".`);
+        }
+        if (Object.hasOwn(options, name))
+            throw new Error(`--${name} is given twice.`);
+        options[name] =
+            equals === -1
+                ? requiredValue(`--${name}`, args[++index])
+                : requiredValue(`--${name}`, argument.slice(equals + 1));
+    }
+    const [adapterCommand, env] = positionals;
+    if (positionals.length !== 2 || !PROVIDER_NAME.test(adapterCommand))
+        return undefined;
+    return {
+        command: 'adapter',
+        env: env,
+        adapter,
+        adapterCommand: adapterCommand,
+        options,
+        ...(json ? { json: true } : {}),
+    };
+}
 function parseUpgrade(args) {
     let channel = 'beta';
     let check = false;
@@ -173,10 +303,3 @@ function requiredValue(flag, input) {
         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/build.d.ts

@@ -0,0 +1,55 @@
+import type { Build, BuildDigest, BuildManifestV1, Bundle, Bundler, ResolvedRuntimeReference } from '../../deployment/index.js';
+import type { LoadedProject } from './project.js';
+/** `astrale-domain build --json`: the build digest of every distinct bundler of the Project. */
+export interface BuildResultV1 {
+    readonly format: 'astrale.build-result';
+    readonly version: 1;
+    readonly origin: string;
+    readonly schema: {
+        readonly revision: BuildManifestV1['schema']['revision'];
+    };
+    readonly builds: readonly {
+        readonly bundler: {
+            readonly id: string;
+            readonly version: string;
+        };
+        readonly digest: BuildDigest;
+    }[];
+}
+/** One bundler a Project declares, with the Environments whose adapters declare it. */
+export interface ProjectBundler {
+    readonly bundler: Bundler;
+    readonly environments: readonly {
+        readonly name: string;
+        /** `<adapter name>@<adapter version>` */
+        readonly adapter: string;
+    }[];
+}
+/**
+ * The distinct bundlers of a Project's Environments, in declaration order. Environments whose
+ * adapters declare one bundler object share its build. Two copies of one bundler (two installed
+ * versions of its package) are two bundlers even under one id and version, since their code can
+ * differ.
+ */
+export declare function projectBundlers(project: LoadedProject): readonly ProjectBundler[];
+/** Bundle one Build without any Environment and identify the bytes by their build digest. */
+export declare function bundleBuild<const BuildValue extends Build>(input: {
+    readonly bundler: Bundler;
+    readonly projectDir: string;
+    readonly build: BuildValue;
+    readonly runtime: ResolvedRuntimeReference;
+    readonly signal: AbortSignal;
+}): Promise<Bundle<BuildValue>>;
+/**
+ * One entry per distinct build: copies of one bundler that produced the same bytes give one entry,
+ * copies that produced different bytes give one entry each.
+ */
+export declare function buildResult(build: Build, bundles: readonly Bundle[]): BuildResultV1;
+/**
+ * A warning for every bundler id and version whose copies produced different bytes: each copy's
+ * Environments deploy their own build, so the Project has more than one build for that bundler.
+ */
+export declare function bundlerCopyWarnings(built: readonly {
+    readonly source: ProjectBundler;
+    readonly bundle: Bundle;
+}[]): readonly string[];

package/dist/tooling/cli/build.js

@@ -0,0 +1,77 @@
+import { verifyBundle } from '../../deployment/index.js';
+/**
+ * The distinct bundlers of a Project's Environments, in declaration order. Environments whose
+ * adapters declare one bundler object share its build. Two copies of one bundler (two installed
+ * versions of its package) are two bundlers even under one id and version, since their code can
+ * differ.
+ */
+export function projectBundlers(project) {
+    const bundlers = new Map();
+    for (const [name, environment] of Object.entries(project.environments)) {
+        const adapter = environment.deployment.adapter;
+        const environments = bundlers.get(adapter.bundler) ?? [];
+        environments.push(Object.freeze({ name, adapter: `${adapter.name}@${adapter.version}` }));
+        bundlers.set(adapter.bundler, environments);
+    }
+    return Object.freeze([...bundlers].map(([bundler, environments]) => Object.freeze({ bundler, environments: Object.freeze(environments) })));
+}
+/** Bundle one Build without any Environment and identify the bytes by their build digest. */
+export async function bundleBuild(input) {
+    const source = await input.bundler.bundle({
+        projectDir: input.projectDir,
+        build: input.build,
+        runtime: input.runtime,
+        signal: input.signal,
+    });
+    return verifyBundle({
+        build: input.build,
+        runtime: input.runtime,
+        bundler: input.bundler,
+        source,
+    });
+}
+/**
+ * One entry per distinct build: copies of one bundler that produced the same bytes give one entry,
+ * copies that produced different bytes give one entry each.
+ */
+export function buildResult(build, bundles) {
+    const builds = new Map();
+    for (const bundle of bundles) {
+        const { id, version } = bundle.manifest.bundler;
+        const key = JSON.stringify([id, version, bundle.digest]);
+        if (builds.has(key))
+            continue;
+        builds.set(key, Object.freeze({ bundler: Object.freeze({ id, version }), digest: bundle.digest }));
+    }
+    return Object.freeze({
+        format: 'astrale.build-result',
+        version: 1,
+        origin: build.schema.compiled.root.origin,
+        schema: Object.freeze({ revision: build.schema.compiled.root.revision }),
+        builds: Object.freeze([...builds.values()]),
+    });
+}
+/**
+ * A warning for every bundler id and version whose copies produced different bytes: each copy's
+ * Environments deploy their own build, so the Project has more than one build for that bundler.
+ */
+export function bundlerCopyWarnings(built) {
+    const byBundler = new Map();
+    for (const { source, bundle } of built) {
+        const { id, version } = bundle.manifest.bundler;
+        const name = `${id}@${version}`;
+        const digests = byBundler.get(name) ?? new Map();
+        const environments = digests.get(bundle.digest) ?? [];
+        environments.push(...source.environments.map((environment) => `${environment.name}: ${environment.adapter}`));
+        digests.set(bundle.digest, environments);
+        byBundler.set(name, digests);
+    }
+    return Object.freeze([...byBundler]
+        .filter(([, digests]) => digests.size > 1)
+        .map(([name, digests]) => `Bundler ${name} gives ${digests.size} build digests for this tree: ` +
+        [...digests]
+            .map(([digest, environments]) => `${digest} (${environments.join(', ')})`)
+            .join('; ') +
+        '. These adapters load different copies of the bundler; align their versions ' +
+        '(`astrale-domain upgrade`) so that it gives one build.'));
+}

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

@@ -10,6 +10,5 @@ export type BunOutcome = {
 };
 /** 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;

package/dist/tooling/cli/bun.js

@@ -14,10 +14,6 @@ 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)
@@ -44,9 +40,6 @@ export function runWithBun(executable, argv) {
         });
     });
 }
-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'));

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

@@ -0,0 +1,35 @@
+import type { DeploymentCommitV1 } from '../../deployment/address/index.js';
+/**
+ * The commit provenance a canonical deploy declares in its deployment record (CT18 `commit`): the
+ * commit of the repository the Project lives in, whether the working tree holds changes that
+ * commit does not, and the last release of the Domain before it, as `git describe` finds it.
+ *
+ * - `dirty` covers tracked changes and untracked files, over the whole working tree; ignored files
+ *   never count. Unlike `git describe --dirty`, an untracked file counts, since a build can import
+ *   it.
+ * - `base` is the nearest release tag of the package the Domain is released from: the
+ *   release-please package that holds the Domain's runtime module (see {@link releaseTagPrefixes}).
+ *   The tag prefix is stripped, and a tag whose rest is not a canonical SemVer version is left
+ *   out, so the record never carries a base a deployment name would refuse (AM-57). A Domain no
+ *   release line holds declares no base: it is never given another package's version.
+ * - Outside a git repository, without git, or in a repository whose commits are not SHA-1, the
+ *   deploy declares no commit (`null`); a deploy never fails for want of provenance.
+ */
+export declare function deploymentCommit(input: {
+    readonly projectDir: string;
+    /** The Domain's runtime module, as the Project's `entrypoints.runtime` resolves it. */
+    readonly runtimeModule: string;
+    readonly signal: AbortSignal;
+}): Promise<DeploymentCommitV1 | null>;
+/**
+ * Whether a remote-tracking branch of the repository already holds a commit. A Publication records
+ * the commit it was built from, and release-please computes the next number from the pushed
+ * history: publishing a commit nobody pushed risks the same number being computed again (tech
+ * Versioning [.73872]). Nothing when git cannot tell. Reads the local remote-tracking refs only,
+ * never the network.
+ */
+export declare function commitPushed(input: {
+    readonly projectDir: string;
+    readonly sha: string;
+    readonly signal: AbortSignal;
+}): Promise<boolean | undefined>;