mulmoclaude 0.5.2 → 0.6.0

package/server/accounting/defaultAccounts.ts

@@ -0,0 +1,87 @@
+// Default chart of accounts seeded into a freshly created book.
+// The active set is intentionally minimal — covers the common
+// categories users need to record their first opening balance and
+// post their first entries, without overwhelming a brand-new user.
+//
+// A second tier of `active: false` entries is included so the user
+// can flip on common-but-not-universal accounts (Inventory, Travel,
+// Depreciation Expense, …) from Manage Accounts with one click
+// rather than typing them in by hand. Inactive accounts stay
+// hidden from journal entry / ledger dropdowns until the user
+// reactivates them. Tax-related accounts (1400 / 2400) are an
+// exception — they ship active by default since almost every
+// jurisdiction levies a consumption / sales / VAT tax.
+
+import type { Account } from "./types.js";
+
+export const DEFAULT_ACCOUNTS: readonly Account[] = [
+  // Assets
+  { code: "1000", name: "Cash", type: "asset" },
+  { code: "1001", name: "Petty Cash", type: "asset", active: false },
+  { code: "1010", name: "Bank — Checking", type: "asset" },
+  { code: "1020", name: "Bank — Savings", type: "asset" },
+  { code: "1100", name: "Accounts Receivable", type: "asset" },
+  { code: "1200", name: "Inventory", type: "asset", active: false },
+  { code: "1300", name: "Prepaid Expenses", type: "asset", active: false },
+  // 14xx is the reserved "tax-related current assets" band — pairs
+  // with 24xx on the liability side for the tax-excluded (税抜)
+  // booking method: input tax paid on purchases sits here as an
+  // asset and is netted against output-tax collected at filing
+  // time. The Ledger view's T-number column and the
+  // JournalEntryForm's per-line taxRegistrationId input key off
+  // the 14xx prefix only (see `isTaxAccountCode`) — the
+  // counterparty registration ID is load-bearing for input-tax
+  // credit on purchases, not for the seller-side liability — so
+  // any custom 14xx account a user adds participates without an
+  // opt-in step. Active by default — most jurisdictions levy a
+  // consumption / sales / VAT tax; tax-free contexts can
+  // deactivate from Manage Accounts.
+  // 1400 was briefly named "Sales Tax Receivable" — that label
+  // conventionally means *output* tax billed to customers but not
+  // yet collected. Renamed to "Input Tax Receivable" so the
+  // purchase-side meaning matches the 14xx / 24xx booking pair and
+  // the non-US naming the rest of the world uses (EU "Input VAT" /
+  // UK VAT input / Japan 仮払消費税). CodeRabbit review on PR #1120.
+  { code: "1400", name: "Input Tax Receivable", type: "asset" },
+  { code: "1500", name: "Equipment", type: "asset" },
+  { code: "1510", name: "Furniture & Fixtures", type: "asset", active: false },
+  { code: "1520", name: "Vehicles", type: "asset", active: false },
+  { code: "1590", name: "Accumulated Depreciation", type: "asset", active: false },
+  // Liabilities
+  { code: "2000", name: "Accounts Payable", type: "liability" },
+  { code: "2100", name: "Credit Card", type: "liability" },
+  { code: "2200", name: "Loans Payable", type: "liability" },
+  { code: "2300", name: "Accrued Expenses", type: "liability", active: false },
+  // 24xx is the reserved "tax-related current liabilities" band;
+  // pairs with 14xx on the asset side. See the 1400 comment above.
+  { code: "2400", name: "Sales Tax Payable", type: "liability" },
+  { code: "2500", name: "Payroll Liabilities", type: "liability", active: false },
+  // Equity
+  // Required for opening balances: setOpeningBalances dumps the
+  // plug into "Retained Earnings" by convention.
+  { code: "3000", name: "Owner's Equity", type: "equity" },
+  { code: "3100", name: "Retained Earnings", type: "equity" },
+  { code: "3200", name: "Owner's Draws", type: "equity", active: false },
+  // Income
+  { code: "4000", name: "Sales", type: "income" },
+  { code: "4010", name: "Service Revenue", type: "income", active: false },
+  { code: "4100", name: "Other Income", type: "income" },
+  { code: "4200", name: "Interest Income", type: "income", active: false },
+  { code: "4300", name: "Sales Returns & Discounts", type: "income", active: false },
+  // Expenses
+  { code: "5000", name: "Cost of Goods Sold", type: "expense" },
+  { code: "5100", name: "Rent", type: "expense" },
+  { code: "5200", name: "Utilities", type: "expense" },
+  { code: "5300", name: "Salaries", type: "expense" },
+  { code: "5400", name: "Office Supplies", type: "expense" },
+  { code: "5500", name: "Advertising & Marketing", type: "expense", active: false },
+  { code: "5600", name: "Travel", type: "expense", active: false },
+  { code: "5610", name: "Meals & Entertainment", type: "expense", active: false },
+  { code: "5700", name: "Professional Fees", type: "expense", active: false },
+  { code: "5710", name: "Insurance", type: "expense", active: false },
+  { code: "5720", name: "Software & Subscriptions", type: "expense", active: false },
+  { code: "5730", name: "Bank Fees", type: "expense", active: false },
+  { code: "5800", name: "Depreciation Expense", type: "expense", active: false },
+  { code: "5810", name: "Taxes", type: "expense", active: false },
+  { code: "5900", name: "Miscellaneous Expense", type: "expense" },
+];

