kelocan 0.1.0

package/dist/commands.js

@@ -0,0 +1,278 @@
+import { readFileSync } from "node:fs";
+import { hostname } from "node:os";
+import { request } from "./api.js";
+import { flagStr } from "./args.js";
+import { clearConfig, readConfig, writeConfig } from "./config.js";
+import { usageError } from "./errors.js";
+import { browserLogin, saveLogin } from "./login.js";
+import { emit, line, outputOpts } from "./output.js";
+import { isUuid, resolveBoard, resolveColumn, resolveLabels } from "./resolve.js";
+const PRIORITIES = ["low", "medium", "high", "urgent"];
+const KINDS = ["task", "idea", "feedback"];
+const OUTCOMES = ["succeeded", "failed", "cancelled"];
+// ---------- auth ----------
+export async function cmdLogin(args) {
+    const url = flagStr(args.flags, "url");
+    const webUrl = flagStr(args.flags, "web-url");
+    const inlineKey = flagStr(args.flags, "api-key");
+    if (inlineKey) {
+        const user = await saveLogin({ url, webUrl, apiKey: inlineKey });
+        line(`Logged in as ${user.name} <${user.email ?? ""}>`);
+        return;
+    }
+    const name = flagStr(args.flags, "name") ?? hostname();
+    const { key } = await browserLogin(name);
+    const user = await saveLogin({ url, webUrl, apiKey: key });
+    line(`Logged in as ${user.name} <${user.email ?? ""}>`);
+}
+export async function cmdLogout() {
+    const config = readConfig();
+    if (!config.api_key) {
+        line("Not logged in.");
+        return;
+    }
+    delete config.api_key;
+    if (Object.keys(config).length === 0)
+        clearConfig();
+    else
+        writeConfig(config);
+    line("Logged out — API key removed from config.");
+}
+export async function cmdWhoami(args) {
+    const user = await request("/users/me");
+    emit(user, outputOpts(args), () => line(`${user.name} <${user.email ?? ""}> (${user.id})`));
+}
+// ---------- boards & tasks (read) ----------
+export async function cmdBoardShow(args) {
+    const ref = args._[0];
+    if (!ref)
+        throw usageError("Usage: kelocan board show <board>");
+    const board = await resolveBoard(ref);
+    emit(board, outputOpts(args), () => {
+        line(`Board: ${board.name} (${board.id})`);
+        if (board.description)
+            line(`  ${board.description}`);
+        if (board.purpose)
+            line(`  purpose: ${board.purpose}`);
+        if (board.sprint_context?.enabled) {
+            const s = board.sprint_context.active_sprint;
+            line(`  sprint: ${s ? `active=${s.name}` : "no active sprint"}`);
+        }
+        for (const c of board.columns ?? []) {
+            line(`  ${c.name} [${c.workflow_role}] — ${c.tasks?.length ?? 0} task(s)`);
+        }
+    });
+}
+export async function cmdTaskList(args) {
+    const ref = args._[0];
+    if (!ref)
+        throw usageError("Usage: kelocan task list <board> [--column X] [--label Y] [--sprint Z]");
+    const board = await resolveBoard(ref);
+    let tasks = collectTasks(board);
+    const colRef = flagStr(args.flags, "column");
+    if (colRef) {
+        const col = resolveColumn(board, colRef);
+        tasks = tasks.filter((t) => t.column_id === col.id);
+    }
+    const labelRef = flagStr(args.flags, "label");
+    if (labelRef) {
+        const wanted = labelRef.split(",").map((s) => s.trim().toLowerCase());
+        tasks = tasks.filter((t) => (t.labels ?? []).some((l) => wanted.includes(l.name.toLowerCase()) || wanted.includes(l.id.toLowerCase())));
+    }
+    const sprint = flagStr(args.flags, "sprint");
+    if (sprint)
+        tasks = filterSprint(tasks, board, sprint);
+    emit(tasks, outputOpts(args), () => {
+        for (const t of tasks) {
+            const labels = (t.labels ?? []).map((l) => l.name).join(",");
+            line(`${t.id}  ${t.title}  [${t.priority}]` +
+                `${t.column_name ? `  <${t.column_name}>` : ""}${labels ? `  {${labels}}` : ""}`);
+        }
+        if (tasks.length === 0)
+            line("(no tasks)");
+    });
+}
+function collectTasks(board) {
+    const out = [];
+    for (const c of board.columns ?? []) {
+        for (const t of c.tasks ?? [])
+            out.push({ ...t, column_name: c.name });
+    }
+    return out;
+}
+function filterSprint(tasks, board, sprint) {
+    const lower = sprint.toLowerCase();
+    if (lower === "backlog")
+        return tasks.filter((t) => !t.sprint_id);
+    if (lower === "active") {
+        const active = board.sprint_context?.active_sprint;
+        if (!active) {
+            throw usageError(`Board "${board.name}" has no active sprint (or sprint is disabled).`);
+        }
+        return tasks.filter((t) => t.sprint_id === active.id);
+    }
+    if (isUuid(sprint))
+        return tasks.filter((t) => t.sprint_id === sprint);
+    throw usageError(`Invalid --sprint value "${sprint}". Valid: active | backlog | <sprint UUID>`);
+}
+export async function cmdTaskShow(args) {
+    const id = args._[0];
+    if (!id)
+        throw usageError("Usage: kelocan task show <task-id>");
+    const task = await request(`/tasks/${id}`);
+    emit(task, outputOpts(args), () => {
+        line(`${task.title} (${task.id})`);
+        line(`  column: ${task.column_id}  kind: ${task.kind}  priority: ${task.priority}`);
+        if (task.is_blocked)
+            line(`  BLOCKED: ${task.blocked_reason ?? ""}`);
+        if (task.active_run)
+            line(`  active run: ${task.active_run.agent_name} (${task.active_run.id})`);
+        if ((task.subtask_total ?? 0) > 0)
+            line(`  subtasks: ${task.subtask_done}/${task.subtask_total}`);
+        if ((task.labels ?? []).length)
+            line(`  labels: ${(task.labels ?? []).map((l) => l.name).join(", ")}`);
+        if ((task.assignees ?? []).length)
+            line(`  assignees: ${(task.assignees ?? []).map((a) => a.name).join(", ")}`);
+        if (task.description)
+            line(`\n${task.description}`);
+    });
+}
+export async function cmdTaskPrompt(args) {
+    const id = args._[0];
+    if (!id)
+        throw usageError("Usage: kelocan task prompt <task-id>");
+    const prompt = await request(`/tasks/${id}/agent-prompt`);
+    emit(prompt, outputOpts(args), () => process.stdout.write(prompt.prompt + "\n"));
+}
+// ---------- tasks (write) ----------
+export async function cmdTaskCreate(args) {
+    const ref = args._[0];
+    const title = flagStr(args.flags, "title");
+    if (!ref || !title) {
+        throw usageError('Usage: kelocan task create <board> --title "..." [--column X]');
+    }
+    const board = await resolveBoard(ref);
+    const colRef = flagStr(args.flags, "column");
+    const column = colRef
+        ? resolveColumn(board, colRef)
+        : (board.columns.find((c) => c.workflow_role === "backlog") ?? board.columns[0]);
+    if (!column)
+        throw usageError(`Board "${board.name}" has no columns.`);
+    const kind = flagStr(args.flags, "kind") ?? "task";
+    if (!KINDS.includes(kind))
+        throw usageError(`Invalid --kind "${kind}". Valid: ${KINDS.join(", ")}`);
+    const priority = flagStr(args.flags, "priority") ?? "medium";
+    if (!PRIORITIES.includes(priority)) {
+        throw usageError(`Invalid --priority "${priority}". Valid: ${PRIORITIES.join(", ")}`);
+    }
+    const labelRefs = flagStr(args.flags, "label")?.split(",").map((s) => s.trim()) ?? [];
+    const label_ids = await resolveLabels(board.id, labelRefs);
+    const sprint = flagStr(args.flags, "sprint");
+    const body = {
+        column_id: column.id,
+        title,
+        kind,
+        priority,
+        label_ids,
+    };
+    const description = flagStr(args.flags, "description");
+    if (description !== undefined)
+        body.description = description;
+    if (sprint !== undefined) {
+        if (sprint !== "active" && sprint !== "backlog" && !isUuid(sprint)) {
+            throw usageError(`Invalid --sprint "${sprint}". Valid: active | backlog | <sprint UUID>`);
+        }
+        body.sprint = sprint;
+    }
+    const task = await request("/tasks", { body });
+    emit(task, outputOpts(args), () => line(`Created task ${task.id} — "${task.title}" in ${column.name}`));
+}
+export async function cmdTaskMove(args) {
+    const id = args._[0];
+    const to = flagStr(args.flags, "to");
+    if (!id || !to)
+        throw usageError("Usage: kelocan task move <task-id> --to <column|role|uuid>");
+    const task = await request(`/tasks/${id}`);
+    const column = await request(`/columns/${task.column_id}`);
+    const board = await request(`/boards/${column.board_id}`);
+    const target = resolveColumn(board, to);
+    const posRaw = flagStr(args.flags, "position");
+    const position = posRaw !== undefined ? Number(posRaw) : undefined;
+    if (position !== undefined && (!Number.isInteger(position) || position < 1)) {
+        throw usageError(`Invalid --position "${posRaw}". Must be an integer >= 1.`);
+    }
+    const moved = await request(`/tasks/${id}/move`, {
+        method: "PATCH",
+        body: { target_column_id: target.id, position },
+    });
+    emit(moved, outputOpts(args), () => line(`Moved "${moved.title}" → ${target.name} [${target.workflow_role}]`));
+}
+export async function cmdTaskComment(args) {
+    const id = args._[0];
+    const message = flagStr(args.flags, "message");
+    const file = flagStr(args.flags, "file");
+    if (!id || (!message && !file)) {
+        throw usageError('Usage: kelocan task comment <task-id> (-m "text" | --file path)');
+    }
+    if (message && file) {
+        throw usageError("Use either -m/--message or --file, not both.");
+    }
+    const form = new FormData();
+    if (message) {
+        form.append("content", message);
+    }
+    else {
+        const buf = readFileSync(file);
+        form.append("files", new Blob([buf]), file.split("/").pop());
+    }
+    const comment = await request(`/tasks/${id}/comments`, { form });
+    emit(comment, outputOpts(args), () => line(`Comment added to task ${id}`));
+}
+// ---------- agent runs & subtasks ----------
+export async function cmdRunStart(args) {
+    const taskId = args._[0];
+    const agent = flagStr(args.flags, "agent");
+    if (!taskId || !agent) {
+        throw usageError('Usage: kelocan run start <task-id> --agent "Devin" [--status "..."]');
+    }
+    const run = await request(`/tasks/${taskId}/agent-runs`, {
+        body: { agent_name: agent, status_text: flagStr(args.flags, "status") },
+    });
+    emit(run, outputOpts(args), () => {
+        line(`run_id: ${run.id}`);
+        line(`started: ${run.agent_name} on task ${run.task_id}`);
+    });
+}
+export async function cmdRunFinish(args) {
+    const runId = args._[0];
+    const outcome = flagStr(args.flags, "outcome");
+    if (!runId || !outcome) {
+        throw usageError("Usage: kelocan run finish <run-id> --outcome <succeeded|failed|cancelled> [-m ...]");
+    }
+    if (!OUTCOMES.includes(outcome)) {
+        throw usageError(`Invalid --outcome "${outcome}". Valid: ${OUTCOMES.join(", ")}`);
+    }
+    const run = await request(`/agent-runs/${runId}/finish`, {
+        body: { outcome, summary: flagStr(args.flags, "message") },
+    });
+    emit(run, outputOpts(args), () => line(`Run ${run.id} finished: ${run.status}`));
+}
+export async function cmdSubtaskList(args) {
+    const taskId = args._[0];
+    if (!taskId)
+        throw usageError("Usage: kelocan subtask list <task-id>");
+    const subs = await request(`/tasks/${taskId}/subtasks`);
+    emit(subs, outputOpts(args), () => {
+        for (const s of subs)
+            line(`${s.is_completed ? "[x]" : "[ ]"} ${s.id}  ${s.title}`);
+        if (subs.length === 0)
+            line("(no subtasks)");
+    });
+}
+export async function cmdSubtaskToggle(args) {
+    const id = args._[0];
+    if (!id)
+        throw usageError("Usage: kelocan subtask toggle <subtask-id>");
+    const sub = await request(`/subtasks/${id}/toggle`, { method: "PATCH" });
+    emit(sub, outputOpts(args), () => line(`${sub.is_completed ? "[x]" : "[ ]"} ${sub.title}`));
+}

