@hadooppei/hwcode 1.0.9 → 1.0.11

package/.pi/dist/lib/knowledge/extractor.js

@@ -0,0 +1,102 @@
+import { createHash } from "node:crypto";
+import { KNOWLEDGE_RUNTIME_DEFAULTS } from "../runtime/defaults.js";
+export const KNOWLEDGE_EXTRACTION_SYSTEM_PROMPT = `You are HWCode's background knowledge reviewer.
+Review only the supplied conversation delta. Return strict JSON and no markdown.
+Persist only knowledge that is likely to be useful in future sessions:
+- explicit user corrections or stable preferences;
+- verified engineering rules, successful procedures, or expensive failed approaches;
+- reusable architecture, testing, debugging, deployment, or operational knowledge.
+Do not persist task summaries, guesses, temporary IDs, credentials, secrets, private data, or facts recoverable by simply reading the repository.
+Do not persist mutable inventory such as current cloud resources, names, availability, status, timestamps, or account snapshots. Preserve the discovery method or selection rule instead. If useful procedure is mixed with volatile facts, remove the volatile facts.
+Use storageHint "rule" only for short, precise, high-value instructions. Use "topic" for multi-step SOPs and detailed experience.
+Use action "revise" only when the delta explicitly corrects prior knowledge; otherwise use "add" or "reinforce".
+Scope may be "global" only for an explicit user directive intended across projects; otherwise use "project".
+Each summary must be one complete sentence of at most 160 characters. Keep each body under 3000 characters. Escape line breaks and quotes inside JSON strings. Set durability to "stable" only after removing facts likely to change or be cheaply rediscovered.
+Return: {"candidates":[{"key":"stable semantic key","title":"...","summary":"one complete sentence","keywords":["..."],"scope":"global|project","body":"markdown body","evidence":["verified evidence"],"confidence":0.0,"storageHint":"rule|topic","action":"add|reinforce|revise","explicitUserDirective":false,"durability":"stable"}]}
+Return {"candidates":[]} when nothing meets the threshold.`;
+export function buildKnowledgeExtractionPrompt(projectRoot, delta) {
+    return `Project root: ${projectRoot}\n\n<conversation_delta>\n${delta}\n</conversation_delta>`;
+}
+export function parseCandidateEnvelope(text) {
+    const trimmed = text.trim();
+    const unfenced = trimmed.replace(/^```(?:json)?\s*/iu, "").replace(/\s*```$/u, "");
+    const start = unfenced.indexOf("{");
+    const end = unfenced.lastIndexOf("}");
+    if (start < 0 || end <= start)
+        throw new Error("Knowledge reviewer did not return a JSON object");
+    let strictError;
+    try {
+        const parsed = JSON.parse(unfenced.slice(start, end + 1));
+        if (!Array.isArray(parsed.candidates))
+            throw new Error("Knowledge reviewer response is missing candidates[]");
+        return parsed.candidates.slice(0, KNOWLEDGE_RUNTIME_DEFAULTS.review.maxCandidates);
+    }
+    catch (error) {
+        strictError = error;
+    }
+    const arrayKey = /["']candidates["']\s*:/gu.exec(unfenced);
+    const arrayStart = arrayKey ? unfenced.indexOf("[", arrayKey.index + arrayKey[0].length) : -1;
+    if (arrayStart >= 0) {
+        const candidates = [];
+        let inString = false;
+        let escaped = false;
+        for (let index = arrayStart + 1; index < unfenced.length && candidates.length < KNOWLEDGE_RUNTIME_DEFAULTS.review.maxCandidates; index++) {
+            const character = unfenced[index];
+            if (inString) {
+                if (escaped)
+                    escaped = false;
+                else if (character === "\\")
+                    escaped = true;
+                else if (character === '"')
+                    inString = false;
+                continue;
+            }
+            if (character === '"') {
+                inString = true;
+                continue;
+            }
+            if (character !== "{")
+                continue;
+            const objectEnd = balancedObjectEnd(unfenced, index);
+            if (objectEnd < 0)
+                break;
+            try {
+                candidates.push(JSON.parse(unfenced.slice(index, objectEnd + 1)));
+            }
+            catch { /* Salvage other complete candidates. */ }
+            index = objectEnd;
+        }
+        if (candidates.length > 0)
+            return candidates;
+    }
+    throw strictError;
+}
+function balancedObjectEnd(value, start) {
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let index = start; index < value.length; index++) {
+        const character = value[index];
+        if (inString) {
+            if (escaped)
+                escaped = false;
+            else if (character === "\\")
+                escaped = true;
+            else if (character === '"')
+                inString = false;
+            continue;
+        }
+        if (character === '"') {
+            inString = true;
+            continue;
+        }
+        if (character === "{")
+            depth++;
+        else if (character === "}" && --depth === 0)
+            return index;
+    }
+    return -1;
+}
+export function knowledgeDeltaDigest(delta) {
+    return createHash("sha256").update(delta).digest("hex");
+}

