@astrale-os/cli 1.0.0-beta.32 → 1.0.0-beta.43

package/src/connection/session.ts

@@ -1,203 +0,0 @@
-import type { AuthApi } from '@astrale-os/sdk/auth'
-import type { GraphApi } from '@astrale-os/sdk/client'
-import type {
-  ClientSessionOptions,
-  SessionAuth,
-  SessionRouteStore,
-} from '@astrale-os/sdk/client/session'
-
-import { createAuth } from '@astrale-os/sdk/auth'
-import { call } from '@astrale-os/sdk/client'
-import { createGraph } from '@astrale-os/sdk/client'
-import { ClientSession } from '@astrale-os/sdk/client/session'
-
-import type { AstraleConfig } from '../lib/config'
-import type { AdminConnectionOptions, ConnectionOptions, ConnectionTarget } from './target'
-
-import {
-  AdminInstanceNotFoundError,
-  connectAdminInstances,
-  findOwnedInstance,
-  type InstanceInfo,
-} from '../admin/instance'
-import { AstraleError } from '../errors'
-import { fetchWithCaFile } from '../lib/ca-fetch'
-import { readConfig } from '../lib/config'
-import { log } from '../lib/log'
-import { isMachine } from '../lib/output'
-import { SESSION_ROUTE_STORE } from '../state/session-routes'
-import { bindCredentialIdentity } from './auth'
-import { createCliCredential, validateCredentialSelection } from './credential'
-import { resolveAdminConnectionTarget, resolveConnectionTarget } from './target'
-
-const DEFAULT_TIMEOUT_MS = 30_000
-const MAXIMUM_ROUTE_AGE_MS = 5 * 60_000
-
-function warnMissingExplicitTarget(options: ConnectionOptions, target: ConnectionTarget): void {
-  if (options.instance !== undefined || options.url !== undefined) return
-  if (!isMachine(options)) return
-  log.warn(`No -i/--url; using ${target.slug ?? target.url}`)
-}
-
-export interface ConnectionContext {
-  readonly session: ClientSession
-  readonly graph: GraphApi
-  readonly auth: AuthApi
-  readonly target: ConnectionTarget
-  /** Local identity label selected for this session; absent for raw credentials or anonymous use. */
-  readonly identity?: string
-}
-
-interface OwnedConnection {
-  readonly context: ConnectionContext
-  close(): void
-}
-
-export type ConnectionFactory = (
-  target: ConnectionTarget,
-  timeoutMs: number,
-  options: ConnectionOptions,
-  config: AstraleConfig,
-) => OwnedConnection
-
-/** Resolve one ordinary target, run a command action, then close terminally. */
-export async function withClientSession<Value>(
-  options: ConnectionOptions,
-  action: (context: ConnectionContext) => Promise<Value>,
-): Promise<Value> {
-  validateCredentialSelection(options)
-  const timeoutMs = resolveTimeoutMs(options.timeout)
-  const config = await readConfig()
-  const target = await resolveConnectionTarget(options, config, {
-    managed: (slug) => lookupManagedInstance(slug, options),
-  })
-  options = await bindCredentialIdentity(options, target)
-  warnMissingExplicitTarget(options, target)
-  return runResolvedClientSession(target, timeoutMs, options, config, action, openConnection)
-}
-
-/** Resolve the configured Admin Domain target under the same terminal lifecycle. */
-export async function withAdminClientSession<Value>(
-  options: AdminConnectionOptions,
-  action: (context: ConnectionContext) => Promise<Value>,
-): Promise<Value> {
-  validateCredentialSelection(options)
-  const timeoutMs = resolveTimeoutMs(options.timeout)
-  const config = await readConfig()
-  const target = await resolveAdminConnectionTarget(options, config)
-  options = await bindCredentialIdentity(options, target)
-  return runResolvedClientSession(target, timeoutMs, options, config, action, openConnection)
-}
-
-/** Owner-private seam used to prove validation order and cleanup without network I/O. */
-export async function withResolvedClientSession<Value>(
-  target: ConnectionTarget,
-  options: ConnectionOptions,
-  config: AstraleConfig,
-  action: (context: ConnectionContext) => Promise<Value>,
-  open: ConnectionFactory = openConnection,
-): Promise<Value> {
-  validateCredentialSelection(options)
-  const timeoutMs = resolveTimeoutMs(options.timeout)
-  return runResolvedClientSession(target, timeoutMs, options, config, action, open)
-}
-
-async function runResolvedClientSession<Value>(
-  target: ConnectionTarget,
-  timeoutMs: number,
-  options: ConnectionOptions,
-  config: AstraleConfig,
-  action: (context: ConnectionContext) => Promise<Value>,
-  open: ConnectionFactory,
-): Promise<Value> {
-  const connection = open(target, timeoutMs, options, config)
-  try {
-    return await action(connection.context)
-  } catch (error) {
-    if (error instanceof Error) (error as Error & { url?: string }).url = target.url
-    throw error
-  } finally {
-    connection.close()
-  }
-}
-
-export function resolveTimeoutMs(raw: string | undefined): number {
-  if (raw === undefined) return DEFAULT_TIMEOUT_MS
-  if (!/^\d+$/.test(raw)) {
-    throw new AstraleError(
-      'INVALID_FLAG',
-      `Invalid --timeout value "${raw}" — expected a positive integer (milliseconds)`,
-    )
-  }
-  const value = Number.parseInt(raw, 10)
-  if (!Number.isSafeInteger(value) || value <= 0) {
-    throw new AstraleError(
-      'INVALID_FLAG',
-      `Invalid --timeout value "${raw}" — must be a positive integer`,
-    )
-  }
-  return value
-}
-
-function openConnection(
-  target: ConnectionTarget,
-  timeoutMs: number,
-  options: ConnectionOptions,
-  config: AstraleConfig,
-): OwnedConnection {
-  const fetch = target.caFile === undefined ? globalThis.fetch : fetchWithCaFile(target.caFile)
-  const auth = createCliCredential(target, options, config, fetch, timeoutMs)
-  const session = new ClientSession(createClientSessionOptions(target, fetch, auth, timeoutMs))
-  const graph = createGraph((call, request) => session.call(call, request))
-  const authApi = createAuth((path, input, request) => session.call(call(path, input), request))
-  return {
-    context: Object.freeze({
-      session,
-      graph,
-      auth: authApi,
-      target,
-      ...(options.as === undefined ? {} : { identity: options.as }),
-    }),
-    close() {
-      session.close()
-    },
-  }
-}
-
-/** Owner-private construction seam proving that transport and source identity stay distinct. */
-export function createClientSessionOptions(
-  target: ConnectionTarget,
-  fetch: NonNullable<ClientSessionOptions['fetch']>,
-  auth: SessionAuth | undefined,
-  timeoutMs: number,
-  routeStore: SessionRouteStore = SESSION_ROUTE_STORE,
-): ClientSessionOptions {
-  return {
-    kernel: target.kernelIssuer,
-    fetch,
-    ...(auth === undefined ? {} : { auth }),
-    routeStore,
-    policy: {
-      maximumRouteAgeMs: MAXIMUM_ROUTE_AGE_MS,
-      ...(new URL(target.url).protocol === 'http:' ? { allowInsecureHttp: true } : {}),
-    },
-    envelopeTransport: 'http',
-    timeoutMs,
-  }
-}
-
-export async function lookupManagedInstance(
-  slug: string,
-  options: ConnectionOptions,
-  openAdmin: typeof withAdminClientSession = withAdminClientSession,
-  connect: typeof connectAdminInstances = connectAdminInstances,
-): Promise<InstanceInfo> {
-  return openAdmin(
-    Object.freeze(options.timeout === undefined ? {} : { timeout: options.timeout }),
-    async (context) => {
-      const found = findOwnedInstance(await (await connect(context)).list(), slug)
-      if (found === undefined) throw new AdminInstanceNotFoundError(slug)
-      return found
-    },
-  )
-}

