tinyhorse 0.1.2__tar.gz → 0.2.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tinyhorse
-Version: 0.1.2
+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,11 +87,33 @@ tinyhorse projects
 tinyhorse clone TULKAS
 ```
 
+## Tiny verbs (0.2.2)
+
+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 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.
+
+**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`.
@@ -141,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.1.2 → tinyhorse-0.2.2}/README.md

@@ -69,11 +69,33 @@ tinyhorse projects
 tinyhorse clone TULKAS
 ```
 
+## Tiny verbs (0.2.2)
+
+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 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.
+
+**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`.
@@ -123,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.1.2 → tinyhorse-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tinyhorse"
-version = "0.1.2"
+version = "0.2.2"
 description = "Git-native project control for local and user-owned infrastructure"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -27,6 +27,7 @@ release = [
 
 [project.scripts]
 tinyhorse = "tinyhorse.cli:main"
+tinyhorse-mcp = "tinyhorse.mcp:main"
 
 [tool.setuptools.packages.find]
 where = ["src"]

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

@@ -1,3 +1,3 @@
 """Tiny Horse: Git-native project control."""
 
-__version__ = "0.1.2"
+__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())