amorphous-cli 0.3.8 → 0.3.9

package/README.md

@@ -3,7 +3,7 @@
 Make an abstract with your AI agent. Describe what you want, and your agent can build and edit it with you.
 
 ```bash
-npx amorphous-cli@latest setup
+npx --yes amorphous-cli@latest setup
 ```
 
-After setup, tell your agent what to make. Ask it to preview, publish, or invite people when you're ready. Run `amorphous-cli --help` to see available commands.
+After setup, tell your agent what to make. Ask it to preview, publish, or invite people when you're ready. Run `npx --yes amorphous-cli@latest --help` to see available commands.

package/hooks/session-start.mjs

@@ -48,7 +48,7 @@ if (target === 'cursor') {
   process.stdout.write(
     `${JSON.stringify({
       additional_context:
-        'The Amorphous skill on this machine was just updated. Read ~/.agents/skills/amorphous/SKILL.md and follow it. Install the CLI with npm install -g amorphous-cli@latest and invoke it as amorphous-cli.',
+        'The Amorphous skill on this machine was just updated. Read ~/.agents/skills/amorphous/SKILL.md and follow it. Run commands with npx --yes amorphous-cli@latest; no global install is needed.',
     })}\n`,
   )
 } else {

package/lib/agent-contract.test.mjs

@@ -41,6 +41,8 @@ test('setup copies the skill, and an edited contract is left alone', () => {
   assert.equal(readFileSync(join(dirs[0], '.amorphous-version'), 'utf8'), `${CLI_VERSION}\n`)
   assert.equal(readFileSync(join(dirs[1], '.amorphous-version'), 'utf8'), `${CLI_VERSION}\n`)
   const skill = readFileSync(join(dirs[0], 'SKILL.md'), 'utf8')
+  assert.match(skill, /npx --yes amorphous-cli@latest <command>/)
+  assert.doesNotMatch(skill, /npm install -g amorphous-cli@latest/)
   assert.match(skill, /amorphous-cli list --view all/)
   assert.match(skill, /run `amorphous-cli pull <id-or-name>` first/)
   assert.match(skill, /Then run `amorphous-cli context` once/)

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

@@ -237,7 +237,7 @@ test('missing credentials quarantine prior private bytes under the original iden
   const sentinel = 'private bytes with missing auth.'
   writeFileSync(join(h.project, 'private-agent.md'), sentinel)
   unlinkSync(h.credentials)
-  await assert.rejects(runCommand(['context'], h.project), /Not signed in/i)
+  await assert.rejects(runCommand(['context'], h.project), /Not signed in\. Run: npx --yes amorphous-cli@latest login/i)
   assert.equal(existsSync(join(h.project, 'private-agent.md')), false)
   assert.equal(readFileSync(privateRecoveryFile(h.project), 'utf8'), sentinel)
 })

package/lib/api.mjs

@@ -1,23 +1,24 @@
 import { cliAppFetchOrigin, cliAppHostHeader } from './config.mjs'
 import { ensureFreshSession } from './session.mjs'
 
+const CLI = 'npx --yes amorphous-cli@latest'
 const FRIENDLY = {
   '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",
-  'Cannot remove yourself': "You can't remove yourself. Run: amorphous-cli people",
-  'Collection not found': 'Folder not found. Run: amorphous-cli folder list',
-  Forbidden: "You don't have access. Run: amorphous-cli list",
-  'Not Found': 'Not found. Run: amorphous-cli list',
-  'Owner required': 'Only the owner can do that. Run: amorphous-cli people',
-  'id required': 'Missing id. Run: amorphous-cli list',
-  'userId required': 'Pass an email or id. Run: amorphous-cli people',
-  'Invalid body': 'Invalid request. Run: amorphous-cli pull',
-  'Name required': 'Name required. Run: amorphous-cli rename --name <name>',
-  'Create failed': 'Could not create the abstract. Run: amorphous-cli list',
-  'Publish failed': 'Could not publish. Run: amorphous-cli push',
-  'File too large': 'That file is too large. Run: amorphous-cli pull',
-  'Not logged in. Run: amorphous login <email>': 'Not signed in. Run: amorphous-cli login',
+  'Grant failed': `Could not invite. Run: ${CLI} people`,
+  'Cannot revoke owner': `You can't remove the owner. Run: ${CLI} people`,
+  'Cannot remove yourself': `You can't remove yourself. Run: ${CLI} people`,
+  'Collection not found': `Folder not found. Run: ${CLI} folder list`,
+  Forbidden: `You don't have access. Run: ${CLI} list`,
+  'Not Found': `Not found. Run: ${CLI} list`,
+  'Owner required': `Only the owner can do that. Run: ${CLI} people`,
+  'id required': `Missing id. Run: ${CLI} list`,
+  'userId required': `Pass an email or id. Run: ${CLI} people`,
+  'Invalid body': `Invalid request. Run: ${CLI} pull`,
+  'Name required': `Name required. Run: ${CLI} rename --name <name>`,
+  'Create failed': `Could not create the abstract. Run: ${CLI} list`,
+  'Publish failed': `Could not publish. Run: ${CLI} push`,
+  'File too large': `That file is too large. Run: ${CLI} pull`,
+  'Not logged in. Run: amorphous login <email>': `Not signed in. Run: ${CLI} login`,
 }
 
 export function friendlyMessage(raw) {
@@ -26,10 +27,10 @@ export function friendlyMessage(raw) {
   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`
+    return `${stripped}. Run: ${CLI} list`
   }
   if (/^This abstract already has \d+ people$/.test(stripped)) {
-    return `${stripped}. Run: amorphous-cli people`
+    return `${stripped}. Run: ${CLI} people`
   }
   return stripped || text || 'Request failed.'
 }

package/lib/commands.mjs

@@ -25,6 +25,7 @@ import {
 
 const COMBINED_GUIDE_MAX_BYTES = 48 * 1024
 const GUIDE_MAX_BYTES = 32 * 1024
+const CLI = 'npx --yes amorphous-cli@latest'
 const QUARANTINE_USER_IDS = [
   'ffffffff-ffff-4fff-8fff-ffffffffffff',
   'eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee',
@@ -114,7 +115,7 @@ export function writeRecipeFiles(cwd, source) {
 function requireMeta(cwd) {
   const meta = readMeta(cwd)
   if (!meta?.abstractId) {
-    throw new Error('No .amorphous.json here. Run amorphous-cli create first.')
+    throw new Error(`No .amorphous.json here. Run ${CLI} create first.`)
   }
   return meta.abstractId
 }
@@ -171,7 +172,7 @@ function sessionUserId(accessToken) {
     if (typeof decoded.sub !== 'string' || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(decoded.sub)) throw new Error()
     return decoded.sub.toLowerCase()
   } catch {
-    throw new Error('The signed-in Amorphous session has no valid user identity. Run amorphous-cli login.')
+    throw new Error(`The signed-in Amorphous session has no valid user identity. Run ${CLI} login.`)
   }
 }
 
@@ -264,11 +265,11 @@ async function cmdContext(cwd, rest) {
     authorizationComplete = true
     const combinedBytes = Buffer.byteLength(abstractGuide.body, 'utf8') + Buffer.byteLength(privateGuide.body, 'utf8')
     if (combinedBytes > COMBINED_GUIDE_MAX_BYTES) {
-      throw new Error('Agent guides exceed the combined 48 KiB UTF-8 context limit. Neither guide was loaded; reduce their size and run amorphous-cli context again.')
+      throw new Error(`Agent guides exceed the combined 48 KiB UTF-8 context limit. Neither guide was loaded; reduce their size and run ${CLI} context again.`)
     }
     const identity = activateGuideIdentity(cwd, id, userId)
     if (!identity.privateSafeToLoad) {
-      throw new Error('Guide identity is uncertain. Existing local files were preserved in recovery and neither guide was loaded; confirm the account and run amorphous-cli context again.')
+      throw new Error(`Guide identity is uncertain. Existing local files were preserved in recovery and neither guide was loaded; confirm the account and run ${CLI} context again.`)
     }
 
     const documents = [
@@ -279,7 +280,7 @@ async function cmdContext(cwd, rest) {
     for (const { kind, guide } of documents) {
       const outcome = materializeGuide({ projectRoot: cwd, abstractId: id, userId, kind, body: guide.body, revision: guide.revision })
       if (outcome.status === 'identity-uncertain') {
-        throw new Error('Guide identity changed during context loading. Do not use either local guide; confirm the account and run amorphous-cli context again.')
+        throw new Error(`Guide identity changed during context loading. Do not use either local guide; confirm the account and run ${CLI} context again.`)
       }
       outcomes.push(outcome)
     }
@@ -313,7 +314,7 @@ async function cmdGuide(cwd, rest) {
   const { flags, positional } = parseFlags(rest)
   if (flags.help || positional[0] !== 'save') return printHelp('guide')
   const kind = positional[1]
-  if (!['abstract', 'private'].includes(kind)) throw new Error('Use: amorphous-cli guide save <abstract|private> [abstract].')
+  if (!['abstract', 'private'].includes(kind)) throw new Error(`Use: ${CLI} guide save <abstract|private> [abstract].`)
   const abstractToken = positional[2]
   const { accessToken, userId } = await guideSession()
   const request = (path, options) => apiFetch(path, { ...options, accessToken })
@@ -322,11 +323,11 @@ async function cmdGuide(cwd, rest) {
   const current = validateGuideResponse(await request(`/api/abstracts/${id}/${endpoint}`), `${kind} guide`)
   const paths = guidePaths(cwd, id, userId)
   const identity = activateGuideIdentity(cwd, id, userId)
-  if (!identity.privateSafeToLoad) throw new Error('Guide identity is uncertain; preserved local files are not eligible for saving. Run context after confirming the signed-in account.')
+  if (!identity.privateSafeToLoad) throw new Error(`Guide identity is uncertain; preserved local files are not eligible for saving. Run ${CLI} context after confirming the signed-in account.`)
   const state = readGuideSyncState(cwd, id, userId)
   const base = state?.guides?.[kind]
-  if (!base) throw new Error('No saved guide revision is available. Run amorphous-cli context first.')
-  if (base.revision !== current.revision) throw new Error('The server guide changed since context was loaded. Run amorphous-cli context, resolve any conflict, then save again.')
+  if (!base) throw new Error(`No saved guide revision is available. Run ${CLI} context first.`)
+  if (base.revision !== current.revision) throw new Error(`The server guide changed since context was loaded. Run ${CLI} context, resolve any conflict, then save again.`)
   const path = kind === 'abstract' ? paths.abstractGuide : paths.privateGuide
   const file = lstatSync(path)
   if (file.isSymbolicLink() || !file.isFile()) throw new Error('Guide file must be a regular non-symlink file.')
@@ -447,7 +448,7 @@ async function cmdSetup(rest) {
   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.
+Prefer ${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.`)
 }
 
@@ -481,7 +482,7 @@ async function cmdCreate(cwd, rest) {
     }
     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.') }
+    else { console.log(data.id); console.log(`Prefer ${CLI} serve while you edit.`) }
     return
   }
   const template = typeof flags.template === 'string' ? flags.template : 'blank'
@@ -509,7 +510,7 @@ async function cmdCreate(cwd, rest) {
   if (jsonMode(flags)) printJson({ id, name: name || 'Untitled' })
   else {
     console.log(id)
-    console.log('Prefer amorphous-cli serve while you edit.')
+    console.log(`Prefer ${CLI} serve while you edit.`)
   }
 }
 
@@ -644,7 +645,7 @@ async function cmdPull(cwd, rest) {
   const records = await apiFetch(`/api/abstracts/${id}/records`)
   writePulledProject(cwd, id, detail, records, { fresh: positional.length > 0 || Boolean(flags.abstract) })
   console.log('Pulled.')
-  console.log('Prefer amorphous-cli serve while you edit.')
+  console.log(`Prefer ${CLI} serve while you edit.`)
 }
 
 async function cmdPush(cwd, rest) {
@@ -660,7 +661,7 @@ async function cmdPush(cwd, rest) {
       body: JSON.stringify({ records: localRecords }),
     })
     if (refused?.length) {
-      console.error(`Skipped (already live): ${refused.join(', ')}. Run: amorphous-cli pull`)
+      console.error(`Skipped (already live): ${refused.join(', ')}. Run: ${CLI} pull`)
     }
   }
   const { html, css, js } = readProjectFiles(cwd)
