@hansjm10/volt-coding-agent 0.0.0-bootstrap.0 → 0.1.0

package/dist/core/tools/lsp.js

@@ -0,0 +1,157 @@
+/**
+ * LSP navigation tool: definition, references, hover, symbols, and on-demand
+ * diagnostics through the language servers configured in the lsp settings.
+ *
+ * The tool is registered as a built-in but only does useful work when an
+ * LspNavigationProvider (the LspManager) is supplied, i.e. when LSP is not
+ * disabled in settings.
+ */
+import { StringEnum } from "@hansjm10/volt-ai";
+import { Text } from "@hansjm10/volt-tui";
+import { Type } from "typebox";
+import { resolveToCwd } from "./path-utils.js";
+import { renderToolPath, str } from "./render-utils.js";
+import { wrapToolDefinition } from "./tool-definition-wrapper.js";
+export const LSP_ACTIONS = [
+    "definition",
+    "references",
+    "implementations",
+    "type-definition",
+    "callers",
+    "callees",
+    "hover",
+    "symbols",
+    "diagnostics",
+    "rename",
+    "fix",
+];
+const lspSchema = Type.Object({
+    action: StringEnum(LSP_ACTIONS, {
+        description: "definition: where a symbol is defined. references: all usages of a symbol. implementations: implementations of an interface/abstract symbol. type-definition: where a symbol's type is defined. callers: functions that call a symbol. callees: functions a symbol calls. hover: type/docs for a symbol. symbols: outline of a file, or project-wide symbol search when symbol is provided. diagnostics: current errors in a file. rename: rename a symbol across the project. fix: apply a quick fix (e.g. add a missing import) or a kind like source.organizeImports.",
+    }),
+    path: Type.String({ description: "Path to the file to query (relative or absolute)" }),
+    symbol: Type.Optional(Type.String({
+        description: "Symbol name to look up. Required for definition, references, callers, callees, hover, and rename; recommended for fix. For symbols, turns the file outline into a project-wide symbol search using this as the query.",
+    })),
+    line: Type.Optional(Type.Number({
+        description: "1-based line number where the symbol occurrence is located. Recommended when the symbol appears multiple times in the file. For fix without a symbol, selects the line to fix.",
+    })),
+    newName: Type.Optional(Type.String({
+        description: "New symbol name. Required for rename.",
+    })),
+    title: Type.Optional(Type.String({
+        description: "Code action title to apply when fix reports multiple available actions.",
+    })),
+    kind: Type.Optional(Type.String({
+        description: 'Code action kind filter for fix, e.g. "source.organizeImports" to organize imports or "source.fixAll" to apply all safe fixes (requested over the whole file when no symbol/line is given).',
+    })),
+});
+function formatLspCall(args, theme, cwd) {
+    const action = str(args?.action) ?? "";
+    const path = str(args?.path);
+    const line = typeof args?.line === "number" ? `:${args.line}` : "";
+    const symbol = str(args?.symbol);
+    let text = `${theme.fg("toolTitle", theme.bold("lsp"))} ${theme.fg("muted", action)}`;
+    if (path) {
+        text += ` ${renderToolPath(path, theme, cwd)}${theme.fg("muted", line)}`;
+    }
+    if (symbol) {
+        text += ` ${theme.fg("toolOutput", symbol)}`;
+    }
+    const newName = str(args?.newName);
+    if (newName) {
+        text += ` ${theme.fg("muted", "->")} ${theme.fg("toolOutput", newName)}`;
+    }
+    const title = str(args?.title);
+    if (title) {
+        text += ` ${theme.fg("muted", `"${title}"`)}`;
+    }
+    return text;
+}
+export function createLspToolDefinition(cwd, options) {
+    const provider = options?.provider;
+    return {
+        name: "lsp",
+        label: "lsp",
+        description: "Query language servers for code intelligence and refactoring. Actions: definition (where a symbol is defined), references (all usages of a symbol), implementations (implementations of an interface/abstract symbol), type-definition (where a symbol's type is defined), callers (functions calling a symbol), callees (functions a symbol calls), hover (type signature and docs), symbols (file outline, or project-wide symbol search when symbol is provided), diagnostics (current errors in a file), rename (rename a symbol across the project; requires symbol and newName), fix (apply a quick fix for diagnostics at a symbol or line; pass title to choose among multiple, or kind such as source.organizeImports). definition/references/implementations/type-definition/callers/callees/hover/rename require a symbol name; pass line when the symbol occurs more than once.",
+        promptSnippet: "Code intelligence via language servers: definition, references, hover, symbols, diagnostics, rename, quick fixes",
+        promptGuidelines: [
+            "Prefer lsp references over grep when finding usages of a symbol, and lsp definition over grep when locating where a symbol is defined.",
+            "Use lsp rename to rename a symbol across the project instead of manual edits, and lsp fix to apply quick fixes such as adding missing imports reported by diagnostics.",
+        ],
+        parameters: lspSchema,
+        async execute(_toolCallId, input, signal, _onUpdate, _ctx) {
+            if (!provider) {
+                throw new Error("LSP is disabled. Run volt with --lsp or set lsp.enabled=true in settings.");
+            }
+            const absolutePath = resolveToCwd(input.path, cwd);
+            const needsSymbol = input.action === "definition" ||
+                input.action === "references" ||
+                input.action === "implementations" ||
+                input.action === "type-definition" ||
+                input.action === "callers" ||
+                input.action === "callees" ||
+                input.action === "hover" ||
+                input.action === "rename";
+            if (needsSymbol && !input.symbol) {
+                throw new Error(`lsp ${input.action} requires a symbol name.`);
+            }
+            if (input.action === "rename" && !input.newName) {
+                throw new Error("lsp rename requires newName.");
+            }
+            let text;
+            switch (input.action) {
+                case "definition":
+                    text = await provider.definition(absolutePath, input.symbol, input.line, signal);
+                    break;
+                case "references":
+                    text = await provider.references(absolutePath, input.symbol, input.line, signal);
+                    break;
+                case "implementations":
+                    text = await provider.implementations(absolutePath, input.symbol, input.line, signal);
+                    break;
+                case "type-definition":
+                    text = await provider.typeDefinition(absolutePath, input.symbol, input.line, signal);
+                    break;
+                case "callers":
+                    text = await provider.callHierarchy(absolutePath, input.symbol, "incoming", input.line, signal);
+                    break;
+                case "callees":
+                    text = await provider.callHierarchy(absolutePath, input.symbol, "outgoing", input.line, signal);
+                    break;
+                case "hover":
+                    text = await provider.hover(absolutePath, input.symbol, input.line, signal);
+                    break;
+                case "symbols":
+                    text = input.symbol
+                        ? await provider.workspaceSymbols(absolutePath, input.symbol, signal)
+                        : await provider.documentSymbols(absolutePath, signal);
+                    break;
+                case "diagnostics":
+                    text = await provider.fileDiagnostics(absolutePath, signal);
+                    break;
+                case "rename":
+                    text = await provider.rename(absolutePath, input.symbol, input.newName, input.line, signal);
+                    break;
+                case "fix":
+                    text = await provider.codeFix(absolutePath, { symbol: input.symbol, line: input.line, title: input.title, kind: input.kind }, signal);
+                    break;
+                default:
+                    throw new Error(`Unknown lsp action: ${String(input.action)}`);
+            }
+            return {
+                content: [{ type: "text", text }],
+                details: { action: input.action },
+            };
+        },
+        renderCall(args, theme, context) {
+            const component = context.lastComponent ?? new Text("", 0, 0);
+            component.setText(formatLspCall(args, theme, context.cwd));
+            return component;
+        },
+    };
+}
+export function createLspTool(cwd, options) {
+    return wrapToolDefinition(createLspToolDefinition(cwd, options));
+}
+//# sourceMappingURL=lsp.js.map

