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

package/dist/tooling/cli/installation/reconcile.d.ts

@@ -0,0 +1,32 @@
+import type { InstallationTarget } from '../../../deployment/adapter/index.js';
+import type { Release } from '../../../deployment/release/index.js';
+import type { AstraleProcessResult } from '../astrale/process.js';
+export interface InstallationEvidence {
+    readonly status: 'unchanged' | 'installed' | 'upgraded';
+    readonly instance: string;
+    readonly origin: string;
+    readonly issuer: string;
+    readonly revision: string;
+    readonly generation: string;
+    readonly etag: string;
+}
+export type AstraleCommandResult = AstraleProcessResult;
+export interface InstallationDependencies {
+    run(input: {
+        readonly executable: string;
+        readonly args: readonly string[];
+        readonly projectDir: string;
+        readonly signal: AbortSignal;
+        readonly timeoutMs: number;
+    }): Promise<AstraleCommandResult>;
+}
+/** Reconcile one observed Release without ever replacing a different issuer. */
+export declare function reconcileInstallation(input: {
+    readonly projectDir: string;
+    readonly target: InstallationTarget;
+    readonly executable: string;
+    readonly identity?: string;
+    readonly credential?: string;
+    readonly release: Release;
+    readonly signal: AbortSignal;
+}, dependencies?: InstallationDependencies): Promise<InstallationEvidence>;

package/dist/tooling/cli/installation/reconcile.js

@@ -0,0 +1,122 @@
+import { astraleAuthorityArguments } from '../astrale/authority.js';
+import { AstraleCliError, isDomainNotInstalledFailure, astraleFailure } from '../astrale/failure.js';
+import { runAstrale } from '../astrale/process.js';
+import { canonicalIssuer, decodeInstallationObservation } from './observation.js';
+/** Reconcile one observed Release without ever replacing a different issuer. */
+export async function reconcileInstallation(input, dependencies = {
+    run: runAstrale,
+}) {
+    const origin = input.release.publication.origin;
+    const revision = input.release.publication.schema.revision;
+    const issuer = canonicalIssuer(input.release.addressing.issuer);
+    const etag = input.release.publication.etag;
+    const identity = input.identity ?? input.target.identity;
+    const authority = astraleAuthorityArguments({
+        ...(identity === undefined ? {} : { identity }),
+        ...(input.credential === undefined ? {} : { credential: input.credential }),
+    });
+    const executable = input.executable;
+    const before = await observe(input, origin, authority, executable, dependencies);
+    if (before !== undefined) {
+        assertIdentity(before, { origin, issuer });
+        if (before.revision === revision && before.etag === etag) {
+            return evidence('unchanged', input.target.instance, before);
+        }
+    }
+    let installationFailure;
+    try {
+        const installed = await dependencies.run({
+            executable,
+            projectDir: input.projectDir,
+            signal: input.signal,
+            timeoutMs: 250_000,
+            args: [
+                '--ci',
+                '--no-prompt',
+                'domain',
+                'install',
+                input.release.addressing.publicUrl,
+                '--direct',
+                '--allow-identity-override',
+                '-i',
+                input.target.instance,
+                '--json',
+                '--timeout',
+                '240000',
+                ...authority,
+            ],
+        });
+        if (installed.code !== 0)
+            installationFailure = astraleFailure('domain install', installed);
+    }
+    catch (cause) {
+        installationFailure = cause;
+    }
+    let after;
+    try {
+        after = await observe(input, origin, authority, executable, dependencies);
+    }
+    catch (cause) {
+        throw installationError(installationFailure === undefined ? [cause] : [installationFailure, cause], 'Domain installation outcome is unknown because reconciliation failed.');
+    }
+    if (installationFailure !== undefined && after === undefined) {
+        throw installationError([installationFailure], 'Domain installation failed and no installed Release was observed.');
+    }
+    if (after === undefined)
+        throw new TypeError('Installed Domain was absent after installation.');
+    try {
+        assertIdentity(after, { origin, issuer });
+        if (after.revision !== revision || after.etag !== etag) {
+            throw new TypeError('Installed Domain evidence differs from the deployed Release.');
+        }
+    }
+    catch (cause) {
+        if (installationFailure === undefined)
+            throw cause;
+        throw installationError([installationFailure, cause], 'Domain installation failed with a different observed Release.');
+    }
+    return evidence(before === undefined ? 'installed' : 'upgraded', input.target.instance, after);
+}
+function installationError(causes, message) {
+    const diagnostics = causes
+        .filter((cause) => cause instanceof AstraleCliError)
+        .map((cause) => cause.message);
+    return new AggregateError(causes, [message, ...diagnostics].join(' '));
+}
+async function observe(input, origin, authority, executable, dependencies) {
+    const result = await dependencies.run({
+        executable,
+        projectDir: input.projectDir,
+        signal: input.signal,
+        timeoutMs: 70_000,
+        args: [
+            '--ci',
+            '--no-prompt',
+            'introspect',
+            origin,
+            '-i',
+            input.target.instance,
+            '--json',
+            '--timeout',
+            '60000',
+            ...authority,
+        ],
+    });
+    if (result.code !== 0) {
+        if (isDomainNotInstalledFailure(result.stderr))
+            return undefined;
+        throw astraleFailure(`introspect ${origin}`, result);
+    }
+    return decodeInstallationObservation(result.stdout);
+}
+function assertIdentity(observed, expected) {
+    if (observed.origin !== expected.origin) {
+        throw new TypeError('Installed Domain evidence has a different origin.');
+    }
+    if (observed.issuer !== expected.issuer) {
+        throw new TypeError(`Installed Domain issuer ${observed.issuer} differs from deployment issuer ${expected.issuer}; refusing replacement.`);
+    }
+}
+function evidence(status, instance, observed) {
+    return Object.freeze({ status, instance, ...observed });
+}

