clankerbend 0.1.0

package/DEVELOPERS.md

@@ -0,0 +1,63 @@
+# OneWhack Developers
+
+## Local Commands
+
+For protocol-only local testing without Codex Desktop:
+
+```sh
+npx clankerbend codex --mock
+```
+
+For local development:
+
+```sh
+npm start
+npm run start:mock
+npm test
+```
+
+`npm test` runs the fast behavior e2e suite through the host and app APIs. To
+exercise the real Codex Desktop surface:
+
+```sh
+npm run test:desktop-real:integration
+```
+
+The real desktop tests create fresh chats, seed deterministic content, verify
+VimNav against the real transcript DOM, and verify Sticky Notes through native
+toolbar injection, pinned overlay save, runtime file attachment, and prompt
+context visibility.
+
+## Useful Docs
+
+- `docs/protocol.md`: OneWhack protocol
+- `docs/app-manifest.md`: app manifest format
+- `docs/author-guide.md`: writing OneWhack apps
+- `docs/launcher-profiles.md`: launcher profiles
+- `docs/app-lifecycle.md`: app installation and lifecycle model
+
+## Release
+
+OneWhack publishes the same package payload under two npm names:
+
+- `@onewillai/clankerbend`: scoped canonical package
+- `clankerbend`: short launcher name for `npx clankerbend codex`
+
+```sh
+npm test
+npm run test:desktop-real:integration
+npm run release:pack
+npm run release:publish -- --yes
+```
+
+`release:pack` creates:
+
+- `dist/npm/clankerbend-<version>.tgz`
+- `dist/npm/onewillai-clankerbend-<version>.tgz`
+
+`release:publish` is guarded by `--yes`. It publishes the scoped package first
+with `--access public`, then publishes the unscoped package. The publish steps
+run interactively so npm can prompt for the configured 2FA method. Pass
+`--otp=<code>` only for accounts that use authenticator-app TOTP codes.
+Provenance is enabled automatically in supported CI providers, or explicitly
+with `--provenance`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OneWill.ai
+
+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.

package/README.md

