@aeye/context 0.3.9 → 0.7.0

package/README.md

@@ -1,42 +1,42 @@
-# @aeye/context
-
-Pull **@aeye's agent context** — the flat agent-reference docs — into your repo with one command.
-
-Each `@aeye/*` package ships LLM/agent docs as flat markdown: an `aeye-<pkg>.md` reference (some
-packages add topic sub-docs like `aeye-core-tools.md`), cross-linked as flat siblings
-(`./aeye-core-types.md`). Those files ship inside each installed package
-(`node_modules/@aeye/core/aeye-core.md`, …). This CLI copies every installed package's doc into one
-flat folder and generates an `aeye.md` index, so the links actually resolve — on GitHub, in your
-editor, and when you point a coding agent at them.
-
-## Usage
-
-```bash
-npx @aeye/context             # → ./docs
-npx @aeye/context .aeye       # → any target directory
-```
-
-Run it from your project root (wherever `node_modules/` lives). Re-run after adding or upgrading
-`@aeye/*` packages to resync. To wire it into your project:
-
-```jsonc
-// package.json
-"scripts": { "context:sync": "aeye-context" }
-```
-
-## What it does
-
-1. Scans `node_modules/@aeye/*` (and pnpm's virtual store) for `aeye-*.md` files and copies each,
-   flat, into the target folder. Deduped by filename; direct dependencies win.
-2. Writes a generated **`aeye.md`** index — a table linking to every synced doc, labelled by each
-   file's title. (Unlike some monorepos, `@aeye` has no hand-written root router, so the index is
-   generated from whatever is installed — it never lists docs you don't have.)
-
-Only files are written — nothing is deleted from the target.
-
-## Options
-
-| Arg | Meaning |
-| --- | --- |
-| `[target-dir]` | Where to write the flat docs + index. Default: `docs`. |
-| `--help` | Show usage. |
+# @aeye/context
+
+Pull **@aeye's agent context** — the flat agent-reference docs — into your repo with one command.
+
+Each `@aeye/*` package ships LLM/agent docs as flat markdown: an `aeye-<pkg>.md` reference (some
+packages add topic sub-docs like `aeye-core-tools.md`), cross-linked as flat siblings
+(`./aeye-core-types.md`). Those files ship inside each installed package
+(`node_modules/@aeye/core/aeye-core.md`, …). This CLI copies every installed package's doc into one
+flat folder and generates an `aeye.md` index, so the links actually resolve — on GitHub, in your
+editor, and when you point a coding agent at them.
+
+## Usage
+
+```bash
+npx @aeye/context             # → ./docs
+npx @aeye/context .aeye       # → any target directory
+```
+
+Run it from your project root (wherever `node_modules/` lives). Re-run after adding or upgrading
+`@aeye/*` packages to resync. To wire it into your project:
+
+```jsonc
+// package.json
+"scripts": { "context:sync": "aeye-context" }
+```
+
+## What it does
+
+1. Scans `node_modules/@aeye/*` (and pnpm's virtual store) for `aeye-*.md` files and copies each,
+   flat, into the target folder. Deduped by filename; direct dependencies win.
+2. Writes a generated **`aeye.md`** index — a table linking to every synced doc, labelled by each
+   file's title. (Unlike some monorepos, `@aeye` has no hand-written root router, so the index is
+   generated from whatever is installed — it never lists docs you don't have.)
+
+Only files are written — nothing is deleted from the target.
+
+## Options
+
+| Arg | Meaning |
+| --- | --- |
+| `[target-dir]` | Where to write the flat docs + index. Default: `docs`. |
+| `--help` | Show usage. |

package/bin/aeye-context.mjs

@@ -1,116 +1,116 @@
-#!/usr/bin/env node
-/**
- * aeye-context — flatten the @aeye agent-reference docs into your repo.
- *
- * Each `@aeye/*` package ships flat `aeye-<pkg>.md` docs in its package root
- * (`node_modules/@aeye/<pkg>/aeye-<pkg>.md`), and those docs cross-link as flat siblings
- * (`./aeye-core-types.md`). This copies every installed package's doc(s) into one flat folder and
- * writes a generated `aeye.md` index, so the links resolve — on GitHub, in your editor, and when
- * handed to a coding agent.
- *
- *   npx @aeye/context               # → ./docs
- *   npx @aeye/context .aeye         # → any target directory
- *
- * Re-run after adding/upgrading @aeye packages to resync.
- */
-import { readdirSync, mkdirSync, copyFileSync, existsSync, readFileSync, writeFileSync, statSync } from 'node:fs';
-import { join } from 'node:path';
-
-const args = process.argv.slice(2);
-if (args.includes('--help') || args.includes('-h')) {
-  console.log(`Usage: aeye-context [target-dir]
-
-  target-dir   where to write the flat docs + generated index (default: docs)
-
-Scans node_modules for every installed @aeye/* package's aeye-*.md, copies them flat into
-<target-dir>, and writes an aeye.md index linking to them.`);
-  process.exit(0);
-}
-
-const target = args.find((a) => !a.startsWith('-')) ?? 'docs';
-const DOC_RE = /^aeye-.*\.md$/;
-
-/** Directories that may hold an installed @aeye package. Direct deps first (they win on dedup). */
-function scopeDirs() {
-  const dirs = [];
-  const scope = join('node_modules', '@aeye');
-  if (existsSync(scope)) {
-    for (const name of readdirSync(scope)) dirs.push(join(scope, name));
-  }
-  // pnpm keeps transitive deps only under the virtual store (harmless no-op on npm/yarn).
-  const store = join('node_modules', '.pnpm');
-  if (existsSync(store)) {
-    for (const entry of readdirSync(store)) {
-      const nested = join(store, entry, 'node_modules', '@aeye');
-      if (existsSync(nested)) {
-        for (const name of readdirSync(nested)) dirs.push(join(nested, name));
-      }
-    }
-  }
-  return dirs;
-}
-
-// Collect docs, deduped by filename (first occurrence — a direct dep — wins).
-const found = new Map(); // filename -> absolute source path
-for (const dir of scopeDirs()) {
-  let files;
-  try {
-    if (!statSync(dir).isDirectory()) continue;
-    files = readdirSync(dir);
-  } catch {
-    continue;
-  }
-  for (const f of files) {
-    if (DOC_RE.test(f) && !found.has(f)) found.set(f, join(dir, f));
-  }
-}
-
-mkdirSync(target, { recursive: true });
-
-/** The first `# ` heading of a markdown file, for the index label. */
-const firstHeading = (text) => {
-  const m = text.match(/^#\s+(.+)$/m);
-  return m ? m[1].trim() : '';
-};
-
-// Copy each doc; capture its title for the index.
-const entries = [];
-for (const [name, src] of found) {
-  const text = readFileSync(src, 'utf8');
-  writeFileSync(join(target, name), text);
-  entries.push({ file: name, title: firstHeading(text) });
-}
-
-// Sort: group by package, the main doc (aeye-<pkg>.md) before its sub-docs, then alphabetical.
-const keyOf = (file) => {
-  const base = file.replace(/^aeye-/, '').replace(/\.md$/, '');
-  const pkg = base.split('-')[0];
-  return { pkg, isSub: base === pkg ? 0 : 1, base };
-};
-entries.sort((a, b) => {
-  const ka = keyOf(a.file);
-  const kb = keyOf(b.file);
-  return ka.pkg.localeCompare(kb.pkg) || ka.isSub - kb.isSub || ka.base.localeCompare(kb.base);
-});
-
-// Generate the index (@aeye has no hand-written root router, so we build one from what's present).
-const rows = entries.map((e) => `| [\`${e.file}\`](./${e.file}) | ${e.title} |`).join('\n');
-const index = `<!-- Generated by @aeye/context — re-run \`npx @aeye/context\` to refresh. Do not edit by hand. -->
-
-# @aeye — agent reference
-
-Flattened agent docs for the \`@aeye/*\` packages installed in this project. Point your coding agent
-(or your editor) at this folder: the \`./aeye-*.md\` links below — and the cross-links inside each
-doc — resolve here.
-
-| Doc | About |
-| --- | --- |
-${rows}
-`;
-writeFileSync(join(target, 'aeye.md'), index);
-
-if (found.size === 0) {
-  console.warn('aeye-context: no @aeye/* packages found under node_modules — wrote an empty index.');
-} else {
-  console.log(`aeye-context: synced ${found.size} doc(s) + aeye.md index → ${target}/`);
-}
+#!/usr/bin/env node
+/**
+ * aeye-context — flatten the @aeye agent-reference docs into your repo.
+ *
+ * Each `@aeye/*` package ships flat `aeye-<pkg>.md` docs in its package root
+ * (`node_modules/@aeye/<pkg>/aeye-<pkg>.md`), and those docs cross-link as flat siblings
+ * (`./aeye-core-types.md`). This copies every installed package's doc(s) into one flat folder and
+ * writes a generated `aeye.md` index, so the links resolve — on GitHub, in your editor, and when
+ * handed to a coding agent.
+ *
+ *   npx @aeye/context               # → ./docs
+ *   npx @aeye/context .aeye         # → any target directory
+ *
+ * Re-run after adding/upgrading @aeye packages to resync.
+ */
+import { readdirSync, mkdirSync, copyFileSync, existsSync, readFileSync, writeFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h')) {
+  console.log(`Usage: aeye-context [target-dir]
+
+  target-dir   where to write the flat docs + generated index (default: docs)
+
+Scans node_modules for every installed @aeye/* package's aeye-*.md, copies them flat into
+<target-dir>, and writes an aeye.md index linking to them.`);
+  process.exit(0);
+}
+
+const target = args.find((a) => !a.startsWith('-')) ?? 'docs';
+const DOC_RE = /^aeye-.*\.md$/;
+
+/** Directories that may hold an installed @aeye package. Direct deps first (they win on dedup). */
+function scopeDirs() {
+  const dirs = [];
+  const scope = join('node_modules', '@aeye');
+  if (existsSync(scope)) {
+    for (const name of readdirSync(scope)) dirs.push(join(scope, name));
+  }
+  // pnpm keeps transitive deps only under the virtual store (harmless no-op on npm/yarn).
+  const store = join('node_modules', '.pnpm');
+  if (existsSync(store)) {
+    for (const entry of readdirSync(store)) {
+      const nested = join(store, entry, 'node_modules', '@aeye');
+      if (existsSync(nested)) {
+        for (const name of readdirSync(nested)) dirs.push(join(nested, name));
+      }
+    }
+  }
+  return dirs;
+}
+
+// Collect docs, deduped by filename (first occurrence — a direct dep — wins).
+const found = new Map(); // filename -> absolute source path
+for (const dir of scopeDirs()) {
+  let files;
+  try {
+    if (!statSync(dir).isDirectory()) continue;
+    files = readdirSync(dir);
+  } catch {
+    continue;
+  }
+  for (const f of files) {
+    if (DOC_RE.test(f) && !found.has(f)) found.set(f, join(dir, f));
+  }
+}
+
+mkdirSync(target, { recursive: true });
+
+/** The first `# ` heading of a markdown file, for the index label. */
+const firstHeading = (text) => {
+  const m = text.match(/^#\s+(.+)$/m);
+  return m ? m[1].trim() : '';
+};
+
+// Copy each doc; capture its title for the index.
+const entries = [];
+for (const [name, src] of found) {
+  const text = readFileSync(src, 'utf8');
+  writeFileSync(join(target, name), text);
+  entries.push({ file: name, title: firstHeading(text) });
+}
+
+// Sort: group by package, the main doc (aeye-<pkg>.md) before its sub-docs, then alphabetical.
+const keyOf = (file) => {
+  const base = file.replace(/^aeye-/, '').replace(/\.md$/, '');
+  const pkg = base.split('-')[0];
+  return { pkg, isSub: base === pkg ? 0 : 1, base };
+};
+entries.sort((a, b) => {
+  const ka = keyOf(a.file);
+  const kb = keyOf(b.file);
+  return ka.pkg.localeCompare(kb.pkg) || ka.isSub - kb.isSub || ka.base.localeCompare(kb.base);
+});
+
+// Generate the index (@aeye has no hand-written root router, so we build one from what's present).
+const rows = entries.map((e) => `| [\`${e.file}\`](./${e.file}) | ${e.title} |`).join('\n');
+const index = `<!-- Generated by @aeye/context — re-run \`npx @aeye/context\` to refresh. Do not edit by hand. -->
+
+# @aeye — agent reference
+
+Flattened agent docs for the \`@aeye/*\` packages installed in this project. Point your coding agent
+(or your editor) at this folder: the \`./aeye-*.md\` links below — and the cross-links inside each
+doc — resolve here.
+
+| Doc | About |
+| --- | --- |
+${rows}
+`;
+writeFileSync(join(target, 'aeye.md'), index);
+
+if (found.size === 0) {
+  console.warn('aeye-context: no @aeye/* packages found under node_modules — wrote an empty index.');
+} else {
+  console.log(`aeye-context: synced ${found.size} doc(s) + aeye.md index → ${target}/`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aeye/context",
-  "version": "0.3.9",
+  "version": "0.7.0",
   "description": "Pull @aeye's agent context into your repo — flatten every installed @aeye/* package's aeye-*.md into one folder (with a generated index) to point a coding agent at.",
   "type": "module",
   "license": "GPL-3.0",