autark-cli 0.1.0

package/README.md

@@ -0,0 +1,56 @@
+# autark-cli
+
+CLI for [autark](https://autark.kushalsm.com) — hypothesis-driven product runbooks.
+
+A product has hypotheses. Each hypothesis has runs. Each run logs actions (emails sent, posts made, replies received). The dashboard shows it all.
+
+## Install
+
+```sh
+npm i -g autark-cli
+```
+
+## Login
+
+```sh
+autark login send your@email.com
+# check inbox
+autark login verify your@email.com --code 123456
+```
+
+## Use
+
+```sh
+# products
+autark product upsert --slug chrome-relay --name "chrome-relay" --tagline "..."
+autark product list
+
+# hypotheses
+autark hypothesis create --product chrome-relay --code H01 --md @./H01.md --title "..."
+autark hypothesis status chrome-relay/H01 --status active   # active|inactive|dead
+
+# runs
+autark run start --hypothesis chrome-relay/H01
+autark run finish --run <run_id> --narrative @./narrative.md
+
+# actions (anything the agent did during a run)
+autark log action --run <run_id> --channel email --title "..." \
+  --recipient person@example.com --agentmail-thread-id <thread_id>
+autark log action --run <run_id> --channel github --title "..." --url https://github.com/...
+
+# context (full hypothesis state for an agent picking up work)
+autark context chrome-relay/H01
+
+autark me
+autark logout
+```
+
+## ENV
+
+- `AUTARK_API_URL` — override the default Worker URL (`https://autark-api.kushalsokke.workers.dev`)
+
+## Architecture
+
+The CLI is a thin HTTP client over a Cloudflare Worker that holds the InstantDB admin token. Magic-link auth via InstantDB. Token saved to `~/.autark/credentials.json` after login.
+
+The web at autark.kushalsm.com is read-only. All writes (product, hypothesis, run, action) come through this CLI or future MCP server.

package/autark.mjs

@@ -0,0 +1,326 @@
+#!/usr/bin/env node
+// autark CLI — thin HTTP client over the autark-api Worker.
+//
+// Auth: magic-link flow saves a refresh_token to ~/.autark/credentials.json.
+// Every subsequent command sends it as `Authorization: Bearer <token>`.
+//
+// All business logic, schema knowledge, and InstantDB connectivity lives in
+// the Worker. The CLI is intentionally thin — it parses args, makes HTTP
+// calls, formats output. Replace this binary in any language tomorrow and
+// the system still works.
+
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import process from 'node:process'
+
+const API = process.env.AUTARK_API_URL || 'https://autark-api.kushalsokke.workers.dev'
+const CREDS_PATH = path.join(os.homedir(), '.autark', 'credentials.json')
+
+const args = process.argv.slice(2)
+main().catch(err => {
+  console.error(err.message)
+  process.exit(1)
+})
+
+async function main() {
+  const [group, command, ...rest] = args
+  if (!group || group === 'help' || group === '--help' || group === '-h') return usage()
+
+  if (group === 'login') {
+    if (command === 'send')   return loginSend(rest)
+    if (command === 'verify') return loginVerify(rest)
+    if (!command || command === '--help') return loginUsage()
+  }
+  if (group === 'logout') return logout()
+  if (group === 'me')     return me()
+
+  if (group === 'product') {
+    if (command === 'upsert') return productUpsert(rest)
+    if (command === 'list')   return productList()
+  }
+  if (group === 'hypothesis') {
+    if (command === 'create') return hypothesisCreate(rest)
+    if (command === 'status') return hypothesisStatus(rest)
+  }
+  if (group === 'run') {
+    if (command === 'start')  return runStart(rest)
+    if (command === 'finish') return runFinish(rest)
+  }
+  if (group === 'log' && command === 'action') return logAction(rest)
+  if (group === 'context') return context([command, ...rest].filter(Boolean))
+
+  usage()
+  process.exit(1)
+}
+
+// ============================================================ auth flow
+
+async function loginSend(rest) {
+  const opts = parseArgs(rest)
+  const email = required(opts._[0] || opts.email, 'email')
+  await api('POST', '/v1/auth/login/send', { email }, { auth: false })
+  console.log(`code sent to ${email}`)
+  console.log(`now run: autark login verify ${email} --code <6-digit-code>`)
+}
+
+async function loginVerify(rest) {
+  const opts = parseArgs(rest)
+  const email = required(opts._[0] || opts.email, 'email')
+  const code  = required(opts.code, '--code')
+  const result = await api('POST', '/v1/auth/login/verify', { email, code }, { auth: false })
+  if (!result.token) throw new Error('verify succeeded but no token returned')
+  saveCredentials({
+    user_id: result.user.id,
+    email:   result.user.email,
+    token:   result.token,
+    saved_at: new Date().toISOString(),
+  })
+  console.log(`logged in as ${result.user.email}`)
+  console.log(`user_id: ${result.user.id}`)
+  console.log(`saved to ${CREDS_PATH}`)
+}
+
+async function logout() {
+  if (fs.existsSync(CREDS_PATH)) fs.unlinkSync(CREDS_PATH)
+  console.log('logged out')
+}
+
+async function me() {
+  const result = await api('GET', '/v1/me')
+  console.log(`${result.email}  (${result.id})`)
+}
+
+// =========================================================== products
+
+async function productUpsert(rest) {
+  const opts = parseArgs(rest)
+  const slug = required(opts.slug, '--slug')
+  const name = required(opts.name, '--name')
+  const result = await api('POST', '/v1/products', {
+    slug,
+    name,
+    url:        opts.url || '',
+    tagline:    opts.tagline || '',
+    visibility: opts.visibility || 'public',
+  })
+  console.log(result.id)
+}
+
+async function productList() {
+  const result = await api('GET', '/v1/products')
+  if (!result.products?.length) {
+    console.log('(no products)')
+    return
+  }
+  for (const p of result.products) {
+    console.log(`${(p.slug || '').padEnd(20)} ${(p.visibility || '').padEnd(8)} ${p.name || ''}`)
+  }
+}
+
+// ========================================================= hypotheses
+
+async function hypothesisCreate(rest) {
+  const opts = parseArgs(rest)
+  const product = required(opts.product, '--product')
+  const code    = required(opts.code, '--code')
+  const md      = readValue(required(opts.md, '--md'))
+  const title   = opts.title
+  const result = await api('POST', '/v1/hypotheses', {
+    product, code, md,
+    title:  title || undefined,
+    status: opts.status || undefined,
+  })
+  console.log(result.id)
+}
+
+async function hypothesisStatus(rest) {
+  const opts = parseArgs(rest)
+  const ref  = required(opts._[0] || opts.hypothesis, 'hypothesis (e.g. chrome-relay/H01)')
+  const status = required(opts.status, '--status')
+  const [productSlug, code] = splitHypothesisRef(ref)
+  const ctx = await api('GET', `/v1/context/${encodeURIComponent(productSlug)}/${encodeURIComponent(code)}`)
+  const hypId = ctx.hypothesis?.id
+  if (!hypId) throw new Error(`hypothesis not found: ${ref}`)
+  const result = await api('PATCH', `/v1/hypotheses/${hypId}/status`, { status })
+  console.log(`${ref} → ${result.status}`)
+}
+
+// =============================================================== runs
+
+async function runStart(rest) {
+  const opts = parseArgs(rest)
+  const ref  = required(opts.hypothesis || opts._[0], '--hypothesis (e.g. chrome-relay/H01)')
+  const [productSlug, code] = splitHypothesisRef(ref)
+  const result = await api('POST', '/v1/runs', { product: productSlug, hypothesis: code })
+  console.log(result.id)
+}
+
+async function runFinish(rest) {
+  const opts = parseArgs(rest)
+  const id   = required(opts.run, '--run')
+  const narrative = readValue(required(opts.narrative, '--narrative'))
+  const result = await api('PATCH', `/v1/runs/${id}/finish`, { narrative_md: narrative })
+  console.log(`${result.id}  finished_at=${result.finished_at}`)
+}
+
+// ============================================================ actions
+
+async function logAction(rest) {
+  const opts = parseArgs(rest)
+  const run = required(opts.run, '--run')
+  const channel = required(opts.channel, '--channel')
+  const title   = required(opts.title, '--title')
+  const result = await api('POST', '/v1/actions', {
+    run,
+    channel,
+    title,
+    url:                 opts.url || undefined,
+    agentmail_thread_id: opts['agentmail-thread-id'] || opts['thread-id'] || opts.thread_id || undefined,
+    recipient:           opts.recipient || undefined,
+    metadata:            opts.metadata ? JSON.parse(readValue(opts.metadata)) : undefined,
+    occurred_at:         opts['occurred-at'] || opts.occurred_at || undefined,
+  })
+  console.log(result.id)
+}
+
+// ============================================================ context
+
+async function context(rest) {
+  const opts = parseArgs(rest)
+  const ref = required(opts._[0] || opts.hypothesis, 'hypothesis (e.g. chrome-relay/H01)')
+  const [productSlug, code] = splitHypothesisRef(ref)
+  const result = await api('GET', `/v1/context/${encodeURIComponent(productSlug)}/${encodeURIComponent(code)}`)
+
+  console.log(`# ${result.product.slug}/${result.hypothesis.code} — ${result.hypothesis.title}\n`)
+  console.log(`Status: ${result.hypothesis.status}\n`)
+  console.log(result.hypothesis.hypothesis_md)
+  for (const run of result.runs) {
+    console.log(`\n\n## Run ${run.run_number}  (${run.id})`)
+    console.log(`started: ${run.started_at}${run.finished_at ? `   finished: ${run.finished_at}` : '   (in progress)'}`)
+    if (run.actions?.length) {
+      console.log(`\nActions:`)
+      for (const a of run.actions) {
+        const pointer = a.url || a.agentmail_thread_id || a.recipient || ''
+        console.log(`  [${a.channel}] ${a.title}${pointer ? `  →  ${pointer}` : ''}`)
+      }
+    }
+    if (run.narrative_md) {
+      console.log(`\n${run.narrative_md}`)
+    }
+  }
+}
+
+// ============================================================ HTTP layer
+
+async function api(method, pathStr, body, { auth = true } = {}) {
+  const headers = { 'content-type': 'application/json' }
+  if (auth) {
+    const creds = loadCredentials()
+    if (!creds) throw new Error('not logged in. run: autark login send <email>')
+    headers.authorization = `Bearer ${creds.token}`
+  }
+  const init = { method, headers }
+  if (body !== undefined) init.body = JSON.stringify(body)
+  const res = await fetch(API + pathStr, init)
+  const text = await res.text()
+  let data = null
+  try { data = text ? JSON.parse(text) : null } catch { data = { raw: text } }
+  if (!res.ok) {
+    const msg = data?.error || `HTTP ${res.status}`
+    throw new Error(msg)
+  }
+  return data
+}
+
+// ============================================================ credentials
+
+function saveCredentials(creds) {
+  fs.mkdirSync(path.dirname(CREDS_PATH), { recursive: true, mode: 0o700 })
+  fs.writeFileSync(CREDS_PATH, JSON.stringify(creds, null, 2), { mode: 0o600 })
+}
+
+function loadCredentials() {
+  if (!fs.existsSync(CREDS_PATH)) return null
+  try {
+    return JSON.parse(fs.readFileSync(CREDS_PATH, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+// ============================================================ arg parsing
+
+function parseArgs(list) {
+  const opts = { _: [] }
+  for (let i = 0; i < list.length; i++) {
+    const arg = list[i]
+    if (!arg.startsWith('--')) {
+      opts._.push(arg)
+      continue
+    }
+    const key = arg.slice(2)
+    const next = list[i + 1]
+    if (!next || next.startsWith('--')) {
+      opts[key] = true
+    } else {
+      opts[key] = next
+      i++
+    }
+  }
+  return opts
+}
+
+function required(value, label) {
+  if (value === undefined || value === null || value === '' || value === true) {
+    throw new Error(`${label} is required`)
+  }
+  return value
+}
+
+function readValue(value) {
+  if (typeof value === 'string' && value.startsWith('@')) {
+    return fs.readFileSync(value.slice(1), 'utf8')
+  }
+  return String(value)
+}
+
+function splitHypothesisRef(ref) {
+  const m = String(ref).match(/^([\w.-]+)\/(H\d{2})$/)
+  if (!m) throw new Error(`expected product/Hxx, got ${ref}`)
+  return [m[1], m[2]]
+}
+
+// ============================================================ usage
+
+function loginUsage() {
+  console.log(`autark login send <email>
+autark login verify <email> --code <6-digit-code>`)
+}
+
+function usage() {
+  console.log(`autark — agent runbook CLI
+
+  autark login send <email>                                send a magic code
+  autark login verify <email> --code <code>                complete login
+  autark logout                                            clear local credentials
+  autark me                                                show signed-in user
+
+  autark product upsert --slug <slug> --name <name> [--url <url>] [--tagline <text>]
+  autark product list
+
+  autark hypothesis create --product <slug> --code H01 --md @./hypothesis.md [--title <t>]
+  autark hypothesis status <slug>/<H01> --status active|inactive|dead
+
+  autark run start --hypothesis <slug>/<H01>
+  autark run finish --run <id> --narrative @./run.md
+
+  autark log action --run <id> --channel <c> --title <t> [--url <u>]
+                    [--agentmail-thread-id <uuid>] [--recipient <email>]
+                    [--metadata @./meta.json]
+
+  autark context <slug>/<H01>
+
+ENV:
+  AUTARK_API_URL  override the default Worker URL`)
+}

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "autark-cli",
+  "version": "0.1.0",
+  "description": "CLI for autark — hypothesis-driven product runbooks. Track products, hypotheses, runs, and actions from the terminal.",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "autark": "autark.mjs"
+  },
+  "files": [
+    "autark.mjs",
+    "README.md"
+  ],
+  "homepage": "https://autark.kushalsm.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kiluazen/autark.git"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}