akm-cli 0.9.16 → 0.9.17-alpha.10

package/dist/llm/metadata-enhance.js

@@ -1,96 +0,0 @@
-// This Source Code Form is subject to the terms of the Mozilla Public
-// License, v. 2.0. If a copy of the MPL was not distributed with this
-// file, You can obtain one at https://mozilla.org/MPL/2.0/.
-/**
- * LLM-driven metadata enhancement for stash entries.
- *
- * Keeps the higher-level workflow for improving descriptions, tags, and search
- * hints separate from the low-level transport client.
- */
-import metadataEnhanceSystemPrompt from "../assets/prompts/metadata-enhance-system.md" with { type: "text" };
-import { parseJsonResponse } from "../core/parse.js";
-import { callStructured } from "./structured-call.js";
-const SYSTEM_PROMPT = metadataEnhanceSystemPrompt;
-/**
- * Use an LLM to enhance a stash entry's metadata: improve description,
- * generate searchHints, and suggest tags.
- *
- * When `akmConfig` is provided, routes through
- * `tryLlmFeature("metadata_enhance", ...)` so the feature gate is honoured: a
- * closed gate yields `{ status: "skipped" }` and a thrown/timed-out call yields
- * `{ status: "failed" }` — neither is reported as an enrichment. When
- * `akmConfig` is `undefined` the gate is bypassed entirely: the LLM call runs
- * unconditionally and errors propagate to direct callers such as tests.
- */
-export async function enhanceMetadata(runner, entry, fileContent, signal, akmConfig, onNotices, lease) {
-    const contextParts = [`Name: ${entry.name}`, `Type: ${entry.type}`];
-    if (entry.description)
-        contextParts.push(`Current description: ${entry.description}`);
-    if (entry.tags?.length)
-        contextParts.push(`Current tags: ${entry.tags.join(", ")}`);
-    if (fileContent) {
-        // Limit content to first 4000 chars to stay within token limits (matches other modules)
-        const truncated = fileContent.length > 4000 ? `${fileContent.slice(0, 4000)}\n... (truncated)` : fileContent;
-        contextParts.push(`File content:\n${truncated}`);
-    }
-    const userPrompt = `${contextParts.join("\n")}
-
-Generate improved metadata for this ${entry.type}. Return JSON with these fields:
-- "description": a clear, concise one-sentence description of what this does
-- "searchHints": an array of 3-6 natural language task phrases an agent might use to find this (e.g. "deploy a docker container", "run database migrations")
-- "tags": an array of 3-8 relevant keyword tags
-
-Return ONLY the JSON object, no explanation.`;
-    // `parse` owns the raw response: the `!raw`/unparseable case ⇒ empty metadata
-    // (still a genuine success), plus the description/searchHints/tags shaping.
-    // `enhanceMetadata` never warns and never bumps telemetry — `onError` (gated
-    // path only) reports `failed` WITHOUT warning, carrying the message so the
-    // caller can surface it. The ungated path (akmConfig === undefined) propagates
-    // errors via callStructured.
-    let timedOut = false;
-    const outcome = await callStructured({
-        feature: "metadata_enhance",
-        akmConfig,
-        runner,
-        ...(lease ? { lease } : {}),
-        messages: [
-            { role: "system", content: SYSTEM_PROMPT },
-            { role: "user", content: userPrompt },
-        ],
-        request: { signal, timeoutMs: runner.timeoutMs },
-        onNotices,
-        parse: (raw) => {
-            const parsed = raw ? parseJsonResponse(raw) : undefined;
-            const metadata = {};
-            if (parsed) {
-                if (typeof parsed.description === "string" && parsed.description) {
-                    metadata.description = parsed.description;
-                }
-                if (Array.isArray(parsed.searchHints)) {
-                    metadata.searchHints = parsed.searchHints
-                        .filter((s) => typeof s === "string" && s.trim().length > 0)
-                        .slice(0, 8);
-                }
-                if (Array.isArray(parsed.tags)) {
-                    metadata.tags = parsed.tags
-                        .filter((s) => typeof s === "string" && s.trim().length > 0)
-                        .slice(0, 10);
-                }
-            }
-            return { status: "enriched", metadata };
-        },
-        onError: (_cls, err) => ({ status: "failed", error: err instanceof Error ? err.message : String(err) }),
-        fallback: { status: "skipped" },
-        // The seam returns the `skipped` fallback for a closed gate AND for a
-        // wrapper-level timeout. Record the timeout so we can reclassify it below —
-        // a timed-out call is a failure, not a silent skip.
-        onFallback: (event) => {
-            if (event.reason === "timeout")
-                timedOut = true;
-        },
-    });
-    if (outcome.status === "skipped" && timedOut) {
-        return { status: "failed", error: "metadata_enhance timed out" };
-    }
-    return outcome;
-}

