@wipcomputer/wip-ldm-os 0.4.82-alpha.1 → 0.4.84

package/docs/universal-installer/TECHNICAL.md

@@ -18,23 +18,24 @@ Every tool is a sensor, an actuator, or both. Every tool should be accessible th
 - Guard a file from edits (wip-file-guard)
 - Generate a video (wip-grok generate_video)
 
-## The Seven Interfaces
+## The Eight Interfaces
 
-Agents don't all speak the same language. Some run shell commands. Some import modules. Some talk MCP. Some read markdown instructions.
+Agents don't all speak the same language. Some run shell commands. Some import modules. Some talk MCP over stdio. Some talk MCP over HTTPS. 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 |
-| **Claude Code Plugin** | Distributable package (skills, agents, hooks, MCP, LSP) | Claude Code marketplace |
+| # | Interface | What | Who uses it |
+|---|-----------|------|-------------|
+| 1 | **CLI** | Shell command | Humans, any agent with bash |
+| 2 | **Module** | ES import | Other tools, scripts |
+| 3 | **MCP Server (local stdio)** | JSON-RPC over stdio | Claude Code, Cursor, OpenClaw |
+| 4 | **Remote MCP** | JSON-RPC over HTTPS (SSE / streamable HTTP) | Claude Desktop, web, mobile |
+| 5 | **OpenClaw Plugin** | Lifecycle hooks + tools | OpenClaw agents |
+| 6 | **Skill** | Markdown instructions (SKILL.md) | Any agent that reads files |
+| 7 | **Claude Code Hook** | PreToolUse/Stop events | Claude Code |
+| 8 | **Claude Code Plugin** | Distributable package (skills, agents, hooks, MCP, LSP) | Claude Code marketplace |
 
-Not every tool needs all seven. Build what makes sense. But the more interfaces you expose, the more agents can use your tool.
+Not every tool needs all eight. Build what makes sense. But the more interfaces you expose, the more agents can use your tool. Local and Remote MCP are sibling transports of the same protocol; they sit next to each other so the relationship is obvious.
 
 ### 1. CLI
 
@@ -75,15 +76,15 @@ An importable ES module. The programmatic interface. Other tools compose with it
 }
 ```
 
-### 3. MCP Server
+### 3. MCP Server (local stdio)
 
-A JSON-RPC server implementing the Model Context Protocol. Any MCP-compatible agent can use it.
+A JSON-RPC server implementing the Model Context Protocol over stdio. Spawned as a child process by the agent. For the HTTP/SSE sibling, see [#4 Remote MCP](#4-remote-mcp).
 
 **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`:
+**Install:** Add to `.mcp.json` with `command` + `args`:
 
 ```json
 {
@@ -94,7 +95,46 @@ A JSON-RPC server implementing the Model Context Protocol. Any MCP-compatible ag
 }
 ```
 
-### 4. OpenClaw Plugin
+### 4. Remote MCP
+
+The HTTP/SSE (or streamable HTTP) sibling of #3. Hosted at an HTTPS endpoint, not spawned locally. The transport that lights up Claude Desktop connectors, web, and mobile clients.
+
+**Contract:** Remote MCP endpoint is **declared by package/catalog metadata** and **registered by `ldm install`**. No filesystem-sniffing fallback.
+
+**Convention:** `mcp.remote` field in `package.json`:
+
+```json
+{
+  "mcp": {
+    "remote": {
+      "url": "https://example.com/mcp",
+      "transport": "streamable-http",
+      "auth": "oauth"
+    }
+  }
+}
+```
+
+`url` may be a placeholder (`"https://__DEPLOYED_URL__"`) when the repo ships the server code and the catalog supplies the URL at install time.
+
+**Detection:** `package.json.mcp.remote.url` is a string.
+
+**Install:** Add to `.mcp.json` as a remote entry, plus print a one-line Claude Desktop hint:
+
+```json
+{
+  "tool-name": {
+    "url": "https://example.com/mcp",
+    "transport": "streamable-http"
+  }
+}
+```
+
+**Auth:** `none` writes the URL as-is. `shared-secret` prompts the user once and stores out-of-band. `oauth` is gated behind a follow-up ticket; first cut prints a TODO.
+
+**Implementation status:** detection + install action are tracked in `ai/product/bugs/installer/` (see [Remote MCP detection](../../ai/product/bugs/installer/2026-04-28--cc-mini--installer-remote-mcp-detection.md) and [Remote MCP install](../../ai/product/bugs/installer/2026-04-28--cc-mini--installer-remote-mcp-install.md)). The spec is canonical now; the detector and installer catch up next.
+
+### 5. OpenClaw Plugin
 
 A plugin for OpenClaw agents. Lifecycle hooks, tool registration, settings.
 
