@fredlackey/devutils 0.0.18 → 0.1.0

package/src/utils/git-status/unix.sh

@@ -0,0 +1,75 @@
+#!/bin/bash
+# git-status: Scan directory for git repos and show status summary
+
+TARGET_DIR="${1:-.}"
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
+CYAN='\033[0;36m'
+NC='\033[0m'  # No Color
+BOLD='\033[1m'
+
+# Find git repos (immediate subdirectories with .git folders)
+for dir in "$TARGET_DIR"/*/; do
+  if [ ! -d "$dir/.git" ]; then
+    continue
+  fi
+
+  repo_name=$(basename "$dir")
+
+  # Get branch name
+  branch=$(git -C "$dir" symbolic-ref --short HEAD 2>/dev/null)
+  if [ -z "$branch" ]; then
+    branch="detached"
+  fi
+
+  # Get dirty file count
+  dirty_count=$(git -C "$dir" status --porcelain 2>/dev/null | wc -l | tr -d ' ')
+
+  # Get stash count
+  stash_count=$(git -C "$dir" stash list 2>/dev/null | wc -l | tr -d ' ')
+
+  # Get ahead/behind counts
+  ahead=0
+  behind=0
+  tracking=$(git -C "$dir" rev-parse --abbrev-ref '@{upstream}' 2>/dev/null)
+  if [ -n "$tracking" ]; then
+    counts=$(git -C "$dir" rev-list --left-right --count HEAD...'@{upstream}' 2>/dev/null)
+    if [ -n "$counts" ]; then
+      ahead=$(echo "$counts" | awk '{print $1}')
+      behind=$(echo "$counts" | awk '{print $2}')
+    fi
+  fi
+
+  # Determine color based on status
+  color="$GREEN"
+  if [ "$dirty_count" -gt 0 ]; then
+    color="$YELLOW"
+  fi
+  if [ "$behind" -gt 0 ]; then
+    color="$RED"
+  fi
+
+  # Build status string
+  status_parts=""
+  if [ "$dirty_count" -gt 0 ]; then
+    status_parts="${status_parts} ${YELLOW}${dirty_count} dirty${NC}"
+  fi
+  if [ "$ahead" -gt 0 ]; then
+    status_parts="${status_parts} ${GREEN}+${ahead}${NC}"
+  fi
+  if [ "$behind" -gt 0 ]; then
+    status_parts="${status_parts} ${RED}-${behind}${NC}"
+  fi
+  if [ "$stash_count" -gt 0 ]; then
+    status_parts="${status_parts} ${CYAN}${stash_count} stash${NC}"
+  fi
+  if [ -z "$status_parts" ]; then
+    status_parts=" ${GREEN}clean${NC}"
+  fi
+
+  # Print the line
+  printf "${color}${BOLD}%-30s${NC} ${CYAN}%-20s${NC}%s\n" "$repo_name" "$branch" "$status_parts"
+done

package/src/utils/registry.json

@@ -0,0 +1,41 @@
+{
+  "_comment": "Built-in utility metadata. Name, description, supported platforms, and arguments for each utility.",
+  "utilities": [
+    {
+      "name": "git-status",
+      "description": "Scan directories for git repos and show a color-coded status summary",
+      "type": "built-in",
+      "platforms": ["macos", "ubuntu", "raspbian", "amazon-linux", "windows", "gitbash"],
+      "arguments": [
+        { "name": "path", "required": false, "description": "Directory to scan (defaults to current directory)" }
+      ],
+      "flags": [
+        { "name": "depth", "type": "number", "description": "How many levels deep to scan for repos (default: 1)" }
+      ]
+    },
+    {
+      "name": "clone",
+      "description": "Clone a git repo and auto-install dependencies using the detected package manager",
+      "type": "built-in",
+      "platforms": ["macos", "ubuntu", "raspbian", "amazon-linux", "windows", "gitbash"],
+      "arguments": [
+        { "name": "url", "required": true, "description": "Git repository URL (SSH or HTTPS)" },
+        { "name": "directory", "required": false, "description": "Target directory name (defaults to repo name)" }
+      ],
+      "flags": []
+    },
+    {
+      "name": "git-push",
+      "description": "Safer git push: shows what will be pushed, confirms before pushing, and protects main/master",
+      "type": "built-in",
+      "platforms": ["macos", "ubuntu", "raspbian", "amazon-linux", "windows", "gitbash"],
+      "arguments": [
+        { "name": "message", "required": true, "description": "Commit message" }
+      ],
+      "flags": [
+        { "name": "force", "type": "boolean", "description": "Allow pushing to protected branches" },
+        { "name": "yes", "type": "boolean", "description": "Skip confirmation prompt" }
+      ]
+    }
+  ]
+}

package/bin/dev.js

@@ -1,16 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * @fileoverview Main entry point for the `dev` CLI command.
- * This file handles tab completion detection and delegates to the CLI module.
- */
-
-// Handle tab completion before loading the full CLI
-// This allows for fast completion responses
-if (process.env.COMP_LINE) {
-  require('../src/completion').handleCompletion();
-  process.exit(0);
-}
-
-// Normal CLI execution
-require('../src/cli').run();

