kennel 0.2.0 → 0.2.2

package/kernel/plugins/projects/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: kennel-projects
+description: Open and read a folder's Raggle Scout connected projects in the Kennel viewer — one card per related repository (dependency, implementation, notes, related) with direction, depth, remote URL, local worktree path, folder links, and copy-context prompts. Use when the user asks to view connected or linked projects for a folder in Kennel, see which repositories depend on or feed a workspace, open a related project folder, or verify the Projects view loads.
+---
+
+# Kennel Projects Plugin
+
+The Projects plugin (`@raggle-ai/projects`) renders a folder's Raggle Scout
+connected-project graph in the Kennel web viewer: one card per related
+repository, a compact card list with relation badges (type, direction,
+depth), the remote URL, the local worktree path, and an "Open folder in the
+viewer" link per card.
+
+This skill covers the agent-facing parts of that plugin: where the data
+comes from, how detection works, and how to open and verify the view. For
+the plugin package's implementation contract, see `plugins/README.md` in the
+Kennel repo.
+
+## When to use
+
+- The user asks which projects are connected to (or linked with) a folder.
+- The user wants dependency, implementation, or notes relations of a
+  workspace shown as a list.
+- Preview or verification work needs the Projects plugin tab for a target
+  folder.
+
+## Data source
+
+The plugin runs Raggle Scout connected-project discovery
+(`@raggle-ai/local` `listConnectedProjects` + `connectedProjectsList`, depth
+1, focused) in a child process and renders its relation rows. There is no
+content file: the tab exists while Scout reports at least one related
+repository, and detection falls back to `unavailable` when none are
+connected. Discovery is cached per folder for 60 seconds. It fails cleanly
+to an in-band error panel when Scout cannot run; it never blocks the rest
+of the viewer.
+
+Each card dataset row has: `worktree` (absolute local path), `repository`
+(remote URL), `type` (`dependency` | `implementation` | `notes` |
+`related`), `direction` (`outgoing` = this folder links to the project;
+`incoming` = the project links to this folder), and `depth` (1 = direct).
+
+## Workflow
+
+1. **Identify the folder** whose connected projects the user wants.
+2. **Check the data without the UI:**
+   `curl -fsS "$URL/api/plugins/projects?path=<folder>"` returns
+   `status: "available"` with a `projects` array (or
+   `status: "error"` + `message` when discovery failed). The folder-shell
+   metadata API (`/api/metadata?part=plugins`) lists the Projects item with
+   a `count` equal to the relation total while Scout reports connections.
+3. **Open the view.** `kennel serve <folder>` (or `kennel view <folder>` in
+   a source checkout), then point at the Projects tab
+   (`/folder/<id>/views/projects`). Launch, port, watch, and link
+   verification mechanics come from the `kennel-preview` skill.
+4. **Verify before reporting.** Confirm the server is alive
+   (`curl -fsS "$URL/api/health"`), the /api/documents root is the requested
+   folder, the Projects tab is present with the expected count, and each
+   card's worktree and repository URL match the discovery output above.
+   Cards additionally link to the connected folder's own viewer page
+   (`/folder/<folderPathId(worktree)>/notes`).
+
+## Boundaries
+
+- Read-only detail: the plugin does not create, edit, or remove repository
+  links. Changing connections is the `rgl` CLI's job
+  (`rgl link`, `rgl unlink`); re-check the tab afterwards (data caches for
+  60 seconds per folder).
+- The stateless count comes from Scout at view time; do not invent
+  relations, directions, or repositories, and do not summarise a stalled
+  discovery as an empty list — an error panel means re-check or run `rgl`.
+- The Projects view only exists inside the Kennel viewer (server + web
+  app); the `@raggle-ai/projects` package is not a standalone CLI.

package/kernel/plugins/projects/eslint.config.js

