@aaqiljamal/visual-editor-server 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,285 @@
+import * as http from 'node:http';
+
+/**
+ * The refusal reasons are structured so the consumer (overlay UI, MCP layer)
+ * can branch on them: "show user a 'this className is composed by cn()' badge",
+ * "open the file at this location", etc. The `details` field is the human
+ * sentence; the `reason` is the machine code.
+ *
+ * v0.1 only accepts a static string literal at the located JSXOpeningElement.
+ * Anything dynamic — cn/clsx/twMerge/cva, template literals, conditionals,
+ * spreads, or anything we don't recognize — refuses with a clear reason.
+ * This is Principle 1's "determinism preconditions" enforced at the writer.
+ */
+type MutateClassNameRefusalReason = "dynamic-call-expression" | "dynamic-template-literal" | "dynamic-conditional" | "dynamic-other" | "dynamic-uncertain-arg" | "dynamic-spread-arg" | "dynamic-conflict" | "unknown-merger" | "no-classname-attribute" | "no-jsx-at-location" | "token-not-found";
+type MutateAttributeRefusalReason = "no-jsx-at-location" | "no-such-attribute" | "dynamic-value" | "token-not-found" | "parse-error";
+
+type ApplyInput = {
+    /** Path relative to the configured workspace root (the same root the Babel data-oid plugin used). */
+    file: string;
+    /** 1-based line number, as Babel reports in `loc.start.line`. */
+    line: number;
+    /** 0-based column number, as Babel reports in `loc.start.column`. */
+    col: number;
+    /** Attribute to mutate. Default "className" — token-swap semantics. Anything else uses whole-value swap (src, href, alt, …). */
+    attribute?: string;
+    /** Exact static class token to swap, e.g. "p-4". For non-className attributes, this is the whole expected current value (or null to skip conflict check). */
+    before: string | null;
+    /** Replacement, e.g. "p-6". For non-className attributes, this is the whole new value. */
+    after: string;
+};
+type ApplyOutcome = {
+    ok: true;
+    /** Unified diff between original and rewritten source. */
+    diff: string;
+    /** Absolute path that was written, for logging. */
+    absolutePath: string;
+    /** For non-className mutations called with before=null, the actual pre-mutation value. Undo uses this. */
+    previousValue?: string;
+} | {
+    ok: false;
+    /** HTTP-shaped status (the http layer maps this 1:1). */
+    status: 400 | 403 | 404 | 409 | 500;
+    reason: ApplyRefusalReason;
+    details: string;
+};
+type ApplyRefusalReason = "invalid-input" | "path-outside-workspace" | "file-not-found" | "read-failed" | "write-failed" | MutateClassNameRefusalReason | MutateAttributeRefusalReason;
+type ApplyOptions = {
+    workspaceRoot: string;
+    /**
+     * If `true`, mutate in memory and return the diff but do NOT write to disk.
+     * /propose uses this; /apply doesn't.
+     */
+    dryRun: boolean;
+};
+/**
+ * The single entry point for both /apply and /propose. Reads, mutates,
+ * conflict-checks (the mutate step's `token-not-found` IS the conflict
+ * signal — if the file moved out from under us, the `before` token won't
+ * be there anymore), then either writes or skips the write.
+ *
+ * Returning `ApplyOutcome` instead of throwing keeps the HTTP layer
+ * mechanical: every refusal carries its own status code and reason.
+ */
+declare function applyToFile(input: ApplyInput, options: ApplyOptions): Promise<ApplyOutcome>;
+
+/**
+ * Small in-memory deque of recently applied mutations, sized to keep the
+ * footprint negligible. Used by the 4th MCP tool (`revert_change`) and
+ * the overlay's "undo last apply" affordance.
+ *
+ * v0.2: persists to `<workspace>/.visual-editor/history.json` so the undo
+ * stack survives server restarts. Persistence is fire-and-forget on every
+ * mutation — `persistNow()` returns a Promise that tests can await for
+ * deterministic checks.
+ */
+type Apply = {
+    file: string;
+    line: number;
+    col: number;
+    before: string;
+    after: string;
+    appliedAt: number;
+};
+declare class RecentApplies {
+    private readonly maxSize;
+    private buffer;
+    private filePath;
+    constructor(maxSize?: number);
+    /**
+     * Wire up disk persistence. If the file exists, its contents become the
+     * initial buffer. If it doesn't, we remember the path for future writes.
+     */
+    load(filePath: string): Promise<void>;
+    push(apply: Apply): void;
+    /**
+     * Find the most-recent entry matching `key`. If no key is provided, returns
+     * the most-recent entry overall (single-step undo). Returns `null` when no
+     * matching entry is in the buffer.
+     */
+    find(key?: {
+        file: string;
+        line: number;
+        col: number;
+    }): Apply | null;
+    remove(apply: Apply): void;
+    list(): readonly Apply[];
+    clear(): void;
+    get size(): number;
+    /**
+     * Write the buffer to disk. No-op when no path has been configured.
+     * Safe to `void`-call for fire-and-forget; tests can `await` it for
+     * determinism.
+     */
+    persistNow(): Promise<void>;
+}
+
+type RevertInput = {
+    /** Optional — when omitted, the most-recent apply is reverted. */
+    file?: string;
+    line?: number;
+    col?: number;
+};
+type RevertOutcome = ApplyOutcome | {
+    ok: false;
+    status: 404;
+    reason: "no-recent-apply";
+    details: string;
+} | {
+    ok: false;
+    status: 400;
+    reason: "invalid-input";
+    details: string;
+};
+/**
+ * Revert a recent apply by swapping `before` and `after` and re-running
+ * the deterministic mutation through `applyToFile`. The conflict path
+ * (file edited externally between Apply and Revert) is the same as
+ * /apply — returns 409 with `token-not-found` if the "after" token no
+ * longer sits at line:col.
+ *
+ * On success, removes the entry from the buffer so re-reverting is not
+ * an infinite loop. The user can re-apply by re-driving the gesture.
+ */
+declare function revertToFile(input: RevertInput, options: ApplyOptions, recent: RecentApplies): Promise<RevertOutcome>;
+
+type ApplyCssPropertyInput = {
+    /** JSX file containing the JSXOpeningElement we resolve from. Workspace-relative. */
+    file: string;
+    /** 1-based line of the JSXOpeningElement. */
+    line: number;
+    /** 0-based column of the JSXOpeningElement. */
+    col: number;
+    /** CSS property to set, e.g. "padding". */
+    property: string;
+    /** New value, e.g. "1.5rem". */
+    value: string;
+};
+type ApplyCssPropertyRefusalReason = "invalid-input" | "path-outside-workspace" | "jsx-file-not-found" | "css-file-not-found" | "read-failed" | "write-failed" | "no-jsx-at-location" | "no-classname-attribute" | "dynamic-classname" | "not-a-css-module" | "unresolved-import" | "parse-error" | "css-parse-error" | "selector-not-found" | "composes-chain" | "invalid-property";
+type ApplyCssPropertyOutcome = {
+    ok: true;
+    diff: string;
+    cssAbsolutePath: string;
+    selector: string;
+    previousValue: string | null;
+} | {
+    ok: false;
+    status: 400 | 403 | 404 | 409 | 500;
+    reason: ApplyCssPropertyRefusalReason;
+    details: string;
+};
+declare function applyCssProperty(input: ApplyCssPropertyInput, options: {
+    workspaceRoot: string;
+    dryRun: boolean;
+}): Promise<ApplyCssPropertyOutcome>;
+
+type ApplyStyledPropertyInput = {
+    /** Workspace-relative JSX file containing both the JSX element AND the styled definition. */
+    file: string;
+    line: number;
+    col: number;
+    property: string;
+    value: string;
+};
+type ApplyStyledPropertyRefusalReason = "invalid-input" | "path-outside-workspace" | "file-not-found" | "read-failed" | "write-failed" | "no-jsx-at-location" | "not-a-styled-component" | "styled-with-interpolation" | "styled-extension-not-supported" | "styled-attrs-not-supported" | "cross-file-styled-not-supported" | "component-not-found" | "parse-error" | "css-parse-error" | "invalid-property";
+type ApplyStyledPropertyOutcome = {
+    ok: true;
+    diff: string;
+    componentName: string;
+    previousValue: string | null;
+} | {
+    ok: false;
+    status: 400 | 403 | 404 | 500;
+    reason: ApplyStyledPropertyRefusalReason;
+    details: string;
+};
+declare function applyStyledProperty(input: ApplyStyledPropertyInput, options: {
+    workspaceRoot: string;
+    dryRun: boolean;
+}): Promise<ApplyStyledPropertyOutcome>;
+
+/**
+ * Single in-memory "what is the user currently looking at" record, set by
+ * the overlay on element acquire and read by the MCP `get_selected_element`
+ * tool. Intentionally null when no selection is active — the MCP tool
+ * returns "no selection" rather than stale state.
+ */
+type Selection = {
+    /** Workspace-relative file path from the element's data-oid. */
+    file: string;
+    /** 1-based line number (Babel convention). */
+    line: number;
+    /** 0-based column (Babel convention). */
+    col: number;
+    /** The full data-oid string for traceability. */
+    oid: string;
+    /** Whole className string (overlay should split if it wants tokens). */
+    className: string;
+    /** DOM tag name like "div", "button". */
+    tagName: string;
+    /** Best-guess component name (file basename or Fiber name). */
+    componentName: string | null;
+    /** How many DOM elements share this data-oid right now (Principle 11). */
+    instanceCount: number;
+};
+declare class CurrentSelection {
+    private current;
+    set(s: Selection | null): void;
+    get(): Selection | null;
+    clear(): void;
+}
+
+/**
+ * Per-session token. Mounted on startup, kept in memory, and persisted to
+ * `<workspace>/.visual-editor/session.json` so the MCP stdio server (a
+ * sibling process spawned by Claude Code) can read it without us having to
+ * pipe it through a separate transport.
+ *
+ * Threat model: a random page running on the same dev machine (e.g. an ad
+ * iframe, a stale tab on another local port) could POST to the loopback
+ * server and clobber files. Requiring an Authorization header that only
+ * the overlay (and the MCP server, via the file) knows blocks that vector.
+ *
+ * Open trade-off in v0.1: GET /token returns the token without auth so
+ * the overlay can bootstrap. A drive-by page could fetch it the same way.
+ * Production hardening would either (a) inject the token into the page at
+ * dev-build time, or (b) pin the Origin/Referer header. Both require
+ * dev-server integration that's out of scope here.
+ */
+declare class SessionToken {
+    private token;
+    private filePath;
+    load(workspaceRoot: string): Promise<string>;
+    /** Construct the token in-process without touching disk. Used by tests. */
+    setInMemory(token: string): void;
+    get(): string;
+    /**
+     * Constant-time compare against the bearer string the client sent. Returns
+     * `true` when the lengths match AND every byte is equal. Plain `===` would
+     * leak length information through timing.
+     */
+    matches(received: string | null): boolean;
+}
+
+type ServerOptions = {
+    /** Absolute path inside which all /apply and /propose writes are constrained. */
+    workspaceRoot: string;
+    /** Optional pre-built buffer (tests inject their own). */
+    recentApplies?: RecentApplies;
+    /** Optional pre-built selection state (tests inject their own). */
+    currentSelection?: CurrentSelection;
+    /** Optional pre-loaded session token (tests inject their own). */
+    sessionToken?: SessionToken;
+    /**
+     * Pinned allowed origins. Empty means any origin (compat with v0.1).
+     * Production: pass the dev URL, e.g. `["http://localhost:3000"]`.
+     */
+    allowedOrigins?: readonly string[];
+};
+/**
+ * Build (but do not start) the local HTTP server. Callers do `.listen(port)`.
+ * Tests pass `port: 0` to get a random port; the CLI binds 7790.
+ */
+declare function createServer(options: ServerOptions): http.Server;
+
+export { type ApplyCssPropertyInput, type ApplyInput, type ApplyStyledPropertyInput, CurrentSelection, RecentApplies, type RevertInput, type Selection, SessionToken, applyCssProperty, applyStyledProperty, applyToFile, createServer, revertToFile };

