@astrale-os/cli 1.0.0-beta.9 → 1.0.0-npm-deprecated.0

package/src/connection/reasons.ts

@@ -1,209 +0,0 @@
-export type FunctionInputIssue = Readonly<{
-  code: string
-  path?: string
-  message: string
-}>
-
-export type QueryInputRepair =
-  | Readonly<{ phase: 'decode' | 'input'; path: string }>
-  | Readonly<{ phase: 'plan'; issue: string; path?: string }>
-  | Readonly<{
-      phase: 'limit'
-      limit: string
-      maximum: number
-      actual: number
-      path?: string
-    }>
-
-export type SchemaUpgradeDetails =
-  | {
-      readonly origin?: string
-      readonly issue?: undefined
-    }
-  | {
-      readonly origin: string
-      readonly issue: 'issuer-changed'
-      readonly installedIssuer: string
-      readonly replacementIssuer: string
-    }
-
-const JSON_POINTER = /^(?:\/(?:[^~/]|~[01])*)*$/u
-const MAXIMUM_FUNCTION_ISSUES = 32
-const MAXIMUM_FUNCTION_ISSUE_MESSAGE_LENGTH = 512
-
-export function reasonCode(reason: unknown): string | undefined {
-  if (!record(reason) || typeof reason.code !== 'string') return undefined
-  return stableCode(reason.code) ? reason.code : undefined
-}
-
-/** Admit only bounded caller-safe Function input issues established by the Kernel. */
-export function functionInputIssues(reason: unknown): readonly FunctionInputIssue[] {
-  if (!reasonWithCode(reason, 'FUNCTION_INPUT_INVALID')) return Object.freeze([])
-  const issues = reason.details.issues
-  if (!Array.isArray(issues)) return Object.freeze([])
-  return Object.freeze(
-    issues.slice(0, MAXIMUM_FUNCTION_ISSUES).flatMap((candidate): FunctionInputIssue[] => {
-      if (
-        !record(candidate) ||
-        typeof candidate.code !== 'string' ||
-        !stableCode(candidate.code) ||
-        typeof candidate.message !== 'string' ||
-        candidate.message.length === 0 ||
-        candidate.message.length > MAXIMUM_FUNCTION_ISSUE_MESSAGE_LENGTH ||
-        candidate.message.normalize('NFC') !== candidate.message ||
-        containsControl(candidate.message) ||
-        (candidate.path !== undefined && !coordinate(candidate.path))
-      ) {
-        return []
-      }
-      return [
-        Object.freeze({
-          code: candidate.code,
-          ...(candidate.path === undefined ? {} : { path: candidate.path }),
-          message: candidate.message,
-        }),
-      ]
-    }),
-  )
-}
-
-/** Admit only public Query-input repair variants; unknown details remain machine-only. */
-export function queryInputRepair(reason: unknown): QueryInputRepair | undefined {
-  if (!reasonWithCode(reason, 'QUERY_INPUT_INVALID')) return undefined
-  const details = reason.details
-  if (details.phase === 'decode' || details.phase === 'input') {
-    if (!exact(details, ['phase', 'path']) || !coordinate(details.path)) return undefined
-    return Object.freeze({ phase: details.phase, path: details.path })
-  }
-  if (details.phase === 'plan') {
-    const fields = details.path === undefined ? ['phase', 'issue'] : ['phase', 'issue', 'path']
-    if (
-      !exact(details, fields) ||
-      typeof details.issue !== 'string' ||
-      !stableCode(details.issue) ||
-      (details.path !== undefined && !coordinate(details.path))
-    ) {
-      return undefined
-    }
-    return Object.freeze({
-      phase: 'plan',
-      issue: details.issue,
-      ...(details.path === undefined ? {} : { path: details.path }),
-    })
-  }
-  if (details.phase !== 'limit') return undefined
-  const fields =
-    details.path === undefined
-      ? ['phase', 'limit', 'maximum', 'actual']
-      : ['phase', 'limit', 'maximum', 'actual', 'path']
-  if (
-    !exact(details, fields) ||
-    typeof details.limit !== 'string' ||
-    !Number.isSafeInteger(details.maximum) ||
-    (details.maximum as number) < 0 ||
-    !Number.isSafeInteger(details.actual) ||
-    (details.actual as number) <= (details.maximum as number) ||
-    (details.path !== undefined && !coordinate(details.path))
-  ) {
-    return undefined
-  }
-  return Object.freeze({
-    phase: 'limit',
-    limit: details.limit,
-    maximum: details.maximum as number,
-    actual: details.actual as number,
-    ...(details.path === undefined ? {} : { path: details.path }),
-  })
-}
-
-/** Decode bounded recovery guidance while preserving the admitted reason itself elsewhere. */
-export function schemaUpgradeDetails(reason: unknown): SchemaUpgradeDetails | undefined {
-  if (!record(reason) || reason.code !== 'SCHEMA_UPGRADE_INCOMPATIBLE') return undefined
-  const details = record(reason.details) ? reason.details : {}
-  const origin = typeof details.origin === 'string' ? details.origin : undefined
-  if (
-    details.issue === 'issuer-changed' &&
-    origin !== undefined &&
-    typeof details.installedIssuer === 'string' &&
-    typeof details.replacementIssuer === 'string'
-  ) {
-    return {
-      origin,
-      issue: details.issue,
-      installedIssuer: details.installedIssuer,
-      replacementIssuer: details.replacementIssuer,
-    }
-  }
-  return origin === undefined ? {} : { origin }
-}
-
-export function schemaUpgradeHint(details: SchemaUpgradeDetails): string {
-  const target = details.origin ?? '<origin>'
-  const explanation =
-    details.issue === 'issuer-changed'
-      ? 'A replacement cannot change an installed Domain issuer.'
-      : 'The replacement changes an immutable part of the installed Domain.'
-  return (
-    `${explanation} If this change is intentional, first run ` +
-    `\`astrale domain uninstall ${target}\`, then install it again. ` +
-    'The Kernel refuses uninstall while dependents or business data remain; uninstall never deletes business data.'
-  )
-}
-
-export function schemaDataRemovalHint(reason: unknown): string | undefined {
-  if (!reasonWithCode(reason, 'DATA_MIGRATION_REQUIRED')) return undefined
-  const requirements = reason.details.requirements
-  if (
-    !Array.isArray(requirements) ||
-    requirements.length === 0 ||
-    !requirements.every(
-      (item) =>
-        record(item) && item.operation === 'remove-facts' && item.reason === 'destructive-change',
-    )
-  ) {
-    return undefined
-  }
-  return 'Delete this data explicitly, then retry. No data was deleted.'
-}
-
-function reasonWithCode(
-  input: unknown,
-  code: string,
-): input is Readonly<{ code: string; details: Readonly<Record<string, unknown>> }> {
-  return (
-    record(input) &&
-    exact(input, ['code', 'details']) &&
-    input.code === code &&
-    record(input.details)
-  )
-}
-
-function coordinate(input: unknown): input is string {
-  return (
-    typeof input === 'string' &&
-    input.length <= 1_024 &&
-    input.normalize('NFC') === input &&
-    JSON_POINTER.test(input)
-  )
-}
-
-function stableCode(input: string): boolean {
-  return /^[A-Z][A-Z0-9_]{0,127}$/u.test(input) && input.normalize('NFC') === input
-}
-
-function containsControl(input: string): boolean {
-  for (const character of input) {
-    const point = character.codePointAt(0)!
-    if (point <= 0x1f || point === 0x7f) return true
-  }
-  return false
-}
-
-function record(input: unknown): input is Readonly<Record<string, unknown>> {
-  return input !== null && typeof input === 'object' && !Array.isArray(input)
-}
-
-function exact(input: Readonly<Record<string, unknown>>, fields: readonly string[]): boolean {
-  const actual = Object.keys(input)
-  return actual.length === fields.length && actual.every((field) => fields.includes(field))
-}

