clankerbend 0.1.0

package/apps/vim-nav/src/vim-nav-app.js

@@ -0,0 +1,221 @@
+export const VIM_NAV_APP_ID = "onewill.vim-nav";
+
+export function createVimNavigatorApp(options = {}) {
+  return {
+    appId: VIM_NAV_APP_ID,
+    name: "Vim Navigator",
+    publicDir: options.publicDir,
+    contributes: {
+      panel: true,
+      annotations: true,
+      commands: true,
+      actions: true,
+      appState: true
+    },
+    permissions: {
+      transcriptRead: true,
+      transcriptAnnotate: true,
+      transcriptNavigate: true,
+      appServerRead: false,
+      appServerApprove: false,
+      appServerRollback: false
+    },
+    panel: {
+      title: "Vim Nav",
+      reloadPolicy: "preserve",
+      preferredWidth: 360
+    },
+
+    getManifest(context) {
+      return {
+        oneWhackVersion: context.protocolVersion,
+        appId: VIM_NAV_APP_ID,
+        name: "Vim Navigator",
+        entry: context.entry,
+        contributes: this.contributes,
+        permissions: this.permissions,
+        panel: this.panel
+      };
+    },
+
+    getState(context) {
+      const anchors = context.transcript.anchors || [];
+      return {
+        appId: VIM_NAV_APP_ID,
+        status: context.desktop.cdpStatus === "connected" ? "ready" : "degraded",
+        source: context.desktop.target?.type === "mock" ? "mock" : "dom",
+        connected: context.desktop.cdpStatus === "connected",
+        entries: anchors.slice(0, 300).map((anchor) => ({
+          entryId: entryId(anchor.anchorId),
+          appId: VIM_NAV_APP_ID,
+          anchorId: anchor.anchorId,
+          markerId: markerId(anchor.anchorId),
+          correlationId: anchor.appServer?.itemId || undefined,
+          title: `${anchorLabel(anchor)} ${anchor.inferredRole || anchor.kind}`,
+          summary: anchor.textPreview,
+          category: "navigation",
+          tone: anchor.anchorId === context.selection?.anchorId ? "accent" : anchor.visible ? "success" : "muted",
+          status: anchor.visible ? "visible" : "offscreen",
+          detail: {
+            order: anchor.order,
+            indexed: anchor.indexed !== false,
+            role: anchor.inferredRole || "unknown"
+          },
+          occurredAt: context.transcript.updatedAt
+        })),
+        annotations: anchors.slice(0, 300).map((anchor) => ({
+          appId: VIM_NAV_APP_ID,
+          anchorId: anchor.anchorId,
+          placement: "leading-rail",
+          priority: 50,
+          markers: [{
+            markerId: markerId(anchor.anchorId),
+            glyph: anchorLabel(anchor),
+            label: anchor.indexed === false ? "Transcript index pending" : `Jump to transcript item ${anchor.order}`,
+            tone: anchor.anchorId === context.selection?.anchorId ? "accent" : "muted",
+            shape: "circle",
+            entryId: entryId(anchor.anchorId),
+            action: {
+              type: "vim.jump",
+              payload: { anchorId: anchor.anchorId }
+            }
+          }]
+        })),
+        commands: [
+          command("vim.prev", "Previous transcript item", "vim.jumpRelative", "k", { delta: -1 }),
+          command("vim.next", "Next transcript item", "vim.jumpRelative", "j", { delta: 1 }),
+          command("vim.first", "First transcript item", "vim.jumpIndex", "gg", { index: 0 }),
+          command("vim.last", "Last transcript item", "vim.jumpIndex", "G", { index: -1 }),
+          command("vim.prevUser", "Previous user message", "vim.jumpRole", "{", { role: "user", direction: -1 }),
+          command("vim.nextUser", "Next user message", "vim.jumpRole", "}", { role: "user", direction: 1 }),
+          command("vim.latestAssistant", "Latest assistant message", "vim.latestRole", ":latest assistant", { role: "assistant" }),
+          command("vim.latestUser", "Latest user message", "vim.latestRole", ":latest user", { role: "user" }),
+          command("vim.search", "Search transcript text", "vim.search", "/term", { query: "" })
+        ],
+        updatedAt: context.state.generatedAt
+      };
+    },
+
+    async handleAction(action, context) {
+      if (action.type === "vim.jump") {
+        const anchorId = action.anchorId || action.payload?.anchorId;
+        return jump(action, context, anchorId);
+      }
+
+      if (action.type === "vim.jumpRelative") {
+        const current = context.selection?.anchorId ||
+          context.transcript.anchors.find((anchor) => anchor.visible)?.anchorId ||
+          context.transcript.anchors[0]?.anchorId;
+        const index = Math.max(0, context.anchorIndex(current));
+        const delta = Number(action.payload?.delta || 0);
+        const target = context.transcript.anchors[Math.max(0, Math.min(context.transcript.anchors.length - 1, index + delta))];
+        return jump(action, context, target?.anchorId);
+      }
+
+      if (action.type === "vim.jumpIndex") {
+        const rawIndex = Number(action.payload?.index || 0);
+        const index = rawIndex < 0 ? context.transcript.anchors.length - 1 : rawIndex;
+        return jump(action, context, context.transcript.anchors[index]?.anchorId);
+      }
+
+      if (action.type === "vim.jumpRole") {
+        const role = String(action.payload?.role || "");
+        const direction = Number(action.payload?.direction || 1) < 0 ? -1 : 1;
+        return jump(action, context, findRoleAnchor(context, role, direction)?.anchorId);
+      }
+
+      if (action.type === "vim.latestRole") {
+        const role = String(action.payload?.role || "");
+        return jump(action, context, latestRoleAnchor(context, role)?.anchorId);
+      }
+
+      if (action.type === "vim.search") {
+        const query = String(action.payload?.query || "").trim().toLowerCase();
+        const direction = Number(action.payload?.direction || 1) < 0 ? -1 : 1;
+        if (!query) throw context.httpError(400, "bad_request", "search query is required");
+        return jump(action, context, searchAnchor(context, query, direction)?.anchorId);
+      }
+
+      throw context.httpError(404, "not_found", `unknown action: ${action.type}`);
+    }
+  };
+}
+
+async function jump(action, context, anchorId) {
+  if (!context.anchorExists(anchorId)) throw context.httpError(404, "not_found", "anchor not found");
+  context.acceptSelection({
+    selectionId: `sel_${action.actionId}`,
+    source: "panel",
+    appId: VIM_NAV_APP_ID,
+    anchorId,
+    entryId: entryId(anchorId),
+    selectedAt: action.requestedAt || new Date().toISOString()
+  }, { broadcast: false });
+
+  const scroll = await context.scrollToAnchor(anchorId, action.payload || {});
+  if (!scroll?.ok) throw context.httpError(503, "adapter_unavailable", scroll?.error || "scroll failed");
+  await context.highlightAnchor(anchorId, { durationMs: action.payload?.durationMs || 1200 });
+  return applied(action, { anchorId });
+}
+
+function findRoleAnchor(context, role, direction) {
+  if (!isRole(role)) throw context.httpError(400, "bad_request", "role must be user, assistant, system, or tool");
+  const anchors = context.transcript.anchors || [];
+  const current = context.selection?.anchorId || anchors.find((anchor) => anchor.visible)?.anchorId || anchors[0]?.anchorId;
+  const start = Math.max(0, context.anchorIndex(current));
+  for (let index = start + direction; index >= 0 && index < anchors.length; index += direction) {
+    if (anchors[index].inferredRole === role) return anchors[index];
+  }
+  return null;
+}
+
+function latestRoleAnchor(context, role) {
+  if (!isRole(role)) throw context.httpError(400, "bad_request", "role must be user, assistant, system, or tool");
+  const anchors = context.transcript.anchors || [];
+  for (let index = anchors.length - 1; index >= 0; index -= 1) {
+    if (anchors[index].inferredRole === role) return anchors[index];
+  }
+  return null;
+}
+
+function searchAnchor(context, query, direction) {
+  const anchors = context.transcript.anchors || [];
+  const current = context.selection?.anchorId || anchors.find((anchor) => anchor.visible)?.anchorId || anchors[0]?.anchorId;
+  const start = Math.max(0, context.anchorIndex(current));
+  for (let offset = 1; offset <= anchors.length; offset += 1) {
+    const index = (start + direction * offset + anchors.length) % anchors.length;
+    if ((anchors[index].textPreview || "").toLowerCase().includes(query)) return anchors[index];
+  }
+  return null;
+}
+
+function anchorLabel(anchor) {
+  return anchor.indexed === false ? "?" : String(anchor.order).padStart(2, "0");
+}
+
+function isRole(role) {
+  return ["user", "assistant", "system", "tool"].includes(role);
+}
+
+function applied(action, data) {
+  return {
+    actionId: action.actionId,
+    appId: VIM_NAV_APP_ID,
+    ok: true,
+    status: "applied",
+    data,
+    completedAt: new Date().toISOString()
+  };
+}
+
+function command(commandId, label, type, shortcut, payload = {}) {
+  return { commandId, appId: VIM_NAV_APP_ID, label, type, shortcut, enabled: true, payload };
+}
+
+function entryId(anchorId) {
+  return `nav:${anchorId}`;
+}
+
+function markerId(anchorId) {
+  return `ruler:${anchorId}`;
+}

