@marcfargas/skills 0.2.1 → 0.3.0

package/LICENSE-CC0

@@ -0,0 +1,118 @@
+CC0 1.0 Universal
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator and
+subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for the
+purpose of contributing to a commons of creative, cultural and scientific
+works ("Commons") that the public can reliably and without fear of later
+claims of infringement build upon, modify, incorporate in other works, reuse
+and redistribute as freely as possible in any form whatsoever and for any
+purposes, including without limitation commercial purposes. These owners may
+contribute to the Commons to promote the ideal of a free culture and the
+further production of creative, cultural and scientific works, or to gain
+reputation or greater distribution for their Work in part through the use and
+efforts of others.
+
+For these and/or other purposes and motivations, and without any expectation
+of additional consideration or compensation, the person associating CC0 with a
+Work (the "Affirmer"), to the extent that he or she is an owner of Copyright
+and Related Rights in the Work, voluntarily elects to apply CC0 to the Work
+and publicly distribute the Work under its terms, with knowledge of his or her
+Copyright and Related Rights in the Work and the meaning and intended legal
+effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not limited
+to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display, communicate,
+     and translate a Work;
+
+ ii. moral rights retained by the original author(s) and/or performer(s);
+
+iii. publicity and privacy rights pertaining to a person's image or likeness
+     depicted in a Work;
+
+ iv. rights protecting against unfair competition in regards to a Work,
+     subject to the limitations in paragraph 4(a), below;
+
+  v. rights protecting the extraction, dissemination, use and reuse of data in
+     a Work;
+
+ vi. database rights (such as those arising under Directive 96/9/EC of the
+     European Parliament and of the Council of 11 March 1996 on the legal
+     protection of databases, and under any national implementation thereof,
+     including any amended or successor version of such directive); and
+
+vii. other similar, equivalent or corresponding rights throughout the world
+     based on applicable law or treaty, and any national implementations
+     thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention of,
+applicable law, Affirmer hereby overtly, fully, permanently, irrevocably and
+unconditionally waives, abandons, and surrenders all of Affirmer's Copyright
+and Related Rights and associated claims and causes of action, whether now
+known or unknown (including existing as well as future claims and causes of
+action), in the Work (i) in all territories worldwide, (ii) for the maximum
+duration provided by applicable law or treaty (including future time
+extensions), (iii) in any current or future medium and for any number of
+copies, and (iv) for any purpose whatsoever, including without limitation
+commercial, advertising or promotional purposes (the "Waiver"). Affirmer makes
+the Waiver for the benefit of each member of the public at large and to the
+detriment of Affirmer's heirs and successors, fully intending that such Waiver
+shall not be subject to revocation, rescission, cancellation, termination, or
+any other legal or equitable action to disrupt the quiet enjoyment of the Work
+by the public as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason be
+judged legally invalid or ineffective under applicable law, then the Waiver
+shall be preserved to the maximum extent permitted taking into account
+Affirmer's express Statement of Purpose. In addition, to the extent the Waiver
+is so judged Affirmer hereby grants to each affected person a royalty-free,
+non transferable, non sublicensable, non exclusive, irrevocable and
+unconditional license to exercise Affirmer's Copyright and Related Rights in
+the Work (i) in all territories worldwide, (ii) for the maximum duration
+provided by applicable law or treaty (including future time extensions), (iii)
+in any current or future medium and for any number of copies, and (iv) for any
+purpose whatsoever, including without limitation commercial, advertising or
+promotional purposes (the "License"). The License shall be deemed effective as
+of the date CC0 was applied by Affirmer to the Work. Should any part of the
+License for any reason be judged legally invalid or ineffective under
+applicable law, such partial invalidity or ineffectiveness shall not invalidate
+the remainder of the License, and in such case Affirmer hereby affirms that he
+or she will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of action
+with respect to the Work, in either case contrary to Affirmer's express
+Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+    surrendered, licensed or otherwise affected by this document.
+
+ b. Affirmer offers the Work as-is and makes no representations or warranties
+    of any kind concerning the Work, express, implied, statutory or otherwise,
+    including without limitation warranties of title, merchantability, fitness
+    for a particular purpose, non infringement, or the absence of latent or
+    other defects, accuracy, or the present or absence of errors, whether or
+    not discoverable, all to the greatest extent permissible under applicable
+    law.
+
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+    that may apply to the Work or any use thereof, including without limitation
+    any person's Copyright and Related Rights in the Work. Further, Affirmer
+    disclaims responsibility for obtaining any necessary consents, permissions
+    or other rights required for any use of the Work.
+
+ d. Affirmer understands and acknowledges that Creative Commons is not a party
+    to this document and has no duty or obligation with respect to this CC0 or
+    use of the Work.
+
+For more information, please see
+<http://creativecommons.org/publicdomain/zero/1.0/>

