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

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@astrale-os/cli",
-  "version": "0.4.0-alpha.13",
+  "version": "0.5.0-alpha.0",
   "description": "Astrale CLI — connect to existing Astrale kernels",
   "keywords": [
     "astrale",
     "cli"
   ],
-  "license": "MIT",
+  "license": "Apache-2.0",
   "author": "Astrale",
   "repository": {
     "type": "git",
@@ -23,7 +23,8 @@
     "studio/server",
     "studio/shared",
     "studio/client/dist",
-    "studio/package.json"
+    "studio/package.json",
+    "THIRD-PARTY-NOTICES.md"
   ],
   "type": "module",
   "exports": {
@@ -34,22 +35,9 @@
     "access": "public",
     "registry": "https://registry.npmjs.org"
   },
-  "scripts": {
-    "preinstall": "node .check-workspace.cjs",
-    "prepare": "husky",
-    "build": "bun scripts/build.ts",
-    "prepack": "bun scripts/build.ts",
-    "typecheck": "tsgo --noEmit",
-    "lint": "oxlint .",
-    "lint:fix": "oxlint --fix .",
-    "format": "pnpm exec oxfmt --write .",
-    "format:check": "pnpm exec oxfmt --check .",
-    "test": "bun test src",
-    "test:watch": "bun test --watch src"
-  },
   "dependencies": {
-    "@astrale-os/kernel-client": ">=0.2.0 <1.0.0",
-    "@astrale-os/kernel-core": ">=0.4.1 <1.0.0",
+    "@astrale-os/kernel-client": ">=0.3.1 <1.0.0",
+    "@astrale-os/kernel-core": ">=0.7.0 <1.0.0",
     "@inquirer/prompts": "^8.5.2",
     "chalk": "^5.6.2",
     "chokidar": "^4.0.3",
@@ -62,7 +50,7 @@
   },
   "devDependencies": {
     "@astrale-os/ox": ">=0.1.0 <1.0.0",
-    "@astrale/commitlint-config": "jsr:~2.0.1",
+    "@astrale/commitlint-config": "npm:@jsr/astrale__commitlint-config@~2.0.1",
     "@commitlint/cli": "~20.3.1",
     "@commitlint/config-conventional": "~20.3.1",
     "@types/bun": "^1.1.16",
@@ -86,5 +74,15 @@
   "engines": {
     "node": ">=20"
   },
-  "packageManager": "pnpm@10.28.0"
-}
+  "scripts": {
+    "preinstall": "node .check-workspace.cjs",
+    "build": "bun scripts/build.ts",
+    "typecheck": "tsgo --noEmit",
+    "lint": "oxlint .",
+    "lint:fix": "oxlint --fix .",
+    "format": "pnpm exec oxfmt --write .",
+    "format:check": "pnpm exec oxfmt --check .",
+    "test": "bun test src",
+    "test:watch": "bun test --watch src"
+  }
+}

package/src/commands/__tests__/help-contract.test.ts

@@ -6,10 +6,7 @@ import { join } from 'node:path'
 
 import { buildProgram } from '../../program'
 
-// The `astrale-cli` skill claims `astrale --help` is the source of truth and
-// "never drifts". These tests hold that claim to account: the version is
-// single-sourced from package.json, no internal `§` spec anchors leak into
-// rendered help, and the workspace skill mirror stays byte-identical.
+// Help output is the public CLI contract: version, spec anchors, and skill mirror stay in sync.
 
 const cliRoot = join(import.meta.dir, '../../..')
 
@@ -28,9 +25,7 @@ describe('help contract — version is single-sourced', () => {
       readFileSync(join(cliRoot, '.release-please-manifest.json'), 'utf8'),
     ) as Record<string, string>
 
-    // `bin/astrale.ts` -> buildProgram -> .version(pkg.version): asserting the
-    // rendered version equals BOTH JSON sources catches a re-hardcoded literal
-    // and a manifest/package.json divergence (release-please bumps both).
+    // Program version must follow both package.json and release-please metadata.
     expect(program.version()).toBe(pkg.version)
     expect(manifest['.']).toBe(pkg.version)
   })
