amorphous-cli 0.1.5 → 0.1.6

package/README.md

@@ -3,5 +3,5 @@
 Build abstracts on Amorphous. An abstract can be anything. Your own agent builds it. Other people open it and write to it.
 
 ```bash
-npx amorphous-cli setup
+npx amorphous-cli@latest setup
 ```

package/index.mjs

@@ -2,13 +2,18 @@
 import { loadDotEnv } from './lib/config.mjs'
 import { runCommand } from './lib/commands.mjs'
 import { ensureLocalHttpsTrust } from './lib/tls.mjs'
+import { startUpdateCheck } from './lib/update-check.mjs'
 
 ensureLocalHttpsTrust()
 loadDotEnv()
 
+const update = startUpdateCheck({ argv: process.argv.slice(2) })
+
 try {
   await runCommand(process.argv.slice(2))
+  await update.finish()
 } catch (e) {
   console.error(e instanceof Error ? e.message : e)
+  await update.finish()
   process.exit(1)
 }

package/lib/agent-contract.mjs

@@ -1,10 +1,11 @@
 import { createHash } from 'node:crypto'
-import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { homedir } from 'node:os'
+import { CLI_VERSION } from './version.mjs'
 
-export const CONTRACT_VERSION = 1
+export const CONTRACT_VERSION = 2
 
 const skillRoot = join(dirname(fileURLToPath(import.meta.url)), '../skill/amorphous')
 
