@astrale-os/cli 0.4.0-alpha.13

package/src/setup/steps/auth.ts

@@ -0,0 +1,54 @@
+import type { SetupContext, SetupStep } from '../types'
+
+import { readLocalStatus } from '../../lib/local-status'
+import { log } from '../../lib/log'
+import { loginViaIdp } from '../../lib/login-flow'
+
+const FIX = 'astrale auth login'
+
+/**
+ * Step 1 — a WorkOS-backed identity with a cached session. Provisioning an
+ * instance requires an `idp` identity (not the local seed key), and stale
+ * access tokens refresh on the first command when a refresh token is cached.
+ */
+export const authStep: SetupStep = {
+  id: 'auth',
+  title: 'Sign in',
+  group: 'connect',
+
+  async detect() {
+    const { identity } = await readLocalStatus()
+    if (!identity || identity.source !== 'idp') {
+      return { state: 'gap', summary: 'Not signed in', fixHint: FIX }
+    }
+    const session = identity.session
+    if (!session || !session.cached) {
+      return { state: 'gap', summary: `No cached token for "${identity.name}"`, fixHint: FIX }
+    }
+    if (session.requiresLogin) {
+      return {
+        state: 'gap',
+        summary: `Session for "${identity.name}" requires login`,
+        fixHint: FIX,
+      }
+    }
+    return {
+      state: 'satisfied',
+      summary: `Signed in as ${identity.name}`,
+      detail: identity.subject,
+    }
+  },
+
+  async ensure(ctx: SetupContext) {
+    const detection = await authStep.detect(ctx)
+    if (detection.state === 'satisfied') {
+      log.success(detection.summary)
+      return 'unchanged'
+    }
+
+    log.step('Sign in with your Astrale account (a URL + code will appear) …')
+    const { identityName } = await loginViaIdp({ use: true })
+    log.success(`Signed in as "${identityName}"`)
+    return 'fixed'
+  },
+}

package/src/setup/steps/domain.ts

@@ -0,0 +1,68 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+import type { SetupStep } from '../types'
+
+import { readLocalStatus } from '../../lib/local-status'
+import { log } from '../../lib/log'
+import { runInherit } from '../../lib/proc'
+import { confirmDefaultYes, promptText } from '../../lib/prompt'
+
+/** A scaffolded domain project carries this config at its root. */
+function hasDomainProject(): boolean {
+  return existsSync(join(process.cwd(), 'astrale.config.ts'))
+}
+
+const FIX = 'npx create-astrale-domain <name> --instance <slug>'
+
+/**
+ * Equip — scaffold a first domain in the current directory via
+ * `create-astrale-domain`, pre-wired to the active instance. The scaffold also
+ * ships the astrale-domain authoring skill, so this covers that skill too.
+ */
+export const domainStep: SetupStep = {
+  id: 'domain',
+  title: 'Scaffold a domain',
+  group: 'equip',
+
+  async detect() {
+    if (hasDomainProject()) {
+      return { state: 'satisfied', summary: 'domain project detected in this directory' }
+    }
+    return { state: 'gap', summary: 'no domain project here', fixHint: FIX }
+  },
+
+  async ensure() {
+    if (hasDomainProject()) {
+      log.success('Domain project already in this directory')
+      return 'unchanged'
+    }
+
+    if (!(await confirmDefaultYes('Scaffold a new domain project here?'))) {
+      log.dim(`  Skipped — scaffold later: ${FIX}`)
+      return 'skipped'
+    }
+
+    const name = await promptText('Domain project name', {
+      default: 'my-domain',
+      validate: (v) =>
+        /^[a-z0-9][a-z0-9-]*$/.test(v) ? true : 'Use a lowercase name like my-domain',
+    })
+    if (!name) {
+      log.dim('  Skipped — no name given.')
+      return 'skipped'
+    }
+
+    const slug = (await readLocalStatus()).instance?.active
+    const args = ['create-astrale-domain', name, ...(slug ? ['--instance', slug] : [])]
+    log.step(`npx ${args.join(' ')}`)
+    if ((await runInherit('npx', args)) !== 0) {
+      log.warn('Scaffold failed — see the output above.')
+      return 'failed'
+    }
+
+    log.success(`Domain scaffolded → ./${name}`)
+    log.dim(`  Next: cd ${name} && pnpm install && pnpm prod`)
+    return 'fixed'
+  },
+}

package/src/setup/steps/index.ts

