agent-message 0.1.0

package/README.md

@@ -0,0 +1,227 @@
+# Agent Messenger
+
+Agent Messenger is a direct-message stack with three clients:
+- HTTP/SSE server (`server/`)
+- Web app (`web/`)
+- CLI (`cli/`)
+
+This README covers a Phase 7 quickstart for local development and local production-like testing.
+
+## Prerequisites
+
+- Go `1.26+`
+- Node.js `18+` and npm
+- Docker + Docker Compose (for PostgreSQL compose flow)
+
+## Server Quickstart
+
+### Option A: Local server with SQLite (default)
+
+```bash
+cd server
+go run .
+```
+
+Default server settings:
+- `SERVER_ADDR=:8080`
+- `DB_DRIVER=sqlite`
+- `SQLITE_DSN=./agent_messenger.sqlite`
+- `UPLOAD_DIR=./uploads`
+- `CORS_ALLOWED_ORIGINS=*`
+
+Example override:
+
+```bash
+cd server
+DB_DRIVER=sqlite SQLITE_DSN=./dev.sqlite UPLOAD_DIR=./uploads go run .
+```
+
+### Option B: Local production-like stack (Server + PostgreSQL)
+
+```bash
+docker compose up --build
+```
+
+This starts:
+- `postgres` on `localhost:5432`
+- `server` on `localhost:8080` with:
+  - `DB_DRIVER=postgres`
+  - `POSTGRES_DSN=postgres://agent:agent@postgres:5432/agent_messenger?sslmode=disable`
+
+To stop and remove containers:
+
+```bash
+docker compose down
+```
+
+To also remove persisted DB/uploads volumes:
+
+```bash
+docker compose down -v
+```
+
+## Web Quickstart
+
+```bash
+cd web
+npm ci
+npm run dev
+```
+
+In local dev, Vite proxies `/api/...` and `/static/uploads/...` to `http://localhost:8080`, so you usually do not need `VITE_API_BASE_URL`.
+If your API is on a different origin, set `VITE_API_BASE_URL`:
+
+```bash
+cd web
+VITE_API_BASE_URL=http://localhost:8080 npm run dev
+```
+
+When `VITE_API_BASE_URL` is set, requests become cross-origin and the server must allow that origin via `CORS_ALLOWED_ORIGINS`.
+
+Build check:
+
+```bash
+cd web
+npm run build
+```
+
+## Local Bundle Commands
+
+From the project root, you can start the SQLite-backed API server and the production-like local web gateway together:
+
+```bash
+./dev-up
+```
+
+This will:
+- build `web/dist`
+- build the Go server binary into `~/.agent-messenger/bin`
+- start the API on `127.0.0.1:18080`
+- start the local web gateway on `127.0.0.1:8788`
+
+To stop both processes:
+
+```bash
+./dev-stop
+```
+
+If you also want to start or stop the named tunnel that serves `https://agent.namjaeyoun.com`, use:
+
+```bash
+./dev-up --with-tunnel
+./dev-stop --with-tunnel
+```
+
+## npm Distribution (macOS)
+
+The repo now includes a publishable npm package surface for macOS (`arm64` and `x64`). The npm command keeps the existing CLI behavior and also adds local stack lifecycle commands:
+
+```bash
+agent-messenger start
+agent-messenger status
+agent-messenger stop
+```
+
+Default npm launcher ports:
+- API: `127.0.0.1:8080`
+- Web: `127.0.0.1:8788`
+
+You can override runtime location and ports when needed:
+
+```bash
+agent-messenger start --runtime-dir /tmp/agent-messenger --api-port 28080 --web-port 28788
+agent-messenger status --runtime-dir /tmp/agent-messenger --api-port 28080 --web-port 28788
+agent-messenger stop --runtime-dir /tmp/agent-messenger
+```
+
+When publishing, `npm pack` / `npm publish` will run the package `prepack` hook, which:
+- builds `web/dist`
+- bundles `deploy/agent_gateway.mjs`
+- cross-compiles macOS `arm64` and `x64` binaries for the Go CLI and API server into `npm/runtime/`
+
+You can run the same packaging step manually from the repo root:
+
+```bash
+npm run prepare:npm-bundle
+```
+
+PWA install:
+
+- Open the deployed web app in Safari on iPhone.
+- Use `Share -> Add to Home Screen`.
+- The app now ships with a web app manifest, service worker, and Apple touch icon so it can be installed like a standalone app.
+
+## Claude Code Skill
+
+Install the agent-messenger CLI skill to give Claude Code full knowledge of this project's CLI commands, flags, and json_render component catalog:
+
+```bash
+npx skills add https://github.com/siisee11/agent-messenger --skill agent-messenger-cli
+```
+
+## CLI Quickstart
+
+Run from `cli/` with optional `--server-url` override.
+
+```bash
+cd cli
+go run . --server-url http://localhost:8080 register alice 1234
+go run . --server-url http://localhost:8080 login alice 1234
+go run . profile list
+go run . profile switch alice
+```
+
+Common commands:
+
+```bash
+# Conversations
+go run . --server-url http://localhost:8080 ls
+go run . --server-url http://localhost:8080 open bob
+
+# Messaging
+go run . --server-url http://localhost:8080 send bob "hello"
+go run . --server-url http://localhost:8080 read bob --n 20
+go run . --server-url http://localhost:8080 edit 1 "edited text"
+go run . --server-url http://localhost:8080 delete 1
+
+# Reactions
+go run . --server-url http://localhost:8080 react 1 👍
+go run . --server-url http://localhost:8080 unreact 1 👍
+
+# Realtime watch
+go run . --server-url http://localhost:8080 watch bob
+```
+
+CLI config is stored at `~/.agent-messenger/config` by default.
+Each successful `login` or `register` also saves a named profile, and `go run . profile switch <username>` swaps the active account locally.
+
+## Validation and Constraints (Phase 7)
+
+- Username identity fields: `3-32` chars, allowed `[A-Za-z0-9._-]`
+- PIN: `4-6` numeric digits
+- Uploads:
+  - max file size: `20 MB`
+  - unsupported file types are rejected
+
+## Dev Checks
+
+Server:
+
+```bash
+cd server
+go test ./...
+```
+
+CLI:
+
+```bash
+cd cli
+go test ./...
+```
+
+Web:
+
+```bash
+cd web
+npm run build
+```