package/src/connection/target.ts

@@ -1,112 +0,0 @@
-import type { IssuerId } from '@astrale-os/sdk/auth'
-
-import { issuer } from '@astrale-os/sdk/auth'
-
-import type { InstanceInfo } from '../lib/admin-instance'
-import type { AdminTargetCommandOpts } from '../lib/admin-target'
-import type { AstraleConfig } from '../lib/config'
-import type { InstanceStore } from '../lib/instance'
-import type { ResolvedInstanceTarget } from '../lib/instance-target'
-
-import { resolveInstanceTarget } from '../lib/instance-target'
-
-export interface ConnectionOptions {
-  readonly url?: string
-  readonly instance?: string
-  readonly timeout?: string
-  readonly as?: string
-  readonly creds?: string
-  readonly anonymous?: boolean
-  readonly ci?: boolean
-}
-
-export interface AdminConnectionOptions extends ConnectionOptions {
-  readonly admin?: string
-  readonly adminUrl?: string
-  readonly domainIssuer?: string
-}
-
-export interface ConnectionTarget {
-  readonly url: string
-  readonly kernelIssuer: IssuerId
-  readonly domainIssuer?: IssuerId
-  readonly slug?: string
-  readonly defaultIdentity?: string
-  readonly caFile?: string
-}
-
-export interface TargetDependencies {
-  readonly instances?: InstanceStore
-  readonly managed?: (slug: string) => Promise<InstanceInfo>
-}
-
-/** Stable local identity-registration key for the exact selected source Kernel. */
-export function registrationKeyForTarget(target: ConnectionTarget): string {
-  return target.slug ?? target.url
-}
-
-/** Resolve the existing URL / instance / active precedence into one exact source Kernel. */
-export async function resolveConnectionTarget(
-  options: ConnectionOptions,
-  config: AstraleConfig,
-  dependencies: TargetDependencies = {},
-): Promise<ConnectionTarget> {
-  const request =
-    options.url !== undefined && options.instance === undefined
-      ? ({ source: 'url', url: options.url } as const)
-      : options.instance !== undefined
-        ? ({ source: 'name', name: options.instance } as const)
-        : ({ source: 'active' } as const)
-  const resolved = await resolveInstanceTarget(request, {
-    config,
-    ...(dependencies.instances === undefined ? {} : { instances: dependencies.instances }),
-    admin: {},
-    ...(dependencies.managed === undefined ? {} : { managed: dependencies.managed }),
-  })
-  return connectionTarget(resolved, options.url)
-}
-
-/** Resolve the configured Admin Domain target without entering managed-instance discovery. */
-export async function resolveAdminConnectionTarget(
-  options: AdminConnectionOptions,
-  config: AstraleConfig,
-  instances?: InstanceStore,
-): Promise<ConnectionTarget> {
-  const resolved = await resolveInstanceTarget(
-    { source: 'admin' },
-    {
-      config,
-      admin: adminLookupOptions(options),
-      ...(instances === undefined ? {} : { instances }),
-    },
-  )
-  return connectionTarget(resolved)
-}
-
-export function adminLookupOptions(options: AdminConnectionOptions): AdminTargetCommandOpts {
-  return {
-    ...(options.admin === undefined ? {} : { admin: options.admin }),
-    ...(options.adminUrl === undefined ? {} : { adminUrl: options.adminUrl }),
-    ...(options.domainIssuer === undefined ? {} : { domainIssuer: options.domainIssuer }),
-    ...(options.instance === undefined ? {} : { instance: options.instance }),
-    ...(options.url === undefined ? {} : { url: options.url }),
-  }
-}
-
-function connectionTarget(
-  resolved: ResolvedInstanceTarget,
-  urlOverride?: string,
-): ConnectionTarget {
-  return Object.freeze({
-    url: urlOverride ?? resolved.url,
-    kernelIssuer: issuer.accept(resolved.kernelIssuer),
-    ...(resolved.domainIssuer === undefined
-      ? {}
-      : { domainIssuer: issuer.accept(resolved.domainIssuer) }),
-    ...(resolved.name === undefined ? {} : { slug: resolved.name }),
-    ...(resolved.defaultIdentity === undefined
-      ? {}
-      : { defaultIdentity: resolved.defaultIdentity }),
-    ...(resolved.caFile === undefined ? {} : { caFile: resolved.caFile }),
-  })
-}

