kennel 0.2.12 → 0.2.13

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

@@ -1,447 +0,0 @@
-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

@@ -1,137 +0,0 @@
-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

@@ -1,69 +0,0 @@
-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

@@ -1,60 +0,0 @@
-import type {
-  FolderPluginContext,
-  FolderPluginData,
-  FolderPluginDetection,
-} from "kennel-plugins/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,
-        },
-      }
-    },
-  }
-}