kankaku 0.6.0 → 0.7.0

package/dist/domain/work-target.js

@@ -26,7 +26,18 @@ function findUsableProject(projects, projectId, clientId) {
         return undefined;
     return project;
 }
-function buildTarget(client, project) {
+/**
+ * A hub task usable as a link target: exists and belongs to `projectId`.
+ * Any {@link HubTask.status} is accepted — a task marked `done` mid-session
+ * keeps linking — only the project match matters here.
+ */
+function findUsableTask(tasks, taskId, projectId) {
+    const task = tasks.find((candidate) => candidate.id === taskId);
+    if (!task || task.projectId !== projectId)
+        return undefined;
+    return task;
+}
+function buildTarget(client, project, task) {
     return {
         clientId: client.id,
         clientCode: client.code,
@@ -38,6 +49,7 @@ function buildTarget(client, project) {
                 projectName: project.name,
             }
             : {}),
+        ...(task !== undefined ? { hubTaskId: task.id, hubTaskTitle: task.title } : {}),
     };
 }
 /**
@@ -45,14 +57,17 @@ function buildTarget(client, project) {
  * file) into a target, or `undefined` when the client id does not resolve
  * to a usable client. A projectId that does not resolve to a usable
  * project of that client is dropped — the client-only target is still
- * returned — rather than failing the whole candidate.
+ * returned — rather than failing the whole candidate. A `hubTaskId` is
+ * kept only when it resolves to a task of the resolved project; a target
+ * with no project never carries one.
  */
