simple-module-cli 0.0.40__tar.gz → 0.0.42__tar.gz

{simple_module_cli-0.0.40 → simple_module_cli-0.0.42}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: simple_module_cli
-Version: 0.0.40
+Version: 0.0.42
 Summary: Standalone scaffolder for the SimpleModule framework — `smpy new`, `smpy create-module`, plugin host.
 Project-URL: Homepage, https://github.com/antosubash/simple_module_python
 Project-URL: Repository, https://github.com/antosubash/simple_module_python

{simple_module_cli-0.0.40 → simple_module_cli-0.0.42}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "simple_module_cli"
-version = "0.0.40"
+version = "0.0.42"
 description = "Standalone scaffolder for the SimpleModule framework — `smpy new`, `smpy create-module`, plugin host."
 readme = "README.md"
 license = "MIT"

{simple_module_cli-0.0.40 → simple_module_cli-0.0.42}/simple_module_cli/cli.py

@@ -23,6 +23,7 @@ import typer
 from simple_module_cli.add_cmd import add_module, run_add
 from simple_module_cli.case import to_kebab_case
 from simple_module_cli.docker_cmd import docker_app
+from simple_module_cli.migrations_cmd import migrations_app
 from simple_module_cli.module_cmd import module_app
 from simple_module_cli.new import new_project
 from simple_module_cli.openapi_cmd import openapi_app
@@ -49,6 +50,22 @@ app.add_typer(docker_app, name="docker")
 app.add_typer(skills_app, name="skills")
 app.add_typer(module_app, name="module")
 app.add_typer(openapi_app, name="openapi")
+app.add_typer(migrations_app, name="migrations")
+
+
+@app.command("doctor")
+def doctor() -> None:
+    """Check installed modules and their database compatibility."""
+    try:
+        from simple_module_core.__main__ import main as run_doctor
+    except ImportError:
+        # The CLI installs on its own (to scaffold); doctor needs a project's framework.
+        typer.echo(
+            "ERROR: smpy doctor needs simple_module_core; run it inside a project.", err=True
+        )
+        raise typer.Exit(1) from None
+
+    raise typer.Exit(run_doctor())
 
 
 @app.command("create-host")

{simple_module_cli-0.0.40 → simple_module_cli-0.0.42}/simple_module_cli/docker_assets.py

@@ -78,7 +78,7 @@ def scaffold_docker_assets(target: Path, ctx: ScaffoldCtx, *, flat: bool = False
         .replace(_PG_DB_TOKEN, pg_db)
         .replace(_APP_EXTRA_ENV_TOKEN, _APP_BROKER_ENV if with_tasks else "")
     )
-    volumes = ["pgdata"] if db == "postgres" else ["appdata"]
+    volumes = ["appdata", "pgdata"] if db == "postgres" else ["appdata"]
     if with_tasks:
         compose += _read(templates / f"compose-tasks-{db}.yml.tpl").replace(_PG_DB_TOKEN, pg_db)
         volumes.append("redisdata")

simple_module_cli-0.0.42/simple_module_cli/migration_recipes/mail_settings.py