package/dist/core/tools/lsp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lsp.js","sourceRoot":"","sources":["../../../src/core/tools/lsp.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * LSP navigation tool: definition, references, hover, symbols, and on-demand\n * diagnostics through the language servers configured in the lsp settings.\n *\n * The tool is registered as a built-in but only does useful work when an\n * LspNavigationProvider (the LspManager) is supplied, i.e. when LSP is not\n * disabled in settings.\n */\n\nimport type { AgentTool } from \"@hansjm10/volt-agent-core\";\nimport { StringEnum } from \"@hansjm10/volt-ai\";\nimport { Text } from \"@hansjm10/volt-tui\";\nimport { type Static, Type } from \"typebox\";\nimport type { ToolDefinition } from \"../extensions/types.ts\";\nimport type { Theme } from \"../theme/runtime.ts\";\nimport { resolveToCwd } from \"./path-utils.ts\";\nimport { renderToolPath, str } from \"./render-utils.ts\";\nimport { wrapToolDefinition } from \"./tool-definition-wrapper.ts\";\n\nexport const LSP_ACTIONS = [\n\t\"definition\",\n\t\"references\",\n\t\"implementations\",\n\t\"type-definition\",\n\t\"callers\",\n\t\"callees\",\n\t\"hover\",\n\t\"symbols\",\n\t\"diagnostics\",\n\t\"rename\",\n\t\"fix\",\n] as const;\nexport type LspAction = (typeof LSP_ACTIONS)[number];\n\n/**\n * Navigation interface implemented by the LspManager.\n *\n * All methods return formatted, human-readable text. Failures (no server, no\n * symbol found, server errors) are reported as text rather than thrown so the\n * model can react to them.\n */\nexport interface LspNavigationProvider {\n\tdefinition(absolutePath: string, symbol: string, line?: number, signal?: AbortSignal): Promise<string>;\n\treferences(absolutePath: string, symbol: string, line?: number, signal?: AbortSignal): Promise<string>;\n\timplementations(absolutePath: string, symbol: string, line?: number, signal?: AbortSignal): Promise<string>;\n\ttypeDefinition(absolutePath: string, symbol: string, line?: number, signal?: AbortSignal): Promise<string>;\n\thover(absolutePath: string, symbol: string, line?: number, signal?: AbortSignal): Promise<string>;\n\tdocumentSymbols(absolutePath: string, signal?: AbortSignal): Promise<string>;\n\tworkspaceSymbols(absolutePath: string, query: string, signal?: AbortSignal): Promise<string>;\n\tcallHierarchy(\n\t\tabsolutePath: string,\n\t\tsymbol: string,\n\t\tdirection: \"incoming\" | \"outgoing\",\n\t\tline?: number,\n\t\tsignal?: AbortSignal,\n\t): Promise<string>;\n\tfileDiagnostics(absolutePath: string, signal?: AbortSignal): Promise<string>;\n\trename(absolutePath: string, symbol: string, newName: string, line?: number, signal?: AbortSignal): Promise<string>;\n\tcodeFix(\n\t\tabsolutePath: string,\n\t\toptions: { symbol?: string; line?: number; title?: string; kind?: string },\n\t\tsignal?: AbortSignal,\n\t): Promise<string>;\n}\n\nconst lspSchema = Type.Object({\n\taction: StringEnum(LSP_ACTIONS, {\n\t\tdescription:\n\t\t\t\"definition: where a symbol is defined. references: all usages of a symbol. implementations: implementations of an interface/abstract symbol. type-definition: where a symbol's type is defined. callers: functions that call a symbol. callees: functions a symbol calls. hover: type/docs for a symbol. symbols: outline of a file, or project-wide symbol search when symbol is provided. diagnostics: current errors in a file. rename: rename a symbol across the project. fix: apply a quick fix (e.g. add a missing import) or a kind like source.organizeImports.\",\n\t}),\n\tpath: Type.String({ description: \"Path to the file to query (relative or absolute)\" }),\n\tsymbol: Type.Optional(\n\t\tType.String({\n\t\t\tdescription:\n\t\t\t\t\"Symbol name to look up. Required for definition, references, callers, callees, hover, and rename; recommended for fix. For symbols, turns the file outline into a project-wide symbol search using this as the query.\",\n\t\t}),\n\t),\n\tline: Type.Optional(\n\t\tType.Number({\n\t\t\tdescription:\n\t\t\t\t\"1-based line number where the symbol occurrence is located. Recommended when the symbol appears multiple times in the file. For fix without a symbol, selects the line to fix.\",\n\t\t}),\n\t),\n\tnewName: Type.Optional(\n\t\tType.String({\n\t\t\tdescription: \"New symbol name. Required for rename.\",\n\t\t}),\n\t),\n\ttitle: Type.Optional(\n\t\tType.String({\n\t\t\tdescription: \"Code action title to apply when fix reports multiple available actions.\",\n\t\t}),\n\t),\n\tkind: Type.Optional(\n\t\tType.String({\n\t\t\tdescription:\n\t\t\t\t'Code action kind filter for fix, e.g. \"source.organizeImports\" to organize imports or \"source.fixAll\" to apply all safe fixes (requested over the whole file when no symbol/line is given).',\n\t\t}),\n\t),\n});\n\nexport type LspToolInput = Static<typeof lspSchema>;\n\nexport interface LspToolDetails {\n\taction: LspAction;\n}\n\nexport interface LspToolOptions {\n\t/** Navigation provider (the LspManager). When absent, the tool reports that LSP is disabled. */\n\tprovider?: LspNavigationProvider;\n}\n\nfunction formatLspCall(args: Partial<LspToolInput> | undefined, theme: Theme, cwd: string): string {\n\tconst action = str(args?.action) ?? \"\";\n\tconst path = str(args?.path);\n\tconst line = typeof args?.line === \"number\" ? `:${args.line}` : \"\";\n\tconst symbol = str(args?.symbol);\n\tlet text = `${theme.fg(\"toolTitle\", theme.bold(\"lsp\"))} ${theme.fg(\"muted\", action)}`;\n\tif (path) {\n\t\ttext += ` ${renderToolPath(path, theme, cwd)}${theme.fg(\"muted\", line)}`;\n\t}\n\tif (symbol) {\n\t\ttext += ` ${theme.fg(\"toolOutput\", symbol)}`;\n\t}\n\tconst newName = str(args?.newName);\n\tif (newName) {\n\t\ttext += ` ${theme.fg(\"muted\", \"->\")} ${theme.fg(\"toolOutput\", newName)}`;\n\t}\n\tconst title = str(args?.title);\n\tif (title) {\n\t\ttext += ` ${theme.fg(\"muted\", `\"${title}\"`)}`;\n\t}\n\treturn text;\n}\n\nexport function createLspToolDefinition(\n\tcwd: string,\n\toptions?: LspToolOptions,\n): ToolDefinition<typeof lspSchema, LspToolDetails | undefined> {\n\tconst provider = options?.provider;\n\treturn {\n\t\tname: \"lsp\",\n\t\tlabel: \"lsp\",\n\t\tdescription:\n\t\t\t\"Query language servers for code intelligence and refactoring. Actions: definition (where a symbol is defined), references (all usages of a symbol), implementations (implementations of an interface/abstract symbol), type-definition (where a symbol's type is defined), callers (functions calling a symbol), callees (functions a symbol calls), hover (type signature and docs), symbols (file outline, or project-wide symbol search when symbol is provided), diagnostics (current errors in a file), rename (rename a symbol across the project; requires symbol and newName), fix (apply a quick fix for diagnostics at a symbol or line; pass title to choose among multiple, or kind such as source.organizeImports). definition/references/implementations/type-definition/callers/callees/hover/rename require a symbol name; pass line when the symbol occurs more than once.\",\n\t\tpromptSnippet:\n\t\t\t\"Code intelligence via language servers: definition, references, hover, symbols, diagnostics, rename, quick fixes\",\n\t\tpromptGuidelines: [\n\t\t\t\"Prefer lsp references over grep when finding usages of a symbol, and lsp definition over grep when locating where a symbol is defined.\",\n\t\t\t\"Use lsp rename to rename a symbol across the project instead of manual edits, and lsp fix to apply quick fixes such as adding missing imports reported by diagnostics.\",\n\t\t],\n\t\tparameters: lspSchema,\n\t\tasync execute(_toolCallId, input: LspToolInput, signal?: AbortSignal, _onUpdate?, _ctx?) {\n\t\t\tif (!provider) {\n\t\t\t\tthrow new Error(\"LSP is disabled. Run volt with --lsp or set lsp.enabled=true in settings.\");\n\t\t\t}\n\t\t\tconst absolutePath = resolveToCwd(input.path, cwd);\n\t\t\tconst needsSymbol =\n\t\t\t\tinput.action === \"definition\" ||\n\t\t\t\tinput.action === \"references\" ||\n\t\t\t\tinput.action === \"implementations\" ||\n\t\t\t\tinput.action === \"type-definition\" ||\n\t\t\t\tinput.action === \"callers\" ||\n\t\t\t\tinput.action === \"callees\" ||\n\t\t\t\tinput.action === \"hover\" ||\n\t\t\t\tinput.action === \"rename\";\n\t\t\tif (needsSymbol && !input.symbol) {\n\t\t\t\tthrow new Error(`lsp ${input.action} requires a symbol name.`);\n\t\t\t}\n\t\t\tif (input.action === \"rename\" && !input.newName) {\n\t\t\t\tthrow new Error(\"lsp rename requires newName.\");\n\t\t\t}\n\n\t\t\tlet text: string;\n\t\t\tswitch (input.action) {\n\t\t\t\tcase \"definition\":\n\t\t\t\t\ttext = await provider.definition(absolutePath, input.symbol!, input.line, signal);\n\t\t\t\t\tbreak;\n\t\t\t\tcase \"references\":\n\t\t\t\t\ttext = await provider.references(absolutePath, input.symbol!, input.line, signal);\n\t\t\t\t\tbreak;\n\t\t\t\tcase \"implementations\":\n\t\t\t\t\ttext = await provider.implementations(absolutePath, input.symbol!, input.line, signal);\n\t\t\t\t\tbreak;\n\t\t\t\tcase \"type-definition\":\n\t\t\t\t\ttext = await provider.typeDefinition(absolutePath, input.symbol!, input.line, signal);\n\t\t\t\t\tbreak;\n\t\t\t\tcase \"callers\":\n\t\t\t\t\ttext = await provider.callHierarchy(absolutePath, input.symbol!, \"incoming\", input.line, signal);\n\t\t\t\t\tbreak;\n\t\t\t\tcase \"callees\":\n\t\t\t\t\ttext = await provider.callHierarchy(absolutePath, input.symbol!, \"outgoing\", input.line, signal);\n\t\t\t\t\tbreak;\n\t\t\t\tcase \"hover\":\n\t\t\t\t\ttext = await provider.hover(absolutePath, input.symbol!, input.line, signal);\n\t\t\t\t\tbreak;\n\t\t\t\tcase \"symbols\":\n\t\t\t\t\ttext = input.symbol\n\t\t\t\t\t\t? await provider.workspaceSymbols(absolutePath, input.symbol, signal)\n\t\t\t\t\t\t: await provider.documentSymbols(absolutePath, signal);\n\t\t\t\t\tbreak;\n\t\t\t\tcase \"diagnostics\":\n\t\t\t\t\ttext = await provider.fileDiagnostics(absolutePath, signal);\n\t\t\t\t\tbreak;\n\t\t\t\tcase \"rename\":\n\t\t\t\t\ttext = await provider.rename(absolutePath, input.symbol!, input.newName!, input.line, signal);\n\t\t\t\t\tbreak;\n\t\t\t\tcase \"fix\":\n\t\t\t\t\ttext = await provider.codeFix(\n\t\t\t\t\t\tabsolutePath,\n\t\t\t\t\t\t{ symbol: input.symbol, line: input.line, title: input.title, kind: input.kind },\n\t\t\t\t\t\tsignal,\n\t\t\t\t\t);\n\t\t\t\t\tbreak;\n\t\t\t\tdefault:\n\t\t\t\t\tthrow new Error(`Unknown lsp action: ${String(input.action)}`);\n\t\t\t}\n\n\t\t\treturn {\n\t\t\t\tcontent: [{ type: \"text\", text }],\n\t\t\t\tdetails: { action: input.action },\n\t\t\t};\n\t\t},\n\t\trenderCall(args, theme, context) {\n\t\t\tconst component = (context.lastComponent as Text | undefined) ?? new Text(\"\", 0, 0);\n\t\t\tcomponent.setText(formatLspCall(args as Partial<LspToolInput> | undefined, theme, context.cwd));\n\t\t\treturn component;\n\t\t},\n\t};\n}\n\nexport function createLspTool(cwd: string, options?: LspToolOptions): AgentTool<typeof lspSchema> {\n\treturn wrapToolDefinition(createLspToolDefinition(cwd, options));\n}\n"]}

