@astrale-os/cli 0.8.1-alpha.3 → 0.8.1-alpha.4

package/README.md

@@ -110,7 +110,7 @@ Main command groups:
 
 | Group | What it covers |
 |-------|----------------|
-| Kernel | `ls`, `get`, `call`, `query`, `describe`, `token` |
+| Kernel | `get`, `call`, `query`, `describe`, `token` |
 | Context | `status`, `whoami`, `use` |
 | Management | `admin`, `instance`, `identity`, `auth`, `idp`, `update` |
 | Agent | `browser` |

package/dist/astrale.js

@@ -2576,7 +2576,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@astrale-os/cli",
-    version: "0.8.1-alpha.3",
+    version: "0.8.1-alpha.4",
     description: "Astrale CLI — connect to existing Astrale kernels",
     keywords: [
       "astrale",
@@ -90852,115 +90852,6 @@ var init_class3 = __esm(() => {
   init_class();
 });
 
-// src/commands/ls.ts
-var exports_ls = {};
-__export(exports_ls, {
-  lsCommand: () => lsCommand,
-  listProjection: () => listProjection,
-  displayName: () => displayName,
-  default: () => ls_default
-});
-async function lsCommand(source2, opts) {
-  if (opts.edge === undefined) {
-    log.error("ls requires --edge <class>; Kernel V2 has no universal child relation");
-    process.exit(1);
-  }
-  let path5;
-  let meta3;
-  let prepared;
-  try {
-    ({ path: path5, meta: meta3 } = await expandSelfInPath(source2, opts));
-    prepared = prepareQuery({
-      sources: [path5],
-      edge: opts.edge,
-      direction: opts.direction,
-      limit: opts.limit,
-      cursor: opts.cursor
-    });
-  } catch (error52) {
-    log.error(error52 instanceof Error ? error52.message : "Invalid edge neighborhood");
-    process.exit(1);
-  }
-  await runKernelCommand({
-    opts,
-    label: `Neighbors of ${path5}`,
-    fn: ({ graph }) => withSelfHint(() => graph.query(prepared.ast, { page: prepared.page }), meta3),
-    format: (response2, format3) => {
-      const graph = completeGraph(response2.result);
-      presentList([...graph.nodes], { ...format3, long: opts.long, quiet: opts.quiet, count: opts.count }, listProjection);
-      if (response2.page.next && !isMachine(format3) && !opts.quiet && !opts.count) {
-        process.stderr.write(`  cursor: ${response2.page.next}
-`);
-      }
-    }
-  });
-}
-function completeGraph(result) {
-  if (result.kind !== "graph")
-    throw new TypeError("ls expected one complete graph Query result");
-  return result.graph;
-}
-function listProjection(nodes) {
-  return {
-    columns: [
-      { key: "name", header: "NAME", color: source_default.cyan },
-      { key: "class", header: "CLASS", color: source_default.dim },
-      { key: "id", header: "ID", color: source_default.dim }
-    ],
-    rows: nodes.map((node4) => ({
-      name: displayName(node4),
-      class: ClassPath.name(node4.class),
-      id: node4.id
-    })),
-    paths: nodes.map((node4) => `@${node4.id}`)
-  };
-}
-function displayName(node4) {
-  const value2 = nodeProperty(node4, "name") ?? nodeProperty(node4, "title") ?? nodeProperty(node4, "slug");
-  return typeof value2 === "string" && value2.length > 0 ? value2 : `@${node4.id}`;
-}
-var ls_default;
-var init_ls = __esm(() => {
-  init_class3();
-  init_source();
-  init_connection2();
-  init_graph6();
-  init_log();
-  init_output();
-  ls_default = {
-    name: "ls",
-    description: "List one finite exact edge neighborhood",
-    afterHelpText: `
-Behavior:
-  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 @note --edge /:notes.example.dev:class.references
-  $ astrale ls @note --edge /:notes.example.dev:class.references --direction incoming --limit 25
-`,
-    arguments: [{ name: "source", description: "Canonical source Path or @id" }],
-    options: [
-      { flags: "--edge <class>", description: "Exact Edge Class to traverse" },
-      {
-        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 (source2, opts) => {
-      await lsCommand(source2, opts);
-    }
-  };
-});
-
 // src/commands/describe.ts
 var exports_describe = {};
 __export(exports_describe, {
@@ -93569,7 +93460,7 @@ Behavior:
   Reads the admin catalog — every domain that has been \`publish\`ed
   (origin → published worker URL). Listing only shows what is INSTALLABLE;
   what is actually mounted where lives on each instance's own graph
-  (\`astrale ls /\` against that instance).
+  (\`astrale query\` against that instance).
 
   Default output is a NAME/ORIGIN/URL/DEFAULT table on a TTY, JSON when piped
   or with --json/--raw (agent-friendly — full DomainInfo objects). -q prints
@@ -95904,9 +95795,21 @@ function renderCommanderError(program2, error, argv = process.argv.slice(2)) {
   ].join(`
 `);
 }
+var RETIRED_COMMANDS = {
+  ls: "astrale query <source> --edge <class>"
+};
 function renderUnknownCommand(tokens, catalog) {
   const command = tokens.join(" ");
   const first = tokens[0];
+  const retired = first === undefined ? undefined : RETIRED_COMMANDS[first];
+  if (retired !== undefined) {
+    return [
+      `Unknown command: ${source_default.bold(`astrale ${command}`)}`,
+      "",
+      `\`astrale ${first}\` was removed. Use ${source_default.bold(retired)} instead.`
+    ].join(`
+`);
+  }
   const namespaceMatches = catalog.filter((entry) => entry.path.at(-1) === first);
   if (namespaceMatches.length > 0) {
     return [
@@ -96106,7 +96009,6 @@ async function buildProgram() {
   registerCommand(program3, withKernelOptions((await Promise.resolve().then(() => (init_token(), exports_token))).default));
   registerCommand(program3, withKernelOptions((await Promise.resolve().then(() => (init_get(), exports_get))).default));
   registerCommand(program3, withKernelOptions((await Promise.resolve().then(() => (init_mutate4(), exports_mutate))).default));
-  registerCommand(program3, withKernelOptions((await Promise.resolve().then(() => (init_ls(), exports_ls))).default));
   registerCommand(program3, withKernelOptions((await Promise.resolve().then(() => (init_describe(), exports_describe))).default));
   registerCommand(program3, withKernelOptions((await Promise.resolve().then(() => (init_query7(), exports_query))).default));
   registerCommand(program3, withKernelOptions((await Promise.resolve().then(() => (init_logs(), exports_logs))).default));
@@ -96194,7 +96096,7 @@ async function buildProgram() {
   program3.addHelpText("after", `
 Command groups:
   Getting started  setup     (sign in, pick an instance, equip your workspace)
-  Kernel        ls, get, mutate, call, query, describe, token
+  Kernel        get, mutate, call, query, describe, token
   Management    admin, instance, domain, identity, auth, idp, update
   Agent         browser   (drive the GUI via agent-browser)
   Studio        studio    (launch the local Domain Studio GUI for a workspace)
@@ -96208,7 +96110,6 @@ Path syntax:
   @nodeId::method                Instance method on a node by UID
 
 Examples:
-  $ astrale ls @note --edge /:notes.example.dev:class.references
   $ astrale studio
   $ astrale admin status
   $ astrale update --check

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/cli",
-  "version": "0.8.1-alpha.3",
+  "version": "0.8.1-alpha.4",
   "description": "Astrale CLI — connect to existing Astrale kernels",
   "keywords": [
     "astrale",

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

@@ -218,18 +218,6 @@ describe('get command', () => {
   })
 })
 
-describe('ls command', () => {
-  /** @evidence TEST-CLI-LS-REQUIRES-EXACT-EDGE-BEFORE-CONNECTION */
-  test('rejects a generic child listing before opening the command connection', async () => {
-    const { lsCommand } = await import('../ls')
-
-    await expect(lsCommand('@node', { json: true })).rejects.toEqual(new ExitError(1))
-
-    expect(runKernelCommandMock).not.toHaveBeenCalled()
-    expect(errors.join('\n')).toContain('Kernel V2 has no universal child relation')
-  })
-})
-
 describe('mutate command', () => {
   /** @evidence TEST-CLI-MUTATE-DISPATCHES-CANONICAL-V3 */
   test('admits authoring input and dispatches one canonical Mutation V3 document', async () => {

package/src/commands/domain/list.ts

@@ -66,7 +66,7 @@ Behavior:
   Reads the admin catalog — every domain that has been \`publish\`ed
   (origin → published worker URL). Listing only shows what is INSTALLABLE;
   what is actually mounted where lives on each instance's own graph
-  (\`astrale ls /\` against that instance).
+  (\`astrale query\` against that instance).
 
   Default output is a NAME/ORIGIN/URL/DEFAULT table on a TTY, JSON when piped
   or with --json/--raw (agent-friendly — full DomainInfo objects). -q prints

package/src/lib/__tests__/command-dx.test.ts

@@ -22,8 +22,9 @@ describe('command DX suggestions', () => {
     expect(usages).toContain('admin use [bookmark]')
     expect(usages).toContain('use <name>')
     expect(usages).toContain('update')
-    expect(usages).toContain('ls <source>')
+    expect(usages).toContain('query [sources...]')
     expect(usages).toContain('status')
+    expect(usages).not.toContain('ls <source>')
   })
 
   test('explains shared verbs as namespaced commands, not arity errors', async () => {
@@ -42,6 +43,17 @@ describe('command DX suggestions', () => {
     expect(rendered).not.toContain('too many arguments')
   })
 
+  test('points retired ls at query', async () => {
+    const program = await buildProgram()
+    const error = new CommanderError(1, 'commander.unknownCommand', "error: unknown command 'ls'")
+    const rendered = stripAnsi(renderCommanderError(program, error, ['ls', '@note']))
+
+    expect(rendered).toContain('Unknown command: astrale ls @note')
+    expect(rendered).toContain('astrale ls` was removed')
+    expect(rendered).toContain('astrale query <source> --edge <class>')
+    expect(rendered).not.toContain('Did you mean:')
+  })
+
   test('suggests nearest command for typo paths', async () => {
     const program = await buildProgram()
     const error = new CommanderError(

package/src/lib/command-dx.ts

@@ -72,9 +72,21 @@ export function renderCommanderError(
   ].join('\n')
 }
 
+const RETIRED_COMMANDS: Record<string, string> = {
+  ls: 'astrale query <source> --edge <class>',
+}
+
 function renderUnknownCommand(tokens: string[], catalog: CommandCatalogEntry[]): string {
   const command = tokens.join(' ')
   const first = tokens[0]
+  const retired = first === undefined ? undefined : RETIRED_COMMANDS[first]
+  if (retired !== undefined) {
+    return [
+      `Unknown command: ${chalk.bold(`astrale ${command}`)}`,
+      '',
+      `\`astrale ${first}\` was removed. Use ${chalk.bold(retired)} instead.`,
+    ].join('\n')
+  }
   const namespaceMatches = catalog.filter((entry) => entry.path.at(-1) === first)
   if (namespaceMatches.length > 0) {
     return [

package/src/program/__tests__/program.test.ts

@@ -171,7 +171,6 @@ describe('program composition', () => {
       'instance status',
       'instance use',
       'logs',
-      'ls',
       'mutate',
       'query',
       'session',
@@ -187,7 +186,7 @@ describe('program composition', () => {
       'whoami',
     ])
     expect(createHash('sha256').update(JSON.stringify(surface)).digest('hex')).toBe(
-      '4a57bfc347f9abebcea239427214eb25fbaf9ca704170c8b4a933d0c9ba4d14e',
+      '4b053fe80827aeb40aecc13cd17c293b8701e59cb04f5ccb8185e9e255376dd1',
     )
   })
 
@@ -267,7 +266,7 @@ describe('help contract — connect-only command surface', () => {
     const program = await buildProgram()
     const names = allCommands(program).map((command) => command.name())
 
-    // `logs` and `domain` have managed/admin meanings, so only retired local-runtime verbs are absent.
+    // `logs` and `domain` have managed/admin meanings, so only retired verbs are absent.
     for (const removed of [
       'init',
       'start',
@@ -279,6 +278,7 @@ describe('help contract — connect-only command surface', () => {
       'graph',
       'server',
       'env',
+      'ls',
     ]) {
       expect(names).not.toContain(removed)
     }

package/src/program/build.ts

@@ -61,7 +61,6 @@ export async function buildProgram(): Promise<Command> {
   registerCommand(program, withKernelOptions((await import('../commands/token')).default))
   registerCommand(program, withKernelOptions((await import('../commands/get')).default))
   registerCommand(program, withKernelOptions((await import('../commands/mutate')).default))
-  registerCommand(program, withKernelOptions((await import('../commands/ls')).default))
   registerCommand(program, withKernelOptions((await import('../commands/describe')).default))
   registerCommand(program, withKernelOptions((await import('../commands/query')).default))
   registerCommand(program, withKernelOptions((await import('../commands/logs')).default))
@@ -159,7 +158,7 @@ export async function buildProgram(): Promise<Command> {
     `
 Command groups:
   Getting started  setup     (sign in, pick an instance, equip your workspace)
-  Kernel        ls, get, mutate, call, query, describe, token
+  Kernel        get, mutate, call, query, describe, token
   Management    admin, instance, domain, identity, auth, idp, update
   Agent         browser   (drive the GUI via agent-browser)
   Studio        studio    (launch the local Domain Studio GUI for a workspace)
@@ -173,7 +172,6 @@ Path syntax:
   @nodeId::method                Instance method on a node by UID
 
 Examples:
-  $ astrale ls @note --edge /:notes.example.dev:class.references
   $ astrale studio
   $ astrale admin status
   $ astrale update --check

package/src/telemetry/__tests__/gate.test.ts

@@ -49,7 +49,7 @@ describe('extractSignals / hasSignals', () => {
   })
 
   test('quiet session has no signals until a transcript is attached', () => {
-    const s = extractSignals([ev(['status'], 0), ev(['ls', '/'], 0)])
+    const s = extractSignals([ev(['status'], 0), ev(['query', '/'], 0)])
     expect(hasSignals(s)).toBe(false)
     s.harnessSessions = [
       {

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

@@ -1,29 +0,0 @@
-import type { Node } from '@astrale-os/sdk/graph/node'
-
-import { ClassPath } from '@astrale-os/sdk/graph/class'
-import { NodeId } from '@astrale-os/sdk/graph/node'
-import { normalizeProperties } from '@astrale-os/sdk/graph/properties'
-import { describe, expect, test } from 'bun:test'
-
-import { displayName, listProjection } from '../ls'
-
-describe('ls display projection', () => {
-  const node = {
-    id: NodeId('note-1'),
-    class: ClassPath.parse('/:notes.example.dev:class.Note'),
-    props: normalizeProperties({ 'notes.example.dev:class.Note.property.title': 'Hello' }),
-  } satisfies Node
-
-  /** @evidence TEST-CLI-LS-PROJECTS-CANONICAL-NODES */
-  test('uses canonical properties for display and @id for pipeable output', () => {
-    expect(displayName(node)).toBe('Hello')
-    expect(listProjection([node])).toMatchObject({
-      rows: [{ name: 'Hello', class: 'Note', id: 'note-1' }],
-      paths: ['@note-1'],
-    })
-  })
-
-  test('falls back to the canonical Node ID when no display property exists', () => {
-    expect(displayName({ ...node, props: normalizeProperties({}) })).toBe('@note-1')
-  })
-})

package/src/commands/ls.ts

@@ -1,125 +0,0 @@
-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 { KernelCommandOpts } from '../connection'
-import type { ListProjection } from '../lib/output'
-import type { CommandDefinition } from '../program/index'
-
-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
-  count?: boolean
-}
-
-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)
-  }
-
-  let path: string
-  let meta
-  let prepared
-  try {
-    ;({ 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)
-  }
-
-  await runKernelCommand({
-    opts,
-    label: `Neighbors of ${path}`,
-    fn: ({ graph }) => withSelfHint(() => graph.query(prepared.ast, { page: prepared.page }), meta),
-    format: (response, format) => {
-      const graph = completeGraph(response.result)
-      presentList(
-        [...graph.nodes],
-        { ...format, long: opts.long, quiet: opts.quiet, count: opts.count },
-        listProjection,
-      )
-      if (response.page.next && !isMachine(format) && !opts.quiet && !opts.count) {
-        process.stderr.write(`  cursor: ${response.page.next}\n`)
-      }
-    },
-  })
-}
-
-function completeGraph(result: QueryResult) {
-  if (result.kind !== 'graph') throw new TypeError('ls expected one complete graph Query result')
-  return result.graph
-}
-
-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}`),
-  }
-}
-
-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 one finite exact edge neighborhood',
-  afterHelpText: `
-Behavior:
-  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 @note --edge /:notes.example.dev:class.references
-  $ astrale ls @note --edge /:notes.example.dev:class.references --direction incoming --limit 25
-`,
-  arguments: [{ name: 'source', description: 'Canonical source Path or @id' }],
-  options: [
-    { flags: '--edge <class>', description: 'Exact Edge Class to traverse' },
-    {
-      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 (source, opts) => {
-    await lsCommand(source as string, opts as LsOpts)
-  },
-} satisfies CommandDefinition