package/cli.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { launchOneWhackCodex } from "./server.mjs";
+
+const ROOT = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_JSON = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8"));
+
+try {
+  await main(process.argv.slice(2));
+} catch (err) {
+  console.error(err.message);
+  process.exit(1);
+}
+
+async function main(argv) {
+  const [command, ...args] = argv;
+
+  if (!command || command === "help" || command === "--help" || command === "-h") {
+    printHelp();
+    return;
+  }
+
+  if (command === "version" || command === "--version" || command === "-v") {
+    console.log(PACKAGE_JSON.version);
+    return;
+  }
+
+  if (command === "codex") {
+    const options = parseCodexArgs(args);
+    await launchOneWhackCodex(options);
+    return;
+  }
+
+  console.error(`Unknown command: ${command}`);
+  printHelp();
+  process.exit(1);
+}
+
+function parseCodexArgs(args) {
+  const options = {
+    mock: false
+  };
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--mock") {
+      options.mock = true;
+    } else if (arg === "--state-dir") {
+      options.stateDir = requiredArg(args[++index], "--state-dir value");
+    } else if (arg === "--help" || arg === "-h") {
+      printCodexHelp();
+      process.exit(0);
+    } else {
+      throw new Error(`unknown codex option: ${arg}`);
+    }
+  }
+  return options;
+}
+
+function printHelp() {
+  console.log(`OneWhack
+
+Usage:
+  clankerbend codex [--mock] [--state-dir path]
+  clankerbend help
+  clankerbend --version
+
+Environment:
+  ONEWILL_ONEWHACK_STATE_DIR       Override OneWhack runtime state directory.
+  ONEWILL_ONEWHACK_TOKEN           Use a specific bearer token for host endpoints.
+  ONEWILL_ONEWHACK_DISABLE_AUTH=1  Disable bearer auth for local development only.
+`);
+}
+
+function printCodexHelp() {
+  console.log(`OneWhack Codex launcher
+
+Usage:
+  clankerbend codex [--mock] [--state-dir path]
+
+Options:
+  --mock            Start against a mock transcript instead of Codex Desktop.
+  --state-dir path  Override OneWhack runtime state directory.
+`);
+}
+
+function requiredArg(value, label) {
+  if (!value) throw new Error(`${label} is required`);
+  return value;
+}

