@wipcomputer/wip-ai-devops-toolbox 1.9.20

package/tools/wip-universal-installer/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+
+
+
+
+
+
+## 2.1.5 (2026-02-21)
+
+Update description to reflect Universal Interface spec purpose
+
+## 2.1.4 (2026-02-21)
+
+Add one-liner to README: what it does and teaches your AI too
+
+## 2.1.3 (2026-02-21)
+
+Fix npm bin entry: rename install.mjs to install.js so npx wip-install works globally
+
+## 2.1.2 (2026-02-21)
+
+Move detailed content to REFERENCE.md. README keeps Problem, Karpathy, Install prompt.
+
+## 2.1.1 (2026-02-21)
+
+Add Universal Interface badges, agent-driven install prompt, fix description
+
+## 2.1.0 (2026-02-21)
+
+Rename Six Doors to Universal Interface. Update all code and docs.
+
+## 2.0.0 (2026-02-20)
+
+Major refactor. Reframed from "WIP Computer installer" to "the spec for agent-native software."
+
+### Added
+- `detect.mjs` ... importable door detection module
+- `SPEC.md` ... formal Six Doors specification
+- `--dry-run` flag ... detect doors without installing
+- `--json` flag ... machine-readable detection output
+- `LICENSE` (MIT)
+- `SKILL.md` with agent instructions
+- `examples/minimal/` ... minimal six-door template
+
+### Changed
+- README rewritten around Karpathy's sensor/actuator argument
+- `install.mjs` now imports detection logic from `detect.mjs`
+- Package name updated: `@wipcomputer/universal-installer`
+
+## 1.0.0 (2026-02-17)
+
+Initial release. Universal installer for WIP.computer repos.
+
+- Detects 6 door types: CLI, Module, MCP, OpenClaw, Skill, CC Hook
+- Installs from GitHub URL, org/repo shorthand, or local path
+- Supports any WIP.computer convention repo

package/tools/wip-universal-installer/LICENSE

@@ -0,0 +1,52 @@
+Dual License: MIT + AGPLv3
+
+Copyright (c) 2026 WIP Computer, Inc.
+
+
+1. MIT License (local and personal use)
+---------------------------------------
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+
+2. GNU Affero General Public License v3.0 (commercial and cloud use)
+--------------------------------------------------------------------
+
+If you run this software as part of a hosted service, cloud platform,
+marketplace listing, or any network-accessible offering for commercial
+purposes, the AGPLv3 terms apply. You must either:
+
+  a) Release your complete source code under AGPLv3, or
+  b) Obtain a commercial license.
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as published
+by the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+
+AGPLv3 for personal use is free. Commercial licenses available.

package/tools/wip-universal-installer/README.md

