kennel 0.2.32 → 0.2.33

package/dist/llm/command.js

@@ -13,12 +13,19 @@ const LLM_USAGE = `Usage:
 Prints only applicable AGENTS.md, personal instructions, and the research
 write destination. The folder defaults to the current directory. Startup
 reads registered workspace configs without scanning notes or the project catalog.
+Folders inside the configured Raggle base repository (rgl base) omit the
+generated write destination and linked repository context. Elsewhere, the
+destination is an explicit Raggle notes link when one exists; otherwise,
+with repositoryNotes enabled in the Kennel user config, it is the repository
+notes folder (kennel notes path), looked up read-only: startup registers nothing.
 
-  full                 Add folder details, all links, local subpaths, and plugin sections.
+  full                 Add folder details and plugin sections; outside the base,
+                       also add all links and local subpaths.
   --depth <count>      Add links and plugin sections, limited to a positive graph depth.
   --profile <name>     Use this personal instruction profile.
-  --no-instructions    Omit personal profiles and all inlined instruction files. Expanded
-                       modes can still include graph paths and plugin context.
+  --no-instructions    Omit personal profiles, all inlined instruction files, and the
+                       generated write destination. Expanded modes can still include
+                       graph paths and plugin context.
   --no-plugins         Omit plugins in expanded modes. Startup never loads plugins.
   --copy               Copy the message to the clipboard instead of printing it.
 

package/dist/llm/worker.js

@@ -19,8 +19,8 @@ import {
   readSync as readSync2,
   statSync as statSync3
 } from "node:fs";
-import { dirname as dirname3, join as join3, relative as relative2 } from "node:path";
-import local3 from "@raggle-ai/local";
+import { dirname as dirname4, join as join4, relative as relative4 } from "node:path";
+import local4 from "@raggle-ai/local";
 function unique(values) {
   return [...new Set(values)];
 }
@@ -28,39 +28,39 @@ function singleLine(text) {
   return text.replace(/\s+/g, " ").trim();
 }
 function gitRoot2(folder) {
-  for (let directory = folder;; directory = dirname3(directory)) {
-    if (statSync3(join3(directory, ".git"), { throwIfNoEntry: false })) {
+  for (let directory = folder;; directory = dirname4(directory)) {
+    if (statSync3(join4(directory, ".git"), { throwIfNoEntry: false })) {
       return directory;
     }
-    if (dirname3(directory) === directory)
+    if (dirname4(directory) === directory)
       return;
   }
 }
 function projectConfigDirectory(folder) {
   const boundary = gitRoot2(folder) ?? folder;
-  for (let directory = folder;; directory = dirname3(directory)) {
-    const config = statSync3(join3(directory, "raggle.json"), {
+  for (let directory = folder;; directory = dirname4(directory)) {
+    const config = statSync3(join4(directory, "raggle.json"), {
       throwIfNoEntry: false
     });
     if (config?.isFile())
       return directory;
-    if (directory === boundary || dirname3(directory) === directory) {
+    if (directory === boundary || dirname4(directory) === directory) {
       return boundary;
     }
   }
 }
 function readProjectConfig(directory) {
   try {
-    return local3.readRaggleProjectConfig(directory);
+    return local4.readRaggleProjectConfig(directory);
   } catch (error) {
-    throw new Error(`Invalid Raggle config ${join3(directory, "raggle.json")}: ${error.message}`);
+    throw new Error(`Invalid Raggle config ${join4(directory, "raggle.json")}: ${error.message}`);
   }
 }
 function readReadmePrefix(worktree) {
   for (const name of readmeNames) {
     let fd;
     try {
-      fd = openSync2(join3(worktree, name), constants2.O_RDONLY | (constants2.O_NONBLOCK ?? 0));
+      fd = openSync2(join4(worktree, name), constants2.O_RDONLY | (constants2.O_NONBLOCK ?? 0));
       if (!fstatSync2(fd).isFile())
         continue;
       const buffer = Buffer.alloc(maxReadmeBytes);
@@ -93,7 +93,7 @@ function projectSummary(project) {
 }
 function repositoryLabel(project) {
   const remoteUrl = project.remoteMismatch?.actualRemoteUrl ?? project.remoteUrl;
-  const browserUrl = remoteUrl ? local3.remoteToBrowserUrl(remoteUrl) ?? remoteUrl : undefined;
+  const browserUrl = remoteUrl ? local4.remoteToBrowserUrl(remoteUrl) ?? remoteUrl : undefined;
   const worktree = canonicalPath(project.worktree);
   return browserUrl ? `${worktree} (${browserUrl})` : worktree;
 }
@@ -103,7 +103,7 @@ function repositoryKeys(project) {
     project.remoteUrl,
     ...project.relatedIds ?? []
   ].flatMap((url) => {
-    const key = url ? local3.repositoryLocationKey(url) : undefined;
+    const key = url ? local4.repositoryLocationKey(url) : undefined;
     return key ? [key] : [];
   });
 }
@@ -118,7 +118,7 @@ function missingLinks(config, connected) {
     return [];
   const present = new Set([...connected.linked, ...connected.linking, ...connected.local].flatMap(repositoryKeys));
   return direct.filter(({ repository }) => {
-    const key = local3.repositoryLocationKey(repository);
+    const key = local4.repositoryLocationKey(repository);
     return Boolean(key) && !isOrganisationKey(key) && !present.has(key);
   });
 }
@@ -187,7 +187,7 @@ function treeLines(root, projects, relations, direction, type, reasons) {
   return lines;
 }
 function localSubpathName(folder, project) {
-  return project.relativePath || relative2(canonicalPath(folder), canonicalPath(project.worktree));
+  return project.relativePath || relative4(canonicalPath(folder), canonicalPath(project.worktree));
 }
 function modeLabel(depth) {
   if (depth === "full")
@@ -196,9 +196,24 @@ function modeLabel(depth) {
 }
 async function buildCoreContext(options) {
   const { folder, depth, signal } = options;
+  signal.throwIfAborted();
+  if (options.localOnly) {
+    return {
+      blocks: [
+        [
+          "## Folder",
+          "",
+          `- Path: ${folder}`,
+          "- Context: current folder only"
+        ].join(`
+`)
+      ],
+      linkedFolders: []
+    };
+  }
   const configDirectory = projectConfigDirectory(folder);
   const config = readProjectConfig(configDirectory);
-  const connected = await local3.mergePersonalRelations(folder, await local3.listConnectedProjects(folder, {
+  const connected = await local4.mergePersonalRelations(folder, await local4.listConnectedProjects(folder, {
     depth
   }));
   signal.throwIfAborted();
@@ -219,7 +234,7 @@ async function buildCoreContext(options) {
   const linkedKeys = new Set(connected.linked.map((project) => canonicalPath(project.worktree)));
   const localSubpaths = connected.local.filter((project) => !linkedKeys.has(canonicalPath(project.worktree))).map((project) => localSubpathName(folder, project)).filter((name) => name && name !== ".");
   const missing = missingLinks(config, connected);
-  const configFile = join3(configDirectory, "raggle.json");
+  const configFile = join4(configDirectory, "raggle.json");
   const blocks = [
     [
       "## Folder",
@@ -280,7 +295,7 @@ async function buildCoreContext(options) {
 }
 var canonicalPath, readmeNames, maxReadmeBytes, maxSummaryLength = 280;
 var init_context = __esm(() => {
-  ({ canonicalPath } = local3);
+  ({ canonicalPath } = local4);
   readmeNames = ["README.md", "README.markdown", "README", "readme.md"];
   maxReadmeBytes = 16 * 1024;
 });
@@ -379,6 +394,7 @@ async function runContributors(contributors, context) {
       output = await contributor.llm({
         folder: context.folder,
         linkedFolders: [...context.linkedFolders],
+        ...context.managedFolders?.length ? { managedFolders: [...context.managedFolders] } : {},
         signal: context.signal
       });
     } catch (error) {
@@ -575,8 +591,9 @@ async function buildAgentContext(options) {
   const { folder, signal } = options;
   const settings = local2.readRaggleUserSettings();
   const checkout = gitRoot(folder);
+  const locations = options.localOnly ? {} : settings.repositoryLocations;
   let remote;
-  if (checkout) {
+  if (checkout && !options.localOnly) {
     try {
       remote = await local2.gitRemoteUrl(checkout);
     } catch (error) {
@@ -592,16 +609,16 @@ async function buildAgentContext(options) {
   };
   if (remote)
     addIdentity(remote);
-  for (const [repository, location] of Object.entries(settings.repositoryLocations)) {
+  for (const [repository, location] of Object.entries(locations)) {
     const preferred = local2.canonicalPath(location.preferredWorktree);
     if (exists(preferred) && checkout && gitRoot(preferred) === checkout) {
       addIdentity(repository);
     }
   }
-  const roots = [
+  const roots = options.localOnly ? [folder] : [
     folder,
     ...settings.projectDirectories,
-    ...Object.values(settings.repositoryLocations).map((entry) => entry.preferredWorktree),
+    ...Object.values(locations).map((entry) => entry.preferredWorktree),
     ...local2.getResolvedWorkspaces().map((entry) => entry.worktree),
     ...settings.baseRepository ? [settings.baseRepository] : []
   ];
@@ -613,7 +630,7 @@ async function buildAgentContext(options) {
     return Boolean(key && identities.has(key));
   };
   const configErrors = new Map;
-  for (const owner of configFolders(roots)) {
+  for (const owner of configFolders(roots, options.localOnly ? checkout : undefined)) {
     signal.throwIfAborted();
     let config;
     try {
@@ -644,15 +661,25 @@ async function buildAgentContext(options) {
   const destination = [...notes][0] ?? [...projectNotes][0];
   const sources = new Set;
   const addChain = (source, boundary) => {
-    for (const ancestor of configFolders([source], boundary).reverse())
+    const root = boundary ?? gitRoot(source);
+    const chain = [];
+    for (let current = local2.canonicalPath(source);; current = dirname2(current)) {
+      chain.push(current);
+      if (current === root || dirname2(current) === current)
+        break;
+    }
+    for (const ancestor of chain.reverse())
       sources.add(ancestor);
-    sources.add(source);
   };
   const outerOrganisations = [...organisations].filter((source) => ![...organisations].some((parent) => parent !== source && inside(source, parent)));
   for (const source of outerOrganisations)
     addChain(source);
   if (destination)
     addChain(destination);
+  for (const source of options.instructionSources ?? []) {
+    if (exists(source))
+      addChain(source);
+  }
   if (checkout)
     sources.add(checkout);
   if (folder !== checkout)
@@ -679,11 +706,9 @@ async function buildAgentContext(options) {
         blocks.push(instruction.content.trim());
     }
   }
-  if (destination && destination !== folder) {
-    blocks.push(`Write any planning or research content you create during this session (markdown, html files etc) to ${destination}`);
-  }
   return {
     blocks,
+    ...destination ? { destination } : {},
     linkedFolders: [...new Set([...notes, ...projectNotes])].filter((path) => path !== folder)
   };
 }
@@ -731,6 +756,236 @@ function renderMessage(blocks) {
 ` : "";
 }
 
