kennel 0.2.0 → 0.2.2

package/kernel/plugins/tasks/src/ui/task-page.tsx

@@ -0,0 +1,392 @@
+import type { UseQueryResult } from "@tanstack/react-query"
+import type { ReactNode } from "react"
+import { useMemo, useRef } from "react"
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query"
+
+import type { FolderPluginViewProps } from "@raggle-ai/folder-plugin/client"
+import type { ContentIssue } from "@raggle-ai/ui/components/content-issues"
+import { Button } from "@raggle-ai/ui/components/button"
+import { ContentIssues } from "@raggle-ai/ui/components/content-issues"
+import { toast } from "@raggle-ai/ui/components/sonner"
+import { EntityDetailPage } from "@raggle-ai/ui/pages/entity-detail-page"
+import { EntityListPage } from "@raggle-ai/ui/pages/entity-list-page"
+
+import type { TodoDataset, UiTodoItem } from "../data/todo-model"
+import { decodeTodoDataset, todoItems } from "../data/todo-model"
+import { ErrorDetails } from "./error-details"
+
+/** Shape of the plugin payload the two task pages read. */
+export type TasksPluginData = {
+  dataset?: unknown
+  linkedStatus?: "pending" | "ready" | "error"
+  folder: string
+  issues?: ContentIssue[]
+  message?: string
+  status?: "available" | "error" | "unavailable"
+  warnings?: ContentIssue[]
+}
+
+/** Agent-friendly error context: folder plus the failure text. */
+const errorContext = (folder: string, error: string) =>
+  [
+    "The Kennel Tasks view for this folder failed. Use the context below to",
+    "diagnose the cause, fix the data, then re-check the Tasks tab.",
+    "",
+    `Folder: ${folder}`,
+    "",
+    "What failed:",
+    "The viewer decodes the merged tasks dataset against a strict schema",
+    "(https://raggle.co/schemas/tasks.json). todo.json passed file-level",
+    "validation, but at least one field violates the schema, so the decode",
+    "threw and the view renders nothing until that field is fixed.",
+    "",
+    "How to read the failure tree:",
+    '- Bracketed keys are a JSON path into todo.json: ["tasks"] -> [7] ->',
+    '  ["resolution"] means tasks[7].resolution in the source file. The',
+    "  number is the task's position in the tasks array (tasks from linked",
+    "  folders come after the local file's). Leaves list every accepted",
+    '  value, and "Expected X, actual Y" shows what the field holds now.',
+    "",
+    "Common causes:",
+    "- An enum field holds free text. resolution accepts only completed,",
+    "  duplicate, wont_do, not_reproducible, moved, or null; status and",
+    "  type are enums too. Move the sentence into a comments entry",
+    "  (id + body + createdAt) or into description, then set the field to",
+    '  an allowed value (finished work uses resolution: "completed").',
+    "- A required field is missing. Each comments entry needs id, body,",
+    "  and createdAt (ISO date-time). Each task needs name.",
+    "- Shape mismatches: null where a string is required (or the reverse),",
+    "  dates not in YYYY-MM-DD, timestamps not ISO.",
+    "",
+    "How to fix and verify:",
+    "1. Edit todo.json in the folder above. Fix the exact field named in",
+    "   the failure tree; do not delete the task.",
+    "2. Confirm the fix by re-opening the Tasks tab, or decode the same",
+    "   payload the viewer uses:",
+    `   curl -fsS "<kennel-url>/api/plugins/tasks?path=${encodeURIComponent(folder)}"`,
+    "   then run decodeTodoDataset from @raggle-ai/tasks/todo-model on the",
+    "   returned .dataset value. Success = no throw.",
+    "3. A healthy Tasks tab shows no red error panel and open/completed",
+    "   counts that match todo.json.",
+    "",
+    "Failure:",
+    error,
+  ].join("\n")
+
+/** Message text of an Error-like failure, or undefined when it has none. */
+const failureText = (error: unknown) =>
+  error instanceof Error && error.message ? error.message : undefined
+
+function TaskIssues({ issues }: { issues: ContentIssue[] }) {
+  return <ContentIssues file="todo.json" issues={issues} />
+}
+
+function LinkedTaskStatus({
+  status,
+  retry,
+}: {
+  status?: string
+  retry: () => void
+}) {
+  if (status === "pending")
+    return (
+      <p role="status">Loading linked tasks… Local tasks remain available.</p>
+    )
+  if (status === "error")
+    return (
+      <p role="alert">
+        Linked tasks could not load.{" "}
+        <button onClick={retry}>Retry linked tasks</button>
+      </p>
+    )
+  return null
+}
+
+function decodeDataset(data: TasksPluginData | undefined) {
+  let dataset: TodoDataset | undefined
+  let decodeError: string | undefined
+  if (data?.status === "available" && data?.dataset) {
+    try {
+      dataset = decodeTodoDataset(data.dataset)
+    } catch (error) {
+      // The dataset is generated server-side, so a decode failure means the
+      // source had a shape the validator could not see (e.g. an invalid
+      // summary). Surface the schema message instead of hiding it.
+      decodeError =
+        error instanceof Error && error.message
+          ? error.message
+          : "Could not parse the task file."
+    }
+  }
+  return { dataset, decodeError }
+}
+
+/** Complete/reopen a task; persists to its `todo.json` on the server. */
+async function toggleTaskDone(folder: string, id: string): Promise<boolean> {
+  const response = await fetch("/api/tasks/toggle", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ path: folder, id }),
+  })
+  if (!response.ok) {
+    let message = "Could not update task."
+    try {
+      const payload = (await response.json()) as {
+        error?: { message?: string }
+      }
+      if (payload.error?.message) message = payload.error.message
+    } catch {
+      // Non-JSON error body; keep the default message.
+    }
+    throw new Error(message)
+  }
+  const payload = (await response.json()) as { done?: boolean }
+  return payload.done ?? false
+}
+
+function useTaskToggle(folder: string, folderId: string) {
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationFn: (id: string) => toggleTaskDone(folder, id),
+    onError: (error) => {
+      toast.error(
+        error instanceof Error ? error.message : "Could not update task.",
+      )
+    },
+    onSuccess: () => {
+      void queryClient.invalidateQueries({
+        queryKey: ["folder", folderId, "tasks"],
+      })
+    },
+  })
+}
+
+/** Everything the task list page and the task detail page share. */
+export type TaskPageData = {
+  /** The noun in "Loading task(s)", "Could not load task(s)", "Retry task(s)". */
+  noun: string
+  folder: string
+  query: UseQueryResult<TasksPluginData> & {
+    /** Re-fetch with the linked-folder retry marker set. */
+    retryLinked: () => void
+  }
+  data?: TasksPluginData
+  dataset?: TodoDataset
+  decodeError?: string
+  tasks: UiTodoItem[]
+  /** First task of the dataset (the detail page's single task). */
+  item: UiTodoItem | null
+  /** Complete/reopen a task by its workspace-qualified address. */
+  toggle: (id: string) => void
+  /** True while a toggle write is in flight. */
+  busy: boolean
+}
+
+/**
+ * One fetch + decode + toggle pipeline for both task pages. `noun` picks the
+ * wording of the loading, error, and retry lines ("task" or "tasks");
+ * `subpath` is the task address for the detail page, "" for the list.
+ */
+export function useTaskPage({
+  folder,
+  folderId,
+  request,
+  subpath,
+  noun,
+}: {
+  folder: string
+  folderId: string
+  request: FolderPluginViewProps["request"]
+  subpath: string
+  noun: string
+}): TaskPageData {
+  const retry = useRef(false)
+  const query = useQuery({
+    enabled: Boolean(folder),
+    gcTime: 5 * 60_000,
+    queryFn: ({ signal }) => {
+      const headers = retry.current
+        ? { "x-kennel-retry-linked": "1" }
+        : undefined
+      retry.current = false
+      return request(subpath, { signal, headers }) as Promise<TasksPluginData>
+    },
+    queryKey: ["folder", folderId, "tasks", subpath],
+    staleTime: 15_000,
+    refetchInterval: (query) =>
+      query.state.data?.linkedStatus === "pending" ? 1_000 : false,
+  })
+  const data = query.data as TasksPluginData | undefined
+  // Stable dataset identity so child lists and the filter memoize cleanly
+  // across chip-interaction re-renders.
+  const { dataset, decodeError } = useMemo(() => decodeDataset(data), [data])
+  const tasks = useMemo(() => todoItems(dataset ?? null), [dataset])
+  const toggle = useTaskToggle(folder, folderId)
+  return {
+    noun,
+    folder,
+    query: {
+      ...query,
+      retryLinked: () => {
+        retry.current = true
+        void query.refetch()
+      },
+    },
+    data,
+    dataset,
+    decodeError,
+    tasks,
+    item: tasks[0] ?? null,
+    toggle: (id) => toggle.mutate(id),
+    busy: toggle.isPending,
+  }
+}
+
+function retryButton(page: TaskPageData, label: string) {
+  return (
+    <Button
+      className="h-7 px-2 text-[13px] text-[#9c3a3a] hover:text-[#6f2020]"
+      onClick={() => void page.query.refetch()}
+      size="sm"
+      type="button"
+      variant="ghost"
+    >
+      {label}
+    </Button>
+  )
+}
+
+/** The task page's failure block, if any: fetch error, validation issues,
+ *  or a decode failure, in that order. */
+function taskErrorNode(page: TaskPageData, fetchError: string): ReactNode {
+  const { data, decodeError, query } = page
+  if (query.error) {
+    return (
+      <ErrorDetails
+        action={retryButton(page, `Retry ${page.noun}`)}
+        context={() => errorContext(page.folder, fetchError)}
+        error={fetchError}
+        title={`Could not load ${page.noun}.`}
+      />
+    )
+  }
+  if (data?.status === "error") {
+    if (data.issues?.length) return <TaskIssues issues={data.issues} />
+    const message = data.message ?? "todo.json could not be validated."
+    return (
+      <ErrorDetails
+        context={() => errorContext(page.folder, message)}
+        error={message}
+        title="todo.json could not be validated."
+      />
+    )
+  }
+  if (decodeError) {
+    return (
+      <ErrorDetails
+        context={() => errorContext(page.folder, decodeError ?? "")}
+        error={decodeError}
+        title="Task data is not valid."
+      />
+    )
+  }
+  return undefined
+}
+
+/** The task page's no-content line, if any: a missing task address on the
+ *  detail page, or a folder without a task file on the list page. */
+function taskEmptyNode(
+  page: TaskPageData,
+  unavailableMessage?: string,
+  missingMessage?: string,
+): string | undefined {
+  const { data, decodeError, item, query } = page
+  if (!data || query.isPending || query.error) return undefined
+  const available = data.status === "available"
+  const failed = data.status === "error"
+  if (
+    available &&
+    !failed &&
+    !item &&
+    data.linkedStatus !== "pending" &&
+    !decodeError &&
+    missingMessage
+  ) {
+    return missingMessage
+  }
+  if (!available && !failed) {
+    return unavailableMessage ?? `No ${page.noun} in this folder.`
+  }
+  return undefined
+}
+
+/**
+ * Page scaffold for both task pages: the shared fetch/error chrome
+ * (linked status, loading line, fetch error, validation issues, decode
+ * errors) rendered through the shared entity page shells, with the page's
+ * own header, extra row, and body inside. `unavailableMessage` and
+ * `missingMessage` are optional per-page lines for the no-content states.
+ * The detail page passes `list` to get the shared "Back to {name}" link.
+ */
+export function TaskPage({
+  page,
+  list,
+  header,
+  extra,
+  unavailableMessage,
+  missingMessage,
+  body,
+}: {
+  page: TaskPageData
+  /** Detail page only: the list this task came from; renders the shared
+   *  "Back to {name}" link before the status chrome. */
+  list?: { href: string; name: string }
+  /** Rendered after the linked-task status bar (e.g. a warnings row). */
+  header?: ReactNode
+  /** Rendered after the linked-task status bar (e.g. a warnings row). */
+  extra?: ReactNode
+  /** Line for "folder has no task file" (the list page). */
+  unavailableMessage?: string
+  /** Line for an address that names no task (the detail page). */
+  missingMessage?: string
+  /** Page body; rendered only when a dataset decoded cleanly. */
+  body?: ReactNode
+}) {
+  const { data, dataset, decodeError, query } = page
+  const fetchError = failureText(query.error) ?? `Could not load ${page.noun}.`
+  const available = data?.status === "available"
+  const headerNode = (
+    <>
+      <LinkedTaskStatus retry={query.retryLinked} status={data?.linkedStatus} />
+      {header}
+    </>
+  )
+  const errorNode = taskErrorNode(page, fetchError)
+  const emptyNode = taskEmptyNode(page, unavailableMessage, missingMessage)
+  const bodyNode = available && dataset && !decodeError ? body : null
+  return list ? (
+    <EntityDetailPage
+      error={errorNode}
+      extra={extra}
+      header={headerNode}
+      listHref={list.href}
+      listName={list.name}
+      loading={query.isPending}
+      missing={emptyNode}
+      noun={page.noun}
+    >
+      {bodyNode}
+    </EntityDetailPage>
+  ) : (
+    <EntityListPage
+      empty={emptyNode}
+      error={errorNode}
+      extra={extra}
+      header={headerNode}
+      loading={query.isPending}
+      noun={page.noun}
+    >
+      {bodyNode}
+    </EntityListPage>
+  )
+}

