@intentic/fileq 1.317.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Artur Kurowski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,46 @@
+# fileq
+
+A CLI that shows an agent the contents of binary workspace files (Office documents, PDFs, images, audio, archives) as budgeted markdown, cached as sidecars.
+
+```mermaid
+flowchart LR
+    agent["Agent<br/>fileq read"] --> fileq(["fileq"])
+    daemon["Daemon<br/>derive · sweep"] --> fileq
+    git["git diff · show<br/>textconv"] --> fileq
+    fileq --> derivers["Derivers<br/>docx · pdf · xlsx · image …"]
+    fileq --> sidecars["Sidecars<br/>.intentic/local/cache/derived"]
+```
+
+- An agent cannot `cat` a docx or the text layer of a PDF. `fileq <file>` prints a capsule line (title, format,
+  token cost, derived or fresh), then the markdown clipped to `--budget` tokens, and names the sidecar that holds the
+  whole text.
+- Each derivable file gets one sidecar at `.intentic/local/cache/derived/<path>.md`. It is fresh while the source's
+  sha256 and the deriver's version stamp both match, so reading a file twice derives it once. Text is neutralized at
+  write time, because a sidecar is later read as a plain file.
+- The daemon keeps sidecars converged in the background with `fileq derive` and `fileq sweep`
+  (`_sandbox/sandbox/src/derived/`), and imports `./formats` and `./sidecar` so both sides agree on what is derivable.
+- In the sandbox image, `git diff` and `git show` on a document print its text through `fileq read --plain`, wired by
+  `fileq git-attributes`.
+- Out of scope: plain text files (read them directly), web pages ([webq](../webq)), OCR and transcription.
+
+## Usage
+
+```sh
+fileq report.docx                    # capsule + markdown up to 4000 tokens, whole text saved
+fileq read deck.pptx --budget 8000   # a bigger slice on stdout
+```
+
+## Key files
+
+- [src/app.ts](src/app.ts) — the command routes and the `--help` text an agent reads.
+- [src/lib/derive.ts](src/lib/derive.ts) — `ensureSidecar`: the pipeline `read`, `derive` and `sweep` all run.
+- [src/lib/formats.ts](src/lib/formats.ts) — `detectFormat`: magic bytes first, extension as fallback.
+- [src/lib/sidecar.ts](src/lib/sidecar.ts) — sidecar paths, front matter and the freshness rule.
+- [src/lib/derivers/deriver.ts](src/lib/derivers/deriver.ts) — the contract every format handler meets.
+- [src/derivers.integration.test.ts](src/derivers.integration.test.ts) — each format's output, by fixture.
+
+## Commands
+
+```sh
+pnpm --filter @intentic/fileq test
+```

package/dist/app.d.ts

@@ -0,0 +1,2 @@
+export declare const app: import("@stricli/core").Application<import("@stricli/core").CommandContext>;
+//# sourceMappingURL=app.d.ts.map

package/dist/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AA8BA,eAAO,MAAM,GAAG,6EAiBf,CAAC"}

package/dist/app.js

@@ -0,0 +1,43 @@
+import { packageVersion } from "@intentic/agent-cli/version";
+import { buildApplication, buildRouteMap } from "@stricli/core";
+import { deriveCommand } from "./commands/derive.command.js";
+import { gitAttributesCommand } from "./commands/git-attributes.command.js";
+import { readCommand } from "./commands/read.command.js";
+import { sweepCommand } from "./commands/sweep.command.js";
+const HELP = `fileq — binary workspace files as clean, budgeted markdown.
+
+Reads the formats an agent cannot: docx, xlsx, pptx, pdf (text layer), images
+(dimensions + EXIF), audio/video (duration + tags), html. Each workspace file
+gets a markdown SIDECAR under .intentic/local/cache/derived/<path>.md, kept
+fresh by content hash — reading a file twice derives once.
+
+  fileq <file>            print it as markdown (default: read), budgeted
+  fileq read <file> --budget 8000
+  fileq derive <file…>    converge named files' sidecars (stale→derive, gone→remove)
+  fileq sweep             converge the whole workspace, prune orphaned sidecars
+  fileq read --plain <f>  the markdown alone, for a program; git's textconv driver
+  fileq git-attributes    the gitattributes that route documents through it
+
+git diff, git show and git log -p on a document print its text, not "Binary
+files differ": the sandbox names every derivable extension diff=fileq.
+
+Not fileq's business: plain text (read it directly), the open web (webq),
+files needing OCR or transcription (later tiers say so in their sidecars).
+
+Exit codes: 0 content, 1 nothing derivable, 2 broken invocation or install.`;
+export const app = buildApplication(buildRouteMap({
+    routes: {
+        read: readCommand,
+        derive: deriveCommand,
+        sweep: sweepCommand,
+        gitAttributes: gitAttributesCommand,
+    },
+    defaultCommand: "read",
+    docs: { brief: "fileq, agent-native file reading: binary files as clean budgeted markdown", fullDescription: HELP },
+}), {
+    name: "fileq",
+    versionInfo: { currentVersion: packageVersion(import.meta.url) },
+    scanner: { caseStyle: "allow-kebab-for-camel" },
+    determineExitCode: () => 2,
+});
+//# sourceMappingURL=app.js.map