@@ -0,0 +1,10 @@
+import baseConfig from "@raggle-ai/eslint-config/base"
+import reactConfig from "@raggle-ai/eslint-config/react"
+
+export default [
+  ...baseConfig,
+  ...reactConfig,
+  {
+    ignores: ["dist/**", "**/_generated/", "vendor/**"],
+  },
+]

package/kernel/plugins/projects/package.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "https://json.schemastore.org/package.json",
+  "name": "@raggle-ai/projects",
+  "version": "0.1.0",
+  "description": "Projects folder plugin: Raggle Scout connected-project cards for Kennel folders.",
+  "type": "module",
+  "license": "MIT",
+  "prettier": "@raggle-ai/prettier-config",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/raggle-ai/kennel.git",
+    "directory": "plugins/projects"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "files": [
+    "src"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./client": "./src/client.tsx",
+    "./manifest": "./src/manifest.ts",
+    "./model": "./src/data/model.ts",
+    "./server": "./src/server.ts"
+  },
+  "scripts": {
+    "test": "bun test test/*.test.mjs",
+    "typecheck": "tsc --noEmit",
+    "format": "prettier . --check --cache --cache-location .cache/.prettiercache --ignore-path ../../.prettierignore",
+    "format:fix": "prettier . --write --cache --cache-location .cache/.prettiercache --ignore-path ../../.prettierignore",
+    "lint": "eslint . --cache --cache-location .cache/.eslintcache",
+    "lint:fix": "eslint . --fix --cache --cache-location .cache/.eslintcache",
+    "clean": "git clean -xdf dist node_modules .cache .turbo/cache",
+    "pack:check": "npm pack --dry-run",
+    "publish:public:dry-run": "npm --@raggle-ai:registry=https://registry.npmjs.org publish --dry-run --access public --registry=https://registry.npmjs.org"
+  },
+  "dependencies": {
+    "@raggle-ai/folder-plugin": "workspace:*",
+    "@raggle-ai/ui": "workspace:*",
+    "@tanstack/react-query": "catalog:tanstack",
+    "lucide-react": "^0.562.0"
+  },
+  "peerDependencies": {
+    "react": ">=18.3.0"
+  },
+  "devDependencies": {
+    "@eslint/compat": "catalog:eslint",
+    "@eslint/eslintrc": "catalog:eslint",
+    "@ianvs/prettier-plugin-sort-imports": "catalog:prettier",
+    "@prettier/plugin-oxc": "catalog:prettier",
+    "@raggle-ai/eslint-config": "workspace:*",
+    "@raggle-ai/prettier-config": "workspace:*",
+    "@raggle-ai/tsconfig": "workspace:*",
+    "@types/node": "catalog:",
+    "@types/react": "catalog:react19",
+    "@types/react-dom": "catalog:react19",
+    "eslint": "catalog:eslint",
+    "eslint-plugin-unused-imports": "catalog:eslint",
+    "prettier": "catalog:prettier",
+    "prettier-plugin-classnames": "catalog:prettier",
+    "prettier-plugin-merge": "catalog:prettier",
+    "prettier-plugin-tailwindcss": "catalog:prettier",
+    "react": "catalog:react19",
+    "react-dom": "catalog:react19",
+    "typescript": "catalog:",
+    "typescript-eslint": "catalog:eslint"
+  }
+}

package/kernel/plugins/projects/src/client.tsx

@@ -0,0 +1,17 @@
+import type { FolderPluginViewProps } from "@raggle-ai/folder-plugin/client"
+
+import { projectsManifest } from "./manifest"
+import { ProjectsPage } from "./ui/projects-page.tsx"
+
+/**
+ * Client entry: the Projects plugin view. The dataset is one
+ * connected-projects list, so every subpath renders the same card page.
+ */
+export function ProjectsPlugin(props: FolderPluginViewProps) {
+  return <ProjectsPage {...props} />
+}
+
+export const projectsClient = {
+  ...projectsManifest,
+  component: ProjectsPlugin,
+}