@@ -0,0 +1,81 @@
+###### WIP Computer
+
+[![npm](https://img.shields.io/npm/v/@wipcomputer/universal-installer)](https://www.npmjs.com/package/@wipcomputer/universal-installer) [![CLI / TUI](https://img.shields.io/badge/interface-CLI_/_TUI-black)](https://github.com/wipcomputer/wip-universal-installer/blob/main/install.js) [![OpenClaw Skill](https://img.shields.io/badge/interface-OpenClaw_Skill-black)](https://clawhub.ai/parkertoddbrooks/wip-universal-installer) [![Claude Code Skill](https://img.shields.io/badge/interface-Claude_Code_Skill-black)](https://github.com/wipcomputer/wip-universal-installer/blob/main/SKILL.md) [![Universal Interface Spec](https://img.shields.io/badge/Universal_Interface_Spec-black?style=flat&color=black)](https://github.com/wipcomputer/wip-universal-installer/blob/main/SPEC.md)
+
+# Universal Installer
+
+Here's how to build software in 2026.
+
+## The Badges
+
+The chiclets at the top of this README tell you what interfaces this repo ships. Every repo that follows the Universal Interface Spec declares its interfaces the same way.
+
+| Badge | What it means |
+|-------|--------------|
+| **npm** | Published to npm. Installable via `npm install`. Versioned, dependency-managed, standard distribution. |
+| **CLI / TUI** | Ships a command-line interface. Humans run it in a terminal. Agents call it from shell. The most portable interface there is. |
+| **OpenClaw Skill** | Registered as a skill on [ClawHub](https://clawhub.ai). OpenClaw agents can discover and use it natively through the gateway. |
+| **Claude Code Skill** | Has a `SKILL.md` that teaches Claude Code (and any agent that reads markdown) when to use this tool, what it does, and how to call it. The agent reads the file and learns the capability. |
+| **Universal Interface Spec** | Follows the [SPEC.md](SPEC.md) convention. The repo's architecture is documented, the interfaces are declared, and any agent or human can understand the full surface area by reading one file. |
+
+When you see these badges on a WIP repo, you know exactly how to consume it. Human or agent, CLI or plugin, local or remote. That's the point.
+
+## The Problem
+
+Most software is built for humans. GUIs, dashboards, web apps. Humans click buttons, fill forms, read screens.
+
+But the users are changing. AI agents are the new users. They don't click. They call functions. They read instructions. They compose tools. They need a **universal interface** ... multiple ways into the same logic, native to however the consumer works.
+
+Software built for humans doesn't work for agents. And software built only for agents doesn't work for humans. You need both.
+
+`wip-universal-installer` gives all your repos the Universal Interface, and teaches your AI how to do it too.
+
+## The Karpathy Argument
+
+Andrej Karpathy put it clearly:
+
+> "I think the app store, the move to mobile, the concept of an app ... is an increasingly outdated concept. What matters are sensors and actuators. Sensors are things that convert physical state into digital state. Actuators are things that convert digital intent into physical change."
+>
+> "All LLMs care about are tools and the tools fall into this sensor/actuator divide. Software shouldn't be built into apps, but into small bespoke tools. Apps are for people. Tools are for LLMs, and increasingly, LLMs are the ones using software."
+
+[Source](https://x.com/karpathy/status/2024583544157458452)
+
+This is the future of software. Not apps. Tools. Sensors and actuators that agents compose together.
+
+## Install
+
+Open your AI coding tool and say:
+
+```
+Read the SPEC.md and SKILL.md at github.com/wipcomputer/wip-universal-installer.
+Then explain to me:
+1. What is this tool?
+2. What does it do?
+3. What would it change or fix in our current system?
+
+Then ask me:
+- Do you have more questions?
+- Do you want to integrate it into our system?
+- Do you want to clone it (use as-is) or fork it (so you can contribute back if you find bugs)?
+```
+
+Your agent will read the repo, explain the tool, and walk you through integration interactively.
+
+Also see **[wip-release](https://github.com/wipcomputer/wip-release)** ... one-command release pipeline for agent-native software.
+
+Also see **[wip-file-guard](https://github.com/wipcomputer/wip-file-guard)** ... the lock for the repo. Blocks AI agents from overwriting your critical files.
+
+See [REFERENCE.md](REFERENCE.md) for sensors/actuators, the interface table, how to build it, the installer, and real examples.
+
+---
+
+## License
+
+```
+CLI, module, skills                            MIT    (use anywhere, no restrictions)
+Hosted or cloud service use                    AGPL   (network service distribution)
+```
+
+AGPL for personal use is free.
+
+Built by Parker Todd Brooks, Lēsa (OpenClaw, Claude Opus 4.6), Claude Code (Claude Opus 4.6).

package/tools/wip-universal-installer/REFERENCE.md

@@ -0,0 +1,122 @@
+###### WIP Computer
+# Universal Installer ... Reference
+
+Sensors/actuators, the interface table, how to build it, the installer, and real examples.
+
+## Sensors and Actuators
+
+Every tool is a sensor, an actuator, or both:
+
+**Sensors** convert state into data:
+- Search the web (wip-grok search_web)
+- Search X/Twitter (wip-grok search_x, wip-x search_recent)
+- Fetch a post (wip-x fetch_post)
+- Read bookmarks (wip-x get_bookmarks)
+- Check system health (wip-healthcheck)
+
+**Actuators** convert intent into action:
+- Generate an image (wip-grok generate_image)
+- Post a tweet (wip-x post_tweet)
+- Guard a file from edits (wip-file-guard)
+- Generate a video (wip-grok generate_video)
+
+## The Universal Interface
+
+Agents don't all speak the same language. Some run shell commands. Some import modules. Some talk MCP. Some read markdown instructions.
+
+So every tool should expose multiple interfaces into the same core logic:
+
+| Interface | What | Who uses it |
+|-----------|------|-------------|
+| **CLI** | Shell command | Humans, any agent with bash |
+| **Module** | ES import | Other tools, scripts |
+| **MCP Server** | JSON-RPC over stdio | Claude Code, Cursor, any MCP client |
+| **OpenClaw Plugin** | Lifecycle hooks + tools | OpenClaw agents |
+| **Skill** | Markdown instructions (SKILL.md) | Any agent that reads files |
+| **Claude Code Hook** | PreToolUse/Stop events | Claude Code |
+
+Not every tool needs all six. Build what makes sense. But the more interfaces you expose, the more agents can use your tool.
+
+See [SPEC.md](SPEC.md) for the full specification.
+
+## How to Build It
+
+The architecture is simple. Four files:
+
+```
+your-tool/
+  core.mjs            <- pure logic, zero deps if possible
+  cli.mjs             <- thin CLI wrapper
+  mcp-server.mjs      <- MCP server wrapping core as tools
+  SKILL.md            <- when/how to use it, for agents
+```
+
+`core.mjs` does the work. Everything else is a thin wrapper. CLI parses argv and calls core. MCP server maps tools to core functions. SKILL.md teaches agents when to call what.
+
+This means one codebase, one set of tests, multiple interfaces.
+
+## The Reference Installer
+
+`wip-install` scans any repo, detects which interfaces exist, and installs them all. One command.
+
+```bash
+# From GitHub
+wip-install wipcomputer/wip-grok
+
+# From a local path
+wip-install /path/to/repo
+
+# Detect only (no install)
+wip-install --dry-run wipcomputer/wip-x
+
+# Machine-readable output
+wip-install --json /path/to/repo
+```
+
+### Example Output
+
+```
+  Installing: wip-grok
+  ────────────────────────────────────────
+  Detected 4 interface(s): cli, module, mcp, skill
+
+  ✓ CLI: wip-grok installed globally
+  ✓ Module: import from "core.mjs"
+  MCP Server detected: mcp-server.mjs
+  ✓ Skill: SKILL.md available
+
+  Done. 4 interface(s) processed.
+```
+
+### What It Detects
+
+| Pattern | Interface | Install action |
+|---------|-----------|---------------|
+| `package.json` with `bin` | CLI | `npm install -g` |
+| `main` or `exports` in `package.json` | Module | Reports import path |
+| `mcp-server.mjs` | MCP | Prints `.mcp.json` config |
+| `openclaw.plugin.json` | OpenClaw | Copies to `~/.openclaw/extensions/` |
+| `SKILL.md` | Skill | Reports path |
+| `guard.mjs` or `claudeCode.hook` | CC Hook | Adds to `~/.claude/settings.json` |
+
+## Real Examples
+
+| Tool | Type | Interfaces | What it does |
+|------|------|------------|-------------|
+| [wip-grok](https://github.com/wipcomputer/wip-grok) | Sensor + Actuator | CLI + Module + MCP + Skill | xAI Grok API: search web/X, generate images/video |
+| [wip-x](https://github.com/wipcomputer/wip-x) | Sensor + Actuator | CLI + Module + MCP + Skill | X Platform API: read/write tweets, bookmarks |
+| [wip-file-guard](https://github.com/wipcomputer/wip-file-guard) | Actuator | CLI + OpenClaw + CC Hook | Protect files from AI edits |
+| [wip-healthcheck](https://github.com/wipcomputer/wip-healthcheck) | Sensor | CLI + Module | System health monitoring |
+
+## Supported Tools
+
+Works with any AI agent or coding tool that can run shell commands:
+
+| Tool | How |
+|------|-----|
+| Claude Code | CLI via bash, hooks via settings.json, MCP via .mcp.json |
+| OpenAI Codex CLI | CLI via bash, skills via AGENTS.md |
+| Cursor | CLI via terminal, MCP via config |
+| Windsurf | CLI via terminal, MCP via config |
+| OpenClaw | Plugins, skills, MCP |
+| Any agent | CLI works everywhere. If it has a shell, it works. |

package/tools/wip-universal-installer/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: wip-universal-installer
+description: Reference installer for agent-native software. Scans a repo, detects which interfaces it exposes, and installs them all.
+license: MIT
+interface: [cli, module, skill]
+metadata:
+  display-name: "Universal Installer"
+  version: "2.1.5"
+  homepage: "https://github.com/wipcomputer/wip-universal-installer"
+  author: "Parker Todd Brooks"
+  category: dev-tools
+  capabilities:
+    - detect-interfaces
+    - install-cli
+    - install-mcp
+    - install-openclaw-plugin
+    - install-claude-code-hook
+  requires:
+    bins: [node, npm, git]
+  openclaw:
+    requires:
+      bins: [node, npm, git]
+    install:
+      - id: node
+        kind: node
+        package: "@wipcomputer/universal-installer"
+        bins: [wip-install]
+        label: "Install via npm"
+    emoji: "🔌"
+compatibility: Requires git, npm, node. Node.js 18+.
+---
+
+# wip-universal-installer
+
+Reference installer for agent-native software. Scans a repo, detects which interfaces it exposes, and installs them all.
+
+## When to Use This Skill
+
+**Use wip-install for:**
+- Installing any repo that follows the Universal Interface pattern
+- Detecting what interfaces a repo provides
+- Setting up CLI tools, MCP servers, OpenClaw plugins, and Claude Code hooks in one command
+
+**Use detect.mjs for:**
+- Programmatically detecting interfaces in a repo
+- Building custom installers or CI pipelines
+- Validating that a repo follows the spec
+
+### Do NOT Use For
+
+- Installing standard npm packages (use npm directly)
+- Repos that don't follow the Universal Interface conventions
+- Building or compiling code (this only installs)
+
+## API Reference
+
+### CLI
+
+```bash
+wip-install /path/to/repo           # install all interfaces
+wip-install org/repo                 # clone from GitHub + install
+wip-install --dry-run /path/to/repo  # detect only, no changes
+wip-install --json /path/to/repo     # JSON output
+```
+
+### Module (detect.mjs)
+
+```javascript
+import { detectInterfaces, describeInterfaces, detectInterfacesJSON } from './detect.mjs';
+
+const { interfaces, pkg } = detectInterfaces('/path/to/repo');
+console.log(describeInterfaces(interfaces));
+
+const json = detectInterfacesJSON('/path/to/repo');
+console.log(JSON.stringify(json, null, 2));
+```
+
+## Universal Interface
+
+See [SPEC.md](https://github.com/wipcomputer/wip-universal-installer/blob/main/SPEC.md) for the full specification.
+
+1. **CLI** ... `package.json` bin field
+2. **Module** ... `package.json` main/exports
+3. **MCP Server** ... `mcp-server.mjs`
+4. **OpenClaw Plugin** ... `openclaw.plugin.json`
+5. **Skill** ... `SKILL.md`
+6. **Claude Code Hook** ... `guard.mjs` or `claudeCode.hook`

package/tools/wip-universal-installer/SPEC.md

@@ -0,0 +1,180 @@
+# The Universal Interface Specification
+
+Every tool is a sensor, an actuator, or both. Every tool should be accessible through multiple interfaces. We call this the Universal Interface.
+
+This is the spec.
+
+## The Six Interfaces
+
+### 1. CLI
+
+A shell command. The most universal interface. If it has a terminal, it works.
+
+**Convention:** `package.json` with a `bin` field.
+
+**Detection:** `pkg.bin` exists.
+
+**Install:** `npm install -g .` or `npm link`.
+
+```json
+{
+  "bin": {
+    "wip-grok": "./cli.mjs"
+  }
+}
+```
+
+### 2. Module
+
+An importable ES module. The programmatic interface. Other tools compose with it.
+
+**Convention:** `package.json` with `main` or `exports` field. File is `core.mjs` by convention.
+
+**Detection:** `pkg.main` or `pkg.exports` exists.
+
+**Install:** `npm install <package>` or import directly from path.
+
+```json
+{
+  "type": "module",
+  "main": "core.mjs",
+  "exports": {
+    ".": "./core.mjs",
+    "./cli": "./cli.mjs"
+  }
+}
+```
+
+### 3. MCP Server
+
+A JSON-RPC server implementing the Model Context Protocol. Any MCP-compatible agent can use it.
+
+**Convention:** `mcp-server.mjs` (or `.js`, `.ts`) at the repo root. Uses `@modelcontextprotocol/sdk`.
+
+**Detection:** One of `mcp-server.mjs`, `mcp-server.js`, `mcp-server.ts`, `dist/mcp-server.js` exists.
+
+**Install:** Add to `.mcp.json`:
+
+```json
+{
+  "tool-name": {
+    "command": "node",
+    "args": ["/path/to/mcp-server.mjs"]
+  }
+}
+```
+
+### 4. OpenClaw Plugin
+
+A plugin for OpenClaw agents. Lifecycle hooks, tool registration, settings.
+
+**Convention:** `openclaw.plugin.json` at the repo root.
+
+**Detection:** `openclaw.plugin.json` exists.
+
+**Install:** Copy to `~/.openclaw/extensions/<name>/`, run `npm install --omit=dev`.
+
+### 5. Skill (SKILL.md)
+
+A markdown file that teaches agents when and how to use the tool. The instruction interface.
+
+**Convention:** `SKILL.md` at the repo root. YAML frontmatter with name, version, description, metadata.
+
+**Detection:** `SKILL.md` exists.
+
+**Install:** Referenced by path. Agents read it when they need the tool.
+
+```yaml
+---
+name: wip-grok
+version: 1.0.0
+description: xAI Grok API. Search the web, search X, generate images.
+metadata:
+  category: search,media
+  capabilities:
+    - web-search
+    - image-generation
+---
+```
+
+### 6. Claude Code Hook
+
+A hook that runs during Claude Code's tool lifecycle (PreToolUse, Stop, etc.).
+
+**Convention:** `guard.mjs` at repo root, or `claudeCode.hook` in `package.json`.
+
+**Detection:** `guard.mjs` exists, or `pkg.claudeCode.hook` is defined.
+
+**Install:** Added to `~/.claude/settings.json` under `hooks`.
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "Edit|Write",
+      "hooks": [{
+        "type": "command",
+        "command": "node /path/to/guard.mjs",
+        "timeout": 5
+      }]
+    }]
+  }
+}
+```
+
+## Architecture
+
+Every repo that follows this spec has the same basic structure:
+
+```
+your-tool/
+  core.mjs            pure logic, zero or minimal deps
+  cli.mjs             thin CLI wrapper around core
+  mcp-server.mjs      MCP server wrapping core functions as tools
+  SKILL.md            agent instructions with YAML frontmatter
+  package.json         name, bin, main, exports, type: module
+  README.md            human documentation
+  ai/                  development process (plans, todos, notes)
+```
+
+Not every tool needs all six interfaces. Build the ones that make sense.
+
+The minimum viable agent-native tool has two interfaces: **Module** (importable) and **Skill** (agent instructions). Add CLI for humans. Add MCP for agents that speak MCP. Add OpenClaw/CC Hook for specific platforms.
+
+## The `ai/` Folder
+
+Every repo should have an `ai/` folder. This is where agents and humans collaborate on the project ... plans, todos, dev updates, research notes, conversations.
+
+```
+ai/
+  plan/              architecture plans, roadmaps
+  dev-updates/       what was built, session logs
+  todos/
+    PUNCHLIST.md     blockers to ship
+    inboxes/         per-agent action items
+  notes/             research, references, raw conversation logs
+```
+
+The `ai/` folder is the development process. It is not part of the published product.
+
+**Public/private split:** If a repo is public, the `ai/` folder should not ship. The recommended pattern is to maintain a private working repo (with `ai/`) and a public repo (everything except `ai/`). The public repo has everything an LLM or human needs to understand and use the tool. The `ai/` folder is operational context for the team building it.
+
+## The Reference Installer
+
+`wip-install` is the reference implementation. It scans a repo, detects which interfaces exist, and installs them all. One command.
+
+```bash
+wip-install /path/to/repo          # local
+wip-install org/repo               # from GitHub
+wip-install --dry-run /path/to/repo # detect only
+wip-install --json /path/to/repo    # JSON output
+```
+
+## Examples
+
+| Repo | Interfaces | Type |
+|------|------------|------|
+| [wip-grok](https://github.com/wipcomputer/wip-grok) | CLI + Module + MCP + Skill | Sensor + Actuator |
+| [wip-x](https://github.com/wipcomputer/wip-x) | CLI + Module + MCP + Skill | Sensor + Actuator |
+| [wip-file-guard](https://github.com/wipcomputer/wip-file-guard) | CLI + OpenClaw + CC Hook | Actuator |
+| [wip-markdown-viewer](https://github.com/wipcomputer/wip-markdown-viewer) | CLI + Module | Actuator |