@astrale-os/cli 0.4.0-alpha.13

package/studio/server/state/create.ts

@@ -0,0 +1,156 @@
+/**
+ * state/create.ts — scaffold a brand-new domain into the workspace and bring it
+ * online. This is the studio's ONE write that ADDS a domain (every other state
+ * module operates on an existing one).
+ *
+ * Flow: validate the slug → `create-astrale-domain <slug> --yes` in the
+ * workspace root (the managed `astrale` adapter is its default; we stamp the
+ * active instance so prod targets it) → `pnpm install` in the new dir so the
+ * domain is fully introspectable + deployable → register + (re)boot it (the live
+ * watcher may have already booted a deps-less static fallback while we were
+ * installing; we stop that and boot fresh) → warm its bundle. The caller
+ * broadcasts the `workspace` event so every client refetches the domain list.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { getBundle } from '../cache'
+import { registerDomain } from '../domain'
+import { bootDomain } from '../lifecycle'
+import { stoppers, workspaceRoot, workspaceSchemaDirName } from '../workspace-state'
+
+/** Mirrors create-astrale-domain's `isValidSlug`: lowercase letters, digits, dots, dashes;
+ *  must start/end alphanumeric. Also guards the filesystem target (no `/`, no `..`, no leading dot). */
+const SLUG = /^[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/
+
+export interface CreateDomainResult {
+  ok: boolean
+  id?: string
+  origin?: string
+  error?: string
+  output: string
+}
+
+async function run(
+  cmd: string,
+  args: string[],
+  cwd: string,
+): Promise<{ code: number; output: string }> {
+  try {
+    const proc = Bun.spawn([cmd, ...args], {
+      cwd,
+      stdout: 'pipe',
+      stderr: 'pipe',
+      env: process.env,
+    })
+    const [out, err] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+    ])
+    const code = await proc.exited
+    return { code, output: `${out}\n${err}`.trim() }
+  } catch (e) {
+    return { code: 1, output: `failed to spawn ${cmd}: ${(e as Error)?.message ?? e}` }
+  }
+}
+
+export async function createDomain(
+  rawName: string,
+  instance: string | null,
+): Promise<CreateDomainResult> {
+  const name = rawName.trim().toLowerCase()
+  if (!name || name.length > 64 || !SLUG.test(name)) {
+    return {
+      ok: false,
+      error: 'Use lowercase letters, digits, dots and dashes (e.g. “crm” or “crm.acme.dev”).',
+      output: '',
+    }
+  }
+  const root = workspaceRoot()
+  if (!root) return { ok: false, error: 'No workspace root is configured.', output: '' }
+  const dir = join(root, name)
+  if (existsSync(dir)) {
+    return {
+      ok: false,
+      error: `A folder named “${name}” already exists in the workspace.`,
+      output: '',
+    }
+  }
+
+  // 1. Scaffold (non-interactive). `--yes` accepts defaults (astrale adapter, template);
+  //    `--instance` stamps the active instance into the managed prod target.
+  const scaffoldArgs = [
+    '--yes',
+    'create-astrale-domain@latest',
+    name,
+    '--yes',
+    ...(instance ? ['--instance', instance] : []),
+  ]
+  const scaffold = await run('npx', scaffoldArgs, root)
+  if (!existsSync(join(dir, 'domain.ts')) || !existsSync(join(dir, 'astrale.config.ts'))) {
+    return {
+      ok: false,
+      error: 'Scaffolding did not produce a domain. See the log.',
+      output: scaffold.output.slice(-6000),
+    }
+  }
+
+  // 1b. Flag the placeholder origin for the agent (we ask for the name only, so the
+  //     origin is `<name>.example.dev` until someone — or the agent — sets the real one).
+  annotateOrigin(dir)
+
+  // 2. Install deps so the domain is fully introspectable + deployable. Best-effort:
+  //    a scaffolded-but-uninstalled domain still loads (static fallback), so a failed
+  //    install is a soft warning, not a hard failure.
+  const install = await run('pnpm', ['install'], dir)
+
+  // 3. Register + boot with deps present. The live watcher may have already booted a
+  //    deps-less fallback for this dir mid-install — stop it and boot fresh.
+  const handle = registerDomain(dir, workspaceSchemaDirName())
+  if (!handle) {
+    return {
+      ok: false,
+      error: 'Scaffold incomplete — the domain triple is missing.',
+      output: combine(scaffold, install),
+    }
+  }
+  stoppers.get(handle.id)?.()
+  const { origin } = await bootDomain(handle).then((b) => {
+    stoppers.set(handle.id, b.stop)
+    return b
+  })
+  await getBundle(handle.id, true) // refresh the cache now that deps are installed
+
+  return { ok: true, id: handle.id, origin, output: combine(scaffold, install) }
+}
+
+function combine(a: { output: string }, b: { output: string }): string {
+  return `$ create-astrale-domain\n${a.output}\n\n$ pnpm install\n${b.output}`.trim().slice(-6000)
+}
+
+/**
+ * Drop an agent-actionable marker on the origin line of the scaffolded
+ * schema/index.ts. We only ask for the NAME, so the origin starts as the
+ * `<name>.example.dev` placeholder — this comment tells a human (or the studio's
+ * agent) it's a placeholder to change, and that the studio re-parses the literal
+ * as the source of truth so the rename takes effect on save. Best-effort: the
+ * template already explains the origin, so a parse miss is harmless.
+ */
+function annotateOrigin(dir: string): void {
+  const file = join(dir, workspaceSchemaDirName(), 'index.ts')
+  try {
+    const src = readFileSync(file, 'utf8')
+    if (src.includes('ORIGIN —')) return // already annotated (idempotent)
+    const m = src.match(/^([ \t]*)export const schema = defineSchema\(/m)
+    if (!m) return
+    const pad = m[1] ?? ''
+    const note =
+      `${pad}// ORIGIN — the domain's permanent identity in the graph. It was set from the name as a\n` +
+      `${pad}// PLACEHOLDER below; change it to your real domain (e.g. "crm.acme.dev"), ideally BEFORE\n` +
+      `${pad}// the first deploy (the origin is hard to change once installed). The studio parses this\n` +
+      `${pad}// literal as the source of truth, so the rename refreshes on save — no other file to touch.\n`
+    writeFileSync(file, src.replace(m[0], note + m[0]))
+  } catch {
+    /* best-effort */
+  }
+}

package/studio/server/state/documents.ts

@@ -0,0 +1,70 @@
+/**
+ * documents.ts — context DOCUMENTS the user drops in for the AI agent. Files are
+ * stored under `.domain-studio/context/documents/` (allow-listed) and tracked in
+ * an index. They travel with the domain and are part of the agent handoff context.
+ */
+import { randomUUID } from 'node:crypto'
+import { existsSync } from 'node:fs'
+import { extname } from 'node:path'
+
+import type { DocMeta } from '../../shared/types'
+
+import { readJson, removeState, statePath, writeJson, writeStateBuffer } from './store'
+
+const INDEX = 'context/documents/index.json'
+const storedPath = (id: string, name: string) => `context/documents/${id}${extname(name)}`
+
+export function listDocuments(root: string): DocMeta[] {
+  return readJson<DocMeta[]>(root, INDEX, [])
+}
+
+export function addDocument(root: string, name: string, type: string, data: Uint8Array): DocMeta {
+  const id = randomUUID()
+  const stored = storedPath(id, name)
+  writeStateBuffer(root, stored, data)
+  const meta: DocMeta = {
+    id,
+    name: name || 'untitled',
+    type: type || 'application/octet-stream',
+    size: data.byteLength,
+    addedAt: new Date().toISOString(),
+    stored,
+  }
+  const docs = listDocuments(root)
+  docs.unshift(meta)
+  writeJson(root, INDEX, docs)
+  return meta
+}
+
+/** Overwrite an existing document's content in place (keeps id/name). */
+export function updateDocument(root: string, id: string, data: Uint8Array): DocMeta | null {
+  const docs = listDocuments(root)
+  const doc = docs.find((d) => d.id === id)
+  if (!doc) return null
+  writeStateBuffer(root, doc.stored, data)
+  doc.size = data.byteLength
+  doc.updatedAt = new Date().toISOString()
+  writeJson(root, INDEX, docs)
+  return doc
+}
+
+export function deleteDocument(root: string, id: string): boolean {
+  const docs = listDocuments(root)
+  const doc = docs.find((d) => d.id === id)
+  if (!doc) return false
+  removeState(root, doc.stored)
+  writeJson(
+    root,
+    INDEX,
+    docs.filter((d) => d.id !== id),
+  )
+  return true
+}
+
+export function readDocument(root: string, id: string): { meta: DocMeta; abs: string } | null {
+  const doc = listDocuments(root).find((d) => d.id === id)
+  if (!doc) return null
+  const abs = statePath(root, doc.stored)
+  if (!existsSync(abs)) return null
+  return { meta: doc, abs }
+}

package/studio/server/state/env.ts

@@ -0,0 +1,161 @@
+/**
+ * env.ts — the env-vars editor backend. 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
+ * the user sanctioned for env editing.
+ *
+ * Env injection is adapter-specific (cloudflare dev: merged into wrangler vars;
+ * cloudflare/astrale prod: pushed to the worker/platform secret store), but the
+ * secrets FILE is universal (`@astrale-os/sdk` loads `secrets: '.env.<env>'`
+ * wholesale via its dotenv parser). We edit that file; we never deploy.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+import type { EnvFileModel, EnvName, EnvVarRow } from '../../shared/types'
+
+import { buildEnvFields } from '../introspect/anatomy-extras'
+
+const ENV_NAMES: EnvName[] = ['dev', 'prod']
+export const isEnvName = (v: unknown): v is EnvName =>
+  typeof v === 'string' && (ENV_NAMES as string[]).includes(v)
+
+/** The conventional secrets file for an env — what create-astrale-domain scaffolds
+ *  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')) : {}
+
+  // env.ts contract — only fillable (non-binding) fields; bindings are adapter-injected.
+  const declared = buildEnvFields(root).filter((f) => f.secret)
+  const declaredNames = new Set(declared.map((f) => f.name))
+
+  const rows: EnvVarRow[] = declared.map((f) => ({
+    name: f.name,
+    value: values[f.name] ?? '',
+    declared: true,
+    optional: f.optional,
+    ...(f.doc ? { doc: f.doc } : {}),
+  }))
+  // orphans — present in the file but not declared in env.ts (kept, flagged, removable)
+  for (const [name, value] of Object.entries(values)) {
+    if (!declaredNames.has(name)) rows.push({ name, value, declared: false, optional: true })
+  }
+
+  const requiredMissing = rows.filter((r) => r.declared && !r.optional && r.value === '').length
+  const config = configText(root)
+  return {
+    env,
+    file,
+    configured: isConfigured(config, env),
+    exists,
+    adapter: adapterOf(config),
+    rows,
+    requiredMissing,
+  }
+}
+
+/** Quote a value for the dotenv file: bare when safe, single-quoted (literal) for
+ *  most specials, double-quoted+escaped only when it contains a single quote. */
+function formatValue(v: string): string {
+  if (v === '') return ''
+  if (/^[A-Za-z0-9_./:@+-]+$/.test(v)) return v
+  if (!v.includes("'")) return `'${v}'`
+  return `"${v.replace(/(["\\$`])/g, '\\$1')}"`
+}
+
+/** Apply key→value updates to dotenv text IN PLACE — comments, blank lines and key
+ *  order are preserved; `null` deletes a key; unknown keys are appended. */
+function applyUpdates(contents: string, updates: Record<string, string | null>): string {
+  const lines = contents.split('\n')
+  const seen = new Set<string>()
+  const out: string[] = []
+  for (const line of lines) {
+    const m = /^(\s*(?:export\s+)?)([A-Za-z_]\w*)\s*=.*$/.exec(line)
+    if (m && !line.trim().startsWith('#') && m[2] in updates) {
+      const key = m[2]
+      seen.add(key)
+      const val = updates[key]
+      if (val === null) continue // drop the line
+      out.push(`${m[1]}${key}=${formatValue(val)}`)
+      continue
+    }
+    out.push(line)
+  }
+  // preserve a single trailing newline while appending new keys after content
+  const trailing = out.length > 0 && out[out.length - 1] === ''
+  if (trailing) out.pop()
+  for (const [key, val] of Object.entries(updates)) {
+    if (val === null || seen.has(key) || !/^[A-Za-z_]\w*$/.test(key)) continue
+    out.push(`${key}=${formatValue(val)}`)
+  }
+  out.push('') // final newline
+  return out.join('\n')
+}
+
+const SCAFFOLD_HEADER = (env: EnvName) =>
+  `# ${env === 'dev' ? 'Dev' : 'Prod'} secrets — the ENTIRE file is treated as secrets by the adapter.\n# Gitignored. Edited via the Domain Studio settings.\n`
+
+/** Write key→value updates to `.env.<env>`, creating it if absent. Returns the
+ *  fresh model. Confined to `<root>/.env.<env>` (fixed name, validated inside root). */
+export function writeEnvUpdates(
+  root: string,
+  env: EnvName,
+  updates: Record<string, string | null>,
+): EnvFileModel {
+  const abs = join(root, envFileName(env))
+  if (!resolve(abs).startsWith(resolve(root)))
+    throw new Error('refused: path escapes the domain root')
+  const prior = existsSync(abs) ? readFileSync(abs, 'utf8') : SCAFFOLD_HEADER(env)
+  writeFileSync(abs, applyUpdates(prior, updates), 'utf8')
+  return readEnvModel(root, env)
+}

