@astrale-os/cli 0.8.0-alpha.0 → 0.8.1-alpha.2

package/dist/types/lib/login-flow.d.ts

@@ -0,0 +1,49 @@
+import { type IdpSession } from './idp';
+/**
+ * The IdP login flow, lifted out of the `auth login` command so it can be
+ * driven from anywhere (the command renders the result; `astrale setup` runs it
+ * as one hand-held step). The side effects — saving the session cache and
+ * upserting the IdP-backed identity — live here so every caller gets identical
+ * behavior; presentation (the device URL is logged here; success lines are the
+ * caller's) does not.
+ */
+export type LoginFlowOpts = {
+    idp?: string;
+    name?: string;
+    scope?: string;
+    audience?: string;
+    clientId?: string;
+    clientSecretEnv?: string;
+    clientCredentials?: boolean;
+    code?: string;
+    redirectUri?: string;
+    codeVerifier?: string;
+    /** Switch the default identity to the one we just logged in (default true). */
+    use?: boolean;
+    /**
+     * Optional device-flow presentation boundary. When supplied, the caller
+     * receives the verification coordinates instead of terminal log output.
+     */
+    onVerification?: (event: DeviceVerification) => void;
+};
+export type DeviceVerification = {
+    verificationUri: string;
+    verificationUriComplete?: string;
+    userCode?: string;
+    expiresIn?: number;
+    message?: string;
+};
+export type LoginResult = {
+    session: IdpSession;
+    identityName: string;
+    idpName: string;
+};
+/**
+ * Authenticate against an IdP and persist the result. Throws on any failure
+ * (no session is written) — notably BEFORE saving when an explicit `--audience`
+ * does not match the minted access token, so a wrong-audience login never
+ * leaves a half-written cache.
+ */
+export declare function loginViaIdp(opts: LoginFlowOpts): Promise<LoginResult>;
+/** Resolve which IdP to use: explicit name, the sole configured one, or WorkOS. */
+export declare function resolveIdpName(name: string | undefined): Promise<string>;

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

@@ -0,0 +1,36 @@
+/**
+ * Issuer reachability helpers — OIDC discovery + JWKS.
+ *
+ * Kernels don't expose `/meta`. They expose OIDC discovery at
+ * `/.well-known/openid-configuration` (standard, returns `issuer` and
+ * `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.
+ */
+type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+export type DiscoveryDocument = {
+    /** OIDC issuer URL. */
+    issuer: string;
+    /** JWKS URI (defaults to `<issuer>/.well-known/jwks.json`). */
+    jwksUri: string;
+};
+export declare function fetchDiscovery(url: string, timeoutMs?: number, fetchImpl?: FetchLike): Promise<DiscoveryDocument>;
+export declare function fetchJwks(jwksUri: string, timeoutMs?: number, fetchImpl?: FetchLike): Promise<{
+    keys: Array<{
+        kid?: string;
+    }>;
+}>;
+/**
+ * Discover the WorkOS organization an instance host pins
+ */
+export declare function fetchOrgHint(url: string, timeoutMs?: number): Promise<string | undefined>;
+/** Verify the pinned issuer publishes self-consistent OIDC discovery and a non-empty JWKS. */
+export declare function checkIssuerReachability(url: string, issuerOverride?: string, fetchImpl?: FetchLike): Promise<{
+    issuer: string;
+    keys: Array<{
+        kid?: string;
+    }>;
+}>;
+export {};

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

