mkit-cli 0.3.1__tar.gz

mkit_cli-0.3.1/.gitattributes

@@ -0,0 +1,19 @@
+# Everything text lands in the working tree as LF, on every platform.
+#
+# Not a preference. mkit generates docs/commands.md from docstrings in the
+# source, so a checkout that rewrote those files to CRLF made the generator
+# produce a different reference than the one in the repo — the suite went red
+# on Windows for a file nobody had touched. Pinning the endings removes the
+# whole class of it.
+* text=auto eol=lf
+
+# Shell scripts must stay LF wherever they run.
+*.sh text eol=lf
+
+# Binary, never touched.
+*.png binary
+*.jpg binary
+*.webp binary
+*.ttf binary
+*.otf binary
+*.woff2 binary

mkit_cli-0.3.1/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,58 @@
+name: Bug report
+description: A command did the wrong thing, or stopped doing anything
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Please do not paste a service account key or a `.env`.
+        `mkit <command> --json` is safe to share: it names missing credentials
+        and prints none of them.
+
+  - type: input
+    id: command
+    attributes:
+      label: The command
+      placeholder: mkit deploy --dry-run
+    validations:
+      required: true
+
+  - type: textarea
+    id: output
+    attributes:
+      label: What it printed
+      description: The JSON envelope if you have it — `mkit <command> --json`.
+      render: shell
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected instead
+    validations:
+      required: true
+
+  - type: dropdown
+    id: kind
+    attributes:
+      label: App kind
+      options: [flutter, android, android-wear, not sure]
+    validations:
+      required: true
+
+  - type: input
+    id: versions
+    attributes:
+      label: mkit and OS
+      description: "`mkit --version`, and which OS."
+      placeholder: "0.3.1 on Windows 11"
+    validations:
+      required: true
+
+  - type: textarea
+    id: doctor
+    attributes:
+      label: mkit doctor --json
+      description: Optional, and safe to paste — it never prints a secret.
+      render: json

mkit_cli-0.3.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Something only Play Console can do
+    url: https://github.com/almasumdev/mkit-cli/blob/main/docs/commands.md
+    about: >-
+      Creating an app, content rating, target audience, tester email lists,
+      production access and App access credentials have no API. `mkit manual`
+      lists them — those are not bugs in mkit.
+  - name: Security issue
+    url: https://github.com/almasumdev/mkit-cli/security/advisories/new
+    about: Anything exposing a credential or publishing without confirmation. Please report privately.

mkit_cli-0.3.1/.github/workflows/publish.yml

@@ -0,0 +1,48 @@
+name: publish
+
+# Publishes to PyPI when a version tag is pushed. No token lives here: PyPI's
+# trusted publishing verifies the workflow's own identity, so there is nothing
+# to leak and nothing to rotate.
+#
+# One-time setup, on https://pypi.org/manage/account/publishing/ :
+#   PyPI project name   mkit-cli
+#   Owner               almasumdev
+#   Repository          mkit-cli
+#   Workflow            publish.yml
+#   Environment         pypi
+# Then make a release: scripts/release.py minor go && git push --follow-tags
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      # The tag is not a release until the suite says so.
+      - run: uv sync --all-extras --dev
+      - run: uv run pytest -q
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write          # what trusted publishing signs with
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

mkit_cli-0.3.1/.github/workflows/tests.yml

@@ -0,0 +1,37 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  pytest:
+    # Three platforms because mkit shells out to git, gradle, adb and a JDK, and
+    # finds each of them differently per OS. Everything here runs against the
+    # fake Play service in tests/ — no job touches a real account.
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.11", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: Install
+        run: uv sync --all-extras --dev
+
+      - name: Tests
+        run: uv run pytest -q
+
+      - name: Generated docs are current
+        # docs/commands.md is generated from the command registry; a stale one
+        # means a flag was changed without the reference following it.
+        run: uv run python scripts/gen_docs.py && git diff --exit-code docs/commands.md

mkit_cli-0.3.1/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+dist/
+*.egg-info/
+.env

mkit_cli-0.3.1/AGENTS.md

