@astrale-os/sdk 0.5.0-beta.132 → 0.5.0-beta.134

package/README.md

@@ -31,6 +31,21 @@ npx -y create-astrale-domain@beta my-domain --yes
 See [the release lifecycle](docs/release.md) for package-set versioning, verification, and stable
 promotion.
 
+### Update a pnpm project
+
+```sh
+pnpm exec astrale-domain upgrade --check  # Preview; no project changes
+pnpm exec astrale-domain upgrade          # Update existing Astrale dependencies to beta
+```
+
+The command covers the workspace root and its packages, pins exact versions, and updates the
+lockfile through pnpm. Use `--channel latest` to select that tag instead. Missing tags and local,
+catalog, or aliased dependencies are left unchanged and reported; peers and overrides are not edited.
+For an older SDK without this command, start with `pnpm dlx @astrale-os/sdk@beta upgrade`.
+Stop development watchers first, then run the project's checks and validate on development.
+Nothing is committed or deployed. A Shell update also requires checking the installed Shell revision.
+Rerunning an upgrade synchronizes installation even when the manifest versions are already current.
+
 ## Handler authority and dependencies
 
 Authenticated handlers use Domain self authority for `kernel`, `graph`, `query`, and `mutate`.
@@ -110,10 +125,10 @@ The repository installs autonomously from its versioned npm-only lockfile:
 ```bash
 git clone https://github.com/astrale-os/sdk.git
 cd sdk
-AGENT_HARNESSES=codex bash scripts/agent_setup/setup.sh
+AGENT_HARNESSES=codex bash scripts/setup/setup.sh
 ```
 
-See [agent setup](scripts/agent_setup/README.md) for Claude Cloud and validation.
+See [agent setup](scripts/setup/README.md) for Claude Cloud and validation.
 
 It can also be consumed as a submodule of the main Astrale workspace:
 

package/dist/application/mutation/failure.js

