stml-cli 0.1.0__py3-none-any.whl

stml_cli/__init__.py

@@ -0,0 +1,22 @@
+"""stml — the partner CLI (024 §Distributing the partner CLI).
+
+Pure-Python, stdlib only. ``certifi`` is the sole packaging dependency, used to
+point OpenSSL at a CA bundle so HTTPS to a real backend verifies on framework
+Python builds that ship no CA store (same fix as the monorepo publish scripts).
+"""
+
+from __future__ import annotations
+
+import os
+
+__version__ = "0.1.0"
+
+# TLS trust: framework/python.org builds have no OpenSSL CA path, so a real
+# https backend fails with "unable to get local issuer certificate". certifi's
+# bundle fixes it. setdefault honours an operator override; no-op for http.
+try:  # pragma: no cover - environment dependent
+    import certifi
+
+    os.environ.setdefault("SSL_CERT_FILE", certifi.where())
+except ImportError:  # pragma: no cover
+    pass

stml_cli/__main__.py

@@ -0,0 +1,153 @@
+"""`stml` CLI entry point — argparse dispatch (024 §CLI surface).
+
+    stml login | logout | whoami
+    stml list [--workspace <ws>]
+    stml pull <app-url> [<dir>]
+    stml push [<app-url>] <dir>
+    stml detach <app-url>            (fork: own the full source)
+    stml revert <app-url> [--yes]    (reset: back to the clean library)
+    stml status <app-url>
+    stml publish <dir> [--org <slug>]
+    stml init <dir> [--name <name>]
+
+Auth: STML4_TOKEN overrides everything; otherwise the cached `stml login`
+session is used (and silently refreshed). Backend: --backend or $STML4_BACKEND.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__, commands, http
+from .config import DEFAULT_BACKEND
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="stml", description="The stml partner CLI.")
+    p.add_argument("--version", action="version", version=f"stml {__version__}")
+    p.add_argument("--backend", default=DEFAULT_BACKEND, help=f"Backend URL (default: {DEFAULT_BACKEND})")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    sub.add_parser("login", help="Authenticate in the browser and cache a session").set_defaults(func=commands.cmd_login)
+    sub.add_parser("logout", help="Delete the cached session").set_defaults(func=commands.cmd_logout)
+    sub.add_parser("whoami", help="Show the resolved user + backend").set_defaults(func=commands.cmd_whoami)
+
+    ls = sub.add_parser(
+        "list",
+        help="List apps you can access (name + pull handle)",
+        description="List apps you can access, with the exact `stml pull` handle for each.",
+    )
+    ls.add_argument("--workspace", metavar="<workspace>", help="Filter to one workspace (slug or name)")
+    ls.set_defaults(func=commands.cmd_list)
+
+    # pull / push (an app's source)
+    pull = sub.add_parser(
+        "pull",
+        help="Pull an app's source to a local folder",
+        description="Pull an app's source to a local folder.",
+        epilog=(
+            "Identify the app by its URL — copy it from `stml list` or straight from\n"
+            "the browser. A trailing /flows/…, /sessions/… or /settings is ignored, so\n"
+            "the URL of a flow or a run resolves to its app just fine.\n\n"
+            "examples:\n"
+            "  stml pull https://app.stml.io/orgs/acme/ws/main/apps/invoice-sync-a1b2\n"
+            "  stml pull https://app.stml.io/orgs/acme/ws/main/apps/invoice-sync-a1b2/flows/x ./work\n"
+            "  stml pull invoice-sync-a1b2                 # a bare slug also works"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    pull.add_argument("app", metavar="<app-url>", help="App URL (from `stml list` or the browser); a bare slug also works")
+    pull.add_argument("dir", nargs="?", metavar="<dir>", help="Target folder (default: ./<app-slug>)")
+    pull.set_defaults(func=commands.cmd_pull)
+
+    push = sub.add_parser(
+        "push",
+        help="Push a local folder into the app overlay and deploy",
+        description="Push a local folder into the app's overlay and deploy it.",
+        epilog=(
+            "The <app-url> is optional when pushing a folder created by `stml pull`\n"
+            "(it remembers the app in .stml/app.json).\n\n"
+            "examples:\n"
+            "  stml push ./invoice-sync                                              # remembered from pull\n"
+            "  stml push https://app.stml.io/orgs/acme/ws/main/apps/invoice-sync-a1b2 ./invoice-sync\n"
+            "  stml push ./invoice-sync --no-deploy"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    push.add_argument("app", nargs="?", metavar="<app-url>", help="App URL to push to (optional for a pulled folder)")
+    push.add_argument("dir", metavar="<dir>", help="Source folder to push")
+    push.add_argument("--no-deploy", action="store_true", help="Write the overlay without deploying")
+    push.add_argument("--prune", action="store_true", help="Delete overlay paths absent from the folder")
+    push.set_defaults(func=commands.cmd_push)
+
+    # detach / revert / status (story 035 — the app's attachment lifecycle)
+    detach = sub.add_parser(
+        "detach",
+        help="Fork an installed app: full source into the overlay, library pin cleared",
+        description=(
+            "Fork an installed app into a self-contained one. The full effective source "
+            "(base library + your overlay) is materialised into the app's overlay and the "
+            "library pin is cleared — after this, `stml pull` returns the whole tree and "
+            "`stml publish` can ship it as your own standalone library. The app stops "
+            "receiving library updates. Non-destructive; `stml revert` undoes it."
+        ),
+    )
+    detach.add_argument("app", metavar="<app-url>", help="App URL (from `stml list`); a bare slug also works")
+    detach.set_defaults(func=commands.cmd_detach)
+
+    revert = sub.add_parser(
+        "revert",
+        help="DESTRUCTIVE: discard all customisations, restore the clean library version",
+        description=(
+            "Permanently delete every overlay customisation (code AND page edits) and restore "
+            "the app to its clean library version. A detached app is re-attached to the exact "
+            "version it was forked from. Connections, configurations, triggers and run history "
+            "are preserved. THERE IS NO UNDO."
+        ),
+    )
+    revert.add_argument("app", metavar="<app-url>", help="App URL (from `stml list`); a bare slug also works")
+    revert.add_argument("--yes", action="store_true", help="Skip the interactive confirmation")
+    revert.set_defaults(func=commands.cmd_revert)
+
+    status = sub.add_parser(
+        "status",
+        help="Show an app's mode (attached / detached / scratch) and provenance",
+    )
+    status.add_argument("app", metavar="<app-url>", help="App URL (from `stml list`); a bare slug also works")
+    status.set_defaults(func=commands.cmd_status)
+
+    # publish / init (library)
+    publish = sub.add_parser("publish", help="Publish a library version from a local folder")
+    publish.add_argument("dir")
+    publish.add_argument("--org", help="Issuer org slug (overrides [tool.stml].issuer-org)")
+    publish.set_defaults(func=commands.cmd_publish)
+
+    init = sub.add_parser("init", help="Scaffold a new library directory")
+    init.add_argument("dir")
+    init.add_argument("--name")
+    init.set_defaults(func=commands.cmd_init)
+
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        args.func(args)
+    except http.HttpError as e:
+        # An unhandled server/transport error (handled ones — e.g. a 409 the
+        # pull picker catches — never reach here). Print the clean detail.
+        print(f"✗ {e.detail}", file=sys.stderr)
+        return 1
+    except SystemExit as e:
+        # SystemExit carries our user-facing error strings; print and exit non-zero.
+        if isinstance(e.code, str):
+            print(e.code, file=sys.stderr)
+            return 1
+        return e.code or 0
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

stml_cli/commands.py

@@ -0,0 +1,322 @@
+"""Subcommand handlers for the `stml` CLI."""
+
+from __future__ import annotations
+
+import sys
+import time
+import tomllib
+import urllib.parse
+from datetime import datetime
+from pathlib import Path
+
+from . import config, http, oauth, paths
+from .packaging import build_tarball
+from .refs import parse_app_ref
+
+
+def _log(msg: str) -> None:
+    print(msg, file=sys.stderr)
+
+
+def _humanize_delta(seconds: float) -> str:
+    """A compact largest-unit relative span, e.g. '42m', '3h', '2d', '15s'."""
+    seconds = int(abs(seconds))
+    for size, unit in ((86400, "d"), (3600, "h"), (60, "m")):
+        if seconds >= size:
+            return f"{seconds // size}{unit}"
+    return f"{seconds}s"
+
+
+def _format_expiry(exp: int, now: float | None = None) -> str:
+    """Render a JWT ``exp`` (epoch seconds) as local time + relative span."""
+    now = time.time() if now is None else now
+    local = datetime.fromtimestamp(exp).strftime("%Y-%m-%d %H:%M:%S")
+    delta = exp - now
+    if delta >= 0:
+        return f"{local} (expires in {_humanize_delta(delta)})"
+    return f"{local} (EXPIRED {_humanize_delta(delta)} ago)"
+
+
+# ── auth ────────────────────────────────────────────────────────────────────
+
+def cmd_login(args) -> None:
+    sess = oauth.login(args.backend)
+    claims = http.token_claims(sess["access_token"])
+    who = claims.get("email") or claims.get("sub") or "?"
+    _log(f"✓ Logged in to {args.backend} as {who}")
+
+
+def cmd_logout(args) -> None:
+    _log("✓ Logged out" if config.clear_session() else "Not logged in.")
+
+
+def cmd_whoami(args) -> None:
+    token = http.resolve_token(args.backend)
+    claims = http.token_claims(token)
+    _log(f"backend: {args.backend}")
+    _log(f"user:    {claims.get('email') or claims.get('sub') or '?'}")
+    if claims.get("exp"):
+        _log(f"token:   {_format_expiry(int(claims['exp']))}")
+
+
+# ── discovery ───────────────────────────────────────────────────────────────
+
+def cmd_list(args) -> None:
+    token = http.resolve_token(args.backend)
+    url = f"{args.backend}/api/apps"
+    if args.workspace:
+        url += "?" + urllib.parse.urlencode({"workspace": args.workspace})
+    apps = http.get_json(url, token).get("apps") or []
+    if not apps:
+        _log("No apps found.")
+        return
+    # Display name + mode (035: attached/detached/scratch) + the app URL — the
+    # exact handle `stml pull`/`push` accept (the URL's app slug is unique, so
+    # it never collides even when a library is installed twice). Rows to stdout
+    # so `stml list | grep …` works; header to stderr.
+    name_w = max(len(a.get("name") or "") for a in apps)
+    mode_w = max((len(a.get("mode") or "") for a in apps), default=4)
+    _log(f"{'APP'.ljust(name_w)}  {'MODE'.ljust(mode_w)}  URL")
+    for a in apps:
+        print(
+            f"{(a.get('name') or '').ljust(name_w)}  "
+            f"{(a.get('mode') or '').ljust(mode_w)}  {a.get('url') or ''}"
+        )
+
+
+# ── app source: pull / push ─────────────────────────────────────────────────
+
+def _pick_by_slug(e: http.HttpError, workspace: str | None, app: str) -> None:
+    """Turn a 409 'matches multiple apps' into a slug picker; re-raise else."""
+    if e.code != 409:
+        raise SystemExit(e.detail)
+    marker = "exact slug:"
+    slugs = (
+        [s.strip() for s in e.detail.split(marker, 1)[1].split(",") if s.strip()]
+        if marker in e.detail else []
+    )
+    prefix = f"{workspace}/" if workspace else ""
+    lines = [f"'{app}' matches multiple apps — pick one by slug:"]
+    lines += [f"    stml pull {prefix}{s}" for s in slugs]
+    if not slugs:
+        lines.append("    run `stml list` to see the slugs")
+    raise SystemExit("\n".join(lines))
+
+
+def cmd_pull(args) -> None:
+    workspace, app = parse_app_ref(args.app)
+    token = http.resolve_token(args.backend)
+
+    query = {"app": app}
+    if workspace:
+        query["workspace"] = workspace
+    url = f"{args.backend}/api/app-source?" + urllib.parse.urlencode(query)
+    try:
+        result = http.get_json(url, token)
+    except http.HttpError as e:
+        _pick_by_slug(e, workspace, app)
+    files = result.get("files") or []
+
+    dest = Path(args.dir).resolve() if args.dir else Path.cwd() / app
+    dest.mkdir(parents=True, exist_ok=True)
+    written = paths.write_tree(dest, files)
+
+    # Record the source coordinate so a later push can be run from the folder.
+    _write_link(dest, args.backend, workspace, app)
+    _log(f"✓ Pulled {len(written)} file(s) from {result.get('app', app)} → {dest}")
+
+
+def cmd_push(args) -> None:
+    src = Path(args.dir).resolve()
+    if not src.is_dir():
+        raise SystemExit(f"{src} is not a directory")
+
+    link = _read_link(src)
+    if args.app:
+        workspace, app = parse_app_ref(args.app)
+    elif link:
+        workspace, app = link.get("workspace"), link["app"]
+    else:
+        raise SystemExit("Pass an app URL (or push a folder created by `stml pull`).")
+
+    files = paths.read_tree(src)
+    if not files:
+        raise SystemExit(f"No source files found under {src}")
+
+    token = http.resolve_token(args.backend)
+    body = {
+        "app": app,
+        "workspace": workspace,
+        "files": files,
+        "deploy": not args.no_deploy,
+        "prune": args.prune,
+    }
+    try:
+        result = http.post_json(f"{args.backend}/api/app-source", body, token)
+    except http.HttpError as e:
+        _pick_by_slug(e, workspace, app)
+    verb = "pushed" if args.no_deploy else "pushed + deployed"
+    _log(f"✓ {verb} {len(files)} file(s) to {app} (written={result.get('written', '?')})")
+
+
+# ── detach / revert (story 035) ─────────────────────────────────────────────
+
+def _detach_revert_url(backend: str, ref: str, action: str) -> str:
+    """The action endpoint for an app reference. The backend accepts a slug or
+    a display name in the path; URL-style refs are reduced to their slug via
+    the same parser pull/push use."""
+    _workspace, app = parse_app_ref(ref)
+    return f"{backend}/api/apps/{urllib.parse.quote(app, safe='')}/{action}"
+
+
+def cmd_detach(args) -> None:
+    token = http.resolve_token(args.backend)
+    result = http.post_json(_detach_revert_url(args.backend, args.app, "detach"), {}, token)
+    if result.get("status") == "noop":
+        _log(result.get("message") or "Nothing to do.")
+        return
+    _log(f"✓ Detached from {result.get('detached_from', '?')} — "
+         f"{result.get('files_materialized', '?')} file(s) materialised; the app is self-contained.")
+    for path in result.get("skipped_binary") or []:
+        _log(f"  ⚠ skipped binary file: {path}")
+    if result.get("deploy_error"):
+        _log(f"  ⚠ deploy failed (detach itself succeeded): {result['deploy_error']}")
+    _log("  `stml pull` now returns the full tree; `stml revert` undoes this.")
+
+
+def cmd_revert(args) -> None:
+    token = http.resolve_token(args.backend)
+    if not args.yes:
+        _log("This PERMANENTLY deletes every customisation of this app (code and page "
+             "edits) and restores the clean library version. There is no undo.")
+        _log("Connections, configurations, triggers and run history are preserved.")
+        answer = input("Type the word revert to continue: ").strip().lower()
+        if answer != "revert":
+            raise SystemExit("Aborted — nothing changed.")
+    result = http.post_json(_detach_revert_url(args.backend, args.app, "revert"), {}, token)
+    if result.get("status") == "noop":
+        _log(result.get("message") or "Nothing to do.")
+        return
+    _log(f"✓ Reverted to {result.get('restored_version', '?')} — "
+         f"{result.get('overlay_files_removed', '?')} overlay file(s) removed.")
+    for f in result.get("removed_flows") or []:
+        _log(f"  ⚠ removed flow whose source left with the overlay: {f.get('name')}")
+    if result.get("version_yanked"):
+        _log("  ⚠ the restored version is yanked — a newer version exists (App Store → Update).")
+    if result.get("deploy_error"):
+        _log(f"  ⚠ deploy failed (revert itself succeeded): {result['deploy_error']}")
+
+
+def cmd_status(args) -> None:
+    """Mode + provenance for one app, resolved via `stml list`'s endpoint."""
+    token = http.resolve_token(args.backend)
+    _workspace, app = parse_app_ref(args.app)
+    apps = http.get_json(f"{args.backend}/api/apps", token).get("apps") or []
+    row = next((a for a in apps if a.get("slug") == app or a.get("name") == app), None)
+    if row is None:
+        raise SystemExit(f"App {app!r} not found (see `stml list`).")
+    _log(f"app:   {row.get('name')} ({row.get('slug')})")
+    _log(f"mode:  {row.get('mode')}")
+    _log(f"url:   {row.get('url')}")
+
+
+# ── publish / init (library, ported from stml_lib.py) ───────────────────────
+
+def cmd_publish(args) -> None:
+    lib_dir = Path(args.dir).resolve()
+    manifest_path = lib_dir / "pyproject.toml"
+    if not manifest_path.exists():
+        raise SystemExit(f"{manifest_path} not found")
+    manifest = tomllib.loads(manifest_path.read_text(encoding="utf-8"))
+    project = manifest.get("project") or {}
+    name, version = project.get("name"), project.get("version")
+    if not name or not version:
+        raise SystemExit("pyproject.toml missing project.name or project.version")
+
+    stml_cfg = (manifest.get("tool") or {}).get("stml") or {}
+    org_slug = args.org or stml_cfg.get("issuer-org")
+    if not org_slug:
+        raise SystemExit("Pass --org or set [tool.stml].issuer-org in pyproject.toml")
+
+    token = http.resolve_token(args.backend)
+
+    # Ensure the library exists (409 = already there, which is fine).
+    try:
+        http.post_json(f"{args.backend}/api/libraries", {"org_slug": org_slug, "name": name}, token)
+        _log(f"Created library {org_slug}/{name}")
+    except http.HttpError as e:
+        if e.code == 409 or "already exists" in (e.detail or ""):
+            _log(f"Library {org_slug}/{name} exists — uploading new version")
+        else:
+            raise SystemExit(e.detail)
+
+    tarball = build_tarball(lib_dir)
+    _log(f"Built tarball: {len(tarball)} bytes")
+    result = http.post_multipart(
+        f"{args.backend}/api/libraries/{org_slug}/{name}/versions",
+        fields={"expected_version": version},
+        file_field="tarball",
+        filename=f"{name}-{version}.tar.gz",
+        file_bytes=tarball,
+        token=token,
+    )
+    sha = (result.get("tarball_sha256") or "")[:12]
+    size_kb = (result.get("size_bytes") or 0) / 1024
+    _log(f"✓ Published {org_slug}/{name}@{version} ({size_kb:.1f} KB, sha={sha}…)")
+
+
+def cmd_init(args) -> None:
+    target = Path(args.dir).resolve()
+    if target.exists() and any(target.iterdir()):
+        raise SystemExit(f"{target} exists and is not empty")
+    target.mkdir(parents=True, exist_ok=True)
+    name = args.name or target.name
+    (target / "pyproject.toml").write_text(
+        f'''[project]
+name = "{name}"
+version = "0.1.0"
+description = "A reusable stml library."
+requires-python = ">=3.11"
+dependencies = []
+
+[tool.stml]
+requires-runtime = ">=0.1"
+issuer-org = ""  # set to your org slug
+exports-flows = []
+depends-on = []
+''',
+        encoding="utf-8",
+    )
+    pkg = target / name.replace("-", "_")
+    pkg.mkdir()
+    (pkg / "__init__.py").write_text('"""Library entry point."""\n', encoding="utf-8")
+    (target / "README.md").write_text(f"# {name}\n", encoding="utf-8")
+    _log(f"✓ Scaffolded {target}")
+
+
+# ── pull/push folder link (.stml/app.json) ──────────────────────────────────
+
+_LINK = Path(".stml") / "app.json"
+
+
+def _write_link(dest: Path, backend: str, workspace: str | None, app: str) -> None:
+    import json
+
+    link_path = dest / _LINK
+    link_path.parent.mkdir(parents=True, exist_ok=True)
+    link_path.write_text(
+        json.dumps({"backend": backend, "workspace": workspace, "app": app}, indent=2),
+        encoding="utf-8",
+    )
+
+
+def _read_link(src: Path) -> dict | None:
+    import json
+
+    p = src / _LINK
+    if not p.exists():
+        return None
+    try:
+        return json.loads(p.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return None

stml_cli/config.py

@@ -0,0 +1,64 @@
+"""Per-OS config dir + the cached login session (024 §OS & runtime support §4).
+
+The refresh token lives here between commands; access tokens are minted per
+call and never persisted. The file is written user-only where the OS supports
+it (``chmod`` is a no-op on Windows, which relies on the per-user profile dir).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+DEFAULT_BACKEND = os.environ.get("STML4_BACKEND", "http://localhost:8010")
+
+_SESSION_FILE = "session.json"
+
+
+def config_dir() -> Path:
+    """OS-appropriate config directory for stml (created on demand)."""
+    if sys.platform == "darwin":
+        base = Path.home() / "Library" / "Application Support"
+    elif os.name == "nt":
+        base = Path(os.environ.get("APPDATA") or (Path.home() / "AppData" / "Roaming"))
+    else:  # Linux / other POSIX
+        base = Path(os.environ.get("XDG_CONFIG_HOME") or (Path.home() / ".config"))
+    return base / "stml"
+
+
+def _session_path() -> Path:
+    return config_dir() / _SESSION_FILE
+
+
+def read_session() -> dict | None:
+    """Return the cached session dict, or None if not logged in."""
+    p = _session_path()
+    if not p.exists():
+        return None
+    try:
+        return json.loads(p.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
+def write_session(session: dict) -> None:
+    """Persist the session dict with user-only perms where supported."""
+    d = config_dir()
+    d.mkdir(parents=True, exist_ok=True)
+    p = _session_path()
+    p.write_text(json.dumps(session, indent=2), encoding="utf-8")
+    try:  # best-effort; POSIX only
+        os.chmod(p, 0o600)
+    except OSError:  # pragma: no cover
+        pass
+
+
+def clear_session() -> bool:
+    """Delete the cached session. Returns True if one was present."""
+    p = _session_path()
+    if p.exists():
+        p.unlink()
+        return True
+    return False

stml_cli/http.py

@@ -0,0 +1,164 @@
+"""Tiny stdlib HTTP client + token resolution.
+
+Token precedence (024 §The partner CLI login flow):
+  1. ``STML4_TOKEN`` env — used verbatim (monorepo `npm run token`, CI).
+  2. the cached login session — its access token, silently refreshed when stale.
+  3. otherwise: a clear "run stml login" error.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from typing import Any
+
+from . import config
+
+CLIENT_ID = "stml4-cli"
+
+
+class HttpError(Exception):
+    """A non-2xx (or transport) failure, carrying the status code + a clean
+    detail string. Callers can branch on ``.code`` (e.g. 409 → disambiguate);
+    the top-level handler prints ``.detail`` for everything else.
+    """
+
+    def __init__(self, code: int, detail: str):
+        super().__init__(detail)
+        self.code = code
+        self.detail = detail
+
+
+# ── low-level requests ──────────────────────────────────────────────────────
+
+def _open(req: urllib.request.Request) -> dict:
+    try:
+        with urllib.request.urlopen(req) as resp:
+            body = resp.read().decode("utf-8")
+            return json.loads(body) if body else {}
+    except urllib.error.HTTPError as e:
+        raw = e.read().decode("utf-8", "replace")
+        detail = raw
+        try:  # FastAPI errors are {"detail": "..."} — surface the message, not JSON
+            parsed = json.loads(raw)
+            if isinstance(parsed, dict) and "detail" in parsed:
+                detail = str(parsed["detail"])
+        except (ValueError, TypeError):
+            pass
+        raise HttpError(e.code, detail)
+    except urllib.error.URLError as e:  # network / DNS / TLS
+        raise HttpError(0, f"cannot reach {req.full_url}: {e.reason}")
+
+
+def get_json(url: str, token: str) -> dict:
+    req = urllib.request.Request(url, headers={"Authorization": f"Bearer {token}"}, method="GET")
+    return _open(req)
+
+
+def post_json(url: str, body: dict, token: str | None = None) -> dict:
+    headers = {"Content-Type": "application/json"}
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    req = urllib.request.Request(
+        url, data=json.dumps(body).encode("utf-8"), headers=headers, method="POST"
+    )
+    return _open(req)
+
+
+def post_form(url: str, fields: dict[str, str]) -> dict:
+    """application/x-www-form-urlencoded POST (the OAuth token endpoint)."""
+    data = urllib.parse.urlencode(fields).encode("utf-8")
+    req = urllib.request.Request(
+        url, data=data,
+        headers={"Content-Type": "application/x-www-form-urlencoded"}, method="POST",
+    )
+    return _open(req)
+
+
+def post_multipart(
+    url: str, fields: dict[str, str], file_field: str, filename: str,
+    file_bytes: bytes, token: str,
+) -> dict:
+    boundary = f"----STML4-{uuid.uuid4().hex}"
+    body = bytearray()
+    for name, value in fields.items():
+        body += f"--{boundary}\r\n".encode()
+        body += f'Content-Disposition: form-data; name="{name}"\r\n\r\n'.encode()
+        body += value.encode("utf-8") + b"\r\n"
+    body += f"--{boundary}\r\n".encode()
+    body += (
+        f'Content-Disposition: form-data; name="{file_field}"; filename="{filename}"\r\n'
+        f"Content-Type: application/gzip\r\n\r\n"
+    ).encode()
+    body += file_bytes + b"\r\n"
+    body += f"--{boundary}--\r\n".encode()
+
+    req = urllib.request.Request(
+        url, data=bytes(body),
+        headers={
+            "Authorization": f"Bearer {token}",
+            "Content-Type": f"multipart/form-data; boundary={boundary}",
+        },
+        method="POST",
+    )
+    return _open(req)
+
+
+# ── token resolution ────────────────────────────────────────────────────────
+
+def resolve_token(backend: str) -> str:
+    """Return a usable access token, refreshing the cached session if stale."""
+    import os
+
+    override = os.environ.get("STML4_TOKEN")
+    if override:
+        return override.strip()
+
+    sess = config.read_session()
+    if not sess or not sess.get("refresh_token"):
+        raise SystemExit("Not logged in. Run: stml login  (or set STML4_TOKEN)")
+
+    now = int(time.time())
+    if not sess.get("expires_at") or int(sess["expires_at"]) - now < 60:
+        sess = refresh_session(backend, sess)
+    return sess["access_token"]
+
+
+def refresh_session(backend: str, sess: dict) -> dict:
+    """Exchange the refresh token for a fresh access token; re-cache."""
+    try:
+        tok = post_form(
+            f"{backend}/mcp/oauth/token",
+            {"grant_type": "refresh_token", "refresh_token": sess["refresh_token"], "client_id": CLIENT_ID},
+        )
+    except HttpError:
+        raise SystemExit("Session expired. Run: stml login")
+    return _store_tokens(backend, tok)
+
+
+def _store_tokens(backend: str, tok: dict) -> dict:
+    now = int(time.time())
+    expires_at = tok.get("expires_at") or (now + int(tok.get("expires_in") or 3600))
+    sess = {
+        "backend": backend,
+        "access_token": tok["access_token"],
+        "refresh_token": tok["refresh_token"],
+        "expires_at": int(expires_at),
+    }
+    config.write_session(sess)
+    return sess
+
+
+def token_claims(token: str) -> dict[str, Any]:
+    """Best-effort decode of a JWT payload (NOT verified — display only)."""
+    try:
+        payload = token.split(".")[1]
+        payload += "=" * (-len(payload) % 4)
+        return json.loads(base64.urlsafe_b64decode(payload))
+    except Exception:
+        return {}

stml_cli/oauth.py

@@ -0,0 +1,90 @@
+"""`stml login` — the browser OAuth loopback flow (024 §The partner CLI login).
+
+Standard PKCE authorization-code flow against the platform's existing
+``/mcp/oauth/{authorize,token}`` endpoints (the same ones `npm run libs:login`
+drives), with a one-shot loopback server catching the redirect. No password is
+ever handled by the CLI; the refresh token is cached, the access token is not.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import secrets
+import sys
+import urllib.parse
+import webbrowser
+from http.server import BaseHTTPRequestHandler, HTTPServer
+
+from . import http
+from .http import CLIENT_ID
+
+_DONE_PAGE = (
+    b"<!doctype html><html><body style='font-family:sans-serif;padding:3rem'>"
+    b"<h2>stml login complete</h2><p>You can close this tab and return to the terminal.</p>"
+    b"</body></html>"
+)
+
+
+def _pkce_pair() -> tuple[str, str]:
+    verifier = secrets.token_urlsafe(64)
+    challenge = base64.urlsafe_b64encode(
+        hashlib.sha256(verifier.encode("ascii")).digest()
+    ).rstrip(b"=").decode("ascii")
+    return verifier, challenge
+
+
+def login(backend: str) -> dict:
+    """Run the browser flow and cache the resulting session. Returns it."""
+    verifier, challenge = _pkce_pair()
+    state = secrets.token_urlsafe(16)
+    captured: dict[str, str | None] = {}
+
+    class _Handler(BaseHTTPRequestHandler):
+        def do_GET(self):  # noqa: N802 (stdlib signature)
+            params = urllib.parse.parse_qs(urllib.parse.urlparse(self.path).query)
+            captured["code"] = (params.get("code") or [None])[0]
+            captured["state"] = (params.get("state") or [None])[0]
+            self.send_response(200)
+            self.send_header("Content-Type", "text/html")
+            self.end_headers()
+            self.wfile.write(_DONE_PAGE)
+
+        def log_message(self, *_args):  # silence the default stderr logging
+            pass
+
+    server = HTTPServer(("127.0.0.1", 0), _Handler)
+    redirect_uri = f"http://127.0.0.1:{server.server_address[1]}/callback"
+    authorize_url = f"{backend}/mcp/oauth/authorize?" + urllib.parse.urlencode({
+        "response_type": "code",
+        "client_id": CLIENT_ID,
+        "redirect_uri": redirect_uri,
+        "state": state,
+        "code_challenge": challenge,
+        "code_challenge_method": "S256",
+        "scope": "mcp",
+    })
+
+    print("Opening your browser to sign in…", file=sys.stderr)
+    print(f"If it doesn't open, visit:\n  {authorize_url}\n", file=sys.stderr)
+    try:
+        webbrowser.open(authorize_url)
+    except Exception:  # headless / no browser — the printed URL is the fallback
+        pass
+
+    server.handle_request()  # blocks until the single callback arrives
+    server.server_close()
+
+    if not captured.get("code"):
+        raise SystemExit("Login failed: no authorization code was returned.")
+    if captured.get("state") != state:
+        raise SystemExit("Login failed: state mismatch (possible CSRF); aborted.")
+
+    tok = http.post_form(f"{backend}/mcp/oauth/token", {
+        "grant_type": "authorization_code",
+        "code": captured["code"],
+        "code_verifier": verifier,
+        "redirect_uri": redirect_uri,
+        "client_id": CLIENT_ID,
+    })
+    return http._store_tokens(backend, tok)

stml_cli/packaging.py

@@ -0,0 +1,42 @@
+"""Publish-layout tarball builder (ported from scripts/stml_lib.py).
+
+One directory → a ``<dir-name>/…`` gzip tarball, excluding local dev junk. The
+platform publish endpoint reads the manifest and explodes ``src/``; this only
+packages the bytes. Kept byte-compatible with the monorepo builder so a lib
+published by either path lands identically.
+"""
+
+from __future__ import annotations
+
+import io
+import tarfile
+from pathlib import Path
+
+EXCLUDE_DIRS = {
+    ".git", ".venv", "venv", "__pycache__", "node_modules", ".pytest_cache",
+    "dist", "build", ".mypy_cache", ".ruff_cache",
+    # Unit tests live in a top-level tests/ per lib (pytest testpaths); test-
+    # named files inside packages are intentional runnable flows, so dir-only.
+    "tests",
+}
+EXCLUDE_DIR_SUFFIXES = (".egg-info",)
+EXCLUDE_FILES = {"uv.lock", "poetry.lock", "Pipfile.lock", ".DS_Store"}
+EXCLUDE_SUFFIXES = {".pyc", ".pyo"}
+
+
+def build_tarball(lib_dir: Path) -> bytes:
+    buf = io.BytesIO()
+    with tarfile.open(fileobj=buf, mode="w:gz") as tar:
+        for path in sorted(lib_dir.rglob("*")):
+            parts = path.relative_to(lib_dir).parts
+            if any(part in EXCLUDE_DIRS for part in parts):
+                continue
+            if any(part.endswith(EXCLUDE_DIR_SUFFIXES) for part in parts):
+                continue
+            if path.name in EXCLUDE_FILES or path.suffix in EXCLUDE_SUFFIXES:
+                continue
+            if not path.is_file():
+                continue
+            arcname = f"{lib_dir.name}/{path.relative_to(lib_dir).as_posix()}"
+            tar.add(path, arcname=arcname)
+    return buf.getvalue()

stml_cli/paths.py

@@ -0,0 +1,70 @@
+"""Cross-platform overlay ↔ local-folder mapping (024 §OS & runtime support).
+
+The overlay keys the platform stores are always POSIX (``flows/x.py``). "Runs on
+Windows" is only real if the CLI:
+  1. maps a POSIX key to a NATIVE path when writing to disk, and back to a POSIX
+     key (never backslashes) when reading — via ``PurePosixPath`` on the wire,
+     ``Path`` on disk;
+  2. reads/writes UTF-8 and preserves ``\n`` exactly, so a pulled file survives
+     an untouched push byte-for-byte (no CRLF injection on Windows).
+
+These two functions are the whole contract; they are unit-tested in isolation so
+the Windows guarantee doesn't rest on a live round-trip.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path, PurePosixPath
+
+# Local-only artifacts that must never be pushed into the overlay.
+_EXCLUDE_DIRS = {
+    ".git", "__pycache__", ".venv", "venv", ".stml",
+    "node_modules", ".mypy_cache", ".ruff_cache", ".pytest_cache",
+}
+_EXCLUDE_NAMES = {".DS_Store"}
+_EXCLUDE_SUFFIXES = {".pyc", ".pyo"}
+
+
+def to_posix_key(rel: Path) -> str:
+    """A native relative path → the POSIX overlay key (forward slashes)."""
+    return PurePosixPath(*rel.parts).as_posix()
+
+
+def key_to_native(key: str) -> Path:
+    """A POSIX overlay key → a native relative Path for this OS."""
+    return Path(*PurePosixPath(key).parts)
+
+
+def read_tree(root: Path) -> list[dict]:
+    """Read a local folder into ``[{path, content}]`` with POSIX keys.
+
+    ``read_text`` (universal newlines) collapses any CRLF to ``\n``, so the
+    content pushed is always LF-normalised regardless of the author's OS.
+    """
+    out: list[dict] = []
+    for p in sorted(root.rglob("*")):
+        rel = p.relative_to(root)
+        if any(part in _EXCLUDE_DIRS for part in rel.parts):
+            continue
+        if p.name in _EXCLUDE_NAMES or p.suffix in _EXCLUDE_SUFFIXES:
+            continue
+        if not p.is_file():
+            continue
+        out.append({"path": to_posix_key(rel), "content": p.read_text(encoding="utf-8")})
+    return out
+
+
+def write_tree(root: Path, files: list[dict]) -> list[str]:
+    """Write ``[{path, content}]`` (POSIX keys) into a local folder.
+
+    ``newline=""`` disables newline translation so ``\n`` is written verbatim —
+    a pulled file is not silently rewritten to CRLF on Windows.
+    """
+    written: list[str] = []
+    for f in files:
+        key = f["path"]
+        dest = root / key_to_native(key)
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(f.get("content") or "", encoding="utf-8", newline="")
+        written.append(key)
+    return written

stml_cli/refs.py

@@ -0,0 +1,47 @@
+"""Resolve an app reference to (workspace, app).
+
+The canonical handle is an **app URL** — exactly what `stml list` prints and what
+the browser shows. Parsing is deliberately forgiving (most-specific first):
+
+  - a full app URL with ANY trailing path — /flows/…, /sessions/…, /settings are
+    ignored, so pasting the URL of a flow or a run still resolves to its app:
+      https://app.stml.io/orgs/acme/ws/main/apps/invoice-sync-a1b2/flows/x/5
+  - a bare path:  /orgs/acme/ws/main/apps/invoice-sync-a1b2
+  - <workspace>/<app>   (legacy, still accepted)
+  - <app>               (a bare slug or display name)
+
+For a URL/path we return the app **slug** (unique) plus the workspace slug for
+context; for the bare forms we return whatever was given (slug or name), and the
+backend resolves + disambiguates it.
+"""
+
+from __future__ import annotations
+
+from urllib.parse import urlparse
+
+
+def parse_app_ref(ref: str) -> tuple[str | None, str]:
+    ref = (ref or "").strip()
+    if not ref:
+        raise SystemExit("No app given. Pass an app URL (see `stml list`).")
+
+    # A URL or a path carrying the app route → pull the slug out, drop the rest.
+    path = urlparse(ref).path if "://" in ref else ref
+    segs = [s for s in path.split("/") if s]
+    if "apps" in segs:
+        i = segs.index("apps")
+        if i + 1 >= len(segs):
+            raise SystemExit(f"URL has no app slug after /apps/: {ref}")
+        app = segs[i + 1]  # trailing /flows/…, /sessions/…, /settings ignored
+        workspace = None
+        if "ws" in segs:
+            j = segs.index("ws")
+            if j + 1 < len(segs):
+                workspace = segs[j + 1]
+        return workspace, app
+
+    # Not a URL: <workspace>/<app>, or a bare slug/name.
+    if "/" in ref:
+        workspace, app = ref.split("/", 1)
+        return (workspace or None), app
+    return None, ref

stml_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: stml-cli
+Version: 0.1.0
+Summary: The stml partner CLI — pull, edit, push, and publish stml apps and libraries.
+Author: stml
+Project-URL: Homepage, https://stml.io
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: certifi
+
+# stml — the partner CLI
+
+Pull an app you built on the platform down to a local folder, edit it with your
+own editor and git, push it back to test, and publish a finished version to the
+App Store — without cloning the stml4 monorepo.
+
+Spec: [`docs/user-stories/feature/024-app-authoring-platform.md`](../docs/user-stories/feature/024-app-authoring-platform.md).
+
+## Requirements
+
+- **Python 3.11 or newer** on your PATH. That's the only hard requirement.
+  - macOS: `brew install python@3.12` (or python.org). **Not** the system
+    `/usr/bin/python3` — it's often 3.9, which is too old.
+  - Linux: your distro's Python 3.11+, or `pipx`/`pyenv`/`uv`.
+  - Windows 10/11: the python.org installer (gives you the `py` launcher).
+
+## Install
+
+| Method | Command |
+|---|---|
+| **pipx** (recommended) | `pipx install stml-cli` |
+| pip (in a venv) | `pip install stml-cli` |
+| single file (no installer) | `curl -fsSL <backend>/cli/stml -o stml && chmod +x stml` |
+
+Runs on **macOS, Linux, and Windows** — it's pure-Python and touches nothing
+platform-specific beyond the filesystem and HTTPS.
+
+## Quickstart
+
+```sh
+# Point at your backend (default: http://localhost:8010)
+export STML4_BACKEND=https://api.stml.io
+
+# 1. Sign in — opens your browser; approve, and a session is cached locally.
+stml login
+stml whoami
+
+# 2. See your apps and their URLs (the handle you pull/push by).
+stml list
+
+# 3. Pull an app's source into a folder — identify it by its URL (copy from
+#    `stml list` or the browser; a trailing /flows/… or /sessions/… is fine).
+stml pull https://app.stml.io/orgs/acme/ws/main/apps/my-app-a1b2 ./my-app
+
+# 3. Edit with your own tools, commit to git, whatever.
+
+# 4. Push it back — checks, writes the overlay, and deploys in one step.
+stml push ./my-app          # app remembered from pull
+#   or: stml push https://app.stml.io/orgs/acme/ws/main/apps/my-app-a1b2 ./my-app
+
+# 5. When ready, publish a version to the App Store.
+#    (bump project.version in pyproject.toml first; set [tool.stml].issuer-org)
+stml publish ./my-app
+```
+
+## Authentication
+
+`stml login` runs the platform's browser OAuth flow (the same one the monorepo's
+`npm run libs:login` uses): you authenticate in the browser, approve, and a
+**refresh token** is cached under your OS config dir (`~/Library/Application
+Support/stml`, `$XDG_CONFIG_HOME/stml`, or `%APPDATA%\stml`). Access tokens are
+minted per-command and never written to disk.
+
+`STML4_TOKEN`, if set, overrides the cache verbatim — how CI and the monorepo
+(`STML4_TOKEN=$(npm run --silent token)`) authenticate.
+
+## Commands
+
+| Command | What |
+|---|---|
+| `stml login` / `logout` / `whoami` | session auth |
+| `stml list [--workspace <ws>]` | list your apps with their app URLs |
+| `stml pull <app-url> [<dir>]` | pull overlay source to a folder (bare slug also works) |
+| `stml push [<app-url>] <dir>` | push a folder to the overlay **and deploy** (`--no-deploy`, `--prune`) |
+| `stml publish <dir> [--org <slug>]` | publish a library version from a folder |
+| `stml init <dir> [--name <name>]` | scaffold a new library directory |

