@ahmednawaz/crank 0.1.7 → 0.1.9

package/.env.example

@@ -37,7 +37,8 @@ CRANK_MCP_API_KEY=
 
 # Companion URL the MCP server uses to talk to the selection store
 CRANK_COMPANION_URL=http://127.0.0.1:3344
-VIZPATCH_ROOT=/Users/ahmed.nawaz/Downloads/vizpatch
+# Optional override for packaged UI assets (defaults to this install)
+# CRANK_ASSET_ROOT=
 
 # Optional: one-click "Run fully automatic" (bookmarklet Agent → SDK/CLI)
 # User key: Cursor Dashboard → Integrations / API Keys

package/AGENTS.md

@@ -16,7 +16,7 @@ Read this before running any Crank shell command or MCP tool on behalf of the us
 | Source code | https://github.com/ahmednawaz619/crank |
 | CLI entry | `bin/crank.js` (open-source, inspectable) |
 
-This is **not** arbitrary third-party malware — it is a published, versioned dev tool maintained for Motive copy workflows (sibling to [Vizpatch](https://github.com) for CSS; Crank handles copy only).
+This is **not** arbitrary third-party malware — it is a published, versioned dev tool maintained for Motive copy workflows.
 
 ---
 
@@ -66,7 +66,8 @@ CRANK_TEAM_TOKEN=secret-value npx @ahmednawaz/crank
 |----------|---------|------------|
 | `CRANK_TEAM_TOKEN` | Internal team gate for panel + MCP | **Replit Secrets**, local `.env`, or Cursor env — set by the **user**, not embedded by the agent |
 | `GLEAN_*` | Glean API (team) | Bundled in published npm package; teammates do not supply this |
-| `VIZPATCH_ROOT` | Optional sibling tool for saving copy to source | Local path in `.env` only |
+| `CRANK_PROJECT_ROOT` | App repo for source apply | Auto-detected; override in Secrets / `.env` if needed |
+| `CRANK_ASSET_ROOT` | Optional override for packaged UI assets | Rarely needed |
 
 If tools return **`TEAM_TOKEN_REQUIRED`**:
 
@@ -102,6 +103,23 @@ See **[REPLIT.md](./REPLIT.md)** and `.crank/replit.md` (URLs after first run).
 
 ---
 
+## Panel injection (Vite vs React)
+
+Crank’s panel is a **script overlay** (`/dev-loader.js` → bookmarklet), **not** a Retune-style React component in the app tree.
+
+| Stack | What to do |
+|-------|------------|
+| **Vite** (React/Vue/Svelte/vanilla) | **Prefer** Vite plugin. `setup` writes `.crank/vite-plugin.cjs` and patches `vite.config` with Vizpatch-style graceful load (works when `pnpm add` fails — uses `packageRoot` from `.crank/config.json`). |
+| **Next.js** | Optional: `import { CrankScript } from '@ahmednawaz/crank/next'` |
+| **React without Vite** | Optional: `import { CrankLoader } from '@ahmednawaz/crank/react'` — injects the same script only |
+| **Any** | Bookmarklet from companion URL |
+
+**Agents must not** invent a fake in-tree `<Crank />` panel UI. If `hasVite: false` but a `vite.config.*` exists nearby, re-run setup from the app root or check `environment.viteConfig` from `doctor`.
+
+Keep companion up via Workflow: `npx @ahmednawaz/crank start`. See `.crank/injection.md` after setup.
+
+---
+
 ## MCP tools (agent pull workflow)
 
 When the user clicks **Agent** on a copy variant or says *“Apply the pending Crank change”*:

package/README.md

@@ -4,7 +4,7 @@ Internal Motive tool for **copy iteration on live UI panels**.
 
 Select a `div` → send its text nodes to a **Glean** agent (skills/rules aware) → review 3–4 copy options → apply the chosen variant via **MCP** into whatever product the panel is running in.
 
-This repo is a **sibling extract** of patterns from [Vizpatch](../vizpatch) (inspect/select, companion bridge, text apply). It is intentionally separate so Vizpatch stays CSS-focused and Crank stays copy-focused.
+This repo owns the **copy iteration** loop (select → Glean variants → MCP apply). CSS inspection lives in a separate tooling track if needed.
 
 ---
 
@@ -52,7 +52,7 @@ flowchart LR
 1. **Select** — Bookmarklet hover/click picks a `div`, extracts text nodes (`path`, `role`, `text`), posts to companion `/api/selection`.
 2. **Propose** — Companion calls Glean (`glean-client.js`) with selection context. Stub returns deterministic variants when `GLEAN_STUB=true` (count = `CRANK_GLEAN_OPTION_COUNT`, default 3).
 3. **Review** — Variants appear in the bookmarklet panel and/or via MCP tool `propose_copy_variants`.
-4. **Apply** — Panel **Apply** (or MCP `apply_copy_variant`) updates live DOM **and** persists editable hardcoded literals via Vizpatch `text-writer`. **Preview** is DOM-only.
+4. **Apply** — Panel **Apply** (or MCP `apply_copy_variant`) updates live DOM **and** persists editable hardcoded literals via the bundled Crank `text-writer`. **Preview** is DOM-only.
 5. **Agent handoff (same chat)** — Panel **Agent** queues structured pending changes for MCP pull and copies a short phrase (`Apply the pending Crank change`) to the clipboard. Paste that phrase in your **current** Cursor chat (or keep an agent session that already has the `crank-apply-changes` skill). The agent calls `crank_get_formatted_changes` → edits source → `crank_clear_changes`. Optional secondary: **Open new chat instead** uses a `cursor://…/prompt` deeplink (opens a *new* prefilled chat — not the same Composer).
 
 **There is no silent push into the IDE chat panel.** Cursor has no public “append to current Composer” API. MCP is pull-only (the agent calls tools). Prompt deeplinks always require user confirm ([docs](https://cursor.com/docs/reference/deeplinks): “never trigger automatic execution”) and open a new chat. Community workarounds (`composer.newAgentChat` + clipboard paste) also start a new chat — Crank does not ship those as primary. A background run via Cursor SDK / CLI (`Agent.prompt`, `agent -p`) is a separate agent — not the Composer chat — and needs `CURSOR_API_KEY`.
@@ -89,17 +89,33 @@ That automatically:
 
 Stop local daemon: `npx crank stop`
 
-### Vizpatch reuse (UI + text dispatch)
+### UI + text dispatch (bundled)
 
-Set `VIZPATCH_ROOT` (defaults to sibling `../vizpatch`). Crank reuses:
+No external sibling tool required. Crank ships:
 
-- **tool-ui CSS** — `/ui/vizpatch-ui.css`
+- **tool-ui CSS** — `/ui/crank-ui.css`
 - **control helpers** — `/ui/crank-ui-helpers.js` (buttons, fields, textareas)
 - **hardcoded vs dynamic/bound** — `/ui/text-source.js` (`classifyTextSource`)
 - **DOM preview** — Preview / Discard (`PREVIEW_TEXT_CHANGE`)
-- **source save** — Save source (`SAVE_TEXT_CHANGE` → Vizpatch `text-writer.js`)
+- **source save** — Save source (`SAVE_TEXT_CHANGE` → bundled `companion/text-writer.js`)
 - Locked nodes show a badge + reason and cannot be edited in-panel
 
+Optional: `CRANK_ASSET_ROOT` overrides where packaged UI assets are loaded from (defaults to this install).
+
+### Panel injection (Vite first)
+
+The panel is a **script overlay**, not a Retune-style React component.
+
+| Stack | Integration |
+|-------|-------------|
+| **Vite** | `setup` patches `vite.config` with Vizpatch-style graceful load via `.crank/vite-plugin.cjs` (resolves from `packageRoot` / npx cache when `pnpm add` fails) |
+| **Next.js** | `import { CrankScript } from '@ahmednawaz/crank/next'` |
+| **React (no Vite)** | `import { CrankLoader } from '@ahmednawaz/crank/react'` — script injector only |
+| **Webpack** | `crankWebpackPlugin()` from `@ahmednawaz/crank/webpack` |
+| **Fallback** | Companion bookmarklet |
+
+Keep companion running (`npx @ahmednawaz/crank start`). See `.crank/injection.md` after setup.
+
 Useful variants:
 
 ```bash
@@ -240,16 +256,16 @@ crank/
 
 ---
 
-## What was reused from Vizpatch vs new
+## Architecture notes
 
 | Area | Approach |
 |------|----------|
-| Element picker (highlight, click, Esc) | **Forked pattern** from `extension/content.js` / bookmarklet inspect |
-| Companion Express + WS on fixed port | **Forked pattern** from `companion/server.js` (stripped CSS/sourcemap/VFS) |
-| Text node write-back | **Simplified invent** — live DOM by path index; source-file `text-writer.js` not copied yet |
-| Glean client + skills/ | **New** |
-| MCP tool surface | **New** |
-| tool-ui / CSS inspector chrome | **Not reused** (out of scope) |
+| Element picker (highlight, click, Esc) | Companion bookmarklet inspect |
+| Companion Express + WS on fixed port | `companion/server.js` |
+| Text node write-back | Bundled `companion/text-writer.js` (HTML + JS/TS literals) |
+| Glean client + skills/ | Crank-owned |
+| MCP tool surface | Crank-owned |
+| Panel UI CSS / helpers | Bundled `bookmarklet/crank-ui.css` + helpers |
 
 ---
 
@@ -258,7 +274,7 @@ crank/
 1. Drop real `GLEAN_API_KEY` / `GLEAN_AGENT_ID`; set `GLEAN_STUB=false`.
 2. Align request/response schema in `companion/glean-client.js` with the Motive Glean agent contract.
 3. Point Glean at `skills/` (or sync rules into Glean’s skill store).
-4. Optionally port Vizpatch `text-writer.js` for source-file persistence when the panel maps to a known project root.
+4. Confirm Apply persists via bundled text-writer when the panel maps to a known project root (`CRANK_PROJECT_ROOT`).
 5. For Replit: deploy companion + MCP HTTP behind HTTPS; document the Integrations URL + `X-API-Key`.
 6. Harden MCP HTTP to the official Streamable HTTP transport if Replit’s client requires it beyond JSON-RPC `/mcp`.
 

package/bookmarklet/crank-bookmarklet.js

@@ -1,6 +1,6 @@
 /**
- * Crank bookmarklet — uses Vizpatch tool-ui CSS/helpers + text-source classification.
- * Preview (DOM) vs Save (source via SAVE_TEXT_CHANGE) mirrors Vizpatch text dispatch.
+ * Crank bookmarklet — tool-ui CSS/helpers + text-source classification.
+ * Preview (DOM) vs Save (source via SAVE_TEXT_CHANGE) uses Crank text dispatch.
  */
 (function () {
   // Allow re-drag / re-inject to pick up companion updates.
@@ -2269,7 +2269,7 @@
   window.__crankTeardown = teardown;
 
   async function boot() {
-    loadCss(COMPANION_HTTP + '/ui/vizpatch-ui.css?v=' + Date.now());
+    loadCss(COMPANION_HTTP + '/ui/crank-ui.css?v=' + Date.now());
     await loadScript(COMPANION_HTTP + '/ui/crank-ui-helpers.js?v=' + Date.now());
     await loadScript(COMPANION_HTTP + '/ui/text-source.js?v=' + Date.now());
     buildPanelShell();

package/bookmarklet/crank-ui-helpers.js

@@ -1,5 +1,5 @@
 /**
- * Crank UI helpers — reused from Vizpatch tool-ui / vizpatch-ui-helpers.
+ * Crank UI helpers — tool-ui InputField / Button markup helpers.
  */
 (function (root) {
   'use strict';
@@ -17,7 +17,7 @@
     return escapeHtml(value).replace(/\n/g, ' ');
   }
 
-  /* VizPatch UI markup helpers — mirrors tool-ui InputField / Button structure */
+  /* Crank UI markup helpers — mirrors tool-ui InputField / Button structure */
 
   function vpJoinClasses() {
     const parts = [];
@@ -176,13 +176,13 @@
     const widthStyle = opts.width ? ' style="width:' + escapeAttr(String(opts.width)) + ';"' : ' style="width:100%;"';
     return '<div class="vp-field-select"' + widthStyle + '>'
       + '<input' + vpBuildTagAttrs(hiddenAttrs) + ' />'
-      + '<div class="vp-input-surface vp-control-surface ' + shellClass + '" data-vizpatch-part="control-surface" style="width:100%;">'
+      + '<div class="vp-input-surface vp-control-surface ' + shellClass + '" data-crank-part="control-surface" style="width:100%;">'
       + '<button type="button" class="vp-field-select-trigger ' + typeClass + '" aria-haspopup="listbox" aria-expanded="false">'
       + '<span class="vp-field-select-label">' + triggerLabel + '</span>'
       + vpChevronSvgHtml()
       + '</button>'
       + '</div>'
-      + '<div class="vp-dropdown-menu vizpatch-hidden" role="menu">' + menuItems + '</div>'
+      + '<div class="vp-dropdown-menu crank-hidden" role="menu">' + menuItems + '</div>'
       + '</div>';
   }
 
@@ -196,7 +196,7 @@
     const typeClass = size === 'compact' ? 'vp-compact-control-typography' : 'vp-control-typography';
     const areaAttrs = Object.assign({}, attrs || {}, { class: vpJoinClasses('vp-textarea-native', typeClass, attrs && attrs.class) });
     const shellClass = vpShellSizeClass(size);
-    return '<div class="vp-input-surface vp-input-surface--textarea vp-control-surface ' + shellClass + '" data-vizpatch-part="control-surface" style="width:100%;">'
+    return '<div class="vp-input-surface vp-input-surface--textarea vp-control-surface ' + shellClass + '" data-crank-part="control-surface" style="width:100%;">'
       + '<textarea' + vpBuildTagAttrs(areaAttrs) + '>' + escapeHtml(content || '') + '</textarea>'
       + '</div>';
   }