kennel 0.2.1 → 0.2.3

package/kernel/plugins/tasks/src/index.ts

@@ -0,0 +1,34 @@
+export { tasksManifest } from "./manifest.ts"
+export type { TodoItemProps } from "./ui/todo-item.js"
+export type {
+  TodoItemData,
+  TodoItemLink,
+  TodoItemRelation,
+  TodoItemStatus,
+  TodoItemStep,
+} from "./data/todo-model.js"
+export type {
+  TodoDataset,
+  TodoDatasetOptions,
+  TodoFilter,
+  TodoFilterSelection,
+  TodoState,
+  UiTodoItem,
+} from "./data/todo-model.js"
+export {
+  decodeTodoDataset,
+  TodoDatasetSchema,
+  todoItems,
+} from "./data/todo-model.js"
+export type { CompactTodoListProps } from "./ui/compact-todo-list.js"
+export { CompactTodoList } from "./ui/compact-todo-list.js"
+export type { TodoFilterBarProps } from "./ui/todo-filter-bar.js"
+export { TodoFilterBar } from "./ui/todo-filter-bar.js"
+export type { TodoStatusFilterProps } from "./ui/todo-status-filter.js"
+export { TodoStatusFilter } from "./ui/todo-status-filter.js"
+export type { TodoAgentFilterProps } from "./ui/todo-agent-filter.js"
+export { TodoAgentFilter } from "./ui/todo-agent-filter.js"
+export type { TodoTagFilterProps } from "./ui/todo-tag-filter.js"
+export { TodoTagFilter } from "./ui/todo-tag-filter.js"
+export { TodoItem } from "./ui/todo-item.js"
+export { TodoWarningsTrigger } from "./ui/todo-warnings.tsx"

package/kernel/plugins/tasks/src/manifest.ts

@@ -0,0 +1,7 @@
+import type { FolderPluginManifest } from "@raggle-ai/folder-plugin"
+
+/** Stable Tasks plugin identity and navigation label. No side effects. */
+export const tasksManifest: FolderPluginManifest = {
+  id: "tasks",
+  label: "Tasks",
+}

package/kernel/plugins/tasks/src/pages/task-detail.tsx

@@ -0,0 +1,48 @@
+import type { FolderPluginViewProps } from "@raggle-ai/folder-plugin/client"
+
+import { TaskPage, useTaskPage } from "../ui/task-page"
+import { TodoItem } from "../ui/todo-item"
+import { TodoWarningsTrigger } from "../ui/todo-warnings"
+
+/** Individual task page: the full single task behind a list row link. */
+export function TaskDetailPage({
+  documentHref,
+  folder,
+  folderId,
+  listHref,
+  request,
+  subpath,
+}: FolderPluginViewProps) {
+  const page = useTaskPage({
+    folder,
+    folderId,
+    noun: "task",
+    request,
+    subpath,
+  })
+
+  return (
+    <TaskPage
+      body={
+        page.item ? (
+          <TodoItem
+            item={page.item}
+            documentHref={documentHref}
+            canToggle={!page.busy}
+            onToggle={() => {
+              if (subpath) page.toggle(subpath)
+            }}
+          />
+        ) : undefined
+      }
+      extra={
+        <div className="flex justify-end">
+          <TodoWarningsTrigger warnings={page.data?.warnings} folder={folder} />
+        </div>
+      }
+      list={{ href: listHref, name: "Tasks" }}
+      missingMessage="Task not found."
+      page={page}
+    />
+  )
+}

package/kernel/plugins/tasks/src/pages/task-list.tsx

