gsjos 0.0.0-stage → 0.6.2

package/README.md

@@ -1,3 +1,180 @@
-# Temporary Holding Version
+# `gsjos` — the OS client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Headless access to a gsjmedia OS workspace, with two faces over one core:
+
+```bash
+gsjos people.list --q "acme"      # CLI — humans, scripts, cron, CI, agents that shell out
+gsjos pipeline.move <id> proposal_sent
+gsjos mcp                         # MCP server (stdio) — Claude Code, Codex, Cursor, OpenClaw
+```
+
+This is **Layer 1** of [`architecture/11-agent-runtime-and-fleet-plan.md`](../../architecture/11-agent-runtime-and-fleet-plan.md):
+the one door through which any agent reads context *and* takes actions. Runtimes are
+replaceable; this is not.
+
+## Why it is shaped like this
+
+**One capability set, two syntaxes.** [`src/verbs.mjs`](src/verbs.mjs) defines every verb once —
+name, arguments, route, human rendering. The CLI parses flags into it; the MCP server generates
+JSON Schema from it. Adding a verb there adds a CLI command and an MCP tool simultaneously, with
+identical semantics. Neither face can drift from the other because neither has its own logic.
+
+**Everything goes through `/api/v1`, never Postgres directly.** So an agent gets the same
+guardrails a human gets: legal status transitions enforced, the same triggers fired, the same
+row-level security applied. An agent can be wrong in judgment; it cannot be wrong in data
+integrity.
+
+**Zero dependencies.** An agent host can `npx gsjos mcp` with nothing else installed,
+and there is no SDK version to drift. The MCP stdio transport is ~120 lines of JSON-RPC.
+
+## Setup
+
+```bash
+npm i -g gsjos
+gsjos login          # asks for API URL, workspace slug, and an API key
+```
+
+`login` prompts only for what you did not pass, so it also runs where nothing can answer a
+prompt — a provisioning script, or an agent session with no TTY:
+
+```bash
+gsjos login --url https://os.gsjmedia.co --workspace gsjmedia --key gsjos_live_…
+op read op://vault/gsjos/key | gsjos login --url … --workspace … --key -   # keeps it out of history
+GSJOS_API_KEY=gsjos_live_… gsjos login --url … --workspace …
+```
+
+The key is read from `--key`, then `GSJOS_API_KEY`, then a prompt. With no TTY and neither of
+the first two it fails naming them, rather than hanging on a question nothing will answer.
+
+**Node 20+** for the CLI and the MCP server. **Node 22+ for `gsjos daemon`**, which needs a
+global `WebSocket` to reach the local agent runtime — it fails at startup with that message
+rather than midway through a run.
+
+Create the key in the OS: **Settings → Agent runtime → API keys**. It is shown once.
+
+A key is not a password and not a service-role key: the server binds it to a workspace agent
+identity that sits in `workspace_members` with `role='agent'`, so requests made with it are held
+to exactly the same row-level permissions as a person's. A key cannot reach another workspace.
+
+Credentials resolve from the environment first, then `~/.gsjos/config.json` — so a laptop uses
+`gsjos login` and a provisioned droplet gets them injected:
+
+```bash
+GSJOS_API_URL=https://app.example.com
+GSJOS_API_KEY=gsjos_live_…
+GSJOS_WORKSPACE=gsjmedia
+```
+
+## As an MCP server
+
+Any MCP client, e.g. Claude Code:
+
+```bash
+claude mcp add gsjos -- npx -y gsjos mcp
+```
+
+Or by config, for a client that reads one:
+
+```json
+{
+  "mcpServers": {
+    "gsjos": {
+      "command": "npx",
+      "args": ["-y", "gsjos", "mcp"],
+      "env": {
+        "GSJOS_API_URL": "https://app.example.com",
+        "GSJOS_API_KEY": "gsjos_live_…",
+        "GSJOS_WORKSPACE": "gsjmedia"
+      }
+    }
+  }
+}
+```
+
+The server's `initialize` response tells the agent to call `schema` first. That verb returns the
+workspace's status vocabularies, legal pipeline stages, and writable fields — generated from the
+same modules the UI and the database constraints use, so it cannot go stale.
+
+## Verbs
+
+Run `gsjos help` for the list, `gsjos help <verb>` for one in detail.
+
+| | |
+|---|---|
+| `schema` | status vocabularies, legal transitions, writable fields |
+| `people.list` · `people.get` · `people.update` | the prospect warehouse |
+| `companies.list` | firmographics |
+| `pipeline.list` · `pipeline.move` | deals by stage |
+| `search` | people + companies by name |
+| `interactions.log` | log a touch — inbound promotes to a lead via a DB trigger |
+| `tam.list` · `tam.create` · `icp.list` · `icp.create` | targeting |
+| `runs.list` · `runs.enqueue` · `agents.dispatch` | the agent work queue |
+| `webhooks.list` · `webhooks.create` · `webhooks.delete` | subscribe a URL to workspace events |
+
+Add `--json` to any verb for raw output instead of the human rendering.
+
+### Walking a large workspace
+
+List verbs are paginated. `--limit` sets the page size and `--cursor` takes you to the next
+page, but you rarely need either — `--all` walks every page for you:
+
+```bash
+gsjos people.list --all --json > people.json
+```
+
+The pagination is keyset, not offset, so a walk of 50k people will not skip or repeat a row
+even while the workspace is being written to underneath it. That is what makes `--all` safe
+to point at an export.
+
+### List values, and commas that are data
+
+A list argument splits on commas. Plenty of real values contain one — the LinkedIn industry
+`Technology, Information & Internet` is a targeting profile away from becoming two industries
+nobody chose. Escape it, or repeat the flag:
+
+```bash
+gsjos tam.create --name "Agencies" --industries 'Marketing Services,Technology\, Information & Internet'
+gsjos tam.create --name "Agencies" --industries "Marketing Services" --industries "Technology, Information & Internet"
+```
+
+Both produce two entries, with the comma intact in the second. The MCP face takes a real
+array, so this is a shell problem only.
+
+### Re-running a write
+
+The API replays a POST that carries an `Idempotency-Key` it has already seen, for 24h, rather
+than running the handler again. `--idempotency-key` is how you send one:
+
+```bash
+gsjos tam.create --name "Agencies" --idempotency-key tam-agencies-v1
+```
+
+Run that script twice and you get one TAM and the same response, not two TAMs. Key it per
+logical operation — not per retry — and a re-run of the whole script is safe. Reusing a key
+with a *different* body is a 409, deliberately: that is a caller bug and hiding it would make
+it permanent.
+
+### Permissions
+
+A key can be narrowed to individual verbs. If a call comes back with
+
+```
+this API key is missing the 'pipeline.move' scope
+```
+
+the key was issued for an agent whose `agent.md` does not declare that verb. Widen the grant
+in the agent definition and re-issue the key — do not reach for a broader key.
+
+## Tests
+
+```bash
+node test/smoke.mjs
+```
+
+Drives the MCP server over a real stdio pipe against a stub API: protocol handshake, tool
+listing, tool calls, error shapes, plus CLI argument parsing and auth headers. It asserts on
+the request body the stub receives, not just the exit code — an argument that parsed into the
+wrong shape is invisible from a 200. It covers every non-interactive `login` path, walks
+a paginated stub end to end, and checks every verb here against the server's own scope
+catalog in `app/src/lib/api/verbs.ts` — a verb the CLI can call but the server cannot scope
+would be a hole in the permission model, so the two lists are not allowed to drift.