@@ -104,12 +144,14 @@ A plugin for OpenClaw agents. Lifecycle hooks, tool registration, settings.
 
 **Install:** Copy to `~/.openclaw/extensions/<name>/`, run `npm install --omit=dev`.
 
-### 5. Skill (SKILL.md)
+### 6. Skill (SKILL.md)
 
 A markdown file that teaches agents when and how to use the tool. The instruction interface. Follows the [Agent Skills Spec](https://agentskills.io/specification).
 
 **Convention:** `SKILL.md` at the repo root. Optional `references/` directory for context files.
 
+**Platform variants:** Codex CLI reads `AGENTS.md` with the same role and content shape. Treat as the Codex-flavored filename for this same interface, not a separate one.
+
 **Detection:** `SKILL.md` exists.
 
 **Install:** `ldm install` deploys `SKILL.md` to `~/.openclaw/skills/<name>/`. If `references/` exists, it is deployed alongside and also to `settings/docs/skills/<name>/` in the workspace (so all agents can read them).
@@ -132,7 +174,7 @@ metadata:
 ---
 ```
 
-### 6. Claude Code Hook
+### 7. Claude Code Hook
 
 A hook that runs during Claude Code's tool lifecycle (PreToolUse, Stop, etc.).
 
@@ -157,7 +199,7 @@ A hook that runs during Claude Code's tool lifecycle (PreToolUse, Stop, etc.).
 }
 ```
 
-### 7. Claude Code Plugin
+### 8. Claude Code Plugin
 
 A distributable plugin for Claude Code. Bundles skills, agents, hooks, MCP servers, and LSP servers into one installable package. Shareable via marketplaces.
 
@@ -188,6 +230,14 @@ your-plugin/
 }
 ```
 
+### Out of scope by design
+
+Disposable, agent-generated artifacts (custom dashboards, ephemeral scripts, one-off automations) are out of scope for this spec. They are products of an agent, not Universal Interface products. The eight interfaces describe what the agent has to *compose with*. Worked example: [SPEC.md ... Worked example (compact sketch)](SPEC.md#worked-example-compact-sketch).
+
+### Future considerations
+
+*LSP as a standalone interface (#9).* LSP servers are currently surfaced via Claude Code Plugin bundles (#8) ... `.lsp.json` is part of the plugin shape. If a product ships a standalone LSP server outside a CC Plugin, we will add it as a numbered interface. Not added today.
+
 ## How to Build It
 
 The architecture is simple. Four files:
@@ -206,30 +256,33 @@ This means one codebase, one set of tests, multiple interfaces.
 
 ## Install Prompt Template
 
-Every product gets an install prompt. Paste it into any AI. The AI reads the spec, explains it, checks what's installed, and walks you through a dry run.
+Every product gets an install prompt. Paste it into any AI. The AI reads the install spec, explains the product, checks what's installed, and walks you through a dry run before touching anything.
+
+The install spec URL convention, behavior contract, track flags, and `agent.txt` distinction are defined in [SPEC.md ... Install Spec](SPEC.md#install-spec). This is the canonical paste-into-an-AI form:
 
 ```
-Read wip.computer/install/{URL}
+Read https://wip.computer/install/<slug>.txt
 
-Then explain:
-1. What is {name of product}?
+Check if <product name> is already installed. If it is, run
+`ldm install --dry-run <slug>` and show me what I have and what's new.
+
+If not, walk me through setup and explain:
+1. What is <product name>?
 2. What does it install on my system?
 3. What changes for us? (this AI)
 4. What changes across all my AIs?
 
-Check if {name of product} is already installed.
-
-If it is, show me what I have and what's new.
-
 Then ask:
 - Do you have questions?
 - Want to see a dry run?
 
-If I say yes, run: {product-init} init --dry-run
+If I say yes, run: ldm install --dry-run <slug>
 
 Show me exactly what will change. Don't install anything until I say "install".
 ```
 
+Tracks: append `--alpha` or `--beta` to install a prerelease (e.g. `ldm install --beta <slug>`). The same install spec URL covers all tracks.
+
 ## 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.
@@ -308,7 +361,8 @@ ldm install                            # update all
 |---------|-----------|---------------|
 | `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 |