@@ -0,0 +1,88 @@
+import { useMemo } from "react"
+
+import type { FolderPluginViewProps } from "@raggle-ai/folder-plugin/client"
+import { FolderFilterBar } from "@raggle-ai/ui/components/folder-filter-bar"
+import { useFolderFilter } from "@raggle-ai/ui/hooks/use-folder-filter"
+
+import type { UiTodoItem } from "../data/todo-model"
+import { qualifiedTaskId } from "../data/task-id"
+import { CompactTodoList } from "../ui/compact-todo-list"
+import { TaskPage, useTaskPage } from "../ui/task-page"
+import { TodoWarningsTrigger } from "../ui/todo-warnings"
+
+/** Main Tasks page: filters, counts, and one compact row per task. */
+export function TaskListPage({
+  folder,
+  folderId,
+  href,
+  request,
+}: FolderPluginViewProps) {
+  const page = useTaskPage({
+    folder,
+    folderId,
+    noun: "tasks",
+    request,
+    subpath: "",
+  })
+  // Shared folder filter over every task: a workspace root merges nested
+  // task files, so folder chips narrow to directories (status filtering of
+  // the visible set happens inside the todo list).
+  const filter = useFolderFilter(page.tasks, {
+    getFolder: (item) => item.jsonTodo.source.id,
+    rootFolder: folder,
+  })
+  const filteredDataset = useMemo(() => {
+    if (!page.dataset) return undefined
+    return {
+      ...page.dataset,
+      tasks: filter.visibleItems.map((item) => item.jsonTodo),
+    }
+  }, [page.dataset, filter.visibleItems])
+  // Workspace-qualified task address: the owning folder plus the task id,
+  // so identical file-local ids (`todo:1` in nested files) stay distinct in
+  // detail links and toggle writes. Falls back to the bare id when the
+  // source folder is unknown.
+  const taskAddress = (item: UiTodoItem) =>
+    qualifiedTaskId(item.jsonTodo.source?.id, item.jsonTodo) ??
+    [item.id, item.key].find((value) => value)
+
+  return (
+    <TaskPage
+      body={
+        filteredDataset ? (
+          <CompactTodoList
+            dataset={filteredDataset}
+            trailingFilters={
+              <TodoWarningsTrigger
+                warnings={page.data?.warnings}
+                folder={folder}
+              />
+            }
+            filters
+            leadingFilters={
+              filter.choices.length > 1 ? (
+                <FolderFilterBar
+                  ariaLabel="Filter tasks by folder"
+                  choices={filter.choices}
+                  onSelect={filter.setSelected}
+                  selected={filter.effectiveSelected}
+                  total={filter.total}
+                />
+              ) : undefined
+            }
+            itemHref={(item) => {
+              const target = taskAddress(item)
+              return target ? href(target) : undefined
+            }}
+            onToggle={(item) => {
+              const target = taskAddress(item)
+              if (target) page.toggle(target)
+            }}
+          />
+        ) : undefined
+      }
+      page={page}
+      unavailableMessage="No local task file in this folder."
+    />
+  )
+}

package/kernel/plugins/tasks/src/server.ts