package/kernel/plugins/tasks/src/ui/todo-agent-filter.tsx

@@ -0,0 +1,36 @@
+import { useMemo } from "react"
+
+import { FilterChipPanel } from "@raggle-ai/ui/components/filter-chip-panel"
+
+import type { TodoDataset, TodoFilterSelection } from "../data/todo-model.js"
+import { datasetAgents } from "../data/todo-model.js"
+
+export type TodoAgentFilterProps = {
+  readonly dataset: TodoDataset | null
+  /** Selected assignee ids; empty shows tasks for any agent. */
+  readonly value: TodoFilterSelection
+  readonly onChange: (value: TodoFilterSelection) => void
+  readonly className?: string
+}
+
+/** Agent filter: expand/collapse chip panel over the assignees in use. */
+export function TodoAgentFilter({
+  dataset,
+  value,
+  onChange,
+  className = "",
+}: TodoAgentFilterProps) {
+  const agents = useMemo(() => datasetAgents(dataset), [dataset])
+  if (!agents.length) return null
+
+  return (
+    <FilterChipPanel
+      ariaLabel="Filter tasks by agent"
+      className={className}
+      label="Agent"
+      onChange={onChange}
+      options={agents.map((agent) => ({ value: agent.id, label: agent.name }))}
+      selected={value}
+    />
+  )
+}

