@1db/cli 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,19 @@
-# Temporary Holding Version
+# 1db
 
-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.
+Connect websites to [1DB](https://www.1-db.com) lead capture from your terminal or an AI agent.
+
+```bash
+npx @1db/cli setup             # sign in through your browser + add 1DB to Claude Code
+```
+
+Then, in any project, ask Claude: “set up 1db for acme.com”. Or drive it yourself:
+
+```bash
+npx @1db/cli init acme.com     # scan + add the site, write DB_* vars to .env.local
+npx @1db/cli send acme.com     # send a test lead
+npx @1db/cli leads acme.com    # see it arrive
+npx @1db/cli keys acme.com     # print the site's endpoint, key and form slug
+```
+
+Run `npx @1db/cli help` for every command, or `npm i -g @1db/cli` to get a plain `1db` command. Zero dependencies, Node 18+.
+Credentials live in `~/.config/1db/config.json` (mode 600); `ONEDB_TOKEN` overrides.

package/bin/1db.mjs

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+// 1DB CLI: zero dependencies, talks to the agent API (/v1/agent/*) with an
+// agent token. Run `1db help` for commands.
+import {
+  CliError,
+  api,
+  bold,
+  dim,
+  ensureIgnored,
+  envLines,
+  green,
+  json,
+  parseArgs,
+  print,
+  readConfig,
+  settings,
+  table,
+  upsertEnvFile,
+  writeConfig,
+} from "../lib/core.mjs";
+import { browserLogin, installMcp, printMcpCommand, promptToken, saveToken } from "../lib/login.mjs";
+
+// ---------- commands ----------
+const commands = {
+  async login({ flags }) {
+    if (flags["api-url"] || flags["app-url"]) {
+      writeConfig({
+        ...readConfig(),
+        ...(flags["api-url"] ? { apiUrl: flags["api-url"] } : {}),
+        ...(flags["app-url"] ? { appUrl: flags["app-url"] } : {}),
+      });
+    }
+    const token = typeof flags.token === "string" ? flags.token : flags.paste ? await promptToken() : await browserLogin();
+    await saveToken(token);
+  },
+
+  async logout() {
+    const { token, ...rest } = readConfig();
+    writeConfig(rest);
+    print(token ? "Logged out." : "Already logged out.");
+  },
+
+  async whoami({ flags }) {
+    const me = await api("/v1/agent/me");
+    if (flags.json) return json(me);
+    print(`${me.organization?.name} ${dim(`(${me.user?.email ?? me.user?.name})`)}`);
+    print(dim(`API ${settings().apiUrl}`));
+  },
+
+  async websites({ flags }) {
+    const { websites } = await api("/v1/agent/websites");
+    if (flags.json) return json(websites);
+    if (websites.length === 0) return print("No websites yet. Add one with `1db init <domain>`.");
+    table(websites, ["slug", "name", "domain", "framework"]);
+  },
+
+  async init({ positional, flags }) {
+    const domain = positional[0];
+    if (!domain) throw new CliError("Usage: 1db init <domain> [--name \"Acme\"] [--env-file .env.local] [--prefix VITE_]");
+    if (!flags.json) print(dim(`Scanning ${domain} and setting it up in 1DB…`));
+    const result = await api("/v1/agent/onboard", { method: "POST", body: { domain, name: flags.name } });
+    if (flags.json) return json(result);
+    writeCredentials(result, flags);
+  },
+
+  async keys({ positional, flags }) {
+    const website = positional[0];
+    if (!website) throw new CliError("Usage: 1db keys <website> [--env-file .env.local]");
+    const result = await api(`/v1/agent/website?website=${encodeURIComponent(website)}`);
+    if (flags.json) return json(result);
+    writeCredentials(result, { ...flags, env: flags["env-file"] ? flags.env : false });
+  },
+
+  async send({ positional, flags }) {
+    const [website, ...pairs] = positional;
+    if (!website) throw new CliError("Usage: 1db send <website> [email=jane@acme.com message=\"Hi\" ...] [--form slug]");
+    const data = pairs.length
+      ? Object.fromEntries(pairs.map((p) => [p.split("=")[0], p.split("=").slice(1).join("=")]))
+      : undefined;
+    const result = await api("/v1/agent/test-lead", {
+      method: "POST",
+      body: { website, data, formSlug: typeof flags.form === "string" ? flags.form : undefined },
+    });
+    if (flags.json) return json(result);
+    if (result.status === 200) print(green(`Lead sent to ${result.formSlug}: ${result.result?.leadId}`));
+    else throw new CliError(`Ingest returned ${result.status}: ${JSON.stringify(result.result)}`);
+  },
+
+  async leads({ positional, flags }) {
+    const website = positional[0];
+    const limit = Number(flags.limit) || 20;
+    const { leads } = await api(`/v1/agent/leads?limit=${limit}${website ? `&website=${encodeURIComponent(website)}` : ""}`);
+    if (flags.json) return json(leads);
+    if (leads.length === 0) return print("No leads yet.");
+    table(
+      leads.map((l) => ({
+        when: new Date(l.createdAt).toLocaleString(),
+        email: l.email ?? "",
+        name: [l.data?.first_name, l.data?.last_name].filter(Boolean).join(" "),
+        sync: l.syncStatus,
+      })),
+      ["when", "email", "name", "sync"],
+    );
+  },
+
+  async mcp({ flags }) {
+    if (!settings().token) throw new CliError("Not logged in. Run `1db login` first.");
+    if (flags.install) return installMcp();
+    printMcpCommand();
+    print(dim("\nOr run `1db mcp --install` to do it for you."));
+  },
+
+  /** One step for a new machine: sign in, then add the MCP server to Claude Code. */
+  async setup({ flags }) {
+    if (!settings().token || flags.relogin) await commands.login({ flags });
+    else print(dim("Already logged in (use --relogin to switch organization)."));
+    installMcp();
+    print(`\nIn any project, ask Claude: ${bold("“set up 1db for acme.com”")}`);
+  },
+
+  help() {
+    print(`${bold("1db")}: connect websites to 1DB lead capture
+
+  1db setup                        Sign in and add 1DB's MCP server to Claude Code (start here)
+  1db login                        Sign in through your browser (or --token 1db_at_..., --paste)
+  1db whoami                       Show the organization the token acts for
+  1db websites                     List websites
+  1db init <domain>                Scan + add a website, write its keys to .env.local
+       [--name "Acme"] [--env-file .env] [--prefix VITE_|NEXT_PUBLIC_|PUBLIC_] [--no-env]
+  1db keys <website>               Print a website's endpoint, key and form slug
+  1db send <website> [k=v ...]     Send a (test) lead through the real ingest endpoint
+  1db leads [website] [--limit 20] Most recent leads
+  1db mcp [--install]              Print (or run) the command that adds 1DB's MCP server to Claude Code
+  1db logout
+
+Every command takes --json. Env: ONEDB_TOKEN, ONEDB_API_URL, ONEDB_APP_URL.`);
+  },
+};
+
+function writeCredentials(result, flags) {
+  const site = result.website;
+  print(`${result.created ? green("Created") : "Found"} ${bold(site.name)} ${dim(`(${site.slug}${site.domain ? `, ${site.domain}` : ""})`)}`);
+  const form = result.forms?.find((f) => f.slug === result.formSlug);
+  if (form) print(dim(`Form ${form.slug}: ${form.fields.map((f) => f.key + (f.required ? "*" : "")).join(", ")}`));
+
+  const prefix = typeof flags.prefix === "string" ? flags.prefix : "";
+  const entries = envLines(result.env, prefix);
+  if (flags.env === false) {
+    print();
+    for (const [k, v] of entries) print(`${k}=${v}`);
+  } else {
+    const file = typeof flags["env-file"] === "string" ? flags["env-file"] : ".env.local";
+    const path = upsertEnvFile(file, entries);
+    ensureIgnored(file);
+    print(green(`Wrote ${entries.map(([k]) => k).join(", ")} to ${path}`));
+  }
+  print();
+  print(`Send leads: POST ${result.leadsUrl}`);
+  print(dim(`  X-API-Key: $${prefix}DB_API_KEY`));
+  print(dim(`  {"formSlug": "$${prefix}DB_FORM_SLUG", "email": "...", ...}`));
+  print(dim(`Test it: 1db send ${site.slug}`));
+}
+
+// ---------- main ----------
+const [name = "help", ...rest] = process.argv.slice(2);
+const command = commands[name === "--help" || name === "-h" ? "help" : name];
+if (!command) {
+  console.error(`Unknown command "${name}". Run \`1db help\`.`);
+  process.exit(1);
+}
+try {
+  await command(parseArgs(rest));
+} catch (error) {
+  console.error(error instanceof CliError ? `Error: ${error.message}` : error);
+  process.exit(1);
+}

package/lib/core.mjs

@@ -0,0 +1,142 @@
+// Shared plumbing for the 1db CLI: config file, args, HTTP, output, env files.
+import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync, appendFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { execFileSync } from "node:child_process";
+
+export const DEFAULT_API_URL = "https://gallant-goshawk-513.convex.site";
+export const DEFAULT_APP_URL = "https://www.1-db.com";
+export const CONFIG_DIR = join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "1db");
+export const CONFIG_FILE = join(CONFIG_DIR, "config.json");
+
+// ---------- config ----------
+export function readConfig() {
+  try {
+    return JSON.parse(readFileSync(CONFIG_FILE, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+export function writeConfig(config) {
+  mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+  writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + "\n", { mode: 0o600 });
+  chmodSync(CONFIG_FILE, 0o600);
+}
+
+export function settings() {
+  const config = readConfig();
+  return {
+    token: process.env.ONEDB_TOKEN || config.token,
+    apiUrl: (process.env.ONEDB_API_URL || config.apiUrl || DEFAULT_API_URL).replace(/\/$/, ""),
+    appUrl: (process.env.ONEDB_APP_URL || config.appUrl || DEFAULT_APP_URL).replace(/\/$/, ""),
+  };
+}
+
+// ---------- args ----------
+export const BOOLEAN_FLAGS = new Set(["json", "help", "install", "paste", "relogin"]);
+
+export function parseArgs(argv) {
+  const positional = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith("--")) {
+      const [key, inline] = arg.slice(2).split("=", 2);
+      if (inline !== undefined) flags[key] = inline;
+      else if (key.startsWith("no-")) flags[key.slice(3)] = false;
+      else if (BOOLEAN_FLAGS.has(key)) flags[key] = true;
+      else if (argv[i + 1] !== undefined && !argv[i + 1].startsWith("--")) flags[key] = argv[++i];
+      else flags[key] = true;
+    } else positional.push(arg);
+  }
+  return { positional, flags };
+}
+
+// ---------- http ----------
+export class CliError extends Error {}
+
+export async function api(path, { method = "GET", body } = {}) {
+  const { token, apiUrl } = settings();
+  if (!token) throw new CliError("Not logged in. Run `1db login` (or set ONEDB_TOKEN).");
+  let res;
+  try {
+    res = await fetch(`${apiUrl}${path}`, {
+      method,
+      headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+  } catch (error) {
+    throw new CliError(`Can't reach ${apiUrl}: ${error.message}`);
+  }
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok && !(path === "/v1/agent/test-lead" && data.result)) {
+    throw new CliError(`${data.error || `HTTP ${res.status}`}${data.hint ? `\n  ${data.hint}` : ""}`);
+  }
+  return data;
+}
+
+// ---------- output ----------
+export const isTTY = process.stdout.isTTY;
+export const dim = (s) => (isTTY ? `\x1b[2m${s}\x1b[0m` : s);
+export const bold = (s) => (isTTY ? `\x1b[1m${s}\x1b[0m` : s);
+export const green = (s) => (isTTY ? `\x1b[32m${s}\x1b[0m` : s);
+export const print = (s = "") => process.stdout.write(s + "\n");
+export const json = (data) => print(JSON.stringify(data, null, 2));
+
+export function table(rows, columns) {
+  if (rows.length === 0) return;
+  const widths = columns.map((c) => Math.max(c.length, ...rows.map((r) => String(r[c] ?? "").length)));
+  print(bold(columns.map((c, i) => c.padEnd(widths[i])).join("  ")));
+  for (const r of rows) print(columns.map((c, i) => String(r[c] ?? "").padEnd(widths[i])).join("  "));
+}
+
+// ---------- env files ----------
+export function envLines(env, prefix) {
+  return Object.entries(env)
+    .filter(([, value]) => value)
+    .map(([key, value]) => [`${prefix}${key}`, value]);
+}
+
+/** Set keys in a dotenv file, replacing existing lines and keeping everything else. */
+export function upsertEnvFile(file, entries) {
+  const path = resolve(file);
+  const lines = existsSync(path) ? readFileSync(path, "utf8").split("\n") : [];
+  const pending = new Map(entries);
+  const out = lines.map((line) => {
+    const key = line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/)?.[1];
+    if (key && pending.has(key)) {
+      const value = pending.get(key);
+      pending.delete(key);
+      return `${key}=${value}`;
+    }
+    return line;
+  });
+  if (pending.size > 0) {
+    while (out.length && out[out.length - 1] === "") out.pop();
+    if (out.length) out.push("");
+    out.push("# 1DB lead capture");
+    for (const [key, value] of pending) out.push(`${key}=${value}`);
+  }
+  writeFileSync(path, out.join("\n").replace(/\n*$/, "\n"));
+  return path;
+}
+
+/** Keep secrets out of git: ignore the env file, and warn if git already tracks it. */
+export function ensureIgnored(file) {
+  const git = (args) => execFileSync("git", args, { stdio: "ignore" });
+  try {
+    git(["ls-files", "--error-unmatch", file]);
+    print(`Warning: git already tracks ${file}. Run \`git rm --cached ${file}\` so the key isn't committed.`);
+    return;
+  } catch {
+    // Not tracked (or not a git repo)
+  }
+  try {
+    git(["check-ignore", "-q", file]);
+  } catch (error) {
+    if (error.status !== 1) return; // 128: not a git repo
+    appendFileSync(resolve(".gitignore"), `\n${file.replace(/^\.\//, "")}\n`);
+    print(dim(`Added ${file} to .gitignore`));
+  }
+}

package/lib/login.mjs

@@ -0,0 +1,99 @@
+// Sign-in (browser device flow or pasted token) and Claude Code MCP install.
+import { hostname } from "node:os";
+import { createInterface } from "node:readline/promises";
+import { execFileSync, spawn } from "node:child_process";
+import { CliError, CONFIG_FILE, api, bold, dim, green, print, readConfig, settings, writeConfig } from "./core.mjs";
+
+// ---------- login ----------
+export function openBrowser(url) {
+  const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+  const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+  try {
+    spawn(cmd, args, { stdio: "ignore", detached: true }).on("error", () => {}).unref();
+  } catch {
+    // No browser here (CI, SSH): the printed link still works from any device
+  }
+}
+
+/** Device flow: print a code, open the approval page, poll until approved. */
+export async function browserLogin() {
+  const { apiUrl, appUrl } = settings();
+  const post = async (path, body) => {
+    const res = await fetch(`${apiUrl}${path}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    }).catch((error) => {
+      throw new CliError(`Can't reach ${apiUrl}: ${error.message}`);
+    });
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok) throw new CliError(data.error || `HTTP ${res.status}`);
+    return data;
+  };
+
+  const start = await post("/v1/agent/login/start", { clientName: `1db CLI on ${hostname()}` });
+  const url = `${appUrl}/cli?code=${start.userCode}`;
+  print(`Approve this sign-in in your browser: ${bold(url)}`);
+  print(`Check the code matches: ${bold(start.userCode)}`);
+  openBrowser(url);
+
+  const deadline = Date.now() + start.expiresIn * 1000;
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, (start.interval || 2) * 1000));
+    const result = await post("/v1/agent/login/poll", { deviceCode: start.deviceCode });
+    if (result.status === "approved") return result.token;
+    if (result.status === "denied") throw new CliError("Sign-in was denied in the browser.");
+    if (result.status === "expired") break;
+  }
+  throw new CliError("The sign-in code expired. Run `1db login` again.");
+}
+
+export async function promptToken() {
+  const { appUrl } = settings();
+  print(`Create an agent token at ${bold(`${appUrl}/settings/api-keys`)} (Agent tokens), then paste it here.`);
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const token = (await rl.question("Agent token: ")).trim();
+  rl.close();
+  return token;
+}
+
+export async function saveToken(token) {
+  if (!token?.startsWith("1db_at_")) throw new CliError("That isn't an agent token (they start with 1db_at_).");
+  const config = readConfig();
+  writeConfig({ ...config, token });
+  const me = await api("/v1/agent/me").catch((error) => {
+    writeConfig(config);
+    throw error;
+  });
+  print(green(`Logged in to ${me.organization?.name ?? "1DB"} as ${me.user?.email ?? me.user?.name ?? "you"}.`));
+  print(dim(`Saved to ${CONFIG_FILE}`));
+}
+
+export function mcpAddArgs() {
+  const { token, appUrl } = settings();
+  return ["mcp", "add", "--scope", "user", "--transport", "http", "1db", `${appUrl}/api/mcp`, "--header", `Authorization: Bearer ${token}`];
+}
+
+/** Print the `claude mcp add` command for clients this CLI can't drive. */
+export function printMcpCommand() {
+  print("Add 1DB to Claude Code in every project:\n");
+  print(`  claude ${mcpAddArgs().map((a) => (/\s/.test(a) ? `"${a}"` : a)).join(" ")}`);
+}
+
+export function installMcp() {
+  const run = (args) => execFileSync("claude", args, { stdio: "pipe" }).toString();
+  try {
+    run(["--version"]);
+  } catch {
+    print("Claude Code isn't installed here. Add the server to your MCP client with:");
+    return printMcpCommand();
+  }
+  try {
+    run(["mcp", "remove", "--scope", "user", "1db"]);
+  } catch {
+    // Not added yet
+  }
+  run(mcpAddArgs());
+  print(green("Added the 1db MCP server to Claude Code (user scope, every project)."));
+}
+

package/package.json

@@ -1,6 +1,29 @@
 {
   "name": "@1db/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Connect websites to 1DB from your terminal or an AI agent: onboard a domain, get its lead keys, send and list leads.",
+  "type": "module",
+  "bin": {
+    "1db": "bin/1db.mjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "UNLICENSED",
+  "publishConfig": { "access": "public" },
+  "homepage": "https://www.1-db.com/docs/guides/ai-agents",
+  "keywords": [
+    "1db",
+    "leads",
+    "lead-capture",
+    "mcp",
+    "claude",
+    "cli",
+    "crm"
+  ]
+}