@atyaio/ledgr 0.0.0-stage → 0.1.1

package/dist/index.js

@@ -0,0 +1,456 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+import pc8 from "picocolors";
+
+// src/commands/init.ts
+import * as fs3 from "fs";
+import * as path3 from "path";
+import * as p from "@clack/prompts";
+import pc2 from "picocolors";
+import { DEFAULT_EXPENSE_CATEGORIES, DEFAULT_REVENUE_CATEGORIES, slugifyKey } from "@atyaio/ledgr-shared";
+
+// src/api.ts
+import * as fs from "fs";
+import * as path from "path";
+import { createRequire } from "module";
+var require2 = createRequire(import.meta.url);
+function loadApi(projectDir) {
+  const local = projectDir && localApiEntry(projectDir);
+  if (local) return require2(local);
+  return require2("@atyaio/ledgr-api");
+}
+function localApiEntry(projectDir) {
+  const entry = path.join(projectDir, "apps", "api", "dist", "main.js");
+  return fs.existsSync(entry) ? entry : void 0;
+}
+function resolveWebDist(projectDir) {
+  if (projectDir) {
+    const local = path.join(projectDir, "apps", "web", "dist");
+    if (fs.existsSync(path.join(local, "index.html"))) return local;
+  }
+  try {
+    const pkg2 = require2.resolve("@atyaio/ledgr-web/package.json");
+    const dist = path.join(path.dirname(pkg2), "dist");
+    if (fs.existsSync(path.join(dist, "index.html"))) return dist;
+  } catch {
+  }
+  try {
+    return loadApi().resolveWebDist();
+  } catch {
+    return void 0;
+  }
+}
+
+// src/source.ts
+import * as fs2 from "fs";
+import * as path2 from "path";
+import { spawnSync } from "child_process";
+import pc from "picocolors";
+var UPSTREAM_URL = "https://github.com/atyaio/ledgr.git";
+var UPSTREAM_REMOTE = "ledgr";
+function hasLocalSource(projectDir) {
+  return fs2.existsSync(path2.join(projectDir, "apps", "api", "package.json")) && fs2.existsSync(path2.join(projectDir, "packages", "cli", "package.json"));
+}
+function localSourceBuilt(projectDir) {
+  return fs2.existsSync(path2.join(projectDir, "apps", "api", "dist", "main.js")) && fs2.existsSync(path2.join(projectDir, "apps", "web", "dist", "index.html"));
+}
+function run(cmd, args, cwd, opts = {}) {
+  const r = spawnSync(cmd, args, { cwd, stdio: opts.quiet ? "pipe" : "inherit", env: process.env });
+  if (r.status !== 0) {
+    const err = opts.quiet ? r.stderr?.toString() ?? "" : "";
+    throw new Error(`${cmd} ${args.join(" ")} failed${err ? `: ${err.trim()}` : ""}`);
+  }
+}
+function has(cmd) {
+  const r = spawnSync(cmd, ["--version"], { stdio: "pipe" });
+  return r.status === 0;
+}
+function cloneSource(dir, from = UPSTREAM_URL) {
+  if (!has("git")) throw new Error("git is required for --standalone (not found on PATH).");
+  if (fs2.existsSync(dir) && fs2.readdirSync(dir).length > 0) throw new Error(`${dir} is not empty. Use a new folder for a standalone project.`);
+  fs2.mkdirSync(path2.dirname(dir), { recursive: true });
+  run("git", ["clone", "--origin", UPSTREAM_REMOTE, from, dir], process.cwd());
+  if (from !== UPSTREAM_URL) run("git", ["remote", "set-url", UPSTREAM_REMOTE, UPSTREAM_URL], dir, { quiet: true });
+  fs2.writeFileSync(path2.join(dir, "ledgr.upstream.json"), JSON.stringify({ repository: UPSTREAM_URL, remote: UPSTREAM_REMOTE, clonedFrom: from, clonedAt: (/* @__PURE__ */ new Date()).toISOString() }, null, 2) + "\n");
+  run("git", ["add", "ledgr.upstream.json"], dir, { quiet: true });
+  run("git", ["-c", "user.name=ledgr", "-c", "user.email=ledgr@localhost", "commit", "-q", "-m", "chore: standalone ledgr project"], dir, { quiet: true });
+}
+function installAndBuild(dir) {
+  if (!has("pnpm")) {
+    throw new Error(`pnpm is required to build ledgr. Install it with ${pc.cyan("corepack enable")} (ships with Node) or ${pc.cyan("npm i -g pnpm")}, then run ${pc.cyan("ledgr upgrade")} in the project folder.`);
+  }
+  run("pnpm", ["install"], dir);
+  run("pnpm", ["build"], dir);
+}
+function upgradeSource(dir) {
+  if (!has("git")) throw new Error("git is required (not found on PATH).");
+  const rev = () => spawnSync("git", ["rev-parse", "--short", "HEAD"], { cwd: dir, stdio: "pipe" }).stdout.toString().trim();
+  const before = rev();
+  const dirty = spawnSync("git", ["status", "--porcelain", "--untracked-files=no"], { cwd: dir, stdio: "pipe" }).stdout.toString().trim();
+  if (dirty) throw new Error("You have uncommitted changes. Commit or stash them first so the upgrade can be merged cleanly.");
+  run("git", ["fetch", UPSTREAM_REMOTE, "main"], dir);
+  const merge = spawnSync("git", ["merge", "--no-edit", "--quiet", `${UPSTREAM_REMOTE}/main`], { cwd: dir, stdio: "inherit" });
+  if (merge.status !== 0) {
+    throw new Error(`Merge has conflicts. Resolve them, run ${pc.cyan("git commit")}, then ${pc.cyan("pnpm install && pnpm build")}.`);
+  }
+  const after = rev();
+  return { before, after, changed: before !== after };
+}
+
+// src/commands/init.ts
+var bail = (v) => {
+  if (p.isCancel(v)) {
+    p.cancel("Cancelled.");
+    process.exit(0);
+  }
+  throw new Error("unexpected");
+};
+var ask = async (v) => {
+  const r = await v;
+  if (p.isCancel(r)) bail(r);
+  return r;
+};
+async function initCommand(opts) {
+  const projectDir = path3.resolve(opts.dir);
+  p.intro(pc2.bgYellow(pc2.black(" ledgr ")) + pc2.dim(opts.standalone ? " init --standalone" : " init"));
+  if (opts.standalone) {
+    if (hasLocalSource(projectDir)) {
+      p.log.info("This folder already carries the ledgr source.");
+    } else {
+      p.log.step(`Cloning the ledgr source into ${pc2.cyan(path3.relative(process.cwd(), projectDir) || ".")} (upstream remote: ${pc2.cyan("ledgr")})`);
+      cloneSource(projectDir, opts.from);
+    }
+    if (opts.build !== false && !localSourceBuilt(projectDir)) {
+      p.log.step("Installing dependencies and building (this takes a minute the first time)\u2026");
+      installAndBuild(projectDir);
+    }
+    p.log.success("Source ready. Customise anything under apps/ and packages/; run `ledgr upgrade` to merge upstream changes later.");
+  }
+  const api = loadApi(projectDir);
+  const paths = api.resolvePaths(path3.join(projectDir, ".ledgr"));
+  if (!fs3.existsSync(projectDir)) {
+    fs3.mkdirSync(projectDir, { recursive: true });
+    p.log.info(`Created folder ${pc2.cyan(path3.relative(process.cwd(), projectDir) || ".")}`);
+  } else if (projectDir !== process.cwd()) {
+    p.log.info(`Setting up ${pc2.cyan(path3.relative(process.cwd(), projectDir))}`);
+  }
+  if (fs3.existsSync(paths.configPath)) {
+    p.log.warn(`A ledgr project already exists at ${pc2.cyan(paths.dir)}`);
+    const again = opts.yes ? false : await ask(p.confirm({ message: "Reconfigure it? (data is kept)", initialValue: false }));
+    if (!again) {
+      p.outro(`Run ${pc2.cyan("ledgr start")} to open it.`);
+      return;
+    }
+  }
+  const folderName = path3.basename(projectDir);
+  const name = opts.name ?? (opts.yes ? folderName : await ask(p.text({ message: "Project / business name", placeholder: folderName, defaultValue: folderName })));
+  const nameAr = opts.yes ? "" : await ask(p.text({ message: `Arabic name ${pc2.dim("(optional, shown when the dashboard is in Arabic)")}`, defaultValue: "", placeholder: "\u0627\u0633\u0645 \u0627\u0644\u0645\u0634\u0631\u0648\u0639" }));
+  const currency = (opts.currency ?? (opts.yes ? "USD" : await ask(p.text({ message: "Currency (ISO 4217)", placeholder: "EGP", defaultValue: "USD", validate: (v) => v && !/^[A-Za-z]{3}$/.test(v) ? "Three letters, e.g. EGP" : void 0 })))).toUpperCase();
+  const locale = opts.yes ? "en-US" : await ask(p.text({ message: "Locale for number & date formatting", placeholder: "en-EG", defaultValue: "en-US" }));
+  const weekStartsOn = opts.yes ? 1 : await ask(p.select({ message: "Week starts on", initialValue: 1, options: [{ value: 6, label: "Saturday" }, { value: 0, label: "Sunday" }, { value: 1, label: "Monday" }] }));
+  let auth = { mode: "none" };
+  const wantAuth = opts.auth === false ? false : opts.yes ? false : await ask(p.confirm({ message: "Protect the dashboard with Supabase Auth? (admins only)", initialValue: true }));
+  if (wantAuth) {
+    const supabaseUrl = await ask(p.text({ message: "Supabase project URL", placeholder: "https://xxxx.supabase.co", validate: (v) => /^https?:\/\/.+/.test(v ?? "") ? void 0 : "Enter the project URL" }));
+    const supabaseAnonKey = await ask(p.password({ message: "Supabase anon (public) key", validate: (v) => v && v.length > 10 ? void 0 : "Paste the anon key" }));
+    auth = { mode: "supabase", supabaseUrl: supabaseUrl.replace(/\/$/, ""), supabaseAnonKey };
+    p.note(
+      `Only users with ${pc2.cyan('app_metadata.role = "admin"')} can sign in.
+Grant it from the Supabase SQL Editor (the dashboard has no app-metadata editor):
+${pc2.dim(`update auth.users set raw_app_meta_data = coalesce(raw_app_meta_data,'{}'::jsonb) || '{"role":"admin"}'::jsonb where email = 'you@example.com';`)}
+After running it, a page reload is enough; no sign-out needed.`,
+      "Who gets access"
+    );
+  } else {
+    p.log.warn("No auth: anyone who can reach the port can use the dashboard. Keep it on localhost.");
+  }
+  const stakeholders = [];
+  if (!opts.yes) {
+    const add = await ask(p.confirm({ message: "Add stakeholders (partners with an ownership %) now?", initialValue: true }));
+    let remaining = 100;
+    while (add) {
+      const sname = await ask(p.text({ message: `Stakeholder ${stakeholders.length + 1} name ${pc2.dim("(empty to finish)")}` }));
+      if (!sname?.trim()) break;
+      const share = await ask(p.text({ message: `${sname}'s ownership %`, defaultValue: String(Math.max(0, remaining)), placeholder: String(Math.max(0, remaining)), validate: (v) => v && (Number.isNaN(Number(v)) || Number(v) < 0 || Number(v) > 100) ? "0\u2013100" : void 0 }));
+      const pct = Number(share || remaining);
+      stakeholders.push({ name: sname.trim(), sharePercent: pct });
+      remaining = Math.round((remaining - pct) * 100) / 100;
+      if (remaining <= 0) {
+        const more = await ask(p.confirm({ message: "Shares reach 100%. Add another anyway?", initialValue: false }));
+        if (!more) break;
+      }
+    }
+  }
+  let expenseCategories = [...DEFAULT_EXPENSE_CATEGORIES];
+  let revenueCategories = [...DEFAULT_REVENUE_CATEGORIES];
+  if (!opts.yes) {
+    expenseCategories = await ask(p.multiselect({ message: "Expense categories to start with", options: DEFAULT_EXPENSE_CATEGORIES.map((c) => ({ value: c, label: c })), initialValues: [...DEFAULT_EXPENSE_CATEGORIES], required: false }));
+    const extra = await ask(p.text({ message: `Extra expense categories ${pc2.dim("(comma separated, optional)")}`, defaultValue: "" }));
+    expenseCategories.push(...(extra ?? "").split(",").map((s2) => s2.trim()).filter(Boolean));
+    revenueCategories = await ask(p.multiselect({ message: "Revenue categories to start with", options: DEFAULT_REVENUE_CATEGORIES.map((c) => ({ value: c, label: c })), initialValues: [...DEFAULT_REVENUE_CATEGORIES], required: false }));
+  }
+  const customFields = [];
+  if (!opts.yes) {
+    const want = await ask(p.confirm({ message: 'Add custom columns (e.g. "Client" on revenue, "Invoice no." on expenses)?', initialValue: true }));
+    while (want) {
+      const entity = await ask(p.select({ message: "Add a column to\u2026", options: [{ value: "revenue", label: "Revenue (profit table)" }, { value: "expense", label: "Expenses" }, { value: "stakeholder", label: "Stakeholders" }, { value: "done", label: pc2.dim("Done adding columns") }] }));
+      if (entity === "done") break;
+      const label = await ask(p.text({ message: "Column label", placeholder: entity === "revenue" ? "Client" : entity === "expense" ? "Invoice no." : "IBAN", validate: (v) => v?.trim() ? void 0 : "Required" }));
+      const type = await ask(p.select({ message: "Column type", options: [{ value: "text", label: "Text" }, { value: "number", label: "Number" }, { value: "money", label: `Money (${currency})` }, { value: "date", label: "Date" }, { value: "boolean", label: "Yes / no" }, { value: "select", label: "Select from options" }] }));
+      let options;
+      if (type === "select") {
+        const raw = await ask(p.text({ message: "Options (comma separated)", placeholder: "Direct, Upwork, Referral", validate: (v) => v?.trim() ? void 0 : "At least one option" }));
+        options = raw.split(",").map((s2) => s2.trim()).filter(Boolean);
+      }
+      const required = await ask(p.confirm({ message: "Required?", initialValue: false }));
+      let key = slugifyKey(label);
+      if (customFields.some((f) => f.entity === entity && f.key === key)) key = `${key}_${customFields.length}`;
+      customFields.push({ entity, label: label.trim(), key, type, options, required });
+      p.log.success(`${entity} \xB7 ${label} (${type})`);
+    }
+  }
+  const port = opts.yes ? 4848 : Number(await ask(p.text({ message: "Port", defaultValue: "4848", placeholder: "4848", validate: (v) => v && Number.isNaN(Number(v)) ? "Number" : void 0 })));
+  const config = {
+    ...api.defaultConfig(),
+    name: name.trim(),
+    ...nameAr?.trim() ? { nameAr: nameAr.trim() } : {},
+    slug: name.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "project",
+    currency,
+    locale: locale || "en-US",
+    weekStartsOn,
+    fiscalYearStartMonth: 1,
+    timezone: Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC",
+    port: port || 4848,
+    auth
+  };
+  const s = p.spinner();
+  s.start("Writing .ledgr/config.json and creating the database");
+  api.writeConfig(paths, config);
+  const ctx = api.loadContext(paths.dir);
+  const result = await api.applyInitialSetup(ctx, { stakeholders, expenseCategories, revenueCategories, customFields });
+  s.stop(`Created ${pc2.cyan(path3.relative(process.cwd(), paths.dir) || ".ledgr")} \xB7 ${result.stakeholders} stakeholders \xB7 ${result.categories} categories \xB7 ${result.customFields} custom columns`);
+  const gi = path3.join(projectDir, ".gitignore");
+  const line = ".ledgr/*.db*";
+  const existing = fs3.existsSync(gi) ? fs3.readFileSync(gi, "utf8") : "";
+  if (!existing.split("\n").some((l) => l.trim() === line)) {
+    const addIgnore = opts.yes ? true : await ask(p.confirm({ message: `Add ${pc2.cyan(line)} to .gitignore? (keeps the database out of git; config.json stays)`, initialValue: true }));
+    if (addIgnore) fs3.writeFileSync(gi, `${existing.replace(/\n*$/, existing ? "\n" : "")}
+# ledgr database (config.json is safe to commit if it has no secrets)
+${line}
+`);
+  }
+  if (auth.mode === "supabase") p.log.info(`${pc2.yellow("Note:")} config.json contains the Supabase anon key. It is a public key, but add ${pc2.cyan(".ledgr/")} to .gitignore if you prefer to keep it out of the repo.`);
+  if (opts.standalone) {
+    p.note(
+      [
+        `${pc2.cyan("ledgr start --open")}      run the dashboard from this folder's own code`,
+        `${pc2.cyan("ledgr upgrade")}           merge the latest ledgr into your copy`,
+        `${pc2.cyan("docker compose up -d")}    host it (data stays in ./.ledgr)`,
+        `${pc2.cyan("git remote add origin \u2026")} push the folder as your own repository`
+      ].join("\n"),
+      "Standalone project"
+    );
+  }
+  p.outro(`Done. Run ${pc2.cyan("ledgr start --open")} in ${pc2.cyan(path3.relative(process.cwd(), projectDir) || "this folder")}${auth.mode === "none" ? "" : " and sign in as an admin"}.`);
+}
+
+// src/commands/start.ts
+import * as path4 from "path";
+import pc3 from "picocolors";
+import open from "open";
+async function startCommand(opts) {
+  const projectDir = path4.resolve(opts.dir);
+  if (hasLocalSource(projectDir) && !localSourceBuilt(projectDir)) {
+    throw new Error(`This folder carries its own ledgr source but it is not built. Run ${pc3.cyan("pnpm install && pnpm build")} here (or ${pc3.cyan("ledgr upgrade")}).`);
+  }
+  const api = loadApi(projectDir);
+  const dir = path4.join(projectDir, ".ledgr");
+  const webDist = opts.apiOnly ? null : resolveWebDist(projectDir);
+  if (!opts.apiOnly && !webDist) {
+    console.error(pc3.yellow("Dashboard build not found (@atyaio/ledgr-web/dist). Serving the API only. Run `pnpm build` in the ledgr repo, or use --api-only to silence this."));
+  }
+  let started;
+  try {
+    started = await api.startApp({ dir, host: opts.host, port: opts.port ? Number(opts.port) : void 0, webDist: webDist ?? null });
+  } catch (e) {
+    if (e instanceof Error && /EADDRINUSE/.test(e.message)) {
+      const port = opts.port ?? "4848";
+      throw new Error(`Port ${port} is already in use (another ledgr or app is running there). Stop it, or start on another port: ${pc3.cyan(`ledgr start --port ${Number(port) + 1}`)}`);
+    }
+    throw e;
+  }
+  const { url, ctx } = started;
+  if (ctx.config.auth.mode === "none" && opts.host !== "127.0.0.1" && opts.host !== "localhost") {
+    console.error(pc3.red(`WARNING: auth.mode is "none" and you are binding to ${opts.host}. Anyone who can reach this host can edit the ledger.`));
+  }
+  console.log(`
+  ${pc3.bgYellow(pc3.black(" ledgr "))}  ${pc3.bold(ctx.config.name)}  \u2192  ${pc3.cyan(url)}
+  ${pc3.dim(`data: ${ctx.paths.dbPath}`)}${hasLocalSource(projectDir) ? pc3.dim("\n  code: this folder (standalone)") : ""}
+`);
+  if (opts.open) await open(url);
+  const stop = () => process.exit(0);
+  process.on("SIGINT", stop);
+  process.on("SIGTERM", stop);
+}
+
+// src/commands/doctor.ts
+import * as fs4 from "fs";
+import * as path5 from "path";
+import pc4 from "picocolors";
+async function doctorCommand(opts) {
+  const projectDir = path5.resolve(opts.dir);
+  const standalone = hasLocalSource(projectDir);
+  if (standalone && !localSourceBuilt(projectDir)) {
+    console.log(`${pc4.red("\u2716")} standalone source present but not built \u2014 run ${pc4.cyan("pnpm install && pnpm build")} here.`);
+    process.exit(1);
+  }
+  const api = loadApi(projectDir);
+  const paths = api.resolvePaths(path5.join(projectDir, ".ledgr"));
+  const ok = (m) => console.log(`${pc4.green("\u2714")} ${m}`);
+  const bad = (m) => console.log(`${pc4.red("\u2716")} ${m}`);
+  const warn = (m) => console.log(`${pc4.yellow("\u25B2")} ${m}`);
+  let failures = 0;
+  if (!fs4.existsSync(paths.configPath)) {
+    bad(`No config at ${paths.configPath}. Run ${pc4.cyan("ledgr init")}.`);
+    process.exit(1);
+  }
+  let ctx;
+  try {
+    ctx = api.loadContext(paths.dir);
+    ok(`config.json valid \xB7 ${ctx.config.name} \xB7 ${ctx.config.currency} \xB7 auth ${ctx.config.auth.mode}`);
+  } catch (e) {
+    bad(`config.json: ${e.message}`);
+    process.exit(1);
+  }
+  if (ctx.config.auth.mode === "none") warn("auth.mode = none \u2014 fine on localhost, not for hosting.");
+  try {
+    const { applied } = api.runMigrations(paths.dbPath);
+    ok(applied.length ? `database migrated (${applied.length} new migration(s))` : "database up to date");
+    const counts = await api.dbCounts(ctx);
+    ok(`${counts.stakeholders} stakeholders \xB7 ${counts.categories} categories \xB7 ${counts.expenses} expenses \xB7 ${counts.revenue} revenue`);
+    if (!counts.stakeholders) warn("no stakeholders yet \u2014 expenses will not be split until you add partners.");
+  } catch (e) {
+    bad(`database: ${e.message}`);
+    failures++;
+  }
+  if (standalone) ok("standalone project: using the ledgr source in this folder");
+  const web = resolveWebDist(projectDir);
+  if (web) ok(`dashboard build found at ${web}`);
+  else {
+    warn("dashboard build missing (@atyaio/ledgr-web/dist) \u2014 `ledgr start` will serve the API only.");
+  }
+  console.log(failures ? pc4.red(`
+${failures} problem(s).`) : pc4.green("\nAll good."));
+  process.exit(failures ? 1 : 0);
+}
+
+// src/commands/seed.ts
+import * as path6 from "path";
+import pc5 from "picocolors";
+async function seedCommand(opts) {
+  const projectDir = path6.resolve(opts.dir);
+  const api = loadApi(projectDir);
+  if (!api.seedDemo) throw new Error("This build of @atyaio/ledgr-api has no demo seeder.");
+  const ctx = api.loadContext(path6.join(projectDir, ".ledgr"));
+  console.log(pc5.dim(`Seeding ${ctx.config.name} with ${opts.months} months of demo data\u2026`));
+  await api.seedDemo(ctx, { months: Number(opts.months) || 12, force: opts.force });
+  console.log(pc5.green("Demo data loaded.") + pc5.dim(" Run `ledgr start --open`."));
+  process.exit(0);
+}
+
+// src/commands/upgrade.ts
+import * as path7 from "path";
+import { spawnSync as spawnSync2 } from "child_process";
+import pc6 from "picocolors";
+
+// src/package.ts
+import { createRequire as createRequire2 } from "module";
+var require3 = createRequire2(import.meta.url);
+var pkg = require3("../package.json");
+var PACKAGE_NAME = pkg.name;
+var PACKAGE_VERSION = pkg.version;
+function runningFromNpxCache() {
+  return /[\\/]_npx[\\/]/.test(new URL(import.meta.url).pathname);
+}
+
+// src/commands/upgrade.ts
+async function upgradeCommand(opts) {
+  const projectDir = path7.resolve(opts.dir);
+  if (!hasLocalSource(projectDir)) {
+    upgradePackage();
+    return;
+  }
+  console.log(pc6.dim("Fetching and merging upstream ledgr/main\u2026"));
+  const r = upgradeSource(projectDir);
+  if (!r.changed) console.log(pc6.green("Already up to date.") + pc6.dim(` (${r.after})`));
+  else console.log(pc6.green(`Merged ${r.before} \u2192 ${r.after}.`));
+  if (opts.build !== false) {
+    console.log(pc6.dim("Installing and building\u2026"));
+    installAndBuild(projectDir);
+  }
+  console.log(pc6.green("Done.") + pc6.dim(" Restart `ledgr start` to pick up the changes."));
+}
+function upgradePackage() {
+  const spec = `${PACKAGE_NAME}@latest`;
+  if (runningFromNpxCache()) {
+    console.log(`${pc6.green("Nothing to do.")} ${pc6.dim(`npx ${PACKAGE_NAME} always runs the latest published version (this one is ${PACKAGE_VERSION}).`)}`);
+    console.log(pc6.dim(`For a fixed install on a server: ${pc6.cyan(`npm install -g ${spec}`)}, then ${pc6.cyan("ledgr start")}.`));
+    return;
+  }
+  console.log(pc6.dim(`Installed ${PACKAGE_NAME} ${PACKAGE_VERSION}. Running ${pc6.cyan(`npm install -g ${spec}`)}\u2026`));
+  run("npm", ["install", "-g", spec], process.cwd());
+  const after = versionOf(PACKAGE_NAME);
+  console.log(pc6.green(after && after !== PACKAGE_VERSION ? `Upgraded ${PACKAGE_VERSION} \u2192 ${after}.` : `Already up to date (${after ?? PACKAGE_VERSION}).`) + pc6.dim(" Restart `ledgr start` to pick up the changes."));
+}
+function versionOf(name) {
+  try {
+    const r = spawnSync2("npm", ["ls", "-g", name, "--json", "--depth=0"], { stdio: "pipe" });
+    const json = JSON.parse(r.stdout.toString() || "{}");
+    return json.dependencies?.[name]?.version;
+  } catch {
+    return void 0;
+  }
+}
+
+// src/commands/backup.ts
+import * as fs5 from "fs";
+import * as path8 from "path";
+import pc7 from "picocolors";
+async function backupCommand(opts) {
+  const projectDir = path8.resolve(opts.dir);
+  const api = loadApi(projectDir);
+  if (!api.backupDatabase) {
+    throw new Error("The installed @atyaio/ledgr-api is too old for `ledgr backup`. Upgrade the ledgr package (or run `ledgr upgrade` in a standalone folder).");
+  }
+  const paths = api.resolvePaths(path8.join(projectDir, ".ledgr"));
+  const ctx = api.loadContext(paths.dir);
+  const toFile = !!opts.out && opts.out.endsWith(".db");
+  const folder = toFile ? path8.dirname(path8.resolve(opts.out)) : path8.resolve(opts.out ?? path8.join(paths.dir, "backups"));
+  const stamp = (/* @__PURE__ */ new Date()).toISOString().slice(0, 19).replace(/[-:]/g, "").replace("T", "-");
+  const prefix = `${ctx.config.slug}-`;
+  const outPath = toFile ? path8.resolve(opts.out) : path8.join(folder, `${prefix}${stamp}.db`);
+  const { bytes } = await api.backupDatabase(paths.dbPath, outPath);
+  console.log(`${pc7.green("\u2714")} ${outPath} ${pc7.dim(`(${(bytes / 1024 / 1024).toFixed(1)} MB)`)}`);
+  const keep = Number(opts.keep);
+  if (!toFile && Number.isFinite(keep) && keep > 0) {
+    const old = fs5.readdirSync(folder).filter((n) => n.startsWith(prefix) && n.endsWith(".db")).sort().slice(0, -keep);
+    for (const n of old) fs5.rmSync(path8.join(folder, n), { force: true });
+    if (old.length) console.log(pc7.dim(`  pruned ${old.length} older backup(s), keeping ${keep}`));
+  }
+}
+
+// src/index.ts
+var program = new Command();
+program.name("ledgr").description("Self-contained finance dashboard for any project: expenses, revenue, stakeholders, splits, analytics.").version(PACKAGE_VERSION, "-v, --version", `print the installed ${PACKAGE_NAME} version`);
+program.command("init [folder]").description("Set up a project: creates <folder>/.ledgr (config + SQLite). Defaults to the current folder.").option("-d, --dir <dir>", "alias for the folder argument", process.cwd()).option("-y, --yes", "accept defaults without prompting").option("--name <name>", "project name").option("--currency <code>", "ISO currency, e.g. EGP").option("--no-auth", "skip Supabase auth (local only)").option("-s, --standalone", "also clone the ledgr source into the folder so the project can customise it (upgrade later with `ledgr upgrade`)").option("--from <repoOrPath>", "where to clone the source from (default: GitHub atyaio/ledgr; a local checkout path works too)").option("--no-build", "standalone: skip pnpm install && pnpm build").action((folder, opts) => initCommand({ ...opts, dir: folder ?? opts.dir }));
+program.command("upgrade").description(`Update ledgr: shared installs run npm install -g ${PACKAGE_NAME}@latest; standalone projects merge the latest source from GitHub and rebuild`).option("-d, --dir <dir>", "project folder", process.cwd()).option("--no-build", "standalone: skip pnpm install && pnpm build after merging").action(upgradeCommand);
+program.command("start").description("Start the API + dashboard for the project in this folder").option("-d, --dir <dir>", "project folder containing .ledgr", process.cwd()).option("-p, --port <port>", "port (default: config.port or 4848)").option("-H, --host <host>", "bind host", "127.0.0.1").option("--open", "open the dashboard in the browser", false).option("--api-only", "do not serve the dashboard", false).action(startCommand);
+program.command("doctor").description("Check config, database and dashboard build").option("-d, --dir <dir>", "project folder containing .ledgr", process.cwd()).action(doctorCommand);
+program.command("backup").description("Copy the database to a timestamped file; safe while the app is running").option("-d, --dir <dir>", "project folder containing .ledgr", process.cwd()).option("-o, --out <path>", "target folder, or a file name ending in .db (default: .ledgr/backups/)").option("--keep <n>", "keep only the newest n backups in the target folder (0 = keep all)", "14").action(backupCommand);
+program.command("seed").description("Insert demo data (a year of realistic entries) into this project").option("-d, --dir <dir>", "project folder containing .ledgr", process.cwd()).option("--demo", "load the demo dataset", true).option("--months <n>", "months of history", "12").option("--force", "seed even if the ledger already has entries", false).action(seedCommand);
+program.parseAsync(process.argv).catch((err) => {
+  console.error(pc8.red(err instanceof Error ? err.message : String(err)));
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@atyaio/ledgr",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Self-contained finance dashboard for any project: expenses, revenue, stakeholders, splits, analytics.",
+  "type": "module",
+  "bin": {
+    "ledgr": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/atyaio/ledgr.git",
+    "directory": "packages/cli"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.8.1",
+    "commander": "^15.0.0",
+    "open": "^11.0.4",
+    "picocolors": "^1.1.1",
+    "@atyaio/ledgr-api": "0.1.1",
+    "@atyaio/ledgr-web": "0.1.1",
+    "@atyaio/ledgr-shared": "0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "tsup": "^9.0.0",
+    "typescript": "~5.9.3"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-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.