akm-cli 0.7.4 → 0.8.0-rc.3

package/dist/core/time.js

@@ -0,0 +1,51 @@
+/**
+ * Shared time and date utilities.
+ *
+ * Centralises parsing of user-facing `--since` values so that all consumers
+ * interpret the same set of formats (ISO-8601, epoch ms, plain date strings)
+ * consistently without private re-implementations drifting apart.
+ */
+import { UsageError } from "./errors";
+// ── Since-flag parsing ───────────────────────────────────────────────────────
+/**
+ * Parse a user-supplied `--since` value and return an ISO-8601 timestamp
+ * string (e.g. `"2026-01-15T10:30:00.000Z"`).
+ *
+ * Accepted input formats:
+ *   - ISO-8601 timestamp (preferred): `"2026-04-01T00:00:00Z"`
+ *   - Plain date: `"2026-04-01"` (interpreted as start-of-day UTC)
+ *   - Epoch milliseconds (pure digit string): `"1744329600000"`
+ *   - Any other value parseable by `new Date()`
+ *
+ * Callers that need a different wire format (e.g. SQLite `"YYYY-MM-DD HH:MM:SS"`)
+ * should convert the returned ISO string themselves.
+ *
+ * @throws {UsageError} when `since` is empty or cannot be parsed as a date.
+ */
+export function parseSinceToIso(since) {
+    const trimmed = since.trim();
+    if (!trimmed) {
+        throw new UsageError("--since cannot be empty.", "INVALID_FLAG_VALUE");
+    }
+    // Pure-digit input → epoch milliseconds
+    if (/^\d+$/.test(trimmed)) {
+        const ms = Number.parseInt(trimmed, 10);
+        const d = new Date(ms);
+        if (Number.isNaN(d.getTime())) {
+            throw new UsageError(`Invalid --since value: ${since}`, "INVALID_FLAG_VALUE");
+        }
+        return d.toISOString();
+    }
+    const parsed = new Date(trimmed);
+    if (Number.isNaN(parsed.getTime())) {
+        throw new UsageError(`Invalid --since value: ${since}. Expected ISO timestamp (e.g. 2026-04-01T00:00:00Z) or epoch ms.`, "INVALID_FLAG_VALUE");
+    }
+    return parsed.toISOString();
+}
+/**
+ * Convert an ISO-8601 timestamp string to the SQLite datetime format
+ * `"YYYY-MM-DD HH:MM:SS"` used by `datetime('now')`.
+ */
+export function isoToSqlite(iso) {
+    return iso.replace("T", " ").replace(/\.\d+Z$/, "");
+}

package/dist/core/warn.js

@@ -1,12 +1,19 @@
 /**
- * Module-level quiet/verbose flags for stderr warning gating.
+ * Module-level quiet/verbose flags and optional file sink for stderr output.
  *
  * `quiet` is controlled by the CLI `--quiet`/`-q` flag.
  * `verbose` is controlled by the CLI `--verbose` flag, with `AKM_VERBOSE`
  * (env var) winning regardless: env > flag > default (false).
+ *
+ * Call `setLogFile(path)` to tee all warn/error/info output to a file in
+ * addition to stderr. The file sink is written even when `--quiet` suppresses
+ * console output, so logs remain available for post-run inspection.
  */
+import fs from "node:fs";
+import path from "node:path";
 let quiet = false;
 let verbose = false;
+let logFilePath;
 export function setQuiet(value) {
     quiet = value;
 }
@@ -51,15 +58,66 @@ export function isVerbose() {
         return false;
     return verbose;
 }
+/**
+ * Direct all warn/error/info output to `filePath` in addition to stderr.
+ * The directory is created if it does not exist. Pass `undefined` to disable.
+ * The file is written even when `--quiet` suppresses console output.
+ */
+export function setLogFile(filePath) {
+    logFilePath = filePath;
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+export function clearLogFile() {
+    logFilePath = undefined;
+}
+export function getLogFile() {
+    return logFilePath;
+}
+function appendToLogFile(level, args) {
+    if (!logFilePath)
+        return;
+    const ts = new Date().toISOString();
+    const msg = args.map((a) => (typeof a === "string" ? a : JSON.stringify(a))).join(" ");
+    try {
+        fs.appendFileSync(logFilePath, `[${ts}] [${level}] ${msg}\n`);
+    }
+    catch {
+        // Never throw from a logging function — log failures are silent.
+    }
+}
+/**
+ * Emit an info/progress line to stderr unless --quiet is active.
+ * Always written to the log file if one is active.
+ * Use for progress counters and status lines (replaces console.error used for progress).
+ */
+export function info(...args) {
+    appendToLogFile("INFO", args);
+    if (!quiet) {
+        console.warn(...args);
+    }
+}
 /**
  * Emit a warning to stderr unless --quiet is active.
+ * Always written to the log file if one is active.
  * Drop-in replacement for console.warn() across the codebase.
  */
 export function warn(...args) {
+    appendToLogFile("WARN", args);
     if (!quiet) {
         console.warn(...args);
     }
 }
+/**
+ * Emit an error to stderr unless --quiet is active.
+ * Always written to the log file if one is active.
+ * Drop-in replacement for console.error() used for diagnostic failures.
+ */
+export function error(...args) {
+    appendToLogFile("ERROR", args);
+    if (!quiet) {
+        console.error(...args);
+    }
+}
 /**
  * Emit a warning only when verbose output is requested. Use for noisy
  * per-item diagnostics that should be replaced by a one-line summary at