wellspin 0.1.0__tar.gz

wellspin-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+node_modules/
+test/.fixtures/
+*.tgz
+.DS_Store

wellspin-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wellspin LLC, Yevhen Reuka and Dmytro Kazarov
+
+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.

wellspin-0.1.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.5
+Name: wellspin
+Version: 0.1.0
+Summary: Prints https://cal.com/wellspin/30min?layout=mobile and opens it in your default browser.
+Author: Wellspin LLC
+Maintainer: Yevhen Reuka, Dmytro Kazarov
+License: MIT License
+        
+        Copyright (c) 2026 Wellspin LLC, Yevhen Reuka and Dmytro Kazarov
+        
+        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.
+License-File: LICENSE
+Keywords: browser,cli,link,open
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# wellspin
+
+Prints a link and opens it in your default browser. That is the whole program.
+
+    uvx wellspin
+
+It writes the URL to stdout and asks the operating system to open it. Whether
+the page then loads is between your browser and the network — this command
+cannot see that and does not claim it.
+
+## The link
+
+    https://cal.com/wellspin/30min?layout=mobile
+
+## Options
+
+| Command | What it does |
+| --- | --- |
+| `uvx wellspin` | print the URL and open it |
+| `uvx wellspin --url` | print the URL only, open nothing |
+| `uvx wellspin --help` | usage |
+| `uvx wellspin --version` | the version of this package |
+
+`pipx run wellspin` behaves the same way, and `pip install wellspin`
+puts `wellspin` on your PATH if you would rather keep it.
+
+In CI the URL is printed and no browser is launched.
+
+## Getting the current link
+
+The URL is baked in when the package is published, so a copy already on your
+machine keeps whatever link it shipped with. To be sure you have the newest:
+
+    uvx wellspin@latest
+
+A changed link means a new version of this package.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | the URL was printed — including when the browser could not be launched |
+| 1 | this package has no usable URL configured |
+| 2 | bad arguments |
+
+## Dependencies
+
+None. `webbrowser` is part of the Python standard library.
+
+## Licence
+
+MIT.

wellspin-0.1.0/README.md

@@ -0,0 +1,52 @@
+# wellspin
+
+Prints a link and opens it in your default browser. That is the whole program.
+
+    uvx wellspin
+
+It writes the URL to stdout and asks the operating system to open it. Whether
+the page then loads is between your browser and the network — this command
+cannot see that and does not claim it.
+
+## The link
+
+    https://cal.com/wellspin/30min?layout=mobile
+
+## Options
+
+| Command | What it does |
+| --- | --- |
+| `uvx wellspin` | print the URL and open it |
+| `uvx wellspin --url` | print the URL only, open nothing |
+| `uvx wellspin --help` | usage |
+| `uvx wellspin --version` | the version of this package |
+
+`pipx run wellspin` behaves the same way, and `pip install wellspin`
+puts `wellspin` on your PATH if you would rather keep it.
+
+In CI the URL is printed and no browser is launched.
+
+## Getting the current link
+
+The URL is baked in when the package is published, so a copy already on your
+machine keeps whatever link it shipped with. To be sure you have the newest:
+
+    uvx wellspin@latest
+
+A changed link means a new version of this package.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | the URL was printed — including when the browser could not be launched |
+| 1 | this package has no usable URL configured |
+| 2 | bad arguments |
+
+## Dependencies
+
+None. `webbrowser` is part of the Python standard library.
+
+## Licence
+
+MIT.

wellspin-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "wellspin"
+version = "0.1.0"
+description = "Prints https://cal.com/wellspin/30min?layout=mobile and opens it in your default browser."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { file = "LICENSE" }
+keywords = ["cli", "open", "browser", "link"]
+authors = [{ name = "Wellspin LLC" }]
+maintainers = [{ name = "Yevhen Reuka" }, { name = "Dmytro Kazarov" }]
+classifiers = [
+  "Environment :: Console",
+  "Intended Audience :: End Users/Desktop",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Utilities",
+]
+dependencies = []
+
+[project.scripts]
+wellspin = "wellspin:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["wellspin"]
+
+[tool.hatch.build.targets.sdist]
+include = ["wellspin", "README.md", "LICENSE"]