package/docs/app-lifecycle.md

@@ -0,0 +1,63 @@
+# OneWhack App Lifecycle
+
+OneWhack separates app installation from profile activation.
+
+## Install
+
+Installing records a manifest in the runtime registry. The public `onewhack`
+CLI intentionally does not expose app-management commands; app installation is
+a product configuration concern for the running OneWhack experience.
+
+The registry stores app id, version, manifest path, distribution metadata,
+bundle kind, source path, and install time. The current host loads bundled
+manifests and additional manifest paths from this registry; copying directories
+or tarballs into a managed app store is reserved for installer tooling. The
+runtime root defaults to:
+
+- macOS: `~/Library/Application Support/OneWill/OneWhack`
+- Linux: `~/.local/state/onewill/onewhack`
+
+Set `ONEWILL_ONEWHACK_STATE_DIR` to override the root location.
+
+`distribution.integrity` is required. Local development installs can use
+`integrity: "dev-local"`. Downloaded packages should be installed with a real
+`--integrity sha256-...` value supplied by the package index.
+
+## Enable And Disable
+
+Profiles decide which installed apps are active.
+
+Enablement is profile-scoped. A host can launch with the default profile or a
+custom user profile while using the same app registry. The default registry
+config path is `registry.json` under the runtime state directory, and launchers
+may override it with `ONEWILL_ONEWHACK_REGISTRY_CONFIG`.
+
+## Start
+
+At startup the launcher builds a profile from app manifests. The host loads app
+factories, validates capabilities, injects configured renderer bridges, and
+serves each panel under:
+
+```text
+/apps/:appId/
+```
+
+Apps receive only their declared context. For example, an app with
+`transcriptRead: false` sees an empty transcript state.
+
+## Update
+
+Manifest `distribution.update` is metadata for update tools. An updater should
+revalidate a replacement manifest and update the installed app record while
+preserving profile enablement.
+
+A future updater can replace the app bundle, validate the new manifest, compare
+`oneWhackVersion`, and update the registry atomically.
+
+## Remove
+
+Removing an app deletes it from the installed app registry and disables it from
+all profiles.
+
+Remove does not delete arbitrary files from disk unless a future package manager
+owns those files and the manifest lifecycle explicitly allows that behavior.

