@fredlackey/devutils 0.0.18 → 0.1.0

package/src/commands/ignore/add.js

@@ -0,0 +1,165 @@
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const { MARKER_START, MARKER_END } = require('./markers');
+
+const meta = {
+  description: 'Add gitignore patterns for a technology',
+  arguments: [
+    { name: 'technology', description: 'Technology name (e.g., node, macos, docker)', required: true }
+  ],
+  flags: [
+    { name: 'path', description: 'Target directory (defaults to current directory)', type: 'string', default: '.' }
+  ]
+};
+
+/**
+ * Resolves the absolute path to a pattern file for a given technology.
+ * Uses __dirname so the path is relative to the installed package, not the
+ * user's working directory.
+ *
+ * @param {string} technology - Technology name (e.g., 'node').
+ * @returns {string} Absolute path to the pattern file.
+ */
+function getPatternFilePath(technology) {
+  return path.resolve(__dirname, '../../patterns/gitignore', `${technology}.txt`);
+}
+
+/**
+ * Adds gitignore patterns for a technology to the .gitignore in the target
+ * directory. If the section already exists, it is replaced in place (idempotent).
+ * If the .gitignore does not exist, it is created.
+ *
+ * @param {object} args - Parsed command arguments ({ positional, flags }).
+ * @param {object} context - The DevUtils context object.
+ */
+async function run(args, context) {
+  const technology = args.positional[0];
+
+  // Validate: technology name is required
+  if (!technology) {
+    context.errors.throwError(400, 'Missing required argument: <technology>. Example: dev ignore add node', 'ignore');
+    return;
+  }
+
+  // Step A: Validate the technology name and read the pattern file
+  const patternFilePath = getPatternFilePath(technology);
+  if (!fs.existsSync(patternFilePath)) {
+    context.errors.throwError(404, `Unknown technology "${technology}". Run "dev ignore list" to see available options.`, 'ignore');
+    return;
+  }
+
+  const patternContent = fs.readFileSync(patternFilePath, 'utf8').trimEnd();
+
+  // Step B: Resolve the target .gitignore path
+  const flagPath = args.flags.path || '.';
+  const gitignorePath = path.resolve(flagPath, '.gitignore');
+
+  // Step C: Read existing .gitignore or start empty
+  let existingContent = '';
+  let fileExists = false;
+  if (fs.existsSync(gitignorePath)) {
+    existingContent = fs.readFileSync(gitignorePath, 'utf8');
+    fileExists = true;
+  }
+
+  // Step D: Build the new section
+  const section = [
+    MARKER_START(technology),
+    patternContent,
+    MARKER_END(technology)
+  ].join('\n');
+
+  // Step E: Check if the section already exists
+  const lines = existingContent.split(/\r?\n/);
+  const startMarker = MARKER_START(technology);
+  const endMarker = MARKER_END(technology);
+  const startIndex = lines.findIndex(line => line.trim() === startMarker);
+  const endIndex = lines.findIndex(line => line.trim() === endMarker);
+
+  let updatedContent;
+  let action;
+
+  if (startIndex !== -1 && endIndex !== -1 && endIndex > startIndex) {
+    // Both markers found: replace the existing section in place
+    const before = lines.slice(0, startIndex);
+    const after = lines.slice(endIndex + 1);
+    const sectionLines = section.split('\n');
+    const newLines = [...before, ...sectionLines, ...after];
+    updatedContent = newLines.join('\n');
+    action = 'updated';
+  } else if (startIndex !== -1 || endIndex !== -1) {
+    // Only one marker found: corrupted state. Warn and append.
+    if (!context.flags.quiet) {
+      context.output.info(`Warning: Found partial markers for "${technology}" in .gitignore. Appending new section at end.`);
+    }
+    updatedContent = existingContent;
+    // Ensure a blank line before the new section
+    if (updatedContent.length > 0 && !updatedContent.endsWith('\n\n') && !updatedContent.endsWith('\n')) {
+      updatedContent += '\n';
+    }
+    if (updatedContent.length > 0 && !updatedContent.endsWith('\n\n')) {
+      updatedContent += '\n';
+    }
+    updatedContent += section;
+    action = 'added';
+  } else {
+    // No markers found: fresh add, append to end
+    updatedContent = existingContent;
+    // Step F: Ensure a blank line before the new section
+    if (updatedContent.length > 0) {
+      if (!updatedContent.endsWith('\n')) {
+        updatedContent += '\n';
+      }
+      if (!updatedContent.endsWith('\n\n')) {
+        updatedContent += '\n';
+      }
+    }
+    updatedContent += section;
+    action = 'added';
+  }
+
+  // Make sure the file ends with a trailing newline
+  if (!updatedContent.endsWith('\n')) {
+    updatedContent += '\n';
+  }
+
+  // Count pattern lines (lines between markers, not including markers)
+  const sectionLines = section.split('\n');
+  const patternLineCount = sectionLines.length - 2; // minus start and end markers
+
+  // Step G: Handle --dry-run
+  if (context.flags.dryRun) {
+    if (context.flags.format === 'json') {
+      context.output.out({
+        technology,
+        action,
+        path: gitignorePath,
+        lines: patternLineCount,
+        dryRun: true
+      });
+    } else {
+      context.output.info(`[dry-run] Would have ${action} ${technology} patterns in ${gitignorePath} (${patternLineCount} lines)`);
+    }
+    return;
+  }
+
+  // Step G: Write the result
+  fs.writeFileSync(gitignorePath, updatedContent);
+
+  // Step H: Output the result
+  if (context.flags.format === 'json') {
+    context.output.out({
+      technology,
+      action,
+      path: gitignorePath,
+      lines: patternLineCount
+    });
+  } else {
+    const verb = action === 'updated' ? 'Updated' : 'Added';
+    context.output.info(`${verb} ${technology} patterns ${action === 'updated' ? 'in' : 'to'} .gitignore`);
+  }
+}
+
+module.exports = { meta, run };