package/studio/server/state/git.ts

@@ -0,0 +1,75 @@
+/**
+ * git.ts — best-effort git enrichment for change tracking. The fixtures are not
+ * git repos, so EVERY function here degrades gracefully and NEVER throws. The
+ * baseline (baseline.ts) is the primary tracker; git only enriches when present.
+ */
+import { execFileSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { dirname, relative, resolve } from 'node:path'
+
+import type { FileChange } from '../../shared/types'
+
+/** Walk parent dirs looking for a `.git` entry (dir or file, to support worktrees/submodules). */
+export function detectGit(root: string): { hasGit: boolean; gitRoot?: string } {
+  let dir = resolve(root)
+  while (true) {
+    if (existsSync(resolve(dir, '.git'))) return { hasGit: true, gitRoot: dir }
+    const parent = dirname(dir)
+    if (parent === dir) return { hasGit: false }
+    dir = parent
+  }
+}
+
+function git(gitRoot: string, args: string[]): string | null {
+  try {
+    return execFileSync('git', ['-C', gitRoot, ...args], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      maxBuffer: 64 * 1024 * 1024,
+    })
+  } catch {
+    return null
+  }
+}
+
+/** `git diff` scoped to the schema dir. Returns stdout (possibly '') or null when there is no git. */
+export function gitDiff(root: string, schemaDirName: string): string | null {
+  const { hasGit, gitRoot } = detectGit(root)
+  if (!hasGit || !gitRoot) return null
+  // Path to the schema dir relative to the git root (forward-slashed for git).
+  const rel = relative(gitRoot, resolve(root, schemaDirName)).split('\\').join('/')
+  const out = git(gitRoot, ['diff', '--', rel || '.'])
+  return out
+}
+
+/** XY porcelain code → our FileChange status. Returns null for codes we don't surface. */
+function mapStatus(xy: string): FileChange['status'] | null {
+  const x = xy[0] ?? ' '
+  const y = xy[1] ?? ' '
+  if (x === '?' || y === '?') return 'added' // untracked
+  if (x === 'A' || y === 'A') return 'added'
+  if (x === 'D' || y === 'D') return 'removed'
+  if (x === 'R' || y === 'R') return 'modified' // rename → surface destination as modified
+  if (x === 'M' || y === 'M' || x === 'C' || y === 'C' || x === 'U' || y === 'U') return 'modified'
+  return null
+}
+
+/** Parse `git status --porcelain` into FileChange[]. Empty array when there is no git. */
+export function gitStatus(root: string): FileChange[] {
+  const { hasGit, gitRoot } = detectGit(root)
+  if (!hasGit || !gitRoot) return []
+  const out = git(gitRoot, ['status', '--porcelain'])
+  if (out == null) return []
+  const changes: FileChange[] = []
+  for (const line of out.split('\n')) {
+    if (!line.trim()) continue
+    const xy = line.slice(0, 2)
+    let path = line.slice(3)
+    // Renames/copies render as "old -> new"; keep the destination path.
+    const arrow = path.indexOf(' -> ')
+    if (arrow !== -1) path = path.slice(arrow + 4)
+    const status = mapStatus(xy)
+    if (status) changes.push({ file: path, status })
+  }
+  return changes
+}