@@ -0,0 +1,83 @@
+import { type Column } from './table';
+export type { Column } from './table';
+export type OutputOpts = {
+    raw?: boolean;
+    json?: boolean;
+    format?: 'yaml' | 'json';
+};
+export type RawOutputOpts = Pick<OutputOpts, 'raw' | 'json'>;
+export declare const RAW_OUTPUT_OPTIONS: readonly [{
+    readonly flags: '--json';
+    readonly description: 'Always-valid JSON (for jq)';
+}, {
+    readonly flags: '--raw';
+    readonly description: 'Unwrapped: bare scalar / raw bytes / JSON for objects';
+}];
+/**
+ * Is the consumer a machine (emit structured data, not a pretty view)?
+ * True for `--json`, `--raw`, or any non-TTY stdout (pipe, redirect, CI, agent).
+ */
+export declare function isMachine(opts?: RawOutputOpts): boolean;
+/**
+ * `--raw` = the *unwrapped* value (bare scalar, raw bytes). The raw-vs-json
+ * distinction only manifests for scalars and binary; objects/arrays fall back
+ * to JSON under either flag.
+ */
+export declare function isUnwrapped(opts?: RawOutputOpts): boolean;
+/**
+ * Write structured data to stdout in the appropriate format.
+ *
+ * Precedence:
+ * - `--raw` / `--json` → plain JSON, no colors (machine-readable)
+ * - explicit `--format yaml|json` → honor regardless of TTY, colors only on TTY
+ * - default on TTY → highlighted YAML
+ * - default on non-TTY → plain JSON
+ *
+ * Void-returning syscalls surface as `undefined` here; `JSON.stringify(undefined)`
+ * itself returns `undefined`, which would print the bare string `undefined` and
+ * break any caller doing `JSON.parse(stdout)`. Normalize to `null` (parseable
+ * JSON, valid YAML) at the entry so every formatter branch is consistent.
+ */
+export declare function output(data: unknown, opts: OutputOpts): void;
+export type PresentOpts = OutputOpts & {
+    denoise?: boolean;
+};
+/** One display row per item plus the columns and (optional) `-q` paths. */
+export type ListProjection = {
+    columns: Column[];
+    rows: Array<Record<string, string>>;
+    paths?: string[];
+};
+export type ListOpts = OutputOpts & {
+    quiet?: boolean;
+    count?: boolean;
+    long?: boolean;
+};
+/**
+ * Strip heavy, low-signal keys (serialized schema blobs, SVG icons, code) at any
+ * depth — so machine output is the kernel's data minus the noise, never a wall.
+ */
+export declare function denoise(value: unknown): unknown;
+/**
+ * Present a single kernel value, shape- and audience-aware.
+ *
+ * - scalar → `--raw` bare (no quotes, for `X=$(…)`) · `--json`/pipe JSON · TTY bare
+ * - object → YAML on a TTY, JSON for machines (delegates to {@link output})
+ * - array  → YAML/JSON fallback (use {@link presentList} for a table)
+ *
+ * `null`/`undefined` normalize to `null` (via `output`) so `JSON.parse(stdout)`
+ * never breaks.
+ */
+export declare function present(value: unknown, opts?: PresentOpts): void;
+/**
+ * Present an array of objects.
+ *
+ * - `--count`     → just the number
+ * - `-q/--quiet`  → one path per line (unix-pipeable)
+ * - machine       → denoised JSON of the raw items (`-l` keeps full items)
+ * - TTY           → an aligned table + a dim count footer
+ *
+ * Projection (columns/rows/paths) is for the human table and `-q` only; the
+ * machine surface stays the kernel's own item fields.
+ */
+export declare function presentList<T>(items: T[], opts: ListOpts, project: (items: T[]) => ListProjection): void;

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

@@ -0,0 +1,18 @@
+/** A display column: which row key to read, its header, and an optional cell color. */
+export type Column = {
+    key: string;
+    header: string;
+    color?: (s: string) => string;
+};
+/**
+ * Render an aligned, optionally-colored table.
+ *
+ * Cells may carry ANSI (e.g. a per-row status color) — widths are computed on
+ * visible length so alignment stays correct. `Column.color` colors a whole
+ * column of otherwise-plain cells. Columns empty across every row are dropped;
+ * the last column is left unpadded so there's no trailing whitespace.
+ */
+export declare function renderTable(rows: Array<Record<string, string>>, opts: {
+    columns: Column[];
+    showHeader?: boolean;
+}): string;

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

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+declare const RESERVED_SLUGS: Set<string>;
+export { RESERVED_SLUGS };
+export declare function validateName(name: string, entity: string): void;
+export declare function validateSlug(slug: string): void;
+export declare function validateUrl(url: string): void;
+/** Non-throwing predicate form of `validateUrl`. */
+export declare function isHttpUrl(url: string): boolean;
+/** `local` = only this machine. `remote` = mirrored via astrale cloud (§2.7). */
+export declare const RegistryModeSchema: z.ZodEnum<["local", "remote"]>;
+export type RegistryMode = z.infer<typeof RegistryModeSchema>;

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

@@ -0,0 +1,2 @@
+export { ASTRALE_HOME, CONFIG_PATH, DATA_DIR, IDENTITIES_PATH, IDPS_PATH, IDP_SESSIONS_DIR, INSTALL_PATH, INSTANCES_PATH, KEYS_DIR, createPaths, } from '../state/index';
+export type { PathEnvironment, Paths } from '../state/index';