package/server/accounting/eventPublisher.ts

@@ -0,0 +1,51 @@
+// Pub/sub publisher for the accounting plugin. Mirror of
+// `server/events/file-change.ts`: module singleton + init function +
+// fire-and-forget publish helpers. The init wiring lives in
+// `server/index.ts` next to `initFileChangePublisher`.
+//
+// Channel names + payload shapes are imported from
+// `src/config/pubsubChannels.ts` so the publisher cannot drift from
+// the View-side subscribers.
+
+import { accountingBookChannel, PUBSUB_CHANNELS, type AccountingBookChannelPayload } from "../../src/config/pubsubChannels.js";
+import { log } from "../system/logger/index.js";
+import type { IPubSub } from "../events/pub-sub/index.js";
+
+let pubsub: IPubSub | null = null;
+
+export function initAccountingEventPublisher(instance: IPubSub): void {
+  pubsub = instance;
+}
+
+function safePublish(channel: string, payload: unknown): void {
+  if (!pubsub) return;
+  try {
+    pubsub.publish(channel, payload);
+  } catch (err) {
+    // Same fire-and-forget rationale as the file-change publisher:
+    // dropping one event is better than crashing the server.
+    log.warn("accounting", "publish failed; subscribers will miss this event", {
+      channel,
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+}
+
+/** Per-book change notification. `period` should be the entry's
+ *  YYYY-MM bucket (or the earliest invalidated month for snapshot
+ *  events). */
+export function publishBookChange(bookId: string, payload: AccountingBookChannelPayload): void {
+  safePublish(accountingBookChannel(bookId), payload);
+}
+
+/** Fired when the *list* of books changes (createBook, deleteBook).
+ *  Payload is intentionally empty — subscribers refetch from
+ *  /api/accounting. */
+export function publishBooksChanged(): void {
+  safePublish(PUBSUB_CHANNELS.accountingBooks, {});
+}
+
+/** Test-only — drop the module singleton so each test starts clean. */
+export function _resetAccountingEventPublisherForTesting(): void {
+  pubsub = null;
+}

package/server/accounting/journal.ts

@@ -0,0 +1,252 @@
+// Pure validation + creation logic for journal entries. No fs access
+// here — callers wire the validated entry to `appendJournal` in
+// `server/utils/files/accounting-io.ts`.
+//
+// Double-entry rule: every entry's lines must satisfy
+//   Σ debit === Σ credit   (within a tolerance of 0.005 — see
+//                            EQUALITY_TOLERANCE below)
+//
+// Append-only: there is no `editEntry`. Corrections are made by
+// `voidEntry` (creates a reversing pair) followed by a fresh
+// `addEntries` call for the corrected booking.
+
+import { randomUUID } from "node:crypto";
+
+import type { Account, JournalEntry, JournalLine } from "./types.js";
+
+/** Floating-point tolerance for the debit = credit check. Currency
+ *  amounts arrive as JavaScript numbers (the on-wire format is JSON,
+ *  so amounts are doubles). 0.005 keeps two-decimal currency math
+ *  honest while accepting the floating-point noise of summing
+ *  many lines. */
+const EQUALITY_TOLERANCE = 0.005;
+
+/** Defensive cap on `JournalLine.taxRegistrationId`. Real-world IDs
+ *  are short (JP T-numbers are 14 chars, EU VAT IDs ≤ 14, GSTIN is
+ *  15, ABN is 11). 32 covers every documented format with comfortable
+ *  margin while still rejecting accidental paste-bombs. Validation
+ *  applies to the *trimmed* value so a string of pure whitespace
+ *  doesn't trip the limit (it normalises to absent). */
+export const MAX_TAX_REGISTRATION_ID_LENGTH = 32;
+
+export interface ValidationError {
+  field: string;
+  message: string;
+}
+
+export interface ValidationResult {
+  ok: boolean;
+  errors: ValidationError[];
+}
+
+function lineHasExactlyOneSide(line: JournalLine): boolean {
+  const hasDebit = typeof line.debit === "number" && line.debit !== 0;
+  const hasCredit = typeof line.credit === "number" && line.credit !== 0;
+  return hasDebit !== hasCredit;
+}
+
+function isNonNegativeNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+
+/** Build today's `YYYY-MM-DD` from the host's local timezone.
+ *  Centralised here so server-side defaults (the void-date on
+ *  `voidEntry`, the today() stamp on opening replacements, etc.)
+ *  agree with the client-side `localDateString()` from
+ *  `src/plugins/accounting/dates.ts`. `toISOString().slice(0, 10)`
+ *  would emit a UTC date instead — which silently flips into
+ *  tomorrow / yesterday in negative-offset timezones. */
+export function localDateString(now: Date = new Date()): string {
+  const year = now.getFullYear();
+  const month = String(now.getMonth() + 1).padStart(2, "0");
+  const day = String(now.getDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+
+/** Validate that `date` is both shaped as YYYY-MM-DD AND represents
+ *  a real calendar day. The bare regex accepts impossible values
+ *  like 2026-02-31 or 2026-13-01 which would then poison
+ *  `periodFromDate`, sort orders, and snapshot keys. We reparse
+ *  through the Date constructor and roundtrip-format to catch
+ *  silent normalisation (e.g. "2026-02-30" → Mar 02). */
+export function isValidCalendarDate(date: string): boolean {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) return false;
+  const [year, month, day] = date.split("-").map((segment) => parseInt(segment, 10));
+  const parsed = new Date(Date.UTC(year, month - 1, day));
+  return parsed.getUTCFullYear() === year && parsed.getUTCMonth() === month - 1 && parsed.getUTCDate() === day;
+}
+
+/** Returns Σ debit − Σ credit. Used by callers that need the actual
+ *  imbalance value (e.g. the OpeningBalancesForm shows live diff). */
+export function netBalance(lines: readonly JournalLine[]): number {
+  let net = 0;
+  for (const line of lines) {
+    if (typeof line.debit === "number") net += line.debit;
+    if (typeof line.credit === "number") net -= line.credit;
+  }
+  return net;
+}
+
+/** Pure validation. Does not throw; returns a list of issues so the
+ *  REST handler can return a structured 400 instead of an opaque
+ *  500. */
+function validateLine(line: JournalLine, idx: number, accountCodes: ReadonlySet<string>, errors: ValidationError[]): void {
+  if (!line.accountCode || !accountCodes.has(line.accountCode)) {
+    errors.push({ field: `lines[${idx}].accountCode`, message: `unknown account code ${JSON.stringify(line.accountCode)}` });
+  }
+  if (line.debit !== undefined && !isNonNegativeNumber(line.debit)) {
+    errors.push({ field: `lines[${idx}].debit`, message: "debit must be a non-negative finite number" });
+  }
+  if (line.credit !== undefined && !isNonNegativeNumber(line.credit)) {
+    errors.push({ field: `lines[${idx}].credit`, message: "credit must be a non-negative finite number" });
+  }
+  if (!lineHasExactlyOneSide(line)) {
+    errors.push({ field: `lines[${idx}]`, message: "each line must set exactly one of debit or credit (and to a non-zero amount)" });
+  }
+  if (line.taxRegistrationId !== undefined) {
+    if (typeof line.taxRegistrationId !== "string") {
+      errors.push({ field: `lines[${idx}].taxRegistrationId`, message: "must be a string" });
+    } else if (line.taxRegistrationId.trim().length > MAX_TAX_REGISTRATION_ID_LENGTH) {
+      errors.push({
+        field: `lines[${idx}].taxRegistrationId`,
+        message: `must be at most ${MAX_TAX_REGISTRATION_ID_LENGTH} characters (got ${line.taxRegistrationId.trim().length})`,
+      });
+    }
+  }
+}
+
+/** Normalize a journal line before persistence: trim string fields
+ *  and drop empty-string optionals so the JSONL doesn't accumulate
+ *  noise like `"taxRegistrationId":""`. Pure — does not mutate
+ *  `line`. */
+function normalizeLine(line: JournalLine): JournalLine {
+  const out: JournalLine = { ...line };
+  if (typeof out.taxRegistrationId === "string") {
+    const trimmed = out.taxRegistrationId.trim();
+    if (trimmed === "") delete out.taxRegistrationId;
+    else out.taxRegistrationId = trimmed;
+  }
+  return out;
+}
+
+export function validateEntry(input: { date: string; lines: readonly JournalLine[]; accounts: readonly Account[] }): ValidationResult {
+  const errors: ValidationError[] = [];
+  if (!isValidCalendarDate(input.date)) {
+    errors.push({ field: "date", message: `expected YYYY-MM-DD calendar date, got ${JSON.stringify(input.date)}` });
+  }
+  if (!Array.isArray(input.lines) || input.lines.length < 2) {
+    errors.push({ field: "lines", message: "an entry needs at least two lines (one debit, one credit)" });
+    return { ok: false, errors };
+  }
+  const accountCodes = new Set(input.accounts.map((account) => account.code));
+  input.lines.forEach((line, idx) => validateLine(line, idx, accountCodes, errors));
+  const net = netBalance(input.lines);
+  if (Math.abs(net) > EQUALITY_TOLERANCE) {
+    errors.push({ field: "lines", message: `Σ debit − Σ credit = ${net.toFixed(4)}; entry must balance` });
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+/** Build a JournalEntry — validation is the caller's responsibility
+ *  (it should have called `validateEntry` first). The id is a fresh
+ *  UUID; createdAt is the wall clock at the moment of creation.
+ *  Lines are normalized so optional string fields don't persist as
+ *  empty strings. */
+export function makeEntry(input: {
+  date: string;
+  lines: readonly JournalLine[];
+  memo?: string;
+  kind?: JournalEntry["kind"];
+  replacesEntryId?: string;
+}): JournalEntry {
+  const entry: JournalEntry = {
+    id: randomUUID(),
+    date: input.date,
+    kind: input.kind ?? "normal",
+    lines: input.lines.map(normalizeLine),
+    memo: input.memo,
+    createdAt: new Date().toISOString(),
+  };
+  if (input.replacesEntryId) entry.replacesEntryId = input.replacesEntryId;
+  return entry;
+}
+
+/** Pick the most descriptive memo from the original entry to quote
+ *  in the voiding entry's memo. Precedence: entry-level memo →
+ *  first non-empty line memo → null (caller falls back to a
+ *  date-only template). */
+function originalMemoToQuote(target: JournalEntry): string | null {
+  if (target.memo && target.memo.trim() !== "") return target.memo;
+  for (const line of target.lines) {
+    if (line.memo && line.memo.trim() !== "") return line.memo;
+  }
+  return null;
+}
+
+/** Build the human-readable memo that goes on the voiding entry.
+ *  Format: `void of '<original memo>' on <original date>` (or the
+ *  no-memo fallback when the original carried no memo). The reason
+ *  the user typed is appended after a colon when present. */
+export function voidMemo(target: JournalEntry, reason: string | undefined): string {
+  const quoted = originalMemoToQuote(target);
+  const base = quoted !== null ? `void of '${quoted}' on ${target.date}` : `void of entry on ${target.date}`;
+  return reason && reason.trim() !== "" ? `${base}: ${reason}` : base;
+}
+
+/** Build the reversing pair for a voided entry. The `void` entry
+ *  swaps debit / credit on every line so the net effect is zero;
+ *  the `void-marker` is a zero-line entry that exists purely to
+ *  carry the `voidedEntryId` reference and the user's reason. The
+ *  marker keeps `listEntries` queries simple — filtering by
+ *  `kind: "void-marker"` surfaces every voided id without scanning
+ *  for matching pairs. */
+export function makeVoidEntries(target: JournalEntry, reason: string | undefined, voidDate: string): { reverse: JournalEntry; marker: JournalEntry } {
+  const swappedLines: JournalLine[] = target.lines.map((line) => {
+    const swapped: JournalLine = {
+      accountCode: line.accountCode,
+      debit: line.credit,
+      credit: line.debit,
+      memo: line.memo,
+    };
+    // Preserve the counterparty tax-registration ID on each reversed
+    // line so the audit trail survives the void — without it, the
+    // reversing pair would silently drop the input-tax-credit
+    // documentation and a later report scan couldn't reconstruct
+    // which T-number / VAT ID the original input tax was tied to.
+    if (line.taxRegistrationId !== undefined) swapped.taxRegistrationId = line.taxRegistrationId;
+    return swapped;
+  });
+  const reverse: JournalEntry = {
+    id: randomUUID(),
+    date: voidDate,
+    kind: "void",
+    lines: swappedLines,
+    memo: voidMemo(target, reason),
+    voidedEntryId: target.id,
+    voidReason: reason,
+    createdAt: new Date().toISOString(),
+  };
+  const marker: JournalEntry = {
+    id: randomUUID(),
+    date: voidDate,
+    kind: "void-marker",
+    lines: [],
+    voidedEntryId: target.id,
+    voidReason: reason,
+    createdAt: new Date().toISOString(),
+  };
+  return { reverse, marker };
+}
+
+/** Returns the set of entry ids that have been voided — built from
+ *  every `void-marker` entry's `voidedEntryId`. Reports use this to
+ *  exclude original-and-reverse pairs from the activity listing
+ *  (the netting is automatic in B/S aggregates because the reverse
+ *  entry has equal-and-opposite lines). */
+export function voidedIdSet(entries: readonly JournalEntry[]): Set<string> {
+  const set = new Set<string>();
+  for (const entry of entries) {
+    if (entry.kind === "void-marker" && entry.voidedEntryId) set.add(entry.voidedEntryId);
+  }
+  return set;
+}

package/server/accounting/openingBalances.ts

@@ -0,0 +1,114 @@
+// Opening balance ("year-start B/S") logic. Adoption flow: a user
+// migrating from another bookkeeping system enters their existing
+// asset / liability / equity balances as of a chosen `asOfDate`,
+// instead of replaying their entire historical journal.
+//
+// Stored as a single `kind: "opening"` entry in the regular journal
+// — keeps the journal as the single source of truth, and makes
+// reports treat the opening as just an early entry without special
+// branches in aggregation.
+//
+// Replacing an existing opening: void the old, append the new. The
+// route handler is responsible for ordering this with snapshot
+// invalidation so the "before" snapshots get dropped.
+
+import type { Account, JournalEntry, JournalLine } from "./types.js";
+import { BALANCE_SHEET_ACCOUNT_TYPES } from "./types.js";
+import { isValidCalendarDate, netBalance, voidedIdSet } from "./journal.js";
+
+const EQUALITY_TOLERANCE = 0.005;
+
+export interface OpeningValidationError {
+  field: string;
+  message: string;
+}
+
+export interface OpeningValidationResult {
+  ok: boolean;
+  errors: OpeningValidationError[];
+}
+
+/** Find the existing opening entry for a book, if any. Multiple
+ *  openings shouldn't coexist (the route enforces void-then-append),
+ *  but if they do the most recent by `createdAt` wins so callers
+ *  always see one canonical opening. */
+export function findActiveOpening(entries: readonly JournalEntry[]): JournalEntry | null {
+  const voided = voidedIdSet(entries);
+  let active: JournalEntry | null = null;
+  for (const entry of entries) {
+    if (entry.kind !== "opening") continue;
+    if (voided.has(entry.id)) continue;
+    if (!active || entry.createdAt > active.createdAt) active = entry;
+  }
+  return active;
+}
+
+interface OpeningValidationInput {
+  asOfDate: string;
+  lines: readonly JournalLine[];
+  accounts: readonly Account[];
+  existingEntries: readonly JournalEntry[];
+}
+
+function validateLineAccountTypes(input: OpeningValidationInput, errors: OpeningValidationError[]): void {
+  const accountByCode = new Map(input.accounts.map((account) => [account.code, account]));
+  input.lines.forEach((line, idx) => {
+    const acct = accountByCode.get(line.accountCode);
+    if (!acct) {
+      errors.push({ field: `lines[${idx}].accountCode`, message: `unknown account code ${JSON.stringify(line.accountCode)}` });
+      return;
+    }
+    if (!BALANCE_SHEET_ACCOUNT_TYPES.includes(acct.type)) {
+      errors.push({
+        field: `lines[${idx}].accountCode`,
+        message: `account ${acct.code} is type ${acct.type}; opening balances may only reference balance-sheet accounts (asset / liability / equity)`,
+      });
+    }
+  });
+}
+
+function validateAsOfPredatesEverything(input: OpeningValidationInput, errors: OpeningValidationError[]): void {
+  // The point of the rule is "you can't enter an opening dated
+  // 2026-01-01 if you've already booked transactions in December
+  // 2025" — that would silently change the meaning of those
+  // December transactions. Existing openings (about to be
+  // replaced) and already-voided entries are exempt.
+  const voided = voidedIdSet(input.existingEntries);
+  for (const entry of input.existingEntries) {
+    if (entry.kind === "opening") continue;
+    if (entry.kind === "void-marker") continue;
+    if (voided.has(entry.id)) continue;
+    if (entry.date < input.asOfDate) {
+      errors.push({
+        field: "asOfDate",
+        message: `cannot set opening as of ${input.asOfDate}: existing entry ${entry.id} dated ${entry.date} is older. Void it first or pick an earlier asOfDate.`,
+      });
+      break; // one error is enough — listing every conflicting entry would be noisy
+    }
+  }
+}
+
+/** Validate inputs for `setOpeningBalances`. Caller passes the full
+ *  list of journal entries in the book so we can check the
+ *  "asOfDate must precede every other entry" rule. An opening with
+ *  zero lines is accepted as a no-op marker — it satisfies the
+ *  "book has an opening" gate the UI uses without committing the
+ *  user to specific balances on day one (they can replace it
+ *  later). */
+export function validateOpening(input: OpeningValidationInput): OpeningValidationResult {
+  const errors: OpeningValidationError[] = [];
+  if (!isValidCalendarDate(input.asOfDate)) {
+    errors.push({ field: "asOfDate", message: `expected YYYY-MM-DD calendar date, got ${JSON.stringify(input.asOfDate)}` });
+  }
+  if (!Array.isArray(input.lines)) {
+    errors.push({ field: "lines", message: "lines must be an array" });
+    return { ok: false, errors };
+  }
+  validateLineAccountTypes(input, errors);
+  const net = netBalance(input.lines);
+  if (Math.abs(net) > EQUALITY_TOLERANCE) {
+    errors.push({ field: "lines", message: `Σ debit − Σ credit = ${net.toFixed(4)}; opening must balance` });
+  }
+  validateAsOfPredatesEverything(input, errors);
+  return { ok: errors.length === 0, errors };
+}