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

package/src/commands/ls.ts

@@ -1,251 +1,125 @@
-import { rawOf } from '@astrale-os/kernel-client/graph'
+import type { Node } from '@astrale-os/sdk/graph/node'
+import type { QueryDirection, QueryResult } from '@astrale-os/sdk/query'
+
+import { ClassPath } from '@astrale-os/sdk/graph/class'
 import chalk from 'chalk'
 
-import type { CommandDefinition } from '../command'
-import type { GraphNode, KernelCommandOpts, SelfExpansionMeta } from '../kernel'
+import type { KernelCommandOpts } from '../connection'
 import type { ListProjection } from '../lib/output'
+import type { CommandDefinition } from '../program/index'
 
-import {
-  bindGraph,
-  childrenCursor,
-  expandSelfInPath,
-  formatKernelError,
-  runKernelCommand,
-  splitRoot,
-  withKernelClient,
-  withSelfHint,
-} from '../kernel'
-import { spinner } from '../lib/log'
-import { isMachine, output, presentList } from '../lib/output'
+import { expandSelfInPath, runKernelCommand, withSelfHint } from '../connection'
+import { nodeProperty, prepareQuery } from '../graph/index'
+import { log } from '../lib/log'
+import { isMachine, presentList } from '../lib/output'
 
 type LsOpts = KernelCommandOpts & {
+  edge?: string
+  direction?: QueryDirection
+  limit?: string
+  cursor?: string
   long?: boolean
   quiet?: boolean
-  recursive?: boolean
   count?: boolean
-  filter?: string
-}
-
-/** A child node row — the shared `function.get` node shape. */
-type Item = GraphNode
-
-// ── Display projection ──────────────────────────────────────
-
-/** `/example.astrale.ai` → `example.astrale.ai`; `/` stays `/`. */
-export function basename(path?: string): string {
-  if (!path || path === '/') return path ?? ''
-  return path.slice(path.lastIndexOf('/') + 1)
-}
-
-/** `/:kernel.astrale.ai:class.Domain` → `Domain`; falls back to the most specific label. */
-export function classNameOf(item: { class?: string; __labels?: string[] }): string {
-  const tail = item.class?.split(/[/:.]/).pop()
-  return tail || item.__labels?.[item.__labels.length - 1] || '?'
 }
 
