@wipcomputer/wip-ldm-os 0.3.6 → 0.4.1

package/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 interface: [cli, skill]
 metadata:
   display-name: "LDM OS"
-  version: "0.3.6"
+  version: "0.4.1"
   homepage: "https://github.com/wipcomputer/wip-ldm-os"
   author: "Parker Todd Brooks"
   category: infrastructure

package/bin/ldm.js

@@ -1056,6 +1056,235 @@ async function cmdUpdates() {
   console.log('');
 }
 
+// ── ldm stack ──
+
+async function cmdStack() {
+  const subcommand = args[1];
+
+  if (!subcommand || subcommand === 'list') {
+    return cmdStackList();
+  }
+  if (subcommand === 'install') {
+    return cmdStackInstall();
+  }
+
+  console.error(`  Unknown stack subcommand: ${subcommand}`);
+  console.error('  Usage: ldm stack [list | install <name>]');
+  process.exit(1);
+}
+
+function loadStacks() {
+  return CATALOG.stacks || {};
+}
+
+function resolveStack(name) {
+  const stacks = loadStacks();
+  const stack = stacks[name];
+  if (!stack) return null;
+
+  // Resolve "includes" (compose stacks from other stacks)
+  let components = [...(stack.components || [])];
+  let mcpServers = [...(stack.mcpServers || [])];
+
+  if (stack.includes) {
+    for (const inc of stack.includes) {
+      const sub = stacks[inc];
+      if (sub) {
+        components = [...(sub.components || []), ...components];
+        mcpServers = [...(sub.mcpServers || []), ...mcpServers];
+      }
+    }
+  }
+
+  // Deduplicate
+  components = [...new Set(components)];
+  const seenMcp = new Set();
+  mcpServers = mcpServers.filter(m => {
+    if (seenMcp.has(m.name)) return false;
+    seenMcp.add(m.name);
+    return true;
+  });
+
+  return { ...stack, components, mcpServers };
+}
+
+function cmdStackList() {
+  const stacks = loadStacks();
+
+  console.log('');
+  console.log('  Available Stacks');
+  console.log('  ────────────────────────────────────');
+
+  if (Object.keys(stacks).length === 0) {
+    console.log('  No stacks defined in catalog.');
+    console.log('');
+    return;
+  }
+
+  for (const [id, stack] of Object.entries(stacks)) {
+    const resolved = resolveStack(id);
+    const compCount = resolved.components.length;
+    const mcpCount = resolved.mcpServers.length;
+    console.log(`  ${id}: ${stack.name}`);
+    console.log(`    ${stack.description}`);
+    console.log(`    ${compCount} component(s), ${mcpCount} MCP server(s)`);
+    console.log('');
+  }
+
+  console.log('  Install: ldm stack install <name>');
+  console.log('  Preview: ldm stack install <name> --dry-run');
+  console.log('');
+}
+
+async function cmdStackInstall() {
+  const stackName = args.slice(2).find(a => !a.startsWith('--'));
+
+  if (!stackName) {
+    console.error('  Usage: ldm stack install <name> [--dry-run]');
+    console.error('  Run: ldm stack list');
+    process.exit(1);
+  }
+
+  const stack = resolveStack(stackName);
+  if (!stack) {
+    console.error(`  Unknown stack: "${stackName}"`);
+    console.error('  Run: ldm stack list');
+    process.exit(1);
+  }
+
+  console.log('');
+  console.log(`  Stack: ${stack.name}`);
+  console.log(`  ────────────────────────────────────`);
+  console.log(`  ${stack.description}`);
+  console.log('');
+
+  // Check what's already installed
+  const registry = readJSON(REGISTRY_PATH);
+  const registeredNames = Object.keys(registry?.extensions || {});
+
+  const ccUserPath = join(HOME, '.claude.json');
+  const ccUser = readJSON(ccUserPath);
+  const registeredMcp = Object.keys(ccUser?.mcpServers || {});
+
+  // Components
+  const componentsToInstall = [];
+  const componentsInstalled = [];
+  for (const compId of stack.components) {
+    const entry = findInCatalog(compId);
+    if (!entry) continue;
+
+    // Check if already installed
+    const matches = entry.registryMatches || [compId];
+    const installed = matches.some(m => registeredNames.includes(m));
+    if (installed) {
+      componentsInstalled.push(entry);
+    } else {
+      componentsToInstall.push(entry);
+    }
+  }
+
+  // MCP servers
+  const mcpToInstall = [];
+  const mcpInstalled = [];
+  for (const mcp of stack.mcpServers) {
+    if (registeredMcp.includes(mcp.name)) {
+      mcpInstalled.push(mcp);
+    } else {
+      mcpToInstall.push(mcp);
+    }
+  }
+
+  // Show status
+  if (componentsInstalled.length > 0) {
+    console.log(`  Already installed (${componentsInstalled.length}):`);
+    for (const c of componentsInstalled) {
+      console.log(`    [x] ${c.name}`);
+    }
+    console.log('');
+  }
+
+  if (mcpInstalled.length > 0) {
+    console.log(`  MCP servers already registered (${mcpInstalled.length}):`);
+    for (const m of mcpInstalled) {
+      console.log(`    [x] ${m.name}`);
+    }
+    console.log('');
+  }
+
+  if (componentsToInstall.length > 0) {
+    console.log(`  Components to install (${componentsToInstall.length}):`);
+    for (const c of componentsToInstall) {
+      console.log(`    [ ] ${c.name} (${c.repo})`);
+    }
+    console.log('');
+  }
+
+  if (mcpToInstall.length > 0) {
+    console.log(`  MCP servers to add (${mcpToInstall.length}):`);
+    for (const m of mcpToInstall) {
+      console.log(`    [ ] ${m.name} (${m.command} ${m.args.join(' ')})`);
+    }
+    console.log('');
+  }
+
+  if (componentsToInstall.length === 0 && mcpToInstall.length === 0) {
+    console.log('  Everything in this stack is already installed.');
+    console.log('');
+    return;
+  }
+
+  if (DRY_RUN) {
+    console.log(`  Would install ${componentsToInstall.length} component(s) and ${mcpToInstall.length} MCP server(s).`);
+    console.log('  Dry run complete. No changes made.');
+    console.log('');
+    return;
+  }
+
+  // Install components via ldm install
+  let installed = 0;
+  for (const c of componentsToInstall) {
+    console.log(`  Installing ${c.name}...`);
+    try {
+      execSync(`ldm install ${c.repo}`, { stdio: 'inherit' });
+      installed++;
+    } catch (e) {
+      console.error(`  x Failed to install ${c.name}: ${e.message}`);
+    }
+  }
+
+  // Register MCP servers
+  let mcpAdded = 0;
+  for (const mcp of mcpToInstall) {
+    console.log(`  Adding MCP: ${mcp.name}...`);
+    try {
+      const mcpArgs = mcp.args.map(a => `"${a}"`).join(' ');
+      execSync(`claude mcp add --scope user ${mcp.name} -- ${mcp.command} ${mcpArgs}`, { stdio: 'pipe' });
+      console.log(`  + MCP: ${mcp.name} registered (user scope)`);
+      mcpAdded++;
+    } catch (e) {
+      // Fallback: write directly to ~/.claude.json
+      try {
+        const config = readJSON(ccUserPath) || {};
+        if (!config.mcpServers) config.mcpServers = {};
+        config.mcpServers[mcp.name] = {
+          command: mcp.command,
+          args: mcp.args,
+        };
+        writeJSON(ccUserPath, config);
+        console.log(`  + MCP: ${mcp.name} registered in ~/.claude.json (fallback)`);
+        mcpAdded++;
+      } catch (e2) {
+        console.error(`  x MCP: ${mcp.name} failed: ${e2.message}`);
+      }
+    }
+  }
+
+  console.log('');
+  console.log(`  Done. ${installed} component(s) installed, ${mcpAdded} MCP server(s) added.`);
+  console.log('  Restart your session to load new MCP servers.');
+  console.log('');
+}
+
 // ── Main ──
 
 async function main() {
@@ -1075,6 +1304,8 @@ async function main() {
     console.log('    ldm msg send <to> <body>    Send a message to a session');
     console.log('    ldm msg list                List pending messages');
     console.log('    ldm msg broadcast <body>    Send to all sessions');
+    console.log('    ldm stack list               Show available stacks');
+    console.log('    ldm stack install <name>     Install a stack (core, web, all)');
     console.log('    ldm updates                 Show available updates from cache');
     console.log('    ldm updates --check         Re-check npm registry for updates');
     console.log('');
@@ -1125,6 +1356,9 @@ async function main() {
     case 'msg':
       await cmdMsg();
       break;
+    case 'stack':
+      await cmdStack();
+      break;
     case 'updates':
       await cmdUpdates();
       break;

package/bin/wip-install.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// wip-install: thin bootstrap + delegate to ldm install.
+// If ldm is on PATH, delegates immediately.
+// If not, installs LDM OS from npm, then delegates.
+// Replaces the standalone 700-line install.js from wip-ai-devops-toolbox.
+
+import { run } from '../lib/bootstrap.mjs';
+run(process.argv.slice(2));

package/catalog.json

@@ -1,5 +1,31 @@
 {
-  "version": "0.2.0",
+  "version": "0.3.0",
+  "stacks": {
+    "core": {
+      "name": "WIP Core",
+      "description": "Essential tools for all WIP.computer team members.",
+      "components": ["memory-crystal", "wip-ai-devops-toolbox", "wip-1password", "wip-markdown-viewer"],
+      "mcpServers": []
+    },
+    "web": {
+      "name": "Web Development",
+      "description": "Frontend tools for Next.js, React, Tailwind projects.",
+      "components": [],
+      "mcpServers": [
+        { "name": "playwright", "command": "npx", "args": ["-y", "@playwright/mcp@latest", "--browser", "chromium"] },
+        { "name": "next-devtools", "command": "npx", "args": ["-y", "next-devtools-mcp@latest"] },
+        { "name": "shadcn", "command": "npx", "args": ["-y", "shadcn@latest", "mcp"] },
+        { "name": "tailwindcss-docs", "command": "npx", "args": ["-y", "tailwindcss-docs-mcp"] }
+      ]
+    },
+    "all": {
+      "name": "Everything",
+      "description": "All WIP tools + web dev stack.",
+      "includes": ["core", "web"],
+      "components": ["wip-xai-grok", "wip-xai-x"],
+      "mcpServers": []
+    }
+  },
   "components": [
     {
       "id": "memory-crystal",

package/docs/universal-installer/SPEC.md

@@ -0,0 +1,206 @@
+# 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
+
+`ldm install` is the primary installer (part of LDM OS). `wip-install` is the standalone fallback. Both scan a repo, detect which interfaces exist, and install them all. One command.
+
+```bash
+ldm install /path/to/repo           # local (via LDM OS)
+ldm install org/repo                # from GitHub
+ldm install org/repo --dry-run      # detect only
+wip-install /path/to/repo           # standalone fallback (bootstraps LDM OS if needed)
+wip-install --json /path/to/repo    # JSON output
+```
+
+For toolbox repos (with a `tools/` directory containing sub-tools), the installer enters toolbox mode and installs each sub-tool.
+
+## Examples
+
+### AI DevOps Toolbox (this repo)
+
+| # | Tool | Interfaces |
+|---|------|------------|
+| | **Repo Management** | |
+| 1 | [Repo Visibility Guard](tools/wip-repo-permissions-hook/) | CLI + Module + MCP + OpenClaw + Skill + CC Hook |
+| 2 | [Repo Manifest Reconciler](tools/wip-repos/) | CLI + Module + MCP + Skill |
+| 3 | [Repo Init](tools/wip-repo-init/) | CLI + Skill |
+| 4 | [README Formatter](tools/wip-readme-format/) | CLI + Skill |
+| 5 | [Branch Guard](tools/wip-branch-guard/) | CLI + Module + CC Hook |
+| | **License, Compliance, and Protection** | |
+| 6 | [Identity File Protection](tools/wip-file-guard/) | CLI + Module + OpenClaw + Skill + CC Hook |
+| 7 | [License Guard](tools/wip-license-guard/) | CLI + Skill |
+| 8 | [License Rug-Pull Detection](tools/wip-license-hook/) | CLI + Module + MCP + Skill |
+| | **Release & Deploy** | |
+| 9 | [Release Pipeline](tools/wip-release/) | CLI + Module + MCP + Skill |
+| 10 | [Private-to-Public Sync](tools/deploy-public/) | CLI + Skill |
+| 11 | [Post-Merge Branch Naming](tools/post-merge-rename/) | CLI + Skill |
+| 12 | [Universal Installer](tools/wip-universal-installer/) | CLI + Module + Skill |
+
+### Other WIP Computer Tools
+
+| Repo | Interfaces |
+|------|------------|
+| [Memory Crystal](https://github.com/wipcomputer/memory-crystal) | CLI + Module + MCP + OpenClaw + Skill |
+| [LDM OS](https://github.com/wipcomputer/wip-ldm-os) | CLI + Module + Skill + CC Hook |
+| [wip-grok](https://github.com/wipcomputer/wip-grok) | CLI + Module + MCP + Skill |
+| [wip-x](https://github.com/wipcomputer/wip-x) | CLI + Module + MCP + Skill |
+| [Markdown Viewer](https://github.com/wipcomputer/wip-markdown-viewer) | CLI + Module |

package/lib/bootstrap.mjs

@@ -0,0 +1,92 @@
+/**
+ * lib/bootstrap.mjs
+ * Thin bootstrap for wip-install.
+ * If ldm is on PATH, delegates to ldm install.
+ * If not, installs LDM OS from npm, then delegates.
+ * This replaces the 700-line standalone install.js from the toolbox.
+ * Zero external dependencies.
+ */
+
+import { execSync } from 'node:child_process';
+
+/**
+ * Check if ldm CLI is available on PATH.
+ * @returns {boolean}
+ */
+export function isLdmAvailable() {
+  try {
+    execSync('ldm --version', { stdio: 'pipe', timeout: 5000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Install LDM OS from npm registry.
+ * @returns {boolean} true if install succeeded
+ */
+export function bootstrapLdmOs() {
+  try {
+    execSync('npm install -g @wipcomputer/wip-ldm-os', { stdio: 'pipe', timeout: 120000 });
+    execSync('ldm init --yes --none', { stdio: 'pipe', timeout: 30000 });
+    return isLdmAvailable();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Delegate to ldm install with the given arguments.
+ * @param {string} target - what to install (org/repo, path, or empty for update-all)
+ * @param {string[]} flags - CLI flags (--dry-run, --json, etc.)
+ */
+export function delegateToLdm(target, flags = []) {
+  const cmd = target
+    ? `ldm install ${target} ${flags.join(' ')}`
+    : `ldm install ${flags.join(' ')}`;
+  execSync(cmd.trim(), { stdio: 'inherit' });
+}
+
+/**
+ * Full bootstrap + delegate flow.
+ * Called by wip-install as the entry point.
+ * @param {string[]} argv - process.argv.slice(2)
+ */
+export function run(argv) {
+  const target = argv.find(a => !a.startsWith('--'));
+  const flags = argv.filter(a => a.startsWith('--'));
+  const jsonOutput = flags.includes('--json');
+
+  if (isLdmAvailable()) {
+    if (!jsonOutput) {
+      console.log('');
+      console.log('  LDM OS detected. Delegating to ldm install...');
+      console.log('');
+    }
+    delegateToLdm(target, flags);
+    return;
+  }
+
+  // LDM not on PATH, try bootstrap
+  if (!jsonOutput) {
+    console.log('');
+    console.log('  LDM OS not found. Installing...');
+    console.log('');
+  }
+
+  if (bootstrapLdmOs()) {
+    if (!jsonOutput) {
+      console.log('  LDM OS installed. Delegating to ldm install...');
+      console.log('');
+    }
+    delegateToLdm(target, flags);
+  } else {
+    if (!jsonOutput) {
+      console.log('  LDM OS could not be installed automatically.');
+      console.log('  Install manually: npm install -g @wipcomputer/wip-ldm-os');
+      console.log('');
+    }
+    process.exit(1);
+  }
+}

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@wipcomputer/wip-ldm-os",
-  "version": "0.3.6",
+  "version": "0.4.1",
   "type": "module",
   "description": "LDM OS: identity, memory, and sovereignty infrastructure for AI agents",
   "main": "src/boot/boot-hook.mjs",
   "bin": {
     "ldm": "bin/ldm.js",
     "wip-ldm-os": "bin/ldm.js",
+    "wip-install": "bin/wip-install.js",
     "ldm-scaffold": "bin/scaffold.sh",
     "ldm-boot-install": "src/boot/install-cli.js",
     "lesa": "dist/bridge/cli.js"