agents.yaml 0.1.0 → 0.2.1

package/src/discover.test.ts

@@ -1,71 +1,153 @@
-import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import path from 'node:path'
-import { afterEach, describe, expect, it } from 'vitest'
-import { addDocuments, loadAgentsFile } from './agents-file.ts'
-import { discoverAgentDocuments } from './discover.ts'
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import path from "node:path"
+import { afterEach, describe, expect, it } from "vitest"
+import { addDocuments, loadAgentsFile } from "./agents-file.ts"
+import { discoverAgentDocuments } from "./discover.ts"
 
 const tempRoots: string[] = []
 
-describe('agents.yaml dependency discovery', () => {
-  afterEach(async () => {
-    await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })))
-  })
+describe("agents.yaml dependency discovery", () => {
+	afterEach(async () => {
+		await Promise.all(
+			tempRoots
+				.splice(0)
+				.map((root) => rm(root, { recursive: true, force: true })),
+		)
+	})
 
-  it('discovers a direct dependency with an AGENTS.md and adds it to agents.yaml', async () => {
-    const root = await createTempProject()
-    const dependencyAgentsPath = path.join(root, 'node_modules', 'direct-lib', 'AGENTS.md')
-    await mkdir(path.dirname(dependencyAgentsPath), { recursive: true })
-    await writeFile(dependencyAgentsPath, '# Direct dependency guidance\n', 'utf8')
+	it("discovers a direct dependency with an AGENTS.md and adds it to agents.yaml", async () => {
+		const root = await createTempProject()
+		const dependencyAgentsPath = path.join(
+			root,
+			"node_modules",
+			"direct-lib",
+			"AGENTS.md",
+		)
+		await mkdir(path.dirname(dependencyAgentsPath), { recursive: true })
+		await writeFile(
+			dependencyAgentsPath,
+			"# Direct dependency guidance\n",
+			"utf8",
+		)
+		await writeFile(
+			path.join(root, "node_modules", "direct-lib", "package.json"),
+			JSON.stringify({
+				name: "direct-lib",
+				description: "Direct fixtures for testing agent guidance.",
+			}),
+			"utf8",
+		)
 
-    const discovered = await discoverAgentDocuments(root)
-    expect(discovered).toEqual([{ path: './node_modules/direct-lib/AGENTS.md' }])
+		const discovered = await discoverAgentDocuments(root)
+		expect(discovered).toEqual([
+			{
+				path: "./node_modules/direct-lib/AGENTS.md",
+				description: "Direct fixtures for testing agent guidance.",
+			},
+		])
 
-    await addDocuments(root, [
-      {
-        path: discovered[0]!.path,
-      },
-    ])
+		await addDocuments(root, [discovered[0]!])
 
-    await expect(loadAgentsFile(root)).resolves.toEqual({
-      version: 1,
-      documents: [
-        {
-          path: './node_modules/direct-lib/AGENTS.md',
-        },
-      ],
-    })
-  })
+		await expect(loadAgentsFile(root)).resolves.toEqual({
+			version: 1,
+			documents: [
+				{
+					path: "./node_modules/direct-lib/AGENTS.md",
+					description: "Direct fixtures for testing agent guidance.",
+				},
+			],
+		})
 
-  it('does not discover an indirect dependency that has an AGENTS.md', async () => {
-    const root = await createTempProject()
-    const directAgentsPath = path.join(root, 'node_modules', 'direct-lib', 'AGENTS.md')
-    const indirectAgentsPath = path.join(
-      root,
-      'node_modules',
-      'direct-lib',
-      'node_modules',
-      'indirect-lib',
-      'AGENTS.md',
-    )
+		await addDocuments(root, [{ path: "./node_modules/direct-lib/AGENTS.md" }])
+		await expect(loadAgentsFile(root)).resolves.toEqual({
+			version: 1,
+			documents: [
+				{
+					path: "./node_modules/direct-lib/AGENTS.md",
+					description: "Direct fixtures for testing agent guidance.",
+				},
+			],
+		})
+	})
 
-    await mkdir(path.dirname(directAgentsPath), { recursive: true })
-    await mkdir(path.dirname(indirectAgentsPath), { recursive: true })
-    await writeFile(directAgentsPath, '# Direct dependency guidance\n', 'utf8')
-    await writeFile(indirectAgentsPath, '# Indirect dependency guidance\n', 'utf8')
+	it("does not discover an indirect dependency that has an AGENTS.md", async () => {
+		const root = await createTempProject()
+		const directAgentsPath = path.join(
+			root,
+			"node_modules",
+			"direct-lib",
+			"AGENTS.md",
+		)
+		const indirectAgentsPath = path.join(
+			root,
+			"node_modules",
+			"direct-lib",
+			"node_modules",
+			"indirect-lib",
+			"AGENTS.md",
+		)
 
-    await expect(discoverAgentDocuments(root)).resolves.toEqual([
-      { path: './node_modules/direct-lib/AGENTS.md' },
-    ])
-  })
+		await mkdir(path.dirname(directAgentsPath), { recursive: true })
+		await mkdir(path.dirname(indirectAgentsPath), { recursive: true })
+		await writeFile(directAgentsPath, "# Direct dependency guidance\n", "utf8")
+		await writeFile(
+			indirectAgentsPath,
+			"# Indirect dependency guidance\n",
+			"utf8",
+		)
+
+		await expect(discoverAgentDocuments(root)).resolves.toEqual([
+			{ path: "./node_modules/direct-lib/AGENTS.md" },
+		])
+	})
+
+	it("includes scoped package descriptions when present", async () => {
+		const root = await createTempProject()
+		const dependencyPath = path.join(
+			root,
+			"node_modules",
+			"@scope",
+			"direct-lib",
+		)
+		await mkdir(dependencyPath, { recursive: true })
+		await writeFile(
+			path.join(dependencyPath, "AGENTS.md"),
+			"# Scoped guidance\n",
+			"utf8",
+		)
+		await writeFile(
+			path.join(dependencyPath, "package.json"),
+			JSON.stringify({
+				name: "@scope/direct-lib",
+				description: "Scoped package guidance breadcrumbs.",
+			}),
+			"utf8",
+		)
+
+		await expect(discoverAgentDocuments(root)).resolves.toEqual([
+			{
+				path: "./node_modules/@scope/direct-lib/AGENTS.md",
+				description: "Scoped package guidance breadcrumbs.",
+			},
+		])
+	})
 })
 
 async function createTempProject(): Promise<string> {
-  const root = await mkdtemp(path.join(tmpdir(), 'agents-yaml-'))
-  tempRoots.push(root)
+	const root = await mkdtemp(path.join(tmpdir(), "agents-yaml-"))
+	tempRoots.push(root)
 
-  await writeFile(path.join(root, 'agents.yaml'), 'version: 1\n\ndocuments: []\n', 'utf8')
-  await writeFile(path.join(root, 'AGENTS.md'), 'Consult ./agents.yaml.\n', 'utf8')
+	await writeFile(
+		path.join(root, "agents.yaml"),
+		"version: 1\n\ndocuments: []\n",
+		"utf8",
+	)
+	await writeFile(
+		path.join(root, "AGENTS.md"),
+		"Consult ./agents.yaml.\n",
+		"utf8",
+	)
 
-  return root
+	return root
 }