+| `mcp-server.mjs` | MCP (local stdio) | Adds `command` + `args` entry to `.mcp.json` |
+| `mcp.remote.url` in `package.json` | Remote MCP | Adds `url` + `transport` entry to `.mcp.json`; prints Claude Desktop hint. **Implementation in flight ([ticket](../../ai/product/bugs/installer/2026-04-28--cc-mini--installer-remote-mcp-detection.md)).** |
 | `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` |
@@ -323,6 +377,7 @@ ldm install                            # update all
 | [wip-file-guard](https://github.com/wipcomputer/wip-ai-devops-toolbox/tree/main/tools/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 |
 | [wip-markdown-viewer](https://github.com/wipcomputer/wip-markdown-viewer) | Actuator | CLI + Module | Live markdown viewer |
+| [wip-codex-remote-control](https://wip.computer/install/wip-codex-remote-control.txt) | Sensor + Actuator | CLI + Module + MCP + Skill + Install Spec | Pair phone with Codex; AI-led install via published install spec. Worked example of the install-spec URL pattern. |
 
 ## Supported Tools
 

package/lib/bin-manifest.mjs

@@ -0,0 +1,257 @@
+// lib/bin-manifest.mjs — bin ownership manifest aggregator + heal helpers
+//
+// Implements the design at
+// ai/product/plans-prds/current/2026-04-28--cc-mini--ldm-bin-ownership-manifest-design.md
+//
+// Two declarers contribute entries:
+//   - LDM CLI: package.json `wipLdmOs.binFiles`
+//   - Extensions: ~/.ldm/extensions/<name>/openclaw.plugin.json `binFiles`
+//
+// Aggregation produces { entries, conflicts }. Conflicts are hard
+// failures: callers MUST check `conflicts.length === 0` before any
+// write. heal() never runs if conflicts exist.
+
+import { existsSync, readFileSync, statSync, mkdirSync, copyFileSync, chmodSync } from 'node:fs';
+import { join, dirname, basename } from 'node:path';
+
+/**
+ * @typedef {Object} BinDeclaration
+ * @property {string} name        - basename written to <binDir>/<name>
+ * @property {string} source      - relative to declarer's installed root
+ * @property {boolean} [executable] - default true; chmod 0755 after copy
+ * @property {string} [purpose]   - free-form, surfaces in verbose doctor
+ */
+
+/**
+ * @typedef {Object} BinEntry
+ * @property {string} name
+ * @property {string} destPath    - resolved absolute path under binDir
+ * @property {string} sourcePath  - resolved absolute path
+ * @property {boolean} executable
+ * @property {string} declarer    - 'wip-ldm-os' or extension name
+ * @property {string} [purpose]
+ */
+
+/**
+ * @typedef {Object} Conflict
+ * @property {string} name
+ * @property {{declarer: string, sourcePath: string}[]} declarers
+ */
+
+/**
+ * Validate a single declaration shape. Returns array of error strings (empty = ok).
+ * @param {BinDeclaration} decl
+ * @returns {string[]}
+ */
+export function validateDeclaration(decl) {
+  const errors = [];
+  if (!decl || typeof decl !== 'object') {
+    errors.push('declaration must be an object');
+    return errors;
+  }
+  if (typeof decl.name !== 'string' || !decl.name) {
+    errors.push('"name" must be a non-empty string');
+  } else if (decl.name !== basename(decl.name) || decl.name.includes('/') || decl.name.includes('\\')) {
+    errors.push(`"name" must be a basename, got "${decl.name}"`);
+  } else if (decl.name.includes('..')) {
+    errors.push(`"name" must not contain "..", got "${decl.name}"`);
+  }
+  if (typeof decl.source !== 'string' || !decl.source) {
+    errors.push('"source" must be a non-empty string');
+  } else if (decl.source.includes('..')) {
+    errors.push(`"source" must not contain "..", got "${decl.source}"`);
+  }
+  if (decl.executable !== undefined && typeof decl.executable !== 'boolean') {
+    errors.push('"executable" must be a boolean if provided');
+  }
+  return errors;
+}
+
+/**
+ * Validate all declarations from one declarer (e.g. the LDM CLI's own
+ * `wipLdmOs.binFiles`, or one extension's `binFiles`). Used by both
+ * runtime aggregation and prepublish CI gate.
+ *
+ * Checks: shape per entry, no internal duplicate `name`, `source` exists
+ * on disk under `packageRoot`.
+ *
+ * @param {string} declarer
+ * @param {string} packageRoot - the absolute path to resolve `source` against
+ * @param {BinDeclaration[]} decls
+ * @returns {{valid: boolean, errors: string[]}}
+ */
+export function validateDeclarations(declarer, packageRoot, decls) {
+  const errors = [];
+  if (!Array.isArray(decls)) {
+    return { valid: false, errors: [`${declarer}: binFiles must be an array`] };
+  }
+  const seen = new Set();
+  for (let i = 0; i < decls.length; i++) {
+    const d = decls[i];
+    const ctx = `${declarer}[${i}]${d?.name ? ` ${d.name}` : ''}`;
+    for (const e of validateDeclaration(d)) errors.push(`${ctx}: ${e}`);
+    if (d && typeof d.name === 'string') {
+      if (seen.has(d.name)) errors.push(`${declarer}: duplicate name within declarer: ${d.name}`);
+      seen.add(d.name);
+    }
+    if (d && typeof d.source === 'string') {
+      const src = join(packageRoot, d.source);
+      if (!existsSync(src)) errors.push(`${ctx}: source not found at ${src}`);
+    }
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Read LDM CLI's own bin declarations from its package.json.
+ * @param {string} ldmCliRoot
+ * @returns {BinDeclaration[]}
+ */
+function readLdmCliDeclarations(ldmCliRoot) {
+  const pkgPath = join(ldmCliRoot, 'package.json');
+  if (!existsSync(pkgPath)) return [];
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+    return Array.isArray(pkg?.wipLdmOs?.binFiles) ? pkg.wipLdmOs.binFiles : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Read one extension's bin declarations from its openclaw.plugin.json.
+ * @param {string} extDir - ~/.ldm/extensions/<name>
+ * @returns {BinDeclaration[]}
+ */
+function readExtensionDeclarations(extDir) {
+  const manifestPath = join(extDir, 'openclaw.plugin.json');
+  if (!existsSync(manifestPath)) return [];
+  try {
+    const m = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+    return Array.isArray(m?.binFiles) ? m.binFiles : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Aggregate all bin entries across LDM CLI + registered extensions.
+ * Returns conflicts for any name claimed by 2+ declarers.
+ *
+ * IMPORTANT: callers MUST check `conflicts.length === 0` before doing any
+ * writes. Conflict means we cannot safely decide who owns the file.
+ *
+ * @param {Object} opts
+ * @param {string} opts.ldmCliRoot       - absolute path to LDM CLI package root
+ * @param {string} opts.extensionsRoot   - absolute path, typically ~/.ldm/extensions
+ * @param {string} opts.binDir           - absolute path, typically ~/.ldm/bin
+ * @param {Object} [opts.registry]       - optional ~/.ldm/extensions/registry.json contents
+ * @returns {{entries: BinEntry[], conflicts: Conflict[]}}
+ */
+export function aggregateBinManifest({ ldmCliRoot, extensionsRoot, binDir, registry } = {}) {
+  /** @type {BinEntry[]} */
+  const entries = [];
+  /** @type {Map<string, {declarer: string, sourcePath: string}[]>} */
+  const claims = new Map();
+
+  function record(declarer, declarerRoot, decls) {
+    for (const d of decls) {
+      if (!d || typeof d.name !== 'string' || typeof d.source !== 'string') continue;
+      const sourcePath = join(declarerRoot, d.source);
+      const list = claims.get(d.name) || [];
+      list.push({ declarer, sourcePath });
+      claims.set(d.name, list);
+      entries.push({
+        name: d.name,
+        destPath: join(binDir, d.name),
+        sourcePath,
+        executable: d.executable !== false,
+        declarer,
+        purpose: d.purpose,
+      });
+    }
+  }
+
+  // 1. LDM CLI
+  record('wip-ldm-os', ldmCliRoot, readLdmCliDeclarations(ldmCliRoot));
+
+  // 2. Registered extensions
+  const extNames = registry?.extensions ? Object.keys(registry.extensions) : [];
+  for (const name of extNames) {
+    const extDir = join(extensionsRoot, name);
+    record(name, extDir, readExtensionDeclarations(extDir));
+  }
+
+  /** @type {Conflict[]} */
+  const conflicts = [];
+  for (const [name, declarers] of claims.entries()) {
+    if (declarers.length > 1) conflicts.push({ name, declarers });
+  }
+
+  return { entries, conflicts };
+}
+
+/**
+ * Verify and (optionally) heal each entry. heal=false is read-only and
+ * just classifies. heal=true restores missing/unexecutable files from
+ * `sourcePath`. Returns a per-entry result so callers can build their
+ * own output.
+ *
+ * NEVER call this if aggregateBinManifest reported conflicts. The caller
+ * must abort instead.
+ *
+ * @param {BinEntry[]} entries
+ * @param {Object} [opts]
+ * @param {boolean} [opts.heal] - default false
+ * @returns {{
+ *   ok: BinEntry[],
+ *   missing: BinEntry[],
+ *   notExecutable: BinEntry[],
+ *   sourceMissing: BinEntry[],
+ *   healed: BinEntry[],
+ *   failed: {entry: BinEntry, reason: string}[]
+ * }}
+ */
+export function healBinManifest(entries, opts = {}) {
+  const heal = opts.heal === true;
+  const ok = [];
+  const missing = [];
+  const notExecutable = [];
+  const sourceMissing = [];
+  const healed = [];
+  const failed = [];
+
+  for (const e of entries) {
+    const destExists = existsSync(e.destPath);
+    const destExecutable = destExists && (statSync(e.destPath).mode & 0o111) !== 0;
+    const expectedExec = e.executable !== false;
+    const destOk = destExists && (!expectedExec || destExecutable);
+
+    if (destOk) {
+      ok.push(e);
+      continue;
+    }
+
+    if (!destExists) missing.push(e);
+    else if (expectedExec && !destExecutable) notExecutable.push(e);
+
+    if (!heal) continue;
+
+    if (!existsSync(e.sourcePath)) {
+      sourceMissing.push(e);
+      failed.push({ entry: e, reason: `source missing at ${e.sourcePath}` });
+      continue;
+    }
+
+    try {
+      mkdirSync(dirname(e.destPath), { recursive: true });
+      copyFileSync(e.sourcePath, e.destPath);
+      if (expectedExec) chmodSync(e.destPath, 0o755);
+      healed.push(e);
+    } catch (err) {
+      failed.push({ entry: e, reason: err.message });
+    }
+  }
+
+  return { ok, missing, notExecutable, sourceMissing, healed, failed };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wipcomputer/wip-ldm-os",
-  "version": "0.4.82-alpha.1",
+  "version": "0.4.84",
   "type": "module",
   "description": "LDM OS: identity, memory, and sovereignty infrastructure for AI agents",
   "engines": {
@@ -18,9 +18,13 @@
   "scripts": {
     "build:bridge": "cd src/bridge && npm install && npx tsup core.ts mcp-server.ts cli.ts openclaw.ts --format esm --dts --clean --outDir ../../dist/bridge",
     "build": "npm run build:bridge",
-    "prepublishOnly": "npm run build:bridge",
+    "prepublishOnly": "npm run build:bridge && npm run validate:bin-manifest",
+    "validate:bin-manifest": "node scripts/validate-bin-manifest.mjs",
     "test:skill-frontmatter": "node scripts/test-skill-frontmatter.mjs",
     "test:installer-update-tracks": "node scripts/test-installer-update-tracks.mjs",
+    "test:ldm-install-bin-shim": "node scripts/test-ldm-install-preserves-foreign-bin.mjs",
+    "test:doctor-cron-target": "node scripts/test-doctor-cron-target.mjs",
+    "test:bin-manifest": "node scripts/test-bin-manifest.mjs",
     "fmt": "npx prettier --write 'src/**/*.{ts,mjs}' 'lib/**/*.mjs' 'bin/**/*.js'",
     "fmt:check": "npx prettier --check 'src/**/*.{ts,mjs}' 'lib/**/*.mjs' 'bin/**/*.js'"
   },
@@ -32,6 +36,35 @@
       "timeout": 15
     }
   },
+  "wipLdmOs": {
+    "binFiles": [
+      {
+        "name": "process-monitor.sh",
+        "source": "bin/process-monitor.sh",
+        "purpose": "kills zombie processes; cron every 3 min"
+      },
+      {
+        "name": "ldm-backup.sh",
+        "source": "scripts/ldm-backup.sh",
+        "purpose": "daily backup; LaunchAgent at 03:00"
+      },
+      {
+        "name": "ldm-restore.sh",
+        "source": "scripts/ldm-restore.sh",
+        "purpose": "restore from backup; operator-invoked"
+      },
+      {
+        "name": "ldm-summary.sh",
+        "source": "scripts/ldm-summary.sh",
+        "purpose": "generate session/daily summaries"
+      },
+      {
+        "name": "backfill-summaries.sh",
+        "source": "scripts/backfill-summaries.sh",
+        "purpose": "backfill summary cadences"
+      }
+    ]
+  },
   "files": [
     "src/",
     "lib/",