package/src/commands/ignore/index.js

@@ -0,0 +1,14 @@
+/**
+ * Ignore service registration.
+ * .gitignore pattern management.
+ */
+module.exports = {
+  name: 'ignore',
+  description: '.gitignore pattern management',
+  commands: {
+    add:    () => require('./add'),
+    remove: () => require('./remove'),
+    list:   () => require('./list'),
+    show:   () => require('./show'),
+  }
+};

package/src/commands/ignore/list.js

@@ -0,0 +1,89 @@
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+
+const meta = {
+  description: 'List available gitignore pattern technologies',
+  arguments: [],
+  flags: []
+};
+
+/**
+ * Returns the absolute path to the gitignore patterns directory.
+ * Uses __dirname so the path is relative to the installed package.
+ *
+ * @returns {string} Absolute path to the patterns directory.
+ */
+function getPatternsDir() {
+  return path.resolve(__dirname, '../../patterns/gitignore');
+}
+
+/**
+ * Lists all available gitignore pattern technologies by scanning the
+ * patterns directory. Each .txt file represents one technology. The
+ * technology name is the filename without the .txt extension.
+ *
+ * @param {object} args - Parsed command arguments ({ positional, flags }).
+ * @param {object} context - The DevUtils context object.
+ */
+async function run(args, context) {
+  const patternsDir = getPatternsDir();
+
+  // Step A: Read the patterns directory
+  if (!fs.existsSync(patternsDir)) {
+    context.errors.throwError(500, 'Patterns directory not found. The DevUtils installation may be corrupted.', 'ignore');
+    return;
+  }
+
+  const files = fs.readdirSync(patternsDir)
+    .filter(f => f.endsWith('.txt'))
+    .sort();
+
+  if (files.length === 0) {
+    context.errors.throwError(500, 'No pattern files found. The DevUtils installation may be corrupted.', 'ignore');
+    return;
+  }
+
+  // Step B: Read the first comment line from each file as a description
+  const technologies = files.map(file => {
+    const name = file.replace(/\.txt$/, '');
+    let description = name;
+
+    try {
+      const content = fs.readFileSync(path.join(patternsDir, file), 'utf8');
+      const firstLine = content.split(/\r?\n/)[0];
+      if (firstLine && firstLine.startsWith('# ')) {
+        description = firstLine.slice(2).trim();
+      }
+    } catch {
+      // If we can't read the file, fall back to the name
+    }
+
+    return { name, description };
+  });
+
+  // Step C: Build the result
+  const result = {
+    technologies,
+    count: technologies.length
+  };
+
+  // Step D: Format the output
+  if (context.flags.format === 'json') {
+    context.output.out(result);
+  } else {
+    // Calculate padding for aligned columns
+    const maxNameLength = Math.max(...technologies.map(t => t.name.length));
+
+    context.output.info('Available technologies:');
+    for (const tech of technologies) {
+      const paddedName = tech.name.padEnd(maxNameLength + 2);
+      context.output.info(`  ${paddedName}${tech.description}`);
+    }
+    context.output.info('');
+    context.output.info('Use "dev ignore add <technology>" to add patterns to .gitignore.');
+  }
+}
+
+module.exports = { meta, run };

