@astrale-os/cli 0.4.0-alpha.13 → 0.5.0-alpha.0

package/src/commands/describe.ts

@@ -2,20 +2,21 @@ import { ClassPath } from '@astrale-os/kernel-core/domain'
 import chalk from 'chalk'
 
 import type { CommandDefinition } from '../command'
-import type { KernelCommandOpts } from '../kernel'
-
-import { expandSelfInPath, extractItems, runKernelCommand, withSelfHint } from '../kernel'
+import type { GraphNode, KernelCommandOpts } from '../kernel'
+
+import {
+  bindGraph,
+  expandSelfInPath,
+  nodeProp,
+  runKernelCommand,
+  splitRoot,
+  unqualifyKey,
+  withSelfHint,
+} from '../kernel'
 import { log } from '../lib/log'
 import { output } from '../lib/output'
 
-type NodeItem = {
-  id?: string
-  slug?: string
-  class?: string
-  properties?: Record<string, unknown>
-}
-
-type DescribeResult = { node: NodeItem; children: NodeItem[] }
+type DescribeResult = { node: GraphNode | undefined; children: GraphNode[] }
 
 // Commander turns `--no-schema` into `schema: false`.
 type DescribeOpts = KernelCommandOpts & { schema?: boolean }
@@ -32,27 +33,18 @@ export async function describeCommand(path: string, opts: DescribeOpts): Promise
   await runKernelCommand<DescribeResult>({
     opts,
     label: expandedPath,
+    // One function.get depth:1 = the node AND its children (was ::get +
+    // ::listChildren). Function-class children are the node's operations.
     fn: async (ctx) => {
-      const node = (await withSelfHint(
-        () => ctx.client.call(`${expandedPath}::get`, {}),
+      const result = await withSelfHint(
+        () => bindGraph(ctx).query((q) => q.from(expandedPath).children()),
         meta,
-      )) as NodeItem
-
-      let children: NodeItem[] = []
-      try {
-        const result = await withSelfHint(
-          () => ctx.client.call(`${expandedPath}::listChildren`, {}),
-          meta,
-        )
-        children = extractItems<NodeItem>(result)
-      } catch {
-        // Node may have no children (leaf node)
-      }
-
-      return { node, children }
+      )
+      const { root, children } = splitRoot(result.wire.nodes, expandedPath)
+      return { node: root, children }
     },
     format: (result, fmtOpts, isRaw) => {
-      const shown = opts.schema === false ? stripSchemaProp(result) : result
+      const shown = opts.schema === false ? stripSchema(result) : result
       if (isRaw) {
         output(shown, fmtOpts)
         return
@@ -62,23 +54,21 @@ export async function describeCommand(path: string, opts: DescribeOpts): Promise
   })
 }
 
-function stripSchemaProp(result: DescribeResult): DescribeResult {
-  const props = result.node.properties
-  if (!props || !('schema' in props)) return result
-  const { schema: _omitted, ...rest } = props
-  return { ...result, node: { ...result.node, properties: rest } }
+function stripSchema(result: DescribeResult): DescribeResult {
+  if (!result.node) return result
+  const entries = Object.entries(result.node.props).filter(([k]) => unqualifyKey(k) !== 'schema')
+  return { ...result, node: { ...result.node, props: Object.fromEntries(entries) } }
 }
 
 // ── Pretty-print ────────────────────────────────────────────
 
 function printDescribe({ node, children }: DescribeResult, path: string): void {
   const kind = classNameOf(node) ?? 'Node'
-  const slug = node.properties?.slug ?? node.slug ?? path.split('/').pop()
-  console.log(`  ${chalk.bold.cyan(String(slug))} ${chalk.dim(`(${kind})`)}`)
+  const name = basename(path) || path
+  console.log(`  ${chalk.bold.cyan(name)} ${chalk.dim(`(${kind})`)}`)
 
-  if (node.properties?.description) {
-    console.log(`  ${chalk.dim(String(node.properties.description))}`)
-  }
+  const description = nodeProp(node, 'description')
+  if (description) console.log(`  ${chalk.dim(String(description))}`)
   console.log('')
 
   const operations = children.filter(isFunction)
@@ -86,12 +76,13 @@ function printDescribe({ node, children }: DescribeResult, path: string): void {
 
   if (operations.length > 0) {
     console.log(`  ${chalk.bold('Operations:')}`)
-    const slugW = Math.max(4, ...operations.map((o) => (o.slug ?? '').length))
-    for (const op of operations) {
-      const opSlug = (op.slug ?? '?').padEnd(slugW)
-      const schema = formatInputSchema(op.properties)
-      console.log(`    ${chalk.green(opSlug)}  ${chalk.dim(schema)}`)
-    }
+    const names = operations.map((o) => basename(o.path))
+    const slugW = Math.max(4, ...names.map((n) => n.length))
+    operations.forEach((op, i) => {
+      const opName = names[i].padEnd(slugW)
+      const schema = formatInputSchema(op)
+      console.log(`    ${chalk.green(opName)}  ${chalk.dim(schema)}`)
+    })
     console.log('')
   }
 
@@ -99,7 +90,7 @@ function printDescribe({ node, children }: DescribeResult, path: string): void {
     console.log(`  ${chalk.bold('Children:')}`)
     for (const child of otherChildren) {
       const childKind = classNameOf(child) ?? '?'
-      console.log(`    ${chalk.cyan(child.slug ?? '?')}  ${chalk.dim(childKind)}`)
+      console.log(`    ${chalk.cyan(basename(child.path) || '?')}  ${chalk.dim(childKind)}`)
     }
     console.log('')
   }
@@ -109,18 +100,26 @@ function printDescribe({ node, children }: DescribeResult, path: string): void {
   }
 }
 
+/** `/a/b/c` → `c`; `/` → `/`. */
+function basename(path?: string): string {
+  if (!path || path === '/') return path ?? ''
+  return path.slice(path.lastIndexOf('/') + 1)
+}
+
 /** Short class name from the contract field `class` (a serialized ClassPath). */
-function classNameOf(item: NodeItem): string | undefined {
-  return item.class ? (ClassPath.tryParse(item.class)?.className ?? undefined) : undefined
+function classNameOf(item: GraphNode | undefined): string | undefined {
+  return item?.class ? (ClassPath.tryParse(item.class)?.className ?? undefined) : undefined
 }
 
-function isFunction(item: NodeItem): boolean {
+function isFunction(item: GraphNode): boolean {
   return classNameOf(item) === 'Function'
 }
 
-function printProperties(node: NodeItem): void {
-  const props = node.properties ?? (node as Record<string, unknown>)
-  const entries = Object.entries(props).filter(([k]) => k !== '__labels' && k !== 'id')
+function printProperties(node: GraphNode | undefined): void {
+  if (!node) return
+  const entries = Object.entries(node.props)
+    .map(([k, v]) => [unqualifyKey(k), v] as const)
+    .filter(([k]) => k !== '__labels' && k !== 'id')
   if (entries.length === 0) return
 
   console.log(`  ${chalk.bold('Properties:')}`)
@@ -130,9 +129,8 @@ function printProperties(node: NodeItem): void {
   }
 }
 
-function formatInputSchema(properties?: Record<string, unknown>): string {
-  if (!properties) return '{}'
-  const raw = properties.inputSchema
+function formatInputSchema(node: GraphNode): string {
+  const raw = nodeProp(node, 'inputSchema')
   if (!raw) return '{}'
 
   try {
@@ -160,9 +158,10 @@ export default {
   description: 'Describe a node: its kind, operations, children, and schemas',
   afterHelpText: `
 Behavior:
-  Raw node dump: full properties + children. For Domain nodes this
-  includes a multi-kB serialized 'schema' — use --no-schema, and pipe
-  to jq rather than reading by eye (it is not a curated summary).
+  One function.get depth:1 — the node plus its children (Function-class
+  children are shown as Operations). Raw dump: full properties + children.
+  For Domain nodes the properties include a multi-kB serialized 'schema' —
+  use --no-schema, and pipe to jq rather than reading by eye.
 
 Examples:
   $ astrale describe /kernel.astrale.ai
@@ -177,6 +176,6 @@ Examples:
     },
   ],
   action: async (path, opts) => {
-    await describeCommand(path as string, opts as Parameters<typeof describeCommand>[1])
+    await describeCommand(path as string, opts as DescribeOpts)
   },
 } satisfies CommandDefinition

package/src/commands/domain/install.ts

@@ -26,7 +26,7 @@ type DomainInstallResult = {
   error?: string | null
 }
 
-/** Mirrors the kernel's `Root.installDomain` return. */
+/** Mirrors the kernel's `Domain.install` return. */
 type DirectInstallResult = { domainId: string; origin: string }
 
 type InstallOpts = KernelCommandOpts &
@@ -50,7 +50,7 @@ Behavior:
   interactively. The target instance is the active one, or -i <slug>; it must be
   admin-managed (otherwise the command fails loudly and points you at --direct).
 
-  --direct: installs a url STRAIGHT onto the instance kernel (Root.installDomain),
+  --direct: installs a url STRAIGHT onto the instance kernel (Domain.install),
   bypassing the admin/catalog. Works on any instance you can authenticate to
   (managed, bookmarked, or local), using your own authority. This is the only
   mode that runs the identity-override consent gate: when the domain's declared
@@ -260,7 +260,7 @@ async function activeSlug(): Promise<string | undefined> {
 // ── Direct path (--direct) ────────────────────────────────────────────────────
 
 /**
- * Install a url straight onto the instance kernel (`Root.installDomain`),
+ * Install a url straight onto the instance kernel (`Domain.install`),
  * bypassing the admin/catalog — the classic path, with the §5 identity-override
  * consent gate. Works on any instance the caller can authenticate to.
  */
@@ -290,7 +290,7 @@ async function installDirect(target: string | undefined, opts: InstallOpts): Pro
     opts,
     label: `Installing domain from ${url}`,
     fn: async (ctx) =>
-      (await ctx.client.call(K.Root.installDomain.path.method.raw, {
+      (await ctx.client.call(K.Domain.install.path.method.raw, {
         url,
         ...(opts.token ? { token: opts.token } : {}),
       })) as DirectInstallResult,

package/src/commands/get.ts

@@ -1,29 +1,46 @@
 import type { CommandDefinition } from '../command'
 import type { KernelCommandOpts } from '../kernel'
 
-import { expandSelfInPath, runKernelCommand, withSelfHint } from '../kernel'
+import { bindGraph, expandSelfInPath, runKernelCommand, withSelfHint } from '../kernel'
 import { log } from '../lib/log'
 import { output } from '../lib/output'
 
-type GetOpts = KernelCommandOpts & { long?: boolean }
+type GetOpts = KernelCommandOpts & {
+  long?: boolean
+}
 
 const INTERNAL_KEYS = new Set(['__labels', 'classId'])
 
-export async function getCommand(path: string, opts: GetOpts): Promise<void> {
-  let expandedPath: string
+export async function getCommand(pathArg: string, opts: GetOpts): Promise<void> {
+  if (!pathArg) {
+    log.error('Usage: astrale get <path>')
+    process.exit(1)
+    return
+  }
+
+  let path: string
   let meta
   try {
-    ;({ path: expandedPath, meta } = await expandSelfInPath(path, opts))
+    ;({ path, meta } = await expandSelfInPath(pathArg, opts))
   } catch (e) {
     log.error(e instanceof Error ? e.message : 'Invalid @self expansion')
     process.exit(1)
+    return
   }
+
   await runKernelCommand({
     opts,
-    label: `Node ${expandedPath}`,
-    fn: (ctx) => withSelfHint(() => ctx.client.call(`${expandedPath}::get`, {}), meta),
-    format: (result, fmtOpts) => {
-      output(opts.long ? result : cleanNode(result), fmtOpts)
+    label: 'Node ' + path,
+    fn: async (ctx) => {
+      const node = await withSelfHint(() => bindGraph(ctx).get(path), meta)
+      if (node === null) {
+        log.error('node "' + path + '" not found or not visible')
+        process.exit(1)
+      }
+      return node
+    },
+    format: (node, fmtOpts) => {
+      output(opts.long ? node : cleanNode(node), fmtOpts)
     },
   })
 }
@@ -40,21 +57,29 @@ function cleanNode(data: unknown): unknown {
 
 export default {
   name: 'get',
-  description: 'Get a node by path or ID',
-  afterHelpText: `
-Behavior:
-  Accepts a tree path (/domain/class.Name) or an id (@nodeId). -l adds
-  the internal fields (__labels, classId) hidden in the summary view.
-
-Examples:
-  $ astrale get /kernel.astrale.ai/class.Root
-  $ astrale get @abc123 -l
-`,
+  description: 'Get one node by path or id',
+  afterHelpText: [
+    '',
+    'Behavior:',
+    '  Point read through the kernel-client GraphApi.get shorthand. Accepts exactly',
+    '  one node path (tree path /domain/class.Name, or an id @nodeId). @self is',
+    '  expanded before dispatch. Missing and masked nodes share one opaque error:',
+    '  node "<path>" not found or not visible.',
+    '',
+    '  Output is the historical flat wire node projection { id, class, path, props }.',
+    '  Add -l to keep the internal fields (__labels, classId). Richer reads -',
+    '  multiple roots, child expansion, edge expansion, cursors, or full GraphData -',
+    '  live on astrale query.',
+    '',
+    'Examples:',
+    '  $ astrale get /kernel.astrale.ai/class.Root',
+    '  $ astrale get @abc123 -l',
+    '  $ astrale get @self --json',
+    '',
+  ].join('\n'),
   arguments: [{ name: 'path', description: 'Node path (/domain/Class) or ID (@nodeId)' }],
-  options: [
-    { flags: '-l, --long', description: 'Include all internal fields (__labels, classId)' },
-  ],
+  options: [{ flags: '-l, --long', description: 'Include internal fields (__labels, classId)' }],
   action: async (path, opts) => {
-    await getCommand(path as string, opts as Parameters<typeof getCommand>[1])
+    await getCommand(path as string, opts as GetOpts)
   },
 } satisfies CommandDefinition

package/src/commands/identity/register.ts

@@ -1,11 +1,10 @@
-import { K } from '@astrale-os/kernel-core'
 import { importJWK, SignJWT, type JWK } from 'jose'
 import { readFile } from 'node:fs/promises'
 
 import type { CommandDefinition } from '../../command'
-import type { KernelCommandOpts } from '../../kernel'
+import type { ClientContext, KernelCommandOpts } from '../../kernel'
 
-import { runKernelCommand } from '../../kernel'
+import { bindGraph, runKernelCommand } from '../../kernel'
 import { KERNEL_PASSTHROUGH_OPTIONS } from '../../kernel/options'
 import { getIdentity, setRegistration } from '../../lib/identity'
 import { getActive } from '../../lib/instance'
@@ -13,7 +12,6 @@ import { fileExists, keypairPaths } from '../../lib/keys'
 import { fatal, log } from '../../lib/log'
 import { output } from '../../lib/output'
 
-type CreateNodeResult = { id: string; path: string }
 type RegisterIdentityResult = { iss: string; sub: string }
 
 type RegisterOpts = KernelCommandOpts & {
@@ -27,37 +25,32 @@ async function readJwk(path: string): Promise<JWK> {
   return JSON.parse(raw) as JWK
 }
 
-type ChildNode = { class?: string; path?: string }
-
 /**
  * Discover the identity-bearer class on the target instance: find the
- * installed distribution domain (whatever its origin — `dist.astrale.ai` in
- * prod, `dist.localhost` locally) and address its `User` class semantically.
+ * installed domain that owns a `User` class (workspace on managed instances)
+ * and address it semantically.
  * The bearer class must exist before a non-root identity can be registered;
  * failing here names the real problem instead of surfacing as a confusing
- * permission error on a hardcoded prod origin.
+ * permission error on a hardcoded origin.
  */
-async function resolveUserClassPath(ctx: {
-  client: { call(path: string, params: unknown): Promise<unknown> }
-}): Promise<string> {
-  const children = (await ctx.client.call('/::listChildren', {})) as ChildNode[]
-  const domains = children
-    .filter((c) => typeof c.class === 'string' && c.class.endsWith(':class.Domain'))
-    .map((c) => (c.path ?? '').replace(/^\//, ''))
+async function resolveUserClassPath(ctx: ClientContext): Promise<string> {
+  const graph = bindGraph(ctx)
+  // Root's direct children are the installed Domain nodes.
+  const result = await graph.children('/')
+  const domains = result.nodes
+    .filter((n) => n.class.className === 'Domain')
+    .map((n) => n.path.raw.replace(/^\//, ''))
     .filter(Boolean)
   for (const origin of domains) {
-    try {
-      // The class materializes as a `class.User` Folder under the domain mount;
-      // a resolvable read means the domain declares it.
-      await ctx.client.call(`/${origin}/class.User::get`, {})
+    // The class materializes as a `class.User` Folder under the domain mount;
+    // a resolving node means the domain declares it (null when absent).
+    if (await graph.get(`/${origin}/class.User`)) {
       return `/:${origin}:class.User`
-    } catch {
-      // This domain has no User class — try the next one.
     }
   }
   throw new Error(
     'No installed domain declares a `User` class on this instance — registering a ' +
-      'non-root identity needs an identity-bearer class (install the distribution ' +
+      'non-root identity needs an identity-bearer class (install workspace or another ' +
       'domain, or pass --class <classPath> explicitly).',
   )
 }
@@ -85,7 +78,7 @@ export default {
     {
       flags: '--class <classPath>',
       description:
-        'Class path of the identity node to create (default: /:dist.<origin>:class.User when distribution is installed)',
+        'Class path of the identity node to create (default: the installed domain that declares class.User)',
     },
     {
       flags: '--path <nodePath>',
@@ -127,23 +120,24 @@ export default {
 
           const classPath = opts.class ?? (await resolveUserClassPath(ctx))
 
-          // A bare `astrale identity create <name>` carries no profile, but the
-          // bearer class may require one (distribution's User wants
-          // firstName/lastName) — default both to the identity name so a dev
+          // A bare `astrale identity create <name>` carries no profile, but a
+          // User bearer class may require one. Default both names so a dev
           // registration works out of the box; `--props` overrides.
           const extraProps = opts.props ? (JSON.parse(opts.props) as Record<string, unknown>) : {}
           const userDefaults = classPath.endsWith(':class.User')
             ? { firstName: name, lastName: name }
             : {}
 
-          const node = (await ctx.client.call(K.Node.createNode.path.method.raw, {
-            class: classPath,
-            path: nodePath,
-            props: { 'Statused.status': 'creating', ...userDefaults, ...extraProps },
-          })) as CreateNodeResult
+          // One-arm create through function.mutate; the minted node id comes
+          // back in createdNodes (keyed by the `at` path).
+          const nodeId = await bindGraph(ctx).createNode(classPath, nodePath, {
+            'Statused.status': 'creating',
+            ...userDefaults,
+            ...extraProps,
+          })
 
           const bootstrap = await mintBootstrapJwt(privateJwk)
-          const result = (await ctx.client.call(`@${node.id}::registerIdentity`, {
+          const result = (await ctx.client.call(`@${nodeId}::registerIdentity`, {
             signingKey: {
               publicKey: { jwk: publicJwk },
               credential: bootstrap,

package/src/commands/logs.ts

@@ -1,9 +1,9 @@
 import type { JournalEntry, JournalFilter } from '@astrale-os/kernel-core'
 
 /**
- * `astrale logs` — tail the kernel event journal (Root.journal) for the target
+ * `astrale logs` — tail the kernel event journal (function.journal) for the target
  * instance. Defaults to the kernel journal syscall
- * `/kernel.astrale.ai/class.Root/journal`; `--service <name>` switches to the
+ * `/kernel.astrale.ai/functions/journal`; `--service <name>` switches to the
  * per-instance `services` domain log buffer (the historical behavior).
  *
  * Target the instance with `-i <instance>` (inherited from withKernelOptions).
@@ -18,13 +18,13 @@ import { runKernelCommand, withKernelClient } from '../kernel'
 import { fatal, withSpinner } from '../lib/log'
 import { isMachine, output, presentList } from '../lib/output'
 
-const ROOT_JOURNAL_PATH = '/kernel.astrale.ai/class.Root/journal'
+const JOURNAL_FN_PATH = '/kernel.astrale.ai/functions/journal'
 const DEFAULT_SERVICES_ORIGIN = 'services.astrale.ai'
 const DEFAULT_LIMIT = 200
 const FOLLOW_INTERVAL_MS = 2000
 // The journal-read syscall journals its own ops; hide them by default so polling
 // doesn't self-pollute the view. `--all` shows them.
-const SELF_READ_PREFIX = 'op:class.Root.method.journal:'
+const SELF_READ_PREFIX = 'op:function.journal:'
 
 // The published @astrale-os/kernel-core@0.5.0 JournalFilter has no `cursor` yet
 // (added on the kernel branch). Type against the augmented shape so the
@@ -48,7 +48,7 @@ type LogsOpts = KernelCommandOpts & {
 }
 
 /**
- * Kernel journal page. The Root.journal syscall returns a BARE `JournalEntry[]`;
+ * Kernel journal page. The function.journal syscall returns a BARE `JournalEntry[]`;
  * the client derives the next cursor from the max `seq`. We still model a
  * `nextCursor` field so the TTY footer / incremental tail share one shape, and
  * so a future paged kernel response degrades gracefully.
@@ -58,7 +58,7 @@ type EventsPage = {
   nextCursor?: number | null
 }
 
-// ── Root.journal (default) ───────────────────────────────────
+// ── function.journal (default) ───────────────────────────────────
 
 /** The highest `seq` across entries, or null when empty. */
 function maxSeq(entries: JournalEntry[]): number | null {
@@ -177,7 +177,7 @@ function eventsProjection(entries: JournalEntry[], showTiming = false): ListProj
 }
 
 async function fetchEventsPage(ctx: ClientContext, opts: LogsOpts): Promise<EventsPage> {
-  const raw = await ctx.client.call(ROOT_JOURNAL_PATH, buildEventsParams(opts))
+  const raw = await ctx.client.call(JOURNAL_FN_PATH, buildEventsParams(opts))
   const page = normalizePage(raw)
   // Strip the journal's own read ops by default (but keep nextCursor past them).
   const entries = opts.all
@@ -313,7 +313,7 @@ export default {
     },
   ],
   afterHelpText: `
-Default: tails the kernel event journal via ${ROOT_JOURNAL_PATH} on the target
+Default: tails the kernel event journal via ${JOURNAL_FN_PATH} on the target
 instance (-i <instance>). Topics use ':'-segmented globs ('*' one segment,
 '**' zero-or-more). Machine output (--json / pipe) emits the JournalEntry[]
 array; a TTY shows a SEQ/TIME/TOPIC/LATENCY/PRINCIPAL table (LATENCY is the