+// packages/llm/src/routing.ts
+import { isAbsolute as isAbsolute2, relative as relative3, sep as sep3 } from "node:path";
+import local3 from "@raggle-ai/local";
+
+// packages/notes/src/store.ts
+import { execFile } from "node:child_process";
+import {
+  mkdir,
+  readdir,
+  readFile,
+  realpath,
+  rename,
+  rm,
+  stat,
+  writeFile
+} from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, dirname as dirname3, join as join3, relative as relative2, resolve, sep as sep2 } from "node:path";
+import { promisify } from "node:util";
+var run = promisify(execFile);
+var REPOSITORY_ID_KEY = "kennel.repoId";
+var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u;
+var markdownExtensions = new Set([".md", ".markdown"]);
+var caseInsensitiveHosts = new Set(["github.com", "gitlab.com", "bitbucket.org"]);
+class RepositoryNotesError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "RepositoryNotesError";
+    this.code = code;
+  }
+}
+function kennelConfigHome() {
+  const xdg = process.env.XDG_CONFIG_HOME?.trim();
+  return xdg ? xdg : join3(homedir(), ".config");
+}
+function kennelConfigFile() {
+  return join3(kennelConfigHome(), "kennel", "config.json");
+}
+function repositoryNotesRoot() {
+  return join3(kennelConfigHome(), "kennel", "repos");
+}
+function isRepositoryId(value) {
+  return typeof value === "string" && UUID.test(value);
+}
+function managedNotesDirectory(id) {
+  if (!isRepositoryId(id)) {
+    throw new RepositoryNotesError("invalid-id", `Invalid repository id: ${id}`);
+  }
+  return join3(repositoryNotesRoot(), id);
+}
+async function readRepositoryNotesSettings() {
+  const file = kennelConfigFile();
+  let text;
+  try {
+    text = await readFile(file, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return { enabled: false };
+    }
+    throw new RepositoryNotesError("config-invalid", `Cannot read ${file}: ${errorMessage(error)}`);
+  }
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch (error) {
+    throw new RepositoryNotesError("config-invalid", `Invalid JSON in ${file}: ${errorMessage(error)}`);
+  }
+  if (!isRecord(value)) {
+    throw new RepositoryNotesError("config-invalid", `${file} must hold an object`);
+  }
+  const section = value.repositoryNotes;
+  if (section === undefined)
+    return { enabled: false };
+  if (!isRecord(section) || section.enabled !== undefined && typeof section.enabled !== "boolean") {
+    throw new RepositoryNotesError("config-invalid", `${file}: repositoryNotes must be an object with a boolean "enabled" field`);
+  }
+  return { enabled: section.enabled === true };
+}
+async function git(args, cwd) {
+  const { stdout } = await run("git", args, {
+    cwd,
+    env: { ...process.env, GIT_OPTIONAL_LOCKS: "0", GIT_TERMINAL_PROMPT: "0" },
+    maxBuffer: 1024 * 1024
+  });
+  return stdout.replace(/\r?\n$/u, "");
+}
+function gitExitCode(error) {
+  const code = error.code;
+  return typeof code === "number" ? code : undefined;
+}
+async function resolveCheckout(folder) {
+  let start;
+  try {
+    start = await realpath(resolve(folder));
+    if (!(await stat(start)).isDirectory())
+      start = dirname3(start);
+  } catch {
+    throw new RepositoryNotesError("not-git", `Folder does not exist: ${folder}`);
+  }
+  let output;
+  try {
+    output = await git(["rev-parse", "--path-format=absolute", "--show-toplevel", "--git-common-dir"], start);
+  } catch (error) {
+    if (gitExitCode(error) === 128) {
+      throw new RepositoryNotesError("not-git", `Not a Git repository: ${start}. Repository notes need a Git checkout.`);
+    }
+    throw error;
+  }
+  const [top, common] = output.split(/\r?\n/u);
+  if (!top || !common) {
+    throw new RepositoryNotesError("not-git", `Not a Git work tree: ${start}`);
+  }
+  const root = await realpath(top);
+  const commonDir = await realpath(common);
+  return { root, commonDir, configFile: join3(commonDir, "config") };
+}
+async function readBinding(checkout) {
+  let value;
+  try {
+    value = await git(["config", "--file", checkout.configFile, "--get", REPOSITORY_ID_KEY], checkout.root);
+  } catch (error) {
+    if (gitExitCode(error) === 1)
+      return;
+    throw error;
+  }
+  const id = value.trim();
+  if (!id)
+    return;
+  if (!isRepositoryId(id)) {
+    throw new RepositoryNotesError("invalid-binding", `${checkout.configFile} has an invalid ${REPOSITORY_ID_KEY} value. Remove it or run "kennel notes new-identity".`);
+  }
+  return id;
+}
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+async function lookupRepositoryNotes(folder) {
+  let checkout;
+  try {
+    checkout = await resolveCheckout(folder);
+  } catch (error) {
+    if (error instanceof RepositoryNotesError && error.code === "not-git") {
+      return { status: "not-git", folder };
+    }
+    throw error;
+  }
+  const id = await readBinding(checkout);
+  if (!id)
+    return { status: "unregistered", checkout, root: checkout.root };
+  return {
+    status: "registered",
+    checkout,
+    id,
+    notesDirectory: managedNotesDirectory(id),
+    root: checkout.root
+  };
+}
+
+// packages/llm/src/routing.ts
+async function managedNotesState(folder) {
+  const base = local3.readRaggleUserSettings().baseRepository;
+  if (base) {
+    const baseFolder = local3.canonicalPath(base);
+    const path = relative3(baseFolder, folder);
+    if (path === "" || !isAbsolute2(path) && path !== ".." && !path.startsWith(`..${sep3}`)) {
+      const [checkout, baseCheckout] = await Promise.all([
+        resolveCheckout(folder),
+        resolveCheckout(baseFolder)
+      ]);
+      if (checkout.commonDir === baseCheckout.commonDir) {
+        return { status: "base" };
+      }
+    }
+  }
+  const settings = await readRepositoryNotesSettings();
+  if (!settings.enabled)
+    return { status: "disabled" };
+  const lookup = await lookupRepositoryNotes(folder);
+  if (lookup.status === "not-git")
+    return { status: "not-git" };
+  if (lookup.status === "unregistered") {
+    return { status: "unregistered", root: lookup.root };
+  }
+  return {
+    status: "registered",
+    notesDirectory: lookup.notesDirectory,
+    root: lookup.root
+  };
+}
+function shellQuote(value) {
+  return `"${value.replace(/[\\"$`]/gu, (character) => `\\${character}`)}"`;
+}
+var managedRules = [
+  "Keep code and requested repository documentation in the repository.",
+  "Stop and report the failure if the destination cannot be resolved or written.",
+  "Report the saved path and offer a preview link of the note with `kennel pop <file-path>` for the user to view in their browser."
+];
+function routingInstruction({
+  explicit,
+  folder,
+  managed
+}) {
+  if (managed.status === "base")
+    return;
+  const message = [
+    "Unless the task or applicable project instructions name another destination,",
+    "write research, plans, meeting notes, and session summaries as Markdown to",
+    "the following local folder:"
+  ].join(" ");
+  if (explicit) {
+    if (explicit === folder)
+      return;
+    return `Write any planning or research content you create during this session (markdown, html files etc) to ${explicit}`;
+  }
+  if (managed.status === "registered") {
+    return [`${message} ${managed.notesDirectory}.`, ...managedRules].join(" ");
+  }
+  if (managed.status === "unregistered") {
+    return [
+      `${message} the notesDirectory returned by \`kennel notes path ${shellQuote(folder)} --json\`. Run this command before the first such write.`,
+      ...managedRules
+    ].join(" ");
+  }
+  return;
+}
+
 // packages/llm/src/index.ts
 var MAX_CONTEXT_BYTES = 1024 * 1024;
 function realDirectory(folder) {
@@ -760,12 +1015,20 @@ async function buildLlmContext(options) {
   signal.throwIfAborted();
   const folder = realDirectory(options.folder);
   const settings = includeInstructions ? readInstructionSettings() : undefined;
+  const managed = settings || depth !== undefined ? await managedNotesState(folder) : undefined;
   const agents = settings || depth !== undefined ? await buildAgentContext({
     folder,
     instructionBytes: settings?.maxBytes,
-    signal
+    signal,
+    localOnly: managed?.status === "base",
+    instructionSources: managed?.status === "registered" ? [managed.notesDirectory] : []
   }) : { blocks: [], linkedFolders: [] };
-  let blocks = agents.blocks;
+  const routing = settings && managed ? routingInstruction({
+    explicit: agents.destination,
+    folder,
+    managed
+  }) : undefined;
+  let blocks = [...agents.blocks, ...routing ? [routing] : []];
   let pluginBlock;
   if (depth !== undefined) {
     await Promise.resolve().then(() => init_context());
@@ -773,16 +1036,18 @@ async function buildLlmContext(options) {
     const core = await buildCoreContext({
       folder,
       depth,
-      signal
+      signal,
+      localOnly: managed?.status === "base"
     });
     const contributions = await runContributors(options.plugins ?? [], {
       folder,
       linkedFolders: [
         ...new Set([...agents.linkedFolders, ...core.linkedFolders])
       ],
+      managedFolders: managed?.status === "registered" ? [managed.notesDirectory] : [],
       signal
     });
-    blocks = [...agents.blocks, ...core.blocks];
+    blocks = [...blocks, ...core.blocks];
     pluginBlock = pluginContextBlock(contributions);
   }
   const personal = settings ? readPersonalInstructions(folder, settings, profile) : undefined;

package/dist/notes/command.d.ts

@@ -0,0 +1 @@
+export declare function notes(args: string[]): Promise<void>;