wexample-wex-addon-dev-javascript 7.16.1__py3-none-any.whl → 8.1.0__py3-none-any.whl

wexample_wex_addon_dev_javascript/config_value/javascript_package_readme_config_value.py

@@ -10,5 +10,8 @@ from wexample_wex_addon_app.config_value.app_readme_config_value import (
 class JavascriptPackageReadmeContentConfigValue(AppReadmeConfigValue):
     """README generation for Javascript packages."""
 
-    def _get_app_description(self) -> str:
-        return self.workdir.get_app_config().get("description", "")
+    def _get_app_description(self) -> str | None:
+        return (
+            self.workdir.get_app_config().get("description")
+            or super()._get_app_description()
+        )

wexample_wex_addon_dev_javascript/file/javascript_package_json_file.py

@@ -1,60 +1,21 @@
 from __future__ import annotations
 
-from wexample_filestate.item.file.json_file import JsonFile
 from wexample_helpers.decorator.base_class import base_class
-from wexample_wex_addon_app.item.file.mixin.app_dependencies_config_file_mixin import (
-    AppDependenciesConfigFileMixin,
+
+from wexample_wex_addon_dev_javascript.file.node_package_json_file import (
+    NodePackageJsonFile,
 )
 
 
 @base_class
-class JavascriptPackageJsonFile(AppDependenciesConfigFileMixin, JsonFile):
-    def add_dependency(
-        self,
-        operator: str = "",
-        **kwargs,
-    ) -> bool:
-        # NPM uses bare versions (or ^/~), not "==".
-        return super().add_dependency(
-            operator=operator,
-            **kwargs,
-        )
-
-    def add_dependency_from_string(
-        self,
-        package_name: str,
-        version: str,
-        operator: str = "",
-        optional: bool = False,
-        group: None | str = None,
-    ) -> bool:
-        """
-        Add or update an npm dependency entry from a raw package name + version string.
-        Equivalent to add_dependency() but without requiring a CodeBaseWorkdir.
-        """
-        if optional:
-            section = "optionalDependencies"
-        elif group == "dev":
-            section = "devDependencies"
-        elif group:
-            section = group
-        else:
-            section = "dependencies"
-
-        constraint = f"{operator}{version}".strip()
-
-        config = self.read_config()
-        deps_node = config.search(path=section, default={})
-        deps = deps_node.to_dict() if deps_node else {}
-
-        if deps.get(package_name) == constraint:
-            return False
-
-        deps[package_name] = constraint
-        config.update_nested({section: deps})
-        self.write_config(config)
-
-        return True
+class JavascriptPackageJsonFile(NodePackageJsonFile):
+    """A published javascript package's package.json.
+
+    On top of the dependency-manifest API, publication metadata (name,
+    version, repository, publishConfig, exports...) is derived from the
+    workdir at dump time — which is why this class must never be attached
+    to an app manifest (see NodePackageJsonFile).
+    """
 
     def dumps(self, content: dict | None = None) -> str:
         content = content or self.read_parsed()
@@ -71,16 +32,6 @@ class JavascriptPackageJsonFile(AppDependenciesConfigFileMixin, JsonFile):
 
         return super().dumps(content)
 
-    def get_dependencies_versions(
-        self, optional: bool = False, group: str = "dev"
-    ) -> dict[str, str]:
-        config = self.read_config()
-        # Use to_dict_or_none() (not get_dict_or_default) so nested ConfigValue
-        # wrappers are unwrapped to native str — matches the dict[str, str] signature.
-        deps = config.search(path="dependencies").to_dict_or_none() or {}
-        peer = config.search(path="peerDependencies").to_dict_or_none() or {}
-        return {**deps, **peer}
-
     def _apply_default_publish_config(self, content: dict) -> None:
         content.setdefault("type", "module")
 

wexample_wex_addon_dev_javascript/file/node_package_json_file.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from wexample_filestate.item.file.json_file import JsonFile
+from wexample_helpers.decorator.base_class import base_class
+from wexample_wex_addon_app.item.file.mixin.app_dependencies_config_file_mixin import (
+    AppDependenciesConfigFileMixin,
+)
+
+
+@base_class
+class NodePackageJsonFile(AppDependenciesConfigFileMixin, JsonFile):
+    """A package.json exposing the dependency-manifest API.
+
+    Suits any workdir shipping a package.json (polyglot apps included);
+    JavascriptPackageJsonFile extends it with package-publication concerns
+    (name/version stamping, publishConfig...) that must never touch an
+    app manifest.
+    """
+
+    def add_dependency(
+        self,
+        operator: str = "",
+        **kwargs,
+    ) -> bool:
+        # NPM uses bare versions (or ^/~), not "==".
+        return super().add_dependency(
+            operator=operator,
+            **kwargs,
+        )
+
+    def add_dependency_from_string(
+        self,
+        package_name: str,
+        version: str,
+        operator: str = "",
+        optional: bool = False,
+        group: None | str = None,
+    ) -> bool:
+        """
+        Add or update an npm dependency entry from a raw package name + version string.
+        Equivalent to add_dependency() but without requiring a CodeBaseWorkdir.
+        """
+        if optional:
+            section = "optionalDependencies"
+        elif group == "dev":
+            section = "devDependencies"
+        elif group:
+            section = group
+        else:
+            section = "dependencies"
+
+        constraint = f"{operator}{version}".strip()
+
+        config = self.read_config()
+        deps_node = config.search(path=section, default={})
+        deps = deps_node.to_dict() if deps_node else {}
+
+        if deps.get(package_name) == constraint:
+            return False
+
+        deps[package_name] = constraint
+        config.update_nested({section: deps})
+        self.write_config(config)
+
+        return True
+
+    def get_dependencies_versions(
+        self, optional: bool = False, group: str = "dev"
+    ) -> dict[str, str]:
+        config = self.read_config()
+        # Use to_dict_or_none() (not get_dict_or_default) so nested ConfigValue
+        # wrappers are unwrapped to native str — matches the dict[str, str] signature.
+        deps = config.search(path="dependencies").to_dict_or_none() or {}
+        peer = config.search(path="peerDependencies").to_dict_or_none() or {}
+        return {**deps, **peer}

wexample_wex_addon_dev_javascript/formatter/javascript_code_formatter.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, ClassVar
+
+from wexample_helpers.decorator.base_class import base_class
+from wexample_wex_addon_ai.formatter.abstract_formatter import AbstractFormatter
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+@base_class
+class JavascriptCodeFormatter(AbstractFormatter):
+    """TypeScript and JavaScript shipped by an npm package, under its `src/`.
+
+    Covers both extensions because the packages are TypeScript sources published as
+    ESM, and a `.js` under `src/` is the same code with the types left out. Build
+    output, tests and config files answer elsewhere.
+    """
+
+    FORMATTER_NAME: ClassVar[str] = "javascript-code"
+    SOURCE_SUFFIXES: ClassVar[set[str]] = {".ts", ".tsx", ".js", ".jsx", ".mts", ".cts"}
+
+    def get_design_rules(self) -> str:
+        return self.read_resource("design_rules", "javascript_code.md")
+
+    def get_writing_rules(self) -> str:
+        return self.read_resource("writing_rules", "javascript_code.md")
+
+    def matches_path(self, path: Path) -> bool:
+        """A source file under the `src/` of a directory holding a `package.json`.
+
+        `node_modules` is excluded outright: every dependency in it carries its own
+        `package.json` and would otherwise match exactly like the package that
+        installed it.
+        """
+        if path.suffix not in self.SOURCE_SUFFIXES or "node_modules" in path.parts:
+            return False
+
+        for parent in path.parents:
+            if parent.name == "src" and (parent.parent / "package.json").exists():
+                return True
+        return False

wexample_wex_addon_dev_javascript/javascript_addon_manager.py

@@ -1,7 +1,37 @@
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
+from wexample_wex_addon_ai.formatter.formatter_contributing_addon_mixin import (
+    FormatterContributingAddonMixin,
+)
 from wexample_wex_core.common.abstract_addon_manager import AbstractAddonManager
 
+if TYPE_CHECKING:
+    from wexample_wex_addon_ai.formatter.abstract_formatter import AbstractFormatter
+
+
+class JavascriptAddonManager(FormatterContributingAddonMixin, AbstractAddonManager):
+    def get_formatter_classes(self) -> list[type[AbstractFormatter]]:
+        from wexample_wex_addon_dev_javascript.formatter.javascript_code_formatter import (
+            JavascriptCodeFormatter,
+        )
+
+        return [JavascriptCodeFormatter]
+
+    def get_workdir_types(self) -> dict[str, type]:
+        from wexample_wex_addon_dev_javascript.workdir.javascript_package_workdir import (
+            JavascriptPackageWorkdir,
+        )
+        from wexample_wex_addon_dev_javascript.workdir.javascript_packages_suite_workdir import (
+            JavascriptPackagesSuiteWorkdir,
+        )
+        from wexample_wex_addon_dev_javascript.workdir.javascript_workdir import (
+            JavascriptWorkdir,
+        )
 
-class JavascriptAddonManager(AbstractAddonManager):
-    pass
+        return {
+            "javascript": JavascriptWorkdir,
+            "javascript-package": JavascriptPackageWorkdir,
+            "javascript-packages-suite": JavascriptPackagesSuiteWorkdir,
+        }

wexample_wex_addon_dev_javascript/resources/design_rules/javascript_code.md

@@ -0,0 +1,17 @@
+This file is design rules for TypeScript shipped by an npm package, under its `src/`.
+Decide the layout below before opening an editor — by the time a file is being written,
+its path is already a decision made.
+
+- One class per file, one file per class, and the file name is the class name in
+  PascalCase — `Common/AsyncConstructor.ts` holds `AsyncConstructor` and nothing else.
+  The class is the file's `export default`.
+- Helper functions are grouped by the type they act on, one file per type, named after
+  it: `Helper/Array.ts`, `Helper/String.ts`, `Helper/Dom.ts`. They are named exports,
+  never a default, and each name is prefixed with the file's subject —
+  `arrayShallowCopy`, `stringToKebabCase`. The prefix is what makes the import readable
+  at the call site, where the file name is no longer visible.
+- Kinds live apart, each in its own directory under `src/`: classes in `Common/`, helper
+  functions in `Helper/`. A class dropped next to the helpers because it serves them is
+  the case to move.
+- No barrel files. Import from the module that defines the symbol, so that a consumer
+  bundling one helper does not pull the package in.

wexample_wex_addon_dev_javascript/resources/writing_rules/javascript_code.md

@@ -0,0 +1,26 @@
+This file is TypeScript shipped by an npm package, under its `src/`. The file's path is
+already decided by the time these rules apply — see
+`ai::design/rules --formatter javascript-code` for the layout decisions that come before
+it.
+
+- Code, names, comments and doc comments are in English, whatever language the
+  conversation is held in.
+- Relative imports carry the `.js` extension even though the source is `.ts` —
+  `import { functionIsType } from '../Helper/Function.js'`. The packages publish native
+  ESM, where the specifier is resolved as written at runtime and an extensionless path
+  has nothing to resolve.
+- The packages compile under `strict`, so every parameter and every return is typed, and
+  `any` is a decision to justify rather than a default. Prefer a generic that keeps the
+  caller's type (`<T>(array: T[]): T[]`) over widening to `unknown[]` and casting back.
+- A `try` is occasional and justified: it catches a failure somewhere that knows what to do
+  about it. Wrapping a call defensively, or writing a `catch` that swallows and a `finally`
+  that lets the failure pass, turns a bug into a wrong result reported nowhere. Let it
+  throw — a stack trace at the point of failure is worth more than a silent fallback
+  discovered three layers later.
+- Defensive code goes the same way: a guard against a state that cannot happen, a `typeof`
+  check on something the type already guarantees, a `?.` or `|| fallback` on a value that
+  is never missing. Validate at the boundary — user input, an external API, a parsed
+  payload — and trust what our own code hands you.
+- Comment only what the code cannot say: a constraint, an invariant, the reason a
+  surprising line is the way it is. A comment that no longer matches the code it
+  describes is deleted, not updated around.

wexample_wex_addon_dev_javascript/services/node/commands/service/install_local.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from wexample_cli.const.tags import AudienceTag, EffectTag, ScopeTag
+from wexample_cli.decorator.command import command
+from wexample_wex_core.const.globals import COMMAND_TYPE_SERVICE
+
+from wexample_wex_addon_dev_javascript.const.tags import DomainTag
+
+if TYPE_CHECKING:
+    from wexample_cli.context.execution_context import ExecutionContext
+    from wexample_wex_addon_app.service.app_service import AppService
+
+# In-container layout convention shared by the local dev composes: the app is
+# served from APP_DIR and each locally-developed javascript suite is mounted
+# under JS_DEV_DIR/<vendor> (see the `local_packages` env config section).
+APP_DIR = "/var/www/html"
+JS_DEV_DIR = "/var/www/javascript-dev"
+
+
+@command(
+    type=COMMAND_TYPE_SERVICE,
+    description="Wire locally-developed npm packages into node_modules/ (local env only)",
+    tags=[
+        DomainTag.FRONTEND,
+        EffectTag.WRITE,
+        AudienceTag.AGENT_SAFE,
+        ScopeTag.APP,
+        ScopeTag.CONTAINER,
+        ScopeTag.LOCAL,
+    ],
+)
+def node__service__install_local(
+    context: ExecutionContext,
+    service: AppService,
+) -> None:
+    """Generic node_modules wiring, reusable by any service whose container
+    runs the app's javascript toolchain (symfony, laravel, vite…).
+
+    Delegating services call this with their own ``service`` so the work runs
+    inside their container.
+    """
+    js_packages = service.app_workdir.get_runtime_config().search(
+        "local_packages.javascript"
+    )
+    if js_packages.is_none():
+        context.io.log("No local_packages.javascript configured, nothing to wire.")
+        return
+
+    vendors = " ".join(sorted(js_packages.to_dict().keys()))
+
+    # Package managers keep the (possibly stale) registry version even when a
+    # newer local source exists, so the deterministic wiring is a forced
+    # symlink over node_modules/ — resolved by each package's declared scoped
+    # name, which differs from its directory name.
+    script = f"""
+set -e
+cd {APP_DIR}
+if [ -f yarn.lock ]; then yarn install
+elif [ -f pnpm-lock.yaml ]; then pnpm install
+else npm install
+fi
+for vendor in {vendors}; do
+  [ -d "{JS_DEV_DIR}/$vendor" ] || continue
+  for src in {JS_DEV_DIR}/$vendor/*/; do
+    [ -f "$src/package.json" ] || continue
+    name=$(node -p "require('$src/package.json').name")
+    mkdir -p "node_modules/$(dirname "$name")"
+    rm -rf "node_modules/$name"
+    ln -s "${{src%/}}" "node_modules/$name"
+    echo "  symlinked $name"
+  done
+done
+"""
+
+    context.io.log(f"Wiring local npm packages ({vendors}) into node_modules/…")
+    output = service.addon_manager.docker_exec(
+        service.name, ["/bin/sh", "-c", script]
+    )
+    context.io.log(output)

wexample_wex_addon_dev_javascript/services/node/commands/service/refresh_lock.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from wexample_cli.const.tags import AudienceTag, EffectTag, ScopeTag
+from wexample_cli.decorator.command import command
+from wexample_cli.decorator.option import option
+from wexample_wex_core.const.globals import COMMAND_TYPE_SERVICE
+
+from wexample_wex_addon_dev_javascript.const.tags import DomainTag
+from wexample_wex_addon_dev_javascript.services.node.commands.service.install_local import (
+    APP_DIR,
+)
+
+if TYPE_CHECKING:
+    from wexample_cli.context.execution_context import ExecutionContext
+    from wexample_wex_addon_app.service.app_service import AppService
+
+
+@option(
+    name="npm_packages",
+    type=str,
+    required=False,
+    default="",
+    description="Space-separated npm package names whose constraint changed in package.json",
+)
+@command(
+    type=COMMAND_TYPE_SERVICE,
+    description="Refresh the javascript lock file after a package.json dependency change",
+    tags=[
+        DomainTag.FRONTEND,
+        EffectTag.WRITE,
+        AudienceTag.AGENT_SAFE,
+        ScopeTag.APP,
+        ScopeTag.CONTAINER,
+        ScopeTag.LOCAL,
+    ],
+)
+def node__service__refresh_lock(
+    context: ExecutionContext,
+    service: AppService,
+    npm_packages: str = "",
+) -> None:
+    """Generic javascript lock refresh, reusable by any service whose
+    container runs the app's javascript toolchain.
+
+    The lock file present in the app tells which package manager owns it.
+    Yarn classic has no lock-only mode, so node_modules is (re)installed
+    along the way — harmless inside the app container.
+    """
+    # The hook reaches every service, carrying only the manifests that moved.
+    if not npm_packages:
+        return
+
+    script = f"""
+set -e
+cd {APP_DIR}
+if [ -f yarn.lock ]; then yarn install
+elif [ -f pnpm-lock.yaml ]; then pnpm install --lockfile-only
+elif [ -f package-lock.json ]; then npm install --package-lock-only
+else
+  echo "No javascript lock file found in {APP_DIR}" >&2
+  exit 1
+fi
+"""
+
+    context.io.log(f"Refreshing javascript lock file ({npm_packages})…")
+    output = service.addon_manager.docker_exec(
+        service.name, ["/bin/sh", "-c", script]
+    )
+    context.io.log(output)

wexample_wex_addon_dev_javascript/workdir/javascript_package_workdir.py

@@ -35,6 +35,14 @@ class JavascriptPackageWorkdir(JavascriptWorkdir):
     def get_project_name(self) -> str:
         return f"@{self.get_vendor_name()}/{string_to_kebab_case(super().get_project_name())}"
 
+    # Lockfile → package manager + its lockfile-only refresh command. The
+    # lockfile present in the repo tells which manager the project uses.
+    _LOCKFILE_REFRESH_COMMANDS: dict[str, list[str]] = {
+        "package-lock.json": ["npm", "install", "--package-lock-only"],
+        "pnpm-lock.yaml": ["pnpm", "install", "--lockfile-only"],
+        "yarn.lock": ["yarn", "install", "--mode", "update-lockfile"],
+    }
+
     def prepare_value(self, raw_value: DictConfig | None = None) -> DictConfig:
         from wexample_filestate.const.disk import DiskItemType
         from wexample_helpers.helper.file import file_read
@@ -76,8 +84,20 @@ class JavascriptPackageWorkdir(JavascriptWorkdir):
 
         return raw_value
 
+    def release(self, **kwargs) -> None:
+        # The lockfile must follow package.json: CI installs run in strict
+        # mode (`npm ci` & co) and fail hard on any desync between the two.
+        # A sibling's propagate step may have bumped constraints here, so the
+        # refresh happens at release start — NOT at propagate time, when the
+        # sibling's new version is not registry-available yet (it publishes,
+        # then waits for the registry, before dependents release: the suite
+        # loop follows the dependency graph).
+        self._refresh_lockfile()
+        return super().release(**kwargs)
+
     def _classify_version_bump(self, last_tag: str) -> str:
         from wexample_helpers.const.types import (
+            UPGRADE_TYPE_INTERMEDIATE,
             UPGRADE_TYPE_MAJOR,
             UPGRADE_TYPE_MINOR,
         )
@@ -147,6 +167,24 @@ class JavascriptPackageWorkdir(JavascriptWorkdir):
 
         git_push_tag(tag, cwd=cwd, remote=remote, inherit_stdio=True)
 
+    def _refresh_lockfile(self) -> None:
+        import shutil
+
+        from wexample_helpers.helper.shell import shell_run
+
+        for lockfile, command in self._LOCKFILE_REFRESH_COMMANDS.items():
+            if not (self.get_path() / lockfile).exists():
+                continue
+            if shutil.which(command[0]) is None:
+                raise RuntimeError(
+                    f"{lockfile} needs a refresh after a dependency change in "
+                    f"{self.get_project_name()}, but '{command[0]}' is not "
+                    f"available on this machine. A stale lockfile would break "
+                    f"the strict CI install."
+                )
+            shell_run(command, cwd=self.get_path())
+            return
+
     def _wait_for_registry(self) -> None:
         """Poll the configured npm registry until the current version is available (max 20 min).