@fredlackey/devutils 0.0.1

package/src/scripts/p.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+/**
+ * @fileoverview Navigate to the projects directory.
+ * @module scripts/p
+ */
+
+/**
+ * Changes the current working directory to the user's projects folder.
+ * Outputs the path for use with shell integration (e.g., cd $(p)).
+ *
+ * @param {string[]} args - Command line arguments (unused)
+ * @returns {Promise<void>}
+ */
+async function main(args) {
+  // TODO: Implement projects folder navigation
+}
+
+module.exports = { main };
+
+if (require.main === module) {
+  main(process.argv.slice(2));
+}

package/src/scripts/packages.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+/**
+ * @fileoverview Find all package.json files with modification dates.
+ * @module scripts/packages
+ */
+
+/**
+ * Recursively finds all package.json files in the current directory
+ * and displays them with their modification timestamps, sorted by date.
+ * Excludes node_modules directories.
+ *
+ * @param {string[]} args - Command line arguments
+ * @param {string} [args.0] - Optional path to search (defaults to current directory)
+ * @returns {Promise<void>}
+ */
+async function main(args) {
+  // TODO: Implement package.json finder
+}
+
+module.exports = { main };
+
+if (require.main === module) {
+  main(process.argv.slice(2));
+}

package/src/scripts/path.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+/**
+ * @fileoverview Display PATH entries one per line.
+ * @module scripts/path
+ */
+
+/**
+ * Outputs each directory in the system PATH environment variable
+ * on a separate line for easier reading.
+ *
+ * @param {string[]} args - Command line arguments (unused)
+ * @returns {Promise<void>}
+ */
+async function main(args) {
+  // TODO: Implement PATH display
+}
+
+module.exports = { main };
+
+if (require.main === module) {
+  main(process.argv.slice(2));
+}

package/src/scripts/ports.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+/**
+ * @fileoverview List open network ports.
+ * @module scripts/ports
+ */
+
+/**
+ * Displays a list of open network ports and the processes using them.
+ * Uses platform-specific commands (lsof, netstat, ss).
+ *
+ * @param {string[]} args - Command line arguments (unused)
+ * @returns {Promise<void>}
+ */
+async function main(args) {
+  // TODO: Implement port listing
+}
+
+module.exports = { main };
+
+if (require.main === module) {
+  main(process.argv.slice(2));
+}

package/src/scripts/q.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+/**
+ * @fileoverview Exit the current shell session.
+ * @module scripts/q
+ */
+
+/**
+ * Exits the current shell session.
+ * Provides a quick way to close the terminal.
+ *
+ * @param {string[]} args - Command line arguments (unused)
+ * @returns {Promise<void>}
+ */
+async function main(args) {
+  // TODO: Implement shell exit
+}
+
+module.exports = { main };
+
+if (require.main === module) {
+  main(process.argv.slice(2));
+}

package/src/scripts/refresh-files.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+
+/**
+ * @fileoverview Copy matching files from source to target directory.
+ * @module scripts/refresh-files
+ */
+
+/**
+ * Compares files in the target directory with a source directory
+ * and copies over files that exist in both locations from the source.
+ * Useful for refreshing files from a stable/reference project.
+ *
+ * @param {string[]} args - Command line arguments
+ * @param {string} args.0 - Source folder path
+ * @param {string} [args.1] - Target folder path (defaults to current directory)
+ * @returns {Promise<void>}
+ */
+async function main(args) {
+  // TODO: Implement file refresh from source
+}
+
+module.exports = { main };
+
+if (require.main === module) {
+  main(process.argv.slice(2));
+}

package/src/scripts/remove-smaller-files.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+
+/**
+ * @fileoverview Compare directories and remove smaller duplicates.
+ * @module scripts/remove-smaller-files
+ */
+
+/**
+ * Compares files between two directories and removes the smaller
+ * version of each matching file pair. Useful for deduplication.
+ *
+ * @param {string[]} args - Command line arguments
+ * @param {string} args.0 - Path to comparison directory
+ * @returns {Promise<void>}
+ */
+async function main(args) {
+  // TODO: Implement duplicate removal by size
+}
+
+module.exports = { main };
+
+if (require.main === module) {
+  main(process.argv.slice(2));
+}

package/src/scripts/rename-files-with-date.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+/**
+ * @fileoverview Normalize date-based filenames.
+ * @module scripts/rename-files-with-date
+ */
+
+/**
+ * Renames files containing dates in their filenames to a standardized
+ * format: "YYYY-MM-DD HH.MM.SS.ext". Handles various input formats
+ * like timestamps from cameras and screenshots.
+ *
+ * @param {string[]} args - Command line arguments
+ * @param {string} [args.0] - Path to process (defaults to current directory)
+ * @returns {Promise<void>}
+ */
+async function main(args) {
+  // TODO: Implement filename date normalization
+}
+
+module.exports = { main };
+
+if (require.main === module) {
+  main(process.argv.slice(2));
+}