@@ -0,0 +1,18 @@
+import type { SetupStep } from '../types'
+
+import { adminStep } from './admin'
+import { agentBrowserStep } from './agent-browser'
+import { authStep } from './auth'
+import { domainStep } from './domain'
+import { instanceStep } from './instance'
+import { skillsStep } from './skills'
+import { skillsBridgeStep } from './skills-bridge'
+
+/** Required prerequisites, walked in order — each is a precondition for the next. */
+export const CONNECT_STEPS: SetupStep[] = [authStep, adminStep, instanceStep]
+
+/** Optional extras, offered together as a pre-checked multi-select. The skills
+ *  bridge runs first so the per-skill steps below detect against the bridged state. */
+export const EQUIP_STEPS: SetupStep[] = [skillsBridgeStep, skillsStep, agentBrowserStep, domainStep]
+
+export const ALL_STEPS: SetupStep[] = [...CONNECT_STEPS, ...EQUIP_STEPS]

package/src/setup/steps/instance.ts

@@ -0,0 +1,119 @@
+import chalk from 'chalk'
+
+import type { SetupContext, SetupStep } from '../types'
+
+import { withAdminKernelClient } from '../../kernel/client'
+import { ADMIN_INSTANCE, type InstanceInfo } from '../../lib/admin-instance'
+import { normalizeInstanceKernelUrl, setActive, upsertManagedBookmark } from '../../lib/instance'
+import { readLocalStatus } from '../../lib/local-status'
+import { log, withSpinner } from '../../lib/log'
+import { renderInstanceHero } from '../../lib/panel'
+import { confirmDefaultYes, promptText, selectFrom } from '../../lib/prompt'
+import { provisionInstance } from '../../lib/provision-instance'
+import { guiOrigin, slugError } from '../util'
+
+/** All admin-managed instances; degrades to [] when the admin kernel is unreachable. */
+async function fetchManaged(ctx: SetupContext): Promise<InstanceInfo[]> {
+  try {
+    return await withSpinner('Checking for existing instances', !ctx.machine, () =>
+      withAdminKernelClient(
+        ctx.opts,
+        async (client) =>
+          (await client.client.call(`${ADMIN_INSTANCE}/list`, {})) as InstanceInfo[],
+      ),
+    )
+  } catch {
+    return []
+  }
+}
+
+/** Print the click-inviting hero for a freshly-active instance. */
+function hero(slug: string, kernelUrl: string): void {
+  console.log('')
+  console.log(renderInstanceHero(slug, guiOrigin(kernelUrl)))
+  console.log('')
+}
+
+async function adopt(info: InstanceInfo): Promise<void> {
+  const { repointedFrom } = await upsertManagedBookmark(info.slug, info.slug, info.url)
+  await setActive(info.slug)
+  if (repointedFrom) {
+    log.warn(
+      `Bookmark "${info.slug}" repointed: ${repointedFrom} → ${normalizeInstanceKernelUrl(info.url)}`,
+    )
+  }
+  log.success(`Active instance: ${info.slug}`)
+  hero(info.slug, info.url)
+}
+
+/**
+ * Step 3 — an active instance, the heart of the flow. If the user already has
+ * managed instances, offer to adopt one or create another; otherwise offer to
+ * provision their first. Either way ends on the instance hero.
+ */
+export const instanceStep: SetupStep = {
+  id: 'instance',
+  title: 'Active instance',
+  group: 'connect',
+
+  async detect(ctx: SetupContext) {
+    const { instance } = await readLocalStatus()
+    if (instance) {
+      return { state: 'satisfied', summary: `${instance.active} (${guiOrigin(instance.url)})` }
+    }
+    return {
+      state: 'gap',
+      summary: 'No active instance',
+      fixHint: ctx.slug ? `astrale instance create ${ctx.slug}` : 'astrale instance create <slug>',
+    }
+  },
+
+  async ensure(ctx: SetupContext) {
+    const { instance } = await readLocalStatus()
+    if (instance) {
+      log.success(`Active instance: ${instance.active} (${guiOrigin(instance.url)})`)
+      return 'unchanged'
+    }
+
+    const managed = await fetchManaged(ctx)
+
+    // Pick an existing instance or fall through to creating a new one.
+    if (managed.length > 0) {
+      const choice = await selectFrom<InstanceInfo | 'create'>(
+        'No active instance. Pick one or create a new instance:',
+        [
+          ...managed.map((info) => ({
+            label: `${info.slug}  ${chalk.dim(guiOrigin(info.url))}`,
+            value: info as InstanceInfo | 'create',
+          })),
+          { label: chalk.cyan('➕  Create a new instance'), value: 'create' as const },
+        ],
+      )
+      if (choice === null) {
+        log.dim('  Skipped — no active instance set.')
+        return 'skipped'
+      }
+      if (choice !== 'create') {
+        await adopt(choice)
+        return 'fixed'
+      }
+    } else {
+      const yes = await confirmDefaultYes('No instances yet. Provision your first one now?')
+      if (!yes) {
+        log.dim('  Skipped — create one later: astrale instance create <slug>')
+        return 'skipped'
+      }
+    }
+
+    const slug =
+      ctx.slug ?? (await promptText('Pick a slug for your instance', { validate: slugError }))
+    if (!slug) {
+      log.dim('  Skipped — no slug given.')
+      return 'skipped'
+    }
+
+    const { created } = await provisionInstance(slug, ctx.opts)
+    hero(slug, created.url)
+    return 'fixed'
+  },
+}