@@ -92,13 +87,7 @@ describe('help contract — connect-only command surface', () => {
     const program = await buildProgram()
     const names = allCommands(program).map((command) => command.name())
 
-    // 'logs' and 'domain' are NOT in this list anymore: each was once LOCAL
-    // runtime management (the historical `astrale logs`, removed with
-    // start/stop; the historical `astrale domain`, local domain wiring) and each
-    // has since been RECLAIMED for a connect-side meaning through the admin
-    // control plane — `astrale logs <service>` tails a MANAGED service's buffer;
-    // `astrale domain publish` registers an installable domain in the admin's
-    // catalog and `astrale domain install <url>` mounts one on an instance.
+    // `logs` and `domain` have managed/admin meanings, so only retired local-runtime verbs are absent.
     for (const removed of [
       'init',
       'start',
@@ -116,6 +105,30 @@ describe('help contract — connect-only command surface', () => {
   })
 })
 
+describe('help contract — read command split', () => {
+  test('get is point-read only and query owns structured read flags', async () => {
+    const program = await buildProgram()
+    const get = allCommands(program).find((command) => command.name() === 'get')
+    const query = allCommands(program).find((command) => command.name() === 'query')
+    const getHelp = get?.helpInformation() ?? ''
+    const queryHelp = query?.helpInformation() ?? ''
+
+    expect(getHelp).toContain('Usage: astrale get [options] <path>')
+    expect(getHelp).toContain('-l, --long')
+    expect(getHelp).not.toContain('--depth')
+    expect(getHelp).not.toContain('--children')
+    expect(getHelp).not.toContain('--edges')
+    expect(getHelp).not.toContain('--graph')
+
+    expect(queryHelp).toContain('Usage: astrale query [options] [paths...]')
+    expect(queryHelp).toContain('--depth <n>')
+    expect(queryHelp).toContain('--children <json>')
+    expect(queryHelp).toContain('--edges <json>')
+    expect(queryHelp).toContain('--ast <json>')
+    expect(queryHelp).toContain('--cypher <query>')
+  })
+})
+
 describe('help contract — skill is single-source, not duplicated', () => {
   const canonical = join(cliRoot, 'skills/astrale-cli/SKILL.md')
   // Workspace mirror lives in the superrepo, outside this submodule. Absent

package/src/commands/__tests__/install-identity-override.test.ts

@@ -11,7 +11,7 @@ describe('admin-path target classification', () => {
   test('a bare origin installs by catalog origin (the unique registry key)', () => {
     expect(domainRefFromTarget('crm.acme.dev')).toEqual({ origin: 'crm.acme.dev' })
     // A host:port that is not a url is still an origin, not a url.
-    expect(domainRefFromTarget('dist.astrale.ai')).toEqual({ origin: 'dist.astrale.ai' })
+    expect(domainRefFromTarget('example.astrale.ai')).toEqual({ origin: 'example.astrale.ai' })
   })
 })
 
@@ -23,7 +23,7 @@ describe('identity-override detection', () => {
 
   test('origin differing from the serving host is an override', () => {
     // The spec §5 attack shape: a fork on workers.dev claiming a well-known origin.
-    expect(isIdentityOverride('distribution.astrale.ai', 'crm.workers.dev')).toBe(true)
+    expect(isIdentityOverride('workspace.astrale.ai', 'crm.workers.dev')).toBe(true)
     // The scaffold default also aliases until the placeholder origin is edited.
     expect(isIdentityOverride('hldom.example.dev', 'hldom-example-dev.acme.workers.dev')).toBe(true)
   })

package/src/commands/__tests__/ls.test.ts

@@ -7,7 +7,7 @@ import { basename, classNameOf } from '../ls'
 // `path` (absolute) and `class` (serialized ClassPath).
 describe('ls — display projection (slug-bug regression)', () => {
   test('basename derives the display name from the absolute path', () => {
-    expect(basename('/dist.astrale.ai')).toBe('dist.astrale.ai')
+    expect(basename('/example.astrale.ai')).toBe('example.astrale.ai')
     expect(basename('/kernel.astrale.ai')).toBe('kernel.astrale.ai')
     expect(basename('/')).toBe('/')
     expect(basename(undefined)).toBe('')

package/src/commands/__tests__/read-commands.test.ts

@@ -0,0 +1,201 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from 'bun:test'
+
+type Wire = { nodes: unknown[]; edges: unknown[]; roots: string[]; next?: Record<string, unknown> }
+type RunOpts = {
+  opts: Record<string, unknown>
+  fn: (ctx: { client: { call: typeof clientCallMock } }) => Promise<unknown>
+  format?: (result: unknown, opts: Record<string, unknown>, isRaw: boolean) => void | Promise<void>
+}
+
+class ExitError extends Error {
+  constructor(readonly code: string | number | null | undefined) {
+    super('process.exit(' + String(code) + ')')
+  }
+}
+
+const emptyWire = (): Wire => ({ nodes: [], edges: [], roots: [] })
+
+let stdout = ''
+let errors: string[] = []
+let originalStdoutWrite: typeof process.stdout.write
+let originalConsoleError: typeof console.error
+let originalExit: typeof process.exit
+let queryAsts: unknown[] = []
+let getPaths: string[] = []
+let queryResult: { wire: Wire } = { wire: emptyWire() }
+let getResult: unknown = null
+let clientCallResult: unknown = { rows: [] }
+
+const clientCallMock = mock(async () => clientCallResult)
+const queryMock = mock(async (ast: unknown) => {
+  queryAsts.push(ast)
+  return queryResult
+})
+const getMock = mock(async (path: string) => {
+  getPaths.push(path)
+  return getResult
+})
+const bindGraphMock = mock(() => ({ query: queryMock, get: getMock }))
+const expandSelfInPathMock = mock(async (path: string) => {
+  if (path === '@self') {
+    return {
+      path: '@expanded-self',
+      meta: { original: '@self', expanded: '@expanded-self', selfId: 'expanded-self' },
+    }
+  }
+  return { path, meta: undefined }
+})
+const withSelfHintMock = mock(async (fn: () => Promise<unknown>) => fn())
+const runKernelCommandMock = mock(async (run: RunOpts) => {
+  const result = await run.fn({ client: { call: clientCallMock } })
+  if (run.format) await run.format(result, run.opts, true)
+})
+
+mock.module('../../kernel', () => ({
+  bindGraph: bindGraphMock,
+  expandSelfInPath: expandSelfInPathMock,
+  runKernelCommand: runKernelCommandMock,
+  withSelfHint: withSelfHintMock,
+}))
+
+beforeEach(() => {
+  stdout = ''
+  errors = []
+  queryAsts = []
+  getPaths = []
+  queryResult = { wire: emptyWire() }
+  getResult = null
+  clientCallResult = { rows: [] }
+  clientCallMock.mockClear()
+  queryMock.mockClear()
+  getMock.mockClear()
+  bindGraphMock.mockClear()
+  expandSelfInPathMock.mockClear()
+  withSelfHintMock.mockClear()
+  runKernelCommandMock.mockClear()
+
+  originalStdoutWrite = process.stdout.write.bind(process.stdout)
+  originalConsoleError = console.error
+  originalExit = process.exit
+  process.stdout.write = ((chunk: string | Uint8Array) => {
+    stdout += typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8')
+    return true
+  }) as typeof process.stdout.write
+  console.error = ((...args: unknown[]) => {
+    errors.push(args.map(String).join(' '))
+  }) as typeof console.error
+  process.exit = ((code?: string | number | null) => {
+    throw new ExitError(code)
+  }) as typeof process.exit
+})
+
+afterEach(() => {
+  process.stdout.write = originalStdoutWrite
+  console.error = originalConsoleError
+  process.exit = originalExit
+})
+
+describe('query command', () => {
+  test('lowers roots and selectors to the expected QueryASTInput', async () => {
+    const { queryCommand } = await import('../query')
+
+    await queryCommand(['/root', '@self'], {
+      json: true,
+      depth: '2',
+      children:
+        '{"classes":["/:kernel.astrale.ai:class.Folder"],"limit":50,"cursor":"child-cursor","order":{"by":"id","dir":"asc"}}',
+      edges:
+        '[{"as":"perm","classes":["/:kernel.astrale.ai:class.has_perm"],"direction":"out","limit":10,"cursor":"edge-cursor","order":{"by":"id","dir":"desc"}},{"direction":"both"}]',
+    })
+
+    expect(queryAsts).toEqual([
+      {
+        version: 1,
+        from: ['/root', '@expanded-self'],
+        steps: [
+          {
+            expand: {
+              edge: 'has_parent',
+              dir: 'in',
+              depth: 2,
+              filter: { class: ['/:kernel.astrale.ai:class.Folder'] },
+              page: { limit: 50, cursor: 'child-cursor' },
+              order: { by: 'id', dir: 'asc' },
+            },
+          },
+          {
+            expand: {
+              edge: ['/:kernel.astrale.ai:class.has_perm'],
+              dir: 'out',
+              as: 'perm',
+              page: { limit: 10, cursor: 'edge-cursor' },
+              order: { by: 'id', dir: 'desc' },
+            },
+          },
+          { expand: { dir: 'both', as: 'e1' } },
+        ],
+      },
+    ])
+    expect(expandSelfInPathMock.mock.calls.map((call) => call[0])).toEqual(['/root', '@self'])
+    expect(withSelfHintMock).toHaveBeenCalledTimes(1)
+  })
+
+  test('rejects an invalid children selector before dispatch', async () => {
+    const { queryCommand } = await import('../query')
+
+    await expect(queryCommand(['/'], { json: true, children: '{"bogus":true}' })).rejects.toEqual(
+      new ExitError(1),
+    )
+
+    expect(errors.join('\n')).toContain('--children invalid selector')
+    expect(queryMock).not.toHaveBeenCalled()
+  })
+
+  test('rejects mixing --ast with positional roots', async () => {
+    const { queryCommand } = await import('../query')
+
+    await expect(
+      queryCommand(['/'], { json: true, ast: '{"version":1,"from":["/"]}' }),
+    ).rejects.toEqual(new ExitError(1))
+
+    expect(errors.join('\n')).toContain(
+      '--ast cannot be used with positional roots or --depth/--children/--edges',
+    )
+    expect(queryMock).not.toHaveBeenCalled()
+  })
+})
+
+describe('get command', () => {
+  test('dispatches a point read and prints the flat wire projection', async () => {
+    const { getCommand } = await import('../get')
+    const row = {
+      id: 'n1',
+      class: '/:demo:class.Widget',
+      path: '/demo/widget',
+      props: { name: 'Widget' },
+      __labels: ['Node', 'Widget'],
+      classId: 'class-1',
+    }
+    getResult = row
+
+    await getCommand('/demo/widget', { json: true })
+
+    expect(getPaths).toEqual(['/demo/widget'])
+    expect(JSON.parse(stdout)).toEqual({
+      id: 'n1',
+      class: '/:demo:class.Widget',
+      path: '/demo/widget',
+      props: { name: 'Widget' },
+    })
+  })
+
+  test('errors with exit 1 when no node resolves', async () => {
+    const { getCommand } = await import('../get')
+    getResult = null
+
+    await expect(getCommand('/missing', { json: true })).rejects.toEqual(new ExitError(1))
+
+    expect(getPaths).toEqual(['/missing'])
+    expect(errors.join('\n')).toContain('node "/missing" not found or not visible')
+  })
+})

package/src/commands/call.ts

@@ -3,7 +3,14 @@ import { K } from '@astrale-os/kernel-core'
 import type { CommandDefinition } from '../command'
 import type { CallCommandOpts, ClientContext, SelfExpansionMeta } from '../kernel'
 
-import { buildSelfContext, resolveSelfIdLazy, runKernelCommand, withSelfHint } from '../kernel'
+import {
+  bindGraph,
+  buildSelfContext,
+  nodeProp,
+  resolveSelfIdLazy,
+  runKernelCommand,
+  withSelfHint,
+} from '../kernel'
 import { presentBinary, type BinaryLike } from '../lib/binary'
 import { log } from '../lib/log'
 import { output, present } from '../lib/output'
@@ -19,12 +26,8 @@ export async function callCommand(
   rawParams: string[],
   opts: CallOpts,
 ): Promise<void> {
-  // ── Expand `@self` in path + raw param strings ──────────
-  // Local resolution, with ONE lazy whoami round-trip for IdP identities
-  // missing a cached registration (persisted, so it's local afterwards).
-  // Throws a typed SelfRefusalError (manager, instance-signed, …) which we
-  // surface as a fatal CLI error. Runs BEFORE `--describe` so users get the
-  // typed refusal instead of a generic NotFoundError from the kernel.
+  // 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
@@ -35,9 +38,7 @@ export async function callCommand(
       const selfId = await resolveSelfIdLazy(selfCtx, opts)
       expandedPath = expandSelfReferences(path, selfId)
       expandedRaw = rawParams.map((p) => expandSelfReferences(p, selfId))
-      // Stamp metadata whenever ANY input mutated — the stale-registration
-      // hint in `formatKernelError` is just as useful when `@self` lived in
-      // a param (`node=@self`) as when it was in the path head.
+      // 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 = {
@@ -80,14 +81,7 @@ export async function callCommand(
     opts,
     label: expandedPath,
     fn: async (ctx): Promise<CallResult> => {
-      // Remote-bound functions live on an external worker. The kernel resolves
-      // the call to a redirect carrying the worker's URL + `iss`; the session
-      // follows it, minting a worker-scoped delegation for that `iss` (the
-      // delegation cache wired in `client.ts`). No client-side binding lookup.
-      //
-      // The one thing the reactive path can't discover after dispatch is a
-      // binary output mode (a JSON decode would corrupt the bytes), so detect
-      // it up front and route to the binary transport — which also auto-follows.
+      // 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 }
@@ -106,26 +100,15 @@ export async function callCommand(
 }
 
 /**
- * Best-effort pre-flight: does the target Function declare a binary output?
- * A binary method must use the binary transport (the value path would JSON-
- * decode and corrupt the bytes), and the client can't discover that after
- * dispatch. For a static path the path IS the Function node — read `output`
- * off it via `::get`. For an instance-method path (`<node>::method`) the
- * Function node isn't addressable that way: resolve the instance's class
- * first, then probe the class's method node (`<classPath>:method`). An
- * interface-hosted instance method still escapes the probe (its Function node
- * hangs off the interface, not the class) — that and any other failure returns
- * false and falls through to the value path, letting the kernel surface the
- * real error. `::get` is a kernel syscall (same origin) so it neither
- * redirects nor triggers delegation.
+ * 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 ctx.client.call(`${target}::get`, {})) as {
-      props?: Record<string, unknown>
-    } | null
+    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
@@ -141,22 +124,23 @@ async function instanceMethodNodePath(
   const source = path.slice(0, sep)
   const method = path.slice(sep + 2)
   if (!source || !method) return undefined
-  const node = (await ctx.client.call(`${source}::get`, {})) as { class?: string } | null
-  // node.class is a ClassPath (`/:domain:class.Name`); appending `:<method>`
-  // forms the MethodPath of the class-owned Function node.
-  return node?.class ? `${node.class}:${method}` : 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
 }
 
 async function describeOperation(path: string, opts: CallOpts): Promise<void> {
-  await runKernelCommand<Record<string, unknown>>({
+  await runKernelCommand({
     opts,
     label: `Schema for ${path}`,
-    fn: (ctx) => ctx.client.call(`${path}::get`, {}) as Promise<Record<string, unknown>>,
+    // The Function node carries the schemas as props (function.get depth:0).
+    fn: async (ctx) => await bindGraph(ctx).get(path),
     format: (node, fmtOpts) => {
-      const props = (node.properties ?? node) as Record<string, unknown>
+      const input = nodeProp(node, 'inputSchema')
+      const outputSchema = nodeProp(node, 'outputSchema')
       const schema: Record<string, unknown> = {}
-      if (props.inputSchema) schema.input = tryParseJson(props.inputSchema)
-      if (props.outputSchema) schema.output = tryParseJson(props.outputSchema)
+      if (input) schema.input = tryParseJson(input)
+      if (outputSchema) schema.output = tryParseJson(outputSchema)
       output(Object.keys(schema).length > 0 ? schema : node, fmtOpts)
     },
   })
@@ -277,8 +261,7 @@ Examples:
   $ astrale call /:host.astrale.ai:class.KernelInstance:list
   $ astrale call /:blog.acme.com:class.Author:list limit=10
   $ astrale call '@self::deactivate'
-  $ astrale call /:dist.astrale.ai:class.Domain:install --creds "$TOKEN" \\
-      -d "$(cat spec.json)"
+  $ astrale call /:workspace.astrale.ai:class.App:available --json
 `,
   arguments: [
     {