package/src/scripts/resize-image.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+/**
+ * @fileoverview Resize image using ImageMagick.
+ * @module scripts/resize-image
+ */
+
+/**
+ * Resizes an image using ImageMagick's convert command with
+ * high-quality settings. Creates a new file with underscore prefix.
+ *
+ * @param {string[]} args - Command line arguments
+ * @param {string} args.0 - Path to the image file
+ * @param {string} [args.1] - Resize geometry (default: "50%")
+ * @returns {Promise<void>}
+ */
+async function main(args) {
+  // TODO: Implement image resizing
+}
+
+module.exports = { main };
+
+if (require.main === module) {
+  main(process.argv.slice(2));
+}

package/src/scripts/rm-safe.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+
+/**
+ * @fileoverview Safe wrapper for rm preventing dangerous operations.
+ * @module scripts/rm-safe
+ */
+
+/**
+ * A safer version of rm that prevents accidental removal of
+ * root directories, top-level system directories, and blocks
+ * dangerous flags like --no-preserve-root.
+ *
+ * @param {string[]} args - Command line arguments (passed to rm)
+ * @returns {Promise<void>}
+ */
+async function main(args) {
+  // TODO: Implement safe rm wrapper
+}
+
+module.exports = { main };
+
+if (require.main === module) {
+  main(process.argv.slice(2));
+}

package/src/scripts/s.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+
+/**
+ * @fileoverview Search text in current directory.
+ * @module scripts/s
+ */
+
+/**
+ * Recursively searches for text matching the specified pattern
+ * in the current directory, excluding .git and node_modules.
+ *
+ * @param {string[]} args - Command line arguments
+ * @param {string} args.0 - Search pattern
+ * @returns {Promise<void>}
+ */
+async function main(args) {
+  // TODO: Implement recursive text search
+}
+
+module.exports = { main };
+
+if (require.main === module) {
+  main(process.argv.slice(2));
+}

package/src/scripts/set-git-public.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+/**
+ * @fileoverview Set git user to public identity.
+ * @module scripts/set-git-public
+ */
+
+/**
+ * Configures the local git repository to use the public identity
+ * stored in the ~/.devutils configuration file.
+ *
+ * @param {string[]} args - Command line arguments (unused)
+ * @returns {Promise<void>}
+ */
+async function main(args) {
+  // TODO: Implement git identity configuration
+}
+
+module.exports = { main };
+
+if (require.main === module) {
+  main(process.argv.slice(2));
+}

package/src/scripts/show-desktop-icons.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+/**
+ * @fileoverview Show desktop icons in Finder.
+ * @module scripts/show-desktop-icons
+ */
+
+/**
+ * Shows all icons on the macOS desktop by modifying Finder preferences
+ * and restarting Finder.
+ *
+ * @param {string[]} args - Command line arguments (unused)
+ * @returns {Promise<void>}
+ */
+async function main(args) {
+  // TODO: Implement desktop icon showing
+}
+
+module.exports = { main };
+
+if (require.main === module) {
+  main(process.argv.slice(2));
+}

package/src/scripts/show-hidden-files.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+/**
+ * @fileoverview Show dotfiles in Finder.
+ * @module scripts/show-hidden-files
+ */
+
+/**
+ * Configures Finder to show hidden files (dotfiles) and restarts Finder
+ * to apply the change.
+ *
+ * @param {string[]} args - Command line arguments (unused)
+ * @returns {Promise<void>}
+ */
+async function main(args) {
+  // TODO: Implement hidden file showing
+}
+
+module.exports = { main };
+
+if (require.main === module) {
+  main(process.argv.slice(2));
+}

package/src/scripts/tpa.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+/**
+ * @fileoverview Terraform apply from plan file.
+ * @module scripts/tpa
+ */
+
+/**
+ * Executes `terraform apply` using the previously saved "tfplan" file
+ * created by `tpo`.
+ *
+ * @param {string[]} args - Command line arguments to pass to terraform apply
+ * @returns {Promise<void>}
+ */
+async function main(args) {
+  // TODO: Implement terraform apply from plan
+}
+
+module.exports = { main };
+
+if (require.main === module) {
+  main(process.argv.slice(2));
+}

package/src/scripts/tpo.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+/**
+ * @fileoverview Terraform plan with output file.
+ * @module scripts/tpo
+ */
+
+/**
+ * Executes `terraform plan` and saves the plan to a file named "tfplan"
+ * for later application with `terraform apply`.
+ *
+ * @param {string[]} args - Command line arguments to pass to terraform plan
+ * @returns {Promise<void>}
+ */
+async function main(args) {
+  // TODO: Implement terraform plan with output
+}
+
+module.exports = { main };
+
+if (require.main === module) {
+  main(process.argv.slice(2));
+}

