@astrale-os/cli 0.4.0-alpha.13

package/src/lib/skills.ts

@@ -0,0 +1,171 @@
+import { existsSync, lstatSync, mkdirSync, readlinkSync, symlinkSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+import { findAgentBrowser } from './browser'
+import { run } from './proc'
+
+/**
+ * Agent skills and the agent-browser tool are owned by the coding-agent harness
+ * (Claude Code et al.) and by npm — not by this CLI. `astrale setup` and
+ * `astrale update` only *detect* them and delegate installation to their real
+ * installers (`npx skills add`, `npm i -g agent-browser`). This module is that
+ * detection + delegation layer.
+ */
+
+/** The skill name the agent harness looks up under `<dir>/<name>/SKILL.md`. */
+export const ASTRALE_CLI_SKILL = 'astrale-cli'
+export const ASTRALE_DOMAIN_SKILL = 'astrale-domain'
+export const AGENT_BROWSER_SKILL = 'agent-browser'
+
+/**
+ * Published skill source consumed by `npx skills add`. The public `astrale-os/cli`
+ * repo hosts BOTH the astrale-cli and astrale-domain skills (under `skills/`), so
+ * one `npx skills add astrale-os/cli` installs both; address one with
+ * `astrale-os/cli@astrale-cli` or `astrale-os/cli@astrale-domain`.
+ */
+export const ASTRALE_CLI_SKILL_SOURCE = 'astrale-os/cli'
+
+/** Human-facing command that installs (or refreshes) both astrale skills, globally. */
+export const SKILL_INSTALL_HINT = `npx skills add ${ASTRALE_CLI_SKILL_SOURCE} -g`
+
+/**
+ * Install or refresh the astrale agent skills by delegating to the skill package
+ * manager (`npx skills add`). We install GLOBALLY (`-g`, user-level): one run
+ * equips every project on the machine — the harness resolves the skills from the
+ * user Claude dir (see {@link detectSkill}) regardless of cwd, and installs land
+ * in `~/.agents/skills` rather than clobbering any project's own `.agents/skills`
+ * (notably this repo's symlinked source). We don't reimplement skill installation
+ * — re-running the real installer is also how an existing install updates to the
+ * latest published SKILL.md, so this doubles as the update path.
+ *
+ * We CAPTURE the installer's output rather than stream it, and surface it only on
+ * failure. A global install reports a benign per-agent note for any agent format
+ * that can't go user-level (e.g. PromptScript: "does not support global skill
+ * installation") as a "Failed to install N" banner — even though `npx skills`
+ * still exits 0 and the skills land for every other agent. Streaming that made a
+ * successful refresh look broken; suppressing it on success lets the caller print
+ * a clean line. Resolves true on exit 0. Requires Node/`npx` on PATH + network.
+ */
+export async function installSkills(): Promise<boolean> {
+  const { code, stdout, stderr } = await run('npx', [
+    'skills',
+    'add',
+    ASTRALE_CLI_SKILL_SOURCE,
+    '-g',
+    '-y',
+  ])
+  if (code !== 0) process.stderr.write(stdout + stderr)
+  return code === 0
+}
+
+/**
+ * The directories the agent harness ACTUALLY loads skills from, in resolution
+ * order: a project `.claude/skills` found by walking UP from cwd (the harness
+ * walks up to the project root), then the user-global Claude dir.
+ *
+ * Deliberately NOT `.agents/skills`: the harness never reads it, so a skill
+ * present only there is on disk but NOT loaded — the false "installed" this
+ * used to report, which let `astrale setup` mark a skill satisfied while the
+ * agent couldn't see it. `.agents/skills` is a SOURCE convention; it only loads
+ * once bridged into `.claude/skills` (e.g. `.claude/skills` symlinked to
+ * `.agents/skills`, as this monorepo wires itself — see {@link ensureSkillsBridge}).
+ * We probe for `SKILL.md` (not the directory) so a symlinked skill still resolves.
+ */
+function skillSearchDirs(): string[] {
+  const dirs: string[] = []
+  let cur = process.cwd()
+  for (;;) {
+    dirs.push(join(cur, '.claude', 'skills'))
+    const parent = dirname(cur)
+    if (parent === cur) break
+    cur = parent
+  }
+  dirs.push(join(homedir(), '.claude', 'skills'))
+  return dirs
+}
+
+export type SkillPresence = { installed: boolean; location: string | null }
+
+/** Is `<name>/SKILL.md` present in a directory the harness actually loads from? */
+export function detectSkill(name: string): SkillPresence {
+  for (const dir of skillSearchDirs()) {
+    const file = join(dir, name, 'SKILL.md')
+    if (existsSync(file)) return { installed: true, location: file }
+  }
+  return { installed: false, location: null }
+}
+
+/** Is the `agent-browser` binary resolvable on PATH? */
+export async function detectAgentBrowser(): Promise<boolean> {
+  return (await findAgentBrowser()) !== null
+}
+
+/* ───────────────────────────── skills bridge ─────────────────────────────
+ * Agent tooling stages skills under `.agents/skills`, but the harness only loads
+ * `.claude/skills` (walking up). A single `.claude/skills -> ../.agents/skills`
+ * symlink bridges EVERY staged skill — present and future — for a workspace and
+ * every project nested under it. This is exactly how this monorepo wires itself.
+ * It complements the global `-g` installs above: those equip machine-wide skills
+ * the CLI owns; this makes a workspace's own staged skills loadable. */
+
+/** The relative target every bridge points at, from `<root>/.claude/skills`. */
+const BRIDGE_TARGET = join('..', '.agents', 'skills')
+
+function isSymlink(p: string): boolean {
+  try {
+    return lstatSync(p).isSymbolicLink()
+  } catch {
+    return false
+  }
+}
+
+/** Nearest ancestor of `fromDir` (inclusive) that stages skills under
+ *  `.agents/skills` — the "skills workspace root". null if none up the tree. */
+function findAgentsSkillsRoot(fromDir: string): string | null {
+  let cur = fromDir
+  for (;;) {
+    if (existsSync(join(cur, '.agents', 'skills'))) return cur
+    const parent = dirname(cur)
+    if (parent === cur) return null
+    cur = parent
+  }
+}
+
+export type BridgeStatus =
+  /** no `.agents/skills` up the tree → nothing to bridge */
+  | { kind: 'none' }
+  /** `.claude/skills` already symlinks to `.agents/skills` → harness loads them */
+  | { kind: 'bridged'; root: string }
+  /** `.claude/skills` exists but isn't our bridge (a real dir / foreign link) → leave it */
+  | { kind: 'foreign'; root: string }
+  /** `.agents/skills` present, no `.claude/skills` → we can create the bridge */
+  | { kind: 'unbridged'; root: string; link: string }
+
+/** Read-only: is the workspace's `.agents/skills` visible to the harness? */
+export function skillsBridgeStatus(fromDir: string = process.cwd()): BridgeStatus {
+  const root = findAgentsSkillsRoot(fromDir)
+  if (!root) return { kind: 'none' }
+  const link = join(root, '.claude', 'skills')
+  if (isSymlink(link)) {
+    try {
+      if (readlinkSync(link) === BRIDGE_TARGET) return { kind: 'bridged', root }
+    } catch {
+      /* unreadable link → treat as foreign, don't touch it */
+    }
+    return { kind: 'foreign', root }
+  }
+  if (existsSync(link)) return { kind: 'foreign', root }
+  return { kind: 'unbridged', root, link }
+}
+
+/** Create the `.claude/skills -> ../.agents/skills` bridge if it's missing.
+ *  Idempotent and NON-destructive: a correct bridge is left as-is; a pre-existing
+ *  real `.claude/skills` (or a foreign symlink) is never clobbered. */
+export function ensureSkillsBridge(fromDir: string = process.cwd()): BridgeStatus {
+  const status = skillsBridgeStatus(fromDir)
+  if (status.kind !== 'unbridged') return status
+  mkdirSync(dirname(status.link), { recursive: true })
+  symlinkSync(BRIDGE_TARGET, status.link)
+  return { kind: 'bridged', root: status.root }
+}

package/src/lib/table.ts

@@ -0,0 +1,62 @@
+import chalk from 'chalk'
+
+/** 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 }
+
+const GUTTER = '  '
+// ESC[…m — built without a control char in the source so no lint disable is needed.
+const ANSI = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, 'g')
+
+/** Printable width of a string, ignoring ANSI color codes. */
+function visibleWidth(s: string): number {
+  return s.replace(ANSI, '').length
+}
+
+/** Pad to a target *visible* width (color codes don't count toward length). */
+function pad(s: string, width: number): string {
+  const diff = width - visibleWidth(s)
+  return diff > 0 ? s + ' '.repeat(diff) : s
+}
+
+/**
+ * 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 function renderTable(
+  rows: Array<Record<string, string>>,
+  opts: { columns: Column[]; showHeader?: boolean },
+): string {
+  if (rows.length === 0) return chalk.dim('  (empty)')
+
+  const cols = opts.columns.filter((c) => rows.some((r) => (r[c.key] ?? '') !== ''))
+  if (cols.length === 0) return chalk.dim('  (empty)')
+
+  const widths = cols.map((c) =>
+    Math.max(
+      opts.showHeader ? c.header.length : 0,
+      ...rows.map((r) => visibleWidth(r[c.key] ?? '')),
+    ),
+  )
+
+  const line = (cell: (col: Column, i: number) => string): string =>
+    '  ' + cols.map(cell).join(GUTTER).replace(/\s+$/, '')
+
+  const lines: string[] = []
+  if (opts.showHeader) {
+    lines.push(line((c, i) => chalk.dim(pad(c.header, widths[i]))))
+  }
+  for (const r of rows) {
+    lines.push(
+      line((c, i) => {
+        const raw = r[c.key] ?? ''
+        const text = i === cols.length - 1 ? raw : pad(raw, widths[i])
+        return c.color ? c.color(text) : text
+      }),
+    )
+  }
+  return lines.join('\n')
+}

package/src/lib/update.ts

@@ -0,0 +1,315 @@
+import { createHash } from 'node:crypto'
+import { chmod, copyFile, mkdir, mkdtemp, readFile, rename, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { z } from 'zod'
+
+import { AstraleError } from '../errors'
+import { INSTALL_PATH } from './paths'
+import { run } from './proc'
+
+const DEFAULT_REPO = 'astrale-os/cli'
+const DEFAULT_CHANNEL = 'alpha'
+
+export const InstallMetadataSchema = z.object({
+  method: z.literal('script'),
+  channel: z.string().min(1).default(DEFAULT_CHANNEL),
+  version: z.string().min(1).optional(),
+  repo: z.string().min(1).default(DEFAULT_REPO),
+  bin: z.string().min(1),
+  installedAt: z.string().optional(),
+})
+
+export type InstallMetadata = z.infer<typeof InstallMetadataSchema>
+
+const ManifestAssetSchema = z.object({
+  name: z.string().min(1),
+  sha256: z
+    .string()
+    .regex(/^[a-fA-F0-9]{64}$/)
+    .optional(),
+})
+
+export const UpdateManifestSchema = z.object({
+  version: z.string().min(1),
+  binaryVersion: z.string().min(1).optional(),
+  channel: z.string().min(1),
+  repo: z.string().min(1).optional(),
+  assets: z.record(
+    z.string(),
+    z.union([
+      ManifestAssetSchema,
+      z
+        .string()
+        .min(1)
+        .transform((name) => ({ name })),
+    ]),
+  ),
+})
+
+export type UpdateManifest = z.infer<typeof UpdateManifestSchema>
+
+export type Platform = {
+  os: 'darwin' | 'linux'
+  arch: 'arm64' | 'x64'
+}
+
+export type UpdateRequest = {
+  check?: boolean
+  channel?: string
+  version?: string
+  currentVersion: string
+  platform?: Platform
+  installPath?: string
+}
+
+export type UpdateResult =
+  | {
+      status: 'up-to-date'
+      currentVersion: string
+      latestVersion: string
+      channel: string
+    }
+  | {
+      status: 'available'
+      currentVersion: string
+      latestVersion: string
+      channel: string
+    }
+  | {
+      status: 'updated'
+      previousVersion: string
+      currentVersion: string
+      channel: string
+      bin: string
+    }
+
+export function detectPlatform(): Platform {
+  const os = process.platform
+  const arch = process.arch
+  if (os !== 'darwin' && os !== 'linux') {
+    throw new AstraleError(
+      'UNSUPPORTED_PLATFORM',
+      `Unsupported OS "${os}" — Astrale update supports macOS and Linux.`,
+    )
+  }
+  if (arch !== 'arm64' && arch !== 'x64') {
+    throw new AstraleError(
+      'UNSUPPORTED_PLATFORM',
+      `Unsupported CPU architecture "${arch}" — Astrale update supports arm64 and x64.`,
+    )
+  }
+  return { os, arch }
+}
+
+export function platformKey(platform: Platform): string {
+  return `${platform.os}-${platform.arch}`
+}
+
+/**
+ * True when running as the Bun-compiled standalone binary (Linux/macOS), which
+ * self-updates by swapping its own file. The Node/npm build does not expose
+ * `process.versions.bun`; it is managed by the user's package manager instead.
+ */
+function isStandaloneBinary(): boolean {
+  return Boolean((process.versions as { bun?: string }).bun)
+}
+
+export async function readInstallMetadata(path = INSTALL_PATH): Promise<InstallMetadata> {
+  let raw: string
+  try {
+    raw = await readFile(path, 'utf8')
+  } catch {
+    throw isStandaloneBinary()
+      ? new AstraleError(
+          'UPDATE_NOT_SCRIPT_INSTALLED',
+          'Astrale was not installed by the official install script.',
+          'Reinstall with: curl -fsSL https://raw.githubusercontent.com/astrale-os/cli/main/install.sh | sh',
+        )
+      : new AstraleError(
+          'UPDATE_PACKAGE_MANAGED',
+          'This Astrale build is managed by your package manager.',
+          'Update with: npm install -g @astrale-os/cli@latest  (or pnpm/bun)',
+        )
+  }
+
+  const parsed = InstallMetadataSchema.safeParse(JSON.parse(raw))
+  if (!parsed.success) {
+    throw new AstraleError(
+      'UPDATE_BAD_INSTALL_METADATA',
+      `Invalid install metadata at ${path}.`,
+      'Reinstall with: curl -fsSL https://raw.githubusercontent.com/astrale-os/cli/main/install.sh | sh',
+    )
+  }
+  return parsed.data
+}
+
+export async function writeInstallMetadata(
+  meta: InstallMetadata,
+  path = INSTALL_PATH,
+): Promise<void> {
+  await mkdir(dirname(path), { recursive: true })
+  await writeFile(path, JSON.stringify(meta, null, 2) + '\n')
+}
+
+export function releaseBase(
+  meta: InstallMetadata,
+  req: Pick<UpdateRequest, 'channel' | 'version'>,
+): string {
+  if (process.env.ASTRALE_UPDATE_BASE) return process.env.ASTRALE_UPDATE_BASE.replace(/\/+$/, '')
+  const repo = meta.repo || DEFAULT_REPO
+  if (req.version) {
+    const version = req.version.replace(/^cli\/v/, '').replace(/^v/, '')
+    return `https://github.com/${repo}/releases/download/cli/v${version}`
+  }
+  return `https://github.com/${repo}/releases/download/${req.channel ?? meta.channel ?? DEFAULT_CHANNEL}`
+}
+
+export async function fetchManifest(base: string): Promise<UpdateManifest> {
+  const raw = await readUrlText(`${base}/manifest.json`)
+  return UpdateManifestSchema.parse(JSON.parse(raw))
+}
+
+export function shouldUpdate(currentVersion: string, manifestVersion: string): boolean {
+  return currentVersion !== manifestVersion
+}
+
+export async function updateAstrale(req: UpdateRequest): Promise<UpdateResult> {
+  const meta = await readInstallMetadata(req.installPath)
+  const currentVersion = meta.version ?? req.currentVersion
+  const channel = req.channel ?? meta.channel ?? DEFAULT_CHANNEL
+  const platform = req.platform ?? detectPlatform()
+  const key = platformKey(platform)
+  const base = releaseBase(meta, { channel, version: req.version })
+  const manifest = await fetchManifest(base)
+  const asset = manifest.assets[key]
+  if (!asset) {
+    throw new AstraleError(
+      'UPDATE_ASSET_NOT_FOUND',
+      `No Astrale CLI release asset for ${key}.`,
+      `Available platforms: ${Object.keys(manifest.assets).join(', ')}`,
+    )
+  }
+
+  if (!shouldUpdate(currentVersion, manifest.version)) {
+    return {
+      status: 'up-to-date',
+      currentVersion,
+      latestVersion: manifest.version,
+      channel: manifest.channel,
+    }
+  }
+
+  if (req.check) {
+    return {
+      status: 'available',
+      currentVersion,
+      latestVersion: manifest.version,
+      channel: manifest.channel,
+    }
+  }
+
+  const tmp = await mkdtemp(join(tmpdir(), 'astrale-update-'))
+  try {
+    const archive = join(tmp, asset.name)
+    await downloadToFile(`${base}/${asset.name}`, archive)
+    const manifestChecksum = 'sha256' in asset ? asset.sha256 : undefined
+    const expected = manifestChecksum ?? (await fetchChecksum(base, asset.name))
+    const actual = await sha256File(archive)
+    if (actual !== expected.toLowerCase()) {
+      throw new AstraleError(
+        'UPDATE_CHECKSUM_MISMATCH',
+        `Checksum mismatch for ${asset.name}.`,
+        `Expected ${expected}; got ${actual}.`,
+      )
+    }
+
+    await extractTarGz(archive, tmp)
+    const nextBin = join(tmp, 'astrale')
+    await chmod(nextBin, 0o755)
+    await smokeVersion(nextBin, manifest.binaryVersion ?? manifest.version)
+
+    const previous = `${meta.bin}.previous`
+    const staged = `${meta.bin}.next`
+    await copyFile(meta.bin, previous).catch(() => undefined)
+    await copyFile(nextBin, staged)
+    await chmod(staged, 0o755)
+    await rename(staged, meta.bin)
+
+    await writeInstallMetadata(
+      {
+        ...meta,
+        channel: manifest.channel,
+        version: manifest.version,
+        installedAt: new Date().toISOString(),
+      },
+      req.installPath,
+    )
+
+    return {
+      status: 'updated',
+      previousVersion: currentVersion,
+      currentVersion: manifest.version,
+      channel: manifest.channel,
+      bin: meta.bin,
+    }
+  } finally {
+    await rm(tmp, { recursive: true, force: true })
+  }
+}
+
+async function readUrlText(url: string): Promise<string> {
+  if (url.startsWith('file://')) {
+    return readFile(new URL(url), 'utf8')
+  }
+  const res = await fetch(url)
+  if (!res.ok) throw new Error(`GET ${url} failed: HTTP ${res.status}`)
+  return res.text()
+}
+
+async function downloadToFile(url: string, path: string): Promise<void> {
+  if (url.startsWith('file://')) {
+    await copyFile(new URL(url), path)
+    return
+  }
+  const res = await fetch(url)
+  if (!res.ok) throw new Error(`GET ${url} failed: HTTP ${res.status}`)
+  const bytes = new Uint8Array(await res.arrayBuffer())
+  await writeFile(path, bytes)
+}
+
+async function fetchChecksum(base: string, assetName: string): Promise<string> {
+  const raw = await readUrlText(`${base}/sha256sums.txt`)
+  for (const line of raw.split(/\r?\n/)) {
+    const [sha, file] = line.trim().split(/\s+/, 2)
+    if (!sha || !file) continue
+    if (file.replace(/^\*/, '') === assetName && /^[a-fA-F0-9]{64}$/.test(sha)) return sha
+  }
+  throw new AstraleError(
+    'UPDATE_CHECKSUM_NOT_FOUND',
+    `Checksum entry not found for ${assetName}.`,
+    `Release base: ${base}`,
+  )
+}
+
+async function sha256File(path: string): Promise<string> {
+  const hash = createHash('sha256')
+  hash.update(await readFile(path))
+  return hash.digest('hex')
+}
+
+async function extractTarGz(archive: string, cwd: string): Promise<void> {
+  const { code, stderr } = await run('tar', ['-xzf', archive, '-C', cwd])
+  if (code !== 0) {
+    throw new Error(`Could not extract update archive: ${stderr.trim()}`)
+  }
+}
+
+async function smokeVersion(bin: string, expectedVersion: string): Promise<void> {
+  const { code, stdout, stderr } = await run(bin, ['--version'])
+  if (code !== 0) throw new Error(`Updated binary failed --version: ${stderr.trim()}`)
+  const actual = stdout.trim()
+  if (actual !== expectedVersion) {
+    throw new Error(`Updated binary reported version ${actual}, expected ${expectedVersion}`)
+  }
+}

package/src/lib/use-target.ts

@@ -0,0 +1,24 @@
+import type { IdentityStore } from './identity'
+import type { InstanceStore } from './instance'
+
+import { resolveInstanceKey } from './instance'
+
+export type UseTarget =
+  | { kind: 'identity'; name: string }
+  | { kind: 'instance'; name: string }
+  | { kind: 'ambiguous'; name: string }
+  | { kind: 'missing'; name: string }
+
+export function resolveUseTarget(
+  name: string,
+  instances: InstanceStore,
+  identities: IdentityStore,
+): UseTarget {
+  const identityExists = !!identities.identities[name]
+  const instanceKey = resolveInstanceKey(instances, name)
+
+  if (identityExists && instanceKey) return { kind: 'ambiguous', name }
+  if (identityExists) return { kind: 'identity', name }
+  if (instanceKey) return { kind: 'instance', name: instanceKey }
+  return { kind: 'missing', name }
+}

package/src/lib/validation.ts

@@ -0,0 +1,59 @@
+import { isDnsLabel } from '@astrale-os/kernel-core'
+import { z } from 'zod'
+
+import { ReservedSlugError } from '../errors'
+
+// Shared validators + schema fragments used by both instance and identity
+// registries — kept in a leaf module to avoid circular imports.
+
+const NAME_RE = /^[a-zA-Z0-9_.-]+$/
+// `host` is the reserved slug of the host/manager kernel (SPEC §5.2); `manager` is the legacy name.
+const RESERVED_SLUGS = new Set(['manager', 'host'])
+
+export { RESERVED_SLUGS }
+
+export function validateName(name: string, entity: string): void {
+  if (!name || !NAME_RE.test(name)) {
+    throw new Error(
+      `Invalid ${entity.toLowerCase()} name "${name}" — must be non-empty and contain only letters, digits, hyphens, underscores, and dots`,
+    )
+  }
+}
+
+export function validateSlug(slug: string): void {
+  // Canonical DNS-label rule (`@astrale-os/kernel-core`): a slug becomes a
+  // hostname label, so reject anything not DNS-safe (§4.7).
+  if (!slug || !isDnsLabel(slug)) {
+    throw new Error(
+      `Invalid slug "${slug}" — must be a lowercase DNS label [a-z0-9-], ≤63 chars, no leading/trailing hyphen (§4.7)`,
+    )
+  }
+  if (RESERVED_SLUGS.has(slug)) {
+    throw new ReservedSlugError(slug)
+  }
+}
+
+export function validateUrl(url: string): void {
+  try {
+    const parsed = new URL(url)
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+      throw new Error('not http(s)')
+    }
+  } catch {
+    throw new Error(`Invalid URL "${url}" — expected a valid http:// or https:// URL`)
+  }
+}
+
+/** Non-throwing predicate form of `validateUrl`. */
+export function isHttpUrl(url: string): boolean {
+  try {
+    validateUrl(url)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** `local` = only this machine. `remote` = mirrored via astrale cloud (§2.7). */
+export const RegistryModeSchema = z.enum(['local', 'remote'])
+export type RegistryMode = z.infer<typeof RegistryModeSchema>