package/README.md

@@ -7,6 +7,7 @@ Reusable skills for AI coding agents. Works with [pi](https://github.com/marioze
 | Category | Skill | Description |
 |----------|-------|-------------|
 | ☁️ Google Cloud | [gcloud](google-cloud/gcloud/) | GCP CLI with agent safety model — hub + 7 reference files |
+| ⚙️ Process | [pm2](process/pm2/) | Process management — keep services alive, auto-restart, monitoring, ecosystem configs |
 | 🚀 Release | [pre-release](release/pre-release/) | Pre-release checklist + AI-written changesets via @changesets/cli |
 | 🔍 Search | [web-search](search/web-search/) | Web search + content extraction via [ddgs](https://github.com/deedy5/ddgs) — no API keys |
 | 🎬 Terminal | [vhs](terminal/vhs/) | Record terminal sessions as GIF/MP4 with [VHS](https://github.com/charmbracelet/vhs) |
@@ -70,6 +71,8 @@ Skills use a **hub + spoke** architecture. The SKILL.md hub is ~140 lines — ju
 skills/
 ├── google-cloud/
 │   └── gcloud/          # 8 files, ~1100 lines total
+├── process/
+│   └── pm2/             # 1 file
 ├── release/
 │   └── pre-release/     # 1 file
 ├── search/
@@ -126,4 +129,8 @@ Building high-quality, multi-model-reviewed agent skills takes serious token bud
 
 ## License
 
-MIT
+**Code** (scripts, tooling): [MIT](./LICENSE)
+
+**Skill content** (`**/SKILL.md` and reference docs): [CC0 1.0 Universal](./LICENSE-CC0) — public domain, no attribution required.
+
+Why CC0 for skills: Skill docs are consumed by AI agents and freely incorporated into any workflow. Attribution requirements create friction in agent contexts where provenance tracking is impractical.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marcfargas/skills",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Reusable AI agent skills for pi, Claude Code, Cursor, and any Agent Skills compatible agent",
   "license": "MIT",
   "author": "Marc Fargas <marc@marcfargas.com>",
@@ -14,6 +14,7 @@
     "ai-agent",
     "skills",
     "gcloud",
+    "pm2",
     "pre-release",
     "vhs",
     "web-search"
@@ -21,6 +22,7 @@
   "pi": {
     "skills": [
       "google-cloud",
+      "process",
       "release",
       "search",
       "terminal"
@@ -37,10 +39,12 @@
   },
   "files": [
     "google-cloud/",
+    "process/",
     "release/",
     "search/",
     "terminal/",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "LICENSE-CC0"
   ]
 }

package/process/pm2/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: pm2
+description: >-
+  Process management with PM2 — start, stop, restart, monitor long-running
+  processes. Use when: keeping services alive, auto-restart on crash, managing
+  daemon processes, ecosystem configs, log management, startup scripts, process
+  monitoring. Triggers: pm2, process manager, keep alive, daemon, auto-restart,
+  ecosystem config, process monitoring.
+---
+
+# PM2 — Process Manager
+
+PM2 keeps processes alive, restarts them on crash, and provides monitoring/logging.
+Use for long-running services, persistent agents, background workers.
+
+> **Not for detached terminals** — use [holdpty](https://github.com/marcfargas/holdpty) when you need PTY output, attach/view, or interactive sessions.
+> **Not for ephemeral tasks** — use `pi -p > file &` for quick fire-and-forget agent runs.
+
+## Quick Reference
+
+### Start a process
+
+```bash
+# Simple
+pm2 start server.js --name myapp
+
+# With interpreter
+pm2 start script.py --interpreter python3 --name worker
+
+# With arguments (use -- to separate pm2 args from script args)
+pm2 start app.js --name api -- --port 3000 --env production
+
+# From ecosystem file
+pm2 start ecosystem.config.cjs
+```
+
+### Manage processes
+
+```bash
+pm2 list                    # List all processes (table)
+pm2 jlist                   # List as JSON (for scripting)
+pm2 info <name|id>          # Detailed process info
+pm2 restart <name|id|all>   # Restart
+pm2 stop <name|id|all>      # Stop (keeps in list)
+pm2 delete <name|id|all>    # Stop + remove from list
+pm2 restart <name> --update-env  # Restart with refreshed env vars
+```
+
+### Logs
+
+```bash
+pm2 logs                     # Tail all logs
+pm2 logs <name> --lines 50   # Tail specific process, last 50 lines
+pm2 flush                    # Clear all log files
+```
+
+Log files location: `~/.pm2/logs/<name>-out.log` and `<name>-error.log`.
+
+### Monitoring
+
+```bash
+pm2 monit          # Real-time TUI: CPU, memory, logs
+pm2 dash           # Dashboard with monitoring + logs
+```
+
+## Ecosystem Config
+
+For reproducible multi-process setups, use an `ecosystem.config.cjs` file:
+
+```javascript
+// ecosystem.config.cjs
+module.exports = {
+  apps: [
+    {
+      name: "api",
+      script: "dist/server.js",
+      instances: 2,                // cluster mode
+      exec_mode: "cluster",
+      env: {
+        NODE_ENV: "production",
+        PORT: 3000,
+      },
+      max_memory_restart: "500M",
+      log_date_format: "YYYY-MM-DD HH:mm:ss",
+    },
+    {
+      name: "worker",
+      script: "dist/worker.js",
+      autorestart: true,
+      max_restarts: 10,
+      restart_delay: 5000,
+      exp_backoff_restart_delay: 100,  // exponential backoff
+      watch: false,
+    },
+  ],
+};
+```
+
+```bash
+pm2 start ecosystem.config.cjs           # Start all apps
+pm2 start ecosystem.config.cjs --only api  # Start specific app
+pm2 restart ecosystem.config.cjs          # Restart all
+pm2 delete ecosystem.config.cjs           # Stop + remove all
+```
+
+### Useful ecosystem options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `script` | string | Script to run (required) |
+| `interpreter` | string | Override interpreter (default: `node`) |
+| `args` | string or string[] | Script arguments |
+| `cwd` | string | Working directory |
+| `instances` | number | Number of instances (cluster mode) |
+| `exec_mode` | string | `"fork"` (default) or `"cluster"` |
+| `autorestart` | boolean | Auto-restart on exit (default: `true`) |
+| `max_restarts` | number | Max consecutive restarts before stopping |
+| `restart_delay` | number | Delay between restarts (ms) |
+| `exp_backoff_restart_delay` | number | Exponential backoff base (ms) |
+| `max_memory_restart` | string | Restart if memory exceeds (e.g. `"500M"`) |
+| `cron_restart` | string | Cron-based restart schedule |
+| `watch` | boolean or string[] | Watch for file changes |
+| `ignore_watch` | string[] | Paths to ignore when watching |
+| `env` | object | Environment variables |
+| `log_date_format` | string | Timestamp format for logs |
+| `error_file` | string | Custom stderr log path |
+| `out_file` | string | Custom stdout log path |
+| `merge_logs` | boolean | Merge cluster instance logs |
+| `stop_exit_codes` | number[] | Exit codes that skip auto-restart |
+
+## Persistence
+
+```bash
+pm2 save               # Save current process list
+pm2 resurrect           # Restore saved process list
+pm2 startup             # Generate OS startup script (auto-start on boot)
+pm2 unstartup           # Remove startup script
+```
+
+After `pm2 startup`, run the command it outputs (may need admin/sudo).
+Then `pm2 save` to snapshot current processes — they'll auto-start on reboot.
+
+## Windows Gotchas
+
+### `.cmd` wrapper resolution
+
+PM2 tries to run `.cmd` files as Node.js scripts. **Never start a `.cmd` shim directly** with PM2.
+
+```bash
+# ❌ WRONG — resolves to pi.cmd, crashes
+pm2 start pi -- -p "prompt"
+
+# ✅ CORRECT — point to the actual .js entry point
+pm2 start /path/to/cli.js --interpreter node -- -p "prompt"
+```
+
+For npm-installed CLIs, find the real script:
+
+```bash
+# Find where the .cmd shim points
+cat "$(which pi)" | head -5
+# → Look for the .js path, then use that with --interpreter node
+```
+
+In ecosystem configs, always use the resolved `.js` path:
+
+```javascript
+module.exports = {
+  apps: [{
+    name: "my-agent",
+    // Resolve the actual cli.js, not the .cmd wrapper
+    script: "C:\\path\\to\\node_modules\\package\\dist\\cli.js",
+    interpreter: "node",
+    args: ["--mode", "json"],
+  }],
+};
+```
+
+### Log paths
+
+PM2 stores logs at `~/.pm2/logs/`. On Windows this is typically `C:\Users\<user>\.pm2\logs\`.
+
+### Daemon
+
+PM2 daemon runs as a background Node.js process. `pm2 kill` stops the daemon and all managed processes. `pm2 ping` checks if the daemon is running.
+
+## Agent Patterns
+
+### Launch a pi agent as a persistent service
+
+First, find the actual `cli.js` path (see Windows Gotchas above):
+
+```bash
+# Find pi's real entry point
+cat "$(which pi)" | head -5
+# e.g. → /path/to/node_modules/@mariozechner/pi-coding-agent/dist/cli.js
+```
+
+```javascript
+// ecosystem.config.cjs
+module.exports = {
+  apps: [{
+    name: "my-agent",
+    // Use the resolved cli.js path — NOT the .cmd wrapper
+    script: "/path/to/node_modules/@mariozechner/pi-coding-agent/dist/cli.js",
+    interpreter: "node",
+    args: ["--mode", "json", "--cwd", "/path/to/project"],
+    autorestart: true,
+    max_restarts: 10,
+    restart_delay: 5000,
+  }],
+};
+```
+
+> **Note**: `pi -p` to non-TTY only outputs final text. Use `--mode json` for full event streaming to PM2 logs.
+
+### Check process health from an agent
+
+```bash
+# Structured output for parsing
+pm2 jlist | node -e "
+  const d = JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));
+  d.forEach(p => console.log(p.name, p.pm2_env.status, 'restarts:', p.pm2_env.restart_time));
+"
+```
+
+### Rotate logs
+
+```bash
+pm2 install pm2-logrotate        # Install log rotation module
+pm2 set pm2-logrotate:max_size 10M
+pm2 set pm2-logrotate:retain 5
+```
+
+## When NOT to Use PM2
+
+- **Detached terminal sessions** → use [holdpty](https://github.com/marcfargas/holdpty) (PTY output, attach/view)
+- **Ephemeral agent runs** → use `pi -p > file &` (fire-and-forget with output capture)
+- **Containers** → the container runtime manages lifecycle; PM2 inside Docker is usually redundant
+- **Systemd environments** → use systemd service units natively on Linux

package/terminal/vhs/SKILL.md

@@ -106,13 +106,23 @@ Require git                        # Fail if git not in PATH
 Require node
 ```
 
+## Windows: Use `Set Shell "cmd"`
+
+VHS's default `bash` resolves to WSL bash on Windows — a separate environment with no access to Windows-installed tools (node, scoop packages, etc.). **Always use `cmd`** on Windows:
+
+```tape
+Set Shell "cmd"
+```
+
+This gives VHS the full Windows PATH so all installed CLIs work.
+
 ## Recommended Defaults
 
 For README demos and documentation:
 
 ```tape
 Output demo.gif
-Set Shell "bash"
+Set Shell "cmd"                    # Windows — use "bash" on Linux/macOS
 Set FontSize 14
 Set Width 1100
 Set Height 600
@@ -211,6 +221,82 @@ vhs record > my-session.tape
 vhs my-session.tape
 ```
 
+### Recording TUI apps with holdpty
+
+Use [holdpty](https://github.com/marcfargas/holdpty) to record full-color TUI applications — apps that need a real PTY for colors, take time to start, or are already running. holdpty provides the PTY, VHS captures the output.
+
+**Why this matters:**
+- TUI apps (pi, htop, k9s, lazygit) need a real PTY for colors and layout
+- Slow-starting apps (AI agents, servers) can be ready before recording begins
+- Already-running processes can be recorded on demand for monitoring/sharing
+
+**The pattern:**
+
+```bash
+# Step 1: Launch the app in holdpty (or it's already running)
+holdpty launch --bg --name demo -- my-tui-app
+
+# Step 2: Wait for it to be ready (or it already is)
+sleep 5
+
+# Step 3: Record with VHS
+vhs record-demo.tape
+
+# Step 4: Clean up (or leave it running)
+holdpty stop demo
+```
+
+**Tape file — attach to a running session:**
+
+```tape
+Output demo.gif
+Output demo.mp4
+Set Shell "cmd"
+Set FontSize 14
+Set Width 1200
+Set Height 700
+Set Theme "Dracula"
+Set Padding 15
+Set WindowBar "Colorful"
+Set BorderRadius 8
+
+# Attach to the running holdpty session
+Type "holdpty attach demo"
+Enter
+Sleep 2s
+
+# Interact with the app (VHS types, app responds with full TUI)
+Type "your input here"
+Enter
+Sleep 15s
+```
+
+**Tape file — view-only snapshot of a running process:**
+
+```tape
+Output snapshot.gif
+Set Shell "cmd"
+Set FontSize 14
+Set Width 1200
+Set Height 700
+Set Theme "Dracula"
+Set Padding 15
+
+# View is read-only — just captures current output
+Type "holdpty view demo"
+Enter
+Sleep 10s
+Ctrl+C
+```
+
+**Use cases:**
+- **README demos** — launch app, let it start, record the interesting part
+- **Monitoring snapshots** — capture what a running service looks like right now
+- **Bug reports** — record a live reproduction with full colors
+- **Agent recordings** — capture an AI agent working with its full TUI (thinking indicators, tool calls, colored output)
+
+> On Windows, use `node.exe <path/to/cli.js>` instead of CLI names when launching via holdpty — see the [holdpty skill](https://github.com/marcfargas/holdpty) for the `.cmd` wrapper gotcha.
+
 ## Themes
 
 Popular themes for demos:
@@ -241,8 +327,10 @@ List all: `vhs themes`
 
 ## Gotchas
 
+- **Windows: `Set Shell "bash"` uses WSL** — VHS resolves `bash` to WSL bash, not Git Bash. Use `Set Shell "cmd"` to get the full Windows PATH. Custom shell paths (`Set Shell "C:/path/to/bash.exe"`) are rejected.
 - **No shell expansion in Type** — `Type "echo $HOME"` types the literal string; variable expansion happens when bash executes it, not in the tape
 - **Quoting** — avoid nested quotes in Type. Use wrapper scripts for complex commands
 - **Windows paths** — use forward slashes in Type strings (`C:/dev/...` not `C:\dev\...`)
 - **Long recordings** — GIFs get huge fast. Keep demos under 30 seconds. Use `Set PlaybackSpeed 2.0` to compress
 - **Terminal size** — if output wraps weird, increase Width or reduce FontSize
+- **TUI apps without holdpty** — apps that need a real PTY for colors (pi, htop, lazygit) will render without colors if launched directly from VHS. Use the holdpty pattern above.