lopebase 0.1.0 → 0.2.0

package/README.md

@@ -1,28 +1,95 @@
-# lopebase
+<p align="center">
+  <a href="https://lopebase.com"><img src="https://lopebase.com/icon-512.png" width="72" height="72" alt="LopeBase"></a>
+</p>
 
-Set up a project in LopeBase from its own repo. Your coding agent does the steps
-and stops for you only when it has to. See ADR 0020.
+<h1 align="center">lopebase</h1>
+
+<p align="center">
+  Set up <a href="https://lopebase.com">LopeBase</a> from your project's own folder.<br>
+  Your coding agent does the steps. It stops for you only when it has to.
+</p>
+
+<p align="center">
+  <a href="https://lopebase.com">Website</a> ·
+  <a href="https://lopebase.com/agents">For agents</a> ·
+  <a href="https://lopebase.com/pricing">Pricing</a> ·
+  <a href="https://www.npmjs.com/package/@lopebase/adapter">@lopebase/adapter</a>
+</p>
+
+---
+
+LopeBase is one place to see and run all of your products: traffic, search,
+signups, revenue, and errors side by side, with a weekly summary and an agent
+that can help. This CLI connects a project to it in a few minutes.
+
+## Quick start
+
+In the folder of any project you run:
 
 ```sh
-npx lopebase          # scan, pick what to connect, hand off to your agent
-npx lopebase login    # connect this computer: approve a code in the browser
-npx lopebase scan     # what the scan found (--json for machines)
-npx lopebase prompt   # print the agent prompt instead of launching an agent
-npx lopebase mcp      # stdio MCP server that forwards to your workspace
+npx lopebase
 ```
 
