@zq-silk/yui 0.0.0

package/dist/core/controllerServer.js

@@ -0,0 +1,269 @@
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { createConnection, createServer } from "node:net";
+import { dirname, join } from "node:path";
+import { CONTROLLER_DISCOVERY_PATH, CONTROLLER_SOCKET_PATH, MAX_CONTROLLER_MESSAGE_BYTES, ControllerProtocolError, controllerFailure, encodeControllerResponse, isEmptyParams, parseControllerRequest } from "./protocol.js";
+export async function startControllerServer(home, dispatcher) {
+    const discoveryPath = join(home, CONTROLLER_DISCOVERY_PATH);
+    const socketPath = join(home, CONTROLLER_SOCKET_PATH);
+    const runtimeDirectory = dirname(discoveryPath);
+    await mkdir(runtimeDirectory, { recursive: true, mode: 0o700 });
+    await chmod(runtimeDirectory, 0o700);
+    const token = randomBytes(32).toString("hex");
+    let closeRunning = async () => undefined;
+    const netServer = createServer((socket) => {
+        receiveRequest(socket, token, dispatcher, () => closeRunning());
+    });
+    try {
+        await listen(netServer, socketPath);
+    }
+    catch (error) {
+        if (!isAddressInUse(error))
+            throw error;
+        if (await socketIsReachable(socketPath))
+            throw controllerAlreadyRunning();
+        await rm(socketPath, { force: true });
+        try {
+            await listen(netServer, socketPath);
+        }
+        catch (retryError) {
+            if (isAddressInUse(retryError))
+                throw controllerAlreadyRunning();
+            throw retryError;
+        }
+    }
+    try {
+        await chmod(socketPath, 0o600);
+        const discovery = Object.freeze({
+            pid: process.pid,
+            socketPath,
+            token
+        });
+        await writeFile(discoveryPath, `${JSON.stringify(discovery)}\n`, { mode: 0o600 });
+        await chmod(discoveryPath, 0o600);
+        let resolveClosed = () => undefined;
+        const closed = new Promise((resolve) => {
+            resolveClosed = resolve;
+        });
+        let closePromise;
+        closeRunning = () => {
+            if (closePromise !== undefined)
+                return closePromise;
+            closePromise = (async () => {
+                await closeNetServer(netServer);
+                await removeOwnedDiscovery(discoveryPath, token);
+                resolveClosed();
+            })();
+            return closePromise;
+        };
+        return Object.freeze({ discovery, closed, close: closeRunning });
+    }
+    catch (error) {
+        await closeNetServer(netServer);
+        throw error;
+    }
+}
+function receiveRequest(socket, token, dispatcher, stop) {
+    let buffer = Buffer.alloc(0);
+    let complete = false;
+    const fail = (code, message, id = "invalid") => {
+        if (complete)
+            return;
+        complete = true;
+        sendResponse(socket, controllerFailure(id, code, message));
+    };
+    socket.on("data", (chunk) => {
+        if (complete)
+            return;
+        buffer = Buffer.concat([buffer, chunk]);
+        const newline = buffer.indexOf(0x0a);
+        if (newline < 0) {
+            if (buffer.length > MAX_CONTROLLER_MESSAGE_BYTES) {
+                fail("MESSAGE_TOO_LARGE", "Controller message exceeds 1 MiB.");
+            }
+            return;
+        }
+        if (newline > MAX_CONTROLLER_MESSAGE_BYTES) {
+            fail("MESSAGE_TOO_LARGE", "Controller message exceeds 1 MiB.");
+            return;
+        }
+        if (buffer.length !== newline + 1) {
+            fail("INVALID_REQUEST", "Invalid controller request.");
+            return;
+        }
+        complete = true;
+        void routeRequest(socket, buffer.subarray(0, newline).toString("utf8"), token, dispatcher, stop);
+    });
+    socket.on("end", () => {
+        if (!complete)
+            fail("INVALID_REQUEST", "Invalid controller request.");
+    });
+    socket.on("error", () => undefined);
+}
+async function routeRequest(socket, line, token, dispatcher, stop) {
+    let request;
+    try {
+        request = parseControllerRequest(line);
+    }
+    catch (error) {
+        const protocolError = error instanceof ControllerProtocolError
+            ? error
+            : new ControllerProtocolError("INVALID_REQUEST", "Invalid controller request.");
+        sendResponse(socket, controllerFailure(protocolError.id, protocolError.code, protocolError.message));
+        return;
+    }
+    if (!tokensMatch(request.token, token)) {
+        sendResponse(socket, controllerFailure(request.id, "UNAUTHORIZED", "Controller authentication failed."));
+        return;
+    }
+    if (request.method === "controller.status") {
+        if (!isEmptyParams(request.params)) {
+            sendResponse(socket, controllerFailure(request.id, "INVALID_PARAMS", "Controller params are invalid."));
+            return;
+        }
+        sendResponse(socket, {
+            id: request.id,
+            ok: true,
+            result: { pid: process.pid, running: true }
+        });
+        return;
+    }
+    if (request.method === "controller.stop") {
+        if (!isEmptyParams(request.params)) {
+            sendResponse(socket, controllerFailure(request.id, "INVALID_PARAMS", "Controller params are invalid."));
+            return;
+        }
+        sendResponse(socket, { id: request.id, ok: true, result: { stopped: true } }, () => void stop());
+        return;
+    }
+    if (dispatcher === undefined) {
+        sendResponse(socket, controllerFailure(request.id, "METHOD_NOT_FOUND", "Controller method was not found."));
+        return;
+    }
+    try {
+        const result = await dispatcher(request.method, request.params);
+        sendResponse(socket, { id: request.id, ok: true, result });
+    }
+    catch (error) {
+        const safeError = safeDispatcherError(error);
+        sendResponse(socket, safeError === undefined
+            ? controllerFailure(request.id, "INTERNAL_ERROR", "Controller request failed.")
+            : controllerFailure(request.id, safeError.code, safeError.message));
+    }
+}
+function sendResponse(socket, response, onFlushed) {
+    let line;
+    try {
+        line = encodeControllerResponse(response);
+    }
+    catch {
+        line = encodeControllerResponse(controllerFailure(response.id, "INTERNAL_ERROR", "Controller request failed."));
+    }
+    socket.end(line, onFlushed);
+}
+function tokensMatch(left, right) {
+    const leftBytes = Buffer.from(left, "hex");
+    const rightBytes = Buffer.from(right, "hex");
+    return leftBytes.length === rightBytes.length && timingSafeEqual(leftBytes, rightBytes);
+}
+function listen(server, socketPath) {
+    return new Promise((resolve, reject) => {
+        const onError = (error) => {
+            server.off("listening", onListening);
+            reject(error);
+        };
+        const onListening = () => {
+            server.off("error", onError);
+            resolve();
+        };
+        server.once("error", onError);
+        server.once("listening", onListening);
+        server.listen(socketPath);
+    });
+}
+function socketIsReachable(socketPath) {
+    return new Promise((resolve) => {
+        const socket = createConnection(socketPath);
+        socket.once("connect", () => {
+            socket.destroy();
+            resolve(true);
+        });
+        socket.once("error", () => {
+            socket.destroy();
+            resolve(false);
+        });
+    });
+}
+function closeNetServer(server) {
+    if (!server.listening)
+        return Promise.resolve();
+    return new Promise((resolve, reject) => {
+        server.close((error) => error === undefined ? resolve() : reject(error));
+    });
+}
+async function removeOwnedDiscovery(path, token) {
+    try {
+        const value = JSON.parse(await readFile(path, "utf8"));
+        if (typeof value === "object"
+            && value !== null
+            && "token" in value
+            && value.token === token) {
+            await rm(path, { force: true });
+        }
+    }
+    catch {
+        // Cleanup is best effort; transport shutdown must still finish.
+    }
+}
+function safeDispatcherError(error) {
+    try {
+        if (!(error instanceof Error) || typeof error.message !== "string")
+            return undefined;
+        const message = safeErrorMessage(error.message);
+        if (message === undefined)
+            return undefined;
+        switch (error.name) {
+            case "CoreApplicationError": {
+                const code = "code" in error && typeof error.code === "string"
+                    ? safeApplicationErrorCode(error.code)
+                    : undefined;
+                return code === undefined ? undefined : { code, message };
+            }
+            case "CoreServiceError":
+                return { code: "SERVICE_ERROR", message };
+            case "CoreJobError":
+                return { code: "JOB_ERROR", message };
+            default:
+                return undefined;
+        }
+    }
+    catch {
+        return undefined;
+    }
+}
+function safeApplicationErrorCode(code) {
+    switch (code) {
+        case "INVALID_PARAMS":
+        case "METHOD_NOT_FOUND":
+        case "NOT_FOUND":
+            return code;
+        default:
+            return undefined;
+    }
+}
+function safeErrorMessage(message) {
+    const safe = message
+        .replace(/[\r\n\u2028\u2029]+/gu, " ")
+        .trim()
+        .slice(0, 512);
+    return safe.length === 0 ? undefined : safe;
+}
+function controllerAlreadyRunning() {
+    return new Error("Controller is already running.");
+}
+function isAddressInUse(error) {
+    return isNodeError(error) && error.code === "EADDRINUSE";
+}
+function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}

