amorphous-cli 0.1.10 → 0.1.12

package/lib/agent-contract.mjs

@@ -5,7 +5,7 @@ import { fileURLToPath } from 'node:url'
 import { homedir } from 'node:os'
 import { CLI_VERSION } from './version.mjs'
 
-export const CONTRACT_VERSION = 10
+export const CONTRACT_VERSION = 13
 
 const skillRoot = join(dirname(fileURLToPath(import.meta.url)), '../skill/amorphous')
 

package/lib/api.mjs

@@ -2,8 +2,6 @@ import { cliAppFetchOrigin, cliAppHostHeader } from './config.mjs'
 import { ensureFreshSession } from './session.mjs'
 
 const FRIENDLY = {
-  'You already own 2 abstracts': 'You already own 2 abstracts. Run: amorphous-cli list',
-  'This abstract already has 8 people': 'This abstract already has 8 people. Run: amorphous-cli people',
   'User not found': 'No account with that email yet.',
   'Grant failed': 'Could not invite. Run: amorphous-cli people',
   'Cannot revoke owner': "You can't remove the owner. Run: amorphous-cli people",
@@ -27,6 +25,12 @@ export function friendlyMessage(raw) {
   if (FRIENDLY[text]) return FRIENDLY[text]
   const stripped = text.replace(/^\d{3}\s+/, '')
   if (FRIENDLY[stripped]) return FRIENDLY[stripped]
+  if (/^You already own \d+ abstracts$/.test(stripped)) {
+    return `${stripped}. Run: amorphous-cli list`
+  }
+  if (/^This abstract already has \d+ people$/.test(stripped)) {
+    return `${stripped}. Run: amorphous-cli people`
+  }
   return stripped || text || 'Request failed.'
 }
 

package/lib/commands.mjs

@@ -64,6 +64,12 @@ function printJson(data) {
   console.log(JSON.stringify(data, null, 2))
 }
 
+function warnIfRemoteChanged(detail) {
+  if (detail?.remoteChangedSincePush) {
+    console.error('This abstract has changed since you last pushed.')
+  }
+}
+
 function readMeta(cwd) {
   const path = projectMetaPath(cwd)
   if (!existsSync(path)) return null
@@ -199,6 +205,11 @@ async function cmdSetup(rest) {
   }
   console.log('Installed the Amorphous skill.')
   for (const dir of dirs ?? installUserSkill()) console.log(dir)
+  console.log(`
+Tell the person:
+They describe what they want made. You make it.
+Prefer amorphous-cli serve while you edit. Open the URL and leave it running. It reloads when the files change.
+They tell you when to push, preview, publish, or invite.`)
 }
 
 async function cmdCreate(cwd, rest) {
@@ -225,7 +236,10 @@ async function cmdCreate(cwd, rest) {
   writeStarter(cwd)
   syncProjectContract(cwd)
   if (jsonMode(flags)) printJson({ id, name: name || 'Untitled' })
-  else console.log(id)
+  else {
+    console.log(id)
+    console.log('Prefer amorphous-cli serve while you edit.')
+  }
 }
 
 function takeAccess(flags, positional) {
@@ -266,8 +280,26 @@ async function cmdInvite(cwd, rest) {
   })
   const url = String(result.url || '')
   if (!url) throw new Error('Could not invite.')
-  if (jsonMode(flags)) printJson({ email, access: role === 'user' ? 'view' : role === 'editor' ? 'edit' : role, url })
-  else console.log(url)
+  const accessLabel = role === 'user' ? 'view' : role === 'editor' ? 'edit' : role
+  if (jsonMode(flags)) {
+    printJson({ email, access: accessLabel, url, mailed: Boolean(result.mailed) })
+    return
+  }
+  console.log(url)
+  if (result.notified === 'role') console.log('Updated their access.')
+  else if (result.mailed) console.log('Emailed the invite.')
+  else console.log('The invite is saved. The email did not send.')
+}
+
+async function cmdNotify(cwd, rest) {
+  const { flags, positional } = parseFlags(rest)
+  if (flags.help) return printHelp('notify')
+  const id = await resolveAbstractId(cwd, flags, positional)
+  const result = await apiFetch(`/api/abstracts/${id}/notify`, { method: 'POST' })
+  const sent = Number(result.sent || 0)
+  if (jsonMode(flags)) printJson({ sent })
+  else if (sent === 0) console.log('No one else to email.')
+  else console.log(sent === 1 ? 'Emailed 1 member.' : `Emailed ${sent} members.`)
 }
 
 async function cmdRemove(cwd, rest) {
@@ -313,6 +345,7 @@ async function cmdPull(cwd, rest) {
   if (flags.help) return printHelp('pull')
   const id = requireMeta(cwd)
   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')
@@ -326,12 +359,14 @@ async function cmdPull(cwd, rest) {
   })
   syncProjectContract(cwd)
   console.log('Pulled.')
+  console.log('Prefer amorphous-cli serve while you edit.')
 }
 
 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}`))
   if (flags.data) {
     const localRecords = recordsFromLocal(cwd)
     const { refused } = await apiFetch(`/api/abstracts/${id}/records`, {
@@ -364,8 +399,27 @@ async function cmdServe(cwd, rest) {
     port,
     json: jsonMode(flags),
   })
+  let warnedRemote = false
+  async function watchRemote() {
+    try {
+      const detail = await apiFetch(`/api/abstracts/${id}`)
+      if (detail.remoteChangedSincePush && !warnedRemote) {
+        warnedRemote = true
+        console.error('This abstract has changed since you last pushed.')
+      } else if (!detail.remoteChangedSincePush) {
+        warnedRemote = false
+      }
+    } catch {
+      /* leave the dev server up if the check cannot reach the abstract */
+    }
+  }
+  void watchRemote()
+  const remoteTimer = setInterval(() => {
+    void watchRemote()
+  }, 20000)
   await new Promise((resolve) => {
     const stop = () => {
+      clearInterval(remoteTimer)
       running.close().then(resolve, resolve)
     }
     process.once('SIGINT', stop)
@@ -394,8 +448,10 @@ async function cmdPreview(cwd, rest) {
   const { flags, positional } = parseFlags(rest)
   if (flags.help) return printHelp('preview')
   const id = await resolveAbstractId(cwd, flags, positional)
+  const detail = await apiFetch(`/api/abstracts/${id}`)
+  warnIfRemoteChanged(detail)
   const urls = urlsFor(id)
-  if (jsonMode(flags)) printJson({ preview: urls.preview })
+  if (jsonMode(flags)) printJson({ preview: urls.preview, remoteChangedSincePush: Boolean(detail.remoteChangedSincePush) })
   else console.log(urls.preview)
 }
 
@@ -403,6 +459,7 @@ 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 live = Boolean(flags.live)
   const version = await apiFetch(`/api/abstracts/${id}/publish`, {
     method: 'POST',
@@ -752,6 +809,8 @@ export async function runCommand(argv, cwd = process.cwd()) {
       return cmdCreate(cwd, rest)
     case 'invite':
       return cmdInvite(cwd, rest)
+    case 'notify':
+      return cmdNotify(cwd, rest)
     case 'remove':
       return cmdRemove(cwd, rest)
     case 'people':

package/lib/help.mjs

@@ -7,13 +7,14 @@ export const ROOT_HELP = `Amorphous
   create                        New abstract
   open [abstract]               Open URL
   preview [abstract]            Preview URL (draft)
