@prestyj/editor 0.7.1

package/dist/core/keyword-captions.js

@@ -0,0 +1,285 @@
+/**
+ * Keyword-highlighted captions — the CapCut "active word" style that
+ * defines viral short-form aesthetics in 2025-2026.
+ *
+ * Plain word-by-word burned captions show every word in the same
+ * style. Keyword highlighting picks the 1-2 most content-bearing words
+ * per phrase and renders them in a stronger color / scale, so the eye
+ * locks onto the meaning even when the viewer is half-scrolling.
+ *
+ * No POS tagger needed — a small heuristic gets us 90% of the way:
+ *   - Numbers and ALL-CAPS tokens are always keywords.
+ *   - Words ≥ minKeywordLen and NOT in the stoplist are keywords.
+ *   - Words in the stoplist (articles / prepositions / fillers) are
+ *     never keywords.
+ *   - We cap to N keywords per phrase to keep emphasis meaningful.
+ *
+ * Output: AssCue list with two styles ("Default" + "Keyword"). The
+ * caller passes them straight into buildAss(); ffmpeg's `subtitles`
+ * filter renders the result.
+ */
+/**
+ * The function-words / discourse markers we strip from keyword
+ * candidates. Lowercase, no punctuation.
+ */
+export const DEFAULT_STOPLIST = [
+    // articles
+    "a",
+    "an",
+    "the",
+    // pronouns
+    "i",
+    "me",
+    "my",
+    "mine",
+    "you",
+    "your",
+    "yours",
+    "he",
+    "him",
+    "his",
+    "she",
+    "her",
+    "hers",
+    "it",
+    "its",
+    "we",
+    "us",
+    "our",
+    "ours",
+    "they",
+    "them",
+    "their",
+    "theirs",
+    "this",
+    "that",
+    "these",
+    "those",
+    // common verbs / aux
+    "is",
+    "are",
+    "was",
+    "were",
+    "be",
+    "been",
+    "being",
+    "am",
+    "do",
+    "does",
+    "did",
+    "doing",
+    "have",
+    "has",
+    "had",
+    "having",
+    "will",
+    "would",
+    "shall",
+    "should",
+    "may",
+    "might",
+    "must",
+    "can",
+    "could",
+    // prepositions / conjunctions
+    "of",
+    "in",
+    "on",
+    "at",
+    "by",
+    "to",
+    "for",
+    "with",
+    "from",
+    "as",
+    "into",
+    "onto",
+    "out",
+    "off",
+    "up",
+    "down",
+    "over",
+    "under",
+    "and",
+    "or",
+    "but",
+    "so",
+    "if",
+    "then",
+    "than",
+    "because",
+    "while",
+    "when",
+    "where",
+    "who",
+    "which",
+    "what",
+    "why",
+    "how",
+    "not",
+    "no",
+    "yes",
+    "okay",
+    "ok",
+    "well",
+    "just",
+    "really",
+    "very",
+    "much",
+    "more",
+    "most",
+    "some",
+    "any",
+    "all",
+    "each",
+    "every",
+    // common fillers (also covered by cut_filler_words but we don't
+    // assume those are gone)
+    "um",
+    "uh",
+    "uhm",
+    "like",
+    "you know",
+    "i mean",
+];
+/**
+ * Build the cues + styles for a keyword-highlighted caption track.
+ *
+ * Returns:
+ *   - styles: pass directly into AssOptions.styles (always 2 styles).
+ *   - cues:   one cue per N words OR per gap boundary. Cues with a
+ *             keyword embed the keyword via an inline `{\rKeyword}` ...
+ *             `{\rDefault}` reset so a single cue can mix both styles.
+ *
+ * The caller controls font/size/colors by overriding fields on the
+ * returned styles before passing them to buildAss.
+ */
+export function buildKeywordCaptions(words, opts = {}) {
+    const groupSize = Math.max(1, opts.groupSize ?? 3);
+    const gapSec = Math.max(0, opts.gapSec ?? 0.4);
+    const minLen = Math.max(1, opts.minKeywordLen ?? 5);
+    const maxKw = Math.max(0, opts.maxKeywordsPerCue ?? 1);
+    const endPad = Math.max(0, opts.endPaddingSec ?? 0.08);
+    const stoplist = new Set((opts.stoplist ?? DEFAULT_STOPLIST).map((s) => s.toLowerCase().trim()));
+    const styles = defaultKeywordStyles();
+    const cues = [];
+    if (words.length === 0)
+        return { cues, styles };
+    let cueWords = [];
+    const flush = () => {
+        if (cueWords.length === 0)
+            return;
+        cues.push(buildCue(cueWords, stoplist, minLen, maxKw, endPad));
+        cueWords = [];
+    };
+    for (let i = 0; i < words.length; i++) {
+        const w = words[i];
+        if (cueWords.length === 0) {
+            cueWords.push(w);
+            continue;
+        }
+        const prev = cueWords[cueWords.length - 1];
+        const gap = w.start - prev.end;
+        if (gap >= gapSec || cueWords.length >= groupSize) {
+            flush();
+        }
+        cueWords.push(w);
+    }
+    flush();
+    return { cues, styles };
+}
+/**
+ * Decide whether a single token (already normalized) is a keyword.
+ * Exported for unit testing.
+ */
+export function isKeywordToken(raw, stoplist, minLen) {
+    const stripped = raw.replace(/[^a-zA-Z0-9']/g, "");
+    if (stripped.length === 0)
+        return false;
+    // Numbers always count.
+    if (/^\d+([.,]\d+)?$/.test(stripped))
+        return true;
+    // Pure ALL-CAPS at length >=2 (avoids "I").
+    if (stripped.length >= 2 && stripped === stripped.toUpperCase() && /[A-Z]/.test(stripped)) {
+        return true;
+    }
+    const lower = stripped.toLowerCase();
+    if (stoplist.has(lower))
+        return false;
+    // Multi-word stoplist phrases like "you know" — token might be either
+    // half. We only check single-token entries here (multi-word stops are
+    // applied at the cut_filler_words layer).
+    if (stripped.length < minLen)
+        return false;
+    return true;
+}
+// ── Internals ───────────────────────────────────────────────
+function buildCue(cueWords, stoplist, minLen, maxKw, endPad) {
+    // Score each word: 0 = function word, 1 = candidate keyword.
+    // Sort by length (longer = more salient), break ties by source order.
+    const candidates = cueWords
+        .map((w, idx) => ({ idx, isKw: isKeywordToken(w.text, stoplist, minLen) }))
+        .filter((c) => c.isKw);
+    // Take up to maxKw, preferring longer words.
+    const chosen = new Set([...candidates]
+        .sort((a, b) => {
+        const la = cueWords[a.idx].text.length;
+        const lb = cueWords[b.idx].text.length;
+        if (la !== lb)
+            return lb - la;
+        return a.idx - b.idx;
+    })
+        .slice(0, maxKw)
+        .map((c) => c.idx));
+    // Build the ASS dialogue text. ASS supports inline style overrides via
+    // {\rStyleName} which switches to that style; {\r} resets to default.
+    const parts = [];
+    cueWords.forEach((w, idx) => {
+        const text = w.text.trim();
+        if (chosen.has(idx)) {
+            parts.push(`{\\rKeyword}${text}{\\r}`);
+        }
+        else {
+            parts.push(text);
+        }
+    });
+    return {
+        start: cueWords[0].start,
+        end: cueWords[cueWords.length - 1].end + endPad,
+        text: parts.join(" "),
+    };
+}
+/**
+ * Sensible defaults that look right for vertical / 9:16 shorts:
+ *   - Default style: large white sans-serif with thick outline.
+ *   - Keyword style: punchy yellow, slightly larger, same font.
+ *
+ * Override via the returned array before passing into buildAss().
+ */
+export function defaultKeywordStyles() {
+    return [
+        {
+            name: "Default",
+            fontName: "Arial",
+            fontSize: 84,
+            primaryColor: "FFFFFF",
+            outlineColor: "000000",
+            outline: 4,
+            bold: true,
+            alignment: 2,
+            marginV: 220,
+        },
+        {
+            name: "Keyword",
+            fontName: "Arial",
+            fontSize: 96,
+            primaryColor: "FFEA00",
+            outlineColor: "000000",
+            outline: 5,
+            bold: true,
+            alignment: 2,
+            marginV: 220,
+        },
+    ];
+}
+//# sourceMappingURL=keyword-captions.js.map

package/dist/core/keyword-captions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyword-captions.js","sourceRoot":"","sources":["../../src/core/keyword-captions.ts"],"names":[],"mappings":"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"}

package/dist/core/keyword-captions.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=keyword-captions.test.d.ts.map

package/dist/core/keyword-captions.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyword-captions.test.d.ts","sourceRoot":"","sources":["../../src/core/keyword-captions.test.ts"],"names":[],"mappings":""}

package/dist/core/keyword-captions.test.js

@@ -0,0 +1,90 @@
+import { describe, expect, it } from "vitest";
+import { buildAss } from "./ass.js";
+import { buildKeywordCaptions, DEFAULT_STOPLIST, isKeywordToken } from "./keyword-captions.js";
+const STOP = new Set(DEFAULT_STOPLIST.map((s) => s.toLowerCase()));
+function w(text, start, end) {
+    return { start, end, text };
+}
+describe("isKeywordToken", () => {
+    it("rejects stoplist function words", () => {
+        expect(isKeywordToken("the", STOP, 5)).toBe(false);
+        expect(isKeywordToken("This", STOP, 5)).toBe(false);
+        expect(isKeywordToken("um", STOP, 5)).toBe(false);
+    });
+    it("accepts long content words", () => {
+        expect(isKeywordToken("retention", STOP, 5)).toBe(true);
+        expect(isKeywordToken("creators", STOP, 5)).toBe(true);
+    });
+    it("rejects words shorter than minLen", () => {
+        expect(isKeywordToken("dog", STOP, 5)).toBe(false);
+    });
+    it("accepts numbers regardless of length / stoplist", () => {
+        expect(isKeywordToken("12", STOP, 5)).toBe(true);
+        expect(isKeywordToken("3.14", STOP, 5)).toBe(true);
+        expect(isKeywordToken("80%", STOP, 5)).toBe(true);
+    });
+    it("accepts ALL-CAPS tokens (>= 2 chars) regardless of length", () => {
+        expect(isKeywordToken("AI", STOP, 5)).toBe(true);
+        expect(isKeywordToken("CEO", STOP, 5)).toBe(true);
+        // single capital letter does NOT count (avoids highlighting "I").
+        expect(isKeywordToken("I", STOP, 5)).toBe(false);
+    });
+    it("strips trailing punctuation when matching", () => {
+        expect(isKeywordToken("retention,", STOP, 5)).toBe(true);
+        expect(isKeywordToken("the.", STOP, 5)).toBe(false);
+    });
+});
+describe("buildKeywordCaptions", () => {
+    it("returns empty cues for empty input", () => {
+        const r = buildKeywordCaptions([]);
+        expect(r.cues).toEqual([]);
+        expect(r.styles.length).toBeGreaterThanOrEqual(2);
+    });
+    it("groups words into cues of groupSize", () => {
+        const words = Array.from({ length: 6 }, (_, i) => w(`word${i}`, i * 0.3, i * 0.3 + 0.25));
+        const r = buildKeywordCaptions(words, { groupSize: 2, gapSec: 5 });
+        expect(r.cues).toHaveLength(3);
+    });
+    it("breaks cues on a gap >= gapSec even mid-group", () => {
+        const words = [w("hello", 0, 0.3), w("world", 0.5, 0.8), w("again", 2.0, 2.3)];
+        const r = buildKeywordCaptions(words, { groupSize: 5, gapSec: 0.5 });
+        // gap between word2 and word3 is 1.2s — forces a new cue.
+        expect(r.cues).toHaveLength(2);
+    });
+    it("emits two styles named Default and Keyword", () => {
+        const r = buildKeywordCaptions([w("retention", 0, 0.3)]);
+        const names = r.styles.map((s) => s.name);
+        expect(names).toContain("Default");
+        expect(names).toContain("Keyword");
+    });
+    it("wraps the longest content word with {\\rKeyword} ... {\\r}", () => {
+        const words = [w("the", 0, 0.2), w("retention", 0.25, 0.65), w("graph", 0.7, 0.95)];
+        const r = buildKeywordCaptions(words, { groupSize: 3, maxKeywordsPerCue: 1 });
+        expect(r.cues[0].text).toContain("{\\rKeyword}retention{\\r}");
+        expect(r.cues[0].text).not.toContain("{\\rKeyword}the");
+    });
+    it("respects maxKeywordsPerCue=2 — can highlight two words", () => {
+        const words = [w("retention", 0, 0.4), w("graph", 0.5, 0.8), w("creators", 0.85, 1.3)];
+        const r = buildKeywordCaptions(words, { groupSize: 3, maxKeywordsPerCue: 2 });
+        const text = r.cues[0].text;
+        expect((text.match(/\{\\rKeyword\}/g) ?? []).length).toBe(2);
+    });
+    it("respects maxKeywordsPerCue=0 — no highlighting", () => {
+        const words = [w("retention", 0, 0.4), w("graph", 0.5, 0.8)];
+        const r = buildKeywordCaptions(words, { groupSize: 3, maxKeywordsPerCue: 0 });
+        expect(r.cues[0].text).not.toContain("{\\rKeyword}");
+    });
+    it("pads cue end past the last word", () => {
+        const r = buildKeywordCaptions([w("hello", 0, 0.3)], { endPaddingSec: 0.2 });
+        expect(r.cues[0].end).toBeCloseTo(0.5, 3);
+    });
+    it("output cues are accepted by buildAss without errors", () => {
+        const words = [w("the", 0, 0.2), w("creator", 0.25, 0.7), w("retention", 0.75, 1.2)];
+        const r = buildKeywordCaptions(words);
+        const ass = buildAss({ styles: r.styles, cues: r.cues, playResX: 1080, playResY: 1920 });
+        expect(ass).toContain("[V4+ Styles]");
+        expect(ass).toContain("Style: Keyword");
+        expect(ass).toContain("retention");
+    });
+});
+//# sourceMappingURL=keyword-captions.test.js.map

package/dist/core/keyword-captions.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyword-captions.test.js","sourceRoot":"","sources":["../../src/core/keyword-captions.test.ts"],"names":[],"mappings":"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"}

package/dist/core/logger.d.ts

@@ -0,0 +1,32 @@
+type LogLevel = "I" | "W" | "E";
+/** Default path: `~/.ezcoder/ezeditor.log`. */
+export declare function defaultLogPath(): string;
+/**
+ * Initialize logger. Idempotent. Writes a session HEADER line with the
+ * fields that don't change across the run, so per-line overhead stays low.
+ */
+export declare function initLogger(filePath?: string, meta?: {
+    version?: string;
+    provider?: string;
+    model?: string;
+    host?: string;
+}): void;
+/** Session ID — useful for filtering one run out of an interleaved log. */
+export declare function getSessionId(): string;
+/** Hot-path skip flag for callers that want to avoid building log payloads. */
+export declare function isLoggerActive(): boolean;
+/**
+ * Write a log line. Format: `HH:MM:SS.mmm L cat msg k=v k=v`.
+ *
+ * Values that contain spaces or `=` are JSON-quoted; bare otherwise. Long
+ * fields are truncated at MAX_FIELD_CHARS with `…(+N)` so the LLM sees the
+ * prefix plus a count of elided chars (rather than a silent cliff).
+ */
+export declare function log(level: LogLevel, category: string, message: string, data?: Record<string, unknown>): void;
+export declare const logInfo: (cat: string, msg: string, data?: Record<string, unknown>) => void;
+export declare const logWarn: (cat: string, msg: string, data?: Record<string, unknown>) => void;
+export declare const logError: (cat: string, msg: string, data?: Record<string, unknown>) => void;
+/** Close the log fd. Safe to call multiple times. */
+export declare function closeLogger(): void;
+export {};
+//# sourceMappingURL=logger.d.ts.map

package/dist/core/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/core/logger.ts"],"names":[],"mappings":"AAoCA,KAAK,QAAQ,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAQhC,+CAA+C;AAC/C,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AA4BD;;;GAGG;AACH,wBAAgB,UAAU,CACxB,QAAQ,GAAE,MAAyB,EACnC,IAAI,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5E,IAAI,CA8BN;AAED,2EAA2E;AAC3E,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,+EAA+E;AAC/E,wBAAgB,cAAc,IAAI,OAAO,CAExC;AAED;;;;;;GAMG;AACH,wBAAgB,GAAG,CACjB,KAAK,EAAE,QAAQ,EACf,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,IAAI,CAeN;AA0BD,eAAO,MAAM,OAAO,GAAI,KAAK,MAAM,EAAE,KAAK,MAAM,EAAE,OAAO,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,SACtD,CAAC;AAC3B,eAAO,MAAM,OAAO,GAAI,KAAK,MAAM,EAAE,KAAK,MAAM,EAAE,OAAO,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,SACtD,CAAC;AAC3B,eAAO,MAAM,QAAQ,GAAI,KAAK,MAAM,EAAE,KAAK,MAAM,EAAE,OAAO,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,SACvD,CAAC;AAE3B,qDAAqD;AACrD,wBAAgB,WAAW,IAAI,IAAI,CASlC"}

package/dist/core/logger.js

@@ -0,0 +1,188 @@
+/**
+ * ezeditor debug logger — optimized for LLM consumption.
+ *
+ * Writes to `~/.ezcoder/ezeditor.log`. Append mode across sessions, rotated at
+ * MAX_BYTES, one generation kept (`ezeditor.log.1`).
+ *
+ * Format choices (every byte fed to an LLM matters):
+ *   - Per-session HEADER carries the rarely-changing fields (date, sid,
+ *     version, provider, model, pid, platform). Lines below reference them
+ *     implicitly so we don't repeat ~80 bytes on every line.
+ *   - Each line: `HH:MM:SS.mmm L cat msg k=v k=v`
+ *       L  — single-letter level (I/W/E). Saves 3-4 bytes/line vs. INFO/WARN/ERROR.
+ *       cat — short stable category (tool, bridge, bridge.call, host, …).
+ *       msg — short imperative phrase, no decorative arrows.
+ *   - Field values JSON-encoded only when they need quoting; bare otherwise.
+ *   - Args/results truncated at MAX_FIELD_CHARS with `…(+N)` overflow marker
+ *     so the LLM sees the prefix + how much was elided.
+ *
+ * Categories:
+ *   startup       CLI launch line + capability probe result
+ *   bridge        Resolve Python bridge spawn/handshake/exit
+ *   bridge.call   Per-method round trips (one line per call: name + dur + ok/err)
+ *   tool          Agent tool calls (one line per call: name + dur + args + result)
+ *   host          Lazy host detection transitions
+ *   shutdown      Clean exit
+ *   fatal         Unhandled errors
+ *
+ * Filter a single run: `grep " sid=<id>" ~/.ezcoder/ezeditor.log` once you've
+ * read the header. Multi-run greps key off the category column.
+ */
+import fs from "node:fs";
+import { mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { randomBytes } from "node:crypto";
+const MAX_BYTES = 10 * 1024 * 1024; // 10 MB
+const MAX_FIELD_CHARS = 200; // Per k=v value cap. Args/results truncated above this.
+let fd = null;
+let sessionId = "";
+/** Default path: `~/.ezcoder/ezeditor.log`. */
+export function defaultLogPath() {
+    return join(homedir(), ".ezcoder", "ezeditor.log");
+}
+function rotateIfNeeded(filePath) {
+    try {
+        const st = fs.statSync(filePath);
+        if (st.size < MAX_BYTES)
+            return;
+        const rotated = `${filePath}.1`;
+        try {
+            fs.unlinkSync(rotated);
+        }
+        catch {
+            // No prior rotation
+        }
+        fs.renameSync(filePath, rotated);
+    }
+    catch {
+        // Log file doesn't exist yet
+    }
+}
+/** Pad to 2/3 chars with leading zeros for stable column widths. */
+function pad(n, w) {
+    return String(n).padStart(w, "0");
+}
+function timestamp() {
+    const d = new Date();
+    return `${pad(d.getHours(), 2)}:${pad(d.getMinutes(), 2)}:${pad(d.getSeconds(), 2)}.${pad(d.getMilliseconds(), 3)}`;
+}
+/**
+ * Initialize logger. Idempotent. Writes a session HEADER line with the
+ * fields that don't change across the run, so per-line overhead stays low.
+ */
+export function initLogger(filePath = defaultLogPath(), meta) {
+    if (fd !== null)
+        return;
+    try {
+        mkdirSync(dirname(filePath), { recursive: true });
+    }
+    catch {
+        // openSync below will surface real failures
+    }
+    rotateIfNeeded(filePath);
+    try {
+        fd = fs.openSync(filePath, "a");
+    }
+    catch {
+        return;
+    }
+    sessionId = randomBytes(4).toString("hex");
+    // Session header — all per-run constants in one line. Bash/awk friendly,
+    // human-readable, LLM-parseable. Subsequent lines don't repeat any of this.
+    const headerParts = [
+        `=== ${new Date().toISOString()}`,
+        `sid=${sessionId}`,
+        `ezeditor=${meta?.version ?? "?"}`,
+    ];
+    if (meta?.provider)
+        headerParts.push(`provider=${meta.provider}`);
+    if (meta?.model)
+        headerParts.push(`model=${meta.model}`);
+    if (meta?.host)
+        headerParts.push(`host=${meta.host}`);
+    headerParts.push(`pid=${process.pid}`, `platform=${process.platform}`, "===");
+    try {
+        fs.writeSync(fd, "\n" + headerParts.join(" ") + "\n");
+    }
+    catch {
+        // Header write failed — proceed; subsequent lines may still land
+    }
+}
+/** Session ID — useful for filtering one run out of an interleaved log. */
+export function getSessionId() {
+    return sessionId;
+}
+/** Hot-path skip flag for callers that want to avoid building log payloads. */
+export function isLoggerActive() {
+    return fd !== null;
+}
+/**
+ * Write a log line. Format: `HH:MM:SS.mmm L cat msg k=v k=v`.
+ *
+ * Values that contain spaces or `=` are JSON-quoted; bare otherwise. Long
+ * fields are truncated at MAX_FIELD_CHARS with `…(+N)` so the LLM sees the
+ * prefix plus a count of elided chars (rather than a silent cliff).
+ */
+export function log(level, category, message, data) {
+    if (fd === null)
+        return;
+    let line = `${timestamp()} ${level} ${category} ${message}`;
+    if (data) {
+        for (const [k, v] of Object.entries(data)) {
+            if (v === undefined || v === null)
+                continue;
+            line += ` ${k}=${formatValue(v)}`;
+        }
+    }
+    line += "\n";
+    try {
+        fs.writeSync(fd, line);
+    }
+    catch {
+        // Don't crash the CLI on a write failure
+    }
+}
+function formatValue(v) {
+    let s;
+    if (typeof v === "string") {
+        s = v;
+    }
+    else if (typeof v === "number" || typeof v === "boolean") {
+        return String(v); // numerics/booleans never need quoting and never overflow
+    }
+    else {
+        try {
+            s = JSON.stringify(v);
+        }
+        catch {
+            s = String(v);
+        }
+    }
+    if (s.length > MAX_FIELD_CHARS) {
+        s = s.slice(0, MAX_FIELD_CHARS) + `…(+${s.length - MAX_FIELD_CHARS})`;
+    }
+    // Quote when the value has whitespace, `=`, or quotes — so grep/awk on
+    // ` k=` boundaries works reliably. Bare otherwise (saves 2 bytes).
+    if (/[\s="]/.test(s)) {
+        return JSON.stringify(s);
+    }
+    return s;
+}
+export const logInfo = (cat, msg, data) => log("I", cat, msg, data);
+export const logWarn = (cat, msg, data) => log("W", cat, msg, data);
+export const logError = (cat, msg, data) => log("E", cat, msg, data);
+/** Close the log fd. Safe to call multiple times. */
+export function closeLogger() {
+    if (fd === null)
+        return;
+    log("I", "shutdown", "exit");
+    try {
+        fs.closeSync(fd);
+    }
+    catch {
+        // Ignore
+    }
+    fd = null;
+}
+//# sourceMappingURL=logger.js.map

package/dist/core/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/core/logger.ts"],"names":[],"mappings":"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"}