package/dist/tooling/cli/orchestrate.js

@@ -1,14 +1,17 @@
 import { existsSync } from 'node:fs';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
-import { pathToFileURL } from 'node:url';
-import { admitRuntime, compile, isDeployment, resolveRuntime, verifyDeployment, verifyPreflight, } from '../../deployment/index.js';
+import { admitRuntime, compile, resolveRuntime, verifyDeployment, verifyPreflight, } from '../../deployment/index.js';
 import { packageDomain } from '../packaging/index.js';
 import { parseArgs } from './arguments.js';
+import { resolveCompatibleAstrale } from './astrale/version.js';
 import { BunRequiredError } from './bun.js';
 import { develop } from './development/develop.js';
 import { loadDeclaredSecrets } from './dotenv.js';
+import { reconcileEnvironmentRelease } from './environment-release.js';
 import { ERROR_USAGE, helpRequest, helpText } from './help.js';
 import { error, info } from './log.js';
+import { importModule, loadProject, runtimeEntrypoint, selectEnvironment } from './project.js';
+import { executeTests } from './test.js';
 const CONFIG_NAMES = ['astrale.config.ts', 'astrale.config.js', 'astrale.config.mjs'];
 export async function run(argv) {
     const requestedHelp = helpRequest(argv);
@@ -26,11 +29,23 @@ export async function run(argv) {
     }
     if (parsed.command === 'lint')
         return lint(parsed);
+    if (parsed.command === 'upgrade') {
+        const { upgrade } = await import('./upgrade/index.js');
+        await upgrade({
+            cwd: process.cwd(),
+            channel: parsed.channel ?? 'beta',
+            check: parsed.check ?? false,
+        });
+        return 0;
+    }
     if (parsed.command === 'package') {
         const result = await packageDomain({ projectDir: process.cwd() });
         info(`Packaged ${result.declarations} public declarations (${result.replacements} references normalized).`);
         return 0;
     }
+    if (parsed.command === 'test' && parsed.env === '') {
+        return executeTests(parsed.suite === undefined ? {} : { suite: parsed.suite });
+    }
     if (!process.versions.bun) {
         throw new BunRequiredError();
     }
@@ -43,46 +58,86 @@ export async function run(argv) {
     if (parsed.command === 'dev') {
         return executeDevelopmentCommand(parsed, { configPath, projectDir });
     }
-    const deployment = await loadDeployment(configPath);
-    const adapter = deployment.adapter;
-    const build = compile(deployment.application);
-    const resolved = await resolveRuntime(deployment.entrypoint, (path) => importModule(resolve(dirname(configPath), path)));
+    const project = await loadProject(configPath);
+    if (parsed.command === 'test') {
+        selectEnvironment(project, parsed.env);
+        return executeTests({
+            environment: parsed.env,
+            ...(parsed.suite === undefined ? {} : { suite: parsed.suite }),
+        });
+    }
+    const build = compile(project.application);
+    const resolved = await resolveRuntime(runtimeEntrypoint(project), (path) => importModule(resolve(dirname(configPath), path)));
     admitRuntime({ runtime: build.runtime }, resolved);
-    const parameters = adapter.parameters(parsed.env);
-    const source = await adapter.prepare(parameters, {
-        projectDir,
-        environment: parsed.env,
-        mode: 'release',
-        build,
-        runtime: resolved,
-    });
-    const artifact = verifyPreflight({ build, runtime: resolved, source });
     if (parsed.command === 'build') {
-        info(`Built ${build.schema.compiled.root.origin} (${artifact.digest}).`);
+        info(`Built ${build.schema.compiled.root.origin} (${build.schema.compiled.root.revision}).`);
         return 0;
     }
-    const secrets = secretsFor(adapter, parameters, projectDir, resolved.runtime);
+    const environment = selectEnvironment(project, parsed.env);
+    const adapter = environment.deployment.adapter;
+    const parameters = environment.deployment.parameters;
     const lifecycle = deploymentLifecycle();
-    let deployed;
     try {
-        deployed = await adapter.deploy(parameters, {
+        const source = await adapter.prepare(parameters, {
+            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,
         });
+        const result = verifyDeployment(artifact, deployed);
+        if (result.status === 'failed') {
+            error(`Deployment failed during ${result.phase}: ${result.error.message}`);
+            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 }),
+            ...(parsed.identity === undefined ? {} : { identity: parsed.identity }),
+            signal: lifecycle.signal,
+        });
+        if (installed === undefined) {
+            info('Installation: skipped');
+        }
+        else {
+            info(`Installation: ${installed.instance} · ${installed.status}`);
+        }
+        info('Ready: deployment verified');
+        return 0;
     }
     finally {
         lifecycle.dispose();
     }
-    const result = verifyDeployment(artifact, deployed);
-    if (result.status === 'failed') {
-        error(`Deployment failed during ${result.phase}: ${result.error.message}`);
-        return 1;
-    }
-    info(`Ready: ${result.release.addressing.issuer}`);
-    return 0;
 }
 export function executeDevelopmentCommand(parsed, input, execute = develop) {
     if (parsed.command !== 'dev')
@@ -91,11 +146,9 @@ export function executeDevelopmentCommand(parsed, input, execute = develop) {
         configPath: input.configPath,
         projectDir: input.projectDir,
         environment: parsed.env,
-        overrides: Object.freeze({
-            ...(parsed.host === undefined ? {} : { publicUrl: parsed.host }),
-            ...(parsed.port === undefined ? {} : { localPort: parsed.port }),
-            ...(parsed.credentialFile === undefined ? {} : { credentialFile: parsed.credentialFile }),
-        }),
+        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 }),
     });