package/dist/core/tools/output-accumulator.d.ts

@@ -0,0 +1,52 @@
+import { type TruncationResult } from "./truncate.ts";
+export interface OutputAccumulatorOptions {
+    maxLines?: number;
+    maxBytes?: number;
+    tempFilePrefix?: string;
+}
+export interface OutputSnapshot {
+    content: string;
+    truncation: TruncationResult;
+    fullOutputPath?: string;
+}
+/**
+ * Incrementally tracks streaming output with bounded memory.
+ *
+ * Appends decode chunks with a streaming UTF-8 decoder, keeps only a decoded
+ * tail for display snapshots, and opens a temp file when the full output needs
+ * to be preserved.
+ */
+export declare class OutputAccumulator {
+    private readonly maxLines;
+    private readonly maxBytes;
+    private readonly maxRollingBytes;
+    private readonly tempFilePrefix;
+    private readonly decoder;
+    private rawChunks;
+    private tailText;
+    private tailBytes;
+    private tailStartsAtLineBoundary;
+    private totalRawBytes;
+    private totalDecodedBytes;
+    private completedLines;
+    private totalLines;
+    private currentLineBytes;
+    private hasOpenLine;
+    private finished;
+    private tempFilePath;
+    private tempFileStream;
+    constructor(options?: OutputAccumulatorOptions);
+    append(data: Buffer): void;
+    finish(): void;
+    snapshot(options?: {
+        persistIfTruncated?: boolean;
+    }): OutputSnapshot;
+    closeTempFile(): Promise<void>;
+    getLastLineBytes(): number;
+    private appendDecodedText;
+    private trimTail;
+    private getSnapshotText;
+    private shouldUseTempFile;
+    private ensureTempFile;
+}
+//# sourceMappingURL=output-accumulator.d.ts.map