package/files/claude/.claude/commands/setup-context.md

@@ -1,3 +0,0 @@
-Read the following files for context:
-- README.md
-- CLAUDE.md

package/files/monorepos/_archive/README.md

@@ -1,36 +0,0 @@
-# Archive
-
-**DO NOT READ OR MODIFY CONTENTS OF THIS FOLDER.**
-
-## Purpose
-
-This folder is a **failsafe backup**—a last resort for code and resources that may need to be referenced in rare circumstances. Think of it as a "soft delete" before permanent removal.
-
-## Critical Warnings
-
-- **Nothing in this folder should be trusted as correct**
-- Contents are outdated, deprecated, or potentially broken
-- Code here has been replaced by better implementations elsewhere
-- Documentation may be inaccurate or misleading
-
-## AI Instructions
-
-**This folder must be ignored by all AI processes:**
-- Do NOT read files from this folder
-- Do NOT reference code or patterns found here
-- Do NOT modify or update any contents
-- Do NOT use this folder as a source of truth for anything
-
-## What Belongs Here
-
-- Deprecated code kept only as an emergency reference
-- Old implementations preserved before deletion
-- Retired features that might need forensic review
-- Anything we're not ready to permanently delete
-
-## Guidelines
-
-- Date items when archiving (use folder names like `YYYYMMDD/`)
-- Include a brief note explaining why the item was archived
-- Never actively maintain or improve archived code
-- Periodically review and permanently delete obsolete items

package/files/monorepos/_legacy/README.md

@@ -1,36 +0,0 @@
-# Legacy
-
-**CONTENTS SHOULD NOT BE TRUSTED. USE WITH CAUTION.**
-
-## Purpose
-
-This folder contains **previous attempts** at building the same concepts, packages, or even the entire project. Think of it as the "last version" or "last attempt" before the current rebuild.
-
-We keep this code for reference, but if we're rebuilding, it's for a reason:
-
-- **A)** We learned enough about the problem and now want to do it properly
-- **B)** We failed completely and need to start over, but want to remember our mistakes
-
-This folder is one step better than `/_archive`—we may occasionally refer to it—but it still should not be treated as a source of truth.
-
-## AI Instructions
-
-**Approach this folder with skepticism:**
-- Do NOT trust patterns or implementations found here
-- Do NOT copy code from this folder without explicit instruction
-- Do NOT use this as a reference for "how things should work"
-- Contents represent what we're moving *away from*, not toward
-
-## What Belongs Here
-
-- Previous iterations of the current project
-- Failed attempts preserved for learning
-- Old architectures we've outgrown
-- Code that "worked" but wasn't good enough
-
-## Guidelines
-
-- Note why the previous attempt was abandoned
-- Reference only when specifically trying to avoid past mistakes
-- Never improve or maintain legacy code—build new instead
-- Move to `/_archive` once the new implementation is stable and proven

package/files/monorepos/ai-docs/README.md