@@ -131,19 +184,6 @@ function secretsFor(adapter, parameters, projectDir, runtime) {
     }
     return Object.freeze(loadDeclaredSecrets(path, file));
 }
-async function loadDeployment(path) {
-    const loaded = (await importModule(path));
-    if (Object.keys(loaded).length !== 1 || !Object.hasOwn(loaded, 'default')) {
-        throw new TypeError('astrale.config.ts must export exactly one default Deployment.');
-    }
-    const deployment = loaded.default;
-    if (!isDeployment(deployment))
-        throw new TypeError('Default export must be created by deploy().');
-    return deployment;
-}
-function importModule(path) {
-    return import(`${pathToFileURL(path).href}?sdk=${Date.now()}`);
-}
 function findConfig(projectDir) {
     return CONFIG_NAMES.map((name) => join(projectDir, name)).find(existsSync);
 }

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

@@ -0,0 +1,17 @@
+import type { Application } 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';
+import type { Frontend } from '../../application/view/index.js';
+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 LoadedDeployment = Deployment<object>;
+export type LoadedEnvironment = ProjectEnvironment<LoadedDeployment>;
+export type LoadedProject = Project<LoadedApplication, 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;
+export declare function importModule(path: string): Promise<unknown>;

package/dist/tooling/cli/project.js