package/bin/gsjos.mjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { main } from "../src/cli.mjs";
+
+const code = await main(process.argv.slice(2));
+
+// `mcp` and `daemon` return null: they are long-running and own the process.
+//
+// Setting `exitCode` rather than calling `process.exit()` matters more than it
+// looks. `process.exit()` tears the event loop down immediately, which (a) can
+// truncate stdout when it is a pipe — exactly how this CLI is used from scripts
+// and agents — and (b) trips a libuv assertion on Windows when HTTP keep-alive
+// sockets are still pooled, which a `--all` walk always leaves behind. The
+// process then dies with 0xC0000409 instead of the status the caller branches
+// on. Letting Node exit on its own is immediate here anyway: the socket pool is
+// unref'd, so nothing holds the loop open.
+if (code !== null) process.exitCode = code;

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "gsjos",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.6.2",
+  "description": "Headless access to a gsjmedia OS workspace — CLI and MCP server over one API core.",
+  "type": "module",
+  "license": "UNLICENSED",
+  "homepage": "https://docs.gsjmedia.co",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gsjmedia/gsjos.git"
+  },
+  "bugs": {
+    "url": "https://github.com/gsjmedia/gsjos/issues"
+  },
+  "keywords": [
+    "mcp",
+    "crm",
+    "agent",
+    "cli"
+  ],
+  "bin": {
+    "gsjos": "bin/gsjos.mjs"
+  },
+  "exports": {
+    ".": "./src/client.mjs",
+    "./verbs": "./src/verbs.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node test/smoke.mjs",
+    "prepublishOnly": "node test/smoke.mjs"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,321 @@
+// CLI face — the same verbs, in shell syntax.
+//
+// Shell-native runtimes compose `gsjos` with pipes, cron, and scripts more
+// naturally than they compose tool calls, so this is a first-class surface, not
+// a debug tool for the MCP server.
+
+import { createInterface } from "node:readline";
+import { VERBS, verbByName } from "./verbs.mjs";
+import { loadConfig, saveConfig, configPath, runVerb, call, GsjosError } from "./client.mjs";
+import { startMcpServer } from "./mcp.mjs";
+import { startDaemon } from "./daemon.mjs";
+
+const ask = (question, { hidden } = {}) =>
+  new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+    if (hidden) rl._writeToOutput = (s) => { if (s.includes(question)) rl.output.write(question); };
+    rl.question(question, (answer) => {
+      rl.close();
+      if (hidden) process.stdout.write("\n");
+      resolve(answer.trim());
+    });
+  });
+
+/** Read the whole of stdin. `--key -` uses this so a secret can be piped in
+ *  from a password manager rather than sitting in shell history, in `ps`
+ *  output, and in the environment of every child process. */
+const readStdin = () =>
+  new Promise((resolve) => {
+    let buffer = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => (buffer += chunk));
+    process.stdin.on("end", () => resolve(buffer.trim()));
+  });
+
+/** `--flag value` and `--flag=value` pairs, with no verb spec to check against.
+ *  For the commands that are not verbs — login, daemon. */
+function plainFlags(argv) {
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    if (!argv[i].startsWith("--")) continue;
+    const [name, inline] = argv[i].slice(2).split("=");
+    flags[name] = inline !== undefined ? inline : argv[++i] ?? "";
+  }
+  return flags;
+}
+
+/** Split a list flag on commas, honouring `\,` as a literal one.
+ *
+ *  Real-world values contain commas — the LinkedIn industry
+ *  "Technology, Information & Internet" is one — and splitting blindly sends
+ *  two junk entries the caller never typed. Escaping is the only way to say
+ *  "this comma is data" in a single shell token. */
+const splitList = (raw) =>
+  String(raw)
+    .split(/(?<!\\),/)
+    .map((part) => part.replace(/\\,/g, ",").trim())
+    .filter(Boolean);
+
+/** Parse `--flag value` pairs plus bare positionals, against a verb's arg spec. */
+function parseArgs(verb, argv) {
+  const positionals = [];
+  const flags = {};
+
+  // A repeated flag accumulates for list args and last-wins for everything
+  // else. Repetition is the escape hatch when a value contains a comma AND the
+  // caller would rather not escape it: `--industries A --industries "B, C"`.
+  const set = (name, value) => {
+    const spec = verb.args[name];
+    flags[name] = spec?.type === "list" && flags[name] !== undefined
+      ? [].concat(flags[name], value)
+      : value;
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    if (token.startsWith("--")) {
+      const [name, inline] = token.slice(2).split("=");
+      const spec = verb.args[name];
+      // Booleans take no value; everything else consumes the next token.
+      if (inline !== undefined) set(name, inline);
+      else if (spec?.type === "boolean") set(name, true);
+      else set(name, argv[++i]);
+    } else {
+      positionals.push(token);
+    }
+  }
+
+  const args = {};
+  const positionalNames = Object.entries(verb.args).filter(([, s]) => s.positional).map(([n]) => n);
+  positionalNames.forEach((name, i) => { if (positionals[i] !== undefined) args[name] = positionals[i]; });
+
+  for (const [name, raw] of Object.entries(flags)) {
+    const spec = verb.args[name];
+    if (!spec) throw new GsjosError(`${verb.name}: unknown option --${name}`, 400);
+    args[name] = raw;
+  }
+
+  // Coerce to the declared types so the API gets numbers as numbers and
+  // comma-separated lists as arrays.
+  for (const [name, value] of Object.entries(args)) {
+    const spec = verb.args[name];
+    if (!spec || value === undefined) continue;
+    if (spec.type === "number") args[name] = Number(value);
+    else if (spec.type === "list") {
+      args[name] = (Array.isArray(value) ? value : [value]).flatMap(splitList);
+    } else if (spec.type === "objects") {
+      // The shell has no way to express a list of records, so it comes in as
+      // JSON. Failing here with the parse error beats sending a string the API
+      // will reject for a reason that has nothing to do with the real mistake.
+      if (typeof value === "string") {
+        try {
+          args[name] = JSON.parse(value);
+        } catch (e) {
+          throw new Error(`--${name} must be valid JSON: ${e.message}`);
+        }
+      }
+      if (!Array.isArray(args[name])) args[name] = [args[name]];
+    }
+  }
+  return args;
+}
+
+function help() {
+  const lines = ["gsjos — headless access to a gsjmedia OS workspace", ""];
+  lines.push("  gsjos login [--url --workspace --key]   store an API key + workspace");
+  lines.push("  gsjos whoami                   show the current config");
+  lines.push("  gsjos mcp                      run as an MCP server (stdio)");
+  lines.push("  gsjos help [verb|command]      this, or one verb or command in detail");
+  lines.push("");
+  lines.push("Verbs:");
+  for (const v of VERBS) {
+    const positional = Object.entries(v.args).filter(([, s]) => s.positional).map(([n, s]) => (s.required ? `<${n}>` : `[${n}]`)).join(" ");
+    lines.push(`  ${`${v.name} ${positional}`.padEnd(34)} ${v.summary.split(".")[0]}.`);
+  }
+  lines.push("");
+  lines.push("List verbs take --limit and --cursor; --all walks every page for you.");
+  lines.push("Any verb takes --json for raw output. A write takes --idempotency-key <k>:");
+  lines.push("re-running with the same key replays the first response instead of creating a second row.");
+  lines.push("A list value splits on commas; escape one you mean literally (Technology\\, Information).");
+  lines.push("Config: GSJOS_API_URL, GSJOS_API_KEY, GSJOS_WORKSPACE (env wins over ~/.gsjos/config.json).");
+  return lines.join("\n");
+}
+
+/** Detail for the commands that are not verbs.
+ *
+ *  Without these, `gsjos help login` fell through to the general help — which
+ *  reads as "login takes no arguments" rather than "look somewhere else", and
+ *  that is exactly the question someone has when they type it. */
+const COMMAND_HELP = {
+  login: [
+    "login — store an API URL, workspace slug and key in ~/.gsjos/config.json",
+    "",
+    "  Prompts for whatever is not passed. Verifies the key against /schema",
+    "  before writing it, so a typo fails here rather than inside an agent run",
+    "  an hour later.",
+    "",
+    "Arguments:",
+    "  --url <string>                 API URL, e.g. https://os.gsjmedia.co",
+    "  --workspace <string>           workspace slug",
+    "  --key <string>                 API key; `--key -` reads it from stdin",
+    "",
+    "Non-interactive — a provisioning script, or an agent session with no TTY:",
+    "  gsjos login --url https://os.gsjmedia.co --workspace acme --key gsjos_live_...",
+    "  cat key.txt | gsjos login --url ... --workspace acme --key -",
+    "  GSJOS_API_KEY=gsjos_live_... gsjos login --url ... --workspace acme",
+    "",
+    "  The key is read from --key, then GSJOS_API_KEY, then a prompt. With no",
+    "  TTY and neither of the first two, it fails naming them rather than",
+    "  hanging on a prompt nothing can answer.",
+  ].join("\n"),
+
+  whoami: "whoami — print the resolved API URL, workspace, key prefix and config path.",
+
+  mcp: [
+    "mcp — run as an MCP server over stdio (Claude Code, Codex, Cursor, OpenClaw).",
+    "",
+    "  Every verb becomes a tool with the same arguments and validation the CLI",
+    "  applies. stdout is the protocol channel; diagnostics go to stderr.",
+  ].join("\n"),
+
+  daemon: [
+    "daemon — claim queued work from the OS and run it on this host.",
+    "",
+    "Arguments:",
+    "  --poll <number>                poll interval in ms",
+    "",
+    "  Needs Node 22+ for a global WebSocket. Outbound only: the host needs",
+    "  nothing inbound.",
+  ].join("\n"),
+};
+
+function verbHelp(verb) {
+  const lines = [`${verb.name} — ${verb.summary}`, "", `  kind: ${verb.kind}`];
+  if (verb.paginated) lines.push("  paginated: --all walks every page (keyset, so no row is skipped or repeated)");
+  if (Object.keys(verb.args).length) {
+    lines.push("", "Arguments:");
+    for (const [name, spec] of Object.entries(verb.args)) {
+      const shape = spec.positional ? `<${name}>` : `--${name} <${spec.type}>`;
+      lines.push(`  ${shape.padEnd(30)} ${spec.desc}${spec.required ? " (required)" : ""}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+export async function main(argv) {
+  const [command, ...rest] = argv;
+  const config = loadConfig();
+  const wantsJson = rest.includes("--json");
+
+  // `--idempotency-key` is transport, not a verb argument — it belongs to every
+  // write the same way `--json` belongs to every read, so it is stripped here
+  // rather than declared 30 times in the verb list. Re-running a create with
+  // the same key replays the first response instead of writing a second row.
+  let idempotencyKey;
+  const args = [];
+  for (let i = 0; i < rest.length; i++) {
+    const token = rest[i];
+    if (token === "--json") continue;
+    if (token === "--idempotency-key") { idempotencyKey = rest[++i]; continue; }
+    if (token.startsWith("--idempotency-key=")) { idempotencyKey = token.slice("--idempotency-key=".length); continue; }
+    args.push(token);
+  }
+
+  if (!command || command === "help") {
+    const topic = args[0];
+    const verb = topic ? verbByName(topic) : null;
+    if (verb) console.log(verbHelp(verb));
+    else if (topic && COMMAND_HELP[topic]) console.log(COMMAND_HELP[topic]);
+    else if (topic) {
+      console.error(`No such verb or command '${topic}'.\n`);
+      console.log(help());
+      return 1;
+    } else console.log(help());
+    return 0;
+  }
+
+  if (command === "login") {
+    const flags = plainFlags(args);
+    const unknown = Object.keys(flags).find((f) => !["url", "workspace", "key"].includes(f));
+    if (unknown) { console.error(`login: unknown option --${unknown}. Run \`gsjos help login\`.`); return 1; }
+
+    // A key can arrive three ways, and the order matters: an explicit flag is
+    // the caller being deliberate, the environment is a provisioned host, and
+    // the prompt is a person at a terminal. Only the last needs a TTY, so a
+    // headless session that passed one of the first two must not be sent to it.
+    let apiKey = flags.key === "-" ? await readStdin() : flags.key;
+    if (!apiKey) apiKey = process.env.GSJOS_API_KEY || "";
+
+    const canPrompt = Boolean(process.stdin.isTTY);
+    if (!apiKey && !canPrompt) {
+      console.error("login: no API key, and no terminal to ask for one.");
+      console.error("Pass --key <key>, pipe it in with --key -, or set GSJOS_API_KEY.");
+      return 1;
+    }
+
+    const apiUrl = flags.url || (canPrompt ? await ask(`API URL [${config.apiUrl}]: `) : "") || config.apiUrl;
+    const workspace = flags.workspace
+      || (canPrompt ? await ask(`Workspace slug${config.workspace ? ` [${config.workspace}]` : ""}: `) : "")
+      || config.workspace;
+    if (!apiKey) apiKey = await ask("API key (Settings → Agent runtime): ", { hidden: true });
+    if (!apiKey) { console.error("An API key is required."); return 1; }
+
+    const next = { apiUrl, workspace, apiKey };
+    try {
+      // Prove the key works before writing it, so a typo fails here rather than
+      // inside an agent run an hour later.
+      const schema = await call(next, { method: "GET", path: "/schema" });
+      const path = saveConfig(next);
+      console.log(`Connected to '${workspace}' — ${schema.counts?.people ?? 0} people, ${schema.counts?.leads ?? 0} leads.`);
+      console.log(`Saved to ${path}`);
+      return 0;
+    } catch (e) {
+      console.error(`Login failed: ${e.message}`);
+      return 1;
+    }
+  }
+
+  if (command === "whoami") {
+    console.log(`workspace: ${config.workspace || "(default)"}`);
+    console.log(`api:       ${config.apiUrl}`);
+    console.log(`key:       ${config.apiKey ? `${config.apiKey.slice(0, 18)}…` : "(none)"}`);
+    console.log(`config:    ${configPath()}`);
+    return 0;
+  }
+
+  if (command === "mcp") {
+    startMcpServer(config);
+    return null; // long-running; the process stays alive on stdin
+  }
+
+  if (command === "daemon") {
+    // Runs on the agent host, next to the runtime. Claims queued work from the
+    // OS over an outbound connection, so the box needs nothing inbound.
+    const flags = plainFlags(args);
+    await startDaemon(config, {
+      pollMs: Number(flags.poll) > 0 ? Number(flags.poll) : undefined,
+    });
+    return 0;
+  }
+
+  const verb = verbByName(command);
+  if (!verb) {
+    console.error(`Unknown command '${command}'. Run \`gsjos help\`.`);
+    return 1;
+  }
+
+  if (idempotencyKey && verb.kind !== "write") {
+    console.error(`${verb.name} is a read — --idempotency-key applies to writes only.`);
+    return 1;
+  }
+
+  try {
+    const data = await runVerb(config, verb.name, parseArgs(verb, args), { idempotencyKey });
+    if (wantsJson || !verb.text) console.log(JSON.stringify(data, null, 2));
+    else console.log(verb.text(data));
+    return 0;
+  } catch (e) {
+    console.error(e instanceof GsjosError ? e.message : String(e?.message ?? e));
+    return 1;
+  }
+}