@invoicer/cli 1.1.0

package/src/commands/generate.ts

@@ -0,0 +1,379 @@
+import fs from "node:fs";
+import inquirer from "inquirer";
+import type { Command } from "commander";
+import { loadJsonFile, writeJsonFile } from "../core/json-store.js";
+import { type ProjectPaths } from "../core/paths.js";
+import { validateConfig, validateLastState } from "../core/validators.js";
+import { type Config, type GenerateOptions, type LastState, type LineItem } from "../domain/types.js";
+import {
+  getDefaultMonth,
+  getInvoiceDate,
+  getInvoicePeriod,
+  resolveInvoiceNumber,
+  validateMonth,
+} from "../services/invoice-number.js";
+import { hasSmtpConfig, sendInvoiceEmail } from "../services/email.js";
+import { renderInvoicePdf } from "../services/pdf-render.js";
+import {
+  aggregateEntriesByDescription,
+  archiveTimesheetEntries,
+  readTimesheetEntries,
+} from "../services/timesheet.js";
+
+function exitWithError(message: string): never {
+  console.error(message);
+  process.exit(1);
+}
+
+function loadConfig(paths: ProjectPaths): Config {
+  return loadJsonFile(paths.configPath, { client: [], from: {} }, validateConfig);
+}
+
+function loadLastState(paths: ProjectPaths): LastState {
+  return loadJsonFile(paths.lastPath, { clients: {} }, validateLastState);
+}
+
+function getCurrency(cfgCurrency?: string): string {
+  return cfgCurrency?.trim() || "USD";
+}
+
+async function selectClient(cfg: Config, preferredClientName?: string) {
+  if (preferredClientName) {
+    const matched = cfg.client.find((client) => client.name === preferredClientName);
+    if (!matched) {
+      exitWithError(`❌ Client "${preferredClientName}" not found in config.json`);
+    }
+    console.log(`📋 Using client: ${matched.name}`);
+    return matched;
+  }
+
+  if (cfg.client.length === 1) {
+    const [single] = cfg.client;
+    console.log(`📋 Using client: ${single.name}`);
+    return single;
+  }
+
+  const clientChoices = cfg.client.map((client, index) => ({
+    name: `${client.name} (${getCurrency(client.currency)} ${client.defaultRate}/hr)`,
+    value: index,
+  }));
+
+  const answer = await inquirer.prompt<{ clientIndex: number }>([
+    {
+      type: "list",
+      name: "clientIndex",
+      message: "Select client:",
+      choices: clientChoices,
+    },
+  ]);
+
+  return cfg.client[answer.clientIndex];
+}
+
+async function collectManualLineItems(params: {
+  options: GenerateOptions;
+  cfg: Config;
+  currency: string;
+  lastHours: number;
+  lastRate: number;
+  defaultRate: number;
+}): Promise<LineItem[]> {
+  const items: LineItem[] = [];
+  let addingItems = true;
+  let itemIndex = 1;
+
+  while (addingItems) {
+    const answer = await inquirer.prompt<{
+      description: string;
+      hours: number;
+      rate: number;
+    }>([
+      {
+        type: "input",
+        name: "description",
+        message: `Description (Item ${itemIndex}):`,
+        default:
+          itemIndex === 1
+            ? (params.options.desc || params.cfg.defaultDescription || "Services")
+            : "",
+      },
+      {
+        type: "number",
+        name: "hours",
+        message: "Hours:",
+        default:
+          itemIndex === 1
+            ? (params.options.hours ? Number(params.options.hours) : Number(params.lastHours ?? 160))
+            : undefined,
+      },
+      {
+        type: "number",
+        name: "rate",
+        message: "Rate per hour:",
+        default:
+          itemIndex === 1
+            ? (params.options.rate ? Number(params.options.rate) : Number(params.lastRate ?? params.defaultRate))
+            : params.defaultRate,
+      },
+    ]);
+
+    const hours = Number(answer.hours);
+    const rate = Number(answer.rate);
+
+    if (!Number.isFinite(hours) || !Number.isFinite(rate)) {
+      exitWithError("❌ Hours and rate must be valid numbers");
+    }
+
+    const amount = hours * rate;
+
+    items.push({
+      description: answer.description,
+      hours,
+      rate,
+      amount,
+    });
+
+    console.log(
+      `   ✓ ${answer.description}: ${hours}h × ${params.currency}${rate} = ${params.currency}${amount.toFixed(2)}`,
+    );
+
+    const addAnotherAnswer = await inquirer.prompt<{ addAnother: boolean }>([
+      {
+        type: "confirm",
+        name: "addAnother",
+        message: "Add another line item?",
+        default: false,
+      },
+    ]);
+
+    addingItems = addAnotherAnswer.addAnother;
+    itemIndex += 1;
+  }
+
+  return items;
+}
+
+export async function handleGenerateCommand(options: GenerateOptions, paths: ProjectPaths): Promise<void> {
+  fs.mkdirSync(paths.outDir, { recursive: true });
+
+  if (!fs.existsSync(paths.configPath)) {
+    console.error("❌ Missing config.json. Create it first (see README).");
+    console.error(`   Looked in: ${paths.projectRoot}`);
+    process.exit(1);
+  }
+
+  const cfg = loadConfig(paths);
+  const last = loadLastState(paths);
+
+  if (cfg.client.length === 0) {
+    exitWithError("❌ No clients found in config.json");
+  }
+
+  const selectedClient = await selectClient(cfg, options.client);
+
+  const clientKey = selectedClient.name;
+  const clientHistory = last.clients[clientKey] || {
+    lastHours: 160,
+    lastRate: selectedClient.defaultRate ?? 0,
+    seqByMonth: {},
+  };
+
+  const month = options.month || getDefaultMonth();
+
+  if (!validateMonth(month)) {
+    exitWithError("❌ Month must be in YYYY-MM format");
+  }
+
+  let lineItems: LineItem[] = [];
+  let entryIdsToArchive: number[] = [];
+
+  if (options.fromTimesheet) {
+    console.log(`\n🔍 Reading timesheet for ${selectedClient.name} (${month})...`);
+    const entries = readTimesheetEntries(paths, { client: selectedClient.name, month });
+
+    if (entries.length === 0) {
+      console.log("   No unbilled entries found for this period.");
+      console.log("   Falling back to manual entry mode.\n");
+    } else {
+      console.log(`   Found ${entries.length} unbilled entries.\n`);
+
+      const aggregated = aggregateEntriesByDescription(entries);
+
+      console.log("📊 Aggregated by service/project:\n");
+      aggregated.forEach((group, index) => {
+        console.log(`   ${index + 1}. ${group.description}`);
+        console.log(`      ${group.hours}h × $${group.rate}/hr = $${group.amount}`);
+        if (group.rateVariance) {
+          console.log(
+            `      ⚠️  Rate variance: $${group.minRate}-$${group.maxRate}/hr (using weighted average)`,
+          );
+        }
+        console.log(`      Period: ${group.periodFrom} to ${group.periodTo}`);
+        console.log(`      Based on ${group.entryIds.length} timesheet entries\n`);
+      });
+
+      const answer = await inquirer.prompt<{ confirmUse: boolean }>([
+        {
+          type: "confirm",
+          name: "confirmUse",
+          message: "Use these aggregated line items?",
+          default: true,
+        },
+      ]);
+
+      if (answer.confirmUse) {
+        lineItems = aggregated.map((group) => ({
+          description: group.description,
+          hours: group.hours,
+          rate: group.rate,
+          amount: group.amount,
+          periodFrom: group.periodFrom,
+          periodTo: group.periodTo,
+        }));
+        entryIdsToArchive = aggregated.flatMap((group) => group.entryIds);
+      }
+    }
+  }
+
+  if (lineItems.length === 0) {
+    lineItems = await collectManualLineItems({
+      options,
+      cfg,
+      currency: getCurrency(selectedClient.currency),
+      lastHours: clientHistory.lastHours,
+      lastRate: clientHistory.lastRate,
+      defaultRate: selectedClient.defaultRate ?? 0,
+    });
+  }
+
+  const seqByMonth = { ...(clientHistory.seqByMonth || {}) };
+  const invoiceNumber = resolveInvoiceNumber({
+    month,
+    invoicePrefix: cfg.invoicePrefix,
+    overrideInvoice: options.invoice,
+    seqByMonth,
+  });
+
+  const invoiceDate = getInvoiceDate();
+  const { periodFrom, periodTo } = getInvoicePeriod(month);
+
+  const currency = getCurrency(selectedClient.currency);
+  const total = lineItems.reduce((sum, item) => sum + item.amount, 0);
+
+  console.log(`\n💰 Total: ${currency}${total.toFixed(2)}\n`);
+
+  const outPath = await renderInvoicePdf(
+    paths,
+    {
+      from: cfg.from || {},
+      client: selectedClient,
+      currency,
+      invoiceNumber,
+      invoiceDate,
+      periodFrom,
+      periodTo,
+      lineItems,
+      paymentTerms: selectedClient.payPeriodType,
+      note: cfg.note,
+    },
+    month,
+  );
+
+  if (!last.clients) {
+    last.clients = {};
+  }
+
+  const firstLineItem = lineItems[0];
+
+  last.clients[clientKey] = {
+    lastHours: firstLineItem?.hours ?? clientHistory.lastHours,
+    lastRate: firstLineItem?.rate ?? clientHistory.lastRate,
+    seqByMonth,
+  };
+
+  writeJsonFile(paths.lastPath, last);
+
+  console.log("✅ Invoice generated:", outPath);
+  console.log("Invoice #:", invoiceNumber);
+  console.log("Total:", `${currency} ${total.toFixed(2)}`);
+
+  if (entryIdsToArchive.length > 0) {
+    const answer = await inquirer.prompt<{ confirmArchive: boolean }>([
+      {
+        type: "confirm",
+        name: "confirmArchive",
+        message: `Archive ${entryIdsToArchive.length} timesheet entries used in this invoice?`,
+        default: true,
+      },
+    ]);
+
+    if (answer.confirmArchive) {
+      const archivedCount = archiveTimesheetEntries(paths, entryIdsToArchive, invoiceNumber, month);
+      console.log(`✅ Archived ${archivedCount} entries to data/archive.json`);
+    }
+  }
+
+  if (hasSmtpConfig()) {
+    const answer = await inquirer.prompt<{ sendEmail: boolean }>([
+      {
+        type: "confirm",
+        name: "sendEmail",
+        message: "Send invoice via email?",
+        default: true,
+      },
+    ]);
+
+    if (answer.sendEmail) {
+      const emailAnswer = await inquirer.prompt<{ clientEmail: string }>([
+        {
+          type: "input",
+          name: "clientEmail",
+          message: "Client email address:",
+          default: selectedClient.email || "",
+          validate: (value: string) =>
+            /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value) || "Enter valid email",
+        },
+      ]);
+
+      try {
+        console.log("\n📧 Sending email...");
+
+        await sendInvoiceEmail({
+          outPath,
+          invoiceNumber,
+          clientName: selectedClient.name,
+          clientEmail: emailAnswer.clientEmail,
+          currency,
+          total,
+          periodFrom,
+          periodTo,
+          senderName: cfg.from?.name,
+        });
+
+        console.log(`✅ Email sent successfully to ${emailAnswer.clientEmail}`);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error("❌ Failed to send email:", message);
+        console.log("   PDF saved locally at:", outPath);
+      }
+    }
+  } else {
+    console.log("\n💡 Tip: Configure SMTP in .env to enable email sending");
+  }
+}
+
+export function registerGenerateCommand(program: Command, paths: ProjectPaths): void {
+  program
+    .command("generate", { isDefault: true })
+    .description("Generate an invoice from manual entry or timesheet")
+    .option("--from-timesheet", "Auto-populate from timesheet entries", false)
+    .option("--client <name>", "Client name (auto-selected if only one client)")
+    .option("--month <YYYY-MM>", "Invoice month (default: current month)")
+    .option("--hours <number>", "Hours for first line item")
+    .option("--rate <number>", "Rate for first line item")
+    .option("--desc <text>", "Description for first line item")
+    .option("--invoice <number>", "Custom invoice number")
+    .action(async (options: GenerateOptions) => {
+      await handleGenerateCommand(options, paths);
+    });
+}