@@ -0,0 +1,49 @@
+# OneWhack
+
+<p align="center">
+  <img src="./assets/onewhack.jpg" alt="OneWhack: mod your clanker with OneWill.ai" width="720">
+</p>
+
+OneWhack lets you build Codex Desktop plugins without rebuilding or re-signing
+Codex Desktop itself. It uses [CDP](https://x.com/OpenAIDevs/status/2065226355495895521)
+to provide a more stable API for tasks such as transcript navigation, chat annotation,
+attaching a file to the prompt window, opening the side panel, and so on.
+
+DEMO VIDEO TODO
+
+OneWhack is an independent [OneWill](https://onewill.ai) project compatible
+with OpenAI Codex Desktop on macOS. It is not affiliated with or endorsed by
+OpenAI (unless... 🥺).
+
+## Quickstart
+
+You'll need macOS with [Codex Desktop](https://chatgpt.com/codex/)
+and [nodejs](https://nodejs.org/en/download). Then just:
+
+```sh
+npx clankerbend codex
+```
+
+That starts Codex Desktop with the default OneWhack profile and bundled apps:
+
+- **VimNav**: Vim-style transcript navigation, number rails, role jumps, search,
+  and a side panel.
+- **Sticky Notes**: select transcript text, click **Add note**, and the
+  generated note will (1) create a markdown file and (2) attach itself to the
+  current Codex prompt. Inspired by
+  [@zats](https://x.com/zats/status/2070492220084326907).
+
+## Runtime State
+
+OneWhack writes runtime state outside the package:
+
+- macOS: `~/Library/Application Support/OneWill/OneWhack`
+
+Override with `ONEWILL_ONEWHACK_STATE_DIR`.
+
+## Security
+
+OneWhack binds to `127.0.0.1` on an OS-assigned ephemeral port. The launcher
+prints the exact host URL, for example `Host: http://127.0.0.1:49152`.
+`/onewhack/*` endpoints require a bearer token by default. For local protocol
+debugging, you can set `ONEWILL_ONEWHACK_DISABLE_AUTH=1`.

package/apps/README.md

@@ -0,0 +1,11 @@
+# OneWhack Apps
+
+This directory contains public OneWhack reference apps.
+
+- `vim-nav/`: Vim-like transcript navigation for Codex Desktop transcript
+  anchors.
+- `sticky-notes/`: selected transcript notes and composer context chips through
+  the shared OneWhack host API.
+
+The public `apps/` tree should contain standalone, auditable apps without
+project-specific state or action vocabulary.

package/apps/sticky-notes/README.md

@@ -0,0 +1,11 @@
+# Sticky Notes
+
+Sticky Notes is a public OneWhack reference app for selected transcript text,
+anchored note overlays, composer context chips, and follow-up draft insertion.
+
+The app does not inspect or mutate Codex Desktop DOM. It contributes selection
+actions and handles note business logic through the OneWhack host API.
+
+```sh
+npm --prefix apps/sticky-notes test
+```

package/apps/sticky-notes/onewhack.manifest.json

@@ -0,0 +1,74 @@
+{
+  "oneWhackVersion": "0.1",
+  "appId": "onewill.sticky-notes",
+  "version": "0.1.0",
+  "name": "OneWill Sticky Notes",
+  "description": "Public reference app for selected transcript notes and composer context chips.",
+  "distribution": {
+    "kind": "local",
+    "source": ".",
+    "integrity": "dev-local",
+    "update": {
+      "channel": "local"
+    }
+  },
+  "entrypoint": {
+    "kind": "module",
+    "module": "./src/sticky-notes-app.js",
+    "factory": "createStickyNotesApp",
+    "publicDir": "./public"
+  },
+  "platform": {
+    "os": [
+      "darwin",
+      "linux",
+      "win32"
+    ],
+    "arch": [
+      "any"
+    ]
+  },
+  "capabilities": {
+    "panel": true,
+    "annotations": true,
+    "actions": true,
+    "appState": true,
+    "selectionActions": true,
+    "overlays": true,
+    "composerContext": true,
+    "composerDraft": true,
+    "rendererBridge": false
+  },
+  "permissions": {
+    "transcriptRead": true,
+    "transcriptAnnotate": true,
+    "transcriptNavigate": true,
+    "overlayWrite": true,
+    "composerWrite": true,
+    "appServerRead": false,
+    "appServerApprove": false,
+    "appServerRollback": false
+  },
+  "panel": {
+    "title": "Sticky Notes",
+    "reloadPolicy": "preserve",
+    "preferredWidth": 380
+  },
+  "lifecycle": {
+    "install": {
+      "kind": "noop"
+    },
+    "start": {
+      "kind": "in-process"
+    },
+    "stop": {
+      "kind": "in-process"
+    },
+    "update": {
+      "kind": "replace-manifest"
+    },
+    "remove": {
+      "kind": "forget"
+    }
+  }
+}

package/apps/sticky-notes/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "onewhack-sticky-notes",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "OneWhack public reference app for transcript range notes and composer context.",
+  "license": "MIT",
+  "scripts": {
+    "test": "node test-onewhack.mjs",
+    "test:desktop-real": "node test-desktop-real.mjs"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/apps/sticky-notes/public/app.js

@@ -0,0 +1,117 @@
+const APP_ID = "onewill.sticky-notes";
+
+const els = {
+  subtitle: document.getElementById("subtitle"),
+  notes: document.getElementById("notes"),
+  userText: document.getElementById("user-text"),
+  insertContext: document.getElementById("insert-context")
+};
+
+const token = readToken();
+let currentState = null;
+
+els.insertContext.addEventListener("click", () => runAction("sticky.compose.insertContext", {
+  userText: els.userText.value,
+  mode: "replace"
+}));
+
+bootstrap();
+
+async function bootstrap() {
+  const state = await getJson("/onewhack/state");
+  render(state);
+  connectEvents();
+}
+
+function render(state) {
+  currentState = state;
+  const app = (state.apps || []).find((candidate) => candidate.appId === APP_ID);
+  const entries = app?.entries || [];
+  els.subtitle.textContent = `${entries.length} note${entries.length === 1 ? "" : "s"} queued`;
+  els.notes.replaceChildren(...entries.map((entry) => {
+    const li = document.createElement("li");
+    const title = document.createElement("strong");
+    title.textContent = entry.title;
+    const summary = document.createElement("div");
+    summary.textContent = entry.summary;
+    const meta = document.createElement("small");
+    meta.textContent = entry.status;
+    li.append(title, summary, meta);
+    return li;
+  }));
+}
+
+async function runAction(type, payload = {}) {
+  const action = {
+    actionId: `${type}:${Date.now()}:${Math.random().toString(36).slice(2)}`,
+    appId: APP_ID,
+    type,
+    payload,
+    requestedAt: new Date().toISOString()
+  };
+  const result = await postJson(`/onewhack/apps/${encodeURIComponent(APP_ID)}/actions`, { action });
+  const state = await getJson("/onewhack/state");
+  render(state);
+  return result;
+}
+
+function readToken() {
+  const params = new URLSearchParams(location.hash.startsWith("#") ? location.hash.slice(1) : location.hash);
+  const value = params.get("onewhack_token") || "";
+  if (value) history.replaceState(null, "", location.pathname + location.search);
+  return value;
+}
+
+function headers(extra = {}) {
+  return {
+    ...extra,
+    ...(token ? { authorization: `Bearer ${token}` } : {})
+  };
+}
+
+function connectEvents() {
+  if (!token) {
+    const events = new EventSource("/onewhack/events");
+    events.addEventListener("state", (event) => render(JSON.parse(event.data)));
+    events.addEventListener("action", () => getJson("/onewhack/state").then(render));
+    return;
+  }
+  fetch("/onewhack/events", { headers: headers() }).then(async (res) => {
+    const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();
+    let buffer = "";
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      buffer += value;
+      let boundary;
+      while ((boundary = buffer.indexOf("\n\n")) >= 0) {
+        const chunk = buffer.slice(0, boundary);
+        buffer = buffer.slice(boundary + 2);
+        const event = chunk.split(/\n/).find((line) => line.startsWith("event: "))?.slice(7);
+        const data = chunk.split(/\n/).filter((line) => line.startsWith("data: ")).map((line) => line.slice(6)).join("\n");
+        if (event === "state" && data) render(JSON.parse(data));
+        if (event === "action") getJson("/onewhack/state").then(render);
+      }
+    }
+  });
+}
+
+async function getJson(url) {
+  const res = await fetch(url, { headers: headers() });
+  return unwrap(res);
+}
+
+async function postJson(url, body) {
+  const res = await fetch(url, {
+    method: "POST",
+    headers: headers({ "content-type": "application/json" }),
+    body: JSON.stringify(body)
+  });
+  return unwrap(res);
+}
+
+async function unwrap(res) {
+  const json = await res.json();
+  if (!json.ok) throw new Error(json.error?.message || `request failed: ${res.status}`);
+  return json.data;
+}

package/apps/sticky-notes/public/index.html

@@ -0,0 +1,23 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>Sticky Notes</title>
+    <link rel="stylesheet" href="./styles.css">
+  </head>
+  <body>
+    <main>
+      <header>
+        <h1>Sticky Notes</h1>
+        <p id="subtitle">Transcript notes</p>
+      </header>
+      <section class="composer">
+        <textarea id="user-text" placeholder="Follow-up request"></textarea>
+        <button id="insert-context" type="button">Insert context</button>
+      </section>
+      <ul id="notes"></ul>
+    </main>
+    <script type="module" src="./app.js"></script>
+  </body>
+</html>

package/apps/sticky-notes/public/styles.css

@@ -0,0 +1,84 @@
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  background: #fbfaf7;
+  color: #24221d;
+  font: 14px/1.45 system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+}
+
+main {
+  display: grid;
+  gap: 14px;
+  padding: 16px;
+}
+
+header {
+  border-bottom: 1px solid #e7dfc4;
+  padding-bottom: 10px;
+}
+
+h1 {
+  margin: 0;
+  font-size: 18px;
+  line-height: 1.2;
+}
+
+p {
+  margin: 4px 0 0;
+  color: #6c6658;
+}
+
+.composer {
+  display: grid;
+  gap: 8px;
+}
+
+textarea {
+  width: 100%;
+  min-height: 86px;
+  resize: vertical;
+  border: 1px solid #d9cfaa;
+  border-radius: 8px;
+  padding: 10px;
+  background: #fff8d8;
+  color: #24221d;
+  font: inherit;
+}
+
+button {
+  justify-self: start;
+  border: 1px solid #bfa643;
+  border-radius: 7px;
+  background: #f5d75d;
+  color: #2c2612;
+  padding: 7px 10px;
+  font: 650 13px/1 system-ui, sans-serif;
+  cursor: pointer;
+}
+
+ul {
+  display: grid;
+  gap: 8px;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+li {
+  border: 1px solid #ead87c;
+  border-radius: 8px;
+  background: #fff0a8;
+  padding: 10px;
+}
+
+strong {
+  display: block;
+  margin-bottom: 4px;
+}
+
+small {
+  color: #766b45;
+}