@zq-silk/yui 0.0.0

package/dist/task/task.js

@@ -0,0 +1,216 @@
+export function createTask(id, title, now, metadata = {}) {
+    const timestamp = now.toISOString();
+    return {
+        schemaVersion: 1,
+        id: requireSafeIdentity(id, "Task id"),
+        title: requireText(title, "Task title"),
+        ...cloneMetadata(metadata),
+        status: "draft",
+        createdAt: timestamp,
+        updatedAt: timestamp
+    };
+}
+export function activateTask(task, now) {
+    if (task.status === "archived")
+        throw new Error(`Cannot activate archived Task: ${task.id}.`);
+    if (task.status === "completed")
+        throw new Error(`Cannot activate completed Task ${task.id}; reopen it instead.`);
+    if (task.status === "active")
+        return task;
+    return { ...task, status: "active", updatedAt: now.toISOString() };
+}
+export function completeTask(task, now, completion) {
+    if (task.status === "completed")
+        return task;
+    if (task.status !== "active") {
+        throw new Error(`Only an active Task can be completed: ${task.id}.`);
+    }
+    const timestamp = now.toISOString();
+    return {
+        ...task,
+        status: "completed",
+        completedAt: timestamp,
+        completedBy: completion.by,
+        completionSummary: requireText(completion.summary, "Task completion summary"),
+        updatedAt: timestamp
+    };
+}
+export function reopenTask(task, now) {
+    if (task.status === "archived")
+        throw new Error(`Cannot reopen archived Task: ${task.id}.`);
+    if (task.status !== "completed") {
+        throw new Error(`Only a completed Task can be reopened: ${task.id}.`);
+    }
+    const { completedAt: _completedAt, completedBy: _completedBy, completionSummary: _completionSummary, ...reopened } = task;
+    return { ...reopened, status: "active", updatedAt: now.toISOString() };
+}
+export function archiveTask(task, now, archive) {
+    if (task.status === "archived")
+        return task;
+    const timestamp = now.toISOString();
+    return {
+        ...task,
+        status: "archived",
+        archivedAt: timestamp,
+        archivedBy: archive?.by ?? "user",
+        ...(archive?.reason === undefined ? {} : { archiveReason: archive.reason.trim() }),
+        ...(archive?.summary === undefined ? {} : { archiveSummary: archive.summary.trim() }),
+        updatedAt: timestamp
+    };
+}
+export function updateTaskArchived(task, archived, now, archive) {
+    if (archived)
+        return archiveTask(task, now, archive);
+    if (task.status === "archived") {
+        throw new Error(`Cannot reopen archived Task: ${task.id}.`);
+    }
+    return { ...task, updatedAt: now.toISOString() };
+}
+export function updateTaskMetadata(task, metadata, now) {
+    const updated = { ...task, updatedAt: now.toISOString() };
+    if (metadata.title !== undefined)
+        updated.title = requireText(metadata.title, "Task title");
+    applyOptional(updated, "description", metadata.description);
+    applyOptional(updated, "priority", metadata.priority);
+    applyOptional(updated, "tags", metadata.tags === undefined || metadata.tags === null
+        ? metadata.tags
+        : [...metadata.tags]);
+    applyOptional(updated, "dueAt", metadata.dueAt);
+    if (metadata.repositoryId !== undefined) {
+        updated.repositoryId = requireSafeIdentity(metadata.repositoryId, "Repository id");
+    }
+    if (metadata.baseRef !== undefined)
+        updated.baseRef = requireText(metadata.baseRef, "Task base ref");
+    if (metadata.cwd !== undefined)
+        updated.cwd = requireText(metadata.cwd, "Task workspace");
+    validateRepositorySelection(updated);
+    return updated;
+}
+function applyOptional(task, key, value) {
+    if (value === undefined)
+        return;
+    if (value === null)
+        delete task[key];
+    else
+        task[key] = value;
+}
+export function updateTaskWorkspace(task, cwd, now) {
+    return { ...task, cwd: requireText(cwd, "Task workspace"), updatedAt: now.toISOString() };
+}
+export function isTaskArchived(task) {
+    return task.status === "archived";
+}
+export function validateTask(task) {
+    if (task.schemaVersion !== 1)
+        throw new Error("Task must use schemaVersion 1.");
+    requireSafeIdentity(task.id, "Task id");
+    requireText(task.title, "Task title");
+    if (!["draft", "active", "completed", "archived"].includes(task.status)) {
+        throw new Error(`Task status is invalid: ${String(task.status)}.`);
+    }
+    requireTimestamp(task.createdAt, "Task createdAt");
+    requireTimestamp(task.updatedAt, "Task updatedAt");
+    if (Date.parse(task.updatedAt) < Date.parse(task.createdAt)) {
+        throw new Error("Task updatedAt cannot precede createdAt.");
+    }
+    if (task.priority !== undefined
+        && !["low", "medium", "high", "urgent"].includes(task.priority)) {
+        throw new Error(`Task priority is invalid: ${String(task.priority)}.`);
+    }
+    if (task.description !== undefined)
+        requireText(task.description, "Task description");
+    if (task.tags !== undefined) {
+        if (!Array.isArray(task.tags))
+            throw new Error("Task tags are invalid.");
+        for (const tag of task.tags)
+            requireText(tag, "Task tag");
+    }
+    if (task.dueAt !== undefined)
+        requireTimestamp(task.dueAt, "Task dueAt");
+    if (task.repositoryId !== undefined)
+        requireSafeIdentity(task.repositoryId, "Repository id");
+    if (task.baseRef !== undefined)
+        requireText(task.baseRef, "Task base ref");
+    if (task.cwd !== undefined)
+        requireText(task.cwd, "Task workspace");
+    validateRepositorySelection(task);
+    const completionFields = [task.completedAt, task.completedBy, task.completionSummary];
+    const hasAnyCompletion = completionFields.some((value) => value !== undefined);
+    const hasAllCompletion = completionFields.every((value) => value !== undefined);
+    if (hasAnyCompletion && !hasAllCompletion) {
+        throw new Error("Task completion metadata must include completedAt, completedBy, and completionSummary.");
+    }
+    if (hasAllCompletion) {
+        requireTimestamp(task.completedAt, "Task completedAt");
+        if (!["user", "operator", "leader"].includes(task.completedBy)) {
+            throw new Error(`Task completedBy is invalid: ${String(task.completedBy)}.`);
+        }
+        requireText(task.completionSummary, "Task completion summary");
+    }
+    if (task.status === "completed" && !hasAllCompletion) {
+        throw new Error("A completed Task requires completedAt, completedBy, and completionSummary.");
+    }
+    if ((task.status === "draft" || task.status === "active") && hasAnyCompletion) {
+        throw new Error(`Task completion metadata is invalid for ${task.status} status.`);
+    }
+    const hasAnyArchive = [task.archivedAt, task.archivedBy, task.archiveReason, task.archiveSummary]
+        .some((value) => value !== undefined);
+    if (task.status === "archived") {
+        if (task.archivedAt === undefined || task.archivedBy === undefined) {
+            throw new Error("An archived Task requires archivedAt and archivedBy.");
+        }
+        requireTimestamp(task.archivedAt, "Task archivedAt");
+        if (!["user", "operator", "leader"].includes(task.archivedBy)) {
+            throw new Error(`Task archivedBy is invalid: ${String(task.archivedBy)}.`);
+        }
+        if (task.archiveReason !== undefined)
+            requireText(task.archiveReason, "Task archive reason");
+        if (task.archiveSummary !== undefined)
+            requireText(task.archiveSummary, "Task archive summary");
+    }
+    else if (hasAnyArchive) {
+        throw new Error(`Task archive metadata is invalid for ${task.status} status.`);
+    }
+    return task;
+}
+function cloneMetadata(metadata) {
+    const cloned = {
+        ...(metadata.description === undefined ? {} : { description: metadata.description }),
+        ...(metadata.priority === undefined ? {} : { priority: metadata.priority }),
+        ...(metadata.tags === undefined ? {} : { tags: [...metadata.tags] }),
+        ...(metadata.dueAt === undefined ? {} : { dueAt: metadata.dueAt }),
+        ...(metadata.repositoryId === undefined
+            ? {}
+            : { repositoryId: requireSafeIdentity(metadata.repositoryId, "Repository id") }),
+        ...(metadata.baseRef === undefined ? {} : { baseRef: requireText(metadata.baseRef, "Task base ref") }),
+        ...(metadata.cwd === undefined ? {} : { cwd: requireText(metadata.cwd, "Task workspace") })
+    };
+    validateRepositorySelection(cloned);
+    return cloned;
+}
+function validateRepositorySelection(value) {
+    if (value.baseRef !== undefined && value.repositoryId === undefined) {
+        throw new Error("Task base ref requires a repository.");
+    }
+}
+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;
+}
+function requireTimestamp(value, label) {
+    if (typeof value !== "string" || !Number.isFinite(Date.parse(value))) {
+        throw new Error(`${label} is invalid.`);
+    }
+}