package/dist/app.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AAC5E,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAG3D,MAAM,IAAI,GAAG;;;;;;;;;;;;;;;;;;;;4EAoB+D,CAAC;AAE7E,MAAM,CAAC,MAAM,GAAG,GAAG,gBAAgB,CAC/B,aAAa,CAAC;IACV,MAAM,EAAE;QACJ,IAAI,EAAE,WAAW;QACjB,MAAM,EAAE,aAAa;QACrB,KAAK,EAAE,YAAY;QACnB,aAAa,EAAE,oBAAoB;KACtC;IACD,cAAc,EAAE,MAAM;IACtB,IAAI,EAAE,EAAE,KAAK,EAAE,2EAA2E,EAAE,eAAe,EAAE,IAAI,EAAE;CACtH,CAAC,EACF;IACI,IAAI,EAAE,OAAO;IACb,WAAW,EAAE,EAAE,cAAc,EAAE,cAAc,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,EAAE;IAChE,OAAO,EAAE,EAAE,SAAS,EAAE,uBAAuB,EAAE;IAC/C,iBAAiB,EAAE,GAAG,EAAE,CAAC,CAAC;CAC7B,CACJ,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

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

package/dist/cli.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runAgentCli } from "@intentic/agent-cli/run";
+await runAgentCli({ name: "fileq", noun: "document", load: async () => ({ app: (await import("./app.js")).app }) });
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAGA,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEtD,MAAM,WAAW,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC"}

package/dist/commands/derive.command.d.ts

@@ -0,0 +1,5 @@
+import { type CommandContext } from "@stricli/core";
+import { type Outcome } from "../lib/derive.js";
+export declare const outcomeLine: (outcome: Outcome) => string;
+export declare const deriveCommand: import("@stricli/core").Command<CommandContext>;
+//# sourceMappingURL=derive.command.d.ts.map

package/dist/commands/derive.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive.command.d.ts","sourceRoot":"","sources":["../../src/commands/derive.command.ts"],"names":[],"mappings":"AAEA,OAAO,EAAgB,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAClE,OAAO,EAAiB,KAAK,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAO/D,eAAO,MAAM,WAAW,YAAa,OAAO,KAAG,MAW9C,CAAC;AAEF,eAAO,MAAM,aAAa,iDAmCxB,CAAC"}

package/dist/commands/derive.command.js