-  serve                         Serve this folder locally
+  serve                         Develop in this folder
   pull                          Pull draft and records to this folder
   push                          Push local files
   publish [--live]              Publish a version; --live is Go live
   live [abstract]               Make a version live
   visibility anyone|members     Anyone can view / Members only
-  invite <email>                Print the link to give them
+  invite <email>                Email an invite and print the link
+  notify                        Email members about the published version
   remove <email|id>             Remove
   people [abstract]             People
   tag / untag                   Tag
@@ -67,7 +68,7 @@ Print the Preview URL (draft).`,
 
   serve: `serve [--port <n>] [--json]
 
-Serve this folder on 127.0.0.1 and reload when index.html, styles.css, or app.js changes.
+Preferred way to develop in this folder. Serves it on 127.0.0.1 and reloads when index.html, styles.css, or app.js changes. Leave it running and open the URL.
 Records start local, in this folder. The page can switch to prod, which reads and writes the abstract's records.`,
 
   pull: `pull
@@ -93,7 +94,11 @@ Anyone can view, or Members only. Uses the live version if you omit --version.`,
 
   invite: `invite <email> [view|use|edit] [--abstract <id|name>] [--json]
 
-Save an invite for this email and print the link to give them. Access: view, use, or edit. Default: view.`,
+Email an invite and print the link. Access: view, use, or edit. Default: view.`,
+
+  notify: `notify [abstract] [--json]
+
+Email members that the published version changed. Does not publish. You are not emailed.`,
 
   remove: `remove <email|id> [--abstract <id|name>]
 