@@ -0,0 +1,18 @@
+import { pathToFileURL } from 'node:url';
+import { runtime } from '../../deployment/index.js';
+import { admitProjectModule } from '../../project/index.js';
+export async function loadProject(path) {
+    return admitProjectModule(await importModule(path));
+}
+export function selectEnvironment(project, name) {
+    if (Object.hasOwn(project.environments, name))
+        return project.environments[name];
+    const known = Object.keys(project.environments).sort();
+    throw new TypeError(`Project has no Environment ${name}; known Environments: ${known.join(', ') || '(none)'}.`);
+}
+export function runtimeEntrypoint(project) {
+    return runtime(project.entrypoints?.runtime ?? './runtime.ts');
+}
+export function importModule(path) {
+    return import(`${pathToFileURL(path).href}?sdk=${Date.now()}`);
+}

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

@@ -0,0 +1,12 @@
+import { spawn } from 'node:child_process';
+export interface TestExecution {
+    readonly environment?: string;
+    readonly suite?: string;
+}
+interface TestRunner {
+    readonly executable: string;
+    readonly arguments: readonly string[];
+}
+/** Run the Project's ordinary test runner, optionally targeting one observed Environment. */
+export declare function executeTests(input: TestExecution, start?: typeof spawn, runner?: TestRunner): Promise<number>;
+export {};

package/dist/tooling/cli/test.js

@@ -0,0 +1,47 @@
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+/** Run the Project's ordinary test runner, optionally targeting one observed Environment. */
+export function executeTests(input, start = spawn, runner = projectVitest()) {
+    const arguments_ = ['run', '--config', 'vitest.config.ts'];
+    if (input.suite !== undefined)
+        arguments_.push('--project', input.suite);
+    const environment = { ...process.env };
+    if (input.environment === undefined)
+        delete environment.ASTRALE_PROJECT_ENVIRONMENT;
+    else
+        environment.ASTRALE_PROJECT_ENVIRONMENT = input.environment;
+    return new Promise((resolve, reject) => {
+        const child = start(runner.executable, [...runner.arguments, ...arguments_], {
+            stdio: 'inherit',
+            env: environment,
+        });
+        child.once('error', reject);
+        child.once('close', (code, signal) => {
+            if (signal !== null) {
+                reject(new Error(`Project tests stopped by ${signal}.`));
+            }
+            else {
+                resolve(code ?? 1);
+            }
+        });
+    });
+}
+function projectVitest() {
+    const projectRequire = createRequire(join(process.cwd(), 'package.json'));
+    const manifestPath = projectRequire.resolve('vitest/package.json');
+    const manifest = projectRequire(manifestPath);
+    const relative = typeof manifest.bin === 'string' ? manifest.bin : manifest.bin?.vitest;
+    if (relative === undefined ||
+        relative.length === 0 ||
+        isAbsolute(relative) ||
+        relative.split(/[\\/]/u).includes('..')) {
+        throw new TypeError('Project Vitest package has no contained executable.');
+    }
+    return Object.freeze({
+        executable: process.versions.bun === undefined
+            ? process.execPath
+            : (process.env.npm_node_execpath ?? 'node'),
+        arguments: Object.freeze([resolve(dirname(manifestPath), relative)]),
+    });
+}

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

@@ -0,0 +1,6 @@
+export interface UpgradeOptions {
+    readonly cwd: string;
+    readonly channel: string;
+    readonly check: boolean;
+}
+export declare function upgrade(options: UpgradeOptions): Promise<void>;

package/dist/tooling/cli/upgrade/index.js