package/src/connection/tsconfig.json

@@ -1,6 +0,0 @@
-{
-  "extends": "../../tsconfig.json",
-  "compilerOptions": { "types": ["@types/node"] },
-  "include": ["*.ts"],
-  "exclude": ["__tests__"]
-}

package/src/errors.ts

@@ -1,66 +0,0 @@
-export class AstraleError extends Error {
-  code: string
-  hint?: string
-
-  constructor(code: string, message: string, hint?: string, options?: ErrorOptions) {
-    if (message.trim() === '') throw new TypeError('CLI error message must be non-blank.')
-    super(message, options)
-    this.name = 'AstraleError'
-    this.code = code
-    this.hint = hint
-  }
-}
-
-export class AuthError extends AstraleError {
-  constructor(message: string, hint?: string) {
-    super('AUTH_ERROR', message, hint ?? 'Run `astrale identity create <name>` to set up keys')
-  }
-}
-
-// ── Typed errors (DESIGN.md §4.6, §4.7, §5.1, §10, §11, §12) ─────────
-
-export class IssuerUnreachableError extends AstraleError {
-  constructor(url: string, hint?: string) {
-    super(
-      'ISSUER_UNREACHABLE',
-      `Issuer endpoint "${url}" not reachable`,
-      hint ?? 'Check the target URL and issuer configuration',
-    )
-  }
-}
-
-export class ReservedSlugError extends AstraleError {
-  constructor(slug: string) {
-    super('RESERVED_SLUG', `Slug "${slug}" is reserved`, 'Pick a different slug')
-  }
-}
-
-export class IdentifierCollisionError extends AstraleError {
-  constructor(identifier: string, existingEntity: string) {
-    super(
-      'IDENTIFIER_COLLISION',
-      `Identifier "${identifier}" collides with existing ${existingEntity}`,
-      'Slug and name share the same CLI namespace (§4.7). Pick a unique value.',
-    )
-  }
-}
-
-export class IdentityKeyMissingError extends AstraleError {
-  constructor(subject: string) {
-    super(
-      'IDENTITY_KEY_MISSING',
-      `No private key on disk for identity "${subject}"`,
-      `Run \`astrale identity create ${subject}\` to generate one.`,
-    )
-  }
-}
-
-export class NotImplementedError extends AstraleError {
-  constructor(feature: string, hint?: string) {
-    super(
-      'NOT_IMPLEMENTED',
-      `"${feature}" is not implemented in v1`,
-      hint ?? 'Track the design implementation progress for updates',
-    )
-  }
-}

