@sebasgc0399/agents-md 0.2.0

package/dist/utils/fs-utils.js

@@ -0,0 +1,121 @@
+/**
+ * Safe file system utilities
+ */
+import fs from 'fs';
+import path from 'path';
+/**
+ * Safely read package.json with size limit (1MB max)
+ */
+export async function readPackageJson(rootPath) {
+    const packagePath = path.join(rootPath, 'package.json');
+    // Check if file exists
+    if (!fs.existsSync(packagePath)) {
+        throw new Error('No package.json found');
+    }
+    // Check file size (max 1MB for safety)
+    const stats = fs.statSync(packagePath);
+    const MAX_SIZE = 1024 * 1024; // 1MB
+    if (stats.size > MAX_SIZE) {
+        throw new Error('package.json is too large (>1MB). This may indicate a corrupted file.');
+    }
+    // Read and parse
+    const content = fs.readFileSync(packagePath, 'utf-8');
+    try {
+        return JSON.parse(content);
+    }
+    catch (error) {
+        throw new Error('Invalid JSON in package.json');
+    }
+}
+/**
+ * Check if a directory exists
+ */
+export function directoryExists(dirPath) {
+    try {
+        return fs.existsSync(dirPath) && fs.statSync(dirPath).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if a file exists
+ */
+export function fileExists(filePath) {
+    try {
+        return fs.existsSync(filePath) && fs.statSync(filePath).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if path is within project (prevent path traversal)
+ */
+export function isPathSafe(basePath, targetPath) {
+    const baseReal = resolveRealPath(path.resolve(basePath));
+    if (!baseReal) {
+        return false;
+    }
+    const targetAbsolute = path.isAbsolute(targetPath)
+        ? path.resolve(targetPath)
+        : path.resolve(baseReal, targetPath);
+    // Outside base directory (including sibling prefix tricks like project -> project2)
+    if (!isPathInside(baseReal, targetAbsolute)) {
+        return false;
+    }
+    // Best-effort symlink guard: only block symlinks that resolve outside project root.
+    const relativeToBase = path.relative(baseReal, targetAbsolute);
+    if (hasExternalSymlinkInExistingSegments(baseReal, relativeToBase)) {
+        return false;
+    }
+    return true;
+}
+function resolveRealPath(value) {
+    try {
+        return fs.realpathSync(value);
+    }
+    catch {
+        return null;
+    }
+}
+function normalizePathForComparison(value) {
+    const normalized = path.normalize(value);
+    return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
+}
+function isPathInside(basePath, targetPath) {
+    const resolvedBase = normalizePathForComparison(path.resolve(basePath));
+    const resolvedTarget = normalizePathForComparison(path.resolve(targetPath));
+    const relative = path.relative(resolvedBase, resolvedTarget);
+    const escapes = relative === '..' ||
+        relative.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relative);
+    return !escapes;
+}
+function hasExternalSymlinkInExistingSegments(basePath, relativePath) {
+    if (!relativePath) {
+        return false;
+    }
+    const segments = relativePath.split(path.sep).filter(Boolean);
+    let current = basePath;
+    for (const segment of segments) {
+        current = path.join(current, segment);
+        if (!fs.existsSync(current)) {
+            break;
+        }
+        try {
+            if (fs.lstatSync(current).isSymbolicLink()) {
+                const symlinkReal = resolveRealPath(current);
+                if (!symlinkReal || !isPathInside(basePath, symlinkReal)) {
+                    return true;
+                }
+            }
+        }
+        catch {
+            // Fail closed if metadata cannot be read.
+            return true;
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=fs-utils.js.map

package/dist/utils/fs-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-utils.js","sourceRoot":"","sources":["../../src/utils/fs-utils.ts"],"names":[],"mappings":"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"}

package/dist/utils/logger.d.ts

@@ -0,0 +1,14 @@
+/**
+ * CLI logging utilities for consistent output
+ */
+export declare class Logger {
+    private isVerbose;
+    constructor(isVerbose?: boolean);
+    success(message: string): void;
+    error(message: string): void;
+    warning(message: string): void;
+    info(message: string): void;
+    verbose(message: string): void;
+    debug(label: string, data: unknown): void;
+}
+//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,qBAAa,MAAM;IACL,OAAO,CAAC,SAAS;gBAAT,SAAS,GAAE,OAAe;IAE9C,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAI9B,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAI5B,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAI9B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAI3B,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAM9B,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI;CAK1C"}

package/dist/utils/logger.js

@@ -0,0 +1,32 @@
+/**
+ * CLI logging utilities for consistent output
+ */
+export class Logger {
+    isVerbose;
+    constructor(isVerbose = false) {
+        this.isVerbose = isVerbose;
+    }
+    success(message) {
+        console.log(`✓ ${message}`);
+    }
+    error(message) {
+        console.error(`✗ Error: ${message}`);
+    }
+    warning(message) {
+        console.warn(`⚠ ${message}`);
+    }
+    info(message) {
+        console.log(message);
+    }
+    verbose(message) {
+        if (this.isVerbose) {
+            console.log(`→ ${message}`);
+        }
+    }
+    debug(label, data) {
+        if (this.isVerbose) {
+            console.log(`[DEBUG] ${label}:`, data);
+        }
+    }
+}
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,OAAO,MAAM;IACG;IAApB,YAAoB,YAAqB,KAAK;QAA1B,cAAS,GAAT,SAAS,CAAiB;IAAG,CAAC;IAElD,OAAO,CAAC,OAAe;QACrB,OAAO,CAAC,GAAG,CAAC,KAAK,OAAO,EAAE,CAAC,CAAC;IAC9B,CAAC;IAED,KAAK,CAAC,OAAe;QACnB,OAAO,CAAC,KAAK,CAAC,YAAY,OAAO,EAAE,CAAC,CAAC;IACvC,CAAC;IAED,OAAO,CAAC,OAAe;QACrB,OAAO,CAAC,IAAI,CAAC,KAAK,OAAO,EAAE,CAAC,CAAC;IAC/B,CAAC;IAED,IAAI,CAAC,OAAe;QAClB,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACvB,CAAC;IAED,OAAO,CAAC,OAAe;QACrB,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,OAAO,CAAC,GAAG,CAAC,KAAK,OAAO,EAAE,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IAED,KAAK,CAAC,KAAa,EAAE,IAAa;QAChC,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,OAAO,CAAC,GAAG,CAAC,WAAW,KAAK,GAAG,EAAE,IAAI,CAAC,CAAC;QACzC,CAAC;IACH,CAAC;CACF"}

package/dist/utils/token-counter.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Token estimation utilities
+ * Uses character count heuristic: ~4 chars/token for text, ~3 chars/token for code
+ */
+/**
+ * Estimate token count for given content
+ * This is approximate but sufficient for validation
+ */
+export declare function estimateTokens(content: string): number;
+/**
+ * Validate token count is within budget
+ */
+export declare function validateTokenCount(content: string): {
+    tokens: number;
+    withinBudget: boolean;
+    warning?: string;
+};
+//# sourceMappingURL=token-counter.d.ts.map

package/dist/utils/token-counter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-counter.d.ts","sourceRoot":"","sources":["../../src/utils/token-counter.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAetD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,OAAO,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAsBA"}

package/dist/utils/token-counter.js

@@ -0,0 +1,45 @@
+/**
+ * Token estimation utilities
+ * Uses character count heuristic: ~4 chars/token for text, ~3 chars/token for code
+ */
+/**
+ * Estimate token count for given content
+ * This is approximate but sufficient for validation
+ */
+export function estimateTokens(content) {
+    // Extract code blocks (more token-dense)
+    const codeBlockRegex = /```[\s\S]*?```/g;
+    const codeBlocks = content.match(codeBlockRegex) || [];
+    const codeChars = codeBlocks.join('').length;
+    // Text without code blocks
+    const textContent = content.replace(codeBlockRegex, '');
+    const textChars = textContent.length;
+    // Estimate: 3 chars/token for code, 4 chars/token for text
+    const codeTokens = Math.ceil(codeChars / 3);
+    const textTokens = Math.ceil(textChars / 4);
+    return codeTokens + textTokens;
+}
+/**
+ * Validate token count is within budget
+ */
+export function validateTokenCount(content) {
+    const tokens = estimateTokens(content);
+    const MIN_TOKENS = 800;
+    const MAX_TOKENS = 1500;
+    if (tokens < MIN_TOKENS) {
+        return {
+            tokens,
+            withinBudget: false,
+            warning: `Output is quite short (${tokens} tokens). Consider adding more details.`,
+        };
+    }
+    if (tokens > MAX_TOKENS) {
+        return {
+            tokens,
+            withinBudget: false,
+            warning: `Output is too long (${tokens} tokens). AI agents may not process it efficiently.`,
+        };
+    }
+    return { tokens, withinBudget: true };
+}
+//# sourceMappingURL=token-counter.js.map

package/dist/utils/token-counter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-counter.js","sourceRoot":"","sources":["../../src/utils/token-counter.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe;IAC5C,yCAAyC;IACzC,MAAM,cAAc,GAAG,iBAAiB,CAAC;IACzC,MAAM,UAAU,GAAG,OAAO,CAAC,KAAK,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC;IACvD,MAAM,SAAS,GAAG,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC;IAE7C,2BAA2B;IAC3B,MAAM,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC;IACxD,MAAM,SAAS,GAAG,WAAW,CAAC,MAAM,CAAC;IAErC,2DAA2D;IAC3D,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC;IAC5C,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC;IAE5C,OAAO,UAAU,GAAG,UAAU,CAAC;AACjC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAe;IAKhD,MAAM,MAAM,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;IACvC,MAAM,UAAU,GAAG,GAAG,CAAC;IACvB,MAAM,UAAU,GAAG,IAAI,CAAC;IAExB,IAAI,MAAM,GAAG,UAAU,EAAE,CAAC;QACxB,OAAO;YACL,MAAM;YACN,YAAY,EAAE,KAAK;YACnB,OAAO,EAAE,0BAA0B,MAAM,yCAAyC;SACnF,CAAC;IACJ,CAAC;IAED,IAAI,MAAM,GAAG,UAAU,EAAE,CAAC;QACxB,OAAO;YACL,MAAM;YACN,YAAY,EAAE,KAAK;YACnB,OAAO,EAAE,uBAAuB,MAAM,qDAAqD;SAC5F,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;AACxC,CAAC"}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@sebasgc0399/agents-md",
+  "version": "0.2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sebasgc0399/agents-md.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sebasgc0399/agents-md/issues"
+  },
+  "homepage": "https://github.com/sebasgc0399/agents-md#readme",
+  "description": "Generate AGENTS.md files for AI coding agents",
+  "type": "module",
+  "bin": {
+    "agents-md": "dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc && npm run copy-templates",
+    "benchmark:lite": "node scripts/benchmark/lite.mjs",
+    "benchmark:p1": "node scripts/benchmark/p1.mjs",
+    "benchmark:p1:update": "node scripts/benchmark/p1.mjs --update-baseline",
+    "benchmark:p2": "node scripts/benchmark/p2.mjs",
+    "copy-templates": "node -e \"require('fs').cpSync('src/templates', 'dist/templates', {recursive: true})\"",
+    "dev": "tsc --watch",
+    "start": "node dist/cli.js",
+    "test": "npm run build && vitest run",
+    "test:coverage": "npm run build && vitest run --coverage",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build && npm test",
+    "release": "release-it"
+  },
+  "keywords": [
+    "agents",
+    "ai",
+    "llm",
+    "documentation",
+    "readme",
+    "claude",
+    "copilot",
+    "windsurf"
+  ],
+  "author": "sebasgc0399",
+  "license": "MIT",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "dependencies": {
+    "commander": "^11.1.0",
+    "mustache": "^4.2.0"
+  },
+  "devDependencies": {
+    "@release-it/conventional-changelog": "^10.0.5",
+    "@types/mustache": "^4.2.5",
+    "@types/node": "^20.10.0",
+    "@vitest/coverage-v8": "^1.1.0",
+    "release-it": "^19.2.4",
+    "tsx": "^4.21.0",
+    "typescript": "^5.3.3",
+    "vitest": "^1.1.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}