@ahmednawaz/crank 0.1.2

package/companion/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@crank/companion",
+  "version": "0.1.0",
+  "private": true,
+  "main": "server.js",
+  "bin": {
+    "crank-companion": "bin/crank.js"
+  },
+  "scripts": {
+    "start": "node server.js"
+  },
+  "dependencies": {
+    "@cursor/sdk": "^1.0.23",
+    "cors": "^2.8.5",
+    "express": "^4.21.2",
+    "ws": "^8.18.0"
+  }
+}

package/companion/persist-apply.js

@@ -0,0 +1,189 @@
+'use strict';
+
+/**
+ * Persist an applied variant to source via Vizpatch text-writer (SAVE_TEXT_CHANGE).
+ * Skips locked/dynamic nodes with an explicit reason — never silent.
+ */
+
+const { saveTextChange, pathHintsFromUrl } = require('./text-dispatch');
+
+function roleLabel(role) {
+  const r = String(role || 'text').toLowerCase();
+  if (r === 'heading') return 'Heading';
+  if (r === 'action' || r === 'button') return 'CTA';
+  if (r === 'label') return 'Label';
+  return 'Body';
+}
+
+/**
+ * @param {object} session - session AFTER store.applyVariant (nodes already updated)
+ * @param {object} variant
+ * @param {string} projectRoot
+ * @param {object} [options]
+ * @param {object[]} [options.preApplyNodes] - session.nodes snapshot before apply
+ */
+function persistAppliedVariant(session, variant, projectRoot, options = {}) {
+  const preNodes = Array.isArray(options.preApplyNodes)
+    ? options.preApplyNodes
+    : session?.nodes || [];
+  const preByPath = new Map(preNodes.map((n) => [String(n.path), n]));
+  const variantNodes = Array.isArray(variant?.nodes) ? variant.nodes : [];
+
+  const results = [];
+  let saved = 0;
+  let skipped = 0;
+  let failed = 0;
+
+  for (const vn of variantNodes) {
+    const path = String(vn.path);
+    const pre =
+      preByPath.get(path) ||
+      (vn.id
+        ? preNodes.find((n) => n && String(n.id) === String(vn.id))
+        : null) ||
+      {};
+    const label = roleLabel(vn.role || pre.role);
+    const newText = String(vn.text != null ? vn.text : '');
+    const oldText = String(
+      pre.originalText != null
+        ? pre.originalText
+        : pre.previousText != null
+          ? pre.previousText
+          : pre.text != null
+            ? pre.text
+            : ''
+    );
+
+    if (oldText === newText) {
+      results.push({
+        path,
+        role: vn.role || pre.role,
+        label,
+        status: 'unchanged',
+        message: 'No text change'
+      });
+      skipped += 1;
+      continue;
+    }
+
+    const editable = pre.editable !== false && vn.editable !== false;
+    const sourceType =
+      (pre.textSource && pre.textSource.type) ||
+      (vn.textSource && vn.textSource.type) ||
+      '';
+
+    if (!editable) {
+      results.push({
+        path,
+        role: vn.role || pre.role,
+        label,
+        status: 'skipped',
+        reason: 'locked',
+        message:
+          sourceType === 'dynamic-data'
+            ? 'Dynamic/bound data — cannot write hardcoded source'
+            : sourceType === 'bound-unknown'
+              ? 'Bound text — cannot save to source'
+              : 'Node is not editable for source save'
+      });
+      skipped += 1;
+      continue;
+    }
+
+    const selectorText =
+      vn.selector || pre.selector || session.selector || '';
+    if (!selectorText) {
+      results.push({
+        path,
+        role: vn.role || pre.role,
+        label,
+        status: 'failed',
+        message: 'No CSS selector available for text save'
+      });
+      failed += 1;
+      continue;
+    }
+
+    if (!oldText) {
+      results.push({
+        path,
+        role: vn.role || pre.role,
+        label,
+        status: 'failed',
+        message:
+          'Missing originalText/oldValue for source resolve — re-select the element'
+      });
+      failed += 1;
+      continue;
+    }
+
+    const pageUrl = session.pageUrl || session.meta?.pageUrl || '';
+    const pathHints = []
+      .concat(Array.isArray(session.meta?.pathHints) ? session.meta.pathHints : [])
+      .concat(pathHintsFromUrl(pageUrl));
+
+    const saveResult = saveTextChange(
+      {
+        selectorText,
+        value: newText,
+        oldValue: oldText,
+        sourceUrl: pageUrl,
+        origin: session.origin || '',
+        pageUrl,
+        pathHints,
+        file: session.meta?.file || pre.file || undefined,
+        componentName:
+          session.meta?.componentName ||
+          pre.componentName ||
+          vn.componentName ||
+          undefined
+      },
+      projectRoot
+    );
+
+    if (saveResult.success) {
+      saved += 1;
+      results.push({
+        path,
+        role: vn.role || pre.role,
+        label,
+        status: 'saved',
+        file: saveResult.file,
+        message: `Saved to ${saveResult.file || 'source'}`
+      });
+    } else {
+      failed += 1;
+      results.push({
+        path,
+        role: vn.role || pre.role,
+        label,
+        status: 'failed',
+        file: saveResult.file,
+        message: saveResult.error || 'Save failed',
+        attemptedFiles: saveResult.attemptedFiles
+      });
+    }
+  }
+
+  const summaryParts = [];
+  if (saved) summaryParts.push(`saved ${saved}`);
+  if (failed) summaryParts.push(`failed ${failed}`);
+  if (skipped) summaryParts.push(`skipped ${skipped}`);
+
+  return {
+    ok: failed === 0,
+    persisted: saved > 0,
+    saved,
+    failed,
+    skipped,
+    results,
+    summary:
+      summaryParts.length > 0
+        ? `Source: ${summaryParts.join(', ')}`
+        : 'Source: nothing to write'
+  };
+}
+
+module.exports = {
+  persistAppliedVariant
+};