package/src/commands/timesheet.ts

@@ -0,0 +1,47 @@
+import type { Command } from "commander";
+import { type ProjectPaths } from "../core/paths.js";
+import { type TimesheetOptions } from "../domain/types.js";
+import {
+  readArchivedEntries,
+  readTimesheetEntries,
+  toArchiveCsv,
+  toTimesheetCsv,
+} from "../services/timesheet.js";
+
+export function registerTimesheetCommand(program: Command, paths: ProjectPaths): void {
+  program
+    .command("timesheet")
+    .description("Manage timesheet data")
+    .option("--export <format>", "Export timesheet (csv|json)", "")
+    .option("--client <name>", "Filter by client")
+    .option("--month <YYYY-MM>", "Filter by month")
+    .option("--archive", "Show archived entries", false)
+    .action(async (options: TimesheetOptions) => {
+      if (options.archive) {
+        const archived = readArchivedEntries(paths, {
+          client: options.client || "",
+          month: options.month || "",
+        });
+
+        if (options.export === "csv") {
+          console.log(toArchiveCsv(archived));
+          process.exit(0);
+        }
+
+        console.log(JSON.stringify(archived, null, 2));
+        process.exit(0);
+      }
+
+      const entries = readTimesheetEntries(paths, {
+        client: options.client || "",
+        month: options.month || "",
+      });
+
+      if (options.export === "csv") {
+        console.log(toTimesheetCsv(entries));
+        process.exit(0);
+      }
+
+      console.log(JSON.stringify(entries, null, 2));
+    });
+}

