kennel 0.2.13 → 0.2.15

package/kernel/packages/api/test/entity-folder.test.ts

@@ -1,131 +0,0 @@
-import { afterEach, describe, expect, test } from "bun:test";
-import { mkdir, mkdtemp, realpath, rm, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-
-import type { FolderEntity } from "../src/contracts";
-import { loadEntityWorkspace, rankEntity } from "../src/server/entity-folder";
-
-const cleanup: (() => Promise<unknown>)[] = [];
-
-afterEach(async () => {
-  delete process.env.XDG_CONFIG_HOME;
-  for (const fn of cleanup.splice(0).reverse()) await fn();
-});
-
-async function tempRoot(prefix: string): Promise<string> {
-  const root = await realpath(await mkdtemp(join(tmpdir(), prefix)));
-  cleanup.push(() => rm(root, { recursive: true, force: true }));
-  return root;
-}
-
-async function entityFolder(root: string, name = "alpha") {
-  const folder = join(root, name);
-  await mkdir(folder);
-  await writeFile(
-    join(folder, "index.md"),
-    "---\ntitle: Alpha\n---\n# Alpha\n",
-  );
-  return folder;
-}
-
-const entity: FolderEntity = {
-  aliases: ["Copper Watch", "Apart Book One"],
-  content: "Sam and Naya discover a watch ticking backwards after the Split.",
-  description: "The first manuscript in Apart.",
-  documents: [{ path: "Chapters/1. The Beginning.md", title: "The Beginning" }],
-  folderPath: "/workspace/books/The Copper Watch",
-  relativePath: "books/The Copper Watch",
-  schemaPath: "/workspace/books/The Copper Watch/schema.json",
-  slug: "the-copper-watch",
-  status: "drafting",
-  title: "The Copper Watch",
-  type: "manuscript",
-};
-
-describe("folder entity search", () => {
-  test("ranks title and alias matches above content matches", () => {
-    expect(rankEntity(entity, "Copper Watch")).toBeGreaterThan(
-      rankEntity(entity, "Split"),
-    );
-  });
-
-  test("searches entity metadata and rejects missing terms", () => {
-    expect(rankEntity(entity, "manuscript drafting")).toBeGreaterThan(0);
-    expect(rankEntity(entity, "unrelated phrase")).toBeLessThan(0);
-  });
-
-  test("uses the open workspace root when no user config exists", async () => {
-    const root = await tempRoot("kennel-entities-root-");
-    await entityFolder(root);
-    process.env.XDG_CONFIG_HOME = await tempRoot("kennel-entities-config-");
-
-    const workspace = await loadEntityWorkspace(undefined, "", null, root);
-
-    expect(workspace.rootPath).toBe(root);
-    expect(workspace.entities.map((item) => item.title)).toEqual(["Alpha"]);
-  });
-
-  test("allows configured roots and rejects filesystem escapes", async () => {
-    const allowed = await tempRoot("kennel-entities-allowed-");
-    const outside = await tempRoot("kennel-entities-outside-");
-    const configHome = await tempRoot("kennel-entities-config-");
-    await mkdir(join(configHome, "kennel"));
-    await writeFile(
-      join(configHome, "kennel", "config.json"),
-      JSON.stringify({ allowedRoots: [allowed] }),
-    );
-    await entityFolder(allowed);
-    await entityFolder(outside);
-    process.env.XDG_CONFIG_HOME = configHome;
-
-    await expect(
-      loadEntityWorkspace(allowed, "", null, outside),
-    ).resolves.toMatchObject({
-      rootPath: allowed,
-    });
-    await expect(
-      loadEntityWorkspace(outside, "", null, allowed),
-    ).rejects.toThrow("outside the configured roots");
-  });
-
-  test("invalid config fails closed", async () => {
-    const root = await tempRoot("kennel-entities-root-");
-    const configHome = await tempRoot("kennel-entities-config-");
-    await mkdir(join(configHome, "kennel"));
-    await writeFile(join(configHome, "kennel", "config.json"), "not json");
-    await entityFolder(root);
-    process.env.XDG_CONFIG_HOME = configHome;
-
-    await expect(
-      loadEntityWorkspace(undefined, "", null, root),
-    ).rejects.toThrow("Invalid Kennel entity root config");
-  });
-
-  test("unreadable config fails closed", async () => {
-    const root = await tempRoot("kennel-entities-root-");
-    const configHome = await tempRoot("kennel-entities-config-");
-    await mkdir(join(configHome, "kennel", "config.json"), {
-      recursive: true,
-    });
-    await entityFolder(root);
-    process.env.XDG_CONFIG_HOME = configHome;
-
-    await expect(
-      loadEntityWorkspace(undefined, "", null, root),
-    ).rejects.toThrow();
-  });
-
-  test("empty workspace root asks the UI to choose a root", async () => {
-    process.env.XDG_CONFIG_HOME = await tempRoot("kennel-entities-config-");
-
-    await expect(
-      loadEntityWorkspace(undefined, "", null),
-    ).resolves.toStrictEqual({
-      entities: [],
-      query: "",
-      rootPath: "",
-      selected: null,
-    });
-  });
-});

package/kernel/packages/api/test/linked-folder-discovery.test.ts

@@ -1,78 +0,0 @@
-import { expect, test } from "bun:test";
-import { mkdtemp, mkdir, writeFile, rm } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { createLinkedFolderDiscovery, discoverLinkedFolders } from "../src/server/linked-folder-discovery";
-
-test("pending discovery returns local state immediately and coalesces requests", async () => {
-  let complete!: (paths: string[]) => void;
-  let calls = 0;
-  const changed: string[] = [];
-  const cache = createLinkedFolderDiscovery(() => {
-    calls++;
-    return new Promise(resolve => { complete = resolve; });
-  }, folder => changed.push(folder));
-  try {
-    expect(cache.read("/project")).toEqual({ folders: [], status: "pending" });
-    const wait = cache.folders("/project");
-    await Promise.resolve();
-    cache.read("/project");
-    expect(calls).toBe(1);
-    complete(["/notes"]);
-    expect(await wait).toEqual(["/notes"]);
-    expect(cache.read("/project").status).toBe("ready");
-    expect(changed).toEqual(["/project"]);
-    expect(calls).toBe(1);
-  } finally { cache.close(); }
-});
-
-test("failed discovery is explicit and cached instead of retrying on every poll", async () => {
-  let calls = 0;
-  const cache = createLinkedFolderDiscovery(async () => { calls++; throw new Error("unavailable"); });
-  try {
-    await cache.folders("/project");
-    expect(cache.read("/project").status).toBe("error");
-    await cache.folders("/project");
-    expect(calls).toBe(1);
-  } finally { cache.close(); }
-});
-
-test("expired linked notes remain available while discovery refreshes", async () => {
-  const now = Date.now;
-  let complete!: (paths: string[]) => void;
-  let calls = 0;
-  const cache = createLinkedFolderDiscovery(async () => {
-    if (++calls === 1) return ["/notes"];
-    return new Promise(resolve => { complete = resolve; });
-  });
-  try {
-    expect(await cache.folders("/project")).toEqual(["/notes"]);
-    const later = now() + 61_000;
-    Date.now = () => later;
-    const result = cache.folders("/project");
-    expect(await Promise.race([result, new Promise(resolve => setTimeout(() => resolve("blocked"), 30))])).toEqual(["/notes"]);
-    expect(cache.read("/project").status).toBe("pending");
-  } finally {
-    complete?.(["/updated"]);
-    Date.now = now;
-    cache.close();
-  }
-});
-
-test("CPU-heavy discovery runs outside the event loop", async () => {
-  const root = await mkdtemp(join(tmpdir(), "kennel-linked-worker-"));
-  const controller = new AbortController();
-  const notes = join(root, "notes");
-  let ticks = 0;
-  const timer = setInterval(() => { ticks++; }, 20);
-  try {
-    await mkdir(notes);
-    const modulePath = join(root, "fixture.cjs");
-    await writeFile(modulePath, `exports.listConnectedProjects = folder => {
-      const end = Date.now() + 600; while (Date.now() < end) {}
-      return { selectedWorktree: folder, relations: [{ type: 'notes', source: folder, target: ${JSON.stringify(notes)} }] };
-    };`);
-    expect(await discoverLinkedFolders(root, controller.signal, modulePath)).toEqual([notes]);
-    expect(ticks).toBeGreaterThan(10);
-  } finally { clearInterval(timer); controller.abort(); await rm(root, { recursive: true, force: true }); }
-});

package/kernel/packages/api/test/media-endpoint.test.ts

@@ -1,83 +0,0 @@
-import { fetch } from "bun";
-import { afterEach, expect, test } from "bun:test";
-import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { createKennelApi } from "../src/server";
-
-const cleanup: (() => Promise<unknown>)[] = [];
-afterEach(async () => {
-  for (const fn of cleanup.splice(0).reverse()) await fn();
-});
-
-async function fixture() {
-  const root = await mkdtemp(join(tmpdir(), "kennel-media-"));
-  cleanup.push(() => rm(root, { recursive: true, force: true }));
-  await mkdir(join(root, "output", "clips"), { recursive: true });
-  await writeFile(join(root, "note.md"), "# Note\n");
-  // A minimal but non-empty fake MP4 payload.
-  await writeFile(
-    join(root, "output", "clips", "clip.mp4"),
-    Buffer.from([0x00, 0x00, 0x00, 0x18, 0x66, 0x74, 0x79, 0x70]),
-  );
-  await writeFile(join(root, "output", "clips", "sheet.jpg"), "jpeg-bytes");
-  await writeFile(join(root, "output", "clips", "page.html"), "<h1>hi</h1>");
-  const api = createKennelApi({ root });
-  cleanup.push(() => api.close());
-  const address = await api.listen(0);
-  if (!address || typeof address === "string")
-    throw new Error("Missing listener");
-  return { root, baseUrl: `http://127.0.0.1:${address.port}` };
-}
-
-const mediaUrl = (baseUrl: string, root: string, file: string) =>
-  `${baseUrl}/api/media?path=${encodeURIComponent(root)}&file=${encodeURIComponent(file)}`;
-
-test("media endpoint serves contained media files with typed headers", async () => {
-  const { root, baseUrl } = await fixture();
-  const response = await fetch(mediaUrl(baseUrl, root, "output/clips/clip.mp4"));
-  expect(response.status).toBe(200);
-  expect(response.headers.get("content-type")).toBe("video/mp4");
-  expect(response.headers.get("accept-ranges")).toBe("bytes");
-  expect(response.headers.get("x-content-type-options")).toBe("nosniff");
-  const body = await response.arrayBuffer();
-  expect(body.byteLength).toBe(8);
-});
-
-test("media endpoint answers range requests with 206 slices", async () => {
-  const { root, baseUrl } = await fixture();
-  const response = await fetch(mediaUrl(baseUrl, root, "output/clips/clip.mp4"), {
-    headers: { Range: "bytes=2-5" },
-  });
-  expect(response.status).toBe(206);
-  expect(response.headers.get("content-range")).toBe("bytes 2-5/8");
-  const slice = new Uint8Array(await response.arrayBuffer());
-  expect(slice).toEqual(new Uint8Array([0x00, 0x18, 0x66, 0x74]));
-});
-
-test("media endpoint revalidates with ETag", async () => {
-  const { root, baseUrl } = await fixture();
-  const url = mediaUrl(baseUrl, root, "output/clips/clip.mp4");
-  const first = await fetch(url);
-  const etag = first.headers.get("etag");
-  expect(etag).toBeTruthy();
-  const cached = await fetch(url, { headers: { "If-None-Match": etag! } });
-  expect(cached.status).toBe(304);
-});
-
-test("media endpoint rejects escaping, missing, and non-media files", async () => {
-  const { root, baseUrl } = await fixture();
-  expect(
-    (await fetch(mediaUrl(baseUrl, root, "../outside/clip.mp4"))).status,
-  ).toBe(404);
-  expect(
-    (await fetch(mediaUrl(baseUrl, root, "output/clips/missing.mp4"))).status,
-  ).toBe(404);
-  // Active content is never served as media.
-  expect(
-    (await fetch(mediaUrl(baseUrl, root, "output/clips/page.html"))).status,
-  ).toBe(404);
-  expect((await fetch(`${baseUrl}/api/media?path=${encodeURIComponent(root)}`)).status).toBe(
-    404,
-  );
-});

package/kernel/packages/api/test/project-discovery.test.ts

@@ -1,44 +0,0 @@
-import { expect, test } from "bun:test";
-import { createProjectDiscovery } from "../src/server/project-discovery";
-
-test("project scans coalesce and keep running for remaining subscribers", async () => {
-  let finish!: (value: []) => void;
-  let workerSignal!: AbortSignal;
-  let calls = 0;
-  const scan = createProjectDiscovery(async (_folder, signal) => {
-    calls++; workerSignal = signal;
-    return new Promise<[]>(resolve => { finish = resolve; });
-  });
-  const first = new AbortController();
-  const second = new AbortController();
-  const a = scan.read("/one", first.signal).catch(error => error.message);
-  const b = scan.read("/one", second.signal);
-  await Promise.resolve();
-  first.abort();
-  expect(await a).toBe("Discovery cancelled");
-  expect(workerSignal.aborted).toBe(false);
-  expect(calls).toBe(1);
-  finish([]);
-  expect(await b).toEqual([]);
-  scan.close();
-});
-
-test("obsolete queued scans never start", async () => {
-  let finish!: (value: []) => void;
-  const calls: string[] = [];
-  const scan = createProjectDiscovery(async folder => {
-    calls.push(folder);
-    return new Promise<[]>(resolve => { finish = resolve; });
-  });
-  const a = scan.read("/active", new AbortController().signal);
-  const controller = new AbortController();
-  const b = scan.read("/obsolete", controller.signal).catch(error => error.message);
-  await Promise.resolve();
-  controller.abort();
-  expect(await b).toBe("Discovery cancelled");
-  finish([]);
-  await a;
-  await new Promise(resolve => setTimeout(resolve, 0));
-  expect(calls).toEqual(["/active"]);
-  scan.close();
-});

package/kernel/packages/api/tsconfig.json

@@ -1,11 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022", "module": "ESNext", "moduleResolution": "Bundler",
-    "strict": true, "skipLibCheck": true, "noEmit": true,
-    "allowImportingTsExtensions": true, "esModuleInterop": true, "jsx": "react-jsx", "types": ["node"],
-    "paths": {
-      "~/*": ["${configDir}/../../packages/*/src"]
-    }
-  },
-  "include": ["src"]
-}

