mkit-cli 0.4.0__tar.gz → 0.5.0__tar.gz

{mkit_cli-0.4.0 → mkit_cli-0.5.0}/CHANGELOG.md

@@ -7,6 +7,15 @@ it rather than doing the wrong thing.
 
 ## Unreleased
 
+## 0.5.0 — 2026-10-23
+
+**An app can keep its own version of any guide.** A file named like the guide
+in the app's repo — `docs/guides/about-screen.md`, `docs/guides/app-ui.md`, or
+under `[guide] app_dir` — is added after the guide and the studio's own rules,
+under *This app's own rules*, and wins over both. `[guide] replace = ["ui"]` in
+the app's `mkit.toml` makes that file the whole guide. Placeholders work in it,
+`{{app.name}}` included, and `mkit guide --json` reports `app` and `replaced`.
+
 ## 0.4.0 — 2026-10-23
 
 **Guides.** `mkit guide` reads the guides every app follows — the About screen,

{mkit_cli-0.4.0 → mkit_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mkit-cli
-Version: 0.4.0
+Version: 0.5.0
 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

{mkit_cli-0.4.0 → mkit_cli-0.5.0}/docs/commands.md

@@ -1,6 +1,6 @@
 # mkit command reference
 
-Generated from the command registry (mkit 0.4.x). Do not edit by hand: run `python scripts/gen_docs.py`.
+Generated from the command registry (mkit 0.5.x). Do not edit by hand: run `python scripts/gen_docs.py`.
 
 Global options, accepted before or after any command: `--json`, `--human`, `--project PATH`, `--dry-run`, `--strict`, `--yes --confirm PACKAGE`, `--no-color`.
 

{mkit_cli-0.4.0 → mkit_cli-0.5.0}/docs/config.md

@@ -128,13 +128,26 @@ signoff = "The <App> team"    # the line above the email address
 
 [guide]
 house_dir = "~/studio/house"  # this studio's own rules, one file per guide
+# In an app's mkit.toml:
+# app_dir = "docs/guides"     # this app's own rules (the default)
+# replace = ["ui"]            # guides this app does its own way, start to finish
 ```
 
-A studio's own decisions beside a guide — its worked examples, a look its apps
-share, a rule it chose differently — go in `house_dir`, in a file named like the
-guide's (`about-screen.md`, `in-app-review.md`, ...). `mkit guide` appends it
-under *This studio's own rules*, which win where the two disagree. Without
-`house_dir`, mkit looks in `docs/house/` beside its own source checkout.
+A guide is read in three layers, each winning over the one before:
+
+1. **The guide** — the same for everyone.
+2. **The studio's rules** — `house_dir/<file>`: its worked examples, a look its
+   apps share, a rule it chose differently. Appended under *This studio's own
+   rules*. Without `house_dir`, mkit looks in `docs/house/` beside its own
+   source checkout.
+3. **The app's rules** — `<app>/docs/guides/<file>` in the app's own repo, or
+   `app_dir`. Appended last, under *This app's own rules*: its own layout idea,
+   a part it does differently, the components to use. An app that lists the
+   guide in `replace` uses its file alone, and neither layer above is read.
+
+The file is named like the guide's: `about-screen.md`, `app-ui.md`,
+`in-app-review.md` — `mkit guide` lists them. Placeholders work in all three,
+`{{app.name}}` included.
 
 ## Store listing file
 

{mkit_cli-0.4.0 → mkit_cli-0.5.0}/src/mkit/__init__.py

@@ -2,4 +2,4 @@
 
 # The one place the engine version lives (pyproject.toml reads it from here).
 # Semantic versioning; see CONTRIBUTING.md.
-__version__ = '0.4.0'
+__version__ = '0.5.0'

{mkit_cli-0.4.0 → mkit_cli-0.5.0}/src/mkit/commands/guide.py

@@ -25,7 +25,8 @@ def guide(ctx, args):
             out.table([(r['name'], r['about']) for r in rows], ('name', 'what it covers'))
             out.line()
             out.line('Read one with `mkit guide <name>`. Your details come from [studio] and [about] '
-                     'in ~/.mkit/config.toml or this app\'s mkit.toml.', 'dim')
+                     'in ~/.mkit/config.toml or this app\'s mkit.toml; an app\'s own rules go in '
+                     'its docs/guides/<file>.', 'dim')
         return {'guides': rows}
 
     try:

{mkit_cli-0.4.0 → mkit_cli-0.5.0}/src/mkit/guides.py

@@ -25,6 +25,10 @@ for it and nobody else - in a house folder: the file of the same name, which is
 appended after the guide under a heading saying it overrides what it
 contradicts. By default that folder is docs/house in the engine's own git
 checkout; [guide] house_dir points anywhere else.
+
+An app may keep its own on top, in its own repo: docs/guides/<file> (or
+[guide] app_dir), appended last and winning over both. An app that names a
+guide in [guide] replace uses its own file alone.
 """
 import os
 import re
@@ -129,20 +133,50 @@ def _keep_parts(text, enabled):
     return '\n'.join(out)
 
 
+def app_file(filename, project):
+    """The app's own version of a guide, in its repo: docs/guides/ unless [guide] app_dir says."""
+    if project is None:
+        return None
+    folder = project.root / project.get('guide.app_dir', 'docs/guides')
+    found = folder / filename
+    return found if found.is_file() else None
+
+
+def _append(text, heading, note, extra):
+    return (text.rstrip('\n') + f'\n\n---\n\n## {heading}\n\n*{note}*\n\n'
+            + extra.read_text(encoding='utf-8').strip() + '\n')
+
+
 def render(name, project=None, raw=False):
-    """The guide as text, filled in for this studio. Returns (text, info)."""
+    """The guide as text, filled in for this studio and app. Returns (text, info).
+
+    Three layers, each winning over the one before: the guide, the studio's
+    house rules, the app's own file. An app that lists the guide in
+    [guide] replace uses its own file alone.
+    """
     filename, _ = GUIDES[name]
     path = _locate(filename)
     if path is None:
         raise FileNotFoundError(filename)
-    text = path.read_text(encoding='utf-8')
     get = settings(project)
-    house = house_file(filename, get)
-    if house:
-        text = (text.rstrip('\n') + '\n\n---\n\n## This studio\'s own rules\n\n'
-                '*Kept by this studio, beside the guide above. Where the two disagree, '
-                'these win.*\n\n' + house.read_text(encoding='utf-8').strip() + '\n')
-    info = {'guide': name, 'file': str(path), 'house': str(house) if house else None, 'unset': []}
+    app = app_file(filename, project)
+    replaced = app is not None and name in (get('guide.replace') or ())
+    if replaced:
+        text, house = app.read_text(encoding='utf-8'), None
+    else:
+        text = path.read_text(encoding='utf-8')
+        house = house_file(filename, get)
+        if house:
+            text = _append(text, "This studio's own rules",
+                           'Kept by this studio, beside the guide above. Where the two disagree, '
+                           'these win.', house)
+        if app:
+            text = _append(text, "This app's own rules",
+                           "Kept in this app's repo. Where they disagree with anything above, "
+                           'they win.', app)
+    info = {'guide': name, 'file': str(app if replaced else path),
+            'house': str(house) if house else None, 'app': str(app) if app else None,
+            'replaced': replaced, 'unset': []}
     if raw:
         return text, info
 

{mkit_cli-0.4.0 → mkit_cli-0.5.0}/tests/test_guides.py

@@ -109,3 +109,34 @@ def test_the_wheel_packs_every_guide():
         pytest.skip('this build does not package the guides')
     for filename, _ in guides.GUIDES.values():
         assert f'"docs/{filename}" = "mkit/_guides/{filename}"' in text, filename
+
+
+def test_an_app_adds_its_own_rules_last(capsys, isolated, project, monkeypatch, tmp_path):
+    house = tmp_path / 'house'
+    house.mkdir()
+    (house / 'app-ui.md').write_text('Studio look.\n', encoding='utf-8')
+    monkeypatch.setenv('MKIT_GUIDE_HOUSE_DIR', str(house))
+    (project / 'docs' / 'guides').mkdir(parents=True)
+    (project / 'docs' / 'guides' / 'app-ui.md').write_text('Cards everywhere in {{app.name}}.\n',
+                                                           encoding='utf-8')
+    monkeypatch.chdir(project)
+    code, env = run(capsys, 'guide', 'ui')
+    text = env['result']['text']
+    assert code == 0 and env['result']['app'] and not env['result']['replaced']
+    assert '## Colours from one place' in text
+    assert text.index('Studio look.') < text.index("## This app's own rules")
+    assert text.rstrip().endswith('Cards everywhere in Demo.')
+
+
+def test_an_app_can_replace_a_guide_outright(capsys, isolated, no_house, project, monkeypatch):
+    with open(project / 'mkit.toml', 'a', encoding='utf-8') as f:
+        f.write('[guide]\napp_dir = "design"\nreplace = ["about"]\n')
+    (project / 'design').mkdir()
+    (project / 'design' / 'about-screen.md').write_text('# Our About page\n\nOne line.\n',
+                                                        encoding='utf-8')
+    monkeypatch.chdir(project)
+    code, env = run(capsys, 'guide', 'about')
+    assert code == 0 and env['result']['replaced']
+    assert env['result']['text'].strip() == '# Our About page\n\nOne line.'
+    code, env = run(capsys, 'guide', 'ui')
+    assert env['result']['app'] is None and '## Colours from one place' in env['result']['text']