package/kernel/plugins/projects/src/data/model.ts

@@ -0,0 +1,129 @@
+/**
+ * Browser-safe data model for the Projects plugin. The server loads a
+ * Raggle Scout connected-projects list and serializes it into a
+ * `ProjectsPayload`; the client decodes it here so a malformed payload
+ * surfaces the exact message instead of "could not parse".
+ */
+
+/** Relation kinds Raggle Scout reports between repositories. */
+export type RepositoryLinkType =
+  "dependency" | "implementation" | "notes" | "related"
+
+/** Which side of the link points at the other project. */
+export type RelationDirection = "incoming" | "outgoing"
+
+/** One connected project card in the dataset. */
+export type ConnectedProject = {
+  /** Canonical remote URL of the connected repository. */
+  repository?: string
+  /** Link type: dependency, implementation, notes, or related. */
+  type: RepositoryLinkType
+  /** `outgoing` = this folder links to it; `incoming` = it links to this folder. */
+  direction: RelationDirection
+  /** Relation-graph distance from the viewed folder (1 = direct). */
+  depth: number
+  /** Absolute worktree path on this machine. */
+  worktree: string
+}
+
+/** Payload shape the server handler returns and the client decodes. */
+export type ProjectsPayload = {
+  folder: string
+  projects: ConnectedProject[]
+  /** `error` means Scout discovery failed; `message` carries the reason. */
+  status: "available" | "error"
+  message?: string
+}
+
+const LINK_TYPES: readonly RepositoryLinkType[] = [
+  "dependency",
+  "implementation",
+  "notes",
+  "related",
+]
+
+function decodeProject(value: unknown): ConnectedProject {
+  if (typeof value !== "object" || value === null) {
+    throw new Error("connected project entry must be an object")
+  }
+  const entry = value as Record<string, unknown>
+  if (typeof entry.worktree !== "string" || !entry.worktree.trim()) {
+    throw new Error("connected project entry needs a worktree path")
+  }
+  if (!LINK_TYPES.includes(entry.type as RepositoryLinkType)) {
+    throw new Error(
+      `connected project type must be one of ${LINK_TYPES.join(", ")}; got ${
+        String(entry.type) || "nothing"
+      }`,
+    )
+  }
+  if (entry.direction !== "incoming" && entry.direction !== "outgoing") {
+    throw new Error(
+      `connected project direction must be "incoming" or "outgoing"; got ${
+        String(entry.direction) || "nothing"
+      }`,
+    )
+  }
+  if (typeof entry.depth !== "number" || entry.depth < 1) {
+    throw new Error("connected project depth must be a positive number")
+  }
+  return {
+    repository:
+      typeof entry.repository === "string" && entry.repository.trim()
+        ? entry.repository
+        : undefined,
+    type: entry.type as RepositoryLinkType,
+    direction: entry.direction,
+    depth: entry.depth,
+    worktree: entry.worktree,
+  }
+}
+
+/** Decode the server payload; throws with the exact field problem on a mismatch. */
+export function decodeProjectsPayload(data: unknown): ProjectsPayload {
+  if (typeof data !== "object" || data === null) {
+    throw new Error("Project data is not valid.")
+  }
+  const payload = data as Record<string, unknown>
+  if (typeof payload.folder !== "string" || !payload.folder.trim()) {
+    throw new Error("Project data needs a folder path")
+  }
+  if (payload.status !== "available" && payload.status !== "error") {
+    throw new Error("Project data status must be available or error")
+  }
+  if (!Array.isArray(payload.projects)) {
+    throw new Error("Project data needs a projects array")
+  }
+  return {
+    folder: payload.folder,
+    projects: payload.projects.map(decodeProject),
+    status: payload.status,
+    message:
+      typeof payload.message === "string" && payload.message.trim()
+        ? payload.message
+        : undefined,
+  }
+}
+
+/** Card heading: `host/owner/repo` from the remote URL, else the worktree basename. */
+export function projectLabel(project: ConnectedProject): string {
+  if (project.repository) {
+    const withoutScheme = project.repository.replace(
+      /^[a-z][a-z0-9+.-]*:\/\//i,
+      "",
+    )
+    const path = withoutScheme.replace(/\.git$/, "")
+    if (path) return path
+  }
+  const parts = project.worktree.split(/[\\/]/).filter(Boolean)
+  return parts[parts.length - 1] ?? project.worktree
+}
+
+/** Human-readable relation description for a card and its copied context. */
+export function relationText(project: ConnectedProject): string {
+  const arrow =
+    project.direction === "outgoing"
+      ? "this folder → project"
+      : "project → this folder"
+  return `${project.type} (${arrow}, depth ${project.depth})`
+}

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

