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

package/studio/server/environment/files.test.ts

@@ -0,0 +1,53 @@
+import { afterEach, expect, test } from 'bun:test'
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { readEnvModel } from './files'
+
+const roots: string[] = []
+
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
+})
+
+test('env editor composes typed fields with isolated config and dotenv previews', () => {
+  const root = mkdtempSync(join(tmpdir(), 'studio-env-preview-'))
+  roots.push(root)
+  writeFileSync(
+    join(root, 'env.ts'),
+    `export interface Env {
+  /** API credential. */
+  API_TOKEN: string
+  OPTIONAL_NOTE?: string
+  WORKER_URL: string
+}`,
+  )
+  writeFileSync(
+    join(root, 'astrale.config.ts'),
+    `// astrale({ dev: { secrets: '.env.fake' } })
+export default cloudflare({ dev: { secrets: '.env.dev' } })`,
+  )
+  writeFileSync(join(root, '.env.dev'), `BASE=token\nAPI_TOKEN="${'${BASE}'}-value"\nORPHAN=kept\n`)
+
+  expect(readEnvModel(root, 'dev')).toEqual({
+    env: 'dev',
+    file: '.env.dev',
+    configured: true,
+    exists: true,
+    adapter: 'cloudflare',
+    requiredMissing: 0,
+    rows: [
+      {
+        name: 'API_TOKEN',
+        value: 'token-value',
+        declared: true,
+        optional: false,
+        doc: 'API credential.',
+      },
+      { name: 'OPTIONAL_NOTE', value: '', declared: true, optional: true },
+      { name: 'BASE', value: 'token', declared: false, optional: true },
+      { name: 'ORPHAN', value: 'kept', declared: false, optional: true },
+    ],
+  })
+})

package/studio/server/{state/env.ts → environment/files.ts}

@@ -1,5 +1,5 @@
 /**
- * env.ts — the env-vars editor backend. Reconciles a domain's `.env.<env>` file
+ * Environment file editor. Reconciles a domain's `.env.<env>` file
  * (the actual secrets/vars, dotenv format) against the `Env` interface in
  * `env.ts` (the typed contract, parsed by buildEnvFields), and is the ONE place
  * the otherwise read-only studio writes a domain file — the explicit exception
@@ -16,6 +16,8 @@ import { join, resolve } from 'node:path'
 import type { EnvFileModel, EnvName, EnvVarRow } from '../../shared/types'
 
 import { buildEnvFields } from '../introspect/anatomy-extras'
+import { readConfigPreview } from '../introspect/config-preview'
+import { parseDotenvPreview } from './dotenv-preview'
 
 const ENV_NAMES: EnvName[] = ['dev', 'prod']
 export const isEnvName = (v: unknown): v is EnvName =>
@@ -25,55 +27,12 @@ export const isEnvName = (v: unknown): v is EnvName =>
  *  and every domain uses. The filename is fixed, so no path-traversal is possible. */
 const envFileName = (env: EnvName) => `.env.${env}`
 