package/kernel/packages/api-client/README.md

@@ -1,72 +0,0 @@
-# Kennel client
-
-Local workspace package `kennel-client`. The web app maps `~/*` to package source
-entry points in TypeScript and Vite, so it uses:
-
-```ts
-import { api } from "~/api-client"
-
-const notes = await api.notes({ path: folder, notesScope: "local", signal })
-const workspace = await api.metadata(href, "workspace", { signal })
-await api.documentEdit({ folder, path, original, start, end, replacement })
-```
-
-The CLI build bundles this client into `cli/dist/core/api-client.js` for published
-Node installs. Its build-time declaration derives response types from generated
-OpenAPI; client typechecks verify that declaration matches the real factory.
-Vite config-time code imports the source by relative path because application
-aliases are not active while Vite loads its configuration.
-
-Other workspace consumers can depend on `"kennel-client": "workspace:*"` and
-import `createKennelClient` from `kennel-client`. Node callers supply `baseUrl`;
-tests can also inject `fetch`. The web singleton uses the current browser origin.
-The `@/*` app-source alias remains unchanged; `~/api-client` is a package shortcut,
-not an npm scope or a package.json import alias.
-
-## Contract pipeline
-
-1. Edit browser-safe Zod schemas and route definitions in
-   `packages/api/src/contracts/schemas.ts`. Public DTOs are inferred from them.
-2. Server handlers validate queries and core successful JSON responses. Existing
-   host/origin authorization stays ahead of mutation parsing. Document edits use
-   the shared body schema after authorization.
-3. Run `bun run --cwd packages/api-client generate`. This produces
-   `packages/api/openapi.json` and `src/generated.d.ts` using openapi-typescript.
-4. The shared client uses openapi-fetch with generated paths for HTTP requests,
-   and the same schemas for runtime response validation. Metadata selectors infer
-   specific response types; callers cannot assert an arbitrary `metadata<T>`.
-5. CI checks generated artifacts, client/core tests, and workspace typechecking.
-   Add operations here instead of adding fetch calls to screens.
-
-Generated files are checked in. Do not edit them manually. This is a **local source
-workspace package**, not a standalone published SDK: its schema imports refer to
-its sibling API package. A published SDK would need bundled schemas and JS output.
-
-## Ownership and compatibility
-
-- This package owns core HTTP actions, encoding, errors, response validation and
-  cancellation. React Query cache keys/hooks and presentation stay in web.
-- Web URL helpers remain for actual links; they do not make HTTP requests.
-- Old API client entry points and `apps/web/src/api/client.ts` are re-exports,
-  not alternative implementations.
-- Raw files and dynamically registered plugins have dedicated escape hatches;
-  plugin payloads are honestly `unknown`, not caller-asserted types.
-- ACP commands, session transcripts and SSE remain separate legacy protocols.
-  They are not represented by this core JSON OpenAPI document. The web lint rule
-  has an explicit four-file allowlist for the remaining session/ACP fetch calls.
-- Errors may still be structured JSON or plain text. `ApiClientError` preserves
-  status, message and structured code. No automatic retries for mutations.
-
-## Verification
-
-```sh
-bun run --cwd packages/api-client generate:check
-bun run --cwd packages/api-client typecheck
-bun test packages/api-client/test packages/api/test
-bun run --cwd apps/web typecheck
-# linked-notes test lives in https://github.com/raggle-ai/kennel-tests
-```
-
-The linked-notes test uses a real fixture server and the same client as consumers.
-Its subprocesses isolate Scout's process-global settings/cache. Browser tests
-mock the standard Fetch `Request` input, including its abort signal.