@@ -0,0 +1,53 @@
+import { resolve } from "node:path";
+import { buildCommand } from "@stricli/core";
+import { ensureSidecar } from "../lib/derive.js";
+import { workspaceRoot } from "../lib/env.js";
+export const outcomeLine = (outcome) => {
+    switch (outcome.kind) {
+        case "derived":
+            return `derived ${outcome.relPath} -> ${outcome.sidecarPath} (${outcome.tokens} tokens)`;
+        case "fresh":
+            return `fresh ${outcome.relPath}`;
+        case "removed":
+            return `removed ${outcome.relPath} (source gone)`;
+        case "skipped":
+            return `skipped ${outcome.relPath}: ${outcome.reason}`;
+    }
+};
+export const deriveCommand = buildCommand({
+    docs: { brief: "Converge sidecars for the named files (derive stale, remove orphaned, skip fresh)" },
+    parameters: {
+        flags: {
+            json: { kind: "boolean", default: false, brief: "One JSON object per line" },
+        },
+        positional: { kind: "array", parameter: { parse: String, brief: "Files to converge, workspace-root-relative (the watcher's own namespace) or absolute", placeholder: "file" } },
+    },
+    async func(flags, ...files) {
+        const root = workspaceRoot();
+        if (root === undefined) {
+            this.process.stdout.write("fileq: derive needs a workspace (WORKSPACE_ROOT is not set); use `fileq read` for one-off files\n");
+            process.exitCode = 2;
+            return;
+        }
+        if (files.length === 0) {
+            this.process.stdout.write("fileq: derive takes file paths (or run `fileq sweep` for the whole workspace)\n");
+            process.exitCode = 2;
+            return;
+        }
+        let useful = 0;
+        for (const file of files) {
+            const outcome = await ensureSidecar(root, resolve(root, file));
+            if (outcome.kind !== "skipped") {
+                useful += 1;
+            }
+            if (flags.json) {
+                this.process.stdout.write(`${JSON.stringify(outcome.kind === "derived" ? { ...outcome, doc: undefined, body: undefined } : outcome)}\n`);
+            }
+            else {
+                this.process.stdout.write(`${outcomeLine(outcome)}\n`);
+            }
+        }
+        process.exitCode = useful > 0 ? 0 : 1;
+    },
+});
+//# sourceMappingURL=derive.command.js.map

package/dist/commands/derive.command.js.map

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

package/dist/commands/git-attributes.command.d.ts

@@ -0,0 +1,3 @@
+import { type CommandContext } from "@stricli/core";
+export declare const gitAttributesCommand: import("@stricli/core").Command<CommandContext>;
+//# sourceMappingURL=git-attributes.command.d.ts.map

package/dist/commands/git-attributes.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-attributes.command.d.ts","sourceRoot":"","sources":["../../src/commands/git-attributes.command.ts"],"names":[],"mappings":"AACA,OAAO,EAAgB,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAGlE,eAAO,MAAM,oBAAoB,iDAQ/B,CAAC"}

package/dist/commands/git-attributes.command.js

@@ -0,0 +1,12 @@
+import { buildCommand } from "@stricli/core";
+import { gitAttributeLines } from "../lib/formats.js";
+export const gitAttributesCommand = buildCommand({
+    docs: {
+        brief: "Print gitattributes marking every derivable format `diff=fileq`, for a `diff.fileq.textconv` of `fileq read --plain`",
+    },
+    parameters: { positional: { kind: "tuple", parameters: [] } },
+    func() {
+        this.process.stdout.write(`${gitAttributeLines().join("\n")}\n`);
+    },
+});
+//# sourceMappingURL=git-attributes.command.js.map

package/dist/commands/git-attributes.command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-attributes.command.js","sourceRoot":"","sources":["../../src/commands/git-attributes.command.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAuB,MAAM,eAAe,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD,MAAM,CAAC,MAAM,oBAAoB,GAAG,YAAY,CAAC;IAC7C,IAAI,EAAE;QACF,KAAK,EAAE,sHAAsH;KAChI;IACD,UAAU,EAAE,EAAE,UAAU,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE,EAAE,EAAE;IAC7D,IAAI;QACA,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,iBAAiB,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrE,CAAC;CACJ,CAAC,CAAC"}

package/dist/commands/read.command.d.ts

@@ -0,0 +1,3 @@
+import { type CommandContext } from "@stricli/core";
+export declare const readCommand: import("@stricli/core").Command<CommandContext>;
+//# sourceMappingURL=read.command.d.ts.map

package/dist/commands/read.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.command.d.ts","sourceRoot":"","sources":["../../src/commands/read.command.ts"],"names":[],"mappings":"AAQA,OAAO,EAAgB,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAalE,eAAO,MAAM,WAAW,iDAwCtB,CAAC"}

package/dist/commands/read.command.js