package/dist/core/tools/output-accumulator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-accumulator.d.ts","sourceRoot":"","sources":["../../../src/core/tools/output-accumulator.ts"],"names":[],"mappings":"AAIA,OAAO,EAAwC,KAAK,gBAAgB,EAAgB,MAAM,eAAe,CAAC;AAE1G,MAAM,WAAW,wBAAwB;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,gBAAgB,CAAC;IAC7B,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB;AAWD;;;;;;GAMG;AACH,qBAAa,iBAAiB;IAC7B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAE7C,OAAO,CAAC,SAAS,CAAgB;IACjC,OAAO,CAAC,QAAQ,CAAM;IACtB,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,wBAAwB,CAAQ;IACxC,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,QAAQ,CAAS;IAEzB,OAAO,CAAC,YAAY,CAAqB;IACzC,OAAO,CAAC,cAAc,CAA0B;IAEhD,YAAY,OAAO,GAAE,wBAA6B,EAKjD;IAED,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAczB;IAED,MAAM,IAAI,IAAI,CASb;IAED,QAAQ,CAAC,OAAO,GAAE;QAAE,kBAAkB,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,cAAc,CA4BvE;IAEK,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAqBnC;IAED,gBAAgB,IAAI,MAAM,CAEzB;IAED,OAAO,CAAC,iBAAiB;IA+BzB,OAAO,CAAC,QAAQ;IAiBhB,OAAO,CAAC,eAAe;IASvB,OAAO,CAAC,iBAAiB;IAMzB,OAAO,CAAC,cAAc;CAWtB","sourcesContent":["import { randomBytes } from \"node:crypto\";\nimport { createWriteStream, type WriteStream } from \"node:fs\";\nimport { tmpdir } from \"node:os\";\nimport { join } from \"node:path\";\nimport { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, type TruncationResult, truncateTail } from \"./truncate.ts\";\n\nexport interface OutputAccumulatorOptions {\n\tmaxLines?: number;\n\tmaxBytes?: number;\n\ttempFilePrefix?: string;\n}\n\nexport interface OutputSnapshot {\n\tcontent: string;\n\ttruncation: TruncationResult;\n\tfullOutputPath?: string;\n}\n\nfunction defaultTempFilePath(prefix: string): string {\n\tconst id = randomBytes(8).toString(\"hex\");\n\treturn join(tmpdir(), `${prefix}-${id}.log`);\n}\n\nfunction byteLength(text: string): number {\n\treturn Buffer.byteLength(text, \"utf-8\");\n}\n\n/**\n * Incrementally tracks streaming output with bounded memory.\n *\n * Appends decode chunks with a streaming UTF-8 decoder, keeps only a decoded\n * tail for display snapshots, and opens a temp file when the full output needs\n * to be preserved.\n */\nexport class OutputAccumulator {\n\tprivate readonly maxLines: number;\n\tprivate readonly maxBytes: number;\n\tprivate readonly maxRollingBytes: number;\n\tprivate readonly tempFilePrefix: string;\n\tprivate readonly decoder = new TextDecoder();\n\n\tprivate rawChunks: Buffer[] = [];\n\tprivate tailText = \"\";\n\tprivate tailBytes = 0;\n\tprivate tailStartsAtLineBoundary = true;\n\tprivate totalRawBytes = 0;\n\tprivate totalDecodedBytes = 0;\n\tprivate completedLines = 0;\n\tprivate totalLines = 0;\n\tprivate currentLineBytes = 0;\n\tprivate hasOpenLine = false;\n\tprivate finished = false;\n\n\tprivate tempFilePath: string | undefined;\n\tprivate tempFileStream: WriteStream | undefined;\n\n\tconstructor(options: OutputAccumulatorOptions = {}) {\n\t\tthis.maxLines = options.maxLines ?? DEFAULT_MAX_LINES;\n\t\tthis.maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;\n\t\tthis.maxRollingBytes = Math.max(this.maxBytes * 2, 1);\n\t\tthis.tempFilePrefix = options.tempFilePrefix ?? \"volt-output\";\n\t}\n\n\tappend(data: Buffer): void {\n\t\tif (this.finished) {\n\t\t\tthrow new Error(\"Cannot append to a finished output accumulator\");\n\t\t}\n\n\t\tthis.totalRawBytes += data.length;\n\t\tthis.appendDecodedText(this.decoder.decode(data, { stream: true }));\n\n\t\tif (this.tempFileStream || this.shouldUseTempFile()) {\n\t\t\tthis.ensureTempFile();\n\t\t\tthis.tempFileStream?.write(data);\n\t\t} else if (data.length > 0) {\n\t\t\tthis.rawChunks.push(data);\n\t\t}\n\t}\n\n\tfinish(): void {\n\t\tif (this.finished) {\n\t\t\treturn;\n\t\t}\n\t\tthis.finished = true;\n\t\tthis.appendDecodedText(this.decoder.decode());\n\t\tif (this.shouldUseTempFile()) {\n\t\t\tthis.ensureTempFile();\n\t\t}\n\t}\n\n\tsnapshot(options: { persistIfTruncated?: boolean } = {}): OutputSnapshot {\n\t\tconst tailTruncation = truncateTail(this.getSnapshotText(), {\n\t\t\tmaxLines: this.maxLines,\n\t\t\tmaxBytes: this.maxBytes,\n\t\t});\n\t\tconst truncated = this.totalLines > this.maxLines || this.totalDecodedBytes > this.maxBytes;\n\t\tconst truncatedBy = truncated\n\t\t\t? (tailTruncation.truncatedBy ?? (this.totalDecodedBytes > this.maxBytes ? \"bytes\" : \"lines\"))\n\t\t\t: null;\n\t\tconst truncation: TruncationResult = {\n\t\t\t...tailTruncation,\n\t\t\ttruncated,\n\t\t\ttruncatedBy,\n\t\t\ttotalLines: this.totalLines,\n\t\t\ttotalBytes: this.totalDecodedBytes,\n\t\t\tmaxLines: this.maxLines,\n\t\t\tmaxBytes: this.maxBytes,\n\t\t};\n\n\t\tif (options.persistIfTruncated && truncation.truncated) {\n\t\t\tthis.ensureTempFile();\n\t\t}\n\n\t\treturn {\n\t\t\tcontent: truncation.content,\n\t\t\ttruncation,\n\t\t\tfullOutputPath: this.tempFilePath,\n\t\t};\n\t}\n\n\tasync closeTempFile(): Promise<void> {\n\t\tif (!this.tempFileStream) {\n\t\t\treturn;\n\t\t}\n\n\t\tconst stream = this.tempFileStream;\n\t\tthis.tempFileStream = undefined;\n\n\t\tawait new Promise<void>((resolve, reject) => {\n\t\t\tconst onError = (error: Error) => {\n\t\t\t\tstream.off(\"finish\", onFinish);\n\t\t\t\treject(error);\n\t\t\t};\n\t\t\tconst onFinish = () => {\n\t\t\t\tstream.off(\"error\", onError);\n\t\t\t\tresolve();\n\t\t\t};\n\t\t\tstream.once(\"error\", onError);\n\t\t\tstream.once(\"finish\", onFinish);\n\t\t\tstream.end();\n\t\t});\n\t}\n\n\tgetLastLineBytes(): number {\n\t\treturn this.currentLineBytes;\n\t}\n\n\tprivate appendDecodedText(text: string): void {\n\t\tif (text.length === 0) {\n\t\t\treturn;\n\t\t}\n\n\t\tconst bytes = byteLength(text);\n\t\tthis.totalDecodedBytes += bytes;\n\t\tthis.tailText += text;\n\t\tthis.tailBytes += bytes;\n\t\tif (this.tailBytes > this.maxRollingBytes * 2) {\n\t\t\tthis.trimTail();\n\t\t}\n\n\t\tlet newlines = 0;\n\t\tlet lastNewline = -1;\n\t\tfor (let i = text.indexOf(\"\\n\"); i !== -1; i = text.indexOf(\"\\n\", i + 1)) {\n\t\t\tnewlines++;\n\t\t\tlastNewline = i;\n\t\t}\n\t\tif (newlines === 0) {\n\t\t\tthis.currentLineBytes += bytes;\n\t\t\tthis.hasOpenLine = true;\n\t\t} else {\n\t\t\tthis.completedLines += newlines;\n\t\t\tconst tail = text.slice(lastNewline + 1);\n\t\t\tthis.currentLineBytes = byteLength(tail);\n\t\t\tthis.hasOpenLine = tail.length > 0;\n\t\t}\n\t\tthis.totalLines = this.completedLines + (this.hasOpenLine ? 1 : 0);\n\t}\n\n\tprivate trimTail(): void {\n\t\tconst buffer = Buffer.from(this.tailText, \"utf-8\");\n\t\tif (buffer.length <= this.maxRollingBytes) {\n\t\t\tthis.tailBytes = buffer.length;\n\t\t\treturn;\n\t\t}\n\n\t\tlet start = buffer.length - this.maxRollingBytes;\n\t\twhile (start < buffer.length && (buffer[start] & 0xc0) === 0x80) {\n\t\t\tstart++;\n\t\t}\n\n\t\tthis.tailStartsAtLineBoundary = start === 0 ? this.tailStartsAtLineBoundary : buffer[start - 1] === 0x0a;\n\t\tthis.tailText = buffer.subarray(start).toString(\"utf-8\");\n\t\tthis.tailBytes = byteLength(this.tailText);\n\t}\n\n\tprivate getSnapshotText(): string {\n\t\tif (this.tailStartsAtLineBoundary) {\n\t\t\treturn this.tailText;\n\t\t}\n\n\t\tconst firstNewline = this.tailText.indexOf(\"\\n\");\n\t\treturn firstNewline === -1 ? this.tailText : this.tailText.slice(firstNewline + 1);\n\t}\n\n\tprivate shouldUseTempFile(): boolean {\n\t\treturn (\n\t\t\tthis.totalRawBytes > this.maxBytes || this.totalDecodedBytes > this.maxBytes || this.totalLines > this.maxLines\n\t\t);\n\t}\n\n\tprivate ensureTempFile(): void {\n\t\tif (this.tempFilePath) {\n\t\t\treturn;\n\t\t}\n\t\tthis.tempFilePath = defaultTempFilePath(this.tempFilePrefix);\n\t\tthis.tempFileStream = createWriteStream(this.tempFilePath, { flags: \"wx\", mode: 0o600 });\n\t\tfor (const chunk of this.rawChunks) {\n\t\t\tthis.tempFileStream.write(chunk);\n\t\t}\n\t\tthis.rawChunks = [];\n\t}\n}\n"]}

