moshcode 0.70.0 → 0.72.0

package/prd/0012-billing-baked-into-the-agent-cli.md

@@ -0,0 +1,129 @@
+---
+openprd: "0.2"
+id: "0012"
+title: "Bake billing into the agent CLI — timer, clients, teams, rates, invoices, rails"
+status: Draft
+authors:
+  - anthony@profullstack.com
+created: 2026-08-29
+updated: 2026-08-29
+repo: https://github.com/moshcoder/moshcode
+discussion:
+implementation: src/timer.mjs · src/clients.mjs · src/teams.mjs · src/rates.mjs · src/billing.mjs · src/payments.mjs · src/business-store.mjs
+tags: business, billing, payments, time-tracking, permissions
+supersedes:
+superseded-by:
+---
+
+## Problem
+
+Every agentic CLI helps you do the work. None of them help you get paid for it.
+
+That gap is not small. An agency running moshcode has the whole engagement in
+this terminal — the engines, the herd, the repos, the deploys — and then leaves
+it to bill: hours reconstructed from memory into a spreadsheet, a rate that
+lives in a signed PDF nobody opens, an invoice retyped into a processor's web
+form. The one system that actually knows how long four agents ran on Acme's
+repo last Tuesday is the one system with nothing to say about it.
+
+It is worse than clerical. Agent work prices differently from human work and the
+existing tools cannot express it: an hour of moshcode is an hour times however
+many engines were running in it, capped at whatever the client was promised.
+"$100/hour/agent, up to 4" is a real sentence in a real contract, and there is
+nowhere to write it down except prose.
+
+The same terminal has a second unanswered question. A devops shop puts moshcode
+on machines its own people and its clients sit at, and "Preshy can use the
+CoinPay tool, the client can read invoices and nothing else" has no expression
+anywhere — not in moshcode, not in the tools it wraps.
+
+## Goals
+
+- Somebody who bills nobody still wants the timer, and gets it: `/timer on`,
+  `/timer off`, and a ledger, with no client, no rate and no gateway.
+- The rate card is written in the words of the contract and read by the machine
+  — including the cap, which is the clause that made the client sign.
+- The hours behind an invoice are the hours that were tracked, not the hours
+  somebody remembered on the last day of the month.
+- Time is never billed twice, and money never settles to an address nobody
+  chose.
+- Which processor a business already uses is their decision, not moshcode's.
+- The split between an operator, an employee and a client is something an
+  operator can write down, and something the pit then respects.
+
+## Non-Goals
+
+- Moving money. moshcode composes an invoice; a gateway delivers it. There is no
+  wallet, no key and no signing in this layer.
+- Being an accounting system. No ledgers, no tax, no reconciliation, no
+  multi-currency FX at settlement time.
+- Being a security boundary. The team gate stops the wrong command; it does not
+  stop a person with a shell. That is an OS account or a container, and this
+  PRD says so out loud rather than implying otherwise.
+- Server-side state. Everything here is two JSON files under `~/.moshcode`.
+  A shared, multi-machine business record is a later question.
+
+## Users
+
+- **The solo operator.** Bills a handful of clients hourly, wants the invoice to
+  be the time that was actually tracked.
+- **The agency.** Several clients, several people, several rates, and a promise
+  about agent caps that has to survive contact with a busy month.
+- **The employee or contractor.** Sits at a machine somebody else set up, needs
+  the engines and the timer and nothing that touches money.
+- **The client.** Occasionally handed a pit; should see what they are being
+  billed and the time behind it, and touch nothing.
+
+## Requirements
+
+- R1 [P0] `/timer on|off` tracks time to a local ledger, with no dependency on
+  a client, a rate or a gateway.
+- R2 [P0] A timer records how many agents were running, and `--agents auto`
+  reads that from the herd rather than asking.
+- R3 [P0] `/client create` accepts contact details as they arrive — a comma
+  form for what is pasted, `--a.b` dotted flags for anything else — with no
+  fixed field list.
+- R4 [P0] `/rate set <who> <spec>` parses the contract sentence, including
+  period, unit, `upto:N` cap and `min:N` floor, in any order after the price.
+- R5 [P0] `/billing <client>` previews without writing; `--mark` claims the
+  time exactly once; `--send` composes the gateway command and only `--yes`
+  runs it.
+- R6 [P0] An invoice refuses to settle when there is no client payee and no
+  wallet rail.
+- R7 [P1] `/payments` connects a rail — CLI (CoinPay, Stripe), OAuth (PayPal,
+  Coinbase) or a bare wallet — and stores no secret, only a vault reference.
+- R8 [P1] `/team` records people, roles and grants; `MOSHCODE_MEMBER` makes the
+  pit act as one of them, and the gate refuses commands they have no grant for.
+- R9 [P1] A permission is written however it is said — `tools:coinpay`,
+  `tools/coinpay`, `allow(tools/coinpay)` — and means the same thing.
+- R10 [P2] `/business`, `/merchant` and `/customer` are the same command as
+  `/client`; `/rates`, `/teams` and `/invoice` likewise.
+
+## UX Notes
+
+The five words are `/timer`, `/client`, `/rate`, `/billing`, `/payments`, plus
+`/team` for who may run them. Each is useful alone, which is the test each one
+had to pass: the timer with no rate, the rate with no gateway, the client with
+no invoice.
+
+Aliases are not synonyms in general English — a merchant is not a customer — but
+they are the same party in every conversation this is for, and the word somebody
+reaches for depends on which product taught it to them. Three doors, one room.
+
+The gate refuses by naming the permission and the command that would grant it,
+because the person who hits it is not the person who can fix it, and "ask an
+owner for `/team grant acme preshy tools:coinpay`" is a message they can paste.
+
+## Open Questions
+
+- Should the business record sync to app.moshcode.sh the way settings do (PRD
+  0010)? An agency's client list on one laptop is the same problem 0010 solved
+  for aliases — but a client list is a different kind of data, and the answer
+  may be that it belongs on the account rather than in a sync.
+- Should `/team` grants travel with `/load`, so a machine handed to a contractor
+  is configured by logging into it? That is the version where this stops being a
+  personal record and starts being an operator tool.
+- Beyond CoinPay, `--send` prints numbers rather than composing a command line.
+  Stripe's CLI is the obvious next one to teach it.
+- Member rates are recorded but not yet used: cost-per-person alongside
+  price-per-client is what turns an invoice into a margin.