package/docs/app-manifest.md

@@ -0,0 +1,130 @@
+# OneWhack App Manifest
+
+OneWhack apps are installed and launched from a `onewhack.manifest.json` file.
+The manifest is the stable contract between the app bundle and the host. The
+host loads local manifests through this schema. The schema also reserves npm
+packages, tarballs, and binary-style bundles for installer tooling.
+
+## Required Fields
+
+```json
+{
+  "oneWhackVersion": "0.1",
+  "appId": "onewill.example.app",
+  "version": "0.1.0",
+  "name": "Example App",
+  "description": "Short human-readable description.",
+  "distribution": {
+    "kind": "local",
+    "source": ".",
+    "integrity": "dev-local",
+    "update": {
+      "channel": "local"
+    }
+  },
+  "entrypoint": {
+    "kind": "module",
+    "module": "./src/example-app.js",
+    "factory": "createExampleApp",
+    "publicDir": "./public"
+  },
+  "platform": {
+    "os": ["darwin", "linux", "win32"],
+    "arch": ["any"]
+  },
+  "capabilities": {
+    "panel": true,
+    "annotations": true,
+    "commands": true,
+    "actions": true,
+    "appState": true,
+    "selectionActions": false,
+    "overlays": false,
+    "composerContext": false,
+    "composerDraft": false,
+    "rendererBridge": false
+  },
+  "permissions": {
+    "transcriptRead": true,
+    "transcriptAnnotate": true,
+    "transcriptNavigate": true,
+    "overlayWrite": false,
+    "composerWrite": false,
+    "appServerRead": false,
+    "appServerApprove": false,
+    "appServerRollback": false
+  }
+}
+```
+
+## Distribution Kinds
+
+- `local`: a manifest on disk, usually during development.
+- `npm`: reserved for a package that contains a manifest and app entrypoint.
+- `tarball`: reserved for a downloaded archive verified by `integrity`.
+- `binary`: reserved for a package that runs an external app process and
+  registers through host lifecycle hooks.
+
+Every app package must declare the same capabilities and permissions regardless
+of distribution shape.
+
+The current host accepts manifest paths. Future installers may accept an app
+directory containing `onewhack.manifest.json`, a `.tgz`/`.tar.gz` bundle, or an
+`npm:<package>` spec. Packaged sources should be verified with an external
+`sha256-...` integrity value before extraction. The manifest still carries
+`distribution.integrity` so registries and update tools can reason about the
+package they installed.
+
+## Entrypoints
+
+`module` entrypoints run in the host process and export the configured factory.
+The factory receives `{ manifest, publicDir }` and returns an app object with
+`getState` and optional `handleAction`.
+
+`binary` entrypoints are for apps that run out of process. They must declare a
+command and lifecycle hooks. The current host can register a binary app and show
+its panel/static state, but it does not yet supervise a long-running binary
+process.
+
+`static` entrypoints are reserved for panel-only apps that render from public
+host state and do not provide host-side action handlers.
+
+## Renderer Bridge
+
+Most apps should not declare a renderer bridge. Apps should prefer host
+capabilities such as transcript navigation, text ranges, overlays, and composer
+drafts. The Navigate profile uses a host-owned Codex Desktop renderer bridge so
+public apps can stay focused on app state and actions.
+
+Adapter packages that intentionally provide host-level renderer behavior may
+declare a bridge:
+
+```json
+{
+  "rendererBridge": {
+    "script": "./adapter/renderer-bridge.js",
+    "primary": true,
+    "provides": [
+      "transcriptSnapshot",
+      "transcriptOrder",
+      "transcriptNavigation",
+      "transcriptHighlight"
+    ],
+    "methods": {
+      "openPanel": "openPanel",
+      "scroll": "scrollToAnchor",
+      "highlight": "highlightAnchor"
+    }
+  }
+}
+```
+
+Only one bridge normally provides transcript snapshot/order/navigation for a
+profile. Other apps can still contribute annotations and panels without owning
+the transcript bridge.
+
+## Validation
+
+Hosts should reject unknown capabilities and permissions so future protocol
+growth is explicit: bump the protocol version or add a new host capability
+before apps depend on new behavior.