package/.pi/dist/lib/knowledge/review-status.js

@@ -0,0 +1,20 @@
+import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { userRuntimePaths } from "../runtime/paths.js";
+export function writeKnowledgeReviewStatus(status, home) {
+    const path = userRuntimePaths(home).knowledgeStatus;
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${process.pid}.tmp`;
+    writeFileSync(temporary, `${JSON.stringify(status, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    renameSync(temporary, path);
+    chmodSync(path, 0o600);
+}
+export function readKnowledgeReviewStatus(home) {
+    try {
+        const parsed = JSON.parse(readFileSync(userRuntimePaths(home).knowledgeStatus, "utf8"));
+        return parsed.version === 1 && parsed.protocolVersion === 3 ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/.pi/dist/lib/knowledge/review-worker.js

@@ -0,0 +1,392 @@
+import { randomUUID } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { createConnection, createServer } from "node:net";
+import { homedir } from "node:os";
+import { parentPort, workerData } from "node:worker_threads";
+import { KNOWLEDGE_RUNTIME_DEFAULTS } from "../runtime/defaults.js";
+import { userRuntimePaths } from "../runtime/paths.js";
+import { parseCandidateEnvelope } from "./extractor.js";
+import { writeKnowledgeReviewStatus } from "./review-status.js";
+import { sanitizeKnowledgeText } from "./sanitize.js";
+import { findNextReviewTask } from "./session-scanner.js";
+import { commitKnowledgeReview, ensureKnowledgeDirectories, loadCurrentManifest } from "./store.js";
+if (!parentPort)
+    throw new Error("Knowledge review worker requires a parent port");
+const home = workerData?.home ?? homedir();
+const paths = userRuntimePaths(home);
+const standbySockets = new Set();
+let eligible = false;
+let stopped = false;
+let sessionsRoot = "";
+let leaderServer;
+let leaderToken = "";
+let standbySocket;
+let electionPending = false;
+let activeTask;
+let activeAttempt = 0;
+let activeStartedAt = 0;
+let activeDeadlineTimer;
+let reviewStatus;
+const reviewAttempts = new Map();
+function send(message) {
+    parentPort.postMessage(message);
+}
+function coordinatorPath() {
+    return process.platform === "win32"
+        ? `\\\\.\\pipe\\hwcode-knowledge-v3-${Buffer.from(home).toString("hex").slice(0, 16)}`
+        : paths.knowledgeCoordinatorSocket;
+}
+function writeLeaderMetadata(electedAt) {
+    writeFileSync(paths.knowledgeLeader, `${JSON.stringify({
+        protocolVersion: 3, leaderToken, pid: process.pid, electedAt,
+    }, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    chmodSync(paths.knowledgeLeader, 0o600);
+}
+function publishReviewStatus() {
+    if (!reviewStatus)
+        return;
+    reviewStatus.updatedAt = new Date().toISOString();
+    try {
+        writeKnowledgeReviewStatus(reviewStatus, home);
+    }
+    catch (error) {
+        send({ type: "review_failed", error: `Unable to write knowledge status: ${error instanceof Error ? error.message : String(error)}` });
+    }
+}
+function boundedError(error) {
+    return sanitizeKnowledgeText(error instanceof Error ? error.message : String(error)).slice(0, 1_000);
+}
+function beginReview(task) {
+    activeAttempt = (reviewAttempts.get(task.reviewKey) ?? 0) + 1;
+    reviewAttempts.set(task.reviewKey, activeAttempt);
+    activeStartedAt = Date.now();
+    clearTimeout(activeDeadlineTimer);
+    activeDeadlineTimer = setTimeout(() => {
+        if (activeTask?.requestId !== task.requestId)
+            return;
+        const error = "knowledge-review-result-timeout";
+        finishReview(task, "failed", { error });
+        activeTask = undefined;
+        send({ type: "review_cancel", requestId: task.requestId, reason: error });
+        send({ type: "review_failed", requestId: task.requestId, error });
+    }, KNOWLEDGE_RUNTIME_DEFAULTS.review.modelTimeoutMs + 5_000);
+    activeDeadlineTimer.unref();
+    if (reviewStatus) {
+        reviewStatus.activeReview = {
+            reviewKey: task.reviewKey,
+            sessionKey: task.sessionKey,
+            sessionFileHash: task.sessionFileHash,
+            projectKey: task.projectKey,
+            attempt: activeAttempt,
+            startedAt: new Date(activeStartedAt).toISOString(),
+        };
+        publishReviewStatus();
+    }
+}
+function finishReview(task, outcome, detail) {
+    clearTimeout(activeDeadlineTimer);
+    activeDeadlineTimer = undefined;
+    if (!reviewStatus)
+        return;
+    reviewStatus.activeReview = undefined;
+    reviewStatus.lastReview = {
+        reviewKey: task.reviewKey,
+        sessionKey: task.sessionKey,
+        attempt: activeAttempt,
+        outcome,
+        completedAt: new Date().toISOString(),
+        durationMs: Math.max(0, Date.now() - activeStartedAt),
+        generationId: detail.generationId,
+        result: detail.result,
+        error: detail.error === undefined ? undefined : boundedError(detail.error),
+    };
+    if (outcome === "saved")
+        reviewAttempts.delete(task.reviewKey);
+    publishReviewStatus();
+}
+function removeLeaderMetadata(token) {
+    try {
+        const current = JSON.parse(readFileSync(paths.knowledgeLeader, "utf8"));
+        if (current.leaderToken === token)
+            rmSync(paths.knowledgeLeader, { force: true });
+    }
+    catch { /* Another contender may already have replaced it. */ }
+}
+function broadcast(message) {
+    const line = `${JSON.stringify(message)}\n`;
+    for (const socket of standbySockets) {
+        if (socket.writable)
+            socket.write(line);
+    }
+}
+function scheduleElection(delay = Math.floor(Math.random() * 500)) {
+    if (!eligible || stopped || electionPending || leaderServer || standbySocket)
+        return;
+    electionPending = true;
+    const timer = setTimeout(() => {
+        electionPending = false;
+        attemptElection();
+    }, delay);
+    timer.unref();
+}
+function stepDown(reason) {
+    if (activeTask)
+        send({ type: "review_cancel", requestId: activeTask.requestId, reason });
+    if (reviewStatus) {
+        reviewStatus.state = "stepped-down";
+        reviewStatus.stepDownReason = reason;
+        reviewStatus.activeReview = undefined;
+        publishReviewStatus();
+    }
+    activeTask = undefined;
+    clearTimeout(activeDeadlineTimer);
+    activeDeadlineTimer = undefined;
+    activeAttempt = 0;
+    activeStartedAt = 0;
+    const token = leaderToken;
+    leaderToken = "";
+    for (const socket of standbySockets)
+        socket.destroy();
+    standbySockets.clear();
+    const server = leaderServer;
+    leaderServer = undefined;
+    if (server) {
+        try {
+            server.close();
+        }
+        catch { /* The failing server may already be closed. */ }
+        if (process.platform !== "win32") {
+            try {
+                unlinkSync(coordinatorPath());
+            }
+            catch { /* Socket may already be gone. */ }
+        }
+    }
+    if (token)
+        removeLeaderMetadata(token);
+    reviewStatus = undefined;
+}
+function becomeStandby(socket) {
+    standbySocket = socket;
+    socket.unref();
+    send({ type: "leadership", state: "standby" });
+    let buffer = "";
+    socket.on("data", (chunk) => {
+        buffer += chunk.toString("utf8");
+        for (;;) {
+            const newline = buffer.indexOf("\n");
+            if (newline < 0)
+                break;
+            const line = buffer.slice(0, newline);
+            buffer = buffer.slice(newline + 1);
+            try {
+                const message = JSON.parse(line);
+                if (message.type === "generation_changed")
+                    send(message);
+            }
+            catch { /* Ignore malformed coordinator notifications. */ }
+        }
+    });
+    socket.once("close", () => {
+        if (standbySocket === socket)
+            standbySocket = undefined;
+        scheduleElection();
+    });
+}
+function cleanStaleSocketAndRetry() {
+    if (process.platform === "win32") {
+        scheduleElection(250);
+        return;
+    }
+    try {
+        mkdirSync(paths.knowledgeElectionLock, { mode: 0o700 });
+    }
+    catch {
+        scheduleElection(250);
+        return;
+    }
+    try {
+        if (existsSync(coordinatorPath()))
+            unlinkSync(coordinatorPath());
+    }
+    catch { /* Retrying listen will surface persistent failures. */ }
+    finally {
+        rmSync(paths.knowledgeElectionLock, { recursive: true, force: true });
+    }
+    scheduleElection();
+}
+function connectToLeader(probe = 0) {
+    if (!eligible || stopped || leaderServer || standbySocket)
+        return;
+    const socket = createConnection(coordinatorPath());
+    let connected = false;
+    socket.once("connect", () => { connected = true; becomeStandby(socket); });
+    socket.once("error", (error) => {
+        socket.destroy();
+        if (connected)
+            return;
+        if (error.code === "ECONNREFUSED" || error.code === "ENOENT") {
+            if (probe < 2) {
+                const timer = setTimeout(() => connectToLeader(probe + 1), 100);
+                timer.unref();
+            }
+            else
+                cleanStaleSocketAndRetry();
+        }
+        else {
+            send({ type: "review_failed", error: `Coordinator connection failed: ${error.message}` });
+            scheduleElection(1_000);
+        }
+    });
+}
+function becomeLeader(server) {
+    leaderServer = server;
+    leaderToken = randomUUID();
+    const electedAt = new Date().toISOString();
+    server.unref();
+    server.on("connection", (socket) => {
+        standbySockets.add(socket);
+        socket.unref();
+        socket.once("close", () => standbySockets.delete(socket));
+        const generationId = loadCurrentManifest(home).generationId;
+        if (generationId)
+            socket.write(`${JSON.stringify({ type: "generation_changed", generationId })}\n`);
+    });
+    server.on("error", (error) => {
+        send({ type: "review_failed", error: `Coordinator server failed: ${error.message}` });
+        stepDown("coordinator-server-failed");
+        scheduleElection();
+    });
+    writeLeaderMetadata(electedAt);
+    reviewStatus = {
+        version: 1, protocolVersion: 3, state: "leader", pid: process.pid, leaderToken, electedAt, updatedAt: electedAt,
+    };
+    publishReviewStatus();
+    send({ type: "leadership", state: "leader", leaderToken });
+    void scanForReview();
+}
+function attemptElection() {
+    if (!eligible || stopped || leaderServer || standbySocket)
+        return;
+    ensureKnowledgeDirectories(home);
+    const server = createServer();
+    const electionError = (error) => {
+        if (error.code === "EADDRINUSE")
+            connectToLeader();
+        else {
+            send({ type: "review_failed", error: `Coordinator election failed: ${error.message}` });
+            scheduleElection(1_000);
+        }
+    };
+    server.once("error", electionError);
+    server.listen(coordinatorPath(), () => {
+        server.off("error", electionError);
+        if (process.platform !== "win32")
+            chmodSync(coordinatorPath(), 0o600);
+        becomeLeader(server);
+    });
+}
+async function scanForReview() {
+    if (!leaderServer || !leaderToken || activeTask || !sessionsRoot || !eligible)
+        return;
+    if (reviewStatus) {
+        reviewStatus.lastScanAt = new Date().toISOString();
+        reviewStatus.lastScanError = undefined;
+        publishReviewStatus();
+    }
+    try {
+        const manifest = loadCurrentManifest(home);
+        const task = findNextReviewTask(sessionsRoot, manifest.reviews);
+        if (!task)
+            return;
+        activeTask = task;
+        beginReview(task);
+        if (!task.delta) {
+            const result = commitKnowledgeReview([], task, leaderToken, home);
+            const generationId = loadCurrentManifest(home).generationId;
+            finishReview(task, "saved", { generationId, result });
+            send({ type: "review_saved", requestId: task.requestId, generationId, result });
+            if (generationId) {
+                send({ type: "generation_changed", generationId });
+                broadcast({ type: "generation_changed", generationId });
+            }
+            activeTask = undefined;
+            queueMicrotask(() => void scanForReview());
+            return;
+        }
+        send({ type: "review_request", leaderToken, requestId: task.requestId, task });
+    }
+    catch (error) {
+        if (activeTask)
+            finishReview(activeTask, "failed", { error });
+        else if (reviewStatus) {
+            reviewStatus.lastScanError = { at: new Date().toISOString(), error: boundedError(error) };
+            publishReviewStatus();
+        }
+        activeTask = undefined;
+        send({ type: "review_failed", error: boundedError(error) });
+    }
+}
+function handleReviewResult(message) {
+    const task = activeTask;
+    if (!task || message.requestId !== task.requestId || message.leaderToken !== leaderToken || !leaderServer)
+        return;
+    let committed = false;
+    try {
+        if (message.error || message.raw === undefined)
+            throw new Error(message.error || "Knowledge review returned no content");
+        const result = commitKnowledgeReview(parseCandidateEnvelope(message.raw), task, leaderToken, home);
+        const generationId = loadCurrentManifest(home).generationId;
+        finishReview(task, "saved", { generationId, result });
+        send({ type: "review_saved", requestId: task.requestId, generationId, result });
+        if (generationId) {
+            send({ type: "generation_changed", generationId });
+            broadcast({ type: "generation_changed", generationId });
+        }
+        committed = true;
+    }
+    catch (error) {
+        finishReview(task, "failed", { error });
+        send({ type: "review_failed", requestId: task.requestId, error: boundedError(error) });
+    }
+    finally {
+        activeTask = undefined;
+        if (committed)
+            queueMicrotask(() => void scanForReview());
+    }
+}
+const scanTimer = setInterval(() => { void scanForReview(); }, KNOWLEDGE_RUNTIME_DEFAULTS.review.intervalMs);
+scanTimer.unref();
+parentPort.on("message", (message) => {
+    if (message.type === "configure") {
+        sessionsRoot = message.sessionsRoot;
+        if (eligible === message.modelAvailable)
+            return;
+        eligible = message.modelAvailable;
+        if (!eligible) {
+            standbySocket?.destroy();
+            standbySocket = undefined;
+            stepDown("model-unavailable");
+            send({ type: "leadership", state: "ineligible" });
+        }
+        else
+            scheduleElection(0);
+        return;
+    }
+    if (message.type === "review_result") {
+        handleReviewResult(message);
+        return;
+    }
+    if (message.type === "scan_now") {
+        void scanForReview();
+        return;
+    }
+    stopped = true;
+    eligible = false;
+    clearInterval(scanTimer);
+    standbySocket?.destroy();
+    standbySocket = undefined;
+    stepDown("worker-stopped");
+    process.exit(0);
+});
+send({ type: "ready" });

package/.pi/dist/lib/knowledge/sanitize.js

@@ -0,0 +1,44 @@
+const PRIVATE_KEY_RE = /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z0-9 ]*PRIVATE KEY-----/giu;
+const BEARER_RE = /\bBearer\s+[A-Za-z0-9._~+/=-]{12,}/giu;
+const JWT_RE = /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/gu;
+const SECRET_ASSIGNMENT_RE = /\b(access[_-]?key|secret(?:[_-]?(?:access|key))?|password|passwd|token|credential|client[_-]?secret)\b(\s*[:=]\s*)[^\s,;]+/giu;
+const URL_CREDENTIAL_RE = /(https?:\/\/)[^\s/@:]+:[^\s/@]+@/giu;
+export function sanitizeKnowledgeText(value) {
+    return value
+        .replace(PRIVATE_KEY_RE, "<redacted-private-key>")
+        .replace(BEARER_RE, "Bearer <redacted>")
+        .replace(JWT_RE, "<redacted-jwt>")
+        .replace(SECRET_ASSIGNMENT_RE, (_match, key, separator) => `${key}${separator}<redacted>`)
+        .replace(URL_CREDENTIAL_RE, "$1<redacted>@")
+        .replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/giu, "<runtime-uuid>")
+        .replace(/\b(?:\d{1,3}\.){3}\d{1,3}\b/gu, "<runtime-ip>")
+        .replace(/\b(vpc|subnet|secgroup|sg|vol|snap|img|inst|eip)-[0-9a-zA-Z]+/gu, "<$1-runtime-id>")
+        .replace(/\/(?:Users|home)\/[a-zA-Z0-9_-]+/gu, "~");
+}
+export function compactKnowledgeText(value, maxChars) {
+    return sanitizeKnowledgeText(value)
+        .replace(/\r\n/gu, "\n")
+        .replace(/[ \t]+$/gmu, "")
+        .trim()
+        .slice(0, maxChars);
+}
+export function compactKnowledgeSummary(value, maxChars) {
+    const normalized = sanitizeKnowledgeText(value).replace(/\s+/gu, " ").trim();
+    if (normalized.length <= maxChars || maxChars <= 0)
+        return normalized.slice(0, Math.max(0, maxChars));
+    if (maxChars === 1)
+        return "…";
+    const limit = maxChars - 1;
+    const prefix = normalized.slice(0, limit);
+    const minimumBoundary = Math.floor(limit * 0.6);
+    const sentenceEnd = Math.max(prefix.lastIndexOf("。"), prefix.lastIndexOf("！"), prefix.lastIndexOf("？"), prefix.lastIndexOf("."), prefix.lastIndexOf("!"), prefix.lastIndexOf("?"));
+    if (sentenceEnd >= minimumBoundary)
+        return prefix.slice(0, sentenceEnd + 1).trimEnd();
+    const next = normalized.charAt(limit);
+    if (/[A-Za-z0-9]/u.test(prefix.at(-1) ?? "") && /[A-Za-z0-9]/u.test(next)) {
+        const wordBoundary = Math.max(prefix.lastIndexOf(" "), prefix.lastIndexOf("-"), prefix.lastIndexOf("/"));
+        if (wordBoundary >= minimumBoundary)
+            return `${prefix.slice(0, wordBoundary).trimEnd()}…`;
+    }
+    return `${prefix.trimEnd()}…`;
+}