@@ -0,0 +1,126 @@
+import { createHash } from "node:crypto";
+import { mkdir, writeFile } from "node:fs/promises";
+import { basename, join, resolve } from "node:path";
+import { toolOutDir } from "@intentic/agent-cli/env";
+import { countParser } from "@intentic/agent-cli/flags";
+import { capsule, clip } from "@intentic/agent-cli/output";
+import { estimateTokens } from "@intentic/base/format";
+import { buildCommand } from "@stricli/core";
+import { errorMessage } from "@intentic/base/errors";
+import { deriverStamp, neutralizeDoc } from "../lib/derivers/deriver.js";
+import { detectFormat } from "../lib/formats.js";
+import { DERIVERS, ensureSidecar } from "../lib/derive.js";
+import { workspaceRoot } from "../lib/env.js";
+export const readCommand = buildCommand({
+    docs: { brief: "One file as clean markdown: budgeted on stdout, whole in its sidecar" },
+    parameters: {
+        flags: {
+            budget: { kind: "parsed", parse: countParser, default: "4000", brief: "Max stdout tokens; 0 prints only the capsule" },
+            json: { kind: "boolean", default: false, brief: "Machine-readable result on stdout" },
+            plain: { kind: "boolean", default: false, brief: "The markdown alone, whole and unbudgeted; nothing saved for a file outside the workspace (git textconv)" },
+        },
+        positional: {
+            kind: "tuple",
+            parameters: [{ parse: String, brief: "The file to read (relative paths resolve against the cwd)", placeholder: "file" }],
+        },
+    },
+    async func(flags, file) {
+        const absPath = resolve(file);
+        const root = workspaceRoot();
+        const save = !flags.plain;
+        const result = root === undefined ? await readOutsideWorkspace(absPath, save) : await readInWorkspace(root, absPath, save);
+        if (result === undefined) {
+            process.exitCode = 1;
+            return;
+        }
+        if (flags.plain) {
+            this.process.stdout.write(result.body === "" ? "" : `${result.body}\n`);
+            return;
+        }
+        if (flags.json) {
+            this.process.stdout.write(`${JSON.stringify({ file: absPath, format: result.format, deriver: result.deriver, tokens: result.tokens, path: result.savedPath, source: result.source, notes: result.notes })}\n`);
+            return;
+        }
+        const fields = [result.title ?? basename(absPath), result.format, `${result.tokens} tokens`, result.source];
+        this.process.stdout.write(capsule("fileq", fields, result.notes));
+        this.process.stdout.write(`saved: ${result.savedPath}\n`);
+        if (flags.budget > 0 && result.body !== "") {
+            this.process.stdout.write("---\n");
+            this.process.stdout.write(withFinalNewline(clip(result.body, flags.budget, result.savedPath, "document")));
+        }
+    },
+});
+const readInWorkspace = async (root, absPath, save) => {
+    const outcome = await ensureSidecar(root, absPath);
+    if (outcome.kind === "skipped" && outcome.reason === "outside-workspace") {
+        return readOutsideWorkspace(absPath, save);
+    }
+    return fromOutcome(outcome);
+};
+const fromOutcome = (outcome) => {
+    switch (outcome.kind) {
+        case "derived":
+            return {
+                format: outcome.format,
+                deriver: deriverStamp(DERIVERS[outcome.format]),
+                body: outcome.body,
+                tokens: outcome.tokens,
+                savedPath: outcome.sidecarPath,
+                source: "derived",
+                title: outcome.doc.title,
+                notes: outcome.doc.notes,
+            };
+        case "fresh":
+            return {
+                format: outcome.format,
+                deriver: deriverStamp(DERIVERS[outcome.format]),
+                body: outcome.body,
+                tokens: outcome.tokens,
+                savedPath: outcome.sidecarPath,
+                source: "fresh",
+                notes: [],
+            };
+        case "removed":
+        case "skipped": {
+            const reason = outcome.kind === "removed" ? "missing" : outcome.reason;
+            process.stdout.write(`fileq: cannot read ${outcome.relPath}: ${reason}\n`);
+            return undefined;
+        }
+    }
+};
+const readOutsideWorkspace = async (absPath, save) => {
+    const format = await detectFormat(absPath).catch(() => undefined);
+    if (format === undefined) {
+        process.stdout.write(`fileq: cannot read ${absPath}: unsupported or missing\n`);
+        return undefined;
+    }
+    let doc;
+    try {
+        doc = neutralizeDoc(await DERIVERS[format].derive(absPath));
+    }
+    catch (error) {
+        process.stdout.write(`fileq: cannot read ${absPath}: derive-failed (${format}): ${errorMessage(error).split("\n")[0]}\n`);
+        return undefined;
+    }
+    const outDir = toolOutDir("fileq");
+    const hash = createHash("sha256").update(absPath).digest("hex").slice(0, 8);
+    const savedPath = join(outDir, `${basename(absPath)
+        .toLowerCase()
+        .replaceAll(/[^a-z0-9.]+/g, "-")}-${hash}.md`);
+    if (save) {
+        await mkdir(outDir, { recursive: true });
+        await writeFile(savedPath, `${doc.markdown}\n`);
+    }
+    return {
+        format,
+        deriver: deriverStamp(DERIVERS[format]),
+        body: doc.markdown,
+        tokens: estimateTokens(doc.markdown),
+        savedPath,
+        source: "derived",
+        title: doc.title,
+        notes: doc.notes,
+    };
+};
+const withFinalNewline = (text) => (text.endsWith("\n") ? text : `${text}\n`);
+//# sourceMappingURL=read.command.js.map