package/dist/config.js

@@ -0,0 +1,70 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { dirname, join } from "node:path";
+export const DEFAULT_SERVER_URL = "https://api.kanban.sakze.com";
+export function configDir() {
+    if (platform() === "win32") {
+        return join(process.env.APPDATA ?? join(homedir(), "AppData", "Roaming"), "kelocan");
+    }
+    return join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "kelocan");
+}
+export function configPath() {
+    return join(configDir(), "config.json");
+}
+export function readConfig() {
+    const path = configPath();
+    if (!existsSync(path))
+        return {};
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+export function writeConfig(config) {
+    const path = configPath();
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    writeFileSync(path, JSON.stringify(config, null, 2) + "\n", { mode: 0o600 });
+    // Enforce 600 even if the file already existed with looser perms.
+    try {
+        chmodSync(path, 0o600);
+    }
+    catch {
+        /* best effort on non-POSIX filesystems */
+    }
+}
+export function clearConfig() {
+    const path = configPath();
+    if (existsSync(path))
+        rmSync(path);
+}
+/** API base URL including /api/v1 suffix. Env KELOCAN_URL wins over config. */
+export function apiBase(config = readConfig()) {
+    let url = (process.env.KELOCAN_URL ?? config.url ?? DEFAULT_SERVER_URL).replace(/\/+$/, "");
+    if (!url.endsWith("/api/v1"))
+        url += "/api/v1";
+    return url;
+}
+/** Web app base URL for /cli/authorize. Env KELOCAN_WEB_URL wins over config. */
+export function webBase(config = readConfig()) {
+    if (process.env.KELOCAN_WEB_URL)
+        return process.env.KELOCAN_WEB_URL.replace(/\/+$/, "");
+    if (config.web_url)
+        return config.web_url.replace(/\/+$/, "");
+    const api = apiBase(config);
+    // Derive: strip /api/v1 suffix and a leading "api." subdomain.
+    const origin = api.replace(/\/api\/v1$/, "");
+    try {
+        const u = new URL(origin);
+        u.hostname = u.hostname.replace(/^api\./, "");
+        return u.origin;
+    }
+    catch {
+        return origin;
+    }
+}
+/** API key: env KELOCAN_API_KEY wins over config. */
+export function apiKey(config = readConfig()) {
+    return process.env.KELOCAN_API_KEY ?? config.api_key;
+}

package/dist/doctor.js

@@ -0,0 +1,198 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { detectAll } from "./agents.js";
+import { apiBase, apiKey, readConfig } from "./config.js";
+import { mcpUrl, probeMcp } from "./install.js";
+import { parseJsonc } from "./jsonc.js";
+import { verifyKey } from "./login.js";
+import { SKILL_NAMES, skillStatus } from "./skills.js";
+const EXPECTED_URL_HINT = "kelocan mcp install --agent <name>";
+function checkConfigEntry(det, expectedUrl) {
+    const out = [];
+    const { def, configPath } = det;
+    if (!existsSync(configPath)) {
+        out.push({
+            level: "fail",
+            message: `config ${configPath} not found`,
+            fix: `kelocan mcp install --agent ${def.id}`,
+        });
+        return out;
+    }
+    const text = readFileSync(configPath, "utf8");
+    if (def.format === "json") {
+        let parsed;
+        try {
+            parsed = parseJsonc(text);
+        }
+        catch (e) {
+            out.push({
+                level: "fail",
+                message: `config ${configPath} is invalid JSON: ${e instanceof Error ? e.message : e}`,
+                fix: `restore ${configPath}.bak or run ${EXPECTED_URL_HINT.replace("<name>", def.id)}`,
+            });
+            return out;
+        }
+        const container = parsed[def.containerKey];
+        let entry = container?.kelocan;
+        let entryNote = "";
+        if (!entry && def.id === "claude") {
+            // `claude mcp add` may store the entry under projects.<dir>.mcpServers
+            const projects = parsed.projects;
+            for (const [dir, proj] of Object.entries(projects ?? {})) {
+                const e = proj.mcpServers?.kelocan;
+                if (e) {
+                    entry = e;
+                    entryNote = ` (local scope under project ${dir})`;
+                    break;
+                }
+            }
+        }
+        if (!entry) {
+            out.push({
+                level: "fail",
+                message: `no ${def.containerKey}.kelocan entry in ${configPath}`,
+                fix: `kelocan mcp install --agent ${def.id}`,
+            });
+            return out;
+        }
+        const url = (entry.url ?? entry.serverUrl);
+        if (url !== expectedUrl) {
+            out.push({
+                level: "warn",
+                message: `kelocan MCP url is "${url ?? "(missing)"}", expected "${expectedUrl}"`,
+                fix: `kelocan mcp install --agent ${def.id}`,
+            });
+        }
+        else {
+            out.push({ level: "ok", message: `MCP entry ok (${configPath}${entryNote})` });
+        }
+    }
+    else if (def.format === "toml") {
+        if (!text.includes("[mcp_servers.kelocan]")) {
+            out.push({
+                level: "fail",
+                message: `no [mcp_servers.kelocan] section in ${configPath}`,
+                fix: `kelocan mcp install --agent ${def.id}`,
+            });
+        }
+        else if (!text.includes(`url = "${expectedUrl}"`)) {
+            out.push({
+                level: "warn",
+                message: `kelocan MCP url in ${configPath} does not match ${expectedUrl}`,
+                fix: `kelocan mcp install --agent ${def.id}`,
+            });
+        }
+        else {
+            out.push({ level: "ok", message: `MCP entry ok (${configPath})` });
+        }
+    }
+    else {
+        // yaml
+        if (!/^\s+kelocan\s*:/m.test(text)) {
+            out.push({
+                level: "fail",
+                message: `no mcp_servers.kelocan entry in ${configPath}`,
+                fix: `kelocan mcp install --agent ${def.id}`,
+            });
+        }
+        else if (!text.includes(`url: "${expectedUrl}"`) && !text.includes(`url: ${expectedUrl}`)) {
+            out.push({
+                level: "warn",
+                message: `kelocan MCP url in ${configPath} does not match ${expectedUrl}`,
+                fix: `kelocan mcp install --agent ${def.id}`,
+            });
+        }
+        else {
+            out.push({ level: "ok", message: `MCP entry ok (${configPath})` });
+        }
+    }
+    return out;
+}
+function checkSkills(det) {
+    const out = [];
+    for (const dir of det.skillDirs) {
+        for (const name of SKILL_NAMES) {
+            const st = skillStatus(dir, name);
+            if (st === "missing") {
+                out.push({
+                    level: "fail",
+                    message: `skill "${name}" missing in ${dir}`,
+                    fix: `kelocan skills install --agent ${det.def.id}`,
+                });
+            }
+            else if (st === "current") {
+                out.push({ level: "ok", message: `skill "${name}" installed (${dir})` });
+            }
+            else {
+                out.push({
+                    level: "warn",
+                    message: `skill "${name}" in ${dir} differs from bundled copy (${st})`,
+                    fix: `kelocan skills install --agent ${det.def.id}`,
+                });
+            }
+        }
+    }
+    return out;
+}
+export async function runDoctor(home = homedir()) {
+    const expectedUrl = mcpUrl();
+    const server = [];
+    // connectivity (REST base) + auth
+    const base = apiBase(readConfig());
+    const key = apiKey();
+    try {
+        const res = await fetch(base.replace(/\/api\/v1$/, "") || base, { method: "HEAD" }).catch(() => null);
+        server.push({
+            level: res ? "ok" : "warn",
+            message: `server ${base} ${res ? "reachable" : "did not answer HEAD"}`,
+        });
+    }
+    catch {
+        server.push({ level: "warn", message: `server ${base} unreachable` });
+    }
+    if (key) {
+        try {
+            const user = await verifyKey(base, key);
+            server.push({ level: "ok", message: `authenticated as ${user.name}` });
+        }
+        catch (e) {
+            server.push({
+                level: "fail",
+                message: `auth failed: ${e instanceof Error ? e.message : e}`,
+                fix: "kelocan login",
+            });
+        }
+    }
+    else {
+        server.push({ level: "warn", message: "no API key configured", fix: "kelocan login" });
+    }
+    try {
+        const status = await probeMcp(expectedUrl, key);
+        server.push({ level: "ok", message: `MCP ${expectedUrl} ${status}` });
+    }
+    catch (e) {
+        server.push({
+            level: "fail",
+            message: `MCP ${expectedUrl}: ${e instanceof Error ? e.message : e}`,
+        });
+    }
+    const agents = detectAll(home).map((det) => {
+        if (!det.detected) {
+            return {
+                agent: det.def.id,
+                name: det.def.name,
+                detected: false,
+                findings: [{ level: "info", message: "not installed — skipped" }],
+            };
+        }
+        return {
+            agent: det.def.id,
+            name: det.def.name,
+            detected: true,
+            findings: [...checkConfigEntry(det, expectedUrl), ...checkSkills(det)],
+        };
+    });
+    const ok = !server.some((f) => f.level === "fail") &&
+        !agents.some((a) => a.findings.some((f) => f.level === "fail"));
+    return { server, agents, ok };
+}

package/dist/errors.js

@@ -0,0 +1,15 @@
+/** Exit codes: 0 ok, 1 validation/client error, 2 auth, 3 network/server. */
+export class CliError extends Error {
+    exitCode;
+    constructor(message, exitCode = 1) {
+        super(message);
+        this.exitCode = exitCode;
+        this.name = "CliError";
+    }
+}
+export function usageError(message) {
+    return new CliError(message, 1);
+}
+export function authError(message) {
+    return new CliError(message, 2);
+}