@@ -1,33 +0,0 @@
-# AI Docs
-
-This folder contains documentation **created by AI, for AI**.
-
-## Purpose
-
-A persistent knowledge base that preserves AI research, discoveries, and insights so they don't have to be repeated. When AI investigates a concept, researches a technique, or works through a problem, the findings are documented here for future reference.
-
-This eliminates redundant research and discovery processes across sessions.
-
-## Usage
-
-- AI writes documentation here after research or discovery work
-- AI reads from this folder to recall prior findings
-- Humans may reference content but it's optimized for AI consumption
-- Treat as a "memory" that persists between AI sessions
-
-## What Belongs Here
-
-- Research findings and conclusions
-- Technology evaluations and comparisons
-- Best practices and implementation patterns
-- Convention documentation and standards
-- Schema definitions
-- Brainstorming outcomes and design decisions
-- Concept explanations and technical deep-dives
-
-## Guidelines
-
-- Write in clear, structured formats AI can easily parse
-- Include context about why research was performed
-- Update documents as understanding evolves
-- Prefer comprehensive detail over brevity

package/files/monorepos/apps/README.md

@@ -1,24 +0,0 @@
-# Apps
-
-This folder contains the main applications for the project.
-
-## Purpose
-
-Each application in this folder represents a distinct, deployable unit—whether it's a frontend, backend API, admin tool, or other service. Applications are organized as separate subdirectories, each with their own dependencies and configuration.
-
-## Structure
-
-```
-apps/
-├── [app-name]-ui-[framework]/    # Frontend applications
-├── [app-name]-api-[framework]/   # Backend API services
-├── [app-name]-admin-[framework]/ # Admin tools
-└── ...
-```
-
-## Guidelines
-
-- Each application should be independently runnable
-- Applications may depend on shared code from `/packages`
-- Keep application-specific code within its subdirectory
-- Use consistent naming: `[project]-[type]-[framework]`

package/files/monorepos/docs/README.md

@@ -1,40 +0,0 @@
-# Docs
-
-This folder contains documentation **created by humans, for humans**.
-
-## Purpose
-
-The counterpart to `/ai-docs`—this folder holds documentation intended for human authors and human readers. Content here should be accessible, verbose enough for clarity, and written so that a junior developer or project manager can understand it.
-
-AI may assist with editing, formatting, or refining language, but the content is fundamentally human-focused.
-
-## Audience
-
-- Junior developers onboarding to the project
-- Project managers needing business context
-- Team members referencing technical decisions
-- External contributors or stakeholders
-
-## What Belongs Here
-
-- Architecture decision records (ADRs)
-- Setup and installation guides
-- API documentation and usage examples
-- Business logic explanations
-- Deployment and operations guides
-- Contributing guidelines
-- Project overviews and roadmaps
-
-## Guidelines
-
-- Write for clarity over brevity
-- Assume the reader may not have full context
-- Explain the "why" alongside the "what"
-- Use plain language; avoid unnecessary jargon
-- Include examples where helpful
-
-## What Does NOT Belong Here
-
-- AI-generated research or discovery docs (use `/ai-docs`)
-- Exploratory research materials (use `/research`)
-- Auto-generated API docs (keep with the relevant app)

package/files/monorepos/packages/README.md

@@ -1,25 +0,0 @@
-# Packages
-
-This folder contains shared libraries and utilities used across applications.
-
-## Purpose
-
-Packages are reusable code modules that provide common functionality to multiple applications in the monorepo. This promotes code reuse, consistency, and maintainability across the project.
-
-## Structure
-
-```
-packages/
-├── [project]-utils/     # Utility functions and helpers
-├── [project]-types/     # Shared type definitions
-├── [project]-config/    # Shared configuration
-└── ...
-```
-
-## Guidelines
-
-- Packages should be framework-agnostic when possible
-- Each package should have a single, well-defined responsibility
-- Packages are imported by applications in `/apps`
-- Keep packages small and focused
-- Document public APIs within each package

package/files/monorepos/research/README.md