package/src/billing.mjs

@@ -0,0 +1,363 @@
+// Tracked time × the rate they agreed to = the number you send them.
+//
+// This is the join, and it is the only file that touches all four of the other
+// ones: the ledger from `/timer`, the rate from `/rate`, the address from
+// `/client`, and the rail from `/payments`. It does the arithmetic nobody
+// enjoys doing at the end of a month, and then it stops — moshcode composes an
+// invoice, CoinPay (or Stripe, or a wallet) delivers it.
+//
+// Two rules the shape here exists to enforce:
+//
+//   Nothing is billed twice. An entry carries `billed` and the invoice id that
+//   claimed it, and drafting is separate from claiming: `/billing acme` is a
+//   preview you can run all day, `--mark` is the one that writes.
+//
+//   Nothing settles to an address nobody decided on. A client with no payee
+//   and no default wallet gets a refusal, not a best guess, because the failure
+//   mode of guessing is money arriving somewhere it cannot be recovered from.
+import { spawnSync } from "node:child_process";
+
+import { loadBusiness, loadTimers, newId, updateBusiness, updateTimers } from "./business-store.mjs";
+import { clientLabel, parseFields, resolveClient } from "./clients.mjs";
+import { GATEWAYS, defaultGateway, gatewayState } from "./payments.mjs";
+import { chargeFor, describeRate, formatMoney, isDollarPegged, isFiat, rateFor } from "./rates.mjs";
+import { humanDuration, selectEntries, windowFrom } from "./timer.mjs";
+import { acid, ash, bone, err, info, ok, table, warn } from "./ui.mjs";
+
+/** A line is a task; entries against the same task collapse into one. */
+function lineKeyFor(entry) {
+  return entry.task || entry.note || "untracked";
+}
+
+/**
+ * Turn a window of tracked time into an invoice draft.
+ *
+ * Charged per entry and then summed, not summed and then charged: the agent
+ * count varies between entries, and an average would quietly bill a two-agent
+ * afternoon at the four-agent rate (or the other way round, which is worse for
+ * a different reason).
+ */
+export function buildInvoice({ business, timers, clientId, since = null, until = null, all = false }) {
+  const client = business.clients?.[clientId] || null;
+  const rate = rateFor(business, clientId);
+  const entries = selectEntries(timers.entries || [], { client: clientId, since, until, unbilled: !all });
+
+  const lines = new Map();
+  const warnings = [];
+  let total = 0;
+  let seconds = 0;
+  const currency = rate?.currency || "USD";
+
+  for (const entry of entries) {
+    seconds += entry.seconds || 0;
+    const charge = chargeFor(entry, rate);
+    const key = lineKeyFor(entry);
+    const line = lines.get(key) || { what: key, seconds: 0, agents: 0, amount: 0, entries: [], flat: false };
+    line.seconds += entry.seconds || 0;
+    line.agents = Math.max(line.agents, entry.agents || 1);
+    line.entries.push(entry.id);
+    if (charge?.amount != null) { line.amount += charge.amount; total += charge.amount; }
+    if (charge?.flat) line.flat = true;
+    lines.set(key, line);
+    if (rate?.cap && (entry.agents || 1) > rate.cap) {
+      warnings.push(`${entry.id}: ${entry.agents} agents ran, ${rate.cap} billed (the cap)`);
+    }
+  }
+
+  // A flat project fee is earned once, however many entries sit under it.
+  if (rate?.per === "project" && entries.length) {
+    lines.set("project fee", { what: "project fee", seconds: 0, agents: 0, amount: rate.amount, entries: [], flat: true });
+    total += rate.amount;
+  }
+
+  return {
+    clientId,
+    client,
+    rate,
+    currency,
+    lines: [...lines.values()],
+    entries,
+    entryIds: entries.map((e) => e.id),
+    seconds,
+    total,
+    warnings,
+  };
+}
+
+/**
+ * Where this client's money should land: their payee, else the wallet rail.
+ *
+ * Per-client because the answer genuinely differs — one client pays a business
+ * account, another pays a project wallet — and a single global address makes
+ * that impossible to express without a second tool.
+ */
+export function settlementFor(business, clientId) {
+  const client = business.clients?.[clientId];
+  if (client?.payee?.address) return { ...client.payee, source: "client" };
+  const wallet = business.payments?.gateways?.wallet;
+  if (wallet?.address) return { chain: wallet.chain, address: wallet.address, source: "wallet" };
+  return null;
+}
+
+/**
+ * The CoinPay command line that turns a draft into a real invoice:
+ * `{ ok, args }`, or `{ ok: false, reason }`.
+ *
+ * Built rather than run: the amount, the currency and the address are decisions
+ * with consequences, and the last thing between them and a stranger's wallet
+ * should be a line a person can read. `--yes` is what runs it, which is the
+ * same convention CoinPay's own CLI uses for its irreversible verbs.
+ *
+ * The currency split is CoinPay's, not ours: `--currency` is a three-letter
+ * fiat code and the settlement ticker travels in `--crypto-currency`. That
+ * expresses a dollar-priced invoice settled in crypto exactly, and a
+ * USDC-priced one honestly, because USDC is a dollar. It cannot express a rate
+ * priced in SOL or BTC — the fiat amount would be a number nobody computed —
+ * so that case is refused with its reason rather than converted by guesswork.
+ */
+export function coinpayArgs(invoice, { payee = null, dueDate = null } = {}) {
+  const currency = invoice.currency;
+  if (!isFiat(currency) && !isDollarPegged(currency)) {
+    return {
+      ok: false,
+      reason: `this rate is priced in ${currency}, and a CoinPay invoice carries a fiat amount — `
+        + `price it in a currency (--prefer ${currency} keeps the settlement) or send it yourself`,
+    };
+  }
+  const priced = isFiat(currency) ? currency : "USD";
+  const crypto = isFiat(currency)
+    ? (invoice.rate?.prefer || []).find((c) => !isFiat(c)) || null
+    : currency;
+  const args = [
+    "invoice", "create",
+    "--amount", invoice.total.toFixed(2),
+    "--currency", priced,
+  ];
+  if (crypto) args.push("--crypto-currency", crypto);
+  if (dueDate) args.push("--due-date", dueDate);
+  if (payee?.address) args.push("--merchant-wallet-address", payee.address);
+  args.push("--notes", invoiceNote(invoice));
+  return { ok: true, args };
+}
+
+function invoiceNote(invoice) {
+  const who = invoice.client?.name || invoice.clientId || "work";
+  const lines = invoice.lines.filter((l) => l.what !== "project fee").map((l) => l.what);
+  const summary = lines.length ? `: ${lines.slice(0, 3).join(", ")}${lines.length > 3 ? `, +${lines.length - 3} more` : ""}` : "";
+  return `${who} — ${humanDuration(invoice.seconds)}${summary}`;
+}
+
+const USAGE = [
+  "usage: /billing <client> [--today|--week|--month|--since <date>] [--all] [--json]",
+  "       /billing <client> --mark            claim the time and record an invoice",
+  "       /billing <client> --send [--yes]    hand it to the connected gateway",
+  "       /billing list · /billing show <id> · /billing void <id>",
+];
+
+export function billingCommand(argv = [], { write = console.log, run = spawnSync } = {}) {
+  const verb = String(argv[0] ?? "").toLowerCase();
+  if (["list", "ls", ""].includes(verb) && argv.length <= 1) return listInvoices(argv.includes("--json"), write);
+  if (["show", "get"].includes(verb)) return showInvoice(argv[1], argv.includes("--json"), write);
+  if (["void", "cancel"].includes(verb)) return voidInvoice(argv[1], write);
+  return draftInvoice(argv, write, run);
+}
+
+function draftInvoice(argv, write, run) {
+  const { fields, rest } = parseFields(argv);
+  const business = loadBusiness();
+  const timers = loadTimers();
+
+  const found = resolveClient(business, rest[0]);
+  if (!found.ok) {
+    if (found.reason === "ambiguous") { write(err(`${JSON.stringify(rest[0])} matches ${found.matches.join(", ")} — say which`)); return 1; }
+    write(err(`no client ${JSON.stringify(rest[0] ?? "")} — ${acid("/client list")}`));
+    USAGE.forEach(write);
+    return 1;
+  }
+
+  const invoice = buildInvoice({
+    business,
+    timers,
+    clientId: found.id,
+    since: windowFrom(fields),
+    all: Boolean(fields.all),
+  });
+
+  if (fields.json) { write(JSON.stringify(invoice, null, 2)); return 0; }
+
+  if (!invoice.entries.length) {
+    write(info(`nothing unbilled for ${bone(found.id)}${fields.all ? "" : " — --all to include time already billed"}`));
+    return 0;
+  }
+  if (!invoice.rate) {
+    write(err(`no rate for ${bone(found.id)} — ${acid(`/rate set ${found.id} $100/hour/agent/upto:4`)}`));
+    return 1;
+  }
+
+  write(`  ${clientLabel(found.id, invoice.client)} ${ash("·")} ${ash(describeRate(invoice.rate))}`);
+  write(table(
+    invoice.lines.map((l) => [
+      l.what,
+      l.seconds ? humanDuration(l.seconds) : ash("—"),
+      l.agents > 1 ? `${l.agents}×` : "",
+      acid(formatMoney(l.amount, invoice.currency)),
+    ]),
+    { columns: ["what", "time", "agents", "amount"], indent: 2 },
+  ));
+  write(`  ${ash("total")} ${bone(humanDuration(invoice.seconds))} ${ash("→")} ${acid(formatMoney(invoice.total, invoice.currency))}`);
+  for (const note of invoice.warnings) write(`  ${ash(note)}`);
+
+  const settlement = settlementFor(business, found.id);
+  if (!settlement) {
+    write(warn("no payee for this client and no wallet rail — nothing to settle to"));
+    write(`  ${acid(`/client payee ${found.id} solana:<address>`)} ${ash("or")} ${acid("/payments connect wallet --chain solana --address <addr>")}`);
+  } else {
+    write(`  ${ash("settles to")} ${acid(`${settlement.chain}:${settlement.address}`)} ${ash(`(${settlement.source})`)}`);
+  }
+
+  if (!fields.mark && !fields.send) {
+    write(`  ${ash("this is a preview —")} ${acid(`/billing ${found.id} --mark`)} ${ash("claims the time,")} ${acid("--send")} ${ash("hands it to the gateway")}`);
+    return 0;
+  }
+
+  if (!settlement) return 1;
+
+  const record = commitInvoice(invoice, settlement);
+  const claimed = record.entryIds.length;
+  write(ok(`invoice ${bone(record.id)} — ${acid(formatMoney(record.total, record.currency))} ${ash(`(${claimed} ${claimed === 1 ? "entry" : "entries"} claimed)`)}`));
+
+  if (!fields.send) return 0;
+  return handOff(record, invoice, business, fields, write, run);
+}
+
+/** Write the invoice and mark its entries, in that order. */
+function commitInvoice(invoice, settlement) {
+  const id = newId("inv-");
+  const record = {
+    id,
+    client: invoice.clientId,
+    createdAt: new Date().toISOString(),
+    currency: invoice.currency,
+    total: invoice.total,
+    seconds: invoice.seconds,
+    lines: invoice.lines,
+    entryIds: invoice.entryIds,
+    rate: invoice.rate,
+    settlement,
+    status: "draft",
+    gateway: null,
+    gatewayRef: null,
+  };
+  updateBusiness((data) => { data.invoices[id] = record; });
+  updateTimers((data) => {
+    for (const entry of data.entries) {
+      if (record.entryIds.includes(entry.id)) { entry.billed = true; entry.invoice = id; }
+    }
+  });
+  return record;
+}
+
+function handOff(record, invoice, business, fields, write, run) {
+  const key = fields.gateway && fields.gateway !== true ? String(fields.gateway).toLowerCase() : defaultGateway(business);
+  if (!key || !GATEWAYS[key]) {
+    write(warn("no payment rail chosen — the invoice is recorded, but nothing was sent"));
+    write(`  ${acid("/payments connect coinpay")}`);
+    return 1;
+  }
+  if (key !== "coinpay") {
+    // Every other rail is a passthrough moshcode has not been taught to speak.
+    // Saying so is better than composing a command line from guesswork.
+    write(info(`${bone(key)} is connected, but moshcode only composes CoinPay invoices`));
+    write(`  ${ash("the numbers are above, and")} ${acid(`/billing show ${record.id}`)} ${ash("has them again whenever you need them")}`);
+    return 0;
+  }
+
+  const state = gatewayState("coinpay", business);
+  if (!state.installed) { write(err(`coinpay is not on PATH — ${acid("/install coinpay")}`)); return 1; }
+
+  const composed = coinpayArgs({ ...invoice, total: record.total }, { payee: record.settlement, dueDate: fields.due && fields.due !== true ? String(fields.due) : null });
+  if (!composed.ok) {
+    write(warn(composed.reason));
+    write(`  ${ash(`invoice ${record.id} is recorded either way —`)} ${acid(`/billing show ${record.id}`)}`);
+    return 1;
+  }
+  const { args } = composed;
+  const printable = `coinpay ${args.map((a) => (/\s/.test(a) ? JSON.stringify(a) : a)).join(" ")}`;
+  write(`  ${ash(printable)}`);
+  if (!fields.yes) {
+    write(`  ${ash("read it, then")} ${acid(`/billing ${record.client} --send --yes`)} ${ash("to run it")}`);
+    return 0;
+  }
+
+  const result = run("coinpay", args, { stdio: "inherit" });
+  if (result?.error) { write(err(String(result.error.message || result.error))); return 1; }
+  if (result?.status) { write(err(`coinpay exited ${result.status} — invoice ${record.id} is still a local draft`)); return result.status; }
+  updateBusiness((data) => {
+    data.invoices[record.id].gateway = "coinpay";
+    data.invoices[record.id].status = "handed-off";
+  });
+  write(ok(`handed to CoinPay — ${acid("coinpay invoice send <id>")} ${ash("emails it to the client")}`));
+  return 0;
+}
+
+function listInvoices(json, write) {
+  const { invoices } = loadBusiness();
+  const ids = Object.keys(invoices).sort();
+  if (json) { write(JSON.stringify(invoices, null, 2)); return 0; }
+  if (!ids.length) { write(info("no invoices yet.")); write(`  ${acid("/billing <client> --mark")}`); return 0; }
+  write(table(
+    ids.map((id) => {
+      const inv = invoices[id];
+      return [
+        bone(id),
+        inv.client || "",
+        ash(String(inv.createdAt || "").slice(0, 10)),
+        humanDuration(inv.seconds),
+        acid(formatMoney(inv.total, inv.currency)),
+        ash(inv.status || "draft"),
+      ];
+    }),
+    { columns: ["id", "client", "date", "time", "amount", "status"], indent: 2 },
+  ));
+  return 0;
+}
+
+function showInvoice(id, json, write) {
+  const { invoices } = loadBusiness();
+  const invoice = invoices[String(id ?? "")];
+  if (!invoice) { write(err(`no invoice ${JSON.stringify(id ?? "")} — ${acid("/billing list")}`)); return 1; }
+  if (json) { write(JSON.stringify(invoice, null, 2)); return 0; }
+  write(`  ${bone(invoice.id)} ${ash(invoice.client || "")} ${ash(String(invoice.createdAt).slice(0, 10))}`);
+  write(table(
+    invoice.lines.map((l) => [l.what, l.seconds ? humanDuration(l.seconds) : ash("—"), acid(formatMoney(l.amount, invoice.currency))]),
+    { columns: ["what", "time", "amount"], indent: 2 },
+  ));
+  write(`  ${ash("total")} ${acid(formatMoney(invoice.total, invoice.currency))} ${ash(`· ${invoice.status}`)}`);
+  if (invoice.settlement) write(`  ${ash("settles to")} ${acid(`${invoice.settlement.chain}:${invoice.settlement.address}`)}`);
+  return 0;
+}
+
+/**
+ * Undo the claim, not the invoice.
+ *
+ * The entries go back to unbilled so they can be re-drafted; the invoice record
+ * stays and is marked void. Deleting it would erase the fact that a number was
+ * once quoted, which is exactly the fact somebody comes looking for.
+ */
+function voidInvoice(id, write) {
+  const key = String(id ?? "");
+  const { invoices } = loadBusiness();
+  const invoice = invoices[key];
+  if (!invoice) { write(err(`no invoice ${JSON.stringify(key)}`)); return 1; }
+  if (invoice.status === "void") { write(info(`${key} is already void`)); return 0; }
+  updateBusiness((data) => { data.invoices[key].status = "void"; data.invoices[key].voidedAt = new Date().toISOString(); });
+  updateTimers((data) => {
+    for (const entry of data.entries) {
+      if (entry.invoice === key) { entry.billed = false; entry.invoice = null; }
+    }
+  });
+  write(ok(`${bone(key)} void — ${invoice.entryIds.length} entries are billable again`));
+  return 0;
+}
+
+export { USAGE as BILLING_USAGE };

