@astrale-os/cli 1.0.0-beta.0 → 1.0.0-beta.10

package/dist/types/admin/binding.d.ts

@@ -0,0 +1,19 @@
+import type { Input } from '@astrale-os/sdk/client';
+import type { ClientSession } from '@astrale-os/sdk/client/session';
+import type { ResolvedClass, ResolvedProperty } from '@astrale-os/sdk/schema';
+import type { DomainBinding } from '@astrale-os/shell';
+import { Path } from '@astrale-os/sdk/graph/path';
+export type AdminBinding = DomainBinding;
+/** Bind the exact Admin revision installed on this source Kernel. */
+export declare function bindAdmin(session: ClientSession): Promise<AdminBinding>;
+/** Admit an injected dynamic binding as the Admin Domain. */
+export declare function requireAdminBinding(binding: AdminBinding): AdminBinding;
+/** Resolve one required Admin Class without rebuilding its schema contract. */
+export declare function requireAdminClass(binding: AdminBinding, name: string, kind: 'node'): ResolvedClass<'node'>;
+export declare function requireAdminClass(binding: AdminBinding, name: string, kind: 'edge'): ResolvedClass<'edge'>;
+/** Resolve one required Admin Core Node as its canonical projection Path. */
+export declare function requireAdminCore(binding: AdminBinding, name: string): Path;
+/** Resolve one effective Property by unambiguous member name. */
+export declare function requireAdminProperty(owner: ResolvedClass, name: string): ResolvedProperty<unknown>;
+/** Invoke one resolved executable instance Method through Kernel Client. */
+export declare function invokeAdminMethod(session: ClientSession, binding: AdminBinding, owner: ResolvedClass<'node'>, name: string, receiver: Path, input: Input): Promise<unknown>;

package/dist/types/admin/instance/client.d.ts

@@ -0,0 +1,22 @@
+import type { ClientSession } from '@astrale-os/sdk/client/session';
+import { type AdminBinding } from '../binding';
+import { type DomainInstallReceipt, type InstanceInfo, type OwnedInstanceInfo } from './model';
+export interface AdminInstanceContext {
+    readonly session: ClientSession;
+}
+export interface AdminInstanceApi {
+    list(): Promise<OwnedInstanceInfo[]>;
+    create(slug: string): Promise<InstanceInfo>;
+    status(identifier: string): Promise<InstanceInfo>;
+    delete(identifier: string): Promise<InstanceInfo>;
+    installDomain(identifier: string, domain: string): Promise<DomainInstallReceipt>;
+}
+export interface AdminInstanceDependencies {
+    readonly bind?: (session: ClientSession) => Promise<AdminBinding>;
+    readonly operationId?: (kind: 'create' | 'status' | 'delete' | 'install-domain') => string;
+}
+/**
+ * Bind one discovered Admin root revision and expose only the public Instance
+ * product journey. No Host lifecycle method is present on this capability.
+ */
+export declare function connectAdminInstances(context: AdminInstanceContext, dependencies?: AdminInstanceDependencies): Promise<AdminInstanceApi>;

package/dist/types/admin/instance/index.d.ts

@@ -0,0 +1,2 @@
+export { connectAdminInstances, type AdminInstanceApi, type AdminInstanceContext, type AdminInstanceDependencies, } from './client';
+export { AdminInstanceNotFoundError, findOwnedInstance, formatInstanceState, type DomainInstallReceipt, type InstanceInfo, type InstanceState, type OwnedInstanceInfo, } from './model';

package/dist/types/admin/instance/model.d.ts