-`login` uses the device flow: it shows a short code, opens your workspace, and
-waits while you press Connect. `login --paste` takes a token from Settings,
-Agent access instead, for workspaces that do not offer device sign-in.
+1. **Scan.** It reads your `package.json` files, config file names, and the
+   variable *names* in example env files, then shows your stack, the services
+   you already use, and what is missing (for example analytics or error
+   tracking).
+2. **Connect this computer.** It opens your LopeBase workspace and shows a
+   short code. Check it matches and press Connect.
+3. **Pick what to connect.** Services already in your code are ticked; the
+   ones you do not use yet are offered, never forced.
+4. **Hand over to your agent.** It finds the coding agents you have installed
+   (Claude Code, Codex, Gemini CLI, opencode, Cursor Agent), gives the one you
+   choose the LopeBase tools, and starts it with what the scan found. The agent
+   does the setup and asks you when it needs a sign-in, a key, or a decision.
+
+No agent installed? It prints the prompt for you to paste instead.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `npx lopebase` | Scan, connect, choose, and hand over to your agent. |
+| `npx lopebase login` | Connect this computer to your workspace with a short code. `--paste` to paste an agent token instead. |
+| `npx lopebase scan` | Show what the scan found. `--json` for scripts. |
+| `npx lopebase prompt` | Print the setup prompt instead of starting an agent. |
+| `npx lopebase mcp` | Run the LopeBase tools as a local MCP server (stdio) for any agent. |
+| `npx lopebase adapter secret` | Print a new signing secret for [@lopebase/adapter](https://www.npmjs.com/package/@lopebase/adapter). Pipe it straight into your secret store. |
+| `npx lopebase adapter check <url>` | Test a running adapter, local or deployed, before you connect it. |
+
+## What it reads, and what it keeps
+
+- **Reads:** `package.json` files at the root and in `apps/`, `packages/`,
+  and similar folders; config file names such as `wrangler.toml` or
+  `vercel.json`; and the variable names in `.env.example` style files.
+- **Never reads** a real `.env` file, and never sends a value anywhere. Only
+  names leave your machine, and only to your own workspace.
+- **Keeps** one thing: an agent token in `~/.config/lopebase/auth.json`,
+  readable only by you. It lasts 30 days, acts as the workspace admin who
+  approved it, is limited to what that admin allowed, and can be revoked any
+  time under Settings, Agent access.
+- `LOPEBASE_TOKEN` and `LOPEBASE_URL` override the saved values, for CI or
+  another machine.
+
+## Use it with any agent
+
+`npx lopebase` sets this up for you. To add the tools by hand, register this
+as a stdio MCP server in your agent:
+
+```sh
+npx -y lopebase mcp
+```
+
+Or point an agent that supports remote MCP straight at your workspace, for
+example `https://yourteam.lopebase.com/api/mcp`. It will ask you to sign in.
+
+## Requirements
+
+Node 18 or newer. Works on macOS, Linux, and Windows.
 
-From this monorepo: `bun run lopebase` (from the repo root). To publish:
-`bun run build` makes `dist/lopebase.js` for Node, and `npm publish` runs
-verify and build first.
+## Help
 
-The scan reads package.json files, config file names, and env var names from
-example env files. It never reads a real `.env` file and never sends a value.
-The token is saved to `~/.config/lopebase/auth.json` (mode 600), or read from
-`LOPEBASE_TOKEN` and `LOPEBASE_URL`.
+Questions or problems: [contact@jackalope.digital](mailto:contact@jackalope.digital).
+Privacy: [app.lopebase.com/legal/privacy](https://app.lopebase.com/legal/privacy).
 
-`src/detect.ts` is also imported by the backoffice's `detect_stack` tool, so the
-terminal and the server give the same answer.
+LopeBase is made by [Jackalope Digital](https://jackalope.digital).

package/dist/lopebase.js

@@ -812,9 +812,282 @@ var Y2 = ({ indicator: t = "dots" } = {}) => {
   } };
 };
 
+// ../admin-adapter/src/security.ts
+var SIGNATURE_HEADER = "lopebase-signature";
+var enc = /* @__PURE__ */ new TextEncoder;
+function hex(bytes) {
+  return [...new Uint8Array(bytes)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+async function sha256Hex(data) {
+  return hex(await crypto.subtle.digest("SHA-256", data));
+}
+async function hmacHex(secret, message) {
+  let key = await crypto.subtle.importKey("raw", enc.encode(secret), { name: "HMAC", hash: "SHA-256" }, !1, ["sign"]);
+  return hex(await crypto.subtle.sign("HMAC", key, enc.encode(message)));
+}
+function newSigningSecret() {
+  let bytes = crypto.getRandomValues(new Uint8Array(32)), bin = "";
+  for (let b of bytes)
+    bin += String.fromCharCode(b);
+  return "lbs_" + btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function payload(t, method, pathAndQuery, bodyHash) {
+  return `${t}.${method.toUpperCase()}.${pathAndQuery}.${bodyHash}`;
+}
+async function signRequest(input) {
+  let t = input.timestamp ?? Math.floor(Date.now() / 1000), body = typeof input.body === "string" ? enc.encode(input.body) : input.body ?? new Uint8Array, sig = await hmacHex(input.secret, payload(t, input.method, input.pathAndQuery, await sha256Hex(body)));
+  return `t=${t},v1=${sig}`;
+}
+var SENSITIVE_PARTS = /* @__PURE__ */ new Set([
+  "password",
+  "passwd",
+  "passcode",
+  "pwd",
+  "hash",
+  "hashed",
+  "salt",
+  "secret",
+  "secrets",
+  "token",
+  "tokens",
+  "credential",
+  "credentials",
+  "ssn",
+  "card",
+  "cvv",
+  "cvc",
+  "iban",
+  "otp",
+  "mfa",
+  "totp",
+  "session",
+  "cookie"
+]), SENSITIVE_JOINED = /apikey|privatekey|secretkey|accesskey|accountnumber|routingnumber|stripecustomer|paymentmethod|recoverycode/;
+function isSensitiveFieldName(name) {
+  let parts = name.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+  if (parts.some((p) => SENSITIVE_PARTS.has(p)))
+    return !0;
+  return SENSITIVE_JOINED.test(parts.join(""));
+}
+
+// ../admin-adapter/src/adapter.ts
+var DEFAULT_BASE_PATH = "/api/lopebase";
+// ../admin-adapter/src/conformance.ts
+import { strict as assert } from "node:assert";
+async function body(res) {
+  return await res.json();
+}
+function conformanceChecks(opts) {
+  if (!opts.adapter && !opts.baseUrl)
+    throw Error("conformanceChecks needs an adapter or a baseUrl");
+  let remote = !opts.adapter, base = opts.baseUrl ? opts.baseUrl.replace(/\/$/, "") : `${opts.origin ?? "https://property.test"}${(opts.basePath ?? opts.adapter?.config.basePath ?? DEFAULT_BASE_PATH).replace(/\/$/, "")}`, send = (req) => opts.adapter ? opts.adapter.handle(req) : fetch(req);
+  async function signedHeaders(url, method, bodyText, timestamp) {
+    if (opts.secret) {
+      let u = new URL(url);
+      return {
+        [SIGNATURE_HEADER]: await signRequest({
+          secret: opts.secret,
+          method,
+          pathAndQuery: u.pathname + u.search,
+          body: bodyText,
+          timestamp
+        })
+      };
+    }
+    return opts.token ? { authorization: `Bearer ${opts.token}` } : {};
+  }
+  let authed = async (path, init) => {
+    let url = base + path, method = init?.method ?? "GET", bodyText = typeof init?.body === "string" ? init.body : void 0;
+    return send(new Request(url, {
+      ...init,
+      headers: {
+        "content-type": "application/json",
+        ...await signedHeaders(url, method, bodyText),
+        ...init?.headers
+      }
+    }));
+  }, resources = () => authed("/resources").then((r) => body(r));
+  return [
+    {
+      name: "GET /health returns { ok } without auth",
+      async run() {
+        let res = await send(new Request(`${base}/health`));
+        assert.equal(res.status, 200);
+        let b = await body(res);
+        assert.equal(typeof b.ok, "boolean");
+      }
+    },
+    {
+      name: "requests without a valid token get 401",
+      async run() {
+        let res = await send(new Request(`${base}/resources`));
+        assert.equal(res.status, 401);
+      }
+    },
+    {
+      name: "GET /resources returns a catalog with field metadata",
+      async run() {
+        let res = await authed("/resources");
+        assert.equal(res.status, 200);
+        let b = await body(res);
+        assert.ok(Array.isArray(b.resources));
+        for (let r of b.resources)
+          assert.ok(r.name && r.label && r.readCapability), assert.ok(Array.isArray(r.fields));
+      }
+    },
+    {
+      name: "GET /actions returns a catalog with param specs",
+      async run() {
+        let res = await authed("/actions");
+        assert.equal(res.status, 200);
+        let b = await body(res);
+        assert.ok(Array.isArray(b.actions));
+        for (let a of b.actions)
+          assert.ok(a.name && a.label && a.capability), assert.ok(Array.isArray(a.params));
+      }
+    },
+    {
+      name: "GET /resources/:name paginates ({ rows, total? })",
+      async run() {
+        let cat = await resources(), name = opts.sampleResource ?? cat.resources[0]?.name;
+        if (!name)
+          return;
+        let res = await authed(`/resources/${name}?limit=5`);
+        assert.equal(res.status, 200);
+        let page = await body(res);
+        assert.ok(Array.isArray(page.rows));
+      }
+    },
+    {
+      name: "GET /resources/:name/:id returns a row or 404-null",
+      async run() {
+        let cat = await resources(), meta = opts.sampleResource ? cat.resources.find((r) => r.name === opts.sampleResource) : cat.resources[0];
+        if (!meta)
+          return;
+        let first = (await body(await authed(`/resources/${meta.name}?limit=1`))).rows[0];
+        if (!first)
+          return;
+        let idField = meta.fields[0]?.name ?? "id", res = await authed(`/resources/${meta.name}/${encodeURIComponent(String(first[idField]))}`);
+        assert.ok(res.status === 200 || res.status === 404);
+      }
+    },
+    {
+      name: "GET /audit returns { rows: AuditEvent[] }",
+      async run() {
+        let res = await authed("/audit");
+        assert.equal(res.status, 200);
+        let b = await body(res);
+        assert.ok(Array.isArray(b.rows));
+      }
+    },
+    {
+      name: "an unknown route returns 404",
+      async run() {
+        let res = await authed("/does-not-exist");
+        assert.equal(res.status, 404);
+      }
+    },
+    {
+      name: "no field in the catalog looks like a secret unless marked safe",
+      async run() {
+        let cat = await resources();
+        for (let r of cat.resources)
+          for (let f of r.fields)
+            assert.ok(!isSensitiveFieldName(f.name) || f.sensitive === "allow", `${r.name}.${f.name} looks sensitive`);
+      }
+    },
+    {
+      name: "rows contain only declared fields, and a page is at most 100",
+      async run() {
+        let cat = await resources();
+        for (let r of cat.resources) {
+          let res = await authed(`/resources/${r.name}?limit=1000`);
+          assert.equal(res.status, 200);
+          let page = await body(res);
+          assert.ok(page.rows.length <= 100, `${r.name} returned ${page.rows.length} rows`);
+          let declared = /* @__PURE__ */ new Set(["id", ...r.fields.map((f) => f.name)]);
+          for (let row of page.rows)
+            for (let k of Object.keys(row))
+              assert.ok(declared.has(k), `${r.name} returned undeclared field ${k}`);
+        }
+      }
+    },
+    ...opts.secret ? [
+      {
+        name: "a stale or tampered signature gets 401",
+        async run() {
+          let url = `${base}/resources`, stale = await signedHeaders(url, "GET", void 0, Math.floor(Date.now() / 1000) - 3600);
+          assert.equal((await send(new Request(url, { headers: stale }))).status, 401);
+          let good = await signedHeaders(url, "GET", void 0), tampered = `${url}?limit=1`;
+          assert.equal((await send(new Request(tampered, { headers: good }))).status, 401);
+        }
+      }
+    ] : [],
+    {
+      name: "a mutation writes an audit row (PATCH round-trips into /audit)",
+      async run() {
+        let writable = (await resources()).resources.find((r) => r.writeCapability && r.fields.some((f) => f.editable));
+        if (!writable || remote)
+          return;
+        let row = (await body(await authed(`/resources/${writable.name}?limit=1`))).rows[0];
+        if (!row)
+          return;
+        let idField = writable.fields[0]?.name ?? "id", editField = writable.fields.find((f) => f.editable)?.name;
+        if (!editField)
+          return;
+        let before = await body(await authed("/audit")), res = await authed(`/resources/${writable.name}/${encodeURIComponent(String(row[idField]))}`, {
+          method: "PATCH",
+          body: JSON.stringify({ patch: { [editField]: row[editField] } })
+        });
+        assert.equal(res.status, 200);
+        let after = await body(await authed("/audit"));
+        assert.ok(after.rows.length > before.rows.length, "expected a new audit row");
+      }
+    }
+  ];
+}
 // bin/lopebase.ts
 var import_picocolors3 = __toESM(require_picocolors(), 1);
 
+// src/adapter-check.ts
+async function checkAdapter(input) {
+  let log = input.log ?? (() => {}), failed = [], passed = 0, base = input.baseUrl.replace(/\/$/, ""), url = new URL(`${base}/resources`), status;
+  try {
+    let headers = input.secret ? {
+      [SIGNATURE_HEADER]: await signRequest({
+        secret: input.secret,
+        method: "GET",
+        pathAndQuery: url.pathname + url.search
+      })
+    } : { authorization: `Bearer ${input.token ?? ""}` };
+    status = (await fetch(url, { headers })).status;
+  } catch (e) {
+    let error = `Could not reach ${base} (${e instanceof Error ? e.message : String(e)}).`;
+    return log(`FAIL  ${error}`), { passed, failed: [{ name: "reachable", error }] };
+  }
+  if (status === 401) {
+    let error = input.secret ? "The adapter refused the signature. The secret here does not match the app's LOPEBASE_SIGNING_SECRET, or the two clocks are more than 5 minutes apart." : "The adapter refused the token.";
+    return log(`FAIL  ${error}`), { passed, failed: [{ name: "authenticated", error }] };
+  }
+  if (status === 404) {
+    let error = `Nothing at ${base}/resources. Check the base URL, usually https://your-app/api/lopebase.`;
+    return log(`FAIL  ${error}`), { passed, failed: [{ name: "found", error }] };
+  }
+  for (let c of conformanceChecks({
+    baseUrl: input.baseUrl,
+    secret: input.secret,
+    token: input.token
+  }))
+    try {
+      await c.run(), passed++, log(`pass  ${c.name}`);
+    } catch (e) {
+      let error = e instanceof Error ? e.message.split(`
+`)[0] : String(e);
+      failed.push({ name: c.name, error }), log(`FAIL  ${c.name}: ${error}`);
+    }
+  return { passed, failed };
+}
+
 // src/agents.ts
 import { spawnSync } from "node:child_process";
 var AGENTS = [
@@ -1376,7 +1649,22 @@ function scanProject(root) {
 }
 
 // bin/lopebase.ts
-var [command = "init", ...rest] = process.argv.slice(2), flag = (name) => rest.includes(`--${name}`), option = (name) => {
+var [command = "init", ...rest] = process.argv.slice(2), HELP = `
+${import_picocolors3.default.bgYellow(import_picocolors3.default.black(" LopeBase "))}  Set up LopeBase from this project's folder.
+
+${import_picocolors3.default.bold("Usage")}
+  npx lopebase                      scan, connect, and hand over to your agent
+  npx lopebase login                connect this computer (--paste for a token)
+  npx lopebase scan [--json]        show what the scan found
+  npx lopebase prompt               print the setup prompt instead
+  npx lopebase mcp                  run the LopeBase tools as a stdio MCP server
+  npx lopebase adapter secret       print a new @lopebase/adapter signing secret
+  npx lopebase adapter check <url>  test a running adapter (reads LOPEBASE_SIGNING_SECRET)
+
+${import_picocolors3.default.bold("Learn more")}
+  ${import_picocolors3.default.cyan("https://lopebase.com")}
+  Help: contact@jackalope.digital
+`, flag = (name) => rest.includes(`--${name}`), option = (name) => {
   let i = rest.indexOf(`--${name}`);
   return i >= 0 ? rest[i + 1] : rest.find((a) => a.startsWith(`--${name}=`))?.split("=")[1];
 }, cwd = process.cwd();
@@ -1560,6 +1848,28 @@ async function main() {
       let facts = scanProject(cwd), detection = detectStack(facts);
       return console.log(onboardingPrompt({ facts, detection, chosen: [] }));
     }
+    case "adapter": {
+      let sub = rest[0];
+      if (sub === "secret")
+        return process.stdout.write(`${newSigningSecret()}
+`);
+      if (sub === "check" && rest[1]) {
+        let envName = option("secret-env") ?? "LOPEBASE_SIGNING_SECRET", secret = process.env[envName]?.trim(), token = process.env.LOPEBASE_ADAPTER_TOKEN?.trim();
+        if (!secret && !token)
+          console.error(`Set ${envName} to the adapter's signing secret (or LOPEBASE_ADAPTER_TOKEN for an older bearer adapter).`), process.exit(1);
+        console.log(`Checking ${rest[1]}`);
+        let res = await checkAdapter({
+          baseUrl: rest[1],
+          secret,
+          token: secret ? void 0 : token,
+          log: (l) => console.log(l.startsWith("FAIL") ? import_picocolors3.default.red(l) : import_picocolors3.default.green(l))
+        });
+        console.log(res.failed.length ? import_picocolors3.default.red(`${res.failed.length} failed, ${res.passed} passed`) : import_picocolors3.default.green(`All ${res.passed} checks passed. Ready to connect.`)), process.exit(res.failed.length ? 1 : 0);
+      }
+      return console.log(`Usage:
+  lopebase adapter secret              print a new signing secret
+  lopebase adapter check <base-url>    test a running adapter (reads LOPEBASE_SIGNING_SECRET)`), process.exit(sub ? 1 : 0);
+    }
     case "mcp": {
       let auth = loadAuth();
       if (!auth)
@@ -1567,7 +1877,7 @@ async function main() {
       return runMcpProxy(auth);
     }
     default:
-      console.log("Usage: lopebase [init|login|scan|prompt|mcp]"), process.exit(command === "--help" || command === "-h" ? 0 : 1);
+      console.log(HELP), process.exit(command === "--help" || command === "-h" || command === "help" ? 0 : 1);
   }
 }
 main();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "lopebase",
-  "version": "0.1.0",
-  "description": "Set up a project in LopeBase from your terminal, with your own coding agent doing the steps.",
+  "version": "0.2.0",
+  "description": "Set up LopeBase from your project's folder: scan your stack, connect your workspace, and let your coding agent do the rest.",
   "type": "module",
   "bin": {
     "lopebase": "dist/lopebase.js"
@@ -25,25 +25,35 @@
     "dev": "bun bin/lopebase.ts"
   },
   "devDependencies": {
+    "@clack/prompts": "^0.11.0",
+    "@lopebase/adapter": "workspace:*",
     "@types/node": "^22.0.0",
+    "picocolors": "^1.1.1",
     "typescript": "~5.7.0",
-    "vitest": "^4.0.0",
-    "@clack/prompts": "^0.11.0",
-    "picocolors": "^1.1.1"
+    "vitest": "^4.0.0"
   },
   "license": "UNLICENSED",
   "homepage": "https://lopebase.com",
   "keywords": [
     "lopebase",
-    "mcp",
     "cli",
+    "mcp",
     "agent",
-    "onboarding"
+    "claude-code",
+    "codex",
+    "onboarding",
+    "analytics",
+    "search-console",
+    "dashboard"
   ],
   "engines": {
     "node": ">=18"
   },
   "publishConfig": {
     "access": "public"
+  },
+  "author": "LopeBase by Jackalope Digital <contact@jackalope.digital> (https://lopebase.com)",
+  "bugs": {
+    "email": "contact@jackalope.digital"
   }
 }