blytz 1.1.1 → 1.2.1

package/README.md

@@ -7,7 +7,7 @@
 - Updates an existing `README.md`
 - Creates a new `README.md` with `--init`
 - Replaces an existing `README.md` with `--force`
-- Reads `package.json` to build README sections automatically
+- Reads `package.json` / `requirements.txt` to build README sections automatically
 - Generates a basic folder tree for the project structure section
 
 ## Install
@@ -16,12 +16,6 @@
 npm install -g blytz
 ```
 
-If you are developing locally from this repository, you can link it instead:
-
-```bash
-npm link
-```
-
 ## Usage
 
 Run the CLI from the root of the project you want to document:
@@ -96,9 +90,9 @@ blytz
 
 ## Notes
 
-- The CLI expects to run in a folder that contains `package.json`
+- The CLI expects to run in a folder that contains `package.json` or `requirements.txt`
 - The CLI reads the local `README.md` in the current directory
-- The folder tree excludes `node_modules` and `.git`
+- The folder tree excludes `node_modules` and `.git` and any folder that might be in `.gitignore`
 
 ## License
 

package/bin/README-NPM.md

@@ -7,7 +7,7 @@
 - Updates an existing `README.md`
 - Creates a new `README.md` with `--init`
 - Replaces an existing `README.md` with `--force`
-- Reads `package.json` to build README sections automatically
+- Reads `package.json` / `requirements.txt` to build README sections automatically
 - Generates a basic folder tree for the project structure section
 
 ## Install
@@ -16,12 +16,6 @@
 npm install -g blytz
 ```
 
-If you are developing locally from this repository, you can link it instead:
-
-```bash
-npm link
-```
-
 ## Usage
 
 Run the CLI from the root of the project you want to document:
@@ -96,9 +90,9 @@ blytz
 
 ## Notes
 
-- The CLI expects to run in a folder that contains `package.json`
+- The CLI expects to run in a folder that contains `package.json` or `requirements.txt`
 - The CLI reads the local `README.md` in the current directory
-- The folder tree excludes `node_modules` and `.git`
+- The folder tree excludes `node_modules` and `.git` and any folder that might be in `.gitignore`
 
 ## License
 

package/bin/cli.js

@@ -5,6 +5,13 @@ import path from 'path';
 import readline from 'readline/promises';
 
 import processReadme from '../src/processReadme.js';
+import {
+    buildLocalFileTree,
+    collectNodeDependencies,
+    collectPythonDependencies,
+    collectScripts,
+    getLicenseName
+} from '../src/readmeContext.js';
 
 const args = process.argv.slice(2);
 const shouldShowHelp = args.includes('--help') || args.includes('-h');
@@ -13,72 +20,59 @@ const shouldForce = args.includes('--force');
 const shouldUpdate = args.length === 0 || args.includes('--update');
 const hasAction = shouldUpdate || shouldInit || shouldForce;
 