@@ -1098,6 +1099,6 @@ export async function runCommand(argv, cwd = process.cwd()) {
     case 'rename':
       return cmdRename(cwd, rest)
     default:
-      throw new Error(`Unknown command “${raw}”. Run amorphous-cli --help.`)
+      throw new Error(`Unknown command “${raw}”. Run ${CLI} --help.`)
   }
 }

package/lib/help.mjs

@@ -31,8 +31,8 @@ export const ROOT_HELP = `Amorphous
   folder remove                 Remove empty folder
   rename --name                 Rename
 
-Run amorphous-cli <command> --help for flags. Pass --json where you need machine output.
-Run amorphous-cli --version to print the installed version.
+Run npx --yes amorphous-cli@latest <command> --help for flags. Pass --json where you need machine output.
+Run npx --yes amorphous-cli@latest --version to print the current version.
 `
 
 export const COMMAND_HELP = {

package/lib/login.mjs

@@ -8,6 +8,8 @@ import { createPkce, statesMatch } from './connect-crypto.mjs'
 import { mailpitBase, sessionFromVerifyUrl, waitForMagicLinkVerifyUrl } from './mailpit.mjs'
 import { saveSession, sessionRecord } from './session.mjs'
 
+const CLI = 'npx --yes amorphous-cli@latest'
+
 function isLocalSupabase() {
   try {
     const host = new URL(supabaseUrl()).hostname
@@ -70,7 +72,7 @@ async function loginViaMailpit(supabase, email, redirectTo, sinceMs) {
 async function readCode(email) {
   if (!process.stdin.isTTY) {
     throw new Error(
-      `Code sent to ${email}. Read it from that inbox, then run: amorphous-cli login ${email} --code <code>`,
+      `Code sent to ${email}. Read it from that inbox, then run: ${CLI} login ${email} --code <code>`,
     )
   }
   const rl = createInterface({ input: process.stdin, output: process.stderr })

package/lib/session.mjs

@@ -6,6 +6,7 @@ import { createClient } from '@supabase/supabase-js'
 import { credentialsPath, loadDotEnv, supabaseAnonKey, supabaseUrl } from './config.mjs'
 
 const REFRESH_WINDOW_MS = 60_000
+const LOGIN_COMMAND = 'npx --yes amorphous-cli@latest login'
 const LOCK_STALE_MS = 15_000
 const LOCK_WAIT_MS = 20_000
 
@@ -58,7 +59,7 @@ async function withCredentialLock(dir, fn) {
         /* the other process released it */
       }
       if (Date.now() - started > LOCK_WAIT_MS) {
-        throw new Error('Not signed in. Run: amorphous-cli login')
+        throw new Error(`Not signed in. Run: ${LOGIN_COMMAND}`)
       }
       await sleep(25)
     }
@@ -115,11 +116,11 @@ export async function ensureFreshSession(options = {}) {
     const now = options.now ?? Date.now()
     const session = loadSession()
     if (!session?.access_token) {
-      throw new Error('Not signed in. Run: amorphous-cli login')
+      throw new Error(`Not signed in. Run: ${LOGIN_COMMAND}`)
     }
     if (!options.force && !sessionNeedsRefresh(session, now)) return session
     if (!session.refresh_token) {
-      throw new Error('Not signed in. Run: amorphous-cli login')
+      throw new Error(`Not signed in. Run: ${LOGIN_COMMAND}`)
     }
     const refresh = options.refresh ?? refreshWithSupabase
     try {
@@ -135,7 +136,7 @@ export async function ensureFreshSession(options = {}) {
       ) {
         return again
       }
-      throw new Error('Not signed in. Run: amorphous-cli login')
+      throw new Error(`Not signed in. Run: ${LOGIN_COMMAND}`)
     }
   })
 }
@@ -148,7 +149,7 @@ export function accessToken() {
 export function authHeaders(extra = {}) {
   const token = accessToken()
   if (!token) {
-    throw new Error('Not signed in. Run: amorphous-cli login')
+    throw new Error(`Not signed in. Run: ${LOGIN_COMMAND}`)
   }
   return {
     Authorization: `Bearer ${token}`,

package/lib/tool-result.test.mjs

@@ -2,14 +2,14 @@ import assert from 'node:assert/strict'
 import test from 'node:test'
 import { toolText } from './tool-result.mjs'
 
-const NUDGE = 'Run: npm install -g amorphous-cli@latest && amorphous-cli setup'
+const NUDGE = 'Run: npx --yes amorphous-cli@latest setup'
 
 test('a successful command keeps stderr the model must see', () => {
   assert.equal(toolText('[{"id":"a"}]', `${NUDGE}\n`, 0), `[{"id":"a"}]\n${NUDGE}`)
 })
 
 test('a failed command returns the error text', () => {
-  assert.equal(toolText('', 'Not signed in. Run: amorphous-cli login\n', 1), 'Not signed in. Run: amorphous-cli login')
+  assert.equal(toolText('', 'Not signed in. Run: npx --yes amorphous-cli@latest login\n', 1), 'Not signed in. Run: npx --yes amorphous-cli@latest login')
 })
 
 test('empty success is ok', () => {

package/lib/update-check.mjs

@@ -8,7 +8,7 @@ import { userSkillDirs } from './agent-contract.mjs'
 import { CLI_VERSION } from './version.mjs'
 
 const CACHE_TTL_MS = 24 * 60 * 60 * 1000
-const NUDGE = 'Run: npm install -g amorphous-cli@latest && amorphous-cli setup\n'
+const NUDGE = 'Run: npx --yes amorphous-cli@latest setup\n'
 
 function parseVersion(v) {
   if (typeof v !== 'string') return null

package/lib/update-check.test.mjs

@@ -14,7 +14,7 @@ import {
   startUpdateCheck,
 } from './update-check.mjs'
 
-const NUDGE = 'Run: npm install -g amorphous-cli@latest && amorphous-cli setup\n'
+const NUDGE = 'Run: npx --yes amorphous-cli@latest setup\n'
 
 test('compareVersions', () => {
   assert.equal(compareVersions('1.0.0', '1.0.0'), 0)
@@ -252,7 +252,8 @@ test('non-setup refreshes a stale skill when registry matches', async () => {
   await update.finish()
   assert.equal(err, '')
   assert.equal(readFileSync(join(d0, '.amorphous-version'), 'utf8').trim(), CLI_VERSION)
-  assert.match(readFileSync(join(d0, 'SKILL.md'), 'utf8'), /npm install -g amorphous-cli@latest/)
+  assert.match(readFileSync(join(d0, 'SKILL.md'), 'utf8'), /npx --yes amorphous-cli@latest <command>/)
+  assert.doesNotMatch(readFileSync(join(d0, 'SKILL.md'), 'utf8'), /npm install -g amorphous-cli@latest/)
 })
 
 test('a newer registry is not copied over the installed skill', async () => {
@@ -291,6 +292,17 @@ test('integration help skips update check file', () => {
     encoding: 'utf8',
   })
   assert.equal(r.status, 0)
-  assert.ok(!r.stderr.includes('Run: npm install -g amorphous-cli@latest && amorphous-cli setup'))
+  assert.ok(!r.stderr.includes('Run: npx --yes amorphous-cli@latest setup'))
+  assert.match(r.stdout, /Run npx --yes amorphous-cli@latest <command> --help for flags/)
   assert.throws(() => readFileSync(cacheFile(home)), { code: 'ENOENT' })
 })
+
+test('skill and session hook use the same no-global-install command', () => {
+  const repoRoot = join(import.meta.dirname, '../..')
+  const skill = readFileSync(join(repoRoot, 'cli/skill/amorphous/SKILL.md'), 'utf8')
+  const hook = readFileSync(join(repoRoot, 'cli/hooks/session-start.mjs'), 'utf8')
+  assert.match(skill, /npx --yes amorphous-cli@latest <command>/)
+  assert.doesNotMatch(skill, /npm install -g amorphous-cli@latest/)
+  assert.match(hook, /Run commands with npx --yes amorphous-cli@latest/)
+  assert.doesNotMatch(hook, /npm install -g amorphous-cli@latest/)
+})

package/mcp.mjs

@@ -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. Prefer amorphous-cli serve while editing; it reloads as the files change.',
+        'Download the abstract files and records into this folder. Overwrites the local copies of those files. Prefer npx --yes amorphous-cli@latest serve while editing; it reloads as the files change.',
       inputSchema: z.object({}),
       annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
     },

package/package.json

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

@@ -40,7 +40,7 @@ They tell you when to push, preview, publish, or invite. Do those when they ask.
 
 ## Start
 
-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. 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.
+Run CLI commands as `npx --yes amorphous-cli@latest <command>`; this uses the latest CLI without a global install. The command examples below abbreviate that prefix as `amorphous-cli`. If a command prints `Run: npx --yes amorphous-cli@latest setup`, run that line, then repeat the command. If you are not signed in, run `npx --yes amorphous-cli@latest 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.
 
 Then choose the path that matches the request: