@pikku/cli 0.12.126 → 0.12.127

package/dist/src/fabric/fabric-commands.js

@@ -46,6 +46,10 @@ import { FabricValidate, renderValidate, } from './functions/validate.function.j
 import { FabricSmoke, renderSmoke } from './functions/smoke.function.js';
 import { FabricPublish } from './functions/publish.function.js';
 import { FabricAdd } from './functions/add.function.js';
+import { FabricReport } from './functions/report.function.js';
+import { FabricFindingsList, renderFindingsList, } from './functions/findings-list.function.js';
+import { FabricFindingsFlush } from './functions/findings-flush.function.js';
+import { FabricFindingsClear } from './functions/findings-clear.function.js';
 import { FabricAddonVerify, renderAddonVerify, } from './functions/addon-verify.function.js';
 export const fabricCommands = defineCLICommands({
     validate: pikkuCLICommand({
@@ -302,6 +306,67 @@ export const fabricCommands = defineCLICommands({
             json: { description: 'Machine-readable output', default: false },
         },
     }),
+    report: pikkuCLICommand({
+        parameters: '[title]',
+        func: FabricReport,
+        description: 'Report a finding — something about pikku that cost time — to fabric',
+        options: {
+            stdin: {
+                description: 'Read the whole finding as JSON on stdin instead of from flags (prose survives the shell intact)',
+                default: false,
+            },
+            kind: {
+                description: 'product (fix pikku) or harness (fix the skill that misled you)',
+            },
+            model: { description: 'The model that hit this' },
+            expected: { description: 'What you expected pikku to do' },
+            actual: { description: 'What it did instead' },
+            skill: {
+                description: 'For a harness finding, the skill that misled you',
+            },
+            passage: { description: 'The passage in that skill it contradicts' },
+            command: { description: 'The command you ran' },
+            error: { description: "The error's message line, verbatim" },
+            repro: { description: 'The shortest way to reach it again' },
+            workaround: { description: 'What you did instead, inside the app' },
+            proposal: {
+                description: 'What pikku should do — named file and function, mechanism, suggested change',
+            },
+            tried: {
+                description: 'For an unresolved finding, what you tried and how each attempt failed',
+            },
+            unresolved: {
+                description: 'No workaround was found — a blocker, not a tax',
+                default: false,
+            },
+            area: { description: 'The part of pikku this is about' },
+            surface: { description: 'Where it showed up: local, deployed or both' },
+            cost: { description: 'What it cost, measured or estimated' },
+            run: { description: 'Run id, to group findings from one build' },
+            deployTarget: { description: 'The deploy target in use' },
+        },
+    }),
+    findings: {
+        description: 'Inspect the findings held locally because they could not be sent',
+        subcommands: {
+            list: pikkuCLICommand({
+                func: FabricFindingsList,
+                render: renderFindingsList,
+                description: 'List the findings queued locally, waiting to be sent',
+            }),
+            flush: pikkuCLICommand({
+                func: FabricFindingsFlush,
+                description: 'Send every finding queued locally',
+                options: {
+                    apiUrl: { description: 'Override the fabric-api URL for this call' },
+                },
+            }),
+            clear: pikkuCLICommand({
+                func: FabricFindingsClear,
+                description: 'Discard every queued finding without sending it',
+            }),
+        },
+    },
     metrics: pikkuCLICommand({
         func: FabricMetrics,
         description: 'Show request rate / error rate / latency for a stage',

package/dist/src/fabric/functions/findings-clear.function.d.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+export declare const FabricFindingsClearInput: z.ZodObject<{}, z.core.$strip>;
+export declare const FabricFindingsClearOutput: z.ZodObject<{
+    dropped: z.ZodNumber;
+}, z.core.$strip>;
+export declare const FabricFindingsClear: import("../../../.pikku/function/pikku-function-types.gen.js").PikkuFunctionConfig<Record<string, never>, {
+    dropped: number;
+}, "rpc" | "session", import("../../../.pikku/function/pikku-function-types.gen.js").PikkuFunctionSessionless<Record<string, never>, {
+    dropped: number;
+}, "rpc" | "session", import("../../../.pikku/function/pikku-function-types.gen.js").WiredServices, unknown> | import("../../../.pikku/function/pikku-function-types.gen.js").PikkuFunction<Record<string, never>, {
+    dropped: number;
+}, "rpc" | "session", import("../../../.pikku/function/pikku-function-types.gen.js").WiredServices>, undefined, undefined>;

package/dist/src/fabric/functions/findings-clear.function.js

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+import { pikkuSessionlessFunc } from '../../../.pikku/function/index.js';
+import { clearSpool } from '../lib/finding-spool.js';
+export const FabricFindingsClearInput = z.object({});
+export const FabricFindingsClearOutput = z.object({
+    dropped: z.number(),
+});
+export const FabricFindingsClear = pikkuSessionlessFunc({
+    description: 'Discard every finding queued locally without sending it.',
+    input: FabricFindingsClearInput,
+    output: FabricFindingsClearOutput,
+    func: async () => {
+        const dropped = await clearSpool();
+        console.log(`[fabric] dropped ${dropped} queued finding(s)`);
+        return { dropped };
+    },
+});

package/dist/src/fabric/functions/findings-flush.function.d.ts

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+export declare const FabricFindingsFlushInput: z.ZodObject<{
+    apiUrl: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const FabricFindingsFlushOutput: z.ZodObject<{
+    sent: z.ZodNumber;
+    remaining: z.ZodNumber;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Explicitly asked for, so unlike `report` this one says plainly that it
+ * cannot run: someone who typed `flush` wants to know the login is missing,
+ * not to have the queue quietly stay put.
+ */
+export declare const FabricFindingsFlush: import("../../../.pikku/function/pikku-function-types.gen.js").PikkuFunctionConfig<{
+    apiUrl?: string | undefined;
+}, {
+    sent: number;
+    remaining: number;
+    reason?: string | undefined;
+}, "rpc" | "session", import("../../../.pikku/function/pikku-function-types.gen.js").PikkuFunctionSessionless<{
+    apiUrl?: string | undefined;
+}, {
+    sent: number;
+    remaining: number;
+    reason?: string | undefined;
+}, "rpc" | "session", import("../../../.pikku/function/pikku-function-types.gen.js").WiredServices, unknown> | import("../../../.pikku/function/pikku-function-types.gen.js").PikkuFunction<{
+    apiUrl?: string | undefined;
+}, {
+    sent: number;
+    remaining: number;
+    reason?: string | undefined;
+}, "rpc" | "session", import("../../../.pikku/function/pikku-function-types.gen.js").WiredServices>, undefined, undefined>;

package/dist/src/fabric/functions/findings-flush.function.js

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+import { pikkuSessionlessFunc } from '../../../.pikku/function/index.js';
+import { resolveApiContext } from '../lib/config.js';
+import { flushSpool } from '../lib/finding-spool.js';
+export const FabricFindingsFlushInput = z.object({
+    apiUrl: z.string().optional(),
+});
+export const FabricFindingsFlushOutput = z.object({
+    sent: z.number(),
+    remaining: z.number(),
+    reason: z.string().optional(),
+});
+/**
+ * Explicitly asked for, so unlike `report` this one says plainly that it
+ * cannot run: someone who typed `flush` wants to know the login is missing,
+ * not to have the queue quietly stay put.
+ */
+export const FabricFindingsFlush = pikkuSessionlessFunc({
+    description: 'Send every finding queued locally.',
+    input: FabricFindingsFlushInput,
+    output: FabricFindingsFlushOutput,
+    func: async (_services, { apiUrl: apiUrlOverride }) => {
+        const ctx = await resolveApiContext({ apiUrlOverride });
+        if (!ctx.token)
+            throw new Error('Not logged in. Run `pikku fabric login` first.');
+        const result = await flushSpool({
+            apiUrl: ctx.apiUrl,
+            token: ctx.token,
+            projectId: ctx.projectId,
+        });
+        console.log(result.remaining === 0
+            ? `[fabric] sent ${result.sent} finding(s)`
+            : `[fabric] sent ${result.sent}, ${result.remaining} still queued (${result.reason})`);
+        return result;
+    },
+});

package/dist/src/fabric/functions/findings-list.function.d.ts

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+export declare const FabricFindingsListInput: z.ZodObject<{}, z.core.$strip>;
+export declare const FabricFindingsListOutput: z.ZodObject<{
+    findings: z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        kind: z.ZodString;
+        reason: z.ZodString;
+        reportedAt: z.ZodString;
+        projectId: z.ZodNullable<z.ZodString>;
+        file: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * What is waiting to be sent. Without this the spool is invisible, and an
+ * agent has no way to tell a finding that reached fabric from one still
+ * sitting on the machine.
+ */
+export declare const FabricFindingsList: import("../../../.pikku/function/pikku-function-types.gen.js").PikkuFunctionConfig<Record<string, never>, {
+    findings: {
+        title: string;
+        kind: string;
+        reason: string;
+        reportedAt: string;
+        projectId: string | null;
+        file: string;
+    }[];
+}, "rpc" | "session", import("../../../.pikku/function/pikku-function-types.gen.js").PikkuFunctionSessionless<Record<string, never>, {
+    findings: {
+        title: string;
+        kind: string;
+        reason: string;
+        reportedAt: string;
+        projectId: string | null;
+        file: string;
+    }[];
+}, "rpc" | "session", import("../../../.pikku/function/pikku-function-types.gen.js").WiredServices, unknown> | import("../../../.pikku/function/pikku-function-types.gen.js").PikkuFunction<Record<string, never>, {
+    findings: {
+        title: string;
+        kind: string;
+        reason: string;
+        reportedAt: string;
+        projectId: string | null;
+        file: string;
+    }[];
+}, "rpc" | "session", import("../../../.pikku/function/pikku-function-types.gen.js").WiredServices>, undefined, undefined>;
+type QueuedFinding = {
+    title: string;
+    kind: string;
+    reason: string;
+    reportedAt: string;
+};
+export declare const renderFindingsList: (_s: unknown, { findings }: {
+    findings: QueuedFinding[];
+}) => void;
+export {};

package/dist/src/fabric/functions/findings-list.function.js

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+import { pikkuSessionlessFunc } from '../../../.pikku/function/index.js';
+import { readSpool } from '../lib/finding-spool.js';
+import { dim, table } from '../lib/output.js';
+export const FabricFindingsListInput = z.object({});
+export const FabricFindingsListOutput = z.object({
+    findings: z.array(z.object({
+        title: z.string(),
+        kind: z.string(),
+        reason: z.string(),
+        reportedAt: z.string(),
+        projectId: z.string().nullable(),
+        file: z.string(),
+    })),
+});
+/**
+ * What is waiting to be sent. Without this the spool is invisible, and an
+ * agent has no way to tell a finding that reached fabric from one still
+ * sitting on the machine.
+ */
+export const FabricFindingsList = pikkuSessionlessFunc({
+    description: 'List the findings queued locally, waiting to be sent.',
+    input: FabricFindingsListInput,
+    output: FabricFindingsListOutput,
+    func: async () => ({
+        findings: (await readSpool()).map((entry) => ({
+            title: entry.payload.title,
+            kind: entry.payload.kind,
+            reason: entry.reason,
+            reportedAt: entry.payload.reportedAt,
+            projectId: entry.projectId,
+            file: entry.file,
+        })),
+    }),
+});
+export const renderFindingsList = (_s, { findings }) => {
+    console.log('');
+    if (findings.length === 0) {
+        console.log(dim('  Nothing queued — every finding you filed was sent.'));
+        console.log('');
+        return;
+    }
+    console.log(table(['REPORTED', 'KIND', 'HELD BECAUSE', 'TITLE'], findings.map((f) => [
+        f.reportedAt.slice(0, 16).replace('T', ' '),
+        f.kind,
+        f.reason,
+        f.title,
+    ])));
+    console.log('');
+    console.log(dim('  `pikku fabric findings flush` sends them.'));
+    console.log('');
+};

package/dist/src/fabric/functions/report.function.d.ts

@@ -0,0 +1,121 @@
+import { z } from 'zod';
+/**
+ * Every field is optional here and the strictness lives in `FindingInput`,
+ * because `--stdin` supplies the whole finding at once and the flags then
+ * carry nothing. Whichever path was used, the same schema decides whether a
+ * finding is well-formed.
+ */
+export declare const FabricReportInput: z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    kind: z.ZodOptional<z.ZodEnum<{
+        product: "product";
+        harness: "harness";
+    }>>;
+    model: z.ZodOptional<z.ZodString>;
+    expected: z.ZodOptional<z.ZodString>;
+    actual: z.ZodOptional<z.ZodString>;
+    skill: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    passage: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    command: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    error: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    repro: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    workaround: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    proposal: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    tried: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    unresolved: z.ZodOptional<z.ZodOptional<z.ZodBoolean>>;
+    area: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    surface: z.ZodOptional<z.ZodOptional<z.ZodEnum<{
+        local: "local";
+        deployed: "deployed";
+        both: "both";
+    }>>>;
+    cost: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    run: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    deployTarget: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    stdin: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const FabricReportOutput: z.ZodObject<{
+    sent: z.ZodBoolean;
+    reason: z.ZodOptional<z.ZodString>;
+    spooled: z.ZodBoolean;
+    queued: z.ZodNumber;
+}, z.core.$strip>;
+export declare const FabricReport: import("../../../.pikku/function/pikku-function-types.gen.js").PikkuFunctionConfig<{
+    title?: string | undefined;
+    kind?: "product" | "harness" | undefined;
+    model?: string | undefined;
+    expected?: string | undefined;
+    actual?: string | undefined;
+    skill?: string | undefined;
+    passage?: string | undefined;
+    command?: string | undefined;
+    error?: string | undefined;
+    repro?: string | undefined;
+    workaround?: string | undefined;
+    proposal?: string | undefined;
+    tried?: string | undefined;
+    unresolved?: boolean | undefined;
+    area?: string | undefined;
+    surface?: "local" | "deployed" | "both" | undefined;
+    cost?: string | undefined;
+    run?: string | undefined;
+    deployTarget?: string | undefined;
+    stdin?: boolean | undefined;
+}, {
+    sent: boolean;
+    spooled: boolean;
+    queued: number;
+    reason?: string | undefined;
+}, "rpc" | "session", import("../../../.pikku/function/pikku-function-types.gen.js").PikkuFunctionSessionless<{
+    title?: string | undefined;
+    kind?: "product" | "harness" | undefined;
+    model?: string | undefined;
+    expected?: string | undefined;
+    actual?: string | undefined;
+    skill?: string | undefined;
+    passage?: string | undefined;
+    command?: string | undefined;
+    error?: string | undefined;
+    repro?: string | undefined;
+    workaround?: string | undefined;
+    proposal?: string | undefined;
+    tried?: string | undefined;
+    unresolved?: boolean | undefined;
+    area?: string | undefined;
+    surface?: "local" | "deployed" | "both" | undefined;
+    cost?: string | undefined;
+    run?: string | undefined;
+    deployTarget?: string | undefined;
+    stdin?: boolean | undefined;
+}, {
+    sent: boolean;
+    spooled: boolean;
+    queued: number;
+    reason?: string | undefined;
+}, "rpc" | "session", import("../../../.pikku/function/pikku-function-types.gen.js").WiredServices, unknown> | import("../../../.pikku/function/pikku-function-types.gen.js").PikkuFunction<{
+    title?: string | undefined;
+    kind?: "product" | "harness" | undefined;
+    model?: string | undefined;
+    expected?: string | undefined;
+    actual?: string | undefined;
+    skill?: string | undefined;
+    passage?: string | undefined;
+    command?: string | undefined;
+    error?: string | undefined;
+    repro?: string | undefined;
+    workaround?: string | undefined;
+    proposal?: string | undefined;
+    tried?: string | undefined;
+    unresolved?: boolean | undefined;
+    area?: string | undefined;
+    surface?: "local" | "deployed" | "both" | undefined;
+    cost?: string | undefined;
+    run?: string | undefined;
+    deployTarget?: string | undefined;
+    stdin?: boolean | undefined;
+}, {
+    sent: boolean;
+    spooled: boolean;
+    queued: number;
+    reason?: string | undefined;
+}, "rpc" | "session", import("../../../.pikku/function/pikku-function-types.gen.js").WiredServices>, undefined, undefined>;

package/dist/src/fabric/functions/report.function.js

@@ -0,0 +1,84 @@
+import { z } from 'zod';
+import { pikkuSessionlessFunc } from '../../../.pikku/function/index.js';
+import { resolveApiContext } from '../lib/config.js';
+import { collectReportEnvironment } from '../lib/report-environment.js';
+import { FindingInput, buildFindingPayload, parseFinding, parseFindingJson, postFinding, renderReceipt, validateFinding, } from '../lib/finding.js';
+import { flushSpool, readSpool, spoolFinding } from '../lib/finding-spool.js';
+/**
+ * Every field is optional here and the strictness lives in `FindingInput`,
+ * because `--stdin` supplies the whole finding at once and the flags then
+ * carry nothing. Whichever path was used, the same schema decides whether a
+ * finding is well-formed.
+ */
+export const FabricReportInput = FindingInput.partial().extend({
+    stdin: z.boolean().optional(),
+});
+export const FabricReportOutput = z.object({
+    sent: z.boolean(),
+    reason: z.string().optional(),
+    spooled: z.boolean(),
+    queued: z.number(),
+});
+const readStdin = async () => {
+    if (process.stdin.isTTY) {
+        throw new Error('--stdin expects the finding as JSON on standard input, and nothing was piped in.');
+    }
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks).toString('utf8');
+};
+/**
+ * Every path that cannot send holds the finding instead. The states that stop
+ * a send — logged out, fabric unreachable — are the states a finding is most
+ * likely to be describing, so dropping it loses exactly the reports worth
+ * having.
+ */
+const hold = async (payload, reason, projectId, message) => {
+    await spoolFinding({ payload, reason, projectId });
+    const queued = (await readSpool()).length;
+    console.log(`[fabric] ${message} — finding queued (${queued} waiting, sent on your next report)`);
+    return { sent: false, reason, spooled: true, queued };
+};
+export const FabricReport = pikkuSessionlessFunc({
+    description: 'Report a finding — something about pikku that cost time — to fabric.',
+    input: FabricReportInput,
+    output: FabricReportOutput,
+    func: async (_services, { stdin, ...flags }) => {
+        const parsed = stdin
+            ? parseFindingJson(await readStdin())
+            : parseFinding(flags);
+        if ('problems' in parsed) {
+            throw new Error(parsed.problems.join('\n'));
+        }
+        const problems = validateFinding(parsed.finding);
+        if (problems.length > 0) {
+            throw new Error(problems.join('\n'));
+        }
+        const payload = buildFindingPayload(parsed.finding, await collectReportEnvironment());
+        console.log(renderReceipt(payload));
+        const ctx = await resolveApiContext();
+        if (!ctx.token) {
+            return hold(payload, 'not-logged-in', ctx.projectId, 'not logged in');
+        }
+        const flushed = await flushSpool({
+            apiUrl: ctx.apiUrl,
+            token: ctx.token,
+            projectId: ctx.projectId,
+        });
+        if (flushed.sent > 0) {
+            console.log(`[fabric] sent ${flushed.sent} finding(s) held from earlier`);
+        }
+        const result = await postFinding({
+            apiUrl: ctx.apiUrl,
+            token: ctx.token,
+            projectId: ctx.projectId,
+            payload,
+        });
+        if (!result.sent) {
+            return hold(payload, result.reason ?? 'send-failed', ctx.projectId, `fabric did not accept it (${result.reason})`);
+        }
+        console.log('[fabric] finding sent');
+        return { sent: true, spooled: false, queued: flushed.remaining };
+    },
+});

package/dist/src/fabric/lib/finding-spool.d.ts

@@ -0,0 +1,56 @@
+import { type FindingPayload } from './finding.js';
+/**
+ * A finding that could not be sent when it was filed, held until it can be.
+ *
+ * The cases that keep a finding from leaving — no token, no linked project, a
+ * fabric that is down — are the same cases the finding is most likely to be
+ * about: a scaffold that never got far enough to log in is exactly the thing
+ * worth hearing about, and printing it and dropping it loses it. The spool
+ * lives in `~/.fabric`, not the repo, so nothing goes stale on an abandoned
+ * branch and git never sees it.
+ */
+export interface SpooledFinding {
+    file: string;
+    spooledAt: string;
+    reason: string;
+    projectId: string | null;
+    payload: FindingPayload;
+}
+/** Oldest entries past this are dropped, so a logged-out machine stays bounded. */
+export declare const SPOOL_LIMIT = 100;
+export declare function spoolDir(): string;
+export declare function spoolFinding(entry: {
+    payload: FindingPayload;
+    reason: string;
+    projectId: string | null;
+}): Promise<string>;
+/**
+ * Chronological, by the timestamp inside each finding rather than the one its
+ * name carries — the name is for a human reading the directory, and ordering
+ * the queue by it would make the send order a property of how a filename
+ * happens to sort. A file that no longer parses is skipped rather than thrown
+ * for: one corrupt entry is not a reason to lose the rest, or to fail the
+ * command that happened to notice.
+ */
+export declare function readSpool(): Promise<SpooledFinding[]>;
+export declare function clearSpool(): Promise<number>;
+export interface FlushResult {
+    sent: number;
+    remaining: number;
+    reason?: string;
+}
+/**
+ * Drain the spool oldest-first, stopping at the first entry fabric does not
+ * accept — a refusal usually means the next one will be refused too, and
+ * hammering an endpoint that just said no is the wrong thing for a command
+ * whose real job is something else.
+ *
+ * An entry keeps the project it was filed against; one spooled before the repo
+ * was linked adopts the project linked now, and sends without one if there is
+ * still none.
+ */
+export declare function flushSpool(ctx: {
+    apiUrl: string;
+    token: string;
+    projectId: string | null;
+}): Promise<FlushResult>;

package/dist/src/fabric/lib/finding-spool.js

@@ -0,0 +1,105 @@
+import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { postFinding } from './finding.js';
+/** Oldest entries past this are dropped, so a logged-out machine stays bounded. */
+export const SPOOL_LIMIT = 100;
+export function spoolDir() {
+    return (process.env.FABRIC_FINDINGS_DIR ?? join(homedir(), '.fabric', 'findings'));
+}
+export async function spoolFinding(entry) {
+    const dir = spoolDir();
+    await mkdir(dir, { recursive: true });
+    const stamp = entry.payload.reportedAt.replace(/[:.]/g, '-');
+    const file = join(dir, `${stamp}-${randomBytes(3).toString('hex')}.json`);
+    await writeFile(file, JSON.stringify({
+        spooledAt: new Date().toISOString(),
+        reason: entry.reason,
+        projectId: entry.projectId,
+        payload: entry.payload,
+    }, null, 2) + '\n', { encoding: 'utf8', mode: 0o600 });
+    await pruneSpool();
+    return file;
+}
+/**
+ * Chronological, by the timestamp inside each finding rather than the one its
+ * name carries — the name is for a human reading the directory, and ordering
+ * the queue by it would make the send order a property of how a filename
+ * happens to sort. A file that no longer parses is skipped rather than thrown
+ * for: one corrupt entry is not a reason to lose the rest, or to fail the
+ * command that happened to notice.
+ */
+export async function readSpool() {
+    const dir = spoolDir();
+    if (!existsSync(dir))
+        return [];
+    const names = (await readdir(dir)).filter((n) => n.endsWith('.json'));
+    const entries = [];
+    for (const name of names) {
+        const file = join(dir, name);
+        try {
+            const parsed = JSON.parse(await readFile(file, 'utf8'));
+            if (!parsed?.payload)
+                continue;
+            entries.push({
+                file,
+                spooledAt: parsed.spooledAt ?? '',
+                reason: parsed.reason ?? 'unknown',
+                projectId: parsed.projectId ?? null,
+                payload: parsed.payload,
+            });
+        }
+        catch {
+            continue;
+        }
+    }
+    return entries.sort((a, b) => a.payload.reportedAt.localeCompare(b.payload.reportedAt) ||
+        a.file.localeCompare(b.file));
+}
+export async function clearSpool() {
+    const entries = await readSpool();
+    for (const entry of entries)
+        await rm(entry.file, { force: true });
+    return entries.length;
+}
+async function pruneSpool() {
+    const entries = await readSpool();
+    const excess = Math.max(0, entries.length - SPOOL_LIMIT);
+    for (const entry of entries.slice(0, excess)) {
+        await rm(entry.file, { force: true });
+    }
+}
+/**
+ * Drain the spool oldest-first, stopping at the first entry fabric does not
+ * accept — a refusal usually means the next one will be refused too, and
+ * hammering an endpoint that just said no is the wrong thing for a command
+ * whose real job is something else.
+ *
+ * An entry keeps the project it was filed against; one spooled before the repo
+ * was linked adopts the project linked now, and sends without one if there is
+ * still none.
+ */
+export async function flushSpool(ctx) {
+    const entries = await readSpool();
+    let sent = 0;
+    for (const [index, entry] of entries.entries()) {
+        const result = await postFinding({
+            apiUrl: ctx.apiUrl,
+            token: ctx.token,
+            projectId: entry.projectId ?? ctx.projectId,
+            payload: entry.payload,
+        });
+        if (!result.sent) {
+            return {
+                sent,
+                remaining: entries.length - index,
+                reason: result.reason,
+            };
+        }
+        await rm(entry.file, { force: true });
+        sent++;
+    }
+    return { sent, remaining: 0 };
+}