@evanbobo/colco4dsh 0.0.0-stage → 0.1.4

package/lib/tasks.mjs

@@ -0,0 +1,158 @@
+// The My Tasks board's side of the plugin: what the browser may ask for, the colco command that asks it, and how
+// colco's reply is shaped before the page sees it. Pure functions, so the route stays a thin wrapper and every rule
+// here is testable without a process or a socket.
+import { field } from "./format.mjs";
+import { safeLink } from "./dashboard.mjs";
+
+/** Tasks per page. The plugin sets it; the browser cannot. */
+export const BOARD_PAGE_SIZE = 25;
+
+/** Highest page the board asks for; the same cap the Colco server enforces. */
+export const MAX_BOARD_PAGE = 10000;
+
+/** Longest task title and project name kept; the server allows 200 and 80 characters. */
+const TITLE_MAX = 200;
+const PROJECT_NAME_MAX = 80;
+
+/** Most project choices kept for the filter. */
+const PROJECT_CHOICES_MAX = 200;
+
+/** The statuses of a task in board order, as the Colco server lists them: work in flight first, done last. */
+export const BOARD_STATUSES = ["in_progress", "blocked", "review", "todo", "backlog", "done"];
+
+/** Task priorities Colco knows. */
+const PRIORITIES = new Set(["high", "medium", "low"]);
+
+/** The only query keys the route accepts. */
+const QUERY_KEYS = new Set(["project", "status", "page"]);
+
+/**
+ * Parse the query of `GET tasks`. Only a project id, one of the six statuses and a page number pass, written as plain
+ * digits or exact words, each at most once. Anything else, including a key that could name a person, is refused, so
+ * nothing the browser sends can reach the colco command as an option or as free text.
+ * @param {URLSearchParams} search
+ * @returns {{ ok: true, value: { project?: number, status?: string, page: number } } | { ok: false, error: string }}
+ */
+export function parseBoardQuery(search) {
+  for (const key of new Set(search.keys())) {
+    if (!QUERY_KEYS.has(key)) return { ok: false, error: `unknown query parameter: ${key.slice(0, 40)}` };
+    if (search.getAll(key).length > 1) return { ok: false, error: `${key} may be given only once` };
+  }
+  const value = { page: 1 };
+  if (search.has("project")) {
+    const project = search.get("project");
+    if (!/^[1-9]\d{0,14}$/.test(project)) return { ok: false, error: "project must be a project id: digits, starting at 1" };
+    value.project = Number(project);
+  }
+  if (search.has("status")) {
+    const status = search.get("status");
+    if (!BOARD_STATUSES.includes(status)) return { ok: false, error: `status must be one of ${BOARD_STATUSES.join(", ")}` };
+    value.status = status;
+  }
+  if (search.has("page")) {
+    const page = search.get("page");
+    if (!/^[1-9]\d{0,4}$/.test(page) || Number(page) > MAX_BOARD_PAGE) return { ok: false, error: `page must be a number from 1 to ${MAX_BOARD_PAGE}` };
+    value.page = Number(page);
+  }
+  return { ok: true, value };
+}
+
+/**
+ * The colco arguments for a parsed query. Each value becomes its own argv element; the page size is the plugin's.
+ * @param {{ project?: number, status?: string, page?: number }} query - the value from parseBoardQuery.
+ */
+export function boardArgs(query) {
+  return [
+    "tasks", "--json",
+    ...query.project !== undefined ? ["--project-id", String(query.project)] : [],
+    ...query.status !== undefined ? ["--status", query.status] : [],
+    "--page", String(query.page ?? 1),
+    "--page-size", String(BOARD_PAGE_SIZE),
+  ];
+}
+
+/**
+ * A string cut to `max` characters, or undefined when the value is not a non-empty string.
+ * @param {unknown} value
+ * @param {number} max
+ */
+function text(value, max) {
+  return typeof value === "string" && value ? value.slice(0, max) : undefined;
+}
+
+/**
+ * A positive safe integer, or undefined.
+ * @param {unknown} value
+ */
+function positive(value) {
+  return Number.isSafeInteger(value) && value >= 1 ? value : undefined;
+}
+
+/**
+ * A non-negative safe integer, or the fallback.
+ * @param {unknown} value
+ * @param {number} fallback
+ */
+function count(value, fallback = 0) {
+  return Number.isSafeInteger(value) && value >= 0 ? value : fallback;
+}
+
+/**
+ * One task for the board, or undefined when it lacks a usable id or status. Only these fields are kept, so a
+ * description or assignee a future server adds never reaches the browser; the link must be an http(s) URL.
+ * @param {Record<string, unknown>} raw - one entry of `tasks` from `colco tasks --json`.
+ */
+function boardTask(raw) {
+  const id = positive(raw.id);
+  if (id === undefined || !BOARD_STATUSES.includes(raw.status)) return undefined;
+  return {
+    id,
+    projectId: positive(raw.projectId),
+    projectName: text(raw.projectName, PROJECT_NAME_MAX),
+    title: text(raw.title, TITLE_MAX),
+    status: raw.status,
+    priority: PRIORITIES.has(raw.priority) ? raw.priority : undefined,
+    dueDate: typeof raw.dueDate === "string" && /^\d{4}-\d{2}-\d{2}$/.test(raw.dueDate) ? raw.dueDate : null,
+    updatedAt: text(raw.updatedAt, 40),
+    link: safeLink(raw.link),
+  };
+}
+
+/**
+ * The reply of `GET tasks`: the page of tasks, the paging numbers, one count per status in board order and the
+ * projects to filter by, each type-checked and cut. A reply without a `tasks` array fails like any malformed colco
+ * reply instead of showing an empty board.
+ * @param {Record<string, unknown>} body - `colco tasks --json`.
+ */
+export function boardReply(body) {
+  const raw = field(body, "tasks", "array", "colco tasks");
+  const pageSize = positive(body.pageSize) && body.pageSize <= 100 ? body.pageSize : BOARD_PAGE_SIZE;
+  const total = count(body.total);
+
+  const perStatus = new Map();
+  if (Array.isArray(body.counts)) {
+    for (const entry of body.counts) {
+      if (entry !== null && typeof entry === "object" && BOARD_STATUSES.includes(entry.status) && !perStatus.has(entry.status)) perStatus.set(entry.status, count(entry.count));
+    }
+  }
+
+  const projects = [];
+  if (Array.isArray(body.projects)) {
+    for (const entry of body.projects) {
+      if (projects.length === PROJECT_CHOICES_MAX) break;
+      const id = entry !== null && typeof entry === "object" ? positive(entry.id) : undefined;
+      const name = id === undefined ? undefined : text(entry.name, PROJECT_NAME_MAX);
+      if (id !== undefined && name !== undefined) projects.push({ id, name, count: count(entry.count) });
+    }
+  }
+
+  return {
+    tasks: raw.map(boardTask).filter((task) => task !== undefined).slice(0, pageSize),
+    page: positive(body.page) && body.page <= MAX_BOARD_PAGE ? body.page : 1,
+    pageSize,
+    total,
+    pages: Math.max(1, Math.ceil(total / pageSize)),
+    counts: BOARD_STATUSES.map((status) => ({ status, count: perStatus.get(status) ?? 0 })),
+    projects,
+  };
+}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Colco",
+    "description": "See your Colco runner, active runs and open decisions in a sidebar tab, set up the runner's rules, and answer decisions from chat."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Colco",
+    "description": "\u5728\u4fa7\u8fb9\u680f\u67e5\u770b Colco Runner\u3001\u8fdb\u884c\u4e2d\u7684\u8fd0\u884c\u548c\u5f85\u51b3\u7b56\uff0c\u8bbe\u7f6e Runner \u89c4\u5219\uff0c\u4e5f\u53ef\u4ee5\u5728\u5bf9\u8bdd\u4e2d\u56de\u7b54\u51b3\u7b56\u3002"
+  }
+}

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@evanbobo/colco4dsh",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.4",
+  "private": false,
+  "description": "DSH plugin for Colco: a Colco page in the left sidebar with your runner, active runs and open decisions, plus chat tools to see and answer them",
+  "type": "module",
+  "main": "index.mjs",
+  "exports": {
+    ".": "./index.mjs",
+    "./client": "./client.js",
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.mjs",
+    "client.js",
+    "lib",
+    "locale/*.json",
+    "icon.svg",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-layout",
+        "@deepseek-ai/dsh-client-ui-sidebar",
+        "@deepseek-ai/dsh-client-ui-renderer"
+      ]
+    }
+  },
+  "engines": {
+    "dsh": ">=0.2.0 <0.3.0",
+    "node": ">=20.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-tools": ">=0.2.0-0 <0.3.0",
+    "@deepseek-ai/schemastery": ">=3.18.0-0 <4.0.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-tools": "0.2.2-alpha.2",
+    "@deepseek-ai/schemastery": "3.18.6-alpha.1"
+  },
+  "scripts": {
+    "test": "bun test"
+  },
+  "keywords": [
+    "colco",
+    "deepseek-harness",
+    "dsh-plugin"
+  ],
+  "license": "MIT"
+}