@fredlackey/devutils 0.0.1

package/README.md

@@ -0,0 +1,156 @@
+# DevUtils CLI
+
+> **Early Development (v0.0.1)** — This project is currently a proof of concept. Core functionality is being built and tested. You're welcome to:
+> - Use it as-is and provide feedback
+> - Participate in development
+> - Watch for future releases (v0.1.0 for beta, v1.0.0 for stable)
+> - [Reach out](#contact) with questions or suggestions
+
+Stop wasting hours setting up new machines. One command, any platform, ready to code.
+
+## The Problem
+
+Every developer knows the pain:
+- New laptop? Spend a day installing tools and configuring dotfiles
+- Switch between work and personal projects? Juggle SSH keys and git configs
+- Help a teammate set up their environment? Walk them through 50 different steps
+- Work on macOS at home, Linux in prod? Remember two sets of commands
+
+## The Solution
+
+```bash
+npm install -g @fredlackey/devutils
+dev setup
+```
+
+That's it. DevUtils CLI detects your operating system and installs everything you need. Your configuration travels with you.
+
+## Installation
+
+```bash
+npm install -g @fredlackey/devutils
+```
+
+**Requirements:** Node.js 18+
+
+## Quick Start
+
+```bash
+# Install essential tools (git, ssh, gpg, etc.)
+dev setup
+
+# Set up your developer profile
+dev configure
+
+# Install your favorite tools
+dev install vscode
+dev install docker
+dev install node
+```
+
+## Key Features
+
+### Cross-Platform Package Installation
+
+Forget whether it's `brew install`, `apt-get install`, or `choco install`. Just run:
+
+```bash
+dev install docker
+dev install node
+dev install vscode
+```
+
+DevUtils CLI figures out the right command for macOS, Ubuntu, Debian, Amazon Linux, Fedora, or Windows.
+
+### Git Identity Management
+
+Manage multiple git identities for work, personal, and client projects:
+
+```bash
+# Create identities with SSH and GPG keys
+dev identity add work --email you@company.com
+dev identity add personal --email you@gmail.com
+
+# Link identities to folders - commits automatically use the right credentials
+dev identity link work ~/work
+dev identity link personal ~/personal https://github.com/yourusername
+```
+
+Clone with any URL format. DevUtils CLI routes it through the correct SSH key automatically.
+
+### Smart .gitignore Management
+
+```bash
+dev ignore node      # Add Node.js patterns
+dev ignore macos     # Add .DS_Store and friends
+dev ignore vscode    # Add .vscode/ patterns
+```
+
+Patterns are managed in sections—run it twice and it won't duplicate.
+
+### Portable Configuration
+
+Your `~/.devutils` file stores your preferences:
+
+```json
+{
+  "user": {
+    "name": "Jane Developer",
+    "email": "jane@example.com"
+  },
+  "identities": {
+    "work": { "email": "jane@company.com", "sshKey": "~/.ssh/id_ed25519_work" },
+    "personal": { "email": "jane@gmail.com", "sshKey": "~/.ssh/id_ed25519_personal" }
+  }
+}
+```
+
+Copy this file to a new machine and run `dev identity sync` to regenerate all your SSH configs.
+
+## Supported Platforms
+
+| Platform | Package Manager |
+|----------|-----------------|
+| macOS | Homebrew |
+| Ubuntu / Debian | APT |
+| Raspberry Pi OS | APT |
+| Amazon Linux / RHEL / Fedora | DNF / YUM |
+| Windows | Chocolatey / winget |
+| WSL | APT (with Windows integration) |
+
+## Available Commands
+
+| Command | Description |
+|---------|-------------|
+| `dev setup` | Install essential development tools |
+| `dev configure` | Set up your developer profile |
+| `dev install <tool>` | Install a tool (cross-platform) |
+| `dev identity add` | Create a new git identity with keys |
+| `dev identity link` | Link an identity to a folder or remote |
+| `dev identity unlink` | Remove a folder link |
+| `dev ignore <tech>` | Add .gitignore patterns |
+| `dev status` | Show current configuration |
+
+## Why DevUtils CLI?
+
+- **Zero memorization** — Same commands on every platform
+- **Identity isolation** — Never accidentally commit with the wrong email again
+- **Reproducible setups** — New machine? `dev setup && dev identity sync`
+- **No lock-in** — Standard tools, standard configs. Uninstall anytime
+
+## Contributing
+
+Contributions welcome! Feel free to open issues or submit pull requests.
+
+## Contact
+
+Questions, suggestions, or just want to chat about the project?
+
+**Fred Lackey**
+- Email: [fred.lackey@gmail.com](mailto:fred.lackey@gmail.com)
+- Website: [fredlackey.com](https://fredlackey.com)
+- GitHub: [@FredLackey](https://github.com/FredLackey)
+
+## License
+
+Apache-2.0

package/bin/dev.js

@@ -0,0 +1,16 @@
+#!/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

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

package/files/monorepos/_archive/README.md

@@ -0,0 +1,36 @@
+# 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

@@ -0,0 +1,36 @@
+# 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

@@ -0,0 +1,33 @@
+# 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

@@ -0,0 +1,24 @@
+# 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

@@ -0,0 +1,40 @@
+# 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

@@ -0,0 +1,25 @@
+# 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

@@ -0,0 +1,29 @@
+# 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

@@ -0,0 +1,24 @@
+# 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/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@fredlackey/devutils",
+  "version": "0.0.1",
+  "description": "A globally-installable Node.js CLI toolkit for bootstrapping and configuring development environments across any machine.",
+  "main": "src/index.js",
+  "bin": {
+    "dev": "./bin/dev.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "files/"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "dependencies": {
+    "commander": "^12.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FredLackey/devutils-cli.git"
+  },
+  "keywords": [],
+  "author": {
+    "name": "Fred Lackey",
+    "email": "fred.lackey@gmail.com",
+    "url": "https://fredlackey.com"
+  },
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "commonjs",
+  "bugs": {
+    "url": "https://github.com/FredLackey/devutils-cli/issues"
+  },
+  "homepage": "https://github.com/FredLackey/devutils-cli#readme"
+}

package/src/cli.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+
+/**
+ * @fileoverview CLI setup using Commander.js
+ * Registers all commands and handles program execution.
+ */
+
+const { program } = require('commander');
+const pkg = require('../package.json');
+
+const configureCommand = require('./commands/configure');
+const statusCommand = require('./commands/status');
+const identityCommand = require('./commands/identity');
+const ignoreCommand = require('./commands/ignore');
+const installCommand = require('./commands/install');
+const { installCompletion, uninstallCompletion } = require('./completion');
+
+/**
+ * Run the CLI program
+ */
+function run() {
+  program
+    .name('dev')
+    .description('CLI toolkit for bootstrapping development environments')
+    .version(pkg.version, '-v, --version', 'Display version number');
+
+  // Global options
+  program
+    .option('--verbose', 'Enable verbose output')
+    .option('-q, --quiet', 'Suppress non-essential output')
+    .option('--no-color', 'Disable colored output');
+
+  // Add commands
+  program.addCommand(configureCommand);
+  program.addCommand(statusCommand);
+  program.addCommand(identityCommand);
+  program.addCommand(ignoreCommand);
+  program.addCommand(installCommand);
+
+  // Setup command - install essential tools
+  const setupCommand = require('./commands/setup');
+  program.addCommand(setupCommand);
+
+  // Completion management
+  const completion = program
+    .command('completion')
+    .description('Manage shell tab completion');
+
+  completion
+    .command('install')
+    .description('Install tab completion for your shell')
+    .action(installCompletion);
+
+  completion
+    .command('uninstall')
+    .description('Remove tab completion')
+    .action(uninstallCompletion);
+
+  // Parse and execute
+  program.parse(process.argv);
+
+  // If no command specified, show help
+  if (process.argv.length === 2) {
+    program.help();
+  }
+}
+
+module.exports = { run };

package/src/commands/README.md

@@ -0,0 +1,41 @@
+# 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.