package/src/discover.ts

@@ -1,115 +1,187 @@
-import { access, opendir } from 'node:fs/promises'
-import path from 'node:path'
-import { formatProjectPath } from './paths.ts'
+import { access, opendir, readFile } from "node:fs/promises"
+import path from "node:path"
+import { formatProjectPath, resolveFromRoot } from "./paths.ts"
 
 export type DiscoveredDocument = {
-  path: string
+	path: string
+	description?: string
 }
 
 const skippedDirectories = new Set([
-  '.git',
-  '.hg',
-  '.svn',
-  '.turbo',
-  '.next',
-  'coverage',
-  'dist',
-  'build',
+	".git",
+	".hg",
+	".svn",
+	".turbo",
+	".next",
+	"coverage",
+	"dist",
+	"build",
 ])
 
-export async function discoverAgentDocuments(root: string): Promise<DiscoveredDocument[]> {
-  const found: DiscoveredDocument[] = []
-  await walk(root, root, found)
-  return found
-    .filter((document) => document.path !== './AGENTS.md')
-    .sort((left, right) => left.path.localeCompare(right.path))
+export async function discoverAgentDocuments(
+	root: string,
+): Promise<DiscoveredDocument[]> {
+	const found: DiscoveredDocument[] = []
+	await walk(root, root, found)
+	return found
+		.filter((document) => document.path !== "./AGENTS.md")
+		.sort((left, right) => left.path.localeCompare(right.path))
 }
 
-async function walk(root: string, directory: string, found: DiscoveredDocument[]): Promise<void> {
-  let handle
-  try {
-    handle = await opendir(directory)
-  } catch {
-    return
-  }
-
-  for await (const entry of handle) {
-    const absolutePath = path.join(directory, entry.name)
-
-    if (entry.isDirectory()) {
-      if (entry.name === 'node_modules') {
-        await scanDirectNodeModules(root, absolutePath, found)
-        continue
-      }
-
-      if (!skippedDirectories.has(entry.name)) {
-        await walk(root, absolutePath, found)
-      }
-      continue
-    }
-
-    if (entry.isFile() && entry.name === 'AGENTS.md') {
-      found.push({ path: formatProjectPath(root, absolutePath) })
-    }
-  }
+export async function describeAgentDocument(
+	root: string,
+	agentsDocumentPath: string,
+): Promise<DiscoveredDocument> {
+	const absolutePath = resolveFromRoot(root, agentsDocumentPath)
+	return documentEntry(
+		root,
+		absolutePath,
+		await readPackageDescription(path.dirname(absolutePath)),
+	)
+}
+
+async function walk(
+	root: string,
+	directory: string,
+	found: DiscoveredDocument[],
+): Promise<void> {
+	let handle
+	try {
+		handle = await opendir(directory)
+	} catch {
+		return
+	}
+
+	for await (const entry of handle) {
+		const absolutePath = path.join(directory, entry.name)
+
+		if (entry.isDirectory()) {
+			if (entry.name === "node_modules") {
+				await scanDirectNodeModules(root, absolutePath, found)
+				continue
+			}
+
+			if (!skippedDirectories.has(entry.name)) {
+				await walk(root, absolutePath, found)
+			}
+			continue
+		}
+
+		if (entry.isFile() && entry.name === "AGENTS.md") {
+			found.push(
+				await documentEntry(
+					root,
+					absolutePath,
+					await readPackageDescription(path.dirname(absolutePath)),
+				),
+			)
+		}
+	}
 }
 
 async function scanDirectNodeModules(
-  root: string,
-  nodeModulesPath: string,
-  found: DiscoveredDocument[],
+	root: string,
+	nodeModulesPath: string,
+	found: DiscoveredDocument[],
 ): Promise<void> {
-  let handle
-  try {
-    handle = await opendir(nodeModulesPath)
-  } catch {
-    return
-  }
-
-  for await (const entry of handle) {
-    if ((!entry.isDirectory() && !entry.isSymbolicLink()) || entry.name.startsWith('.')) {
-      continue
-    }
-
-    const packagePath = path.join(nodeModulesPath, entry.name)
-    if (entry.name.startsWith('@')) {
-      await scanScopedPackages(root, packagePath, found)
-      continue
-    }
-
-    await addPackageAgentsDocument(root, packagePath, found)
-  }
+	let handle
+	try {
+		handle = await opendir(nodeModulesPath)
+	} catch {
+		return
+	}
+
+	for await (const entry of handle) {
+		if (
+			(!entry.isDirectory() && !entry.isSymbolicLink()) ||
+			entry.name.startsWith(".")
+		) {
+			continue
+		}
+
+		const packagePath = path.join(nodeModulesPath, entry.name)
+		if (entry.name.startsWith("@")) {
+			await scanScopedPackages(root, packagePath, found)
+			continue
+		}
+
+		await addPackageAgentsDocument(root, packagePath, found)
+	}
 }
 
 async function scanScopedPackages(
-  root: string,
-  scopePath: string,
-  found: DiscoveredDocument[],
+	root: string,
+	scopePath: string,
+	found: DiscoveredDocument[],
 ): Promise<void> {
-  let handle
-  try {
-    handle = await opendir(scopePath)
-  } catch {
-    return
-  }
-
-  for await (const entry of handle) {
-    if (entry.isDirectory() || entry.isSymbolicLink()) {
-      await addPackageAgentsDocument(root, path.join(scopePath, entry.name), found)
-    }
-  }
+	let handle
+	try {
+		handle = await opendir(scopePath)
+	} catch {
+		return
+	}
+
+	for await (const entry of handle) {
+		if (entry.isDirectory() || entry.isSymbolicLink()) {
+			await addPackageAgentsDocument(
+				root,
+				path.join(scopePath, entry.name),
+				found,
+			)
+		}
+	}
 }
 
 async function addPackageAgentsDocument(
-  root: string,
-  packagePath: string,
-  found: DiscoveredDocument[],
+	root: string,
+	packagePath: string,
+	found: DiscoveredDocument[],
 ): Promise<void> {
-  const agentsPath = path.join(packagePath, 'AGENTS.md')
-  try {
-    await access(agentsPath)
-    found.push({ path: formatProjectPath(root, agentsPath) })
-  } catch {
-    // Packages without AGENTS.md are simply not candidates.
-  }
+	const agentsPath = path.join(packagePath, "AGENTS.md")
+	try {
+		await access(agentsPath)
+		found.push(
+			await documentEntry(
+				root,
+				agentsPath,
+				await readPackageDescription(packagePath),
+			),
+		)
+	} catch {
+		// Packages without AGENTS.md are simply not candidates.
+	}
+}
+
+async function documentEntry(
+	root: string,
+	agentsPath: string,
+	description: string | undefined,
+): Promise<DiscoveredDocument> {
+	return {
+		path: formatProjectPath(root, agentsPath),
+		...(description ? { description } : {}),
+	}
+}
+
+async function readPackageDescription(
+	packagePath: string,
+): Promise<string | undefined> {
+	try {
+		const source = await readFile(
+			path.join(packagePath, "package.json"),
+			"utf8",
+		)
+		const parsed = JSON.parse(source) as unknown
+		if (!isPackageJson(parsed) || typeof parsed.description !== "string")
+			return undefined
+
+		const description = parsed.description.trim()
+		return description && description.length > 0 ? description : undefined
+	} catch {
+		return undefined
+	}
+}
+
+function isPackageJson(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null
 }

package/src/index.ts

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
-import { run } from './run.ts'
+import { run } from "./run.ts"
 
 run(process.argv.slice(2)).catch((error: unknown) => {
-  const message = error instanceof Error ? error.message : String(error)
-  console.error(`agents: ${message}`)
-  process.exitCode = 1
+	const message = error instanceof Error ? error.message : String(error)
+	console.error(`agents: ${message}`)
+	process.exitCode = 1
 })

package/src/paths.ts

@@ -1,18 +1,23 @@
-import path from 'node:path'
+import path from "node:path"
 
 export function cwd(): string {
-  return process.cwd()
+	return process.cwd()
 }
 
 export function resolveFromRoot(root: string, input: string): string {
-  return path.isAbsolute(input) ? path.normalize(input) : path.resolve(root, input)
+	return path.isAbsolute(input)
+		? path.normalize(input)
+		: path.resolve(root, input)
 }
 
 export function formatProjectPath(root: string, target: string): string {
-  const relative = path.relative(root, target).split(path.sep).join(path.posix.sep)
-  if (relative.startsWith('..')) {
-    return target
-  }
+	const relative = path
+		.relative(root, target)
+		.split(path.sep)
+		.join(path.posix.sep)
+	if (relative.startsWith("..")) {
+		return target
+	}
 
-  return relative.startsWith('.') ? relative : `./${relative}`
+	return relative.startsWith(".") ? relative : `./${relative}`
 }