package/dist/core/tools/output-accumulator.js

@@ -0,0 +1,184 @@
+import { randomBytes } from "node:crypto";
+import { createWriteStream } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, truncateTail } from "./truncate.js";
+function defaultTempFilePath(prefix) {
+    const id = randomBytes(8).toString("hex");
+    return join(tmpdir(), `${prefix}-${id}.log`);
+}
+function byteLength(text) {
+    return Buffer.byteLength(text, "utf-8");
+}
+/**
+ * Incrementally tracks streaming output with bounded memory.
+ *
+ * Appends decode chunks with a streaming UTF-8 decoder, keeps only a decoded
+ * tail for display snapshots, and opens a temp file when the full output needs
+ * to be preserved.
+ */
+export class OutputAccumulator {
+    maxLines;
+    maxBytes;
+    maxRollingBytes;
+    tempFilePrefix;
+    decoder = new TextDecoder();
+    rawChunks = [];
+    tailText = "";
+    tailBytes = 0;
+    tailStartsAtLineBoundary = true;
+    totalRawBytes = 0;
+    totalDecodedBytes = 0;
+    completedLines = 0;
+    totalLines = 0;
+    currentLineBytes = 0;
+    hasOpenLine = false;
+    finished = false;
+    tempFilePath;
+    tempFileStream;
+    constructor(options = {}) {
+        this.maxLines = options.maxLines ?? DEFAULT_MAX_LINES;
+        this.maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+        this.maxRollingBytes = Math.max(this.maxBytes * 2, 1);
+        this.tempFilePrefix = options.tempFilePrefix ?? "volt-output";
+    }
+    append(data) {
+        if (this.finished) {
+            throw new Error("Cannot append to a finished output accumulator");
+        }
+        this.totalRawBytes += data.length;
+        this.appendDecodedText(this.decoder.decode(data, { stream: true }));
+        if (this.tempFileStream || this.shouldUseTempFile()) {
+            this.ensureTempFile();
+            this.tempFileStream?.write(data);
+        }
+        else if (data.length > 0) {
+            this.rawChunks.push(data);
+        }
+    }
+    finish() {
+        if (this.finished) {
+            return;
+        }
+        this.finished = true;
+        this.appendDecodedText(this.decoder.decode());
+        if (this.shouldUseTempFile()) {
+            this.ensureTempFile();
+        }
+    }
+    snapshot(options = {}) {
+        const tailTruncation = truncateTail(this.getSnapshotText(), {
+            maxLines: this.maxLines,
+            maxBytes: this.maxBytes,
+        });
+        const truncated = this.totalLines > this.maxLines || this.totalDecodedBytes > this.maxBytes;
+        const truncatedBy = truncated
+            ? (tailTruncation.truncatedBy ?? (this.totalDecodedBytes > this.maxBytes ? "bytes" : "lines"))
+            : null;
+        const truncation = {
+            ...tailTruncation,
+            truncated,
+            truncatedBy,
+            totalLines: this.totalLines,
+            totalBytes: this.totalDecodedBytes,
+            maxLines: this.maxLines,
+            maxBytes: this.maxBytes,
+        };
+        if (options.persistIfTruncated && truncation.truncated) {
+            this.ensureTempFile();
+        }
+        return {
+            content: truncation.content,
+            truncation,
+            fullOutputPath: this.tempFilePath,
+        };
+    }
+    async closeTempFile() {
+        if (!this.tempFileStream) {
+            return;
+        }
+        const stream = this.tempFileStream;
+        this.tempFileStream = undefined;
+        await new Promise((resolve, reject) => {
+            const onError = (error) => {
+                stream.off("finish", onFinish);
+                reject(error);
+            };
+            const onFinish = () => {
+                stream.off("error", onError);
+                resolve();
+            };
+            stream.once("error", onError);
+            stream.once("finish", onFinish);
+            stream.end();
+        });
+    }
+    getLastLineBytes() {
+        return this.currentLineBytes;
+    }
+    appendDecodedText(text) {
+        if (text.length === 0) {
+            return;
+        }
+        const bytes = byteLength(text);
+        this.totalDecodedBytes += bytes;
+        this.tailText += text;
+        this.tailBytes += bytes;
+        if (this.tailBytes > this.maxRollingBytes * 2) {
+            this.trimTail();
+        }
+        let newlines = 0;
+        let lastNewline = -1;
+        for (let i = text.indexOf("\n"); i !== -1; i = text.indexOf("\n", i + 1)) {
+            newlines++;
+            lastNewline = i;
+        }
+        if (newlines === 0) {
+            this.currentLineBytes += bytes;
+            this.hasOpenLine = true;
+        }
+        else {
+            this.completedLines += newlines;
+            const tail = text.slice(lastNewline + 1);
+            this.currentLineBytes = byteLength(tail);
+            this.hasOpenLine = tail.length > 0;
+        }
+        this.totalLines = this.completedLines + (this.hasOpenLine ? 1 : 0);
+    }
+    trimTail() {
+        const buffer = Buffer.from(this.tailText, "utf-8");
+        if (buffer.length <= this.maxRollingBytes) {
+            this.tailBytes = buffer.length;
+            return;
+        }
+        let start = buffer.length - this.maxRollingBytes;
+        while (start < buffer.length && (buffer[start] & 0xc0) === 0x80) {
+            start++;
+        }
+        this.tailStartsAtLineBoundary = start === 0 ? this.tailStartsAtLineBoundary : buffer[start - 1] === 0x0a;
+        this.tailText = buffer.subarray(start).toString("utf-8");
+        this.tailBytes = byteLength(this.tailText);
+    }
+    getSnapshotText() {
+        if (this.tailStartsAtLineBoundary) {
+            return this.tailText;
+        }
+        const firstNewline = this.tailText.indexOf("\n");
+        return firstNewline === -1 ? this.tailText : this.tailText.slice(firstNewline + 1);
+    }
+    shouldUseTempFile() {
+        return (this.totalRawBytes > this.maxBytes || this.totalDecodedBytes > this.maxBytes || this.totalLines > this.maxLines);
+    }
+    ensureTempFile() {
+        if (this.tempFilePath) {
+            return;
+        }
+        this.tempFilePath = defaultTempFilePath(this.tempFilePrefix);
+        this.tempFileStream = createWriteStream(this.tempFilePath, { flags: "wx", mode: 0o600 });
+        for (const chunk of this.rawChunks) {
+            this.tempFileStream.write(chunk);
+        }
+        this.rawChunks = [];
+    }
+}
+//# sourceMappingURL=output-accumulator.js.map

