@fredlackey/devutils 0.0.18 → 0.1.0

package/README.md

@@ -1,178 +1,251 @@
 # 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
+> **Work in Progress** -- This project is under active development and has not been fully tested in real-world environments. Commands may change, break, or behave unexpectedly. Use at your own risk. The stable, production-ready release will ship as **v1.0**. Until then, versions in the `0.x` range should be considered pre-release.
 
-Stop wasting hours setting up new machines. One command, any platform, ready to code.
+A config-driven CLI toolkit for bootstrapping and managing development environments across any machine.
 
-## 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.
+DevUtils replaces scattered dotfiles, setup scripts, and manual configuration with a single `dev` command. You tell it what you need, and it handles the rest -- whether you're setting up a new laptop, syncing git identities across machines, or managing tool installations.
 
 ## Installation
 
-### If You Have Node.js Installed
-
-If you already have Node.js 18+ on your machine, install DevUtils CLI as a global npm package:
-
 ```bash
 npm install -g @fredlackey/devutils
 ```
 
-### Fresh Machine (No Node.js)
-
-For a fresh machine without Node.js, run the bootstrap script. It installs everything you need: build tools, nvm, Node.js LTS, and DevUtils CLI.
-
-**macOS:**
-```bash
-bash -c "$(curl -LsS https://raw.github.com/fredlackey/devutils-cli/main/setup.sh)"
-```
-
-**Ubuntu / Debian / Raspberry Pi OS:**
-```bash
-bash -c "$(wget -qO - https://raw.github.com/fredlackey/devutils-cli/main/setup.sh)"
-```
-
-**Amazon Linux / RHEL / Fedora:**
-```bash
-bash -c "$(curl -LsS https://raw.github.com/fredlackey/devutils-cli/main/setup.sh)"
-```
-
-The script is interactive by default. For automated/CI environments, add `--no-prompt`:
-
-```bash
-bash -c "$(curl -LsS https://raw.github.com/fredlackey/devutils-cli/main/setup.sh)" -- --no-prompt
-```
+Requires Node.js 18 or later.
 
 ## 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:
+Once installed, the `dev` command is available globally:
 
 ```bash
-dev install docker
-dev install node
-dev install vscode
+dev help               # Show all available services and commands
+dev version            # Print the current version
+dev config init        # Walk through first-time setup
+dev status             # Check the health of your environment
+dev ignore node        # Add Node.js patterns to .gitignore
+dev tools list         # See what tools are installed
+dev identity list      # List your configured git identities
+dev util list          # Browse available utility functions
 ```
 
-DevUtils CLI figures out the right command for macOS, Ubuntu, Raspberry Pi OS, Amazon Linux, Windows, or Git Bash.
-
-### Git Identity Management
+## Command Reference
 
-Manage multiple git identities for work, personal, and client projects:
+DevUtils organizes commands by service. The general pattern is:
 