@@ -0,0 +1,89 @@
+# mkit for AI agents
+
+Read this before running mkit in any app.
+
+## The release rule
+
+**Never run a release or publish command unless the user asked for that
+exact action in this conversation.** Not to test, not to verify a change,
+not as a "safe" dry run.
+
+Release and publish commands:
+
+| Command | Changes |
+|---|---|
+| `deploy` (including `deploy --dry-run`) | builds, bumps and commits the version, uploads to Play |
+| `promote`, `rollout` | what users on a track get |
+| `listing apply`, `datasafety apply`, `testers set` | the store listing and testing setup |
+| `products apply` | in-app products and prices |
+| `rules`, `config set`, `remoteconfig apply`, `remoteconfig rollback` | the live Firebase project |
+| `reviews reply` | a public reply |
+| `bump`, `share` | the app's version commit; a build handed to testers |
+
+`deploy --dry-run` is on the list because it bumps and builds, uploads a
+full bundle to Play and takes minutes; it is still release work.
+
+When the user does ask:
+
+1. Say exactly what will happen (app, version, track, what changes).
+2. Run the plan form first where there is one (`listing plan`,
+   `products plan`, `remoteconfig plan`) and show the result.
+3. Run it with `--yes --confirm <package>`. The engine refuses without both
+   when it is not at a terminal (exit 6). `safety.no_prompt` does not change
+   this: it only spares a person at a terminal the typed confirmation. Approval covers that one action;
+   the next publish needs a new one.
+
+## Free to run
+
+Everything else, when it helps the task: `doctor`, `status`, `version`,
+`commands`, `schema`, `manual`, `self status`, `devices`, `listing plan`,
+`products plan`, `remoteconfig plan`, `whatsnew check`, `datasafety check`,
+`stats`, `vitals`, `crashes`, `reviews list`, `aso rank`, `aso score`,
+`config show`, `testers show`, `products list`, `prices convert`,
+`firebase sha`, `remoteconfig versions`.
+
+`run` builds and installs on a device: only when the user wants the app on a
+device, and only on the device they mean.
+
+`studio` opens a window on the user's screen: only when they ask for it.
+
+## Discover, don't guess
+
+- `mkit commands --json`: every command with its risk class, needed
+  features, and a JSON Schema of its input.
+- `mkit schema <command> --json`: one command in detail.
+- `mkit doctor --json`: which features this app uses and what is broken.
+- `mkit manual`: what only Play Console can do. Tell the user; don't look for
+  a workaround.
+- Reference: `docs/commands.md`, `docs/config.md`.
+
+## Output contract
+
+Off a terminal mkit prints JSON on its own. stdout is exactly one envelope:
+
+```json
+{"ok": true, "command": "...", "exit": 0, "result": {}, "warnings": [], "skipped": []}
+{"ok": false, "command": "...", "exit": 3, "error": {"code": "...", "message": "...", "hint": "...", "retryable": false}}
+```
+
+stderr has one JSON event per line (`step`, `done`, `detail`, `warn`,
+`skipped`, `upload`, `log`). Branch on `exit`; follow `error.hint`.
+
+| exit | meaning | what to do |
+|---|---|---|
+| 0 | ok | |
+| 1 | failed | read `error`, report it |
+| 2 | usage | fix the arguments |
+| 3 | credential missing | tell the user which key `hint` names; never ask for the secret itself |
+| 4 | not found | |
+| 5 | conflict: remote changed, edit expired, already in review | re-run the plan, then ask again |
+| 6 | needs confirmation | stop and ask the user |
+| 7 | done, with skipped steps | report what `skipped` lists |
+| 10 | plan found differences | show the diff |
+
+## Changing mkit itself
+
+Changes go in the engine, never in an app's copy; follow
+CONTRIBUTING.md (tests, regenerated docs, changelog, version).
+
+Never read, print or copy `.env` files or credentials. Never commit them.