package/companion/selection-store.js

@@ -0,0 +1,175 @@
+'use strict';
+
+/**
+ * In-memory selection + variant session store.
+ * Browser bookmarklet writes here; MCP tools and Glean client read/write here.
+ */
+
+const crypto = require('crypto');
+const { assignUnitLabels } = require('../lib/copy-labels');
+
+/** @type {Map<string, object>} */
+const sessions = new Map();
+
+let activeSessionId = null;
+
+function createSessionId() {
+  return crypto.randomBytes(8).toString('hex');
+}
+
+/**
+ * @param {object} payload
+ * @returns {object}
+ */
+function normalizeNodes(nodes) {
+  return assignUnitLabels(
+    (Array.isArray(nodes) ? nodes : []).map((n, i) => {
+    const text = n && n.text != null ? String(n.text) : '';
+    const path = n && n.path != null ? String(n.path) : String(i);
+    return {
+      ...n,
+      id: (n && n.id) || `copy-${path}`,
+      path,
+      text,
+      previousText: n.previousText != null ? String(n.previousText) : text,
+      // Freeze source baseline for SAVE_TEXT_CHANGE oldValue across applies.
+      originalText:
+        n.originalText != null ? String(n.originalText) : text
+    };
+  })
+  );
+}
+
+function setSelection(payload) {
+  const id = createSessionId();
+  const nodes = normalizeNodes(payload.nodes);
+  const session = {
+    id,
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    origin: payload.origin || '',
+    pageUrl: payload.pageUrl || '',
+    selector: payload.selector || '',
+    tagName: payload.tagName || '',
+    nodes,
+    combinedText: payload.combinedText || nodes.map((n) => n.text).join('\n'),
+    variants: [],
+    appliedVariantId: null,
+    meta: payload.meta || {}
+  };
+  sessions.set(id, session);
+  activeSessionId = id;
+  return session;
+}
+
+function getActiveSession() {
+  if (!activeSessionId) {
+    return null;
+  }
+  return sessions.get(activeSessionId) || null;
+}
+
+function getSession(id) {
+  if (!id) {
+    return getActiveSession();
+  }
+  return sessions.get(id) || null;
+}
+
+function listSessions() {
+  return Array.from(sessions.values()).sort((a, b) =>
+    String(b.updatedAt).localeCompare(String(a.updatedAt))
+  );
+}
+
+/**
+ * @param {string} sessionId
+ * @param {object[]} variants
+ */
+function setVariants(sessionId, variants) {
+  const session = getSession(sessionId);
+  if (!session) {
+    throw new Error(`Unknown session: ${sessionId}`);
+  }
+  session.variants = Array.isArray(variants) ? variants : [];
+  session.updatedAt = new Date().toISOString();
+  sessions.set(session.id, session);
+  activeSessionId = session.id;
+  return session;
+}
+
+/**
+ * Apply a variant's node map onto the stored selection (source of truth for MCP).
+ * Live DOM apply is pushed to connected browsers via WebSocket by the server.
+ */
+function applyVariant(sessionId, variantId) {
+  const session = getSession(sessionId);
+  if (!session) {
+    throw new Error(`Unknown session: ${sessionId}`);
+  }
+  const variant = (session.variants || []).find((v) => v.id === variantId);
+  if (!variant) {
+    throw new Error(`Unknown variant: ${variantId}`);
+  }
+
+  const byPath = new Map(
+    (variant.nodes || []).map((n) => [String(n.path), n])
+  );
+
+  session.nodes = (session.nodes || []).map((node) => {
+    const next =
+      byPath.get(String(node.path)) ||
+      (node.id
+        ? (variant.nodes || []).find((n) => String(n.id) === String(node.id))
+        : null);
+    if (!next) {
+      return node;
+    }
+    return {
+      ...node,
+      id: node.id || next.id || `copy-${node.path}`,
+      text: next.text,
+      previousText: node.text,
+      originalText:
+        node.originalText != null ? node.originalText : node.text
+    };
+  });
+  session.combinedText = session.nodes.map((n) => n.text).join('\n');
+  session.appliedVariantId = variantId;
+  session.updatedAt = new Date().toISOString();
+  sessions.set(session.id, session);
+  activeSessionId = session.id;
+  return { session, variant };
+}
+
+function clearSessions() {
+  sessions.clear();
+  activeSessionId = null;
+}
+
+function setGleanProgress(sessionId, progress) {
+  const session = getSession(sessionId);
+  if (!session) return null;
+  session.gleanProgress = progress || null;
+  session.gleanProgressAt = new Date().toISOString();
+  sessions.set(session.id, session);
+  return session.gleanProgress;
+}
+
+function getGleanProgress(sessionId) {
+  const session = getSession(sessionId);
+  if (!session) return null;
+  return session.gleanProgress || null;
+}
+
+module.exports = {
+  setSelection,
+  getActiveSession,
+  getSession,
+  listSessions,
+  setVariants,
+  applyVariant,
+  clearSessions,
+  setGleanProgress,
+  getGleanProgress
+};