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

package/src/connection/failure/render.ts

@@ -1,116 +0,0 @@
-import chalk from 'chalk'
-
-import type { OperationRecovery } from '../command'
-import type { FailureDiagnostic } from './model'
-
-import { log } from '../../lib/log'
-import {
-  functionInputIssues,
-  queryInputRepair,
-  reasonCode,
-  schemaDataRemovalHint,
-  schemaUpgradeDetails,
-  schemaUpgradeHint,
-} from '../reasons'
-
-export function renderFailure(
-  failure: FailureDiagnostic,
-  machine: boolean,
-  url: string,
-  recovery: OperationRecovery | undefined,
-): void {
-  if (failure.kind === 'transport') return renderTransport(failure, machine, url, recovery)
-  if (failure.kind === 'response') return renderResponse(failure, machine)
-  if (machine)
-    return writeRaw({ error: failure.code, message: failure.message, hint: failure.hint })
-  log.error(`${chalk.bold(failure.code)}: ${failure.message}`)
-  if (failure.hint) log.dim(`  ${failure.hint}`)
-}
-
-function renderTransport(
-  failure: Extract<FailureDiagnostic, { kind: 'transport' }>,
-  machine: boolean,
-  url: string,
-  recovery: OperationRecovery | undefined,
-): void {
-  const invocation = failure.context.kind === 'invocation' ? failure.context : undefined
-  if (machine) {
-    writeRaw({
-      error: failure.code,
-      message: failure.message,
-      phase: failure.phase,
-      transport: failure.context,
-      ...(url === '' ? {} : { url }),
-      ...(invocation?.delivery === 'unknown' && recovery !== undefined ? recovery : {}),
-    })
-    return
-  }
-  log.error(`${chalk.bold(failure.code)}: ${failure.message}`)
-  if (url) log.dim(`  target: ${url}`)
-  log.dim(`  phase: ${failure.phase}`)
-  if (failure.phase === 'connect') log.dim('  Check the target and run `astrale status`.')
-  else if (failure.phase === 'timeout') log.dim('  Try increasing `--timeout`.')
-  else if (invocation?.delivery === 'unknown') renderRecovery(recovery)
-}
-
-function renderResponse(
-  failure: Extract<FailureDiagnostic, { kind: 'response' }>,
-  machine: boolean,
-): void {
-  const code = reasonCode(failure.reason)
-  const issues = functionInputIssues(failure.reason)
-  const removalHint = schemaDataRemovalHint(failure.reason)
-  const addressNotPublic = code === 'SCHEMA_DOMAIN_ADDRESS_NOT_PUBLIC'
-  const upgrade = schemaUpgradeDetails(failure.reason)
-  const message = addressNotPublic
-    ? 'Expose the Domain through a public HTTPS URL or public tunnel, then retry.'
-    : removalHint && !machine
-      ? 'Existing business data still uses schema definitions being removed.'
-      : failure.message
-  const hint =
-    code === 'FUNCTION_INPUT_INVALID' && (machine || issues.length === 0)
-      ? 'Use `astrale introspect <path>` to see the callable input.'
-      : (removalHint ?? (upgrade ? schemaUpgradeHint(upgrade) : undefined))
-  if (machine) {
-    writeRaw({
-      error: 'RESPONSE_ERROR',
-      code: failure.code,
-      message,
-      ...(failure.reason === undefined ? {} : { reason: failure.reason }),
-      ...(hint === undefined ? {} : { hint }),
-    })
-    return
-  }
-  const label = addressNotPublic
-    ? 'SCHEMA_DOMAIN_ADDRESS_NOT_PUBLIC'
-    : removalHint
-      ? 'DATA_MIGRATION_REQUIRED'
-      : `RESPONSE_ERROR(${failure.code})`
-  log.error(`${chalk.bold(label)}: ${message}`)
-  if (code && !addressNotPublic && !removalHint) log.dim(`  reason: ${code}`)
-  for (const issue of issues)
-    console.log(
-      chalk.red(`  ${issue.path || '<input>'}: ${issue.message} (${chalk.dim(issue.code)})`),
-    )
-  const repair = queryInputRepair(failure.reason)
-  if (repair?.phase === 'plan') log.dim(`  ${repair.path ?? '/'}  ${repair.issue}`)
-  else if (repair?.phase === 'limit')
-    log.dim(`  ${repair.path ?? '/'}  ${repair.limit} limit ${repair.actual}/${repair.maximum}`)
-  else if (repair) log.dim(`  ${repair.path}  ${repair.phase} input`)
-  if (upgrade?.issue === 'issuer-changed') {
-    log.dim(`  installed issuer: ${upgrade.installedIssuer}`)
-    log.dim(`  replacement issuer: ${upgrade.replacementIssuer}`)
-  }
-  if (hint) log.dim(`  ${hint}`)
-}
-
-function renderRecovery(recovery: OperationRecovery | undefined): void {
-  if (!recovery)
-    return log.dim('  Delivery is unknown; do not automatically retry a mutating call.')
-  log.dim('  Delivery is unknown; retry with the same operation id:')
-  log.dim(`  operation: ${recovery.operation}`)
-  log.dim(`  ${recovery.retry}`)
-}
-
-const writeRaw = (payload: Record<string, unknown>): void =>
-  void process.stderr.write(`${JSON.stringify(payload)}\n`)

package/src/connection/index.ts

@@ -1,8 +0,0 @@
-export { createPathCall } from './call'
-export { runKernelCommand } from './command'
-export type { KernelCommandOpts, OperationRecovery } from './command'
-export { expandSelfInCall, expandSelfInPath, withSelfHint } from './self'
-export type { SelfExpansionMeta } from './self'
-export { withAdminClientSession, withClientSession, type ConnectionContext } from './session'
-export { registrationKeyForTarget } from './target'
-export type { AdminConnectionOptions, ConnectionOptions, ConnectionTarget } from './target'

package/src/connection/lifetime.ts

@@ -1,25 +0,0 @@
-const MINIMUM_CREDENTIAL_TTL_SECONDS = 60
-const INVOCATION_RECEIPT_MARGIN_SECONDS = 5
-const CACHE_HANDOFF_MARGIN_SECONDS = 5
-const TOKEN_EXCHANGE_SETTLEMENT_MARGIN_SECONDS = 15
-
-/** Cover the complete command deadline while preserving the existing short-command floor. */
-export function invocationCredentialTtlSeconds(timeoutMs: number): number {
-  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1) {
-    throw new TypeError('Invocation credential timeout must be a positive safe integer.')
-  }
-  return Math.max(
-    MINIMUM_CREDENTIAL_TTL_SECONDS,
-    Math.ceil(timeoutMs / 1_000) + INVOCATION_RECEIPT_MARGIN_SECONDS,
-  )
-}
-
-/** Leave the final carrier lifetime intact after source delegation and issuer exchange settle. */
-export function exchangeCredentialTtlSeconds(timeoutMs: number): number {
-  return invocationCredentialTtlSeconds(timeoutMs) + TOKEN_EXCHANGE_SETTLEMENT_MARGIN_SECONDS
-}
-
-/** Refresh a cached token before the final Session carrier can cross a second boundary. */
-export function cachedCredentialTtlSeconds(timeoutMs: number): number {
-  return invocationCredentialTtlSeconds(timeoutMs) + CACHE_HANDOFF_MARGIN_SECONDS
-}

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 }),
-    },
-  }
-}