kennel 0.2.0 → 0.2.2

package/kernel/packages/agents/src/node.ts

@@ -0,0 +1,447 @@
+import { lstat, readFile, realpath, stat } from "node:fs/promises"
+import { homedir } from "node:os"
+import { basename, dirname, resolve } from "node:path"
+
+import type { ClientProfile } from "./profiles.ts"
+import type {
+  AgentChainEntry,
+  AgentClientId,
+  AgentSource,
+  AgentsResolution,
+  AgentWarning,
+  ClientFilter,
+  SourceLevel,
+} from "./types.ts"
+import { CLIENT_ORDER, PROFILES } from "./profiles.ts"
+import { dedupeSources, sortSources } from "./resolve.ts"
+
+export type ResolveAgentsOptions = {
+  folder: string
+  client?: ClientFilter
+  /** Home directory used to expand `~` global paths. Defaults to the OS home. */
+  homeDir?: string
+  /** Skip reading file content, used for the navigation source count. */
+  readText?: boolean
+  /**
+   * Folders connected to the working folder by repository links, resolved by
+   * the host. Each linked folder's instruction files are inventoried as an
+   * explicit `linked` row (never claimed as loaded by any client).
+   */
+  linkedFolders?: string[]
+}
+
+type BuildSourceInput = {
+  clientId: AgentClientId
+  filename: string
+  level: SourceLevel
+  literalPath: string
+  override: boolean
+  readText: boolean
+}
+
+type Candidate = {
+  filename: string
+  relative: string
+}
+
+async function canonicalize(path: string): Promise<string | null> {
+  try {
+    return await realpath(path)
+  } catch {
+    return null
+  }
+}
+
+async function hasGit(folder: string): Promise<boolean> {
+  const entry = await lstat(resolve(folder, ".git")).catch(() => undefined)
+  return Boolean(entry)
+}
+
+async function nearestGitRoot(folder: string): Promise<string | null> {
+  let current = folder
+  while (true) {
+    if (await hasGit(current)) return current
+    const parent = dirname(current)
+    if (parent === current) return null
+    current = parent
+  }
+}
+
+/**
+ * Nearest ancestor carrying a `raggle.json` workspace marker. Raggle
+ * workspaces are the project boundary for this preview: the ancestor walk
+ * stops there, so a folder inside a workspace only ever shows instructions
+ * within that workspace (plus its global sources).
+ */
+async function nearestRaggleRoot(folder: string): Promise<string | null> {
+  let current = folder
+  while (true) {
+    const entry = await lstat(resolve(current, "raggle.json")).catch(
+      () => undefined,
+    )
+    if (entry) return current
+    const parent = dirname(current)
+    if (parent === current) return null
+    current = parent
+  }
+}
+
+/**
+ * Resolve the ancestor boundary for one client. `git` stops at the nearest
+ * `.git` root. `root` walks to the filesystem root, like Stepladder and the
+ * Pi and Claude Code context loaders. Only exact instruction filenames are
+ * read at each ancestor, so the wide root walk never reads arbitrary content.
+ */
+async function ancestorBoundary(
+  folder: string,
+  scope: ClientProfile["scope"],
+): Promise<string> {
+  let current = folder
+  while (true) {
+    if (scope === "git" && (await hasGit(current))) return current
+    const parent = dirname(current)
+    if (parent === current) return current
+    current = parent
+  }
+}
+
+function ancestorChain(folder: string, boundary: string): string[] {
+  const chain: string[] = []
+  let current = folder
+  while (true) {
+    chain.push(current)
+    if (current === boundary) break
+    const parent = dirname(current)
+    if (parent === current) break
+    current = parent
+  }
+  return chain
+}
+
+function sourceLevel(
+  index: number,
+  total: number,
+  scope: ClientProfile["scope"],
+): SourceLevel {
+  if (total === 1) return "project"
+  if (index === 0) return "project"
+  if (scope === "git" && index === total - 1) return "repository"
+  return "parent"
+}
+
+async function isRegularFile(path: string): Promise<boolean> {
+  const details = await stat(path).catch(() => undefined)
+  return details?.isFile() === true
+}
+
+/**
+ * Merge the ancestor walks of every profile into one ordered chain. The
+ * working folder stays first; deeper duplicates keep the filenames found by
+ * each client. Used for the `all` filter — a single client passes one chain
+ * straight through.
+ */
+function mergeChains(chains: AgentChainEntry[][]): AgentChainEntry[] {
+  const byDirectory = new Map<string, AgentChainEntry>()
+  const order: string[] = []
+  for (const chain of chains) {
+    for (const entry of chain) {
+      const existing = byDirectory.get(entry.directory)
+      if (!existing) {
+        byDirectory.set(entry.directory, {
+          ...entry,
+          filenames: [...entry.filenames],
+        })
+        order.push(entry.directory)
+      } else {
+        for (const filename of entry.filenames) {
+          if (!existing.filenames.includes(filename)) {
+            existing.filenames.push(filename)
+          }
+        }
+      }
+    }
+  }
+  return order.map((directory) => byDirectory.get(directory)!)
+}
+
+async function selectFiles(
+  directory: string,
+  candidates: string[],
+  mode: ClientProfile["filesMode"],
+): Promise<Candidate[]> {
+  if (mode === "all") {
+    const found: Candidate[] = []
+    for (const relative of candidates) {
+      if (await isRegularFile(resolve(directory, relative))) {
+        found.push({ filename: basename(relative), relative })
+      }
+    }
+    return found
+  }
+  for (const relative of candidates) {
+    if (await isRegularFile(resolve(directory, relative))) {
+      return [{ filename: basename(relative), relative }]
+    }
+  }
+  return []
+}
+
+function expandHome(path: string, homeDir: string): string {
+  if (path === "~") return homeDir
+  if (path.startsWith("~/")) return resolve(homeDir, path.slice(2))
+  return path
+}
+
+function globalDirectory(
+  profile: ClientProfile,
+  homeDir: string,
+): string | null {
+  if (profile.globalDir === null) return null
+  const envValue = profile.globalEnv
+    ? process.env[profile.globalEnv]?.trim()
+    : undefined
+  if (envValue) return expandHome(envValue, homeDir)
+  if (profile.globalDir === "") return homeDir
+  return resolve(homeDir, profile.globalDir)
+}
+
+function readError(error: unknown): string {
+  return error instanceof Error ? error.message : "Could not read file"
+}
+
+const INSTRUCTION_NAMES = new Set(
+  Object.values(PROFILES)
+    .flatMap((profile) => [...profile.files, ...profile.globalFiles])
+    .map((path) => basename(path).toLowerCase()),
+)
+
+async function codexModelInstructionsFile(
+  codexHome: string,
+): Promise<string | null> {
+  try {
+    const content = await readFile(resolve(codexHome, "config.toml"), "utf8")
+    const match =
+      /^\s*model_instructions_file\s*=\s*["']?([^"'\n]+)["']?\s*$/m.exec(
+        content,
+      )
+    return match?.[1]?.trim() ?? null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Realpath, authorize, and read one instruction file. The file is only read,
+ * never executed. A regular file check rejects directories and special files
+ * that a symlink could otherwise point at. Content is read in full.
+ */
+async function loadSource(input: BuildSourceInput): Promise<AgentSource> {
+  const real = await canonicalize(input.literalPath)
+  if (!real) {
+    return {
+      id: input.literalPath,
+      path: input.literalPath,
+      sourcePaths: [input.literalPath],
+      filename: input.filename,
+      directory: dirname(input.literalPath),
+      level: input.level,
+      status: "unreadable",
+      text: "",
+      size: 0,
+      clientIds: [input.clientId],
+      override: input.override,
+      applies: true,
+      reason: "Path cannot be resolved",
+    }
+  }
+
+  const record: AgentSource = {
+    id: real,
+    path: real,
+    sourcePaths: [input.literalPath],
+    filename: input.filename,
+    directory: dirname(real),
+    level: input.level,
+    status: "loaded",
+    text: "",
+    size: 0,
+    clientIds: [input.clientId],
+    override: input.override,
+    applies: true,
+  }
+
+  // A symlink may point anywhere; the resolved target must still be an
+  // instruction file, never an arbitrary non-instruction file like a secret.
+  if (!INSTRUCTION_NAMES.has(basename(real).toLowerCase())) {
+    record.status = "unsafe"
+    record.reason = "Symlink resolves to a non-instruction file"
+    return record
+  }
+
+  const details = await stat(real).catch(() => undefined)
+  if (!details?.isFile()) {
+    record.status = "unreadable"
+    record.reason = "Not a regular file"
+    return record
+  }
+  record.size = details.size
+
+  if (input.readText) {
+    try {
+      record.text = await readFile(real, "utf8")
+    } catch (error) {
+      record.status = "unreadable"
+      record.reason = readError(error)
+    }
+  }
+
+  return record
+}
+
+/**
+ * Resolve every instruction source that applies to a working folder for one
+ * client filter. The result is read-only and ordered project → parents →
+ * global. Child and sibling folders are never scanned. Each client uses its
+ * own documented ancestor boundary.
+ */
+export async function resolveAgents(
+  options: ResolveAgentsOptions,
+): Promise<AgentsResolution> {
+  const homeDir = options.homeDir ?? homedir()
+  const client = options.client ?? "all"
+  const readText = options.readText ?? true
+
+  const folder = await canonicalize(options.folder)
+  if (!folder) throw new Error(`Folder not found: ${options.folder}`)
+
+  const repositoryRoot = await nearestGitRoot(folder)
+  const workspaceRoot = await nearestRaggleRoot(folder)
+  const profileIds: AgentClientId[] = client === "all" ? CLIENT_ORDER : [client]
+
+  const sources: AgentSource[] = []
+  const warnings: AgentWarning[] = []
+  const profileChains: AgentChainEntry[][] = []
+
+  for (const profileId of profileIds) {
+    const profile = PROFILES[profileId]
+    // A Raggle workspace root caps the walk for every client; without one,
+    // each client falls back to its own documented ancestor boundary.
+    const boundary =
+      workspaceRoot ?? (await ancestorBoundary(folder, profile.scope))
+    const ancestors = ancestorChain(folder, boundary)
+    const chain: AgentChainEntry[] = []
+
+    for (let index = 0; index < ancestors.length; index += 1) {
+      const directory = ancestors[index]
+      if (!directory) continue
+      const level = sourceLevel(index, ancestors.length, profile.scope)
+      const files = await selectFiles(
+        directory,
+        profile.files,
+        profile.filesMode,
+      )
+      chain.push({
+        directory,
+        level,
+        filenames: files.map((file) => file.filename),
+      })
+      for (const file of files) {
+        const source = await loadSource({
+          clientId: profileId,
+          filename: file.filename,
+          level,
+          literalPath: resolve(directory, file.relative),
+          override: file.filename === "AGENTS.override.md",
+          readText,
+        })
+        sources.push(source)
+      }
+    }
+
+    profileChains.push(chain)
+
+    // Linked project folders (the host's connected-notes relation graph)
+    // contribute their root instruction files as an explicit inventory row.
+    // Real clients do not load these automatically — the row is labelled
+    // `linked` so the preview never claims a client applies them.
+    for (const linkedFolder of options.linkedFolders ?? []) {
+      const canonicalLinked = await canonicalize(linkedFolder)
+      if (!canonicalLinked || canonicalLinked === folder) continue
+      const linkedFiles = await selectFiles(
+        canonicalLinked,
+        profile.files,
+        profile.filesMode,
+      )
+      chain.push({
+        directory: canonicalLinked,
+        level: "linked",
+        filenames: linkedFiles.map((file) => file.filename),
+      })
+      for (const file of linkedFiles) {
+        const source = await loadSource({
+          clientId: profileId,
+          filename: file.filename,
+          level: "linked",
+          literalPath: resolve(canonicalLinked, file.relative),
+          override: file.filename === "AGENTS.override.md",
+          readText,
+        })
+        sources.push(source)
+      }
+    }
+
+    const globalDir = globalDirectory(profile, homeDir)
+    if (globalDir) {
+      const globals = await selectFiles(
+        globalDir,
+        profile.globalFiles,
+        profile.globalMode,
+      )
+      for (const file of globals) {
+        const source = await loadSource({
+          clientId: profileId,
+          filename: file.filename,
+          level: "global",
+          literalPath: resolve(globalDir, file.relative),
+          override: file.filename === "AGENTS.override.md",
+          readText,
+        })
+        sources.push(source)
+      }
+      if (globals.length === 0 && profile.globalFiles.length > 0) {
+        warnings.push({
+          kind: "missing",
+          path: globalDir,
+          clientIds: [profileId],
+          reason: "No global instruction file found in this directory",
+        })
+      }
+    }
+
+    if (profileId === "codex") {
+      const codexHome = globalDirectory(profile, homeDir)
+      if (codexHome) {
+        const fallback = await codexModelInstructionsFile(codexHome)
+        if (fallback) {
+          warnings.push({
+            kind: "unsupported",
+            clientIds: [profileId],
+            reason: `Codex model_instructions_file (${fallback}) is configured but not applied here`,
+          })
+        }
+      }
+    }
+  }
+
+  const deduped = dedupeSources(sources)
+  const ordered = sortSources(deduped)
+
+  return {
+    folder,
+    repositoryRoot,
+    client,
+    sources: ordered,
+    warnings,
+    chain: mergeChains(profileChains),
+  }
+}

package/kernel/packages/agents/src/profiles.ts

@@ -0,0 +1,137 @@
+import type { AgentClientId, ClientFilter } from "./types.ts"
+
+export type ClientProfile = {
+  id: AgentClientId
+  label: string
+  /** Ancestor walk scope: `git` stops at the nearest repository root, `root` walks to the filesystem root. */
+  scope: "root" | "git"
+  /**
+   * Candidate instruction files checked in each ancestor directory, in order.
+   * A relative path may include a subdirectory, e.g. `.claude/CLAUDE.md`.
+   */
+  files: string[]
+  /** `first` loads only the first existing candidate; `all` loads every candidate as a separate source. */
+  filesMode: "first" | "all"
+  /** Global directory relative to home, or `""` for home itself. `null` disables a global source. */
+  globalDir: string | null
+  /** Environment variable that replaces the whole global directory when set. */
+  globalEnv?: string
+  /** Candidate instruction files checked inside the global directory. */
+  globalFiles: string[]
+  /** Same mode as `filesMode`, applied to the global directory. */
+  globalMode: "first" | "all"
+  /** True when discovery rules were verified against client documentation or source. */
+  verified: boolean
+  /** What was verified and where the rules come from. */
+  note: string
+  /** Explicit limits of this preview that are not part of the real client prompt. */
+  limits: string
+}
+
+export const CLIENT_ORDER: AgentClientId[] = [
+  "generic",
+  "codex",
+  "claude",
+  "pi",
+]
+
+export const PROFILES: Record<AgentClientId, ClientProfile> = {
+  generic: {
+    id: "generic",
+    label: "Generic",
+    scope: "root",
+    files: ["AGENTS.md"],
+    filesMode: "first",
+    globalDir: ".agents",
+    globalFiles: ["AGENTS.md"],
+    globalMode: "first",
+    verified: false,
+    note: "Reference view of the ancestor AGENTS.md chain. No client execution behavior is claimed.",
+    limits:
+      "Walks to the filesystem root like Stepladder; only AGENTS.md files are read.",
+  },
+  codex: {
+    id: "codex",
+    label: "Codex",
+    scope: "git",
+    files: ["AGENTS.override.md", "AGENTS.md"],
+    filesMode: "first",
+    globalDir: ".codex",
+    globalEnv: "CODEX_HOME",
+    globalFiles: ["AGENTS.override.md", "AGENTS.md"],
+    globalMode: "first",
+    verified: true,
+    note: "Verified from the Codex 0.154.0 binary: reads the repository root plus every directory from the CWD up to the root, and prefers AGENTS.override.md over AGENTS.md per directory.",
+    limits:
+      "A configured model_instructions_file fallback is not applied here; a warning appears when it is configured.",
+  },
+  claude: {
+    id: "claude",
+    label: "Claude Code",
+    scope: "root",
+    files: ["CLAUDE.md", ".claude/CLAUDE.md", "CLAUDE.local.md"],
+    filesMode: "all",
+    globalDir: ".claude",
+    globalFiles: ["CLAUDE.md"],
+    globalMode: "first",
+    verified: true,
+    note: "Verified from the Claude Code 2.1.274 binary: loads ~/.claude/CLAUDE.md and, walking to the filesystem root, each ancestor's CLAUDE.md, .claude/CLAUDE.md, and CLAUDE.local.md.",
+    limits:
+      "Conditional .claude/rules/*.md files and @path imports are not expanded here.",
+  },
+  pi: {
+    id: "pi",
+    label: "Pi",
+    scope: "root",
+    files: [
+      "AGENTS.override.md",
+      "AGENTS.md",
+      "AGENTS.MD",
+      "CLAUDE.md",
+      "CLAUDE.MD",
+    ],
+    filesMode: "first",
+    globalDir: ".pi/agent",
+    globalEnv: "PI_CODING_AGENT_DIR",
+    globalFiles: [
+      "AGENTS.override.md",
+      "AGENTS.md",
+      "AGENTS.MD",
+      "CLAUDE.md",
+      "CLAUDE.MD",
+    ],
+    globalMode: "first",
+    verified: true,
+    note: "Verified from the Pi 0.85.1 source (resource-loader.js): first match wins from AGENTS.override.md, AGENTS.md, AGENTS.MD, CLAUDE.md, CLAUDE.MD, in each ancestor directory and in the global directory.",
+    limits: "Uses the same candidate list for the global directory.",
+  },
+}
+
+export const FILTERS: Array<{ id: ClientFilter; label: string }> = [
+  { id: "generic", label: "Generic" },
+  { id: "codex", label: "Codex" },
+  { id: "claude", label: "Claude Code" },
+  { id: "pi", label: "Pi" },
+]
+
+export function clientLabel(id: AgentClientId) {
+  return PROFILES[id].label
+}
+
+/**
+ * Resolves the plugin-relative subpath to a single client. Pi is the default
+ * client; unknown values (including the legacy `all` mode) fall back to it.
+ */
+export function parseClientFilter(
+  value: string | null | undefined,
+): AgentClientId {
+  if (
+    value === "generic" ||
+    value === "codex" ||
+    value === "claude" ||
+    value === "pi"
+  ) {
+    return value
+  }
+  return "pi"
+}

package/kernel/packages/agents/src/resolve.ts

@@ -0,0 +1,69 @@
+import type { AgentSource, SourceLevel } from "./types.ts"
+
+export const LEVEL_ORDER: Record<SourceLevel, number> = {
+  project: 0,
+  parent: 1,
+  repository: 2,
+  linked: 3,
+  global: 4,
+}
+
+function unique<T>(values: T[]): T[] {
+  return [...new Set(values)]
+}
+
+function pathSegments(path: string): number {
+  const normalized = path.replaceAll("\\", "/").replace(/\/+$/, "")
+  if (!normalized) return 0
+  return normalized.split("/").length
+}
+
+/**
+ * Merge sources that point at the same physical file. The first occurrence
+ * keeps its position and status; later occurrences contribute their client ids
+ * and literal source paths, so a shared instruction file is shown once and
+ * labelled with every client that loads it.
+ */
+export function dedupeSources(sources: AgentSource[]): AgentSource[] {
+  const merged = new Map<string, AgentSource>()
+  for (const source of sources) {
+    const existing = merged.get(source.id)
+    if (!existing) {
+      merged.set(source.id, {
+        ...source,
+        clientIds: [...source.clientIds],
+        sourcePaths: unique([...source.sourcePaths]),
+      })
+      continue
+    }
+    existing.clientIds = unique([...existing.clientIds, ...source.clientIds])
+    existing.sourcePaths = unique([
+      ...existing.sourcePaths,
+      ...source.sourcePaths,
+    ])
+    if (existing.status !== "loaded" && source.status === "loaded") {
+      existing.status = source.status
+      existing.text = source.text
+      existing.size = source.size
+      existing.reason = source.reason
+    }
+    if (source.override) existing.override = true
+  }
+  return [...merged.values()]
+}
+
+/**
+ * Order sources project → parents → repository → global. Deeper directories
+ * come before shallower ones within the ancestor levels, then the file name
+ * breaks any remaining tie. This display order never changes a client's own
+ * loading order.
+ */
+export function sortSources(sources: AgentSource[]): AgentSource[] {
+  return [...sources].sort((left, right) => {
+    const level = LEVEL_ORDER[left.level] - LEVEL_ORDER[right.level]
+    if (level !== 0) return level
+    const depth = pathSegments(right.directory) - pathSegments(left.directory)
+    if (depth !== 0) return depth
+    return left.filename.localeCompare(right.filename)
+  })
+}

package/kernel/packages/agents/src/server.ts

@@ -0,0 +1,60 @@
+import type {
+  FolderPluginContext,
+  FolderPluginData,
+  FolderPluginDetection,
+} from "@raggle-ai/folder-plugin/server"
+
+import type { AgentsResolution, ClientFilter } from "./types.ts"
+import { agentsManifest } from "./manifest.ts"
+import { resolveAgents } from "./node.ts"
+import { parseClientFilter } from "./profiles.ts"
+
+export type AgentsCreatePluginOptions = {
+  /** Home directory used to expand `~` global paths. Intended for tests. */
+  homeDir?: string
+}
+
+export function createAgentsPlugin(options: AgentsCreatePluginOptions = {}) {
+  return {
+    ...agentsManifest,
+    async detect(context: FolderPluginContext): Promise<FolderPluginDetection> {
+      try {
+        const result: AgentsResolution = await resolveAgents({
+          folder: context.folder,
+          client: "all",
+          homeDir: options.homeDir,
+          linkedFolders: context.linkedFolders,
+          readText: false,
+        })
+        return { count: result.sources.length, status: "available" }
+      } catch {
+        // The Agents item is always available, even when discovery fails.
+        return { status: "available" }
+      }
+    },
+    async handle(
+      context: FolderPluginContext,
+      subpath: string,
+    ): Promise<FolderPluginData> {
+      const client: ClientFilter = parseClientFilter(subpath.trim() || null)
+      const result: AgentsResolution = await resolveAgents({
+        folder: context.folder,
+        client,
+        homeDir: options.homeDir,
+        linkedFolders: context.linkedFolders,
+      })
+      return {
+        kind: "available",
+        data: {
+          client,
+          folder: result.folder,
+          repositoryRoot: result.repositoryRoot,
+          sources: result.sources,
+          status: "available",
+          warnings: result.warnings,
+          chain: result.chain,
+        },
+      }
+    },
+  }
+}