stml-cli 0.1.0__tar.gz

stml_cli-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,76 @@
+# 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/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "stml-cli"
+version = "0.1.0"
+description = "The stml partner CLI — pull, edit, push, and publish stml apps and libraries."
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [{ name = "stml" }]
+# Runtime is stdlib-only; certifi is the sole dependency, for TLS trust on
+# framework Python builds that ship no CA bundle (024 §Distributing the partner CLI).
+dependencies = ["certifi"]
+
+[project.scripts]
+stml = "stml_cli.__main__:main"
+
+[project.urls]
+Homepage = "https://stml.io"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["stml_cli*"]

stml_cli-0.1.0/setup.cfg

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

stml_cli-0.1.0/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-0.1.0/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())