@uzukko/agentpm 0.1.2 → 0.2.0

package/src/manifest-cache.ts

@@ -0,0 +1,208 @@
+/**
+ * Manifest cache management with ETag, atomic writes, and fallback chain.
+ */
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+import chalk from 'chalk'
+import { validateManifest, satisfiesVersion } from './manifest-validator.js'
+import { BUILTIN_MANIFEST } from './builtin-manifest.js'
+import type { Manifest } from './manifest-validator.js'
+
+const CACHE_DIR = join(homedir(), '.agentpm')
+const MANIFEST_PATH = join(CACHE_DIR, 'manifest.json')
+const PREV_PATH = join(CACHE_DIR, 'manifest.prev.json')
+const META_PATH = join(CACHE_DIR, 'manifest.meta.json')
+const TTL_MS = 24 * 60 * 60 * 1000 // 24 hours
+
+interface CacheMeta {
+  fetchedAt: string
+  version: string
+  etag?: string
+}
+
+// ── Meta helpers ──
+
+function readMeta(): CacheMeta | null {
+  try {
+    if (!existsSync(META_PATH)) return null
+    return JSON.parse(readFileSync(META_PATH, 'utf-8'))
+  } catch {
+    return null
+  }
+}
+
+function saveMeta(meta: CacheMeta): void {
+  mkdirSync(CACHE_DIR, { recursive: true, mode: 0o700 })
+  const tmpPath = `${META_PATH}.${process.pid}.tmp`
+  writeFileSync(tmpPath, JSON.stringify(meta), { mode: 0o600 })
+  renameSync(tmpPath, META_PATH)
+}
+
+function isFresh(meta: CacheMeta): boolean {
+  const fetchedAt = new Date(meta.fetchedAt).getTime()
+  return Date.now() - fetchedAt < TTL_MS
+}
+
+// ── Cache read/write ──
+
+function readAndValidateCache(path: string): Manifest | null {
+  try {
+    if (!existsSync(path)) return null
+    const raw = readFileSync(path, 'utf-8')
+    const parsed = JSON.parse(raw)
+    return validateManifest(parsed)
+  } catch {
+    return null // corrupted or validation failed
+  }
+}
+
+function atomicSaveCache(manifest: Manifest): void {
+  mkdirSync(CACHE_DIR, { recursive: true, mode: 0o700 })
+  const tmpPath = `${MANIFEST_PATH}.${process.pid}.tmp`
+  writeFileSync(tmpPath, JSON.stringify(manifest, null, 2), { mode: 0o600 })
+  // Backup current → prev
+  try {
+    renameSync(MANIFEST_PATH, PREV_PATH)
+  } catch {
+    /* first run — no existing cache */
+  }
+  // Atomic swap
+  renameSync(tmpPath, MANIFEST_PATH)
+}
+
+// ── Network fetch ──
+
+async function fetchFromServer(
+  apiUrl: string,
+  apiKey?: string,
+  etag?: string,
+): Promise<{ manifest?: unknown; etag?: string; notModified: boolean }> {
+  const headers: Record<string, string> = { Accept: 'application/json' }
+  if (apiKey) headers['Authorization'] = `Bearer ${apiKey}`
+  if (etag) headers['If-None-Match'] = etag
+
+  const url = `${apiUrl.replace(/\/$/, '')}/api/cli/manifest`
+  const res = await fetch(url, { headers, signal: AbortSignal.timeout(10_000) })
+
+  if (res.status === 304) {
+    return { etag, notModified: true }
+  }
+  if (!res.ok) {
+    throw new Error(`HTTP ${res.status}`)
+  }
+
+  const manifest = await res.json()
+  const newEtag = res.headers.get('etag') || undefined
+  return { manifest, etag: newEtag, notModified: false }
+}
+
+// ── Public API ──
+
+/**
+ * Load manifest with 5-level fallback chain:
+ * 1. Fresh cache → 2. Server fetch → 3. Expired cache → 4. Prev backup → 5. Builtin
+ */
+export async function loadManifest(
+  apiUrl: string,
+  apiKey?: string,
+  cliVersion?: string,
+): Promise<Manifest> {
+  const meta = readMeta()
+
+  // 1. Fresh cache
+  if (meta && isFresh(meta)) {
+    const cached = readAndValidateCache(MANIFEST_PATH)
+    if (cached) {
+      return applyVersionCheck(cached, cliVersion)
+    }
+  }
+
+  // 2. Server fetch (with ETag for efficiency)
+  try {
+    const result = await fetchFromServer(apiUrl, apiKey, meta?.etag)
+
+    if (result.notModified && meta) {
+      // 304: Just refresh TTL
+      saveMeta({ ...meta, fetchedAt: new Date().toISOString() })
+      const cached = readAndValidateCache(MANIFEST_PATH)
+      if (cached) return applyVersionCheck(cached, cliVersion)
+    }
+
+    if (result.manifest) {
+      const validated = validateManifest(result.manifest)
+      atomicSaveCache(validated)
+      saveMeta({
+        fetchedAt: new Date().toISOString(),
+        version: validated.version,
+        etag: result.etag,
+      })
+      return applyVersionCheck(validated, cliVersion)
+    }
+  } catch {
+    // Network error — fall through to cached fallbacks
+  }
+
+  // 3. Expired cache
+  const expired = readAndValidateCache(MANIFEST_PATH)
+  if (expired) {
+    console.error(chalk.yellow('Warning: Using cached manifest (server unreachable)'))
+    return applyVersionCheck(expired, cliVersion)
+  }
+
+  // 4. Previous backup
+  const prev = readAndValidateCache(PREV_PATH)
+  if (prev) {
+    console.error(chalk.yellow('Warning: Using previous manifest (cache corrupted)'))
+    return applyVersionCheck(prev, cliVersion)
+  }
+
+  // 5. Builtin
+  console.error(chalk.yellow('Warning: Using builtin commands (no manifest available)'))
+  return BUILTIN_MANIFEST
+}
+
+/**
+ * Force-fetch latest manifest (for `agentpm update`)
+ */
+export async function forceUpdate(
+  apiUrl: string,
+  apiKey?: string,
+): Promise<Manifest> {
+  const result = await fetchFromServer(apiUrl, apiKey)
+  if (!result.manifest) {
+    throw new Error('Server returned no manifest')
+  }
+  const validated = validateManifest(result.manifest)
+  atomicSaveCache(validated)
+  saveMeta({
+    fetchedAt: new Date().toISOString(),
+    version: validated.version,
+    etag: result.etag,
+  })
+  return validated
+}
+
+/**
+ * Version compatibility check.
+ * CLI < minCliVersion → always use builtin (incompatible manifest)
+ */
+function applyVersionCheck(manifest: Manifest, cliVersion?: string): Manifest {
+  if (!cliVersion) return manifest
+  if (!satisfiesVersion(cliVersion, manifest.minCliVersion)) {
+    console.error(
+      chalk.yellow(
+        `Warning: CLI v${cliVersion} は古いです。` +
+        `npm update -g @uzukko/agentpm でアップデートしてください`,
+      ),
+    )
+    return BUILTIN_MANIFEST
+  }
+  return manifest
+}

