@astrale-os/sdk 0.6.0-beta.2 → 0.6.0-beta.21

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

@@ -0,0 +1,154 @@
+import type { DeploymentRecordV1, DeploymentSummaryV1 } from '../../deployment/address/index.js';
+import type { DeploymentCallTarget } from '../../deployment/index.js';
+import type { InstallationSourcesV1, InstalledOnV1 } from './installed-on.js';
+import type { LoadedEnvironment } from './project.js';
+import type { DomainRegistry } from './registry/index.js';
+export type { InstallationSourcesV1, InstalledOnV1, InstanceSourceV1 } from './installed-on.js';
+export type { InstallationUnknownReason } from './registry/index.js';
+/**
+ * `astrale-domain list --json` on stdout: the deployments of the Project's Environments that their
+ * hosts keep for the caller, each with its computed name, the instances known to pin it and where
+ * it is called. It changes nothing, at any host, registry or instance.
+ */
+export interface ListResultV1 {
+    readonly format: 'astrale.deployment-list';
+    readonly version: 1;
+    readonly origin: string;
+    /** Environment by Environment in the Project's order, each in its host's order. */
+    readonly deployments: readonly ListedDeploymentV1[];
+    /**
+     * The selected Environments whose deployments are not in `deployments`, and why: the listing is
+     * complete exactly when this is empty.
+     */
+    readonly unlisted: readonly UnlistedEnvironmentV1[];
+    /** Where every `installedOn` comes from, and what of it is unknown (AM-198). */
+    readonly installations: InstallationSourcesV1;
+}
+/**
+ * One deployment: what its host knows (`DeploymentSummaryV1`), the Environment it was listed for
+ * and its adapter, its computed name, and its call target. `lastCallAt` and a preview's `expiresAt`
+ * are as of the listing: a platform namespace (adapter-cloudflare) reads every call from its calls
+ * dataset, and omits both without Account Analytics Read. Admin's Services (adapter-astrale) keeps
+ * every deployment until it is retired and counts no call: its rows are `published`, with neither
+ * clock, and say whether their Service serves them (`current`).
+ */
+export type ListedDeploymentV1 = Omit<DeploymentSummaryV1, 'record'> & {
+    /** The Project Environment whose line holds the deployment, as its host listed it. */
+    readonly environment: string;
+    /** `<adapter name>@<adapter version>` */
+    readonly adapter: string;
+    /**
+     * The deployment's name (`deploymentName`, CT28), computed and never stored: the version of the
+     * registry that names its release (`1.5.0`), or its build elsewhere (`1.5.0 · staging`), else
+     * from its record's commit (`1.4.2 + 7 commits · a1b2c3d · staging`). Print it as it is,
+     * environment included (AM-57).
+     */
+    readonly name: string;
+    /**
+     * The instances known to pin this deployment: those `--instance` asked, as their Kernels list
+     * them (CT24). Partial by nature: an instance is known only when asked, and one whose
+     * installations are unknown is under `installations`, never absent from here as "not installed"
+     * (AM-198).
+     */
+    readonly installedOn: readonly InstalledOnV1[];
+    /**
+     * The record its deployer declared, as `acceptDeploymentRecord` admits it. `null` when there is
+     * no admitted record: the host returns a record this SDK refuses or one that describes another
+     * deployment, or keeps none (the adapter lists it without a record, as a platform namespace lists
+     * a deployment it has not activated). The deployment is then listed from what its host knows, and
+     * named in the listed Environment, from the commit of that record only when the record names this
+     * deployment, origin and Environment.
+     */
+    readonly record: DeploymentRecordV1 | null;
+    /**
+     * Why there is no admitted record: the refusal of the stored one, or that its host keeps none;
+     * present exactly when `record` is `null`.
+     */
+    readonly recordRefusal?: string;
+    /**
+     * Whether the stable URL of the deployment's Service serves it; present only for a host with
+     * Services (Admin's Services).
+     */
+    readonly current?: boolean;
+    /** Where to call this deployment, and on Admin's Services its Service. */
+    readonly callTarget: DeploymentCallTarget;
+};
+/**
+ * An Environment the listing did not list:
+ * - `legacy-direct`: it replaces one stable target in place and makes no immutable deployment;
+ * - `refused`: `deploy` refuses its configuration, so it deploys nothing;
+ * - `unsupported`: its adapter deploys immutable deployments but lists none.
+ */
+export interface UnlistedEnvironmentV1 {
+    readonly environment: string;
+    readonly adapter: string;
+    readonly reason: 'legacy-direct' | 'refused' | 'unsupported';
+}
+/** What a listing found, beside the result: what to tell a person, and what failed. */
+export interface DeploymentListing {
+    readonly result: ListResultV1;
+    /**
+     * One line for each Environment not listed, each record not admitted and each source of
+     * INSTALLED ON that could not tell, for stderr.
+     */
+    readonly notices: readonly string[];
+    /** Environments whose host could not be listed: their deployments are missing from the result. */
+    readonly failures: readonly {
+        readonly environment: string;
+        readonly adapter: string;
+        readonly error: Error;
+    }[];
+    /**
+     * The Domain registry could not be read, so no deployment can be named by its version and the
+     * result is not to be printed: versions are never dropped silently (AM-224). That is a missing
+     * Astrale CLI, one older than the listing's floor, no identity it may use, an Admin it cannot
+     * reach, an index it cannot read, or an interruption while it reads; never a source of
+     * INSTALLED ON, which only makes the listing partial.
+     */
+    readonly registryFailure?: Error;
+}
+/** What the listing reads through the Astrale CLI: the registry index and the instances. */
+export type DeploymentRegistry = Pick<DomainRegistry, 'index' | 'instance'>;
+/**
+ * List the deployments of the selected Environments, one adapter `list` call each, then name them
+ * and say where they are installed (tech [.59528]: the records, the registry's versions and the
+ * instances' pins).
+ *
+ * Only an Environment that deploys immutable deployments (CT33 canonical) is listed; the others are
+ * `unlisted`, with the reason. A record the host returns but `acceptDeploymentRecord` refuses never
+ * fails the listing: that deployment is listed from what its host knows, its record `null`. This
+ * covers a host whose SDK still admits a record this SDK refuses, and a host that lists a record
+ * its own SDK no longer admits as it is stored (Admin's Services does). An Environment whose host
+ * cannot be listed, or whose adapter answers anything but deployments, is a failure, and the others
+ * are still listed.
+ *
+ * Once a deployment is listed, the registry is opened once: its index of the origin names each
+ * deployment by the version of its release or build (CT28; none when the origin is unregistered or
+ * not readable), and the instances that pin each deployment come from each `--instance` (CT24);
+ * Admin does not say which instances pin a release (AM-241). A registry that cannot be opened or
+ * whose index cannot be read is `registryFailure`, and the instance reads still running are
+ * stopped at once; an instance that cannot tell never fails the listing: it is partial (AM-198,
+ * AM-224).
+ */
+export declare function listDeployments(input: {
+    readonly origin: string;
+    /** The selected Environments, in the Project's order. */
+    readonly environments: readonly (readonly [string, LoadedEnvironment])[];
+    readonly identity?: string;
+    readonly signal: AbortSignal;
+    /**
+     * Opens the Domain registry, once, and only when at least one deployment is listed. Every read
+     * it makes follows `signal`, which also stops when the index cannot be read.
+     */
+    readonly registry: (signal: AbortSignal) => Promise<DeploymentRegistry>;
+    /** Instances to ask what they run (`--instance`, repeatable). */
+    readonly instances?: readonly string[];
+}): Promise<DeploymentListing>;
+/**
+ * The listing as a table for a person, at `now`: each deployment's release, its name as computed
+ * (never shortened, AM-57), its Environment and state (`active (current)` for the deployment its
+ * Service serves), the instances known to pin it (`?` when a source could not tell, AM-198), its
+ * last call and its expiry, and the URL `astrale domain install` takes. Without deployments, it says so only for what was listed: nothing when a host
+ * `failed` (stderr says which), and that some Environments were not listed when any was not.
+ */
+export declare function renderDeploymentList(result: ListResultV1, now: number, failed?: boolean): readonly string[];