package/src/core/json-store.ts

@@ -0,0 +1,33 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export function readJsonFile(filePath: string): unknown | undefined {
+  if (!fs.existsSync(filePath)) {
+    return undefined;
+  }
+
+  const raw = fs.readFileSync(filePath, "utf8");
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Invalid JSON in ${filePath}: ${message}`);
+  }
+}
+
+export function loadJsonFile<T>(
+  filePath: string,
+  fallback: T,
+  validate: (value: unknown) => T,
+): T {
+  const parsed = readJsonFile(filePath);
+  if (parsed === undefined) {
+    return fallback;
+  }
+  return validate(parsed);
+}
+
+export function writeJsonFile(filePath: string, value: unknown): void {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(value, null, 2));
+}

package/src/core/paths.ts

@@ -0,0 +1,42 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export interface ProjectPaths {
+  projectRoot: string;
+  configPath: string;
+  lastPath: string;
+  timesheetPath: string;
+  archivePath: string;
+  outDir: string;
+  indexHtmlPath: string;
+}
+
+export function findProjectRoot(startDir = process.cwd()): string | null {
+  let currentDir = startDir;
+  const root = path.parse(currentDir).root;
+
+  while (currentDir !== root) {
+    const configPath = path.join(currentDir, "config.json");
+    if (fs.existsSync(configPath)) {
+      return currentDir;
+    }
+    currentDir = path.dirname(currentDir);
+  }
+
+  return null;
+}
+
+export function createProjectPaths(startDir = process.cwd()): ProjectPaths {
+  const moduleRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+  const projectRoot = findProjectRoot(startDir) ?? (fs.existsSync(path.join(moduleRoot, "config.json")) ? moduleRoot : process.cwd());
+  return {
+    projectRoot,
+    configPath: path.join(projectRoot, "config.json"),
+    lastPath: path.join(projectRoot, "data", "last.json"),
+    timesheetPath: path.join(projectRoot, "data", "timesheet.json"),
+    archivePath: path.join(projectRoot, "data", "archive.json"),
+    outDir: path.join(projectRoot, "out"),
+    indexHtmlPath: path.join(projectRoot, "index.html"),
+  };
+}

package/src/core/validators.ts

@@ -0,0 +1,168 @@
+import {
+  type ArchiveData,
+  type ArchivedEntry,
+  type ClientConfig,
+  type ClientHistory,
+  type Config,
+  type LastState,
+  type TimesheetData,
+  type TimesheetEntry,
+} from "../domain/types.js";
+
+function ensureObject(value: unknown, label: string): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function ensureString(value: unknown, label: string, fallback = ""): string {
+  if (value === undefined || value === null) {
+    return fallback;
+  }
+  if (typeof value !== "string") {
+    throw new Error(`${label} must be a string`);
+  }
+  return value;
+}
+
+function ensureNumber(value: unknown, label: string): number {
+  if (typeof value !== "number" || Number.isNaN(value)) {
+    throw new Error(`${label} must be a number`);
+  }
+  return value;
+}
+
+function ensureOptionalNumber(value: unknown, label: string, fallback: number): number {
+  if (value === undefined || value === null || value === "") {
+    return fallback;
+  }
+  if (typeof value === "string") {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed)) {
+      throw new Error(`${label} must be numeric`);
+    }
+    return parsed;
+  }
+  return ensureNumber(value, label);
+}
+
+export function validateClientConfig(value: unknown, indexLabel = "client"): ClientConfig {
+  const client = ensureObject(value, indexLabel);
+
+  return {
+    name: ensureString(client.name, `${indexLabel}.name`).trim(),
+    email: ensureString(client.email, `${indexLabel}.email`, "").trim(),
+    address: ensureString(client.address, `${indexLabel}.address`, "").trim(),
+    currency: ensureString(client.currency, `${indexLabel}.currency`, "USD") || "USD",
+    defaultRate: ensureOptionalNumber(client.defaultRate, `${indexLabel}.defaultRate`, 0),
+    payPeriodType: ensureString(client.payPeriodType, `${indexLabel}.payPeriodType`, "").trim(),
+  };
+}
+
+export function validateConfig(value: unknown): Config {
+  const obj = ensureObject(value, "config");
+  const clientsRaw = obj.client;
+
+  if (!Array.isArray(clientsRaw)) {
+    throw new Error("config.client must be an array");
+  }
+
+  const fromRaw = obj.from === undefined ? {} : ensureObject(obj.from, "config.from");
+
+  return {
+    client: clientsRaw.map((client, index) => validateClientConfig(client, `config.client[${index}]`)),
+    defaultDescription: ensureString(obj.defaultDescription, "config.defaultDescription", ""),
+    from: {
+      name: ensureString(fromRaw.name, "config.from.name", ""),
+      email: ensureString(fromRaw.email, "config.from.email", ""),
+      address: ensureString(fromRaw.address, "config.from.address", ""),
+    },
+    invoicePrefix: ensureString(obj.invoicePrefix, "config.invoicePrefix", "INV"),
+    note: ensureString(obj.note, "config.note", ""),
+  };
+}
+
+function validateClientHistory(value: unknown, label: string): ClientHistory {
+  const obj = ensureObject(value, label);
+  const seqByMonthRaw = obj.seqByMonth === undefined ? {} : ensureObject(obj.seqByMonth, `${label}.seqByMonth`);
+
+  const seqByMonth = Object.entries(seqByMonthRaw).reduce<Record<string, number>>((acc, [month, seq]) => {
+    acc[month] = ensureOptionalNumber(seq, `${label}.seqByMonth.${month}`, 0);
+    return acc;
+  }, {});
+
+  return {
+    lastHours: ensureOptionalNumber(obj.lastHours, `${label}.lastHours`, 160),
+    lastRate: ensureOptionalNumber(obj.lastRate, `${label}.lastRate`, 0),
+    seqByMonth,
+  };
+}
+
+export function validateLastState(value: unknown): LastState {
+  const obj = ensureObject(value, "last");
+  const clientsRaw = obj.clients === undefined ? {} : ensureObject(obj.clients, "last.clients");
+
+  const clients = Object.entries(clientsRaw).reduce<Record<string, ClientHistory>>((acc, [name, history]) => {
+    acc[name] = validateClientHistory(history, `last.clients.${name}`);
+    return acc;
+  }, {});
+
+  return { clients };
+}
+
+function validateTimesheetEntry(value: unknown, label: string): TimesheetEntry {
+  const obj = ensureObject(value, label);
+
+  return {
+    id: ensureOptionalNumber(obj.id, `${label}.id`, Date.now()),
+    client: ensureString(obj.client, `${label}.client`),
+    date: ensureString(obj.date, `${label}.date`),
+    hours: ensureOptionalNumber(obj.hours, `${label}.hours`, 0),
+    description: ensureString(obj.description, `${label}.description`, ""),
+    rate: ensureOptionalNumber(obj.rate, `${label}.rate`, 0),
+    amount: ensureOptionalNumber(obj.amount, `${label}.amount`, 0),
+    createdAt: ensureString(obj.createdAt, `${label}.createdAt`, ""),
+  };
+}
+
+export function validateTimesheetData(value: unknown): TimesheetData {
+  const obj = ensureObject(value, "timesheet");
+  const entriesRaw = obj.entries === undefined ? [] : obj.entries;
+
+  if (!Array.isArray(entriesRaw)) {
+    throw new Error("timesheet.entries must be an array");
+  }
+
+  return {
+    entries: entriesRaw.map((entry, index) => validateTimesheetEntry(entry, `timesheet.entries[${index}]`)),
+  };
+}
+
+function validateArchivedEntry(value: unknown, label: string): ArchivedEntry {
+  const entry = validateTimesheetEntry(value, label);
+  const obj = ensureObject(value, label);
+
+  return {
+    ...entry,
+    archivedAt: ensureString(obj.archivedAt, `${label}.archivedAt`),
+    archivedReason: ensureString(obj.archivedReason, `${label}.archivedReason`, "invoiced"),
+    invoiceNumber: ensureString(obj.invoiceNumber, `${label}.invoiceNumber`),
+    invoiceMonth: ensureString(obj.invoiceMonth, `${label}.invoiceMonth`),
+  };
+}
+
+export function validateArchiveData(value: unknown): ArchiveData {
+  const obj = ensureObject(value, "archive");
+  const archivedRaw = obj.archivedEntries === undefined ? [] : obj.archivedEntries;
+
+  if (!Array.isArray(archivedRaw)) {
+    throw new Error("archive.archivedEntries must be an array");
+  }
+
+  return {
+    archivedEntries: archivedRaw.map((entry, index) =>
+      validateArchivedEntry(entry, `archive.archivedEntries[${index}]`),
+    ),
+  };
+}