package/src/manifest-validator.ts

@@ -0,0 +1,216 @@
+/**
+ * Manifest schema validation + checksum verification
+ */
+import { createHash } from 'node:crypto'
+
+export interface ManifestOption {
+  flags: string
+  description?: string
+  param: string
+  required?: boolean
+  default?: string
+  type?: 'int' | 'float' | 'bool' | 'json' | 'string[]' | 'negatable'
+  choices?: string[]
+  resolve?: 'spaceId'
+  dependsOn?: string
+  conflictsWith?: string
+}
+
+export interface ManifestSubcommand {
+  name: string
+  description: string
+  aliases?: string[]
+  tool: string
+  examples?: string[]
+  deprecated?: boolean
+  hidden?: boolean
+  stdinMode?: boolean
+  options: ManifestOption[]
+}
+
+export interface ManifestCommand {
+  name: string
+  description: string
+  aliases?: string[]
+  tool?: string
+  options?: ManifestOption[]
+  subcommands?: ManifestSubcommand[]
+}
+
+export interface Manifest {
+  version: string
+  minCliVersion: string
+  generatedAt: string
+  checksum: string
+  commands: ManifestCommand[]
+}
+
+// Validation regex patterns
+const NAME_RE = /^[a-z][a-z0-9-]*$/
+const PARAM_RE = /^[a-zA-Z][a-zA-Z0-9]*$/
+const TOOL_RE = /^[a-z][a-z_]*$/
+const FLAGS_RE = /^(-[a-zA-Z],\s)?--[a-z][a-z0-9-]*(\s<[^>]+>)?$/
+
+/** Strip ANSI escape sequences and control characters */
+export function sanitize(str: string): string {
+  // eslint-disable-next-line no-control-regex
+  return str.replace(/[\x00-\x1f\x7f]|\x1b\[[0-9;]*[a-zA-Z]/g, '')
+}
+
+class ManifestValidationError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'ManifestValidationError'
+  }
+}
+
+function validateOption(opt: ManifestOption, path: string): void {
+  if (!opt.flags || typeof opt.flags !== 'string') {
+    throw new ManifestValidationError(`${path}: missing flags`)
+  }
+  // Allow --no-xxx negatable flags
+  const flagsToCheck = opt.type === 'negatable' ? opt.flags.replace('--no-', '--') : opt.flags
+  if (!FLAGS_RE.test(flagsToCheck)) {
+    throw new ManifestValidationError(`${path}: invalid flags format: ${opt.flags}`)
+  }
+  if (!opt.param || !PARAM_RE.test(opt.param)) {
+    throw new ManifestValidationError(`${path}: invalid param: ${opt.param}`)
+  }
+  if (opt.type && !['int', 'float', 'bool', 'json', 'string[]', 'negatable'].includes(opt.type)) {
+    throw new ManifestValidationError(`${path}: invalid type: ${opt.type}`)
+  }
+}
+
+function validateSubcommand(sub: ManifestSubcommand, path: string): void {
+  if (!sub.name || !NAME_RE.test(sub.name)) {
+    throw new ManifestValidationError(`${path}: invalid name: ${sub.name}`)
+  }
+  if (!sub.tool || !TOOL_RE.test(sub.tool)) {
+    throw new ManifestValidationError(`${path}: invalid tool: ${sub.tool}`)
+  }
+  if (!sub.description || typeof sub.description !== 'string') {
+    throw new ManifestValidationError(`${path}: missing description`)
+  }
+  if (!Array.isArray(sub.options)) {
+    throw new ManifestValidationError(`${path}: options must be an array`)
+  }
+  for (let i = 0; i < sub.options.length; i++) {
+    validateOption(sub.options[i], `${path}.options[${i}]`)
+  }
+}
+
+function validateCommand(cmd: ManifestCommand, path: string): void {
+  if (!cmd.name || !NAME_RE.test(cmd.name)) {
+    throw new ManifestValidationError(`${path}: invalid name: ${cmd.name}`)
+  }
+  if (!cmd.description || typeof cmd.description !== 'string') {
+    throw new ManifestValidationError(`${path}: missing description`)
+  }
+
+  // Top-level command with direct tool (e.g., dashboard)
+  if (cmd.tool) {
+    if (!TOOL_RE.test(cmd.tool)) {
+      throw new ManifestValidationError(`${path}: invalid tool: ${cmd.tool}`)
+    }
+    if (cmd.options) {
+      for (let i = 0; i < cmd.options.length; i++) {
+        validateOption(cmd.options[i], `${path}.options[${i}]`)
+      }
+    }
+  }
+
+  // Command with subcommands
+  if (cmd.subcommands) {
+    if (!Array.isArray(cmd.subcommands)) {
+      throw new ManifestValidationError(`${path}: subcommands must be an array`)
+    }
+    for (let i = 0; i < cmd.subcommands.length; i++) {
+      validateSubcommand(cmd.subcommands[i], `${path}.subcommands[${i}]`)
+    }
+  }
+
+  if (!cmd.tool && !cmd.subcommands) {
+    throw new ManifestValidationError(`${path}: must have either tool or subcommands`)
+  }
+}
+
+function verifyChecksum(manifest: Manifest): boolean {
+  const expected = manifest.checksum
+  if (!expected || !expected.startsWith('sha256:')) return false
+  const computed = createHash('sha256').update(JSON.stringify(manifest.commands)).digest('hex')
+  return expected === `sha256:${computed}`
+}
+
+/**
+ * Validate a parsed manifest object.
+ * Returns the typed manifest or throws ManifestValidationError.
+ */
+export function validateManifest(raw: unknown): Manifest {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new ManifestValidationError('Manifest must be a JSON object')
+  }
+
+  const m = raw as Record<string, unknown>
+
+  if (typeof m.version !== 'string') {
+    throw new ManifestValidationError('Missing version')
+  }
+  if (typeof m.minCliVersion !== 'string') {
+    throw new ManifestValidationError('Missing minCliVersion')
+  }
+  if (!Array.isArray(m.commands)) {
+    throw new ManifestValidationError('Missing commands array')
+  }
+
+  const manifest = raw as Manifest
+
+  // Checksum verification (corruption detection)
+  // Empty checksum is allowed for builtin manifest only (version '0.0.0-builtin')
+  if (manifest.checksum) {
+    if (!verifyChecksum(manifest)) {
+      throw new ManifestValidationError('Checksum mismatch — manifest may be corrupted')
+    }
+  } else if (manifest.version !== '0.0.0-builtin') {
+    throw new ManifestValidationError('Missing checksum — manifest integrity cannot be verified')
+  }
+
+  // Validate each command
+  for (let i = 0; i < manifest.commands.length; i++) {
+    validateCommand(manifest.commands[i], `commands[${i}]`)
+  }
+
+  // Sanitize display strings
+  for (const cmd of manifest.commands) {
+    cmd.description = sanitize(cmd.description)
+    if (cmd.subcommands) {
+      for (const sub of cmd.subcommands) {
+        sub.description = sanitize(sub.description)
+        if (sub.examples) {
+          sub.examples = sub.examples.map(sanitize)
+        }
+        for (const opt of sub.options) {
+          if (opt.description) opt.description = sanitize(opt.description)
+        }
+      }
+    }
+    if (cmd.options) {
+      for (const opt of cmd.options) {
+        if (opt.description) opt.description = sanitize(opt.description)
+      }
+    }
+  }
+
+  return manifest
+}
+
+/**
+ * Compare semver strings: returns true if current >= required
+ */
+export function satisfiesVersion(current: string, required: string): boolean {
+  const parse = (v: string) => v.split('.').map(Number)
+  const [cMaj, cMin = 0, cPat = 0] = parse(current)
+  const [rMaj, rMin = 0, rPat = 0] = parse(required)
+  if (cMaj !== rMaj) return cMaj > rMaj
+  if (cMin !== rMin) return cMin > rMin
+  return cPat >= rPat
+}