@@ -37,15 +37,21 @@ function mutationCode(input) {
     const value = input;
     if (value.code === 'STATE_TRANSITION_ILLEGAL')
         return value.code;
-    for (const candidate of [value.code, nestedCode(value.reason), nestedCode(value.data)]) {
+    for (const candidate of [
+        value.code,
+        directOrNestedCode(value.reason),
+        directOrNestedCode(value.data),
+    ]) {
         if (typeof candidate === 'string' && candidate.startsWith('MUTATION_')) {
             return candidate;
         }
     }
     return undefined;
 }
-function nestedCode(input) {
-    return input !== null && typeof input === 'object' && !Array.isArray(input)
-        ? Reflect.get(input, 'code')
-        : undefined;
+function directOrNestedCode(input) {
+    return typeof input === 'string'
+        ? input
+        : input !== null && typeof input === 'object' && !Array.isArray(input)
+            ? Reflect.get(input, 'code')
+            : undefined;
 }

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

@@ -1,5 +1,5 @@
 import type { LintReportFormat } from '../linter/index.js';
-export declare const COMMANDS: readonly ['dev', 'build', 'deploy', 'test', 'lint', 'package'];
+export declare const COMMANDS: readonly ['dev', 'build', 'deploy', 'test', 'lint', 'package', 'upgrade'];
 export type Command = (typeof COMMANDS)[number];
 export interface ParsedArgs {
     readonly command: Command;
@@ -12,6 +12,8 @@ export interface ParsedArgs {
     readonly suite?: string;
     readonly sessionFile?: string;
     readonly secretsFile?: string;
+    readonly channel?: string;
+    readonly check?: boolean;
 }
 /** Parse the frozen `astrale-domain` command grammar without performing effects. */
 export declare function parseArgs(argv: readonly string[]): ParsedArgs;

package/dist/tooling/cli/arguments.js

@@ -1,8 +1,10 @@
 import { isAbsolute, normalize } from 'node:path';
-export const COMMANDS = ['dev', 'build', 'deploy', 'test', 'lint', 'package'];
+export const COMMANDS = ['dev', 'build', 'deploy', 'test', 'lint', 'package', 'upgrade'];
 /** Parse the frozen `astrale-domain` command grammar without performing effects. */
 export function parseArgs(argv) {
     const [command, ...rest] = argv;
+    if (command === 'upgrade')
+        return parseUpgrade(rest);
     const fix = rest.includes('--fix');
     const deployOnly = rest.includes('--deploy-only');
     let sessionFile;
@@ -142,6 +144,24 @@ export function parseArgs(argv) {
             throw new Error(command ? `Unknown command "${command}".` : 'Missing command.');
     }
 }
+function parseUpgrade(args) {
+    let channel = 'beta';
+    let check = false;
+    for (let index = 0; index < args.length; index++) {
+        const argument = args[index];
+        if (argument === '--check')
+            check = true;
+        else if (argument === '--channel' || argument.startsWith('--channel=')) {
+            channel = requiredValue('--channel', argument === '--channel' ? args[++index] : argument.slice(10));
+            if (!/^[A-Za-z][A-Za-z0-9._-]*$/u.test(channel)) {
+                throw new Error('--channel must be a registry dist-tag, such as beta or latest.');
+            }
+        }
+        else
+            throw new Error(`Unknown upgrade argument "${argument}".`);
+    }
+    return { command: 'upgrade', env: '', channel, check };
+}
 function lintFormat(input) {
     if (input !== 'stylish' && input !== 'json') {
         throw new Error(`--format must be "stylish" or "json", got "${input ?? ''}"`);

package/dist/tooling/cli/help.js

@@ -24,6 +24,7 @@ Commands:
   test                    Run Project tests, optionally against one Environment.
   lint                    Check Domain source and architecture.
   package                 Prepare public declarations for publication.
+  upgrade                 Update Astrale dependencies through pnpm (default: beta).
 
 Options:
   -h, --help              Show help.
@@ -31,6 +32,29 @@ Options:
 Run "astrale-domain <command> --help" for command-specific help.
 `;
 const COMMAND_HELP = Object.freeze({
+    upgrade: `Update existing Astrale dependencies in a pnpm project or workspace.
+
+Usage:
+  astrale-domain upgrade [--channel <tag>] [--check]
+
+Options:
+  --channel <tag>         Registry dist-tag to select (default: beta).
+  --check                 Show changes without modifying project files or installing.
+  -h, --help              Show help for upgrade.
+
+Behavior:
+  Updates dependencies, devDependencies, and optionalDependencies under @astrale-os/
+  and @astrale-domains/, including the workspace root. Writes exact versions and
+  runs pnpm install once. The selected tag is authoritative, even if older than
+  the current version. Installation is synchronized even when versions are unchanged,
+  so retrying can finish a previously failed install. Packages without that tag remain
+  unchanged with a warning.
+  Local links, catalogs, aliases, peers, and overrides are not rewritten.
+  Does not load astrale.config.ts, require Bun, run project checks, commit, or deploy.
+  Stop development watchers before upgrading. Review changes and run your project's
+  checks afterwards. Failed installations leave local changes available for repair.
+  For an older SDK without this command: pnpm dlx @astrale-os/sdk@beta upgrade.
+`,
     dev: `Build, verify, remotely deploy, and watch one Project Environment.
 
 Usage:

package/dist/tooling/cli/orchestrate.js

@@ -29,6 +29,15 @@ 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).`);

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

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

@@ -0,0 +1,57 @@
+import spawn from 'cross-spawn';
+/** pnpm owns registry configuration, installation policy, and lockfile resolution. */
+export function runPnpm(cwd, args, install = false) {
+    return new Promise((resolve, reject) => {
+        const child = spawn('pnpm', [...args], {
+            cwd,
+            stdio: install ? 'inherit' : ['ignore', 'pipe', 'pipe'],
+            shell: false,
+        });
+        let stdout = '';
+        let stderr = '';
+        let failure;
+        let escalation;
+        const stop = (reason) => {
+            if (failure)
+                return;
+            failure = new Error(reason);
+            child.kill('SIGTERM');
+            escalation = setTimeout(() => child.kill('SIGKILL'), 1_000);
+        };
+        const interrupt = () => stop('Upgrade interrupted; inspect local changes before retrying.');
+        process.once('SIGINT', interrupt);
+        process.once('SIGTERM', interrupt);
+        const timer = setTimeout(() => stop('pnpm timed out.'), install ? 600_000 : 60_000);
+        child.stdout?.on('data', (chunk) => {
+            stdout += chunk.toString('utf8');
+            if (stdout.length > 4 * 1024 * 1024)
+                stop('pnpm output exceeded the supported limit.');
+        });
+        child.stderr?.on('data', (chunk) => {
+            stderr += chunk.toString('utf8');
+            if (stderr.length > 4 * 1024 * 1024)
+                stop('pnpm output exceeded the supported limit.');
+        });
+        const cleanup = () => {
+            clearTimeout(timer);
+            if (escalation)
+                clearTimeout(escalation);
+            process.removeListener('SIGINT', interrupt);
+            process.removeListener('SIGTERM', interrupt);
+        };
+        child.once('error', (cause) => {
+            cleanup();
+            reject(new Error("Could not start pnpm. Install the project's declared pnpm version.", { cause }));
+        });
+        child.once('close', (code, signal) => {
+            cleanup();
+            if (failure)
+                reject(failure);
+            else if (code !== 0) {
+                reject(new Error(`pnpm ${args[0]} failed (${signal ?? code}).${stderr ? `\n${stderr.trim()}` : ''}`));
+            }
+            else
+                resolve(stdout);
+        });
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/sdk",
-  "version": "0.5.0-beta.132",
+  "version": "0.5.0-beta.134",
   "description": "Schema-first SDK for defining, composing, and deploying Astrale domains",
   "keywords": [
     "astrale",
@@ -244,6 +244,7 @@
     "@astrale-os/kernel-server": "0.5.0-beta.52",
     "@lucide/icons": "1.34.0",
     "@typescript/native-preview": "7.0.0-dev.20260707.2",
+    "cross-spawn": "7.0.6",
     "hono": "^4.13.2",
     "jose": "^6.2.9",
     "typescript": "~6.0.3"
@@ -256,6 +257,7 @@
     "@commitlint/config-conventional": "~21.2.2",
     "@hono/node-server": "^2.1.1",
     "@hono/node-server-v1": "npm:@hono/node-server@1.19.0",
+    "@types/cross-spawn": "6.0.6",
     "@types/node": "^22.20.1",
     "husky": "~9.1.7",
     "lint-staged": "~17.3.0",
@@ -329,10 +331,11 @@
     "qualify:publications": "node scripts/qualify-publications.mjs",
     "qualify": "node scripts/qualify.mjs",
     "sync:linter-policy": "node scripts/sync-domain-policy.mjs",
-    "setup": "bash scripts/agent_setup/setup.sh",
-    "setup:codex": "AGENT_HARNESSES=codex bash scripts/agent_setup/setup.sh",
-    "setup:claude": "AGENT_HARNESSES=claude bash scripts/agent_setup/setup.sh",
-    "check:agent-setup": "bash scripts/agent_setup/verify.sh",
-    "test:agent-setup": "node --test scripts/agent_setup/*.test.cjs"
+    "setup": "bash scripts/setup/setup.sh",
+    "setup:codex": "AGENT_HARNESSES=codex bash scripts/setup/setup.sh",
+    "setup:claude": "AGENT_HARNESSES=claude bash scripts/setup/setup.sh",
+    "check:agent-setup": "bash scripts/setup/verify.sh",
+    "test:agent-setup": "node --test scripts/setup/*.test.cjs",
+    "setup:local": "AGENT_SETUP_TOOLS=check bash scripts/setup/setup.sh"
   }
 }