aweshare 0.2.2 → 0.2.4

package/README.md

@@ -1,13 +1,33 @@
 <div align="center">
-
-  <img src="logo/logo.webp" alt="aweshare" width="860">
-
-# aweshare
-
-**Open-source, local-first AI capability relay**
-
-**English** · [简体中文](./README_cn.md)
-
+  <img src="./logo/logo.png" alt="aweshare" width="760">
+  <h1>aweshare: Local-first AI Capability Relay</h1>
+  <p><strong>An open-source, local-first AI capability relay.</strong></p>
+  <p>Share local Ollama/vLLM or authorized OpenAI/Anthropic backends through a grant-based hub, consumed with standard SDKs via <code>namespace/alias</code>.</p>
+  <p><strong>Upstream API keys never leave the producer's device.</strong></p>
+  <p>
+    <strong>English</strong> ·
+    <a href="./README_cn.md">简体中文</a> ·
+    <a href="https://www.npmjs.com/package/aweshare">npm</a> ·
+    <a href="https://github.com/wehuman01/aweshare">GitHub</a>
+  </p>
+  <p>
+    <a href="https://ko-fi.com/mugpeng"><img src="https://img.shields.io/badge/Ko--fi-Buy%20me%20a%20coffee-FF5E5B?style=flat-square&logo=ko-fi&logoColor=white" alt="Ko-fi"></a>
+  </p>
+  <p>
+    <a href="https://github.com/wehuman01/aweshare-source/releases"><img src="https://img.shields.io/badge/version-0.2.4-7C3AED?style=flat-square" alt="Version"></a>
+    <a href="https://github.com/wehuman01/aweshare"><img src="https://img.shields.io/badge/node-%E2%89%A522-0EA5E9?style=flat-square" alt="Node"></a>
+    <a href="https://github.com/wehuman01/aweshare/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-22C55E?style=flat-square" alt="License"></a>
+    <a href="https://www.npmjs.com/package/aweshare"><img src="https://img.shields.io/badge/npm-aweshare-7C3AED?style=flat-square" alt="npm package"></a>
+  </p>
+  <p>
+    <img src="https://img.shields.io/badge/status-beta-c96a3d?style=flat-square" alt="Status">
+    <img src="https://img.shields.io/badge/docker-ghcr.io%2Fwehuman01%2Faweshare-2496ED?style=flat-square&logo=docker" alt="Docker image">
+    <img src="https://img.shields.io/badge/protocol-OpenAI%20%7C%20Anthropic-0ea5a4?style=flat-square" alt="Protocols">
+    <img src="https://img.shields.io/badge/platform-docker%20%7C%20npm%20%7C%20node-334155?style=flat-square" alt="Platform">
+    <img src="https://img.shields.io/npm/dt/aweshare?style=flat-square" alt="npm downloads">
+    <img src="https://img.shields.io/github/stars/wehuman01/aweshare?style=flat-square" alt="GitHub stars">
+    <img src="https://img.shields.io/badge/deploy-self%20hosted-334155?style=flat-square" alt="Self hosted">
+  </p>
 </div>
 
 Producers run a lightweight agent on their own machine and share local Ollama/vLLM or **authorized** OpenAI/Anthropic backends. Upstream API keys live only on the producer's device and are injected by the local agent at forwarding time. Consumers point a standard OpenAI/Anthropic SDK at the hub and call models by `namespace/alias` — exactly like using any other model vendor.