package/src/graph/.spec/api.d.ts

@@ -1,41 +0,0 @@
-import type { ClassKey, ClassRef } from '@astrale-os/sdk/graph/class'
-import type { MutationAST } from '@astrale-os/sdk/mutation'
-import type { QueryAST, QueryDirection } from '@astrale-os/sdk/query'
-
-/** Admit one canonical Domain-rooted Class Path into its DSL coordinate. */
-export function classReference(input: string, label: string): ClassRef
-
-/** Admit one canonical Domain-rooted Class Path into its exact string identity. */
-export function classKey(input: string, label: string): ClassKey
-
-/** Untrusted CLI fields used to author or admit one exact Query V6 request. */
-export interface QueryCommandInput {
-  readonly sources: readonly string[]
-  readonly class?: string
-  readonly ast?: unknown
-  readonly edge?: string
-  readonly direction?: QueryDirection
-  readonly limit?: string
-  readonly cursor?: string
-}
-
-/** Canonical query plus caller-bound pagination kept outside the AST. */
-export interface PreparedQuery {
-  readonly ast: QueryAST
-  readonly page: Readonly<{ readonly size: number; readonly after?: string }>
-}
-
-/** Admit canonical Query V6 or author its supported Path/Class/one-edge CLI subset. */
-export function prepareQuery(input: QueryCommandInput): PreparedQuery
-
-/** Admit canonical Mutation V3 or its exact authoring input; legacy PatchData is rejected. */
-export function prepareMutation(input: unknown): MutationAST
-
-/** Return the user-facing leaf of one exact qualified Property key. */
-export function unqualifyProperty(key: string): string
-
-/** Read one property by exact key first, then by its qualified leaf name. */
-export function nodeProperty(
-  node: { readonly props: Readonly<Record<string, unknown>> } | null | undefined,
-  name: string,
-): unknown

package/src/graph/.spec/laws/documents.ts

@@ -1,24 +0,0 @@
-import { defineLaw } from '@astrale-os/spec/authoring'
-
-export const CLI_GRAPH_QUERY_V6 = defineLaw({
-  id: 'CLI-GRAPH-QUERY-V6',
-  statement:
-    'CLI query input becomes exactly one canonical Query V6 document with an explicit finite limit; --class authors one exact Class source, exact Property ordering and Node or Edge projection profiles are admitted through the canonical AST surface, and legacy versions or unsupported selector combinations fail before a Graph call.',
-  tests: [
-    { file: '__tests__/query.test.ts', id: 'TEST-CLI-GRAPH-AUTHORS-QUERY-V6' },
-    { file: '__tests__/query.test.ts', id: 'TEST-CLI-GRAPH-AUTHORS-CLASS-QUERY' },
-    { file: '__tests__/query.test.ts', id: 'TEST-CLI-GRAPH-ADMITS-QUERY-V6-ORDERING' },
-    { file: '__tests__/query.test.ts', id: 'TEST-CLI-GRAPH-ADMITS-QUERY-V6-PROJECTIONS' },
-    { file: '__tests__/query.test.ts', id: 'TEST-CLI-GRAPH-REJECTS-LEGACY-QUERY' },
-  ],
-})
-
-export const CLI_GRAPH_MUTATION_V2 = defineLaw({
-  id: 'CLI-GRAPH-MUTATION-V2',
-  statement:
-    'CLI mutation input is admitted as canonical Mutation V2 or its exact authoring input; PatchData and other historical shapes never reach GraphApi.mutate.',
-  tests: [
-    { file: '__tests__/mutation.test.ts', id: 'TEST-CLI-GRAPH-ADMITS-MUTATION-V2' },
-    { file: '__tests__/mutation.test.ts', id: 'TEST-CLI-GRAPH-REJECTS-PATCH-DATA' },
-  ],
-})