@@ -4,9 +4,7 @@ export interface InstanceInfo {
     readonly id: string;
     readonly slug: string;
     readonly url: string;
-    readonly hostId?: string;
-    readonly region?: string;
-    readonly state?: InstanceState;
+    readonly state: InstanceState;
     readonly phase?: string;
     readonly error?: string | null;
     readonly createdAt?: string;
@@ -24,17 +22,12 @@ export interface DomainInstallReceipt {
     readonly installedRevision?: string;
     readonly error?: string;
 }
-export declare class AdminInstanceNotFoundError extends Error {
-    readonly identifier: string;
-    readonly name = "NotFoundError";
-    constructor(identifier: string);
-}
-export declare class AdminHostNotFoundError extends Error {
+export declare class AdminInstanceNotFoundError extends AstraleError {
     readonly identifier: string;
-    readonly name = "NotFoundError";
     constructor(identifier: string);
 }
 /** Match an owner-scoped Instance by slug, canonical Node Path, or bare Node id. */
 export declare function findOwnedInstance(instances: readonly OwnedInstanceInfo[], identifier: string): OwnedInstanceInfo | undefined;
-/** Human-readable location of an Instance (state, region, and Host Path). */
-export declare function formatInstanceLocation(info: InstanceInfo): string;
+/** Human-readable non-ready lifecycle state for one Instance. */
+export declare function formatInstanceState(info: InstanceInfo): string;
+import { AstraleError } from '../../errors';

package/dist/types/connection/auth.d.ts

@@ -1,4 +1,5 @@
 import type { AstraleConfig } from '../lib/config';
+import type { ConnectionOptions, ConnectionTarget } from './target';
 import { type Identity } from '../identity/registry';
 import { IdpAudienceMismatchError } from '../lib/idp';
 import { IdpSessionNoRefreshTokenError } from '../lib/idp-session';
@@ -7,6 +8,8 @@ export type KeyIdentityAuthOptions = {
     subject?: string;
     audience: string;
 };
+/** Pin the local identity label before a session performs any authenticated effect. */
+export declare function bindCredentialIdentity<Options extends ConnectionOptions>(options: Options, target: ConnectionTarget): Promise<Options>;
 /**
  * Resolve a signed JWT credential from CLI options.
  *

package/dist/types/connection/call.d.ts

@@ -0,0 +1,3 @@
+import { type Call } from '@astrale-os/sdk/client';
+/** Convert the CLI's untrusted text/JSON boundary into the one public Call representation. */
+export declare function createPathCall(path: string, input: unknown): Call;

package/dist/types/connection/command.d.ts

@@ -0,0 +1,27 @@
+import type { ConnectionContext } from './session';
+import type { ConnectionOptions } from './target';
+export interface KernelCommandOpts extends ConnectionOptions {
+    readonly raw?: boolean;
+    readonly json?: boolean;
+    readonly format?: 'yaml' | 'json';
+    readonly debug?: boolean;
+}
+export interface OperationRecovery {
+    readonly operation: string;
+    readonly retry: string;
+}
+/**
+ * Encapsulates the standard kernel command lifecycle:
+ * spinner → connect → call → timing → output → error handling.
+ *
+ * Commands provide a `fn` that does the actual work and an optional
+ * `format` callback for custom output. If `format` is omitted, the
+ * result is passed to the standard `output()` function.
+ */
+export declare function runKernelCommand<T>(input: {
+    readonly opts: KernelCommandOpts;
+    readonly label: string;
+    readonly recovery?: OperationRecovery;
+    readonly fn: (context: ConnectionContext) => Promise<T>;
+    readonly format?: (result: T, options: KernelCommandOpts, machine: boolean) => void | Promise<void>;
+}): Promise<void>;

package/dist/types/connection/credential.d.ts

@@ -0,0 +1,14 @@
+import type { Fetch } from '@astrale-os/sdk/client';
+import type { SessionAuth } from '@astrale-os/sdk/client/session';
+import { type IssuerId } from '@astrale-os/sdk/auth';
+import type { AstraleConfig } from '../lib/config';
+import type { ConnectionOptions, ConnectionTarget } from './target';
+export interface SourceCredentialResolver {
+    resolve(audience: IssuerId, signal: AbortSignal): Promise<string>;
+}
+/** Resolve source authority; an omitted Session delegation preserves exact current authority. */
+export declare function createConnectionCredential(expectedSourceIssuer: IssuerId, source: SourceCredentialResolver): SessionAuth;
+/** Bind CLI identity state and Core Auth delegation to one Session auth capability. */
+export declare function createCliCredential(target: ConnectionTarget, options: ConnectionOptions, config: AstraleConfig, fetch?: Fetch, timeoutMs?: number): SessionAuth | undefined;
+/** Reject contradictory explicit credential selections before identity or network access. */
+export declare function validateCredentialSelection(options: ConnectionOptions): void;

package/dist/types/connection/errors.d.ts

@@ -0,0 +1 @@
+export { formatKernelError, functionInputIssues, schemaUpgradeHint } from './failure';

package/dist/types/connection/exchange.d.ts

@@ -0,0 +1,9 @@
+import type { IssuerId } from '@astrale-os/sdk/auth';
+import type { Fetch } from '@astrale-os/sdk/client';
+import type { SourceCredentialResolver } from './credential';
+import type { ConnectionTarget } from './target';
+import { ExchangeCredentialCache } from '../state/exchange-credentials';
+/** Exchange exact authenticated User authority for a Domain bearer bound to this Kernel. */
+export declare function createExchangeCredentialResolver(target: ConnectionTarget & {
+    readonly domainIssuer: IssuerId;
+}, source: SourceCredentialResolver, fetch: Fetch, timeoutMs: number, cache?: ExchangeCredentialCache): SourceCredentialResolver;

package/dist/types/connection/failure/classify.d.ts

@@ -0,0 +1,2 @@
+import type { FailureDiagnostic } from './model';
+export declare function classifyFailure(error: unknown): FailureDiagnostic;

package/dist/types/connection/failure/index.d.ts

@@ -0,0 +1,5 @@
+import type { OperationRecovery } from '../command';
+export { functionInputIssues, schemaUpgradeHint } from '../reasons';
+export declare function formatKernelError(error: unknown, machine: boolean, urlArg?: string, debug?: boolean, options?: {
+    recovery?: OperationRecovery;
+}): Promise<void>;

package/dist/types/connection/failure/model.d.ts

@@ -0,0 +1,25 @@
+export type TransportDiagnosticContext = {
+    readonly kind: 'acquisition';
+    readonly resource: 'publication' | 'bundle';
+} | {
+    readonly kind: 'invocation';
+    readonly delivery: 'not-sent' | 'unknown';
+    readonly invocation?: unknown;
+};
+export type FailureDiagnostic = {
+    readonly kind: 'simple';
+    readonly code: string;
+    readonly message: string;
+    readonly hint?: string;
+} | {
+    readonly kind: 'response';
+    readonly code: number;
+    readonly message: string;
+    readonly reason?: unknown;
+} | {
+    readonly kind: 'transport';
+    readonly code: 'CONNECTION_ERROR' | 'DISCONNECTED' | 'TIMEOUT' | 'TRANSPORT_ERROR';
+    readonly message: string;
+    readonly phase: string;
+    readonly context: TransportDiagnosticContext;
+};

package/dist/types/connection/failure/render.d.ts

@@ -0,0 +1,3 @@
+import type { OperationRecovery } from '../command';
+import type { FailureDiagnostic } from './model';
+export declare function renderFailure(failure: FailureDiagnostic, machine: boolean, url: string, recovery: OperationRecovery | undefined): void;

package/dist/types/connection/index.d.ts

@@ -0,0 +1,8 @@
+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/dist/types/connection/reasons.d.ts

@@ -0,0 +1,37 @@
+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;
+};
+export declare function reasonCode(reason: unknown): string | undefined;
+/** Admit only bounded caller-safe Function input issues established by the Kernel. */
+export declare function functionInputIssues(reason: unknown): readonly FunctionInputIssue[];
+/** Admit only public Query-input repair variants; unknown details remain machine-only. */
+export declare function queryInputRepair(reason: unknown): QueryInputRepair | undefined;
+/** Decode bounded recovery guidance while preserving the admitted reason itself elsewhere. */
+export declare function schemaUpgradeDetails(reason: unknown): SchemaUpgradeDetails | undefined;
+export declare function schemaUpgradeHint(details: SchemaUpgradeDetails): string;
+export declare function schemaDataRemovalHint(reason: unknown): string | undefined;

package/dist/types/connection/self.d.ts

@@ -0,0 +1,37 @@
+import type { ConnectionContext } from './session';
+/** 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 declare function withSelfHint<T>(action: () => Promise<T>, meta: SelfExpansionMeta | undefined): Promise<T>;
+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 declare function resolveSelfIdAuthenticated(context: ConnectionContext, dependencies?: ResolveSelfIdDependencies): Promise<{
+    readonly id: string;
+    readonly slug?: string;
+}>;
+/** Expand @self in path-like commands and return metadata for NotFound diagnostics. */
+export declare function expandSelfInPath(path: string, context: ConnectionContext): Promise<{
+    readonly path: string;
+    readonly meta?: SelfExpansionMeta;
+}>;
+/** Expand @self once across one Call path and its CLI-authored string parameters. */
+export declare function expandSelfInCall(path: string, parameters: Readonly<Record<string, unknown>>, context: ConnectionContext): Promise<{
+    readonly path: string;
+    readonly parameters: Readonly<Record<string, unknown>>;
+    readonly meta?: SelfExpansionMeta;
+}>;
+export {};

package/dist/types/connection/session.d.ts

@@ -0,0 +1,31 @@
+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 { ClientSession } from '@astrale-os/sdk/client/session';
+import type { AstraleConfig } from '../lib/config';
+import type { AdminConnectionOptions, ConnectionOptions, ConnectionTarget } from './target';
+import { connectAdminInstances, type InstanceInfo } from '../admin/instance';
+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 declare function withClientSession<Value>(options: ConnectionOptions, action: (context: ConnectionContext) => Promise<Value>): Promise<Value>;
+/** Resolve the configured Admin Domain target under the same terminal lifecycle. */
+export declare function withAdminClientSession<Value>(options: AdminConnectionOptions, action: (context: ConnectionContext) => Promise<Value>): Promise<Value>;
+/** Owner-private seam used to prove validation order and cleanup without network I/O. */
+export declare function withResolvedClientSession<Value>(target: ConnectionTarget, options: ConnectionOptions, config: AstraleConfig, action: (context: ConnectionContext) => Promise<Value>, open?: ConnectionFactory): Promise<Value>;
+export declare function resolveTimeoutMs(raw: string | undefined): number;
+/** Owner-private construction seam proving that transport and source identity stay distinct. */
+export declare function createClientSessionOptions(target: ConnectionTarget, fetch: NonNullable<ClientSessionOptions['fetch']>, auth: SessionAuth | undefined, timeoutMs: number): ClientSessionOptions;
+export declare function lookupManagedInstance(slug: string, options: ConnectionOptions, openAdmin?: typeof withAdminClientSession, connect?: typeof connectAdminInstances): Promise<InstanceInfo>;
+export {};

package/dist/types/connection/target.d.ts

@@ -0,0 +1,38 @@
+import type { IssuerId } 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';
+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 declare function registrationKeyForTarget(target: ConnectionTarget): string;
+/** Resolve the existing URL / instance / active precedence into one exact source Kernel. */
+export declare function resolveConnectionTarget(options: ConnectionOptions, config: AstraleConfig, dependencies?: TargetDependencies): Promise<ConnectionTarget>;
+/** Resolve the configured Admin Domain target without entering managed-instance discovery. */
+export declare function resolveAdminConnectionTarget(options: AdminConnectionOptions, config: AstraleConfig, instances?: InstanceStore): Promise<ConnectionTarget>;
+export declare function adminLookupOptions(options: AdminConnectionOptions): AdminTargetCommandOpts;

package/dist/types/errors.d.ts

@@ -1,7 +1,7 @@
 export declare class AstraleError extends Error {
     code: string;
     hint?: string;
-    constructor(code: string, message: string, hint?: string);
+    constructor(code: string, message: string, hint?: string, options?: ErrorOptions);
 }
 export declare class AuthError extends AstraleError {
     constructor(message: string, hint?: string);

package/dist/types/lib/admin-instance.d.ts

@@ -0,0 +1,17 @@
+import type { AdminConnectionOptions, ConnectionContext } from '../connection';
+export { AdminInstanceNotFoundError, findOwnedInstance, formatInstanceState, type InstanceInfo, type InstanceState, type OwnedInstanceInfo, } from '../admin/instance';
+/** Resolve the Admin target and read only the caller-visible Instance inventory. */
+export declare function listOwnedInstances(options: AdminConnectionOptions): Promise<import("./admin-instance").OwnedInstanceInfo[]>;
+/** Read caller-visible inventory together with the exact local identity used for the Admin call. */
+export declare function listOwnedInstancesWithIdentity(options: AdminConnectionOptions): Promise<Readonly<{
+    instances: import("./admin-instance").OwnedInstanceInfo[];
+    identity?: string | undefined;
+}>>;
+/** Reuse an already-open Admin session for a caller-visible Instance inventory. */
+export declare function listOwnedInstancesInContext(context: ConnectionContext): Promise<import("./admin-instance").OwnedInstanceInfo[]>;
+/** Request one managed Instance; Admin owns infrastructure placement. */
+export declare function createOwnedInstance(options: AdminConnectionOptions, slug: string): Promise<import("./admin-instance").InstanceInfo>;
+/** Refresh one exact caller-visible Instance through its V2 receiver Method. */
+export declare function statusOwnedInstance(options: AdminConnectionOptions, identifier: string): Promise<import("./admin-instance").InstanceInfo>;
+/** Delete one exact caller-visible Instance through its V2 receiver Method. */
+export declare function deleteOwnedInstance(options: AdminConnectionOptions, identifier: string): Promise<import("./admin-instance").InstanceInfo>;

package/dist/types/lib/admin-target.d.ts

@@ -2,8 +2,12 @@ import { z } from 'zod';
 import type { AstraleConfig } from './config';
 import type { InstanceStore } from './instance';
 export declare const DEFAULT_ADMIN_TARGET_NAME = "admin";
-export declare const DEFAULT_ADMIN_TARGET_URL = "https://admin.eu.astrale.ai/api";
-export declare const DEFAULT_ADMIN_DOMAIN_ISSUER = "https://admin.beta.astrale.ai";
+export declare function defaultAdminTargetForChannel(channel: string): {
+    readonly url: string;
+    readonly domainIssuer: string;
+};
+export declare const DEFAULT_ADMIN_TARGET_URL: string;
+export declare const DEFAULT_ADMIN_DOMAIN_ISSUER: string;
 export declare const DEFAULT_ADMIN_TARGET_CONFIG: {
     name: string;
     url: string;

package/dist/types/lib/failure-debug.d.ts

@@ -0,0 +1 @@
+export declare function printFailureDebug(error: unknown, url: string): void;

package/dist/types/lib/idp.d.ts

@@ -162,6 +162,8 @@ export declare const IdpSessionSchema: z.ZodObject<{
     idp: z.ZodString;
     issuer: z.ZodString;
     subject: z.ZodString;
+    /** OAuth client that issued this session's refresh token. */
+    clientId: z.ZodOptional<z.ZodString>;
     audience: z.ZodOptional<z.ZodString>;
     organizationId: z.ZodOptional<z.ZodString>;
     access_token: z.ZodString;
@@ -194,6 +196,8 @@ export declare const IdpSessionSchema: z.ZodObject<{
     idp: z.ZodString;
     issuer: z.ZodString;
     subject: z.ZodString;
+    /** OAuth client that issued this session's refresh token. */
+    clientId: z.ZodOptional<z.ZodString>;
     audience: z.ZodOptional<z.ZodString>;
     organizationId: z.ZodOptional<z.ZodString>;
     access_token: z.ZodString;
@@ -226,6 +230,8 @@ export declare const IdpSessionSchema: z.ZodObject<{
     idp: z.ZodString;
     issuer: z.ZodString;
     subject: z.ZodString;
+    /** OAuth client that issued this session's refresh token. */
+    clientId: z.ZodOptional<z.ZodString>;
     audience: z.ZodOptional<z.ZodString>;
     organizationId: z.ZodOptional<z.ZodString>;
     access_token: z.ZodString;
@@ -316,6 +322,7 @@ export declare function fetchOidcMetadata(issuer: string): Promise<OidcMetadata>
 export declare function workosAuthKitMetadata(apiHost?: string, clientId?: string): OidcMetadata;
 export declare function builtinIdpConfig(name: string, clientIdOverride?: string, env?: NodeJS.ProcessEnv): IdpConfig | null;
 export declare function workosClientIdFromEnv(env?: NodeJS.ProcessEnv): string | undefined;
+export declare function legacyBuiltinWorkosReplacement(existing: IdpConfig, clientIdOverride?: string, env?: NodeJS.ProcessEnv): IdpConfig | undefined;
 export declare function postForm(url: string, params: URLSearchParams): Promise<TokenResponse>;
 export declare function postJson(url: string, bodyInput: Record<string, string>): Promise<TokenResponse>;
 export declare function tokenExpiresAt(token: TokenResponse): string | undefined;

package/dist/types/lib/instance-target.d.ts

@@ -1,5 +1,5 @@
-import type { InstanceInfo } from '../admin/instance/model';
 import type { AstraleConfig } from './config';
+import { type InstanceInfo } from '../admin/instance/model';
 import { type AdminTargetCommandOpts, type ResolvedAdminTarget } from './admin-target';
 import { type InstanceStore } from './instance';
 export type InstanceTargetRequest = {

package/dist/types/lib/instance.d.ts

@@ -172,7 +172,13 @@ export declare function upsertInstance(key: string, opts?: AddInstanceOpts): Pro
  * normalized kernel URL). Reports the previous URL when an existing
  * bookmark was repointed to a different kernel so callers can warn.
  */
-export declare function upsertManagedBookmark(key: string, slug: string, rawUrl: string, organizationId?: string): Promise<{
+export declare function upsertManagedBookmark(input: Readonly<{
+    key: string;
+    slug: string;
+    url: string;
+    organizationId?: string;
+    defaultIdentity?: string;
+}>): Promise<{
     entry: InstanceEntry;
     repointedFrom?: string;
 }>;
@@ -182,7 +188,9 @@ export declare function clearActive(identifier: string): Promise<void>;
 export declare function getActive(config?: AstraleConfig): Promise<InstanceEntry & {
     name: string;
 }>;
-export declare function resolveInstance(identifier: string, config?: AstraleConfig): Promise<ResolvedInstance>;
+export declare function resolveInstance(identifier: string, config?: AstraleConfig, opts?: {
+    persist?: boolean;
+}): Promise<ResolvedInstance>;
 export declare function resolveKernelUrl(opts: {
     url?: string;
     instance?: string;

package/dist/types/lib/log.d.ts

@@ -10,9 +10,11 @@ export declare const log: {
 };
 /** Report an error with hint (when present) and exit. `--json` / `--ci` / a
  *  non-TTY stdout always get one structured JSON line on stderr. */
-export declare function fatal(e: unknown, opts?: MachineOpts): never;
-/** Admit expected invalid input and exit through {@link fatal}. */
-export declare function failClosed(error: unknown, opts?: MachineOpts): never;
+export declare function fatal(e: unknown, opts?: MachineOpts & {
+    readonly debug?: boolean;
+}): never;
+/** Project only a caller-authored admission failure into the CLI input family. */
+export declare function failInput(error: unknown, opts?: MachineOpts): never;
 /** Shortcut for stub commands that aren't wired in v1 (§15). */
 export declare function fatalNotImplemented(feature: string, hint?: string): never;
 /**

package/dist/types/lib/meta.d.ts

@@ -6,8 +6,8 @@
  * `jwks_uri`) and JWKS at `/.well-known/jwks.json`. These helpers probe
  * both to verify the issuer is alive and publishes at least one key.
  *
- * Domain workers may expose `/meta` for deployment drift detection; that is
- * outside this connect-only CLI surface.
+ * Domain deployment readiness uses the canonical Domain Publication; that is
+ * outside this issuer-connectivity helper.
  */
 type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
 export type DiscoveryDocument = {

package/dist/types/lib/proc.d.ts

@@ -0,0 +1,43 @@
+import { type ChildProcess, type StdioOptions } from 'node:child_process';
+export type RunResult = {
+    /** Exit code, or -1 when the process was killed by a signal. */
+    code: number;
+    stdout: string;
+    stderr: string;
+};
+/**
+ * Spawn a child process and capture stdout/stderr as UTF-8 text.
+ *
+ * Uses `node:child_process` rather than `Bun.spawn` so the exact same code runs
+ * under both the Bun-compiled standalone binary (Linux/macOS) and the Node/npm
+ * build (Windows and any Node user). The promise rejects only when the process
+ * fails to spawn (e.g. ENOENT); a non-zero exit resolves with that `code` so
+ * callers can branch on it.
+ */
+export declare function run(file: string, args?: string[], opts?: {
+    cwd?: string;
+}): Promise<RunResult>;
+/**
+ * Spawn a child process with inherited stdio so its output streams live to the
+ * user's terminal. Used for hand-held installs (npm / npx) where progress
+ * matters and the output is for the human, not for parsing. Resolves with the
+ * exit code; rejects only when the process fails to spawn (e.g. ENOENT).
+ */
+export declare function runInherit(file: string, args?: string[], opts?: {
+    cwd?: string;
+}): Promise<number>;
+/**
+ * Spawn a LONG-LIVED child and return the handle immediately so the caller can
+ * supervise it (wait for exit, forward signals, tear down siblings). Unlike
+ * run()/runInherit() — which resolve only once the child closes — this is for
+ * servers the command keeps attached to (e.g. `astrale studio`'s Bun server and
+ * Vite dev process). Same node:child_process basis (cross-runtime) and bare
+ * PATH-name lookup convention. Default stdio streams stdout/stderr live but
+ * ignores stdin, so two supervised children never contend for the TTY.
+ */
+export declare function spawnHandle(file: string, args?: string[], opts?: {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    stdio?: StdioOptions;
+    detached?: boolean;
+}): ChildProcess;

package/dist/types/lib/self.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Lexical `@self` helpers. Effective-principal resolution is deliberately not
+ * local: connection/self.ts asks the authenticated target Kernel through
+ * Identity.whoami before replacing any reference.
+ */
+/** Cheap pre-check before invoking authenticated principal resolution. */
+export declare function containsSelfRef(input: string): boolean;
+/** Replace every admitted `@self` token with one authenticated NodeId. */
+export declare function expandSelfReferences(input: string, selfId: string): string;