@astrale-os/cli 0.8.0-alpha.0 → 0.8.1-alpha.2

package/src/commands/auth/logout.ts

@@ -1,9 +1,10 @@
-import type { CommandDefinition } from '../../command'
+import type { CommandDefinition } from '../../program/index'
 
-import { getDefault, readIdentities } from '../../lib/identity'
+import { getDefault, readIdentities } from '../../identity/index'
 import { deleteIdpSession, listIdpSessions } from '../../lib/idp'
 import { log } from '../../lib/log'
 import { output, RAW_OUTPUT_OPTIONS } from '../../lib/output'
+import { ExchangeCredentialCache } from '../../state/index'
 
 export default {
   name: 'logout',
@@ -28,6 +29,7 @@ export default {
     }
 
     for (const name of names) await deleteIdpSession(name)
+    await new ExchangeCredentialCache().clear()
 
     if (opts.raw || opts.json) {
       output({ cleared: names }, opts)

package/src/commands/auth/status.ts

@@ -1,9 +1,9 @@
 import chalk from 'chalk'
 
-import type { CommandDefinition } from '../../command'
 import type { ListOpts, ListProjection } from '../../lib/output'
+import type { CommandDefinition } from '../../program/index'
 
-import { readIdentities } from '../../lib/identity'
+import { readIdentities } from '../../identity/index'
 import { isSessionExpired, listIdpSessions } from '../../lib/idp'
 import { log } from '../../lib/log'
 import { isMachine, presentList, RAW_OUTPUT_OPTIONS } from '../../lib/output'

package/src/commands/auth/token.ts

@@ -1,6 +1,6 @@
-import type { CommandDefinition } from '../../command'
+import type { CommandDefinition } from '../../program/index'
 
-import { getDefault, getIdentity, readIdentities } from '../../lib/identity'
+import { getDefault, getIdentity, readIdentities } from '../../identity/index'
 import { isSessionExpired, readIdpSession, type IdpSession } from '../../lib/idp'
 import { ensureFreshSession } from '../../lib/idp-session'
 import { log } from '../../lib/log'

package/src/commands/browser.ts

@@ -1,7 +1,7 @@
 import chalk from 'chalk'
 import { existsSync } from 'node:fs'
 
-import type { CommandDefinition } from '../command'
+import type { CommandDefinition } from '../program/index'
 
 import {
   ab,

package/src/commands/call.ts

@@ -1,59 +1,40 @@
-import { K } from '@astrale-os/kernel-core'
+import { Path } from '@astrale-os/sdk/graph/path'
 
-import type { CommandDefinition } from '../command'
-import type { CallCommandOpts, ClientContext, SelfExpansionMeta } from '../kernel'
+import type { ConnectionContext, KernelCommandOpts } from '../connection'
+import type { CommandDefinition } from '../program/index'
 
-import {
-  bindGraph,
-  buildSelfContext,
-  nodeProp,
-  resolveSelfIdLazy,
-  runKernelCommand,
-  withSelfHint,
-} from '../kernel'
-import { presentBinary, type BinaryLike } from '../lib/binary'
+import { createPathCall, expandSelfInCall, runKernelCommand, withSelfHint } from '../connection'
+import { nodeProperty } from '../graph/index'
+import { presentBinary } from '../lib/binary'
 import { log } from '../lib/log'
 import { output, present } from '../lib/output'
-import { containsSelfRef, expandSelfReferences } from '../lib/self'
 
-type CallOpts = CallCommandOpts & { describe?: boolean; dryRun?: boolean; output?: string }
+type CallOpts = KernelCommandOpts & {
+  data?: string
+  describe?: boolean
+  dryRun?: boolean
+  output?: string
+}
 
-/** A call resolves to either a JSON value or a binary response. */
-type CallResult = { kind: 'binary'; response: BinaryLike } | { kind: 'value'; value: unknown }
+type CallResult = Awaited<ReturnType<ConnectionContext['session']['dispatch']>>
+type MaterializedCallResult =
+  | Exclude<CallResult, { readonly kind: 'stream' }>
+  | { readonly kind: 'stream'; readonly values: readonly unknown[] }
 
 export async function callCommand(
   path: string,
   rawParams: string[],
   opts: CallOpts,
 ): Promise<void> {
-  // Expand @self before describe/execute so refusals are typed and stale IdP
-  // registrations can refresh through whoami.
-  let expandedPath = path
-  let expandedRaw = rawParams
-  let selfMeta: SelfExpansionMeta | undefined
-  const inputsHaveSelf = containsSelfRef(path) || rawParams.some(containsSelfRef)
-  if (inputsHaveSelf) {
-    try {
-      const selfCtx = await buildSelfContext(opts)
-      const selfId = await resolveSelfIdLazy(selfCtx, opts)
-      expandedPath = expandSelfReferences(path, selfId)
-      expandedRaw = rawParams.map((p) => expandSelfReferences(p, selfId))
-      // Stale-registration hints apply when @self appears in either path or params.
-      const rawMutated = expandedRaw.some((p, i) => p !== rawParams[i])
-      if (expandedPath !== path || rawMutated) {
-        selfMeta = {
-          original: path,
-          expanded: expandedPath,
-          selfId,
-          identity: selfCtx.identity?.name,
-          slug: selfCtx.instanceSlug,
-        }
-      }
-    } catch (e) {
-      log.error(e instanceof Error ? e.message : 'Invalid @self expansion')
-      process.exit(1)
-    }
+  // Expand @self before describe/execute through authenticated Identity.whoami.
+  let expanded: Awaited<ReturnType<typeof expandSelfInCall>>
+  try {
+    expanded = await expandSelfInCall(path, rawParams, opts)
+  } catch (error) {
+    log.error(error instanceof Error ? error.message : 'Invalid @self expansion')
+    process.exit(1)
   }
+  const expandedPath = expanded.path
 
   // ── Describe mode: show schema without executing ────────
   // Runs AFTER expansion so `astrale call @self::m --describe` works.
@@ -64,7 +45,7 @@ export async function callCommand(
   // ── Parse params ────────────────────────────────────────
   let params: Record<string, unknown>
   try {
-    params = await parseParams(expandedRaw, opts.data)
+    params = await parseParams([...expanded.parameters], opts.data)
   } catch (e) {
     log.error(e instanceof Error ? e.message : 'Invalid params')
     process.exit(1)
@@ -77,56 +58,39 @@ export async function callCommand(
   }
 
   // ── Execute ────────────────────────────────────────────
-  await runKernelCommand<CallResult>({
+  await runKernelCommand<MaterializedCallResult>({
     opts,
     label: expandedPath,
-    fn: async (ctx): Promise<CallResult> => {
-      // Binary outputs must be routed before dispatch; JSON decoding would corrupt bytes.
-      if (await isBinaryOutput(ctx, expandedPath)) {
-        const response = await withSelfHint(() => ctx.client.binary(expandedPath, params), selfMeta)
-        return { kind: 'binary', response }
-      }
-      const value = await withSelfHint(() => ctx.client.call(expandedPath, params), selfMeta)
-      return { kind: 'value', value }
-    },
+    fn: (ctx) =>
+      withSelfHint(
+        async () =>
+          materializeCallResult(await ctx.session.dispatch(createPathCall(expandedPath, params))),
+        expanded.meta,
+      ),
     format: async (result, fmtOpts) => {
-      if (result.kind === 'binary') {
-        await presentBinary(result.response, fmtOpts, { outFile: opts.output })
-        return
+      switch (result.kind) {
+        case 'value':
+          present(result.value, fmtOpts)
+          return
+        case 'binary':
+          await presentBinary(result.value, fmtOpts, { outFile: opts.output })
+          return
+        case 'stream':
+          output(result.values, fmtOpts)
+          return
+        case 'redirect':
+          throw new Error('Client Session returned an unresolved redirect.')
       }
-      present(result.value, fmtOpts)
     },
   })
 }
 
-/**
- * Best-effort binary preflight. Static paths read the Function node directly;
- * instance paths probe the class method node and fall back to value transport on miss.
- */
-async function isBinaryOutput(ctx: ClientContext, path: string): Promise<boolean> {
-  try {
-    const target = path.includes('::') ? await instanceMethodNodePath(ctx, path) : path
-    if (!target) return false
-    const node = await bindGraph(ctx).get(target)
-    // Props travel under fully-qualified keys; `output.key` IS that key.
-    return node?.props?.[K.$.i('Function').output.key] === 'binary'
-  } catch {
-    return false
-  }
-}
-
-/** `<node>::method` → the method's Function-node MethodPath, via the node's class. */
-async function instanceMethodNodePath(
-  ctx: ClientContext,
-  path: string,
-): Promise<string | undefined> {
-  const sep = path.lastIndexOf('::')
-  const source = path.slice(0, sep)
-  const method = path.slice(sep + 2)
-  if (!source || !method) return undefined
-  const node = await bindGraph(ctx).get(source)
-  // ClassPath + method name forms the class-owned Function MethodPath.
-  return node?.class ? `${node.class.raw}:${method}` : undefined
+/** Drain a session-backed stream before the command-scoped Client Session closes. */
+export async function materializeCallResult(result: CallResult): Promise<MaterializedCallResult> {
+  if (result.kind !== 'stream') return result
+  const values: unknown[] = []
+  for await (const value of result.stream) values.push(value)
+  return Object.freeze({ kind: 'stream', values: Object.freeze(values) })
 }
 
 async function describeOperation(path: string, opts: CallOpts): Promise<void> {
@@ -134,10 +98,10 @@ async function describeOperation(path: string, opts: CallOpts): Promise<void> {
     opts,
     label: `Schema for ${path}`,
     // The Function node carries the schemas as props (function.get depth:0).
-    fn: async (ctx) => await bindGraph(ctx).get(path),
+    fn: async ({ graph }) => await graph.get(Path.parse(path)),
     format: (node, fmtOpts) => {
-      const input = nodeProp(node, 'inputSchema')
-      const outputSchema = nodeProp(node, 'outputSchema')
+      const input = nodeProperty(node, 'inputSchema')
+      const outputSchema = nodeProperty(node, 'outputSchema')
       const schema: Record<string, unknown> = {}
       if (input) schema.input = tryParseJson(input)
       if (outputSchema) schema.output = tryParseJson(outputSchema)
@@ -254,8 +218,8 @@ Self-reference:
   @self expands to your nodeId on the active instance (path head or
   bare param value, e.g. node=@self). --data and stdin payloads are
   sent verbatim — pre-resolve manually to a literal @<nodeId> there
-  (e.g. via 'astrale describe @self -q', or shell-substituted from the
-  registration record in ~/.astrale/identities.json).
+  (e.g. via 'astrale get @self --json'). Resolution authenticates to
+  the selected Kernel and never trusts a local registration or JWT sub.
 
 Examples:
   $ astrale call /:host.astrale.ai:class.KernelInstance:list

package/src/commands/describe.ts

@@ -1,181 +1,86 @@
-import { ClassPath } from '@astrale-os/kernel-core/domain'
+import type { Node } from '@astrale-os/sdk/graph/node'
+
+import { ClassPath } from '@astrale-os/sdk/graph/class'
+import { Path } from '@astrale-os/sdk/graph/path'
 import chalk from 'chalk'
 
-import type { CommandDefinition } from '../command'
-import type { GraphNode, KernelCommandOpts } from '../kernel'
+import type { KernelCommandOpts } from '../connection'
+import type { CommandDefinition } from '../program/index'
 
-import {
-  bindGraph,
-  expandSelfInPath,
-  nodeProp,
-  runKernelCommand,
-  splitRoot,
-  unqualifyKey,
-  withSelfHint,
-} from '../kernel'
+import { expandSelfInPath, runKernelCommand, withSelfHint } from '../connection'
+import { unqualifyProperty } from '../graph/index'
 import { log } from '../lib/log'
 import { output } from '../lib/output'
 
-type DescribeResult = { node: GraphNode | undefined; children: GraphNode[] }
-
-// Commander turns `--no-schema` into `schema: false`.
 type DescribeOpts = KernelCommandOpts & { schema?: boolean }
+type DescribedNode = Omit<Node, 'props'> & { readonly props: Readonly<Record<string, unknown>> }
 
-export async function describeCommand(path: string, opts: DescribeOpts): Promise<void> {
-  let expandedPath: string
+/** Describe only facts present on the canonical Node; no hierarchy is inferred from its Path. */
+export async function describeCommand(target: string, opts: DescribeOpts): Promise<void> {
+  let path: string
   let meta
   try {
-    ;({ path: expandedPath, meta } = await expandSelfInPath(path, opts))
-  } catch (e) {
-    log.error(e instanceof Error ? e.message : 'Invalid @self expansion')
+    ;({ path, meta } = await expandSelfInPath(target, opts))
+  } catch (error) {
+    log.error(error instanceof Error ? error.message : 'Invalid target')
     process.exit(1)
   }
-  await runKernelCommand<DescribeResult>({
+
+  await runKernelCommand({
     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 result = await withSelfHint(
-        () => bindGraph(ctx).query((q) => q.from(expandedPath).children()),
-        meta,
-      )
-      const { root, children } = splitRoot(result.wire.nodes, expandedPath)
-      return { node: root, children }
-    },
-    format: (result, fmtOpts, isRaw) => {
-      const shown = opts.schema === false ? stripSchema(result) : result
-      if (isRaw) {
-        output(shown, fmtOpts)
-        return
-      }
-      printDescribe(shown, expandedPath)
+    label: `Describe ${path}`,
+    fn: ({ graph }) => withSelfHint(() => graph.getOrThrow(Path.parse(path)), meta),
+    format: (node, format, machine) => {
+      const shown = opts.schema === false ? withoutSchema(node) : node
+      if (machine || format.format !== undefined) output(shown, format)
+      else printDescription(path, shown)
     },
   })
 }
 
-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 name = basename(path) || path
-  console.log(`  ${chalk.bold.cyan(name)} ${chalk.dim(`(${kind})`)}`)
-
-  const description = nodeProp(node, 'description')
-  if (description) console.log(`  ${chalk.dim(String(description))}`)
-  console.log('')
-
-  const operations = children.filter(isFunction)
-  const otherChildren = children.filter((c) => !isFunction(c))
-
-  if (operations.length > 0) {
-    console.log(`  ${chalk.bold('Operations:')}`)
-    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('')
-  }
-
-  if (otherChildren.length > 0) {
-    console.log(`  ${chalk.bold('Children:')}`)
-    for (const child of otherChildren) {
-      const childKind = classNameOf(child) ?? '?'
-      console.log(`    ${chalk.cyan(basename(child.path) || '?')}  ${chalk.dim(childKind)}`)
-    }
-    console.log('')
+function withoutSchema(node: Node): DescribedNode {
+  return {
+    ...node,
+    props: Object.fromEntries(
+      Object.entries(node.props).filter(([key]) => unqualifyProperty(key) !== 'schema'),
+    ),
   }
-
-  if (children.length === 0) {
-    printProperties(node)
-  }
-}
-
-/** `/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: GraphNode | undefined): string | undefined {
-  return item?.class ? (ClassPath.tryParse(item.class)?.className ?? undefined) : undefined
-}
-
-function isFunction(item: GraphNode): boolean {
-  return classNameOf(item) === 'Function'
-}
-
-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:')}`)
-  for (const [k, v] of entries) {
-    const val = typeof v === 'string' && v.length > 80 ? v.slice(0, 80) + '...' : String(v)
-    console.log(`    ${chalk.cyan(k)}: ${chalk.dim(val)}`)
-  }
-}
-
-function formatInputSchema(node: GraphNode): string {
-  const raw = nodeProp(node, 'inputSchema')
-  if (!raw) return '{}'
-
-  try {
-    const schema = typeof raw === 'string' ? JSON.parse(raw) : raw
-    if (typeof schema !== 'object' || schema === null) return '{}'
-
-    const props = (schema as { properties?: Record<string, { type?: string }> }).properties
-    if (!props || Object.keys(props).length === 0) return '{}'
-
-    const required = new Set((schema as { required?: string[] }).required ?? [])
-
-    const fields = Object.entries(props).map(([name, def]) => {
-      const type = def?.type ?? '?'
-      return required.has(name) ? `${name}: ${type}` : `${name}?: ${type}`
-    })
-
-    return `{ ${fields.join(', ')} }`
-  } catch {
-    return '{...}'
+function printDescription(target: string, node: DescribedNode): void {
+  console.log(`  ${chalk.bold.cyan(target)}`)
+  console.log(`  ${chalk.dim('id')}     ${node.id}`)
+  console.log(
+    `  ${chalk.dim('class')}  ${ClassPath.name(node.class)} ${chalk.dim(`(${node.class})`)}`,
+  )
+
+  const properties = Object.entries(node.props)
+  if (properties.length === 0) return
+  console.log(`\n  ${chalk.bold('Properties:')}`)
+  for (const [key, value] of properties) {
+    const rendered = typeof value === 'string' ? value : JSON.stringify(value)
+    console.log(`    ${chalk.cyan(unqualifyProperty(key))}: ${chalk.dim(rendered)}`)
   }
 }
 
 export default {
   name: 'describe',
-  description: 'Describe a node: its kind, operations, children, and schemas',
+  description: 'Describe the canonical facts of one node',
   afterHelpText: `
 Behavior:
-  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.
+  Reads one canonical Node and presents its ID, Class, and properties.
+  It does not infer operations or children from path layout. --no-schema
+  omits schema-valued properties from Domain-sized results.
 
 Examples:
-  $ astrale describe /kernel.astrale.ai
-  $ astrale describe /host.astrale.ai --no-schema | jq .
+  $ astrale describe /:kernel.astrale.ai:class.Domain
+  $ astrale describe @self --no-schema
 `,
-  arguments: [{ name: 'path', description: 'Node path (/domain/Class) or ID (@nodeId)' }],
+  arguments: [{ name: 'target', description: 'Canonical Node Path or @id' }],
   options: [
-    {
-      flags: '--no-schema',
-      description:
-        'Omit the serialized `schema` property (useful for Domain nodes, where it is multi-kB)',
-    },
+    { flags: '--no-schema', description: 'Omit properties whose qualified leaf is schema' },
   ],
-  action: async (path, opts) => {
-    await describeCommand(path as string, opts as DescribeOpts)
+  action: async (target, opts) => {
+    await describeCommand(target as string, opts as DescribeOpts)
   },
 } satisfies CommandDefinition