-/** The addressable path of a child (for `-q` / tree descent). */
-function itemPath(item: Item): string {
-  return item.path ?? (item.id ? `@${item.id}` : '')
-}
-
-function lsProjection(items: Item[]): ListProjection {
-  return {
-    columns: [
-      { key: 'name', header: 'NAME', color: chalk.cyan },
-      { key: 'kind', header: 'KIND', color: chalk.dim },
-      { key: 'id', header: 'ID', color: chalk.dim },
-    ],
-    rows: items.map((i) => ({ name: basename(i.path), kind: classNameOf(i), id: i.id ?? '' })),
-    paths: items.map(itemPath),
+export async function lsCommand(source: string, opts: LsOpts): Promise<void> {
+  if (opts.edge === undefined) {
+    log.error('ls requires --edge <class>; Kernel V2 has no universal child relation')
+    process.exit(1)
   }
-}
 
-function applyFilter(items: Item[], filter: string | undefined): Item[] {
-  if (!filter) return items
-  const f = filter.toLowerCase()
-  return items.filter((i) => {
-    const kindMatch = classNameOf(i).toLowerCase() === f
-    const labelMatch = i.__labels?.some((l) => l.toLowerCase() === f) ?? false
-    return kindMatch || labelMatch
-  })
-}
-
-// ── Command ─────────────────────────────────────────────────
-
-export async function lsCommand(path: string, opts: LsOpts): Promise<void> {
-  let expandedPath: string
+  let path: string
   let meta
+  let prepared
   try {
-    ;({ path: expandedPath, meta } = await expandSelfInPath(path, opts))
-  } catch (e) {
-    process.stderr.write((e instanceof Error ? e.message : 'Invalid @self expansion') + '\n')
+    ;({ path, meta } = await expandSelfInPath(source, opts))
+    prepared = prepareQuery({
+      sources: [path],
+      edge: opts.edge,
+      direction: opts.direction,
+      limit: opts.limit,
+      cursor: opts.cursor,
+    })
+  } catch (error) {
+    log.error(error instanceof Error ? error.message : 'Invalid edge neighborhood')
     process.exit(1)
   }
 
-  if (opts.recursive) {
-    return recursiveLs(expandedPath, opts, meta)
-  }
-
   await runKernelCommand({
     opts,
-    label: `Children of ${expandedPath}`,
-    // Flat listing = ONE function.get depth:1; the root is dropped, the rest are
-    // the direct children (replaces the removed `::listChildren` syscall).
-    fn: async (ctx) => {
-      const result = await withSelfHint(
-        () => bindGraph(ctx).query((q) => q.from(expandedPath).children()),
-        meta,
-      )
-      return {
-        children: splitRoot(result.wire.nodes, expandedPath).children,
-        next: childrenCursor(result.wire),
-      }
-    },
-    format: ({ children, next }, fmtOpts) => {
-      const items = applyFilter(children, opts.filter)
+    label: `Neighbors of ${path}`,
+    fn: ({ graph }) => withSelfHint(() => graph.query(prepared.ast, { page: prepared.page }), meta),
+    format: (response, format) => {
+      const graph = completeGraph(response.result)
       presentList(
-        items,
-        { ...fmtOpts, quiet: opts.quiet, count: opts.count, long: opts.long },
-        lsProjection,
+        [...graph.nodes],
+        { ...format, long: opts.long, quiet: opts.quiet, count: opts.count },
+        listProjection,
       )
-      if (next && !isMachine(fmtOpts) && !opts.quiet && !opts.count) {
-        process.stdout.write(
-          chalk.dim(
-            '  more children truncated - page with `query ' +
-              expandedPath +
-              ' --depth 1 --children \'{"cursor":"' +
-              next +
-              '"}\'`\n',
-          ),
-        )
+      if (response.page.next && !isMachine(format) && !opts.quiet && !opts.count) {
+        process.stderr.write(`  cursor: ${response.page.next}\n`)
       }
     },
   })
 }
 
-// ── Recursive tree ──────────────────────────────────────────
-
-const MAX_DEPTH = 5
-
-type TreeNode = Item & { children: TreeNode[] }
-
-async function recursiveLs(
-  path: string,
-  opts: LsOpts,
-  meta: SelfExpansionMeta | undefined,
-): Promise<void> {
-  const machine = isMachine(opts)
-  const spin = !machine ? spinner(`Listing ${path} recursively...`) : null
-
-  try {
-    await withKernelClient(opts, async (ctx) => {
-      // The recursive walk is now ONE function.get to the depth cap; the tree is
-      // reassembled client-side from the flat node page (was an N+1 buildTree).
-      const result = await withSelfHint(
-        () => bindGraph(ctx).query((q) => q.from(path).descend(MAX_DEPTH)),
-        meta,
-      )
-      const tree = buildTree(result.wire.nodes, path)
-      spin?.succeed(`Tree of ${path}`)
-      if (!machine) console.log('')
-
-      if (machine || opts.format) {
-        output(tree, opts)
-      } else if (opts.quiet) {
-        printTreeQuiet(tree)
-      } else {
-        printTree(tree, '')
-      }
-    })
-  } catch (error) {
-    if (!machine && spin) spin.fail('Failed')
-    await formatKernelError(error, machine, undefined, opts.debug, { credential: opts.creds })
-    process.exit(1)
-  }
+function completeGraph(result: QueryResult) {
+  if (result.kind !== 'graph') throw new TypeError('ls expected one complete graph Query result')
+  return result.graph
 }
 
-/** Parent absolute path of an absolute node path (`/a/b` → `/a`; `/a` → `/`). */
-function parentPathOf(path: string): string {
-  const i = path.lastIndexOf('/')
-  return i <= 0 ? '/' : path.slice(0, i)
-}
-
-/** Reassemble the flat `function.get` node page into a tree rooted at `rootPath`. */
-function buildTree(nodes: readonly GraphNode[], rootPath: string): TreeNode[] {
-  const rootRaw = rawOf(rootPath)
-  const byPath = new Map<string, TreeNode>()
-  for (const n of nodes) {
-    const raw = rawOf(n.path)
-    if (raw === rootRaw) continue
-    byPath.set(raw, { ...n, children: [] })
-  }
-
-  const roots: TreeNode[] = []
-  for (const [raw, node] of byPath) {
-    const parent = parentPathOf(raw)
-    const parentNode = parent === rootRaw ? undefined : byPath.get(parent)
-    if (parentNode) parentNode.children.push(node)
-    else roots.push(node)
-  }
-  return roots
-}
-
-function printTree(nodes: TreeNode[], prefix: string): void {
-  for (let i = 0; i < nodes.length; i++) {
-    const node = nodes[i]
-    const isLast = i === nodes.length - 1
-    const connector = isLast ? '└── ' : '├── '
-    const childPrefix = isLast ? '    ' : '│   '
-
-    const name = basename(node.path) || node.id || '?'
-    console.log(`${prefix}${connector}${chalk.cyan(name)}  ${chalk.dim(classNameOf(node))}`)
-
-    if (node.children.length > 0) {
-      printTree(node.children, prefix + childPrefix)
-    }
+export function listProjection(nodes: Node[]): ListProjection {
+  return {
+    columns: [
+      { key: 'name', header: 'NAME', color: chalk.cyan },
+      { key: 'class', header: 'CLASS', color: chalk.dim },
+      { key: 'id', header: 'ID', color: chalk.dim },
+    ],
+    rows: nodes.map((node) => ({
+      name: displayName(node),
+      class: ClassPath.name(node.class),
+      id: node.id,
+    })),
+    paths: nodes.map((node) => `@${node.id}`),
   }
 }
 
-function printTreeQuiet(nodes: TreeNode[]): void {
-  for (const node of nodes) {
-    process.stdout.write(itemPath(node) + '\n')
-    if (node.children.length > 0) printTreeQuiet(node.children)
-  }
+export function displayName(node: Node): string {
+  const value =
+    nodeProperty(node, 'name') ?? nodeProperty(node, 'title') ?? nodeProperty(node, 'slug')
+  return typeof value === 'string' && value.length > 0 ? value : `@${node.id}`
 }
 
 export default {
   name: 'ls',
-  description: 'List children of a node',
+  description: 'List one finite exact edge neighborhood',
   afterHelpText: `
 Behavior:
-  Default output is a NAME/KIND/ID table on a TTY, JSON when piped. One
-  function.get depth:1 fetches the direct children; -R fetches the whole
-  subtree (to depth ${MAX_DEPTH}) in a SINGLE call and renders it as a tree.
-  --filter matches a child KIND or label (post-filter): Folder, Function,
-  Domain. At a domain's tree position the children are Folder nodes
-  (class.X), not Class — so --filter Class returns nothing; use --filter
-  Folder, or descend into class.<X>. -q prints one absolute path per line
-  (pipeable).
+  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 /
-  $ astrale ls /kernel.astrale.ai --filter Folder
-  $ astrale ls / -q | xargs -I{} astrale describe {}
+  $ astrale ls @note --edge /:notes.example.dev:class.references
+  $ astrale ls @note --edge /:notes.example.dev:class.references --direction incoming --limit 25
 `,
-  arguments: [
-    { name: 'path', description: 'Node path (/domain/Class) or ID (@nodeId)', required: false },
-  ],
+  arguments: [{ name: 'source', description: 'Canonical source Path or @id' }],
   options: [
-    { flags: '-l, --long', description: 'Full node dump (default: compact)' },
-    { flags: '-q, --quiet', description: 'One path per line (unix-pipeable)' },
-    { flags: '-R, --recursive', description: 'List recursively (tree view)' },
-    { flags: '--count', description: 'Print only the number of children' },
+    { flags: '--edge <class>', description: 'Exact Edge Class to traverse' },
     {
-      flags: '--filter <kind>',
-      description: 'Filter children by kind or label (e.g., Folder, Function, Domain)',
+      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 (path, opts) => {
-    await lsCommand((path as string | undefined) ?? '/', opts as LsOpts)
+  action: async (source, opts) => {
+    await lsCommand(source as string, opts as LsOpts)
   },
 } satisfies CommandDefinition

package/src/commands/mutate.ts

@@ -1,189 +1,120 @@
-import type { PatchInput } from '@astrale-os/kernel-client/graph'
+import type { MutationResult } from '@astrale-os/sdk/mutation'
 
-import { patchDataSchema } from '@astrale-os/kernel-core'
 import chalk from 'chalk'
 import { readFile } from 'node:fs/promises'
 
-import type { CommandDefinition } from '../command'
-import type { KernelCommandOpts } from '../kernel'
-import type { MutationResultWire } from '../kernel'
+import type { KernelCommandOpts } from '../connection'
+import type { CommandDefinition } from '../program/index'
 
-import { bindGraph, runKernelCommand } from '../kernel'
+import { runKernelCommand } from '../connection'
+import { prepareMutation } from '../graph/index'
 import { log } from '../lib/log'
 import { output } from '../lib/output'
 import { renderTable } from '../lib/table'
 
-type MutateOpts = KernelCommandOpts & { data?: string; file?: string; dry?: boolean }
+type MutateOpts = KernelCommandOpts & {
+  data?: string
+  file?: string
+  dry?: boolean
+}
 
 export async function mutateCommand(opts: MutateOpts): Promise<void> {
-  let raw: unknown
+  let mutation
   try {
-    raw = await readPatch(opts)
-  } catch (e) {
-    log.error(e instanceof Error ? e.message : 'Invalid patch')
+    mutation = prepareMutation(await readDocument(opts))
+  } catch (error) {
+    log.error(error instanceof Error ? error.message : 'Invalid Mutation V3 document')
     process.exit(1)
-    return
   }
 
-  // --dry: validate the patch locally against the kernel's own schema and print
-  // the normalized form (every arm defaulted to []). No kernel round-trip.
   if (opts.dry) {
-    const parsed = patchDataSchema.safeParse(raw)
-    if (!parsed.success) {
-      log.error('Patch failed local validation:')
-      for (const issue of parsed.error.issues) {
-        log.dim(`  ${issue.path.join('.') || '(root)'}: ${issue.message}`)
-      }
-      process.exit(1)
-    }
-    output(parsed.data, opts)
+    output(mutation, opts)
     return
   }
 
-  await runKernelCommand<MutationResultWire>({
+  await runKernelCommand<MutationResult>({
     opts,
     label: 'Mutate',
-    fn: (ctx) => bindGraph(ctx).mutate(raw as PatchInput),
-    format: (result, fmtOpts, isRaw) => {
-      if (isRaw) {
-        output(result, fmtOpts)
-        return
-      }
-      printResult(result)
+    fn: ({ graph }) => graph.mutate(mutation),
+    format: (result, format, machine) => {
+      if (machine || format.format !== undefined) output(result, format)
+      else printResult(result)
     },
   })
 }
 
-/** Patch source ladder (highest wins): --data > --file > stdin. */
-async function readPatch(opts: MutateOpts): Promise<unknown> {
-  if (opts.data) {
+async function readDocument(opts: MutateOpts): Promise<unknown> {
+  const authored = [opts.data !== undefined, opts.file !== undefined].filter(Boolean).length
+  if (authored > 1) throw new TypeError('--data and --file are mutually exclusive')
+  if (opts.data !== undefined) return parseJson(opts.data, '--data')
+  if (opts.file !== undefined) {
+    let raw: string
     try {
-      return JSON.parse(opts.data)
-    } catch {
-      throw new Error(`Invalid JSON in --data: ${opts.data}`)
+      raw = await readFile(opts.file, 'utf8')
+    } catch (error) {
+      throw new Error(
+        `Cannot read --file ${opts.file}: ${error instanceof Error ? error.message : error}`,
+      )
     }
+    return parseJson(raw, opts.file)
   }
-  if (opts.file) {
-    let text: string
-    try {
-      text = await readFile(opts.file, 'utf-8')
-    } catch (e) {
-      throw new Error(`Cannot read --file ${opts.file}: ${e instanceof Error ? e.message : e}`)
-    }
-    try {
-      return JSON.parse(text)
-    } catch {
-      throw new Error(`Invalid JSON in ${opts.file}`)
-    }
+  if (process.stdin.isTTY) {
+    throw new TypeError('No mutation provided; use --data, --file, or stdin')
   }
-  const stdin = await readStdin()
-  if (stdin) {
-    try {
-      return JSON.parse(stdin)
-    } catch {
-      throw new Error('Invalid JSON from stdin')
-    }
-  }
-  throw new Error(
-    'No patch provided — pass --data <json>, --file <path>, or pipe a PatchData JSON on stdin',
-  )
+  const chunks: Buffer[] = []
+  for await (const chunk of process.stdin) chunks.push(Buffer.from(chunk))
+  const raw = Buffer.concat(chunks).toString('utf8').trim()
+  if (raw.length === 0) throw new TypeError('No mutation provided on stdin')
+  return parseJson(raw, 'stdin')
 }
 
-async function readStdin(): Promise<string | null> {
-  if (process.stdin.isTTY) return null
-  const chunks: Buffer[] = []
-  for await (const chunk of process.stdin) {
-    chunks.push(chunk as Buffer)
+function parseJson(raw: string, source: string): unknown {
+  try {
+    return JSON.parse(raw)
+  } catch {
+    throw new TypeError(`${source} must contain valid JSON`)
   }
-  const text = Buffer.concat(chunks).toString('utf-8').trim()
-  return text || null
 }
 
-function printResult(result: MutationResultWire): void {
-  const nodeRows = Object.entries(result.createdNodes ?? {})
-  const edgeRows = Object.entries(result.createdEdges ?? {})
-
-  if (nodeRows.length === 0 && edgeRows.length === 0) {
-    console.log(chalk.dim('  applied — no nodes or edges minted (updates/deletes only)'))
+function printResult(result: MutationResult): void {
+  const rows = Object.entries(result.createdNodes).map(([binding, id]) => ({ binding, id }))
+  if (rows.length === 0) {
+    console.log(chalk.dim('  applied — no Nodes created'))
     return
   }
-
-  if (nodeRows.length > 0) {
-    console.log(`  ${chalk.bold('Created nodes:')}`)
-    console.log(
-      renderTable(
-        nodeRows.map(([at, id]) => ({ at, id })),
-        {
-          columns: [
-            { key: 'at', header: 'AT', color: chalk.cyan },
-            { key: 'id', header: 'ID', color: chalk.dim },
-          ],
-          showHeader: true,
-        },
-      ),
-    )
-    console.log('')
-  }
-
-  if (edgeRows.length > 0) {
-    console.log(`  ${chalk.bold('Created edges:')}`)
-    console.log(
-      renderTable(
-        edgeRows.map(([tuple, id]) => ({ tuple, id })),
-        {
-          columns: [
-            { key: 'tuple', header: 'CLASS|SOURCE|SLUG|TARGET', color: chalk.cyan },
-            { key: 'id', header: 'ID', color: chalk.dim },
-          ],
-          showHeader: true,
-        },
-      ),
-    )
-    console.log('')
-  }
+  console.log(`  ${chalk.bold('Created nodes:')}`)
+  console.log(
+    renderTable(rows, {
+      columns: [
+        { key: 'binding', header: 'BINDING', color: chalk.cyan },
+        { key: 'id', header: 'ID', color: chalk.dim },
+      ],
+      showHeader: true,
+    }),
+  )
 }
 
 export default {
   name: 'mutate',
-  description: 'Apply a batch graph write (create/update/delete nodes & edges) via function.mutate',
+  description: 'Apply one atomic Mutation V3 graph transition',
   afterHelpText: `
 Behavior:
-  Sends a PatchData patch through the kernel's function.mutate door — a
-  single all-or-nothing write. Patch source (highest wins): --data > --file
-  > stdin. Prints the minted id maps (createdNodes: at→id, createdEdges:
-  class|source|slug|target → id); --json emits the raw MutationResult.
-
-  Authorization is per-arm: a create needs USE on the class and EDIT on the
-  parent, an update/delete needs EDIT on the target. A denied arm fails the
-  whole patch. --dry validates the patch locally (kernel patchDataSchema) and
-  prints the normalized form without touching the kernel.
+  Accepts a canonical astrale.graph.mutation/v3 document or its exact
+  { preconditions, operations } authoring input. Source is --data, --file,
+  or stdin. --dry admits and prints the canonical document without opening a
+  Kernel connection. The result contains the real createdNodes binding map.
 
-PatchData shape:
-  {
-    "nodes": {
-      "create": [{ "class": "/:d:class.X", "at": "/d/x", "props": {} }],
-      "update": [{ "class": "/:d:class.X", "path": "/d/x", "props": {} }],
-      "delete": [{ "class": "/:d:class.X", "path": "/d/x" }]
-    },
-    "edges": {
-      "create": [{ "class": "/:d:class.e", "source": "/a", "target": "/b", "props": {} }],
-      "delete": [{ "class": "/:d:class.e", "source": "/a", "target": "/b" }]
-    }
-  }
+  Legacy PatchData nodes/edges arms and createdEdges IDs are not part of
+  Mutation V3 and are rejected rather than approximated.
 
 Examples:
-  $ astrale mutate --data '{"nodes":{"create":[{"class":"/:blog.acme.com:class.Author","at":"/blog.acme.com/authors/ada","props":{}}]}}'
-  $ astrale mutate --file patch.json
-  $ echo '{"nodes":{"delete":[{"class":"/:d:class.X","path":"/d/x"}]}}' | astrale mutate
-  $ astrale mutate --file patch.json --dry
+  $ astrale mutate --file mutation.v3.json
+  $ astrale mutate --data '{"preconditions":[],"operations":[]}' --dry
 `,
   options: [
-    { flags: '-d, --data <json>', description: 'PatchData as a JSON string' },
-    { flags: '-f, --file <path>', description: 'Read PatchData JSON from a file' },
-    {
-      flags: '--dry',
-      description: 'Validate locally (no kernel call) and print the normalized patch',
-    },
+    { flags: '-d, --data <json>', description: 'Mutation V3 JSON document' },
+    { flags: '-f, --file <path>', description: 'Read a Mutation V3 document from a file' },
+    { flags: '--dry', description: 'Admit and print canonical Mutation V3 without dispatch' },
   ],
   action: async (opts) => {
     await mutateCommand(opts as MutateOpts)