package/README.md

@@ -1,161 +0,0 @@
-# AgentPM CLI
-
-Command-line client for [AgentPM](https://agentpm.app) — AI-first project management.
-
-[日本語はこちら](#日本語)
-
-## Installation
-
-```bash
-npm install -g @uzukko/agentpm
-```
-
-## Setup
-
-1. Create an account at [AgentPM](https://agentpm.app)
-2. Go to Settings → API Keys and generate a key
-3. Login via CLI:
-
-```bash
-agentpm login
-```
-
-## Usage
-
-```bash
-# List projects
-agentpm space list
-
-# List tasks
-agentpm task list --space-id <SPACE_ID>
-
-# Create a task
-agentpm task create --space-id <SPACE_ID> --title "Task title"
-
-# Get task details
-agentpm task get --id <TASK_ID>
-
-# Update task
-agentpm task update --id <TASK_ID> --status in_progress
-
-# Toss ball (change who needs to act next)
-agentpm ball toss --task-id <TASK_ID> --side client --reason "Please review"
-
-# Milestones
-agentpm milestone list --space-id <SPACE_ID>
-
-# Meetings
-agentpm meeting list --space-id <SPACE_ID>
-
-# Wiki
-agentpm wiki list --space-id <SPACE_ID>
-```
-
-Run `agentpm --help` for the full list of commands.
-
-## Configuration
-
-Saved in `~/.taskapprc.json`:
-
-```json
-{
-  "apiKey": "tsk_...",
-  "apiUrl": "https://agentpm.app",
-  "defaultSpaceId": "optional"
-}
-```
-
-Set `defaultSpaceId` to skip `--space-id` on every command.
-
-## Environment Variables
-
-Override config file settings:
-
-| Variable | Description |
-|----------|-------------|
-| `TASKAPP_API_KEY` | API Key |
-| `TASKAPP_API_URL` | API URL (default: https://agentpm.app) |
-| `TASKAPP_SPACE_ID` | Default Space ID |
-
----
-
-## 日本語
-
-AI ファーストのプロジェクト管理ツール [AgentPM](https://agentpm.app) のコマンドラインクライアントです。
-
-### インストール
-
-```bash
-npm install -g @uzukko/agentpm
-```
-
-### セットアップ
-
-1. [AgentPM](https://agentpm.app) でアカウント作成
-2. 設定 → APIキー管理 から API Key を発行
-3. CLI にログイン:
-
-```bash
-agentpm login
-```
-
-### 使い方
-
-```bash
-# プロジェクト一覧
-agentpm space list
-
-# タスク一覧
-agentpm task list --space-id <SPACE_ID>
-
-# タスク作成
-agentpm task create --space-id <SPACE_ID> --title "タスク名"
-
-# タスク詳細
-agentpm task get --id <TASK_ID>
-
-# タスク更新
-agentpm task update --id <TASK_ID> --status in_progress
-
-# ボール変更（次に誰がアクションすべきか）
-agentpm ball toss --task-id <TASK_ID> --side client --reason "確認お願いします"
-
-# マイルストーン一覧
-agentpm milestone list --space-id <SPACE_ID>
-
-# ミーティング一覧
-agentpm meeting list --space-id <SPACE_ID>
-
-# Wiki ページ一覧
-agentpm wiki list --space-id <SPACE_ID>
-```
-
-全コマンド一覧は `agentpm --help` で確認できます。
-
-### 設定ファイル
-
-`~/.taskapprc.json` に保存されます:
-
-```json
-{
-  "apiKey": "tsk_...",
-  "apiUrl": "https://agentpm.app",
-  "defaultSpaceId": "省略可"
-}
-```
-
-`defaultSpaceId` を設定すると `--space-id` の指定を省略できます。
-
-### 環境変数
-
-設定ファイルより優先されます:
-
-| 変数 | 説明 |
-|------|------|
-| `TASKAPP_API_KEY` | API Key |
-| `TASKAPP_API_URL` | API URL (デフォルト: https://agentpm.app) |
-| `TASKAPP_SPACE_ID` | デフォルト Space ID |
-
-## License
-
-MIT

package/dist/defaults.d.ts

@@ -1,4 +0,0 @@
-export declare const defaults: {
-    supabaseUrl: string;
-    supabaseServiceKey: string;
-};

package/dist/defaults.js

@@ -1,8 +0,0 @@
-// Built-in defaults for the CLI.
-// For npm publish builds, these are injected at build time via scripts/inject-defaults.sh.
-// Developers can override any value via env vars or ~/.taskapprc.json.
-export const defaults = {
-    supabaseUrl: process.env.TASKAPP_BUILTIN_SUPABASE_URL || '',
-    supabaseServiceKey: process.env.TASKAPP_BUILTIN_SUPABASE_SERVICE_KEY || '',
-};
-//# sourceMappingURL=defaults.js.map