mkit_cli-0.3.1/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+Every change is described here before it is released. Versions follow semantic
+versioning (see CONTRIBUTING.md). An app states the oldest engine it works with
+in `mkit.toml` (`requires = ">=0.3"`), and an older engine refuses to run for
+it rather than doing the wrong thing.
+
+## Unreleased
+
+## 0.3.1 — first public release
+
+mkit shipped a small studio's Android apps for a year before this; this is that
+tool, with the studio's own house style and private services taken out. What is
+here is the engine.
+
+**Release.** `mkit deploy` in one command: preflight, a commit for whatever was
+already uncommitted, the version bump in its own commit, Firestore rules, the
+release build, the upload with mapping and release notes, the in-app update
+document, a Telegram message, and a push. A failure before Play accepts the
+build undoes the bump commit — and only if it is still at HEAD, so it can never
+drop someone else's work. `promote`, `rollout` and `share` move a build on from
+there.
+
+**Store.** The listing, what's new, screenshots, the feature graphic, data
+safety and in-app products all live in the repo, in every language, with `plan`
+showing the difference against Play before `apply` sends it. `mkit art build`
+draws the screenshots from real device captures.
+
+**Insight.** `stats`, `vitals`, `crashes`, `reviews`, and `aso rank` /
+`aso score` for where an app sits in Play search.
+
+**Firebase.** Firestore rules, Remote Config (`plan`, `apply`, `pull`,
+`rollback`), and an in-app update document the app reads at startup.
+
+**Devices.** `run` builds and installs on a phone or emulator, `logs` follows
+just that app, `studio` opens the project in Android Studio.
+
+**Getting started.** `mkit init` writes `mkit.toml` and a commented `.env`
+naming every credential, where it comes from and how to encode it; an existing
+`.env` is never replaced, not even with `--force`. `mkit doctor` says what is
+configured, what is broken, and which store commands an app cannot run because
+it has no file for them. `mkit manual` lists the Play Console steps that have no
+API — including production access for a new personal account and App access
+credentials for an app behind a sign-in.
+
+**Staying current.** `mkit self status` says whether a newer release is on PyPI,
+and `mkit self update` names the upgrade command for whichever of uv, pipx or
+pip installed it.
+
+**For agents.** JSON output off a terminal, one envelope per run, an exit code
+per outcome, a risk class per command, and a confirmation that publish-class
+commands will not run without.
+
+**Built and tested** on Linux, macOS and Windows against Python 3.11 and 3.13,
+with a check that the generated command reference matches the code on every
+platform. Releases publish to PyPI from a version tag through trusted
+publishing, with no token stored anywhere.

mkit_cli-0.3.1/CONTRIBUTING.md

@@ -0,0 +1,71 @@
+# Contributing
+
+Issues and pull requests are welcome. mkit drives real releases to the Play
+Store, so the bar is less about style than about never surprising someone on
+release day.
+
+## Getting set up
+
+```bash
+git clone https://github.com/almasumdev/mkit-cli
+cd mkit-cli
+uv sync                 # or: pip install -e ".[dev]"
+uv run pytest           # the whole suite, against a fake Play service
+```
+
+Nothing in the tests touches a real Google account. Play is faked by
+`tests/fakeplay.py`, and it stays that way: a test that could publish is not a
+test.
+
+## The checklist for a change
+
+1. Make the change. Keep anything app-specific out of the code.
+2. Add or update tests in `tests/`.
+3. `uv run python scripts/gen_docs.py` if a command, flag or summary changed —
+   `docs/commands.md` is generated from the command registry, and
+   `tests/test_docs.py` fails while it is stale.
+4. `uv run pytest` — everything passes.
+5. Describe the change under `## Unreleased` in `CHANGELOG.md`, in words
+   somebody using the command would understand.
+
+## Rules that must hold
+
+- **A command that changes what users, testers or Play review see is
+  `risk='publish'`** and calls `safety.confirm` before changing anything.
+  `tests/test_docs.py` pins the list, so adding one is a deliberate act.
+- **Nothing publishes in a test.** Use `tests/fakeplay.py` or `--dry-run`.
+- **Secrets never reach output.** Read them through `secrets.Secrets`, which
+  registers each one for masking.
+- **JSON output and exit codes are a contract.** Agents and scripts branch on
+  them; changing a shape or a code is a major version.
+- **A per-app difference becomes an `mkit.toml` key**, documented in
+  `docs/config.md` — never a branch in the code on an app's name.
+
+## Versioning
+
+Semantic versioning, in `src/mkit/__init__.py` only (`pyproject.toml` reads it
+from there).
+
+| Bump | When |
+|---|---|
+| patch | fixes; commands, flags, `mkit.toml` keys and JSON output unchanged |
+| minor | new commands, flags, config keys or output fields; nothing existing breaks |
+| major | anything an existing `mkit.toml`, script or agent would break on |
+
+Releasing:
+
+```bash
+uv run python scripts/release.py minor      # shows the version and changelog entry
+uv run python scripts/release.py minor go   # tests, bumps, dates the changelog, tags
+git push --follow-tags
+```
+
+The script refuses with uncommitted changes, failing tests, or an empty
+`## Unreleased` section, so every tag is a tested, described state.
+
+## Reporting a bug
+
+Say which app kind (Flutter, native, Wear), the command you ran, and the JSON
+output — `mkit <command> --json`. Never paste a service account key, and note
+that `mkit doctor --json` is safe to share: it names which credentials are
+missing without printing any of them.