-```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
+```
+dev <service> <method> [arguments] [flags]
 ```
 
-Clone with any URL format. DevUtils CLI routes it through the correct SSH key automatically.
-
-### Smart .gitignore Management
+### Services
+
+#### config -- User configuration and onboarding
+
+| Method   | Description                                  |
+|----------|----------------------------------------------|
+| `init`   | Run first-time setup and create config files |
+| `show`   | Display the current configuration            |
+| `get`    | Read a specific config value                 |
+| `set`    | Update a specific config value               |
+| `reset`  | Reset configuration to defaults              |
+| `export` | Export config to a file                       |
+| `import` | Import config from a file                    |
+
+#### machine -- Machine profiles and detection
+
+| Method   | Description                         |
+|----------|-------------------------------------|
+| `detect` | Auto-detect the current machine     |
+| `show`   | Show the active machine profile     |
+| `set`    | Set a machine profile value         |
+| `list`   | List all known machine profiles     |
+
+#### identity -- Git identities, SSH keys, GPG signing
+
+| Method   | Description                                 |
+|----------|---------------------------------------------|
+| `add`    | Register a new git identity                 |
+| `remove` | Remove a registered identity                |
+| `list`   | List all identities                         |
+| `show`   | Show details for a specific identity        |
+| `link`   | Link an identity to a folder or repo        |
+| `unlink` | Remove a folder/repo identity link          |
+| `sync`   | Sync identity configs to git and SSH        |
+
+#### tools -- Tool installation and management
+
+| Method    | Description                              |
+|-----------|------------------------------------------|
+| `install` | Install a tool using the platform's package manager |
+| `check`   | Check if a tool is installed             |
+| `list`    | List available or installed tools        |
+| `search`  | Search for tools by name                 |
+
+#### ignore -- .gitignore pattern management
+
+| Method   | Description                                  |
+|----------|----------------------------------------------|
+| `add`    | Add technology patterns to .gitignore        |
+| `remove` | Remove a technology's patterns               |
+| `list`   | List available technologies                  |
+| `show`   | Show patterns for a specific technology      |
+
+#### util -- Utility functions
+
+| Method   | Description                           |
+|----------|---------------------------------------|
+| `add`    | Register a custom utility             |
+| `remove` | Unregister a utility                  |
+| `list`   | List all available utilities          |
+| `show`   | Show details for a specific utility   |
+| `run`    | Execute a utility                     |
+
+#### alias -- Shorthand bin entries
+
+| Method   | Description                              |
+|----------|------------------------------------------|
+| `add`    | Create a new alias                       |
+| `remove` | Delete an alias                          |
+| `list`   | List all registered aliases              |
+| `sync`   | Regenerate alias wrapper scripts         |
+
+#### auth -- OAuth and credential management
+
+| Method    | Description                          |
+|-----------|--------------------------------------|
+| `login`   | Authenticate with a service          |
+| `logout`  | Revoke credentials for a service     |
+| `list`    | List authenticated services          |
+| `status`  | Show current auth status             |
+| `refresh` | Refresh an expired token             |
+
+#### api -- API plugin system
+
+| Method    | Description                         |
+|-----------|-------------------------------------|
+| `list`    | List installed API plugins          |
+| `enable`  | Enable a plugin                     |
+| `disable` | Disable a plugin                    |
+| `update`  | Update a plugin to latest version   |
+
+#### ai -- AI coding assistant launcher
+
+| Method     | Description                             |
+|------------|-----------------------------------------|
+| `launch`   | Start an AI coding session              |
+| `resume`   | Resume a previous session               |
+| `list`     | List configured AI tools                |
+| `sessions` | List past sessions                      |
+| `show`     | Show details for a session or AI tool   |
+| `set`      | Update AI tool settings                 |
+
+#### search -- Markdown search
+
+| Method        | Description                              |
+|---------------|------------------------------------------|
+| `query`       | Run a general search                     |
+| `keyword`     | Search by keyword                        |
+| `semantic`    | Search by meaning (requires AI plugin)   |
+| `get`         | Retrieve a specific search result        |
+| `collections` | List indexed collections                 |
+| `index`       | Build or rebuild the search index        |
+| `status`      | Show indexing status                     |
+
+### Top-Level Commands
+
+These commands don't belong to a service and are called directly:
+
+| Command   | Description                        |
+|-----------|------------------------------------|
+| `status`  | Overall health check               |
+| `version` | Show current version               |
+| `help`    | Show the help message              |
+| `schema`  | Introspect available commands      |
+| `update`  | Update DevUtils to latest version  |
+
+### Global Flags
+
+These flags work with any command:
+
+| Flag                              | Description                        |
+|-----------------------------------|------------------------------------|
+| `--format <json\|table\|yaml\|csv>` | Set the output format             |
+| `--dry-run`                       | Show what would happen without doing it |
+| `--verbose`                       | Increase output detail             |
+| `--quiet`                         | Suppress non-essential output      |
+| `--json <data>`                   | Pass structured input as JSON      |
+| `--help`, `-h`                    | Show help                          |
+| `--version`, `-v`                 | Show version                       |
+
+## API Plugin System
+
+DevUtils doesn't bundle API integrations directly. Instead, API wrappers are installed as separate plugin packages and managed through the `dev api` service.
+
+Plugins live in `~/.devutils/plugins/` and are registered in `~/.devutils/plugins.json`. Each plugin is a standard npm package that exports a defined interface. This keeps the core CLI small and lets you add only the integrations you actually use.
 
 ```bash