package/kernel/packages/api-client/package.json

@@ -1,26 +0,0 @@
-{
-  "name": "kennel-client",
-  "version": "0.1.0",
-  "private": true,
-  "type": "module",
-  "exports": {
-    ".": "./src/index.ts",
-    "./errors": "./src/errors.ts",
-    "./generated": "./src/generated.d.ts"
-  },
-  "scripts": {
-    "generate": "bun scripts/generate.ts",
-    "generate:check": "bun scripts/generate.ts --check",
-    "typecheck": "tsc --noEmit",
-    "test": "bun test test"
-  },
-  "dependencies": {
-    "openapi-fetch": "0.17.0",
-    "zod": "catalog:"
-  },
-  "devDependencies": {
-    "@types/bun": "catalog:",
-    "openapi-typescript": "7.13.0",
-    "typescript": "catalog:"
-  }
-}

package/kernel/packages/api-client/scripts/generate.ts

@@ -1,68 +0,0 @@
-import { readFile, writeFile } from "node:fs/promises";
-import openapiTS, { astToString } from "openapi-typescript";
-import { z } from "zod";
-import { routes } from "../../api/src/contracts/schemas";
-
-const paths: Record<string, unknown> = {};
-const schema = (value: z.ZodType) => {
-  const { $schema, ...json } = z.toJSONSchema(value, {
-    target: "draft-2020-12",
-  });
-  return json;
-};
-for (const [operationId, route] of Object.entries(routes)) {
-  const query = schema(route.query);
-  paths[route.path] = {
-    [route.method]: {
-      operationId,
-      parameters: Object.entries(query.properties ?? {}).map(
-        ([name, value]) => ({
-          name,
-          in: "query",
-          required: query.required?.includes(name) ?? false,
-          schema: value,
-        }),
-      ),
-      ...("body" in route
-        ? {
-            requestBody: {
-              required: true,
-              content: { "application/json": { schema: schema(route.body) } },
-            },
-          }
-        : {}),
-      responses: {
-        ["response" in route ? "200" : "204"]: {
-          description: "Success",
-          ...("response" in route
-            ? {
-                content: {
-                  "application/json": { schema: schema(route.response) },
-                },
-              }
-            : {}),
-        },
-        default: { description: "Request rejected; JSON or plain-text error" },
-      },
-    },
-  };
-}
-const document = {
-  openapi: "3.1.0",
-  info: { title: "Kennel core API", version: "1.0.0" },
-  paths,
-};
-const json = JSON.stringify(document, null, 2) + "\n";
-const declarations = astToString(await openapiTS(json));
-for (const [path, content] of [
-  [new URL("../../api/openapi.json", import.meta.url), json],
-  [new URL("../src/generated.d.ts", import.meta.url), declarations],
-] as const) {
-  if (process.argv.includes("--check")) {
-    if ((await readFile(path, "utf8").catch(() => "")) !== content) {
-      throw new Error(
-        `Stale generated contract: ${path.pathname}. Run bun run --cwd packages/api-client generate`,
-      );
-    }
-  } else await writeFile(path, content);
-}

