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

package/src/commands/query.ts

@@ -1,319 +1,141 @@
-import { getInputSchema, K } from '@astrale-os/kernel-core'
-import chalk from 'chalk'
+import type { QueryDirection } from '@astrale-os/sdk/query'
 
-import type { CommandDefinition } from '../command'
-import type { GetResultWire, KernelCommandOpts, QueryASTInput, SelfExpansionMeta } from '../kernel'
+import { readFile } from 'node:fs/promises'
 
-import { bindGraph, expandSelfInPath, runKernelCommand, withSelfHint } from '../kernel'
+import type { KernelCommandOpts, SelfExpansionMeta } from '../connection'
+import type { CommandDefinition } from '../program/index'
+
+import { expandSelfInPath, runKernelCommand, withSelfHint } from '../connection'
+import { prepareQuery, type QueryCommandInput } from '../graph/index'
 import { log } from '../lib/log'
 import { isMachine, output } from '../lib/output'
 
 type QueryOpts = KernelCommandOpts & {
-  depth?: string
-  children?: string
-  edges?: string
   ast?: string
-  cypher?: string
+  file?: string
+  definition?: string
+  edge?: string
+  direction?: QueryDirection
+  limit?: string
+  cursor?: string
 }
 
-type QueryMode =
-  | { kind: 'cypher'; cypher: string }
-  | { kind: 'ast'; ast: QueryASTInput }
-  | { kind: 'roots'; roots: string[]; meta: SelfExpansionMeta | undefined; query: BuiltQuery }
-
-export async function queryCommand(paths: string[], opts: QueryOpts): Promise<void> {
-  let mode: QueryMode
+export async function queryCommand(sources: string[], opts: QueryOpts): Promise<void> {
+  let input: QueryCommandInput
+  let meta: SelfExpansionMeta | undefined
   try {
-    mode = await parseMode(paths, opts)
-  } catch (e) {
-    log.error(e instanceof Error ? e.message : 'Invalid arguments')
+    const ast = await readAst(opts)
+    if (ast === undefined) {
+      const expanded = await Promise.all(sources.map((source) => expandSelfInPath(source, opts)))
+      input = {
+        sources: expanded.map(({ path }) => path),
+        definition: opts.definition,
+        edge: opts.edge,
+        direction: opts.direction,
+        limit: opts.limit,
+        cursor: opts.cursor,
+      }
+      meta = expanded.find((entry) => entry.meta !== undefined)?.meta
+    } else {
+      input = {
+        sources,
+        ast,
+        definition: opts.definition,
+        edge: opts.edge,
+        direction: opts.direction,
+        limit: opts.limit,
+        cursor: opts.cursor,
+      }
+    }
+  } catch (error) {
+    log.error(error instanceof Error ? error.message : 'Invalid query')
     process.exit(1)
-    return
   }
 
-  if (mode.kind === 'cypher') {
-    await runKernelCommand({
-      opts,
-      label: 'Query',
-      fn: (ctx) => ctx.client.call(K.$.f('query').path.domain.raw, { cypher: mode.cypher }),
-      format: (result, fmtOpts) => output(result, fmtOpts),
-    })
-    return
+  let prepared
+  try {
+    prepared = prepareQuery(input)
+  } catch (error) {
+    log.error(error instanceof Error ? error.message : 'Invalid Query V6 document')
+    process.exit(1)
   }
 
-  await runKernelCommand<GetResultWire>({
+  await runKernelCommand({
     opts,
-    label: mode.kind === 'roots' ? 'Query ' + mode.roots.join(' ') : 'Query',
-    fn: async (ctx) => {
-      const read = () => bindGraph(ctx).query(mode.kind === 'roots' ? mode.query.ast : mode.ast)
-      const result = mode.kind === 'roots' ? await withSelfHint(read, mode.meta) : await read()
-      return result.wire
-    },
-    format: (result, fmtOpts) => {
-      output(result, fmtOpts)
-      if (result.next && !isMachine(fmtOpts)) printCursorFooter(result.next)
+    label: 'Query',
+    fn: ({ graph }) => withSelfHint(() => graph.query(prepared.ast, { page: prepared.page }), meta),
+    format: (response, format) => {
+      output(response.result, format)
+      if (response.page.next && !isMachine(format)) {
+        process.stderr.write(`  cursor: ${response.page.next}\n`)
+      }
     },
   })
 }
 
-async function parseMode(paths: string[], opts: QueryOpts): Promise<QueryMode> {
-  const rootsInput = paths ?? []
-  const hasRoots = rootsInput.length > 0
-  const hasAst = opts.ast !== undefined
-  const hasCypher = opts.cypher !== undefined
-  const hasSelectors =
-    opts.depth !== undefined || opts.children !== undefined || opts.edges !== undefined
-
-  if (hasCypher) {
-    if (hasAst || hasRoots || hasSelectors) {
-      throw new Error('--cypher cannot be used with roots, --ast, --depth, --children, or --edges')
-    }
-    return { kind: 'cypher', cypher: opts.cypher as string }
-  }
-
-  if (hasAst) {
-    if (hasRoots || hasSelectors) {
-      throw new Error('--ast cannot be used with positional roots or --depth/--children/--edges')
-    }
-    return { kind: 'ast', ast: parseAst(opts.ast as string) }
+async function readAst(opts: QueryOpts): Promise<unknown | undefined> {
+  if (opts.ast !== undefined && opts.file !== undefined) {
+    throw new TypeError('--ast and --file are mutually exclusive')
   }
-
-  if (!hasRoots) {
+  if (opts.ast !== undefined) return parseJson(opts.ast, '--ast')
+  if (opts.file === undefined) return undefined
+  let raw: string
+  try {
+    raw = await readFile(opts.file, 'utf8')
+  } catch (error) {
     throw new Error(
-      'Usage: astrale query <paths...> [--depth <n>] [--children <json>] [--edges <json>] | --ast <json> | --cypher <query>',
+      `Cannot read --file ${opts.file}: ${error instanceof Error ? error.message : error}`,
     )
   }
-
-  const { roots, meta } = await expandRoots(rootsInput, opts)
-  return { kind: 'roots', roots, meta, query: buildQuery(roots, opts) }
-}
-
-function parseAst(raw: string): QueryASTInput {
-  let parsed: unknown
-  try {
-    parsed = JSON.parse(raw)
-  } catch {
-    throw new Error('--ast must be JSON: ' + raw)
-  }
-  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
-    throw new Error('--ast must be a JSON object')
-  }
-  return parsed as QueryASTInput
-}
-
-async function expandRoots(
-  paths: string[],
-  opts: QueryOpts,
-): Promise<{ roots: string[]; meta: SelfExpansionMeta | undefined }> {
-  const roots: string[] = []
-  let meta: SelfExpansionMeta | undefined
-  for (const p of paths) {
-    const expanded = await expandSelfInPath(p, opts)
-    roots.push(expanded.path)
-    if (!meta && expanded.meta) meta = expanded.meta
-  }
-  return { roots, meta }
-}
-
-type QueryDir = 'in' | 'out' | 'both'
-type QueryOrder = { by: string; dir: 'asc' | 'desc' }
-type ChildrenSelector = { classes?: string[]; limit?: number; cursor?: string; order?: QueryOrder }
-type EdgeSelector = {
-  as?: string
-  classes?: string[]
-  direction?: QueryDir
-  limit?: number
-  cursor?: string
-  order?: QueryOrder
-}
-type BuiltQuery = { ast: QueryASTInput; depth: number; hasEdges: boolean }
-
-function buildQuery(roots: string[], opts: QueryOpts): BuiltQuery {
-  const depth = opts.depth !== undefined ? parseRange('--depth', opts.depth, 0, 5) : 0
-  const children =
-    opts.children !== undefined
-      ? parseSelector<ChildrenSelector>('--children', opts.children, getInputSchema.shape.children)
-      : undefined
-  const edges =
-    opts.edges !== undefined
-      ? parseSelector<EdgeSelector | EdgeSelector[]>(
-          '--edges',
-          opts.edges,
-          getInputSchema.shape.edges,
-        )
-      : undefined
-
-  const steps: NonNullable<QueryASTInput['steps']> = []
-  if (depth > 0) steps.push({ expand: childExpand(depth, children) })
-  edgeSelectors(edges).forEach((selector, index) => {
-    steps.push({ expand: edgeExpand(selector, index) })
-  })
-
-  return {
-    ast: { version: 1, from: roots, ...(steps.length > 0 ? { steps } : {}) },
-    depth,
-    hasEdges: edges !== undefined,
-  }
-}
-
-function childExpand(depth: number, children: ChildrenSelector | undefined) {
-  return {
-    edge: 'has_parent',
-    dir: 'in' as const,
-    depth,
-    ...(children?.classes !== undefined ? { filter: { class: children.classes } } : {}),
-    ...pageFields(children),
-    ...(children?.order !== undefined ? { order: children.order } : {}),
-  }
-}
-
-function edgeExpand(selector: EdgeSelector, index: number) {
-  return {
-    ...(selector.classes !== undefined ? { edge: selector.classes } : {}),
-    dir: selector.direction ?? 'both',
-    as: selector.as ?? 'e' + index,
-    ...pageFields(selector),
-    ...(selector.order !== undefined ? { order: selector.order } : {}),
-  }
-}
-
-function pageFields(selector: { limit?: number; cursor?: string } | undefined) {
-  if (selector?.limit === undefined && selector?.cursor === undefined) return {}
-  return {
-    page: {
-      ...(selector.limit !== undefined ? { limit: selector.limit } : {}),
-      ...(selector.cursor !== undefined ? { cursor: selector.cursor } : {}),
-    },
-  }
-}
-
-function edgeSelectors(edges: EdgeSelector | EdgeSelector[] | undefined): EdgeSelector[] {
-  if (edges === undefined) return []
-  return Array.isArray(edges) ? edges : [edges]
-}
-
-function parseRange(flag: string, raw: string, min: number, max: number): number {
-  const n = Number(raw)
-  if (!Number.isInteger(n) || n < min || n > max) {
-    throw new Error(flag + ' needs an integer in [' + min + ', ' + max + '], got "' + raw + '"')
-  }
-  return n
+  return parseJson(raw, opts.file)
 }
 
-type SelectorIssue = { readonly path: readonly PropertyKey[]; readonly message: string }
-type SelectorSchema = {
-  safeParse(
-    value: unknown,
-  ): { success: true } | { success: false; error: { issues: readonly SelectorIssue[] } }
-}
-
-function parseSelector<T>(flag: string, raw: string, schema: SelectorSchema): T {
-  let parsed: unknown
+function parseJson(raw: string, source: string): unknown {
   try {
-    parsed = JSON.parse(raw)
+    return JSON.parse(raw)
   } catch {
-    throw new Error(flag + ' must be JSON: ' + raw)
-  }
-  if (parsed === null || typeof parsed !== 'object') {
-    throw new Error(
-      flag + ' must be a JSON selector object' + (flag === '--edges' ? ' or array' : ''),
-    )
-  }
-  const check = schema.safeParse(parsed)
-  if (!check.success) {
-    const detail = check.error.issues
-      .map((i) => (i.path.join('.') || '(root)') + ': ' + i.message)
-      .join('; ')
-    throw new Error(flag + ' invalid selector: ' + detail)
-  }
-  return parsed as T
-}
-
-function printCursorFooter(next: NonNullable<GetResultWire['next']>): void {
-  const entries = Object.entries(next)
-  if (entries.length === 1) {
-    const cursors = entries[0]?.[1]
-    if (cursors?.children) {
-      process.stdout.write(
-        chalk.dim('  more: --children \'{"cursor":"' + cursors.children + '"}\'\n'),
-      )
-    }
-    for (const [alias, cursor] of Object.entries(cursors?.edges ?? {})) {
-      process.stdout.write(
-        chalk.dim(
-          '  more edges[' +
-            alias +
-            ']: --edges \'{"as":"' +
-            alias +
-            '","cursor":"' +
-            cursor +
-            '"}\'\n',
-        ),
-      )
-    }
-    return
+    throw new TypeError(`${source} must contain valid JSON`)
   }
-  process.stdout.write(
-    chalk.dim('  more results - per-root cursors in .next (page each root by --cursor)\n'),
-  )
 }
 
 export default {
   name: 'query',
-  description: 'Run a structured graph read',
-  afterHelpText: [
-    '',
-    'Behavior:',
-    '  Structured read door for the query AST. Positional roots build a v1 AST',
-    '  with optional child and edge expansion, then lower through function.get',
-    '  today. A true query syscall may back this command later.',
-    '',
-    '  Output is always the full GraphData envelope { nodes, edges, aliases }',
-    '  with .roots and .next when returned. On a TTY, cursor footers are printed',
-    '  when .next has more pages.',
-    '',
-    '  --children takes { classes?, limit?, cursor?, order? } and shapes the',
-    '  depth-1 children page (needs --depth >= 1 to bite). --edges takes an edge',
-    '  selector, or a JSON array of selectors.',
-    '',
-    '  --ast (experimental) accepts a raw QueryASTInput JSON object. The AST shape',
-    '  is not a stable contract yet — prefer the flags above. @self is not expanded',
-    '  inside --ast JSON.',
-    '',
-    '  --cypher is a read-only escape hatch. The kernel rejects write keywords',
-    '  such as CREATE, DELETE, SET, MERGE, REMOVE, and DETACH.',
-    '',
-    'Examples:',
-    '  $ astrale query / --depth 1',
-    '  $ astrale query /a /b --edges \'{"direction":"both"}\'',
-    '  $ astrale query /kernel.astrale.ai --depth 2 --children \'{"classes":["/:kernel.astrale.ai:class.Folder"]}\'',
-    "  $ astrale query --cypher 'MATCH (n) RETURN count(n) AS total'",
-    '',
-  ].join('\n'),
-  arguments: [
-    {
-      name: 'paths...',
-      description: 'One or more root paths (/domain/Class) or IDs (@nodeId)',
-      required: false,
-    },
-  ],
+  description: 'Run one canonical Query V6 graph read',
+  afterHelpText: `
+Behavior:
+  Positional Paths and --definition author a finite Query V6 read. --edge adds
+  one exact Edge-Class expansion; --direction defaults to outgoing. --ast and
+  --file accept a complete canonical astrale.graph.query/v6 document, including
+  Property ordering and Node or Edge reference/value projections. --cursor resumes
+  one caller-bound query scope.
+
+  Legacy depth/children selector JSON and raw Cypher are not portable Kernel
+  V2 query contracts and are not accepted.
+
+Examples:
+  $ astrale query /:notes.example.dev:class.Note --limit 50
+  $ astrale query --definition /:notes.example.dev:class.Note --limit 50
+  $ astrale query @note --edge /:notes.example.dev:class.references --direction outgoing --limit 25
+  $ astrale query --file query.v6.json --cursor "$CURSOR"
+`,
+  arguments: [{ name: 'sources...', description: 'Canonical source Paths', required: false }],
   options: [
-    { flags: '--depth <n>', description: 'Subtree depth to fetch (0-5, default 0)' },
-    {
-      flags: '--children <json>',
-      description: 'Children selector { classes?, limit?, cursor?, order? } (needs --depth >= 1)',
-    },
+    { flags: '--ast <json>', description: 'Canonical Query V6 JSON document' },
+    { flags: '-f, --file <path>', description: 'Read a canonical Query V6 document from a file' },
     {
-      flags: '--edges <json>',
-      description: 'Edge selector (or JSON array of selectors) to include',
+      flags: '--definition <path>',
+      description: 'Select Nodes implementing one exact Class or Interface',
     },
+    { flags: '--edge <class>', description: 'Expand one exact Edge Class' },
     {
-      flags: '--ast <json>',
-      description: 'Raw QueryASTInput JSON object (experimental, unstable shape)',
+      flags: '--direction <direction>',
+      description: 'Edge direction (requires --edge)',
+      choices: ['outgoing', 'incoming', 'incident'],
     },
-    { flags: '--cypher <query>', description: 'Read-only Cypher escape hatch' },
+    { flags: '--limit <n>', description: 'Finite selected binding limit (default: 100)' },
+    { flags: '--cursor <token>', description: 'Resume one live query scope' },
   ],
-  action: async (paths, opts) => {
-    await queryCommand(Array.isArray(paths) ? paths : [], opts as QueryOpts)
+  action: async (sources, opts) => {
+    await queryCommand((sources as string[] | undefined) ?? [], opts as QueryOpts)
   },
 } satisfies CommandDefinition

package/src/commands/session/analyze.ts

@@ -1,6 +1,6 @@
 import chalk from 'chalk'
 
-import type { CommandDefinition } from '../../command'
+import type { CommandDefinition } from '../../program/index'
 
 import { log } from '../../lib/log'
 import { analyzeSession } from '../../telemetry/analyze'

package/src/commands/session/list.ts

@@ -1,6 +1,6 @@
 import chalk from 'chalk'
 
-import type { CommandDefinition } from '../../command'
+import type { CommandDefinition } from '../../program/index'
 
 import { log } from '../../lib/log'
 import { isMachine, output, RAW_OUTPUT_OPTIONS } from '../../lib/output'

package/src/commands/setup.ts

@@ -1,4 +1,4 @@
-import type { CommandDefinition } from '../command'
+import type { CommandDefinition } from '../program/index'
 
 import { ADMIN_TARGET_OPTIONS } from '../lib/admin-target'
 import { fatal } from '../lib/log'

package/src/commands/status.ts

@@ -1,6 +1,6 @@
 import chalk from 'chalk'
 
-import type { CommandDefinition } from '../command'
+import type { CommandDefinition } from '../program/index'
 
 import { readLocalStatus } from '../lib/local-status'
 import { log } from '../lib/log'

package/src/commands/studio.ts

@@ -3,7 +3,7 @@ import type { ChildProcess } from 'node:child_process'
 import { existsSync, realpathSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
 
-import type { CommandDefinition } from '../command'
+import type { CommandDefinition } from '../program/index'
 
 import { fatal, log } from '../lib/log'
 import { isMachine, output, RAW_OUTPUT_OPTIONS, type RawOutputOpts } from '../lib/output'

package/src/commands/token.ts

@@ -1,7 +1,9 @@
-import type { CommandDefinition } from '../command'
-import type { KernelCommandOpts } from '../kernel'
+import { issuer } from '@astrale-os/sdk/auth'
 
-import { runKernelCommand } from '../kernel'
+import type { KernelCommandOpts } from '../connection'
+import type { CommandDefinition } from '../program/index'
+
+import { runKernelCommand } from '../connection'
 import { log } from '../lib/log'
 
 /**
@@ -17,19 +19,23 @@ export type TokenOpts = KernelCommandOpts & {
 }
 
 export async function tokenCommand(opts: TokenOpts): Promise<void> {
-  if (opts.for && !opts.as) opts.as = opts.for
+  const commandOpts: TokenOpts = opts.for && !opts.as ? { ...opts, as: opts.for } : opts
   await runKernelCommand<string>({
-    opts,
+    opts: commandOpts,
     label: 'Minting delegation token',
     fn: async (ctx) => {
-      const audience = opts.audience ?? ''
-      const parsedTtl = Number(opts.ttl)
+      const audience =
+        commandOpts.audience === undefined
+          ? ctx.target.kernelIssuer
+          : issuer.accept(commandOpts.audience)
+      const parsedTtl = Number(commandOpts.ttl)
       const ttl = Number.isFinite(parsedTtl) && parsedTtl > 0 ? parsedTtl : 3600
-      const result = await ctx.client.as(ctx.credential).auth.delegate({
+      const self = await ctx.auth.whoami()
+      return ctx.auth.delegate(self.id, {
         audience,
-        ttl,
+        ttlSeconds: ttl,
+        attenuation: { kind: 'identity', self: true },
       })
-      return result
     },
     format: (token, fmtOpts, isRaw) => {
       if (isRaw) {
@@ -47,24 +53,23 @@ export default {
   description: 'Mint a fresh delegation token for the active instance + identity',
   afterHelpText: `
 Behavior:
-  Default ttl 3600s, audience empty. The result is a two-layer
-  envelope: an outer JWT signed by the kernel system key
-  (sub __system__) wrapping an inner ES256 delegation credential for
-  the identity. The token aud must match the worker's expected
-  audience or the worker rejects it. --for is an alias of --as.
+  Delegates the selected authenticated identity for 3600 seconds by default.
+  The default audience is the target Kernel issuer; choose --audience when the
+  credential is intended for another service. --for is an alias of --as.
 
-What this token is FOR — worker-direct HTTP calls:
-  Use it as a Bearer token against a domain worker's own URL
-  (curl/fetch to its remote functions). It carries NO .grant claim,
-  so it CANNOT drive a raw kernel ClientSession — for kernel calls
-  use 'astrale call' (which signs per-call) instead.
+  The receiver must admit the exact token audience. A Kernel-audience token can
+  be reused with --creds; a service-audience token can be sent as a Bearer token
+  to that service's authenticated endpoint.
 
 Examples:
   $ export TOKEN=$(astrale token --audience shell.astrale.ai --raw)
   $ astrale token --audience worker.example.com --for alice -i staging
 `,
   options: [
-    { flags: '--audience <aud>', description: 'Token audience (defaults to empty)' },
+    {
+      flags: '--audience <aud>',
+      description: 'Token audience (default: target Kernel issuer)',
+    },
     { flags: '--ttl <sec>', description: 'TTL in seconds (default: 3600)' },
     { flags: '--for <identity>', description: 'Mint the token for this identity (alias of --as)' },
   ],

package/src/commands/update.ts

@@ -1,4 +1,4 @@
-import type { CommandDefinition } from '../command'
+import type { CommandDefinition } from '../program/index'
 
 import pkg from '../../package.json' with { type: 'json' }
 import { fatal, log } from '../lib/log'

package/src/commands/use.ts

@@ -1,7 +1,6 @@
-import type { CommandDefinition } from '../command'
+import type { CommandDefinition } from '../program/index'
 
-import { setDefault } from '../lib/identity'
-import { readIdentities } from '../lib/identity'
+import { readIdentities, setDefault } from '../identity/index'
 import { readInstances } from '../lib/instance'
 import { fatal, log } from '../lib/log'
 import { resolveUseTarget } from '../lib/use-target'

package/src/commands/view-serve.ts

@@ -1,7 +1,7 @@
 import { readFile } from 'node:fs/promises'
 
-import type { CommandDefinition } from '../command'
 import type { ViewServeConfig } from '../lib/view/session'
+import type { CommandDefinition } from '../program/index'
 
 import { startViewServer } from '../lib/view/server'