package/studio/server/state/handoff.ts

@@ -0,0 +1,55 @@
+/**
+ * handoff.ts — shared helpers that turn 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.
+ */
+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'
+
+/** 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)
+  return computeChanges(handle.root, bundle?.ir ?? null, files, {
+    schemaDirName: handle.schemaDirName,
+  })
+}
+
+/** 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 lines: string[] = []
+  for (const c of cs.schemaChanges)
+    lines.push(
+      `${c.breaking ? '! ' : '+ '}${c.kind} ${c.target}${c.detail ? ` (${c.detail})` : ''}`,
+    )
+  for (const f of cs.fileChanges) lines.push(`~ ${f.status} ${f.file}`)
+  return lines.join('\n')
+}
+
+/** Refresh the on-disk context/auto digests so an external agent can read them. */
+export async function refreshAuto(handle: DomainHandle): Promise<void> {
+  const cs = await changeSet(handle)
+  const store = readComments(handle.root)
+  const open = store.comments.filter((c) => c.status === 'open')
+  const commentsDigest = open
+    .map(
+      (c, i) =>
+        `${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')
+  materializeAuto(handle.root, {
+    changes: changeText(cs) || 'no tracked changes',
+    schemaChange: schemaSummary || 'no schema changes since baseline',
+    comments: commentsDigest || 'no open comments',
+  })
+}