tallyd 0.0.0-stage → 0.1.0

package/dist/cli/args.js

@@ -0,0 +1,147 @@
+/**
+ * Argument parsing, written rather than installed.
+ *
+ * A dependency would do this, and for a tool this size the dependency is the
+ * larger risk: everything a ledger CLI needs — long flags, `--flag=value` and
+ * `--flag value`, short aliases, repeated values, `--` to stop parsing — is a
+ * page of code that can be tested against the awkward cases instead of
+ * trusted.
+ *
+ * The awkward cases are the point. `--account -1100` should be a value, not a
+ * missing flag followed by a stray negative number. `--as-at=2026-08-31` and
+ * `--as-at 2026-08-31` must mean the same thing. An unknown flag must be an
+ * error rather than silently ignored, because a typo in `--as-at` that reports
+ * the wrong period without complaining is exactly the failure a report tool
+ * cannot afford.
+ */
+export class ArgumentError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ArgumentError";
+    }
+}
+function specFor(specs, name) {
+    const direct = specs[name];
+    if (direct !== undefined)
+        return { key: name, spec: direct };
+    if (name.length === 1) {
+        for (const [key, spec] of Object.entries(specs)) {
+            if (spec.short === name)
+                return { key, spec };
+        }
+    }
+    throw new ArgumentError(`Unknown option: ${name.length === 1 ? "-" : "--"}${name}`);
+}
+/**
+ * Parse `argv` against a flag table.
+ *
+ * Everything after a bare `--` is positional, however it looks. Anything not
+ * recognised is an error rather than a shrug.
+ */
+export function parseArgs(argv, specs) {
+    const positional = [];
+    const flags = {};
+    let index = 0;
+    let literal = false;
+    const setValue = (key, spec, value) => {
+        if (spec.kind === "list") {
+            const existing = flags[key];
+            if (Array.isArray(existing))
+                existing.push(value);
+            else
+                flags[key] = [value];
+            return;
+        }
+        flags[key] = value;
+    };
+    while (index < argv.length) {
+        const token = argv[index];
+        index++;
+        if (literal) {
+            positional.push(token);
+            continue;
+        }
+        if (token === "--") {
+            literal = true;
+            continue;
+        }
+        const isLong = token.startsWith("--") && token.length > 2;
+        const isShort = !isLong && token.startsWith("-") && token.length > 1 && token !== "-";
+        if (!isLong && !isShort) {
+            positional.push(token);
+            continue;
+        }
+        const body = isLong ? token.slice(2) : token.slice(1);
+        const equals = body.indexOf("=");
+        const name = equals === -1 ? body : body.slice(0, equals);
+        const inline = equals === -1 ? null : body.slice(equals + 1);
+        const { key, spec } = specFor(specs, name);
+        if (spec.kind === "boolean") {
+            if (inline !== null) {
+                if (inline !== "true" && inline !== "false") {
+                    throw new ArgumentError(`--${key} is a switch and takes no value`);
+                }
+                flags[key] = inline === "true";
+                continue;
+            }
+            flags[key] = true;
+            continue;
+        }
+        if (inline !== null) {
+            setValue(key, spec, inline);
+            continue;
+        }
+        // A value is whatever comes next, even if it starts with a dash: an
+        // account code or a negative amount is a legitimate value.
+        const next = argv[index];
+        if (next === undefined) {
+            throw new ArgumentError(`--${key} needs a value`);
+        }
+        index++;
+        setValue(key, spec, next);
+    }
+    return Object.freeze({ positional: Object.freeze(positional), flags: Object.freeze(flags) });
+}
+export function stringFlag(parsed, name) {
+    const value = parsed.flags[name];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string") {
+        throw new ArgumentError(`--${name} takes a single value`);
+    }
+    return value;
+}
+export function requiredFlag(parsed, name) {
+    const value = stringFlag(parsed, name);
+    if (value === undefined)
+        throw new ArgumentError(`--${name} is required`);
+    return value;
+}
+export function booleanFlag(parsed, name) {
+    return parsed.flags[name] === true;
+}
+export function listFlag(parsed, name) {
+    const value = parsed.flags[name];
+    if (value === undefined)
+        return [];
+    if (Array.isArray(value))
+        return value;
+    if (typeof value === "string")
+        return [value];
+    throw new ArgumentError(`--${name} takes values`);
+}
+/** Render a flag table as aligned help text. */
+export function renderFlags(specs, indent = "  ") {
+    const entries = Object.entries(specs);
+    if (entries.length === 0)
+        return "";
+    const left = entries.map(([name, spec]) => {
+        const short = spec.short === undefined ? "    " : `-${spec.short}, `;
+        const placeholder = spec.kind === "boolean" ? "" : ` <${spec.placeholder ?? (spec.kind === "list" ? "value..." : "value")}>`;
+        return `${short}--${name}${placeholder}`;
+    });
+    const width = Math.max(...left.map((text) => text.length));
+    return entries
+        .map(([, spec], i) => `${indent}${left[i].padEnd(width + 2)}${spec.describe}`)
+        .join("\n");
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+export { type FlagKind, type FlagSpec, type FlagSpecs, type ParsedArgs, ArgumentError, parseArgs, stringFlag, requiredFlag, booleanFlag, listFlag, renderFlags, } from "./args.js";
+export { type CliEnvironment, type CliResult, run } from "./run.js";

package/dist/cli/index.js

@@ -0,0 +1,2 @@
+export { ArgumentError, parseArgs, stringFlag, requiredFlag, booleanFlag, listFlag, renderFlags, } from "./args.js";
+export { run } from "./run.js";

package/dist/cli/main.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * The executable. Everything interesting is in `run`, which is a pure
+ * function; this file exists to connect it to the process.
+ */
+export {};

package/dist/cli/main.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+/**
+ * The executable. Everything interesting is in `run`, which is a pure
+ * function; this file exists to connect it to the process.
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { run } from "./run.js";
+import { date } from "../ledger/date.js";
+function today() {
+    // The only place in the codebase that reads the clock, kept to one line so
+    // it is obvious where non-determinism enters.
+    const now = new Date();
+    const iso = `${now.getUTCFullYear()}-${String(now.getUTCMonth() + 1).padStart(2, "0")}-${String(now.getUTCDate()).padStart(2, "0")}`;
+    return date(iso);
+}
+const result = run(process.argv.slice(2), {
+    readFile: (path) => readFileSync(path, "utf8"),
+    writeFile: (path, contents) => writeFileSync(path, contents, "utf8"),
+    today,
+});
+if (result.stdout !== "")
+    process.stdout.write(`${result.stdout}\n`);
+if (result.stderr !== "")
+    process.stderr.write(result.stderr);
+process.exit(result.code);

package/dist/cli/run.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The commands.
+ *
+ * `run` is a pure function of its arguments and an environment: it takes the
+ * argv, a filesystem reader and a clock, and returns text plus an exit code.
+ * Nothing here touches `process` or `console`, which is what makes the whole
+ * CLI testable end to end without spawning anything.
+ *
+ * Exit codes carry meaning. Zero is success; 1 is a usage or input problem;
+ * and 2 is reserved for work that ran to completion and came out wrong — a
+ * reconciliation that does not balance, a trial balance that does not agree.
+ * A CI job that treats an unbalanced reconciliation as a pass is worse than no
+ * CI job at all.
+ */
+import type { CalendarDate } from "../ledger/date.js";
+export interface CliEnvironment {
+    /** Read a file as UTF-8, or throw. */
+    readonly readFile: (path: string) => string;
+    /** Today, for commands that default their as-at date. */
+    readonly today: () => CalendarDate;
+    /**
+     * Write a file, for the commands that produce an artefact. Absent in
+     * read-only environments, in which case those commands say so rather than
+     * failing halfway through.
+     */
+    readonly writeFile?: (path: string, contents: string) => void;
+}
+export interface CliResult {
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly code: number;
+}
+/** Run one invocation. Never throws; every failure becomes an exit code. */
+export declare function run(argv: readonly string[], environment: CliEnvironment): CliResult;