@raccolta/cli 0.1.1

package/README.md

@@ -0,0 +1,12 @@
+# Raccolta CLI
+
+Install:
+
+```powershell
+npm install -g @raccolta/cli
+rac login --endpoint https://api.raccolta.dev/api
+rac tasks
+```
+
+Create an API key in the dashboard under Settings > API. Keys use the
+`rac_` prefix and are stored locally in `~/.raccolta/config.json`.

package/bin/postinstall.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+const useColor = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR
+const green = (text) => (useColor ? `\x1b[32m${text}\x1b[0m` : text)
+const bold = (text) => (useColor ? `\x1b[1m${text}\x1b[0m` : text)
+const dim = (text) => (useColor ? `\x1b[2m${text}\x1b[0m` : text)
+
+console.log('')
+console.log(`${green('[ok]')} ${bold('Raccolta CLI installed')}`)
+console.log('')
+console.log('Next steps:')
+console.log(`  1. Create an API key in ${bold('Raccolta -> Settings -> API')}`)
+console.log(`  2. Run ${bold('rac login')}`)
+console.log(`  3. Run ${bold('rac tasks')}`)
+console.log('')
+console.log(dim('Docs: run rac help'))

package/bin/rac.js

@@ -0,0 +1,483 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import readline from 'node:readline/promises'
+import { stdin as input, stdout as output } from 'node:process'
+
+const VERSION = '0.1.1'
+const DEFAULT_ENDPOINT = 'https://api.raccolta.dev/api'
+const CONFIG_DIR = path.join(os.homedir(), '.raccolta')
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json')
+const INSTRUCTIONS_START = '<!-- RACCOLTA CLI INSTRUCTIONS START -->'
+const INSTRUCTIONS_END = '<!-- RACCOLTA CLI INSTRUCTIONS END -->'
+
+const COMMANDS = new Set(['login', 'tasks', 'whoami', 'logout', 'config', 'help'])
+const ANSI_RE = /\x1b\[[0-9;]*m/g
+const USE_COLOR = Boolean(output.isTTY) && !process.env.NO_COLOR
+const ANSI = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  gray: '\x1b[90m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+}
+
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error)
+  console.error(`Error: ${message}`)
+  process.exitCode = 1
+})
+
+async function main() {
+  const parsed = parseArgs(process.argv.slice(2))
+  const command = parsed.command || 'help'
+
+  if (parsed.flags.version) {
+    console.log(`rac ${VERSION}`)
+    return
+  }
+
+  if (parsed.flags.help || command === 'help') {
+    printHelp()
+    return
+  }
+
+  if (!COMMANDS.has(command)) {
+    throw new Error(`Unknown command "${command}". Run rac help.`)
+  }
+
+  if (command === 'login') return login(parsed)
+  if (command === 'tasks') return tasks(parsed)
+  if (command === 'whoami') return whoami()
+  if (command === 'logout') return logout()
+  if (command === 'config') return printConfig()
+}
+
+function parseArgs(argv) {
+  const flags = {}
+  const positionals = []
+  let command = ''
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+    if (!arg.startsWith('-') && !command) {
+      command = arg
+      continue
+    }
+    if (!arg.startsWith('-')) {
+      positionals.push(arg)
+      continue
+    }
+
+    const normalized = arg.replace(/^--?/, '')
+    const [rawKey, inlineValue] = normalized.split('=', 2)
+    const key = rawKey.replace(/-([a-z])/g, (_, char) => char.toUpperCase())
+    const takesValue = ['endpoint', 'key', 'limit'].includes(key)
+
+    if (takesValue) {
+      flags[key] = inlineValue ?? argv[++i]
+    } else {
+      flags[key] = true
+    }
+  }
+
+  return { command, flags, positionals }
+}
+
+function printHelp() {
+  console.log(`${style('Raccolta CLI', 'bold')} ${VERSION}
+
+Usage:
+  rac login [--endpoint https://api.raccolta.dev/api] [--key rac_...]
+  rac tasks [--limit 50]
+  rac whoami
+  rac logout
+
+Install:
+  npm install -g @raccolta/cli
+
+Create API keys in the dashboard under Settings > API.`)
+}
+
+async function login({ flags }) {
+  const existing = await readConfig().catch(() => null)
+  const rl = createReadline()
+  try {
+    console.log(style('Raccolta CLI Setup', 'bold'))
+    console.log('')
+
+    const endpointDefault = normalizeEndpoint(
+      flags.endpoint ||
+        process.env.RAC_ENDPOINT ||
+        process.env.RAC_API_URL ||
+        existing?.endpoint ||
+        DEFAULT_ENDPOINT,
+    )
+    const endpointInput = flags.endpoint
+      ? endpointDefault
+      : await ask(rl, `Endpoint (${endpointDefault}): `)
+    const endpoint = normalizeEndpoint(endpointInput || endpointDefault)
+
+    const apiKey =
+      flags.key ||
+      process.env.RAC_API_KEY ||
+      (await ask(rl, 'API key (from Settings > API): '))
+
+    if (!apiKey?.trim()) throw new Error('API key is required')
+    if (!apiKey.trim().startsWith('rac_')) throw new Error('Raccolta API keys must start with rac_')
+
+    console.log(`${style('[ok]', 'green')} Endpoint ${style(endpoint, 'dim')}`)
+    console.log(`${style('[ok]', 'green')} Validating API key...`)
+
+    const validation = await apiJson(endpoint, '/cli/auth/validate', apiKey.trim())
+    if (!validation?.ok) throw new Error('API key validation failed')
+
+    await writeConfig({
+      endpoint,
+      apiKey: apiKey.trim(),
+      profile: validation.profile,
+      workspace: validation.workspace,
+      updatedAt: new Date().toISOString(),
+    })
+
+    const profileName = validation.profile?.name || validation.profile?.email || validation.profile?.id || 'Raccolta user'
+    const workspaceName = validation.workspace?.name || 'Raccolta Workspace'
+    console.log(`${style('[ok]', 'green')} Connected profile ${profileName} to workspace ${workspaceName}`)
+
+    const shouldAppend =
+      flags.yes ||
+      (!flags.noInstructions &&
+        (await confirm(rl, 'Append agent instructions to CLAUDE.md and AGENTS.md in this directory?', true)))
+
+    if (shouldAppend) {
+      const written = await appendAgentInstructions(process.cwd(), validation.workspace)
+      for (const item of written) {
+        console.log(`${style('[ok]', 'green')} ${item.action} ${item.file}`)
+      }
+    }
+
+    console.log('')
+    console.log(`Next: run ${style('rac tasks', 'bold')} to see your tasks.`)
+  } finally {
+    rl.close()
+  }
+}
+
+async function tasks({ flags }) {
+  const config = await requireConfig()
+  const limit = parseLimit(flags.limit)
+  console.log(`${style('[ok]', 'green')} Fetching tasks...`)
+  const data = await apiJson(
+    config.endpoint,
+    `/cli/tasks?limit=${encodeURIComponent(String(limit))}`,
+    config.apiKey,
+  )
+
+  const workspaceName = data?.workspace?.name || config.workspace?.name || 'Raccolta Workspace'
+  const rows = Array.isArray(data?.tasks) ? data.tasks : []
+  console.log('')
+  console.log(style(`${workspaceName} Tasks`, 'bold'))
+  console.log('')
+
+  if (rows.length === 0) {
+    console.log(style('No tasks found.', 'dim'))
+    return
+  }
+
+  printTable(
+    rows.map((task) => ({
+      Code: task.code || '',
+      Title: task.title || '',
+      Status: task.status || '',
+      Priority: formatPriority(task.priority),
+      Agent: task.agent || 'None',
+    })),
+  )
+  console.log('')
+  console.log(style(`${rows.length} ${rows.length === 1 ? 'task' : 'tasks'}`, 'dim'))
+}
+
+async function whoami() {
+  const config = await requireConfig()
+  const validation = await apiJson(config.endpoint, '/cli/auth/validate', config.apiKey)
+  const profileName = validation.profile?.name || validation.profile?.email || validation.profile?.id || 'Raccolta user'
+  const workspaceName = validation.workspace?.name || 'Raccolta Workspace'
+  console.log(`Profile: ${profileName}`)
+  console.log(`Workspace: ${workspaceName}`)
+  console.log(`Endpoint: ${config.endpoint}`)
+}
+
+async function logout() {
+  await fs.rm(CONFIG_FILE, { force: true })
+  console.log('Removed local Raccolta CLI credentials.')
+}
+
+async function printConfig() {
+  const config = await readConfig().catch(() => null)
+  console.log(`Config file: ${CONFIG_FILE}`)
+  if (!config) {
+    console.log('Status: not logged in')
+    return
+  }
+  console.log(`Endpoint: ${config.endpoint}`)
+  console.log(`Workspace: ${config.workspace?.name || config.workspace?.id || 'Unknown'}`)
+  console.log(`Profile: ${config.profile?.name || config.profile?.email || config.profile?.id || 'Unknown'}`)
+}
+
+async function apiJson(endpoint, route, apiKey) {
+  const response = await fetch(`${endpoint}${route}`, {
+    method: 'GET',
+    headers: {
+      Accept: 'application/json',
+      Authorization: `Bearer ${apiKey}`,
+    },
+    signal: AbortSignal.timeout(20000),
+  })
+  const text = await response.text()
+  let payload = null
+  if (text) {
+    try {
+      payload = JSON.parse(text)
+    } catch {
+      payload = { error: text.slice(0, 300) }
+    }
+  }
+  if (!response.ok) {
+    if (response.status === 401 && route.startsWith('/cli/')) {
+      throw new Error('API key rejected. Create a fresh key in Raccolta Settings > API, then run rac login again. If the fresh key is rejected too, deploy the latest Beast backend.')
+    }
+    throw new Error(payload?.error || `Request failed with ${response.status}`)
+  }
+  return payload
+}
+
+function normalizeEndpoint(value) {
+  let endpoint = String(value || DEFAULT_ENDPOINT).trim()
+  if (!endpoint) endpoint = DEFAULT_ENDPOINT
+  if (!/^https?:\/\//i.test(endpoint)) endpoint = `https://${endpoint}`
+  endpoint = endpoint.replace(/\/+$/, '')
+  if (!endpoint.endsWith('/api')) endpoint = `${endpoint}/api`
+  return endpoint
+}
+
+function parseLimit(value) {
+  if (value == null || value === '') return 50
+  const parsed = Number.parseInt(value, 10)
+  if (!Number.isFinite(parsed) || parsed <= 0) throw new Error('limit must be a positive number')
+  return Math.min(parsed, 200)
+}
+
+function formatPriority(value) {
+  const text = String(value || '').trim().toLowerCase()
+  if (!text || text === 'none') return 'None'
+  return `${text.charAt(0).toUpperCase()}${text.slice(1)}`
+}
+
+function printTable(rows) {
+  const headers = Object.keys(rows[0] || {})
+  const widths = tableWidths(headers, rows)
+
+  console.log(formatRow(headers, headers, widths, true))
+  console.log(style(widths.map((width) => '-'.repeat(width)).join('  '), 'gray'))
+  for (const row of rows) {
+    console.log(formatRow(headers.map((header) => row[header] ?? ''), headers, widths))
+  }
+}
+
+function tableWidths(headers, rows) {
+  const terminalWidth = Math.max(72, Math.min(Number(output.columns || 100), 140))
+  const gapWidth = Math.max(0, headers.length - 1) * 2
+  const fixedHeaders = headers.filter((header) => header !== 'Title')
+  const fixedCaps = {
+    Code: 10,
+    Status: 14,
+    Priority: 10,
+    Agent: 14,
+  }
+  const fixedWidths = Object.fromEntries(
+    fixedHeaders.map((header) => {
+      const max = Math.max(
+        visibleWidth(header),
+        ...rows.map((row) => visibleWidth(String(row[header] ?? ''))),
+      )
+      return [header, Math.min(max, fixedCaps[header] || max)]
+    }),
+  )
+  const fixedTotal = Object.values(fixedWidths).reduce((sum, width) => sum + width, 0)
+  const titleMax = Math.max(24, terminalWidth - fixedTotal - gapWidth)
+  const titleContent = Math.max(
+    visibleWidth('Title'),
+    ...rows.map((row) => visibleWidth(String(row.Title ?? ''))),
+  )
+  const titleWidth = Math.min(titleContent, titleMax)
+
+  return headers.map((header) => (header === 'Title' ? titleWidth : fixedWidths[header] || visibleWidth(header)))
+}
+
+function formatRow(values, headers, widths, isHeader = false) {
+  return values
+    .map((value, index) => {
+      const header = headers[index]
+      const width = widths[index]
+      const text = truncateVisible(String(value), width)
+      const padded = padVisible(text, width)
+      return isHeader ? style(padded, 'dim') : styleTableCell(header, padded, value)
+    })
+    .join('  ')
+}
+
+function styleTableCell(header, padded, rawValue) {
+  const value = String(rawValue || '').trim().toLowerCase()
+  if (header === 'Status') {
+    if (value === 'shipped') return style(padded, 'green')
+    if (value === 'in progress') return style(padded, 'yellow')
+    if (value === 'todo') return style(padded, 'cyan')
+    if (value === 'declined' || value === 'archive' || value === 'archived') return style(padded, 'gray')
+    if (value === 'requests') return style(padded, 'blue')
+  }
+  if (header === 'Priority') {
+    if (value === 'urgent') return style(padded, 'red')
+    if (value === 'high') return style(padded, 'yellow')
+    if (value === 'medium') return style(padded, 'blue')
+    if (value === 'low') return style(padded, 'green')
+    if (value === 'none') return style(padded, 'dim')
+  }
+  if (header === 'Agent' && value === 'none') return style(padded, 'dim')
+  return padded
+}
+
+function style(text, color) {
+  if (!USE_COLOR || !ANSI[color]) return text
+  return `${ANSI[color]}${text}${ANSI.reset}`
+}
+
+function stripAnsi(value) {
+  return String(value ?? '').replace(ANSI_RE, '')
+}
+
+function visibleWidth(value) {
+  let width = 0
+  for (const char of Array.from(stripAnsi(value))) {
+    width += charWidth(char)
+  }
+  return width
+}
+
+function padVisible(value, width) {
+  return `${value}${' '.repeat(Math.max(0, width - visibleWidth(value)))}`
+}
+
+function truncateVisible(value, width) {
+  const text = stripAnsi(value)
+  if (visibleWidth(text) <= width) return text
+  if (width <= 1) return Array.from(text).slice(0, width).join('')
+
+  let next = ''
+  let used = 0
+  const limit = width - 1
+  for (const char of Array.from(text)) {
+    const charDisplayWidth = charWidth(char)
+    if (used + charDisplayWidth > limit) break
+    next += char
+    used += charDisplayWidth
+  }
+  return `${next}.`
+}
+
+function charWidth(char) {
+  const code = char.codePointAt(0)
+  if (code == null) return 0
+  if (
+    (code >= 0x0300 && code <= 0x036f) ||
+    (code >= 0x1ab0 && code <= 0x1aff) ||
+    (code >= 0x1dc0 && code <= 0x1dff) ||
+    (code >= 0x20d0 && code <= 0x20ff) ||
+    (code >= 0xfe20 && code <= 0xfe2f)
+  ) {
+    return 0
+  }
+  if (
+    (code >= 0x1100 && code <= 0x115f) ||
+    code === 0x2329 ||
+    code === 0x232a ||
+    (code >= 0x2e80 && code <= 0xa4cf) ||
+    (code >= 0xac00 && code <= 0xd7a3) ||
+    (code >= 0xf900 && code <= 0xfaff) ||
+    (code >= 0xfe10 && code <= 0xfe19) ||
+    (code >= 0xfe30 && code <= 0xfe6f) ||
+    (code >= 0xff00 && code <= 0xff60) ||
+    (code >= 0xffe0 && code <= 0xffe6)
+  ) {
+    return 2
+  }
+  return 1
+}
+
+async function readConfig() {
+  const text = await fs.readFile(CONFIG_FILE, 'utf8')
+  return JSON.parse(text)
+}
+
+async function requireConfig() {
+  const config = await readConfig().catch(() => null)
+  if (!config?.endpoint || !config?.apiKey) {
+    throw new Error('Not logged in. Run rac login first.')
+  }
+  return config
+}
+
+async function writeConfig(config) {
+  await fs.mkdir(CONFIG_DIR, { recursive: true })
+  await fs.writeFile(CONFIG_FILE, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 })
+  await fs.chmod(CONFIG_FILE, 0o600).catch(() => {})
+}
+
+function createReadline() {
+  return readline.createInterface({ input, output })
+}
+
+async function ask(rl, question) {
+  return (await rl.question(question)).trim()
+}
+
+async function confirm(rl, question, defaultYes = true) {
+  const suffix = defaultYes ? ' [Y/n] ' : ' [y/N] '
+  const answer = (await rl.question(`${question}${suffix}`)).trim().toLowerCase()
+  if (!answer) return defaultYes
+  return ['y', 'yes', 'j', 'ja'].includes(answer)
+}
+
+async function appendAgentInstructions(directory, workspace = {}) {
+  const workspaceName = workspace?.name || 'Raccolta Workspace'
+  const block = `${INSTRUCTIONS_START}
+# Raccolta CLI
+
+This project is connected to the Raccolta workspace "${workspaceName}".
+
+- Use \`rac tasks\` to list current Raccolta tasks/cards.
+- Use task codes like \`RAC-12\` when referencing work from the CLI.
+- Do not print or commit Raccolta API keys. Local credentials are stored in \`~/.raccolta/config.json\`.
+${INSTRUCTIONS_END}
+`
+
+  const results = []
+  for (const file of ['CLAUDE.md', 'AGENTS.md']) {
+    const filePath = path.join(directory, file)
+    const existing = await fs.readFile(filePath, 'utf8').catch(() => '')
+    if (existing.includes(INSTRUCTIONS_START)) {
+      results.push({ file, action: 'Instructions already present in' })
+      continue
+    }
+
+    const next = existing.trimEnd() ? `${existing.trimEnd()}\n\n${block}` : `${block}`
+    await fs.writeFile(filePath, next, 'utf8')
+    results.push({ file, action: existing ? 'Updated' : 'Created' })
+  }
+  return results
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@raccolta/cli",
+  "version": "0.1.1",
+  "description": "Raccolta command line integration",
+  "type": "module",
+  "scripts": {
+    "postinstall": "node ./bin/postinstall.js"
+  },
+  "bin": {
+    "rac": "bin/rac.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "UNLICENSED"
+}