amorphous-cli 0.1.12 → 0.2.0

package/README.md

@@ -5,3 +5,5 @@ Make whatever you want, yourself, with your own agent, or with others. And whate
 ```bash
 npx amorphous-cli@latest setup
 ```
+
+Create a purpose-built starter with `amorphous-cli create --template list|board|landing` (or omit the flag for a blank page). Collaborators can run `amorphous-cli recommend --note "…"` to send local source to the owner for review. The owner can publish a recommendation live or decline it in the abstract.

package/lib/agent-contract.mjs

@@ -53,12 +53,16 @@ export function syncProjectContract(cwd) {
   return 'refreshed'
 }
 
-export function writeStarter(cwd) {
+export function writeStarter(cwd, template = 'blank') {
   const assets = join(skillRoot, 'assets')
+  const templates = JSON.parse(readFileSync(join(dirname(skillRoot), '../templates.json'), 'utf8'))
+  const selected = templates[template]
+  if (!selected) throw new Error(`Unknown template “${template}”. Choose blank, list, board, or landing.`)
+  const starterFiles = { 'index.html': selected.html, 'styles.css': selected.css, 'app.js': selected.js }
   for (const name of ['index.html', 'styles.css', 'app.js']) {
     const dest = join(cwd, name)
     if (!existsSync(dest)) {
-      writeFileSync(dest, readFileSync(join(assets, name)))
+      writeFileSync(dest, starterFiles[name] ?? readFileSync(join(assets, name)))
     }
   }
   for (const name of ['data.ndjson', 'private.ndjson']) {

package/lib/agent-contract.test.mjs

@@ -31,7 +31,18 @@ test('setup copies the skill, and an edited contract is left alone', () => {
   const project = mkdtempSync(join(tmpdir(), 'amorphous-page-'))
   assert.equal(syncProjectContract(project), 'wrote')
   writeStarter(project)
-  assert.match(readFileSync(join(project, 'index.html'), 'utf8'), /id="who"/)
+  assert.match(readFileSync(join(project, 'index.html'), 'utf8'), /Make this abstract your own/)
+  assert.equal(readFileSync(join(project, 'styles.css'), 'utf8').length > 0, true)
+  const board = mkdtempSync(join(tmpdir(), 'amorphous-board-'))
+  writeStarter(board, 'board')
+  assert.match(readFileSync(join(board, 'index.html'), 'utf8'), /Project board/)
+  assert.match(readFileSync(join(board, 'app.js'), 'utf8'), /board-card/)
+  for (const [template, expected] of [['list', 'SHARED LIST'], ['landing', 'A CLEAR, HUMAN INTRODUCTION']]) {
+    const dir = mkdtempSync(join(tmpdir(), `amorphous-${template}-`))
+    writeStarter(dir, template)
+    assert.match(readFileSync(join(dir, 'index.html'), 'utf8'), new RegExp(expected))
+  }
+  assert.throws(() => writeStarter(project, 'unknown'), /Unknown template/)
   assert.match(readFileSync(join(project, 'AGENTS.md'), 'utf8'), new RegExp(`amorphous-contract: ${CONTRACT_VERSION}`))
 
   const edited = readFileSync(join(project, 'AGENTS.md'), 'utf8') + '\nEdited.\n'

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/)
+})

package/lib/commands.mjs

@@ -1,11 +1,13 @@
-import { readFileSync, writeFileSync, existsSync } from 'node:fs'
+import { readFileSync, writeFileSync, existsSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
 import { installUserSkill, syncProjectContract, writeStarter } from './agent-contract.mjs'
 import { ensureSessionHooks } from './agent-hooks.mjs'
 import { shouldRefreshSkill } from './update-check.mjs'
 import { CLI_VERSION } from './version.mjs'
 import { homedir } from 'node:os'
 import { apiFetch } from './api.mjs'
-import { abstractsOrigin, appOrigin, projectMetaPath } from './config.mjs'
+import { appOrigin, projectMetaPath } from './config.mjs'
+import { urlsFromDiscovery } from './app-origins.mjs'
 import { recordsFromLocal, readProjectFiles, writeProjectFiles } from './files.mjs'
 import { startServe } from './serve.mjs'
 import { ALIASES, printHelp, wantsHelp } from './help.mjs'
@@ -80,6 +82,18 @@ function writeMeta(cwd, abstractId) {
   writeFileSync(projectMetaPath(cwd), JSON.stringify({ abstractId }, null, 2) + '\n')
 }
 
+export function writeRecipeFiles(cwd, source) {
+  const files = [['index.html', source?.html], ['styles.css', source?.css], ['app.js', source?.js]]
+  if (files.some(([, content]) => typeof content !== 'string')) throw new Error('Recipe response did not include source files.')
+  const paths = files.map(([name]) => join(cwd, name))
+  if ([...paths, join(cwd, 'data.ndjson'), join(cwd, 'private.ndjson')].some(existsSync)) {
+    throw new Error('Recipe creation needs an empty source folder so it can write the generated files safely.')
+  }
+  for (let index = 0; index < files.length; index++) writeFileSync(paths[index], files[index][1])
+  writeFileSync(join(cwd, 'data.ndjson'), '')
+  writeFileSync(join(cwd, 'private.ndjson'), '')
+}
+
 function requireMeta(cwd) {
   const meta = readMeta(cwd)
   if (!meta?.abstractId) {
@@ -215,7 +229,37 @@ They tell you when to push, preview, publish, or invite.`)
 async function cmdCreate(cwd, rest) {
   const { flags } = parseFlags(rest)
   if (flags.help) return printHelp('create')
-  const data = await apiFetch('/api/abstracts', { method: 'POST' })
+  if (flags['recipe-config'] === true) throw new Error('Pass a JSON file with --recipe-config <file>.')
+  if (typeof flags['recipe-config'] === 'string') {
+    const recipePath = flags['recipe-config'].startsWith('/') ? flags['recipe-config'] : join(cwd, flags['recipe-config'])
+    let config
+    try { config = JSON.parse(readFileSync(recipePath, 'utf8')) } catch { throw new Error('Could not read recipe config JSON.') }
+    if (!config || typeof config !== 'object' || Array.isArray(config)) throw new Error('Recipe config must be a JSON object.')
+    if (typeof flags.name === 'string' && flags.name.trim()) config.name = flags.name.trim()
+    const sourceTargets = ['index.html', 'styles.css', 'app.js', 'data.ndjson', 'private.ndjson', '.amorphous.json']
+    if (sourceTargets.some(name => existsSync(join(cwd, name)))) {
+      throw new Error('Recipe creation needs an empty project folder.')
+    }
+    const data = await apiFetch('/api/abstracts/recipe', { method: 'POST', body: JSON.stringify(config) })
+    writeRecipeFiles(cwd, data.source)
+    writeMeta(cwd, data.id)
+    if (data.recoveryContract) {
+      writeFileSync(projectMetaPath(cwd), JSON.stringify({ abstractId: data.id, recoveryContract: data.recoveryContract }, null, 2) + '\n')
+    }
+    const folderName = folderToken(flags)
+    if (folderName) {
+      const folder = await resolveFolder(folderName)
+      await apiFetch(`/api/abstracts/${data.id}/filing`, {
+        method: 'PATCH', body: JSON.stringify({ collection_id: folder.id }),
+      })
+    }
+    syncProjectContract(cwd)
+    if (jsonMode(flags)) printJson({ id: data.id, name: data.name })
+    else { console.log(data.id); console.log('Prefer amorphous-cli serve while you edit.') }
+    return
+  }
+  const template = typeof flags.template === 'string' ? flags.template : 'blank'
+  const data = await apiFetch('/api/abstracts', { method: 'POST', body: JSON.stringify({ template }) })
   const id = data.id
   writeMeta(cwd, id)
   const name = typeof flags.name === 'string' ? flags.name.trim() : ''
@@ -233,7 +277,7 @@ async function cmdCreate(cwd, rest) {
       body: JSON.stringify({ collection_id: folder.id }),
     })
   }
-  writeStarter(cwd)
+  writeStarter(cwd, template)
   syncProjectContract(cwd)
   if (jsonMode(flags)) printJson({ id, name: name || 'Untitled' })
   else {
@@ -340,24 +384,38 @@ async function cmdPeople(cwd, rest) {
   }
 }
 
+export function writePulledProject(cwd, id, detail, records, { fresh = false } = {}) {
+  if (fresh && readdirSync(cwd).length) {
+    throw new Error('Pulling into a new folder needs an empty directory.')
+  }
+  const abstract = detail?.abstract
+  if (!abstract || typeof abstract.draft_html !== 'string' || typeof abstract.draft_css !== 'string' || typeof abstract.draft_js !== 'string') {
+    throw new Error('Abstract response did not include editable source files.')
+  }
+  const rows = records?.records || []
+  writeProjectFiles(cwd, {
+    html: abstract.draft_html,
+    css: abstract.draft_css,
+    js: abstract.draft_js,
+    shared: rows.filter((r) => r.visibility !== 'private'),
+    private: rows.filter((r) => r.visibility === 'private'),
+  })
+  const recoveryContract = abstract.draft_recovery_contract
+  writeFileSync(projectMetaPath(cwd), JSON.stringify({
+    abstractId: id,
+    ...(recoveryContract && typeof recoveryContract === 'object' ? { recoveryContract } : {}),
+  }, null, 2) + '\n')
+  syncProjectContract(cwd)
+}
+
 async function cmdPull(cwd, rest) {
-  const { flags } = parseFlags(rest)
+  const { flags, positional } = parseFlags(rest)
   if (flags.help) return printHelp('pull')
-  const id = requireMeta(cwd)
+  const id = await resolveAbstractId(cwd, flags, positional)
   const detail = await apiFetch(`/api/abstracts/${id}`)
   warnIfRemoteChanged(detail)
   const records = await apiFetch(`/api/abstracts/${id}/records`)
-  const rows = records.records || []
-  const shared = rows.filter((r) => r.visibility !== 'private')
-  const priv = rows.filter((r) => r.visibility === 'private')
-  writeProjectFiles(cwd, {
-    html: detail.abstract.draft_html,
-    css: detail.abstract.draft_css,
-    js: detail.abstract.draft_js,
-    shared,
-    private: priv,
-  })
-  syncProjectContract(cwd)
+  writePulledProject(cwd, id, detail, records, { fresh: positional.length > 0 || Boolean(flags.abstract) })
   console.log('Pulled.')
   console.log('Prefer amorphous-cli serve while you edit.')
 }
@@ -366,7 +424,8 @@ async function cmdPush(cwd, rest) {
   const { flags } = parseFlags(rest)
   if (flags.help) return printHelp('push')
   const id = requireMeta(cwd)
-  warnIfRemoteChanged(await apiFetch(`/api/abstracts/${id}`))
+  const detail = await apiFetch(`/api/abstracts/${id}`)
+  warnIfRemoteChanged(detail)
   if (flags.data) {
     const localRecords = recordsFromLocal(cwd)
     const { refused } = await apiFetch(`/api/abstracts/${id}/records`, {
@@ -380,7 +439,8 @@ async function cmdPush(cwd, rest) {
   const { html, css, js } = readProjectFiles(cwd)
   await apiFetch(`/api/abstracts/${id}/push`, {
     method: 'POST',
-    body: JSON.stringify({ html, css, js }),
+    body: JSON.stringify({ html, css, js, expectedRevision: detail.abstract.draft_revision,
+      ...(readMeta(cwd)?.recoveryContract ? { recoveryContract: readMeta(cwd).recoveryContract } : {}) }),
   })
   console.log(flags.data ? 'Pushed source and records.' : 'Pushed source.')
 }
@@ -397,6 +457,7 @@ async function cmdServe(cwd, rest) {
     cwd,
     abstractId: id,
     port,
+    environment: flags.preview ? 'preview' : 'production',
     json: jsonMode(flags),
   })
   let warnedRemote = false
@@ -427,19 +488,16 @@ async function cmdServe(cwd, rest) {
   })
 }
 
-function urlsFor(id) {
-  return {
-    open: `${appOrigin().replace(/\/$/, '')}/a/${id}`,
-    preview: `${abstractsOrigin().replace(/\/$/, '')}/${id}/draft`,
-    live: `${abstractsOrigin().replace(/\/$/, '')}/${id}`,
-  }
+async function urlsFor(id) {
+  const discovery = await apiFetch('/api/runtime/origins', { auth: false })
+  return urlsFromDiscovery(id, appOrigin(), discovery, process.env)
 }
 
 async function cmdOpen(cwd, rest) {
   const { flags, positional } = parseFlags(rest)
   if (flags.help) return printHelp('open')
   const id = await resolveAbstractId(cwd, flags, positional)
-  const urls = urlsFor(id)
+  const urls = await urlsFor(id)
   if (jsonMode(flags)) printJson(urls)
   else console.log(urls.open)
 }
@@ -450,7 +508,7 @@ async function cmdPreview(cwd, rest) {
   const id = await resolveAbstractId(cwd, flags, positional)
   const detail = await apiFetch(`/api/abstracts/${id}`)
   warnIfRemoteChanged(detail)
-  const urls = urlsFor(id)
+  const urls = await urlsFor(id)
   if (jsonMode(flags)) printJson({ preview: urls.preview, remoteChangedSincePush: Boolean(detail.remoteChangedSincePush) })
   else console.log(urls.preview)
 }
@@ -459,16 +517,29 @@ async function cmdPublish(cwd, rest) {
   const { flags, positional } = parseFlags(rest)
   if (flags.help) return printHelp('publish')
   const id = await resolveAbstractId(cwd, flags, positional)
-  warnIfRemoteChanged(await apiFetch(`/api/abstracts/${id}`))
+  const detail = await apiFetch(`/api/abstracts/${id}`)
+  warnIfRemoteChanged(detail)
   const live = Boolean(flags.live)
   const version = await apiFetch(`/api/abstracts/${id}/publish`, {
     method: 'POST',
-    body: JSON.stringify({ live }),
+    body: JSON.stringify({ live, expectedRevision: detail.abstract.draft_revision }),
   })
   if (jsonMode(flags)) printJson({ id: version.id, label: version.label, live })
   else console.log(live ? 'It’s live.' : 'Published.')
 }
 
+async function cmdRecommend(cwd, rest) {
+  const { flags } = parseFlags(rest)
+  if (flags.help) return printHelp('recommend')
+  const id = requireMeta(cwd)
+  const { html, css, js } = readProjectFiles(cwd)
+  const result = await apiFetch(`/api/abstracts/${id}/recommendations`, {
+    method: 'POST', body: JSON.stringify({ html, css, js, note: typeof flags.note === 'string' ? flags.note : '' }),
+  })
+  if (jsonMode(flags)) printJson(result)
+  else console.log('Recommendation sent to the abstract owner.')
+}
+
 async function cmdLive(cwd, rest) {
   const { flags, positional } = parseFlags(rest)
   if (flags.help) return printHelp('live')
@@ -520,7 +591,6 @@ async function cmdList(rest) {
   if (folder) params.set('collection', String(folder))
   if (flags.tag) params.set('tag', String(flags.tag))
   if (flags.search) params.set('search', String(flags.search))
-  if (flags.space) params.set('space', String(flags.space))
   for (const key of ['starred', 'archived', 'owned', 'member', 'open', 'closed']) {
     if (flags[key]) params.set(key, 'true')
   }
@@ -703,58 +773,6 @@ async function cmdFolderMove(rest) {
   console.log('Moved folder.')
 }
 
-async function cmdFolderInvite(rest) {
-  const { flags, positional } = parseFlags(rest)
-  const token = positional[0]
-  const email = flags.email || positional[1]
-  if (!token || !email) throw new Error('Pass a folder and --email <email>.')
-  const folder = await resolveFolder(token)
-  await apiFetch(`/api/organise/collections/${folder.id}/invite`, {
-    method: 'POST',
-    body: JSON.stringify({ email }),
-  })
-  console.log('Added.')
-}
-
-async function cmdFolderRemove(rest) {
-  const { flags, positional } = parseFlags(rest)
-  const token = positional[0]
-  const who = flags.email || positional[1]
-  if (!token || !who) throw new Error('Pass a folder and an email or id.')
-  const folder = await resolveFolder(token)
-  const body = /@/.test(who) ? { email: who } : { userId: who }
-  await apiFetch(`/api/organise/collections/${folder.id}/revoke`, {
-    method: 'POST',
-    body: JSON.stringify(body),
-  })
-  console.log('Removed.')
-}
-
-async function cmdFolderPeople(rest) {
-  const { flags, positional } = parseFlags(rest)
-  const token = positional[0]
-  if (!token) throw new Error('Pass a folder.')
-  const folder = await resolveFolder(token)
-  const share = await apiFetch(`/api/organise/collections/${folder.id}`)
-  const people = (share.people || []).map((m) => ({
-    id: m.user_id,
-    name: m.name,
-    access: accessLabel(m.role),
-    role: m.role,
-  }))
-  if (jsonMode(flags)) {
-    printJson({ folder: folder.path, people })
-    return
-  }
-  if (!people.length) {
-    console.log('No people yet.')
-    return
-  }
-  for (const p of people) {
-    console.log(`${p.name} · ${p.access} · ${p.id}`)
-  }
-}
-
 async function cmdFolder(rest) {
   const { flags } = parseFlags(rest)
   if (flags.help || !rest[0]) return printHelp('folder')
@@ -762,33 +780,7 @@ async function cmdFolder(rest) {
   if (sub === 'new') return cmdFolderNew(tail)
   if (sub === 'list') return cmdFolderList(tail)
   if (sub === 'move') return cmdFolderMove(tail)
-  if (sub === 'invite') return cmdFolderInvite(tail)
-  if (sub === 'remove') return cmdFolderRemove(tail)
-  if (sub === 'people') return cmdFolderPeople(tail)
-  throw new Error('folder needs new, list, move, invite, remove, or people.')
-}
-
-async function cmdSpaceNew(rest) {
-  const { flags } = parseFlags(rest)
-  const name = flags.name || rest.find((a) => !a.startsWith('--'))
-  if (!name) throw new Error('Use folder new instead.')
-  const data = await apiFetch('/api/spaces', {
-    method: 'POST',
-    body: JSON.stringify({ name }),
-  })
-  console.log(data.id, data.name)
-}
-
-async function cmdSpaceMember(rest) {
-  const { flags, positional } = parseFlags(rest)
-  const spaceId = flags.space || positional[0]
-  const email = flags.email || positional[1]
-  if (!spaceId || !email) throw new Error('Use folder invite instead.')
-  await apiFetch(`/api/spaces/${spaceId}/members`, {
-    method: 'POST',
-    body: JSON.stringify({ email, role: flags.role || 'member' }),
-  })
-  console.log('Added.')
+  throw new Error('folder needs new, list, or move.')
 }
 
 export async function runCommand(argv, cwd = process.cwd()) {
@@ -827,6 +819,8 @@ export async function runCommand(argv, cwd = process.cwd()) {
       return cmdServe(cwd, rest)
     case 'publish':
       return cmdPublish(cwd, rest)
+    case 'recommend':
+      return cmdRecommend(cwd, rest)
     case 'live':
       return cmdLive(cwd, rest)
     case 'visibility':
@@ -853,10 +847,6 @@ export async function runCommand(argv, cwd = process.cwd()) {
       return cmdFolder(rest)
     case 'rename':
       return cmdRename(cwd, rest)
-    case 'space':
-      if (rest[0] === 'new') return cmdSpaceNew(rest.slice(1))
-      if (rest[0] === 'member') return cmdSpaceMember(rest.slice(1))
-      throw new Error('Use folder instead.')
     default:
       throw new Error(`Unknown command “${raw}”. Run amorphous-cli --help.`)
   }

package/lib/files.mjs

@@ -43,8 +43,10 @@ export function writeProjectFiles(cwd, payload) {
 export function recordsFromLocal(cwd) {
   const { shared, private: priv } = readProjectFiles(cwd)
   return [
-    ...shared.map((r) => ({ ...r, visibility: r.visibility || 'shared' })),
-    ...priv.map((r) => ({ ...r, visibility: 'private' })),
+    ...shared.map((r) => ({ ...r, revision: r.revision || 1, visibility: r.visibility || 'shared',
+      collection: r.collection || 'default', created_by: r.created_by || null })),
+    ...priv.map((r) => ({ ...r, revision: r.revision || 1, visibility: 'private',
+      collection: r.collection || 'default', created_by: r.created_by || null })),
   ]
 }
 
@@ -66,6 +68,9 @@ export function insertLocalRecord(cwd, row) {
   }
   body.visibility = body.visibility === 'private' ? 'private' : 'shared'
   if (!body.id) body.id = randomUUID()
+  body.revision = 1
+  body.collection = 'default'
+  body.created_by = null
   const rows = recordsFromLocal(cwd)
   if (rows.some((r) => r.id === body.id)) return { status: 409, message: 'Conflict' }
   rows.push(body)
@@ -83,6 +88,9 @@ export function replaceLocalRecord(cwd, id, row) {
     ...(row && typeof row === 'object' ? row : {}),
     id,
     visibility: existing.visibility,
+    revision: existing.revision + 1,
+    collection: existing.collection,
+    created_by: existing.created_by,
   }
   rows[index] = next
   writeLocalRecords(cwd, rows)

package/lib/help.mjs

@@ -11,6 +11,7 @@ export const ROOT_HELP = `Amorphous
   pull                          Pull draft and records to this folder
   push                          Push local files
   publish [--live]              Publish a version; --live is Go live
+  recommend [--note <text>]     Send this draft to the owner for review
   live [abstract]               Make a version live
   visibility anyone|members     Anyone can view / Members only
   invite <email>                Email an invite and print the link
@@ -25,9 +26,6 @@ export const ROOT_HELP = `Amorphous
   folder new                    New folder
   folder list                   Folders
   folder move                   Move folder
-  folder invite                 Invite to a folder
-  folder remove                 Remove from a folder
-  folder people                 People on a folder
   rename --name                 Rename
 
 Run amorphous-cli <command> --help for flags. Pass --json where you need machine output.
@@ -54,9 +52,9 @@ Start the local MCP server on stdio.`,
 List abstracts. Default view is all (All Abstracts).
 --folder filters to a folder. --tag filters to a tag.`,
 
-  create: `create [--name <name>] [--folder <name>] [--json]
+  create: `create [--name <name>] [--folder <name>] [--template blank|list|board|landing] [--recipe-config <file>] [--json]
 
-New abstract. Writes .amorphous.json in this directory.`,
+New abstract. --recipe-config creates a supported recipe and writes its generated source files. Writes .amorphous.json in this directory.`,
 
   open: `open [abstract] [--json]
 
@@ -84,6 +82,10 @@ Push local index.html, styles.css, and app.js.
 
 Publish a new version. --live also makes it the live version (Go live).`,
 
+  recommend: `recommend [--note <text>] [--json]
+
+Send this folder's HTML, CSS, and JavaScript to the owner as a proposal. It does not change the live version.`,
+
   live: `live [abstract] [--version <id>]
 
 Make this the live version. Uses the latest published version if you omit --version.`,
@@ -140,16 +142,12 @@ Unstar.`,
 
 Suggest folder from the name. Default is a suggestion only. --apply uses it.`,
 
-  folder: `folder <new|list|move|invite|remove|people> …
+  folder: `folder <new|list|move> …
 
   folder new --name <name> [--parent <id>]
   folder list [--json]
   folder move <folder> --parent <id|none>
-  folder invite <folder> --email <email>
-  folder remove <folder> <email|id>
-  folder people <folder> [--json]
-
-New folder, or move a folder. folder invite adds someone who already has an account. It does not send an email.`,
+New folder, or move a folder. Folders organize your library and do not grant access.`,
 
   rename: `rename [abstract] --name <name>
 

package/lib/participant-client.mjs

@@ -0,0 +1,82 @@
+const ACTION = /^[a-z][a-z0-9_.-]{0,79}$/
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+const TOKEN = /^[A-Za-z0-9_-]{40,64}$/
+const RECEIPT = /^[0-9a-f]{8}-[0-9a-f-]{27,}$/i
+const ACTION_NAMES = new Set([
+  'records.query', 'records.create', 'records.patch', 'records.delete',
+  'items.add', 'items.done', 'items.move', 'items.edit', 'items.delete',
+  'private.query', 'private.create', 'private.patch', 'private.delete',
+  'form.submit', 'form.mine', 'form.edit',
+])
+
+export function createParticipantClient({ origin, appId, token, hostHeaders = {}, fetchImpl = fetch }) {
+  const base = new URL(origin)
+  if (!['https:', 'http:'].includes(base.protocol) || base.username || base.password ||
+      base.search || base.hash || (base.pathname !== '/' && base.pathname !== '')) {
+    throw new TypeError('Participant app origin must be an HTTP(S) origin')
+  }
+  if (base.protocol === 'http:' && !['localhost', '127.0.0.1', '[::1]'].includes(base.hostname) &&
+      !base.hostname.endsWith('.localhost')) {
+    throw new TypeError('Participant grant requires HTTPS outside local development')
+  }
+  if (!UUID.test(appId) || !TOKEN.test(token)) throw new TypeError('Invalid participant connection settings')
+  if (Object.keys(hostHeaders).some((key) => key.toLowerCase() !== 'host') ||
+      Object.values(hostHeaders).some((value) => typeof value !== 'string' || /[\r\n]/.test(value))) {
+    throw new TypeError('Invalid participant host configuration')
+  }
+  const root = `/api/v1/apps/${appId.toLowerCase()}`
+
+  async function request(path, { method = 'GET', body, idempotencyKey, approvalId } = {}) {
+    if (typeof path !== 'string' || !path.startsWith(`${root}/`) || path.includes('..') || path.includes('?')) {
+      throw new Error('Unsupported participant endpoint')
+    }
+    const actionRoute = new RegExp(`^${root}/actions/([^/]+)/invoke$`).exec(path)
+    const receiptPrefix = `${root}/receipts/`
+    const getOnly = path === `${root}/me` || path === `${root}/actions` ||
+      path === `${root}/status` || path === `${root}/activity` ||
+      (path.startsWith(receiptPrefix) && RECEIPT.test(path.slice(receiptPrefix.length)) )
+    const postAction = Boolean(actionRoute && ACTION_NAMES.has(actionRoute[1]))
+    const allowed = (getOnly && method === 'GET') || (postAction && method === 'POST')
+    if (!allowed) throw new Error('Unsupported participant endpoint')
+    const headers = { ...hostHeaders, Authorization: `AmorphousGrant ${token}`, Accept: 'application/json' }
+    if (body !== undefined) headers['Content-Type'] = 'application/json'
+    if (idempotencyKey !== undefined) {
+      if (typeof idempotencyKey !== 'string' || idempotencyKey.length < 1 || idempotencyKey.length > 200) {
+        throw new TypeError('Invalid idempotency key')
+      }
+      headers['Idempotency-Key'] = idempotencyKey
+    }
+    if (approvalId !== undefined) {
+      if (typeof approvalId !== 'string' || !UUID.test(approvalId)) throw new TypeError('Invalid approval id')
+      headers['Amorphous-Approval'] = approvalId
+    }
+    const response = await fetchImpl(new URL(path, base), {
+      method, headers, redirect: 'error', ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+    })
+    const raw = await response.text()
+    let payload
+    try { payload = raw ? JSON.parse(raw) : null } catch { payload = null }
+    if (!response.ok) throw new Error(`Participant request failed (${response.status})`)
+    return payload
+  }
+
+  return Object.freeze({
+    request,
+    me: () => request(`${root}/me`),
+    discover: () => request(`${root}/actions`),
+    invoke: (action, input, idempotencyKey, approvalId) => {
+      if (typeof action !== 'string' || !ACTION.test(action) || !ACTION_NAMES.has(action)) throw new TypeError('Invalid action')
+      if (!input || typeof input !== 'object' || Array.isArray(input)) throw new TypeError('Invalid action input')
+      if (approvalId !== undefined && (typeof approvalId !== 'string' || !RECEIPT.test(approvalId))) {
+        throw new TypeError('Invalid approval id')
+      }
+      return request(`${root}/actions/${action}/invoke`, { method: 'POST', body: input, idempotencyKey, approvalId })
+    },
+    receipt: (receiptId) => {
+      if (typeof receiptId !== 'string' || !RECEIPT.test(receiptId)) throw new TypeError('Invalid receipt id')
+      return request(`${root}/receipts/${receiptId}`)
+    },
+    status: () => request(`${root}/status`),
+    activity: () => request(`${root}/activity`),
+  })
+}