mkit_cli-0.3.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nurullah Al-Masum
+
+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.

mkit_cli-0.3.1/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.5
+Name: mkit-cli
+Version: 0.3.1
+Summary: Release Android apps to Google Play from the command line: build, upload, listing, screenshots, data safety, in-app products, vitals and Firebase, in one tool built for humans and AI agents.
+Project-URL: Homepage, https://github.com/almasumdev/mkit-cli
+Project-URL: Documentation, https://github.com/almasumdev/mkit-cli/blob/main/docs/commands.md
+Project-URL: Repository, https://github.com/almasumdev/mkit-cli
+Project-URL: Issues, https://github.com/almasumdev/mkit-cli/issues
+Project-URL: Changelog, https://github.com/almasumdev/mkit-cli/blob/main/CHANGELOG.md
+Author: Nurullah Al-Masum
+License-Expression: MIT
+License-File: LICENSE
+Keywords: android,aso,firebase,flutter,google-play,release
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: System :: Software Distribution
+Requires-Python: >=3.11
+Requires-Dist: google-api-python-client>=2.150
+Requires-Dist: google-auth>=2.35
+Requires-Dist: pillow>=11
+Requires-Dist: requests>=2.32
+Description-Content-Type: text/markdown
+
+# mkit
+
+[![tests](https://github.com/almasumdev/mkit-cli/actions/workflows/tests.yml/badge.svg)](https://github.com/almasumdev/mkit-cli/actions/workflows/tests.yml)
+[![licence: MIT](https://img.shields.io/badge/licence-MIT-blue.svg)](https://github.com/almasumdev/mkit-cli/blob/main/LICENSE)
+
+One command-line tool for everything around an Android app that is not writing
+it: build and install on a device, release to Google Play, keep the store
+listing, screenshots, data safety and in-app products in your repo, read
+installs, vitals, crashes and reviews, check search rank, and drive the
+Firebase side (Firestore rules, Remote Config, an in-app update document).
+
+Flutter and native Kotlin apps, including apps with a Wear OS module.
+
+```bash
+mkit deploy          # bump, build, upload to Play, publish, notify, push
+mkit run -p          # build and install on the phone
+mkit status          # what every track holds right now
+mkit crashes         # what is breaking in production
+```
+
+A release is one command. `mkit deploy` bumps the version, commits it, builds
+the bundle, uploads it with its mapping file and release notes, stages it on a
+track, writes the update document, sends a message, and pushes — and if
+anything fails before Play accepts the build, the version bump undoes itself so
+the repo never claims a release that did not happen.
+
+## Why it exists
+
+Shipping an Android app means a dozen small jobs that live in different places:
+a Gradle command, the Play Console, the Firebase console, a screenshot folder
+somebody renamed, a changelog nobody updated. Each is easy; together they are a
+release day. mkit puts them behind one tool, with the app's settings in one
+file, so the same release happens the same way every time — and so an AI agent
+can run the safe parts without being handed your Play Console password.
+
+It was built to ship a small studio's apps and has been doing that for a while.
+It is opinionated where opinions save time and configurable where apps really
+differ.
+
+## Install
+
+Requires Python 3.11 or newer. [uv](https://docs.astral.sh/uv/) is the easiest
+way in, and installs mkit as a command of its own rather than into a project:
+
+```bash
+uv tool install mkit-cli
+mkit --version
+```
+
+With pipx: `pipx install mkit-cli`. With pip: `pip install mkit-cli`.
+
+The latest from `main`, between releases:
+`uv tool install git+https://github.com/almasumdev/mkit-cli`
+
+`mkit self status` says whether a newer release is out, and `mkit self update`
+gives the upgrade command for whichever of these installed it.
+
+## Getting started
+
+In an app's folder:
+
+```bash
+mkit init            # writes mkit.toml, asking what it cannot work out
+mkit doctor          # what is configured, what is missing, and what to add
+```
+
+`mkit.toml` is the whole of an app's configuration:
+
+```toml
+[app]
+name    = "My App"
+kind    = "flutter"          # flutter | android | android-wear
+package = "com.example.app"
+
+[play]                       # switches Play features on
+
+[store]                      # store listing, art and data safety in the repo
+listing_dir = "store/listing"
+```
+
+Credentials never live in that file. A Google Play service account goes in
+`.env` (per app) or `~/.mkit/.env` (shared); `mkit doctor` names the exact key
+when one is missing, and never prints a secret. Every setting is documented in
+[docs/config.md](https://github.com/almasumdev/mkit-cli/blob/main/docs/config.md).
+
+## What it does
+
+| | |
+|---|---|
+| **Develop** | `run`, `devices`, `logs`, `emu`, `studio`, `gradle`, `version`, `bump` |
+| **Release** | `deploy`, `status`, `promote`, `rollout`, `share` |
+| **Store** | `listing`, `whatsnew`, `datasafety`, `testers`, `art` |
+| **Money** | `products`, `prices` |
+| **Insight** | `stats`, `vitals`, `crashes`, `reviews`, `aso` |
+| **Firebase** | `rules`, `config`, `remoteconfig`, `firebase` |
+
+Every command, flag and example: [docs/commands.md](https://github.com/almasumdev/mkit-cli/blob/main/docs/commands.md),
+generated from the code so it cannot describe a flag that does not exist.
+
+Commands are classed by what they can change — `read`, `plan`, `write`,
+`publish` — and anything in the `publish` class refuses to run without an
+explicit confirmation naming the package.
+
+Some things have no API and must be done in the Play Console. `mkit manual`
+lists them, so you know what is left rather than discovering it at release
+time.
+
+## Working with AI agents
+
+mkit answers in JSON whenever it is not attached to a terminal, with one
+envelope on stdout and a documented exit code per outcome, so an agent can
+branch on a result instead of reading prose. [AGENTS.md](https://github.com/almasumdev/mkit-cli/blob/main/AGENTS.md) is the
+contract: which commands are safe to run unasked, which need a human to say so,
+and what an agent must never do.
+
+## Documentation
+
+| | |
+|---|---|
+| [docs/commands.md](https://github.com/almasumdev/mkit-cli/blob/main/docs/commands.md) | every command and flag |
+| [docs/config.md](https://github.com/almasumdev/mkit-cli/blob/main/docs/config.md) | `mkit.toml`, the store and keyword files, credentials |
+| [docs/store.md](https://github.com/almasumdev/mkit-cli/blob/main/docs/store.md) | the `store/` folder: what lives where, in every language |
+| [docs/store-art.md](https://github.com/almasumdev/mkit-cli/blob/main/docs/store-art.md) | screenshots and the feature graphic, built from real captures |
+| [docs/in-app-update.md](https://github.com/almasumdev/mkit-cli/blob/main/docs/in-app-update.md) | how an app should check for updates: Play first, your policy second |
+| [docs/news-topics.md](https://github.com/almasumdev/mkit-cli/blob/main/docs/news-topics.md) | news and offer notifications over FCM topics |
+| [AGENTS.md](https://github.com/almasumdev/mkit-cli/blob/main/AGENTS.md) | the agent contract |
+| [CONTRIBUTING.md](https://github.com/almasumdev/mkit-cli/blob/main/CONTRIBUTING.md) | changing mkit, tests, versioning |
+| [SECURITY.md](https://github.com/almasumdev/mkit-cli/blob/main/SECURITY.md) | what counts as a security bug here, and how to report it |
+
+## Status and scope
+
+Developed on Windows against real apps on Google Play; the code paths for
+macOS and Linux exist but are less travelled, and there is no CI yet. The test
+suite runs against a fake Play service — nothing in the tests touches a real
+account.
+
+It does not: create an app in the Play Console, answer content rating or target
+audience questionnaires, manage tester email lists (the API only takes Google
+Groups), or publish for you when managed publishing is on. `mkit manual` is the
+full list.
+
+Issues and pull requests are welcome. If you use it for your own apps, I would
+like to hear what broke.
+
+## Licence
+
+MIT. See [LICENSE](https://github.com/almasumdev/mkit-cli/blob/main/LICENSE).