package/src/commands/ignore/markers.js

@@ -0,0 +1,43 @@
+'use strict';
+
+/**
+ * Shared marker constants for DevUtils-managed .gitignore sections.
+ *
+ * These markers wrap each technology's patterns so that the ignore commands
+ * can identify, replace, and remove sections without disturbing manually
+ * added patterns. The format is:
+ *
+ *   # >>> devutils:<name>
+ *   ... patterns ...
+ *   # <<< devutils:<name>
+ *
+ * @module commands/ignore/markers
+ */
+
+/**
+ * Returns the start marker for a given technology name.
+ * @param {string} name - Technology name (e.g., 'node', 'macos').
+ * @returns {string} The start marker line.
+ */
+const MARKER_START = (name) => `# >>> devutils:${name}`;
+
+/**
+ * Returns the end marker for a given technology name.
+ * @param {string} name - Technology name (e.g., 'node', 'macos').
+ * @returns {string} The end marker line.
+ */
+const MARKER_END = (name) => `# <<< devutils:${name}`;
+
+/**
+ * The prefix used to identify start markers when parsing .gitignore files.
+ * @type {string}
+ */
+const MARKER_START_PREFIX = '# >>> devutils:';
+
+/**
+ * The prefix used to identify end markers when parsing .gitignore files.
+ * @type {string}
+ */
+const MARKER_END_PREFIX = '# <<< devutils:';
+
+module.exports = { MARKER_START, MARKER_END, MARKER_START_PREFIX, MARKER_END_PREFIX };

package/src/commands/ignore/remove.js

