akm-cli 0.7.4 → 0.8.0-rc.10

package/dist/core/text-truncation.js

@@ -0,0 +1,107 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Shared text-truncation heuristics used by `distill` and `consolidate`.
+ *
+ * Both commands need to recognise when an LLM-produced description string was
+ * sliced mid-sentence (typically the model hit its output budget). The two
+ * implementations historically maintained overlapping-but-not-identical
+ * vocabularies of hanging-connector words, which was a maintenance trap.
+ *
+ * This module is the single source of truth. `distill` continues to layer its
+ * own section-heading regex on top (those patterns are distill-specific and
+ * intentionally stay local to that module).
+ */
+/**
+ * Words that, when ending a sentence, suggest the description was truncated
+ * mid-sentence. Prepositions, conjunctions, articles, and auxiliary verbs that
+ * almost always have *something* following them in well-formed prose.
+ *
+ * This is the UNION of the two prior vocabularies used by `distill` and
+ * `consolidate` — a superset of both, so behaviour is at least as strict as
+ * either previous check.
+ *
+ * Stored lowercased; callers must lower-case the last word before lookup.
+ */
+export const TRUNCATION_TRAILING_WORDS = new Set([
+    "a",
+    "after",
+    "an",
+    "and",
+    "are",
+    "as",
+    "at",
+    "be",
+    "been",
+    "before",
+    "being",
+    "but",
+    "by",
+    "can",
+    "could",
+    "did",
+    "do",
+    "does",
+    "for",
+    "from",
+    "had",
+    "has",
+    "have",
+    "if",
+    "in",
+    "into",
+    "is",
+    "may",
+    "might",
+    "must",
+    "of",
+    "on",
+    "onto",
+    "or",
+    "per",
+    "shall",
+    "should",
+    "so",
+    "than",
+    "that",
+    "the",
+    "to",
+    "upon",
+    "via",
+    "was",
+    "were",
+    "when",
+    "which",
+    "while",
+    "will",
+    "with",
+    "would",
+]);
+/**
+ * Returns a reason string when `description` looks truncated mid-sentence;
+ * returns `null` if the description appears complete.
+ *
+ * Heuristics:
+ *   - Trailing `,`, `;`, `:`, or `+` (operator-style cutoff like `max-width:100% +`)
+ *   - Trailing ellipsis (`...` or `…`)
+ *   - Last word matches {@link TRUNCATION_TRAILING_WORDS}
+ *
+ * Does NOT detect section-heading fragments — that check is distill-specific
+ * and lives in `src/commands/distill.ts` (`HEADING_FRAGMENT_PATTERNS`).
+ */
+export function detectTruncatedDescription(description) {
+    const trimmed = description.trim();
+    if (trimmed.length === 0)
+        return null; // empty handled elsewhere
+    if (/[,;:+]$/.test(trimmed))
+        return "ends with trailing punctuation/operator";
+    if (/\.{3,}$/.test(trimmed) || /…$/.test(trimmed))
+        return "ends with ellipsis";
+    const lastWord = trimmed.split(/\s+/).pop() ?? "";
+    const normalized = lastWord.toLowerCase();
+    if (TRUNCATION_TRAILING_WORDS.has(normalized)) {
+        return `ends with hanging connector "${lastWord}"`;
+    }
+    return null;
+}

package/dist/core/time.js

@@ -0,0 +1,54 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * 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/tty.js

@@ -0,0 +1,59 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Terminal-glyph and color gating helpers (#486).
+ *
+ * Honor the [NO_COLOR](https://no-color.org/) convention — when NO_COLOR is
+ * present in the environment (with any value, including empty), the CLI
+ * suppresses both ANSI color codes AND decorative emoji glyphs. Emoji often
+ * render as garbage in non-Unicode terminals or get logged as literal bytes
+ * when output is piped to text aggregators, so we treat them as a subset of
+ * "color" decoration.
+ *
+ * Detection is also automatic on non-TTY stderr (output piped or redirected
+ * to a file), where decorative glyphs add nothing.
+ */
+/**
+ * Returns true when decorative glyphs and color codes should be emitted.
+ * False when NO_COLOR is set or stderr is not a TTY (unless FORCE_COLOR
+ * overrides per the de-facto Node convention).
+ */
+export function shouldDecorate() {
+    if (process.env.NO_COLOR !== undefined)
+        return false;
+    if (process.env.FORCE_COLOR !== undefined && process.env.FORCE_COLOR !== "" && process.env.FORCE_COLOR !== "0") {
+        return true;
+    }
+    return process.stderr.isTTY === true;
+}
+// Map known decorative emoji to plain ASCII fallbacks. Anything not listed
+// is still removed by the catch-all sweep below when decoration is off.
+const EMOJI_FALLBACKS = [
+    [/\u{1F44B}\s*/gu, ""], // wave (with trailing space)
+    [/✓/g, "[ok]"],
+    [/✗/g, "[x]"],
+    [/✘/g, "[x]"],
+    [/⚠️?/g, "[!]"],
+    [/\u{1F4DA}\s*/gu, ""], // books
+];
+/**
+ * If decoration is disabled, replace known emoji with ASCII fallbacks and
+ * strip any remaining pictograph code points. If decoration is enabled,
+ * return the input unchanged.
+ */
+export function plainize(text) {
+    if (shouldDecorate())
+        return text;
+    let out = text;
+    for (const [pattern, repl] of EMOJI_FALLBACKS) {
+        out = out.replace(pattern, repl);
+    }
+    // Catch-all for unmapped pictographs. Future-proof when new emoji are added
+    // to call sites without updating the explicit map.
+    out = out.replace(/[\u{1F300}-\u{1FAFF}]/gu, "");
+    // Collapse runs of whitespace introduced by emoji removal, but preserve
+    // intentional leading indentation. Only collapses interior runs.
+    out = out.replace(/(\S)[ \t]{2,}/g, "$1 ");
+    return out;
+}

package/dist/core/warn.js

@@ -1,12 +1,22 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
- * 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 +61,68 @@ 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 (e) {
+        // Log file write failed — emit directly to stderr so the message is not lost.
+        process.stderr.write(`[akm:warn] log-file write failed (${logFilePath}): ${e}\n`);
+        process.stderr.write(`[${ts}] [${level}] ${msg}\n`);
+    }
+}
+/**
+ * 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

package/dist/core/write-source.js

@@ -1,3 +1,6 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
  * write-source — the only place in the codebase that branches on `source.kind`.
  *