package/kernel/packages/api-client/src/errors.ts

@@ -1,59 +0,0 @@
-/**
- * Error raised by the viewer API client when the server rejects a request.
- * Carries the structured code/status from the endpoint when available so the
- * UI can adapt (403 remote host actions, 409 stale edits, ...).
- */
-type ErrorBody =
-  { error?: { code?: string; message?: string } | string } | undefined;
-
-export class ApiClientError extends Error {
-  readonly code?: string;
-  readonly status?: number;
-
-  constructor(
-    message: string,
-    options: { code?: string; status?: number } = {},
-  ) {
-    super(message);
-    this.name = "ApiClientError";
-    this.code = options.code;
-    this.status = options.status;
-  }
-}
-
-/**
- * Turns a failed fetch Response into an ApiClientError. Server endpoints
- * agree on `{ error: { code, message } }` JSON, but plain-text errors (older
- * middleware, Vite plugin fallbacks) are preserved too. The body is read
- * exactly once and parsed as JSON only when the content type suggests it.
- */
-export async function expectedError(
-  response: Response,
-): Promise<ApiClientError> {
-  const body = await response.text().catch(() => "");
-  const structured = response.headers
-    .get("content-type")
-    ?.includes("application/json");
-  if (structured) {
-    try {
-      const value = JSON.parse(body) as ErrorBody;
-      const error = value?.error;
-      if (error && typeof error === "object" && error.message) {
-        return new ApiClientError(error.message, {
-          code: error.code,
-          status: response.status,
-        });
-      }
-      if (typeof error === "string" && error)
-        return new ApiClientError(error, { status: response.status });
-    } catch {
-      // Not JSON despite the header; fall through to the raw text.
-    }
-  }
-  return new ApiClientError(
-    body.trim() || `Request failed with status ${response.status}`,
-    {
-      status: response.status,
-    },
-  );
-}