package/docs/author-guide.md

@@ -0,0 +1,126 @@
+# OneWhack App Author Guide
+
+The public reference apps are `apps/vim-nav` and `apps/sticky-notes`. VimNav
+demonstrates transcript navigation and annotations. Sticky Notes demonstrates
+text-range selection, host-rendered overlays, composer context, and draft
+insertion using only documented host APIs.
+
+## App Shape
+
+A module app exports a factory:
+
+```js
+export function createExampleApp(options = {}) {
+  return {
+    appId: "onewill.example.app",
+    name: "Example App",
+    publicDir: options.publicDir,
+    contributes: {
+      panel: true,
+      annotations: true,
+      actions: true,
+      appState: true,
+      selectionActions: false,
+      overlays: false,
+      composerContext: false,
+      composerDraft: false
+    },
+    permissions: {
+      transcriptRead: true,
+      transcriptAnnotate: true,
+      transcriptNavigate: true,
+      overlayWrite: false,
+      composerWrite: false,
+      appServerRead: false
+    },
+    getState(context) {
+      return {
+        appId: this.appId,
+        status: "ready",
+        source: "dom",
+        connected: context.desktop.cdpStatus === "connected",
+        entries: [],
+        annotations: [],
+        updatedAt: context.state.generatedAt
+      };
+    },
+    async handleAction(action, context) {
+      return {
+        actionId: action.actionId,
+        appId: this.appId,
+        ok: true,
+        status: "applied",
+        completedAt: new Date().toISOString()
+      };
+    }
+  };
+}
+```
+
+The host wraps app state and actions in OneWhack HTTP envelopes. The app should
+throw `context.httpError(...)` for expected validation failures.
+
+## Transcript Annotations
+
+Apps return annotation requests from `getState`. The host and renderer bridge
+own final placement, sorting, and collision avoidance:
+
+```js
+{
+  appId: "onewill.example.app",
+  anchorId: anchor.anchorId,
+  placement: "leading-rail",
+  priority: 80,
+  markers: [{
+    markerId: `example:${anchor.anchorId}`,
+    glyph: "E",
+    label: "Example marker",
+    tone: "muted",
+    shape: "circle",
+    entryId: `example:${anchor.anchorId}`,
+    action: {
+      type: "example.select",
+      payload: { anchorId: anchor.anchorId }
+    }
+  }]
+}
+```
+
+Apps should not mutate Codex Desktop DOM directly for placement. Renderer
+bridges register through `window.__oneWhackRuntime` and call host-owned
+annotation APIs.
+
+## Text Ranges And Composer Context
+
+Apps that work with selected text should consume `context.selection.range` and
+contribute `selectionActions` from app state. Apps request overlays through
+`context.openOverlay(...)`, queue composer context through
+`context.addComposerContext(...)`, and insert follow-up drafts through
+`context.setComposerDraft(...)`.
+
+Apps should not query Codex Desktop DOM, position floating menus, render
+composer chips, or write into the composer directly. Those details belong in
+the OneWhack host adapter and renderer runtime.
+
+## Actions
+
+Actions are routed through:
+
+```text
+POST /onewhack/apps/:appId/actions
+```
+
+An action must include non-empty `appId`, `actionId`, and `type`. Action IDs are
+idempotency keys; repeated requests return the original result.
+
+## E2E
+
+Reference apps should run:
+
+```sh
+npm test
+npm run test:desktop-real:integration
+```
+
+Desktop tests are explicit because they launch Codex Desktop with a disposable
+profile and CDP port.