package/dist/commands/read.command.js.map

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

package/dist/commands/sweep.command.d.ts

@@ -0,0 +1,3 @@
+import { type CommandContext } from "@stricli/core";
+export declare const sweepCommand: import("@stricli/core").Command<CommandContext>;
+//# sourceMappingURL=sweep.command.d.ts.map

package/dist/commands/sweep.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sweep.command.d.ts","sourceRoot":"","sources":["../../src/commands/sweep.command.ts"],"names":[],"mappings":"AACA,OAAO,EAAgB,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAUlE,eAAO,MAAM,YAAY,iDAoCvB,CAAC"}

package/dist/commands/sweep.command.js

@@ -0,0 +1,41 @@
+import { buildCommand } from "@stricli/core";
+import { sweep } from "../lib/sweep.js";
+import { workspaceRoot } from "../lib/env.js";
+import { outcomeLine } from "./derive.command.js";
+export const sweepCommand = buildCommand({
+    docs: { brief: "Converge every derivable workspace file's sidecar; prune shadows of deleted files" },
+    parameters: {
+        flags: {
+            json: { kind: "boolean", default: false, brief: "Machine-readable summary on stdout" },
+            quiet: { kind: "boolean", default: false, brief: "Totals only, no per-file lines" },
+        },
+        positional: { kind: "tuple", parameters: [] },
+    },
+    async func(flags) {
+        const root = workspaceRoot();
+        if (root === undefined) {
+            this.process.stdout.write("fileq: sweep needs a workspace (WORKSPACE_ROOT is not set)\n");
+            process.exitCode = 2;
+            return;
+        }
+        const result = await sweep(root, (outcome) => {
+            if (!flags.quiet && !flags.json && outcome.kind !== "fresh") {
+                this.process.stdout.write(`${outcomeLine(outcome)}\n`);
+            }
+        });
+        const counts = { derived: 0, fresh: 0, removed: 0, skipped: 0 };
+        for (const outcome of result.outcomes) {
+            counts[outcome.kind] += 1;
+        }
+        if (flags.json) {
+            this.process.stdout.write(`${JSON.stringify({ ...counts, pruned: result.pruned.length })}\n`);
+        }
+        else {
+            for (const relPath of result.pruned) {
+                this.process.stdout.write(`pruned ${relPath} (source gone)\n`);
+            }
+            this.process.stdout.write(`sweep: ${counts.derived} derived, ${counts.fresh} fresh, ${counts.removed + result.pruned.length} removed, ${counts.skipped} skipped\n`);
+        }
+    },
+});
+//# sourceMappingURL=sweep.command.js.map

package/dist/commands/sweep.command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sweep.command.js","sourceRoot":"","sources":["../../src/commands/sweep.command.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAuB,MAAM,eAAe,CAAC;AAClE,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AACxC,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAOlD,MAAM,CAAC,MAAM,YAAY,GAAG,YAAY,CAAC;IACrC,IAAI,EAAE,EAAE,KAAK,EAAE,mFAAmF,EAAE;IACpG,UAAU,EAAE;QACR,KAAK,EAAE;YACH,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,oCAAoC,EAAE;YACtF,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,gCAAgC,EAAE;SACtF;QACD,UAAU,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE,EAAE;KAChD;IACD,KAAK,CAAC,IAAI,CAAuB,KAAiB;QAC9C,MAAM,IAAI,GAAG,aAAa,EAAE,CAAC;QAC7B,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACrB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,8DAA8D,CAAC,CAAC;YAC1F,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;YACrB,OAAO;QACX,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,EAAE;YACzC,IAAI,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;gBAC1D,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YAC3D,CAAC;QACL,CAAC,CAAC,CAAC;QACH,MAAM,MAAM,GAAG,EAAE,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;QAChE,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;YACpC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC9B,CAAC;QACD,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;YACb,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC;QAClG,CAAC;aAAM,CAAC;YACJ,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;gBAClC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,OAAO,kBAAkB,CAAC,CAAC;YACnE,CAAC;YACD,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CACrB,UAAU,MAAM,CAAC,OAAO,aAAa,MAAM,CAAC,KAAK,WAAW,MAAM,CAAC,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,aAAa,MAAM,CAAC,OAAO,YAAY,CAC3I,CAAC;QACN,CAAC;IACL,CAAC;CACJ,CAAC,CAAC"}

