@astrale-os/cli 0.8.1-alpha.2 → 0.8.1-alpha.4

package/README.md

@@ -110,7 +110,7 @@ Main command groups:
 
 | Group | What it covers |
 |-------|----------------|
-| Kernel | `ls`, `get`, `call`, `query`, `describe`, `token` |
+| Kernel | `get`, `call`, `query`, `describe`, `token` |
 | Context | `status`, `whoami`, `use` |
 | Management | `admin`, `instance`, `identity`, `auth`, `idp`, `update` |
 | Agent | `browser` |

package/dist/astrale.js

@@ -2576,7 +2576,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@astrale-os/cli",
-    version: "0.8.1-alpha.2",
+    version: "0.8.1-alpha.4",
     description: "Astrale CLI — connect to existing Astrale kernels",
     keywords: [
       "astrale",
@@ -90137,6 +90137,9 @@ var init_mutation2 = __esm(() => {
 
 // src/graph/mutation.ts
 function prepareMutation(input) {
+  if (isLegacyPatchData(input)) {
+    throw new TypeError("Legacy PatchData { nodes, edges } is not Mutation V3. Author { preconditions, operations } or a canonical astrale.graph.mutation/v3 document.");
+  }
   if (isCanonicalCandidate(input))
     return MutationAST.decode(input);
   return MutationAST.create(input);
@@ -90144,6 +90147,9 @@ function prepareMutation(input) {
 function isCanonicalCandidate(input) {
   return input !== null && typeof input === "object" && !Array.isArray(input) && (Object.hasOwn(input, "format") || Object.hasOwn(input, "version"));
 }
+function isLegacyPatchData(input) {
+  return input !== null && typeof input === "object" && !Array.isArray(input) && !Object.hasOwn(input, "operations") && (Object.hasOwn(input, "nodes") || Object.hasOwn(input, "edges"));
+}
 var init_mutation3 = __esm(() => {
   init_mutation2();
 });
@@ -90308,6 +90314,99 @@ var init_binary4 = __esm(() => {
   init_output();
 });
 
+// src/commands/call-describe.ts
+function describeCallableFromSchema(path5, schema2) {
+  if (path5.ast.anchor.kind !== "domain")
+    return;
+  const origin = path5.ast.anchor.origin;
+  const last = path5.ast.steps.at(-1);
+  const document = asRecord2(schema2);
+  if (document === undefined || last === undefined)
+    return;
+  if (last.kind === "method") {
+    const owner = path5.ast.steps.at(-2);
+    if (owner?.kind === "projection" && (owner.projection.kind === "class" || owner.projection.kind === "interface")) {
+      const bag = asRecord2(owner.projection.kind === "class" ? document.classes : document.interfaces);
+      const definition3 = asRecord2(bag?.[owner.projection.name]);
+      const method = asRecord2(asRecord2(definition3?.methods)?.[last.name]);
+      if (method !== undefined) {
+        return Object.freeze({
+          path: path5.raw,
+          origin,
+          class: owner.projection.name,
+          method: last.name,
+          dispatch: last.dispatch,
+          ...callableFields(method)
+        });
+      }
+    }
+    const matches3 = findNamedMethods(document, origin, path5.raw, last.name, last.dispatch);
+    if (matches3.length === 1)
+      return matches3[0];
+    if (matches3.length > 1) {
+      return Object.freeze({
+        path: path5.raw,
+        origin,
+        method: last.name,
+        dispatch: last.dispatch,
+        candidates: Object.freeze(matches3)
+      });
+    }
+    return;
+  }
+  if (last.kind === "projection" && last.projection.kind === "function") {
+    const fn2 = asRecord2(asRecord2(document.functions)?.[last.projection.name]);
+    if (fn2 === undefined)
+      return;
+    return Object.freeze({
+      path: path5.raw,
+      origin,
+      function: last.projection.name,
+      ...callableFields(fn2)
+    });
+  }
+  return;
+}
+function missingCallableDescription(path5) {
+  return new AstraleError("CALL_DESCRIBE_UNAVAILABLE", `No callable schema is installed for ${path5}.`, "Use a Domain-rooted Path such as /:host.astrale.ai:class.Manager:createInstance. Method Paths are not Function nodes.");
+}
+function findNamedMethods(schema2, origin, path5, method, dispatch) {
+  const matches3 = [];
+  for (const bag of [schema2.classes, schema2.interfaces]) {
+    const definitions2 = asRecord2(bag);
+    if (definitions2 === undefined)
+      continue;
+    for (const [className, definition3] of Object.entries(definitions2)) {
+      const methodDef = asRecord2(asRecord2(asRecord2(definition3)?.methods)?.[method]);
+      if (methodDef === undefined)
+        continue;
+      matches3.push(Object.freeze({
+        path: path5,
+        origin,
+        class: className,
+        method,
+        dispatch,
+        ...callableFields(methodDef)
+      }));
+    }
+  }
+  return matches3;
+}
+function callableFields(value2) {
+  return {
+    ...typeof value2.description === "string" ? { description: value2.description } : {},
+    ...value2.auth === undefined ? {} : { auth: value2.auth },
+    ...value2.input === undefined ? {} : { input: value2.input },
+    ...value2.output === undefined ? {} : { output: value2.output }
+  };
+}
+function asRecord2(input) {
+  return input !== null && typeof input === "object" && !Array.isArray(input) ? input : undefined;
+}
+var init_call_describe = __esm(() => {
+  init_errors2();
+});
+
 // src/commands/call.ts
 var exports_call = {};
 __export(exports_call, {
@@ -90374,28 +90473,20 @@ async function describeOperation(path5, opts) {
   await runKernelCommand({
     opts,
     label: `Schema for ${path5}`,
-    fn: async ({ graph }) => await graph.get(Path.parse(path5)),
-    format: (node4, fmtOpts) => {
-      const input = nodeProperty(node4, "inputSchema");
-      const outputSchema = nodeProperty(node4, "outputSchema");
-      const schema2 = {};
-      if (input)
-        schema2.input = tryParseJson(input);
-      if (outputSchema)
-        schema2.output = tryParseJson(outputSchema);
-      output(Object.keys(schema2).length > 0 ? schema2 : node4, fmtOpts);
-    }
+    fn: async ({ graph }) => {
+      const parsed = Path.parse(path5);
+      if (parsed.ast.anchor.kind !== "domain") {
+        throw missingCallableDescription(path5);
+      }
+      const domain3 = await graph.getOrThrow(Path.parse(`/:${parsed.ast.anchor.origin}`));
+      const described = describeCallableFromSchema(parsed, nodeProperty(domain3, "schema"));
+      if (described === undefined)
+        throw missingCallableDescription(path5);
+      return described;
+    },
+    format: (schema2, fmtOpts) => output(schema2, fmtOpts)
   });
 }
-function tryParseJson(value2) {
-  if (typeof value2 !== "string")
-    return value2;
-  try {
-    return JSON.parse(value2);
-  } catch {
-    return value2;
-  }
-}
 async function parseParams(rawParams, dataFlag) {
   if (dataFlag) {
     if (rawParams.length > 0) {
@@ -90471,6 +90562,7 @@ var init_call2 = __esm(() => {
   init_binary4();
   init_log();
   init_output();
+  init_call_describe();
   PARAM_KEY_RE = /^[A-Za-z_][A-Za-z0-9_-]*$/;
   call_default = {
     name: "call",
@@ -90490,16 +90582,19 @@ Self-reference:
   (e.g. via 'astrale get @self --json'). Resolution authenticates to
   the selected Kernel and never trusts a local registration or JWT sub.
 
+  --describe reads the callable's input/output from the installed Domain
+  schema. Method Paths are not Function nodes.
+
 Examples:
-  $ astrale call /:host.astrale.ai:class.KernelInstance:list
+  $ astrale call /:host.astrale.ai:class.Manager:createInstance --describe
   $ astrale call /:blog.acme.com:class.Author:list limit=10
   $ astrale call '@self::deactivate'
-  $ astrale call /:shell.astrale.ai:function.search-domains --json
+  $ astrale call /:kernel.astrale.ai:function.journal --data '{"limit":5}' --json
 `,
     arguments: [
       {
         name: "path",
-        description: "Operation path (e.g., /:host.astrale.ai:class.KernelInstance:list or /node::method)"
+        description: "Operation path (e.g., /:host.astrale.ai:class.Manager:createInstance or /node::method)"
       },
       { name: "params...", description: "Params as key=value pairs", required: false }
     ],
@@ -90597,7 +90692,7 @@ async function getCommand(target2, opts) {
   try {
     ({ path: path5, meta: meta3 } = await expandSelfInPath(target2, opts));
   } catch (error52) {
-    log.error(error52 instanceof Error ? error52.message : "Invalid target");
+    await formatKernelError(error52, isMachine(opts), undefined, opts.debug);
     process.exit(1);
   }
   await runKernelCommand({
@@ -90611,7 +90706,7 @@ var get_default;
 var init_get = __esm(() => {
   init_path5();
   init_connection2();
-  init_log();
+  init_errors12();
   init_output();
   get_default = {
     name: "get",
@@ -90757,115 +90852,6 @@ var init_class3 = __esm(() => {
   init_class();
 });
 
-// src/commands/ls.ts
-var exports_ls = {};
-__export(exports_ls, {
-  lsCommand: () => lsCommand,
-  listProjection: () => listProjection,
-  displayName: () => displayName,
-  default: () => ls_default
-});
-async function lsCommand(source2, opts) {
-  if (opts.edge === undefined) {
-    log.error("ls requires --edge <class>; Kernel V2 has no universal child relation");
-    process.exit(1);
-  }
-  let path5;
-  let meta3;
-  let prepared;
-  try {
-    ({ path: path5, meta: meta3 } = await expandSelfInPath(source2, opts));
-    prepared = prepareQuery({
-      sources: [path5],
-      edge: opts.edge,
-      direction: opts.direction,
-      limit: opts.limit,
-      cursor: opts.cursor
-    });
-  } catch (error52) {
-    log.error(error52 instanceof Error ? error52.message : "Invalid edge neighborhood");
-    process.exit(1);
-  }
-  await runKernelCommand({
-    opts,
-    label: `Neighbors of ${path5}`,
-    fn: ({ graph }) => withSelfHint(() => graph.query(prepared.ast, { page: prepared.page }), meta3),
-    format: (response2, format3) => {
-      const graph = completeGraph(response2.result);
-      presentList([...graph.nodes], { ...format3, long: opts.long, quiet: opts.quiet, count: opts.count }, listProjection);
-      if (response2.page.next && !isMachine(format3) && !opts.quiet && !opts.count) {
-        process.stderr.write(`  cursor: ${response2.page.next}
-`);
-      }
-    }
-  });
-}
-function completeGraph(result) {
-  if (result.kind !== "graph")
-    throw new TypeError("ls expected one complete graph Query result");
-  return result.graph;
-}
-function listProjection(nodes) {
-  return {
-    columns: [
-      { key: "name", header: "NAME", color: source_default.cyan },
-      { key: "class", header: "CLASS", color: source_default.dim },
-      { key: "id", header: "ID", color: source_default.dim }
-    ],
-    rows: nodes.map((node4) => ({
-      name: displayName(node4),
-      class: ClassPath.name(node4.class),
-      id: node4.id
-    })),
-    paths: nodes.map((node4) => `@${node4.id}`)
-  };
-}
-function displayName(node4) {
-  const value2 = nodeProperty(node4, "name") ?? nodeProperty(node4, "title") ?? nodeProperty(node4, "slug");
-  return typeof value2 === "string" && value2.length > 0 ? value2 : `@${node4.id}`;
-}
-var ls_default;
-var init_ls = __esm(() => {
-  init_class3();
-  init_source();
-  init_connection2();
-  init_graph6();
-  init_log();
-  init_output();
-  ls_default = {
-    name: "ls",
-    description: "List one finite exact edge neighborhood",
-    afterHelpText: `
-Behavior:
-  Lists Nodes reached from one source through one exact Edge Class. Kernel V2
-  has no universal parent/child relation, so --edge is required and recursive
-  tree walking is intentionally absent. Direction defaults to outgoing and the
-  finite default limit is 100. -q emits one @id per line.
-
-Examples:
-  $ astrale ls @note --edge /:notes.example.dev:class.references
-  $ astrale ls @note --edge /:notes.example.dev:class.references --direction incoming --limit 25
-`,
-    arguments: [{ name: "source", description: "Canonical source Path or @id" }],
-    options: [
-      { flags: "--edge <class>", description: "Exact Edge Class to traverse" },
-      {
-        flags: "--direction <direction>",
-        description: "Traversal direction (default: outgoing)",
-        choices: ["outgoing", "incoming", "incident"]
-      },
-      { flags: "--limit <n>", description: "Finite selected Node limit (default: 100)" },
-      { flags: "--cursor <token>", description: "Resume one live query scope" },
-      { flags: "-l, --long", description: "Print complete canonical Nodes" },
-      { flags: "-q, --quiet", description: "Print one @id per line" },
-      { flags: "--count", description: "Print only the number of returned Nodes" }
-    ],
-    action: async (source2, opts) => {
-      await lsCommand(source2, opts);
-    }
-  };
-});
-
 // src/commands/describe.ts
 var exports_describe = {};
 __export(exports_describe, {
@@ -91173,24 +91159,37 @@ function printRecord(record10) {
 `);
 }
 function acceptRecord2(input, index) {
-  if (!isRecord8(input) || !Number.isSafeInteger(input.sequence) || typeof input.timestamp !== "string" || typeof input.topic !== "string") {
+  if (!isRecord8(input) || !Number.isSafeInteger(input.sequence) || typeof input.topic !== "string") {
     throw new TypeError(`Kernel journal record ${index} is invalid`);
   }
-  for (const key of ["principal", "correlationId", "causationId"]) {
-    if (input[key] !== undefined && typeof input[key] !== "string") {
-      throw new TypeError(`Kernel journal record ${index}.${key} must be text`);
-    }
+  const occurredAt = optionalText2(input.occurredAt, index, "occurredAt");
+  const timestamp = optionalText2(input.timestamp, index, "timestamp") ?? occurredAt;
+  if (timestamp === undefined) {
+    throw new TypeError(`Kernel journal record ${index} is missing occurredAt/timestamp`);
   }
+  const correlation = isRecord8(input.correlation) ? input.correlation : undefined;
+  const correlationId = optionalText2(input.correlationId, index, "correlationId") ?? optionalText2(correlation?.invocationId, index, "correlation.invocationId");
+  const principal = optionalText2(input.principal, index, "principal");
   return Object.freeze({
     sequence: input.sequence,
-    timestamp: input.timestamp,
+    timestamp,
     topic: input.topic,
     payload: input.payload,
-    ...input.principal === undefined ? {} : { principal: input.principal },
-    ...input.correlationId === undefined ? {} : { correlationId: input.correlationId },
-    ...input.causationId === undefined ? {} : { causationId: input.causationId }
+    ...occurredAt === undefined ? {} : { occurredAt },
+    ...optionalText2(input.committedAt, index, "committedAt") === undefined ? {} : { committedAt: input.committedAt },
+    ...principal === undefined ? {} : { principal },
+    ...correlationId === undefined ? {} : { correlationId },
+    ...optionalText2(input.causationId, index, "causationId") === undefined ? {} : { causationId: input.causationId }
   });
 }
+function optionalText2(input, index, field) {
+  if (input === undefined)
+    return;
+  if (typeof input !== "string") {
+    throw new TypeError(`Kernel journal record ${index}.${field} must be text`);
+  }
+  return input;
+}
 function positiveInteger3(flag, raw2) {
   if (!/^\d+$/.test(raw2))
     throw new TypeError(`${flag} must be a positive integer`);
@@ -92742,7 +92741,8 @@ Examples:
 var exports_list = {};
 __export(exports_list, {
   default: () => list_default,
-  buildInstanceRows: () => buildInstanceRows
+  buildInstanceRows: () => buildInstanceRows,
+  adminInventoryUnavailable: () => adminInventoryUnavailable
 });
 function buildInstanceRows(managed, bookmarks, show) {
   const rows = [];
@@ -92786,9 +92786,19 @@ function buildInstanceRows(managed, bookmarks, show) {
   }
   return rows;
 }
-var COLUMNS, list_default;
+function adminInventoryUnavailable(cause) {
+  const code = cause instanceof AstraleError ? cause.code : undefined;
+  if (code !== undefined && ADMIN_INVENTORY_CODES.has(code)) {
+    return new AstraleError("ADMIN_INVENTORY_UNAVAILABLE", "Managed instance listing needs the Admin Domain and an IdP-backed identity. Admin is not deployed in this environment.", "Use `astrale instance list --bookmarked` for local kernel bookmarks. Key-backed identities cannot mint an Admin Domain token.");
+  }
+  if (cause instanceof AstraleError)
+    return cause;
+  return new AstraleError("ADMIN_INVENTORY_UNAVAILABLE", cause instanceof Error ? cause.message : String(cause), "Use `astrale instance list --bookmarked` for local kernel bookmarks.");
+}
+var COLUMNS, list_default, ADMIN_INVENTORY_CODES;
 var init_list = __esm(() => {
   init_source();
+  init_errors2();
   init_admin_instance();
   init_admin_instance();
   init_admin_target();
@@ -92823,7 +92833,11 @@ var init_list = __esm(() => {
         }));
         let managed = [];
         if (!opts.bookmarked) {
-          managed = await withSpinner("Fetching instances", !isMachine(opts), () => listOwnedInstances(opts));
+          try {
+            managed = await withSpinner("Fetching instances", !isMachine(opts), () => listOwnedInstances(opts));
+          } catch (error52) {
+            throw adminInventoryUnavailable(error52);
+          }
         }
         if (isMachine(opts)) {
           output({
@@ -92848,6 +92862,15 @@ var init_list = __esm(() => {
       }
     }
   };
+  ADMIN_INVENTORY_CODES = new Set([
+    "TOKEN_EXCHANGE_SOURCE_INVALID",
+    "TOKEN_EXCHANGE_SOURCE_EXPIRED",
+    "TOKEN_EXCHANGE_UNSUPPORTED",
+    "TOKEN_EXCHANGE_DISCOVERY_FAILED",
+    "TOKEN_EXCHANGE_PROTOCOL_ERROR",
+    "TOKEN_EXCHANGE_INSECURE",
+    "ADMIN_DOMAIN_ISSUER_MISSING"
+  ]);
 });
 
 // src/commands/instance/bookmark.ts
@@ -93437,7 +93460,7 @@ Behavior:
   Reads the admin catalog — every domain that has been \`publish\`ed
   (origin → published worker URL). Listing only shows what is INSTALLABLE;
   what is actually mounted where lives on each instance's own graph
-  (\`astrale ls /\` against that instance).
+  (\`astrale query\` against that instance).
 
   Default output is a NAME/ORIGIN/URL/DEFAULT table on a TTY, JSON when piped
   or with --json/--raw (agent-friendly — full DomainInfo objects). -q prints
@@ -93591,8 +93614,23 @@ __export(exports_install, {
   isIdentityOverride: () => isIdentityOverride,
   installViaAdmin: () => installViaAdmin,
   domainRefFromTarget: () => domainRefFromTarget,
+  directInstallCallInput: () => directInstallCallInput,
   default: () => install_default
 });
+function directInstallCallInput(url3, token, operation2 = crypto.randomUUID()) {
+  return Object.freeze({
+    operation: operation2,
+    domains: [
+      Object.freeze({
+        source: Object.freeze({
+          kind: "remote",
+          url: url3,
+          ...token === undefined ? {} : { token }
+        })
+      })
+    ]
+  });
+}
 async function installViaAdmin(target2, opts, dependencies = {}) {
   const admin = { ...defaultAdminInstallDependencies, ...dependencies };
   const interactive = !!process.stdin.isTTY && !(opts.ci || opts.noPrompt || process.env.CI);
@@ -93710,20 +93748,18 @@ async function installDirect(target2, opts) {
   await runKernelCommand({
     opts,
     label: `Installing domain from ${url3}`,
-    fn: async ({ session }) => await session.call(createPathCall(Path.project(exports_syscalls.install.ref).raw, {
-      domains: [{ url: url3, ...opts.token ? { token: opts.token } : {} }]
-    })),
+    fn: async ({ session }) => await session.call(createPathCall(Path.project(exports_syscalls.install.ref).raw, directInstallCallInput(url3, opts.token))),
     format: (result, fmtOpts, isRaw) => {
       if (isRaw) {
         output(result, fmtOpts);
         return;
       }
-      const installed = result[0];
-      if (!installed)
-        throw new Error("Kernel install returned no installed Domain receipt.");
-      log.success(`Domain installed: ${installed.origin}@${installed.revision}`);
-      if (installed.etag)
-        log.dim(`  publication: ${installed.etag}`);
+      const installed = result.transitions[0]?.intent;
+      if (installed === undefined) {
+        throw new Error("Kernel install returned no committed Domain transition.");
+      }
+      const revision = installed.target?.schemaRevision ?? result.operation;
+      log.success(`Domain installed: ${installed.origin}@${revision}`);
       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}.`);
       }
@@ -95759,9 +95795,21 @@ function renderCommanderError(program2, error, argv = process.argv.slice(2)) {
   ].join(`
 `);
 }
+var RETIRED_COMMANDS = {
+  ls: "astrale query <source> --edge <class>"
+};
 function renderUnknownCommand(tokens, catalog) {
   const command = tokens.join(" ");
   const first = tokens[0];
+  const retired = first === undefined ? undefined : RETIRED_COMMANDS[first];
+  if (retired !== undefined) {
+    return [
+      `Unknown command: ${source_default.bold(`astrale ${command}`)}`,
+      "",
+      `\`astrale ${first}\` was removed. Use ${source_default.bold(retired)} instead.`
+    ].join(`
+`);
+  }
   const namespaceMatches = catalog.filter((entry) => entry.path.at(-1) === first);
   if (namespaceMatches.length > 0) {
     return [
@@ -95961,7 +96009,6 @@ async function buildProgram() {
   registerCommand(program3, withKernelOptions((await Promise.resolve().then(() => (init_token(), exports_token))).default));
   registerCommand(program3, withKernelOptions((await Promise.resolve().then(() => (init_get(), exports_get))).default));
   registerCommand(program3, withKernelOptions((await Promise.resolve().then(() => (init_mutate4(), exports_mutate))).default));
-  registerCommand(program3, withKernelOptions((await Promise.resolve().then(() => (init_ls(), exports_ls))).default));
   registerCommand(program3, withKernelOptions((await Promise.resolve().then(() => (init_describe(), exports_describe))).default));
   registerCommand(program3, withKernelOptions((await Promise.resolve().then(() => (init_query7(), exports_query))).default));
   registerCommand(program3, withKernelOptions((await Promise.resolve().then(() => (init_logs(), exports_logs))).default));
@@ -96049,7 +96096,7 @@ async function buildProgram() {
   program3.addHelpText("after", `
 Command groups:
   Getting started  setup     (sign in, pick an instance, equip your workspace)
-  Kernel        ls, get, mutate, call, query, describe, token
+  Kernel        get, mutate, call, query, describe, token
   Management    admin, instance, domain, identity, auth, idp, update
   Agent         browser   (drive the GUI via agent-browser)
   Studio        studio    (launch the local Domain Studio GUI for a workspace)
@@ -96063,7 +96110,6 @@ Path syntax:
   @nodeId::method                Instance method on a node by UID
 
 Examples:
-  $ astrale ls @note --edge /:notes.example.dev:class.references
   $ astrale studio
   $ astrale admin status
   $ astrale update --check

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/cli",
-  "version": "0.8.1-alpha.2",
+  "version": "0.8.1-alpha.4",
   "description": "Astrale CLI — connect to existing Astrale kernels",
   "keywords": [
     "astrale",

package/src/commands/__tests__/call-describe.test.ts

@@ -0,0 +1,67 @@
+import { Path } from '@astrale-os/sdk/graph/path'
+import { describe, expect, test } from 'bun:test'
+
+import { describeCallableFromSchema } from '../call-describe'
+
+const schema = {
+  classes: {
+    Manager: {
+      methods: {
+        createInstance: {
+          auth: 'authorized',
+          description: 'Create one child Instance.',
+          input: { type: 'object', required: ['operationId', 'slug'] },
+          output: { mode: 'value' },
+        },
+      },
+    },
+  },
+  functions: {
+    journal: {
+      description: 'Read the authorized Kernel journal.',
+      input: { type: 'object' },
+    },
+  },
+}
+
+describe('describeCallableFromSchema', () => {
+  test('reads a static Class method from the Domain schema', () => {
+    const described = describeCallableFromSchema(
+      Path.parse('/:host.astrale.ai:class.Manager:createInstance'),
+      schema,
+    )
+    expect(described).toMatchObject({
+      origin: 'host.astrale.ai',
+      class: 'Manager',
+      method: 'createInstance',
+      dispatch: 'static',
+      description: 'Create one child Instance.',
+      auth: 'authorized',
+    })
+    expect(described?.input).toMatchObject({ required: ['operationId', 'slug'] })
+  })
+
+  test('finds an instance method when the receiver Path is not a Class projection', () => {
+    expect(
+      describeCallableFromSchema(
+        Path.parse('/:host.astrale.ai:core.manager::createInstance'),
+        schema,
+      ),
+    ).toMatchObject({
+      origin: 'host.astrale.ai',
+      class: 'Manager',
+      method: 'createInstance',
+      dispatch: 'instance',
+    })
+  })
+
+  test('reads a standalone Function from the Domain schema', () => {
+    expect(
+      describeCallableFromSchema(Path.parse('/:kernel.astrale.ai:function.journal'), schema),
+    ).toMatchObject({
+      origin: 'kernel.astrale.ai',
+      function: 'journal',
+      description: 'Read the authorized Kernel journal.',
+    })
+  })
+})

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

@@ -0,0 +1,20 @@
+import { describe, expect, test } from 'bun:test'
+
+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',
+      domains: [
+        {
+          source: {
+            kind: 'remote',
+            url: 'https://tasks.example.test',
+            token: 'secret',
+          },
+        },
+      ],
+    })
+  })
+})

package/src/commands/__tests__/instance-list-admin.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, test } from 'bun:test'
+
+import { AstraleError } from '../../errors'
+import { adminInventoryUnavailable } from '../instance/list'
+
+describe('adminInventoryUnavailable', () => {
+  test('turns key-backed Admin exchange failures into a bookmark-only instruction', () => {
+    const error = adminInventoryUnavailable(
+      new AstraleError(
+        'TOKEN_EXCHANGE_SOURCE_INVALID',
+        'The source identity credential has no valid expiration.',
+      ),
+    )
+    expect(error.code).toBe('ADMIN_INVENTORY_UNAVAILABLE')
+    expect(error.message).toContain('Admin is not deployed')
+    expect(error.hint).toContain('instance list --bookmarked')
+  })
+
+  test('turns a missing Admin Domain issuer into the same instruction', () => {
+    const error = adminInventoryUnavailable(
+      new AstraleError('ADMIN_DOMAIN_ISSUER_MISSING', 'no Domain issuer'),
+    )
+    expect(error.code).toBe('ADMIN_INVENTORY_UNAVAILABLE')
+    expect(error.hint).toContain('Key-backed identities cannot mint an Admin Domain token')
+  })
+})