package/dist/types/state/exchange-credentials.d.ts

@@ -0,0 +1,25 @@
+export declare namespace exchange {
+    interface Artifact {
+        readonly version: 1;
+        readonly entries: Record<string, Entry>;
+    }
+    interface Key {
+        readonly kernelIssuer: string;
+        readonly domainIssuer: string;
+        readonly user: string;
+    }
+    interface Entry {
+        readonly credential: string;
+        readonly expiresAt: number;
+    }
+}
+export declare class ExchangeCredentialCache {
+    private readonly path;
+    private readonly refreshing;
+    constructor(path?: string);
+    getOrRefresh(key: exchange.Key, refresh: () => Promise<exchange.Entry>, now?: () => number): Promise<string>;
+    deleteKernel(kernelIssuer: string): Promise<void>;
+    clear(): Promise<void>;
+    private getOrRefreshOnce;
+    private transition;
+}

package/dist/types/state/files.d.ts

@@ -0,0 +1,9 @@
+/** Atomically publish one complete private state file through a same-directory temporary file. */
+export declare function atomicWrite(path: string, data: string): Promise<void>;
+export interface FileLockOptions {
+    readonly pollIntervalMs?: number;
+    readonly staleAfterMs?: number;
+    readonly timeoutMs?: number;
+}
+/** Run one transition under a bounded cross-process create-exclusive lock. */
+export declare function withFileLock<Value>(lockPath: string, transition: () => Promise<Value>, options?: FileLockOptions): Promise<Value>;

package/dist/types/state/identities.d.ts

@@ -0,0 +1,42 @@
+import type { FileLockOptions } from './files';
+export type IdentitySource = 'key' | 'idp';
+export type IdentityMode = 'local' | 'remote';
+export interface Registration {
+    readonly iss: string;
+    readonly sub: string;
+    readonly registeredAt: string;
+}
+export interface Identity {
+    readonly subject: string;
+    readonly createdAt: string;
+    readonly source?: IdentitySource;
+    readonly mode?: IdentityMode;
+    readonly kid?: string;
+    readonly idp?: string;
+    readonly issuer?: string;
+    readonly audience?: string;
+    readonly claims?: Readonly<Record<string, unknown>>;
+    readonly registrations?: Readonly<Record<string, Registration>>;
+}
+export interface IdentityStore {
+    readonly default: string;
+    readonly identities: Readonly<Record<string, Identity>>;
+}
+export declare const IDENTITY_STORE_VERSION: 1;
+export type IdentityStateErrorCode = 'IDENTITY_STATE_INVALID' | 'IDENTITY_STATE_VERSION_UNSUPPORTED' | 'IDENTITY_STATE_UNREADABLE' | 'IDENTITY_STATE_BACKUP_CONFLICT';
+export declare class IdentityStateError extends Error {
+    readonly code: IdentityStateErrorCode;
+    readonly path: string;
+    constructor(code: IdentityStateErrorCode, path: string, message: string, cause?: unknown);
+}
+export interface IdentityStoreOptions {
+    readonly path?: string;
+    readonly now?: () => Date;
+    readonly lock?: FileLockOptions;
+}
+export interface IdentityUpdate<Value> {
+    readonly next: IdentityStore;
+    readonly value: Value;
+}
+export declare function readIdentityStore(options?: IdentityStoreOptions): Promise<IdentityStore>;
+export declare function updateIdentityStore<Value>(transition: (current: IdentityStore) => IdentityUpdate<Value> | Promise<IdentityUpdate<Value>>, options?: IdentityStoreOptions): Promise<Value>;

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

@@ -0,0 +1,8 @@
+export { atomicWrite, withFileLock } from './files';
+export type { FileLockOptions } from './files';
+export { ExchangeCredentialCache } from './exchange-credentials';
+export type { exchange } from './exchange-credentials';
+export { IDENTITY_STORE_VERSION, readIdentityStore, updateIdentityStore } from './identities';
+export type { Identity, IdentityMode, IdentitySource, IdentityStore, IdentityStoreOptions, IdentityUpdate, Registration, } from './identities';
+export { ASTRALE_HOME, CONFIG_PATH, DATA_DIR, IDENTITIES_PATH, IDPS_PATH, IDP_SESSIONS_DIR, EXCHANGE_CREDENTIALS_PATH, INSTALL_PATH, INSTANCES_PATH, KEYS_DIR, createPaths, paths, } from './paths';
+export type { PathEnvironment, Paths } from './paths';