package/src/graph/.spec/laws/projection.ts

@@ -1,13 +0,0 @@
-import { defineLaw } from '@astrale-os/spec/authoring'
-
-export const CLI_GRAPH_PROPERTY_PROJECTION = defineLaw({
-  id: 'CLI-GRAPH-PROPERTY-PROJECTION',
-  statement:
-    'An exact property key wins over a qualified leaf-name match; otherwise the first canonical property with that leaf is presented without rewriting the Node.',
-  tests: [
-    {
-      file: '__tests__/projection.test.ts',
-      id: 'TEST-CLI-GRAPH-PROJECTS-QUALIFIED-PROPERTIES',
-    },
-  ],
-})

package/src/graph/.spec/layout.ts

@@ -1,14 +0,0 @@
-import { defineLayout } from '@astrale-os/spec/authoring'
-
-export default defineLayout({
-  entries: [
-    '__tests__/',
-    'class.ts',
-    'index.ts',
-    'mutation.ts',
-    'projection.ts',
-    'query.ts',
-    'tsconfig.json',
-  ],
-  exact: true,
-})

package/src/graph/__tests__/mutation.test.ts

@@ -1,51 +0,0 @@
-import { describe, expect, test } from 'bun:test'
-
-import { prepareMutation } from '../mutation'
-
-describe('prepareMutation', () => {
-  /** @evidence TEST-CLI-GRAPH-ADMITS-MUTATION-V3 */
-  test('creates one canonical Mutation V3 document from exact authoring input', () => {
-    expect(
-      JSON.parse(
-        JSON.stringify(
-          prepareMutation({
-            preconditions: [],
-            operations: [
-              {
-                op: 'node.create',
-                as: 'note',
-                class: 'notes.example.dev:class.Note',
-                props: {},
-              },
-            ],
-          }),
-        ),
-      ),
-    ).toEqual({
-      format: 'astrale.graph.mutation',
-      version: 'v3',
-      preconditions: [],
-      operations: [
-        {
-          op: 'node.create',
-          as: 'note',
-          class: 'notes.example.dev:class.Note',
-          props: {},
-        },
-      ],
-    })
-  })
-
-  /** @evidence TEST-CLI-GRAPH-REJECTS-PATCH-DATA */
-  test('rejects legacy PatchData instead of narrowing it', () => {
-    expect(() => prepareMutation({ nodes: { create: [] }, edges: { create: [] } })).toThrow(
-      /Legacy PatchData/,
-    )
-  })
-
-  test('rejects an empty operations list in CLI language', () => {
-    expect(() => prepareMutation({ preconditions: [], operations: [] })).toThrow(
-      'Mutation V3 requires at least one operation',
-    )
-  })
-})

package/src/graph/__tests__/projection.test.ts

@@ -1,22 +0,0 @@
-import { describe, expect, test } from 'bun:test'
-
-import { nodeProperty, unqualifyProperty } from '../projection'
-
-describe('graph presentation properties', () => {
-  /** @evidence TEST-CLI-GRAPH-PROJECTS-QUALIFIED-PROPERTIES */
-  test('prefers exact keys and otherwise projects a qualified leaf', () => {
-    const node = {
-      props: {
-        name: 'exact',
-        '/:example.test:class.Widget.property.name': 'qualified',
-        '/:example.test:class.Widget.property.description': 'shown',
-      },
-    }
-
-    expect(nodeProperty(node, 'name')).toBe('exact')
-    expect(nodeProperty(node, 'description')).toBe('shown')
-    expect(unqualifyProperty('/:example.test:class.Widget.property.description')).toBe(
-      'description',
-    )
-  })
-})