kennel 0.2.1 → 0.2.2

package/kernel/plugins/tasks/src/ui/todo-warnings.tsx

@@ -0,0 +1,106 @@
+import { TriangleAlert } from "lucide-react"
+
+import type { ContentIssue } from "@raggle-ai/ui/components/content-issues"
+import { Button } from "@raggle-ai/ui/components/button"
+import { CopyContextButton } from "@raggle-ai/ui/components/copy-context"
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from "@raggle-ai/ui/components/dialog"
+
+/**
+ * Advisory warnings stay hidden until wanted: a compact amber button (with
+ * the warning count) sits at the right end of the filter bar and opens the
+ * full list in a modal, so warnings never push the task list around.
+ */
+export function TodoWarningsTrigger({
+  warnings,
+  folder,
+}: {
+  warnings?: ContentIssue[]
+  /** Viewed folder, for the copyable agent fix instructions. */
+  folder?: string
+}) {
+  if (!warnings?.length) return null
+  return (
+    <Dialog>
+      <DialogTrigger asChild>
+        <Button
+          className="h-7 shrink-0 gap-1.5 border-amber-300 bg-amber-50 px-2
+            text-[13px] text-amber-700 hover:bg-amber-100"
+          size="sm"
+          variant="outline"
+          aria-label={`${warnings.length} todo.json warnings; open details`}
+        >
+          <TriangleAlert aria-hidden="true" className="size-3.5" />
+          Warnings ({warnings.length})
+        </Button>
+      </DialogTrigger>
+      <DialogContent>
+        <DialogHeader>
+          <div className="flex items-start justify-between gap-3">
+            <div>
+              <DialogTitle>todo.json warnings</DialogTitle>
+              <DialogDescription>
+                Advisory only — the task file is still valid and the counts are
+                unaffected. Link notes to these tasks to clear the warnings.
+              </DialogDescription>
+            </div>
+            <CopyContextButton
+              context={() => todoWarningsContext(warnings, folder)}
+              label="Copy fix instructions for an agent"
+              variant="outline"
+              className="mt-0.5 shrink-0 text-slate-500 hover:text-slate-900"
+            />
+          </div>
+        </DialogHeader>
+        <ul
+          className="m-0 max-h-72 list-disc space-y-1.5 overflow-y-auto pl-5
+            text-sm text-amber-700"
+        >
+          {warnings.map((warning, index) => (
+            <li key={index}>
+              <code className="text-[13px]">{warning.path || "todo.json"}</code>
+              {warning.path ? ": " : " — "}
+              {warning.message}
+            </li>
+          ))}
+        </ul>
+      </DialogContent>
+    </Dialog>
+  )
+}
+
+/** Agent-facing fix prompt built from the warnings on click (not render). */
+export const todoWarningsContext = (
+  warnings: readonly ContentIssue[],
+  folder?: string,
+) =>
+  [
+    "You are fixing advisory warnings in a Kennel Tasks workspace.",
+    folder
+      ? `The viewed folder is: ${folder}`
+      : "Work inside the viewed folder.",
+    "",
+    "The todo.json task files are still valid — these warnings are advisory.",
+    "Fix every warning; the context below lists each one.",
+    "",
+    "Warnings:",
+    ...warnings.map(
+      (warning) => `- ${warning.path || "todo.json"}: ${warning.message}`,
+    ),
+    "",
+    "Instructions for the LLM:",
+    "- Read every todo.json under the folder: the root todo.json, plus the file\n  named before the ': ' separator in each warning path. Do not invent tasks\n  and do not change statuses, priorities, or deadlines.",
+    '- For "no notes; link the accompanying note file or https reference":\n  create or update one accompanying markdown note next to that todo.json,\n  then add a notes array entry to the task — a note path relative to the\n  folder that owns the todo.json (optionally with a #Section heading) or an\n  https URL.',
+    "- Connect things where possible: put the related file references (specs,\n  evidence, other notes, and the task key such as 'Tracked as\n  office/todo.json TODO-7') into the note's linked sections so task and\n  note point at each other, and link existing workspace notes instead of\n  creating duplicates.",
+    '- For "references a missing note file": point the entry at an existing\n  file, or create the referenced note when it is clearly the intended\n  companion for that task.',
+    "- Keep todo.json valid: notes entries must be non-empty strings holding\n  a folder-relative path (never absolute or containing '..') or an https URL.",
+    "- Verify afterwards: re-open the Tasks tab and confirm the Warnings\n  button is gone, or GET /api/plugins/tasks?path=<folder> and confirm the\n  warnings array is empty.",
+  ]
+    .filter((line) => line != null)
+    .join("\n")

package/kernel/plugins/tasks/test/api.test.mjs

