tinyhorse 0.2.1__tar.gz → 0.2.2__tar.gz

{tinyhorse-0.2.1/src/tinyhorse.egg-info → tinyhorse-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tinyhorse
-Version: 0.2.1
+Version: 0.2.2
 Summary: Git-native project control for local and user-owned infrastructure
 Author: Tiny Horse contributors
 License-Expression: Apache-2.0
@@ -87,26 +87,33 @@ tinyhorse projects
 tinyhorse clone TULKAS
 ```
 
-## Tiny verbs (0.2.0)
+## Tiny verbs (0.2.2)
 
-Autonomous git control uses short names. They wrap the same storage loop:
+Autonomous git control uses short names. They wrap the same storage loop.
+`tinyhorse --help` repeats this; every subcommand has a description.
 
 | Tiny | Same as / meaning |
 |------|-------------------|
 | `tinyhorse park` | `push` — publish the canonical bundle, including parked WIP |
 | `tinyhorse claim NAME` | `clone` — restore a Drive project by name |
 | `tinyhorse doctor` | compare local vs canonical; dirty is ok if that dirt is parked |
-| `tinyhorse freeze-writer` | refuse later park/push from this checkout |
-| `tinyhorse from-zip ZIP DEST` | GitHub zipball → git checkout (optional `--storage`) |
-| `tinyhorse ingest-github URL` | `migrate` a git remote into Tiny Horse |
+| `tinyhorse freeze-writer` | refuse park/push from this checkout |
+| `tinyhorse freeze-writer --clear` | unfreeze (or delete `.git/tinyhorse-freeze`) |
+| `tinyhorse from-zip ZIP DEST` | GitHub zipball → **one new commit** (no history) |
+| `tinyhorse ingest-github URL` | `migrate` a git URL → **full history** |
+| `tinyhorse tag v1.2.0` | annotated git tag on **your** project, then park |
 
-WIP (uncommitted files, extra worktrees, `refs/backup/`) is snapshotted into `refs/tinyhorse/wip/<name>` inside the **same** bundle. Park drops wip refs for worktrees that are gone or clean. An in-progress rebase/merge is refused until packed. MCP stdio: `tinyhorse-mcp` (`park`, `claim`, `doctor`, `from_zip`, `status`).
+WIP (uncommitted files, extra worktrees, `refs/backup/`) is snapshotted into `refs/tinyhorse/wip/<name>` inside the **same** bundle. Park drops wip refs for worktrees that are gone or clean. An in-progress rebase/merge is refused until packed.
+
+**Your versioning** is git tags on the project, not `tinyhorse --version`. `tinyhorse tag v1.0` creates `git tag -a v1.0` and parks so the tag lives in the canonical bundle.
+
+MCP: `tinyhorse-mcp --help` then stdio JSON-RPC (`park`, `claim`, `doctor`, `from_zip`, `status`, `tag`).
 
 `projects` discovers top-level Drive project folders that are marked by Tiny Horse
 or contain Git bundles, surfaces empty/ambiguous folders instead of guessing, and
 does not print provider folder/file IDs. `clone PROJECT` requires one exact project
 name, restores the canonical bundle, writes the machine-local binding when needed,
-and verifies that the restored working tree is clean. Explicit `pull LOCATOR`
+and restores parked WIP (the tree may be dirty; that is success). Explicit `pull LOCATOR`
 remains available for automation and unusual layouts.
 
 The Drive adapter searches for exactly one canonical file with that name in that folder. `push` creates it once and then updates the same Drive object in place. Multiple same-named candidates are treated as an error instead of guessed around. Before replacing an existing object, Tiny Horse downloads and verifies canonical Git, compares its durable refs with the local bundle, and writes only with the snapshot token from that inspect. File storage serializes readers and writers with an exclusive lock, hashes the bytes it copies, and `fsync`s unique temporary files before replace. Drive content replacement uses Drive API v2 `If-Match` so a changed object returns HTTP 412 instead of a silent overwrite. It then reads the object back and requires the SHA-256 of the downloaded bytes to match the upload. See `docs/STORAGE_SAFETY.md`.
@@ -156,19 +163,25 @@ For an intentional history rewrite or ref deletion, use `tinyhorse push --force`
 ## CLI
 
 ```bash
+tinyhorse --help
 tinyhorse status [PATH]
 tinyhorse init [PATH] (--drive | --storage LOCATOR) [--project NAME]
-tinyhorse push [PATH] [--force]
+tinyhorse park [PATH] [--force]          # also: push
 tinyhorse pull LOCATOR DESTINATION
 tinyhorse doctor [PATH]
 tinyhorse projects
-tinyhorse clone PROJECT [DESTINATION]
+tinyhorse claim PROJECT [DESTINATION]    # also: clone
+tinyhorse tag NAME [PATH] [-m MSG] [--no-park]
+tinyhorse freeze-writer [PATH] [--clear]
+tinyhorse from-zip ZIP DEST [--project NAME] [--storage LOCATOR]
+tinyhorse ingest-github URL [DEST] [--drive | --storage LOCATOR] [--project NAME]
 tinyhorse bundle PATH OUTPUT
 tinyhorse verify-bundle BUNDLE
 tinyhorse migrate REMOTE [DESTINATION] [--drive | --storage LOCATOR] [--project NAME]
 tinyhorse auth login [--client-secrets PATH] [--no-browser]
 tinyhorse auth status [--refresh]
 tinyhorse auth logout
+tinyhorse-mcp --help
 ```
 
 `status`, `migrate`, `push`, `pull`, `doctor`, and the auth commands produce machine-readable JSON where appropriate. `doctor` compares local HEAD to the canonical bundle and reports `in_sync`, `local_ahead`, `local_behind`, or `diverged_or_unrelated`. A refused safe push exits without replacing canonical storage and explains which HEAD, branch, tag, or ref would have been lost.

{tinyhorse-0.2.1 → tinyhorse-0.2.2}/README.md

@@ -69,26 +69,33 @@ tinyhorse projects
 tinyhorse clone TULKAS
 ```
 
-## Tiny verbs (0.2.0)
+## Tiny verbs (0.2.2)
 
-Autonomous git control uses short names. They wrap the same storage loop:
+Autonomous git control uses short names. They wrap the same storage loop.
+`tinyhorse --help` repeats this; every subcommand has a description.
 
 | Tiny | Same as / meaning |
 |------|-------------------|
 | `tinyhorse park` | `push` — publish the canonical bundle, including parked WIP |
 | `tinyhorse claim NAME` | `clone` — restore a Drive project by name |
 | `tinyhorse doctor` | compare local vs canonical; dirty is ok if that dirt is parked |
-| `tinyhorse freeze-writer` | refuse later park/push from this checkout |
-| `tinyhorse from-zip ZIP DEST` | GitHub zipball → git checkout (optional `--storage`) |
-| `tinyhorse ingest-github URL` | `migrate` a git remote into Tiny Horse |
+| `tinyhorse freeze-writer` | refuse park/push from this checkout |
+| `tinyhorse freeze-writer --clear` | unfreeze (or delete `.git/tinyhorse-freeze`) |
+| `tinyhorse from-zip ZIP DEST` | GitHub zipball → **one new commit** (no history) |
+| `tinyhorse ingest-github URL` | `migrate` a git URL → **full history** |
+| `tinyhorse tag v1.2.0` | annotated git tag on **your** project, then park |
 
-WIP (uncommitted files, extra worktrees, `refs/backup/`) is snapshotted into `refs/tinyhorse/wip/<name>` inside the **same** bundle. Park drops wip refs for worktrees that are gone or clean. An in-progress rebase/merge is refused until packed. MCP stdio: `tinyhorse-mcp` (`park`, `claim`, `doctor`, `from_zip`, `status`).
+WIP (uncommitted files, extra worktrees, `refs/backup/`) is snapshotted into `refs/tinyhorse/wip/<name>` inside the **same** bundle. Park drops wip refs for worktrees that are gone or clean. An in-progress rebase/merge is refused until packed.
+
+**Your versioning** is git tags on the project, not `tinyhorse --version`. `tinyhorse tag v1.0` creates `git tag -a v1.0` and parks so the tag lives in the canonical bundle.
+
+MCP: `tinyhorse-mcp --help` then stdio JSON-RPC (`park`, `claim`, `doctor`, `from_zip`, `status`, `tag`).
 
 `projects` discovers top-level Drive project folders that are marked by Tiny Horse
 or contain Git bundles, surfaces empty/ambiguous folders instead of guessing, and
 does not print provider folder/file IDs. `clone PROJECT` requires one exact project
 name, restores the canonical bundle, writes the machine-local binding when needed,
-and verifies that the restored working tree is clean. Explicit `pull LOCATOR`
+and restores parked WIP (the tree may be dirty; that is success). Explicit `pull LOCATOR`
 remains available for automation and unusual layouts.
 
 The Drive adapter searches for exactly one canonical file with that name in that folder. `push` creates it once and then updates the same Drive object in place. Multiple same-named candidates are treated as an error instead of guessed around. Before replacing an existing object, Tiny Horse downloads and verifies canonical Git, compares its durable refs with the local bundle, and writes only with the snapshot token from that inspect. File storage serializes readers and writers with an exclusive lock, hashes the bytes it copies, and `fsync`s unique temporary files before replace. Drive content replacement uses Drive API v2 `If-Match` so a changed object returns HTTP 412 instead of a silent overwrite. It then reads the object back and requires the SHA-256 of the downloaded bytes to match the upload. See `docs/STORAGE_SAFETY.md`.
@@ -138,19 +145,25 @@ For an intentional history rewrite or ref deletion, use `tinyhorse push --force`
 ## CLI
 
 ```bash
+tinyhorse --help
 tinyhorse status [PATH]
 tinyhorse init [PATH] (--drive | --storage LOCATOR) [--project NAME]
-tinyhorse push [PATH] [--force]
+tinyhorse park [PATH] [--force]          # also: push
 tinyhorse pull LOCATOR DESTINATION
 tinyhorse doctor [PATH]
 tinyhorse projects
-tinyhorse clone PROJECT [DESTINATION]
+tinyhorse claim PROJECT [DESTINATION]    # also: clone
+tinyhorse tag NAME [PATH] [-m MSG] [--no-park]
+tinyhorse freeze-writer [PATH] [--clear]
+tinyhorse from-zip ZIP DEST [--project NAME] [--storage LOCATOR]
+tinyhorse ingest-github URL [DEST] [--drive | --storage LOCATOR] [--project NAME]
 tinyhorse bundle PATH OUTPUT
 tinyhorse verify-bundle BUNDLE
 tinyhorse migrate REMOTE [DESTINATION] [--drive | --storage LOCATOR] [--project NAME]
 tinyhorse auth login [--client-secrets PATH] [--no-browser]
 tinyhorse auth status [--refresh]
 tinyhorse auth logout
+tinyhorse-mcp --help
 ```
 
 `status`, `migrate`, `push`, `pull`, `doctor`, and the auth commands produce machine-readable JSON where appropriate. `doctor` compares local HEAD to the canonical bundle and reports `in_sync`, `local_ahead`, `local_behind`, or `diverged_or_unrelated`. A refused safe push exits without replacing canonical storage and explains which HEAD, branch, tag, or ref would have been lost.

{tinyhorse-0.2.1 → tinyhorse-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tinyhorse"
-version = "0.2.1"
+version = "0.2.2"
 description = "Git-native project control for local and user-owned infrastructure"
 readme = "README.md"
 requires-python = ">=3.10"

{tinyhorse-0.2.1 → tinyhorse-0.2.2}/src/tinyhorse/__init__.py

@@ -1,3 +1,3 @@
 """Tiny Horse: Git-native project control."""
 
-__version__ = "0.2.1"
+__version__ = "0.2.2"

tinyhorse-0.2.2/src/tinyhorse/cli.py

@@ -0,0 +1,347 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from argparse import RawDescriptionHelpFormatter
+
+from . import __version__
+
+from .auth import AuthError, google_drive_auth_status, login_google_drive, logout_google_drive
+from .config import ConfigError
+from .git import GitError, create_bundle, repository_state, verify_bundle
+from .storage import StorageError
+from .workflow import (
+    WorkflowError,
+    clone_project,
+    doctor,
+    freeze_writer,
+    from_zip,
+    ingest_github,
+    init_drive_project,
+    init_project,
+    migrate_remote,
+    projects,
+    pull,
+    push,
+    tag_project,
+    unfreeze_writer,
+)
+
+
+EPILOG = """
+WIP: park snapshots dirty files, untracked files, and extra worktrees into
+refs/tinyhorse/wip/<name> inside the same canonical bundle. refs/backup/* is
+kept. An in-progress rebase/merge/cherry-pick is refused until finished.
+Removed or clean worktrees drop their wip refs on the next park.
+
+Your versioning: git tags on THIS repo are durable. Prefer:
+  tinyhorse tag v1.0.0
+which creates an annotated git tag and parks. You can also `git tag -a` then
+`tinyhorse park`. Tiny Horse's own package version (tinyhorse --version) is
+unrelated to your project's tags.
+
+Zip vs git URL:
+  from-zip     GitHub zipball → ONE new commit (no history)
+  ingest-github / migrate  clone the git URL → full history
+
+Freeze: tinyhorse freeze-writer writes .git/tinyhorse-freeze.
+Unfreeze: tinyhorse freeze-writer --clear  (or delete that file).
+
+MCP: tinyhorse-mcp --help   then stdio JSON-RPC (park, claim, doctor, from_zip, status, tag).
+"""
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="tinyhorse",
+        formatter_class=RawDescriptionHelpFormatter,
+        description="Git-native canonical storage. One bundle per project. Does not replace git.",
+        epilog=EPILOG,
+    )
+    parser.add_argument("--version", action="version", version=f"tinyhorse {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    status = sub.add_parser(
+        "status",
+        help="print local Git state as JSON",
+        description="HEAD, branch, dirty, remotes. Does not talk to Drive.",
+    )
+    status.add_argument("path", nargs="?", default=".", help="git checkout (default: .)")
+
+    init = sub.add_parser(
+        "init",
+        help="bind an existing Git repo to canonical storage",
+        description="Writes .tinyhorse.toml (machine-local). Does not park yet.",
+    )
+    init.add_argument("path", nargs="?", default=".", help="git checkout (default: .)")
+    init_storage = init.add_mutually_exclusive_group(required=True)
+    init_storage.add_argument(
+        "--storage",
+        help="file:/path/to.bundle or gdrive://FOLDER_ID/FILE.bundle",
+    )
+    init_storage.add_argument(
+        "--drive",
+        action="store_true",
+        help="find or create a top-level Drive folder named --project (or the directory name)",
+    )
+    init.add_argument("--project", help="Drive/project display name; defaults to directory name")
+
+    force_help = (
+        "allow non-fast-forward history or ref deletion; "
+        "still aborts if storage changed during preflight"
+    )
+
+    push_cmd = sub.add_parser(
+        "push",
+        help="safely publish a verified canonical bundle (also: park)",
+        description="Parks WIP into refs/tinyhorse/wip/*, then publishes. Dirty is included, not dropped.",
+    )
+    push_cmd.add_argument("path", nargs="?", default=".", help="git checkout (default: .)")
+    push_cmd.add_argument("--force", action="store_true", help=force_help)
+
+    pull_cmd = sub.add_parser(
+        "pull",
+        help="restore a repository from a storage locator",
+        description="Restores durable refs and parked WIP. Recovered trees may be dirty; that is success.",
+    )
+    pull_cmd.add_argument("storage", help="file:... or gdrive://FOLDER_ID/FILENAME")
+    pull_cmd.add_argument("destination", help="new directory; must not already exist")
+
+    doctor_cmd = sub.add_parser(
+        "doctor",
+        help="compare local state with canonical storage",
+        description=(
+            "ok if HEAD/refs match and either the tree is clean or its dirt is parked "
+            "in refs/tinyhorse/wip. Exit 1 if not ok."
+        ),
+    )
+    doctor_cmd.add_argument("path", nargs="?", default=".", help="git checkout (default: .)")
+
+    sub.add_parser(
+        "projects",
+        help="list discoverable Tiny Horse projects on Google Drive",
+        description="Names and bundle filenames only; no Drive folder IDs.",
+    )
+
+    clone_cmd = sub.add_parser(
+        "clone",
+        help="discover and restore a Tiny Horse project by name (also: claim)",
+        description="Restores WIP. Dirty after claim is ok when that dirt was parked.",
+    )
+    clone_cmd.add_argument("project", help="exact Drive project display name")
+    clone_cmd.add_argument("destination", nargs="?", help="new directory; defaults to the project name")
+
+    bundle = sub.add_parser("bundle", help="create a complete Git bundle (includes parked WIP)")
+    bundle.add_argument("path", help="git checkout")
+    bundle.add_argument("output", help="bundle file to write")
+
+    verify = sub.add_parser("verify-bundle", help="verify a Git bundle (header + fsck)")
+    verify.add_argument("bundle", help="path to a .bundle file")
+
+    park = sub.add_parser(
+        "park",
+        help="tiny: publish canonical bundle including WIP (same as push)",
+        description="Preferred autonomous name for push.",
+    )
+    park.add_argument("path", nargs="?", default=".", help="git checkout (default: .)")
+    park.add_argument("--force", action="store_true", help=force_help)
+
+    claim = sub.add_parser(
+        "claim",
+        help="tiny: restore a Drive project by name (same as clone)",
+    )
+    claim.add_argument("project", help="exact Drive project display name")
+    claim.add_argument("destination", nargs="?", help="new directory")
+
+    freeze = sub.add_parser(
+        "freeze-writer",
+        help="tiny: refuse park/push from this checkout until cleared",
+        description="Writes .git/tinyhorse-freeze. Unfreeze with --clear or by deleting that file.",
+    )
+    freeze.add_argument("path", nargs="?", default=".", help="git checkout (default: .)")
+    freeze.add_argument(
+        "--clear",
+        action="store_true",
+        help="remove .git/tinyhorse-freeze so park/push work again",
+    )
+
+    fromzip = sub.add_parser(
+        "from-zip",
+        help="tiny: zipball → ONE new git commit (no history)",
+        description=(
+            "GitHub zipballs have no .git. Tiny Horse inits a repo and makes one commit. "
+            "For full history use ingest-github / migrate on the git URL. "
+            "Then init --drive and park, or pass --storage here."
+        ),
+    )
+    fromzip.add_argument("archive", help="path to .zip (GitHub zipball or any project zip)")
+    fromzip.add_argument("destination", help="new directory; must not already exist")
+    fromzip.add_argument("--project", help="display name stored if --storage is also passed")
+    fromzip.add_argument(
+        "--storage",
+        help="optional bind: file:... or gdrive://FOLDER_ID/FILE.bundle",
+    )
+
+    ingest = sub.add_parser(
+        "ingest-github",
+        help="tiny: git URL → Tiny Horse with full history (same as migrate)",
+        description="Does not modify the GitHub repo. Canonical authority becomes Tiny Horse storage.",
+    )
+    ingest.add_argument("remote", help="https://github.com/owner/repo.git or any git URL")
+    ingest.add_argument("destination", nargs="?", help="local checkout; defaults to repo name")
+    ingest.add_argument("--project", help="Drive/project display name")
+    ingest_storage = ingest.add_mutually_exclusive_group()
+    ingest_storage.add_argument("--drive", action="store_true", help="provision Drive (default if neither flag)")
+    ingest_storage.add_argument("--storage", help="file:... or gdrive:// locator")
+
+    tag = sub.add_parser(
+        "tag",
+        help="tiny: annotated git tag on THIS project, then park",
+        description=(
+            "Your versioning, not tinyhorse --version. "
+            "Creates git tag -a NAME and parks so the tag lives in the canonical bundle. "
+            "Example: tinyhorse tag v1.2.0 -m 'html-live S1 freeze'"
+        ),
+    )
+    tag.add_argument("name", help="tag name, e.g. v1.2.0")
+    tag.add_argument("path", nargs="?", default=".", help="git checkout (default: .)")
+    tag.add_argument("-m", "--message", help="annotation; default: tinyhorse tag NAME")
+    tag.add_argument(
+        "--no-park",
+        action="store_true",
+        help="only create the git tag; do not park",
+    )
+    tag.add_argument("--force", action="store_true", help="move an existing tag, then park with --force")
+
+    move = sub.add_parser(
+        "migrate",
+        help="migrate a Git remote into Tiny Horse canonical storage",
+        description="Same as ingest-github. Never pushes to or deletes the source remote.",
+    )
+    move.add_argument("remote", help="git URL or local path")
+    move.add_argument(
+        "destination",
+        nargs="?",
+        help="local checkout destination; defaults to the repository name",
+    )
+    move.add_argument("--project", help="project display name; defaults to repository name")
+    migrate_storage = move.add_mutually_exclusive_group()
+    migrate_storage.add_argument(
+        "--drive",
+        action="store_true",
+        help="auto-provision Google Drive storage (the default)",
+    )
+    migrate_storage.add_argument(
+        "--storage",
+        help="explicit canonical storage locator instead of Google Drive",
+    )
+
+    auth = sub.add_parser("auth", help="manage storage-provider authentication")
+    auth_sub = auth.add_subparsers(dest="auth_command", required=True)
+
+    auth_login = auth_sub.add_parser("login", help="sign in to Google Drive")
+    auth_login.add_argument(
+        "--client-secrets",
+        help="Google OAuth desktop-app client JSON; defaults to configured locations",
+    )
+    auth_login.add_argument(
+        "--no-browser",
+        action="store_true",
+        help="print the authorization URL instead of opening a browser",
+    )
+
+    auth_status = auth_sub.add_parser("status", help="show Google Drive authentication state")
+    auth_status.add_argument(
+        "--refresh",
+        action="store_true",
+        help="refresh an expired access token while checking status",
+    )
+
+    auth_sub.add_parser("logout", help="remove Tiny Horse's saved Google Drive credentials")
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    try:
+        if args.command == "status":
+            print(repository_state(args.path).to_json())
+        elif args.command == "init":
+            if args.drive:
+                print(init_drive_project(args.path, args.project))
+            else:
+                print(init_project(args.path, args.storage, args.project))
+        elif args.command in ("push", "park"):
+            print(push(args.path, force=args.force).to_json())
+        elif args.command == "pull":
+            print(pull(args.storage, args.destination).to_json())
+        elif args.command == "doctor":
+            result = doctor(args.path)
+            print(result.to_json())
+            return 0 if result.ok else 1
+        elif args.command == "projects":
+            print(projects().to_json())
+        elif args.command in ("clone", "claim"):
+            print(clone_project(args.project, args.destination).to_json())
+        elif args.command == "freeze-writer":
+            if args.clear:
+                print(str(unfreeze_writer(args.path)))
+            else:
+                print(str(freeze_writer(args.path)))
+        elif args.command == "from-zip":
+            print(from_zip(args.archive, args.destination, project=args.project, storage=args.storage))
+        elif args.command == "ingest-github":
+            print(
+                ingest_github(
+                    args.remote,
+                    args.destination,
+                    project=args.project,
+                    storage=args.storage,
+                ).to_json()
+            )
+        elif args.command == "tag":
+            print(
+                tag_project(
+                    args.path,
+                    args.name,
+                    message=args.message,
+                    park_after=not args.no_park,
+                    force=args.force,
+                ).to_json()
+            )
+        elif args.command == "bundle":
+            print(create_bundle(args.path, args.output))
+        elif args.command == "verify-bundle":
+            print(verify_bundle(args.bundle))
+        elif args.command == "migrate":
+            print(
+                migrate_remote(
+                    args.remote,
+                    args.destination,
+                    project=args.project,
+                    storage=args.storage,
+                ).to_json()
+            )
+        elif args.command == "auth":
+            if args.auth_command == "login":
+                print(
+                    login_google_drive(
+                        args.client_secrets,
+                        open_browser=not args.no_browser,
+                    ).to_json()
+                )
+            elif args.auth_command == "status":
+                status = google_drive_auth_status(refresh=args.refresh)
+                print(status.to_json())
+                return 0 if status.authenticated else 1
+            elif args.auth_command == "logout":
+                print(logout_google_drive().to_json())
+        return 0
+    except (AuthError, GitError, ConfigError, StorageError, WorkflowError) as exc:
+        print(f"tinyhorse: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{tinyhorse-0.2.1 → tinyhorse-0.2.2}/src/tinyhorse/mcp.py

@@ -61,8 +61,33 @@ TOOLS = [
             "properties": {"path": {"type": "string"}},
         },
     },
+    {
+        "name": "tag",
+        "description": "Annotated git tag on this project, then park (tinyhorse tag).",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "name": {"type": "string"},
+                "path": {"type": "string"},
+                "message": {"type": "string"},
+            },
+            "required": ["name"],
+        },
+    },
 ]
 