package/dist/lib/archives.d.ts

@@ -0,0 +1,18 @@
+export interface ArchiveEntry {
+    readonly path: string;
+    readonly size: number | undefined;
+    readonly packed: number | undefined;
+    readonly directory: boolean;
+}
+export declare const zipEntries: (bytes: Uint8Array) => ArchiveEntry[];
+export declare const looksLikeTar: (bytes: Uint8Array) => boolean;
+export declare const tarEntries: (bytes: Uint8Array) => ArchiveEntry[];
+export interface GzipHead {
+    readonly name: string | undefined;
+    readonly unpackedBytes: number;
+}
+export declare const gzipHead: (bytes: Uint8Array) => GzipHead | undefined;
+export declare const tarOnPath: () => boolean;
+export declare const parseTarListing: (stdout: string) => ArchiveEntry[];
+export declare const listWithTar: (absPath: string) => Promise<ArchiveEntry[]>;
+//# sourceMappingURL=archives.d.ts.map

package/dist/lib/archives.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archives.d.ts","sourceRoot":"","sources":["../../src/lib/archives.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,YAAY;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAElC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC/B;AAGD,eAAO,MAAM,UAAU,UAAW,UAAU,KAAG,YAAY,EAS1D,CAAC;AAiCF,eAAO,MAAM,YAAY,UAAW,UAAU,KAAG,OAAqG,CAAC;AAiEvJ,eAAO,MAAM,UAAU,UAAW,UAAU,KAAG,YAAY,EAkB1D,CAAC;AAEF,MAAM,WAAW,QAAQ;IAErB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAElC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAClC;AAcD,eAAO,MAAM,QAAQ,UAAW,UAAU,KAAG,QAAQ,GAAG,SAMvD,CAAC;AAGF,eAAO,MAAM,SAAS,QAAO,OAAwB,CAAC;AAOtD,eAAO,MAAM,eAAe,WAAY,MAAM,KAAG,YAAY,EAa5D,CAAC;AAOF,eAAO,MAAM,WAAW,YAAmB,MAAM,KAAG,OAAO,CAAC,YAAY,EAAE,CAGzE,CAAC"}

package/dist/lib/archives.js