package/src/scripts/u.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+/**
+ * @fileoverview Update system packages and tools.
+ * @module scripts/u
+ */
+
+/**
+ * Updates the system's package manager and installed packages.
+ * Platform-specific: macOS (softwareupdate + Homebrew), Linux (apt/yum).
+ *
+ * @param {string[]} args - Command line arguments (unused)
+ * @returns {Promise<void>}
+ */
+async function main(args) {
+  // TODO: Implement system update
+}
+
+module.exports = { main };
+
+if (require.main === module) {
+  main(process.argv.slice(2));
+}

package/src/scripts/vpush.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+/**
+ * @fileoverview Commit with package.json version as message.
+ * @module scripts/vpush
+ */
+
+/**
+ * Stages all changes, commits using the version from package.json
+ * as the commit message, and pushes to the remote.
+ *
+ * @param {string[]} args - Command line arguments (unused)
+ * @returns {Promise<void>}
+ */
+async function main(args) {
+  // TODO: Implement version-based commit and push
+}
+
+module.exports = { main };
+
+if (require.main === module) {
+  main(process.argv.slice(2));
+}

package/src/scripts/y.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+/**
+ * @fileoverview Shortcut for yarn commands.
+ * @module scripts/y
+ */
+
+/**
+ * Executes yarn with the provided arguments.
+ * Acts as a shorthand for common yarn operations.
+ *
+ * @param {string[]} args - Command line arguments to pass to yarn
+ * @returns {Promise<void>}
+ */
+async function main(args) {
+  // TODO: Implement yarn shortcut
+}
+
+module.exports = { main };
+
+if (require.main === module) {
+  main(process.argv.slice(2));
+}

package/src/utils/README.md

@@ -0,0 +1,95 @@
+# Utils
+
+This folder contains internal shared utilities used by Commands, Scripts, and Installs.
+
+## Purpose
+
+Utils provide common functionality that is reused across the package. These are **not** directly invokable by users — they are internal helpers.
+
+## Planned Utilities
+
+| File | Description |
+|------|-------------|
+| `os.js` | Operating system detection (macOS, Debian, RHEL, Windows, WSL) |
+| `shell.js` | Shell command execution wrappers |
+| `config.js` | Read/write `~/.devutils` configuration file |
+| `prompts.js` | Interactive user prompts and wizards |
+| `logger.js` | Consistent logging and output formatting |
+| `paths.js` | Path resolution and home directory helpers |
+| `git.js` | Git repository detection and operations |
+| `npm.js` | npm/package.json utilities |
+
+## Example: OS Detection
+
+```javascript
+// utils/os.js
+
+function detect() {
+  const platform = process.platform;
+
+  if (platform === 'darwin') {
+    return { type: 'macos', packageManager: 'brew' };
+  }
+
+  if (platform === 'linux') {
+    // Check for WSL
+    if (process.env.WSL_DISTRO_NAME) {
+      return { type: 'windows-wsl', packageManager: 'apt' };
+    }
+    // Check for Debian-based (apt)
+    if (fs.existsSync('/etc/debian_version')) {
+      return { type: 'debian', packageManager: 'apt' };
+    }
+    // Check for RHEL-based (yum/dnf)
+    if (fs.existsSync('/etc/redhat-release')) {
+      return { type: 'rhel', packageManager: 'dnf' };
+    }
+  }
+
+  if (platform === 'win32') {
+    return { type: 'windows', packageManager: 'choco' };
+  }
+
+  return { type: 'unknown', packageManager: null };
+}
+
+module.exports = { detect };
+```
+
+## Example: Config Helper
+
+```javascript
+// utils/config.js
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const CONFIG_PATH = path.join(os.homedir(), '.devutils');
+
+function read() {
+  if (!fs.existsSync(CONFIG_PATH)) {
+    return null;
+  }
+  return JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8'));
+}
+
+function write(config) {
+  config.updated = new Date().toISOString();
+  fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2));
+}
+
+module.exports = { read, write, CONFIG_PATH };
+```
+
+## Guidelines
+
+1. **Single responsibility** — Each util should do one thing well
+2. **No side effects** — Avoid global state; return values instead
+3. **Error handling** — Throw descriptive errors; let callers handle them
+4. **Platform-aware** — Consider cross-platform compatibility
+
+## Related
+
+- **Commands** (`../commands/`) — Use utils for common operations
+- **Scripts** (`../scripts/`) — Use utils for OS detection, shell execution
+- **Installs** (`../installs/`) — Use `os.js` for platform detection