@@ -212,9 +232,12 @@ Usage metering: one row per request (alias, real model, status, duration, byte c
 | `AWESHARE_CONSUMER_RPS` / `BURST` / `CONCURRENCY` | 10 / 20 / 8 | per-consumer limits |
 | `AWESHARE_HEAD_TIMEOUT_MS` / `IDLE_TIMEOUT_MS` | 120000 / 300000 | response-head timeout / stream idle timeout |
 | `AWESHARE_MAX_BODY_BYTES` | 32MB | request body cap |
+| `AWESHARE_NO_UPDATE_CHECK` | unset | set to `1` to disable the passive update reminder |
 
 Health: agent heartbeats every 15s, silent 45s = dead; backends with 2 consecutive AUTH/QUOTA failures auto-degrade (alias shows `degraded`, dispatch stops), 30s probes recover. A new connection with the same producer token replaces the old one (latest-wins).
 
+Updating a npm install: `aweshare self-update` (asks before installing; `--check` only shows versions). The CLI also reminds you at most once a day when a newer npm release exists.
+
 ## Development
 
 ```bash
@@ -232,7 +255,7 @@ aweshare hub serve
 aweshare agent doctor
 ```
 
-Releasing: push a `v*` tag with a matching `## [x.y.z]` section in `docs/CHANGELOG.md`; CI publishes the `aweshare` package to npm via Trusted Publishing (OIDC, no token secret) and the Docker image to `ghcr.io/wehuman01/aweshare`.
+Releasing: push a `v*` tag with a matching `## [x.y.z]` section in `docs/CHANGELOG.md`; CI publishes the `aweshare` package to npm via Trusted Publishing (OIDC, no token secret), pushes the Docker image to `ghcr.io/wehuman01/aweshare`, and mirrors user-facing docs to the public repo (`wehuman01/aweshare`).
 
 Layout: `packages/protocol` (shared wire protocol) · `apps/hub` (HTTP+WS+SQLite+CLI) · `apps/agent` (CLI). Design docs live in `docs/specs/`; the changelog in `docs/CHANGELOG.md`; contribution scope in [CONTRIBUTING.md](./CONTRIBUTING.md).
 

package/bin/aweshare.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
-// Umbrella CLI: `aweshare hub ...` / `aweshare agent ...`.
+// Umbrella CLI: `aweshare hub ...` / `aweshare agent ...` / `aweshare self-update`.
 // Dev convenience — the real entry points live in apps/hub and apps/agent.
 import { readFileSync } from 'node:fs'
+import { maybeCheckForUpdate, runSelfUpdate } from './self-update.mjs'
 
 const [, , cmd, ...rest] = process.argv
 
@@ -22,22 +23,33 @@ async function main() {
 Usage:
   aweshare hub <command>      hub side: init, serve, token, grant, consumer, usage
   aweshare agent <command>    producer side: init, start, doctor, grant, revoke, list
+  aweshare self-update [--check]   update the aweshare CLI itself (npm registry)
+
+Environment:
+  AWESHARE_NO_UPDATE_CHECK=1  disable the passive update reminder
 
 Install (published):  npm install -g aweshare
 From source:          pnpm install && pnpm build, then pnpm link --global`)
     return
   }
+  if (cmd === 'self-update') {
+    await runSelfUpdate(rest)
+    return
+  }
   const target = Object.hasOwn(routes, cmd) ? routes[cmd] : undefined
   if (!target) {
-    console.error(`unknown target '${cmd}' — expected 'hub' or 'agent'`)
+    console.error(`unknown target '${cmd}' — expected 'hub', 'agent' or 'self-update'`)
     process.exitCode = 1
     return
   }
+  const reminder = maybeCheckForUpdate(process.argv.slice(2)).catch(() => null)
   process.argv = [process.argv[0], `aweshare-${cmd}`, ...rest]
   await import(target)
+  const message = await reminder
+  if (message) console.error(message)
 }
 
 main().catch((err) => {
-  console.error(err instanceof Error ? err.stack ?? err.message : err)
+  console.error(`error: ${err instanceof Error ? err.message : err}`)
   process.exit(1)
 })

package/bin/self-update.mjs

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+// `aweshare self-update` — update the npm-installed aweshare CLI in place.
+// Also exports the passive update reminder used by the umbrella CLI.
+// Plain Node, no dependencies: this file ships in the tarball as-is.
+import { execFile } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import path from 'node:path'
+import { createInterface } from 'node:readline'
+import { fileURLToPath } from 'node:url'
+
+const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+  .version
+
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000
+const REMIND_INTERVAL_MS = 24 * 60 * 60 * 1000
+
+function runCommand(command, args, { cwd, timeout = 120_000 } = {}) {
+  return new Promise((resolve, reject) => {
+    // npm ships as npm.cmd on Windows. Node 20+ (CVE-2024-27980) refuses to
+    // spawn .cmd/.bat shims without a shell, so the whole self-update flow
+    // fails on Windows unless we route through one.
+    execFile(
+      command,
+      args,
+      { timeout, cwd, shell: process.platform === 'win32' },
+      (error, stdout, stderr) => {
+        if (error) {
+          reject(new Error(stderr.trim() || error.message))
+          return
+        }
+        resolve(stdout.trim())
+      },
+    )
+  })
+}
+
+export async function getNpmLatestVersion(run = runCommand) {
+  return run('npm', ['view', 'aweshare', 'version'], { timeout: 60_000 })
+}
+
+/** Ask a y/n question on the terminal. Empty answer means yes. */
+function confirm(question) {
+  return new Promise((resolve) => {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+      resolve(null)
+      return
+    }
+    const rl = createInterface({ input: process.stdin, output: process.stdout })
+    rl.question(`${question} (y/n) `, (answer) => {
+      rl.close()
+      const trimmed = answer.trim().toLowerCase()
+      resolve(trimmed === '' || trimmed === 'y' || trimmed === 'yes')
+    })
+  })
+}
+
+/**
+ * `aweshare self-update [--check]`.
+ * Throws on failure; the umbrella CLI reports and exits non-zero.
+ */
+export async function runSelfUpdate(args, { run = runCommand, confirmFn = confirm } = {}) {
+  const checkOnly = args.includes('--check')
+  const latest = await getNpmLatestVersion(run)
+
+  console.log(`current version: ${VERSION}`)
+  console.log(`latest version:  ${latest}`)
+
+  if (VERSION === latest) {
+    console.log('already up to date')
+    return
+  }
+  if (checkOnly) return
+
+  const ok = await confirmFn(`Update aweshare from ${VERSION} to ${latest}?`)
+  if (ok === null) {
+    throw new Error('stdin is not a terminal — run interactively, or use: npm install -g aweshare')
+  }
+  if (!ok) {
+    console.log('update cancelled')
+    return
+  }
+
+  console.log('updating via npm...')
+  await run('npm', ['install', '-g', 'aweshare'], { timeout: 300_000 })
+  console.log(`updated to ${latest} — run 'aweshare -v' to verify`)
+}
+
+/** Long-running or non-working commands never see the reminder. */
+export function shouldSkipUpdateCheck(argv) {
+  if (argv.length === 0) return true
+  const [cmd, sub] = argv
+  if (['help', '-h', '--help', '-v', '--version'].includes(cmd)) return true
+  if (cmd === 'self-update') return true
+  if ((cmd === 'hub' && sub === 'serve') || (cmd === 'agent' && sub === 'start')) return true
+  return false
+}
+
+function defaultCacheFile() {
+  return path.join(homedir(), '.cache', 'aweshare', 'update-check.json')
+}
+
+async function readJson(file) {
+  try {
+    return JSON.parse(await readFile(file, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+async function writeJson(file, data) {
+  try {
+    await mkdir(path.dirname(file), { recursive: true })
+    await writeFile(file, `${JSON.stringify(data, null, 2)}\n`)
+  } catch {
+    // a failed cache write must never break the command it decorates
+  }
+}
+
+/**
+ * Passive reminder: at most one npm lookup and one reminder per 24h.
+ * Returns the reminder text to print (on stderr) or null.
+ */
+export async function maybeCheckForUpdate(argv, { run = runCommand, cacheFile, now } = {}) {
+  if (process.env.AWESHARE_NO_UPDATE_CHECK === '1') return null
+  if (shouldSkipUpdateCheck(argv)) return null
+
+  cacheFile = cacheFile ?? defaultCacheFile()
+  now = now ?? Date.now()
+  let cache = await readJson(cacheFile)
+
+  let latest = null
+  if (cache && now - Date.parse(cache.lastChecked) < CHECK_INTERVAL_MS) {
+    latest = cache.latestVersion
+  } else {
+    try {
+      latest = await getNpmLatestVersion(run)
+    } catch {
+      return null
+    }
+    cache = {
+      lastChecked: new Date(now).toISOString(),
+      latestVersion: latest,
+      lastReminded: cache?.lastReminded ?? '',
+    }
+    await writeJson(cacheFile, cache)
+  }
+
+  if (!latest || latest === VERSION) return null
+
+  const lastRemindedMs = cache.lastReminded ? Date.parse(cache.lastReminded) : 0
+  if (now - lastRemindedMs < REMIND_INTERVAL_MS) return null
+
+  await writeJson(cacheFile, { ...cache, lastReminded: new Date(now).toISOString() })
+  return `Update available: ${VERSION} → ${latest}. Run \`aweshare self-update\` to update.`
+}
+
+// direct execution: `node bin/self-update.mjs --check`
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  runSelfUpdate(process.argv.slice(2)).catch((err) => {
+    console.error(`error: ${err instanceof Error ? err.message : String(err)}`)
+    process.exit(1)
+  })
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aweshare",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "type": "module",
   "description": "Open-source, local-first AI capability relay",
   "license": "MIT",
@@ -16,6 +16,7 @@
   },
   "files": [
     "bin",
+    "!bin/*.test.mjs",
     "apps/hub/dist",
     "apps/hub/package.json",
     "apps/agent/dist",