@@ -0,0 +1,133 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { unzipSync } from "fflate";
+import { onPath } from "./tools.js";
+const run = promisify(execFile);
+export const zipEntries = (bytes) => {
+    const entries = [];
+    unzipSync(bytes, {
+        filter: (file) => {
+            entries.push({ path: file.name, size: file.originalSize, packed: file.size, directory: file.name.endsWith("/") });
+            return false;
+        },
+    });
+    return entries;
+};
+const BLOCK = 512;
+const decoder = new TextDecoder();
+const field = (bytes, offset, length) => {
+    const raw = bytes.subarray(offset, offset + length);
+    const end = raw.indexOf(0);
+    return decoder.decode(end === -1 ? raw : raw.subarray(0, end)).trim();
+};
+const octal = (bytes, offset, length) => {
+    const text = field(bytes, offset, length).replaceAll(/[^0-7]/g, "");
+    return text === "" ? 0 : Number.parseInt(text, 8);
+};
+const headerChecks = (block) => {
+    if (block.length < BLOCK) {
+        return false;
+    }
+    let sum = 0;
+    for (let index = 0; index < BLOCK; index++) {
+        sum += index >= 148 && index < 156 ? 0x20 : (block[index] ?? 0);
+    }
+    return sum === octal(block, 148, 8);
+};
+export const looksLikeTar = (bytes) => bytes.length >= BLOCK && (field(bytes, 257, 6).startsWith("ustar") || headerChecks(bytes));
+const paxPath = (data) => {
+    for (const record of decoder.decode(data).split("\n")) {
+        const match = /^\d+ path=(.*)$/.exec(record);
+        if (match !== null) {
+            return match[1];
+        }
+    }
+    return undefined;
+};
+const blockAt = (bytes, offset) => {
+    if (offset + BLOCK > bytes.length) {
+        return undefined;
+    }
+    const header = bytes.subarray(offset, offset + BLOCK);
+    if (header.every((byte) => byte === 0)) {
+        return undefined;
+    }
+    const size = octal(header, 124, 12);
+    return {
+        header,
+        type: field(header, 156, 1),
+        size,
+        data: bytes.subarray(offset + BLOCK, offset + BLOCK + size),
+        next: offset + BLOCK + Math.ceil(size / BLOCK) * BLOCK,
+    };
+};
+const NAME_CARRIERS = new Set(["L", "x", "X", "g"]);
+const carriedName = (block, current) => {
+    if (block.type === "L") {
+        return field(block.data, 0, block.data.length);
+    }
+    return block.type === "g" ? current : (paxPath(block.data) ?? current);
+};
+const entryOf = (block, carried) => {
+    const prefix = field(block.header, 345, 155);
+    const name = field(block.header, 0, 100);
+    const path = carried ?? (prefix === "" ? name : `${prefix}/${name}`);
+    const directory = block.type === "5" || path.endsWith("/");
+    return { path, size: directory ? undefined : block.size, packed: undefined, directory };
+};
+export const tarEntries = (bytes) => {
+    if (!looksLikeTar(bytes)) {
+        throw new Error("not a tar archive: no header block at the start");
+    }
+    const entries = [];
+    let carried;
+    let offset = 0;
+    for (let block = blockAt(bytes, offset); block !== undefined; block = blockAt(bytes, offset)) {
+        offset = block.next;
+        if (NAME_CARRIERS.has(block.type)) {
+            carried = carriedName(block, carried);
+            continue;
+        }
+        entries.push(entryOf(block, carried));
+        carried = undefined;
+    }
+    return entries;
+};
+const gzipName = (bytes, flags) => {
+    if ((flags & 0x08) === 0) {
+        return undefined;
+    }
+    const extra = (flags & 0x04) === 0 ? 0 : 2 + ((bytes[10] ?? 0) | ((bytes[11] ?? 0) << 8));
+    const end = bytes.indexOf(0, 10 + extra);
+    const name = end === -1 ? "" : decoder.decode(bytes.subarray(10 + extra, end));
+    return name === "" ? undefined : name;
+};
+export const gzipHead = (bytes) => {
+    if (bytes.length < 18 || bytes[0] !== 0x1f || bytes[1] !== 0x8b) {
+        return undefined;
+    }
+    const view = new DataView(bytes.buffer, bytes.byteOffset + bytes.length - 4, 4);
+    return { name: gzipName(bytes, bytes[3] ?? 0), unpackedBytes: view.getUint32(0, true) };
+};
+export const tarOnPath = () => onPath("tar");
+const LISTING_LINE = /^(\S+)\s+\S+\s+(\d+)\s+\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}(?::\d{2})?\s+(.+)$/;
+export const parseTarListing = (stdout) => {
+    const entries = [];
+    for (const line of stdout.split("\n")) {
+        const match = LISTING_LINE.exec(line);
+        if (match === null) {
+            continue;
+        }
+        const [, mode = "", size = "0", path = ""] = match;
+        const directory = mode.startsWith("d");
+        entries.push({ path: path.split(" -> ")[0] ?? path, size: directory ? undefined : Number(size), packed: undefined, directory });
+    }
+    return entries;
+};
+const TAR_TIMEOUT_MS = 60_000;
+const TAR_MAX_BUFFER = 16 * 1024 * 1024;
+export const listWithTar = async (absPath) => {
+    const { stdout } = await run("tar", ["-tvf", absPath], { timeout: TAR_TIMEOUT_MS, maxBuffer: TAR_MAX_BUFFER });
+    return parseTarListing(stdout);
+};
+//# sourceMappingURL=archives.js.map

package/dist/lib/archives.js.map

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