package/dist/core/tools/output-accumulator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-accumulator.js","sourceRoot":"","sources":["../../../src/core/tools/output-accumulator.ts"],"names":[],"mappings":"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","sourcesContent":["import { randomBytes } from \"node:crypto\";\nimport { createWriteStream, type WriteStream } from \"node:fs\";\nimport { tmpdir } from \"node:os\";\nimport { join } from \"node:path\";\nimport { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, type TruncationResult, truncateTail } from \"./truncate.ts\";\n\nexport interface OutputAccumulatorOptions {\n\tmaxLines?: number;\n\tmaxBytes?: number;\n\ttempFilePrefix?: string;\n}\n\nexport interface OutputSnapshot {\n\tcontent: string;\n\ttruncation: TruncationResult;\n\tfullOutputPath?: string;\n}\n\nfunction defaultTempFilePath(prefix: string): string {\n\tconst id = randomBytes(8).toString(\"hex\");\n\treturn join(tmpdir(), `${prefix}-${id}.log`);\n}\n\nfunction byteLength(text: string): number {\n\treturn Buffer.byteLength(text, \"utf-8\");\n}\n\n/**\n * Incrementally tracks streaming output with bounded memory.\n *\n * Appends decode chunks with a streaming UTF-8 decoder, keeps only a decoded\n * tail for display snapshots, and opens a temp file when the full output needs\n * to be preserved.\n */\nexport class OutputAccumulator {\n\tprivate readonly maxLines: number;\n\tprivate readonly maxBytes: number;\n\tprivate readonly maxRollingBytes: number;\n\tprivate readonly tempFilePrefix: string;\n\tprivate readonly decoder = new TextDecoder();\n\n\tprivate rawChunks: Buffer[] = [];\n\tprivate tailText = \"\";\n\tprivate tailBytes = 0;\n\tprivate tailStartsAtLineBoundary = true;\n\tprivate totalRawBytes = 0;\n\tprivate totalDecodedBytes = 0;\n\tprivate completedLines = 0;\n\tprivate totalLines = 0;\n\tprivate currentLineBytes = 0;\n\tprivate hasOpenLine = false;\n\tprivate finished = false;\n\n\tprivate tempFilePath: string | undefined;\n\tprivate tempFileStream: WriteStream | undefined;\n\n\tconstructor(options: OutputAccumulatorOptions = {}) {\n\t\tthis.maxLines = options.maxLines ?? DEFAULT_MAX_LINES;\n\t\tthis.maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;\n\t\tthis.maxRollingBytes = Math.max(this.maxBytes * 2, 1);\n\t\tthis.tempFilePrefix = options.tempFilePrefix ?? \"volt-output\";\n\t}\n\n\tappend(data: Buffer): void {\n\t\tif (this.finished) {\n\t\t\tthrow new Error(\"Cannot append to a finished output accumulator\");\n\t\t}\n\n\t\tthis.totalRawBytes += data.length;\n\t\tthis.appendDecodedText(this.decoder.decode(data, { stream: true }));\n\n\t\tif (this.tempFileStream || this.shouldUseTempFile()) {\n\t\t\tthis.ensureTempFile();\n\t\t\tthis.tempFileStream?.write(data);\n\t\t} else if (data.length > 0) {\n\t\t\tthis.rawChunks.push(data);\n\t\t}\n\t}\n\n\tfinish(): void {\n\t\tif (this.finished) {\n\t\t\treturn;\n\t\t}\n\t\tthis.finished = true;\n\t\tthis.appendDecodedText(this.decoder.decode());\n\t\tif (this.shouldUseTempFile()) {\n\t\t\tthis.ensureTempFile();\n\t\t}\n\t}\n\n\tsnapshot(options: { persistIfTruncated?: boolean } = {}): OutputSnapshot {\n\t\tconst tailTruncation = truncateTail(this.getSnapshotText(), {\n\t\t\tmaxLines: this.maxLines,\n\t\t\tmaxBytes: this.maxBytes,\n\t\t});\n\t\tconst truncated = this.totalLines > this.maxLines || this.totalDecodedBytes > this.maxBytes;\n\t\tconst truncatedBy = truncated\n\t\t\t? (tailTruncation.truncatedBy ?? (this.totalDecodedBytes > this.maxBytes ? \"bytes\" : \"lines\"))\n\t\t\t: null;\n\t\tconst truncation: TruncationResult = {\n\t\t\t...tailTruncation,\n\t\t\ttruncated,\n\t\t\ttruncatedBy,\n\t\t\ttotalLines: this.totalLines,\n\t\t\ttotalBytes: this.totalDecodedBytes,\n\t\t\tmaxLines: this.maxLines,\n\t\t\tmaxBytes: this.maxBytes,\n\t\t};\n\n\t\tif (options.persistIfTruncated && truncation.truncated) {\n\t\t\tthis.ensureTempFile();\n\t\t}\n\n\t\treturn {\n\t\t\tcontent: truncation.content,\n\t\t\ttruncation,\n\t\t\tfullOutputPath: this.tempFilePath,\n\t\t};\n\t}\n\n\tasync closeTempFile(): Promise<void> {\n\t\tif (!this.tempFileStream) {\n\t\t\treturn;\n\t\t}\n\n\t\tconst stream = this.tempFileStream;\n\t\tthis.tempFileStream = undefined;\n\n\t\tawait new Promise<void>((resolve, reject) => {\n\t\t\tconst onError = (error: Error) => {\n\t\t\t\tstream.off(\"finish\", onFinish);\n\t\t\t\treject(error);\n\t\t\t};\n\t\t\tconst onFinish = () => {\n\t\t\t\tstream.off(\"error\", onError);\n\t\t\t\tresolve();\n\t\t\t};\n\t\t\tstream.once(\"error\", onError);\n\t\t\tstream.once(\"finish\", onFinish);\n\t\t\tstream.end();\n\t\t});\n\t}\n\n\tgetLastLineBytes(): number {\n\t\treturn this.currentLineBytes;\n\t}\n\n\tprivate appendDecodedText(text: string): void {\n\t\tif (text.length === 0) {\n\t\t\treturn;\n\t\t}\n\n\t\tconst bytes = byteLength(text);\n\t\tthis.totalDecodedBytes += bytes;\n\t\tthis.tailText += text;\n\t\tthis.tailBytes += bytes;\n\t\tif (this.tailBytes > this.maxRollingBytes * 2) {\n\t\t\tthis.trimTail();\n\t\t}\n\n\t\tlet newlines = 0;\n\t\tlet lastNewline = -1;\n\t\tfor (let i = text.indexOf(\"\\n\"); i !== -1; i = text.indexOf(\"\\n\", i + 1)) {\n\t\t\tnewlines++;\n\t\t\tlastNewline = i;\n\t\t}\n\t\tif (newlines === 0) {\n\t\t\tthis.currentLineBytes += bytes;\n\t\t\tthis.hasOpenLine = true;\n\t\t} else {\n\t\t\tthis.completedLines += newlines;\n\t\t\tconst tail = text.slice(lastNewline + 1);\n\t\t\tthis.currentLineBytes = byteLength(tail);\n\t\t\tthis.hasOpenLine = tail.length > 0;\n\t\t}\n\t\tthis.totalLines = this.completedLines + (this.hasOpenLine ? 1 : 0);\n\t}\n\n\tprivate trimTail(): void {\n\t\tconst buffer = Buffer.from(this.tailText, \"utf-8\");\n\t\tif (buffer.length <= this.maxRollingBytes) {\n\t\t\tthis.tailBytes = buffer.length;\n\t\t\treturn;\n\t\t}\n\n\t\tlet start = buffer.length - this.maxRollingBytes;\n\t\twhile (start < buffer.length && (buffer[start] & 0xc0) === 0x80) {\n\t\t\tstart++;\n\t\t}\n\n\t\tthis.tailStartsAtLineBoundary = start === 0 ? this.tailStartsAtLineBoundary : buffer[start - 1] === 0x0a;\n\t\tthis.tailText = buffer.subarray(start).toString(\"utf-8\");\n\t\tthis.tailBytes = byteLength(this.tailText);\n\t}\n\n\tprivate getSnapshotText(): string {\n\t\tif (this.tailStartsAtLineBoundary) {\n\t\t\treturn this.tailText;\n\t\t}\n\n\t\tconst firstNewline = this.tailText.indexOf(\"\\n\");\n\t\treturn firstNewline === -1 ? this.tailText : this.tailText.slice(firstNewline + 1);\n\t}\n\n\tprivate shouldUseTempFile(): boolean {\n\t\treturn (\n\t\t\tthis.totalRawBytes > this.maxBytes || this.totalDecodedBytes > this.maxBytes || this.totalLines > this.maxLines\n\t\t);\n\t}\n\n\tprivate ensureTempFile(): void {\n\t\tif (this.tempFilePath) {\n\t\t\treturn;\n\t\t}\n\t\tthis.tempFilePath = defaultTempFilePath(this.tempFilePrefix);\n\t\tthis.tempFileStream = createWriteStream(this.tempFilePath, { flags: \"wx\", mode: 0o600 });\n\t\tfor (const chunk of this.rawChunks) {\n\t\t\tthis.tempFileStream.write(chunk);\n\t\t}\n\t\tthis.rawChunks = [];\n\t}\n}\n"]}