package/src/setup/steps/skills-bridge.ts

@@ -0,0 +1,70 @@
+import { existsSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+import type { SetupStep } from '../types'
+
+import { log } from '../../lib/log'
+import { ensureSkillsBridge, skillsBridgeStatus } from '../../lib/skills'
+
+/**
+ * Equip — make a workspace's own staged skills loadable. Agent tooling stages
+ * skills under `.agents/skills`, but the harness (Claude Code et al.) only loads
+ * `.claude/skills` (walking up to the project root). A single
+ * `.claude/skills -> ../.agents/skills` symlink bridges every staged skill —
+ * present and future — for this workspace and every project nested under it.
+ * This is exactly how this monorepo wires its own skills; doing it in `setup`
+ * means a skill landing in `.agents/skills` is loaded, not silently invisible
+ * (the gap that let agent-browser report "installed" yet never load).
+ *
+ * Runs first in the equip group so the per-skill steps below detect against the
+ * already-bridged state. Idempotent and non-destructive.
+ */
+function countStaged(root: string): number {
+  try {
+    const dir = join(root, '.agents', 'skills')
+    return readdirSync(dir).filter((e) => existsSync(join(dir, e, 'SKILL.md'))).length
+  } catch {
+    return 0
+  }
+}
+
+export const skillsBridgeStep: SetupStep = {
+  id: 'skills-bridge',
+  title: 'workspace skills bridge',
+  group: 'equip',
+
+  async detect() {
+    const s = skillsBridgeStatus()
+    if (s.kind === 'none') return { state: 'satisfied', summary: 'no workspace skills to bridge' }
+    if (s.kind === 'bridged')
+      return { state: 'satisfied', summary: '.agents/skills bridged → the harness loads them' }
+    if (s.kind === 'foreign')
+      return { state: 'satisfied', summary: '.claude/skills already present — left as-is' }
+    const n = countStaged(s.root)
+    return {
+      state: 'gap',
+      summary: `${n} skill${n === 1 ? '' : 's'} in .agents/skills not loaded by the harness`,
+      fixHint: `ln -s ../.agents/skills ${s.link}`,
+    }
+  },
+
+  async ensure() {
+    const before = skillsBridgeStatus()
+    if (before.kind === 'none' || before.kind === 'bridged') return 'unchanged'
+    if (before.kind === 'foreign') {
+      log.dim('  .claude/skills already exists — leaving it untouched.')
+      return 'unchanged'
+    }
+    const after = ensureSkillsBridge()
+    if (after.kind === 'bridged') {
+      log.success(
+        `Workspace skills bridged — ${join(after.root, '.agents/skills')} → .claude/skills`,
+      )
+      return 'fixed'
+    }
+    log.warn(
+      'Could not create the skills bridge — create it manually: ln -s ../.agents/skills .claude/skills',
+    )
+    return 'failed'
+  },
+}

package/src/setup/steps/skills.ts

@@ -0,0 +1,59 @@
+import type { SetupStep } from '../types'
+
+import { log } from '../../lib/log'
+import {
+  ASTRALE_CLI_SKILL,
+  ASTRALE_DOMAIN_SKILL,
+  detectSkill,
+  installSkills,
+  SKILL_INSTALL_HINT,
+} from '../../lib/skills'
+
+const FIX = SKILL_INSTALL_HINT
+
+/**
+ * Equip — the astrale agent skills. Both the astrale-cli (ops) and astrale-domain
+ * (authoring) skills publish from the one public `astrale-os/cli` repo, so a
+ * single `npx skills add astrale-os/cli -g` installs both, globally. We don't
+ * reimplement skill installation; we detect presence and delegate to `npx skills
+ * add` (the skill package manager). A global (user-level) install equips every
+ * project on the machine, so a freshly scaffolded domain has the skills without
+ * shipping its own copy.
+ */
+const bothInstalled = (): boolean =>
+  detectSkill(ASTRALE_CLI_SKILL).installed && detectSkill(ASTRALE_DOMAIN_SKILL).installed
+
+export const skillsStep: SetupStep = {
+  id: 'skills',
+  title: 'astrale agent skills (cli + domain)',
+  group: 'equip',
+
+  async detect() {
+    if (bothInstalled()) {
+      return { state: 'satisfied', summary: 'astrale-cli + astrale-domain skills installed' }
+    }
+    const have = detectSkill(ASTRALE_CLI_SKILL).installed
+      ? 'astrale-domain'
+      : 'astrale agent skills'
+    return { state: 'gap', summary: `${have} not installed`, fixHint: FIX }
+  },
+
+  async ensure() {
+    if (bothInstalled()) {
+      log.success('astrale-cli + astrale-domain skills already installed')
+      return 'unchanged'
+    }
+
+    log.step(`Installing the astrale agent skills — ${FIX}`)
+    if (!(await installSkills())) {
+      log.warn(`Skill install did not complete — run it later: ${FIX}`)
+      return 'failed'
+    }
+    if (bothInstalled()) {
+      log.success('astrale-cli + astrale-domain skills installed')
+    } else {
+      log.success('astrale-cli skill installed')
+    }
+    return 'fixed'
+  },
+}

package/src/setup/types.ts

@@ -0,0 +1,61 @@
+import type { AdminTargetCommandOpts } from '../lib/admin-target'
+
+/**
+ * The setup reconciler models onboarding as a list of small, independent steps,
+ * each able to (a) `detect` its state without side effects and (b) `ensure` its
+ * state interactively, taking the user by the hand. `detect` powers the
+ * read-only plan + checklist (and the agent-facing `--plan` JSON); `ensure` is
+ * the hand-held fix. Both are idempotent — re-running setup when everything is
+ * already satisfied just prints a row of ✔.
+ */
+
+export type StepState = 'satisfied' | 'gap' | 'broken'
+
+export type StepDetection = {
+  state: StepState
+  /** One-line status for the checklist (no symbol — the renderer adds it). */
+  summary: string
+  /** Optional dim detail line. */
+  detail?: string
+  /** The granular command an agent (or a human) would run to close the gap. */
+  fixHint?: string
+}
+
+export type StepOutcome = 'fixed' | 'unchanged' | 'skipped' | 'failed'
+
+export type SetupOpts = AdminTargetCommandOpts & {
+  /** Read-only: print the plan and exit without mutating anything. */
+  plan?: boolean
+  json?: boolean
+  raw?: boolean
+  // Global flags (program.ts) that force non-interactive.
+  ci?: boolean
+  noPrompt?: boolean
+  // Threaded into admin-kernel calls (provisioning, instance listing).
+  as?: string
+  creds?: string
+  timeout?: string
+  debug?: boolean
+}
+
+export type SetupContext = {
+  /** TTY and not --ci / --no-prompt / CI: ok to prompt and mutate. */
+  interactive: boolean
+  /** isMachine(opts): --json / --raw or piped — structured output, no spinners. */
+  machine: boolean
+  opts: SetupOpts
+  /** Instance slug hint from the positional arg, used when provisioning. */
+  slug?: string
+}
+
+export type StepGroup = 'connect' | 'equip'
+
+export type SetupStep = {
+  id: string
+  title: string
+  group: StepGroup
+  /** Read-only probe for the plan + checklist. Never prompts, never mutates. */
+  detect: (ctx: SetupContext) => Promise<StepDetection>
+  /** Interactive, idempotent hand-holding. May print rich output (e.g. a hero). */
+  ensure: (ctx: SetupContext) => Promise<StepOutcome>
+}

package/src/setup/util.ts

@@ -0,0 +1,34 @@
+import { validateSlug, validateUrl } from '../lib/validation'
+
+/**
+ * The clickable GUI origin for an instance — its kernel URL stripped of the
+ * `/api` path bookmarks carry (`https://app.eu.astrale.ai/api` →
+ * `https://app.eu.astrale.ai`). This is the URL we put in front of the user.
+ */
+export function guiOrigin(kernelUrl: string): string {
+  try {
+    return new URL(kernelUrl).origin
+  } catch {
+    return kernelUrl
+  }
+}
+
+/** inquirer `validate`: true when the slug is valid, else the human message. */
+export function slugError(value: string): true | string {
+  try {
+    validateSlug(value)
+    return true
+  } catch (e) {
+    return e instanceof Error ? e.message : 'Invalid slug'
+  }
+}
+
+/** inquirer `validate`: true when the value is an http(s) URL, else the message. */
+export function urlError(value: string): true | string {
+  try {
+    validateUrl(value)
+    return true
+  } catch (e) {
+    return e instanceof Error ? e.message : 'Invalid URL'
+  }
+}

package/src/test-utils.ts

@@ -0,0 +1,18 @@
+import { mkdtemp, mkdir } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { createPaths, type Paths } from './lib/env'
+
+export type TestEnv = {
+  paths: Paths
+  tmp: string
+}
+
+export async function createTestEnv(): Promise<TestEnv> {
+  const tmp = await mkdtemp(join(tmpdir(), 'astrale-test-'))
+  const paths = createPaths(tmp)
+  await mkdir(paths.keys, { recursive: true })
+  await mkdir(paths.data, { recursive: true })
+  return { paths, tmp }
+}