@astrale-os/cli 1.0.0-beta.3 → 1.0.0-beta.31

package/src/lib/instance-target.ts

@@ -1,6 +1,6 @@
-import type { InstanceInfo } from '../admin/instance/model'
 import type { AstraleConfig } from './config'
 
+import { AdminInstanceNotFoundError, type InstanceInfo } from '../admin/instance/model'
 import { AstraleError } from '../errors'
 import {
   DEFAULT_ADMIN_TARGET_NAME,
@@ -190,19 +190,8 @@ export function isAdminDiscoveryFailure(error: unknown): boolean {
 }
 
 export function isManagedInstanceNotFound(error: unknown): boolean {
-  if (error instanceof AstraleError && error.code === 'INSTANCE_NOT_FOUND') return true
-  if (!(error instanceof Error)) return false
-  if (error.name === 'NotFoundError') return true
-  // The admin kernel reports a missing instance node as InternalKernelError
-  // with a NOT_FOUND-prefixed message. In this lookup that's an instance
-  // miss (config problem), not a kernel fault — map it so callers get the
-  // typed INSTANCE_NOT_FOUND with remediation instead of a raw kernel error.
-  if (error.name === 'InternalKernelError' && /^NOT_FOUND\b/.test(error.message)) return true
-  const data = (error as Error & { data?: unknown }).data
   return (
-    error.name === 'KernelError' &&
-    !!data &&
-    typeof data === 'object' &&
-    (data as { type?: unknown }).type === 'NotFoundError'
+    error instanceof AdminInstanceNotFoundError ||
+    (error instanceof AstraleError && error.code === 'INSTANCE_NOT_FOUND')
   )
 }

package/src/lib/instance.ts

@@ -297,22 +297,26 @@ export async function upsertInstance(
  * bookmark was repointed to a different kernel so callers can warn.
  */
 export async function upsertManagedBookmark(
-  key: string,
-  slug: string,
-  rawUrl: string,
-  organizationId?: string,
+  input: Readonly<{
+    key: string
+    slug: string
+    url: string
+    organizationId?: string
+    defaultIdentity?: string
+  }>,
 ): Promise<{ entry: InstanceEntry; repointedFrom?: string }> {
   const store = await readInstances()
-  const previousUrl = store.instances[key]?.url
-  const url = normalizeInstanceKernelUrl(rawUrl)
-  const { entry } = await upsertInstance(key, {
+  const previousUrl = store.instances[input.key]?.url
+  const url = normalizeInstanceKernelUrl(input.url)
+  const { entry } = await upsertInstance(input.key, {
     url,
     issuer: url,
-    slug,
-    name: slug,
+    slug: input.slug,
+    name: input.slug,
     kind: 'bookmark',
     mode: 'remote',
-    ...(organizationId ? { organizationId } : {}),
+    ...(input.organizationId ? { organizationId: input.organizationId } : {}),
+    ...(input.defaultIdentity ? { defaultIdentity: input.defaultIdentity } : {}),
   })
   return {
     entry,
@@ -362,8 +366,9 @@ export async function getActive(config?: AstraleConfig): Promise<InstanceEntry &
 export async function resolveInstance(
   identifier: string,
   config?: AstraleConfig,
+  opts: { persist?: boolean } = {},
 ): Promise<ResolvedInstance> {
-  const store = await readInstances(config)
+  const store = await readInstances(config, opts)
   const key = resolveInstanceKey(store, identifier)
   const entry = key ? store.instances[key] : undefined
   if (!key || !entry?.url) {

package/src/lib/log.ts

@@ -2,6 +2,7 @@ import chalk from 'chalk'
 import ora, { type Ora } from 'ora'
 
 import { AstraleError, NotImplementedError } from '../errors'
+import { printFailureDebug } from './failure-debug'
 import { formatElapsed } from './format'
 import { isMachine, type MachineOpts } from './output'
 
@@ -18,28 +19,34 @@ export 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 function fatal(e: unknown, opts?: MachineOpts): never {
+export function fatal(e: unknown, opts?: MachineOpts & { readonly debug?: boolean }): never {
   // Ctrl-C at an interactive (@inquirer/prompts) prompt — exit quietly with the
   // SIGINT convention, not a red error line.
   if (e instanceof Error && e.name === 'ExitPromptError') process.exit(130)
-  const msg = e instanceof Error ? e.message : String(e)
-  const code = e instanceof AstraleError ? e.code : e instanceof Error ? e.name : 'Error'
+  const msg =
+    e instanceof AstraleError ? e.message : 'The CLI encountered an unexpected internal failure.'
+  const code = e instanceof AstraleError ? e.code : 'UNEXPECTED_ERROR'
   if (isMachine(opts)) {
     const payload: Record<string, unknown> = { error: code, message: msg }
     if (e instanceof AstraleError && e.hint) payload.hint = e.hint
     process.stderr.write(JSON.stringify(payload) + '\n')
-    process.exit(1)
+  } else {
+    log.error(`${code}: ${msg}`)
+    if (e instanceof AstraleError && e.hint) log.dim(`  hint: ${e.hint}`)
   }
-  log.error(e instanceof AstraleError ? `${code}: ${msg}` : msg)
-  if (e instanceof AstraleError && e.hint) log.dim(`  hint: ${e.hint}`)
+  if (opts?.debug) printFailureDebug(e, '')
   process.exit(1)
 }
 
-/** Admit expected invalid input and exit through {@link fatal}. */
-export function failClosed(error: unknown, opts?: MachineOpts): never {
+/** Project only a caller-authored admission failure into the CLI input family. */
+export function failInput(error: unknown, opts?: MachineOpts): never {
   if (error instanceof AstraleError) fatal(error, opts)
+  if (!(error instanceof TypeError)) fatal(error, opts)
   fatal(
-    new AstraleError('INVALID_INPUT', error instanceof Error ? error.message : String(error)),
+    new AstraleError(
+      'INVALID_INPUT',
+      error.message.trim() ? error.message : 'CLI input is invalid.',
+    ),
     opts,
   )
 }

package/src/lib/output.ts

@@ -17,7 +17,7 @@ export type RawOutputOpts = Pick<OutputOpts, 'raw' | 'json'>
 export type MachineOpts = RawOutputOpts & { readonly ci?: boolean }
 
 export const RAW_OUTPUT_OPTIONS = [
-  { flags: '--json', description: 'Always-valid JSON (for jq)' },
+  { flags: '--json', description: 'JSON; streaming commands emit one JSON value per line' },
   { flags: '--raw', description: 'Unwrapped: bare scalar / raw bytes / JSON for objects' },
 ] as const
 

package/src/lib/proc.ts

@@ -22,7 +22,11 @@ export function run(
   opts: { cwd?: string } = {},
 ): Promise<RunResult> {
   return new Promise((resolve, reject) => {
-    const child = spawn(file, args, { cwd: opts.cwd, stdio: ['ignore', 'pipe', 'pipe'] })
+    const child = spawn(file, args, {
+      cwd: opts.cwd,
+      shell: false,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
     let stdout = ''
     let stderr = ''
     child.stdout?.setEncoding('utf8')
@@ -50,7 +54,7 @@ export function runInherit(
   opts: { cwd?: string } = {},
 ): Promise<number> {
   return new Promise((resolve, reject) => {
-    const child = spawn(file, args, { cwd: opts.cwd, stdio: 'inherit' })
+    const child = spawn(file, args, { cwd: opts.cwd, shell: false, stdio: 'inherit' })
     child.on('error', reject)
     child.on('close', (code) => resolve(code ?? -1))
   })
@@ -73,6 +77,7 @@ export function spawnHandle(
   return spawn(file, args, {
     cwd: opts.cwd,
     env: opts.env,
+    shell: false,
     // `detached` makes the child its own process-group leader so the caller can
     // tear down the whole tree (the child AND its grandchildren) with a single
     // group signal — `process.kill(-child.pid, …)`.

package/src/lib/provision-instance.ts

@@ -9,12 +9,10 @@ import { createOwnedInstance } from './admin-instance'
 import { setActive, upsertManagedBookmark } from './instance'
 import { withSpinner } from './log'
 import { isMachine } from './output'
-import { promptSelect } from './prompt'
 import { validateSlug } from './validation'
 
 export type ProvisionOpts = KernelCommandOpts &
   AdminTargetCommandOpts & {
-    hostId?: string
     // Global flags (program.ts) that force non-interactive — mirrors `instance use`.
     ci?: boolean
     noPrompt?: boolean
@@ -35,10 +33,10 @@ export type ProvisionResult = {
 const SAGA_TIMEOUT_MS = '240000'
 
 /**
- * Provision an alpha instance through the admin kernel, then bookmark it and
+ * Provision an instance through the admin kernel, then bookmark it and
  * make it the active target. Extracted from `instance create` so `astrale
- * setup` provisions through the exact same saga (auth assertion → alphaCreate →
- * bookmark → set-active), including the interactive multi-host picker.
+ * setup` provisions through the exact same saga (auth assertion → create →
+ * bookmark → set-active).
  *
  * Presentation is deliberately minimal here (a spinner + a one-line success);
  * the caller renders anything richer — `setup` follows this with a hero panel.
@@ -48,15 +46,10 @@ export async function provisionInstance(
   opts: ProvisionOpts,
 ): Promise<ProvisionResult> {
   validateSlug(slug)
-  await assertAlphaCreateAuth(opts)
-  // The created instance must belong to the LOGGED-IN identity — never to an
-  // identity pinned on the admin bookmark (that mismatch silently made a fresh
-  // user's instance unusable). `--as` still wins.
-  if (!opts.as) opts = { ...opts, as: (await readIdentities()).default }
+  const authentication = await instanceCreateAuthentication(opts)
+  opts = authentication.opts
 
   const machine = isMachine(opts)
-  const interactive = !!process.stdin.isTTY && !(opts.ci || opts.noPrompt || process.env.CI)
-
   let repointedFrom: string | undefined
   let selectionError: unknown = null
   // The global 30s default doesn't just fail the CLIENT: the disconnect kills
@@ -65,21 +58,24 @@ export async function provisionInstance(
   // timeout; an explicit --timeout still wins.
   const createOpts = { ...opts, timeout: opts.timeout ?? SAGA_TIMEOUT_MS }
 
-  const runProvision = (hostId: string | undefined) =>
+  const runProvision = () =>
     withSpinner(
       `Provisioning instance ${slug}`,
       !machine,
       async () => {
-        const created = await createOwnedInstance(createOpts, slug, hostId)
+        const created = await createOwnedInstance(createOpts, slug)
         try {
           // Org id from the create response — authoritative for token scoping
           // (the router's /auth/org is eventually consistent).
-          const bookmarked = await upsertManagedBookmark(
-            slug,
+          const bookmarked = await upsertManagedBookmark({
+            key: slug,
             slug,
-            created.url,
-            created.organizationId,
-          )
+            url: created.url,
+            ...(created.organizationId ? { organizationId: created.organizationId } : {}),
+            ...(authentication.defaultIdentity
+              ? { defaultIdentity: authentication.defaultIdentity }
+              : {}),
+          })
           repointedFrom = bookmarked.repointedFrom
           await setActive(slug)
         } catch (e) {
@@ -93,23 +89,7 @@ export async function provisionInstance(
       },
     )
 
-  // Host placement is chosen SERVER-side (the caller's ready + USE-granted
-  // hosts). We recover ONLY from its multi-host ambiguity: pop a picker and
-  // retry with the chosen host_id — the ambiguity error throws before any
-  // provisioning side effect, so the retry is clean. No host / permission /
-  // capacity / a non-interactive run all reject through to the caller's `fatal`,
-  // surfacing the server's own message plus the listed ids. An explicit
-  // `--host-id` skips all of this.
-  const created = await runProvision(opts.hostId).catch(async (e: unknown) => {
-    const hostIds = !opts.hostId && interactive ? parseEligibleHostIds(e) : null
-    if (!hostIds) throw e
-    const chosen = await promptSelect(
-      `${hostIds.length} hosts available — pick one to provision on`,
-      hostIds.map((hid) => ({ name: hid, value: hid })),
-    )
-    if (!chosen) throw e
-    return runProvision(chosen)
-  })
+  const created = await runProvision()
 
   // Warnings go to stderr so machine-readable stdout stays clean.
   const warn = (msg: string) => console.error(chalk.yellow('⚠'), msg)
@@ -124,31 +104,28 @@ export async function provisionInstance(
   return { created, slug, repointedFrom, ...(selectionError ? { selectionError } : {}) }
 }
 
-/**
- * Recover the eligible host ids from alphaCreate's multi-host error
- * ("N ready hosts are assigned (id1, id2). Specify host_id…") — only when
- * there's a real choice (>1). Returns null for any other error (no host,
- * permission, capacity). Deliberately coupled to that message wording (Option
- * B: no admin-side change); if it ever drifts we simply stop offering the
- * picker and the raw error is shown instead — no worse than before.
- */
-export function parseEligibleHostIds(error: unknown): string[] | null {
-  const text = error instanceof Error ? error.message : String(error)
-  const match = /ready hosts are assigned \(([^)]+)\)/.exec(text)
-  if (!match) return null
-  const ids = match[1]!
-    .split(',')
-    .map((s) => s.trim())
-    .filter(Boolean)
-  return ids.length > 1 ? ids : null
+async function instanceCreateAuthentication(opts: ProvisionOpts): Promise<{
+  readonly opts: ProvisionOpts
+  readonly defaultIdentity?: string
+}> {
+  if (opts.creds) return { opts }
+  const store = await readIdentities()
+  const defaultIdentity = selectInstanceCreateIdentity(store, opts)
+  return {
+    opts: opts.as ? opts : { ...opts, as: defaultIdentity },
+    defaultIdentity,
+  }
 }
 
-async function assertAlphaCreateAuth(opts: Pick<ProvisionOpts, 'as' | 'creds'>): Promise<void> {
-  if (opts.creds) return
-  assertAlphaCreateIdentity(await readIdentities(), opts)
+export function selectInstanceCreateIdentity(
+  store: IdentityStore,
+  opts: Pick<ProvisionOpts, 'as'> = {},
+): string {
+  assertInstanceCreateIdentity(store, opts)
+  return opts.as ?? store.default
 }
 
-export function assertAlphaCreateIdentity(
+export function assertInstanceCreateIdentity(
   store: IdentityStore,
   opts: Pick<ProvisionOpts, 'as'> = {},
 ): void {

package/src/lib/skills/lock.ts

@@ -0,0 +1,117 @@
+import { randomUUID } from 'node:crypto'
+import { lstat, mkdir, readFile, readdir, rm, stat, unlink, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+
+export type FileLockOptions = {
+  pollIntervalMs?: number
+  staleAfterMs?: number
+  timeoutMs?: number
+}
+
+type Claim = { directory: string; pid: number; ticket: number | null; choosing: boolean }
+
+/**
+ * Serialize a cross-process transition with a filesystem bakery lock.
+ *
+ * Every contender owns a UUID directory for its entire lifetime. Dead claims are
+ * removed only by that unrepeatable name, so recovery never deletes a pathname a
+ * new live owner could have replaced between an ownership check and an unlink.
+ */
+export async function withFileLock<T>(
+  lockPath: string,
+  fn: () => Promise<T>,
+  opts: FileLockOptions = {},
+): Promise<T> {
+  const pollIntervalMs = opts.pollIntervalMs ?? 100
+  const staleAfterMs = opts.staleAfterMs ?? 30_000
+  const timeoutMs = opts.timeoutMs ?? 60_000
+  const deadline = Date.now() + timeoutMs
+  const claimsRoot = `${lockPath}.claims`
+  const token = randomUUID()
+  const claimDirectory = join(claimsRoot, token)
+
+  await mkdir(dirname(lockPath), { recursive: true })
+  await mkdir(claimsRoot, { recursive: true })
+  await mkdir(claimDirectory)
+  await writeFile(join(claimDirectory, 'owner.json'), JSON.stringify({ pid: process.pid }), {
+    mode: 0o600,
+  })
+  await writeFile(join(claimDirectory, 'choosing'), '', { mode: 0o600 })
+
+  try {
+    const claims = await liveClaims(claimsRoot, staleAfterMs)
+    const ticket = Math.max(0, ...claims.flatMap((claim) => claim.ticket ?? [])) + 1
+    await writeFile(join(claimDirectory, 'ticket'), String(ticket), { mode: 0o600 })
+    await unlink(join(claimDirectory, 'choosing'))
+
+    for (;;) {
+      const contenders = await liveClaims(claimsRoot, staleAfterMs)
+      const blocked = contenders.some(
+        (claim) =>
+          claim.directory !== claimDirectory &&
+          (claim.choosing ||
+            claim.ticket === null ||
+            claim.ticket < ticket ||
+            (claim.ticket === ticket && claim.directory < claimDirectory)),
+      )
+      if (!blocked) return await fn()
+      if (Date.now() >= deadline) throw new Error('Timed out waiting for another skill update')
+      await new Promise((resolve) => setTimeout(resolve, pollIntervalMs))
+    }
+  } finally {
+    await rm(claimDirectory, { recursive: true, force: true })
+  }
+}
+
+async function liveClaims(root: string, staleAfterMs: number): Promise<Claim[]> {
+  const directories = (await readdir(root, { withFileTypes: true }).catch(() => []))
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => join(root, entry.name))
+  const claims = await Promise.all(
+    directories.map(async (directory): Promise<Claim | null> => {
+      try {
+        const owner = JSON.parse(await readFile(join(directory, 'owner.json'), 'utf8')) as {
+          pid?: unknown
+        }
+        if (typeof owner.pid !== 'number') return await discardIfStale(directory, staleAfterMs)
+        if (!isPidAlive(owner.pid)) {
+          await rm(directory, { recursive: true, force: true })
+          return null
+        }
+        const choosing = await lstat(join(directory, 'choosing'))
+          .then(() => true)
+          .catch(() => false)
+        const ticket = await readFile(join(directory, 'ticket'), 'utf8')
+          .then((value) => {
+            const parsed = Number(value)
+            return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : null
+          })
+          .catch(() => null)
+        return { directory, pid: owner.pid, ticket, choosing }
+      } catch {
+        return await discardIfStale(directory, staleAfterMs)
+      }
+    }),
+  )
+  return claims.filter((claim): claim is Claim => claim !== null)
+}
+
+async function discardIfStale(directory: string, staleAfterMs: number): Promise<null> {
+  try {
+    if (Date.now() - (await stat(directory)).mtimeMs > staleAfterMs) {
+      await rm(directory, { recursive: true, force: true })
+    }
+  } catch {
+    // A concurrently released unique claim is already gone.
+  }
+  return null
+}
+
+function isPidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (error) {
+    return (error as { code?: string }).code === 'EPERM'
+  }
+}