Flask-Node 0.1.2__tar.gz → 0.2.0__tar.gz

{flask_node-0.1.2/src/Flask_Node.egg-info → flask_node-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Flask-Node
-Version: 0.1.2
+Version: 0.2.0
 Summary: Isolated Node/npm infrastructure for Flask extensions
 License-Expression: MIT
 Requires-Python: >=3.10
@@ -224,6 +224,78 @@ packages raise `PackageNotFoundError`; unsafe or missing assets raise
 `AssetResolutionError`. This is filesystem path validation, not protection
 against concurrent malicious filesystem changes.
 
+## Installed package entries
+
+After packages have been installed explicitly, consumers can resolve their
+JavaScript entry points through either the manager or the `Node` facade:
+
+```python
+entry = manager.resolve_entry("example")
+plugin = manager.resolve_entry("example", "plugin")
+scoped_entry = manager.resolve_entry("@scope/plugin")
+# Equivalent, inside the current application's context:
+entry = node.resolve_entry("example")
+```
+
+`resolve_entry(name, subpath=None)` returns an absolute, existing regular-file
+`pathlib.Path`. Package and subpath are separate arguments; do not put a subpath
+in `name`. Only locally installed packages under the manager's `node_modules`
+are accepted. Resolution is anchored to that manager, independent of the Python
+process's working directory or the location of consumer-owned source files.
+It does not require or generate a managed project manifest.
+
+The resolver invokes the configured `NODE_BIN` through `CommandRunner` and uses
+Node's `module.createRequire(...).resolve(...)`. It never loads or evaluates the
+target package, installs packages, invokes npm/npx, downloads files, copies
+assets, or writes helper files. Invoke it during an explicit consumer operation
+after installation; Flask-Node does not resolve entries or run processes during
+normal Flask initialization.
+
+Resolution follows Node's **require** semantics:
+
+- `exports`, when present, takes precedence over `main` and controls which root
+  and subpath entries are accessible. Blocked/private subpaths fail even when a
+  matching file exists.
+- Conditional exports use Node's active require conditions, including `node`,
+  `require`, and applicable `default` branches, in manifest order. An
+  `import`-only entry is unavailable. Additional conditions supplied by the Node
+  runtime/configuration, such as version-dependent `module-sync`, follow Node's
+  own behavior; Flask-Node does not emulate or override them.
+- Without `exports`, Node uses `main` and its legacy file/directory lookup,
+  including `.js`, `.json`, `.node` extension probing and index fallbacks.
+  Export targets require their exact files; legacy extension/index probing does
+  not apply to those targets. Nonstandard fields such as `module` are not used.
+
+These semantics suit consumers using require-style JavaScript plugin resolution.
+Consumers needing import-condition selection must not assume this API selects
+that branch. Resolution is separate from loading: a returned path may identify
+ESM, JSON, or a native addon, and does not guarantee that a consumer's loader can
+execute it. See Node's [resolution documentation](https://nodejs.org/api/modules.html#requireresolverequest-options)
+and [conditional exports](https://nodejs.org/api/packages.html#conditional-exports).
+
+Package names use the existing registry-name validation. A supplied subpath must
+be a nonempty relative string with no empty, `.` or `..` segments, absolute or
+Windows drive paths, backslashes, NULs, or percent encoding. The package,
+`node_modules`, and package manifest follow the existing symlink containment
+checks. The resolved entry must remain within that installed package's resolved
+root; internal symlinks are allowed, escaping symlinks are rejected. Ancestor or
+global packages, built-ins, directories, and other non-file results are
+unsupported. These are filesystem checks, not protection against concurrent
+malicious filesystem changes.
+
+Invalid package names raise `ConfigurationError`; missing or malformed installed
+packages raise `PackageNotFoundError`; package containment failures retain
+`AssetResolutionError`. Entry validation, Node resolution failures, and invalid
+results raise the publicly exported `EntryResolutionError`, derived from
+`NodeError`, with the requested entry and Node error code/message where available.
+Missing Node and runner failures propagate as `ExecutableNotFoundError` and
+`CommandExecutionError`; command diagnostics remain intact. Invalid resolver
+responses include captured output in the error. Existing `resolve(name, asset)`
+continues to resolve explicit filesystem paths and does not consult `exports`.
+
+Package-entry resolution is available starting with **0.2.0**. Consumer
+extensions using this API should declare `Flask-Node>=0.2.0`.
+
 ## Publishing browser assets
 
 Consuming extensions choose which npm dependencies and browser assets they need.
@@ -317,7 +389,8 @@ python -m venv .venv
 ```
 
 Tests inject/mock the runner and subprocess boundary. They never download npm
-packages or require Node. A custom runner can be supplied to `Node(runner=...)`
+packages. Offline integration tests use temporary fake packages and real Node
+when available; pytest reports explicit skips when Node is unavailable. A custom runner can be supplied to `Node(runner=...)`
 or `NodeManager(..., runner=...)` for testing. This dependency injection is not a
 consumer plugin protocol.
 

{flask_node-0.1.2 → flask_node-0.2.0}/README.md

@@ -210,6 +210,78 @@ packages raise `PackageNotFoundError`; unsafe or missing assets raise
 `AssetResolutionError`. This is filesystem path validation, not protection
 against concurrent malicious filesystem changes.
 
+## Installed package entries
+
+After packages have been installed explicitly, consumers can resolve their
+JavaScript entry points through either the manager or the `Node` facade:
+
+```python
+entry = manager.resolve_entry("example")
+plugin = manager.resolve_entry("example", "plugin")
+scoped_entry = manager.resolve_entry("@scope/plugin")
+# Equivalent, inside the current application's context:
+entry = node.resolve_entry("example")
+```
+
+`resolve_entry(name, subpath=None)` returns an absolute, existing regular-file
+`pathlib.Path`. Package and subpath are separate arguments; do not put a subpath
+in `name`. Only locally installed packages under the manager's `node_modules`
+are accepted. Resolution is anchored to that manager, independent of the Python
+process's working directory or the location of consumer-owned source files.
+It does not require or generate a managed project manifest.
+
+The resolver invokes the configured `NODE_BIN` through `CommandRunner` and uses
+Node's `module.createRequire(...).resolve(...)`. It never loads or evaluates the
+target package, installs packages, invokes npm/npx, downloads files, copies
+assets, or writes helper files. Invoke it during an explicit consumer operation
+after installation; Flask-Node does not resolve entries or run processes during
+normal Flask initialization.
+
+Resolution follows Node's **require** semantics:
+
+- `exports`, when present, takes precedence over `main` and controls which root
+  and subpath entries are accessible. Blocked/private subpaths fail even when a
+  matching file exists.
+- Conditional exports use Node's active require conditions, including `node`,
+  `require`, and applicable `default` branches, in manifest order. An
+  `import`-only entry is unavailable. Additional conditions supplied by the Node
+  runtime/configuration, such as version-dependent `module-sync`, follow Node's
+  own behavior; Flask-Node does not emulate or override them.
+- Without `exports`, Node uses `main` and its legacy file/directory lookup,
+  including `.js`, `.json`, `.node` extension probing and index fallbacks.
+  Export targets require their exact files; legacy extension/index probing does
+  not apply to those targets. Nonstandard fields such as `module` are not used.
+
+These semantics suit consumers using require-style JavaScript plugin resolution.
+Consumers needing import-condition selection must not assume this API selects
+that branch. Resolution is separate from loading: a returned path may identify
+ESM, JSON, or a native addon, and does not guarantee that a consumer's loader can
+execute it. See Node's [resolution documentation](https://nodejs.org/api/modules.html#requireresolverequest-options)
+and [conditional exports](https://nodejs.org/api/packages.html#conditional-exports).
+
+Package names use the existing registry-name validation. A supplied subpath must
+be a nonempty relative string with no empty, `.` or `..` segments, absolute or
+Windows drive paths, backslashes, NULs, or percent encoding. The package,
+`node_modules`, and package manifest follow the existing symlink containment
+checks. The resolved entry must remain within that installed package's resolved
+root; internal symlinks are allowed, escaping symlinks are rejected. Ancestor or
+global packages, built-ins, directories, and other non-file results are
+unsupported. These are filesystem checks, not protection against concurrent
+malicious filesystem changes.
+
+Invalid package names raise `ConfigurationError`; missing or malformed installed
+packages raise `PackageNotFoundError`; package containment failures retain
+`AssetResolutionError`. Entry validation, Node resolution failures, and invalid
+results raise the publicly exported `EntryResolutionError`, derived from
+`NodeError`, with the requested entry and Node error code/message where available.
+Missing Node and runner failures propagate as `ExecutableNotFoundError` and
+`CommandExecutionError`; command diagnostics remain intact. Invalid resolver
+responses include captured output in the error. Existing `resolve(name, asset)`
+continues to resolve explicit filesystem paths and does not consult `exports`.
+
+Package-entry resolution is available starting with **0.2.0**. Consumer
+extensions using this API should declare `Flask-Node>=0.2.0`.
+
 ## Publishing browser assets
 
 Consuming extensions choose which npm dependencies and browser assets they need.
@@ -303,7 +375,8 @@ python -m venv .venv
 ```
 
 Tests inject/mock the runner and subprocess boundary. They never download npm
-packages or require Node. A custom runner can be supplied to `Node(runner=...)`
+packages. Offline integration tests use temporary fake packages and real Node
+when available; pytest reports explicit skips when Node is unavailable. A custom runner can be supplied to `Node(runner=...)`
 or `NodeManager(..., runner=...)` for testing. This dependency injection is not a
 consumer plugin protocol.
 

{flask_node-0.1.2 → flask_node-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "Flask-Node"
-version = "0.1.2"
+version = "0.2.0"
 description = "Isolated Node/npm infrastructure for Flask extensions"
 readme = "README.md"
 requires-python = ">=3.10"

{flask_node-0.1.2 → flask_node-0.2.0/src/Flask_Node.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Flask-Node
-Version: 0.1.2
+Version: 0.2.0
 Summary: Isolated Node/npm infrastructure for Flask extensions
 License-Expression: MIT
 Requires-Python: >=3.10
@@ -224,6 +224,78 @@ packages raise `PackageNotFoundError`; unsafe or missing assets raise
 `AssetResolutionError`. This is filesystem path validation, not protection
 against concurrent malicious filesystem changes.
 
+## Installed package entries
+
+After packages have been installed explicitly, consumers can resolve their
+JavaScript entry points through either the manager or the `Node` facade:
+
+```python
+entry = manager.resolve_entry("example")
+plugin = manager.resolve_entry("example", "plugin")
+scoped_entry = manager.resolve_entry("@scope/plugin")
+# Equivalent, inside the current application's context:
+entry = node.resolve_entry("example")
+```
+
+`resolve_entry(name, subpath=None)` returns an absolute, existing regular-file
+`pathlib.Path`. Package and subpath are separate arguments; do not put a subpath
+in `name`. Only locally installed packages under the manager's `node_modules`
+are accepted. Resolution is anchored to that manager, independent of the Python
+process's working directory or the location of consumer-owned source files.
+It does not require or generate a managed project manifest.
+
+The resolver invokes the configured `NODE_BIN` through `CommandRunner` and uses
+Node's `module.createRequire(...).resolve(...)`. It never loads or evaluates the
+target package, installs packages, invokes npm/npx, downloads files, copies
+assets, or writes helper files. Invoke it during an explicit consumer operation
+after installation; Flask-Node does not resolve entries or run processes during
+normal Flask initialization.
+
+Resolution follows Node's **require** semantics:
+
+- `exports`, when present, takes precedence over `main` and controls which root
+  and subpath entries are accessible. Blocked/private subpaths fail even when a
+  matching file exists.
+- Conditional exports use Node's active require conditions, including `node`,
+  `require`, and applicable `default` branches, in manifest order. An
+  `import`-only entry is unavailable. Additional conditions supplied by the Node
+  runtime/configuration, such as version-dependent `module-sync`, follow Node's
+  own behavior; Flask-Node does not emulate or override them.
+- Without `exports`, Node uses `main` and its legacy file/directory lookup,
+  including `.js`, `.json`, `.node` extension probing and index fallbacks.
+  Export targets require their exact files; legacy extension/index probing does
+  not apply to those targets. Nonstandard fields such as `module` are not used.
+
+These semantics suit consumers using require-style JavaScript plugin resolution.
+Consumers needing import-condition selection must not assume this API selects
+that branch. Resolution is separate from loading: a returned path may identify
+ESM, JSON, or a native addon, and does not guarantee that a consumer's loader can
+execute it. See Node's [resolution documentation](https://nodejs.org/api/modules.html#requireresolverequest-options)
+and [conditional exports](https://nodejs.org/api/packages.html#conditional-exports).
+
+Package names use the existing registry-name validation. A supplied subpath must
+be a nonempty relative string with no empty, `.` or `..` segments, absolute or
+Windows drive paths, backslashes, NULs, or percent encoding. The package,
+`node_modules`, and package manifest follow the existing symlink containment
+checks. The resolved entry must remain within that installed package's resolved
+root; internal symlinks are allowed, escaping symlinks are rejected. Ancestor or
+global packages, built-ins, directories, and other non-file results are
+unsupported. These are filesystem checks, not protection against concurrent
+malicious filesystem changes.
+
+Invalid package names raise `ConfigurationError`; missing or malformed installed
+packages raise `PackageNotFoundError`; package containment failures retain
+`AssetResolutionError`. Entry validation, Node resolution failures, and invalid
+results raise the publicly exported `EntryResolutionError`, derived from
+`NodeError`, with the requested entry and Node error code/message where available.
+Missing Node and runner failures propagate as `ExecutableNotFoundError` and
+`CommandExecutionError`; command diagnostics remain intact. Invalid resolver
+responses include captured output in the error. Existing `resolve(name, asset)`
+continues to resolve explicit filesystem paths and does not consult `exports`.
+
+Package-entry resolution is available starting with **0.2.0**. Consumer
+extensions using this API should declare `Flask-Node>=0.2.0`.
+
 ## Publishing browser assets
 
 Consuming extensions choose which npm dependencies and browser assets they need.
@@ -317,7 +389,8 @@ python -m venv .venv
 ```
 
 Tests inject/mock the runner and subprocess boundary. They never download npm
-packages or require Node. A custom runner can be supplied to `Node(runner=...)`
+packages. Offline integration tests use temporary fake packages and real Node
+when available; pytest reports explicit skips when Node is unavailable. A custom runner can be supplied to `Node(runner=...)`
 or `NodeManager(..., runner=...)` for testing. This dependency injection is not a
 consumer plugin protocol.
 

{flask_node-0.1.2 → flask_node-0.2.0}/src/Flask_Node.egg-info/SOURCES.txt

@@ -11,6 +11,7 @@ src/flask_node/__init__.py
 src/flask_node/assets.py
 src/flask_node/cli.py
 src/flask_node/config.py
+src/flask_node/entry.py
 src/flask_node/exceptions.py
 src/flask_node/extension.py
 src/flask_node/manager.py
@@ -21,6 +22,7 @@ tests/conftest.py
 tests/test_assets.py
 tests/test_cli.py
 tests/test_declarative.py
+tests/test_entry.py
 tests/test_extension.py
 tests/test_manager.py
 tests/test_package.py

{flask_node-0.1.2 → flask_node-0.2.0}/src/flask_node/__init__.py

@@ -8,6 +8,7 @@ from .exceptions import (
     CommandExecutionError,
     ConfigurationError,
     DependencyConflictError,
+    EntryResolutionError,
     EnvironmentError,
     ExecutableNotFoundError,
     NodeError,
@@ -27,6 +28,7 @@ __all__ = [
     "CommandRunner",
     "ConfigurationError",
     "DependencyConflictError",
+    "EntryResolutionError",
     "EnvironmentError",
     "ExecutableNotFoundError",
     "Node",

flask_node-0.2.0/src/flask_node/entry.py

@@ -0,0 +1,101 @@
+"""Resolve installed entries using Node, without loading package code."""
+
+import json
+from pathlib import Path, PureWindowsPath
+
+from .exceptions import EntryResolutionError
+from .runner import CommandRunner
+
+# Only built-in modules are loaded. The synthetic anchor need not exist.
+_SCRIPT = """
+const { createRequire, isBuiltin } = require('node:module');
+const [anchor, specifier] = process.argv.slice(1);
+try {
+    if (isBuiltin(specifier)) {
+        throw Object.assign(new Error('Built-in modules are unsupported'), {
+            code: 'ERR_UNSUPPORTED_BUILTIN'
+        });
+    }
+    const resolved = createRequire(anchor).resolve(specifier);
+    process.stdout.write(JSON.stringify({path: resolved}));
+} catch (error) {
+    process.stdout.write(JSON.stringify({error: {
+        code: error.code || 'ERR_ENTRY_RESOLUTION', message: error.message
+    }}));
+}
+"""
+
+
+def validate_subpath(subpath: str | None) -> str | None:
+    if subpath is None:
+        return None
+    if (
+        not isinstance(subpath, str)
+        or not subpath
+        or Path(subpath).is_absolute()
+        or PureWindowsPath(subpath).drive
+        or "\\" in subpath
+        or "\x00" in subpath
+        or "%" in subpath
+        or any(part in ("", ".", "..") for part in subpath.split("/"))
+    ):
+        raise EntryResolutionError(f"Unsafe package entry subpath: {subpath!r}")
+    return subpath
+
+
+def resolve_entry(
+    runner: CommandRunner,
+    node_bin: str,
+    directory: Path,
+    root: Path,
+    specifier: str,
+) -> Path:
+    result = runner.run(
+        node_bin,
+        (
+            "--input-type=commonjs",
+            "--eval",
+            _SCRIPT,
+            "--",
+            str(directory / ".flask-node-resolver.cjs"),
+            specifier,
+        ),
+        cwd=directory,
+        capture_output=True,
+    )
+    try:
+        payload = json.loads(result.stdout or "")
+        if not isinstance(payload, dict):
+            raise TypeError("expected an object")
+        if "error" in payload:
+            error = payload["error"]
+            if not isinstance(error, dict):
+                raise ValueError("invalid error response")
+            detail = (
+                f"Cannot resolve entry {specifier!r}: "
+                f"{error.get('code', 'ERR_ENTRY_RESOLUTION')}: "
+                f"{error.get('message', 'unknown resolution failure')}"
+            )
+            if result.stderr:
+                detail += f"; stderr={result.stderr!r}"
+            raise EntryResolutionError(detail)
+        value = payload.get("path")
+        if not isinstance(value, str) or not Path(value).is_absolute():
+            raise ValueError(
+                "expected an absolute file path; built-ins are unsupported"
+            )
+        target = Path(value).resolve(strict=True)
+        if not target.is_relative_to(root):
+            raise EntryResolutionError(
+                f"Entry {specifier!r} escapes its installed package: {target}"
+            )
+        if not target.is_file():
+            raise EntryResolutionError(
+                f"Entry {specifier!r} is not a regular file: {target}"
+            )
+        return target
+    except (ValueError, OSError, RuntimeError, TypeError) as exc:
+        raise EntryResolutionError(
+            f"Cannot resolve entry {specifier!r}: {exc}; "
+            f"stdout={result.stdout!r}; stderr={result.stderr!r}"
+        ) from exc

{flask_node-0.1.2 → flask_node-0.2.0}/src/flask_node/exceptions.py

@@ -54,3 +54,7 @@ class AssetConflictError(NodeError):
 
 class AssetPublicationError(NodeError):
     pass
+
+
+class EntryResolutionError(NodeError):
+    """An installed package entry is unavailable, unsafe, or unsupported."""

{flask_node-0.1.2 → flask_node-0.2.0}/src/flask_node/extension.py

@@ -113,6 +113,9 @@ class Node:
     def resolve(self, name: str, asset: str | Path) -> Path:
         return self.get_manager().resolve(name, asset)
 
+    def resolve_entry(self, name: str, subpath: str | None = None) -> Path:
+        return self.get_manager().resolve_entry(name, subpath)
+
     @property
     def assets(self) -> tuple[NodeAsset, ...]:
         return self.get_manager().assets

{flask_node-0.1.2 → flask_node-0.2.0}/src/flask_node/manager.py

@@ -8,6 +8,7 @@ from typing import Any
 
 from .assets import NodeAsset, destination_path, publish, validate_tree
 from .config import read_configuration
+from .entry import resolve_entry, validate_subpath
 from .exceptions import (
     AssetConflictError,
     AssetPublicationError,
@@ -319,6 +320,16 @@ class NodeManager:
     def resolve(self, name: str, asset: str | Path) -> Path:
         return self.package(name).resolve(asset)
 
+    def resolve_entry(self, name: str, subpath: str | None = None) -> Path:
+        """Resolve an installed entry using Node's require conditions, without loading it."""
+        validate_name(name)
+        subpath = validate_subpath(subpath)
+        package = self.package(name)
+        specifier = name if subpath is None else f"{name}/{subpath}"
+        return resolve_entry(
+            self.runner, self.node_bin, self.directory, package.root, specifier
+        )
+
     def status(self) -> dict[str, Any]:
         return {
             "directory": str(self.directory),

flask_node-0.2.0/tests/test_entry.py

@@ -0,0 +1,364 @@
+import json
+import shutil
+from pathlib import Path
+
+import pytest
+from flask import Flask
+
+from flask_node import (
+    AssetResolutionError,
+    CommandExecutionError,
+    CommandResult,
+    CommandRunner,
+    ConfigurationError,
+    EntryResolutionError,
+    ExecutableNotFoundError,
+    Node,
+    NodeManager,
+    PackageNotFoundError,
+)
+
+
+def installed(manager, name="example", **manifest):
+    root = manager.directory / "node_modules" / name
+    root.mkdir(parents=True)
+    (root / "package.json").write_text(json.dumps({"version": "1", **manifest}))
+    for filename in ("index.js", "plugin.js", "require.cjs", "import.mjs", "main.js"):
+        # Loading this code would fail, proving resolution does not evaluate it.
+        (root / filename).write_text("throw new Error('PACKAGE EXECUTED');")
+    return root
+
+
+def response(runner, path):
+    runner.run.return_value = CommandResult(
+        ("node",), 0, json.dumps({"path": str(path)})
+    )
+
+
+@pytest.mark.parametrize(
+    "name,subpath", [("example", None), ("@scope/example", None), ("example", "plugin")]
+)
+def test_boundary(manager, runner, name, subpath):
+    root = installed(manager, name)
+    target = root / ("plugin.js" if subpath else "index.js")
+    response(runner, target)
+    assert manager.resolve_entry(name, subpath) == target
+    executable, args = runner.run.call_args.args
+    assert executable == manager.node_bin
+    assert args[-2:] == (
+        str(manager.directory / ".flask-node-resolver.cjs"),
+        name + (f"/{subpath}" if subpath else ""),
+    )
+    assert runner.run.call_args.kwargs == {
+        "cwd": manager.directory,
+        "capture_output": True,
+    }
+    assert not manager.manifest_path.exists()
+    assert not (manager.directory / ".flask-node-resolver.cjs").exists()
+    runner.locate.assert_not_called()
+
+
+@pytest.mark.parametrize(
+    "name", [None, "", "../x", "/x", "x/plugin", "node:fs", "@scope/../x", "C:\\x"]
+)
+def test_invalid_name(manager, runner, name):
+    with pytest.raises(ConfigurationError):
+        manager.resolve_entry(name)
+    runner.run.assert_not_called()
+    assert not manager.directory.exists()
+
+
+@pytest.mark.parametrize(
+    "subpath",
+    [
+        "",
+        ".",
+        "..",
+        "../x",
+        "x/../y",
+        "/x",
+        "C:/x",
+        "x\\y",
+        "x//y",
+        "./x",
+        "x/",
+        "\x00",
+        "%2e%2e/x",
+        "x%2fy",
+        1,
+        Path("plugin"),
+    ],
+)
+def test_invalid_subpath(manager, runner, subpath):
+    with pytest.raises(EntryResolutionError):
+        manager.resolve_entry("example", subpath)
+    runner.run.assert_not_called()
+    assert not manager.directory.exists()
+
+
+def test_missing_package(manager, runner):
+    with pytest.raises(PackageNotFoundError):
+        manager.resolve_entry("example")
+    runner.run.assert_not_called()
+    assert not manager.directory.exists()
+
+
+@pytest.mark.parametrize("value", ["fs", "node:fs", "relative.js", None])
+def test_unsupported_results(manager, runner, value):
+    installed(manager)
+    runner.run.return_value = CommandResult(("node",), 0, json.dumps({"path": value}))
+    with pytest.raises(EntryResolutionError):
+        manager.resolve_entry("example")
+
+
+@pytest.mark.parametrize("output", ["", "garbage", "[]", '{"error": null}'])
+def test_malformed_response(manager, runner, output):
+    installed(manager)
+    runner.run.return_value = CommandResult(("node",), 0, output, "diagnostic")
+    with pytest.raises(EntryResolutionError, match="diagnostic"):
+        manager.resolve_entry("example")
+
+
+@pytest.mark.parametrize("code", ["MODULE_NOT_FOUND", "ERR_PACKAGE_PATH_NOT_EXPORTED"])
+def test_node_error(manager, runner, code):
+    installed(manager)
+    runner.run.return_value = CommandResult(
+        ("node",), 0, json.dumps({"error": {"code": code, "message": "blocked entry"}})
+    )
+    with pytest.raises(EntryResolutionError, match=f"{code}: blocked entry"):
+        manager.resolve_entry("example", "plugin")
+
+
+@pytest.mark.parametrize(
+    "error",
+    [
+        ExecutableNotFoundError("missing node"),
+        CommandExecutionError(
+            "failed",
+            args=("node",),
+            cwd="managed",
+            returncode=7,
+            stdout="out",
+            stderr="err",
+        ),
+    ],
+)
+def test_runner_errors_preserved(manager, runner, error):
+    installed(manager)
+    runner.run.side_effect = error
+    with pytest.raises(type(error)) as caught:
+        manager.resolve_entry("example")
+    assert caught.value is error
+
+
+def test_missing_executable(manager, monkeypatch):
+    installed(manager)
+    manager.runner = CommandRunner()
+    monkeypatch.setattr("flask_node.runner.shutil.which", lambda executable: None)
+    with pytest.raises(ExecutableNotFoundError):
+        manager.resolve_entry("example")
+
+
+@pytest.mark.parametrize(
+    "kind", ["outside", "sibling", "directory", "missing", "symlink"]
+)
+def test_containment_and_files(manager, runner, tmp_path, kind):
+    root = installed(manager)
+    outside = tmp_path / "outside.js"
+    outside.write_text("outside")
+    if kind == "sibling":
+        target = installed(manager, "other") / "index.js"
+    elif kind == "directory":
+        target = root
+    elif kind == "missing":
+        target = root / "missing.js"
+    elif kind == "symlink":
+        target = root / "link.js"
+        target.symlink_to(outside)
+    else:
+        target = outside
+    response(runner, target)
+    with pytest.raises(EntryResolutionError):
+        manager.resolve_entry("example")
+
+
+@pytest.mark.parametrize("kind", ["modules", "package", "manifest"])
+def test_preflight_symlink_escape(manager, runner, tmp_path, kind):
+    root = installed(manager)
+    if kind == "modules":
+        shutil.rmtree(manager.directory / "node_modules")
+        (manager.directory / "node_modules").symlink_to(
+            tmp_path, target_is_directory=True
+        )
+    elif kind == "package":
+        shutil.rmtree(root)
+        root.symlink_to(tmp_path, target_is_directory=True)
+    else:
+        (root / "package.json").unlink()
+        (root / "package.json").symlink_to(tmp_path / "outside.json")
+    with pytest.raises(AssetResolutionError):
+        manager.resolve_entry("example")
+    runner.run.assert_not_called()
+
+
+def test_facade_isolation(tmp_path, runner):
+    node = Node(runner=runner)
+    for name in ("one", "two"):
+        app = Flask(name, root_path=str(tmp_path / name))
+        app.config["NODE_DIR"] = "custom"
+        node.init_app(app)
+        runner.run.assert_not_called()
+        manager = node.get_manager(app)
+        assert not manager.directory.exists()
+        root = installed(manager)
+        response(runner, root / "plugin.js")
+        with app.app_context():
+            assert node.resolve_entry("example", "plugin") == root / "plugin.js"
+        assert runner.run.call_args.kwargs["cwd"] == tmp_path / name / "custom"
+        runner.reset_mock()
+
+
+@pytest.fixture
+def real_manager(tmp_path):
+    executable = shutil.which("node")
+    if executable is None:
+        pytest.skip("Node executable unavailable: offline entry integration skipped")
+    return NodeManager(tmp_path / "custom-managed", node_bin=executable)
+
+
+@pytest.mark.parametrize(
+    "name,subpath,manifest,expected",
+    [
+        ("example", None, {}, "index.js"),
+        ("@scope/example", None, {"main": "main"}, "main.js"),
+        ("example", "plugin", {}, "plugin.js"),
+        (
+            "example",
+            None,
+            {"main": "main.js", "exports": "./require.cjs"},
+            "require.cjs",
+        ),
+        (
+            "example",
+            None,
+            {
+                "exports": {
+                    "import": "./import.mjs",
+                    "require": "./require.cjs",
+                    "default": "./main.js",
+                }
+            },
+            "require.cjs",
+        ),
+        (
+            "example",
+            None,
+            {"exports": {"node": "./main.js", "default": "./index.js"}},
+            "main.js",
+        ),
+        ("example", None, {"exports": {"default": "./main.js"}}, "main.js"),
+        (
+            "@scope/example",
+            "plugin",
+            {"exports": {"./plugin": "./require.cjs"}},
+            "require.cjs",
+        ),
+    ],
+)
+def test_offline_real_resolution(
+    real_manager, tmp_path, monkeypatch, name, subpath, manifest, expected
+):
+    root = installed(real_manager, name, **manifest)
+    unrelated = tmp_path / "unrelated"
+    unrelated.mkdir()
+    monkeypatch.chdir(unrelated)
+    before = {
+        p: p.read_bytes() for p in real_manager.directory.rglob("*") if p.is_file()
+    }
+    assert real_manager.resolve_entry(name, subpath) == root / expected
+    after = {
+        p: p.read_bytes() for p in real_manager.directory.rglob("*") if p.is_file()
+    }
+    assert before == after
+
+
+@pytest.mark.parametrize(
+    "manifest,subpath",
+    [
+        ({}, "missing"),
+        ({"exports": {".": "./index.js"}}, "plugin"),
+        ({"exports": {"import": "./import.mjs"}}, None),
+        ({"exports": "./missing.js"}, None),
+        ({"exports": "./main"}, None),
+        ({"exports": {"./plugin": None}}, "plugin"),
+    ],
+)
+def test_offline_missing_or_blocked(real_manager, manifest, subpath):
+    installed(real_manager, **manifest)
+    with pytest.raises(EntryResolutionError, match="example"):
+        real_manager.resolve_entry("example", subpath)
+
+
+def test_offline_builtin(real_manager):
+    installed(real_manager, "fs")
+    with pytest.raises(EntryResolutionError, match="ERR_UNSUPPORTED_BUILTIN"):
+        real_manager.resolve_entry("fs")
+
+
+def test_offline_internal_symlink(real_manager):
+    root = installed(real_manager)
+    (root / "plugin.js").unlink()
+    (root / "plugin.js").symlink_to(root / "index.js")
+    assert real_manager.resolve_entry("example", "plugin") == root / "index.js"
+
+
+def test_offline_directory_index(real_manager):
+    root = installed(real_manager)
+    (root / "plugin.js").unlink()
+    (root / "plugin").mkdir()
+    target = root / "plugin/index.js"
+    target.write_text("throw new Error('PACKAGE EXECUTED');")
+    assert real_manager.resolve_entry("example", "plugin") == target
+
+
+def test_offline_entry_symlink_escape(real_manager, tmp_path):
+    root = installed(real_manager)
+    outside = tmp_path / "outside.js"
+    outside.write_text("throw new Error('PACKAGE EXECUTED');")
+    (root / "index.js").unlink()
+    (root / "index.js").symlink_to(outside)
+    with pytest.raises(EntryResolutionError, match="escapes"):
+        real_manager.resolve_entry("example")
+
+
+def test_no_ancestor_fallback(real_manager, tmp_path):
+    ancestor = NodeManager(tmp_path)
+    installed(ancestor)
+    with pytest.raises(PackageNotFoundError):
+        real_manager.resolve_entry("example")
+    assert not real_manager.directory.exists()
+
+
+def test_offline_exports_directory_rejected(real_manager):
+    installed(real_manager, exports="./")
+    with pytest.raises(EntryResolutionError):
+        real_manager.resolve_entry("example")
+
+
+def test_resolution_error_retains_stderr(manager, runner):
+    installed(manager)
+    runner.run.return_value = CommandResult(
+        ("node",),
+        0,
+        json.dumps({"error": {"code": "MODULE_NOT_FOUND", "message": "missing"}}),
+        "runtime diagnostic",
+    )
+    with pytest.raises(EntryResolutionError, match="runtime diagnostic"):
+        manager.resolve_entry("example")
+
+
+def test_explicit_asset_ignores_exports(real_manager):
+    root = installed(real_manager, exports={".": "./index.js"})
+    assert real_manager.resolve("example", "plugin.js") == root / "plugin.js"
+    with pytest.raises(EntryResolutionError, match="ERR_PACKAGE_PATH_NOT_EXPORTED"):
+        real_manager.resolve_entry("example", "plugin")