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

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@astrale-os/cli",
-  "version": "0.4.0-alpha.13",
+  "version": "0.6.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,33 +23,23 @@
     "studio/server",
     "studio/shared",
     "studio/client/dist",
-    "studio/package.json"
+    "studio/package.json",
+    "viewer/dist",
+    "THIRD-PARTY-NOTICES.md"
   ],
   "type": "module",
   "exports": {
     "./keys": "./src/lib/keys.ts",
-    "./paths": "./src/lib/paths.ts"
+    "./paths": "./src/lib/paths.ts",
+    "./connect-core": "./src/connect-core.ts"
   },
   "publishConfig": {
     "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 +52,8 @@
   },
   "devDependencies": {
     "@astrale-os/ox": ">=0.1.0 <1.0.0",
-    "@astrale/commitlint-config": "jsr:~2.0.1",
+    "@astrale-os/shell": ">=0.3.5 <1.0.0",
+    "@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",
@@ -70,6 +61,7 @@
     "@typescript/native-preview": "latest",
     "husky": "~9.1.7",
     "lint-staged": "~16.2.7",
+    "msgpackr": "^1.12.1",
     "oxfmt": "0.52.0",
     "oxlint": "latest",
     "typescript": "~6.0.1-rc"
@@ -86,5 +78,15 @@
   "engines": {
     "node": ">=20"
   },
-  "packageManager": "pnpm@10.28.0"
-}
+  "scripts": {
+    "preinstall": "node .check-workspace.cjs",
+    "build": "bun scripts/build.ts",
+    "typecheck": "tsgo --noEmit && tsgo --noEmit -p viewer",
+    "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/command.ts

@@ -16,6 +16,8 @@ export type CommandDefinition = {
   description: string
   /** One-line summary shown in the parent's command list (Commander `.summary()`). */
   summary?: string
+  /** Hide from help listings (internal entries, e.g. `__view-serve`). */
+  hidden?: boolean
   aliases?: string[]
   arguments?: CommandArgument[]
   options?: CommandOption[]

package/src/commands/__tests__/admin-instance.test.ts

@@ -3,12 +3,13 @@ import { describe, expect, test } from 'bun:test'
 import type { IdentityStore } from '../../lib/identity'
 
 import { AuthError } from '../../errors'
-import { ADMIN_INSTANCE } from '../../lib/admin-instance'
+import { ADMIN_INSTANCE, adminInstanceMethod } from '../../lib/admin-instance'
 import { assertAlphaCreateIdentity } from '../instance/create'
 
 describe('admin-backed instance commands', () => {
   test('target the merged Instance class', () => {
-    expect(ADMIN_INSTANCE).toBe('/admin.astrale.ai/class.Instance')
+    expect(ADMIN_INSTANCE).toBe('/:admin.astrale.ai:class.Instance')
+    expect(adminInstanceMethod('list')).toBe('/:admin.astrale.ai:class.Instance:list')
   })
 
   test('instance create preflight points fresh installs at WorkOS login', () => {

package/src/commands/__tests__/domain-list.test.ts

@@ -1,7 +1,6 @@
 import { describe, expect, test } from 'bun:test'
 
-import type { DomainInfo } from '../../lib/admin-domain'
-
+import { ADMIN_DOMAIN, adminDomainMethod, type DomainInfo } from '../../lib/admin-domain'
 import { byDefaultThenName, domainProjection, type DomainRow } from '../domain/list'
 
 const strip = (s: string): string => s.replace(/\[[0-9;]*m/g, '')
@@ -18,6 +17,11 @@ function entry(over: Partial<DomainInfo>): DomainInfo {
 }
 
 describe('domain list — ordering', () => {
+  test('uses the semantic static method path', () => {
+    expect(ADMIN_DOMAIN).toBe('/:admin.astrale.ai:class.DomainEntry')
+    expect(adminDomainMethod('list')).toBe('/:admin.astrale.ai:class.DomainEntry:list')
+  })
+
   test('install-by-default sorts first, then alphabetical by origin', () => {
     const rows = [
       entry({ origin: 'zeta.astrale.ai' }),

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('shell.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/__tests__/view.test.ts

@@ -0,0 +1,100 @@
+import { beforeEach, describe, expect, mock, test } from 'bun:test'
+
+const getMock = mock(async (_path: string) => ({ id: 'issue-id' }))
+const clientCallMock = mock(async (): Promise<unknown> => {
+  throw new Error('View:resolve must not run for a bare --view-url')
+})
+const abMock = mock(async (_args: string[]) => ({
+  ok: true,
+  data: { snapshot: '- button "Ready" [ref=e1]' },
+  error: null,
+}))
+
+mock.module('../../kernel', () => ({
+  bindGraph: () => ({ get: getMock }),
+  expandSelfInPath: async (path: string) => ({ path }),
+  resolveKernelTarget: mock(),
+  withKernelClient: async (
+    _opts: unknown,
+    run: (ctx: { client: { call: typeof clientCallMock } }) => Promise<unknown>,
+  ) => run({ client: { call: clientCallMock } }),
+}))
+
+mock.module('../../lib/browser', () => ({
+  ab: abMock,
+  AGENT_BROWSER_REPO: 'vercel-labs/agent-browser',
+  BROWSER_DIR: '/tmp/astrale-browser',
+  findAgentBrowser: mock(async () => '/usr/bin/agent-browser'),
+}))
+
+beforeEach(() => {
+  getMock.mockClear()
+  clientCallMock.mockClear()
+  abMock.mockClear()
+})
+
+describe('view session resolution', () => {
+  test('uses a bare --view-url target only as shell context', async () => {
+    const { resolveSession } = await import('../view')
+    const targetPath = '/users/user-1/issue-1'
+
+    const result = await resolveSession(undefined, {
+      viewUrl: 'http://127.0.0.1:5173/ui/issues',
+      handshake: 'shell',
+      target: targetPath,
+    })
+
+    expect(getMock).toHaveBeenCalledWith(targetPath)
+    expect(clientCallMock).not.toHaveBeenCalled()
+    expect(result).toEqual({
+      view: {
+        url: 'http://127.0.0.1:5173/ui/issues',
+        functionId: 'dev-view',
+        handshake: 'shell',
+        name: 'dev',
+      },
+      target: { id: 'issue-id', path: targetPath },
+      candidates: [],
+    })
+  })
+
+  test('lists every candidate without requiring a view selection', async () => {
+    const { resolveSession } = await import('../view')
+    const targetPath = '/domains/ai-gateway.astrale.ai/core/gemini-3-5-flash'
+    const candidates = [
+      {
+        id: 'chat-id',
+        path: '/domains/ai-gateway.astrale.ai/views/chat',
+        url: 'https://ai-gateway.astrale.ai/ui/chat',
+        origin: 'class' as const,
+      },
+      {
+        id: 'model-id',
+        path: '/domains/ai-gateway.astrale.ai/views/model',
+        url: 'https://ai-gateway.astrale.ai/ui/model',
+        origin: 'class' as const,
+      },
+    ]
+    clientCallMock.mockImplementationOnce(async () => candidates)
+
+    const result = await resolveSession(targetPath, { list: true })
+
+    expect(result).toEqual({
+      target: { id: 'issue-id', path: targetPath },
+      candidates,
+    })
+  })
+})
+
+describe('view capture timing', () => {
+  test('settles the view before taking a screenshot', async () => {
+    const { runSnapshotExtras } = await import('../view')
+
+    await runSnapshotExtras({ screenshot: '/tmp/view.png' })
+
+    const commands = abMock.mock.calls.map(([args]) => args[0])
+    expect(commands.at(-1)).toBe('screenshot')
+    expect(commands.slice(0, -1).every((command) => command === 'snapshot')).toBe(true)
+    expect(commands.length).toBeGreaterThan(2)
+  })
+})