driggsby 0.1.41 → 0.2.0

package/dist/dev/tool-allowlist.js

@@ -0,0 +1,18 @@
+// The read-only tools a Driggsby app may call. This mirrors the allowlist
+// Driggsby enforces server-side for embedded apps; the dev host enforces it
+// too so an app that works locally works identically after deploy, and a
+// disallowed call never even reaches Driggsby.
+export const APP_TOOL_ALLOWLIST = new Set([
+    "get_history",
+    "get_overview",
+    "list_accounts",
+    "list_assets_and_liabilities",
+    "list_findings",
+    "list_investment_holdings",
+    "list_outstanding_debts",
+    "list_recurring_transactions",
+    "query_cash_sql",
+    "query_investment_sql",
+    "search_cash_transactions",
+    "search_investment_activity",
+]);

package/dist/dev/watcher.js

@@ -0,0 +1,76 @@
+// Change detection for the serve folder. `driggsby dev` tells the embedded
+// app to reload when a served file changes. Polling a directory signature —
+// names, sizes, mtimes — is deliberately boring: it behaves identically on
+// macOS, Linux, and Windows (recursive fs.watch does not), and a scaffolded
+// static app is a handful of files, so a walk every second is nothing.
+import { readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+export const WATCH_POLL_MS = 1_000;
+// One stable string describing the current served files; any edit, add,
+// delete, or rename changes it. Skips what dev never serves (dotfiles,
+// node_modules), so churn in an ignored folder can't cause reloads.
+export async function directorySignature(serveDirectory) {
+    const parts = [];
+    await collectSignature(serveDirectory, "", parts);
+    return parts.join("\n");
+}
+async function collectSignature(directory, prefix, parts) {
+    let entries;
+    try {
+        entries = await readdir(directory, { withFileTypes: true });
+    }
+    catch {
+        parts.push(`${prefix}<unreadable>`);
+        return;
+    }
+    entries.sort((a, b) => (a.name < b.name ? -1 : 1));
+    for (const entry of entries) {
+        if (entry.name.startsWith(".") || entry.name === "node_modules") {
+            continue;
+        }
+        const entryPath = join(directory, entry.name);
+        const entryKey = `${prefix}${entry.name}`;
+        if (entry.isDirectory()) {
+            await collectSignature(entryPath, `${entryKey}/`, parts);
+            continue;
+        }
+        if (!entry.isFile()) {
+            continue;
+        }
+        try {
+            const stats = await stat(entryPath);
+            parts.push(`${entryKey}:${String(stats.size)}:${String(stats.mtimeMs)}`);
+        }
+        catch {
+            parts.push(`${entryKey}:<gone>`);
+        }
+    }
+}
+// Polls until stopped; calls onChange once per observed signature change.
+export function watchDirectory(serveDirectory, onChange, pollMs = WATCH_POLL_MS) {
+    let stopped = false;
+    let lastSignature = null;
+    let timer = null;
+    const poll = async () => {
+        const signature = await directorySignature(serveDirectory);
+        if (stopped) {
+            return;
+        }
+        if (lastSignature !== null && signature !== lastSignature) {
+            onChange();
+        }
+        lastSignature = signature;
+        timer = setTimeout(() => {
+            void poll();
+        }, pollMs);
+        // Never keep the process alive just to poll.
+        timer.unref();
+    };
+    void poll();
+    return () => {
+        stopped = true;
+        if (timer !== null) {
+            clearTimeout(timer);
+        }
+    };
+}

package/dist/help.js

@@ -0,0 +1,180 @@
+// Help text is contract, asserted byte-for-byte against the fixtures in
+// __fixtures__/. The mcp and mcp setup blocks are still byte-identical to
+// the Rust CLI's output (captured from driggsby 0.1.42), including the clap
+// quirks (the trailing spaces on the blank line before [possible values] in
+// the long setup help, and the distinct short/long setup variants). The root
+// help grew past the Rust CLI when login/logout landed; its fixture pins the
+// current text.
+export const ROOT_HELP = `Usage: npx driggsby@latest <COMMAND>
+
+Commands:
+  mcp       Set up Driggsby MCP clients.
+  login     Sign in to Driggsby and save an app token on this machine.
+  logout    Remove the saved Driggsby app token.
+  init      Create a new Driggsby app in a new folder.
+  dev       Preview the app in this directory with your live Driggsby data.
+  deploy    Deploy the app in this directory to Driggsby.
+  rollback  Switch which deployed version of your app is live.
+  versions  List your deployed app's versions.
+
+Options:
+  -h, --help     Print help
+  -V, --version  Print version
+
+Examples:
+  npx driggsby@latest mcp setup
+  npx driggsby@latest mcp setup claude-code
+  npx driggsby@latest mcp setup codex
+  npx driggsby@latest mcp setup other
+  npx driggsby@latest login
+  npx driggsby@latest init money-dash
+  npx driggsby@latest dev
+  npx driggsby@latest deploy
+`;
+export const INIT_HELP = `Create a new Driggsby app in a new folder.
+
+This makes a small static app — index.html, app.js, styles.css — plus the
+driggsby.json that names it. The app shows sample data on its own, and your
+real Driggsby data when it runs inside Driggsby.
+
+Usage: npx driggsby@latest init [NAME]
+
+Arguments:
+  [NAME]  The app's name: 3-63 lowercase letters, digits, and dashes.
+          Any readable name works — the first deploy assigns the app's
+          address by adding a unique ending, like
+          your-name-x7k2qf.driggsby.dev — so names never collide.
+          Asked for when omitted.
+
+Options:
+  -h, --help  Print help
+`;
+export const LOGIN_HELP = `Sign in to Driggsby and save an app token on this machine.
+
+This opens a Driggsby approval page in your browser. Approving it issues an
+app token that lets this machine read your Driggsby data and deploy Driggsby
+apps. The token is saved locally for other driggsby commands and is never
+printed.
+
+Usage: npx driggsby@latest login
+
+Options:
+  -h, --help  Print help
+`;
+export const LOGOUT_HELP = `Remove the saved Driggsby app token.
+
+This removes the app token that npx driggsby@latest login saved on this
+machine. It does not sign you out of Driggsby in your browser or in your AI
+clients.
+
+Usage: npx driggsby@latest logout
+
+Options:
+  -h, --help  Print help
+`;
+export const DEV_HELP = `Preview the app in this directory with your live Driggsby data.
+
+This runs the app locally, embedded the same way Driggsby embeds it after a
+deploy, so what you see here is what a deploy will show. Edits to the app's
+files reload the page on save.
+
+While dev runs, the preview serves your financial data to this machine —
+other websites can't reach it, but anything running locally can, so stop
+it when you're done.
+
+Sign in first with npx driggsby@latest login.
+
+Usage: npx driggsby@latest dev
+
+Options:
+  -h, --help  Print help
+`;
+export const DEPLOY_HELP = `Deploy the app in this directory to Driggsby.
+
+This reads driggsby.json next to your app files, uploads only what changed,
+and makes the new version live at your app's driggsby.dev address. The
+first deploy creates the app: Driggsby assigns its address (your name plus
+a unique ending) and saves it back into driggsby.json. With --preview, the
+version is uploaded and kept ready without changing what's live.
+
+Sign in first with npx driggsby@latest login.
+
+Usage: npx driggsby@latest deploy [--preview]
+
+Options:
+      --preview  Upload this version without making it live.
+  -h, --help     Print help
+`;
+export const ROLLBACK_HELP = `Switch which deployed version of your app is live.
+
+Driggsby keeps your app's recent versions, so going live with any of them —
+older or newer — re-uploads nothing. Without --to, this lists the versions
+you can choose from and asks for one.
+
+Usage: npx driggsby@latest rollback [--to <VERSION>]
+
+Options:
+      --to <VERSION>  The version number to make live, as shown by
+                      npx driggsby@latest versions.
+  -h, --help          Print help
+`;
+export const VERSIONS_HELP = `List your deployed app's versions.
+
+Shows every version Driggsby has kept for the app in this directory, which
+one is live, and the version numbers npx driggsby@latest rollback accepts.
+
+Usage: npx driggsby@latest versions
+
+Options:
+  -h, --help  Print help
+`;
+export const MCP_HELP = `Set up Driggsby MCP clients.
+
+Usage: npx driggsby@latest mcp <COMMAND>
+
+Commands:
+  setup  Set up Driggsby for an AI client.
+
+Options:
+  -h, --help  Print help
+`;
+// mcp setup -h: clap's compact table.
+export const MCP_SETUP_HELP_SHORT = `Set up Driggsby for an AI client.
+
+Usage: npx driggsby@latest mcp setup [OPTIONS] [CLIENT]
+
+Arguments:
+  [CLIENT]  Client ID: claude-code, codex, or other.
+
+Options:
+      --print     Print the native setup command instead of running it.
+  -s <MCP_SCOPE>  Claude Code only. Values: local, user (default). [possible values: local, user]
+  -h, --help      Print help (see more with '--help')
+`;
+// mcp setup --help: clap's long form. The trailing spaces after the
+// "Values: local, user (default)." line are clap's own rendering.
+export const MCP_SETUP_HELP_LONG = `Set up Driggsby for an AI client.
+
+Run once per client. This adds Driggsby's MCP URL to supported native client configs. Choose other
+to print OAuth-based remote MCP setup instructions.
+
+Supported clients: claude-code, codex, other.
+
+Usage: npx driggsby@latest mcp setup [OPTIONS] [CLIENT]
+
+Arguments:
+  [CLIENT]
+          Client ID: claude-code, codex, or other.
+
+Options:
+      --print
+          Print the native setup command instead of running it.
+
+  -s <MCP_SCOPE>
+          Claude Code only. Values: local, user (default).
+${"          "}
+          [possible values: local, user]
+
+  -h, --help
+          Print help (see a summary with '-h')
+`;

package/dist/init/init-command.js

@@ -0,0 +1,114 @@
+// driggsby init: scaffold a new Driggsby app in a new folder. The result is
+// a no-build static app (index.html + app.js + styles.css) that renders
+// sample data on its own and live data inside Driggsby, plus the
+// driggsby.json that names it. With a slug argument it acts directly;
+// without one, it asks (a person) or explains the exact re-run (an agent or
+// script).
+import { mkdir, readdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { slugProblem } from "@driggsby/deploy";
+import { CliError } from "../cli-error.js";
+import { quotedForTerminal, wrapProse } from "../terminal-text.js";
+import { APP_JS, STYLES_CSS, driggsbyJsonText, indexHtml } from "./templates.js";
+// Argv and prompt answers echo back inside quotes with this cap; a slug can
+// never be longer than 63 characters, so the cap only trims hostile input.
+const MAX_SLUG_ECHO_CHARS = 80;
+const INIT_RETRY_LINES = "Pick another name and re-run:\n  npx driggsby@latest init <NAME>";
+function defaultInitIo() {
+    return {
+        out: (text) => {
+            process.stdout.write(text);
+        },
+        ask: async (question) => {
+            const { createInterface } = await import("node:readline/promises");
+            const readline = createInterface({ input: process.stdin, output: process.stdout });
+            try {
+                return await readline.question(question);
+            }
+            finally {
+                readline.close();
+            }
+        },
+        interactive: process.stdin.isTTY && process.stdout.isTTY,
+    };
+}
+export async function runInit(options, io = defaultInitIo()) {
+    const parentDirectory = options.parentDirectory ?? process.cwd();
+    const slug = options.slug ?? (await askForSlug(io));
+    const problem = slugProblem(slug);
+    if (problem !== null) {
+        // slugProblem's wording spans lines; re-flow it as one paragraph. A bad
+        // argv slug is a usage error (exit 2); a bad prompt answer is the same
+        // conversational exit 1 the other interactive commands use.
+        const flatProblem = problem.replaceAll("\n", " ");
+        throw new CliError(`${wrapProse(`${quotedForTerminal(slug, MAX_SLUG_ECHO_CHARS)} won't work as an app name: ${flatProblem}.`)}\n\n${INIT_RETRY_LINES}`, options.slug === null ? 1 : 2);
+    }
+    // The slug passed the strict pattern above, so from here it is safe to
+    // print bare and to interpolate into the scaffolded index.html.
+    const appDirectory = join(parentDirectory, slug);
+    await ensureNewOrEmptyDirectory(appDirectory, slug);
+    await writeScaffold(appDirectory, slug);
+    io.out(`✓ Created   ${slug}/\n\n` +
+        "  index.html     the page\n" +
+        "  app.js         fetches and renders your data — start editing here\n" +
+        "  styles.css     the look\n" +
+        "  driggsby.json  the app's name and which folder deploys\n\n" +
+        `${wrapProse("The app shows sample data on its own; dev and deploy both give it your real accounts.")}\n\n` +
+        "Next:\n" +
+        `  cd ${slug}\n` +
+        "  npx driggsby@latest dev      preview with your real data\n" +
+        "  npx driggsby@latest deploy   put it live on driggsby.dev\n");
+    return 0;
+}
+async function askForSlug(io) {
+    if (!io.interactive) {
+        throw new CliError("This terminal can't prompt for a name, so pass one directly:\n" +
+            "  npx driggsby@latest init <NAME>\n\n" +
+            wrapProse("Any readable name works (3-63 lowercase letters, digits, and dashes) — Driggsby adds a unique ending at first deploy (<NAME>-x7k2qf.driggsby.dev), so names never collide."), 2);
+    }
+    io.out("The name starts your app's address — a unique ending is added at first\n" +
+        "deploy: <NAME>-x7k2qf.driggsby.dev\n\n");
+    const answer = await io.ask("Name your app (like money-dash): ");
+    return answer.trim();
+}
+// The scaffold only ever writes into a folder it created or one that exists
+// empty — never into files someone already has.
+async function ensureNewOrEmptyDirectory(appDirectory, slug) {
+    try {
+        await mkdir(appDirectory);
+        return;
+    }
+    catch (error) {
+        if (error.code !== "EEXIST") {
+            throw new CliError(wrapProse(`We couldn't create a ${slug} folder here. Check that this directory is writable and try again.`), 1);
+        }
+    }
+    let entries;
+    try {
+        entries = await readdir(appDirectory);
+    }
+    catch {
+        // The existing path isn't a readable directory (it's a file, or
+        // unreadable) — either way it isn't a safe scaffold target.
+        throw new CliError(existsMessage(slug), 1);
+    }
+    if (entries.length > 0) {
+        throw new CliError(existsMessage(slug), 1);
+    }
+}
+function existsMessage(slug) {
+    return `${wrapProse(`Something named ${slug} already exists here and isn't an empty folder. Pick another name, or move it first.`)}\n\n${INIT_RETRY_LINES}`;
+}
+async function writeScaffold(appDirectory, slug) {
+    // "wx" refuses to overwrite: even a file that appears between the
+    // emptiness check and this write stays untouched.
+    const writes = [
+        ["index.html", indexHtml(slug)],
+        ["app.js", APP_JS],
+        ["styles.css", STYLES_CSS],
+        ["driggsby.json", driggsbyJsonText(slug)],
+    ];
+    for (const [name, content] of writes) {
+        await writeFile(join(appDirectory, name), content, { flag: "wx" });
+    }
+}

package/dist/init/templates.js

@@ -0,0 +1,271 @@
+// The files `driggsby init` scaffolds: a no-build static app plus the
+// driggsby.json that names it. The app renders obviously-synthetic sample
+// data on its own, and live Driggsby data once a Driggsby host embeds it
+// (`driggsby dev` locally, or the Driggsby console after a deploy). The
+// sample values below are invented for the template and match the real
+// tool result shapes only in structure, so the scaffold's render functions
+// work unchanged when live data replaces them.
+export function indexHtml(slug) {
+    return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>${slug}</title>
+  <link rel="stylesheet" href="styles.css">
+</head>
+<body>
+  <main>
+    <header>
+      <h1>${slug}</h1>
+      <p class="sample-note" id="sample-note">Sample data — your real accounts
+      appear when this app runs inside Driggsby.</p>
+    </header>
+    <section aria-label="Overview">
+      <div class="stat-grid" id="overview"></div>
+    </section>
+    <section aria-label="Accounts">
+      <h2>Accounts</h2>
+      <div id="accounts"></div>
+    </section>
+  </main>
+  <script type="module" src="/-/driggsby-sdk.js"></script>
+  <script type="module" src="app.js"></script>
+</body>
+</html>
+`;
+}
+export const APP_JS = `// Your app's code. Edit anything — driggsby dev reloads the page on save.
+//
+// Reading data is one call:
+//
+//   driggsby.watch(tool, params, callback)
+//
+// Each watch is a live subscription: the callback runs with a fresh result
+// whenever your Driggsby data changes. The sample data below matches the
+// real result shapes, so the render functions work unchanged either way.
+
+// ---------------------------------------------------------------------------
+// Sample data. Every name and number here is invented. It renders only
+// until real data arrives from Driggsby.
+// ---------------------------------------------------------------------------
+
+const SAMPLE_OVERVIEW = {
+  summary_rollups: {
+    net_worth_estimate: { amount: "52340.00", currency_code: "USD" },
+    cash: { amount: "8120.00", currency_code: "USD" },
+    total_assets: { amount: "61540.00", currency_code: "USD" },
+    total_liabilities: { amount: "9200.00", currency_code: "USD" }
+  }
+};
+
+const SAMPLE_ACCOUNTS = {
+  linked_accounts: [
+    {
+      institution_name: "Sample Bank",
+      account_display_name: "Everyday Checking",
+      account_mask_last4: "1111",
+      current_balance: { amount: "5120.00", currency_code: "USD" }
+    },
+    {
+      institution_name: "Sample Bank",
+      account_display_name: "Rainy Day Savings",
+      account_mask_last4: "2222",
+      current_balance: { amount: "3000.00", currency_code: "USD" }
+    },
+    {
+      institution_name: "Sample Card",
+      account_display_name: "Travel Card",
+      account_mask_last4: "1212",
+      current_balance: { amount: "9200.00", currency_code: "USD" }
+    }
+  ]
+};
+
+// ---------------------------------------------------------------------------
+// Rendering. Data lands via textContent, never innerHTML, so a value can
+// only ever read as text.
+// ---------------------------------------------------------------------------
+
+function formatMoney(value) {
+  if (!value || typeof value.amount !== "string") return "—";
+  const number = Number(value.amount);
+  if (!Number.isFinite(number)) return "—";
+  return new Intl.NumberFormat(undefined, {
+    style: "currency",
+    currency: value.currency_code || "USD"
+  }).format(number);
+}
+
+function element(tag, className, text) {
+  const node = document.createElement(tag);
+  if (className) node.className = className;
+  if (text !== undefined) node.textContent = text;
+  return node;
+}
+
+function renderOverview(result) {
+  const rollups = (result && result.summary_rollups) || {};
+  const container = document.getElementById("overview");
+  container.replaceChildren();
+  const stats = [
+    ["Net worth", rollups.net_worth_estimate],
+    ["Cash", rollups.cash],
+    ["Assets", rollups.total_assets],
+    ["Liabilities", rollups.total_liabilities]
+  ];
+  for (const [label, value] of stats) {
+    const stat = element("div", "stat");
+    stat.append(
+      element("div", "stat-label", label),
+      element("div", "stat-value", formatMoney(value))
+    );
+    container.append(stat);
+  }
+}
+
+function renderAccounts(result) {
+  const accounts = (result && result.linked_accounts) || [];
+  const container = document.getElementById("accounts");
+  container.replaceChildren();
+  for (const account of accounts) {
+    const row = element("div", "account-row");
+    const names = element("div", "account-names");
+    const mask = account.account_mask_last4;
+    names.append(
+      element("div", "account-name", account.account_display_name || "Account"),
+      element(
+        "div",
+        "account-institution",
+        (account.institution_name || "") + (mask ? " ····" + mask : "")
+      )
+    );
+    row.append(names, element("div", "account-balance", formatMoney(account.current_balance)));
+    container.append(row);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Live data. window.driggsby exists when the Driggsby SDK loaded — inside
+// Driggsby, or under driggsby dev. Standalone, the sample data stays and
+// the note above explains why.
+// ---------------------------------------------------------------------------
+
+renderOverview(SAMPLE_OVERVIEW);
+renderAccounts(SAMPLE_ACCOUNTS);
+
+let overviewIsLive = false;
+let accountsAreLive = false;
+
+function removeSampleNoteWhenAllLive() {
+  if (!overviewIsLive || !accountsAreLive) return;
+  const note = document.getElementById("sample-note");
+  if (note) note.remove();
+}
+
+if (window.driggsby) {
+  driggsby.watch("get_overview", {}, (result) => {
+    overviewIsLive = true;
+    removeSampleNoteWhenAllLive();
+    renderOverview(result);
+  });
+  driggsby.watch("list_accounts", {}, (result) => {
+    accountsAreLive = true;
+    removeSampleNoteWhenAllLive();
+    renderAccounts(result);
+  });
+}
+`;
+export const STYLES_CSS = `:root {
+  --background: #ffffff;
+  --text: #1f2430;
+  --text-muted: #6d7280;
+  --hairline: #e6e8ec;
+  --note-background: #fdf6e3;
+  --note-text: #7a5b1e;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  background: var(--background);
+  color: var(--text);
+  font-family: system-ui, -apple-system, "Segoe UI", sans-serif;
+  font-size: 15px;
+  line-height: 1.5;
+}
+
+main {
+  max-width: 720px;
+  margin: 0 auto;
+  padding: 48px 24px 64px;
+}
+
+h1 {
+  margin: 0;
+  font-size: 22px;
+  font-weight: 600;
+}
+
+h2 {
+  margin: 40px 0 4px;
+  font-size: 15px;
+  font-weight: 600;
+}
+
+.sample-note {
+  display: inline-block;
+  margin: 12px 0 0;
+  padding: 4px 10px;
+  border-radius: 6px;
+  background: var(--note-background);
+  color: var(--note-text);
+  font-size: 13px;
+}
+
+.stat-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));
+  gap: 20px;
+  margin-top: 32px;
+}
+
+.stat-label {
+  font-size: 13px;
+  color: var(--text-muted);
+}
+
+.stat-value {
+  font-size: 20px;
+  font-weight: 600;
+  font-variant-numeric: tabular-nums;
+}
+
+.account-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 16px;
+  padding: 12px 0;
+  border-top: 1px solid var(--hairline);
+}
+
+.account-row:first-child {
+  border-top: none;
+}
+
+.account-institution {
+  font-size: 13px;
+  color: var(--text-muted);
+}
+
+.account-balance {
+  font-variant-numeric: tabular-nums;
+}
+`;
+export function driggsbyJsonText(slug) {
+    return `{\n  "slug": ${JSON.stringify(slug)},\n  "serve": "."\n}\n`;
+}