-/** Mirror of the SDK's minimal dotenv parser (`@astrale-os/sdk` cli/dotenv) so the
- *  studio reads values exactly as the deploy path will: `#` comments, `export`,
- *  quotes (single = literal), `${VAR}` interpolation against earlier keys. */
-function parseDotenv(contents: string): Record<string, string> {
-  const out: Record<string, string> = {}
-  for (const raw of contents.split('\n')) {
-    const line = raw.trim()
-    if (!line || line.startsWith('#')) continue
-    const m = /^(?:export\s+)?([A-Za-z_]\w*)\s*=\s*(.*)$/.exec(line)
-    if (!m) continue
-    let value = m[2].trim()
-    const single = value.length >= 2 && value.startsWith("'") && value.endsWith("'")
-    if (single || (value.length >= 2 && value.startsWith('"') && value.endsWith('"')))
-      value = value.slice(1, -1)
-    out[m[1]] = single ? value : value.replace(/\$\{(\w+)\}/g, (_, n: string) => out[n] ?? '')
-  }
-  return out
-}
-
-/** astrale.config.ts with comments stripped — so a COMMENTED-OUT adapter block
- *  (e.g. the scaffold's "swap to cloudflare" example) never reads as active config.
- *  The `[^:]` guard keeps `https://` in URLs from being mistaken for a line comment. */
-function configText(root: string): string {
-  let s: string
-  try {
-    s = readFileSync(join(root, 'astrale.config.ts'), 'utf8')
-  } catch {
-    return ''
-  }
-  return s.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:])\/\/.*$/gm, '$1')
-}
-
-/** Is this `.env.<env>` wired into astrale.config's ACTIVE `secrets:`? (vs convention only) */
-function isConfigured(config: string, env: EnvName): boolean {
-  return new RegExp(`secrets\\s*:\\s*['"]\\.env\\.${env}['"]`).test(config)
-}
-
-function adapterOf(config: string): EnvFileModel['adapter'] {
-  if (/\bastrale\s*\(/.test(config)) return 'astrale'
-  if (/\bcloudflare\s*\(/.test(config)) return 'cloudflare'
-  return 'unknown'
-}
-
 /** Build the merged model for one env: env.ts fillable fields ⨯ the `.env.<env>` values. */
 export function readEnvModel(root: string, env: EnvName): EnvFileModel {
   const file = envFileName(env)
   const abs = join(root, file)
   const exists = existsSync(abs)
-  const values = exists ? parseDotenv(readFileSync(abs, 'utf8')) : {}
+  const values = exists ? parseDotenvPreview(readFileSync(abs, 'utf8')) : {}
 
   // env.ts contract — only fillable (non-binding) fields; bindings are adapter-injected.
   const declared = buildEnvFields(root).filter((f) => f.secret)
@@ -92,13 +51,13 @@ export function readEnvModel(root: string, env: EnvName): EnvFileModel {
   }
 
   const requiredMissing = rows.filter((r) => r.declared && !r.optional && r.value === '').length
-  const config = configText(root)
+  const config = readConfigPreview(root)
   return {
     env,
     file,
-    configured: isConfigured(config, env),
+    configured: config.configuredSecretFiles.includes(file),
     exists,
-    adapter: adapterOf(config),
+    adapter: config.adapter,
     rows,
     requiredMissing,
   }

package/studio/server/{state → handoff}/copy.ts

@@ -1,16 +1,18 @@
 /**
- * copy.ts — the copy-payload builder. A PURE function (no IO): it turns studio
+ * Pure copy-payload projection for a Studio handoff (no IO). It turns studio
  * state into a single Markdown handoff payload that an author agent can paste
  * into its own session. The payload ends with a fenced ```json``` machine-state
  * block in the annotate shape so the author can reply by appending
  * {role:'author'} thread entries and merging back by id.
  */
-import type { Comment, ContextItem, DocMeta, ThreadEntry } from '../../shared/types'
+import type { Comment, ContextItem, DocMeta, SchemaRevision, ThreadEntry } from '../../shared/types'
 
 interface CopyParts {
   origin: string
   root: string
-  schemaHash: string
+  /** Studio render fingerprint retained by the handoff machine-state. */
+  renderFingerprint: string
+  schemaRevision?: SchemaRevision
   openComments: Comment[]
   userContext: ContextItem[]
   autoContext: ContextItem[]
@@ -61,7 +63,16 @@ function toMachineState(comment: Comment): {
 }
 
 export function buildCopyMarkdown(parts: CopyParts): string {
-  const { origin, root, schemaHash, openComments, userContext, autoContext, documents = [] } = parts
+  const {
+    origin,
+    root,
+    renderFingerprint,
+    schemaRevision,
+    openComments,
+    userContext,
+    autoContext,
+    documents = [],
+  } = parts
   const lines: string[] = []
 
   // ── Header ──
@@ -69,7 +80,8 @@ export function buildCopyMarkdown(parts: CopyParts): string {
   lines.push('')
   lines.push(`- **Origin:** \`${origin}\``)
   lines.push(`- **Repo root:** \`${root}\``)
-  lines.push(`- **Schema hash:** \`${schemaHash}\``)
+  if (schemaRevision) lines.push(`- **Schema revision:** \`${schemaRevision}\``)
+  lines.push(`- **Render fingerprint:** \`${renderFingerprint}\``)
   lines.push('')
   lines.push(
     'Load the **astrale-domain** skill, use the context/threads below, ' +
@@ -143,8 +155,11 @@ export function buildCopyMarkdown(parts: CopyParts): string {
   }
 
   // ── Trailing machine-state block ──
+  // `schemaVersion` is the established annotate wire key. Its value remains the
+  // render fingerprint because it detects anchor/layout drift, not installation
+  // compatibility.
   const machineState = {
-    schemaVersion: schemaHash,
+    schemaVersion: renderFingerprint,
     comments: openComments.map(toMachineState),
   }
   lines.push('```json')

package/studio/server/handoff/service.test.ts

@@ -0,0 +1,22 @@
+import { expect, test } from 'bun:test'
+
+import type { ChangeSet } from '../../shared/types'
+
+import { changeText } from './service'
+
+test('labels schema changes as indicative structure rather than Runtime compatibility', () => {
+  const changes: ChangeSet = {
+    source: 'baseline',
+    hasGit: false,
+    hasBaseline: true,
+    schemaChanges: [{ kind: 'class-removed', target: 'Legacy' }],
+    fileChanges: [],
+    structuralStatus: 'changed',
+  }
+
+  const text = changeText(changes)
+  expect(text).toContain('Indicative source/structure diff only')
+  expect(text).toContain('~ class-removed Legacy')
+  expect(text).not.toContain('BREAKING')
+  expect(text).not.toContain('additive')
+})

package/studio/server/{state/handoff.ts → handoff/service.ts}

@@ -1,5 +1,5 @@
 /**
- * handoff.ts — shared helpers that turn live domain state into the "what changed
+ * Handoff service that turns live domain state into the "what changed
  * + what to read" material both the Copy payload (api.ts) and the live agent
  * runner depend on. Extracted so there is ONE definition of the change text and
  * the auto-context refresh.
@@ -8,29 +8,36 @@ import type { ChangeSet } from '../../shared/types'
 import type { DomainHandle } from '../domain'
 
 import { getBundle } from '../cache'
-import { computeChanges, hashAnatomyFiles } from './baseline'
-import { readComments } from './comments'
-import { materializeAuto } from './context'
+import { computeChanges, hashAnatomyFiles } from '../state/baseline'
+import { readComments } from '../state/comments'
+import { materializeAuto } from '../state/context'
+import { detectGit, gitDiff } from '../workspace/git'
 
 /** Current changes vs the review baseline (schema IR diff + anatomy file diff). */
 export async function changeSet(handle: DomainHandle): Promise<ChangeSet> {
   const bundle = await getBundle(handle.id)
   const files = hashAnatomyFiles(handle.root, handle.schemaDirName)
+  const { hasGit } = detectGit(handle.root)
+  const diffText = hasGit ? gitDiff(handle.root, handle.schemaDirName) : null
   return computeChanges(handle.root, bundle?.ir ?? null, files, {
-    schemaDirName: handle.schemaDirName,
+    currentRevision: bundle?.schemaRevision ?? null,
+    git: {
+      hasGit,
+      ...(diffText === null ? {} : { diffText }),
+    },
   })
 }
 
 /** A human-readable "current changes" blob for the handoff payload. */
 export function changeText(cs: ChangeSet): string {
-  if (cs.schemaDiffText && cs.schemaDiffText.trim()) return cs.schemaDiffText.trim()
+  const notice =
+    'Indicative source/structure diff only; the Kernel Runtime has not assessed installation or data migration.'
+  if (cs.schemaDiffText && cs.schemaDiffText.trim()) return `${notice}\n${cs.schemaDiffText.trim()}`
   const lines: string[] = []
   for (const c of cs.schemaChanges)
-    lines.push(
-      `${c.breaking ? '! ' : '+ '}${c.kind} ${c.target}${c.detail ? ` (${c.detail})` : ''}`,
-    )
+    lines.push(`~ ${c.kind} ${c.target}${c.detail ? ` (${c.detail})` : ''}`)
   for (const f of cs.fileChanges) lines.push(`~ ${f.status} ${f.file}`)
-  return lines.join('\n')
+  return lines.length > 0 ? `${notice}\n${lines.join('\n')}` : ''
 }
 
 /** Refresh the on-disk context/auto digests so an external agent can read them. */
@@ -44,12 +51,12 @@ export async function refreshAuto(handle: DomainHandle): Promise<void> {
         `${i + 1}. [${c.kind} ${c.id}] ${c.anchorRefs[0]?.ref ?? ''} — ${c.thread.at(-1)?.text ?? ''}`,
     )
     .join('\n')
-  const schemaSummary = cs.schemaChanges
-    .map((c) => `${c.breaking ? 'BREAKING ' : ''}${c.kind} ${c.target}`)
-    .join('\n')
+  const schemaSummary = cs.schemaChanges.map((c) => `STRUCTURAL ${c.kind} ${c.target}`).join('\n')
   materializeAuto(handle.root, {
     changes: changeText(cs) || 'no tracked changes',
-    schemaChange: schemaSummary || 'no schema changes since baseline',
+    schemaChange: schemaSummary
+      ? `Indicative only; Runtime compatibility was not assessed.\n${schemaSummary}`
+      : 'no schema changes since baseline',
     comments: commentsDigest || 'no open comments',
   })
 }

package/studio/server/index.ts

@@ -42,7 +42,7 @@ const domains = resolveTarget(target, schemaDir)
 if (!domains.length) {
   console.error(`\n  ✗ No Astrale domains found at ${target}`)
   console.error(
-    `    (looking for: astrale.config.ts + implementation.ts (or legacy domain.ts) + ${schemaDir}/index.ts)\n`,
+    `    (looking for: astrale.config.ts + application.ts + schema.ts or ${schemaDir}/index.ts)\n`,
   )
   process.exit(1)
 }

package/studio/server/instances/active.ts

@@ -0,0 +1,72 @@
+import type { InstanceInfo, InstancesState } from '../../shared/types'
+
+import { decodeJsonObject, runStudioCliJson, runStudioCliText } from '../cli'
+
+async function astraleJson(args: string[]): Promise<Record<string, unknown> | null> {
+  const result = await runStudioCliJson(args, decodeJsonObject)
+  return result.ok ? result.data : null
+}
+
+function records(value: unknown): Record<string, unknown>[] {
+  return Array.isArray(value) ? value.map(decodeJsonObject).filter((item) => item !== null) : []
+}
+
+async function activeName(): Promise<string | null> {
+  const active = await astraleJson(['instance', 'active', '--json'])
+  return typeof active?.name === 'string' ? active.name : null
+}
+
+/** The CLI-owned global active instance. */
+export const activeInstanceName = activeName
+
+export async function listInstances(): Promise<InstancesState> {
+  const local = await astraleJson(['instance', 'list', '--bookmarked', '--json'])
+  const active = typeof local?.active === 'string' ? local.active : await activeName()
+  const instances: InstanceInfo[] = []
+  for (const bookmark of records(local?.bookmarks)) {
+    if (typeof bookmark.name !== 'string') continue
+    instances.push({
+      name: bookmark.name,
+      url: typeof bookmark.url === 'string' ? bookmark.url : '',
+      active: bookmark.active === true || bookmark.name === active,
+      kind: 'bookmark',
+    })
+  }
+  const managed = await astraleJson(['instance', 'list', '--admin-only', '--json'])
+  for (const item of records(managed?.instances)) {
+    if (
+      typeof item.slug !== 'string' ||
+      instances.some((instance) => instance.name === item.slug)
+    ) {
+      continue
+    }
+    instances.push({
+      name: item.slug,
+      url: typeof item.url === 'string' ? item.url : '',
+      active: item.slug === active,
+      kind: 'managed',
+    })
+  }
+  if (active && !instances.some((instance) => instance.name === active)) {
+    instances.unshift({ name: active, url: '', active: true, kind: 'bookmark' })
+  }
+  return { active, instances }
+}
+
+export async function setActiveInstance(
+  name: string,
+): Promise<{ ok: boolean; active: string | null; output: string }> {
+  const result = await runStudioCliText([
+    'instance',
+    'use',
+    name,
+    '--adopt-default',
+    '--skip-jwks-check',
+  ])
+  const combined = `${result.stdout}\n${result.stderr}`.trim()
+  return {
+    ok: result.ok,
+    active: await activeName(),
+    output: (combined || result.detail).slice(-1000),
+  }
+}

package/studio/server/instances/deploy-record.test.ts

@@ -0,0 +1,31 @@
+import { afterEach, expect, test } from 'bun:test'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { writeJson } from '../state/store'
+import { lastDeploy } from './deploy-record'
+
+const roots: string[] = []
+
+afterEach(() => {
+  while (roots.length > 0) rmSync(roots.pop()!, { recursive: true, force: true })
+})
+
+test('reads the previous deploy fingerprint key but exposes only the current name', () => {
+  const root = mkdtempSync(join(tmpdir(), 'studio-deploy-record-'))
+  roots.push(root)
+  writeJson(root, 'deploy.json', {
+    at: '2026-08-20T00:00:00.000Z',
+    schemaHash: 'sha-legacy',
+    ok: true,
+    url: 'https://notes.svc.example.astrale.ai',
+  })
+
+  expect(lastDeploy(root)).toEqual({
+    at: '2026-08-20T00:00:00.000Z',
+    renderFingerprint: 'sha-legacy',
+    ok: true,
+    url: 'https://notes.svc.example.astrale.ai',
+  })
+})

package/studio/server/instances/deploy-record.ts

@@ -0,0 +1,37 @@
+import type { DeployRecord } from '../../shared/types'
+
+import { asJsonRecord, asString } from '../json'
+import { readJson, writeJson } from '../state/store'
+
+const DEPLOY_RECORD_FILE = 'deploy.json'
+
+function decodeDeployRecord(value: unknown): DeployRecord | undefined {
+  const stored = asJsonRecord(value)
+  const at = asString(stored?.at)
+  if (!at || stored?.ok !== true) return undefined
+  const renderFingerprint = asString(stored.renderFingerprint) ?? asString(stored.schemaHash) ?? ''
+  const url = asString(stored.url)
+  return {
+    at,
+    renderFingerprint,
+    ok: true,
+    ...(url === undefined ? {} : { url }),
+  }
+}
+
+export function lastDeploy(root: string): DeployRecord | null {
+  return readJson(root, DEPLOY_RECORD_FILE, decodeDeployRecord, null)
+}
+
+export function recordSuccessfulDeploy(
+  root: string,
+  renderFingerprint: string | null,
+  url: string | null,
+): void {
+  writeJson(root, DEPLOY_RECORD_FILE, {
+    at: new Date().toISOString(),
+    renderFingerprint: renderFingerprint ?? '',
+    ok: true,
+    url: url ?? undefined,
+  } satisfies DeployRecord)
+}

package/studio/server/instances/deploy.ts

@@ -0,0 +1,56 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import type { DeployResult } from '../../shared/types'
+import type { DomainHandle } from '../domain'
+
+import { recordSuccessfulDeploy } from './deploy-record'
+
+export function hasProdScript(root: string): boolean {
+  try {
+    const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'))
+    return typeof pkg?.scripts?.prod === 'string'
+  } catch {
+    return false
+  }
+}
+
+const SVC_URL = /https:\/\/[\w-]+\.svc\.[\w.-]+\.astrale\.ai\b/
+
+/** Run `pnpm prod` only after an explicit outward-facing deploy request. */
+export async function runDeploy(
+  handle: DomainHandle,
+  renderFingerprint: string | null,
+): Promise<DeployResult> {
+  if (!hasProdScript(handle.root)) {
+    return {
+      ok: false,
+      url: null,
+      output:
+        'This domain has no "prod" script in package.json — it is not deployable via `pnpm prod`.',
+    }
+  }
+  let out = ''
+  let err = ''
+  let code = 1
+  try {
+    const proc = Bun.spawn(['pnpm', 'prod'], {
+      cwd: handle.root,
+      stdout: 'pipe',
+      stderr: 'pipe',
+    })
+    ;[out, err] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+    ])
+    code = await proc.exited
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    return { ok: false, url: null, output: `failed to start pnpm: ${message}` }
+  }
+  const combined = `${out}\n${err}`.trim()
+  const url = combined.match(SVC_URL)?.[0] ?? null
+  const ok = code === 0
+  if (ok) recordSuccessfulDeploy(handle.root, renderFingerprint, url)
+  return { ok, url, output: combined.slice(-6000) }
+}

package/studio/server/{state/instance.test.ts → instances/probe.test.ts}

@@ -1,16 +1,17 @@
 import { describe, expect, test } from 'bun:test'
 
-import { schemaHashOf } from '../introspect/hash'
-import {
-  installedBundleRootHash,
-  installedDomainCommand,
-  installedDomainProbeResult,
-} from './instance'
+import { installedDomainCommand, installedDomainProbeResult } from './probe'
 
 describe('installed Domain introspection', () => {
   test('uses the public bundle introspection command for the selected instance', () => {
-    expect(installedDomainCommand('issues.astrale.ai', 'staging')).toEqual([
-      'astrale',
+    const descriptor = JSON.stringify({
+      version: 1,
+      executable: '/usr/local/bin/bun',
+      args: ['/workspace/cli/bin/astrale.ts'],
+    })
+    expect(installedDomainCommand('issues.astrale.ai', 'staging', descriptor)).toEqual([
+      '/usr/local/bin/bun',
+      '/workspace/cli/bin/astrale.ts',
       'introspect',
       'issues.astrale.ai',
       '--bundle',
@@ -20,22 +21,25 @@ describe('installed Domain introspection', () => {
     ])
   })
 
-  test('hashes the installed Bundle root with the same deterministic hash as local schema', () => {
+  test('retains the complete installed Bundle for installed SDK admission', () => {
     const root = {
       version: 'v1',
       domain: 'issues.astrale.ai',
       classes: { Issue: { properties: { title: { type: 'string' } } } },
     }
-    const probe = installedDomainProbeResult(
-      JSON.stringify({
-        state: 'ready',
-        bundle: { format: 'astrale.dsl.bundle', version: 'v1', root, closure: [] },
-      }),
-      '',
-      0,
-    )
-    expect(probe.state).toBe('installed')
-    expect(installedBundleRootHash(probe)).toBe(schemaHashOf(root))
+    expect(
+      installedDomainProbeResult(
+        JSON.stringify({
+          state: 'ready',
+          bundle: { format: 'astrale.dsl.bundle', version: 'v1', root, closure: [] },
+        }),
+        '',
+        0,
+      ),
+    ).toEqual({
+      state: 'installed',
+      bundle: { format: 'astrale.dsl.bundle', version: 'v1', root, closure: [] },
+    })
   })
 
   test('does not mistake the removed Domain Node shape for installation introspection', () => {
@@ -45,7 +49,7 @@ describe('installed Domain introspection', () => {
         '',
         0,
       ),
-    ).toEqual({ state: 'unknown', root: null })
+    ).toEqual({ state: 'unknown', bundle: null })
   })
 
   test('recognizes the current CLI not-installed diagnostic', () => {
@@ -58,6 +62,6 @@ describe('installed Domain introspection', () => {
         }),
         1,
       ),
-    ).toEqual({ state: 'not-installed', root: null })
+    ).toEqual({ state: 'not-installed', bundle: null })
   })
 })

package/studio/server/instances/probe.ts

@@ -0,0 +1,67 @@
+import { decodeJsonObject, runStudioCliJson, studioCliCommand } from '../cli'
+
+function installedDomainArgs(origin: string, instance: string): string[] {
+  return ['introspect', origin, '--bundle', '--json', '-i', instance]
+}
+
+export function installedDomainCommand(
+  origin: string,
+  instance: string,
+  encodedDescriptor?: string,
+): string[] {
+  return studioCliCommand(installedDomainArgs(origin, instance), encodedDescriptor)
+}
+
+export type InstalledDomainProbe =
+  | { state: 'installed'; bundle: unknown }
+  | { state: 'not-installed' | 'unknown'; bundle: null }
+
+function jsonObject(text: string): Record<string, unknown> | null {
+  try {
+    const value = JSON.parse(text)
+    return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : null
+  } catch {
+    return null
+  }
+}
+
+export function installedDomainProbeResult(
+  stdout: string,
+  stderr: string,
+  exitCode: number,
+): InstalledDomainProbe {
+  const output = jsonObject(stdout)
+  const diagnostic = jsonObject(stderr)
+  const error = output?.error ?? diagnostic?.error
+  if (
+    error === 'DOMAIN_NOT_INSTALLED' ||
+    error === 'NOT_FOUND' ||
+    /\b(?:DOMAIN_NOT_INSTALLED|NOT_FOUND)\b/.test(`${stdout}\n${stderr}`)
+  ) {
+    return { state: 'not-installed', bundle: null }
+  }
+
+  if (exitCode === 0) {
+    const bundle = output?.bundle
+    if (
+      bundle !== null &&
+      typeof bundle === 'object' &&
+      !Array.isArray(bundle) &&
+      Object.prototype.hasOwnProperty.call(bundle, 'root')
+    ) {
+      return { state: 'installed', bundle }
+    }
+  }
+  return { state: 'unknown', bundle: null }
+}
+
+export async function getInstalledDomain(
+  origin: string,
+  instance: string,
+  timeoutMs = 8000,
+): Promise<InstalledDomainProbe> {
+  const result = await runStudioCliJson(installedDomainArgs(origin, instance), decodeJsonObject, {
+    timeoutMs,
+  })
+  return installedDomainProbeResult(result.stdout, result.stderr, result.exitCode)
+}

package/studio/server/instances/status.test.ts

@@ -0,0 +1,12 @@
+import { expect, test } from 'bun:test'
+
+import { schemaRevisionDrift } from './status'
+
+test('computes drift only from two admitted canonical revisions', () => {
+  const local = `sha256:${'a'.repeat(64)}` as const
+  const other = `sha256:${'b'.repeat(64)}` as const
+  expect(schemaRevisionDrift(local, local)).toBe('in-sync')
+  expect(schemaRevisionDrift(local, other)).toBe('drifted')
+  expect(schemaRevisionDrift(local, null)).toBe('unknown')
+  expect(schemaRevisionDrift(null, other)).toBe('unknown')
+})