@@ -0,0 +1,99 @@
+import { describe, expect, test } from "bun:test"
+
+import { serializeTodoSource, toggleTaskSource } from "../src/api.ts"
+
+const source = `{
+  "$schema": "https://raggle.co/schemas/tasks.json",
+  "version": 2,
+  "id": "todo",
+  "title": "Project",
+  "tasks": [
+    {
+      "id": "t1",
+      "key": "TODO-1",
+      "name": "One",
+      "status": "todo",
+      "done": false
+    },
+    {
+      "id": "t2",
+      "key": "TODO-2",
+      "name": "Two",
+      "status": "done",
+      "done": true,
+      "resolution": "completed"
+    }
+  ]
+}
+`
+
+function parse(sourceText) {
+  return JSON.parse(sourceText)
+}
+
+describe("toggleTaskSource", () => {
+  test("marks an open task done with resolution and timestamps", () => {
+    const { done, next } = toggleTaskSource(source, "t1")
+    expect(done).toBe(true)
+    const doc = parse(next)
+    const task = doc.tasks[0]
+    expect(task.done).toBe(true)
+    expect(task.status).toBe("done")
+    expect(task.resolution).toBe("completed")
+    expect(typeof task.completedAt).toBe("string")
+    expect(typeof task.updatedAt).toBe("string")
+  })
+
+  test("matches a task by key", () => {
+    const { done } = toggleTaskSource(source, "TODO-1")
+    expect(done).toBe(true)
+  })
+
+  test("reopens a done task back to todo", () => {
+    const { done, next } = toggleTaskSource(source, "t2")
+    expect(done).toBe(false)
+    const task = parse(next).tasks[1]
+    expect(task.done).toBe(false)
+    expect(task.status).toBe("todo")
+    expect(task.resolution).toBe(null)
+    expect(task.completedAt).toBe(null)
+    expect(typeof task.updatedAt).toBe("string")
+  })
+
+  test("leaves other tasks untouched", () => {
+    const { next } = toggleTaskSource(source, "t1")
+    const task = parse(next).tasks[1]
+    expect(task.id).toBe("t2")
+    expect(task.status).toBe("done")
+  })
+
+  test("throws not-found for an unknown id", () => {
+    expect(() => toggleTaskSource(source, "nope")).toThrow(
+      /Task not found: nope/,
+    )
+  })
+
+  test("throws bad-request for an invalid document", () => {
+    expect(() => toggleTaskSource('{"tasks": [', "t1")).toThrow(
+      /not valid JSON/,
+    )
+  })
+})
+
+describe("serializeTodoSource", () => {
+  test("preserves the original indent and trailing newline", () => {
+    const doc = parse(source)
+    const next = serializeTodoSource(doc, source)
+    expect(next.endsWith("\n")).toBe(true)
+    expect(next.includes('\n      "id": "t1"')).toBe(true)
+    expect(JSON.parse(next)).toEqual(JSON.parse(source))
+  })
+
+  test("falls back to two-space indent without a trailing newline", () => {
+    const compact = '{"tasks":[{"id":"t1","name":"One"}]}'
+    const next = serializeTodoSource(parse(compact), compact)
+    expect(next.endsWith("\n")).toBe(false)
+    expect(next.includes('\n  "tasks"')).toBe(true)
+    expect(JSON.parse(next)).toEqual(JSON.parse(compact))
+  })
+})

package/kernel/plugins/tasks/test/folder-sources.test.mjs

@@ -0,0 +1,46 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { expect, test } from "bun:test"
+
+import { createTasksPlugin } from "../src/server.ts"
+
+test("a nested workspace merges task files into folder-tagged sources", async () => {
+  const folder = await mkdtemp(join(tmpdir(), "kennel-tasks-plugin-"))
+  try {
+    const nested = join(folder, "clients", "client-one")
+    await mkdir(nested, { recursive: true })
+    await writeFile(
+      join(folder, "todo.json"),
+      JSON.stringify({
+        title: "Example Workspace",
+        people: [{ id: "member", name: "Team Member" }],
+        tasks: [{ id: "root1", name: "Root", done: false }],
+      }),
+    )
+    await writeFile(
+      join(nested, "todo.json"),
+      JSON.stringify({
+        tasks: [{ id: "n1", name: "Nested", done: true }],
+      }),
+    )
+    const plugin = createTasksPlugin()
+    const detection = await plugin.detect({ folder })
+    expect(detection.status).toBe("available")
+    expect(detection.count).toBe(2)
+    const result = await plugin.handle({ folder }, "")
+    expect(result.kind).toBe("available")
+    const dataset = result.data.dataset
+    expect(dataset.people).toEqual([{ id: "member", name: "Team Member" }])
+    expect(dataset.tasks).toHaveLength(2)
+    expect(dataset.summary).toEqual({ completed: 1, open: 1, sources: 2 })
+    expect(dataset.tasks.map((task) => task.source.id).sort()).toEqual(
+      [folder, nested].sort(),
+    )
+    expect(dataset.sources.map((source) => source.id).sort()).toEqual(
+      [folder, nested].sort(),
+    )
+  } finally {
+    await rm(folder, { recursive: true, force: true })
+  }
+})

