@justinmoon/agent-tools 0.1.0

package/README.md

@@ -0,0 +1,57 @@
+# @justinmoon/agent-tools
+
+CLI tooling for AI agent project hygiene.
+
+## Usage
+
+```bash
+npx @justinmoon/agent-tools <command>
+```
+
+## Commands
+
+### list-docs
+
+List docs in `./docs/` with frontmatter summaries and "read when" hints.
+
+```bash
+npx @justinmoon/agent-tools list-docs
+```
+
+### check-docs
+
+Validate all docs have proper frontmatter. Use in CI.
+
+```bash
+npx @justinmoon/agent-tools check-docs
+```
+
+#### Doc format
+
+```markdown
+---
+summary: Brief description of what this doc covers
+read_when:
+  - when working on feature X
+  - when debugging Y
+---
+```
+
+### check-justfile
+
+Verify all justfile recipes have a `#` summary comment. Use in CI.
+
+```bash
+npx @justinmoon/agent-tools check-justfile
+npx @justinmoon/agent-tools check-justfile path/to/justfile
+```
+
+## CI Integration
+
+Add to your `pre-merge` justfile recipe:
+
+```just
+pre-merge: lint test
+    npx -y @justinmoon/agent-tools check-docs
+    npx -y @justinmoon/agent-tools check-justfile
+```

package/bin/agent-tools.mjs