@@ -0,0 +1,447 @@
+import { readdir, readFile, stat } from "node:fs/promises"
+import { basename, dirname, relative, resolve, sep } from "node:path"
+
+import type {
+  FolderPluginContext,
+  FolderPluginDetection,
+  FolderPluginPayload,
+} from "@raggle-ai/folder-plugin/server"
+import { matchSubpath } from "@raggle-ai/folder-plugin/subpath"
+
+import type { TodoFile, TodoIssue } from "./data/parse.ts"
+import {
+  parseTodoSource,
+  starterTodoSource,
+  todoFileWarnings,
+  todoIssueSummary,
+} from "./data/parse.ts"
+import { parseQualifiedTaskId, refMatchesFolder } from "./data/task-id.ts"
+import { tasksManifest } from "./manifest.ts"
+
+type TaskSource = {
+  document: TodoFile
+  /** Absolute directory that owns the `todo.json` file. */
+  folder: string
+  /** Path relative to the viewed root, e.g. "todo.json" or "clients/client-one/todo.json". */
+  path: string
+}
+
+type TaskSourceLoad = {
+  issues: Array<{ file: string; problems: TodoIssue[] }>
+  /** Advisory warnings per file; they never invalidate a source. */
+  warnings: Array<{ file: string; problems: TodoIssue[] }>
+  sources: TaskSource[]
+}
+
+/**
+ * Recursively discover `todo.json` files under a folder. Hidden directories
+ * and `node_modules` are skipped and directory symlinks are not followed, so
+ * discovered files stay contained inside the folder. Invalid files are
+ * reported, valid files become task sources (mirroring the calendar
+ * plugin's recursive discovery). `viewRoot` is the folder the viewer opened;
+ * `scanRoot` defaults to it but may be a linked folder, in which case source
+ * paths stay relative to the viewed root.
+ */
+async function loadTaskSources(
+  viewRoot: string,
+  scanRoot: string = viewRoot,
+): Promise<TaskSourceLoad> {
+  const visit = async (current: string): Promise<string[]> => {
+    const entries = await readdir(current, { withFileTypes: true }).catch(
+      () => [],
+    )
+    const paths: string[] = []
+    for (const entry of entries) {
+      if (entry.isFile() && entry.name === "todo.json") {
+        paths.push(resolve(current, entry.name))
+        continue
+      }
+      if (
+        !entry.isDirectory() ||
+        entry.name.startsWith(".") ||
+        entry.name === "node_modules"
+      )
+        continue
+      paths.push(...(await visit(resolve(current, entry.name))))
+    }
+    return paths
+  }
+
+  const paths = (await visit(scanRoot)).sort((left, right) =>
+    relative(scanRoot, left).localeCompare(relative(scanRoot, right)),
+  )
+  const issues: TaskSourceLoad["issues"] = []
+  const warnings: TaskSourceLoad["warnings"] = []
+  const sources: TaskSource[] = []
+  await Promise.all(
+    paths.map(async (path) => {
+      const sourceText = await readFile(path, "utf8")
+      const file = relative(viewRoot, path).split(sep).join("/")
+      const parsed = parseTodoSource(sourceText)
+      if (!parsed.ok) {
+        issues.push({ file, problems: parsed.issues })
+        return
+      }
+      warnings.push({
+        file,
+        problems: [
+          ...todoFileWarnings(parsed.document),
+          ...(await missingNoteIssues(parsed.document, dirname(path))),
+        ],
+      })
+      sources.push({
+        document: parsed.document,
+        folder: dirname(path),
+        path: file,
+      })
+    }),
+  )
+  issues.sort((left, right) => left.file.localeCompare(right.file))
+  return { issues, sources, warnings }
+}
+
+/**
+ * Load `todo.json` files from the host-resolved linked folders (the same
+ * relation graph that powers linked notes). Paths stay relative to the
+ * viewed root so linked sources never collide with the root `todo.json`
+ * semantics; the multi-source dataset already renders them as their own
+ * folder chips.
+ */
+async function loadLinkedTaskSources(
+  viewRoot: string,
+  linkedFolders: string[],
+): Promise<TaskSourceLoad> {
+  const loads = await Promise.all(
+    linkedFolders.map((folder) => loadTaskSources(viewRoot, folder)),
+  )
+  return {
+    issues: loads.flatMap((load) => load.issues),
+    sources: loads.flatMap((load) => load.sources),
+    warnings: loads.flatMap((load) => load.warnings),
+  }
+}
+
+/** Root-file issues keep their short paths; nested files get a file prefix. */
+function flattenIssues(load: TaskSourceLoad) {
+  return load.issues.flatMap(({ file, problems }) =>
+    problems.map((problem) => ({
+      path: file === "todo.json" ? problem.path : `${file}: ${problem.path}`,
+      message: problem.message,
+    })),
+  )
+}
+
+/** Root-file warnings keep their short paths; nested files get a file prefix. */
+function flattenWarnings(load: TaskSourceLoad) {
+  return load.warnings.flatMap(({ file, problems }) =>
+    problems.map((problem) => ({
+      path: file === "todo.json" ? problem.path : `${file}: ${problem.path}`,
+      message: problem.message,
+      severity: problem.severity,
+    })),
+  )
+}
+
+/**
+ * Server-side advisory: a folder-relative `notes` entry should resolve to a
+ * real file next to its `todo.json`. A dead reference defeats the point of
+ * note linking, so it warns (never errors); https entries are skipped.
+ */
+async function missingNoteIssues(
+  document: TodoFile,
+  folder: string,
+): Promise<TodoIssue[]> {
+  const missing: TodoIssue[] = []
+  for (const [index, task] of document.tasks.entries()) {
+    const notes = task.notes
+    if (!Array.isArray(notes)) continue
+    for (const [noteIndex, note] of notes.entries()) {
+      if (typeof note !== "string" || /^https?:\/\//i.test(note)) continue
+      const target = (note.split("#", 1)[0] ?? "").trim()
+      if (!target) continue
+      const exists = await stat(resolve(folder, target))
+        .then((entry) => entry.isFile())
+        .catch(() => false)
+      if (!exists) {
+        missing.push({
+          message: `references a missing note file: ${target}`,
+          path: `tasks[${index}].notes[${noteIndex}]`,
+          severity: "warning",
+        })
+      }
+    }
+  }
+  return missing
+}
+
+function taskCompleted(task: Record<string, unknown>) {
+  return task.done === true || task.status === "done"
+}
+
+function tasksOf(source: TaskSource) {
+  return Array.isArray(source.document.tasks) ? source.document.tasks : []
+}
+
+function sourceTitle(folder: string) {
+  return `${basename(folder)} tasks`
+}
+
+/**
+ * Merged dataset for the workspace list: every valid `todo.json` under the
+ * viewed folder becomes one source, root folder first, and every task is
+ * tagged with its owning folder so the client can filter by folder chips.
+ */
+function mergedDataset(folder: string, sources: TaskSource[]) {
+  const root = sources.find((source) => source.path === "todo.json")
+  const title =
+    root && typeof root.document.title === "string"
+      ? root.document.title
+      : sourceTitle(folder)
+
+  const byFolder = new Map<string, TaskSource[]>()
+  for (const source of sources) {
+    byFolder.set(source.folder, [
+      ...(byFolder.get(source.folder) ?? []),
+      source,
+    ])
+  }
+  const ordered = new Map<string, TaskSource[]>()
+  ordered.set(folder, byFolder.get(folder) ?? [])
+  for (const sourceFolder of [...byFolder.keys()].sort()) {
+    const docs = byFolder.get(sourceFolder)
+    if (docs && sourceFolder !== folder) ordered.set(sourceFolder, docs)
+  }
+
+  const datasetSources: Array<{
+    id: string
+    open: number
+    title: string
+    total: number
+  }> = []
+  const tasks: Array<Record<string, unknown>> = []
+  for (const [sourceFolder, docs] of ordered) {
+    const fileTasks = docs.flatMap(tasksOf)
+    const completed = fileTasks.filter(taskCompleted).length
+    datasetSources.push({
+      id: sourceFolder,
+      open: fileTasks.length - completed,
+      title: sourceTitle(sourceFolder),
+      total: fileTasks.length,
+    })
+    for (const task of fileTasks) {
+      tasks.push({
+        ...task,
+        source: { id: sourceFolder, title: sourceTitle(sourceFolder) },
+      })
+    }
+  }
+
+  const completed = tasks.filter(taskCompleted).length
+  return {
+    ...root?.document,
+    $schema:
+      typeof root?.document.$schema === "string"
+        ? root.document.$schema
+        : "https://raggle.co/schemas/tasks.json",
+    id: typeof root?.document.id === "string" ? root.document.id : "todo",
+    project: { name: title },
+    sources: datasetSources,
+    summary: {
+      completed,
+      open: tasks.length - completed,
+      sources: datasetSources.length,
+    },
+    tasks,
+    title,
+    version:
+      typeof root?.document.version === "number" ? root.document.version : 1,
+  }
+}
+
+function singleTaskDataset(
+  folder: string,
+  source: TaskSource,
+  task: Record<string, unknown>,
+) {
+  const completed = taskCompleted(task)
+  return {
+    ...source.document,
+    $schema:
+      typeof source.document.$schema === "string"
+        ? source.document.$schema
+        : "https://raggle.co/schemas/tasks.json",
+    version:
+      typeof source.document.version === "number" ? source.document.version : 1,
+    project: { name: sourceTitle(folder) },
+    sources: [
+      {
+        id: source.folder,
+        open: completed ? 0 : 1,
+        title: sourceTitle(source.folder),
+        total: 1,
+      },
+    ],
+    summary: {
+      completed: completed ? 1 : 0,
+      open: completed ? 0 : 1,
+      sources: 1,
+    },
+    tasks: [
+      {
+        ...task,
+        source: { id: source.folder, title: sourceTitle(source.folder) },
+      },
+    ],
+  }
+}
+
+export function createTasksPlugin() {
+  return {
+    ...tasksManifest,
+    async detect(context: FolderPluginContext): Promise<FolderPluginDetection> {
+      const [loads, linked] = await Promise.all([
+        loadTaskSources(context.folder),
+        loadLinkedTaskSources(context.folder, context.linkedFolders ?? []),
+      ])
+      const merged: TaskSourceLoad = {
+        issues: [...loads.issues, ...linked.issues],
+        sources: [...loads.sources, ...linked.sources],
+        // Warnings are advisory: detection stays "available" with its count.
+        warnings: [],
+      }
+      const noContent =
+        merged.sources.length === 0 && merged.issues.length === 0
+      if (noContent) return { status: "unavailable" }
+      if (merged.issues.length > 0) {
+        // Explicit error state: a todo.json exists but is not valid (locally
+        // or in a linked folder). The host flags the navigation item.
+        return {
+          status: "error",
+          error: todoIssueSummary(flattenIssues(merged)),
+        }
+      }
+      return {
+        count: merged.sources.reduce(
+          (sum, source) => sum + tasksOf(source).length,
+          0,
+        ),
+        status: "available",
+      }
+    },
+    async handle(
+      context: FolderPluginContext,
+      subpath: string,
+    ): Promise<FolderPluginPayload<unknown>> {
+      const [load, linked] = await Promise.all([
+        loadTaskSources(context.folder),
+        loadLinkedTaskSources(context.folder, context.linkedFolders ?? []),
+      ])
+      const sources = [...load.sources, ...linked.sources]
+      const rootIssue = load.issues.find((issue) => issue.file === "todo.json")
+      if (rootIssue) {
+        // In-band error payload: precise, per-field issues the client renders
+        // directly. Throwing would map to a misleading 4xx/5xx instead.
+        return {
+          kind: "available",
+          data: {
+            folder: context.folder,
+            issues: rootIssue.problems,
+            status: "error",
+          },
+        }
+      }
+
+      const warnings = flattenWarnings({
+        issues: [],
+        sources: [],
+        warnings: [...load.warnings, ...linked.warnings],
+      })
+
+      if (subpath === "" || sources.length === 0) {
+        // Workspace list: the root folder always owns a source (even with no
+        // file) so a missing/empty folder still yields an empty, valid
+        // dataset — for the list and for any detail subpath alike.
+        return {
+          kind: "available",
+          data: {
+            dataset: mergedDataset(context.folder, sources),
+            folder: context.folder,
+            status: "available",
+            warnings,
+          },
+        }
+      }
+
+      // Individual task view: match the subpath against the task id or key
+      // across every discovered source (local and linked) and return a
+      // single-task dataset.
+      const id = subpath.trim()
+      // Qualified addresses (`<folderPathId(folder)>@<id|key>`) name their
+      // owning folder, so identical file-local ids `todo:1` resolve to the
+      // right file. A ref that matches no source is an id that contains "@":
+      // it drops through to the legacy bare-id search below. A ref that
+      // matches a real source but no task is a broken address and must not
+      // silently show a different source's task.
+      const qualified = parseQualifiedTaskId(id)
+      if (qualified) {
+        const source = sources.find((item) =>
+          refMatchesFolder(qualified.ref, item.folder),
+        )
+        if (source) {
+          const task = tasksOf(source).find(
+            (item) => item.id === qualified.id || item.key === qualified.id,
+          )
+          return {
+            kind: "available",
+            data: task
+              ? {
+                  dataset: singleTaskDataset(context.folder, source, task),
+                  folder: context.folder,
+                  status: "available",
+                  warnings,
+                }
+              : {
+                  folder: context.folder,
+                  message: `Task not found: ${id}`,
+                  status: "error",
+                },
+          }
+        }
+      }
+      // Legacy bare id/key: first source that contains it wins, via the
+      // shared subpath matcher (also used by the minimal reference plugin).
+      const bare = matchSubpath(
+        sources,
+        id,
+        tasksOf,
+        (item, target) => item.id === target || item.key === target,
+      )
+      if (bare) {
+        return {
+          kind: "available",
+          data: {
+            dataset: singleTaskDataset(context.folder, bare.source, bare.item),
+            folder: context.folder,
+            status: "available",
+            warnings,
+          },
+        }
+      }
+      return {
+        kind: "available",
+        data: {
+          folder: context.folder,
+          message: `Task not found: ${id}`,
+          status: "error",
+        },
+      }
+    },
+    init(context: FolderPluginContext) {
+      return {
+        files: [
+          { path: "todo.json", content: starterTodoSource(context.folder) },
+        ],
+      }
+    },
+  }
+}

package/kernel/plugins/tasks/src/styles.css

@@ -0,0 +1,9 @@
+.todo-panel {
+  overflow: hidden;
+  border: 1px solid rgb(226 232 240);
+  border-radius: 0.75rem;
+  background: rgb(255 255 255);
+  box-shadow:
+    0 1px 2px rgb(15 23 42 / 0.06),
+    0 1px 1px rgb(15 23 42 / 0.04);
+}