package/dist/registry/create-provider-registry.js

@@ -1,29 +0,0 @@
-// This Source Code Form is subject to the terms of the Mozilla Public
-// License, v. 2.0. If a copy of the MPL was not distributed with this
-// file, You can obtain one at https://mozilla.org/MPL/2.0/.
-/**
- * Generic factory-map utility.
- *
- * Creates a lightweight registry that maps string keys to factory functions.
- * Both registry/factory.ts (registry discovery) and sources/provider-factory.ts
- * (source providers) are built on this utility.
- */
-export function createProviderRegistry() {
-    const map = new Map();
-    return {
-        register(type, factory) {
-            map.set(type, factory);
-        },
-        resolve(type) {
-            return map.get(type) ?? null;
-        },
-        /** Removes a registration. No-op if `type` was never registered. */
-        unregister(type) {
-            map.delete(type);
-        },
-        /** Snapshot of all registered keys. Iteration order matches insertion order. */
-        list() {
-            return [...map.keys()];
-        },
-    };
-}

package/dist/registry/pinned-request-helper.js

@@ -1,247 +0,0 @@
-// This Source Code Form is subject to the terms of the Mozilla Public
-// License, v. 2.0. If a copy of the MPL was not distributed with this
-// file, You can obtain one at https://mozilla.org/MPL/2.0/.
-/** Parse and validate the private stdin request before any socket is opened. */
-async function readNodePinnedHelperRequest(isIP) {
-    const MAX_PRELUDE_BYTES = 64 * 1024;
-    const iterator = process.stdin[Symbol.asyncIterator]();
-    let buffered = Buffer.alloc(0);
-    const readExact = async (length) => {
-        while (buffered.byteLength < length) {
-            const next = await iterator.next();
-            if (next.done)
-                throw new Error("Registry helper input ended before the request prelude was complete");
-            buffered = Buffer.concat([buffered, Buffer.from(next.value)]);
-        }
-        const result = buffered.subarray(0, length);
-        buffered = buffered.subarray(length);
-        return result;
-    };
-    const preludeLength = (await readExact(4)).readUInt32BE(0);
-    if (preludeLength === 0 || preludeLength > MAX_PRELUDE_BYTES) {
-        throw new Error("Registry helper request prelude exceeds its protocol limit");
-    }
-    const raw = JSON.parse((await readExact(preludeLength)).toString("utf8"));
-    if (typeof raw.url !== "string" || typeof raw.address !== "string") {
-        throw new Error("Registry helper request prelude is invalid");
-    }
-    const url = new URL(raw.url);
-    if ((url.protocol !== "http:" && url.protocol !== "https:") || url.username || url.password) {
-        throw new Error("Registry helper accepts only credential-free HTTP(S) URLs");
-    }
-    const addressFamily = isIP(raw.address);
-    if (addressFamily === 0)
-        throw new Error("Registry helper requires a numeric pinned address");
-    if (typeof raw.timeoutMs !== "number" || !Number.isSafeInteger(raw.timeoutMs) || raw.timeoutMs <= 0) {
-        throw new Error("Registry helper timeout is invalid");
-    }
-    if (!Array.isArray(raw.headers) || raw.headers.length > 256) {
-        throw new Error("Registry helper headers are invalid");
-    }
-    const headers = {};
-    for (const pair of raw.headers) {
-        if (!Array.isArray(pair) ||
-            pair.length !== 2 ||
-            typeof pair[0] !== "string" ||
-            typeof pair[1] !== "string" ||
-            pair[0].length > 256 ||
-            pair[1].length > 16_384) {
-            throw new Error("Registry helper header entry is invalid");
-        }
-        headers[pair[0].toLowerCase()] = pair[1];
-    }
-    for (const name of [
-        "connection",
-        "keep-alive",
-        "proxy-authorization",
-        "proxy-connection",
-        "te",
-        "trailer",
-        "transfer-encoding",
-        "upgrade",
-    ]) {
-        delete headers[name];
-    }
-    headers.host = url.host;
-    return {
-        addressFamily: addressFamily,
-        bodyPresent: raw.bodyPresent === true,
-        headers,
-        initialBody: buffered,
-        iterator,
-        method: typeof raw.method === "string" ? raw.method.toUpperCase() : "GET",
-        pinnedAddress: raw.address,
-        timeoutMs: raw.timeoutMs,
-        url,
-    };
-}
-/**
- * The body of the one-request Node helper used by Bun's registry transport.
- * Its parser is passed explicitly when the parent serializes both functions.
- */
-export async function nodePinnedRequestHelperMain(readRequest, http, https, isIP) {
-    const MAX_FRAME_BYTES = 1024 * 1024;
-    const FRAME_PRELUDE = 0;
-    const FRAME_BODY = 1;
-    const FRAME_END = 2;
-    const FRAME_ERROR = 3;
-    const writeBuffer = async (value) => {
-        await new Promise((resolve, reject) => {
-            process.stdout.write(value, (error) => (error ? reject(error) : resolve()));
-        });
-    };
-    const writeFrame = async (type, payload = new Uint8Array()) => {
-        if (payload.byteLength > MAX_FRAME_BYTES && type !== FRAME_BODY) {
-            throw new Error("Registry helper frame exceeds its protocol limit");
-        }
-        if (type === FRAME_BODY && payload.byteLength > MAX_FRAME_BYTES) {
-            for (let offset = 0; offset < payload.byteLength; offset += MAX_FRAME_BYTES) {
-                await writeFrame(type, payload.subarray(offset, Math.min(payload.byteLength, offset + MAX_FRAME_BYTES)));
-            }
-            return;
-        }
-        const header = Buffer.allocUnsafe(5);
-        header[0] = type;
-        header.writeUInt32BE(payload.byteLength, 1);
-        await writeBuffer(header);
-        if (payload.byteLength > 0)
-            await writeBuffer(payload);
-    };
-    const errorPayload = (error) => {
-        const candidate = error;
-        return Buffer.from(JSON.stringify({
-            name: typeof candidate?.name === "string" ? candidate.name.slice(0, 128) : "Error",
-            message: typeof candidate?.message === "string" ? candidate.message.slice(0, 8_192) : String(error).slice(0, 8_192),
-            code: typeof candidate?.code === "string" ? candidate.code.slice(0, 128) : undefined,
-        }));
-    };
-    try {
-        const nodeMajor = Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10);
-        if (!Number.isInteger(nodeMajor) || nodeMajor < 22) {
-            throw new Error(`The pinned registry helper requires Node.js >= 22; found ${process.versions.node}`);
-        }
-        const { addressFamily, bodyPresent, headers, initialBody, iterator, method, pinnedAddress, timeoutMs, url } = await readRequest(isIP);
-        const hostname = url.hostname.startsWith("[") && url.hostname.endsWith("]") ? url.hostname.slice(1, -1) : url.hostname;
-        const lookup = (_hostname, options, callback) => {
-            if (typeof options === "object" && options !== null && "all" in options && options.all === true) {
-                callback(null, [{ address: pinnedAddress, family: addressFamily }]);
-            }
-            else {
-                callback(null, pinnedAddress, addressFamily);
-            }
-        };
-        const requestOptions = {
-            protocol: url.protocol,
-            hostname,
-            port: url.port || undefined,
-            path: `${url.pathname}${url.search}`,
-            method,
-            headers,
-            lookup,
-            // One helper owns exactly one fresh connection. It never pools a socket
-            // selected for an earlier DNS answer.
-            agent: false,
-            ...(url.protocol === "https:" && isIP(hostname) === 0 ? { servername: hostname } : {}),
-        };
-        let responseStarted = false;
-        let requestFinished = false;
-        let request;
-        const responseDone = new Promise((resolve, reject) => {
-            const requestFn = url.protocol === "https:" ? https.request : http.request;
-            request = requestFn(requestOptions, async (response) => {
-                responseStarted = true;
-                try {
-                    await writeFrame(FRAME_PRELUDE, Buffer.from(JSON.stringify({
-                        status: response.statusCode ?? 500,
-                        statusText: response.statusMessage ?? "",
-                        rawHeaders: response.rawHeaders,
-                    })));
-                    for await (const chunk of response) {
-                        await writeFrame(FRAME_BODY, Buffer.from(chunk));
-                    }
-                    await writeFrame(FRAME_END);
-                    resolve();
-                }
-                catch (error) {
-                    reject(error);
-                }
-            });
-            const headerTimer = setTimeout(() => {
-                request?.destroy(new Error(`Registry request timed out after ${timeoutMs}ms while awaiting response headers`));
-            }, timeoutMs);
-            request.once("response", () => clearTimeout(headerTimer));
-            request.once("error", (error) => {
-                clearTimeout(headerTimer);
-                if (!responseStarted)
-                    reject(error);
-            });
-        });
-        const writeRequestChunk = async (chunk) => {
-            if (!request || request.destroyed)
-                throw new Error("Registry helper request closed while streaming its body");
-            const activeRequest = request;
-            if (activeRequest.write(chunk))
-                return;
-            await new Promise((resolve, reject) => {
-                const onDrain = () => {
-                    cleanup();
-                    resolve();
-                };
-                const onError = (error) => {
-                    cleanup();
-                    reject(error);
-                };
-                const cleanup = () => {
-                    activeRequest.off("drain", onDrain);
-                    activeRequest.off("error", onError);
-                };
-                activeRequest.once("drain", onDrain);
-                activeRequest.once("error", onError);
-            });
-        };
-        const bodyDone = (async () => {
-            if (!request)
-                throw new Error("Registry helper request was not initialized");
-            if (bodyPresent) {
-                if (initialBody.byteLength > 0) {
-                    await writeRequestChunk(initialBody);
-                }
-                while (true) {
-                    const next = await iterator.next();
-                    if (next.done)
-                        break;
-                    await writeRequestChunk(Buffer.from(next.value));
-                }
-            }
-            requestFinished = true;
-            request.end();
-        })();
-        try {
-            await Promise.all([responseDone, bodyDone]);
-        }
-        catch (error) {
-            if (!requestFinished && !responseStarted)
-                request?.destroy(error);
-            throw error;
-        }
-    }
-    catch (error) {
-        try {
-            await writeFrame(FRAME_ERROR, errorPayload(error));
-        }
-        catch {
-            // The parent also treats an unframed EOF as a transport failure.
-        }
-        process.exitCode = 1;
-    }
-}
-/** Materialize both self-contained passes into a one-request Node program. */
-export function nodePinnedRequestHelperSource() {
-    return (`import * as http from "node:http";\n` +
-        `import * as https from "node:https";\n` +
-        `import { isIP } from "node:net";\n` +
-        `(${nodePinnedRequestHelperMain.toString()})(${readNodePinnedHelperRequest.toString()}, http, https, isIP).catch((error) => {\n` +
-        `  console.error(error instanceof Error ? error.message : String(error));\n` +
-        `  process.exitCode = 1;\n` +
-        `});\n`);
-}