amorphous-cli 0.3.3 → 0.3.4

package/lib/agent-guide-commands.test.mjs

@@ -107,6 +107,46 @@ test('context fetches only authorized guide endpoints and materializes both docs
   assert.equal(calls.length, 4, 'a new context invocation freshly authorizes both guides')
 })
 
+test('context does not ask the agent to read guides that contain no text', async (t) => {
+  const h = await contextHarness(t, {
+    responder(req, res) {
+      res.writeHead(200, { 'content-type': 'application/json' })
+      res.end(JSON.stringify({ body: '', revision: 0, updatedAt: null, updatedBy: null }))
+    },
+  })
+  const logs = []
+  const originalLog = console.log
+  console.log = (...args) => logs.push(args.join(' '))
+  try {
+    await runCommand(['context'], h.project)
+  } finally { console.log = originalLog }
+
+  assert.equal(readFileSync(join(h.project, 'agent.md'), 'utf8'), '')
+  assert.equal(readFileSync(join(h.project, 'private-agent.md'), 'utf8'), '')
+  assert.ok(logs.includes('Neither guide contains text; continue with the abstract task.'))
+  assert.equal(logs.some((line) => line.startsWith('Read agent.md')), false)
+  assert.equal(logs.some((line) => line.startsWith('The private guide is supplied')), false)
+})
+
+test('context names only guide files that contain text', async (t) => {
+  const h = await contextHarness(t, {
+    responder(req, res) {
+      const isPrivate = req.url.endsWith('/private-agent-guide')
+      res.writeHead(200, { 'content-type': 'application/json' })
+      res.end(JSON.stringify({ body: isPrivate ? '' : 'Shared instructions.', revision: isPrivate ? 0 : 1, updatedAt: null, updatedBy: null }))
+    },
+  })
+  const logs = []
+  const originalLog = console.log
+  console.log = (...args) => logs.push(args.join(' '))
+  try {
+    await runCommand(['context'], h.project)
+  } finally { console.log = originalLog }
+
+  assert.ok(logs.includes('Read agent.md before working on the abstract.'))
+  assert.equal(logs.some((line) => line.includes('private-agent.md before')), false)
+})
+
 test('context refuses both guides above the combined cap before writing either', async (t) => {
   const root = mkdtempSync(join(tmpdir(), 'am-guide-cap-'))
   const project = join(root, 'project')

package/lib/commands.mjs

@@ -227,19 +227,25 @@ function quarantineActiveGuides(cwd, fallbackAbstractId) {
 
 function enforceActiveGuideCaps(cwd, abstractId, userId) {
   const paths = guidePaths(cwd, abstractId, userId)
-  const files = [paths.abstractGuide, paths.privateGuide]
+  const files = [
+    { name: 'agent.md', path: paths.abstractGuide },
+    { name: 'private-agent.md', path: paths.privateGuide },
+  ]
   let combinedBytes = 0
-  for (const path of files) {
+  const inspected = []
+  for (const { path } of files) {
     const info = lstatSync(path)
     if (info.isSymbolicLink() || !info.isFile()) throw new Error('Active guide files must be regular non-symlink files.')
     if (info.size > GUIDE_MAX_BYTES) {
       throw new Error('An active guide exceeds the 32 KiB UTF-8 context limit. Neither guide was loaded; local text is preserved without truncation.')
     }
     combinedBytes += info.size
+    inspected.push(info.size)
   }
   if (combinedBytes > COMBINED_GUIDE_MAX_BYTES) {
     throw new Error('Active guide files exceed the combined 48 KiB UTF-8 context limit. Neither guide was loaded; local text is preserved without truncation.')
   }
+  return files.filter((_, index) => inspected[index] > 0).map(({ name }) => name)
 }
 
 async function cmdContext(cwd, rest) {
@@ -277,7 +283,7 @@ async function cmdContext(cwd, rest) {
       }
       outcomes.push(outcome)
     }
-    enforceActiveGuideCaps(cwd, id, userId)
+    const nonemptyGuides = enforceActiveGuideCaps(cwd, id, userId)
     const conflicts = outcomes.filter((outcome) => outcome.status === 'conflict')
     if (conflicts.length) {
       const paths = conflicts.map((item) => item.conflictPath).join(', ')
@@ -285,8 +291,14 @@ async function cmdContext(cwd, rest) {
     }
     console.log(`Loaded guide context for ${id} (abstract revision ${abstractGuide.revision}; private revision ${privateGuide.revision}).`)
     console.log('Context does not fetch source; source release/version is separate from these guide revisions.')
-    console.log('The private guide is supplied to this local agent process and cannot be recalled after download.')
-    console.log('Read agent.md, then private-agent.md before working on the abstract.')
+    if (nonemptyGuides.includes('private-agent.md')) {
+      console.log('The private guide is supplied to this local agent process and cannot be recalled after download.')
+    }
+    if (nonemptyGuides.length) {
+      console.log(`Read ${nonemptyGuides.join(' and ')} before working on the abstract.`)
+    } else {
+      console.log('Neither guide contains text; continue with the abstract task.')
+    }
   } catch (error) {
     if (!authorizationComplete) {
       try { quarantineActiveGuides(cwd, id) } catch (quarantineError) {
@@ -988,14 +1000,33 @@ async function cmdFolderMove(rest) {
   console.log('Moved folder.')
 }
 
+async function cmdFolderRemove(rest) {
+  const { flags, positional } = parseFlags(rest)
+  const token = flags.id || positional[0]
+  if (!token) throw new Error('Pass a folder name or id.')
+  const folders = await loadFolders()
+  const want = String(token)
+  const folder = folders.find((candidate) => candidate.id === want || candidate.path === want)
+  const nameMatches = folders.filter((candidate) => candidate.name.toLowerCase() === want.toLowerCase())
+  if (!folder && nameMatches.length > 1) {
+    throw new Error(`More than one folder is named “${token}”. Use its full path or id.`)
+  }
+  const target = folder || nameMatches[0]
+  if (!target) throw new Error(`No folder named “${token}”`)
+  await apiFetch(`/api/organise/collections/${target.id}`, { method: 'DELETE' })
+  if (jsonMode(flags)) printJson({ id: target.id, name: target.name, removed: true })
+  else console.log('Folder removed.')
+}
+
 async function cmdFolder(rest) {
   const { flags } = parseFlags(rest)
-  if (flags.help || !rest[0]) return printHelp('folder')
+  if (flags.help || !rest[0]) return printHelp(rest[0] === 'list' ? 'folder-list' : 'folder')
   const [sub, ...tail] = rest
   if (sub === 'new') return cmdFolderNew(tail)
   if (sub === 'list') return cmdFolderList(tail)
   if (sub === 'move') return cmdFolderMove(tail)
-  throw new Error('folder needs new, list, or move.')
+  if (sub === 'remove') return cmdFolderRemove(tail)
+  throw new Error('folder needs new, list, move, or remove.')
 }
 
 export async function runCommand(argv, cwd = process.cwd()) {

package/lib/folder-command.test.mjs

@@ -0,0 +1,178 @@
+import assert from 'node:assert/strict'
+import { createServer } from 'node:http'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import test from 'node:test'
+import { runCommand } from './commands.mjs'
+import { saveSession } from './session.mjs'
+
+const folderId = '00000000-0000-4000-8000-000000000003'
+const userId = '10000000-0000-4000-8000-000000000001'
+const payload = (value) => Buffer.from(JSON.stringify(value)).toString('base64url')
+const accessToken = `header.${payload({ sub: userId, exp: Math.floor(Date.now() / 1000) + 3600 })}.signature`
+
+async function folderHarness(t, deleteStatus = 200, collections) {
+  const root = mkdtempSync(join(tmpdir(), 'am-folder-command-'))
+  const oldCredentials = process.env.AMORPHOUS_CREDENTIALS
+  const oldAppUrl = process.env.AMORPHOUS_CLI_APP_URL
+  const oldAppOrigin = process.env.APP_ORIGIN
+  process.env.AMORPHOUS_CREDENTIALS = join(root, 'credentials.json')
+  process.env.APP_ORIGIN = 'https://amorphous.test'
+  saveSession({
+    access_token: accessToken,
+    refresh_token: 'unused',
+    expires_at: Math.floor(Date.now() / 1000) + 3600,
+  })
+
+  const calls = []
+  const server = createServer((req, res) => {
+    calls.push({ method: req.method, url: req.url, authorization: req.headers.authorization })
+    res.setHeader('content-type', 'application/json')
+    if (req.method === 'GET' && req.url === '/api/organise/meta') {
+      res.end(JSON.stringify({
+        all_collections: collections || [{
+          id: folderId,
+          name: 'QA smoke 2026-10-21',
+          path: 'QA smoke 2026-10-21',
+          parent_id: null,
+          abstract_count: 0,
+        }],
+      }))
+      return
+    }
+    if (req.method === 'DELETE' && req.url === `/api/organise/collections/${folderId}`) {
+      res.statusCode = deleteStatus
+      res.end(JSON.stringify(deleteStatus === 200 ? { ok: true } : {
+        statusCode: 409,
+        statusMessage: 'Move the folder contents out before removing it',
+        message: 'Move the folder contents out before removing it',
+      }))
+      return
+    }
+    res.statusCode = 404
+    res.end(JSON.stringify({ message: 'Not found' }))
+  })
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve))
+  process.env.AMORPHOUS_CLI_APP_URL = `http://127.0.0.1:${server.address().port}`
+
+  t.after(async () => {
+    server.closeAllConnections?.()
+    await new Promise((resolve) => server.close(resolve))
+    rmSync(root, { recursive: true, force: true })
+    if (oldCredentials === undefined) delete process.env.AMORPHOUS_CREDENTIALS
+    else process.env.AMORPHOUS_CREDENTIALS = oldCredentials
+    if (oldAppUrl === undefined) delete process.env.AMORPHOUS_CLI_APP_URL
+    else process.env.AMORPHOUS_CLI_APP_URL = oldAppUrl
+    if (oldAppOrigin === undefined) delete process.env.APP_ORIGIN
+    else process.env.APP_ORIGIN = oldAppOrigin
+  })
+
+  return calls
+}
+
+test('folder remove resolves a folder name and deletes the empty folder', async (t) => {
+  const calls = await folderHarness(t)
+  let output = ''
+  const originalLog = console.log
+  console.log = (message) => { output = String(message) }
+  try {
+    await runCommand(['folder', 'remove', 'QA smoke 2026-10-21'])
+  } finally {
+    console.log = originalLog
+  }
+
+  assert.deepEqual(calls.map(({ method, url }) => [method, url]), [
+    ['GET', '/api/organise/meta'],
+    ['DELETE', `/api/organise/collections/${folderId}`],
+  ])
+  assert.ok(calls.every((call) => call.authorization === `Bearer ${accessToken}`))
+  assert.equal(output, 'Folder removed.')
+})
+
+test('folder remove requires an id or path when folder names collide', async (t) => {
+  const calls = await folderHarness(t, 200, [
+    {
+      id: folderId,
+      name: 'QA smoke',
+      path: 'Production / QA smoke',
+      parent_id: '00000000-0000-4000-8000-000000000005',
+      abstract_count: 0,
+    },
+    {
+      id: '00000000-0000-4000-8000-000000000004',
+      name: 'QA smoke',
+      path: 'Launch / QA smoke',
+      parent_id: '00000000-0000-4000-8000-000000000005',
+      abstract_count: 0,
+    },
+  ])
+
+  await assert.rejects(
+    runCommand(['folder', 'remove', 'QA smoke']),
+    /More than one folder is named.*full path or id/,
+  )
+  assert.deepEqual(calls.map(({ method, url }) => [method, url]), [
+    ['GET', '/api/organise/meta'],
+  ])
+})
+
+test('folder remove reports that a non-empty folder must be cleared first', async (t) => {
+  const calls = await folderHarness(t, 409)
+  await assert.rejects(
+    runCommand(['folder', 'remove', folderId]),
+    /Move the folder contents out before removing it/,
+  )
+  assert.deepEqual(calls.map(({ method, url }) => [method, url]), [
+    ['GET', '/api/organise/meta'],
+    ['DELETE', `/api/organise/collections/${folderId}`],
+  ])
+})
+
+test('folder remove returns machine-readable confirmation in JSON mode', async (t) => {
+  await folderHarness(t)
+  let output = ''
+  const originalLog = console.log
+  console.log = (message) => { output = String(message) }
+  try {
+    await runCommand(['folder', 'remove', folderId, '--json'])
+  } finally {
+    console.log = originalLog
+  }
+
+  assert.deepEqual(JSON.parse(output), {
+    id: folderId,
+    name: 'QA smoke 2026-10-21',
+    removed: true,
+  })
+})
+
+test('folder help describes the remove command and its empty-folder requirement', async () => {
+  let output = ''
+  const originalLog = console.log
+  console.log = (message) => { output = String(message) }
+  try {
+    await runCommand(['folder', '--help'])
+  } finally {
+    console.log = originalLog
+  }
+
+  assert.match(output, /folder remove <folder>/)
+  assert.match(output, /Only empty folders can be removed/i)
+  assert.match(output, /--json/)
+})
+
+test('folder list help stays focused on listing folders', async () => {
+  let output = ''
+  const originalLog = console.log
+  console.log = (message) => { output = String(message) }
+  try {
+    await runCommand(['folder', 'list', '--help'])
+  } finally {
+    console.log = originalLog
+  }
+
+  assert.match(output, /folder list \[--json\]/)
+  assert.match(output, /list your folders/i)
+  assert.doesNotMatch(output, /folder (new|move|remove)/)
+})

package/lib/help.mjs

@@ -15,7 +15,7 @@ export const ROOT_HELP = `Amorphous
   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
+  visibility anyone|members     Anyone can view; app may accept shared-record writes / Members only
   invite <email>                Email an invite and print the link
   notify                        Email members about the published version
   remove <email|id>             Remove
@@ -28,6 +28,7 @@ export const ROOT_HELP = `Amorphous
   folder new                    New folder
   folder list                   Folders
   folder move                   Move folder
+  folder remove                 Remove empty folder
   rename --name                 Rename
 
 Run amorphous-cli <command> --help for flags. Pass --json where you need machine output.
@@ -105,7 +106,9 @@ Make this the live version. Uses the latest published version if you omit --vers
 
   visibility: `visibility <anyone|members> [abstract] [--version <id>]
 
-Anyone can view, or Members only. Uses the live version if you omit --version.`,
+Anyone: anyone with the link can view. If the app writes shared records, anyone with the link can add them; use this only when public submissions are intended.
+Members: only invited people can view; shared-record writes follow their access.
+Uses the live version if you omit --version.`,
 
   invite: `invite <email> [view|use|edit] [--abstract <id|name>] [--json]
 
@@ -155,12 +158,18 @@ Unstar.`,
 
 Suggest folder from the name. Default is a suggestion only. --apply uses it.`,
 
-  folder: `folder <new|list|move> …
+  folder: `folder <new|list|move|remove> …
 
   folder new --name <name> [--parent <id>]
   folder list [--json]
   folder move <folder> --parent <id|none>
-New folder, or move a folder. Folders organize your library and do not grant access.`,
+  folder remove <folder> [--json]
+New folder, or move a folder. Folders organize your library and do not grant access.
+Only empty folders can be removed; move their contents out first.`,
+
+  'folder-list': `folder list [--json]
+
+List your folders.`,
 
   rename: `rename [abstract] --name <name>
 

package/lib/help.test.mjs

@@ -1,6 +1,6 @@
 import assert from 'node:assert/strict'
 import test from 'node:test'
-import { printHelp } from './help.mjs'
+import { printHelp, ROOT_HELP } from './help.mjs'
 
 test('serve help explains that prod mode can write live records', () => {
   let output = ''
@@ -33,3 +33,24 @@ test('pull help makes the fresh-folder abstract target explicit', () => {
   assert.match(output, /before context/i)
   assert.match(output, /owner or editor/i)
 })
+
+test('visibility help explains public shared-record writes', () => {
+  let output = ''
+  const originalLog = console.log
+  console.log = (message) => { output = String(message) }
+  try {
+    printHelp('visibility')
+  } finally {
+    console.log = originalLog
+  }
+
+  assert.match(output, /if the app writes shared records/i)
+  assert.match(output, /anyone with the link can add them/i)
+  assert.match(output, /members: only invited people can view/i)
+  assert.match(output, /shared-record writes follow their access/i)
+  assert.match(output, /live version/i)
+})
+
+test('root help does not hide the write effect of public visibility', () => {
+  assert.match(ROOT_HELP, /anyone can view; app may accept shared-record writes/i)
+})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amorphous-cli",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "mcpName": "io.github.amorphous-one/amorphous",
   "description": "Make whatever you want, yourself, with your own agent, or with others.",
   "type": "module",

package/skill/amorphous/SKILL.md

@@ -50,6 +50,8 @@ Then choose the path that matches the request:
 - **Access:** View members can open the live abstract and load its guides, but cannot pull, recommend, or change source. Use members can use the live abstract and submit source recommendations for the owner to review when source files are already available to them. Only owners and editors can pull and edit source or publish a version; only the owner can invite/remove members, change visibility, or make a version live. Follow the access already granted; ask the owner for a role change if the requested work needs more access.
 - **New abstract:** Run `amorphous-cli create --name "..." [--template blank|list|board|landing]`. The list, board, and landing starters are working examples, not just mockups.
 
+After `context` succeeds, follow its final guide-reading instruction. It names only guide files that contain text; if neither guide contains text, continue without opening empty guide files. The private-guide handling warning appears only when that guide contains text.
+
 Edit the files to match what they asked for. `me` and `names` are how the abstract knows who is here. Prefer `amorphous-cli serve` while you edit. Open that URL and leave it running; it reloads when the files change, making it the easiest way to check the work. Records start local in this folder. Use prod mode only when the person explicitly asks you to inspect or change live records: `find` reads live data, while `insert` and `replace` change it immediately. Do not write live records during UI work or read-only checks. You can push and preview without prod mode.
 
 ## Loop
@@ -64,6 +66,8 @@ When they ask:
 - `amorphous-cli invite <email> use` or `edit` or `view`. It emails them a link and prints that link. They open it and sign in with that email.
 - `amorphous-cli notify` emails members that the published version changed. It does not publish. Do that only when they ask.
 
+Use `amorphous-cli folder list` to inspect library folders, `amorphous-cli folder new --name "<name>"` to create one, and `amorphous-cli folder move <folder> --parent <id|none>` to reorganize them. Remove an empty folder with `amorphous-cli folder remove <folder>`; move its abstracts and subfolders out first.
+
 `amorphous-cli visibility anyone` lets anyone view the abstract and write shared records through it. Those writes persist on the abstract. Make it public only when the person explicitly asks for public access and understands that anyone can add shared records. `amorphous-cli visibility members` keeps the abstract to invited people.
 
 Do not make a public abstract that lets anyone keep adding shared records, such as an open list. Those records stay on the abstract and use up its storage. Keep shared records to a set you replace, or keep the abstract to invited people.