amorphous-cli 0.1.13 → 0.3.0

package/lib/agent-guides-files.test.mjs

@@ -0,0 +1,367 @@
+import assert from 'node:assert/strict'
+import { execFileSync, spawnSync } from 'node:child_process'
+import { existsSync, mkdtempSync, mkdirSync, readFileSync, lstatSync, readdirSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, test } from 'node:test'
+import {
+  guidePaths,
+  ensureGuideFilesIgnored,
+  readGuideSyncState,
+  writeGuideSyncState,
+  materializeGuide,
+  activateGuideIdentity,
+  guideBodyHash,
+} from './agent-guides-files.mjs'
+
+const roots = []
+const idA = '00000000-0000-4000-8000-000000000001'
+const idB = '00000000-0000-4000-8000-000000000002'
+const userA = '10000000-0000-4000-8000-000000000001'
+const userB = '10000000-0000-4000-8000-000000000002'
+function root() {
+  const value = mkdtempSync(join(tmpdir(), 'am-guide-'))
+  roots.push(value)
+  return value
+}
+afterEach(() => { for (const value of roots.splice(0)) rmSync(value, { recursive: true, force: true }) })
+
+function initGit(workspace) {
+  execFileSync('git', ['init', '--quiet', workspace])
+  writeFileSync(join(workspace, '.git', 'info', 'exclude'), '# local excludes\n')
+}
+
+test('guide paths are fixed, separated, and sync state is bound to abstract and user', () => {
+  const workspace = root()
+  const paths = guidePaths(workspace, idA, userA)
+  assert.equal(paths.abstractGuide, join(paths.projectRoot, 'agent.md'))
+  assert.equal(paths.privateGuide, join(paths.projectRoot, 'private-agent.md'))
+  assert.notEqual(paths.syncState, guidePaths(workspace, idA, userB).syncState)
+  assert.notEqual(paths.syncState, guidePaths(workspace, idB, userA).syncState)
+  const hash = 'a'.repeat(64)
+  writeGuideSyncState(workspace, idA, userA, { abstract: { revision: 2, hash } })
+  assert.deepEqual(readGuideSyncState(workspace, idA, userA).guides.abstract, { revision: 2, hash })
+  assert.equal(readGuideSyncState(workspace, idA, userB), null)
+})
+
+test('guide ignore rules prefer Git info exclude and preserve user content', () => {
+  const workspace = root()
+  initGit(workspace)
+  const exclude = join(workspace, '.git', 'info', 'exclude')
+  ensureGuideFilesIgnored(workspace)
+  ensureGuideFilesIgnored(workspace)
+  const text = readFileSync(exclude, 'utf8')
+  assert.match(text, /# local excludes/)
+  assert.match(text, /\/agent\.md/)
+  assert.match(text, /\/private-agent\.md/)
+  assert.match(text, /\.amorphous-guides/)
+  assert.match(text, /\.amorphous-guide-\*\.tmp/)
+  assert.equal((text.match(/BEGIN amorphous agent guides/g) || []).length, 1)
+  assert.match(text, /\.amorphous-guides/)
+  assert.equal(existsSync(join(workspace, '.gitignore')), false)
+})
+
+test('Git exclude rules scope nested abstract guides to their actual workspace directory', () => {
+  const repo = root()
+  execFileSync('git', ['init', '--quiet', repo])
+  const workspace = join(repo, 'apps', 'my-abstract')
+  const secondWorkspace = join(repo, 'apps', 'second abstract')
+  const adjacent = join(repo, 'apps', 'other-abstract')
+  mkdirSync(workspace, { recursive: true })
+  mkdirSync(secondWorkspace, { recursive: true })
+  mkdirSync(adjacent, { recursive: true })
+  ensureGuideFilesIgnored(workspace)
+  ensureGuideFilesIgnored(secondWorkspace)
+
+  const exclude = readFileSync(join(repo, '.git', 'info', 'exclude'), 'utf8')
+  assert.match(exclude, /\/apps\/my-abstract\/agent\.md/)
+  assert.match(exclude, /\/apps\/my-abstract\/private-agent\.md/)
+  assert.match(exclude, /\/apps\/my-abstract\/\.amorphous-guides\//)
+  assert.match(exclude, /\/apps\/second\\ abstract\/private-agent\.md/)
+  const ignored = (path) => spawnSync('git', ['check-ignore', '--no-index', '--quiet', '--', path], { cwd: repo }).status === 0
+  assert.equal(ignored('apps/my-abstract/agent.md'), true)
+  assert.equal(ignored('apps/my-abstract/private-agent.md'), true)
+  assert.equal(ignored('apps/second abstract/private-agent.md'), true)
+  assert.equal(ignored('apps/other-abstract/private-agent.md'), false)
+  assert.equal(ignored('agent.md'), false)
+})
+
+test('worktree gitdir pointers keep the workspace-local ignore fallback', () => {
+  const base = root()
+  const workspace = join(base, 'worktree')
+  const gitDir = join(base, 'git-data')
+  mkdirSync(workspace)
+  mkdirSync(join(gitDir, 'info'), { recursive: true })
+  writeFileSync(join(gitDir, 'info', 'exclude'), 'external rules\n')
+  writeFileSync(join(workspace, '.git'), 'gitdir: ../git-data\n')
+
+  ensureGuideFilesIgnored(workspace)
+  assert.match(readFileSync(join(workspace, '.gitignore'), 'utf8'), /\/private-agent\.md/)
+  assert.equal(readFileSync(join(gitDir, 'info', 'exclude'), 'utf8'), 'external rules\n')
+})
+
+test('private guide refuses an effective ignore negation without writing private bytes', () => {
+  const workspace = root()
+  initGit(workspace)
+  writeFileSync(join(workspace, '.gitignore'), '!private-agent.md\n')
+  assert.throws(() => materializeGuide({ projectRoot: workspace, abstractId: idA, userId: userA,
+    kind: 'private', body: 'private text must not land here', revision: 1 }), /ignored|tracked|refusing/i)
+  assert.equal(existsSync(join(workspace, 'private-agent.md')), false)
+  assert.equal(existsSync(join(workspace, '.amorphous-guides')), false)
+})
+
+test('private guide refuses an already tracked active path without changing it', () => {
+  const workspace = root()
+  initGit(workspace)
+  writeFileSync(join(workspace, 'private-agent.md'), 'tracked user content')
+  execFileSync('git', ['add', '--', 'private-agent.md'], { cwd: workspace })
+  assert.throws(() => materializeGuide({ projectRoot: workspace, abstractId: idA, userId: userA,
+    kind: 'private', body: 'private text must not overwrite tracked content', revision: 1 }), /ignored|tracked|refusing/i)
+  assert.equal(readFileSync(join(workspace, 'private-agent.md'), 'utf8'), 'tracked user content')
+  assert.equal(existsSync(join(workspace, '.amorphous-guides')), false)
+})
+
+test('abstract guide refuses an already tracked control-plane path without changing it', () => {
+  const workspace = root()
+  initGit(workspace)
+  writeFileSync(join(workspace, 'agent.md'), 'tracked project instructions')
+  execFileSync('git', ['add', '--', 'agent.md'], { cwd: workspace })
+  assert.throws(() => materializeGuide({ projectRoot: workspace, abstractId: idA, userId: userA,
+    kind: 'abstract', body: 'remote guide must not overwrite tracked source', revision: 1 }), /tracked|refusing/i)
+  assert.equal(readFileSync(join(workspace, 'agent.md'), 'utf8'), 'tracked project instructions')
+  assert.equal(existsSync(join(workspace, '.amorphous-guides')), false)
+})
+
+test('guide ignore rules use a managed .gitignore block outside Git', () => {
+  const workspace = root()
+  writeFileSync(join(workspace, '.gitignore'), 'user-file\n')
+  ensureGuideFilesIgnored(workspace)
+  ensureGuideFilesIgnored(workspace)
+  const text = readFileSync(join(workspace, '.gitignore'), 'utf8')
+  assert.match(text, /^user-file\n/)
+  assert.match(text, /\/private-agent\.md/)
+  assert.equal((text.match(/BEGIN amorphous agent guides/g) || []).length, 1)
+})
+
+test('atomic materialization uses restrictive permissions and does not rewrite unchanged bytes', () => {
+  const workspace = root()
+  initGit(workspace)
+  ensureGuideFilesIgnored(workspace)
+  const first = materializeGuide({ projectRoot: workspace, abstractId: idA, userId: userA,
+    kind: 'abstract', body: 'shared guide', revision: 1 })
+  assert.equal(first.status, 'written')
+  const mode = lstatSync(join(workspace, 'agent.md')).mode & 0o777
+  assert.equal(mode, 0o600)
+  const mtime = lstatSync(join(workspace, 'agent.md')).mtimeMs
+  const same = materializeGuide({ projectRoot: workspace, abstractId: idA, userId: userA,
+    kind: 'abstract', body: 'shared guide', revision: 1 })
+  assert.equal(same.status, 'unchanged')
+  assert.equal(lstatSync(join(workspace, 'agent.md')).mtimeMs, mtime)
+  assert.deepEqual(readdirSync(workspace).filter(name => name.includes('.tmp')), [])
+})
+
+test('local edits and remote changes create ignored conflict copies without overwriting either', () => {
+  const workspace = root()
+  ensureGuideFilesIgnored(workspace)
+  materializeGuide({ projectRoot: workspace, abstractId: idA, userId: userA,
+    kind: 'abstract', body: 'base', revision: 1 })
+  writeFileSync(join(workspace, 'agent.md'), 'local edit')
+  const result = materializeGuide({ projectRoot: workspace, abstractId: idA, userId: userA,
+    kind: 'abstract', body: 'remote edit', revision: 2 })
+  assert.equal(result.status, 'conflict')
+  assert.equal(readFileSync(join(workspace, 'agent.md'), 'utf8'), 'local edit')
+  assert.equal(readFileSync(result.conflictPath, 'utf8'), 'remote edit')
+  assert.match(readFileSync(join(workspace, '.gitignore'), 'utf8'), /\.amorphous-guides/)
+})
+
+test('local-only edits are retained when the remote body still matches the saved base', () => {
+  const workspace = root()
+  ensureGuideFilesIgnored(workspace)
+  materializeGuide({ projectRoot: workspace, abstractId: idA, userId: userA,
+    kind: 'abstract', body: 'base', revision: 1 })
+  writeFileSync(join(workspace, 'agent.md'), 'local-only edit')
+  const result = materializeGuide({ projectRoot: workspace, abstractId: idA, userId: userA,
+    kind: 'abstract', body: 'base', revision: 2 })
+  assert.equal(result.status, 'local-only')
+  assert.equal(readFileSync(join(workspace, 'agent.md'), 'utf8'), 'local-only edit')
+  assert.deepEqual(readGuideSyncState(workspace, idA, userA).guides.abstract,
+    { revision: 2, hash: guideBodyHash('base') })
+  assert.equal(result.conflictPath, undefined)
+})
+
+test('identity switch moves prior private bytes to that identity recovery path and removes active file', () => {
+  const workspace = root()
+  ensureGuideFilesIgnored(workspace)
+  materializeGuide({ projectRoot: workspace, abstractId: idA, userId: userA,
+    kind: 'private', body: 'A private bytes', revision: 1 })
+  const result = activateGuideIdentity(workspace, idA, userB)
+  assert.equal(result.status, 'switched')
+  assert.equal(result.recovered.length, 1)
+  assert.match(result.recovered[0], new RegExp(`${idA}/${userA}/`))
+  assert.equal(readFileSync(result.recovered[0], 'utf8'), 'A private bytes')
+  assert.throws(() => lstatSync(join(workspace, 'private-agent.md')), { code: 'ENOENT' })
+})
+
+test('identity switch refuses recovery paths exposed by Git ignore negations', () => {
+  const workspace = root()
+  initGit(workspace)
+  materializeGuide({ projectRoot: workspace, abstractId: idA, userId: userA,
+    kind: 'private', body: 'private bytes must stay ignored', revision: 1 })
+  writeFileSync(join(workspace, '.gitignore'), [
+    '!.amorphous-guides/',
+    '.amorphous-guides/private-check',
+    '!.amorphous-guides/recovery/',
+    '!.amorphous-guides/recovery/**',
+    '',
+  ].join('\n'), { flag: 'a' })
+
+  assert.equal(spawnSync('git', ['check-ignore', '--quiet', '--', '.amorphous-guides/private-check'], { cwd: workspace }).status, 0)
+  assert.equal(spawnSync('git', ['check-ignore', '--quiet', '--', '.amorphous-guides/recovery/probe/private-agent.md'], { cwd: workspace }).status, 1)
+  assert.throws(() => activateGuideIdentity(workspace, idA, userB), /ignored|tracked|refusing/i)
+  assert.equal(readFileSync(join(workspace, 'private-agent.md'), 'utf8'), 'private bytes must stay ignored')
+  const recoveryRoot = join(workspace, '.amorphous-guides', 'recovery')
+  assert.deepEqual(existsSync(recoveryRoot)
+    ? readdirSync(recoveryRoot, { recursive: true }).filter((name) => name.endsWith('private-agent.md'))
+    : [], [])
+  const add = spawnSync('git', ['add', '-A', '--dry-run', '--ignore-errors'], { cwd: workspace, encoding: 'utf8' })
+  assert.equal(add.status, 0)
+  assert.doesNotMatch(add.stdout, /\.amorphous-guides\/recovery\/.*private-agent\.md/)
+})
+
+test('non-Git fallback refuses exposed internal recovery destinations', () => {
+  const workspace = root()
+  materializeGuide({ projectRoot: workspace, abstractId: idA, userId: userA,
+    kind: 'private', body: 'private fallback bytes', revision: 1 })
+  writeFileSync(join(workspace, '.gitignore'), [
+    '!.amorphous-guides/',
+    '.amorphous-guides/private-check',
+    '!.amorphous-guides/recovery/',
+    '!.amorphous-guides/recovery/**',
+    '',
+  ].join('\n'), { flag: 'a' })
+  assert.throws(() => activateGuideIdentity(workspace, idA, userB), /ignored|tracked|refusing/i)
+  assert.equal(readFileSync(join(workspace, 'private-agent.md'), 'utf8'), 'private fallback bytes')
+  const recoveryRoot = join(workspace, '.amorphous-guides', 'recovery')
+  assert.deepEqual(existsSync(recoveryRoot)
+    ? readdirSync(recoveryRoot, { recursive: true }).filter((name) => name.endsWith('private-agent.md'))
+    : [], [])
+})
+
+test('non-Git fallback evaluates nested ignore files before identity recovery', () => {
+  const workspace = root()
+  materializeGuide({ projectRoot: workspace, abstractId: idA, userId: userA,
+    kind: 'private', body: 'nested-ignore private bytes', revision: 1 })
+  writeFileSync(join(workspace, '.gitignore'), [
+    '!.amorphous-guides/',
+    '.amorphous-guides/*',
+    '!.amorphous-guides/.gitignore',
+    '',
+  ].join('\n'), { flag: 'a' })
+  writeFileSync(join(workspace, '.amorphous-guides', '.gitignore'), [
+    '!recovery/',
+    '!recovery/**',
+    '',
+  ].join('\n'))
+
+  assert.throws(() => activateGuideIdentity(workspace, idA, userB), /ignored|tracked|refusing/i)
+  assert.equal(readFileSync(join(workspace, 'private-agent.md'), 'utf8'), 'nested-ignore private bytes')
+  const recoveryRoot = join(workspace, '.amorphous-guides', 'recovery')
+  assert.deepEqual(existsSync(recoveryRoot)
+    ? readdirSync(recoveryRoot, { recursive: true }).filter((name) => name.endsWith('private-agent.md'))
+    : [], [])
+
+  execFileSync('git', ['init', '--quiet', workspace])
+  assert.equal(spawnSync('git', ['check-ignore', '--quiet', '--', '.amorphous-guides/recovery/probe/private-agent.md'], { cwd: workspace }).status, 1)
+  execFileSync('git', ['add', '-A', '--ignore-errors'], { cwd: workspace })
+  const staged = execFileSync('git', ['diff', '--cached', '--name-only'], { cwd: workspace, encoding: 'utf8' })
+  assert.doesNotMatch(staged, /recovery\/.*private-agent\.md/)
+  assert.doesNotMatch(staged, /private-agent\.md/)
+})
+
+test('same-identity activation rejects active guide symlinks without reading or removing them', () => {
+  const workspace = root()
+  ensureGuideFilesIgnored(workspace)
+  materializeGuide({ projectRoot: workspace, abstractId: idA, userId: userA,
+    kind: 'abstract', body: 'authorized abstract guide', revision: 1 })
+  const outside = join(root(), 'private-target.md')
+  writeFileSync(outside, 'must not be read or changed')
+  symlinkSync(outside, join(workspace, 'private-agent.md'))
+  assert.throws(() => activateGuideIdentity(workspace, idA, userA), /symlink/i)
+  assert.equal(lstatSync(join(workspace, 'private-agent.md')).isSymbolicLink(), true)
+  assert.equal(readFileSync(outside, 'utf8'), 'must not be read or changed')
+})
+
+test('materialization rejects guides above 32 KiB by UTF-8 byte count before writing', () => {
+  const workspace = root()
+  const oversizedUnicode = 'é'.repeat(16_385)
+  assert.ok(oversizedUnicode.length < 32 * 1024)
+  assert.ok(Buffer.byteLength(oversizedUnicode, 'utf8') > 32 * 1024)
+  assert.throws(() => materializeGuide({ projectRoot: workspace, abstractId: idA, userId: userA,
+    kind: 'private', body: oversizedUnicode, revision: 1 }), /32 KiB/i)
+  assert.equal(existsSync(join(workspace, 'private-agent.md')), false)
+  assert.equal(existsSync(join(workspace, '.amorphous-guides')), false)
+})
+
+test('malformed identity state fails closed and preserves private bytes only in recovery', () => {
+  const workspace = root()
+  ensureGuideFilesIgnored(workspace)
+  writeFileSync(join(workspace, 'private-agent.md'), 'possibly private')
+  mkdirSync(join(workspace, '.amorphous-guides'), { recursive: true })
+  writeFileSync(join(workspace, '.amorphous-guides', 'active.json'), '{bad')
+  const result = activateGuideIdentity(workspace, idA, userA)
+  assert.equal(result.status, 'recovered-unknown-identity')
+  assert.equal(result.privateSafeToLoad, false)
+  assert.equal(readFileSync(result.recovered[0], 'utf8'), 'possibly private')
+  assert.throws(() => lstatSync(join(workspace, 'private-agent.md')), { code: 'ENOENT' })
+})
+
+test('symlinked project roots, guide targets, and state parents are rejected', () => {
+  const base = root()
+  const real = join(base, 'real')
+  mkdirSync(real)
+  const rootLink = join(base, 'root-link')
+  symlinkSync(real, rootLink)
+  assert.throws(() => guidePaths(rootLink, idA, userA), /symlink|project root/i)
+
+  const targetWorkspace = root()
+  ensureGuideFilesIgnored(targetWorkspace)
+  const outside = join(base, 'outside.md')
+  writeFileSync(outside, 'outside')
+  symlinkSync(outside, join(targetWorkspace, 'agent.md'))
+  assert.throws(() => materializeGuide({ projectRoot: targetWorkspace, abstractId: idA, userId: userA,
+    kind: 'abstract', body: 'new', revision: 1 }), /symlink/i)
+  assert.equal(readFileSync(outside, 'utf8'), 'outside')
+})
+
+test('malformed state metadata is rejected and bytes are not trusted', () => {
+  const workspace = root()
+  const paths = guidePaths(workspace, idA, userA)
+  mkdirSync(join(workspace, '.amorphous-guides', 'state', idA, userA), { recursive: true })
+  writeFileSync(paths.syncState, '{bad')
+  assert.throws(() => readGuideSyncState(workspace, idA, userA), /state/i)
+  writeFileSync(paths.syncState, JSON.stringify({ schemaVersion: 1, abstractId: idA, userId: userA,
+    guides: { private: { revision: 1, hash: 'a'.repeat(64), body: 'must not be metadata' } } }))
+  assert.throws(() => readGuideSyncState(workspace, idA, userA), /metadata/i)
+})
+
+test('symlinked state parent components are rejected before metadata reads', () => {
+  const base = root()
+  const workspace = join(base, 'workspace')
+  const external = join(base, 'external')
+  mkdirSync(workspace)
+  mkdirSync(join(external, 'state', idA, userA), { recursive: true })
+  mkdirSync(join(workspace, '.amorphous-guides'))
+  symlinkSync(join(external, 'state'), join(workspace, '.amorphous-guides', 'state'))
+  assert.throws(() => readGuideSyncState(workspace, idA, userA), /symlink/i)
+})
+
+test('symlinked ignore targets are rejected without changing their destination', () => {
+  const base = root()
+  const workspace = join(base, 'workspace')
+  const external = join(base, 'external-ignore')
+  mkdirSync(workspace)
+  writeFileSync(external, 'outside rules\n')
+  symlinkSync(external, join(workspace, '.gitignore'))
+  assert.throws(() => ensureGuideFilesIgnored(workspace), /symlink/i)
+  assert.equal(readFileSync(external, 'utf8'), 'outside rules\n')
+})

package/lib/api.mjs

@@ -35,17 +35,22 @@ export function friendlyMessage(raw) {
 }
 
 export async function apiFetch(path, opts = {}) {
+  const { accessToken, ...fetchOptions } = opts
   const url = `${cliAppFetchOrigin()}${path}`
-  const headers = { ...cliAppHostHeader(), ...(opts.headers || {}) }
-  if (opts.auth !== false) {
-    const session = await ensureFreshSession(opts.forceRefresh ? { force: true } : {})
-    headers.Authorization = `Bearer ${session.access_token}`
+  const headers = { ...cliAppHostHeader(), ...(fetchOptions.headers || {}) }
+  if (fetchOptions.auth !== false) {
+    if (accessToken) {
+      headers.Authorization = `Bearer ${accessToken}`
+    } else {
+      const session = await ensureFreshSession(fetchOptions.forceRefresh ? { force: true } : {})
+      headers.Authorization = `Bearer ${session.access_token}`
+    }
   }
-  if (opts.body && !headers['Content-Type']) {
+  if (fetchOptions.body && !headers['Content-Type']) {
     headers['Content-Type'] = 'application/json'
   }
   const res = await fetch(url, {
-    ...opts,
+    ...fetchOptions,
     headers,
   })
   const text = await res.text()
@@ -55,7 +60,7 @@ export async function apiFetch(path, opts = {}) {
   } catch {
     data = text
   }
-  if (res.status === 401 && opts.auth !== false && !opts.retried) {
+  if (res.status === 401 && fetchOptions.auth !== false && !accessToken && !fetchOptions.retried) {
     return apiFetch(path, { ...opts, retried: true, forceRefresh: true })
   }
   if (!res.ok) {

package/lib/app-origins.mjs

@@ -0,0 +1,52 @@
+import { getDomain, getPublicSuffix } from 'tldts'
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+/** URL construction mirrors shared/app-origins.ts; hosted bases come from the platform. */
+export function hostedAppUrls(id, platformOrigin, env = process.env) {
+  if (!UUID.test(id)) throw new Error('Invalid app ID')
+  const platform = new URL(platformOrigin)
+  if (platform.username || platform.password || platform.pathname !== '/' || platform.search || platform.hash ||
+    !['http:', 'https:'].includes(platform.protocol)) throw new Error('Invalid platform origin')
+  const local = platform.hostname.endsWith('.localhost') || platform.hostname.endsWith('.test')
+  const runtimeBase = env.RUNTIME_BASE_DOMAIN || (local ? 'apps.localhost' : '')
+  const previewBase = env.PREVIEW_BASE_DOMAIN || (local ? 'preview.localhost' : '')
+  if (!runtimeBase || !previewBase || runtimeBase === previewBase) {
+    throw new Error('Runtime and preview base domains are not configured')
+  }
+  const validBase = (base) => base.includes('.') && base.split('.').every((label) => /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(label)) &&
+    getDomain(base, { allowPrivateDomains: true }) && base !== getPublicSuffix(base, { allowPrivateDomains: true })
+  if (!validBase(runtimeBase) || !validBase(previewBase) || runtimeBase.endsWith(`.${previewBase}`) || previewBase.endsWith(`.${runtimeBase}`)) {
+    throw new Error('Invalid runtime base domains')
+  }
+  const scheme = env.RUNTIME_SCHEME || (local ? 'http' : 'https')
+  const port = env.RUNTIME_PORT ?? (local ? platform.port : '')
+  if (!['http', 'https'].includes(scheme) || (port !== '' && (!/^\d+$/.test(port) || Number(port) < 1 || Number(port) > 65535))) {
+    throw new Error('Invalid runtime origin configuration')
+  }
+  if (!local && (scheme !== 'https' || port ||
+    getDomain(runtimeBase, { allowPrivateDomains: true }) === getDomain(platform.hostname, { allowPrivateDomains: true }) ||
+    getDomain(previewBase, { allowPrivateDomains: true }) === getDomain(platform.hostname, { allowPrivateDomains: true }))) {
+    throw new Error('Production runtime origins must be HTTPS and separate from the platform domain')
+  }
+  const suffix = port ? `:${port}` : ''
+  return {
+    open: `${platform.origin}/a/${id}`,
+    preview: `${scheme}://${id}.${previewBase}${suffix}/${id}/draft`,
+    live: `${scheme}://${id}.${runtimeBase}${suffix}/${id}`,
+  }
+}
+
+export function urlsFromDiscovery(id, platformOrigin, discovery, overrides = {}) {
+  if (!discovery || typeof discovery !== 'object' ||
+    discovery.appOrigin !== new URL(platformOrigin).origin) {
+    throw new Error('Runtime origin discovery did not match the configured platform')
+  }
+  return hostedAppUrls(id, platformOrigin, {
+    RUNTIME_BASE_DOMAIN: overrides.RUNTIME_BASE_DOMAIN || discovery.runtimeBase,
+    PREVIEW_BASE_DOMAIN: overrides.PREVIEW_BASE_DOMAIN || discovery.previewBase,
+    RUNTIME_SCHEME: overrides.RUNTIME_SCHEME || discovery.runtimeScheme,
+    RUNTIME_PORT: overrides.RUNTIME_PORT ?? discovery.runtimePort,
+  })
+}
+

package/lib/app-origins.test.mjs

@@ -0,0 +1,40 @@
+import { test } from 'node:test'
+import { strict as assert } from 'node:assert'
+import { hostedAppUrls, urlsFromDiscovery } from './app-origins.mjs'
+
+const id = '11111111-1111-4111-8111-111111111111'
+
+test('CLI URLs use per-app production and preview hosts', () => {
+  assert.deepEqual(hostedAppUrls(id, 'http://amorphous.localhost:3849', {}), {
+    open: `http://amorphous.localhost:3849/a/${id}`,
+    preview: `http://${id}.preview.localhost:3849/${id}/draft`,
+    live: `http://${id}.apps.localhost:3849/${id}`,
+  })
+})
+
+test('CLI production URLs require configured isolated domains', () => {
+  assert.throws(() => hostedAppUrls(id, 'https://platform.example.org', {}), /not configured/)
+})
+
+test('hosted CLI derives URLs from validated server discovery without local configuration', () => {
+  assert.deepEqual(urlsFromDiscovery(id, 'https://platform.example.org', {
+    appOrigin: 'https://platform.example.org', runtimeBase: 'apps.example.net',
+    previewBase: 'preview.example.net', runtimeScheme: 'https', runtimePort: '',
+  }), {
+    open: `https://platform.example.org/a/${id}`,
+    preview: `https://${id}.preview.example.net/${id}/draft`,
+    live: `https://${id}.apps.example.net/${id}`,
+  })
+  assert.throws(() => urlsFromDiscovery(id, 'https://platform.example.org', {
+    appOrigin: 'https://other.example.org', runtimeBase: 'apps.example.net',
+    previewBase: 'preview.example.net', runtimeScheme: 'https', runtimePort: '',
+  }), /did not match/)
+  assert.throws(() => urlsFromDiscovery(id, 'https://platform.example.org', {
+    appOrigin: 'https://platform.example.org/path', runtimeBase: 'apps.example.net',
+    previewBase: 'preview.example.net', runtimeScheme: 'https', runtimePort: '',
+  }), /did not match/)
+  assert.throws(() => urlsFromDiscovery(id, 'https://platform.example.org', {
+    appOrigin: 'https://platform.example.org', runtimeBase: 'apps.platform.example.org',
+    previewBase: 'preview.example.net', runtimeScheme: 'https', runtimePort: '',
+  }), /separate/)
+})