package/kernel/plugins/tasks/test/package.test.mjs

@@ -0,0 +1,54 @@
+import assert from "node:assert/strict"
+import { readFile } from "node:fs/promises"
+import test from "node:test"
+
+const packageJson = JSON.parse(
+  await readFile(new URL("../package.json", import.meta.url), "utf8"),
+)
+
+test("tasks package is ready for public npm publishing", () => {
+  assert.equal(packageJson.private, undefined)
+  assert.equal(packageJson.version, "0.1.0")
+  assert.equal(packageJson.license, "MIT")
+  assert.equal(packageJson.publishConfig?.access, "public")
+  assert.equal(packageJson.repository?.directory, "plugins/tasks")
+  assert.deepEqual(packageJson.files, ["src"])
+})
+
+test("tasks package ships the standard plugin script set", () => {
+  for (const script of [
+    "test",
+    "typecheck",
+    "format",
+    "lint",
+    "clean",
+    "pack:check",
+    "publish:public:dry-run",
+  ]) {
+    assert.ok(
+      typeof packageJson.scripts?.[script] === "string",
+      `missing script "${script}"`,
+    )
+  }
+})
+
+test("tasks package exposes API routes, parser, manifest, and split server/client entry points", () => {
+  assert.deepEqual(Object.keys(packageJson.exports).sort(), [
+    ".",
+    "./api",
+    "./client",
+    "./manifest",
+    "./parse",
+    "./server",
+    "./todo-model",
+    "./todo-model/styles.css",
+  ])
+})
+
+test("tasks client entry does not import the Node server entry", async () => {
+  const clientSource = await readFile(
+    new URL("../src/client.tsx", import.meta.url),
+    "utf8",
+  )
+  assert.doesNotMatch(clientSource, /node:|\/server"/)
+})

package/kernel/plugins/tasks/test/parse.test.mjs

@@ -0,0 +1,225 @@
+import { expect, test } from "bun:test"
+
+import {
+  parseTodoSource,
+  starterTodoSource,
+  todoIssueSummary,
+  validateTodoFile,
+} from "../src/data/parse.ts"
+
+test("parses a valid v2 document", () => {
+  const parsed = parseTodoSource(
+    JSON.stringify({
+      $schema: "https://raggle.co/schemas/tasks.json",
+      version: 2,
+      id: "todo",
+      title: "Local AI Tasks",
+      tasks: [
+        {
+          id: "t1",
+          key: "TODO-1",
+          name: "Follow up",
+          status: "todo",
+          priority: 2,
+          deadline: "2026-12-31",
+          acceptanceCriteria: [{ id: "ac-1", text: "Reply", done: false }],
+        },
+      ],
+    }),
+  )
+  expect(parsed.ok).toBe(true)
+  if (!parsed.ok) return
+  expect(parsed.document.tasks).toHaveLength(1)
+})
+
+test("reports invalid JSON with a readable detail", () => {
+  const parsed = parseTodoSource('{"tasks": [')
+  expect(parsed.ok).toBe(false)
+  if (parsed.ok) return
+  expect(parsed.issues).toHaveLength(1)
+  expect(parsed.issues[0].path).toBe("#")
+  expect(parsed.issues[0].message).toContain("not valid JSON")
+})
+
+test("non-object documents are rejected", () => {
+  expect(validateTodoFile(null)).toEqual([
+    { path: "#", message: "todo.json must contain a JSON object" },
+  ])
+  expect(validateTodoFile([1, 2])).toEqual([
+    { path: "#", message: "todo.json must contain a JSON object" },
+  ])
+})
+
+test("flags bad version and missing tasks array", () => {
+  const issues = validateTodoFile({ version: 3 })
+  expect(issues).toContainEqual({
+    path: "version",
+    message: "must be 1 or 2; got 3",
+  })
+  expect(issues).toContainEqual({
+    path: "tasks",
+    message: "must be an array of tasks",
+  })
+})
+
+test("flags a task without a name", () => {
+  const issues = validateTodoFile({ version: 2, tasks: [{ id: "t1" }] })
+  expect(issues).toContainEqual({
+    path: "tasks[0].name",
+    message: "required; a task needs a non-empty name",
+  })
+})
+
+test("flags an unknown status enum value", () => {
+  const issues = validateTodoFile({
+    version: 2,
+    tasks: [{ id: "t1", name: "One", status: "in-progress" }],
+  })
+  expect(issues).toContainEqual({
+    path: "tasks[0].status",
+    message:
+      'must be one of todo, in_progress, blocked, review, done, canceled; got "in-progress"',
+  })
+})
+
+test("flags an unknown type enum value", () => {
+  const issues = validateTodoFile({
+    version: 2,
+    tasks: [{ id: "t1", name: "One", type: "story" }],
+  })
+  expect(issues).toContainEqual({
+    path: "tasks[0].type",
+    message:
+      'must be one of task, bug, feature, chore, spike, epic, milestone; got "story"',
+  })
+})
+
+test("flags out-of-range priority and bad deadline", () => {
+  const issues = validateTodoFile({
+    version: 2,
+    tasks: [{ id: "t1", name: "One", priority: 9, deadline: "31/12/2026" }],
+  })
+  expect(issues).toContainEqual({
+    path: "tasks[0].priority",
+    message: "must be an integer between 1 and 5",
+  })
+  expect(issues).toContainEqual({
+    path: "tasks[0].deadline",
+    message: "must be an ISO date (YYYY-MM-DD)",
+  })
+})
+
+test("flags duplicate task ids", () => {
+  const issues = validateTodoFile({
+    version: 2,
+    tasks: [
+      { id: "t1", name: "One" },
+      { id: "t1", name: "Two" },
+    ],
+  })
+  expect(issues).toContainEqual({
+    path: "tasks[1].id",
+    message: 'duplicate task id "t1"',
+  })
+  expect(issues).not.toContainEqual(
+    expect.objectContaining({ path: "tasks[0].id" }),
+  )
+})
+
+test("flags check items missing required fields", () => {
+  const issues = validateTodoFile({
+    version: 2,
+    tasks: [
+      {
+        id: "t1",
+        name: "One",
+        steps: [{ id: "s1", text: "Do it" }],
+        acceptanceCriteria: "nope",
+      },
+    ],
+  })
+  expect(issues).toContainEqual({
+    path: "tasks[0].steps[0].done",
+    message: "required boolean",
+  })
+  expect(issues).toContainEqual({
+    path: "tasks[0].acceptanceCriteria",
+    message: "must be an array of check items",
+  })
+})
+
+test("flags invalid links", () => {
+  const issues = validateTodoFile({
+    version: 2,
+    tasks: [
+      {
+        id: "t1",
+        name: "One",
+        links: [
+          {
+            id: "l1",
+            provider: "github",
+            kind: "issue",
+            relation: "references",
+            url: "git@github.com:org/repo.git",
+          },
+          {
+            id: "l2",
+            provider: "linear",
+            kind: "issue",
+            relation: "references",
+            url: "https://example.com/x",
+          },
+        ],
+      },
+    ],
+  })
+  expect(issues).toContainEqual({
+    path: "tasks[0].links[0].url",
+    message: "is not a valid absolute URL",
+  })
+  expect(issues).toContainEqual({
+    path: "tasks[0].links[1].url",
+    message: "linear links must use linear.app",
+  })
+})
+
+test("flags relations that reference unknown task ids", () => {
+  const issues = validateTodoFile({
+    version: 2,
+    tasks: [
+      { id: "t1", name: "One" },
+      {
+        id: "t2",
+        name: "Two",
+        relations: [{ type: "blocked_by", targetTaskId: "missing" }],
+      },
+    ],
+  })
+  expect(issues).toContainEqual({
+    path: "tasks[1].relations[0].targetTaskId",
+    message: 'references unknown task id "missing"',
+  })
+})
+
+test("summary is compact for nav badges", () => {
+  expect(
+    todoIssueSummary([{ path: "tasks[0].name", message: "required" }]),
+  ).toBe("tasks[0].name: required")
+  expect(
+    todoIssueSummary([
+      { path: "tasks[0].name", message: "required" },
+      { path: "tasks[1].status", message: "bad status" },
+    ]),
+  ).toBe("2 problems found in todo.json (first: tasks[0].name — required)")
+})
+
+test("starter todo source validates and uses the folder name as title", () => {
+  const source = starterTodoSource("/tmp/kennel-example/local-ai")
+  const parsed = parseTodoSource(source)
+  expect(parsed.ok).toBe(true)
+  if (!parsed.ok) return
+  expect(parsed.document.tasks).toHaveLength(1)
+  expect(parsed.document.version).toBe(2)
+  expect(parsed.document.title).toBe("local-ai")
+})