wellspin-0.1.0/wellspin/__init__.py

@@ -0,0 +1,27 @@
+"""wellspin — print a link and open it in your default browser."""
+
+from importlib.metadata import PackageNotFoundError, version as _version
+
+from ._cli import main as _main
+
+NAME = "wellspin"
+URL = "https://cal.com/wellspin/30min?layout=mobile"
+
+
+def _installed_version() -> str:
+    try:
+        return _version(NAME)
+    except PackageNotFoundError:  # running from a checkout rather than an install
+        return "0+unknown"
+
+
+def main() -> int:
+    """Console entry point. Returns the exit code."""
+    return _main(NAME, URL, _installed_version())
+
+
+def _console() -> None:
+    raise SystemExit(main())
+
+
+__all__ = ["NAME", "URL", "main"]

wellspin-0.1.0/wellspin/_cli.py

@@ -0,0 +1,214 @@
+"""Shared behaviour for every one of these commands.
+
+A deliberate mirror of src/run.js — same flags, same exit codes, same refusal
+to claim more than it knows. Kept free of I/O so the tests can drive it without
+opening tabs, and copied verbatim into each published package.
+
+Nothing outside the standard library is used: webbrowser ships with Python, so
+these packages have no dependencies at all.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import webbrowser
+from typing import Callable, Iterable, Optional, Sequence, Tuple
+from urllib.parse import urlsplit
+
+EXIT_OK = 0
+EXIT_CONFIG = 1
+EXIT_USAGE = 2
+
+# Values that mean "nobody filled this in yet". Rejected rather than quietly
+# replaced with some default page.
+_PLACEHOLDERS = {
+    "none",
+    "null",
+    "tbd",
+    "todo",
+    "placeholder",
+    "changeme",
+    "change-me",
+    "replaceme",
+    "replace-me",
+    "http://",
+    "https://",
+}
+
+_CI_SIGNALS = (
+    "CI",
+    "CONTINUOUS_INTEGRATION",
+    "GITHUB_ACTIONS",
+    "GITLAB_CI",
+    "CIRCLECI",
+    "TRAVIS",
+    "BUILDKITE",
+    "DRONE",
+    "APPVEYOR",
+    "TEAMCITY_VERSION",
+    "TF_BUILD",
+    "JENKINS_URL",
+    "CODEBUILD_BUILD_ID",
+    "NETLIFY",
+    "VERCEL",
+)
+
+_KNOWN_FLAGS = ("--help", "--version", "--url")
+
+
+def detect_ci(env) -> Optional[str]:
+    """Name the variable that identified a CI runner, or None.
+
+    CI=false and CI=0 count as "not CI" — some shells export it blank.
+    """
+    for key in _CI_SIGNALS:
+        value = env.get(key)
+        if value is None:
+            continue
+        text = str(value).strip().lower()
+        if text in ("", "false", "0"):
+            continue
+        return key
+    return None
+
+
+def read_url(raw) -> Tuple[bool, str]:
+    """Check a configured URL without rewriting it.
+
+    Returns (ok, url_or_reason). The URL comes back trimmed but otherwise
+    exactly as configured, so path, query and fragment survive untouched.
+    """
+    if raw is None:
+        return False, "no URL is configured for this package"
+    if not isinstance(raw, str):
+        return False, "URL must be a string, got %s" % type(raw).__name__
+
+    url = raw.strip()
+    if not url:
+        return False, "the configured URL is empty"
+    if url.lower() in _PLACEHOLDERS or "<" in url or ">" in url:
+        return False, "the configured URL is still a placeholder: %s" % url
+
+    # urlsplit rather than a hand-rolled pattern: an earlier regex here left
+    # "@" out of the host class, so a link carrying credentials fell through to
+    # the generic "not a valid URL" message instead of the specific one. The
+    # standard parser knows the grammar; matching it by hand does not.
+    try:
+        parts = urlsplit(url)
+    except ValueError as error:
+        return False, "the configured URL is not a valid URL: %s (%s)" % (url, error)
+
+    if parts.scheme != "https":
+        return False, "the URL must use https: %s" % url
+    try:
+        if parts.username or parts.password:
+            return False, "the URL must not carry credentials"
+        host = parts.hostname
+    except ValueError as error:
+        return False, "the configured URL is not a valid URL: %s (%s)" % (url, error)
+
+    if not host:
+        return False, "the URL has no host: %s" % url
+
+    return True, url
+
+
+def help_text(name: str) -> str:
+    return "\n".join(
+        (
+            "%s — print a link and open it in your default browser." % name,
+            "",
+            "Usage",
+            "  uvx %s            print the URL and open it" % name,
+            "  uvx %s --url      print the URL only" % name,
+            "  uvx %s --help     show this help" % name,
+            "  uvx %s --version  show the version of this package" % name,
+            "",
+            "pipx run %s works the same way." % name,
+            "",
+            "The URL is fixed when the package is published. To be sure you have the",
+            "newest one, ask for it explicitly: uvx %s@latest" % name,
+        )
+    )
+
+
+def run(
+    argv: Sequence[str],
+    name: str,
+    version: str,
+    url,
+    open_url: Callable[[str], bool],
+    stdout: Callable[[str], None],
+    stderr: Callable[[str], None],
+    env,
+) -> int:
+    """The whole program. Returns the process exit code."""
+    unknown: Iterable[str] = [a for a in argv if a not in _KNOWN_FLAGS]
+    unknown = list(unknown)
+    if unknown:
+        stderr("%s: unknown argument: %s\nTry: %s --help\n" % (name, unknown[0], name))
+        return EXIT_USAGE
+
+    # One thing at a time: --url --version has no single sensible answer.
+    flags = list(dict.fromkeys(argv))
+    if len(flags) > 1:
+        stderr("%s: use one option at a time, got %s\nTry: %s --help\n" % (name, " ".join(flags), name))
+        return EXIT_USAGE
+
+    flag = flags[0] if flags else None
+
+    # Both answer before the URL is looked at, so they still work on a package
+    # whose link has not been filled in yet.
+    if flag == "--help":
+        stdout(help_text(name) + "\n")
+        return EXIT_OK
+    if flag == "--version":
+        stdout("%s\n" % version)
+        return EXIT_OK
+
+    ok, value = read_url(url)
+    if not ok:
+        stderr("%s: %s\n" % (name, value))
+        return EXIT_CONFIG
+
+    if flag == "--url":
+        stdout("%s\n" % value)
+        return EXIT_OK
+
+    # The link reaches the user first, so it is theirs whatever happens next.
+    stdout("%s\n" % value)
+
+    ci = detect_ci(env)
+    if ci:
+        stderr("%s: %s is set, not opening a browser.\n" % (name, ci))
+        return EXIT_OK
+
+    try:
+        launched = open_url(value)
+    except Exception as error:  # noqa: BLE001 - any failure is the same to us
+        launched = False
+        detail = str(error) or error.__class__.__name__
+        stderr("%s: could not launch a browser (%s). Open the URL above yourself.\n" % (name, detail))
+    else:
+        if not launched:
+            stderr("%s: could not launch a browser. Open the URL above yourself.\n" % name)
+
+    # Handing over the link is the job. Whether the page then loaded is not
+    # something this process can observe, so it is not claimed either way.
+    return EXIT_OK
+
+
+def main(name: str, url, version: str) -> int:
+    return run(
+        argv=sys.argv[1:],
+        name=name,
+        version=version,
+        url=url,
+        # webbrowser builds the platform command itself and never goes through
+        # a shell, so a link carrying quotes or semicolons stays a link.
+        open_url=lambda target: webbrowser.open(target, new=2),
+        stdout=sys.stdout.write,
+        stderr=sys.stderr.write,
+        env=os.environ,
+    )