@astrale-os/cli 1.0.0-beta.1 → 1.0.0-beta.2

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 legacy annotate 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/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 cohort 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')
+})

package/studio/server/instances/status.ts

@@ -0,0 +1,49 @@
+import type { InstanceStatus, SchemaRevision } from '../../shared/types'
+import type { DomainHandle } from '../domain'
+
+import { admittedBundleRevision } from '../introspect/revision'
+import { hasProdScript } from './deploy'
+import { lastDeploy } from './deploy-record'
+import { getInstalledDomain } from './probe'
+
+export function schemaRevisionDrift(
+  localRevision: SchemaRevision | null,
+  installedRevision: SchemaRevision | null,
+): InstanceStatus['drift'] {
+  if (!localRevision || !installedRevision) return 'unknown'
+  return localRevision === installedRevision ? 'in-sync' : 'drifted'
+}
+
+export async function instanceStatus(
+  handle: DomainHandle,
+  deployTarget: string | null,
+  origin: string | null,
+  localRevision: SchemaRevision | null,
+): Promise<InstanceStatus> {
+  const deployable = hasProdScript(handle.root)
+  const last = lastDeploy(handle.root)
+  let install: InstanceStatus['install'] = 'unknown'
+  let installedRevision: SchemaRevision | null = null
+  let drift: InstanceStatus['drift'] = 'unknown'
+
+  if (origin && deployTarget) {
+    const probe = await getInstalledDomain(origin, deployTarget)
+    if (probe.state === 'installed') {
+      install = 'installed'
+      installedRevision = await admittedBundleRevision(handle.root, probe.bundle)
+      drift = schemaRevisionDrift(localRevision, installedRevision)
+    } else if (probe.state === 'not-installed') {
+      install = 'not-installed'
+    }
+  }
+
+  return {
+    deployTarget,
+    deployable,
+    install,
+    drift,
+    localRevision,
+    installedRevision,
+    lastDeploy: last,
+  }
+}

package/studio/server/introspect/anatomy/client-tree.ts

@@ -0,0 +1,57 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+import type { ClientTree } from '../../../shared/types'
+
+import { listDirs, listFiles, readTextSafe } from './source'
+
+// Client tree and best-effort top-level route registry parsing.
+const RESERVED_CLIENT_DIRS = new Set(['shell', 'ui', 'views'])
+
+export function buildClientTree(
+  root: string,
+  clientDir: string | null = join(root, 'client'),
+): ClientTree {
+  // Current SDK projects own presentation modules directly under ui/. Legacy
+  // projects still point at a client package whose authored tree is client/src.
+  const srcDir = clientDir
+    ? join(clientDir, 'src')
+    : existsSync(join(root, 'ui'))
+      ? join(root, 'ui')
+      : ''
+  if (!existsSync(srcDir)) {
+    return { shell: [], features: [], routes: {}, present: false }
+  }
+
+  const shell = listFiles(join(srcDir, 'shell'))
+
+  const features = listDirs(srcDir)
+    .filter((d) => !RESERVED_CLIENT_DIRS.has(d))
+    .map((name) => ({ name, files: listFiles(join(srcDir, name)) }))
+
+  const routes = parseRoutes(
+    listFiles(srcDir)
+      .filter((file) => /\.[cm]?[jt]sx?$/.test(file))
+      .map((file) => join(srcDir, file)),
+  )
+
+  return { shell, features, routes, present: true }
+}
+
+/**
+ * Best-effort parse of top-level client route registries. Domains call these
+ * maps ROUTES, VIEW_REGISTRY, or another local name; the stable contract is a
+ * quoted `/ui/…` key pointing at a component identifier.
+ */
+function parseRoutes(files: string[]): Record<string, string> {
+  const routes: Record<string, string> = {}
+  for (const file of files) {
+    const src = readTextSafe(file)
+    const entryRe = /['"`](\/ui\/[^'"`]+)['"`]\s*:\s*([A-Za-z_$][\w$.]*)/g
+    let match: RegExpExecArray | null
+    while ((match = entryRe.exec(src)) !== null) {
+      routes[match[1]] = match[2]
+    }
+  }
+  return routes
+}