@jesscss/plugin-js 2.0.0-alpha.7 → 2.0.0-alpha.8

package/README.md

@@ -1,6 +1,51 @@
 # @jesscss/plugin-js
 
-Jess plugin that enables JavaScript/TypeScript module imports.
+**Import bridge for JavaScript/TypeScript modules in stylesheets — a seed of the
+JavaScript-execution / CSS-in-JS story.**
 
-This package checks for a usable Deno runtime before executing non-`@jesscss/fns`
-modules. It is intended to be auto-loaded by `jess` when installed.
+This plugin lets a stylesheet pull in JavaScript/TypeScript modules
+(`.js`, `.mjs`, `.cjs`, `.ts`, `.mts`, `.cts`) — the mechanism behind `@use` /
+`@-from` script imports and legacy Less `@plugin` loading. When installed, it is
+auto-loaded by `jess`.
+
+## Sandboxed execution
+
+`plugin-js` does **not** run untrusted module code in your Node process. Before
+executing anything, it checks for a usable **Deno** runtime (`deno --version`)
+and runs the module in a Deno subprocess behind a permission broker:
+
+- **read** is limited to `node_modules` (and an optional `jsReadRoot`),
+- **net** is denied unless you opt in (`allowHttp`, optionally scoped to
+  `allowNetHosts`),
+- **env / write / run / ffi / sys** are denied outright.
+
+Values cross the boundary through a small typed bridge (dimensions, colors,
+quoted strings, lists, detached rules, …). Built-in `@jesscss/fns` modules are
+trusted and imported directly, without the worker. If no Deno binary is found,
+the plugin fails with a clear message instead of falling back to unsandboxed
+execution.
+
+## Why it exists — the convergence angle
+
+One of the four tools [Jess](https://github.com/jesscss/jess) aims to converge is
+**CSS-in-JS**: running real JavaScript inside stylesheets so styles can be
+dynamic without leaving CSS files. This plugin — together with
+[`@jesscss/plugin-node-modules`](../jess-plugin-node-modules), which resolves the
+packages — is a seed of that story.
+
+That convergence is **roadmap — being proven through the alpha, not claimed as
+done.** Legacy Less `@plugin` is supported for compatibility but deprecated in
+favor of `@-from` / `@-use`.
+
+## Status
+
+**Alpha.** Part of Jess, the ground-up rewrite of Less.js (Jess *is* Less.js
+v5). Requires a Deno runtime for script execution. The programmatic
+plugin/compiler API is **not yet stabilized** — the `jess` / `lessc` CLIs are the
+public surface for the alpha. Watch the [docs site](https://jesscss.github.io/)
+for the API once it settles.
+
+- Project overview & positioning: <https://github.com/jesscss/jess#readme>
+- Docs: <https://jesscss.github.io/> (currently pre-alpha content)
+- Issues: <https://github.com/jesscss/jess/issues>
+- License: MIT

package/lib/index.cjs

@@ -144,6 +144,33 @@ const RUNTIME_MISSING_MESSAGE = [
 const BOOT_TIMEOUT_MS = 8e3;
 const REQUEST_TIMEOUT_MS = 1e4;
 const IDLE_SHUTDOWN_MS = 5e3;
+/**
+* Environment variables that inject a Node.js debugger/inspector bootloader
+* into child processes (VS Code / Cursor "Auto Attach", `node --inspect`, etc.).
+*
+* These must never leak into the sandboxed Deno worker: the injected bootloader
+* tries to read the environment, the Jess Deno sandbox denies `env` permission,
+* and the worker never signals ready — producing a spurious
+* "Timed out waiting for Deno worker startup" failure. Deno does not use any of
+* these vars, so stripping them is safe.
+*/
+const DEBUG_ENV_KEY_RE = /^(NODE_OPTIONS|NODE_INSPECT|VSCODE_INSPECTOR_OPTIONS)/i;
+const DEBUG_ENV_VALUE_RE = /js-debug|bootloader/i;
+/**
+* Returns a copy of `env` with Node debugger/inspector-attach variables removed,
+* so a spawned Deno subprocess starts regardless of the parent's debug env.
+* The Deno permission sandbox is untouched; this only stops leaking the debugger
+* into it.
+*/
+const sanitizeSpawnEnv = (env = process.env) => {
+	const clean = {};
+	for (const [key, value] of Object.entries(env)) {
+		if (DEBUG_ENV_KEY_RE.test(key)) continue;
+		if (typeof value === "string" && DEBUG_ENV_VALUE_RE.test(value)) continue;
+		clean[key] = value;
+	}
+	return clean;
+};
 const isPathInside = (candidatePath, rootPath) => {
 	const rel = node_path.relative(rootPath, candidatePath);
 	return rel === "" || !rel.startsWith("..") && !node_path.isAbsolute(rel);
@@ -227,7 +254,10 @@ var JsPlugin = class JsPlugin extends _jesscss_core.AbstractPlugin {
 		this.idleTimer.unref?.();
 	}
 	ensureRuntimeAvailable() {
-		if ((0, node_child_process.spawnSync)(this.opts.denoCommand ?? "deno", ["--version"], { stdio: "ignore" }).status !== 0) throw new Error(RUNTIME_MISSING_MESSAGE);
+		if ((0, node_child_process.spawnSync)(this.opts.denoCommand ?? "deno", ["--version"], {
+			stdio: "ignore",
+			env: sanitizeSpawnEnv(process.env)
+		}).status !== 0) throw new Error(RUNTIME_MISSING_MESSAGE);
 	}
 	ensureRuntime() {
 		if (this.runtimeState.status === "ready") {
@@ -354,7 +384,7 @@ var JsPlugin = class JsPlugin extends _jesscss_core.AbstractPlugin {
 				"pipe"
 			],
 			env: {
-				...process.env,
+				...sanitizeSpawnEnv(process.env),
 				DENO_PERMISSION_BROKER_PATH: socketPath
 			}
 		});
@@ -587,3 +617,4 @@ exports.JESS_PLUGIN_JS_GLOBAL = JESS_PLUGIN_JS_GLOBAL;
 exports.JsPlugin = JsPlugin;
 exports.__toESM = __toESM;
 exports.default = jsPlugin;
+exports.sanitizeSpawnEnv = sanitizeSpawnEnv;

package/lib/index.d.ts

@@ -14,6 +14,13 @@ export interface JsPluginOptions extends JavaScriptSandboxConfig {
      */
     runtimeApi?: 'module' | 'less';
 }
+/**
+ * Returns a copy of `env` with Node debugger/inspector-attach variables removed,
+ * so a spawned Deno subprocess starts regardless of the parent's debug env.
+ * The Deno permission sandbox is untouched; this only stops leaking the debugger
+ * into it.
+ */
+export declare const sanitizeSpawnEnv: (env?: NodeJS.ProcessEnv) => NodeJS.ProcessEnv;
 export declare class JsPlugin extends AbstractPlugin {
     opts: JsPluginOptions;
     private static cleanupRegistered;

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,cAAc,EACf,MAAM,eAAe,CAAC;AAQvB,MAAM,MAAM,uBAAuB,GAAG;IACpC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,WAAW,eAAgB,SAAQ,uBAAuB;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;CAChC;AA8GD,qBAAa,QAAS,SAAQ,cAAc;IAoBvB,IAAI,EAAE,eAAe;IAnBxC,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAS;IACzC,OAAO,CAAC,MAAM,CAAC,aAAa,CAAuB;IACnD,IAAI,SAAQ;IACZ,mBAAmB,WAAiC;IACpD,OAAO,CAAC,YAAY,CAAoC;IACxD,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,YAAY,CAAyB;IAC7C,OAAO,CAAC,gBAAgB,CAAqB;IAC7C,OAAO,CAAC,MAAM,CAA6C;IAC3D,OAAO,CAAC,YAAY,CAAM;IAC1B,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,OAAO,CAIV;IAEL,OAAO,CAAC,SAAS,CAA6B;gBAE3B,IAAI,GAAE,eAAoB;IAM7C,OAAO;IAIP,OAAO,CAAC,MAAM,CAAC,sBAAsB;IAkBrC,OAAO,CAAC,cAAc;IAOtB,OAAO,CAAC,oBAAoB;IAY5B,OAAO,CAAC,sBAAsB;IAU9B,OAAO,CAAC,aAAa;IA4BrB,OAAO,CAAC,gBAAgB;IAUxB,OAAO,CAAC,aAAa;IAarB,OAAO,CAAC,YAAY;IAepB,OAAO,CAAC,mBAAmB;YA0Bb,WAAW;IA8CzB,OAAO,CAAC,WAAW;YAwFL,YAAY;IAW1B,OAAO,CAAC,cAAc;IAiCtB,OAAO,CAAC,gBAAgB;YAQV,UAAU;IAwBxB,OAAO,CAAC,QAAQ;IA0BhB,OAAO;IAMP,OAAO,CAAC,iBAAiB;IAgBnB,MAAM,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IA+CpE;;;;;OAKG;IACG,gBAAgB,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC,CAAA;KAAE,CAAC;CA6BnI;AAED;;;GAGG;AACH,eAAO,MAAM,qBAAqB,iCAAiC,CAAC;AAOpE,QAAA,MAAM,QAAQ,UAAY,eAAe,aAEtB,CAAC;AAEpB,eAAe,QAAQ,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,cAAc,EACf,MAAM,eAAe,CAAC;AAQvB,MAAM,MAAM,uBAAuB,GAAG;IACpC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,WAAW,eAAgB,SAAQ,uBAAuB;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;CAChC;AAmCD;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAC3B,MAAK,MAAM,CAAC,UAAwB,KACnC,MAAM,CAAC,UAYT,CAAC;AA0FF,qBAAa,QAAS,SAAQ,cAAc;IAoBvB,IAAI,EAAE,eAAe;IAnBxC,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAS;IACzC,OAAO,CAAC,MAAM,CAAC,aAAa,CAAuB;IACnD,IAAI,SAAQ;IACZ,mBAAmB,WAAiC;IACpD,OAAO,CAAC,YAAY,CAAoC;IACxD,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,YAAY,CAAyB;IAC7C,OAAO,CAAC,gBAAgB,CAAqB;IAC7C,OAAO,CAAC,MAAM,CAA6C;IAC3D,OAAO,CAAC,YAAY,CAAM;IAC1B,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,OAAO,CAIV;IAEL,OAAO,CAAC,SAAS,CAA6B;gBAE3B,IAAI,GAAE,eAAoB;IAM7C,OAAO;IAIP,OAAO,CAAC,MAAM,CAAC,sBAAsB;IAkBrC,OAAO,CAAC,cAAc;IAOtB,OAAO,CAAC,oBAAoB;IAY5B,OAAO,CAAC,sBAAsB;IAW9B,OAAO,CAAC,aAAa;IA4BrB,OAAO,CAAC,gBAAgB;IAUxB,OAAO,CAAC,aAAa;IAarB,OAAO,CAAC,YAAY;IAepB,OAAO,CAAC,mBAAmB;YA0Bb,WAAW;IA8CzB,OAAO,CAAC,WAAW;YAwFL,YAAY;IAW1B,OAAO,CAAC,cAAc;IAiCtB,OAAO,CAAC,gBAAgB;YAQV,UAAU;IAwBxB,OAAO,CAAC,QAAQ;IA0BhB,OAAO;IAMP,OAAO,CAAC,iBAAiB;IAgBnB,MAAM,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IA+CpE;;;;;OAKG;IACG,gBAAgB,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC,CAAA;KAAE,CAAC;CA6BnI;AAED;;;GAGG;AACH,eAAO,MAAM,qBAAqB,iCAAiC,CAAC;AAOpE,QAAA,MAAM,QAAQ,UAAY,eAAe,aAEtB,CAAC;AAEpB,eAAe,QAAQ,CAAC"}

package/lib/index.js

@@ -115,6 +115,33 @@ const RUNTIME_MISSING_MESSAGE = [
 const BOOT_TIMEOUT_MS = 8e3;
 const REQUEST_TIMEOUT_MS = 1e4;
 const IDLE_SHUTDOWN_MS = 5e3;
+/**
+* Environment variables that inject a Node.js debugger/inspector bootloader
+* into child processes (VS Code / Cursor "Auto Attach", `node --inspect`, etc.).
+*
+* These must never leak into the sandboxed Deno worker: the injected bootloader
+* tries to read the environment, the Jess Deno sandbox denies `env` permission,
+* and the worker never signals ready — producing a spurious
+* "Timed out waiting for Deno worker startup" failure. Deno does not use any of
+* these vars, so stripping them is safe.
+*/
+const DEBUG_ENV_KEY_RE = /^(NODE_OPTIONS|NODE_INSPECT|VSCODE_INSPECTOR_OPTIONS)/i;
+const DEBUG_ENV_VALUE_RE = /js-debug|bootloader/i;
+/**
+* Returns a copy of `env` with Node debugger/inspector-attach variables removed,
+* so a spawned Deno subprocess starts regardless of the parent's debug env.
+* The Deno permission sandbox is untouched; this only stops leaking the debugger
+* into it.
+*/
+const sanitizeSpawnEnv = (env = process.env) => {
+	const clean = {};
+	for (const [key, value] of Object.entries(env)) {
+		if (DEBUG_ENV_KEY_RE.test(key)) continue;
+		if (typeof value === "string" && DEBUG_ENV_VALUE_RE.test(value)) continue;
+		clean[key] = value;
+	}
+	return clean;
+};
 const isPathInside = (candidatePath, rootPath) => {
 	const rel = path.relative(rootPath, candidatePath);
 	return rel === "" || !rel.startsWith("..") && !path.isAbsolute(rel);
@@ -198,7 +225,10 @@ var JsPlugin = class JsPlugin extends AbstractPlugin {
 		this.idleTimer.unref?.();
 	}
 	ensureRuntimeAvailable() {
-		if (spawnSync(this.opts.denoCommand ?? "deno", ["--version"], { stdio: "ignore" }).status !== 0) throw new Error(RUNTIME_MISSING_MESSAGE);
+		if (spawnSync(this.opts.denoCommand ?? "deno", ["--version"], {
+			stdio: "ignore",
+			env: sanitizeSpawnEnv(process.env)
+		}).status !== 0) throw new Error(RUNTIME_MISSING_MESSAGE);
 	}
 	ensureRuntime() {
 		if (this.runtimeState.status === "ready") {
@@ -325,7 +355,7 @@ var JsPlugin = class JsPlugin extends AbstractPlugin {
 				"pipe"
 			],
 			env: {
-				...process.env,
+				...sanitizeSpawnEnv(process.env),
 				DENO_PERMISSION_BROKER_PATH: socketPath
 			}
 		});
@@ -554,4 +584,4 @@ const jsPlugin = ((opts) => {
 	return new JsPlugin(opts);
 });
 //#endregion
-export { JESS_PLUGIN_JS_GLOBAL, JsPlugin, jsPlugin as default };
+export { JESS_PLUGIN_JS_GLOBAL, JsPlugin, jsPlugin as default, sanitizeSpawnEnv };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jesscss/plugin-js",
-  "version": "2.0.0-alpha.7",
+  "version": "2.0.0-alpha.8",
   "description": "Jess plugin for JavaScript/TypeScript module imports with Deno runtime checks",
   "main": "lib/index.cjs",
   "types": "lib/index.d.ts",
@@ -18,7 +18,7 @@
   ],
   "dependencies": {
     "deno": "^2.6.8",
-    "@jesscss/core": "2.0.0-alpha.7"
+    "@jesscss/core": "2.0.0-alpha.8"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",