package/npm/bin/agent-messenger.mjs

@@ -0,0 +1,386 @@
+#!/usr/bin/env node
+
+import { spawn, spawnSync } from 'node:child_process'
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { access, constants } from 'node:fs/promises'
+import os from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import process from 'node:process'
+import { fileURLToPath } from 'node:url'
+
+const DEFAULT_API_HOST = '127.0.0.1'
+const DEFAULT_API_PORT = 8080
+const DEFAULT_WEB_HOST = '127.0.0.1'
+const DEFAULT_WEB_PORT = 8788
+const STARTUP_ATTEMPTS = 40
+const STARTUP_DELAY_MS = 500
+const PROCESS_STOP_DELAY_MS = 1000
+
+const scriptDir = dirname(fileURLToPath(import.meta.url))
+const packageRoot = resolve(scriptDir, '..', '..')
+const bundleRoot = resolve(packageRoot, 'npm', 'runtime')
+const bundleBinDir = join(bundleRoot, 'bin')
+const bundleGatewayPath = join(bundleRoot, 'agent_gateway.mjs')
+const bundleWebDistDir = join(bundleRoot, 'web-dist')
+
+const lifecycleCommands = new Set(['start', 'stop', 'status'])
+
+async function main() {
+  const [command, ...rest] = process.argv.slice(2)
+  if (!command) {
+    printRootUsage()
+    process.exit(1)
+  }
+
+  if (command === '--help' || command === '-h' || command === 'help') {
+    printRootUsage()
+    return
+  }
+
+  if (lifecycleCommands.has(command)) {
+    const options = parseLifecycleOptions(rest)
+    await ensureBundleReady()
+
+    if (command === 'start') {
+      await startStack(options)
+      return
+    }
+    if (command === 'stop') {
+      await stopStack(options, { quiet: false })
+      return
+    }
+    await printStatus(options)
+    return
+  }
+
+  await ensureBundleReady()
+  delegateToBundledCli([command, ...rest])
+}
+
+function printRootUsage() {
+  console.error(`Usage:
+  agent-messenger start [--runtime-dir <dir>] [--api-host <host>] [--api-port <port>] [--web-host <host>] [--web-port <port>]
+  agent-messenger stop [--runtime-dir <dir>]
+  agent-messenger status [--runtime-dir <dir>] [--api-host <host>] [--api-port <port>] [--web-host <host>] [--web-port <port>]
+  agent-messenger <existing-cli-command> [...args]`)
+}
+
+function parseLifecycleOptions(args) {
+  const options = {
+    runtimeDir: join(os.homedir(), '.agent-messenger'),
+    apiHost: DEFAULT_API_HOST,
+    apiPort: DEFAULT_API_PORT,
+    webHost: DEFAULT_WEB_HOST,
+    webPort: DEFAULT_WEB_PORT,
+  }
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index]
+    if (arg === '--help' || arg === '-h') {
+      printRootUsage()
+      process.exit(0)
+    }
+
+    if (arg === '--runtime-dir') {
+      options.runtimeDir = requireOptionValue(args, ++index, arg)
+      continue
+    }
+    if (arg === '--api-host') {
+      options.apiHost = requireOptionValue(args, ++index, arg)
+      continue
+    }
+    if (arg === '--web-host') {
+      options.webHost = requireOptionValue(args, ++index, arg)
+      continue
+    }
+    if (arg === '--api-port') {
+      options.apiPort = parsePort(requireOptionValue(args, ++index, arg), arg)
+      continue
+    }
+    if (arg === '--web-port') {
+      options.webPort = parsePort(requireOptionValue(args, ++index, arg), arg)
+      continue
+    }
+
+    throw new Error(`unknown option: ${arg}`)
+  }
+
+  return options
+}
+
+function requireOptionValue(args, index, flag) {
+  const value = args[index]
+  if (!value || value.startsWith('-')) {
+    throw new Error(`missing value for ${flag}`)
+  }
+  return value
+}
+
+function parsePort(value, flag) {
+  const parsed = Number(value)
+  if (!Number.isInteger(parsed) || parsed <= 0 || parsed > 65535) {
+    throw new Error(`invalid port for ${flag}: ${value}`)
+  }
+  return parsed
+}
+
+async function ensureBundleReady() {
+  const requiredPaths = [
+    bundleGatewayPath,
+    bundleWebDistDir,
+    resolveBinaryPath('agent-messenger-server'),
+    resolveBinaryPath('agent-messenger-cli'),
+  ]
+
+  for (const target of requiredPaths) {
+    if (!existsSync(target)) {
+      throw new Error(
+        `npm bundle is incomplete: missing ${target}. Run "npm run prepare:npm-bundle" before packing or publishing.`,
+      )
+    }
+  }
+
+  await access(resolveBinaryPath('agent-messenger-server'), constants.X_OK)
+  await access(resolveBinaryPath('agent-messenger-cli'), constants.X_OK)
+}
+
+function resolveBinaryPath(baseName) {
+  if (process.platform !== 'darwin') {
+    throw new Error(`unsupported platform: ${process.platform}. This package currently supports macOS only.`)
+  }
+
+  let archSuffix
+  if (process.arch === 'arm64') {
+    archSuffix = 'darwin-arm64'
+  } else if (process.arch === 'x64') {
+    archSuffix = 'darwin-amd64'
+  } else {
+    throw new Error(`unsupported architecture: ${process.arch}. Expected arm64 or x64 on macOS.`)
+  }
+
+  return join(bundleBinDir, `${baseName}-${archSuffix}`)
+}
+
+function runtimePaths(runtimeDir) {
+  return {
+    runtimeDir,
+    logDir: join(runtimeDir, 'logs'),
+    uploadDir: join(runtimeDir, 'uploads'),
+    serverLog: join(runtimeDir, 'logs', 'server.log'),
+    gatewayLog: join(runtimeDir, 'logs', 'gateway.log'),
+    serverPidfile: join(runtimeDir, 'server.pid'),
+    gatewayPidfile: join(runtimeDir, 'gateway.pid'),
+    sqlitePath: join(runtimeDir, 'agent_messenger.sqlite'),
+  }
+}
+
+async function startStack(options) {
+  const paths = runtimePaths(options.runtimeDir)
+  mkdirSync(paths.runtimeDir, { recursive: true })
+  mkdirSync(paths.logDir, { recursive: true })
+  mkdirSync(paths.uploadDir, { recursive: true })
+
+  await stopStack(options, { quiet: true })
+
+  writeFileSync(paths.serverLog, '')
+  writeFileSync(paths.gatewayLog, '')
+
+  const serverBinary = resolveBinaryPath('agent-messenger-server')
+  const gatewayChild = { pid: null }
+
+  try {
+    const serverChild = spawnDetached(serverBinary, [], {
+      ...process.env,
+      SERVER_ADDR: `${options.apiHost}:${options.apiPort}`,
+      DB_DRIVER: 'sqlite',
+      SQLITE_DSN: paths.sqlitePath,
+      UPLOAD_DIR: paths.uploadDir,
+      CORS_ALLOWED_ORIGINS: '*',
+    }, paths.serverLog)
+    writeFileSync(paths.serverPidfile, `${serverChild.pid}\n`)
+
+    await waitForHttp(`http://${options.apiHost}:${options.apiPort}/healthz`, 'API server')
+
+    gatewayChild.pid = spawnDetached(
+      process.execPath,
+      [bundleGatewayPath],
+      {
+        ...process.env,
+        AGENT_GATEWAY_HOST: options.webHost,
+        AGENT_GATEWAY_PORT: String(options.webPort),
+        AGENT_API_ORIGIN: `http://${options.apiHost}:${options.apiPort}`,
+        AGENT_WEB_DIST: bundleWebDistDir,
+      },
+      paths.gatewayLog,
+    ).pid
+    writeFileSync(paths.gatewayPidfile, `${gatewayChild.pid}\n`)
+
+    await waitForHttp(`http://${options.webHost}:${options.webPort}`, 'web gateway')
+  } catch (error) {
+    await stopStack(options, { quiet: true })
+    throw error
+  }
+
+  console.log('Agent Messenger is up.')
+  console.log(`API:  http://${options.apiHost}:${options.apiPort}`)
+  console.log(`Web:  http://${options.webHost}:${options.webPort}`)
+  console.log(`Logs: ${paths.serverLog} ${paths.gatewayLog}`)
+}
+
+async function stopStack(options, { quiet }) {
+  const paths = runtimePaths(options.runtimeDir)
+  const stoppedServer = await killFromPidfile(paths.serverPidfile)
+  const stoppedGateway = await killFromPidfile(paths.gatewayPidfile)
+
+  if (!quiet) {
+    if (stoppedServer || stoppedGateway) {
+      console.log('Agent Messenger is stopped.')
+    } else {
+      console.log('Agent Messenger is not running.')
+    }
+  }
+}
+
+async function printStatus(options) {
+  const paths = runtimePaths(options.runtimeDir)
+  const serverPid = readPidfile(paths.serverPidfile)
+  const gatewayPid = readPidfile(paths.gatewayPidfile)
+  const serverRunning = serverPid !== null && isPidAlive(serverPid)
+  const gatewayRunning = gatewayPid !== null && isPidAlive(gatewayPid)
+  const apiHealthy = serverRunning ? await isHttpReady(`http://${options.apiHost}:${options.apiPort}/healthz`) : false
+  const webHealthy = gatewayRunning ? await isHttpReady(`http://${options.webHost}:${options.webPort}`) : false
+
+  console.log(`API server: ${serverRunning ? 'running' : 'stopped'}${apiHealthy ? ' (healthy)' : ''}`)
+  console.log(`Web gateway: ${gatewayRunning ? 'running' : 'stopped'}${webHealthy ? ' (healthy)' : ''}`)
+  console.log(`Runtime dir: ${paths.runtimeDir}`)
+  console.log(`API URL: http://${options.apiHost}:${options.apiPort}`)
+  console.log(`Web URL: http://${options.webHost}:${options.webPort}`)
+}
+
+function delegateToBundledCli(args) {
+  const cliBinary = resolveBinaryPath('agent-messenger-cli')
+  const result = spawnSync(cliBinary, args, {
+    stdio: 'inherit',
+    env: process.env,
+  })
+
+  if (result.error) {
+    throw result.error
+  }
+
+  if (result.signal) {
+    process.kill(process.pid, result.signal)
+    return
+  }
+
+  process.exit(result.status ?? 1)
+}
+
+function spawnDetached(command, args, env, logFile) {
+  const stdoutFd = openSync(logFile, 'a')
+  const stderrFd = openSync(logFile, 'a')
+
+  try {
+    const child = spawn(command, args, {
+      detached: true,
+      stdio: ['ignore', stdoutFd, stderrFd],
+      env,
+    })
+    child.unref()
+
+    if (!Number.isInteger(child.pid) || child.pid <= 0) {
+      throw new Error(`failed to launch background process: ${command}`)
+    }
+    return { pid: child.pid }
+  } finally {
+    closeSync(stdoutFd)
+    closeSync(stderrFd)
+  }
+}
+
+function readPidfile(pidfile) {
+  if (!existsSync(pidfile)) {
+    return null
+  }
+
+  const raw = readFileSync(pidfile, 'utf8').trim()
+  const pid = Number(raw)
+  if (!Number.isInteger(pid) || pid <= 0) {
+    rmSync(pidfile, { force: true })
+    return null
+  }
+  return pid
+}
+
+function isPidAlive(pid) {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (error) {
+    if (error && typeof error === 'object' && 'code' in error && error.code === 'ESRCH') {
+      return false
+    }
+    return true
+  }
+}
+
+async function killFromPidfile(pidfile) {
+  const pid = readPidfile(pidfile)
+  if (pid === null) {
+    return false
+  }
+
+  if (isPidAlive(pid)) {
+    safeKill(pid, 'SIGTERM')
+    await sleep(PROCESS_STOP_DELAY_MS)
+    if (isPidAlive(pid)) {
+      safeKill(pid, 'SIGKILL')
+    }
+  }
+
+  rmSync(pidfile, { force: true })
+  return true
+}
+
+async function waitForHttp(url, label) {
+  for (let attempt = 0; attempt < STARTUP_ATTEMPTS; attempt += 1) {
+    if (await isHttpReady(url)) {
+      return
+    }
+    await sleep(STARTUP_DELAY_MS)
+  }
+  throw new Error(`${label} did not become ready: ${url}`)
+}
+
+async function isHttpReady(url) {
+  try {
+    const controller = new AbortController()
+    const timeout = setTimeout(() => controller.abort(), 1000)
+    const response = await fetch(url, { signal: controller.signal })
+    clearTimeout(timeout)
+    return response.ok
+  } catch {
+    return false
+  }
+}
+
+function sleep(ms) {
+  return new Promise((resolvePromise) => {
+    setTimeout(resolvePromise, ms)
+  })
+}
+
+function safeKill(pid, signal) {
+  try {
+    process.kill(pid, signal)
+  } catch (error) {
+    if (!(error && typeof error === 'object' && 'code' in error && error.code === 'ESRCH')) {
+      throw error
+    }
+  }
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error))
+  process.exit(1)
+})