package/dist/tmux/commandExecutor.js

@@ -0,0 +1,69 @@
+import { spawnSync } from "node:child_process";
+export class CommandExecutionError extends Error {
+    code;
+    exitStatus;
+    stderr;
+    constructor(code, exitStatus, stderr = "") {
+        super(commandExecutionMessage(code));
+        this.code = code;
+        this.exitStatus = exitStatus;
+        this.stderr = stderr;
+        this.name = "CommandExecutionError";
+    }
+}
+export class NodeCommandExecutor {
+    run(command, args, options = {}) {
+        const common = options.timeoutMs === undefined ? {} : { timeout: options.timeoutMs };
+        const result = options.inheritStdio === true
+            ? spawnSync(command, args, { ...common, stdio: "inherit" })
+            : spawnSync(command, args, {
+                ...common,
+                encoding: "utf8",
+                stdio: ["ignore", "pipe", "pipe"]
+            });
+        if (result.error !== undefined || result.status !== 0) {
+            throw stableCommandExecutionError(result);
+        }
+        return options.inheritStdio === true ? "" : String(result.stdout ?? "");
+    }
+}
+function stableCommandExecutionError(error) {
+    const details = errorDetails(error);
+    if (details.code === "ENOENT") {
+        return new CommandExecutionError("COMMAND_NOT_FOUND", details.exitStatus, details.stderr);
+    }
+    if (details.code === "ETIMEDOUT"
+        || details.signal === "SIGTERM"
+        || details.signal === "SIGKILL") {
+        return new CommandExecutionError("COMMAND_TIMED_OUT", details.exitStatus, details.stderr);
+    }
+    return new CommandExecutionError("COMMAND_FAILED", details.exitStatus, details.stderr);
+}
+function errorDetails(error) {
+    if (typeof error !== "object" || error === null)
+        return { stderr: "" };
+    const candidate = error;
+    const nested = typeof candidate.error === "object" && candidate.error !== null
+        ? candidate.error
+        : {};
+    return {
+        ...(typeof candidate.code === "string"
+            ? { code: candidate.code }
+            : typeof nested.code === "string" ? { code: nested.code } : {}),
+        ...(typeof candidate.signal === "string" ? { signal: candidate.signal } : {}),
+        ...(typeof candidate.status === "number" ? { exitStatus: candidate.status } : {}),
+        stderr: typeof candidate.stderr === "string"
+            ? candidate.stderr
+            : Buffer.isBuffer(candidate.stderr) ? candidate.stderr.toString("utf8") : ""
+    };
+}
+function commandExecutionMessage(code) {
+    switch (code) {
+        case "COMMAND_NOT_FOUND":
+            return "Command was not found.";
+        case "COMMAND_TIMED_OUT":
+            return "Command execution timed out.";
+        case "COMMAND_FAILED":
+            return "Command execution failed.";
+    }
+}

package/dist/tmux/terminalHandoff.js

@@ -0,0 +1,17 @@
+/**
+ * Release every Yui claim on a terminal before a foreground tmux client
+ * inherits it. The optional close callback is expected to be idempotent.
+ */
+export function handoffTerminal(input, closeInteractiveInput = () => { }) {
+    try {
+        closeInteractiveInput();
+    }
+    finally {
+        if (input.isTTY === true
+            && input.isRaw === true
+            && typeof input.setRawMode === "function") {
+            input.setRawMode(false);
+        }
+        input.pause();
+    }
+}