-function resolveCandidate(candidate, clients, projects) {
+function resolveCandidate(candidate, clients, projects, tasks) {
     const client = findUsableClient(clients, candidate.clientId);
     if (!client)
         return undefined;
     const project = candidate.projectId !== undefined ? findUsableProject(projects, candidate.projectId, client.id) : undefined;
-    return buildTarget(client, project);
+    const task = project !== undefined && candidate.hubTaskId !== undefined ? findUsableTask(tasks, candidate.hubTaskId, project.id) : undefined;
+    return buildTarget(client, project, task);
 }
 /** The longest-matching active project whose `repoPaths` contains `cwd`, exactly or as an ancestor directory. */
 function matchByRepoPath(cwd, projects) {
@@ -82,11 +97,12 @@ function isCwdWithin(cwd, repoPath) {
 /** Which source (if any) {@link resolveWorkTarget} would use, computed independently so callers can display it. */
 export function resolveWorkTargetSource(input) {
     const { session } = input;
+    const tasks = input.tasks ?? [];
     if (session === "skipped")
         return undefined;
-    if (session !== undefined && resolveCandidate(session, input.clients, input.projects) !== undefined)
+    if (session !== undefined && resolveCandidate(session, input.clients, input.projects, tasks) !== undefined)
         return "session";
-    if (input.project !== undefined && resolveCandidate(input.project, input.clients, input.projects) !== undefined)
+    if (input.project !== undefined && resolveCandidate(input.project, input.clients, input.projects, tasks) !== undefined)
         return "project";
     const matched = matchByRepoPath(input.cwd, input.projects);
     if (matched && findUsableClient(input.clients, matched.clientId))
@@ -101,15 +117,16 @@ export function resolveWorkTargetSource(input) {
  */
 export function resolveWorkTarget(input) {
     const { session } = input;
+    const tasks = input.tasks ?? [];
     if (session === "skipped")
         return undefined;
     if (session !== undefined) {
-        const resolved = resolveCandidate(session, input.clients, input.projects);
+        const resolved = resolveCandidate(session, input.clients, input.projects, tasks);
         if (resolved)
             return resolved;
     }
     if (input.project !== undefined) {
-        const resolved = resolveCandidate(input.project, input.clients, input.projects);
+        const resolved = resolveCandidate(input.project, input.clients, input.projects, tasks);
         if (resolved)
             return resolved;
     }
@@ -117,11 +134,16 @@ export function resolveWorkTarget(input) {
     if (matched) {
         const client = findUsableClient(input.clients, matched.clientId);
         if (client)
-            return buildTarget(client, matched);
+            return buildTarget(client, matched, undefined);
     }
     return undefined;
 }
-/** `<clientName>` or `<clientName> · <projectName>` — the display label used by the status bar and the "remember" prompt. */
+/**
+ * `<clientName>`, `<clientName> · <projectName>`, or with a linked hub task
+ * appended as `... › <hubTaskTitle>` — the display label used by the
+ * status bar and the "remember" prompt.
+ */
 export function formatWorkTargetLabel(target) {
-    return target.projectName ? `${target.clientName} · ${target.projectName}` : target.clientName;
+    const base = target.projectName ? `${target.clientName} · ${target.projectName}` : target.clientName;
+    return target.hubTaskTitle ? `${base} › ${target.hubTaskTitle}` : base;
 }

package/dist/ports/catalog.d.ts

@@ -1,10 +1,12 @@
-import type { Client, Project } from "../domain/work-target.ts";
-/** A cached read of the hub's clients/projects, plus when and against which hub URL it was fetched. */
+import type { Client, HubTask, Project } from "../domain/work-target.ts";
+/** A cached read of the hub's clients/projects/tasks, plus when and against which hub URL it was fetched. */
 export interface CatalogSnapshot {
     fetchedAt: number;
     url: string;
     clients: Client[];
     projects: Project[];
+    /** Optional because a cache written by an older build (before hub task linking) never had this field; a missing value reads as "no tasks known yet." */
+    tasks?: HubTask[];
 }
 /**
  * Read-only access to the hub catalog (clients/projects). `read()` is a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kankaku",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "pi extension that records agent work time per prompt, excluding waits for the user, with subagent linkage and task/session views",
   "license": "MIT",
   "author": "soyunninja",

package/src/adapters/cached-catalog.ts

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
-import type { Client, Project } from "../domain/work-target.ts";
+import type { Client, HubTask, Project } from "../domain/work-target.ts";
 import type { Clock } from "../ports/clock.ts";
 import type { Catalog, CatalogSnapshot } from "../ports/catalog.ts";
 import { OWNER_DIR_MODE, OWNER_FILE_MODE } from "./file-modes.ts";
@@ -16,6 +16,10 @@ function isProjectArray(value: unknown): value is Project[] {
   return Array.isArray(value) && value.every((item) => item && typeof item === "object" && typeof (item as Project).id === "string");
 }
 
+function isHubTaskArray(value: unknown): value is HubTask[] {
+  return Array.isArray(value) && value.every((item) => item && typeof item === "object" && typeof (item as HubTask).id === "string");
+}
+
 function isCatalogSnapshot(value: unknown): value is CatalogSnapshot {
   if (!value || typeof value !== "object") return false;
   const record = value as Record<string, unknown>;
@@ -23,7 +27,8 @@ function isCatalogSnapshot(value: unknown): value is CatalogSnapshot {
     typeof record["fetchedAt"] === "number" &&
     typeof record["url"] === "string" &&
     isClientArray(record["clients"]) &&
-    isProjectArray(record["projects"])
+    isProjectArray(record["projects"]) &&
+    (record["tasks"] === undefined || isHubTaskArray(record["tasks"]))
   );
 }
 
@@ -35,8 +40,13 @@ export interface CachedCatalogDeps {
   clock: Clock;
   /** Cache TTL in ms. Defaults to 6 hours. */
   ttlMs?: number;
-  /** Fetch a fresh `{ clients, projects }` pair, e.g. `createPocketBaseCatalogFetcher(...)`. */
-  fetchCatalog: (signal?: AbortSignal) => Promise<{ clients: Client[]; projects: Project[] }>;
+  /**
+   * Fetch a fresh `{ clients, projects, tasks }` triple, e.g.
+   * `createPocketBaseCatalogFetcher(...)`. `tasks` is optional here (unlike
+   * on the real PocketBase fetcher) so a test double that only cares about
+   * clients/projects keeps compiling unchanged.
+   */
+  fetchCatalog: (signal?: AbortSignal) => Promise<{ clients: Client[]; projects: Project[]; tasks?: HubTask[] }>;
 }
 
 /**
@@ -73,8 +83,14 @@ export class CachedCatalog implements Catalog {
 
   async refresh(signal?: AbortSignal): Promise<CatalogSnapshot | undefined> {
     try {
-      const { clients, projects } = await this.deps.fetchCatalog(signal);
-      const snapshot: CatalogSnapshot = { fetchedAt: this.deps.clock.now(), url: this.deps.url, clients, projects };
+      const { clients, projects, tasks } = await this.deps.fetchCatalog(signal);
+      const snapshot: CatalogSnapshot = {
+        fetchedAt: this.deps.clock.now(),
+        url: this.deps.url,
+        clients,
+        projects,
+        ...(tasks !== undefined ? { tasks } : {}),
+      };
       this.writeDisk(snapshot);
       this.memo = snapshot;
       this.memoized = true;

package/src/adapters/hub-actions.ts

@@ -0,0 +1,83 @@
+/**
+ * Shared line-building for the hub-facing `/kankaku` subcommands (`sync`,
+ * `sync all`, `sync status`, `backfill`, `catalog refresh`) and the panel's
+ * `sync`/`export` screens (`adapters/panel/screens/sync.ts`), extracted from
+ * `kankaku-command.ts` so the subcommands and the panel can never drift —
+ * see odd/tasks/kankaku-panel.md P4.
+ */
+import type { CatalogSnapshot } from "../ports/catalog.ts";
+import type { SyncCommandDeps } from "./kankaku-command.ts";
+import type { SyncSummary } from "./sync-runner.ts";
+
+/**
+ * `/kankaku sync status`'s report lines: the watermark, the pending count,
+ * how many tasks fell outside this run's revisit window (R3), and the last
+ * error, when any. Exact body of `handleSyncCommand`'s `status` branch.
+ */
+export function buildSyncStatusLines(status: ReturnType<SyncCommandDeps["status"]>): string[] {
+  const { state, pending, staleOutsideWindow } = status;
+  const lines = [state?.syncedThrough ? `synced through ${state.syncedThrough}` : "never synced", `pending: ${pending}`];
+  if (staleOutsideWindow > 0) {
+    lines.push(`${staleOutsideWindow} task(s) never synced fall outside the sync window — run '/kankaku sync all' to upload them`);
+  }
+  if (state?.lastError) lines.push(`last error: ${state.lastError.message} (at ${state.lastError.at})`);
+  return lines;
+}
+
+/**
+ * Render a {@link SyncSummary} as report lines: counts, any stop reason, the
+ * new watermark, and the unassigned/failed breakdowns. Used by `/kankaku
+ * sync`/`sync all` and the panel's sync screen.
+ */
+export function formatSyncSummaryLines(summary: SyncSummary): string[] {
+  const lines = [`uploaded ${summary.uploaded}, updated ${summary.updated}, skipped ${summary.skipped}, failed ${summary.failed.length}`];
+
+  if (summary.locked) lines.push("another sync is already in progress; nothing was attempted");
+  if (summary.error) lines.push(`stopped early: ${summary.error}`);
+  if (summary.syncedThrough) lines.push(`synced through ${summary.syncedThrough}`);
+
+  const unassignedEntries = Object.entries(summary.unassigned).sort(([a], [b]) => a.localeCompare(b));
+  if (unassignedEntries.length > 0) {
+    lines.push("unassigned (Sin determinar):");
+    for (const [label, count] of unassignedEntries) lines.push(`  ${label}: ${count}`);
+  }
+
+  if (summary.failed.length > 0) {
+    lines.push("failed:");
+    for (const entry of summary.failed) lines.push(`  ${entry.id}: ${entry.reason}`);
+  }
+
+  return lines;
+}
+
+/**
+ * `/kankaku backfill`'s report lines: tasks routed to Sin determinar this
+ * run, grouped by their old free-text label, or "no unassigned tasks" when
+ * none were. Exact body of `handleBackfillCommand`.
+ */
+export function formatBackfillLines(summary: SyncSummary): string[] {
+  const unassignedEntries = Object.entries(summary.unassigned).sort(([a], [b]) => a.localeCompare(b));
+
+  const lines =
+    unassignedEntries.length > 0
+      ? [
+          ...unassignedEntries.map(([label, count]) => `${label}: ${count} task(s) -> Sin determinar`),
+          "reassign these in the hub web app's unassigned queue",
+        ]
+      : ["no unassigned tasks"];
+
+  if (summary.error) lines.push(`stopped early: ${summary.error}`);
+  return lines;
+}
+
+/**
+ * `/kankaku catalog refresh`'s report lines: client/project counts, or an
+ * unreachable notice when the refresh failed (`snapshot` is `undefined`).
+ * The subcommand still notifies that failure as an error rather than a
+ * report (see `handleCatalogCommand`); the panel's sync screen shows
+ * whatever this returns either way.
+ */
+export function formatCatalogRefreshLines(snapshot: CatalogSnapshot | undefined): string[] {
+  if (!snapshot) return ["hub unreachable; catalog not refreshed"];
+  return [`refreshed: ${snapshot.clients.length} client(s), ${snapshot.projects.length} project(s)`];
+}