package/kernel/plugins/tasks/src/ui/todo-filter-bar.tsx

@@ -0,0 +1,66 @@
+import type { ReactNode } from "react"
+
+import type {
+  TodoDataset,
+  TodoFilter,
+  TodoFilterSelection,
+} from "../data/todo-model.js"
+import { TodoAgentFilter } from "./todo-agent-filter.js"
+import { TodoStatusFilter } from "./todo-status-filter.js"
+import { TodoTagFilter } from "./todo-tag-filter.js"
+
+export type TodoFilterBarProps = {
+  readonly dataset: TodoDataset | null
+  readonly filter: TodoFilter
+  readonly onFilterChange: (filter: TodoFilter) => void
+  /** Selected tags; empty shows tasks with any tags. */
+  readonly tag: TodoFilterSelection
+  readonly onTagChange: (tag: TodoFilterSelection) => void
+  /** Selected assignee ids; empty shows tasks for any agent. */
+  readonly assignee: TodoFilterSelection
+  readonly onAssigneeChange: (assignee: TodoFilterSelection) => void
+  /** Slot rendered first in the row, e.g. the folder filter bar. */
+  readonly leading?: ReactNode
+  /** Slot rendered at the right end of the row, e.g. the warnings button. */
+  readonly trailing?: ReactNode
+  readonly className?: string
+}
+
+/** One horizontal filter line: Status dropdown plus expandable Agent and
+ * Tag chip panels, all filterable together. */
+export function TodoFilterBar({
+  dataset,
+  filter,
+  onFilterChange,
+  tag,
+  onTagChange,
+  assignee,
+  onAssigneeChange,
+  leading,
+  trailing,
+  className = "",
+}: TodoFilterBarProps) {
+  return (
+    <div
+      className={["flex flex-wrap items-center gap-x-3 gap-y-2", className]
+        .filter(Boolean)
+        .join(" ")}
+    >
+      {leading}
+      <TodoStatusFilter
+        dataset={dataset}
+        onChange={onFilterChange}
+        value={filter}
+      />
+      <TodoAgentFilter
+        dataset={dataset}
+        onChange={onAssigneeChange}
+        value={assignee}
+      />
+      <TodoTagFilter dataset={dataset} onChange={onTagChange} value={tag} />
+      {trailing ? (
+        <div className="ml-auto flex shrink-0">{trailing}</div>
+      ) : null}
+    </div>
+  )
+}