kankaku 0.6.0 → 0.7.0

package/src/domain/work-target.ts

@@ -32,6 +32,19 @@ export interface Project {
   active: boolean;
 }
 
+/**
+ * A hub `tasks` row: something kankaku can link a session's `task_entries`
+ * row to (`task_entries.task`), never create. See `domain/hub-entry.ts` for
+ * the create-only assignment rule this feeds.
+ */
+export interface HubTask {
+  id: string;
+  title: string;
+  projectId: string;
+  status: "open" | "doing" | "done";
+  externalRef?: string;
+}
+
 export interface WorkTarget {
   clientId: string;
   clientCode: string;
@@ -39,12 +52,23 @@ export interface WorkTarget {
   projectId?: string;
   projectCode?: string;
   projectName?: string;
+  /** Hub `tasks` record id, kept only when it belongs to `projectId`. See {@link resolveWorkTarget}. */
+  hubTaskId?: string;
+  /** Denormalised alongside `hubTaskId` for display. */
+  hubTaskTitle?: string;
 }
 
 /** ids picked from the session, or from the project's `.kankaku/config.json`. */
 export interface WorkTargetCandidate {
   clientId: string;
   projectId?: string;
+  /**
+   * A hub task the user picked for this session (`/kankaku task pick`).
+   * Only ever set on the session-level candidate — the project config file
+   * and `repoPaths` matching never carry one (task linking is session-only,
+   * see AGENTS.md).
+   */
+  hubTaskId?: string;
 }
 
 /**
@@ -63,6 +87,8 @@ export interface ResolveWorkTargetInput {
   cwd: string;
   clients: Client[];
   projects: Project[];
+  /** The hub's known tasks, to validate a candidate's `hubTaskId` against. Defaults to `[]` so existing callers compile unchanged. */
+  tasks?: HubTask[];
 }
 
 export type WorkTargetSourceName = "session" | "project" | "repoPaths";
@@ -81,7 +107,18 @@ function findUsableProject(projects: Project[], projectId: string, clientId: str
   return project;
 }
 