@@ -1,29 +0,0 @@
-# Research
-
-This folder is a **workspace for reference artifacts**—often excluded from version control.
-
-## Purpose
-
-A staging area where developers can pull in external artifacts, code samples, documentation, or even entire repos from other sources. This keeps useful reference material close at hand without polluting the actual codebase.
-
-The goal: work within a single IDE while having access to everything you need.
-
-## Git Status
-
-This folder is **typically excluded from the repository** (added to `.gitignore`). Contents are meant to be temporary and local to each developer's environment. Don't assume anything here will persist or be shared.
-
-## What Belongs Here
-
-- Cloned repos for reference
-- Code samples from external sources
-- API documentation downloads
-- Third-party library source code
-- Screenshots, PDFs, or other reference materials
-- Anything useful for development that doesn't belong in the repo
-
-## Guidelines
-
-- Treat this folder as ephemeral and personal
-- Don't rely on contents being available to others
-- Clean up periodically—this isn't long-term storage
-- If findings are valuable, document them in `/ai-docs` or `/docs`

package/files/monorepos/scripts/README.md

@@ -1,24 +0,0 @@
-# Scripts
-
-This folder contains development, build, and operational scripts.
-
-## Purpose
-
-Utility scripts that automate common tasks across the monorepo. These scripts help with development workflows, builds, deployments, and maintenance operations.
-
-## What Belongs Here
-
-- Build and compilation scripts
-- Development environment setup
-- Database migration helpers
-- Deployment automation
-- Code generation tools
-- Maintenance and cleanup utilities
-
-## Guidelines
-
-- Make scripts executable (`chmod +x`)
-- Include usage comments at the top of each script
-- Use consistent naming conventions
-- Document any required environment variables
-- Keep scripts idempotent when possible

package/src/commands/README.md

@@ -1,41 +0,0 @@
-# Commands
-
-This folder contains the implementation logic for **Commands** — multi-word CLI operations invoked with the `dev` prefix.
-
-## Structure
-
-```
-dev <action> [subcommand] [arguments] [options]
-```
-
-## Examples
-
-```bash
-dev configure              # Configure developer profile
-dev status                 # Show current configuration
-dev install vscode         # Install VS Code
-dev ignore node            # Add Node.js patterns to .gitignore
-dev identity add           # Add a new identity profile
-dev identity remove        # Remove an identity profile
-dev identity link          # Link identity to a source folder
-```
-
-## Files
-
-| File | Command | Description |
-|------|---------|-------------|
-| `configure.js` | `dev configure` | Interactive configuration wizard |
-| `status.js` | `dev status` | Display current configuration |
-| `install.js` | `dev install <name>` | Install development tools |
-| `ignore.js` | `dev ignore <technology>` | Append patterns to .gitignore |
-| `identity.js` | `dev identity <action>` | Manage identity profiles (add, remove, link) |
-
-## Related
-
-- **Scripts** (`../scripts/`) — Standalone global utilities (e.g., `afk`, `clone`)
-- **Installs** (`../installs/`) — Platform-specific installation logic
-- **Utils** (`../utils/`) — Internal shared utilities
-
-## Documentation
-
-See [docs/COMMANDS.md](../../docs/COMMANDS.md) for the complete command specification.

package/src/commands/configure.js