@@ -0,0 +1,298 @@
+#!/usr/bin/env node
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+
+const args = process.argv.slice(2);
+const command = args[0];
+const commandArgs = args.slice(1);
+
+// ── Dispatch ────────────────────────────────────────────────────────────────
+
+const commands = {
+  'list-docs': listDocs,
+  'check-docs': checkDocs,
+  'check-justfile': checkJustfile,
+};
+
+if (!command || command === '--help' || command === '-h') {
+  console.log(`agent-tools - AI agent project hygiene.
+
+Usage:
+  agent-tools <command>
+
+Commands:
+  list-docs          List docs in ./docs/ with summaries and read-when hints
+  check-docs         Validate all docs have proper frontmatter (CI)
+  check-justfile     Verify all justfile recipes have a summary comment (CI)
+
+Options:
+  --help             Show this help`);
+  process.exit(0);
+}
+
+if (!commands[command]) {
+  console.error(`Unknown command: ${command}\nRun 'agent-tools --help' for usage.`);
+  process.exit(1);
+}
+
+commands[command](commandArgs);
+
+// ── Docs shared ─────────────────────────────────────────────────────────────
+
+const EXCLUDED_DIRS = new Set(['archive', 'research']);
+
+function walkMarkdownFiles(dir, base = dir) {
+  const entries = readdirSync(dir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    if (entry.name.startsWith('.')) continue;
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (EXCLUDED_DIRS.has(entry.name)) continue;
+      files.push(...walkMarkdownFiles(fullPath, base));
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      files.push(relative(base, fullPath));
+    }
+  }
+  return files.sort((a, b) => a.localeCompare(b));
+}
+
+function extractMetadata(fullPath) {
+  const content = readFileSync(fullPath, 'utf8');
+
+  if (!content.startsWith('---')) {
+    return { summary: null, readWhen: [], error: 'missing front matter' };
+  }
+
+  const endIndex = content.indexOf('\n---', 3);
+  if (endIndex === -1) {
+    return { summary: null, readWhen: [], error: 'unterminated front matter' };
+  }
+
+  const frontMatter = content.slice(3, endIndex).trim();
+  const lines = frontMatter.split('\n');
+
+  let summaryLine = null;
+  const readWhen = [];
+  let collectingField = null;
+
+  for (const rawLine of lines) {
+    const line = rawLine.trim();
+
+    if (line.startsWith('summary:')) {
+      summaryLine = line;
+      collectingField = null;
+      continue;
+    }
+
+    if (line.startsWith('read_when:')) {
+      collectingField = 'read_when';
+      const inline = line.slice('read_when:'.length).trim();
+      if (inline.startsWith('[') && inline.endsWith(']')) {
+        try {
+          const parsed = JSON.parse(inline.replace(/'/g, '"'));
+          if (Array.isArray(parsed)) {
+            readWhen.push(...parsed.filter(v => v != null).map(v => String(v).trim()).filter(Boolean));
+          }
+        } catch {
+          // ignore malformed inline arrays
+        }
+      }
+      continue;
+    }
+
+    if (collectingField === 'read_when') {
+      if (line.startsWith('- ')) {
+        const hint = line.slice(2).trim();
+        if (hint) readWhen.push(hint);
+      } else if (line === '') {
+        // skip blank lines within field
+      } else {
+        collectingField = null;
+      }
+    }
+  }
+
+  if (!summaryLine) {
+    return { summary: null, readWhen, error: 'summary key missing' };
+  }
+
+  const summaryValue = summaryLine.slice('summary:'.length).trim();
+  const normalized = summaryValue
+    .replace(/^['"]|['"]$/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+  if (!normalized) {
+    return { summary: null, readWhen, error: 'summary is empty' };
+  }
+
+  return { summary: normalized, readWhen };
+}
+
+// ── list-docs ───────────────────────────────────────────────────────────────
+
+function listDocs(args) {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`agent-tools list-docs - List docs with summaries and read-when hints.
+
+Usage:
+  agent-tools list-docs
+
+Scans ./docs/ for markdown files with YAML frontmatter.`);
+    return;
+  }
+
+  const docsDir = join(process.cwd(), 'docs');
+  if (!existsSync(docsDir)) {
+    console.log('No docs/ folder found.');
+    return;
+  }
+
+  const files = walkMarkdownFiles(docsDir);
+  console.log('Listing all markdown files in docs folder:');
+
+  for (const relativePath of files) {
+    const fullPath = join(docsDir, relativePath);
+    const { summary, readWhen, error } = extractMetadata(fullPath);
+    if (summary) {
+      console.log(`${relativePath} - ${summary}`);
+      if (readWhen.length > 0) {
+        console.log(`  Read when: ${readWhen.join('; ')}`);
+      }
+    } else {
+      const reason = error ? ` - [${error}]` : '';
+      console.log(`${relativePath}${reason}`);
+    }
+  }
+
+  console.log(
+    '\nReminder: keep docs up to date as behavior changes. When your task matches any "Read when" hint above, read that doc before coding, and suggest new coverage when it is missing.'
+  );
+}
+
+// ── check-docs ──────────────────────────────────────────────────────────────
+
+function checkDocs(args) {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`agent-tools check-docs - Validate docs frontmatter (for CI).
+
+Usage:
+  agent-tools check-docs
+
+Ensures every .md in ./docs/ has a summary and read_when in frontmatter.`);
+    return;
+  }
+
+  const docsDir = join(process.cwd(), 'docs');
+  if (!existsSync(docsDir)) {
+    process.exit(0);
+  }
+
+  const files = walkMarkdownFiles(docsDir);
+  const failures = [];
+
+  for (const relativePath of files) {
+    const fullPath = join(docsDir, relativePath);
+    const { summary, error } = extractMetadata(fullPath);
+    if (!summary && error) {
+      failures.push({ file: relativePath, error });
+    }
+  }
+
+  if (failures.length > 0) {
+    console.error('check-docs failed:');
+    for (const { file, error } of failures) {
+      console.error(`  ${file}: ${error}`);
+    }
+    console.error(`\nAll docs must have frontmatter with 'summary' and 'read_when' fields.`);
+    console.error('Example:');
+    console.error('---');
+    console.error('summary: Brief description of what this doc covers');
+    console.error('read_when:');
+    console.error('  - when to read this doc');
+    console.error('---');
+    process.exit(1);
+  }
+
+  console.log(`check-docs passed: ${files.length} docs have valid frontmatter`);
+}
+
+// ── check-justfile ──────────────────────────────────────────────────────────
+
+function checkJustfile(args) {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`agent-tools check-justfile - Verify all recipes have a summary comment.
+
+Usage:
+  agent-tools check-justfile [path/to/justfile]
+
+just --list uses the # comment above each recipe as its summary.
+This tool ensures no recipe is missing one.`);
+    return;
+  }
+
+  const justfilePath = resolve(args[0] || 'justfile');
+
+  let content;
+  try {
+    content = readFileSync(justfilePath, 'utf8');
+  } catch (e) {
+    if (e.code === 'ENOENT') {
+      console.log(`No justfile found at ${justfilePath}`);
+      return;
+    }
+    throw e;
+  }
+
+  const lines = content.split('\n');
+  const missing = [];
+  let recipeCount = 0;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    const recipeMatch = line.match(/^([a-zA-Z_][a-zA-Z0-9_-]*)\s*(?:[^:=]*)?:/);
+    if (!recipeMatch) continue;
+
+    const name = recipeMatch[1];
+    if (['set', 'export', 'alias', 'import', 'mod'].includes(name)) continue;
+
+    recipeCount++;
+
+    // Look backwards for a comment (skip blank lines)
+    let hasComment = false;
+    let isPrivate = false;
+    for (let j = i - 1; j >= 0; j--) {
+      const prev = lines[j].trim();
+      if (prev === '') continue;
+      if (prev === '[private]') {
+        isPrivate = true;
+        break;
+      }
+      if (prev.startsWith('#')) {
+        hasComment = true;
+      }
+      break;
+    }
+
+    if (!hasComment && !isPrivate) {
+      missing.push({ name, line: i + 1 });
+    }
+  }
+
+  if (missing.length > 0) {
+    console.error(`check-justfile failed: ${missing.length} recipe(s) missing summary comment:\n`);
+    for (const { name, line } of missing) {
+      console.error(`  line ${line}: ${name}`);
+    }
+    console.error(`\nAdd a comment above each recipe, e.g.:`);
+    console.error(`  # Build the project.`);
+    console.error(`  build:`);
+    console.error(`    cargo build`);
+    process.exit(1);
+  }
+
+  console.log(`check-justfile passed: ${recipeCount} recipes, all have comments`);
+}

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@justinmoon/agent-tools",
+  "version": "0.1.0",
+  "description": "CLI tooling for AI agent project hygiene: docs indexing, justfile linting.",
+  "bin": {
+    "agent-tools": "./bin/agent-tools.mjs"
+  },
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/justinmoon/agent-tools.git"
+  },
+  "keywords": [
+    "ai-agents",
+    "docs",
+    "justfile",
+    "lint",
+    "ci"
+  ]
+}