-if (shouldShowHelp) {
-    console.log('Usage: blytz [--update|--init|--force]');
-    process.exit(0);
-}
-
-if (!hasAction) {
-    console.log('Usage: blytz [--update|--init|--force]');
-    process.exit(0);
-}
-
-function buildFileTree(dirPath, depth = 0, maxDepth = 4) {
-    if (depth >= maxDepth) {
-        return {};
-    }
-
-    const tree = {};
-    const entries = fs.readdirSync(dirPath, { withFileTypes: true })
-        .filter(entry => entry.name !== 'node_modules' && entry.name !== '.git')
-        .sort((left, right) => left.name.localeCompare(right.name));
-
-    for (const entry of entries) {
-        const entryPath = path.join(dirPath, entry.name);
-
-        if (entry.isDirectory()) {
-            tree[entry.name] = buildFileTree(entryPath, depth + 1, maxDepth);
-        } else {
-            tree[entry.name] = null;
-        }
+const supportsColor = process.stdout.isTTY && process.env.NO_COLOR !== '1';
+const ANSI = {
+    reset: '\x1b[0m',
+    bold: '\x1b[1m',
+    dim: '\x1b[2m',
+    cyan: '\x1b[36m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    red: '\x1b[31m',
+    blue: '\x1b[34m'
+};
+
+function colorize(text, ...codes) {
+    if (!supportsColor) {
+        return text;
     }
 
-    return tree;
+    return `${codes.join('')}${text}${ANSI.reset}`;
 }
 
-function collectDependencies(packageJson) {
-    return Object.keys(packageJson.dependencies || {}).sort();
+function formatLabel(label, color) {
+    return colorize(label, ANSI.bold, color);
 }
 
-function collectPythonDependencies(requirementsContent) {
-    return requirementsContent
-        .split(/\r?\n/)
-        .map(line => line.trim())
-        .filter(line => line && !line.startsWith('#'))
-        .filter(line => !line.startsWith('-'))
-        .map(line => line.split(';')[0].trim())
-        .map(line => line.split(/[=<>!~]/)[0].trim())
-        .filter(Boolean)
-        .sort((left, right) => left.localeCompare(right));
+function printHelp(output = console.log) {
+    output([
+        formatLabel('Usage', ANSI.blue),
+        `  ${colorize('blytz', ANSI.bold, ANSI.green)} ${colorize('[command]', ANSI.dim)}`,
+        '',
+        formatLabel('Commands', ANSI.blue),
+        `  ${colorize('--update', ANSI.yellow)}         ${colorize('Update the existing README.md using project metadata.', ANSI.dim)}`,
+        `  ${colorize('--init', ANSI.yellow)}           ${colorize('Create a new README.md and prompt for title and description.', ANSI.dim)}`,
+        `  ${colorize('--force', ANSI.yellow)}          ${colorize('Replace the existing README.md with a newly generated one.', ANSI.dim)}`,
+        `  ${colorize('--help, -h', ANSI.yellow)}       ${colorize('Show this help message.', ANSI.dim)}`,
+        '',
+    ].join('\n'));
 }
 
-function collectScripts(packageJson) {
-    const scripts = new Map();
-
-    for (const [name, command] of Object.entries(packageJson.scripts || {})) {
-        scripts.set(name, [{ package: '(root)', command }]);
-    }
-
-    return scripts;
+if (shouldShowHelp) {
+    printHelp();
+    process.exit(0);
 }
 
-function getLicenseName(licenseContent) {
-    const firstLine = licenseContent
-        .split(/\r?\n/)
-        .map(line => line.trim())
-        .find(Boolean);
-
-    return firstLine || '';
+if (!hasAction) {
+    if (args.length > 0) {
+        const invalidCommand = args.find(arg => arg.startsWith('-')) || args[0];
+        console.error(`${formatLabel('Error', ANSI.red)} Command not available: ${colorize(invalidCommand, ANSI.bold, ANSI.red)}`);
+        console.error('');
+        printHelp(console.error);
+        process.exit(1);
+    }
+    printHelp();
+    process.exit(0);
 }
 
 async function promptForTitleAndDescription() {
@@ -88,8 +82,8 @@ async function promptForTitleAndDescription() {
     });
 
     try {
-        const titleContent = (await rl.question('Add title: ')).trim();
-        const descriptionContent = (await rl.question('Add description: ')).trim();
+        const titleContent = (await rl.question(`${formatLabel('Title', ANSI.yellow)} ${colorize('(leave blank to use project name)', ANSI.dim)}: `)).trim();
+        const descriptionContent = (await rl.question(`${formatLabel('Description', ANSI.yellow)} ${colorize('(leave blank to use default intro)', ANSI.dim)}: `)).trim();
         return { titleContent, descriptionContent };
     } finally {
         rl.close();
@@ -97,7 +91,7 @@ async function promptForTitleAndDescription() {
 }
 
 async function main() {
-    console.log("Scanning for project files...");
+    console.log(`${formatLabel('Info', ANSI.cyan)} Scanning for project files...`);
 
     const targetDir = process.cwd();
     const readmePath = path.join(targetDir, 'README.md');
@@ -110,28 +104,28 @@ async function main() {
     const hasLicense = fs.existsSync(licensePath);
 
     if (!readmeExists && !shouldInit && !shouldForce) {
-        console.error("Error: No README.md found in this directory. Try --init.");
+        console.error(`${formatLabel('Error', ANSI.red)} No README.md found in this directory. Try ${colorize('--init', ANSI.bold, ANSI.yellow)}.`);
         process.exit(1);
     }
 
     if (readmeExists && shouldInit && !shouldForce) {
-        console.error("README.md already exists. Try --force.");
+        console.error(`${formatLabel('Error', ANSI.red)} README.md already exists. Try ${colorize('--force', ANSI.bold, ANSI.red)}.`);
         process.exit(1);
     }
 
     if (!hasPackageJson && !hasRequirements) {
-        console.error("Error: No package.json or requirements.txt found in this directory.");
+        console.error(`${formatLabel('Error', ANSI.red)} No ${colorize('package.json', ANSI.bold)} or ${colorize('requirements.txt', ANSI.bold)} found in this directory.`);
         process.exit(1);
     }
 
-    console.log("Files found. Processing README...");
+    console.log(`${formatLabel('Info', ANSI.cyan)} Files found. Processing README...`);
 
     if (shouldForce && readmeExists) {
         fs.unlinkSync(readmePath);
     }
 
     const readmeContent = fs.existsSync(readmePath) ? fs.readFileSync(readmePath, 'utf-8') : '';
-    const fileTree = buildFileTree(targetDir);
+    const fileTree = buildLocalFileTree(fs, path, targetDir, targetDir);
     const projectName = path.basename(targetDir);
     const licenseName = hasLicense ? getLicenseName(fs.readFileSync(licensePath, 'utf-8')) : '';
     const shouldPromptMetadata = !shouldUpdate;
@@ -148,8 +142,8 @@ async function main() {
         context = {
             packageJson,
             packages: [{ path: 'package.json', content: packageJson }],
-            dependencies: collectDependencies(packageJson),
-            scripts: collectScripts(packageJson),
+            dependencies: collectNodeDependencies([{ path: 'package.json', content: packageJson }]),
+            scripts: collectScripts([{ path: 'package.json', content: packageJson }]),
             fileTree,
             titleContent,
             descriptionContent,
@@ -165,7 +159,7 @@ async function main() {
 
         context = {
             packages: [{ path: 'requirements.txt', content: requirementsContent }],
-            dependencies: collectPythonDependencies(requirementsContent),
+            dependencies: collectPythonDependencies([{ path: 'requirements.txt', content: requirementsContent }]),
             scripts: new Map(),
             fileTree,
             titleContent,
@@ -183,11 +177,11 @@ async function main() {
 
     fs.writeFileSync(readmePath, updatedReadme, 'utf-8');
 
-    console.log("Success! README.md has been auto-fixed.");
+    console.log(`${formatLabel('Success', ANSI.green)} README.md has been auto-fixed.`);
 }
 
 (main()
     .catch(error => {
-        console.error("An error occurred during processing:", error.message);
+        console.error(`${formatLabel('Error', ANSI.red)} An error occurred during processing: ${error.message}`);
         process.exit(1);
     }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blytz",
-  "version": "1.1.1",
+  "version": "1.2.1",
   "bin": {
     "blytz": "./bin/cli.js"
   },
@@ -13,7 +13,7 @@
   "description": "An automated CLI tool to fix and maintain project READMEs",
   "type": "module",
   "scripts": {
-    "start": "node src/index.js",
+    "start": "node server/server.js",
     "prepublishOnly": "node scripts/sync-readme.js prepublish",
     "postpublish": "node scripts/sync-readme.js postpublish"
   },

package/src/processReadme.js

@@ -3,7 +3,7 @@ import getDefaultContent from "./template.js";
 
 //Core engine: processes README content and returns updated version
 export default function processReadme(content, projectType, context = {}) {
-    const { titleContent = "" } = context ?? {};
+    const { titleContent = "", descriptionContent = "", projectName = "" } = context ?? {};
 
     const normalizedContent = (content || "").replace(/^##(?=\S)/gm, "## ");
 
@@ -11,9 +11,13 @@ export default function processReadme(content, projectType, context = {}) {
     const sections = normalizedContent.split("## ");
     const sectionMap = {};
 
-    // Extract intro (title + description)
+    // Extract intro (title + description)
     const intro = sections[0].trim();
-    const finalIntro = titleContent ? `# ${titleContent}` : intro;
+    const resolvedTitle = titleContent || projectName || "";
+    const resolvedDescription = descriptionContent || getDefaultContent("description", projectType, context);
+    const finalIntro = resolvedTitle
+        ? [`# ${resolvedTitle}`, resolvedDescription].filter(Boolean).join("\n\n")
+        : intro;
 
     // Parse sections
     sections.slice(1).forEach(section => {
@@ -24,14 +28,13 @@ export default function processReadme(content, projectType, context = {}) {
         sectionMap[title] = body;
     });
 
-    // Required sections
-    const requiredSections = [
-        "description",
-        "installation",
-        "usage",
-        "dependencies",
-        "folder structure",
-        "license",
+    // Required sections
+    const requiredSections = [
+        "installation",
+        "usage",
+        "dependencies",
+        "folder structure",
+        "license",
         "built by"
     ];
 

package/src/readmeContext.js

@@ -0,0 +1,269 @@
+export const DEFAULT_IGNORED_NAMES = new Set([
+    "node_modules",
+    ".git",
+    ".agent",
+    "dist",
+    "build",
+    "out",
+    "target",
+    "venv",
+    ".venv",
+    "__pycache__",
+    ".idea",
+    ".vscode",
+    ".DS_Store",
+    "Thumbs.db",
+    ".env",
+    ".env.local",
+    ".env.development",
+    ".env.production"
+]);
+
+export function collectNodeDependencies(packages = []) {
+    const dependencies = new Set();
+
+    for (const pkg of packages) {
+        for (const dependency of Object.keys(pkg?.content?.dependencies || {})) {
+            dependencies.add(dependency);
+        }
+    }
+
+    return Array.from(dependencies).sort((left, right) => left.localeCompare(right));
+}
+
+export function collectPythonDependencies(files = []) {
+    const dependencies = new Set();
+
+    for (const file of files) {
+        if (!file?.content) {
+            continue;
+        }
+
+        file.content
+            .split(/\r?\n/)
+            .map(line => line.trim())
+            .filter(line => line && !line.startsWith("#"))
+            .filter(line => !line.startsWith("-"))
+            .map(line => line.split(";")[0].trim())
+            .map(line => line.split(/[=<>!~]/)[0].trim())
+            .filter(Boolean)
+            .forEach(dependency => dependencies.add(dependency));
+    }
+
+    return Array.from(dependencies).sort((left, right) => left.localeCompare(right));
+}
+
+export function collectScripts(packages = []) {
+    const scripts = new Map();
+
+    for (const pkg of packages) {
+        const packageDir = pkg.path === "package.json" ? "(root)" : pkg.path.replace("/package.json", "");
+
+        for (const [name, command] of Object.entries(pkg?.content?.scripts || {})) {
+
+            if(name !=="start"){
+                continue;
+            }
+
+            if (!scripts.has(name)) {
+                scripts.set(name, []);
+            }
+
+            scripts.get(name).push({ package: packageDir, command });
+        }
+    }
+
+    return scripts;
+}
+
+export function getLicenseName(licenseContent = "") {
+    const firstLine = licenseContent
+        .split(/\r?\n/)
+        .map(line => line.trim())
+        .find(Boolean);
+
+    return firstLine || "";
+}
+
+function escapeRegex(value) {
+    return value.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
+}
+
+function globToRegex(pattern) {
+    let regex = "";
+
+    for (let index = 0; index < pattern.length; index += 1) {
+        const char = pattern[index];
+        const nextChar = pattern[index + 1];
+
+        if (char === "*") {
+            if (nextChar === "*") {
+                regex += ".*";
+                index += 1;
+            } else {
+                regex += "[^/]*";
+            }
+            continue;
+        }
+
+        if (char === "?") {
+            regex += "[^/]";
+            continue;
+        }
+
+        regex += escapeRegex(char);
+    }
+
+    return regex;
+}
+
+export function parseGitignoreContent(content, baseDir = "") {
+    return content
+        .split(/\r?\n/)
+        .map(line => line.trim())
+        .filter(line => line && !line.startsWith("#"))
+        .map(line => {
+            const negated = line.startsWith("!");
+            const rawPattern = negated ? line.slice(1).trim() : line;
+
+            if (!rawPattern) {
+                return null;
+            }
+
+            const directoryOnly = rawPattern.endsWith("/");
+            const normalizedPattern = rawPattern.replace(/\/+$/, "").replace(/\\/g, "/");
+
+            if (!normalizedPattern) {
+                return null;
+            }
+
+            const anchored = normalizedPattern.startsWith("/");
+            const matcherPattern = anchored ? normalizedPattern.slice(1) : normalizedPattern;
+
+            return {
+                baseDir: baseDir.replace(/\\/g, "/"),
+                negated,
+                directoryOnly,
+                hasSlash: matcherPattern.includes("/"),
+                regex: new RegExp(`^${globToRegex(matcherPattern)}(?:/.*)?$`),
+                basenameRegex: new RegExp(`^${globToRegex(matcherPattern)}$`)
+            };
+        })
+        .filter(Boolean);
+}
+
+export function isIgnoredByGitignore(relativePath, isDirectory, gitignoreRules = []) {
+    const normalizedPath = relativePath.replace(/\\/g, "/");
+    let ignored = false;
+
+    for (const rule of gitignoreRules) {
+        if (rule.directoryOnly && !isDirectory) {
+            continue;
+        }
+
+        if (rule.baseDir && normalizedPath !== rule.baseDir && !normalizedPath.startsWith(`${rule.baseDir}/`)) {
+            continue;
+        }
+
+        const scopedPath = rule.baseDir
+            ? normalizedPath.slice(rule.baseDir.length).replace(/^\/+/, "")
+            : normalizedPath;
+        const pathParts = scopedPath.split("/");
+        const matches = rule.hasSlash
+            ? rule.regex.test(scopedPath)
+            : pathParts.some(part => rule.basenameRegex.test(part));
+
+        if (matches) {
+            ignored = !rule.negated;
+        }
+    }
+
+    return ignored;
+}
+
+export function parseLocalGitignore(fs, gitignorePath, baseDir = "") {
+    if (!fs.existsSync(gitignorePath)) {
+        return [];
+    }
+
+    return parseGitignoreContent(fs.readFileSync(gitignorePath, "utf-8"), baseDir);
+}
+
+export function buildLocalFileTree(fs, path, dirPath, rootDir = dirPath, inheritedGitignoreRules = [], depth = 0, maxDepth = 3) {
+    if (depth >= maxDepth) {
+        return {};
+    }
+
+    const relativeDir = path.relative(rootDir, dirPath).replace(/\\/g, "/");
+    const localGitignoreRules = parseLocalGitignore(
+        fs,
+        path.join(dirPath, ".gitignore"),
+        relativeDir === "" ? "" : relativeDir
+    );
+    const gitignoreRules = [...inheritedGitignoreRules, ...localGitignoreRules];
+    const tree = {};
+    const entries = fs.readdirSync(dirPath, { withFileTypes: true })
+        .filter(entry => {
+            if (DEFAULT_IGNORED_NAMES.has(entry.name)) {
+                return false;
+            }
+
+            const entryPath = path.join(dirPath, entry.name);
+            const relativePath = path.relative(rootDir, entryPath);
+
+            return !isIgnoredByGitignore(relativePath, entry.isDirectory(), gitignoreRules);
+        })
+        .sort((left, right) => left.name.localeCompare(right.name));
+
+    for (const entry of entries) {
+        const entryPath = path.join(dirPath, entry.name);
+
+        if (entry.isDirectory()) {
+            tree[entry.name] = buildLocalFileTree(fs, path, entryPath, rootDir, gitignoreRules, depth + 1, maxDepth);
+        } else {
+            tree[entry.name] = null;
+        }
+    }
+
+    return tree;
+}
+
+export function buildRemoteFileTree(treeData, gitignoreRules = [], maxDepth = 3) {
+    const fileTree = {};
+
+    if (!treeData?.tree || !Array.isArray(treeData.tree)) {
+        return fileTree;
+    }
+
+    for (const item of treeData.tree) {
+        const parts = item.path.split("/");
+        const name = parts[parts.length - 1];
+        const isDirectory = item.type === "tree";
+
+        if (DEFAULT_IGNORED_NAMES.has(name) || isIgnoredByGitignore(item.path, isDirectory, gitignoreRules)) {
+            continue;
+        }
+
+        if (parts.length > maxDepth) {
+            continue;
+        }
+
+        let current = fileTree;
+
+        for (let index = 0; index < parts.length; index += 1) {
+            const part = parts[index];
+            const isFile = index === parts.length - 1 && item.type === "blob";
+
+            if (isFile) {
+                current[part] = null;
+            } else {
+                if (!current[part]) {
+                    current[part] = {};
+                }
+                current = current[part];
+            }
+        }
+    }
+
+    return fileTree;
+}

package/src/index.js

@@ -1,73 +0,0 @@
-import getDefaultContent from "./template.js";
-import { detectProjectType } from "./projectReader.js";
-
-export function generateReadme(input = {}) {
-    const {
-        readmeContent = "",
-        packageJson = null,
-        fileTree = null,
-        username = "Unknown",
-        projectName = null,
-        hasPackageJson = false,
-        hasRequirementsTxt = false
-    } = input ?? {};
-
-    const resolvedProjectName = projectName || packageJson?.name || "this project";
-
-    const context = {
-        packageJson,
-        fileTree,
-        username,
-        projectName: resolvedProjectName,
-        hasPackageJson,
-        hasRequirementsTxt
-    };
-
-    const projectType = detectProjectType(context);
-
-    // parse existing readme into sections
-    const sections = (readmeContent || "").split("## ");
-    const sectionMap = {};
-    const intro = sections[0].trim();
-
-    sections.slice(1).forEach(section => {
-        const lines = section.split("\n");
-        const title = lines[0].trim().toLowerCase();
-        const content = lines.slice(1).join("\n").trim();
-        sectionMap[title] = content;
-    });
-
-    const requiredSections = ["description", "installation", "usage", "dependencies", "folder structure", "built by"];
-    const autoManagedSections = ["installation", "usage", "dependencies", "folder structure"];
-
-    // fill in missing sections or update auto-managed ones
-    requiredSections.forEach(section => {
-        const newContent = getDefaultContent(section, projectType, context);
-        if (!(section in sectionMap)) {
-            sectionMap[section] = newContent;
-        } else if (autoManagedSections.includes(section) && sectionMap[section].trim() !== newContent.trim()) {
-            sectionMap[section] = newContent;
-        }
-    });
-
-    const formatTitle = title => title.split(" ").map(w => w[0].toUpperCase() + w.slice(1)).join(" ");
-
-    // build the final readme
-    let newReadme = intro ? intro + "\n\n" : "";
-    requiredSections.forEach(section => {
-        newReadme += `## ${formatTitle(section)}\n${sectionMap[section]}\n\n`;
-    });
-
-    // append any extra sections the user had
-    Object.keys(sectionMap).forEach(section => {
-        if (!requiredSections.includes(section)) {
-            newReadme += `## ${formatTitle(section)}\n\n ${sectionMap[section]}\n\n`;
-        }
-    });
-
-    return { content: newReadme, changed: readmeContent !== newReadme };
-}
-
-export { detectProjectType } from "./projectReader.js";
-export { default as getDefaultContent } from "./template.js";
-export { default as getProjectStructure } from "./fileTree.js";

package/src/projectReader.js

@@ -1,5 +0,0 @@
-export function detectProjectType(context) {
-    if (context?.hasPackageJson) return "node";
-    if (context?.hasRequirementsTxt) return "python";
-    return "unknown";
-}