stml_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+stml_cli/__init__.py,sha256=24NhWGqLjLcIepCQTVzJ4XpcXH4m2PKI97iwaZcqsk8,789
+stml_cli/__main__.py,sha256=6XpV-fU9IF_mcWaEw-8_FCNV1RlAVnQNFW87vSx8CUE,7229
+stml_cli/commands.py,sha256=oNZg1RjQYYRg3ntOypzz9ZiKDwhBWEeW6f5LaPulD0A,12657
+stml_cli/config.py,sha256=va3K5zTLylAj53Pg7fuzA_obXUeXkER6WmxtCJRY-vM,1934
+stml_cli/http.py,sha256=WMb9QsJNNLoHfa0RCqMoK1lUh8cB8yl8WrHT1IeWdKA,5676
+stml_cli/oauth.py,sha256=3nSc6B4uFibfNMBlAVPKNCy2H_f5VDc5yV584VluL-E,3258
+stml_cli/packaging.py,sha256=ggOjdsEM0kQu0f5IEHuTaofr6clupqXK8GyonwJbfEI,1626
+stml_cli/paths.py,sha256=C6OKhiTI_H6AU9g4tQnR3nL0WPncsau_JCaQXs3xRtI,2619
+stml_cli/refs.py,sha256=Bgp305FqtqpUeDORth-lKH4KoSGBosyZDstEXoCiBXA,1862
+stml_cli-0.1.0.dist-info/METADATA,sha256=GqdY2kIEwfnW5xDUTHB8-OLDnSYmiA5R1Ik6Y6xupA8,3379
+stml_cli-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+stml_cli-0.1.0.dist-info/entry_points.txt,sha256=i3Zxa4MVRZREo5hm7lF82PQpHctVP9gowtssxW1WKN4,48
+stml_cli-0.1.0.dist-info/top_level.txt,sha256=cuShv3nGzgfIZZAT7Xq_tOLE3dVUft3KW-LKT-b4hEc,9
+stml_cli-0.1.0.dist-info/RECORD,,

stml_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

stml_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+stml = stml_cli.__main__:main

stml_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+stml_cli