@@ -75,9 +76,12 @@ export function userSkillDirs(home = homedir()) {
 
 export function installUserSkill(home = homedir()) {
   const dirs = userSkillDirs(home)
+  const stamp = `${CLI_VERSION}\n`
   for (const dest of dirs) {
+    rmSync(dest, { recursive: true, force: true })
     mkdirSync(dest, { recursive: true })
     cpSync(skillRoot, dest, { recursive: true })
+    writeFileSync(join(dest, '.amorphous-version'), stamp)
   }
   return dirs
 }

package/lib/agent-contract.test.mjs

@@ -1,5 +1,5 @@
 import assert from 'node:assert/strict'
-import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import test from 'node:test'
@@ -10,6 +10,7 @@ import {
   syncProjectContract,
   writeStarter,
 } from './agent-contract.mjs'
+import { CLI_VERSION } from './version.mjs'
 
 test('setup copies the skill, and an edited contract is left alone', () => {
   const home = mkdtempSync(join(tmpdir(), 'amorphous-skill-'))
@@ -17,6 +18,12 @@ test('setup copies the skill, and an edited contract is left alone', () => {
   assert.equal(dirs.length, 2)
   assert.match(readFileSync(join(dirs[0], 'SKILL.md'), 'utf8'), /build abstracts/)
   assert.match(readFileSync(join(dirs[1], 'assets/app.js'), 'utf8'), /amorphous\.me/)
+  assert.equal(readFileSync(join(dirs[0], '.amorphous-version'), 'utf8'), `${CLI_VERSION}\n`)
+  assert.equal(readFileSync(join(dirs[1], '.amorphous-version'), 'utf8'), `${CLI_VERSION}\n`)
+
+  writeFileSync(join(dirs[1], 'stray.txt'), 'gone')
+  installUserSkill(home)
+  assert.equal(existsSync(join(dirs[1], 'stray.txt')), false)
 
   const project = mkdtempSync(join(tmpdir(), 'amorphous-page-'))
   assert.equal(syncProjectContract(project), 'wrote')
@@ -29,7 +36,23 @@ test('setup copies the skill, and an edited contract is left alone', () => {
   assert.equal(syncProjectContract(project), 'kept')
   assert.match(readFileSync(join(project, 'AGENTS.md'), 'utf8'), /Edited\./)
 
-  writeFileSync(join(project, 'AGENTS.md'), projectContract().replace('amorphous-contract: 1', 'amorphous-contract: 0'))
+  const older = projectContract().replace(
+    `amorphous-contract: ${CONTRACT_VERSION}`,
+    'amorphous-contract: 0',
+  )
+  writeFileSync(join(project, 'AGENTS.md'), older)
   assert.equal(syncProjectContract(project), 'refreshed')
-  assert.match(readFileSync(join(project, 'AGENTS.md'), 'utf8'), /amorphous-contract: 1/)
+  assert.match(
+    readFileSync(join(project, 'AGENTS.md'), 'utf8'),
+    new RegExp(`amorphous-contract: ${CONTRACT_VERSION}`),
+  )
+
+  writeFileSync(
+    join(project, 'AGENTS.md'),
+    projectContract().replace(
+      `amorphous-contract: ${CONTRACT_VERSION}`,
+      `amorphous-contract: ${CONTRACT_VERSION + 1}`,
+    ),
+  )
+  assert.equal(syncProjectContract(project), 'kept')
 })

package/lib/update-check.mjs

@@ -0,0 +1,188 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { randomBytes } from 'node:crypto'
+import { ALIASES } from './help.mjs'
+import { userSkillDirs } from './agent-contract.mjs'
+import { CLI_VERSION } from './version.mjs'
+
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000
+const NUDGE = 'Run: npx amorphous-cli@latest setup\n'
+
+function parseVersion(v) {
+  if (typeof v !== 'string') return null
+  const m = v.match(/^(\d+)\.(\d+)\.(\d+)(?:-([^+]+))?(?:\+.*)?$/)
+  if (!m) return null
+  return {
+    major: Number(m[1]),
+    minor: Number(m[2]),
+    patch: Number(m[3]),
+    prerelease: m[4] ?? null,
+  }
+}
+
+export function compareVersions(a, b) {
+  const va = parseVersion(a)
+  const vb = parseVersion(b)
+  if (!va || !vb) return null
+  if (va.major !== vb.major) return va.major < vb.major ? -1 : 1
+  if (va.minor !== vb.minor) return va.minor < vb.minor ? -1 : 1
+  if (va.patch !== vb.patch) return va.patch < vb.patch ? -1 : 1
+  if (va.prerelease && vb.prerelease) return 0
+  if (va.prerelease && !vb.prerelease) return -1
+  if (!va.prerelease && vb.prerelease) return 1
+  return 0
+}
+
+function resolveCommand(argv) {
+  const raw = argv[0]
+  if (!raw) return ''
+  return ALIASES[raw] || raw
+}
+
+export function shouldCheck(argv, env = process.env) {
+  if ('CI' in env) return false
+  if (env.AMORPHOUS_NO_UPDATE_CHECK === '1') return false
+  if (!argv.length) return false
+  if (argv[0] === 'help') return false
+  if (argv.includes('-h') || argv.includes('--help')) return false
+  if (resolveCommand(argv) === 'mcp') return false
+  return true
+}
+
+function existsSkill(path) {
+  try {
+    readFileSync(path)
+    return true
+  } catch {
+    return false
+  }
+}
+
+export function skillStale(home, version) {
+  const dirs = userSkillDirs(home)
+  for (const dir of dirs) {
+    const skillPath = join(dir, 'SKILL.md')
+    if (!existsSkill(skillPath)) continue
+    const stampPath = join(dir, '.amorphous-version')
+    let stamp
+    try {
+      stamp = readFileSync(stampPath, 'utf8').trim()
+    } catch {
+      return true
+    }
+    const cmp = compareVersions(stamp, version)
+    if (cmp === null) continue
+    if (cmp < 0) return true
+  }
+  return false
+}
+
+function cachePath(home) {
+  return join(home, '.config', 'amorphous', 'update-check.json')
+}
+
+function readCache(home) {
+  try {
+    const data = JSON.parse(readFileSync(cachePath(home), 'utf8'))
+    if (!data?.checkedAt) return null
+    return data
+  } catch {
+    return null
+  }
+}
+
+function cacheFresh(cache, now) {
+  if (!cache?.checkedAt) return false
+  const t = Date.parse(cache.checkedAt)
+  if (Number.isNaN(t)) return false
+  return now() - t < CACHE_TTL_MS
+}
+
+function writeCache(home, data) {
+  const dir = join(home, '.config', 'amorphous')
+  mkdirSync(dir, { recursive: true })
+  const dest = cachePath(home)
+  const tmp = join(dir, `.update-check.${process.pid}.${randomBytes(4).toString('hex')}.tmp`)
+  writeFileSync(tmp, JSON.stringify(data) + '\n')
+  renameSync(tmp, dest)
+}
+
+function defaultRegistry(env) {
+  const raw = env.npm_config_registry || 'https://registry.npmjs.org'
+  return raw.replace(/\/$/, '')
+}
+
+export function defaultFetchLatest(env = process.env) {
+  const registry = defaultRegistry(env)
+  return fetch(`${registry}/amorphous-cli/latest`, {
+    signal: AbortSignal.timeout(1500),
+  }).then(async (res) => {
+    if (!res.ok) throw new Error('registry')
+    const body = await res.json()
+    if (typeof body?.version !== 'string') throw new Error('registry')
+    return body.version
+  })
+}
+
+function needsNudge({ cmd, version, latest, home }) {
+  if (latest && compareVersions(version, latest) === -1) return true
+  if (cmd !== 'setup' && skillStale(home, version)) return true
+  return false
+}
+
+export function startUpdateCheck({
+  argv,
+  env = process.env,
+  home = homedir(),
+  version = CLI_VERSION,
+  now = () => Date.now(),
+  fetchLatest = () => defaultFetchLatest(env),
+  stderr = process.stderr,
+} = {}) {
+  let printed = false
+  let fetchPromise = null
+  let cache = null
+  let stale = false
+
+  if (shouldCheck(argv, env)) {
+    cache = readCache(home)
+    stale = !cacheFresh(cache, now)
+    if (stale) {
+      fetchPromise = fetchLatest().catch(() => null)
+    }
+  }
+
+  return {
+    async finish() {
+      try {
+        if (!shouldCheck(argv, env)) return
+        const cmd = resolveCommand(argv)
+        let latest = typeof cache?.latest === 'string' ? cache.latest : null
+
+        if (stale) {
+          const fetched = fetchPromise ? await fetchPromise : null
+          const next = { checkedAt: new Date(now()).toISOString() }
+          if (fetched) {
+            next.latest = fetched
+            latest = fetched
+          } else if (latest) {
+            next.latest = latest
+          }
+          try {
+            writeCache(home, next)
+          } catch {
+            /* a read-only home must not change the command's exit code */
+          }
+        }
+
+        if (!printed && needsNudge({ cmd, version, latest, home })) {
+          printed = true
+          stderr.write(NUDGE)
+        }
+      } catch {
+        /* a failed lookup must not change the command's exit code */
+      }
+    },
+  }
+}

package/lib/update-check.test.mjs

@@ -0,0 +1,270 @@
+import assert from 'node:assert/strict'
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { mkdtempSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { spawnSync } from 'node:child_process'
+import test from 'node:test'
+import { userSkillDirs } from './agent-contract.mjs'
+import { CLI_VERSION } from './version.mjs'
+import {
+  compareVersions,
+  shouldCheck,
+  skillStale,
+  startUpdateCheck,
+} from './update-check.mjs'
+
+const NUDGE = 'Run: npx amorphous-cli@latest setup\n'
+
+test('compareVersions', () => {
+  assert.equal(compareVersions('1.0.0', '1.0.0'), 0)
+  assert.equal(compareVersions('1.0.0', '1.0.1'), -1)
+  assert.equal(compareVersions('1.1.0', '1.0.9'), 1)
+  assert.equal(compareVersions('2.0.0', '1.9.9'), 1)
+  assert.equal(compareVersions('1.0.0-beta', '1.0.0'), -1)
+  assert.equal(compareVersions('1.0.0-beta', '1.0.0-rc'), 0)
+  assert.equal(compareVersions('nope', '1.0.0'), null)
+})
+
+function cacheFile(home) {
+  return join(home, '.config', 'amorphous', 'update-check.json')
+}
+
+function writeCache(home, data) {
+  const dir = join(home, '.config', 'amorphous')
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(cacheFile(home), JSON.stringify(data) + '\n')
+}
+
+test('fresh cache nudges when cached latest is newer', async () => {
+  const home = mkdtempSync(join(tmpdir(), 'amorphous-uc-'))
+  const now = () => Date.parse('2026-01-01T12:00:00.000Z')
+  writeCache(home, { checkedAt: '2026-01-01T10:00:00.000Z', latest: '9.9.9' })
+  let fetchCalls = 0
+  let err = ''
+  const update = startUpdateCheck({
+    argv: ['list'],
+    env: {},
+    home,
+    version: '0.1.0',
+    now,
+    fetchLatest: async () => {
+      fetchCalls++
+      return '9.9.9'
+    },
+    stderr: { write: (s) => {
+      err += s
+    } },
+  })
+  await update.finish()
+  assert.equal(fetchCalls, 0)
+  assert.equal(err, NUDGE)
+})
+
+test('stale cache fetches and rewrites cache', async () => {
+  const home = mkdtempSync(join(tmpdir(), 'amorphous-uc-'))
+  const t0 = Date.parse('2026-01-01T00:00:00.000Z')
+  let nowMs = t0
+  writeCache(home, { checkedAt: '2025-01-01T00:00:00.000Z', latest: '0.1.0' })
+  let fetchCalls = 0
+  const update = startUpdateCheck({
+    argv: ['setup'],
+    env: {},
+    home,
+    version: CLI_VERSION,
+    now: () => nowMs,
+    fetchLatest: async () => {
+      fetchCalls++
+      return CLI_VERSION
+    },
+    stderr: { write: () => {} },
+  })
+  nowMs = t0 + 1000
+  await update.finish()
+  assert.equal(fetchCalls, 1)
+  const cache = JSON.parse(readFileSync(cacheFile(home), 'utf8'))
+  assert.equal(cache.latest, CLI_VERSION)
+  assert.ok(cache.checkedAt)
+})
+
+test('fetch failure keeps old latest and prints nothing', async () => {
+  const home = mkdtempSync(join(tmpdir(), 'amorphous-uc-'))
+  writeCache(home, { checkedAt: '2025-01-01T00:00:00.000Z', latest: '0.1.0' })
+  let err = ''
+  const update = startUpdateCheck({
+    argv: ['setup'],
+    env: {},
+    home,
+    version: CLI_VERSION,
+    now: () => Date.parse('2026-01-02T00:00:00.000Z'),
+    fetchLatest: async () => {
+      throw new Error('offline')
+    },
+    stderr: { write: (s) => {
+      err += s
+    } },
+  })
+  await update.finish()
+  assert.equal(err, '')
+  const cache = JSON.parse(readFileSync(cacheFile(home), 'utf8'))
+  assert.equal(cache.latest, '0.1.0')
+  assert.ok(cache.checkedAt)
+})
+
+test('corrupt cache triggers fetch', async () => {
+  const home = mkdtempSync(join(tmpdir(), 'amorphous-uc-'))
+  const dir = join(home, '.config', 'amorphous')
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(cacheFile(home), '{not json')
+  let fetchCalls = 0
+  const update = startUpdateCheck({
+    argv: ['setup'],
+    env: {},
+    home,
+    version: CLI_VERSION,
+    now: () => Date.now(),
+    fetchLatest: async () => {
+      fetchCalls++
+      return CLI_VERSION
+    },
+    stderr: { write: () => {} },
+  })
+  await update.finish()
+  assert.equal(fetchCalls, 1)
+})
+
+test('equal or newer running version stays quiet', async () => {
+  const home = mkdtempSync(join(tmpdir(), 'amorphous-uc-'))
+  writeCache(home, { checkedAt: new Date().toISOString(), latest: CLI_VERSION })
+  let err = ''
+  const update = startUpdateCheck({
+    argv: ['list'],
+    env: {},
+    home,
+    version: CLI_VERSION,
+    now: () => Date.now(),
+    fetchLatest: async () => '0.0.1',
+    stderr: { write: (s) => {
+      err += s
+    } },
+  })
+  await update.finish()
+  assert.equal(err, '')
+
+  writeCache(home, { checkedAt: new Date().toISOString(), latest: '0.1.0' })
+  err = ''
+  const update2 = startUpdateCheck({
+    argv: ['list'],
+    env: {},
+    home,
+    version: CLI_VERSION,
+    now: () => Date.now(),
+    fetchLatest: async () => '0.1.0',
+    stderr: { write: (s) => {
+      err += s
+    } },
+  })
+  await update2.finish()
+  assert.equal(err, '')
+})
+
+test('shouldCheck', () => {
+  const off = {}
+  assert.equal(shouldCheck([], off), false)
+  assert.equal(shouldCheck(['help'], off), false)
+  assert.equal(shouldCheck(['list', '--help'], off), false)
+  assert.equal(shouldCheck(['login', '-h'], off), false)
+  assert.equal(shouldCheck(['mcp'], off), false)
+  assert.equal(shouldCheck(['mcp', 'whatever'], off), false)
+  assert.equal(shouldCheck(['setup'], { CI: '1' }), false)
+  assert.equal(shouldCheck(['setup'], { AMORPHOUS_NO_UPDATE_CHECK: '1' }), false)
+  assert.equal(shouldCheck(['setup'], off), true)
+  assert.equal(shouldCheck(['grant'], off), true)
+})
+
+test('skillStale', () => {
+  const home = mkdtempSync(join(tmpdir(), 'amorphous-skill-stale-'))
+  assert.equal(skillStale(home, CLI_VERSION), false)
+
+  const [d0, d1] = userSkillDirs(home)
+  mkdirSync(d0, { recursive: true })
+  writeFileSync(join(d0, 'SKILL.md'), 'skill')
+  assert.equal(skillStale(home, CLI_VERSION), true)
+
+  writeFileSync(join(d0, '.amorphous-version'), '0.1.0\n')
+  assert.equal(skillStale(home, CLI_VERSION), true)
+
+  writeFileSync(join(d0, '.amorphous-version'), `${CLI_VERSION}\n`)
+  assert.equal(skillStale(home, CLI_VERSION), false)
+
+  writeFileSync(join(d0, '.amorphous-version'), 'not-a-version\n')
+  assert.equal(skillStale(home, CLI_VERSION), false)
+
+  mkdirSync(d1, { recursive: true })
+  writeFileSync(join(d1, 'SKILL.md'), 'skill')
+  writeFileSync(join(d1, '.amorphous-version'), '9.9.9\n')
+  assert.equal(skillStale(home, CLI_VERSION), false)
+
+  writeFileSync(join(d1, '.amorphous-version'), '0.1.0\n')
+  assert.equal(skillStale(home, CLI_VERSION), true)
+})
+
+test('setup skips skill stamp nudge when registry matches', async () => {
+  const home = mkdtempSync(join(tmpdir(), 'amorphous-uc-'))
+  const [d0] = userSkillDirs(home)
+  mkdirSync(d0, { recursive: true })
+  writeFileSync(join(d0, 'SKILL.md'), 'skill')
+  writeCache(home, { checkedAt: new Date().toISOString(), latest: CLI_VERSION })
+  let err = ''
+  const update = startUpdateCheck({
+    argv: ['setup'],
+    env: {},
+    home,
+    version: CLI_VERSION,
+    now: () => Date.now(),
+    fetchLatest: async () => CLI_VERSION,
+    stderr: { write: (s) => {
+      err += s
+    } },
+  })
+  await update.finish()
+  assert.equal(err, '')
+})
+
+test('non-setup nudges on stale skill when registry matches', async () => {
+  const home = mkdtempSync(join(tmpdir(), 'amorphous-uc-'))
+  const [d0] = userSkillDirs(home)
+  mkdirSync(d0, { recursive: true })
+  writeFileSync(join(d0, 'SKILL.md'), 'skill')
+  writeCache(home, { checkedAt: new Date().toISOString(), latest: CLI_VERSION })
+  let err = ''
+  const update = startUpdateCheck({
+    argv: ['list'],
+    env: {},
+    home,
+    version: CLI_VERSION,
+    now: () => Date.now(),
+    fetchLatest: async () => CLI_VERSION,
+    stderr: { write: (s) => {
+      err += s
+    } },
+  })
+  await update.finish()
+  assert.equal(err, NUDGE)
+})
+
+test('integration help skips update check file', () => {
+  const home = mkdtempSync(join(tmpdir(), 'amorphous-int-'))
+  const repoRoot = join(import.meta.dirname, '../..')
+  const env = { ...process.env, HOME: home, USERPROFILE: home }
+  delete env.AMORPHOUS_NO_UPDATE_CHECK
+  delete env.CI
+  const r = spawnSync(process.execPath, ['cli/index.mjs', '--help'], {
+    cwd: repoRoot,
+    env,
+    encoding: 'utf8',
+  })
+  assert.equal(r.status, 0)
+  assert.ok(!r.stderr.includes('Run: npx amorphous-cli@latest setup'))
+  assert.throws(() => readFileSync(cacheFile(home)), { code: 'ENOENT' })
+})

package/lib/version.mjs

@@ -0,0 +1,3 @@
+import { readFileSync } from 'node:fs'
+
+export const CLI_VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version

package/mcp.mjs

@@ -9,6 +9,7 @@ import { fileURLToPath } from 'node:url'
 import { McpServer } from '@modelcontextprotocol/server'
 import { serveStdio } from '@modelcontextprotocol/server/stdio'
 import { z } from 'zod'
+import { CLI_VERSION } from './lib/version.mjs'
 
 const cliPath = join(dirname(fileURLToPath(import.meta.url)), 'index.mjs')
 
@@ -49,7 +50,7 @@ async function call(args) {
 }
 
 await serveStdio(() => {
-  const server = new McpServer({ name: 'amorphous', version: '0.1.5' })
+  const server = new McpServer({ name: 'amorphous', version: CLI_VERSION })
 
   server.registerTool(
     'list',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amorphous-cli",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "mcpName": "io.github.amorphous-one/amorphous",
   "description": "Build abstracts on Amorphous. An abstract can be anything.",
   "type": "module",