@@ -0,0 +1,17 @@
+export { projectsManifest } from "./manifest.ts"
+export type {
+  ConnectedProject,
+  ProjectsPayload,
+  RelationDirection,
+  RepositoryLinkType,
+} from "./data/model.ts"
+export {
+  decodeProjectsPayload,
+  projectLabel,
+  relationText,
+} from "./data/model.ts"
+export { projectItemContext, projectsErrorContext } from "./project-context.ts"
+export type { ProjectsPluginProps } from "./ui/projects-page.tsx"
+export { ProjectsPage } from "./ui/projects-page.tsx"
+export type { ProjectCardProps } from "./ui/project-card.tsx"
+export { ProjectCard } from "./ui/project-card.tsx"

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

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

package/kernel/plugins/projects/src/project-context.ts

@@ -0,0 +1,41 @@
+import type { ConnectedProject } from "./data/model.ts"
+import { relationText } from "./data/model.ts"
+
+/**
+ * Agent-friendly context for one connected-project card, following the
+ * shared copy-context format (see .agents/skills/llm-copy-context).
+ */
+export function projectItemContext(project: ConnectedProject) {
+  return [
+    "You are helping inspect a connected project. Use the context below to act on it.",
+    "",
+    "Instructions for the LLM:",
+    "- Treat the local path as the authoritative location of the project.",
+    "- The repository URL is the canonical identity; if it is missing, work",
+    "  from the local path only.",
+    "- If information is missing, state the exact missing input - never invent it.",
+    "- Return: 1) project summary, 2) relation to the viewed folder, 3) next step.",
+    "",
+    "Project context:",
+    `- Repository: ${project.repository ?? "unknown (no remote URL)"}`,
+    `- Local path: ${project.worktree}`,
+    `- Relation: ${relationText(project)}`,
+  ].join("\n")
+}
+
+/** Agent-friendly context for a failed Projects view (folder plus failure). */
+export function projectsErrorContext(folder: string, error: string) {
+  return [
+    "The Kennel Projects view for this folder failed. Use the context below to",
+    "diagnose the cause, then re-check the Projects tab.",
+    "",
+    "Instructions for the LLM:",
+    "- The Projects view runs Raggle Scout connected-project discovery",
+    "  (`@raggle-ai/local` listConnectedProjects) in a child process and",
+    "  renders one card per relation.",
+    `- Folder: ${folder}`,
+    "",
+    "Failure:",
+    error,
+  ].join("\n")
+}

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