@@ -0,0 +1,164 @@
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const { MARKER_START, MARKER_END } = require('./markers');
+
+const meta = {
+  description: 'Remove managed gitignore patterns for a technology',
+  arguments: [
+    { name: 'technology', description: 'Technology name to remove (e.g., node, macos)', required: true }
+  ],
+  flags: [
+    { name: 'path', description: 'Target directory (defaults to current directory)', type: 'string', default: '.' }
+  ]
+};
+
+/**
+ * Removes a DevUtils-managed section from the .gitignore in the target
+ * directory. If the section does not exist, this is a no-op (idempotent).
+ * If removing the section leaves the file empty, the file is deleted.
+ *
+ * @param {object} args - Parsed command arguments ({ positional, flags }).
+ * @param {object} context - The DevUtils context object.
+ */
+async function run(args, context) {
+  const technology = args.positional[0];
+
+  // Validate: technology name is required
+  if (!technology) {
+    context.errors.throwError(400, 'Missing required argument: <technology>. Example: dev ignore remove node', 'ignore');
+    return;
+  }
+
+  // Step A: Resolve the .gitignore path
+  const flagPath = args.flags.path || '.';
+  const gitignorePath = path.resolve(flagPath, '.gitignore');
+
+  // Step B: Read existing .gitignore
+  if (!fs.existsSync(gitignorePath)) {
+    if (context.flags.format === 'json') {
+      context.output.out({
+        technology,
+        action: 'none',
+        message: `No .gitignore found at ${path.resolve(flagPath)}.`
+      });
+    } else {
+      context.output.info(`No .gitignore found at ${path.resolve(flagPath)}.`);
+    }
+    return;
+  }
+
+  const existingContent = fs.readFileSync(gitignorePath, 'utf8');
+
+  // Step C: Find the section markers
+  const lines = existingContent.split(/\r?\n/);
+  const startMarker = MARKER_START(technology);
+  const endMarker = MARKER_END(technology);
+  const startIndex = lines.findIndex(line => line.trim() === startMarker);
+  const endIndex = lines.findIndex(line => line.trim() === endMarker);
+
+  if (startIndex === -1 && endIndex === -1) {
+    // Section not present: no-op
+    if (context.flags.format === 'json') {
+      context.output.out({
+        technology,
+        action: 'none',
+        message: `No managed section for "${technology}" found in .gitignore.`
+      });
+    } else {
+      context.output.info(`No managed section for "${technology}" found in .gitignore.`);
+    }
+    return;
+  }
+
+  if (startIndex === -1 || endIndex === -1 || endIndex <= startIndex) {
+    // Only one marker found or end before start: corrupted state
+    context.output.info(`Warning: Found partial or corrupted markers for "${technology}" in .gitignore. Please fix manually.`);
+    return;
+  }
+
+  // Step D: Remove the section (start through end marker, inclusive)
+  const before = lines.slice(0, startIndex);
+  let after = lines.slice(endIndex + 1);
+
+  // Clean up one trailing blank line after the end marker
+  if (after.length > 0 && after[0].trim() === '') {
+    after = after.slice(1);
+  }
+
+  let newLines = [...before, ...after];
+
+  // Build the updated content
+  let updatedContent = newLines.join('\n');
+
+  // Step E: If the file is now empty (only whitespace), delete it
+  if (updatedContent.trim() === '') {
+    if (context.flags.dryRun) {
+      if (context.flags.format === 'json') {
+        context.output.out({
+          technology,
+          action: 'removed',
+          path: gitignorePath,
+          fileDeleted: true,
+          dryRun: true
+        });
+      } else {
+        context.output.info(`[dry-run] Would remove ${technology} patterns from .gitignore and delete the empty file`);
+      }
+      return;
+    }
+
+    fs.unlinkSync(gitignorePath);
+
+    if (context.flags.format === 'json') {
+      context.output.out({
+        technology,
+        action: 'removed',
+        path: gitignorePath,
+        fileDeleted: true
+      });
+    } else {
+      context.output.info(`Removed ${technology} patterns from .gitignore (file deleted -- was empty)`);
+    }
+    return;
+  }
+
+  // Make sure the file ends with a trailing newline
+  if (!updatedContent.endsWith('\n')) {
+    updatedContent += '\n';
+  }
+
+  // Handle --dry-run
+  if (context.flags.dryRun) {
+    if (context.flags.format === 'json') {
+      context.output.out({
+        technology,
+        action: 'removed',
+        path: gitignorePath,
+        fileDeleted: false,
+        dryRun: true
+      });
+    } else {
+      context.output.info(`[dry-run] Would remove ${technology} patterns from .gitignore`);
+    }
+    return;
+  }
+
+  // Step E: Write the result
+  fs.writeFileSync(gitignorePath, updatedContent);
+
+  // Step F: Output the result
+  if (context.flags.format === 'json') {
+    context.output.out({
+      technology,
+      action: 'removed',
+      path: gitignorePath,
+      fileDeleted: false
+    });
+  } else {
+    context.output.info(`Removed ${technology} patterns from .gitignore`);
+  }
+}
+
+module.exports = { meta, run };

package/src/commands/ignore/show.js