package/dist/core/tools/path-utils.d.ts

@@ -0,0 +1,10 @@
+export declare function pathExists(filePath: string): Promise<boolean>;
+export declare function expandPath(filePath: string): string;
+/**
+ * Resolve a path relative to the given cwd.
+ * Handles ~ expansion and absolute paths.
+ */
+export declare function resolveToCwd(filePath: string, cwd: string): string;
+export declare function resolveReadPath(filePath: string, cwd: string): string;
+export declare function resolveReadPathAsync(filePath: string, cwd: string): Promise<string>;
+//# sourceMappingURL=path-utils.d.ts.map

package/dist/core/tools/path-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-utils.d.ts","sourceRoot":"","sources":["../../../src/core/tools/path-utils.ts"],"names":[],"mappings":"AA8BA,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOnE;AAED,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAElE;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAgCrE;AAED,wBAAsB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAgCzF","sourcesContent":["import { accessSync, constants } from \"node:fs\";\nimport { access } from \"node:fs/promises\";\nimport { normalizePath, resolvePath } from \"../../utils/paths.ts\";\n\nconst NARROW_NO_BREAK_SPACE = \"\\u202F\";\n\nfunction tryMacOSScreenshotPath(filePath: string): string {\n\treturn filePath.replace(/ (AM|PM)\\./gi, `${NARROW_NO_BREAK_SPACE}$1.`);\n}\n\nfunction tryNFDVariant(filePath: string): string {\n\t// macOS stores filenames in NFD (decomposed) form, try converting user input to NFD\n\treturn filePath.normalize(\"NFD\");\n}\n\nfunction tryCurlyQuoteVariant(filePath: string): string {\n\t// macOS uses U+2019 (right single quotation mark) in screenshot names like \"Capture d'écran\"\n\t// Users typically type U+0027 (straight apostrophe)\n\treturn filePath.replace(/'/g, \"\\u2019\");\n}\n\nfunction fileExists(filePath: string): boolean {\n\ttry {\n\t\taccessSync(filePath, constants.F_OK);\n\t\treturn true;\n\t} catch {\n\t\treturn false;\n\t}\n}\n\nexport async function pathExists(filePath: string): Promise<boolean> {\n\ttry {\n\t\tawait access(filePath, constants.F_OK);\n\t\treturn true;\n\t} catch {\n\t\treturn false;\n\t}\n}\n\nexport function expandPath(filePath: string): string {\n\treturn normalizePath(filePath, { normalizeUnicodeSpaces: true, stripAtPrefix: true });\n}\n\n/**\n * Resolve a path relative to the given cwd.\n * Handles ~ expansion and absolute paths.\n */\nexport function resolveToCwd(filePath: string, cwd: string): string {\n\treturn resolvePath(filePath, cwd, { normalizeUnicodeSpaces: true, stripAtPrefix: true });\n}\n\nexport function resolveReadPath(filePath: string, cwd: string): string {\n\tconst resolved = resolveToCwd(filePath, cwd);\n\n\tif (fileExists(resolved)) {\n\t\treturn resolved;\n\t}\n\n\t// Try macOS AM/PM variant (narrow no-break space before AM/PM)\n\tconst amPmVariant = tryMacOSScreenshotPath(resolved);\n\tif (amPmVariant !== resolved && fileExists(amPmVariant)) {\n\t\treturn amPmVariant;\n\t}\n\n\t// Try NFD variant (macOS stores filenames in NFD form)\n\tconst nfdVariant = tryNFDVariant(resolved);\n\tif (nfdVariant !== resolved && fileExists(nfdVariant)) {\n\t\treturn nfdVariant;\n\t}\n\n\t// Try curly quote variant (macOS uses U+2019 in screenshot names)\n\tconst curlyVariant = tryCurlyQuoteVariant(resolved);\n\tif (curlyVariant !== resolved && fileExists(curlyVariant)) {\n\t\treturn curlyVariant;\n\t}\n\n\t// Try combined NFD + curly quote (for French macOS screenshots like \"Capture d'écran\")\n\tconst nfdCurlyVariant = tryCurlyQuoteVariant(nfdVariant);\n\tif (nfdCurlyVariant !== resolved && fileExists(nfdCurlyVariant)) {\n\t\treturn nfdCurlyVariant;\n\t}\n\n\treturn resolved;\n}\n\nexport async function resolveReadPathAsync(filePath: string, cwd: string): Promise<string> {\n\tconst resolved = resolveToCwd(filePath, cwd);\n\n\tif (await pathExists(resolved)) {\n\t\treturn resolved;\n\t}\n\n\t// Try macOS AM/PM variant (narrow no-break space before AM/PM)\n\tconst amPmVariant = tryMacOSScreenshotPath(resolved);\n\tif (amPmVariant !== resolved && (await pathExists(amPmVariant))) {\n\t\treturn amPmVariant;\n\t}\n\n\t// Try NFD variant (macOS stores filenames in NFD form)\n\tconst nfdVariant = tryNFDVariant(resolved);\n\tif (nfdVariant !== resolved && (await pathExists(nfdVariant))) {\n\t\treturn nfdVariant;\n\t}\n\n\t// Try curly quote variant (macOS uses U+2019 in screenshot names)\n\tconst curlyVariant = tryCurlyQuoteVariant(resolved);\n\tif (curlyVariant !== resolved && (await pathExists(curlyVariant))) {\n\t\treturn curlyVariant;\n\t}\n\n\t// Try combined NFD + curly quote (for French macOS screenshots like \"Capture d'écran\")\n\tconst nfdCurlyVariant = tryCurlyQuoteVariant(nfdVariant);\n\tif (nfdCurlyVariant !== resolved && (await pathExists(nfdCurlyVariant))) {\n\t\treturn nfdCurlyVariant;\n\t}\n\n\treturn resolved;\n}\n"]}

package/dist/core/tools/path-utils.js