@@ -0,0 +1,276 @@
+import { execFile } from "node:child_process"
+import { existsSync } from "node:fs"
+import { createRequire } from "node:module"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+
+import type {
+  FolderPluginContext,
+  FolderPluginData,
+  FolderPluginDetection,
+} from "@raggle-ai/folder-plugin/server"
+
+import type { ConnectedProject } from "./data/model.ts"
+import { projectsManifest } from "./manifest.ts"
+
+/**
+ * Raggle Scout performs synchronous catalog/native work; a promise or
+ * timeout around that work in this process cannot protect HTTP/SSE from
+ * event-loop starvation. Like the host's linked-folder discovery, the
+ * connected-projects list is therefore computed in a child process
+ * `require`-ing the Scout local module (`@raggle-ai/local`, which exports
+ * `listConnectedProjects` and `connectedProjectsList`).
+ */
+const scoutScript = `
+const local = require(process.argv[1]);
+(async () => {
+  const folder = process.argv[2];
+  const connected = await local.listConnectedProjects(folder, {
+    depth: 1,
+    focused: true,
+  });
+  process.stdout.write(JSON.stringify(local.connectedProjectsList(folder, connected)));
+})().catch(error => { console.error(error); process.exitCode = 1; });
+`
+
+/**
+ * Resolve an `@raggle-ai/local` module that exports the connected-projects
+ * API. Published npm versions predate the API, so prefer the caller's own
+ * resolution and fall back to a sibling Scout development checkout.
+ */
+function resolveScoutModule(): string | undefined {
+  const require = createRequire(import.meta.url)
+  const candidates: string[] = []
+  try {
+    candidates.push(require.resolve("@raggle-ai/local"))
+  } catch {
+    // No installed copy; fall through to the dev checkout.
+  }
+  // Walk up from this file to a kennel checkout marker, then look for the
+  // Scout checkout as a sibling of the repo root.
+  let directory = dirname(fileURLToPath(import.meta.url))
+  while (dirname(directory) !== directory) {
+    if (existsSync(join(directory, "raggle.json"))) {
+      candidates.push(
+        join(dirname(directory), "raggle-ai-scout", "packages", "local"),
+      )
+      break
+    }
+    directory = dirname(directory)
+  }
+  for (const candidate of candidates) {
+    try {
+      const mod = require(candidate) as Record<string, unknown>
+      if (
+        typeof mod.listConnectedProjects === "function" &&
+        typeof mod.connectedProjectsList === "function"
+      ) {
+        return candidate
+      }
+    } catch {
+      // Unresolvable or broken; try the next candidate.
+    }
+  }
+  return undefined
+}
+
+type ScoutList = {
+  repositories?: unknown
+}
+
+/** Shape the Scout list rows into card entries, dropping unusable rows. */
+function normalizeRepositories(raw: ScoutList): ConnectedProject[] {
+  const repositories: ConnectedProject[] = []
+  if (!Array.isArray(raw.repositories)) return repositories
+  for (const value of raw.repositories) {
+    const row = value as Record<string, unknown> | null
+    if (!row || typeof row !== "object" || typeof row.worktree !== "string")
+      continue
+    const type = row.type
+    const direction = row.direction
+    if (
+      (type !== "dependency" &&
+        type !== "implementation" &&
+        type !== "notes" &&
+        type !== "related") ||
+      (direction !== "incoming" && direction !== "outgoing") ||
+      typeof row.depth !== "number" ||
+      typeof row.repository !== "string" ||
+      row.worktree.length === 0
+    )
+      continue
+    repositories.push({
+      depth: row.depth,
+      direction,
+      repository: row.repository,
+      type,
+      worktree: row.worktree,
+    })
+  }
+  return repositories
+}
+
+type ProjectsLoad = {
+  message?: string
+  projects: ConnectedProject[]
+  status: "available" | "error"
+}
+
+/** One Scout run; never rejects — failures become an in-band error payload. */
+function discoverProjects(
+  scoutModule: string,
+  folder: string,
+): Promise<ProjectsLoad> {
+  return new Promise((resolve) => {
+    execFile(
+      process.execPath,
+      ["-e", scoutScript, scoutModule, folder],
+      {
+        timeout: 60_000,
+        maxBuffer: 8 * 1024 * 1024,
+        // Do not inherit debugging/preload flags into background catalog jobs.
+        env: { ...process.env, NODE_OPTIONS: "" },
+      },
+      (error, stdout) => {
+        if (error) {
+          // Scout can stall when several catalog runs contend on one
+          // machine. The caller can retry; results stay cached per folder.
+          resolve({
+            message:
+              "Raggle Scout discovery timed out or failed. Retry the view to try again.",
+            projects: [],
+            status: "error",
+          })
+          return
+        }
+        try {
+          const list = JSON.parse(stdout) as ScoutList
+          resolve({
+            projects: normalizeRepositories(list),
+            status: "available",
+          })
+        } catch (parseError) {
+          resolve({
+            message: `Could not parse the Scout response: ${
+              parseError instanceof Error
+                ? parseError.message
+                : String(parseError)
+            }`,
+            projects: [],
+            status: "error",
+          })
+        }
+      },
+    )
+  })
+}
+
+/** Freshness window before a folder's Scout result is re-queried. */
+const TTL = 60_000
+/** Per-folder cache; values are served stale while a refresh is running. */
+const cache = new Map<string, ProjectsLoad>()
+const stamps = new Map<string, number>()
+/** In-flight Scout requests, one per folder. */
+const inflight = new Map<string, Promise<ProjectsLoad>>()
+/**
+ * Machine-wide single-flight queue: one Scout subprocess at a time.
+ * Overlapping catalog runs contend and can stall, so runs never overlap.
+ */
+let queue: Promise<void> = Promise.resolve()
+
+function requestProjects(
+  scoutModule: string,
+  folder: string,
+): Promise<ProjectsLoad> {
+  const existing = inflight.get(folder)
+  if (existing) return existing
+  const run = queue.then(
+    () => discoverProjects(scoutModule, folder),
+    () => discoverProjects(scoutModule, folder),
+  )
+  queue = run.then(
+    () => undefined,
+    () => undefined,
+  )
+  inflight.set(folder, run)
+  return run.finally(() => {
+    inflight.delete(folder)
+  })
+}
+
+async function loadProjects(
+  context: FolderPluginContext,
+): Promise<ProjectsLoad> {
+  const folder = context.folder
+  const cached = cache.get(folder)
+  const stamp = stamps.get(folder) ?? 0
+  if (cached && Date.now() - stamp < TTL) return cached
+  // Nothing fresh in the cache: start a refresh, but serve any stale value
+  // right away instead of blocking the view on a slow Scout run.
+  const scoutModule = resolveScoutModule()
+  if (cached && !scoutModule) return cached
+  if (scoutModule) {
+    const promise = requestProjects(scoutModule, folder)
+    if (cached) {
+      void promise.then((load) => {
+        // A stale-while-revalidate pass keeps the next view fresh; errors do
+        // not overwrite the last known good list.
+        if (load.status === "available") {
+          cache.set(folder, load)
+          stamps.set(folder, Date.now())
+        }
+      })
+      return cached
+    }
+    const load = await promise
+    if (load.status === "available") {
+      cache.set(folder, load)
+      stamps.set(folder, Date.now())
+    }
+    return load
+  }
+  return {
+    message:
+      "Raggle Scout module (@raggle-ai/local with connected-project discovery) could not be resolved.",
+    projects: [],
+    status: "error",
+  }
+}
+
+export function createProjectsPlugin() {
+  return {
+    ...projectsManifest,
+    async detect(
+      _context: FolderPluginContext,
+    ): Promise<FolderPluginDetection> {
+      // Detection never runs Scout: a late or contended catalog run must
+      // not hide the tab. The view renders its own loading/error states.
+      return { status: "available" }
+    },
+    async handle(
+      context: FolderPluginContext,
+      _subpath: string,
+    ): Promise<FolderPluginData> {
+      const load = await loadProjects(context)
+      if (load.status === "error") {
+        return {
+          kind: "available",
+          data: {
+            folder: context.folder,
+            message: load.message,
+            projects: [],
+            status: "error",
+          },
+        }
+      }
+      return {
+        kind: "available",
+        data: {
+          folder: context.folder,
+          projects: load.projects,
+          status: "available",
+        },
+      }
+    },
+  }
+}