-dev ignore node      # Add Node.js patterns
-dev ignore macos     # Add .DS_Store and friends
-dev ignore vscode    # Add .vscode/ patterns
+dev api list               # See what's installed
+dev api enable <plugin>    # Enable a plugin
+dev api disable <plugin>   # Disable a plugin
+dev api update <plugin>    # Update to latest version
 ```
 
-Patterns are managed in sections—run it twice and it won't duplicate.
-
-### Portable Configuration
-
-Your `~/.devutils` file stores your preferences:
+## Configuration
 
-```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" }
-  }
-}
-```
+All user data lives in `~/.devutils/`, created during `dev config init`:
 
-Copy this file to a new machine and run `dev identity sync` to regenerate all your SSH configs.
+- `config.json` -- User preferences, profile name, backup location
+- `aliases.json` -- Registered alias mappings
+- `ai.json` -- AI tool configurations
+- `plugins.json` -- Installed API plugin registry
+- `machines/` -- Machine profiles
+- `auth/` -- OAuth tokens and API credentials
+- `plugins/` -- Installed API plugin packages
+- `utils/` -- User-added custom utilities
+- `bin/` -- Generated alias wrapper scripts (added to PATH)
+- `cache/` -- Temporary data
 
 ## Supported Platforms
 
-| Platform | Package Manager |
-|----------|-----------------|
-| macOS | Homebrew |
-| Ubuntu | APT / Snap |
-| Raspberry Pi OS | APT / Snap |
-| Amazon Linux | DNF / YUM |
-| Windows | Chocolatey / winget |
-| Git Bash | Manual / Portable |
-
-## 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.
+| Platform          | Package Manager     |
+|-------------------|---------------------|
+| macOS             | Homebrew            |
+| Ubuntu            | APT, Snap           |
+| Raspberry Pi OS   | APT, Snap           |
+| Amazon Linux      | DNF, YUM            |
+| Windows           | Chocolatey, winget  |
+| Git Bash          | Manual / Portable   |
+
+## Current Status
+
+DevUtils is in **pre-release** (`0.1.x`). The core framework, command routing, and service structure are in place. Basic smoke tests pass on Ubuntu 24.04 in Docker, but deeper integration testing -- real Git operations, SSH key workflows, GitHub auth, tool installation, and interactive prompts -- has not been completed yet.
+
+What's working:
+- Command routing and service discovery across all 11 services
+- Config init, show, get, set, reset, file-based export/import
+- Machine detection and profile management
+- Gitignore pattern management (add, remove, list, show)
+- Tool check, list, search, and dry-run install
+- Identity CRUD (add, list, show, remove)
+- Alias management and wrapper generation
+- AI tool configuration
+- Schema introspection
+- Platform detection (macOS, Ubuntu, Raspberry Pi OS, Amazon Linux, Windows, Git Bash)
+
+What still needs real-world testing:
+- SSH key generation and GitHub integration
+- Git identity sync to actual repositories
+- Config backup/restore via remote Git repo
+- OAuth login flows
+- Tool installation on each supported platform
+- API plugin installation and lifecycle
+- AI session launch and resume
+- QMD search indexing and queries
+
+Patch versions (`0.1.1`, `0.1.2`, etc.) will ship as issues are found and fixed during hands-on use. Minor version bumps (`0.2.0`) are reserved for breaking changes. The first stable release will be **v1.0.0**.
 
 ## 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)

package/package.json

@@ -1,101 +1,26 @@
 {
   "name": "@fredlackey/devutils",
-  "version": "0.0.18",
-  "description": "A globally-installable Node.js CLI toolkit for bootstrapping and configuring development environments across any machine.",
+  "version": "0.1.0",
+  "description": "A config-driven CLI toolkit for bootstrapping and managing development environments across any machine.",
   "main": "src/index.js",
   "bin": {
-    "dev": "./bin/dev.js",
-    "afk": "./src/scripts/afk.js",
-    "backup-all": "./src/scripts/backup-all.js",
-    "backup-source": "./src/scripts/backup-source.js",
-    "brewd": "./src/scripts/brewd.js",
-    "brewi": "./src/scripts/brewi.js",
-    "brewr": "./src/scripts/brewr.js",
-    "brews": "./src/scripts/brews.js",
-    "brewu": "./src/scripts/brewu.js",
-    "c": "./src/scripts/c.js",
-    "ccurl": "./src/scripts/ccurl.js",
-    "certbot-crontab-init": "./src/scripts/certbot-crontab-init.js",
-    "certbot-init": "./src/scripts/certbot-init.js",
-    "ch": "./src/scripts/ch.js",
-    "claude-danger": "./src/scripts/claude-danger.js",
-    "clean-dev": "./src/scripts/clean-dev.js",
-    "clear-dns-cache": "./src/scripts/clear-dns-cache.js",
-    "clone": "./src/scripts/clone.js",
-    "code-all": "./src/scripts/code-all.js",
-    "count": "./src/scripts/count.js",
-    "count-files": "./src/scripts/count-files.js",
-    "count-folders": "./src/scripts/count-folders.js",
-    "d": "./src/scripts/d.js",
-    "datauri": "./src/scripts/datauri.js",
-    "delete-files": "./src/scripts/delete-files.js",
-    "docker-clean": "./src/scripts/docker-clean.js",
-    "dp": "./src/scripts/dp.js",
-    "e": "./src/scripts/e.js",
-    "empty-trash": "./src/scripts/empty-trash.js",
-    "evm": "./src/scripts/evm.js",
-    "fetch-github-repos": "./src/scripts/fetch-github-repos.js",
-    "get-channel": "./src/scripts/get-channel.js",
-    "get-course": "./src/scripts/get-course.js",
-    "get-dependencies": "./src/scripts/get-dependencies.js",
-    "get-folder": "./src/scripts/get-folder.js",
-    "get-tunes": "./src/scripts/get-tunes.js",
-    "get-video": "./src/scripts/get-video.js",
-    "git-backup": "./src/scripts/git-backup.js",
-    "git-clone": "./src/scripts/git-clone.js",
-    "git-pup": "./src/scripts/git-pup.js",
-    "git-push": "./src/scripts/git-push.js",
-    "h": "./src/scripts/h.js",
-    "hide-desktop-icons": "./src/scripts/hide-desktop-icons.js",
-    "hide-hidden-files": "./src/scripts/hide-hidden-files.js",
-    "install-dependencies-from": "./src/scripts/install-dependencies-from.js",
-    "ips": "./src/scripts/ips.js",
-    "iso": "./src/scripts/iso.js",
-    "killni": "./src/scripts/killni.js",
-    "ll": "./src/scripts/ll.js",
-    "local-ip": "./src/scripts/local-ip.js",
-    "m": "./src/scripts/m.js",
-    "map": "./src/scripts/map.js",
-    "mkd": "./src/scripts/mkd.js",
-    "ncu-update-all": "./src/scripts/ncu-update-all.js",
-    "nginx-init": "./src/scripts/nginx-init.js",
-    "npmi": "./src/scripts/npmi.js",
-    "o": "./src/scripts/o.js",
-    "org-by-date": "./src/scripts/org-by-date.js",
-    "p": "./src/scripts/p.js",
-    "packages": "./src/scripts/packages.js",
-    "path": "./src/scripts/path.js",
-    "ports": "./src/scripts/ports.js",
-    "q": "./src/scripts/q.js",
-    "refresh-files": "./src/scripts/refresh-files.js",
-    "remove-smaller-files": "./src/scripts/remove-smaller-files.js",
-    "rename-files-with-date": "./src/scripts/rename-files-with-date.js",
-    "resize-image": "./src/scripts/resize-image.js",
-    "rm-safe": "./src/scripts/rm-safe.js",
-    "s": "./src/scripts/s.js",
-    "set-git-public": "./src/scripts/set-git-public.js",
-    "show-desktop-icons": "./src/scripts/show-desktop-icons.js",
-    "show-hidden-files": "./src/scripts/show-hidden-files.js",
-    "tpa": "./src/scripts/tpa.js",
-    "tpo": "./src/scripts/tpo.js",
-    "u": "./src/scripts/u.js",
-    "vpush": "./src/scripts/vpush.js",
-    "y": "./src/scripts/y.js"
+    "dev": "./src/cli.js"
   },
   "files": [
-    "bin/",
     "src/",
-    "files/"
+    "package.json",
+    "README.md",
+    "LICENSE"
   ],
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "node test/index.js"
   },
   "dependencies": {
     "commander": "^12.0.0"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/FredLackey/devutils-cli.git"
+    "url": "git+ssh://git@github.com/FredLackey/devutils-cli.git"
   },
   "keywords": [],
   "author": {