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

package/dist/project/define.js

@@ -1,14 +1,18 @@
-import { isApplication } from '../application/index.js';
+import { isDomainDefinition } from '../application/index.js';
 import { isDeployment } from '../deployment/deployment.js';
+import { ENVIRONMENT_NAME } from '../deployment/environment.js';
 import { isTests } from '../testing/index.js';
+import { installCommand } from './install-command.js';
 const admittedProjects = new WeakSet();
-const ENVIRONMENT_NAME = /^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/u;
 /** Capture one inert Project definition without loading entrypoints or performing effects. */
 export function defineProject(input) {
     const value = record(input, 'Project definition');
-    exact(value, ['application', 'environments'], ['entrypoints', 'tests'], invalid);
-    if (!isApplication(input.application))
-        throw new TypeError('Project Application is not admitted.');
+    if (Object.hasOwn(value, 'application')) {
+        throw new TypeError('Project `application` is now `domain`: defineProject({ domain, environments }).');
+    }
+    exact(value, ['domain', 'environments'], ['entrypoints', 'tests'], invalid);
+    if (!isDomainDefinition(input.domain))
+        throw new TypeError('Project Domain is not admitted.');
     const environments = record(input.environments, 'Project environments');
     if (Reflect.ownKeys(environments).some((key) => typeof key !== 'string')) {
         throw new TypeError('Project Environment names must be strings.');
@@ -16,27 +20,28 @@ export function defineProject(input) {
     const names = Object.keys(environments);
     if (names.length === 0)
         throw new TypeError('Project must declare at least one Environment.');
-    const captured = Object.create(null);
-    for (const name of names) {
+    const declared = names.map((name) => {
         if (!ENVIRONMENT_NAME.test(name)) {
             throw new TypeError(`Project Environment name "${name}" is not normalized.`);
         }
-        const environment = record(environments[name], `Project Environment ${name}`);
-        exact(environment, ['deployment'], ['installation'], () => invalidEnvironment(name));
+        return [name, record(environments[name], `Project Environment ${name}`)];
+    });
+    // One refusal names every Environment that declares installation, each with its own commands.
+    const installations = declared
+        .filter(([, environment]) => Object.hasOwn(environment, 'installation'))
+        .map(([name, environment]) => installationRefusal(environment, name));
+    if (installations.length > 0)
+        throw new TypeError(installations.join('\n'));
+    const captured = Object.create(null);
+    for (const [name, environment] of declared) {
+        exact(environment, ['deployment'], [], () => invalidEnvironment(name));
         if (!isDeployment(environment.deployment)) {
             throw new TypeError(`Project Environment ${name} deployment is not admitted.`);
         }
-        const installation = environment.installation === undefined
-            ? undefined
-            : admitInstallation(environment.installation, name);
         environment.deployment.adapter.admit?.(environment.deployment.parameters, {
             environment: name,
-            ...(installation === undefined ? {} : { installation }),
-        });
-        captured[name] = Object.freeze({
-            deployment: environment.deployment,
-            ...(installation === undefined ? {} : { installation }),
         });
+        captured[name] = Object.freeze({ deployment: environment.deployment });
     }
     const entrypoints = input.entrypoints === undefined ? undefined : admitEntrypoints(input.entrypoints);
     if (input.tests !== undefined && !isTests(input.tests)) {
@@ -44,7 +49,7 @@ export function defineProject(input) {
     }
     const project = Object.freeze({
         kind: 'project',
-        application: input.application,
+        domain: input.domain,
         environments: Object.freeze(captured),
         ...(entrypoints === undefined ? {} : { entrypoints }),
         ...(input.tests === undefined ? {} : { tests: input.tests }),
@@ -68,22 +73,37 @@ function admitEntrypoints(input) {
     }
     return Object.freeze({ runtime: input.runtime });
 }
-function admitInstallation(input, environment) {
-    const value = record(input, `Project Environment ${environment} installation`);
-    exact(value, ['instance'], ['identity'], () => {
-        throw new TypeError(`Project Environment ${environment} installation may contain only instance and identity.`);
-    });
-    const instance = stableCoordinate(value.instance, 'installation instance');
-    const identity = value.identity === undefined
-        ? undefined
-        : stableCoordinate(value.identity, 'installation identity');
-    return Object.freeze({ instance, ...(identity === undefined ? {} : { identity }) });
-}
-function stableCoordinate(input, label) {
-    if (typeof input !== 'string' || input.length === 0 || input.trim() !== input) {
-        throw new TypeError(`Project ${label} must be a non-empty stable string.`);
+/**
+ * A deploy no longer installs (DX [.81399], AM-72): an Environment that still declares
+ * `installation` is refused before any effect, with the commands that replace it. Its only
+ * consumer pins an SDK older than this refusal.
+ *
+ * adapter-astrale deploys on Admin's Services, never through the installation's instance. The
+ * installation's instance and identity move to the install command.
+ */
+function installationRefusal(environment, name) {
+    const declared = environment.installation;
+    if (declared === undefined) {
+        return (`Project Environment ${name} declares \`installation\`, which a deploy no longer reads: a ` +
+            'deploy never installs. Remove the key.');
     }
-    return input;
+    const installation = declared !== null && typeof declared === 'object'
+        ? declared
+        : {};
+    const instance = stable(installation.instance);
+    const identity = stable(installation.identity);
+    return (`Project Environment ${name} declares installation, and a deploy no longer installs. ` +
+        `Remove \`installation\`, run \`astrale-domain deploy ${name}\`, ` +
+        `then install the URL it prints with \`${installCommand(instance, identity)}\`.`);
+}
+/** A declared coordinate worth repeating in guidance: a non-empty single-line trimmed string. */
+function stable(input) {
+    return typeof input === 'string' &&
+        input.length > 0 &&
+        input.trim() === input &&
+        !/[\s`]/u.test(input)
+        ? input
+        : undefined;
 }
 function record(input, label) {
     if (input === null || typeof input !== 'object' || Array.isArray(input)) {
@@ -99,8 +119,8 @@ function exact(input, required, optional, fail) {
     }
 }
 function invalid() {
-    throw new TypeError('Project definition may contain only application, environments, entrypoints, and tests.');
+    throw new TypeError('Project definition may contain only domain, environments, entrypoints, and tests.');
 }
 function invalidEnvironment(name) {
-    throw new TypeError(`Project Environment ${name} may contain only deployment and installation.`);
+    throw new TypeError(`Project Environment ${name} may contain only deployment.`);
 }

package/dist/project/index.d.ts

@@ -1,4 +1,4 @@
 export { admitProjectModule, PROJECT_EXPORT_HINT } from './admit.js';
 export { defineProject, isProject } from './define.js';
 export type { ProjectInput } from './define.js';
-export type { ApplicationOfProject, EnvironmentsOfProject, Project, ProjectEntrypoints, ProjectEnvironment, } from './project.js';
+export type { DomainDefinitionOfProject, EnvironmentsOfProject, Project, ProjectEntrypoints, ProjectEnvironment, } from './project.js';

package/dist/project/install-command.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The command that installs a deployed URL on an instance, as every SDK refusal and help text
+ * names it. A deploy never installs (DX [.81399], AM-72): `astrale-domain deploy <environment>`
+ * prints a URL, and this command installs it.
+ */
+export declare function installCommand(instance?: string, identity?: string): string;

package/dist/project/install-command.js

@@ -0,0 +1,9 @@
+/**
+ * The command that installs a deployed URL on an instance, as every SDK refusal and help text
+ * names it. A deploy never installs (DX [.81399], AM-72): `astrale-domain deploy <environment>`
+ * prints a URL, and this command installs it.
+ */
+export function installCommand(instance = '<instance>', identity) {
+    return (`astrale domain install <url> -i ${instance}` +
+        (identity === undefined ? '' : ` --as ${identity}`));
+}

package/dist/project/project.d.ts

@@ -1,24 +1,26 @@
-import type { ApplicationIdentity } from '../application/index.js';
-import type { InstallationTarget } from '../deployment/adapter/index.js';
+import type { DomainDefinitionIdentity } from '../application/index.js';
 import type { Tests } from '../testing/index.js';
 export interface ProjectEntrypoints {
     readonly runtime: string;
 }
+/**
+ * One Environment of a Project: where and how its deployments are made. It never names an
+ * instance: a deploy installs nothing, and `astrale domain install <url>` installs a deployment.
+ */
 export interface ProjectEnvironment<DeploymentValue = unknown> {
     readonly deployment: DeploymentValue;
-    readonly installation?: InstallationTarget;
 }
 /** The complete independently executable software-product definition in astrale.config.ts. */
-export interface Project<ApplicationValue extends ApplicationIdentity = ApplicationIdentity, EnvironmentsValue extends Readonly<Record<string, ProjectEnvironment>> = Readonly<Record<string, ProjectEnvironment>>, TestsValue extends Tests | undefined = undefined> {
+export interface Project<DomainDefinitionValue extends DomainDefinitionIdentity = DomainDefinitionIdentity, EnvironmentsValue extends Readonly<Record<string, ProjectEnvironment>> = Readonly<Record<string, ProjectEnvironment>>, TestsValue extends Tests | undefined = undefined> {
     readonly kind: 'project';
-    readonly application: ApplicationValue;
+    readonly domain: DomainDefinitionValue;
     readonly environments: EnvironmentsValue;
     readonly entrypoints?: ProjectEntrypoints;
     readonly tests?: TestsValue;
 }
-export type ApplicationOfProject<Value> = Value extends {
-    readonly application: infer ApplicationValue;
-} ? Extract<ApplicationValue, ApplicationIdentity> : never;
+export type DomainDefinitionOfProject<Value> = Value extends {
+    readonly domain: infer DomainDefinitionValue;
+} ? Extract<DomainDefinitionValue, DomainDefinitionIdentity> : never;
 export type EnvironmentsOfProject<Value> = Value extends {
     readonly environments: infer EnvironmentsValue;
 } ? EnvironmentsValue : never;

package/dist/testing/dataset/define.d.ts

@@ -7,7 +7,7 @@ export type AuthoredDatasetVariables = DatasetVariables | void;
 /** The exact variables record retained by a Dataset for one authored return type. */
 export type DatasetVariablesOf<Value> = [Value] extends [void] ? Readonly<Record<never, never>> : Value extends DatasetVariables ? Value : never;
 export interface DatasetInput<Schema extends schemaLanguage.DomainSchema, Variables extends AuthoredDatasetVariables> {
-    /** Stable lowercase identity, unique within one Application. */
+    /** Stable lowercase identity, unique within one Domain. */
     readonly id: string;
     readonly title?: string;
     readonly description?: string;

package/dist/testing/load.js

@@ -21,7 +21,7 @@ export async function loadDataset(reference, load, source) {
         throw new TypeError(`Dataset module ${reference.path} default export is not an admitted Dataset.`);
     }
     if (dataset.schema !== source) {
-        throw new TypeError(`Dataset ${dataset.id} (${reference.path}) targets Schema ${dataset.schema.origin}, not the exact Application Schema.`);
+        throw new TypeError(`Dataset ${dataset.id} (${reference.path}) targets Schema ${dataset.schema.origin}, not the exact Domain Schema.`);
     }
     return Object.freeze({ reference, dataset });
 }

package/dist/tooling/cli/adapter-command.d.ts

@@ -0,0 +1,35 @@
+import type { LoadedEnvironment } from './project.js';
+/**
+ * `astrale-domain <adapter> <command> <environment> --json` on stdout: what one provider command
+ * of the Environment's adapter answered (adapter-cloudflare: `cloudflare plan` and
+ * `cloudflare init`, which provision its host on the operator's own account).
+ */
+export interface AdapterCommandReportV1 {
+    readonly format: 'astrale.adapter-command';
+    readonly version: 1;
+    /** `<adapter name>@<adapter version>` */
+    readonly adapter: string;
+    readonly command: string;
+    readonly environment: string;
+    /** 0 done; 1 refused or blocked. */
+    readonly exitCode: 0 | 1;
+    /** What the adapter's command answered, as it answered it. */
+    readonly result: unknown;
+}
+/**
+ * `astrale-domain <adapter> <command> <environment> [--<option> <value>]... [--json]`: run one
+ * provider command an adapter declares, on an Environment that adapter deploys. The CLI only
+ * routes: it refuses an Environment whose adapter has another name, a command the adapter does
+ * not declare and an option the command does not declare, each before any effect, and prints what
+ * the command answers. Exit status: the command's (0 done, 1 refused or blocked), 1 when it could
+ * not run.
+ */
+export declare function runAdapterCommand(input: {
+    readonly adapter: string;
+    readonly command: string;
+    readonly environment: string;
+    readonly definition: LoadedEnvironment;
+    readonly options: Readonly<Record<string, string>>;
+    readonly json: boolean;
+    readonly signal: AbortSignal;
+}): Promise<number>;

package/dist/tooling/cli/adapter-command.js

@@ -0,0 +1,66 @@
+import { error, info, warn } from './log.js';
+/**
+ * `astrale-domain <adapter> <command> <environment> [--<option> <value>]... [--json]`: run one
+ * provider command an adapter declares, on an Environment that adapter deploys. The CLI only
+ * routes: it refuses an Environment whose adapter has another name, a command the adapter does
+ * not declare and an option the command does not declare, each before any effect, and prints what
+ * the command answers. Exit status: the command's (0 done, 1 refused or blocked), 1 when it could
+ * not run.
+ */
+export async function runAdapterCommand(input) {
+    const { adapter, parameters } = input.definition.deployment;
+    const name = `${adapter.name}@${adapter.version}`;
+    if (adapter.name !== input.adapter) {
+        error(`Environment ${input.environment} deploys through adapter ${adapter.name}, not ` +
+            `${input.adapter}: run \`astrale-domain ${adapter.name} <command> ${input.environment}\`.`);
+        return 1;
+    }
+    const commands = 'commands' in adapter ? adapter.commands : undefined;
+    const command = commands?.[input.command];
+    if (command === undefined) {
+        const declared = Object.entries(commands ?? {}).map(([candidate, { summary }]) => `${candidate} (${summary})`);
+        error(`Adapter ${name} declares no command ${input.command}` +
+            (declared.length === 0 ? '.' : `; its commands: ${declared.join('; ')}.`));
+        return 1;
+    }
+    const declaredOptions = command.options ?? {};
+    const unknown = Object.keys(input.options).filter((option) => !Object.hasOwn(declaredOptions, option));
+    if (unknown.length > 0) {
+        const known = Object.entries(declaredOptions).map(([option, description]) => `--${option} (${description})`);
+        error(`${input.adapter} ${input.command} takes no option ${unknown.map((option) => `--${option}`).join(', ')}` +
+            (known.length === 0 ? '.' : `; its options: ${known.join('; ')}.`));
+        return 1;
+    }
+    let answered;
+    try {
+        answered = await command.run(parameters, {
+            environment: input.environment,
+            signal: input.signal,
+            options: Object.freeze({ ...input.options }),
+        });
+    }
+    catch (cause) {
+        error(`${input.adapter} ${input.command} ${input.environment} (${name}) failed: ` +
+            (cause instanceof Error ? cause.message : String(cause)));
+        return 1;
+    }
+    for (const line of answered.warnings ?? [])
+        warn(line);
+    if (input.json) {
+        const report = Object.freeze({
+            format: 'astrale.adapter-command',
+            version: 1,
+            adapter: name,
+            command: input.command,
+            environment: input.environment,
+            exitCode: answered.exitCode,
+            result: answered.result,
+        });
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    }
+    else {
+        for (const line of answered.lines)
+            info(line);
+    }
+    return answered.exitCode;
+}

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

@@ -1,19 +1,30 @@
 import type { LintReportFormat } from '../linter/index.js';
-export declare const COMMANDS: readonly ['dev', 'build', 'deploy', 'test', 'lint', 'package', 'upgrade'];
+import { type Version } from '../../platform/versioning/index.js';
+export declare const COMMANDS: readonly ['build', 'deploy', 'diff', 'list', 'publish', 'test', 'lint', 'package', 'upgrade', 'yank'];
 export type Command = (typeof COMMANDS)[number];
 export interface ParsedArgs {
-    readonly command: Command;
+    /** `adapter`: a provider command of an Environment's adapter (`<adapter> <command> <env>`). */
+    readonly command: Command | 'adapter';
     readonly env: string;
     readonly fix?: boolean;
     readonly format?: LintReportFormat;
-    readonly deployOnly?: boolean;
     readonly identity?: string;
-    readonly credentialFile?: string;
     readonly suite?: string;
-    readonly sessionFile?: string;
-    readonly secretsFile?: string;
     readonly channel?: string;
     readonly check?: boolean;
+    readonly json?: boolean;
+    /** `yank`: the published version it names. */
+    readonly version?: Version;
+    /** `yank --undo`: restore the version instead of yanking it. */
+    readonly undo?: boolean;
+    readonly allowDirty?: boolean;
+    /** `list`: instances to ask what they run, in argument order. */
+    readonly instances?: readonly string[];
+    /** `<adapter> <command> <env>`: the adapter name and its command. */
+    readonly adapter?: string;
+    readonly adapterCommand?: string;
+    /** `<adapter> <command> <env> --<option> <value>`: the options, by name. */
+    readonly options?: Readonly<Record<string, string>>;
 }
 /** Parse the frozen `astrale-domain` command grammar without performing effects. */
 export declare function parseArgs(argv: readonly string[]): ParsedArgs;