package/dist/core/protocol.js

@@ -0,0 +1,169 @@
+export const MAX_CONTROLLER_MESSAGE_BYTES = 1_048_576;
+export const CONTROLLER_DISCOVERY_PATH = "runtime/controller.json";
+export const CONTROLLER_SOCKET_PATH = "runtime/controller.sock";
+export class ControllerProtocolError extends Error {
+    code;
+    id;
+    constructor(code, message, id = "invalid") {
+        super(message);
+        this.code = code;
+        this.id = id;
+        this.name = "ControllerProtocolError";
+    }
+}
+export function parseControllerRequest(line) {
+    if (Buffer.byteLength(line) > MAX_CONTROLLER_MESSAGE_BYTES) {
+        throw new ControllerProtocolError("MESSAGE_TOO_LARGE", "Controller message exceeds 1 MiB.");
+    }
+    try {
+        const value = JSON.parse(line);
+        if (!isRecord(value) || !hasExactKeys(value, ["id", "token", "method", "params"])) {
+            throw new Error("shape");
+        }
+        if (!isIdentifier(value.id)
+            || typeof value.token !== "string"
+            || !/^[a-f0-9]{64}$/u.test(value.token)
+            || typeof value.method !== "string"
+            || value.method.length > 128
+            || !/^[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*)*$/u.test(value.method)
+            || !isJsonValue(value.params)) {
+            throw new Error("fields");
+        }
+        return Object.freeze({
+            id: value.id,
+            token: value.token,
+            method: value.method,
+            params: value.params
+        });
+    }
+    catch (error) {
+        if (error instanceof ControllerProtocolError)
+            throw error;
+        throw new ControllerProtocolError("INVALID_REQUEST", "Invalid controller request.");
+    }
+}
+export function parseControllerResponse(line, expectedId) {
+    if (Buffer.byteLength(line) > MAX_CONTROLLER_MESSAGE_BYTES) {
+        throw invalidResponse();
+    }
+    try {
+        const value = JSON.parse(line);
+        if (!isRecord(value) || value.id !== expectedId || !isIdentifier(value.id)) {
+            throw new Error("identity");
+        }
+        if (value.ok === true) {
+            if (!hasExactKeys(value, ["id", "ok", "result"]) || !isJsonValue(value.result)) {
+                throw new Error("success");
+            }
+            return Object.freeze({ id: value.id, ok: true, result: value.result });
+        }
+        if (value.ok !== false
+            || !hasExactKeys(value, ["id", "ok", "error"])
+            || !isRecord(value.error)
+            || !hasExactKeys(value.error, ["code", "message"])
+            || typeof value.error.code !== "string"
+            || !/^[A-Z][A-Z0-9_]{0,63}$/u.test(value.error.code)
+            || typeof value.error.message !== "string"
+            || value.error.message.length === 0
+            || value.error.message.length > 512) {
+            throw new Error("failure");
+        }
+        return Object.freeze({
+            id: value.id,
+            ok: false,
+            error: Object.freeze({ code: value.error.code, message: value.error.message })
+        });
+    }
+    catch {
+        throw invalidResponse();
+    }
+}
+export function encodeControllerRequest(request) {
+    const line = JSON.stringify(request);
+    parseControllerRequest(line);
+    return appendNewline(line);
+}
+export function encodeControllerResponse(response) {
+    const line = JSON.stringify(response);
+    parseControllerResponse(line, response.id);
+    return appendNewline(line);
+}
+export function controllerFailure(id, code, message) {
+    return Object.freeze({
+        id,
+        ok: false,
+        error: Object.freeze({ code, message })
+    });
+}
+export function parseControllerDiscovery(value, expectedSocketPath) {
+    if (!isRecord(value)
+        || !hasExactKeys(value, ["pid", "socketPath", "token"])
+        || !Number.isSafeInteger(value.pid)
+        || value.pid < 1
+        || value.socketPath !== expectedSocketPath
+        || typeof value.token !== "string"
+        || !/^[a-f0-9]{64}$/u.test(value.token)) {
+        throw new ControllerProtocolError("CONTROLLER_DISCOVERY_INVALID", "Controller discovery is invalid.");
+    }
+    return Object.freeze({
+        pid: value.pid,
+        socketPath: value.socketPath,
+        token: value.token
+    });
+}
+export function isEmptyParams(value) {
+    return isRecord(value) && Reflect.ownKeys(value).length === 0;
+}
+function appendNewline(line) {
+    if (Buffer.byteLength(line) > MAX_CONTROLLER_MESSAGE_BYTES) {
+        throw new ControllerProtocolError("MESSAGE_TOO_LARGE", "Controller message exceeds 1 MiB.");
+    }
+    return `${line}\n`;
+}
+function invalidResponse() {
+    return new ControllerProtocolError("INVALID_RESPONSE", "Controller response is invalid.");
+}
+function isIdentifier(value) {
+    return typeof value === "string"
+        && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u.test(value);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasExactKeys(value, keys) {
+    const actual = Reflect.ownKeys(value);
+    return actual.length === keys.length
+        && actual.every((key) => typeof key === "string")
+        && keys.every((key) => Object.hasOwn(value, key));
+}
+function isJsonValue(value) {
+    const pending = [value];
+    const seen = new Set();
+    while (pending.length > 0) {
+        const current = pending.pop();
+        if (current === null
+            || typeof current === "string"
+            || typeof current === "boolean") {
+            continue;
+        }
+        if (typeof current === "number") {
+            if (!Number.isFinite(current))
+                return false;
+            continue;
+        }
+        if (typeof current !== "object")
+            return false;
+        if (seen.has(current))
+            return false;
+        seen.add(current);
+        if (Array.isArray(current)) {
+            pending.push(...current);
+            continue;
+        }
+        const prototype = Object.getPrototypeOf(current);
+        if (prototype !== Object.prototype && prototype !== null)
+            return false;
+        pending.push(...Object.values(current));
+    }
+    return true;
+}

package/dist/decision/decision.js

@@ -0,0 +1,42 @@
+export function createDecision(id, taskId, title, rationale, now) {
+    const timestamp = now.toISOString();
+    return {
+        schemaVersion: 1,
+        id: requireSafeIdentity(id, "Decision id"),
+        taskId: requireSafeIdentity(taskId, "Task id"),
+        title: requireText(title, "Decision title"),
+        rationale: requireText(rationale, "Decision rationale"),
+        status: "active",
+        createdAt: timestamp,
+        updatedAt: timestamp
+    };
+}
+export function supersedeDecision(decision, reason, now) {
+    if (decision.status === "superseded") {
+        throw new Error(`Decision is already superseded: ${decision.id}.`);
+    }
+    const timestamp = now.toISOString();
+    return {
+        ...decision,
+        status: "superseded",
+        supersededReason: requireText(reason, "Decision supersede reason"),
+        supersededAt: timestamp,
+        updatedAt: timestamp
+    };
+}
+function requireSafeIdentity(value, label) {
+    const normalized = requireText(value, label);
+    if (["__proto__", "prototype", "constructor", ".", ".."].includes(normalized)
+        || /[\/\\\0]/.test(normalized)) {
+        throw new Error(`${label} is invalid.`);
+    }
+    return normalized;
+}
+function requireText(value, label) {
+    if (typeof value !== "string" || value.includes("\0"))
+        throw new Error(`${label} is invalid.`);
+    const normalized = value.trim();
+    if (normalized.length === 0)
+        throw new Error(`${label} is required.`);
+    return normalized;
+}