depwake 0.3.1__tar.gz

depwake-0.3.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Depwake Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

depwake-0.3.1/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: depwake
+Version: 0.3.1
+Summary: Wake your sleeping dependencies — risk-grouped upgrade plans, safe auto-bumps, no noise
+License: MIT
+Project-URL: Homepage, https://github.com/YOUR-USER/depwake
+Project-URL: Issues, https://github.com/YOUR-USER/depwake/issues
+Keywords: dependencies,upgrades,npm,pypi,maintenance
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Depwake ⏰
+
+[![CI](https://github.com/YOUR-USER/depwake/actions/workflows/ci.yml/badge.svg)](https://github.com/YOUR-USER/depwake/actions/workflows/ci.yml)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/YOUR-USER/depwake/badge)](https://scorecard.dev/viewer/?uri=github.com/YOUR-USER/depwake)
+
+**Wake your sleeping dependencies.**
+
+Your side project has 47 outdated packages, 3 security advisories, and a `package.json` from 2023. Dependabot spams you with 40 context-free PRs. Depwake does the opposite: one risk-grouped plan — patch today, minor this week, major deliberately — and safe auto-bumps for the boring parts.
+
+```bash
+pip install depwake
+depwake plan ./my-project              # risk-grouped plan, Markdown/JSON too
+depwake apply ./my-project --dry-run   # preview safe bumps (patch only)
+depwake apply ./my-project             # bump patches, .bak backups, majors never touched
+depwake verify ./my-project --strict   # facts vs assumptions, no network
+```
+
+> ⭐ If dependency hell has ever eaten your weekend, star this — it helps other devs find it.
+
+Advisories included: every plan queries OSV and sorts 🔒 rows first —
+urllib3 1.26 alone carries 20 advisories ([measured](benchmarks/BENCH.md)).
+
+## Before / after
+
+```bash
+$ depwake plan ./my-project
+depwake plan: 4 dep(s) — 1 major, 3 minor, 0 patch, 0 unknown
+  MAJOR   npm  express 4.17.0 -> 5.2.1 [floor]
+  MINOR   npm  lodash 4.17.20 -> 4.18.1 [floor]
+  MINOR   pypi requests 2.28.0 -> 2.34.2
+  MINOR   pypi six 1.16.0 -> 1.17.0
+```
+
+```bash
+$ depwake plan ./my-project --format markdown > UPGRADE.md   # paste into a PR
+$ depwake plan ./my-project --fail-on major                  # CI gate: exit 1 while majors pend
+```
+
+## Why not Dependabot / Renovate?
+
+| | Depwake | Bots |
+|---|---|---|
+| Unit of work | one grouped plan, you decide the order | N noisy PRs, no prioritization |
+| Risk language | patch today / minor this week / major deliberately | version numbers, you interpret |
+| Honesty | range floors labeled `[floor]`; offline → `unknown`, never guessed | — |
+| Scope | works without installs, lockfiles optional but rewarded | needs full install + config |
+| Agent-native | `SKILL.md` your coding agent can run | docs page, if you're lucky |
+
+Dependabot is a fine notifier. Depwake is the Sunday-morning plan *and* the safe pair of hands.
+
+## Supported
+
+`package.json` (+ `package-lock.json` / `npm-shrinkwrap.json`), `requirements.txt`, `pyproject.toml`. Pre-1.0 minors count as major (in 0.x, anything may break). Needs network for latest versions; offline degrades to `unknown`, never to guesses.
+
+## Contributing — built for drive-by PRs
+
+- 📦 New manifest format = one parser + fixtures (`good first issue`)
+- 🔌 New ecosystem (crates.io, RubyGems…) = one fetcher + tests
+- 🌍 Translations welcome (`README.<lang>.md`)
+- Rules: stdlib only, every feature ships with a test, never auto-bump a major
+
+## Roadmap
+
+- [x] v0.1 — plan / apply, 3 manifest formats, Markdown + JSON + CI gate
+- [x] v0.2 — OSV advisories, cache, `--offline`, `verify`, includes/markers/optionals, Action + CI + demo, real-repo validation
+- [x] v0.3 — colors, progress, config file, `-o`, severity filter, JSON counts, apply hints
+- [ ] Advisory reachability (is the vulnerable function even imported?)
+- [ ] `depwake PR` — open the grouped upgrade as draft PRs per risk tier (needs GitHub)
+- [ ] Lockfile generation for lockless projects (`--write-lock`)
+
+## License
+
+MIT — see [LICENSE](LICENSE).

depwake-0.3.1/README.md

@@ -0,0 +1,73 @@
+# Depwake ⏰
+
+[![CI](https://github.com/YOUR-USER/depwake/actions/workflows/ci.yml/badge.svg)](https://github.com/YOUR-USER/depwake/actions/workflows/ci.yml)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/YOUR-USER/depwake/badge)](https://scorecard.dev/viewer/?uri=github.com/YOUR-USER/depwake)
+
+**Wake your sleeping dependencies.**
+
+Your side project has 47 outdated packages, 3 security advisories, and a `package.json` from 2023. Dependabot spams you with 40 context-free PRs. Depwake does the opposite: one risk-grouped plan — patch today, minor this week, major deliberately — and safe auto-bumps for the boring parts.
+
+```bash
+pip install depwake
+depwake plan ./my-project              # risk-grouped plan, Markdown/JSON too
+depwake apply ./my-project --dry-run   # preview safe bumps (patch only)
+depwake apply ./my-project             # bump patches, .bak backups, majors never touched
+depwake verify ./my-project --strict   # facts vs assumptions, no network
+```
+
+> ⭐ If dependency hell has ever eaten your weekend, star this — it helps other devs find it.
+
+Advisories included: every plan queries OSV and sorts 🔒 rows first —
+urllib3 1.26 alone carries 20 advisories ([measured](benchmarks/BENCH.md)).
+
+## Before / after
+
+```bash
+$ depwake plan ./my-project
+depwake plan: 4 dep(s) — 1 major, 3 minor, 0 patch, 0 unknown
+  MAJOR   npm  express 4.17.0 -> 5.2.1 [floor]
+  MINOR   npm  lodash 4.17.20 -> 4.18.1 [floor]
+  MINOR   pypi requests 2.28.0 -> 2.34.2
+  MINOR   pypi six 1.16.0 -> 1.17.0
+```
+
+```bash
+$ depwake plan ./my-project --format markdown > UPGRADE.md   # paste into a PR
+$ depwake plan ./my-project --fail-on major                  # CI gate: exit 1 while majors pend
+```
+
+## Why not Dependabot / Renovate?
+
+| | Depwake | Bots |
+|---|---|---|
+| Unit of work | one grouped plan, you decide the order | N noisy PRs, no prioritization |
+| Risk language | patch today / minor this week / major deliberately | version numbers, you interpret |
+| Honesty | range floors labeled `[floor]`; offline → `unknown`, never guessed | — |
+| Scope | works without installs, lockfiles optional but rewarded | needs full install + config |
+| Agent-native | `SKILL.md` your coding agent can run | docs page, if you're lucky |
+
+Dependabot is a fine notifier. Depwake is the Sunday-morning plan *and* the safe pair of hands.
+
+## Supported
+
+`package.json` (+ `package-lock.json` / `npm-shrinkwrap.json`), `requirements.txt`, `pyproject.toml`. Pre-1.0 minors count as major (in 0.x, anything may break). Needs network for latest versions; offline degrades to `unknown`, never to guesses.
+
+## Contributing — built for drive-by PRs
+
+- 📦 New manifest format = one parser + fixtures (`good first issue`)
+- 🔌 New ecosystem (crates.io, RubyGems…) = one fetcher + tests
+- 🌍 Translations welcome (`README.<lang>.md`)
+- Rules: stdlib only, every feature ships with a test, never auto-bump a major
+
+## Roadmap
+
+- [x] v0.1 — plan / apply, 3 manifest formats, Markdown + JSON + CI gate
+- [x] v0.2 — OSV advisories, cache, `--offline`, `verify`, includes/markers/optionals, Action + CI + demo, real-repo validation
+- [x] v0.3 — colors, progress, config file, `-o`, severity filter, JSON counts, apply hints
+- [ ] Advisory reachability (is the vulnerable function even imported?)
+- [ ] `depwake PR` — open the grouped upgrade as draft PRs per risk tier (needs GitHub)
+- [ ] Lockfile generation for lockless projects (`--write-lock`)
+
+## License
+
+MIT — see [LICENSE](LICENSE).

depwake-0.3.1/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "depwake"
+version = "0.3.1"
+description = "Wake your sleeping dependencies — risk-grouped upgrade plans, safe auto-bumps, no noise"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+keywords = ["dependencies", "upgrades", "npm", "pypi", "maintenance"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.scripts]
+depwake = "depwake.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/YOUR-USER/depwake"
+Issues = "https://github.com/YOUR-USER/depwake/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]

depwake-0.3.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

depwake-0.3.1/src/depwake/__init__.py

@@ -0,0 +1,3 @@
+"""Depwake: wake your sleeping dependencies. Stdlib only."""
+
+__version__ = "0.3.1"

depwake-0.3.1/src/depwake/__main__.py

@@ -0,0 +1,13 @@
+"""Entry point. Works as `python -m depwake` AND as `python path/to/__main__.py`."""
+
+try:
+    from .cli import main
+except ImportError:  # pragma: no cover - path-invoked fallback
+    import os
+    import sys
+
+    sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+    from depwake.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

depwake-0.3.1/src/depwake/apply.py

@@ -0,0 +1,124 @@
+"""Safe auto-bumps: patch (default) and optionally minor. Never major.
+
+Rules, in order:
+1. Only items whose risk is included AND whose current version is exact
+   (lockfile or == pin). Range floors are assumptions — listed, not touched.
+2. package.json: keep the range prefix, replace the version triple
+   (^4.17.0 -> ^4.17.21). requirements/pyproject: only == pins.
+3. Numbered .bak backups, never clobbered. --dry-run changes nothing.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .plan import Plan
+
+TRIPLE = re.compile(r"\d+\.\d+\.\d+[^,\s|]*")
+
+
+@dataclass
+class ApplyResult:
+    changed: list[str] = field(default_factory=list)   # "file: name old -> new"
+    skipped: list[str] = field(default_factory=list)   # "name: reason"
+    backups: list[str] = field(default_factory=list)
+
+
+def _backup(path: Path) -> Path:
+    dest = path.with_suffix(path.suffix + ".bak")
+    i = 1
+    while dest.exists():
+        dest = Path(f"{path}.bak.{i}")
+        i += 1
+    dest.write_bytes(path.read_bytes())
+    return dest
+
+
+def _bump_npm_range(rng: str, latest: str) -> str | None:
+    if not TRIPLE.search(rng):
+        return None
+    return TRIPLE.sub(latest, rng, count=1)
+
+
+def apply_plan(root: str | Path, plan: Plan, include: set[str] | None = None,
+               dry_run: bool = False) -> ApplyResult:
+    include = include or {"patch"}
+    root = Path(root)
+    res = ApplyResult()
+    eligible = [i for i in plan.items
+                if i.risk in include
+                and i.latest
+                and i.dep.current_source in ("lock", "pin")]
+    for item in plan.items:
+        if item not in eligible:
+            if item.risk in ("major",):
+                n = len(item.advisories)
+                extra = f" — ⚠ {n} open advisor{'y' if n == 1 else 'ies'}, plan it soon" if n else ""
+                res.skipped.append(f"{item.dep.name}: major — upgrade deliberately, never auto-bumped{extra}")
+            elif item.risk == "unknown":
+                res.skipped.append(f"{item.dep.name}: unknown version — resolve first ({item.note})")
+            elif item.risk in include:
+                res.skipped.append(f"{item.dep.name}: current is a range floor, not exact — add a lockfile")
+            continue
+    by_file: dict[Path, list] = {}
+    for item in eligible:
+        if item.dep.ecosystem == "npm":
+            by_file.setdefault(root / "package.json", []).append(item)
+        else:
+            req = root / "requirements.txt"
+            proj = root / "pyproject.toml"
+            by_file.setdefault(req if req.exists() else proj, []).append(item)
+    for path, items in by_file.items():
+        if not path.exists():
+            for item in items:
+                res.skipped.append(f"{item.dep.name}: {path.name} not found")
+            continue
+        if not dry_run:
+            res.backups.append(str(_backup(path)))
+        text = path.read_text(encoding="utf-8")
+        for item in items:
+            d = item.dep
+            assert item.latest
+            if path.name == "package.json":
+                data = json.loads(text)
+                done = False
+                for section in ("dependencies", "devDependencies",
+                                "peerDependencies", "optionalDependencies"):
+                    if d.name in (data.get(section) or {}):
+                        new = _bump_npm_range(data[section][d.name], item.latest)
+                        if new and new != data[section][d.name]:
+                            data[section][d.name] = new
+                            res.changed.append(f"{path.name}: {d.name} {d.current} -> {item.latest}")
+                            done = True
+                text = json.dumps(data, indent=2) + "\n"
+                if not done:
+                    res.skipped.append(f"{d.name}: range {d.wanted!r} has no version triple to bump")
+            else:
+                new_text, n = re.subn(
+                    rf"(?m)^(\s*{re.escape(d.name)}\s*==\s*){re.escape(d.current or '')}\s*$",
+                    rf"\g<1>{item.latest}", text, count=1)
+                if n:
+                    text = new_text
+                    res.changed.append(f"{path.name}: {d.name} {d.current} -> {item.latest}")
+                else:
+                    res.skipped.append(f"{d.name}: pin line not found or not ==")
+        if not dry_run:
+            path.write_text(text, encoding="utf-8")
+    return res
+
+
+def format_apply(res: ApplyResult, dry_run: bool = False) -> str:
+    head = "depwake apply (dry run — nothing written):" if dry_run else "depwake apply:"
+    lines = [head]
+    for c in res.changed:
+        lines.append(f"  BUMP {c}")
+    for s in res.skipped:
+        lines.append(f"  SKIP {s}")
+    for b in res.backups:
+        lines.append(f"  backup: {b}")
+    if not res.changed:
+        lines.append("  nothing to bump.")
+    return "\n".join(lines)

depwake-0.3.1/src/depwake/cache.py

@@ -0,0 +1,44 @@
+"""Tiny file cache for registry lookups. Stdlib only.
+
+Same TTL for version + advisory data: staleness here costs a delayed
+upgrade notice, never a wrong one (versions only move forward; advisories
+only accumulate — both refresh within the hour).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+from pathlib import Path
+
+TTL = 3600
+
+
+def cache_dir() -> Path:
+    import os
+    base = os.environ.get("XDG_CACHE_HOME") or str(Path.home() / ".cache")
+    d = Path(base) / "depwake"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def _path(key: str) -> Path:
+    return cache_dir() / (hashlib.sha256(key.encode()).hexdigest() + ".json")
+
+
+def get(key: str, ttl: float = TTL) -> object | None:
+    try:
+        p = _path(key)
+        if not p.exists() or time.time() - p.stat().st_mtime > ttl:
+            return None
+        return json.loads(p.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+
+
+def put(key: str, value: object) -> None:
+    try:
+        _path(key).write_text(json.dumps(value), encoding="utf-8")
+    except OSError:
+        pass  # cache is best-effort; a full disk must never break a plan

depwake-0.3.1/src/depwake/cli.py

@@ -0,0 +1,228 @@
+"""`depwake` CLI. Stdlib only. Exit codes: 0 clean, 1 findings, 2 usage."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import time
+
+from . import __version__
+from .apply import apply_plan, format_apply
+from .cache import get as cache_get
+from .cache import put as cache_put
+from .color import enabled as color_enabled
+from .config import load as load_config
+from .manifests import discover
+from .plan import build
+from .registry import Latest, fetch, fetch_advisories
+from .report import format_json, format_markdown, format_text
+
+RISK_ORDER = {"major": 0, "minor": 1, "patch": 2}
+
+
+def _version_fetcher(args: argparse.Namespace):
+    def go(eco: str, name: str) -> Latest:
+        if args.offline:
+            return Latest(None, "", "offline mode (--offline)")
+        key = f"latest:{eco}:{name}"
+        if not args.no_cache:
+            hit = cache_get(key)
+            if isinstance(hit, dict) and "version" in hit:
+                return Latest(hit.get("version"), hit.get("url", ""), hit.get("error", ""))
+        got = fetch(eco, name, args.timeout)
+        if not args.no_cache:
+            cache_put(key, {"version": got.version, "url": got.url, "error": got.error})
+        return got
+    return go
+
+
+def _advisory_fetcher(args: argparse.Namespace):
+    def go(deps: list[tuple[str, str, str]]):
+        if args.offline or args.no_advisories:
+            return {}
+        out: dict = {}
+        missing = []
+        for eco, name, ver in deps:
+            key = f"osv:{eco}:{name}:{ver}"
+            hit = None if args.no_cache else cache_get(key)
+            if isinstance(hit, list):
+                from .registry import Advisory
+                out[(eco, name)] = [Advisory(**a) for a in hit]
+            else:
+                missing.append((eco, name, ver))
+        if missing:
+            fresh = fetch_advisories(missing, args.timeout)
+            by_key = {(e, n): v for e, n, v in missing}
+            for k, advs in fresh.items():
+                out[k] = advs
+                if not args.no_cache and k in by_key:
+                    cache_put(f"osv:{k[0]}:{k[1]}:{by_key[k]}",
+                              [a.to_dict() for a in advs])
+        return out
+    return go
+
+
+def _shared_flags(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--timeout", type=float, default=10.0, help="Registry timeout (s).")
+    p.add_argument("--no-advisories", action="store_true", help="Skip OSV advisory lookup.")
+    p.add_argument("--no-cache", action="store_true", help="Bypass the registry cache.")
+    p.add_argument("--offline", action="store_true",
+                   help="No network: versions/advisories become unknown with reasons.")
+    p.add_argument("--color", choices=["auto", "always", "never"], default="auto")
+    p.add_argument("--quiet", action="store_true", help="Only the report on stdout.")
+
+
+def _resolve_config(args: argparse.Namespace) -> tuple[list, list, list, str]:
+    """Apply config file: ignore list + fail_on default.
+
+    Returns (deps, notes, ignored_names, fail_on). Ignored deps vanish from
+    counts but always leave a note — silent filtering would be lying by omission.
+    """
+    cfg = load_config(args.root)
+    deps, notes = discover(args.root)
+    ignored = sorted({d.name for d in deps if d.name.lower() in set(cfg.get("ignore", []))})
+    if ignored:
+        deps = [d for d in deps if d.name not in ignored]
+        notes.append(f"ignored {len(ignored)} dep(s) per config: {', '.join(ignored)}")
+    fail_on = args.fail_on if getattr(args, "fail_on", None) else cfg.get("fail_on", "never")
+    return (deps, notes, ignored, fail_on)
+
+
+def _say(args: argparse.Namespace, msg: str) -> None:
+    if not args.quiet:
+        print(f"depwake: {msg}", file=sys.stderr)
+
+
+def cmd_plan(args: argparse.Namespace) -> int:
+    try:
+        deps, notes, _, fail_on = _resolve_config(args)
+    except ValueError as exc:
+        print(f"depwake: error: {exc}", file=sys.stderr)
+        return 2
+    color = color_enabled(args.color)
+    _say(args, f"checking {len(deps)} dep(s)…")
+    t0 = time.time()
+    plan = build(deps, fetcher=_version_fetcher(args), timeout=args.timeout,
+                 advisory_fetcher=_advisory_fetcher(args),
+                 min_severity=args.min_severity)
+    plan.notes.extend(notes)
+    _say(args, f"done in {time.time() - t0:.1f}s")
+    if args.format == "json":
+        rendered = format_json(plan)
+    elif args.format == "markdown":
+        rendered = format_markdown(plan, args.root)
+    else:
+        rendered = format_text(plan, color=color)
+    if args.output:
+        from pathlib import Path
+        Path(args.output).write_text(rendered if rendered.endswith("\n") else rendered + "\n",
+                                     encoding="utf-8")
+        print(f"wrote {args.output}")
+        return 0 if fail_on == "never" else _gate(plan, fail_on)
+    if args.format == "markdown":
+        print(rendered, end="")
+    else:
+        print(rendered)
+    if fail_on == "never":
+        return 0
+    return _gate(plan, fail_on)
+
+
+def _gate(plan, fail_on: str) -> int:
+    threshold = RISK_ORDER[fail_on]
+    bad = [i for i in plan.items if i.risk in RISK_ORDER and RISK_ORDER[i.risk] <= threshold]
+    return 1 if bad else 0
+
+
+def cmd_apply(args: argparse.Namespace) -> int:
+    try:
+        deps, notes, _, _ = _resolve_config(args)
+    except ValueError as exc:
+        print(f"depwake: error: {exc}", file=sys.stderr)
+        return 2
+    _say(args, f"checking {len(deps)} dep(s)…")
+    plan = build(deps, fetcher=_version_fetcher(args),
+                 timeout=args.timeout, advisory_fetcher=_advisory_fetcher(args))
+    include = {"patch"} | ({"minor"} if args.include_minor else set())
+    res = apply_plan(args.root, plan, include=include, dry_run=args.dry_run)
+    print(format_apply(res, dry_run=args.dry_run))
+    if res.changed and not args.dry_run:
+        npm = any(c.startswith("package.json") for c in res.changed)
+        pypi = any(not c.startswith("package.json") for c in res.changed)
+        hints = []
+        if npm:
+            hints.append("npm install  (refresh the lockfile)")
+        if pypi:
+            hints.append("pip install -r requirements.txt  (or reinstall your project)")
+        hints.append("re-run depwake plan to confirm")
+        print("  next: " + " → ".join(hints))
+    return 0
+
+
+def cmd_verify(args: argparse.Namespace) -> int:
+    """How much of this project is exactly known? Facts (lock/pin) vs
+    assumptions (range floors) vs blind spots (unknown). No network."""
+    try:
+        deps, notes = discover(args.root)
+    except ValueError as exc:
+        print(f"depwake: error: {exc}", file=sys.stderr)
+        return 2
+    exact = [d for d in deps if d.current_source in ("lock", "pin")]
+    floors = [d for d in deps if d.current_source == "floor"]
+    unknown = [d for d in deps if d.current_source == "unknown"]
+    lines = [f"depwake verify: {len(exact)}/{len(deps)} exact, "
+             f"{len(floors)} range-floor assumptions, {len(unknown)} unknown"]
+    for d in floors:
+        lines.append(f"  FLOOR   {d.ecosystem:4} {d.name} {d.wanted} (add a lockfile)")
+    for d in unknown:
+        lines.append(f"  UNKNOWN {d.ecosystem:4} {d.name} {d.wanted}")
+    for note in notes:
+        lines.append(f"  note: {note}")
+    print("\n".join(lines))
+    if args.strict and (floors or unknown):
+        return 1
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="depwake",
+        description="Wake your sleeping dependencies — risk-grouped plans, safe auto-bumps.",
+    )
+    p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    pl = sub.add_parser("plan", help="Risk-grouped upgrade plan (patch/minor/major/unknown).")
+    pl.add_argument("root", nargs="?", default=".", help="Project directory.")
+    pl.add_argument("--format", choices=["text", "markdown", "json"], default="text")
+    _shared_flags(pl)
+    pl.add_argument("--fail-on", choices=["major", "minor", "patch", "never"], default=None,
+                    help="Exit 1 if upgrades at/above this risk are pending "
+                         "(default: config fail_on, else never).")
+    pl.add_argument("-o", "--output", default=None, help="Write report to file instead of stdout.")
+    pl.add_argument("--min-severity", choices=["Critical", "High", "Medium", "Low"], default=None,
+                    help="Only attach advisories at/above this severity (Unscored always shown).")
+    pl.set_defaults(func=cmd_plan)
+
+    ap = sub.add_parser("apply", help="Auto-bump patch (and optionally minor). Never major.")
+    ap.add_argument("root", nargs="?", default=".")
+    _shared_flags(ap)
+    ap.add_argument("--include-minor", action="store_true", help="Also bump minor upgrades.")
+    ap.add_argument("--dry-run", action="store_true", help="Show what would change.")
+    ap.set_defaults(func=cmd_apply)
+
+    vf = sub.add_parser("verify", help="Facts vs assumptions: lock/pin coverage, no network.")
+    vf.add_argument("root", nargs="?", default=".")
+    vf.add_argument("--strict", action="store_true",
+                    help="Exit 1 unless every dep is exactly known.")
+    vf.set_defaults(func=cmd_verify)
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    return int(args.func(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())