@nuasite/agent-summary 0.0.3 → 0.0.6

package/README.md

@@ -1,15 +1,65 @@
-# astro-agent-summary
+# @nuasite/agent-summary
 
-To install dependencies:
+`@nuasite/agent-summary` is a tiny Astro integration that turns your built site into a machine-readable catalog (`AGENTS.md`) for agentic or LLM-driven tooling. During `astro build` it walks every generated HTML page, extracts lightweight metadata, captures redirects, and keeps several machine-friendly blocks in `AGENTS.md` up to date.
+
+## What it does
+- Discovers every concrete page emitted by Astro (skipping redirect-only routes).
+- Reads the built HTML, normalizes the title/description, and records prominent headings as contextual breadcrumbs.
+- Serializes each page (and redirect) into JSONL blocks bounded by dedicated `<page_summary*>` markers.
+- Creates `AGENTS.md` if it does not exist, or replaces only the generated blocks when they already exist.
+
+The resulting file can be fed directly into embeddings, vector stores, or custom command palettes so an agent always has a fresh summary of your documentation surface.
+
+## Installation
 
 ```bash
-bun install
+bun add -D @nuasite/agent-summary
+# or: npm install -D @nuasite/agent-summary
+```
+
+## Usage
+1. Ensure there is an `AGENTS.md` at the project root (the integration will create one if it is missing).
+2. Register the integration in your `astro.config.mjs`:
+
+```ts
+import { defineConfig } from 'astro/config'
+import { agentsSummary } from '@nuasite/agent-summary'
+
+export default defineConfig({
+	integrations: [
+		agentsSummary(),
+	],
+})
+```
+
+3. Run your normal build (`bun run astro build`, `npm run build`, etc.). When the build finishes you should see a log similar to:
+
 ```
+[agents-summary] Updated AGENTS.md with 42 page entries and 3 redirects.
+```
+
+### Generated blocks
+
+`updateAgentsSummary` writes (or updates) sections inside `AGENTS.md`. You can keep anything you like before/between/after them; only the content between `<page_summary>` marker pair is ever rewritten.
+
+JSONL excerpt:
+
+```
+<page_summary>
 
-To run:
+{"kind":"page","route":"/docs/getting-started","title":"Getting started","description":"Overview of the quickstart workflow.","headlines":[{"level":"h1","text":"Getting started"},{"level":"h2","text":"Install"}]}
+{"kind":"redirect","route":"/old-path","to":"/docs/getting-started","status":"302"}
+
+</page_summary>
+```
+
+## Development
+
+The package is written in TypeScript and tested with Bun:
 
 ```bash
-bun run src/index.ts
+bun install
+bun test packages/agent-summary/tests/cases/unit/utils.test.ts
 ```
 
-This project was created using `bun init` in bun v1.3.2. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.
+`src/agent-summary-integration.ts` contains the integration entry point, while `src/utils.ts` focuses on parsing HTML, detecting redirects, and keeping `AGENTS.md` synchronized.

package/package.json

@@ -3,11 +3,11 @@
 	"description": "Create simple summary of the project for LLM.",
 	"repository": {
 		"type": "git",
-		"url": "git+https://github.com/nuasite/nua.git",
+		"url": "git+https://github.com/nuasite/nuasite.git",
 		"directory": "packages/agent-summary"
 	},
 	"license": "Apache-2.0",
-	"version": "0.0.3",
+	"version": "0.0.6",
 	"module": "src/index.ts",
 	"types": "src/index.ts",
 	"type": "module",

package/{src → tests/cases/unit}/utils.test.ts

@@ -2,9 +2,9 @@ import { afterAll, afterEach, beforeAll, describe, expect, it } from 'bun:test'
 import { promises as fs } from 'node:fs'
 import path from 'node:path'
 import os from 'node:os'
-import type { PageMeta, RedirectMeta } from './types.ts'
+import type { PageMeta, RedirectMeta } from '../../../src/types.ts'
 
-const utilsModule = await import('./utils.ts')
+const utilsModule = await import('../../../src/utils.ts')
 const {
 	decodeEntities,
 	sanitize,
@@ -162,10 +162,19 @@ describe('updateAgentsSummary', () => {
 		}
 	})
 
+	const blockBody = (content: string, start: string, end: string): string => {
+		const startIndex = content.indexOf(start)
+		if (startIndex === -1) {
+			return ''
+		}
+		const bodyStart = startIndex + start.length + 2
+		const endIndex = content.indexOf(`\n${end}`, bodyStart)
+		const body = content.slice(bodyStart, endIndex >= 0 ? endIndex : bodyStart)
+		return body.trimEnd()
+	}
+
 	const summaryLines = (content: string): string[] => {
-		const bodyStart = content.indexOf(SUMMARY_START) + SUMMARY_START.length + 2
-		const bodyEnd = content.indexOf(`\n\n${SUMMARY_END}`)
-		const body = content.slice(bodyStart, bodyEnd >= 0 ? bodyEnd : bodyStart)
+		const body = blockBody(content, SUMMARY_START, SUMMARY_END)
 		return body.length === 0 ? [] : body.split('\n')
 	}
 
@@ -193,8 +202,7 @@ describe('updateAgentsSummary', () => {
 		await updateAgentsSummary(pages, redirects)
 
 		const content = await fs.readFile(AGENTS_PATH, 'utf8')
-		expect(content.startsWith(`${SUMMARY_START}\n\n`)).toBe(true)
-		expect(content.trimEnd().endsWith(`${SUMMARY_END}`)).toBe(true)
+		expect(content.includes(SUMMARY_START)).toBe(true)
 
 		const lines = summaryLines(content)
 		expect(lines).toEqual([
@@ -224,7 +232,7 @@ describe('updateAgentsSummary', () => {
 
 		const content = await fs.readFile(AGENTS_PATH, 'utf8')
 		expect(content.startsWith(prefix)).toBe(true)
-		expect(content.endsWith(suffix)).toBe(true)
+		expect(content).toContain(suffix)
 		const lines = summaryLines(content)
 		expect(lines).toEqual([
 			JSON.stringify({ kind: 'page', route: '/', title: 'Home', description: 'Home description', headlines: [] }),

package/tests/tsconfig.json

@@ -0,0 +1,10 @@
+{
+	"extends": "../../../tsconfig.settings.json",
+	"compilerOptions": {
+		"noEmit": true,
+		"emitDeclarationOnly": false
+	},
+	"references": [
+		{ "path": "../src" }
+	]
+}