package/src/connection/self.ts

@@ -1,138 +0,0 @@
-import { NodeUnavailableError } from '@astrale-os/sdk/client'
-
-import type { ConnectionContext } from './session'
-
-import { AstraleError } from '../errors'
-import { containsSelfRef, expandSelfReferences } from '../lib/self'
-
-/** Metadata attached to errors after an authenticated caller-authored @self expansion. */
-export interface SelfExpansionMeta {
-  readonly original: string
-  readonly expanded: string
-  readonly selfId: string
-  readonly slug?: string
-}
-
-/**
- * Run `action`; if it throws NodeUnavailableError, retain the authenticated
- * expansion for precise diagnostics. The error is re-thrown either way.
- */
-export async function withSelfHint<T>(
-  action: () => Promise<T>,
-  meta: SelfExpansionMeta | undefined,
-): Promise<T> {
-  if (!meta) return action()
-  try {
-    return await action()
-  } catch (err) {
-    if (err instanceof NodeUnavailableError) {
-      ;(err as Error & { expandedFromSelf?: SelfExpansionMeta }).expandedFromSelf = meta
-    }
-    throw err
-  }
-}
-
-type AuthenticatedSelf = {
-  readonly id?: unknown
-  readonly slug?: string
-}
-
-export type ResolveSelfIdDependencies = {
-  readonly whoami?: (context: ConnectionContext) => Promise<AuthenticatedSelf>
-}
-
-/** Resolve @self only from the effective principal authenticated by the selected Kernel. */
-export async function resolveSelfIdAuthenticated(
-  context: ConnectionContext,
-  dependencies: ResolveSelfIdDependencies = {},
-): Promise<{ readonly id: string; readonly slug?: string }> {
-  const resolved = await (dependencies.whoami ?? whoamiSelfId)(context)
-  if (typeof resolved.id !== 'string' || resolved.id.trim().length === 0) {
-    throw new AstraleError(
-      'SELF_RESOLUTION_FAILED',
-      '`@self` could not be resolved: authenticated Identity.whoami returned no NodeId.',
-    )
-  }
-  return resolved.slug === undefined
-    ? { id: resolved.id }
-    : { id: resolved.id, slug: resolved.slug }
-}
-
-async function whoamiSelfId({ auth, target }: ConnectionContext): Promise<AuthenticatedSelf> {
-  return {
-    ...(await auth.whoami()),
-    ...(target.slug === undefined ? {} : { slug: target.slug }),
-  }
-}
-
-/** Expand @self in path-like commands and return metadata for NotFound diagnostics. */
-export async function expandSelfInPath(
-  path: string,
-  context: ConnectionContext,
-): Promise<{ readonly path: string; readonly meta?: SelfExpansionMeta }> {
-  const expanded = await expandSelfValues(path, [], context)
-  return expanded.meta === undefined
-    ? { path: expanded.path }
-    : { path: expanded.path, meta: expanded.meta }
-}
-
-/** Expand @self once across one Call path and its CLI-authored string parameters. */
-export async function expandSelfInCall(
-  path: string,
-  parameters: Readonly<Record<string, unknown>>,
-  context: ConnectionContext,
-): Promise<{
-  readonly path: string
-  readonly parameters: Readonly<Record<string, unknown>>
-  readonly meta?: SelfExpansionMeta
-}> {
-  const values = Object.values(parameters).filter(
-    (value): value is string => typeof value === 'string',
-  )
-  const expanded = await expandSelfValues(path, values, context)
-  if (expanded.parameters === values) {
-    return expanded.meta === undefined
-      ? { path: expanded.path, parameters }
-      : { path: expanded.path, parameters, meta: expanded.meta }
-  }
-  let index = 0
-  const entries = Object.entries(parameters).map(([key, value]) => [
-    key,
-    typeof value === 'string' ? expanded.parameters[index++] : value,
-  ])
-  const resolved = Object.freeze(Object.fromEntries(entries))
-  return expanded.meta === undefined
-    ? { path: expanded.path, parameters: resolved }
-    : { path: expanded.path, parameters: resolved, meta: expanded.meta }
-}
-
-async function expandSelfValues(
-  path: string,
-  parameters: readonly string[],
-  context: ConnectionContext,
-): Promise<{
-  readonly path: string
-  readonly parameters: readonly string[]
-  readonly meta?: SelfExpansionMeta
-}> {
-  if (!containsSelfRef(path) && !parameters.some(containsSelfRef)) {
-    return { path, parameters }
-  }
-  const self = await resolveSelfIdAuthenticated(context)
-  const expandedPath = expandSelfReferences(path, self.id)
-  const expandedParameters = parameters.map((parameter) => expandSelfReferences(parameter, self.id))
-  const changed =
-    expandedPath !== path ||
-    expandedParameters.some((parameter, index) => parameter !== parameters[index])
-  if (!changed) return { path, parameters }
-  return {
-    path: expandedPath,
-    parameters: expandedParameters,
-    meta: {
-      original: path,
-      expanded: expandedPath,
-      selfId: self.id,
-      ...(self.slug === undefined ? {} : { slug: self.slug }),
-    },
-  }
-}

package/src/connection/session.ts

@@ -1,196 +0,0 @@
-import type { AuthApi } from '@astrale-os/sdk/auth'
-import type { GraphApi } from '@astrale-os/sdk/client'
-import type { ClientSessionOptions, SessionAuth } 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 { 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,
-): ClientSessionOptions {
-  return {
-    kernel: target.kernelIssuer,
-    fetch,
-    ...(auth === undefined ? {} : { auth }),
-    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__"]
-}