+HELP = """tinyhorse-mcp — stdio JSON-RPC 2.0 for Tiny Horse
+
+Tools: park, claim, doctor, from_zip, status, tag
+
+This process reads JSON-RPC from stdin. If you ran it in a terminal by
+mistake, this help is the intended output. Example:
+
+  echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | tinyhorse-mcp
+
+tinyhorse --help documents WIP, zip vs git ingest, freeze, and user tags.
+"""
+
 
 def _run_cli(argv: list[str]) -> tuple[int, str]:
     from io import StringIO
@@ -98,6 +123,13 @@ def _handle(name: str, arguments: dict[str, Any]) -> dict[str, Any]:
         code, text = _run_cli(argv)
     elif name == "status":
         code, text = _run_cli(["status", arguments.get("path") or "."])
+    elif name == "tag":
+        argv = ["tag", arguments["name"]]
+        if arguments.get("path"):
+            argv.append(arguments["path"])
+        if arguments.get("message"):
+            argv.extend(["-m", arguments["message"]])
+        code, text = _run_cli(argv)
     else:
         return {"error": {"code": -32601, "message": f"unknown tool {name}"}}
     return {"content": [{"type": "text", "text": text}], "isError": code != 0}
@@ -128,7 +160,14 @@ def serve() -> None:
         sys.stdout.flush()
 
 
