noeta-cli 0.1.0

package/README.md

@@ -0,0 +1,91 @@
+# noeta-cli
+
+Installs the `noeta` command (`npm i -g noeta-cli` for the short form; `npx noeta-cli …` works with no install).
+
+CLI portal to a [Noeta Cloud](https://noeta.cloud) workspace — for agents and
+the humans who authorize them.
+
+```bash
+npx noeta-cli login
+```
+
+That's the whole setup: your browser opens, you sign in, pick an access level
+(full / editor / commenter / read-only), and click **Approve**. The command
+finishes on the click — it never asks for terminal input — and saves the token
+locally. From then on the CLI *is* the integration; no MCP client
+configuration required:
+
+```bash
+npx noeta-cli whoami                              # who am I, which workspace, what cap
+npx noeta-cli tools                               # list the workspace's tools
+npx noeta-cli call get_doc '{"docId":"<id>"}'     # read a document
+npx noeta-cli call insert_blocks '{"docId":"<id>","blocks":[{"type":"paragraph","content":"hi"}]}'
+npx noeta-cli logout                              # revoke the token server-side + forget it
+```
+
+`login` defaults to `https://noeta.cloud`; pass your deployment's URL for
+per-org instances: `npx noeta-cli login https://your-org.noeta.cloud`. Credentials
+live in `~/.config/noeta/credentials.json` (0600), one entry per deployment;
+the last login is the default target and `--url` / `NOETA_URL` switch between
+them. `NOETA_TOKEN` overrides the store entirely (CI).
+
+## What the identity is
+
+Approving mints a **delegated agent identity**: it acts on *your* behalf,
+capped at the level you approved — it can do at most what you can do, never
+more, and everything it writes is attributed to you *via* the agent. Revoke
+any time with `npx noeta-cli logout` (or `DELETE /api/agents/<id>` as your
+signed-in user).
+
+## For agents driving this programmatically
+
+No command reads stdin, and `--json` makes stdout a single machine-readable
+value (progress and errors go to stderr):
+
+```bash
+npx noeta-cli login --json --no-open   # stderr: the approval link to hand to the user
+                                   # stdout: {"token":…,"agentId":…,"mcpUrl":…} on approval
+npx noeta-cli whoami --json
+npx noeta-cli tools --json
+npx noeta-cli call get_doc '{"docId":"<id>"}'   # stdout: the tool result JSON
+```
+
+Exit codes: `0` ok · `1` usage/network/server error · `2` login denied,
+expired, or timed out · `3` the tool call returned an error (reason on stderr).
+
+Prefer a native MCP connection? `login` also prints the one-liner:
+
+```bash
+claude mcp add --transport http noeta https://your-org.noeta.cloud/mcp \
+  --header "Authorization: Bearer noeta_…"
+```
+
+## The raw HTTP contract (no node required)
+
+The CLI is a convenience over plain HTTP — any language can do this
+(OAuth-device-grant shaped):
+
+```bash
+# 1. start (no auth): returns userCode (for the browser), deviceCode (for you), verifyUrl
+curl -X POST https://your-org.noeta.cloud/api/agent-auth/start \
+  -H 'content-type: application/json' -d '{"clientName":"My Agent"}'
+
+# 2. send the user to verifyUrl (…/?agent-auth=<userCode>) and let them approve
+
+# 3. poll (no auth) every ~2s until "approved"; the token is returned exactly ONCE
+curl -X POST https://your-org.noeta.cloud/api/agent-auth/poll \
+  -H 'content-type: application/json' -d '{"deviceCode":"<deviceCode>"}'
+```
+
+Then, with `Authorization: Bearer <token>`:
+
+- `POST /mcp` — MCP over Streamable HTTP (JSON-RPC 2.0): `tools/list`, `tools/call`
+- `GET /agent/me` — the authenticated identity
+- `POST /agent/revoke` — self-revoke (what `logout` calls)
+
+Requests expire after 10 minutes; the `userCode` in the URL can't poll the
+token; the server stores only a hash of the token.
+
+## Requirements
+
+Node ≥ 18 (global `fetch`). Zero dependencies.

package/cli.mjs

@@ -0,0 +1,290 @@
+#!/usr/bin/env node
+// noeta — CLI portal to a Noeta Cloud workspace (BUILD_PLAN §8.7).
+//
+//   npx noeta-cli login                 browser approval → token saved locally
+//   npx noeta-cli tools                 list the workspace's MCP tools
+//   npx noeta-cli call get_doc '{"docId":"…"}'
+//   npx noeta-cli whoami · logout
+//
+// Built for agents: no command ever reads stdin. `login` opens a browser (or prints
+// the link with --no-open) and finishes the moment the user clicks Approve; every
+// other command runs with the stored token, so an agent with shell access can use
+// the whole workspace with NO MCP client configuration. `--json` makes stdout a
+// single machine-readable value (progress goes to stderr).
+//
+// Credentials: ~/.config/noeta/credentials.json (0600; override the directory with
+// NOETA_CONFIG_DIR). Precedence for authed commands: --url flag > NOETA_URL > the
+// last login; token: NOETA_TOKEN > the stored token for that URL.
+// Exit codes: 0 ok · 1 usage/network/server error · 2 login denied/expired/timed
+// out · 3 the tool call itself returned an error.
+
+import { spawn } from "node:child_process";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import process from "node:process";
+
+const DEFAULT_URL = "https://noeta.cloud";
+
+const USAGE = `noeta — CLI portal to a Noeta Cloud workspace
+
+Usage: noeta <command> [args] [options]
+
+Commands:
+  login [url]          Authorize this machine via a browser approval (no prompts;
+                       finishes when the user clicks Approve). Saves the token.
+                       url defaults to ${DEFAULT_URL}; if repeated, the last wins.
+  whoami               Show the authenticated agent identity + workspace
+  tools                List the workspace's MCP tools
+  call <tool> [json]   Call an MCP tool; args as a JSON object (or via --args)
+  logout               Revoke this machine's token server-side and forget it
+  help                 Show this help
+
+Options:
+  --url <url>          Target a specific saved deployment (default: last login)
+  --json               Machine-readable stdout (progress/errors → stderr)
+  --name <name>        [login] Display name on the approval screen (default "MCP agent")
+  --no-open            [login] Don't launch a browser; just print the approval link
+  --timeout <sec>      [login] Max seconds to wait (default: the server's window)
+  --args <json>        [call] Tool arguments as a JSON object
+
+Environment: NOETA_URL, NOETA_TOKEN (override the store), NOETA_CONFIG_DIR.
+Exit codes: 0 ok · 1 error · 2 login denied/expired/timed out · 3 tool-call error.
+
+The same access over raw HTTP (any language): POST /api/agent-auth/start → browser
+approves at verifyUrl → POST /api/agent-auth/poll → Bearer token for POST /mcp.`;
+
+// ── arg parsing (no deps) ─────────────────────────────────────────────────────
+
+const argv = process.argv.slice(2);
+const opts = { json: false, open: true, name: "MCP agent", url: null, timeout: null, args: null };
+const positionals = [];
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (a === "-h" || a === "--help") {
+    console.log(USAGE);
+    process.exit(0);
+  } else if (a === "--json") opts.json = true;
+  else if (a === "--no-open") opts.open = false;
+  else if (a === "--name") opts.name = argv[++i] ?? opts.name;
+  else if (a === "--url") opts.url = argv[++i] ?? null;
+  else if (a === "--timeout") opts.timeout = Number(argv[++i]);
+  else if (a === "--args") opts.args = argv[++i] ?? null;
+  else if (a.startsWith("-")) die(`Unknown option: ${a}\n\n${USAGE}`);
+  else positionals.push(a);
+}
+const command = positionals.shift() ?? "help";
+
+// In --json mode stdout is reserved for the final value; everything else → stderr.
+const log = (msg) => (opts.json ? process.stderr : process.stdout).write(msg);
+const emit = (human, jsonValue) =>
+  opts.json ? process.stdout.write(`${JSON.stringify(jsonValue)}\n`) : console.log(human);
+
+function die(msg, code = 1) {
+  process.stderr.write(`✖ ${msg}\n`);
+  process.exit(code);
+}
+
+// ── credential store ──────────────────────────────────────────────────────────
+
+const configDir = () => process.env.NOETA_CONFIG_DIR ?? join(homedir(), ".config", "noeta");
+const credsPath = () => join(configDir(), "credentials.json");
+
+function readCreds() {
+  try {
+    return JSON.parse(readFileSync(credsPath(), "utf8"));
+  } catch {
+    return { default: null, origins: {} };
+  }
+}
+
+function writeCreds(creds) {
+  mkdirSync(configDir(), { recursive: true });
+  writeFileSync(credsPath(), `${JSON.stringify(creds, null, 2)}\n`, { mode: 0o600 });
+}
+
+/** Resolve the deployment + token an authed command should use. */
+function resolveSession() {
+  const creds = readCreds();
+  const url = (opts.url ?? process.env.NOETA_URL ?? creds.default ?? "").replace(/\/$/, "");
+  if (!url) die(`no deployment selected — run \`npx noeta-cli login\` first (or pass --url / set NOETA_URL)`);
+  const token = process.env.NOETA_TOKEN ?? creds.origins?.[url]?.token;
+  if (!token) die(`no token for ${url} — run \`npx noeta-cli login ${url}\` (or set NOETA_TOKEN)`);
+  return { url, token, creds };
+}
+
+// ── HTTP helpers ──────────────────────────────────────────────────────────────
+
+async function post(baseUrl, path, body, headers = {}) {
+  try {
+    return await fetch(`${baseUrl}${path}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", ...headers },
+      body: JSON.stringify(body),
+    });
+  } catch (err) {
+    die(`could not reach ${baseUrl} (${err.message}). Is the URL right and the server up?`);
+  }
+}
+
+let rpcId = 0;
+async function mcp(session, method, params) {
+  const res = await post(session.url, "/mcp", { jsonrpc: "2.0", id: ++rpcId, method, params }, {
+    Authorization: `Bearer ${session.token}`,
+  });
+  if (res.status === 401) die(`unauthorized — the token for ${session.url} was revoked or expired. Run \`npx noeta-cli login ${session.url}\`.`);
+  if (!res.ok) die(`${method} failed: HTTP ${res.status} ${await res.text()}`);
+  const body = await res.json();
+  if (body.error) die(`${method} failed: ${body.error.message ?? JSON.stringify(body.error)}`);
+  return body.result;
+}
+
+/** Best-effort browser open; the printed URL is always the fallback (headless/SSH). */
+function openBrowser(url) {
+  const [cmd, args] =
+    process.platform === "darwin"
+      ? ["open", [url]]
+      : process.platform === "win32"
+        ? ["cmd", ["/c", "start", "", url]]
+        : ["xdg-open", [url]];
+  try {
+    spawn(cmd, args, { stdio: "ignore", detached: true }).unref();
+  } catch {
+    /* fall back to the printed URL */
+  }
+}
+
+// ── commands ──────────────────────────────────────────────────────────────────
+
+async function cmdLogin() {
+  // Last positional wins so npm scripts can bake in a default the caller overrides.
+  const baseUrl = (positionals.pop() ?? DEFAULT_URL).replace(/\/$/, "");
+
+  const startRes = await post(baseUrl, "/api/agent-auth/start", { clientName: opts.name });
+  if (!startRes.ok) die(`start failed: HTTP ${startRes.status} ${await startRes.text()}`);
+  const { deviceCode, verifyUrl, expiresIn, interval } = await startRes.json();
+
+  const windowSec = Number.isFinite(opts.timeout) && opts.timeout > 0 ? opts.timeout : expiresIn;
+  log(`\nAuthorize ${opts.name} in your browser (link expires in ${Math.round(expiresIn / 60)} min):\n`);
+  log(`\n  ${verifyUrl}\n\n`);
+  if (opts.open) openBrowser(verifyUrl);
+  log("Waiting for approval…");
+
+  const deadline = Date.now() + windowSec * 1000;
+  let approval = null;
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, (interval ?? 2) * 1000));
+    const res = await post(baseUrl, "/api/agent-auth/poll", { deviceCode });
+    if (res.status === 404) die("the request expired or was denied. Re-run to try again.", 2);
+    if (!res.ok) die(`poll failed: HTTP ${res.status}`);
+    const body = await res.json();
+    if (body.status === "approved") {
+      approval = body;
+      break;
+    }
+    log(".");
+  }
+  if (!approval) die("timed out waiting for approval. Re-run to try again.", 2);
+  log(" approved ✔\n");
+
+  const { token, agentId, agentName, workspaceId } = approval;
+  const creds = readCreds();
+  creds.origins = { ...creds.origins, [baseUrl]: { token, agentId, agentName, workspaceId } };
+  creds.default = baseUrl;
+  writeCreds(creds);
+
+  const mcpUrl = `${baseUrl}/mcp`;
+  if (opts.json) {
+    emit(null, { token, agentId, agentName, workspaceId, mcpUrl, baseUrl });
+    return;
+  }
+  console.log(`\nConnected as ${agentName} (${agentId}) — workspace ${workspaceId}.`);
+  console.log(`Token saved to ${credsPath()} (shown below once; the server stores only a hash).\n`);
+  console.log(`Use it straight from this CLI — no MCP configuration needed:`);
+  console.log(`  npx noeta-cli tools`);
+  console.log(`  npx noeta-cli call get_doc '{"docId":"<id>"}'\n`);
+  console.log(`Or wire up an MCP client:`);
+  console.log(`  claude mcp add --transport http noeta ${mcpUrl} --header "Authorization: Bearer ${token}"\n`);
+  console.log(`Disconnect any time with: npx noeta-cli logout`);
+}
+
+async function cmdWhoami() {
+  const session = resolveSession();
+  const res = await fetch(`${session.url}/agent/me`, { headers: { Authorization: `Bearer ${session.token}` } });
+  if (res.status === 401) die(`unauthorized — run \`npx noeta-cli login ${session.url}\``);
+  if (!res.ok) die(`whoami failed: HTTP ${res.status}`);
+  const me = await res.json();
+  emit(
+    `${me.name} (${me.agentId})\n` +
+      `  deployment: ${session.url}\n` +
+      `  workspace:  ${me.workspaceId ?? "—"}\n` +
+      `  acting for: ${me.delegatedUserId ?? "— (standalone service account)"}\n` +
+      `  access cap: ${me.roleCap ?? "none (the user's full role)"}`,
+    { ...me, baseUrl: session.url },
+  );
+}
+
+async function cmdTools() {
+  const session = resolveSession();
+  const result = await mcp(session, "tools/list", {});
+  const tools = result.tools ?? [];
+  if (opts.json) return emit(null, tools);
+  for (const t of tools) {
+    const first = (t.description ?? "").split(". ")[0];
+    console.log(`${t.name.padEnd(16)} ${first}`);
+  }
+  console.log(`\n${tools.length} tools. Call one with: npx noeta-cli call <tool> '<json-args>'`);
+}
+
+async function cmdCall() {
+  const name = positionals.shift();
+  if (!name) die(`usage: noeta call <tool> ['{"json":"args"}']`);
+  const raw = opts.args ?? positionals.shift() ?? "{}";
+  let args;
+  try {
+    args = JSON.parse(raw);
+  } catch {
+    die(`tool arguments must be a JSON object, got: ${raw}`);
+  }
+
+  const session = resolveSession();
+  const result = await mcp(session, "tools/call", { name, arguments: args });
+  const text = (result.content ?? [])
+    .filter((c) => c.type === "text")
+    .map((c) => c.text)
+    .join("\n");
+  if (result.isError) {
+    process.stderr.write(`✖ ${text}\n`);
+    process.exit(3);
+  }
+  // Tool results are already JSON text — print raw so output is pipeable either way.
+  process.stdout.write(`${text}\n`);
+}
+
+async function cmdLogout() {
+  const session = resolveSession();
+  // Revoke server-side first (best effort — the local forget still happens).
+  const res = await fetch(`${session.url}/agent/revoke`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${session.token}` },
+  });
+  const revoked = res.ok;
+  if (!revoked) process.stderr.write(`⚠ server-side revoke failed (HTTP ${res.status}) — token forgotten locally only\n`);
+
+  const creds = session.creds;
+  delete creds.origins?.[session.url];
+  if (creds.default === session.url) creds.default = Object.keys(creds.origins ?? {})[0] ?? null;
+  writeCreds(creds);
+  emit(`Disconnected from ${session.url}${revoked ? " (token revoked)" : ""}.`, { loggedOut: session.url, revoked });
+}
+
+// ── dispatch ──────────────────────────────────────────────────────────────────
+
+const commands = { login: cmdLogin, whoami: cmdWhoami, tools: cmdTools, call: cmdCall, logout: cmdLogout };
+if (command === "help") {
+  console.log(USAGE);
+} else if (commands[command]) {
+  await commands[command]();
+} else {
+  die(`unknown command: ${command}\n\n${USAGE}`);
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "noeta-cli",
+  "version": "0.1.0",
+  "description": "CLI portal to Noeta Cloud for agents & humans: `npx noeta-cli login` (browser approval, no prompts), then call the workspace API/MCP tools directly — no MCP client configuration required.",
+  "type": "module",
+  "bin": {
+    "noeta": "./cli.mjs"
+  },
+  "files": [
+    "cli.mjs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "agent",
+    "cli",
+    "oauth-device-flow",
+    "noeta"
+  ],
+  "license": "MIT"
+}