@astrale-os/cli 0.8.1-alpha.7 → 1.0.0-beta.0

package/README.md

@@ -13,6 +13,12 @@ curl -fsSL https://raw.githubusercontent.com/astrale-os/cli/main/install.sh | sh
 The installer places a verified standalone binary at
 `~/.astrale/bin/astrale` by default. No local runtime is installed.
 
+During the prerelease period, install the current standalone beta explicitly:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/astrale-os/cli/main/install.sh | ASTRALE_CHANNEL=beta sh
+```
+
 Optional installer environment:
 
 ```bash
@@ -29,6 +35,12 @@ ships the [Domain Studio](studio/README.md) (`astrale studio`):
 npm install -g @astrale-os/cli
 ```
 
+During the prerelease period, install the current beta explicitly:
+
+```bash
+npm install -g @astrale-os/cli@beta
+```
+
 The npm build bundles all dependencies, so no private-registry access is needed.
 `astrale studio` launches a local web GUI to author and inspect a domain, with
 local Claude Code and Codex agent harnesses (`--harness claude|codex`); it runs on
@@ -36,9 +48,9 @@ local Claude Code and Codex agent harnesses (`--harness claude|codex`); it runs
 (the rest of the CLI needs only Node ≥ 22). The curl-installed standalone binary
 above does not include the studio — use the npm install for `astrale studio`.
 
-> Pre-1.0, `npm install -g @astrale-os/cli` installs the latest published
-> build (currently an alpha). The curl installer's channels (alpha/beta/rc) are
-> a binary-only concept.
+> Prereleases use their matching npm dist-tag (`alpha`, `beta`, or `rc`); bare
+> `npm install -g @astrale-os/cli` follows the stable `latest` tag. The curl
+> installer has separate binary channels with the same names.
 
 ## Quickstart
 

package/dist/astrale.js

@@ -9738,7 +9738,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@astrale-os/cli",
-    version: "0.8.1-alpha.7",
+    version: "1.0.0-beta.0",
     description: "Astrale CLI — connect to existing Astrale kernels",
     keywords: [
       "astrale",
@@ -9799,7 +9799,7 @@ var init_package = __esm(() => {
       "lint:fix": "oxlint --fix .",
       format: "pnpm exec oxfmt --write .",
       "format:check": "pnpm exec oxfmt --check .",
-      test: "bun test src",
+      test: "bun test src && node --test scripts/*.test.mjs",
       "test:watch": "bun test --watch src"
     },
     dependencies: {
@@ -9814,10 +9814,10 @@ var init_package = __esm(() => {
       zod: "^3.25.0"
     },
     devDependencies: {
-      "@astrale-os/kernel-client": "0.6.0-beta.3",
+      "@astrale-os/kernel-client": ">=0.6.0-beta.3 <1.0.0",
       "@astrale-os/ox": ">=0.1.0 <1.0.0",
-      "@astrale-os/sdk": "0.5.0-beta.3",
-      "@astrale-os/shell": "0.3.8-beta.2",
+      "@astrale-os/sdk": ">=0.5.0-beta.3 <1.0.0",
+      "@astrale-os/shell": ">=0.3.8-beta.2 <1.0.0",
       "@astrale/commitlint-config": "jsr:~2.0.1",
       "@commitlint/cli": "~20.3.1",
       "@commitlint/config-conventional": "~20.3.1",
@@ -87021,16 +87021,20 @@ function schemaUpgradeDetails2(reason) {
   if (!record10(reason) || reason.code !== "SCHEMA_UPGRADE_INCOMPATIBLE")
     return;
   const details = record10(reason.details) ? reason.details : {};
-  return {
-    ...typeof details.origin === "string" ? { origin: details.origin } : {},
-    ...typeof details.issue === "string" ? { issue: details.issue } : {},
-    ...typeof details.expected === "string" ? { expected: details.expected } : {},
-    ...typeof details.actual === "string" ? { actual: details.actual } : {}
-  };
+  const origin = typeof details.origin === "string" ? details.origin : undefined;
+  if (details.issue === "issuer-changed" && origin !== undefined && typeof details.installedIssuer === "string" && typeof details.replacementIssuer === "string") {
+    return {
+      origin,
+      issue: details.issue,
+      installedIssuer: details.installedIssuer,
+      replacementIssuer: details.replacementIssuer
+    };
+  }
+  return origin === undefined ? {} : { origin };
 }
 function schemaUpgradeHint(details) {
   const target2 = details.origin ?? "<origin>";
-  const explanation = details.expected !== undefined && details.actual !== undefined ? "A replacement cannot change an installed Domain issuer." : "The replacement changes an immutable part of the installed Domain.";
+  const explanation = details.issue === "issuer-changed" ? "A replacement cannot change an installed Domain issuer." : "The replacement changes an immutable part of the installed Domain.";
   return `${explanation} If this change is intentional, first run ` + `\`astrale domain uninstall ${target2}\`, then install it again. ` + "The Kernel refuses uninstall while dependents or business data remain; uninstall never deletes business data.";
 }
 function reasonWithCode(input, code) {
@@ -87063,7 +87067,7 @@ var init_reasons = __esm(() => {
 });
 
 // src/connection/errors.ts
-async function formatKernelError(error52, isRaw, urlArg = "", debug = false) {
+async function formatKernelError(error52, isRaw, urlArg = "", debug = false, opts = {}) {
   const url3 = urlArg || (error52 instanceof Error ? error52.url ?? "" : "");
   const localContext = await contextForError(error52);
   if (error52 instanceof AstraleError) {
@@ -87088,7 +87092,7 @@ async function formatKernelError(error52, isRaw, urlArg = "", debug = false) {
   const name = error52.name;
   switch (name) {
     case "TransportError":
-      presentTransportError(error52, isRaw, url3, localContext);
+      presentTransportError(error52, isRaw, url3, localContext, opts.recovery);
       break;
     case "ResponseError": {
       const code = error52.code;
@@ -87117,11 +87121,9 @@ async function formatKernelError(error52, isRaw, urlArg = "", debug = false) {
         presentFunctionInputIssues(inputIssues);
         if (queryRepair !== undefined)
           presentQueryInputRepair(queryRepair);
-        if (upgrade?.expected !== undefined) {
-          log.dim(`  installed issuer: ${upgrade.expected}`);
-        }
-        if (upgrade?.actual !== undefined) {
-          log.dim(`  replacement issuer: ${upgrade.actual}`);
+        if (upgrade?.issue === "issuer-changed") {
+          log.dim(`  installed issuer: ${upgrade.installedIssuer}`);
+          log.dim(`  replacement issuer: ${upgrade.replacementIssuer}`);
         }
         if (hint !== undefined)
           log.dim(`  ${hint}`);
@@ -87194,7 +87196,7 @@ function mapPublicError(error52) {
   }
   return { code: name && name !== "Error" ? name : "UNKNOWN", message: error52.message };
 }
-function presentTransportError(error52, isRaw, url3, context) {
+function presentTransportError(error52, isRaw, url3, context, recovery) {
   const phase = transportPhase(error52);
   const delivery = transportDelivery(error52);
   const code = phase === "connect" ? "CONNECTION_ERROR" : phase === "timeout" ? "TIMEOUT" : phase === "closed" ? "DISCONNECTED" : "TRANSPORT_ERROR";
@@ -87205,7 +87207,8 @@ function presentTransportError(error52, isRaw, url3, context) {
       ...url3 === "" ? {} : { url: url3 },
       ...phase === undefined ? {} : { phase },
       ...delivery === undefined ? {} : { delivery },
-      ...context === undefined ? {} : { context }
+      ...context === undefined ? {} : { context },
+      ...delivery === "unknown" && recovery !== undefined ? recovery : {}
     });
     return;
   }
@@ -87218,10 +87221,18 @@ function presentTransportError(error52, isRaw, url3, context) {
     log.dim("  Check the target and run `astrale status`.");
   else if (phase === "timeout")
     log.dim("  Try increasing `--timeout`.");
-  else if (delivery === "unknown") {
+  else if (delivery === "unknown")
+    printOperationRecovery(recovery);
+  printLocalContext(context);
+}
+function printOperationRecovery(recovery) {
+  if (recovery === undefined) {
     log.dim("  Delivery is unknown; do not automatically retry a mutating call.");
+    return;
   }
-  printLocalContext(context);
+  log.dim("  Delivery is unknown; retry with the same operation id:");
+  log.dim(`  operation: ${recovery.operation}`);
+  log.dim(`  ${recovery.retry}`);
 }
 function presentFunctionInputIssues(issues) {
   for (const issue2 of issues) {
@@ -88640,7 +88651,9 @@ async function runKernelCommand(input) {
   } catch (error52) {
     if (!isRaw && spin)
       spin.fail(`${label} failed`);
-    await formatKernelError(error52, isRaw, undefined, opts.debug);
+    await formatKernelError(error52, isRaw, undefined, opts.debug, {
+      recovery: input.recovery
+    });
     process.exit(1);
   }
 }
@@ -93593,11 +93606,12 @@ __export(exports_install, {
   default: () => install_default,
   directInstallCallInput: () => directInstallCallInput,
   domainRefFromTarget: () => domainRefFromTarget,
+  installDirect: () => installDirect,
   installViaAdmin: () => installViaAdmin,
   isIdentityOverride: () => isIdentityOverride,
   probeDeclaredOrigin: () => probeDeclaredOrigin
 });
-function directInstallCallInput(url3, token, operation2 = crypto.randomUUID()) {
+function directInstallCallInput(url3, operation2, token) {
   return Object.freeze({
     operation: operation2,
     domains: [
@@ -93611,6 +93625,15 @@ function directInstallCallInput(url3, token, operation2 = crypto.randomUUID()) {
     ]
   });
 }
+function acceptOperationId(input) {
+  if (typeof input !== "string" || !OPERATION_ID_PATTERN.test(input)) {
+    throw new AstraleError("INVALID_FLAG", "--operation must be a canonical lowercase UUIDv4.", "Omit --operation for a fresh install; use it only with the exact UUID printed for recovery.");
+  }
+  return input;
+}
+function createOperationId() {
+  return acceptOperationId(globalThis.crypto.randomUUID());
+}
 async function installViaAdmin(target2, opts, dependencies = {}) {
   const admin = { ...defaultAdminInstallDependencies, ...dependencies };
   const interactive = !!process.stdin.isTTY && !(opts.ci || opts.noPrompt || process.env.CI);
@@ -93648,8 +93671,9 @@ async function installViaAdmin(target2, opts, dependencies = {}) {
       log.dim(`  origin: ${result.origin}`);
       log.dim(`  url:    ${result.url}`);
     });
-  } catch (e) {
-    fatal(e, opts);
+  } catch (error52) {
+    await formatKernelError(error52, isMachine(opts), undefined, opts.debug);
+    process.exit(1);
   }
 }
 function assertInstallTargetReady(instance) {
@@ -93712,40 +93736,49 @@ async function activeSlug() {
     return;
   }
 }
-async function installDirect(target2, opts) {
+async function installDirect(target2, opts, dependencies = {}) {
+  const direct = { ...defaultDirectInstallDependencies, ...dependencies };
   let host = "";
   let consentedOrigin;
+  let operation2;
   try {
     if (!target2) {
       throw new AstraleError("MISSING_ARG", "--direct requires a domain url.", "e.g. astrale domain install https://crm.acme.dev --direct");
     }
     host = validateInstallUrl(target2);
+    operation2 = opts.operation === undefined ? direct.createOperationId() : direct.acceptOperationId(opts.operation);
     consentedOrigin = await ensureIdentityOverrideConsent(target2, host, opts.allowIdentityOverride ?? false);
   } catch (e) {
-    fatal(e);
+    fatal(e, opts);
   }
   const url3 = target2;
-  await runKernelCommand({
+  const retry = directInstallRetry(url3, operation2, opts);
+  await direct.runKernelCommand({
     opts,
-    label: `Installing domain from ${url3}`,
-    fn: async ({ session }) => await session.call(createPathCall(Path.project(exports_syscalls.install.ref).raw, directInstallCallInput(url3, opts.token))),
+    label: `Installing domain from ${url3} (operation ${operation2})`,
+    recovery: { operation: operation2, retry },
+    fn: async ({ session }) => await session.call(createPathCall(Path.project(exports_syscalls.install.ref).raw, directInstallCallInput(url3, operation2, opts.token))),
     format: (result, fmtOpts, isRaw) => {
       if (isRaw) {
         output(result, fmtOpts);
         return;
       }
       const installed = result.transitions[0]?.intent;
-      if (installed === undefined) {
+      if (!installed)
         throw new Error("Kernel install returned no committed Domain transition.");
-      }
       const revision = installed.target?.schemaRevision ?? result.operation;
       log.success(`Domain installed: ${installed.origin}@${revision}`);
+      log.dim(`  operation:   ${result.operation}`);
       if (isIdentityOverride(installed.origin, host) && installed.origin !== consentedOrigin) {
         log.warn(`Installed origin "${installed.origin}" differs from the serving host "${host}" ` + `and was not confirmed before install (the worker's /meta did not declare it). ` + `Every ${installed.origin}/* call on this instance now routes to ${host}.`);
       }
     }
   });
 }
+function directInstallRetry(url3, operation2, opts) {
+  const instance = opts.instance === undefined ? "" : ` -i ${opts.instance}`;
+  return `astrale domain install ${url3} --direct --operation ${operation2}${instance}`;
+}
 function validateInstallUrl(value2) {
   let url3;
   try {
@@ -93798,12 +93831,13 @@ async function probeDeclaredOrigin(url3) {
     return;
   }
 }
-var install_default, defaultAdminInstallDependencies;
+var OPERATION_ID_PATTERN, install_default, defaultAdminInstallDependencies, defaultDirectInstallDependencies;
 var init_install3 = __esm(() => {
   init_path5();
   init_kernel2();
   init_source();
   init_connection2();
+  init_errors12();
   init_errors2();
   init_admin_domain();
   init_admin_instance();
@@ -93813,6 +93847,7 @@ var init_install3 = __esm(() => {
   init_output();
   init_prompt();
   init_validation2();
+  OPERATION_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
   install_default = {
     name: "install",
     description: "Install a domain on an instance (via the admin catalog, or --direct from a url)",
@@ -93831,6 +93866,10 @@ Behavior:
   origin differs from its serving host, it requires explicit consent (an
   interactive DANGER prompt, or --allow-identity-override in scripts).
 
+  A fresh, strong operation id is generated automatically. Use --operation
+  only to retry or recover the exact same direct install after an outcome-unknown
+  timeout or disconnect.
+
 Examples:
   $ astrale domain install crm.acme.dev -i staging          # by origin, via admin
   $ astrale domain install https://crm.acme.dev             # by url, via admin
@@ -93855,12 +93894,19 @@ Examples:
         flags: "--token <token>",
         description: "Bearer token for private domain install endpoints (--direct only)"
       },
+      {
+        flags: "--operation <uuid>",
+        description: "Reuse an exact direct-install operation id for explicit retry/recovery"
+      },
       {
         flags: "--allow-identity-override",
         description: "Consent to a domain whose origin differs from its serving host (--direct only)"
       }
     ],
     action: async (target2, opts) => {
+      if (opts.operation !== undefined && !opts.direct) {
+        fatal(new AstraleError("INVALID_FLAG", "--operation is valid only with --direct.", "Ordinary direct installs generate a fresh operation id automatically."), opts);
+      }
       if (opts.direct) {
         await installDirect(target2, opts);
         return;
@@ -93873,6 +93919,11 @@ Examples:
     listDomains: listAdminDomainsInContext,
     install: installAdminDomainInContext
   });
+  defaultDirectInstallDependencies = Object.freeze({
+    acceptOperationId,
+    createOperationId,
+    runKernelCommand
+  });
 });
 
 // src/commands/domain/uninstall.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/cli",
-  "version": "0.8.1-alpha.7",
+  "version": "1.0.0-beta.0",
   "description": "Astrale CLI — connect to existing Astrale kernels",
   "keywords": [
     "astrale",
@@ -62,10 +62,10 @@
     "zod": "^3.25.0"
   },
   "devDependencies": {
-    "@astrale-os/kernel-client": "0.6.0-beta.3",
+    "@astrale-os/kernel-client": ">=0.6.0-beta.3 <1.0.0",
     "@astrale-os/ox": ">=0.1.0 <1.0.0",
-    "@astrale-os/sdk": "0.5.0-beta.3",
-    "@astrale-os/shell": "0.3.8-beta.2",
+    "@astrale-os/sdk": ">=0.5.0-beta.3 <1.0.0",
+    "@astrale-os/shell": ">=0.3.8-beta.2 <1.0.0",
     "@astrale/commitlint-config": "npm:@jsr/astrale__commitlint-config@~2.0.1",
     "@commitlint/cli": "~20.3.1",
     "@commitlint/config-conventional": "~20.3.1",
@@ -107,7 +107,7 @@
     "lint:fix": "oxlint --fix .",
     "format": "pnpm exec oxfmt --write .",
     "format:check": "pnpm exec oxfmt --check .",
-    "test": "bun test src",
+    "test": "bun test src && node --test scripts/*.test.mjs",
     "test:watch": "bun test --watch src"
   }
 }

package/src/commands/__tests__/domain-install-operation.test.ts

@@ -0,0 +1,121 @@
+import { afterEach, describe, expect, mock, test } from 'bun:test'
+
+import { installDirect } from '../domain/install'
+
+const GENERATED = '4a4c9a18-50f6-4d84-a7b7-2d83e3e45dc8'
+const RETRY = '139137b5-af47-47ce-92b2-b64a2b0c63d7'
+
+const originalFetch = globalThis.fetch
+
+class ExitError extends Error {}
+
+afterEach(() => {
+  globalThis.fetch = originalFetch
+})
+
+describe('direct domain install operation identity', () => {
+  test('generates one operation before transport and exposes it for recovery', async () => {
+    globalThis.fetch = mock(async () =>
+      Response.json({ domainName: 'crm.test' }),
+    ) as unknown as typeof fetch
+    const create = mock(() => GENERATED)
+    const requests: unknown[] = []
+    let recovery: unknown
+
+    await installDirect(
+      'https://crm.test',
+      { direct: true, json: true },
+      {
+        createOperationId: create,
+        runKernelCommand: async (input) => {
+          recovery = input.recovery
+          requests.push(
+            await input.fn({
+              session: {
+                call: async (call: { input: unknown }) => call.input,
+              },
+            } as never),
+          )
+        },
+      },
+    )
+
+    expect(create).toHaveBeenCalledTimes(1)
+    expect(requests).toEqual([
+      {
+        operation: GENERATED,
+        domains: [{ source: { kind: 'remote', url: 'https://crm.test' } }],
+      },
+    ])
+    expect(recovery).toEqual({
+      operation: GENERATED,
+      retry: `astrale domain install https://crm.test --direct --operation ${GENERATED}`,
+    })
+  })
+
+  test('accepts an explicit operation only as the exact retry identity', async () => {
+    globalThis.fetch = mock(async () =>
+      Response.json({ domainName: 'crm.test' }),
+    ) as unknown as typeof fetch
+    const create = mock(() => GENERATED)
+    const accepted: string[] = []
+    const requests: unknown[] = []
+
+    await installDirect(
+      'https://crm.test',
+      { direct: true, operation: RETRY, json: true },
+      {
+        createOperationId: create,
+        acceptOperationId: (input) => {
+          accepted.push(String(input))
+          return RETRY
+        },
+        runKernelCommand: async (input) => {
+          requests.push(
+            await input.fn({
+              session: {
+                call: async (call: { input: unknown }) => call.input,
+              },
+            } as never),
+          )
+        },
+      },
+    )
+
+    expect(create).not.toHaveBeenCalled()
+    expect(accepted).toEqual([RETRY])
+    expect(requests).toEqual([
+      {
+        operation: RETRY,
+        domains: [{ source: { kind: 'remote', url: 'https://crm.test' } }],
+      },
+    ])
+  })
+
+  test('rejects a non-UUID operation before metadata or Kernel transport', async () => {
+    const originalExit = process.exit
+    const originalWrite = process.stderr.write
+    const fetch = mock(async () => Response.json({ domainName: 'crm.test' }))
+    const run = mock(async () => undefined)
+    globalThis.fetch = fetch as unknown as typeof globalThis.fetch
+    process.exit = (() => {
+      throw new ExitError('exit')
+    }) as typeof process.exit
+    process.stderr.write = (() => true) as typeof process.stderr.write
+    try {
+      await expect(
+        installDirect(
+          'https://crm.test',
+          { direct: true, operation: 'guessable-operation', json: true },
+          { runKernelCommand: run },
+        ),
+      ).rejects.toBeInstanceOf(ExitError)
+    } finally {
+      process.exit = originalExit
+      process.stderr.write = originalWrite
+    }
+
+    expect(fetch).not.toHaveBeenCalled()
+    expect(run).not.toHaveBeenCalled()
+  })
+})

package/src/commands/__tests__/domain-install-owned.test.ts

@@ -1,3 +1,4 @@
+import { ResponseError } from '@astrale-os/kernel-client'
 import { afterEach, beforeEach, describe, expect, mock, test } from 'bun:test'
 
 import type { OwnedInstanceInfo } from '../../lib/admin-instance'
@@ -118,4 +119,69 @@ describe('admin domain install owner boundary', () => {
     expect(calls).toEqual([])
     expect(calls).toEqual([])
   })
+
+  test('preserves an incompatible issuer reason returned through Admin', async () => {
+    inventory = [
+      {
+        id: 'owned-id',
+        slug: 'owned',
+        url: 'https://owned.eu.astrale.ai',
+        state: 'ready',
+      },
+    ]
+    const domain = {
+      id: 'crm-id',
+      origin: 'crm.acme.dev',
+      name: 'CRM',
+      url: 'https://crm.acme.dev',
+      createdAt: '2026-08-20T00:00:00.000Z',
+      updatedAt: '2026-08-20T00:00:00.000Z',
+    }
+    const failure = new ResponseError(5001, 'Schema operation is not supported.', {
+      code: 'SCHEMA_UPGRADE_INCOMPATIBLE',
+      details: {
+        phase: 'upgrade',
+        origin: domain.origin,
+        issue: 'issuer-changed',
+        installedIssuer: 'https://old.example',
+        replacementIssuer: 'https://new.example',
+      },
+    })
+    const { installViaAdmin } = await import('../domain/install')
+
+    await expect(
+      installViaAdmin(
+        domain.origin,
+        {
+          instance: 'owned',
+          json: true,
+          noPrompt: true,
+        },
+        {
+          listInstances: async () => inventory,
+          listDomains: async () => [domain],
+          install: async () => {
+            throw failure
+          },
+        },
+      ),
+    ).rejects.toEqual(new ExitError(1))
+
+    expect(JSON.parse(stderr)).toEqual({
+      error: 'RESPONSE_ERROR',
+      code: 5001,
+      message: 'Schema operation is not supported.',
+      reason: {
+        code: 'SCHEMA_UPGRADE_INCOMPATIBLE',
+        details: {
+          phase: 'upgrade',
+          origin: 'crm.acme.dev',
+          issue: 'issuer-changed',
+          installedIssuer: 'https://old.example',
+          replacementIssuer: 'https://new.example',
+        },
+      },
+      hint: expect.stringContaining('astrale domain uninstall crm.acme.dev'),
+    })
+  })
 })

package/src/commands/__tests__/install-direct.test.ts

@@ -4,8 +4,9 @@ import { directInstallCallInput } from '../domain/install'
 
 describe('directInstallCallInput', () => {
   test('sends the current remote install syscall, not a legacy url list', () => {
-    expect(directInstallCallInput('https://tasks.example.test', 'secret', 'op-1')).toEqual({
-      operation: 'op-1',
+    const operation = '4a4c9a18-50f6-4d84-a7b7-2d83e3e45dc8'
+    expect(directInstallCallInput('https://tasks.example.test', operation, 'secret')).toEqual({
+      operation,
       domains: [
         {
           source: {