package/dist/tooling/cli/list.js

@@ -0,0 +1,381 @@
+import { acceptDeploymentRecord } from '../../deployment/address/index.js';
+import { deploymentName } from '../../platform/versioning/name.js';
+import { selectDeployMode } from './deploy-mode.js';
+import { installationNotices, installedOn, installedOnCell, readInstallations, skippedInstallations, } from './installed-on.js';
+/**
+ * List the deployments of the selected Environments, one adapter `list` call each, then name them
+ * and say where they are installed (tech [.59528]: the records, the registry's versions and the
+ * instances' pins).
+ *
+ * Only an Environment that deploys immutable deployments (CT33 canonical) is listed; the others are
+ * `unlisted`, with the reason. A record the host returns but `acceptDeploymentRecord` refuses never
+ * fails the listing: that deployment is listed from what its host knows, its record `null`. This
+ * covers a host whose SDK still admits a record this SDK refuses, and a host that lists a record
+ * its own SDK no longer admits as it is stored (Admin's Services does). An Environment whose host
+ * cannot be listed, or whose adapter answers anything but deployments, is a failure, and the others
+ * are still listed.
+ *
+ * Once a deployment is listed, the registry is opened once: its index of the origin names each
+ * deployment by the version of its release or build (CT28; none when the origin is unregistered or
+ * not readable), and the instances that pin each deployment come from each `--instance` (CT24);
+ * Admin does not say which instances pin a release (AM-241). A registry that cannot be opened or
+ * whose index cannot be read is `registryFailure`, and the instance reads still running are
+ * stopped at once; an instance that cannot tell never fails the listing: it is partial (AM-198,
+ * AM-224).
+ */
+export async function listDeployments(input) {
+    const hosted = [];
+    const unlisted = [];
+    const notices = [];
+    const failures = [];
+    for (const [environment, definition] of input.environments) {
+        const { adapter, parameters } = definition.deployment;
+        const name = `${adapter.name}@${adapter.version}`;
+        const mode = selectDeployMode({ command: 'deploy', environment, definition });
+        if (mode.kind !== 'canonical') {
+            unlisted.push(Object.freeze({
+                environment,
+                adapter: name,
+                reason: mode.kind,
+            }));
+            notices.push(mode.kind === 'legacy-direct'
+                ? `Environment ${environment} is not listed: it deploys in legacy direct mode, replacing ` +
+                    'one stable target in place, and has no immutable deployments.'
+                : `Environment ${environment} is not listed: deploy refuses its configuration. ` +
+                    mode.refusals.map((refusal) => refusal.guidance).join(' '));
+            continue;
+        }
+        if (!('list' in adapter) || typeof adapter.list !== 'function') {
+            unlisted.push(Object.freeze({ environment, adapter: name, reason: 'unsupported' }));
+            notices.push(`Environment ${environment} is not listed: adapter ${name} lists no deployments.`);
+            continue;
+        }
+        let listed;
+        try {
+            listed = await adapter.list(parameters, {
+                origin: input.origin,
+                environment,
+                signal: input.signal,
+                ...(input.identity === undefined ? {} : { identity: input.identity }),
+            });
+            if (!Array.isArray(listed)) {
+                throw new TypeError(`Adapter ${name} listed no array of deployments.`);
+            }
+            for (const deployment of listed)
+                admitListed(deployment, name);
+        }
+        catch (cause) {
+            failures.push(Object.freeze({
+                environment,
+                adapter: name,
+                error: cause instanceof Error ? cause : new Error(String(cause)),
+            }));
+            continue;
+        }
+        for (const deployment of listed) {
+            const row = hostedDeployment(deployment, { origin: input.origin, environment, adapter: name });
+            if (row.recordRefusal !== undefined) {
+                notices.push(deployment.record === undefined
+                    ? `Deployment ${deployment.label} (${environment}) is listed from what its host knows: ` +
+                        `${row.recordRefusal}`
+                    : `Deployment ${deployment.label} (${environment}) is listed from what its host knows: its ` +
+                        `stored record is not admitted. ${row.recordRefusal}`);
+            }
+            hosted.push(row);
+        }
+    }
+    let publications = [];
+    let installations = skippedInstallations(input.instances ?? []);
+    let registryFailure;
+    if (hosted.length > 0) {
+        // One signal for every registry read, so that an unreadable index stops the others.
+        const reads = new AbortController();
+        const interrupt = () => reads.abort(input.signal.reason);
+        if (input.signal.aborted)
+            interrupt();
+        else
+            input.signal.addEventListener('abort', interrupt, { once: true });
+        try {
+            const registry = await input.registry(reads.signal);
+            // The index and every `--instance` are read together; the latter fail only when the reads
+            // are stopped, which is handled where they are awaited below.
+            const read = readInstallations(registry, input.origin, input.instances ?? [], reads.signal);
+            read.catch(() => undefined);
+            try {
+                publications = (await registry.index(input.origin))?.publications ?? [];
+            }
+            catch (cause) {
+                // Nothing is printed without the versions: stop the CLI processes still asking instances
+                // what they run, and wait only for them to end.
+                reads.abort(cause);
+                await read.catch(() => undefined);
+                throw cause;
+            }
+            installations = await read;
+        }
+        catch (cause) {
+            registryFailure = cause instanceof Error ? cause : new Error(String(cause));
+        }
+        finally {
+            input.signal.removeEventListener('abort', interrupt);
+        }
+    }
+    // INSTALLED ON is reported only for rows the listing prints.
+    if (hosted.length > 0 && registryFailure === undefined) {
+        notices.push(...installationNotices(installations.sources));
+    }
+    return Object.freeze({
+        result: Object.freeze({
+            format: 'astrale.deployment-list',
+            version: 1,
+            origin: input.origin,
+            deployments: Object.freeze(hosted.map((row) => listedDeployment(row, publications, installations))),
+            unlisted: Object.freeze(unlisted),
+            installations: installations.sources,
+        }),
+        notices: Object.freeze(notices),
+        failures: Object.freeze(failures),
+        ...(registryFailure === undefined ? {} : { registryFailure }),
+    });
+}
+/**
+ * One listed deployment's record, admitted when it describes exactly this deployment of this
+ * origin and Environment, else refused with why, or none when its host keeps none (`NO_RECORD`).
+ */
+function hostedDeployment(deployment, listing) {
+    if (deployment.record === undefined) {
+        return { deployment, listing, record: null, recordRefusal: NO_RECORD };
+    }
+    try {
+        const admitted = acceptDeploymentRecord(deployment.record);
+        const recordRefusal = describesAnother(admitted, deployment.label, listing);
+        return recordRefusal === undefined
+            ? { deployment, listing, record: admitted }
+            : { deployment, listing, record: null, recordRefusal };
+    }
+    catch (cause) {
+        return {
+            deployment,
+            listing,
+            record: null,
+            recordRefusal: cause instanceof Error ? cause.message : String(cause),
+        };
+    }
+}
+/**
+ * One listed deployment, named and placed. With an admitted record, its name comes from the
+ * registry's Publications of the origin that name its release, else its build, else from its
+ * record (CT28). Otherwise it is named in the listed Environment, with the commit of the stored
+ * record only when that record names this deployment, origin and Environment, and never by a
+ * version: a record the listing does not admit gives no digest to name.
+ */
+function listedDeployment(hosted, publications, installations) {
+    const { deployment, listing, record, recordRefusal } = hosted;
+    // A build digest names the row from any Publication of the origin, whatever its URL: the row is
+    // a deployment its own host lists for the caller, and the build of a version deployed elsewhere
+    // is another deployment at another URL (`1.5.0 · staging`, tech [.83533]). An instance's pin,
+    // which a frozen Worker's tenant may serve, is named only within its issuer (AM-73, AM-224).
+    const name = record === null
+        ? deploymentName(canonicalParts(deployment.record, deployment.label, listing), [])
+        : deploymentName(record, publications);
+    return Object.freeze({
+        environment: listing.environment,
+        adapter: listing.adapter,
+        name,
+        installedOn: installedOn(deployment.url, installations),
+        id: deployment.id,
+        url: deployment.url,
+        label: deployment.label,
+        line: deployment.line,
+        owner: deployment.owner,
+        state: deployment.state,
+        retention: deployment.retention,
+        createdAt: deployment.createdAt,
+        ...(deployment.lastCallAt === undefined ? {} : { lastCallAt: deployment.lastCallAt }),
+        ...(deployment.expiresAt === undefined ? {} : { expiresAt: deployment.expiresAt }),
+        ...(deployment.retiredAt === undefined ? {} : { retiredAt: deployment.retiredAt }),
+        ...(deployment.retirement === undefined ? {} : { retirement: deployment.retirement }),
+        signingKeyId: deployment.signingKeyId,
+        record,
+        ...(recordRefusal === undefined ? {} : { recordRefusal }),
+        ...(deployment.current === undefined ? {} : { current: deployment.current }),
+        callTarget: deployment.callTarget,
+    });
+}
+/**
+ * Why a deployment its host keeps no record of has none: the adapter lists it without `record`, as a
+ * platform namespace lists a deployment it has not activated.
+ */
+const NO_RECORD = 'Its host keeps no record of it: it has not been activated (a deploy still in progress, or one ' +
+    'that stopped before activating it).';
+/** Why an admitted record does not describe the listed deployment, if it does not. */
+function describesAnother(record, label, listing) {
+    if (record.providerScript !== label) {
+        return `Deployment record describes deployment ${record.providerScript}, not ${label}.`;
+    }
+    if (record.origin !== listing.origin) {
+        return `Deployment record declares origin ${record.origin}, not ${listing.origin}.`;
+    }
+    if (record.environment !== listing.environment) {
+        return `Deployment record declares environment ${record.environment}, not ${listing.environment}.`;
+    }
+    return undefined;
+}
+/**
+ * What a deployment name may read of a stored record that is not admitted: the listed Environment,
+ * never the record's own, and the record's commit only when the record names this deployment, its
+ * origin and that Environment, each part kept only with the type the name reads. No digest: a
+ * record the listing does not admit is never named by a published version.
+ */
+function canonicalParts(input, label, listing) {
+    const value = members(input);
+    // A record that does not say it describes this deployment says nothing of it, not its commit.
+    const describesThis = value?.providerScript === label &&
+        value.origin === listing.origin &&
+        value.environment === listing.environment;
+    const commit = describesThis ? members(value.commit) : undefined;
+    const base = members(commit?.base);
+    return {
+        environment: listing.environment,
+        commit: typeof commit?.sha === 'string'
+            ? {
+                sha: commit.sha,
+                dirty: commit.dirty === true,
+                ...(typeof base?.version === 'string' && typeof base.distance === 'number'
+                    ? { base: { version: base.version, distance: base.distance } }
+                    : {}),
+            }
+            : null,
+    };
+}
+const STATES = ['deploying', 'active', 'retiring', 'retired', 'failed'];
+/**
+ * Admit one deployment an adapter listed, before any is kept: the facts a row prints, each of the
+ * type `DeploymentSummaryV1` gives it, and a call target an operator can act on. Anything else is
+ * that Environment's failure, never a row without its call target.
+ */
+function admitListed(deployment, adapter) {
+    const invalid = (member) => {
+        throw new TypeError(`Adapter ${adapter} listed an invalid deployment (${member}).`);
+    };
+    const value = members(deployment) ?? invalid('deployment');
+    for (const key of ['id', 'url', 'label', 'line', 'owner', 'createdAt', 'signingKeyId']) {
+        if (!text(value[key]))
+            invalid(key);
+    }
+    for (const key of ['lastCallAt', 'expiresAt', 'retiredAt']) {
+        if (value[key] !== undefined && !text(value[key]))
+            invalid(key);
+    }
+    if (!STATES.includes(value.state))
+        invalid('state');
+    if (value.retention !== 'preview' && value.retention !== 'published')
+        invalid('retention');
+    if (value.retirement !== undefined &&
+        value.retirement !== 'expired' &&
+        value.retirement !== 'withdrawn') {
+        invalid('retirement');
+    }
+    if (value.current !== undefined && typeof value.current !== 'boolean')
+        invalid('current');
+    const target = members(value.callTarget) ?? invalid('callTarget');
+    if (target.kind === 'services') {
+        if (!text(target.path) ||
+            !text(target.service) ||
+            (target.admin !== undefined && !text(target.admin))) {
+            invalid('callTarget');
+        }
+    }
+    else if (target.kind !== 'namespace' || !text(target.namespace) || !text(target.script)) {
+        invalid('callTarget');
+    }
+}
+function text(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+function members(input) {
+    return input !== null && typeof input === 'object' && !Array.isArray(input)
+        ? input
+        : undefined;
+}
+const COLUMNS = [
+    'RELEASE',
+    'VERSION',
+    'ENV',
+    'STATE',
+    'INSTALLED ON',
+    'LAST CALL',
+    'EXPIRES',
+    'URL',
+];
+const MINUTE = 60_000;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+/**
+ * The listing as a table for a person, at `now`: each deployment's release, its name as computed
+ * (never shortened, AM-57), its Environment and state (`active (current)` for the deployment its
+ * Service serves), the instances known to pin it (`?` when a source could not tell, AM-198), its
+ * last call and its expiry, and the URL `astrale domain install` takes. Without deployments, it says so only for what was listed: nothing when a host
+ * `failed` (stderr says which), and that some Environments were not listed when any was not.
+ */
+export function renderDeploymentList(result, now, failed = false) {
+    if (result.deployments.length === 0) {
+        if (failed)
+            return Object.freeze([]);
+        return Object.freeze([
+            result.unlisted.length === 0
+                ? `No deployments of ${result.origin}.`
+                : `No deployments of ${result.origin} in the Environments listed; ` +
+                    `${result.unlisted.length} not listed (see above).`,
+        ]);
+    }
+    const rows = result.deployments.map((deployment) => [
+        deployment.record === null ? '?' : shortDigest(deployment.record.releaseDigest),
+        deployment.name,
+        deployment.environment,
+        deployment.current === true ? `${deployment.state} (current)` : deployment.state,
+        installedOnCell(deployment.installedOn, result.installations),
+        deployment.lastCallAt === undefined
+            ? '—'
+            : `${elapsed(now - Date.parse(deployment.lastCallAt))} ago`,
+        expiry(deployment, now),
+        deployment.url,
+    ]);
+    const widths = COLUMNS.map((column, index) => Math.max(column.length, ...rows.map((row) => row[index].length)));
+    const line = (cells) => cells
+        .map((cell, index) => (index === cells.length - 1 ? cell : cell.padEnd(widths[index])))
+        .join('  ');
+    return Object.freeze([line(COLUMNS), ...rows.map(line)]);
+}
+/** `sha256:` and the first seven hexadecimal digits, as git abbreviates a commit. */
+function shortDigest(digest) {
+    return `${digest.slice(0, 'sha256:'.length + 7)}…`;
+}
+/**
+ * When a deployment stops serving: `never` once published, else its preview expiry as its host
+ * keeps it, 30 days after its activation or its last call, whichever is later (AM-123), with the
+ * calls counted since the host recorded them; `due` once that instant passed but the host has not
+ * retired it yet; for a retired deployment, why it was retired.
+ */
+function expiry(deployment, now) {
+    if (deployment.state === 'retiring')
+        return 'retiring';
+    if (deployment.state === 'retired')
+        return deployment.retirement ?? 'retired';
+    if (deployment.retention === 'published')
+        return 'never';
+    if (deployment.expiresAt === undefined)
+        return '—';
+    const remaining = Date.parse(deployment.expiresAt) - now;
+    return remaining > 0 ? `in ${elapsed(remaining)}` : 'due';
+}
+/** A duration as a person reads it in a listing: minutes, then hours, then days. */
+function elapsed(milliseconds) {
+    if (!(milliseconds >= MINUTE))
+        return '< 1 min';
+    if (milliseconds < HOUR)
+        return `${Math.floor(milliseconds / MINUTE)} min`;
+    if (milliseconds < DAY)
+        return `${Math.floor(milliseconds / HOUR)} h`;
+    return `${Math.floor(milliseconds / DAY)} d`;
+}

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

@@ -6,5 +6,10 @@ export declare const YELLOW = "\u001B[33m";
 export declare const RED = "\u001B[31m";
 export declare const RESET = "\u001B[0m";
 export declare function info(msg: string): void;
+/**
+ * Where a command reports its progress: `info` on stdout for a person, the same lines on stderr
+ * when stdout carries one machine-readable document (`--json`).
+ */
+export declare function progress(machine: boolean): (msg: string) => void;
 export declare function warn(msg: string): void;
 export declare function error(msg: string): void;

package/dist/tooling/cli/log.js

@@ -8,6 +8,15 @@ export const RESET = '\x1b[0m';
 export function info(msg) {
     process.stdout.write(`${DIM}›${RESET} ${msg}\n`);
 }
+/**
+ * Where a command reports its progress: `info` on stdout for a person, the same lines on stderr
+ * when stdout carries one machine-readable document (`--json`).
+ */
+export function progress(machine) {
+    if (!machine)
+        return info;
+    return (msg) => process.stderr.write(`${DIM}›${RESET} ${msg}\n`);
+}
 export function warn(msg) {
     process.stderr.write(`${YELLOW}!${RESET} ${msg}\n`);
 }

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>;