@@ -0,0 +1,169 @@
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const { MARKER_START_PREFIX, MARKER_END_PREFIX } = require('./markers');
+
+const meta = {
+  description: 'Show managed gitignore sections in the current directory',
+  arguments: [],
+  flags: [
+    { name: 'path', description: 'Target directory (defaults to current directory)', type: 'string', default: '.' }
+  ]
+};
+
+/**
+ * Scans the .gitignore in the target directory and reports which
+ * DevUtils-managed sections are present, including the technology name,
+ * pattern line count, and line range for each section. Also counts
+ * unmanaged lines (lines outside any DevUtils section that are not blank
+ * or comments).
+ *
+ * @param {object} args - Parsed command arguments ({ positional, flags }).
+ * @param {object} context - The DevUtils context object.
+ */
+async function run(args, context) {
+  // Step A: Resolve the .gitignore path
+  const flagPath = args.flags.path || '.';
+  const gitignorePath = path.resolve(flagPath, '.gitignore');
+
+  // Step B: Read the file
+  if (!fs.existsSync(gitignorePath)) {
+    if (context.flags.format === 'json') {
+      context.output.out({
+        path: gitignorePath,
+        sections: [],
+        count: 0,
+        unmanagedLines: 0,
+        message: `No .gitignore found at ${path.resolve(flagPath)}.`
+      });
+    } else {
+      context.output.info(`No .gitignore found at ${path.resolve(flagPath)}.`);
+    }
+    return;
+  }
+
+  const content = fs.readFileSync(gitignorePath, 'utf8');
+  const lines = content.split(/\r?\n/);
+
+  // Step C: Parse managed sections
+  const sections = [];
+  const managedLineIndices = new Set();
+  let i = 0;
+
+  while (i < lines.length) {
+    const trimmedLine = lines[i].trim();
+
+    if (trimmedLine.startsWith(MARKER_START_PREFIX)) {
+      // Found a start marker -- extract the technology name
+      const technology = trimmedLine.slice(MARKER_START_PREFIX.length);
+      const startLine = i + 1; // 1-indexed
+      managedLineIndices.add(i);
+
+      // Find the corresponding end marker
+      const expectedEnd = `# <<< devutils:${technology}`;
+      let endIdx = -1;
+
+      for (let j = i + 1; j < lines.length; j++) {
+        if (lines[j].trim() === expectedEnd) {
+          endIdx = j;
+          break;
+        }
+      }
+
+      if (endIdx !== -1) {
+        // Mark all lines in this section as managed
+        for (let k = i; k <= endIdx; k++) {
+          managedLineIndices.add(k);
+        }
+
+        const patternLineCount = endIdx - i - 1; // lines between markers
+        const endLine = endIdx + 1; // 1-indexed
+
+        sections.push({
+          technology,
+          lines: patternLineCount,
+          startLine,
+          endLine
+        });
+
+        i = endIdx + 1;
+      } else {
+        // Orphaned start marker -- no matching end
+        sections.push({
+          technology,
+          lines: null,
+          startLine,
+          endLine: null,
+          error: 'Missing end marker'
+        });
+        i++;
+      }
+    } else if (trimmedLine.startsWith(MARKER_END_PREFIX)) {
+      // Orphaned end marker -- no matching start
+      const technology = trimmedLine.slice(MARKER_END_PREFIX.length);
+      managedLineIndices.add(i);
+      sections.push({
+        technology,
+        lines: null,
+        startLine: null,
+        endLine: i + 1, // 1-indexed
+        error: 'Missing start marker'
+      });
+      i++;
+    } else {
+      i++;
+    }
+  }
+
+  // Step D: Count unmanaged lines (not blank, not comments, not in a section)
+  let unmanagedLines = 0;
+  for (let idx = 0; idx < lines.length; idx++) {
+    if (managedLineIndices.has(idx)) continue;
+    const trimmed = lines[idx].trim();
+    if (trimmed === '') continue;
+    if (trimmed.startsWith('#')) continue;
+    unmanagedLines++;
+  }
+
+  // Step E: Build the result
+  const result = {
+    path: gitignorePath,
+    sections,
+    count: sections.length,
+    unmanagedLines
+  };
+
+  // Step F: Format the output
+  if (context.flags.format === 'json') {
+    context.output.out(result);
+  } else {
+    if (sections.length === 0) {
+      context.output.info('No DevUtils-managed sections found in .gitignore.');
+    } else {
+      // Calculate padding for aligned columns
+      const maxNameLength = Math.max(...sections.map(s => s.technology.length));
+      const maxLinesLength = Math.max(...sections.map(s => s.lines !== null ? String(s.lines).length : 1));
+
+      context.output.info('Managed sections in .gitignore:');
+      for (const section of sections) {
+        if (section.error) {
+          const paddedName = section.technology.padEnd(maxNameLength + 2);
+          context.output.info(`  ${paddedName}[${section.error}]`);
+        } else {
+          const paddedName = section.technology.padEnd(maxNameLength + 2);
+          const paddedLines = String(section.lines).padStart(maxLinesLength);
+          context.output.info(`  ${paddedName}${paddedLines} patterns  (lines ${section.startLine}-${section.endLine})`);
+        }
+      }
+      context.output.info('');
+      context.output.info(`${sections.length} managed section${sections.length === 1 ? '' : 's'}.`);
+    }
+
+    if (unmanagedLines > 0) {
+      context.output.info(`Plus ${unmanagedLines} unmanaged line${unmanagedLines === 1 ? '' : 's'}.`);
+    }
+  }
+}
+
+module.exports = { meta, run };