package/dist/types/state/paths.d.ts

@@ -0,0 +1,32 @@
+export interface PathEnvironment {
+    readonly ASTRALE_HOME?: string;
+    readonly ASTRALE_KEYS_DIR?: string;
+    readonly ASTRALE_DATA_DIR?: string;
+}
+export interface Paths {
+    readonly home: string;
+    readonly keys: string;
+    readonly data: string;
+    readonly config: string;
+    readonly install: string;
+    readonly identities: string;
+    readonly instances: string;
+    readonly idps: string;
+    readonly idpSessionsDir: string;
+    readonly exchangeCredentials: string;
+    idpDir(name: string): string;
+    idpSession(identityName: string): string;
+}
+/** Resolve every CLI state path once from explicit input and the captured environment. */
+export declare function createPaths(home?: string, environment?: PathEnvironment): Paths;
+export declare const paths: Paths;
+export declare const ASTRALE_HOME: string;
+export declare const KEYS_DIR: string;
+export declare const DATA_DIR: string;
+export declare const CONFIG_PATH: string;
+export declare const INSTALL_PATH: string;
+export declare const IDENTITIES_PATH: string;
+export declare const INSTANCES_PATH: string;
+export declare const IDPS_PATH: string;
+export declare const IDP_SESSIONS_DIR: string;
+export declare const EXCHANGE_CREDENTIALS_PATH: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/cli",
-  "version": "0.8.0-alpha.0",
+  "version": "0.8.1-alpha.2",
   "description": "Astrale CLI — connect to existing Astrale kernels",
   "keywords": [
     "astrale",
@@ -29,16 +29,28 @@
   ],
   "type": "module",
   "exports": {
-    "./keys": "./src/lib/keys.ts",
-    "./paths": "./src/lib/paths.ts"
+    "./connect-core": {
+      "types": "./dist/types/connect-core.d.ts",
+      "import": "./dist/public/connect-core.js",
+      "default": "./dist/public/connect-core.js"
+    },
+    "./keys": {
+      "types": "./dist/types/keys/index.d.ts",
+      "import": "./dist/public/keys/index.js",
+      "default": "./dist/public/keys/index.js"
+    },
+    "./paths": {
+      "types": "./dist/types/paths/index.d.ts",
+      "import": "./dist/public/paths/index.js",
+      "default": "./dist/public/paths/index.js"
+    },
+    "./identity-export-v1.schema.json": "./src/identity/.spec/schemas/identity-export-v1.schema.json"
   },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "@astrale-os/kernel-client": ">=0.3.1 <1.0.0",
-    "@astrale-os/kernel-core": ">=0.7.0 <1.0.0",
     "@inquirer/prompts": "^8.5.2",
     "chalk": "^5.6.2",
     "chokidar": "^4.0.3",
@@ -50,8 +62,10 @@
     "zod": "^3.25.0"
   },
   "devDependencies": {
+    "@astrale-os/kernel-client": "0.6.0-beta.1",
     "@astrale-os/ox": ">=0.1.0 <1.0.0",
-    "@astrale-os/shell": ">=0.3.5 <1.0.0",
+    "@astrale-os/sdk": "0.5.0-beta.1",
+    "@astrale-os/shell": "0.3.8-beta.1",
     "@astrale/commitlint-config": "npm:@jsr/astrale__commitlint-config@~2.0.1",
     "@commitlint/cli": "~20.3.1",
     "@commitlint/config-conventional": "~20.3.1",
@@ -74,13 +88,21 @@
       "oxfmt --write"
     ]
   },