@@ -1,199 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * @fileoverview Configure command - Create the initial .devutils configuration
- * file with user information.
- */
-
-const { Command } = require('commander');
-const fs = require('fs');
-const path = require('path');
-const readline = require('readline');
-
-const CONFIG_FILE = path.join(process.env.HOME || process.env.USERPROFILE, '.devutils');
-
-/**
- * Create readline interface for prompts
- * @returns {readline.Interface}
- */
-function createPrompt() {
-  return readline.createInterface({
-    input: process.stdin,
-    output: process.stdout
-  });
-}
-
-/**
- * Prompt user for input
- * @param {readline.Interface} rl - Readline interface
- * @param {string} question - Question to ask
- * @param {string} [defaultValue] - Default value if empty
- * @returns {Promise<string>}
- */
-function ask(rl, question, defaultValue) {
-  return new Promise(resolve => {
-    const prompt = defaultValue ? `${question} [${defaultValue}]: ` : `${question}: `;
-    rl.question(prompt, answer => {
-      resolve(answer.trim() || defaultValue || '');
-    });
-  });
-}
-
-/**
- * Prompt user for confirmation
- * @param {readline.Interface} rl - Readline interface
- * @param {string} question - Question to ask
- * @returns {Promise<boolean>}
- */
-function confirm(rl, question) {
-  return new Promise(resolve => {
-    rl.question(`${question} (y/n): `, answer => {
-      resolve(answer.toLowerCase().startsWith('y'));
-    });
-  });
-}
-
-/**
- * Load existing configuration
- * @returns {object|null}
- */
-function loadConfig() {
-  try {
-    if (fs.existsSync(CONFIG_FILE)) {
-      const content = fs.readFileSync(CONFIG_FILE, 'utf8');
-      return JSON.parse(content);
-    }
-  } catch (err) {
-    // Invalid JSON or read error
-  }
-  return null;
-}
-
-/**
- * Save configuration to file
- * @param {object} config - Configuration object
- */
-function saveConfig(config) {
-  fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + '\n');
-}
-
-/**
- * Display current configuration
- * @param {object} config - Configuration object
- */
-function displayConfig(config) {
-  console.log('\nCurrent Configuration:');
-  console.log('─'.repeat(40));
-
-  if (config.user) {
-    console.log('User:');
-    console.log(`  Name:  ${config.user.name || '(not set)'}`);
-    console.log(`  Email: ${config.user.email || '(not set)'}`);
-    console.log(`  URL:   ${config.user.url || '(not set)'}`);
-  }
-
-  console.log('\nConfig file:', CONFIG_FILE);
-  if (config.created) {
-    console.log(`Created:     ${new Date(config.created).toLocaleString()}`);
-  }
-  if (config.updated) {
-    console.log(`Updated:     ${new Date(config.updated).toLocaleString()}`);
-  }
-  console.log('');
-}
-
-/**
- * Run the configure command
- * @param {object} options - Command options
- */
-async function runConfigure(options) {
-  const existingConfig = loadConfig();
-
-  // Show existing config if requested
-  if (options.show) {
-    if (existingConfig) {
-      displayConfig(existingConfig);
-    } else {
-      console.log('\nNo configuration found.');
-      console.log(`Run 'dev configure' to create ${CONFIG_FILE}\n`);
-    }
-    return;
-  }
-
-  let name = options.name;
-  let email = options.email;
-  let url = options.url;
-
-  // If all required params provided via CLI, skip interactive mode
-  const hasAllRequired = name && email;
-
-  if (!hasAllRequired) {
-    // Check for existing config
-    if (existingConfig && !options.force) {
-      console.log('\nExisting configuration found:');
-      displayConfig(existingConfig);
-
-      const rl = createPrompt();
-      const shouldUpdate = await confirm(rl, 'Do you want to update this configuration?');
-      rl.close();
-
-      if (!shouldUpdate) {
-        console.log('Configuration unchanged.');
-        return;
-      }
-    }
-
-    const rl = createPrompt();
-
-    console.log('\n--- Developer Profile Setup ---\n');
-
-    // Get user information (use CLI args as defaults if provided)
-    name = await ask(rl, 'Name (required)', name || existingConfig?.user?.name);
-    if (!name) {
-      console.error('\nError: Name is required.');
-      rl.close();
-      process.exit(1);
-    }
-
-    email = await ask(rl, 'Email (required)', email || existingConfig?.user?.email);
-    if (!email) {
-      console.error('\nError: Email is required.');
-      rl.close();
-      process.exit(1);
-    }
-
-    url = await ask(rl, 'URL (optional)', url || existingConfig?.user?.url);
-
-    rl.close();
-  }
-
-  // Build config object
-  const now = new Date().toISOString();
-  const config = {
-    user: {
-      name,
-      email,
-      ...(url && { url })
-    },
-    created: existingConfig?.created || now,
-    updated: now
-  };
-
-  // Save configuration
-  saveConfig(config);
-
-  console.log(`\nConfiguration saved to ${CONFIG_FILE}`);
-  displayConfig(config);
-}
-
-// Create and configure the command
-const configure = new Command('configure')
-  .description('Configure developer profile and create ~/.devutils')
-  .option('--name <name>', 'Developer name')
-  .option('--email <email>', 'Developer email')
-  .option('--url <url>', 'Developer URL (optional)')
-  .option('--force', 'Overwrite existing config without prompting')
-  .option('-s, --show', 'Display current configuration')
-  .action(runConfigure);
-
-module.exports = configure;