@@ -0,0 +1,115 @@
+import { existsSync } from 'node:fs';
+import { readFile, realpath, writeFile } from 'node:fs/promises';
+import { isAbsolute, join, relative } from 'node:path';
+import { failureMessage } from '../failure.js';
+import { projectRoot, readManifest, record, registryDependency, updatedManifest, } from './manifest.js';
+import { runPnpm } from './process.js';
+export async function upgrade(options) {
+    const root = await realpath(projectRoot(options.cwd));
+    const rootManifest = await readManifest(root);
+    const rootValue = JSON.parse(rootManifest.source);
+    const manager = record(rootValue) ? rootValue.packageManager : undefined;
+    if (manager !== undefined
+        ? typeof manager !== 'string' || !manager.startsWith('pnpm@')
+        : !existsSync(join(root, 'pnpm-workspace.yaml')) && !existsSync(join(root, 'pnpm-lock.yaml'))) {
+        throw new Error('Upgrade currently supports pnpm projects only. Declare packageManager: "pnpm@<version>" in package.json.');
+    }
+    const directories = new Set([root]);
+    if (existsSync(join(root, 'pnpm-workspace.yaml'))) {
+        const inventory = JSON.parse(await runPnpm(root, [
+            '--recursive',
+            '--include-workspace-root',
+            'list',
+            '--depth',
+            '-1',
+            '--json',
+        ]));
+        if (!Array.isArray(inventory))
+            throw new Error('Invalid pnpm workspace inventory.');
+        for (const entry of inventory) {
+            if (!record(entry) || typeof entry.path !== 'string' || !isAbsolute(entry.path))
+                throw new Error('Invalid pnpm workspace path.');
+            const directory = await realpath(entry.path);
+            const offset = relative(root, directory);
+            if (offset === '..' ||
+                offset.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`) ||
+                isAbsolute(offset)) {
+                throw new Error(`Workspace package is outside ${root}: ${entry.path}.`);
+            }
+            directories.add(directory);
+        }
+    }
+    const manifests = await Promise.all([...directories].sort().map(readManifest));
+    const names = new Set();
+    const skipped = new Set();
+    for (const manifest of manifests) {
+        for (const dependency of manifest.dependencies) {
+            if (registryDependency(dependency.value))
+                names.add(dependency.name);
+            else
+                skipped.add(`${dependency.name}: ${dependency.value} (left unchanged)`);
+        }
+    }
+    const versions = new Map();
+    const queue = [...names].sort();
+    // Resolve the complete plan before writing. Each package's tag is observed once.
+    for (let offset = 0; offset < queue.length; offset += 4) {
+        await Promise.all(queue.slice(offset, offset + 4).map(async (name) => {
+            const tags = JSON.parse(await runPnpm(root, ['view', name, 'dist-tags', '--json']));
+            if (!record(tags))
+                throw new Error(`Invalid registry dist-tags for ${name}.`);
+            const version = tags[options.channel];
+            if (version === undefined)
+                skipped.add(`${name}: no ${options.channel} tag (left unchanged)`);
+            else if (typeof version !== 'string' ||
+                !/^\d+\.\d+\.\d+(?:-[\w.-]+)?(?:\+[\w.-]+)?$/u.test(version)) {
+                throw new Error(`Invalid ${options.channel} version for ${name}.`);
+            }
+            else
+                versions.set(name, version);
+        }));
+    }
+    process.stdout.write(`Astrale upgrade · ${options.channel}\nWorkspace: ${root}\n`);
+    for (const warning of [...skipped].sort())
+        process.stdout.write(`Skipped: ${warning}\n`);
+    const changes = manifests
+        .map((manifest) => ({ manifest, source: updatedManifest(manifest, versions) }))
+        .filter(({ manifest, source }) => manifest.source !== source);
+    for (const { manifest } of changes) {
+        for (const dependency of manifest.dependencies) {
+            const next = registryDependency(dependency.value) ? versions.get(dependency.name) : undefined;
+            if (next !== undefined && next !== dependency.value)
+                process.stdout.write(`${relative(root, manifest.path)} · ${dependency.name}: ${dependency.value} → ${next}\n`);
+        }
+    }
+    if (changes.length === 0) {
+        process.stdout.write('No dependency changes.\n');
+    }
+    if (options.check) {
+        process.stdout.write('Check only: no project files changed; nothing installed.\n');
+        return;
+    }
+    if (versions.size === 0) {
+        process.stdout.write('No matching registry versions; nothing installed.\n');
+        return;
+    }
+    for (const { manifest } of changes) {
+        if ((await readFile(manifest.path, 'utf8')) !== manifest.source)
+            throw new Error(`Manifest changed during upgrade: ${manifest.path}. Retry against the current files.`);
+    }
+    for (const { manifest, source } of changes)
+        await writeFile(manifest.path, source);
+    try {
+        await runPnpm(root, ['install', '--no-frozen-lockfile'], true);
+    }
+    catch (cause) {
+        throw new Error(`${failureMessage(cause)}\nDependency installation failed. Local changes remain; repair and run pnpm install. Nothing committed or deployed.`, { cause });
+    }
+    process.stdout.write("Dependencies installed. Run your project's typecheck, lint, tests, and build before deploying. Nothing committed or deployed.\n");
+    if (changes.some(({ manifest }) => manifest.dependencies.some(({ name, value }) => name === '@astrale-domains/shell' &&
+        registryDependency(value) &&
+        versions.has(name) &&
+        versions.get(name) !== value))) {
+        process.stdout.write('Shell changed: verify the installed Shell revision before deploying dependent Domains.\n');
+    }
+}

package/dist/tooling/cli/upgrade/manifest.d.ts

@@ -0,0 +1,18 @@
+export interface Dependency {
+    readonly name: string;
+    readonly value: string;
+    readonly start: number;
+    readonly end: number;
+}
+export interface Manifest {
+    readonly path: string;
+    readonly source: string;
+    readonly dependencies: readonly Dependency[];
+}
+export declare function record(value: unknown): value is Record<string, unknown>;
+/** Find a declared workspace without escaping an enclosing repository. */
+export declare function projectRoot(cwd: string): string;
+export declare function readManifest(directory: string): Promise<Manifest>;
+export declare function registryDependency(value: string): boolean;
+/** Replace only dependency value tokens; preserve formatting and all unrelated content. */
+export declare function updatedManifest(manifest: Manifest, versions: ReadonlyMap<string, string>): string;

package/dist/tooling/cli/upgrade/manifest.js

@@ -0,0 +1,77 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import ts from 'typescript';
+const SECTIONS = new Set(['dependencies', 'devDependencies', 'optionalDependencies']);
+export function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/** Find a declared workspace without escaping an enclosing repository. */
+export function projectRoot(cwd) {
+    let directory = resolve(cwd);
+    let nearest;
+    for (;;) {
+        if (existsSync(join(directory, 'pnpm-workspace.yaml')))
+            return directory;
+        if (nearest === undefined && existsSync(join(directory, 'package.json')))
+            nearest = directory;
+        if (existsSync(join(directory, '.git')) || dirname(directory) === directory)
+            break;
+        directory = dirname(directory);
+    }
+    if (nearest === undefined)
+        throw new Error(`No package.json found from ${cwd}.`);
+    return nearest;
+}
+export async function readManifest(directory) {
+    const path = join(directory, 'package.json');
+    const source = await readFile(path, 'utf8');
+    const value = JSON.parse(source);
+    if (!record(value))
+        throw new Error(`Invalid package manifest: ${path}.`);
+    const tree = ts.parseJsonText(path, source);
+    const statement = tree.statements[0];
+    if (!statement ||
+        !ts.isExpressionStatement(statement) ||
+        !ts.isObjectLiteralExpression(statement.expression)) {
+        throw new Error(`Invalid package manifest: ${path}.`);
+    }
+    const dependencies = [];
+    for (const section of statement.expression.properties) {
+        if (!ts.isPropertyAssignment(section) || !SECTIONS.has(section.name.getText(tree).slice(1, -1)))
+            continue;
+        if (!ts.isObjectLiteralExpression(section.initializer))
+            throw new Error(`Invalid dependency section in ${path}.`);
+        for (const property of section.initializer.properties) {
+            if (!ts.isPropertyAssignment(property) || !ts.isStringLiteral(property.name))
+                continue;
+            const name = property.name.text;
+            if (!name.startsWith('@astrale-os/') && !name.startsWith('@astrale-domains/'))
+                continue;
+            if (!ts.isStringLiteral(property.initializer))
+                throw new Error(`Invalid dependency ${name} in ${path}.`);
+            dependencies.push({
+                name,
+                value: property.initializer.text,
+                start: property.initializer.getStart(tree),
+                end: property.initializer.end,
+            });
+        }
+    }
+    return { path, source, dependencies };
+}
+export function registryDependency(value) {
+    return value.length > 0 && !/[:/\\#]/u.test(value) && !value.endsWith('.tgz');
+}
+/** Replace only dependency value tokens; preserve formatting and all unrelated content. */
+export function updatedManifest(manifest, versions) {
+    let result = manifest.source;
+    for (const dependency of [...manifest.dependencies].reverse()) {
+        const version = registryDependency(dependency.value) ? versions.get(dependency.name) : undefined;
+        if (version !== undefined && version !== dependency.value) {
+            result =
+                result.slice(0, dependency.start) + JSON.stringify(version) + result.slice(dependency.end);
+        }
+    }
+    return result;
+}

package/dist/tooling/cli/upgrade/process.d.ts

@@ -0,0 +1,2 @@
+/** pnpm owns registry configuration, installation policy, and lockfile resolution. */
+export declare function runPnpm(cwd: string, args: readonly string[], install?: boolean): Promise<string>;