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

package/src/commands/ls.ts

@@ -1,14 +1,17 @@
+import { rawOf } from '@astrale-os/kernel-client/graph'
 import chalk from 'chalk'
 
 import type { CommandDefinition } from '../command'
-import type { KernelCommandOpts, ClientContext, SelfExpansionMeta } from '../kernel'
+import type { GraphNode, KernelCommandOpts, SelfExpansionMeta } from '../kernel'
 import type { ListProjection } from '../lib/output'
 
 import {
+  bindGraph,
+  childrenCursor,
   expandSelfInPath,
-  extractItems,
   formatKernelError,
   runKernelCommand,
+  splitRoot,
   withKernelClient,
   withSelfHint,
 } from '../kernel'
@@ -23,25 +26,19 @@ type LsOpts = KernelCommandOpts & {
   filter?: string
 }
 
-/** A child node as returned by `::listChildren`. */
-type Item = {
-  id?: string
-  class?: string
-  path?: string
-  props?: Record<string, unknown>
-  __labels?: string[]
-}
+/** A child node row — the shared `function.get` node shape. */
+type Item = GraphNode
 
 // ── Display projection ──────────────────────────────────────
 
-/** `/dist.astrale.ai` → `dist.astrale.ai`; `/` stays `/`. */
+/** `/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: Item): string {
+export function classNameOf(item: { class?: string; __labels?: string[] }): string {
   const tail = item.class?.split(/[/:.]/).pop()
   return tail || item.__labels?.[item.__labels.length - 1] || '?'
 }
@@ -92,14 +89,36 @@ export async function lsCommand(path: string, opts: LsOpts): Promise<void> {
   await runKernelCommand({
     opts,
     label: `Children of ${expandedPath}`,
-    fn: (ctx) => withSelfHint(() => ctx.client.call(`${expandedPath}::listChildren`, {}), meta),
-    format: (result, fmtOpts) => {
-      const items = applyFilter(extractItems<Item>(result), opts.filter)
+    // 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)
       presentList(
         items,
         { ...fmtOpts, quiet: opts.quiet, count: opts.count, long: opts.long },
         lsProjection,
       )
+      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',
+          ),
+        )
+      }
     },
   })
 }
@@ -107,9 +126,8 @@ export async function lsCommand(path: string, opts: LsOpts): Promise<void> {
 // ── Recursive tree ──────────────────────────────────────────
 
 const MAX_DEPTH = 5
-const MAX_NODES = 200
 
-type TreeNode = Item & { children?: TreeNode[] }
+type TreeNode = Item & { children: TreeNode[] }
 
 async function recursiveLs(
   path: string,
@@ -121,8 +139,13 @@ async function recursiveLs(
 
   try {
     await withKernelClient(opts, async (ctx) => {
-      const counter = { count: 0 }
-      const tree = await withSelfHint(() => buildTree(ctx, path, 0, counter), meta)
+      // 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('')
 
@@ -141,32 +164,30 @@ async function recursiveLs(
   }
 }
 
-async function buildTree(
-  ctx: ClientContext,
-  path: string,
-  depth: number,
-  counter: { count: number },
-): Promise<TreeNode[]> {
-  if (depth >= MAX_DEPTH || counter.count >= MAX_NODES) return []
-  try {
-    const result = await ctx.client.call(`${path}::listChildren`, {})
-    const items = extractItems<Item>(result)
-
-    const nodes: TreeNode[] = []
-    for (const item of items) {
-      if (counter.count >= MAX_NODES) break
-      counter.count++
-      const node: TreeNode = { ...item }
-      // Descend by the child's absolute path (the kernel returns `path`, not `slug`).
-      if (item.path && item.path !== '/') {
-        node.children = await buildTree(ctx, item.path, depth + 1, counter)
-      }
-      nodes.push(node)
-    }
-    return nodes
-  } catch {
-    return []
+/** 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 {
@@ -179,7 +200,7 @@ function printTree(nodes: TreeNode[], prefix: string): void {
     const name = basename(node.path) || node.id || '?'
     console.log(`${prefix}${connector}${chalk.cyan(name)}  ${chalk.dim(classNameOf(node))}`)
 
-    if (node.children && node.children.length > 0) {
+    if (node.children.length > 0) {
       printTree(node.children, prefix + childPrefix)
     }
   }
@@ -188,7 +209,7 @@ function printTree(nodes: TreeNode[], prefix: string): void {
 function printTreeQuiet(nodes: TreeNode[]): void {
   for (const node of nodes) {
     process.stdout.write(itemPath(node) + '\n')
-    if (node.children) printTreeQuiet(node.children)
+    if (node.children.length > 0) printTreeQuiet(node.children)
   }
 }
 
@@ -197,13 +218,14 @@ export default {
   description: 'List children of a node',
   afterHelpText: `
 Behavior:
-  Default output is a NAME/KIND/ID table on a TTY, JSON when piped. --filter
-  matches a node KIND or label: Folder, Method, 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> and
-  --filter Method. -R tree view is TTY-only (raw/JSON emits the nested tree).
-  -q prints one absolute path per line (pipeable). Note: ls /<domain> may
-  report NOT_FOUND even when it exists — use describe, or ls one of its children.
+  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).
 
 Examples:
   $ astrale ls /
@@ -220,10 +242,10 @@ Examples:
     { flags: '--count', description: 'Print only the number of children' },
     {
       flags: '--filter <kind>',
-      description: 'Filter children by kind or label (e.g., Folder, Method, Domain)',
+      description: 'Filter children by kind or label (e.g., Folder, Function, Domain)',
     },
   ],
   action: async (path, opts) => {
-    await lsCommand((path as string | undefined) ?? '/', opts as Parameters<typeof lsCommand>[1])
+    await lsCommand((path as string | undefined) ?? '/', opts as LsOpts)
   },
 } satisfies CommandDefinition

package/src/commands/mutate.ts

@@ -0,0 +1,191 @@
+import type { PatchInput } from '@astrale-os/kernel-client/graph'
+
+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 { bindGraph, runKernelCommand } from '../kernel'
+import { log } from '../lib/log'
+import { output } from '../lib/output'
+import { renderTable } from '../lib/table'
+
+type MutateOpts = KernelCommandOpts & { data?: string; file?: string; dry?: boolean }
+
+export async function mutateCommand(opts: MutateOpts): Promise<void> {
+  let raw: unknown
+  try {
+    raw = await readPatch(opts)
+  } catch (e) {
+    log.error(e instanceof Error ? e.message : 'Invalid patch')
+    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)
+    return
+  }
+
+  await runKernelCommand<MutationResultWire>({
+    opts,
+    label: 'Mutate',
+    fn: (ctx) => bindGraph(ctx).mutate(raw as PatchInput),
+    format: (result, fmtOpts, isRaw) => {
+      if (isRaw) {
+        output(result, fmtOpts)
+        return
+      }
+      printResult(result)
+    },
+  })
+}
+
+/** Patch source ladder (highest wins): --data > --file > stdin. */
+async function readPatch(opts: MutateOpts): Promise<unknown> {
+  if (opts.data) {
+    try {
+      return JSON.parse(opts.data)
+    } catch {
+      throw new Error(`Invalid JSON in --data: ${opts.data}`)
+    }
+  }
+  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}`)
+    }
+  }
+  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',
+  )
+}
+
+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)
+  }
+  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)'))
+    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('')
+  }
+}
+
+export default {
+  name: 'mutate',
+  description: 'Apply a batch graph write (create/update/delete nodes & edges) via function.mutate',
+  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.
+
+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" }]
+    }
+  }
+
+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
+`,
+  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',
+    },
+  ],
+  action: async (opts) => {
+    await mutateCommand(opts as MutateOpts)
+  },
+} satisfies CommandDefinition