package/docs/launcher-profiles.md

@@ -0,0 +1,50 @@
+# OneWhack Launcher Profiles
+
+A launcher profile is the host configuration for one Codex Desktop session. It
+selects app manifests, chooses the default side-panel app, and decides which
+renderer bridge provides transcript primitives.
+
+## Commands
+
+```sh
+npx clankerbend codex
+npx clankerbend codex --mock
+```
+
+In this repository, `npm start` runs `clankerbend codex` through the local package.
+`npm run start:mock` runs the same profile without Codex Desktop.
+
+## Profile Construction
+
+Profiles are built from manifests with `loadProfileFromManifests`. Each loaded
+app contributes:
+
+- an app object for host state/actions
+- an optional renderer bridge
+- panel metadata
+- capabilities and permissions
+
+Provider selection comes from renderer bridge metadata. The first primary bridge
+normally provides transcript snapshot, order, navigation, and highlight.
+
+The built-in Navigate profile always includes VimNav and Sticky Notes.
+Additional apps are product configuration owned by the running OneWhack
+experience and stored in the runtime registry.
+
+The launcher also reads `ONEWILL_ONEWHACK_REGISTRY_CONFIG`, defaulting to
+`registry.json` under the runtime state directory, and merges enabled app
+manifests from the selected registry profile. Set `ONEWILL_ONEWHACK_PROFILE` to
+override the selected registry profile when building a custom launcher.
+
+Runtime state defaults to:
+
+- macOS: `~/Library/Application Support/OneWill/OneWhack`
+- Linux: `~/.local/state/onewill/onewhack`
+
+Set `ONEWILL_ONEWHACK_STATE_DIR` to override the root state directory.
+
+## Ports And Cleanup
+
+The host and CDP adapter bind to `127.0.0.1` and use ephemeral ports. Launchers
+must stop the host, CDP adapter, and launched Codex Desktop child process on
+`SIGINT` or `SIGTERM`.