@aeye/context 0.3.9

package/README.md

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

package/bin/aeye-context.mjs

@@ -0,0 +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}/`);
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@aeye/context",
+  "version": "0.3.9",
+  "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",
+  "author": "ClickerMonkey",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ClickerMonkey/aeye.git",
+    "directory": "packages/context"
+  },
+  "bin": {
+    "aeye-context": "bin/aeye-context.mjs"
+  },
+  "files": [
+    "bin",
+    "README.md"
+  ],
+  "keywords": [
+    "aeye",
+    "context",
+    "docs",
+    "llm",
+    "agent",
+    "cli"
+  ]
+}