@@ -0,0 +1,99 @@
+import { accessSync, constants } from "node:fs";
+import { access } from "node:fs/promises";
+import { normalizePath, resolvePath } from "../../utils/paths.js";
+const NARROW_NO_BREAK_SPACE = "\u202F";
+function tryMacOSScreenshotPath(filePath) {
+    return filePath.replace(/ (AM|PM)\./gi, `${NARROW_NO_BREAK_SPACE}$1.`);
+}
+function tryNFDVariant(filePath) {
+    // macOS stores filenames in NFD (decomposed) form, try converting user input to NFD
+    return filePath.normalize("NFD");
+}
+function tryCurlyQuoteVariant(filePath) {
+    // macOS uses U+2019 (right single quotation mark) in screenshot names like "Capture d'écran"
+    // Users typically type U+0027 (straight apostrophe)
+    return filePath.replace(/'/g, "\u2019");
+}
+function fileExists(filePath) {
+    try {
+        accessSync(filePath, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function pathExists(filePath) {
+    try {
+        await access(filePath, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function expandPath(filePath) {
+    return normalizePath(filePath, { normalizeUnicodeSpaces: true, stripAtPrefix: true });
+}
+/**
+ * Resolve a path relative to the given cwd.
+ * Handles ~ expansion and absolute paths.
+ */
+export function resolveToCwd(filePath, cwd) {
+    return resolvePath(filePath, cwd, { normalizeUnicodeSpaces: true, stripAtPrefix: true });
+}
+export function resolveReadPath(filePath, cwd) {
+    const resolved = resolveToCwd(filePath, cwd);
+    if (fileExists(resolved)) {
+        return resolved;
+    }
+    // Try macOS AM/PM variant (narrow no-break space before AM/PM)
+    const amPmVariant = tryMacOSScreenshotPath(resolved);
+    if (amPmVariant !== resolved && fileExists(amPmVariant)) {
+        return amPmVariant;
+    }
+    // Try NFD variant (macOS stores filenames in NFD form)
+    const nfdVariant = tryNFDVariant(resolved);
+    if (nfdVariant !== resolved && fileExists(nfdVariant)) {
+        return nfdVariant;
+    }
+    // Try curly quote variant (macOS uses U+2019 in screenshot names)
+    const curlyVariant = tryCurlyQuoteVariant(resolved);
+    if (curlyVariant !== resolved && fileExists(curlyVariant)) {
+        return curlyVariant;
+    }
+    // Try combined NFD + curly quote (for French macOS screenshots like "Capture d'écran")
+    const nfdCurlyVariant = tryCurlyQuoteVariant(nfdVariant);
+    if (nfdCurlyVariant !== resolved && fileExists(nfdCurlyVariant)) {
+        return nfdCurlyVariant;
+    }
+    return resolved;
+}
+export async function resolveReadPathAsync(filePath, cwd) {
+    const resolved = resolveToCwd(filePath, cwd);
+    if (await pathExists(resolved)) {
+        return resolved;
+    }
+    // Try macOS AM/PM variant (narrow no-break space before AM/PM)
+    const amPmVariant = tryMacOSScreenshotPath(resolved);
+    if (amPmVariant !== resolved && (await pathExists(amPmVariant))) {
+        return amPmVariant;
+    }
+    // Try NFD variant (macOS stores filenames in NFD form)
+    const nfdVariant = tryNFDVariant(resolved);
+    if (nfdVariant !== resolved && (await pathExists(nfdVariant))) {
+        return nfdVariant;
+    }
+    // Try curly quote variant (macOS uses U+2019 in screenshot names)
+    const curlyVariant = tryCurlyQuoteVariant(resolved);
+    if (curlyVariant !== resolved && (await pathExists(curlyVariant))) {
+        return curlyVariant;
+    }
+    // Try combined NFD + curly quote (for French macOS screenshots like "Capture d'écran")
+    const nfdCurlyVariant = tryCurlyQuoteVariant(nfdVariant);
+    if (nfdCurlyVariant !== resolved && (await pathExists(nfdCurlyVariant))) {
+        return nfdCurlyVariant;
+    }
+    return resolved;
+}
+//# sourceMappingURL=path-utils.js.map

package/dist/core/tools/path-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-utils.js","sourceRoot":"","sources":["../../../src/core/tools/path-utils.ts"],"names":[],"mappings":"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","sourcesContent":["import { accessSync, constants } from \"node:fs\";\nimport { access } from \"node:fs/promises\";\nimport { normalizePath, resolvePath } from \"../../utils/paths.ts\";\n\nconst NARROW_NO_BREAK_SPACE = \"\\u202F\";\n\nfunction tryMacOSScreenshotPath(filePath: string): string {\n\treturn filePath.replace(/ (AM|PM)\\./gi, `${NARROW_NO_BREAK_SPACE}$1.`);\n}\n\nfunction tryNFDVariant(filePath: string): string {\n\t// macOS stores filenames in NFD (decomposed) form, try converting user input to NFD\n\treturn filePath.normalize(\"NFD\");\n}\n\nfunction tryCurlyQuoteVariant(filePath: string): string {\n\t// macOS uses U+2019 (right single quotation mark) in screenshot names like \"Capture d'écran\"\n\t// Users typically type U+0027 (straight apostrophe)\n\treturn filePath.replace(/'/g, \"\\u2019\");\n}\n\nfunction fileExists(filePath: string): boolean {\n\ttry {\n\t\taccessSync(filePath, constants.F_OK);\n\t\treturn true;\n\t} catch {\n\t\treturn false;\n\t}\n}\n\nexport async function pathExists(filePath: string): Promise<boolean> {\n\ttry {\n\t\tawait access(filePath, constants.F_OK);\n\t\treturn true;\n\t} catch {\n\t\treturn false;\n\t}\n}\n\nexport function expandPath(filePath: string): string {\n\treturn normalizePath(filePath, { normalizeUnicodeSpaces: true, stripAtPrefix: true });\n}\n\n/**\n * Resolve a path relative to the given cwd.\n * Handles ~ expansion and absolute paths.\n */\nexport function resolveToCwd(filePath: string, cwd: string): string {\n\treturn resolvePath(filePath, cwd, { normalizeUnicodeSpaces: true, stripAtPrefix: true });\n}\n\nexport function resolveReadPath(filePath: string, cwd: string): string {\n\tconst resolved = resolveToCwd(filePath, cwd);\n\n\tif (fileExists(resolved)) {\n\t\treturn resolved;\n\t}\n\n\t// Try macOS AM/PM variant (narrow no-break space before AM/PM)\n\tconst amPmVariant = tryMacOSScreenshotPath(resolved);\n\tif (amPmVariant !== resolved && fileExists(amPmVariant)) {\n\t\treturn amPmVariant;\n\t}\n\n\t// Try NFD variant (macOS stores filenames in NFD form)\n\tconst nfdVariant = tryNFDVariant(resolved);\n\tif (nfdVariant !== resolved && fileExists(nfdVariant)) {\n\t\treturn nfdVariant;\n\t}\n\n\t// Try curly quote variant (macOS uses U+2019 in screenshot names)\n\tconst curlyVariant = tryCurlyQuoteVariant(resolved);\n\tif (curlyVariant !== resolved && fileExists(curlyVariant)) {\n\t\treturn curlyVariant;\n\t}\n\n\t// Try combined NFD + curly quote (for French macOS screenshots like \"Capture d'écran\")\n\tconst nfdCurlyVariant = tryCurlyQuoteVariant(nfdVariant);\n\tif (nfdCurlyVariant !== resolved && fileExists(nfdCurlyVariant)) {\n\t\treturn nfdCurlyVariant;\n\t}\n\n\treturn resolved;\n}\n\nexport async function resolveReadPathAsync(filePath: string, cwd: string): Promise<string> {\n\tconst resolved = resolveToCwd(filePath, cwd);\n\n\tif (await pathExists(resolved)) {\n\t\treturn resolved;\n\t}\n\n\t// Try macOS AM/PM variant (narrow no-break space before AM/PM)\n\tconst amPmVariant = tryMacOSScreenshotPath(resolved);\n\tif (amPmVariant !== resolved && (await pathExists(amPmVariant))) {\n\t\treturn amPmVariant;\n\t}\n\n\t// Try NFD variant (macOS stores filenames in NFD form)\n\tconst nfdVariant = tryNFDVariant(resolved);\n\tif (nfdVariant !== resolved && (await pathExists(nfdVariant))) {\n\t\treturn nfdVariant;\n\t}\n\n\t// Try curly quote variant (macOS uses U+2019 in screenshot names)\n\tconst curlyVariant = tryCurlyQuoteVariant(resolved);\n\tif (curlyVariant !== resolved && (await pathExists(curlyVariant))) {\n\t\treturn curlyVariant;\n\t}\n\n\t// Try combined NFD + curly quote (for French macOS screenshots like \"Capture d'écran\")\n\tconst nfdCurlyVariant = tryCurlyQuoteVariant(nfdVariant);\n\tif (nfdCurlyVariant !== resolved && (await pathExists(nfdCurlyVariant))) {\n\t\treturn nfdCurlyVariant;\n\t}\n\n\treturn resolved;\n}\n"]}