package/dist/index.js

@@ -0,0 +1,21 @@
+import {
+  CurrentSelection,
+  RecentApplies,
+  SessionToken,
+  applyCssProperty,
+  applyStyledProperty,
+  applyToFile,
+  createServer,
+  revertToFile
+} from "./chunk-QEI2RGE2.js";
+export {
+  CurrentSelection,
+  RecentApplies,
+  SessionToken,
+  applyCssProperty,
+  applyStyledProperty,
+  applyToFile,
+  createServer,
+  revertToFile
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@aaqiljamal/visual-editor-server",
+  "version": "0.2.0",
+  "description": "Node-side AST mutator for visual-editor: Tailwind className, CSS Modules, styled-components. Used by @aaqiljamal/visual-editor-next as a library, or standalone via the `visual-editor-server` CLI.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "visual-editor-server": "bin/visual-editor-server.cjs"
+  },
+  "files": ["dist", "bin", "README.md"],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "node --import tsx --test 'test/**/*.test.ts'",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["visual-editor", "tailwind", "css-modules", "styled-components", "ast"],
+  "license": "MIT",
+  "author": "Aaqil Jamal",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/The-Design-Alchemist/visual-editor.git",
+    "directory": "packages/server"
+  },
+  "homepage": "https://github.com/The-Design-Alchemist/visual-editor#readme",
+  "bugs": "https://github.com/The-Design-Alchemist/visual-editor/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@babel/parser": "^7.27.0",
+    "@babel/types": "^7.27.0",
+    "@types/diff": "^7.0.2",
+    "diff": "^9.0.0",
+    "postcss": "^8.5.14",
+    "recast": "^0.23.11",
+    "tailwind-merge": "^3.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsup": "^8.3.5",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.3"
+  }
+}