+  "devEngines": {
+    "runtime": {
+      "name": "node",
+      "version": ">=24 <25",
+      "onFail": "error"
+    }
+  },
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "scripts": {
     "preinstall": "node .check-workspace.cjs",
     "build": "bun scripts/build.ts",
-    "typecheck": "tsgo --noEmit && tsgo --noEmit -p viewer",
+    "package:check": "pnpm run typecheck && pnpm run test && pnpm run build && node scripts/verify-public-exports.mjs",
+    "typecheck": "tsgo --noEmit && tsgo --noEmit -p tsconfig.tests.json && tsgo --noEmit -p viewer && tsgo --noEmit -p studio",
     "lint": "oxlint .",
     "lint:fix": "oxlint --fix .",
     "format": "pnpm exec oxfmt --write .",

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

@@ -0,0 +1,3 @@
+/** CLI-private V2 Admin adapters; no package export or duplicate control-plane semantics. */
+export * as catalog from '../catalog/.spec/api.js'
+export * as instance from '../instance/.spec/api.js'

package/src/admin/.spec/architecture.md

@@ -0,0 +1,15 @@
+# CLI Admin adapters
+
+This private aggregate translates the frozen CLI command journey into the discovered V2
+`admin.astrale.ai` contract. It binds the exact served Domain revision through Kernel Client,
+uses `GraphApi` for policy-visible inventory, and invokes receiver-oriented Methods through
+`DomainBinding`. It does not import Admin implementation code, hard-code one schema revision, call
+Host directly, or persist remote graph truth.
+
+`instance` owns create/list/status/delete/install projection and explicitly excludes the reserved
+Admin Host from consumer placement. `catalog` owns Domain inventory, publication, and default-set
+configuration. `graph` is their bounded cursor helper and is not re-exported by the aggregate.
+
+Commander grammar, help text, output shapes, bookmark behavior, and current interactive host
+selection remain owned by the existing command surface; these adapters change only its remote
+semantic owner.

package/src/admin/.spec/icon.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="#7c3aed" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round">
+  <path d="M12 3 4.5 7v10L12 21l7.5-4V7z"/><path d="M8 10h8M8 14h5"/><circle cx="17" cy="16" r="2.5"/>
+</svg>

package/src/admin/.spec/layout.ts

@@ -0,0 +1,6 @@
+import { defineLayout } from '@astrale-os/spec/authoring'
+
+export default defineLayout({
+  entries: ['catalog/', 'graph/', 'index.ts', 'instance/'],
+  exact: true,
+})

package/src/admin/catalog/.spec/api.d.ts

@@ -0,0 +1,65 @@
+import type { DomainBinding } from '@astrale-os/kernel-client/domain'
+import type { ClientSession } from '@astrale-os/kernel-client/session'
+
+import type { AdminGraphApi } from '../../graph/.spec/api.js'
+
+export interface DomainInfo {
+  readonly id: string
+  readonly origin: string
+  readonly name: string
+  readonly url?: string
+  readonly description?: string
+  readonly installByDefault?: boolean
+  readonly createdAt: string
+  readonly updatedAt: string
+}
+
+export interface PublishDomainInput {
+  readonly origin: string
+  readonly name: string
+  readonly url: string
+  readonly description?: string
+  readonly installByDefault?: boolean
+}
+
+export interface PublishDomainResult {
+  readonly entry: DomainInfo
+  readonly changed: boolean
+  readonly isNew: boolean
+}
+
+export interface InstallDomainResult {
+  readonly name: string
+  readonly origin: string
+  readonly instanceId: string
+  readonly url: string
+  readonly ok: boolean
+  readonly error?: string | null
+}
+
+export interface AdminCatalogContext {
+  readonly session: ClientSession
+  readonly graph: AdminGraphApi
+}
+
+export interface AdminCatalogApi {
+  list(): Promise<DomainInfo[]>
+  require(identifier: string): Promise<DomainInfo>
+  publish(input: PublishDomainInput): Promise<PublishDomainResult>
+}
+
+export class AdminDomainNotFoundError extends Error {
+  constructor(identifier: string)
+  readonly name: 'NotFoundError'
+  readonly identifier: string
+}
+
+export interface AdminCatalogDependencies {
+  readonly bind?: (session: ClientSession) => Promise<DomainBinding>
+  readonly operationId?: (kind: 'publish' | 'configure-default') => string
+}
+
+export function connectAdminCatalog(
+  context: AdminCatalogContext,
+  dependencies?: AdminCatalogDependencies,
+): Promise<AdminCatalogApi>

package/src/admin/catalog/.spec/architecture.md

@@ -0,0 +1,6 @@
+# CLI Admin catalog adapter
+
+The adapter reads policy-visible `Domain` Nodes through bounded Graph pages and derives default
+membership from the Fleet relation. Publication invokes `Fleet.publishDomain`; a requested default
+change is a separate explicit `Domain.configureDefault` call. Unchanged publication input is a
+no-op, and an omitted description preserves the current value.

package/src/admin/catalog/.spec/icon.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="#059669" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round">
+  <path d="M5 4h14v16H5zM8 8h8M8 12h8M8 16h5"/><circle cx="17" cy="16" r="2"/>
+</svg>

package/src/admin/catalog/.spec/layout.ts

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