package/mcp.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * Local MCP. Six tools for abstracts.
+ * Local MCP. Tools for abstracts.
  * Stdout is the protocol. The CLI runs as a child so its output stays off this stream.
  */
 import { spawn } from 'node:child_process'
@@ -72,7 +72,7 @@ await serveStdio(() => {
     {
       title: 'Pull the abstract',
       description:
-        'Download the abstract files and records into this folder. Overwrites the local copies of those files.',
+        'Download the abstract files and records into this folder. Overwrites the local copies of those files. Prefer amorphous-cli serve while editing; it reloads as the files change.',
       inputSchema: z.object({}),
       annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
     },
@@ -122,7 +122,7 @@ await serveStdio(() => {
     {
       title: 'Invite someone',
       description:
-        'Save an invite for this email and return the link to give them. This does not send an email. access is view (can open), use (can write shared records), or edit (can change the abstract).',
+        'Email an invite and return the link. access is view (can open), use (can write shared records), or edit (can change the abstract).',
       inputSchema: z.object({
         email: z.string().describe('Email address'),
         access: z.enum(['view', 'use', 'edit']).describe('view, use, or edit'),
@@ -132,5 +132,17 @@ await serveStdio(() => {
     async ({ email, access }) => call(['invite', email, access, '--json']),
   )
 
+  server.registerTool(
+    'notify',
+    {
+      title: 'Email members about the published version',
+      description:
+        'Email members that the published version changed. On demand. This does not publish. The person running it is not emailed.',
+      inputSchema: z.object({}),
+      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    },
+    async () => call(['notify', '--json']),
+  )
+
   return server
 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amorphous-cli",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "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

@@ -30,6 +30,14 @@ A running abstract provides `amorphous` in `app.js`:
 
 A private record belongs to the signed-in person who wrote it. The abstract does not read `private.ndjson`.
 
+## Person
+
+After `setup`, tell them this, briefly. `setup` also prints it. Say it to them in your own words.
+
+They describe what they want made. You make it.
+Prefer `amorphous-cli serve` while you edit. Open the URL and leave it running. It reloads when the files change, and it is the easiest way for them to look at the work.
+They tell you when to push, preview, publish, or invite. Do those when they ask.
+
 ## Loop
 
 Install the CLI once with `npm install -g amorphous-cli@latest`, then call it as `amorphous-cli <command>`. If a command prints `Run: npm install -g amorphous-cli@latest && amorphous-cli setup`, run that line, then repeat the command.
@@ -37,11 +45,15 @@ Install the CLI once with `npm install -g amorphous-cli@latest`, then call it as
 1. If you are not signed in, run `amorphous-cli login`. Show the person the link it prints and ask them to finish in the browser. Do not ask for an email or a code.
 2. `amorphous-cli create --name "..."` in a folder, or `amorphous-cli pull` when `.amorphous.json` is already there.
 3. Edit the files to match what they asked for. `me` and `names` are how the abstract knows who is here.
-4. `amorphous-cli serve` and open that URL. It reloads when the files change. Records on that page start in this folder. Switch the page to prod to read and write the abstract's records.
-5. `amorphous-cli push` sends the source. `amorphous-cli push --data` also sends the records in this folder.
-6. `amorphous-cli preview` and open that URL.
-7. `amorphous-cli publish --live`
-8. `amorphous-cli invite <email> use` or `edit` or `view`. It prints a link and does not send an email. Give them that link. They open it and sign in with that email.
+4. Prefer `amorphous-cli serve` while you edit. Open that URL and leave it running. It reloads when the files change, and it is the easiest way to check the work. Records on that page start in this folder. Switch the page to prod to read and write the abstract's records. You can push and preview without it.
+
+When they ask:
+
+- `amorphous-cli push` sends the source. `amorphous-cli push --data` also sends the records in this folder.
+- `amorphous-cli preview` and open that URL.
+- `amorphous-cli publish --live`
+- `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.
 
 `amorphous-cli visibility anyone` lets anyone view and write shared records. `amorphous-cli visibility members` keeps the abstract to invited people.