-function buildTarget(client: Client, project: Project | undefined): WorkTarget {
+/**
+ * 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: HubTask[], taskId: string, projectId: string): HubTask | undefined {
+  const task = tasks.find((candidate) => candidate.id === taskId);
+  if (!task || task.projectId !== projectId) return undefined;
+  return task;
+}
+
+function buildTarget(client: Client, project: Project | undefined, task: HubTask | undefined): WorkTarget {
   return {
     clientId: client.id,
     clientCode: client.code,
@@ -93,6 +130,7 @@ function buildTarget(client: Client, project: Project | undefined): WorkTarget {
           projectName: project.name,
         }
       : {}),
+    ...(task !== undefined ? { hubTaskId: task.id, hubTaskTitle: task.title } : {}),
   };
 }
 
@@ -101,13 +139,17 @@ function buildTarget(client: Client, project: Project | undefined): WorkTarget {
  * 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: WorkTargetCandidate, clients: Client[], projects: Project[]): WorkTarget | undefined {
+function resolveCandidate(candidate: WorkTargetCandidate, clients: Client[], projects: Project[], tasks: HubTask[]): WorkTarget | undefined {
   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. */
@@ -139,10 +181,11 @@ function isCwdWithin(cwd: string, repoPath: string): boolean {
 /** Which source (if any) {@link resolveWorkTarget} would use, computed independently so callers can display it. */
 export function resolveWorkTargetSource(input: ResolveWorkTargetInput): WorkTargetSourceName | undefined {
   const { session } = input;
+  const tasks = input.tasks ?? [];
   if (session === "skipped") return undefined;
-  if (session !== undefined && resolveCandidate(session, input.clients, input.projects) !== undefined) return "session";
+  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) return "project";
+  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)) return "repoPaths";
@@ -158,28 +201,34 @@ export function resolveWorkTargetSource(input: ResolveWorkTargetInput): WorkTarg
  */
 export function resolveWorkTarget(input: ResolveWorkTargetInput): WorkTarget | undefined {
   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;
   }
 
   const matched = matchByRepoPath(input.cwd, input.projects);
   if (matched) {
     const client = findUsableClient(input.clients, matched.clientId);
-    if (client) return buildTarget(client, matched);
+    if (client) 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: WorkTarget): string {
-  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/src/extension.ts

@@ -184,6 +184,18 @@ export default function kankaku(pi: ExtensionAPI): void {
   let hubConfigError: string | undefined;
   let sync: SyncCommandDeps | undefined;
   let autoSyncEnabled: boolean | undefined;
+  let hubUrl: string | undefined;
+
+  // Resolved once, here (never on a hot path): see README "Hub
+  // (PocketBase)" > "Agent and measurement quality" and the panel's `about`
+  // screen (`adapters/panel/screens/about.ts`). Both degrade to `undefined`
+  // on any failure rather than guessing. Unlike the sync sink below (which
+  // needs them only when the hub is configured), the `about` screen shows
+  // these regardless — so they are resolved unconditionally here.
+  const agentVersion = resolveAgentVersion();
+  // extension.ts lives at <package root>/src/extension.ts.
+  const pluginPackageRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+  const pluginVersion = resolvePluginVersion(pluginPackageRoot);
 
   // `homeDir` is passed as a reference, never invoked here: any failure
   // resolving it (no HOME, a sandbox) must not fail extension load for
@@ -194,6 +206,7 @@ export default function kankaku(pi: ExtensionAPI): void {
 
   if (hub.credentials) {
     const credentials = hub.credentials;
+    hubUrl = credentials.url;
     const client = new PocketBaseClient({ url: credentials.url, email: credentials.email, password: credentials.password });
     // Same defensive resolution as above; falls back to the OS temp dir
     // when no home directory is available so an env-only hub configuration
@@ -226,20 +239,13 @@ export default function kankaku(pi: ExtensionAPI): void {
     const catalogRef = catalog;
     const machineName = machine;
 
-    // Resolved once, here (never on a hot path): see README "Hub
-    // (PocketBase)" > "Agent and measurement quality". Both degrade to
-    // `undefined` on any failure rather than guessing.
-    const agentVersion = resolveAgentVersion();
-    // extension.ts lives at <package root>/src/extension.ts.
-    const pluginPackageRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
-    const pluginVersion = resolvePluginVersion(pluginPackageRoot);
-
     const runOnce = (options?: { full?: boolean; trigger?: SyncTrigger }) => {
       const snapshot = catalogRef.read();
       const sink = new PocketBaseSink({
         client,
         clients: snapshot?.clients ?? [],
         projects: snapshot?.projects ?? [],
+        tasks: snapshot?.tasks ?? [],
         machine: machineName,
         promptMode: syncConfig.promptMode,
         syncRecords: syncConfig.syncRecords,
@@ -308,6 +314,11 @@ export default function kankaku(pi: ExtensionAPI): void {
     ...(hubConfigError !== undefined ? { hubConfigError } : {}),
     ...(sync !== undefined ? { sync } : {}),
     ...(autoSyncEnabled !== undefined ? { autoSyncEnabled } : {}),
+    config,
+    kankakuDir: resolvedDir,
+    ...(agentVersion !== undefined ? { agentVersion } : {}),
+    ...(pluginVersion !== undefined ? { pluginVersion } : {}),
+    ...(hubUrl !== undefined ? { hubUrl } : {}),
     ...(roleOverride !== undefined ? { roleOverride } : {}),
     ...(childMarkerPresent ? { childMarkerPresent } : {}),
     ...(profile !== undefined ? { profile } : {}),

package/src/ports/catalog.ts

@@ -1,11 +1,13 @@
-import type { Client, Project } from "../domain/work-target.ts";
+import type { Client, HubTask, 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. */
+/** 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[];
 }
 
 /**