package/src/business-delegate.mjs

@@ -0,0 +1,105 @@
+// Where /timer and /billing actually run.
+//
+// Both started life inside moshcode (PRD 0012) and now also exist as their own
+// cross-platform CLIs — @profullstack/timer and @profullstack/billing — because
+// neither is a moshcode idea: tracking time and sending an invoice are things
+// you want under any agentic CLI, and on Windows, where moshcode does not go.
+//
+// So the rule here is: when asked, moshcode conducts them the way /gh conducts
+// gh. The two are NOT kept in sync, and that is the point of preferring the
+// external one where it is wanted: a second copy of a billing model is a copy
+// that drifts, and the published package is the one that gets the fixes.
+//
+// ---------------------------------------------------------------------------
+// Why this is opt-in rather than "delegate whenever the CLI is on PATH", which
+// is what it did when it first landed:
+//
+// Only half the business layer has somewhere to go. /timer and /billing have
+// standalone equivalents; /client, /rate, /payments and /team do not — the
+// rails and the permission model are moshcode's, and /client's freeform dotted
+// fields have no shape in the package's typed client model, so moving it would
+// lose data rather than relocate it.
+//
+// Delegating that half by default splits one person's records across two
+// stores. /client and /rate keep writing ~/.moshcode/business.json while
+// /billing reads ~/.profullstack/billing/ledger.json, so:
+//
+//   /client create "Acme Inc"      → written to moshcode
+//   /rate set acme-inc $100/hour   → written to moshcode
+//   /billing acme-inc              → "no client acme-inc"
+//
+// That is not a missing feature, it is somebody's invoice failing to exist. And
+// it only happens on a machine that installed the CLIs, so CI — which has not —
+// stays green while every developer box that took the install goes red.
+//
+// Hence: opt in, knowing that `billing import` is how the existing ledger comes
+// across. When the whole layer has an outside home, this becomes the default.
+import { isInstalled } from "./engines.mjs";
+import { TOOLS, openTool } from "./tools.mjs";
+
+/** Commands that have an external CLI, and the TOOLS key that owns it. */
+export const DELEGATED = { timer: "timer", billing: "billing", invoice: "billing" };
+
+/** Whether this machine has asked for the standalone CLIs to be used. */
+export function externalEnabled() {
+  return /^(1|true|yes)$/i.test(String(process.env.MOSHCODE_EXTERNAL_BILLING || ""));
+}
+
+/** The external CLI for a command, if it is enabled and this machine has it. */
+export function externalFor(cmd) {
+  if (!externalEnabled()) return null;
+  const key = DELEGATED[String(cmd || "").toLowerCase()];
+  if (!key) return null;
+  const tool = TOOLS[key];
+  if (!tool || !isInstalled(tool.bin, tool.binDirs)) return null;
+  return { key, tool };
+}
+
+/**
+ * Hand a command to its CLI, or report that there is nothing to hand it to.
+ *
+ * Returns `{ delegated: false }` when the CLI is absent so the caller can fall
+ * through to the built-in rather than failing — a missing optional tool is not
+ * an error, it is just the older path.
+ */
+export async function delegate(cmd, argv = [], opts = {}) {
+  const found = externalFor(cmd);
+  if (!found) return { delegated: false, code: 0 };
+  // openPassthrough resolves { ok, code, signal }, not a number. Assigning the
+  // object straight to process.exitCode throws ERR_INVALID_ARG_TYPE *after* the
+  // child has already printed its output, which reads as the tool crashing when
+  // in fact it succeeded.
+  const result = await openTool(found.tool, argv, opts);
+  return { delegated: true, code: exitCodeOf(result) };
+}
+
+/**
+ * One number out of a passthrough result.
+ *
+ * A child killed by a signal reports `code: null`, and passing that on as 0
+ * would call an interrupted invoice run a success.
+ */
+export function exitCodeOf(result) {
+  if (typeof result === "number") return result;
+  if (!result || typeof result !== "object") return 0;
+  if (Number.isInteger(result.code)) return result.code;
+  if (result.signal) return 1;
+  return result.ok === false ? 1 : 0;
+}
+
+/**
+ * The one-line nudge shown after the built-in runs.
+ *
+ * Written to stderr, and only when the CLI is actually installed and simply not
+ * switched on, so it never lands in the middle of `--json` output and never
+ * advertises a tool that is not there. Someone who has installed the package is
+ * the only person for whom the variable is worth mentioning.
+ */
+export function installHint(cmd) {
+  const key = DELEGATED[String(cmd || "").toLowerCase()];
+  if (!key || externalEnabled()) return null;
+  const tool = TOOLS[key];
+  if (!tool || !isInstalled(tool.bin, tool.binDirs)) return null;
+  return `tip: @profullstack/${key} is installed — set MOSHCODE_EXTERNAL_BILLING=1 to use it`
+    + " (move your records first with: billing import)";
+}