-def main() -> int:
+def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if argv in ([], ["-h"], ["--help"]) and (argv or sys.stdin.isatty()):
+        print(HELP, end="")
+        return 0
+    if "-h" in argv or "--help" in argv:
+        print(HELP, end="")
+        return 0
     serve()
     return 0
 

{tinyhorse-0.2.1 → tinyhorse-0.2.2}/src/tinyhorse/workflow.py

@@ -335,7 +335,7 @@ def migrate_remote(
 FREEZE_NAME = "tinyhorse-freeze"
 
 
-def writer_frozen(repo: str | Path) -> bool:
+def _freeze_marker(repo: str | Path) -> Path:
     root = Path(repository_state(repo).root)
     marker = Path(
         subprocess.run(
@@ -348,28 +348,82 @@ def writer_frozen(repo: str | Path) -> bool:
     )
     if not marker.is_absolute():
         marker = root / marker
-    return marker.is_file()
+    return marker
+
+
+def writer_frozen(repo: str | Path) -> bool:
+    return _freeze_marker(repo).is_file()
 
 
 def freeze_writer(repo: str | Path = ".") -> Path:
     """Refuse later park/push from this checkout until the freeze file is removed."""
-    root = Path(repository_state(repo).root)
-    marker = Path(
-        subprocess.run(
-            ["git", "-C", str(root), "rev-parse", "--git-path", FREEZE_NAME],
-            check=True,
-            text=True,
-            stdout=subprocess.PIPE,
-            stderr=subprocess.PIPE,
-        ).stdout.strip()
-    )
-    if not marker.is_absolute():
-        marker = root / marker
+    marker = _freeze_marker(repo)
     marker.parent.mkdir(parents=True, exist_ok=True)
     marker.write_text("frozen\n", encoding="utf-8")
     return marker
 
 
+def unfreeze_writer(repo: str | Path = ".") -> Path:
+    marker = _freeze_marker(repo)
+    marker.unlink(missing_ok=True)
+    return marker
+
+
+@dataclass(frozen=True)
+class TagResult:
+    name: str
+    oid: str
+    parked: bool
+    push: SyncResult | None = None
+
+    def to_json(self) -> str:
+        return json.dumps(
+            {
+                "name": self.name,
+                "oid": self.oid,
+                "parked": self.parked,
+                "push": None if self.push is None else json.loads(self.push.to_json()),
+            },
+            indent=2,
+            sort_keys=True,
+        )
+
+
+def tag_project(
+    repo: str | Path,
+    name: str,
+    message: str | None = None,
+    *,
+    park_after: bool = True,
+    force: bool = False,
+) -> TagResult:
+    """Annotated git tag on the operator's repo, then park into canonical storage."""
+    name = name.strip()
+    if not name or any(c.isspace() for c in name):
+        raise WorkflowError("tag name must be a single git-ref token, e.g. v1.2.0")
+    root = Path(repository_state(repo).root)
+    msg = (message or f"tinyhorse tag {name}").strip()
+    args = ["-C", str(root), "tag", "-a", name, "-m", msg]
+    if force:
+        args.insert(3, "-f")
+    try:
+        _git(args)
+    except WorkflowError as exc:
+        raise WorkflowError(f"could not create tag {name}: {exc}") from exc
+    oid = _git(["-C", str(root), "rev-parse", name])
+    parked = False
+    sync = None
+    if park_after:
+        if not (root / CONFIG_NAME).is_file():
+            raise WorkflowError(
+                f"tagged {name} locally but this checkout is not bound; "
+                "run tinyhorse init then tinyhorse park"
+            )
+        sync = push(root, force=force)
+        parked = True
+    return TagResult(name=name, oid=oid, parked=parked, push=sync)
+
+
 def from_zip(
     archive: str | Path,
     destination: str | Path,

{tinyhorse-0.2.1 → tinyhorse-0.2.2/src/tinyhorse.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tinyhorse
-Version: 0.2.1
+Version: 0.2.2
 Summary: Git-native project control for local and user-owned infrastructure
 Author: Tiny Horse contributors
 License-Expression: Apache-2.0
@@ -87,26 +87,33 @@ tinyhorse projects
 tinyhorse clone TULKAS
 ```
 
-## Tiny verbs (0.2.0)
+## Tiny verbs (0.2.2)
 
-Autonomous git control uses short names. They wrap the same storage loop:
+Autonomous git control uses short names. They wrap the same storage loop.
+`tinyhorse --help` repeats this; every subcommand has a description.
 
 | Tiny | Same as / meaning |
 |------|-------------------|
 | `tinyhorse park` | `push` — publish the canonical bundle, including parked WIP |
 | `tinyhorse claim NAME` | `clone` — restore a Drive project by name |
 | `tinyhorse doctor` | compare local vs canonical; dirty is ok if that dirt is parked |
-| `tinyhorse freeze-writer` | refuse later park/push from this checkout |
-| `tinyhorse from-zip ZIP DEST` | GitHub zipball → git checkout (optional `--storage`) |
-| `tinyhorse ingest-github URL` | `migrate` a git remote into Tiny Horse |
+| `tinyhorse freeze-writer` | refuse park/push from this checkout |
+| `tinyhorse freeze-writer --clear` | unfreeze (or delete `.git/tinyhorse-freeze`) |
+| `tinyhorse from-zip ZIP DEST` | GitHub zipball → **one new commit** (no history) |
+| `tinyhorse ingest-github URL` | `migrate` a git URL → **full history** |
+| `tinyhorse tag v1.2.0` | annotated git tag on **your** project, then park |
 
-WIP (uncommitted files, extra worktrees, `refs/backup/`) is snapshotted into `refs/tinyhorse/wip/<name>` inside the **same** bundle. Park drops wip refs for worktrees that are gone or clean. An in-progress rebase/merge is refused until packed. MCP stdio: `tinyhorse-mcp` (`park`, `claim`, `doctor`, `from_zip`, `status`).
+WIP (uncommitted files, extra worktrees, `refs/backup/`) is snapshotted into `refs/tinyhorse/wip/<name>` inside the **same** bundle. Park drops wip refs for worktrees that are gone or clean. An in-progress rebase/merge is refused until packed.
+
+**Your versioning** is git tags on the project, not `tinyhorse --version`. `tinyhorse tag v1.0` creates `git tag -a v1.0` and parks so the tag lives in the canonical bundle.
+
+MCP: `tinyhorse-mcp --help` then stdio JSON-RPC (`park`, `claim`, `doctor`, `from_zip`, `status`, `tag`).
 
 `projects` discovers top-level Drive project folders that are marked by Tiny Horse
 or contain Git bundles, surfaces empty/ambiguous folders instead of guessing, and
 does not print provider folder/file IDs. `clone PROJECT` requires one exact project
 name, restores the canonical bundle, writes the machine-local binding when needed,
-and verifies that the restored working tree is clean. Explicit `pull LOCATOR`
+and restores parked WIP (the tree may be dirty; that is success). Explicit `pull LOCATOR`
 remains available for automation and unusual layouts.
 
 The Drive adapter searches for exactly one canonical file with that name in that folder. `push` creates it once and then updates the same Drive object in place. Multiple same-named candidates are treated as an error instead of guessed around. Before replacing an existing object, Tiny Horse downloads and verifies canonical Git, compares its durable refs with the local bundle, and writes only with the snapshot token from that inspect. File storage serializes readers and writers with an exclusive lock, hashes the bytes it copies, and `fsync`s unique temporary files before replace. Drive content replacement uses Drive API v2 `If-Match` so a changed object returns HTTP 412 instead of a silent overwrite. It then reads the object back and requires the SHA-256 of the downloaded bytes to match the upload. See `docs/STORAGE_SAFETY.md`.
@@ -156,19 +163,25 @@ For an intentional history rewrite or ref deletion, use `tinyhorse push --force`
 ## CLI
 
 ```bash
+tinyhorse --help
 tinyhorse status [PATH]
 tinyhorse init [PATH] (--drive | --storage LOCATOR) [--project NAME]
-tinyhorse push [PATH] [--force]
+tinyhorse park [PATH] [--force]          # also: push
 tinyhorse pull LOCATOR DESTINATION
 tinyhorse doctor [PATH]
 tinyhorse projects
-tinyhorse clone PROJECT [DESTINATION]
+tinyhorse claim PROJECT [DESTINATION]    # also: clone
+tinyhorse tag NAME [PATH] [-m MSG] [--no-park]
+tinyhorse freeze-writer [PATH] [--clear]
+tinyhorse from-zip ZIP DEST [--project NAME] [--storage LOCATOR]
+tinyhorse ingest-github URL [DEST] [--drive | --storage LOCATOR] [--project NAME]
 tinyhorse bundle PATH OUTPUT
 tinyhorse verify-bundle BUNDLE
 tinyhorse migrate REMOTE [DESTINATION] [--drive | --storage LOCATOR] [--project NAME]
 tinyhorse auth login [--client-secrets PATH] [--no-browser]
 tinyhorse auth status [--refresh]
 tinyhorse auth logout
+tinyhorse-mcp --help
 ```
 
 `status`, `migrate`, `push`, `pull`, `doctor`, and the auth commands produce machine-readable JSON where appropriate. `doctor` compares local HEAD to the canonical bundle and reports `in_sync`, `local_ahead`, `local_behind`, or `diverged_or_unrelated`. A refused safe push exits without replacing canonical storage and explains which HEAD, branch, tag, or ref would have been lost.

{tinyhorse-0.2.1 → tinyhorse-0.2.2}/src/tinyhorse.egg-info/SOURCES.txt

@@ -22,6 +22,7 @@ src/tinyhorse.egg-info/requires.txt
 src/tinyhorse.egg-info/top_level.txt
 tests/test_auth.py
 tests/test_git.py
+tests/test_help_and_tag.py
 tests/test_release_tool.py
 tests/test_storage.py
 tests/test_wip.py

tinyhorse-0.2.2/tests/test_help_and_tag.py

@@ -0,0 +1,101 @@
+import os
+import subprocess
+import tempfile
+import unittest
+from io import StringIO
+from pathlib import Path
+from unittest.mock import patch
+
+from tinyhorse.cli import main
+from tinyhorse.mcp import HELP, main as mcp_main
+from tinyhorse.workflow import freeze_writer, init_project, tag_project, unfreeze_writer, writer_frozen
+
+
+def _env(home: Path) -> dict[str, str]:
+    env = os.environ.copy()
+    env["HOME"] = str(home)
+    env["GIT_CONFIG_NOSYSTEM"] = "1"
+    env.pop("GIT_CONFIG_GLOBAL", None)
+    return env
+
+
+def _repo(path: Path) -> Path:
+    path.mkdir()
+    env = _env(path)
+    subprocess.run(["git", "init", "-b", "main"], cwd=path, check=True, stdout=subprocess.PIPE, env=env)
+    subprocess.run(["git", "config", "user.email", "test@example.com"], cwd=path, check=True, env=env)
+    subprocess.run(["git", "config", "user.name", "Tiny Horse Test"], cwd=path, check=True, env=env)
+    (path / "hello.txt").write_text("horse\n")
+    subprocess.run(["git", "add", "."], cwd=path, check=True, env=env)
+    subprocess.run(["git", "commit", "-m", "initial"], cwd=path, check=True, stdout=subprocess.PIPE, env=env)
+    return path
+
+
+class HelpTests(unittest.TestCase):
+    def test_top_help_teaches_wip_zip_tag(self):
+        buf = StringIO()
+        with patch("sys.stdout", buf), self.assertRaises(SystemExit) as ctx:
+            main(["--help"])
+        self.assertEqual(ctx.exception.code, 0)
+        text = buf.getvalue()
+        self.assertIn("refs/tinyhorse/wip", text)
+        self.assertIn("from-zip", text)
+        self.assertIn("one new commit", text.lower())
+        self.assertIn("ingest-github", text)
+        self.assertIn("tinyhorse tag", text)
+        self.assertIn("tinyhorse-freeze", text)
+        self.assertIn("MCP", text)
+
+    def test_from_zip_help_says_no_history(self):
+        buf = StringIO()
+        with patch("sys.stdout", buf), self.assertRaises(SystemExit):
+            main(["from-zip", "--help"])
+        self.assertIn("one commit", buf.getvalue().lower())
+        self.assertIn("ingest-github", buf.getvalue())
+
+    def test_mcp_help(self):
+        buf = StringIO()
+        with patch("sys.stdout", buf):
+            self.assertEqual(mcp_main(["--help"]), 0)
+        out = buf.getvalue()
+        self.assertIn("JSON-RPC", out)
+        self.assertIn("tinyhorse-mcp", out)
+
+
+class TagAndFreezeTests(unittest.TestCase):
+    def test_tag_then_park_round_trip(self):
+        with tempfile.TemporaryDirectory() as td:
+            root = Path(td)
+            repo = _repo(root / "repo")
+            bundle = root / "repo.bundle"
+            init_project(repo, bundle.as_uri(), "tagged")
+            subprocess.run(["git", "add", ".tinyhorse.toml"], cwd=repo, check=True)
+            subprocess.run(["git", "commit", "-m", "config"], cwd=repo, check=True, stdout=subprocess.PIPE)
+            result = tag_project(repo, "v1.2.0", message="operator version")
+            self.assertTrue(result.parked)
+            self.assertEqual(result.name, "v1.2.0")
+            restored = root / "restored"
+            from tinyhorse.workflow import pull
+
+            pull(bundle.as_uri(), restored)
+            tag = subprocess.run(
+                ["git", "rev-parse", "v1.2.0"],
+                cwd=restored,
+                check=True,
+                text=True,
+                stdout=subprocess.PIPE,
+            ).stdout.strip()
+            self.assertEqual(tag, result.oid)
+
+    def test_unfreeze(self):
+        with tempfile.TemporaryDirectory() as td:
+            root = Path(td)
+            repo = _repo(root / "repo")
+            freeze_writer(repo)
+            self.assertTrue(writer_frozen(repo))
+            unfreeze_writer(repo)
+            self.assertFalse(writer_frozen(repo))
+
+
+if __name__ == "__main__":
+    unittest.main()

{tinyhorse-0.2.1 → tinyhorse-0.2.2}/tests/test_release_tool.py

@@ -24,7 +24,7 @@ class ReleaseToolTests(unittest.TestCase):
         pyproject_version, init_version = release.package_version(ROOT)
         self.assertEqual(pyproject_version, init_version)
         self.assertEqual(pyproject_version, __version__)
-        self.assertEqual(pyproject_version, "0.2.1")
+        self.assertEqual(pyproject_version, "0.2.2")
 
     def test_manifest_includes_release_tooling(self):
         manifest = (ROOT / "MANIFEST.in").read_text(encoding="utf-8")

tinyhorse-0.2.1/src/tinyhorse/cli.py

@@ -1,230 +0,0 @@
-from __future__ import annotations
-
-import argparse
-import sys
-
-from . import __version__
-
-from .auth import AuthError, google_drive_auth_status, login_google_drive, logout_google_drive
-from .config import ConfigError
-from .git import GitError, create_bundle, repository_state, verify_bundle
-from .storage import StorageError
-from .workflow import (
-    WorkflowError,
-    clone_project,
-    doctor,
-    freeze_writer,
-    from_zip,
-    ingest_github,
-    init_drive_project,
-    init_project,
-    migrate_remote,
-    projects,
-    pull,
-    push,
-)
-
-
-def _parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(prog="tinyhorse")
-    parser.add_argument("--version", action="version", version=f"tinyhorse {__version__}")
-    sub = parser.add_subparsers(dest="command", required=True)
-
-    status = sub.add_parser("status", help="print local Git state as JSON")
-    status.add_argument("path", nargs="?", default=".")
-
-    init = sub.add_parser("init", help="bind an existing Git repo to canonical storage")
-    init.add_argument("path", nargs="?", default=".")
-    init_storage = init.add_mutually_exclusive_group(required=True)
-    init_storage.add_argument("--storage", help="explicit storage locator")
-    init_storage.add_argument(
-        "--drive",
-        action="store_true",
-        help="find or create this project's Google Drive storage automatically",
-    )
-    init.add_argument("--project", help="project display name; defaults to repository directory name")
-
-    push_cmd = sub.add_parser("push", help="safely publish a verified canonical bundle")
-    push_cmd.add_argument("path", nargs="?", default=".")
-    push_cmd.add_argument(
-        "--force",
-        action="store_true",
-        help="allow intentional non-fast-forward history/ref changes; concurrent storage changes still abort",
-    )
-
-    pull_cmd = sub.add_parser("pull", help="restore a repository from canonical storage")
-    pull_cmd.add_argument("storage", help="file:... or gdrive://FOLDER_ID/FILENAME")
-    pull_cmd.add_argument("destination")
-
-    doctor_cmd = sub.add_parser("doctor", help="compare local state with canonical storage")
-    doctor_cmd.add_argument("path", nargs="?", default=".")
-
-    projects_cmd = sub.add_parser(
-        "projects", help="list discoverable Tiny Horse projects on Google Drive"
-    )
-
-    clone_cmd = sub.add_parser(
-        "clone", help="discover and restore a Tiny Horse project by name"
-    )
-    clone_cmd.add_argument("project")
-    clone_cmd.add_argument("destination", nargs="?")
-
-    bundle = sub.add_parser("bundle", help="create a complete Git bundle")
-    bundle.add_argument("path")
-    bundle.add_argument("output")
-
-    verify = sub.add_parser("verify-bundle", help="verify a Git bundle")
-    verify.add_argument("bundle")
-
-    park = sub.add_parser("park", help="tiny: publish canonical bundle (same as push)")
-    park.add_argument("path", nargs="?", default=".")
-    park.add_argument("--force", action="store_true")
-
-    claim = sub.add_parser("claim", help="tiny: restore a Drive project by name (same as clone)")
-    claim.add_argument("project")
-    claim.add_argument("destination", nargs="?")
-
-    freeze = sub.add_parser(
-        "freeze-writer",
-        help="tiny: refuse park/push from this checkout until unfrozen",
-    )
-    freeze.add_argument("path", nargs="?", default=".")
-
-    fromzip = sub.add_parser(
-        "from-zip",
-        help="tiny: GitHub zipball (or any zip) → git checkout, optional bind",
-    )
-    fromzip.add_argument("archive")
-    fromzip.add_argument("destination")
-    fromzip.add_argument("--project")
-    fromzip.add_argument("--storage", help="file:... or gdrive:// locator to bind after ingest")
-
-    ingest = sub.add_parser(
-        "ingest-github",
-        help="tiny: git URL → Tiny Horse (same as migrate)",
-    )
-    ingest.add_argument("remote")
-    ingest.add_argument("destination", nargs="?")
-    ingest.add_argument("--project")
-    ingest_storage = ingest.add_mutually_exclusive_group()
-    ingest_storage.add_argument("--drive", action="store_true")
-    ingest_storage.add_argument("--storage")
-
-    move = sub.add_parser(
-        "migrate",
-        help="migrate a Git remote into Tiny Horse canonical storage",
-    )
-    move.add_argument("remote")
-    move.add_argument(
-        "destination",
-        nargs="?",
-        help="local checkout destination; defaults to the repository name",
-    )
-    move.add_argument("--project", help="project display name; defaults to repository name")
-    migrate_storage = move.add_mutually_exclusive_group()
-    migrate_storage.add_argument(
-        "--drive",
-        action="store_true",
-        help="auto-provision Google Drive storage (the default)",
-    )
-    migrate_storage.add_argument(
-        "--storage",
-        help="explicit canonical storage locator instead of Google Drive",
-    )
-
-    auth = sub.add_parser("auth", help="manage storage-provider authentication")
-    auth_sub = auth.add_subparsers(dest="auth_command", required=True)
-
-    auth_login = auth_sub.add_parser("login", help="sign in to Google Drive")
-    auth_login.add_argument(
-        "--client-secrets",
-        help="Google OAuth desktop-app client JSON; defaults to configured locations",
-    )
-    auth_login.add_argument(
-        "--no-browser",
-        action="store_true",
-        help="print the authorization URL instead of opening a browser",
-    )
-
-    auth_status = auth_sub.add_parser("status", help="show Google Drive authentication state")
-    auth_status.add_argument(
-        "--refresh",
-        action="store_true",
-        help="refresh an expired access token while checking status",
-    )
-
-    auth_sub.add_parser("logout", help="remove Tiny Horse's saved Google Drive credentials")
-
-    return parser
-
-
-def main(argv: list[str] | None = None) -> int:
-    args = _parser().parse_args(argv)
-    try:
-        if args.command == "status":
-            print(repository_state(args.path).to_json())
-        elif args.command == "init":
-            if args.drive:
-                print(init_drive_project(args.path, args.project))
-            else:
-                print(init_project(args.path, args.storage, args.project))
-        elif args.command in ("push", "park"):
-            print(push(args.path, force=args.force).to_json())
-        elif args.command == "pull":
-            print(pull(args.storage, args.destination).to_json())
-        elif args.command == "doctor":
-            result = doctor(args.path)
-            print(result.to_json())
-            return 0 if result.ok else 1
-        elif args.command == "projects":
-            print(projects().to_json())
-        elif args.command in ("clone", "claim"):
-            print(clone_project(args.project, args.destination).to_json())
-        elif args.command == "freeze-writer":
-            print(str(freeze_writer(args.path)))
-        elif args.command == "from-zip":
-            print(from_zip(args.archive, args.destination, project=args.project, storage=args.storage))
-        elif args.command == "ingest-github":
-            print(
-                ingest_github(
-                    args.remote,
-                    args.destination,
-                    project=args.project,
-                    storage=args.storage,
-                ).to_json()
-            )
-        elif args.command == "bundle":
-            print(create_bundle(args.path, args.output))
-        elif args.command == "verify-bundle":
-            print(verify_bundle(args.bundle))
-        elif args.command == "migrate":
-            print(
-                migrate_remote(
-                    args.remote,
-                    args.destination,
-                    project=args.project,
-                    storage=args.storage,
-                ).to_json()
-            )
-        elif args.command == "auth":
-            if args.auth_command == "login":
-                print(
-                    login_google_drive(
-                        args.client_secrets,
-                        open_browser=not args.no_browser,
-                    ).to_json()
-                )
-            elif args.auth_command == "status":
-                status = google_drive_auth_status(refresh=args.refresh)
-                print(status.to_json())
-                return 0 if status.authenticated else 1
-            elif args.auth_command == "logout":
-                print(logout_google_drive().to_json())
-        return 0
-    except (AuthError, GitError, ConfigError, StorageError, WorkflowError) as exc:
-        print(f"tinyhorse: {exc}", file=sys.stderr)
-        return 2
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())