@@ -0,0 +1,48 @@
+"""Frozen system mail-settings move from d7b3a9e5c1f2 (#711).
+
+An existing target value wins; the obsolete source row is removed.
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+_TABLE = "settings_setting"
+_SCOPE_SYSTEM = "system"
+_SYSTEM_SCOPE_ID = ""
+
+_KEY_PAIRS = (
+    ("users.mailer", "mail.backend"),
+    *((f"users.smtp_{f}", f"mail.smtp_{f}") for f in ("host", "port", "username", "password")),
+    ("users.smtp_from", "mail.smtp_from"),
+    ("users.smtp_tls", "mail.smtp_tls"),
+)
+
+
+def _rename(old: str, new: str) -> None:
+    scope = {"scope": _SCOPE_SYSTEM, "scope_id": _SYSTEM_SCOPE_ID, "old": old, "new": new}
+    bind = op.get_bind()
+    bind.execute(
+        sa.text(
+            f"DELETE FROM {_TABLE} WHERE scope = :scope AND scope_id = :scope_id AND key = :old"
+            f" AND EXISTS (SELECT 1 FROM {_TABLE} AS t WHERE t.scope = :scope"
+            " AND t.scope_id = :scope_id AND t.key = :new)"
+        ),
+        scope,
+    )
+    bind.execute(
+        sa.text(
+            f"UPDATE {_TABLE} SET key = :new"
+            " WHERE scope = :scope AND scope_id = :scope_id AND key = :old"
+        ),
+        scope,
+    )
+
+
+def upgrade() -> None:
+    for old, new in _KEY_PAIRS:
+        _rename(old, new)
+
+
+def downgrade() -> None:
+    for old, new in _KEY_PAIRS:
+        _rename(new, old)

simple_module_cli-0.0.42/simple_module_cli/migration_recipes/users_tokens.py

@@ -0,0 +1,34 @@
+"""Frozen token-storage upgrade from a626b1c8d023 (#711).
+
+Upgrade and downgrade invalidate all access/refresh credentials. Stop all old
+application workers before upgrading; clients must sign in again.
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+
+def _clear_tokens() -> None:
+    for table in ("users_refresh_token", "users_access_token"):
+        op.execute(sa.table(table).delete())
+
+
+def upgrade() -> None:
+    _clear_tokens()
+    with op.batch_alter_table("users_refresh_token") as batch:
+        batch.alter_column(
+            "token", existing_type=sa.Uuid(), type_=sa.String(64), postgresql_using="token::text"
+        )
+    with op.batch_alter_table("users_access_token") as batch:
+        batch.alter_column("token", existing_type=sa.String(43), type_=sa.String(64))
+
+
+def downgrade() -> None:
+    # Digests cannot be restored to UUIDs or bearer secrets.
+    _clear_tokens()
+    with op.batch_alter_table("users_refresh_token") as batch:
+        batch.alter_column(
+            "token", existing_type=sa.String(64), type_=sa.Uuid(), postgresql_using="token::uuid"
+        )
+    with op.batch_alter_table("users_access_token") as batch:
+        batch.alter_column("token", existing_type=sa.String(64), type_=sa.String(43))

simple_module_cli-0.0.42/simple_module_cli/migrations_cmd.py

@@ -0,0 +1,66 @@
+"""Prepare frozen framework upgrades in a consuming host's own Alembic graph."""
+
+from __future__ import annotations
+
+import os
+from importlib.resources import files
+from pathlib import Path
+from typing import Annotated
+from uuid import uuid4
+
+import typer
+
+migrations_app = typer.Typer(help="Prepare host-owned framework upgrade revisions.")
+_RECIPES = {
+    "mail.settings_namespace_v1": ("mail", "mail_settings.py"),
+    "users.hashed_bearer_tokens_v1": ("users", "users_tokens.py"),
+}
+
+
+@migrations_app.command("prepare")
+def prepare(
+    upgrade_id: Annotated[str, typer.Argument(help="Stable framework upgrade id.")],
+    head: Annotated[str, typer.Option("--head", help="Explicit host head or label@head.")],
+    config: Annotated[Path | None, typer.Option("--config", help="Host alembic.ini.")] = None,
+) -> None:
+    """Write a self-contained revision; never connect to or migrate the database."""
+    if upgrade_id not in _RECIPES:
+        raise typer.BadParameter(f"Unknown upgrade {upgrade_id!r}; choose {', '.join(_RECIPES)}")
+    try:
+        from alembic.config import Config
+        from alembic.script import ScriptDirectory
+        from alembic.util.exc import CommandError
+    except ImportError as exc:
+        raise typer.BadParameter(
+            "Run this command in the host environment with Alembic installed"
+        ) from exc
+
+    root = Path(os.environ.get("SM_PROJECT_ROOT", Path.cwd()))
+    if config is None:
+        config = root / "alembic.ini"
+        if not config.is_file():
+            config = root / "host/alembic.ini"
+    if not config.is_file():
+        raise typer.BadParameter(f"Host Alembic config not found: {config}")
+    try:
+        script = ScriptDirectory.from_config(Config(str(config)))
+        parent = script.get_revision(head)
+        if parent is None or not parent.is_head:
+            raise typer.BadParameter("--head must resolve to one existing host head")
+        label, recipe = _RECIPES[upgrade_id]
+        existing = {name for rev in script.walk_revisions() for name in rev.branch_labels}
+    except CommandError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+
+    # Frozen source is copied, so future package changes cannot change this revision.
+    source = files("simple_module_cli").joinpath("migration_recipes", recipe).read_text()
+    revision = uuid4().hex[:12]
+    branch_labels = None if label in existing else (label,)
+    identifiers = (
+        f"\nrevision = {revision!r}\ndown_revision = {parent.revision!r}\n"
+        f"branch_labels = {branch_labels!r}\ndepends_on = None\n"
+    )
+    path = Path(script.versions) / f"{revision}_{upgrade_id.replace('.', '_')}.py"
+    with path.open("x") as output:
+        output.write(source + identifiers)
+    typer.echo(f"Prepared {upgrade_id}: {path}. Review it, then run alembic upgrade heads.")

simple_module_cli-0.0.42/simple_module_cli/package_update.py

@@ -0,0 +1,189 @@
+"""``smpy package-update`` — bump simple_module_* deps to latest PyPI versions.
+
+Walks the project's ``pyproject.toml`` (and any ``[tool.uv.workspace]`` members),
+finds every dependency whose distribution name starts with ``simple_module_`` /
+``simple-module-``, queries PyPI for the latest non-yanked release, and points
+the constraint at it. Includes optional dependencies and dependency groups.
+Matching npm packages use the selected core release when published on npm.
+
+The rewrite preserves the pin style you wrote: ``==0.0.32`` becomes
+``==0.0.33``, ``>=0.0.32`` becomes ``>=0.0.33``, and an upper bound that
+excludes the latest release skips the dependency instead of being dropped.
+``--loosen`` restores the older behaviour of rewriting every constraint to
+``name>=<latest>``.
+
+Dependencies whose ``[tool.uv.sources]`` entry points at a workspace member, a
+local path, a git ref, or a URL are left untouched — those aren't installed
+from PyPI.
+"""
+
+from __future__ import annotations
+
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+from typing import Annotated
+
+import tomlkit
+import typer
+
+from simple_module_cli.package_update_deps import (
+    Change,
+    Skip,
+    collect_sm_deps,
+    local_sources,
+    normalize,
+    process_file,
+    source_map,
+    workspace_member_dirs,
+)
+from simple_module_cli.package_update_npm import load_manifests, plan_npm
+from simple_module_cli.pypi import Fetcher, default_fetcher, fetch_latest
+
+__all__ = ["package_update", "run_update"]
+
+
+_CORE = "simple-module-core"
+
+
+def _npm_target(cache: dict[str, str | None], skips: list[Skip]) -> tuple[str | None, str | None]:
+    """The core version npm pins follow, or why there is none.
+
+    npm pins move in lockstep with the Python core pin, so when this run left
+    that pin alone (an upper bound, a local source) the npm pins stay too.
+    """
+    for skip in skips:
+        if normalize(skip.package) == _CORE:
+            return None, f"simple_module_core not updated ({skip.reason})"
+    latest = next((v for n, v in cache.items() if normalize(n) == _CORE), None)
+    return latest, None if latest else "simple_module_core not found on PyPI"
+
+
+def _print_summary(changes: list[Change], skips: list[Skip], dry_run: bool) -> None:
+    if not changes and not skips:
+        typer.echo("No simple_module_* or @simple-module-py/* dependencies found.")
+        return
+    by_file: dict[Path, list[str]] = {}
+    for c in changes:
+        by_file.setdefault(c.file, []).append(f"  {c.package}: {c.old}  →  {c.new}")
+    for s in skips:
+        by_file.setdefault(s.file, []).append(f"  {s.package}: skipped ({s.reason})")
+    for file, lines in by_file.items():
+        typer.echo(f"\n{file}")
+        for line in lines:
+            typer.echo(line)
+    if changes:
+        verb = "Would update" if dry_run else "Updated"
+        file_count = len({c.file for c in changes})
+        typer.echo(f"\n{verb} {len(changes)} dependency(ies) across {file_count} file(s).")
+        if not dry_run:
+            if any(c.file.suffix == ".toml" for c in changes):
+                typer.echo("Run `uv sync` to apply Python changes.")
+            for directory in sorted(
+                {c.file.parent for c in changes if c.file.name == "package.json"}
+            ):
+                typer.echo(f"Run `npm install` in {directory} to apply npm changes.")
+    elif skips:
+        typer.echo("\nNo updates applied.")
+
+
+def run_update(
+    path: Path,
+    *,
+    dry_run: bool = False,
+    include_pre: bool = False,
+    loosen: bool = False,
+    fetcher: Fetcher | None = None,
+) -> None:
+    """Programmatic entry point — separated from the Typer command for testing."""
+    path = path.resolve()
+    root = path if path.name == "pyproject.toml" else path / "pyproject.toml"
+    if not root.is_file():
+        typer.echo(f"ERROR: {root} not found.", err=True)
+        raise typer.Exit(code=1)
+
+    fetch = fetcher or default_fetcher
+    root_doc = tomlkit.parse(root.read_bytes().decode("utf-8"))
+    files: list[tuple[Path, tomlkit.TOMLDocument]] = [(root, root_doc)]
+    for member in workspace_member_dirs(root, root_doc):
+        if member == root:
+            continue
+        files.append((member, tomlkit.parse(member.read_bytes().decode("utf-8"))))
+
+    npm_manifests = load_manifests([file.parent for file, _ in files])
+    inherited = source_map(root_doc)
+    locals_by_file = {file: local_sources(doc, inherited) for file, doc in files}
+
+    # Pre-fetch all unique sm packages in parallel — PyPI calls dominate runtime.
+    names = {n for file, doc in files for n in collect_sm_deps(doc, locals_by_file[file])}
+    if any(manifest.packages for manifest in npm_manifests) and not any(
+        normalize(n) == _CORE for n in names
+    ):
+        names.add("simple_module_core")
+    unique_names = sorted(names)
+    cache: dict[str, str | None] = {}
+    if unique_names:
+        with ThreadPoolExecutor(max_workers=min(8, len(unique_names))) as pool:
+            results = pool.map(
+                lambda n: (n, fetch_latest(n, include_pre=include_pre, fetcher=fetch)),
+                unique_names,
+            )
+            cache = dict(results)
+
+    all_changes: list[Change] = []
+    all_skips: list[Skip] = []
+    pending: list[tuple[Path, str]] = []
+
+    for file, doc in files:
+        changes, skips, new_doc = process_file(
+            file, doc, cache=cache, loosen=loosen, local=locals_by_file[file]
+        )
+        all_changes.extend(changes)
+        all_skips.extend(skips)
+        if new_doc is not None:
+            pending.append((file, tomlkit.dumps(new_doc)))
+
+    target, blocked = _npm_target(cache, all_skips)
+    changes, skips, npm_pending = plan_npm(npm_manifests, target, fetch, blocked=blocked)
+    all_changes.extend(changes)
+    all_skips.extend(skips)
+    pending.extend(npm_pending)
+
+    if not dry_run:
+        for file, content in pending:
+            # newline="" keeps each file's own line endings (CRLF must not become CRCRLF).
+            file.write_text(content, encoding="utf-8", newline="")
+
+    _print_summary(all_changes, all_skips, dry_run)
+
+
+def package_update(
+    path: Annotated[
+        Path,
+        typer.Option("--path", help="Project root or pyproject.toml. Defaults to cwd."),
+    ] = Path(),
+    dry_run: Annotated[
+        bool,
+        typer.Option("--dry-run", help="Show planned changes without writing."),
+    ] = False,
+    include_pre: Annotated[
+        bool,
+        typer.Option("--include-pre", help="Include pre-release versions."),
+    ] = False,
+    loosen: Annotated[
+        bool,
+        typer.Option(
+            "--loosen",
+            help="Rewrite Python constraints to `>=<latest>` instead of keeping their operator.",
+        ),
+    ] = False,
+) -> None:
+    """Update simple_module_* dependencies and lockstep @simple-module-py/* pins.
+
+    Each constraint keeps the operator it already has — `==0.0.32` becomes
+    `==0.0.33`, `>=0.0.32` becomes `>=0.0.33` — so bumping versions never
+    silently changes a project's pinning policy. A dependency whose upper
+    bound excludes the latest release is reported and left alone. Pass
+    `--loosen` to rewrite Python constraints to `>=<latest>` instead.
+    npm pins keep exact, caret or tilde style and skip unpublished core versions.
+    """
+    run_update(path, dry_run=dry_run, include_pre=include_pre, loosen=loosen)

simple_module_cli-0.0.42/simple_module_cli/package_update_deps.py

@@ -0,0 +1,153 @@
+"""Python manifest discovery and dependency planning for package-update."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import tomlkit
+from tomlkit.items import Array
+
+from simple_module_cli.requirements import parse_requirement, rewrite_requirement
+
+
+@dataclass(frozen=True)
+class Change:
+    file: Path
+    package: str
+    old: str
+    new: str
+
+
+@dataclass(frozen=True)
+class Skip:
+    file: Path
+    package: str
+    reason: str
+
+
+def normalize(name: str) -> str:
+    return re.sub(r"[-_.]+", "-", name).lower()
+
+
+def _is_sm_package(name: str) -> bool:
+    return normalize(name).startswith("simple-module-")
+
+
+def _dep_name(spec: str) -> str | None:
+    """Extract the distribution name from a PEP 508 requirement string."""
+    parsed = parse_requirement(spec)
+    return parsed.name if parsed else None
+
+
+def _is_local_source(source: Any) -> bool:
+    if isinstance(source, (list, Array)):
+        return any(_is_local_source(item) for item in source)
+    if not isinstance(source, dict):
+        return False
+    if source.get("workspace") is True:
+        return True
+    return any(key in source for key in ("path", "git", "url"))
+
+
+def _get_uv_section(doc: tomlkit.TOMLDocument, key: str) -> dict[str, Any] | None:
+    tool = doc.get("tool")
+    if not isinstance(tool, dict):
+        return None
+    uv = tool.get("uv")
+    if not isinstance(uv, dict):
+        return None
+    section = uv.get(key)
+    return section if isinstance(section, dict) else None
+
+
+def workspace_member_dirs(root_pyproject: Path, doc: tomlkit.TOMLDocument) -> list[Path]:
+    workspace = _get_uv_section(doc, "workspace")
+    if workspace is None:
+        return []
+    members = workspace.get("members") or []
+    base = root_pyproject.parent
+    out: list[Path] = []
+    for pattern in members:
+        for match in sorted(base.glob(str(pattern))):
+            if (match / "pyproject.toml").is_file():
+                out.append(match / "pyproject.toml")
+    return list(dict.fromkeys(p.resolve() for p in out))
+
+
+def source_map(doc: tomlkit.TOMLDocument) -> dict[str, Any]:
+    return {normalize(name): src for name, src in (_get_uv_section(doc, "sources") or {}).items()}
+
+
+def local_sources(doc: tomlkit.TOMLDocument, inherited: dict[str, Any]) -> set[str]:
+    sources = {**inherited, **source_map(doc)}
+    return {name for name, source in sources.items() if _is_local_source(source)}
+
+
+def _dependency_arrays(doc: tomlkit.TOMLDocument):
+    project = doc.get("project", {})
+    if isinstance(project, dict):
+        deps = project.get("dependencies")
+        if isinstance(deps, (list, Array)):
+            yield deps
+        optional = project.get("optional-dependencies", {})
+        if isinstance(optional, dict):
+            for deps in optional.values():
+                if isinstance(deps, (list, Array)):
+                    yield deps
+    groups = doc.get("dependency-groups", {})
+    if isinstance(groups, dict):
+        for deps in groups.values():
+            if isinstance(deps, (list, Array)):
+                yield deps
+
+
+def collect_sm_deps(doc: tomlkit.TOMLDocument, local: set[str]) -> list[str]:
+    return [
+        name
+        for deps in _dependency_arrays(doc)
+        for raw in deps
+        if isinstance(raw, str)
+        and (name := _dep_name(raw))
+        and _is_sm_package(name)
+        and normalize(name) not in local
+    ]
+
+
+def process_file(
+    path: Path,
+    doc: tomlkit.TOMLDocument,
+    *,
+    cache: dict[str, str | None],
+    loosen: bool = False,
+    local: set[str],
+) -> tuple[list[Change], list[Skip], tomlkit.TOMLDocument | None]:
+    changes: list[Change] = []
+    skips: list[Skip] = []
+
+    for deps in _dependency_arrays(doc):
+        for idx, raw in enumerate(deps):
+            if not isinstance(raw, str):
+                continue
+            dep_str = raw
+            name = _dep_name(dep_str)
+            if not name or not _is_sm_package(name):
+                continue
+            if normalize(name) in local:
+                skips.append(Skip(path, name, "workspace/local source"))
+                continue
+            latest = cache.get(name)
+            if latest is None:
+                skips.append(Skip(path, name, "not found on PyPI"))
+                continue
+            result = rewrite_requirement(dep_str, latest, loosen=loosen)
+            if result.spec is None:
+                if result.reason:
+                    skips.append(Skip(path, name, result.reason))
+                continue
+            deps[idx] = result.spec
+            changes.append(Change(path, name, dep_str.strip(), result.spec))
+
+    return changes, skips, doc if changes else None

simple_module_cli-0.0.42/simple_module_cli/package_update_npm.py

@@ -0,0 +1,126 @@
+"""Plan lockstep npm updates without installing packages or writing files."""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+from urllib.parse import quote
+
+from simple_module_cli.package_update_deps import Change, Skip
+from simple_module_cli.pypi import Fetcher
+
+_SECTIONS = ("dependencies", "devDependencies", "optionalDependencies", "peerDependencies")
+_PREFIX = "@simple-module-py/"
+_REGISTRY = "https://registry.npmjs.org/"
+_SEMVER = re.compile(
+    r"(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)"
+    r"(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?"
+    r"(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?"
+)
+
+
+def _version_key(version: str) -> tuple | None:
+    match = _SEMVER.fullmatch(version)
+    if not match:
+        return None
+    major, minor, patch, pre = match.groups()
+    identifiers = (pre or "").split(".") if pre else []
+    if any(part.isdigit() and len(part) > 1 and part.startswith("0") for part in identifiers):
+        return None
+    suffix = tuple((0, int(p)) if p.isdigit() else (1, p) for p in identifiers)
+    return (int(major), int(minor), int(patch), pre is None, suffix)
+
+
+@dataclass
+class Manifest:
+    path: Path
+    original: str
+    doc: dict[str, Any]
+
+    @property
+    def packages(self) -> set[str]:
+        return {
+            name
+            for section in _SECTIONS
+            for name in self.doc.get(section, {})
+            if name.startswith(_PREFIX)
+        }
+
+
+def load_manifests(directories: list[Path]) -> list[Manifest]:
+    manifests = []
+    paths = dict.fromkeys(
+        path.resolve()
+        for directory in directories
+        for path in (directory / "package.json", directory / "client_app/package.json")
+        if path.is_file()
+    )
+    for path in paths:
+        original = path.read_bytes().decode("utf-8")
+        doc = json.loads(original)
+        if not isinstance(doc, dict):
+            raise ValueError(f"{path}: expected a JSON object")
+        for section in _SECTIONS:
+            if section in doc and not isinstance(doc[section], dict):
+                raise ValueError(f"{path}: {section} must be an object")
+        manifests.append(Manifest(path, original, doc))
+    return manifests
+
+
+def _render(manifest: Manifest) -> str:
+    match = re.search(r"(?:\r?\n)([ \t]+)\S", manifest.original)
+    indent = match[1] if match else None
+    newline = "\r\n" if "\r\n" in manifest.original else "\n"
+    rendered = json.dumps(manifest.doc, indent=indent, ensure_ascii=False)
+    if newline != "\n":
+        rendered = rendered.replace("\n", newline)
+    return rendered + (newline if manifest.original.endswith("\n") else "")
+
+
+def plan_npm(
+    manifests: list[Manifest], target: str | None, fetcher: Fetcher, *, blocked: str | None = None
+) -> tuple[list[Change], list[Skip], list[tuple[Path, str]]]:
+    changes: list[Change] = []
+    skips: list[Skip] = []
+    pending: list[tuple[Path, str]] = []
+    available: dict[str, bool] = {}
+    target_key = _version_key(target) if target else None
+    for manifest in manifests:
+        changed = False
+        for section in _SECTIONS:
+            for name, pin in manifest.doc.get(section, {}).items():
+                if not name.startswith(_PREFIX):
+                    continue
+                style = pin[:1] if isinstance(pin, str) and pin[:1] in ("^", "~") else ""
+                current = _version_key(pin[len(style) :]) if isinstance(pin, str) else None
+                reason = None
+                if current is None:
+                    reason = f"unsupported npm reference {pin!r}"
+                elif target_key is None:
+                    reason = blocked or f"no npm-compatible simple_module_core target ({target})"
+                elif current >= target_key:
+                    continue
+                else:
+                    if name not in available:
+                        try:
+                            data = fetcher(_REGISTRY + quote(name, safe="@"))
+                            available[name] = isinstance(data, dict) and target in (
+                                data.get("versions") or {}
+                            )
+                        except (OSError, ValueError):  # HTTP/URL/timeout, bad JSON
+                            available[name] = False
+                    if not available[name]:
+                        reason = f"npm release {target} unavailable"
+                if reason:
+                    skips.append(Skip(manifest.path, name, reason))
+                    continue
+                new = style + str(target)
+                manifest.doc[section][name] = new
+                changes.append(Change(manifest.path, name, pin, new))
+                changed = True
+        if changed:
+            pending.append((manifest.path, _render(manifest)))
+    return changes, skips, pending