atk-cli 0.2.0__tar.gz → 0.2.1__tar.gz

{atk_cli-0.2.0 → atk_cli-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atk-cli
-Version: 0.2.0
+Version: 0.2.1
 Summary: AI Toolkit - Manage AI development tools through a git-backed, declarative manifest
 Project-URL: Homepage, https://github.com/Svtoo/atk
 Project-URL: Repository, https://github.com/Svtoo/atk

{atk_cli-0.2.0 → atk_cli-0.2.1}/docs/ROADMAP.md

@@ -25,6 +25,7 @@
 | 8     | MCP Management       | ✅      | Auto-install to Claude Code, Codex, Gemini, etc. |
 | 9     | Plug/Unplug          | ✅      | `atk plug`/`unplug` — unified agent wiring  |
 | 10    | Data Backup          | ⏳      | Backup/restore plugin data                  |
+| 11    | Git Sync             | 🔄     | Remote sync, auto-push, repo status         |
 
 ## Phase Summaries
 
@@ -83,6 +84,10 @@ Deprecates `atk mcp add`/`atk mcp remove`. `atk mcp <plugin>` reverts to its ori
 
 Backup and restore plugin data (databases, state files).
 
+### Phase 11: Git Sync 🔄
+
+`atk git` proxy command for managing the .atk repository without navigating to it. `auto_push` config parameter for automatic push after mutations. Enhanced `atk status` with repository section showing branch, remote, sync state, and working directory status.
+
 ---
 
 ## Navigation

{atk_cli-0.2.0 → atk_cli-0.2.1}/docs/backlog.md

@@ -8,10 +8,9 @@ This document collects ideas, deferred features, and future enhancements. Items
 For the master plan, see `ROADMAP.md`.
 ---
 
-## Git push 
+## ~~Git push~~ -> Promoted to Phase 11
 
-For .atk registries with remote repositories, enable a config parameter alongside with auto_commit and auto_push to automatically push changes to the remote. 
-also add command to pull changes from the remote. just a proxy for git, but useful so that the user does not need to navigate to the .atk directory to pull/push changes.
+Addressed by Phase 11: Git Sync. `atk git` proxy command replaces dedicated push/pull commands. `auto_push` config parameter enables automatic push after mutations. `atk status` shows repository state. See `ROADMAP.md` Phase 11 and `specs/git-sync-spec.md`.
 ---
 ## ~~Manage Agents.md and other prompts through atk~~ → Promoted to Phase 9
 

atk_cli-0.2.1/docs/phases/phase-11-git-sync.md

@@ -0,0 +1,88 @@
+# Phase 11: Git Sync
+
+> **Status**: In Progress
+> **Last Updated**: 2026-04-14
+
+Remote synchronization for ATK Home. Users can add a git remote, auto-push after mutations, and see repository state in `atk status`.
+
+## Goals
+
+1. Users can manage the .atk git repo without navigating to the directory
+2. Mutations can automatically push to a remote after committing
+3. `atk status` shows the git repository state alongside plugin status
+
+---
+
+## Scenarios
+
+### Scenario 1: Git Proxy
+
+**User story:** I want to manage my .atk repo's git remote without `cd ~/.atk`.
+
+**Flow:**
+1. `atk git remote add origin git@github.com:user/dotfiles-atk.git`
+2. ATK runs `git remote add origin ...` in ATK_HOME
+3. Git output passed through to terminal
+
+**Edge cases:**
+- ATK Home not initialized -> exit 3
+- Git not available -> exit 7
+- Invalid git arguments -> git's own error, git's exit code
+
+### Scenario 2: Auto-Push After Mutation
+
+**User story:** I want my plugin changes to automatically sync to my remote.
+
+**Flow:**
+1. Edit `manifest.yaml` to set `auto_push: true`
+2. `atk add openmemory`
+3. ATK adds plugin, commits (auto_commit), pushes (auto_push)
+4. Remote now has the latest state
+
+**Edge cases:**
+- No remote configured -> warn, don't error
+- Push fails (auth, network) -> warn, don't error; commit already succeeded
+- `auto_commit: false` with `auto_push: true` -> no push (push requires commit)
+
+### Scenario 3: Repository Status
+
+**User story:** I want to see if my .atk repo is in sync with the remote.
+
+**Flow:**
+1. `atk status`
+2. ATK shows plugin table (existing behavior)
+3. ATK shows Repository section: branch, remote, ahead/behind, last commit, working dir
+
+**Edge cases:**
+- No remote -> show `(none)` for remote, omit sync line
+- No tracking branch -> show `(no tracking branch)` for sync
+- Empty repo (no commits) -> gracefully degrade, show what's available
+- Git queries fail -> skip failing fields, show what's available
+
+---
+
+## Tasks
+
+- [ ] Write git-sync-spec.md
+- [ ] Update ROADMAP.md with Phase 11
+- [ ] Update commands-spec.md with `atk git` command
+- [ ] Update home-spec.md with `auto_push` in manifest schema
+- [ ] Update backlog.md — promote "Git push" item
+- [ ] Add git helper functions to `git.py` (push, branch, remote info, ahead/behind, working dir status)
+- [ ] Add `auto_push` field to `ConfigSection` in `manifest_schema.py`
+- [ ] Add `atk git` proxy command to `cli.py`
+- [ ] Add repository section to `atk status` output
+- [ ] Wire auto-push into `add.py`, `remove.py`, `upgrade.py`
+- [ ] Update initial manifest in `init.py` with `auto_push: false`
+- [ ] Tests for all new functions and behaviors
+
+## Acceptance Criteria
+
+- `atk git remote add origin <url>` successfully adds a remote to .atk
+- `atk git push` pushes .atk commits to the remote
+- `atk git log --oneline` shows .atk commit history
+- Setting `auto_push: true` in manifest causes mutations to push after commit
+- Auto-push failure warns but does not fail the mutation
+- `atk status` shows Repository section with branch, remote, sync, last commit, working dir
+- `atk status` with no remote shows `(none)` gracefully
+- `make check` passes (ruff + mypy + pytest)

{atk_cli-0.2.0 → atk_cli-0.2.1}/docs/specs/commands-spec.md

@@ -62,6 +62,7 @@ flowchart TB
         plug[atk plug]
         mcp[atk mcp]
         help[atk help]
+        git[atk git]
     end
 
     init --> add
@@ -711,6 +712,42 @@ Continue? [y/N]:
 
 ---
 
+## `atk git [args...]`
+
+Run git commands in ATK Home. Thin proxy — passes all arguments to `git` executed in ATK_HOME.
+
+**Arguments:**
+- `[args...]`: Any git arguments (passed through verbatim)
+
+**Usage:**
+```bash
+atk git remote add origin git@github.com:user/dotfiles-atk.git
+atk git remote show origin
+atk git push
+atk git pull
+atk git log --oneline -5
+atk git status
+atk git diff
+```
+
+**Behavior:**
+1. Validate ATK Home is initialized (exit 3 if not)
+2. Require git available (exit 7 if not)
+3. Execute `git <args>` in ATK_HOME with stdin/stdout/stderr passed through
+4. Return git's exit code
+
+**Notes:**
+- No argument validation — git handles its own errors
+- Interactive commands work (stdin is passed through)
+- Destructive commands are the user's responsibility
+
+**Exit Codes:**
+- 3: ATK Home not initialized
+- 7: Git not available
+- (other): Git's own exit code passed through
+
+---
+
 # Deferred to Future
 
 The following commands and features are documented in `atk-future.md`:

atk_cli-0.2.1/docs/specs/git-sync-spec.md

@@ -0,0 +1,156 @@
+# Git Sync Specification
+
+> **Status**: Approved
+> **Last Updated**: 2026-04-14
+
+## Overview
+
+ATK Home is a git-backed repository. Phase 1 introduced `auto_commit` — every mutation creates a local commit. Git Sync extends this with remote synchronization: users can add a remote, auto-push after mutations, and see the repository state in `atk status`.
+
+## Design Principles
+
+1. **Proxy, don't reinvent.** `atk git` passes arguments straight to `git` in ATK_HOME. Users already know git.
+2. **Push is best-effort.** Auto-push failures warn but never fail the mutation. The commit already succeeded locally.
+3. **Sensible defaults.** `auto_push` defaults to `false`. Users opt in after adding a remote.
+
+## `atk git [args...]`
+
+Thin proxy that runs `git <args>` in ATK_HOME.
+
+### Behavior
+
+1. Resolve ATK_HOME (env var or `~/.atk/`)
+2. Validate ATK Home is initialized (exit 3 if not)
+3. Require git available (exit 7 if not)
+4. Execute `git <args>` in ATK_HOME with stdin/stdout/stderr passed through (no capture)
+5. Return git's exit code
+
+### Examples
+
+```bash
+atk git remote add origin git@github.com:user/dotfiles-atk.git
+atk git remote show origin
+atk git push
+atk git pull
+atk git log --oneline -5
+atk git status
+atk git diff
+```
+
+### Edge Cases
+
+- No arguments (`atk git`) — passes no args to git, which prints git help. Acceptable.
+- Interactive commands (`atk git rebase -i`) — works because stdin/stdout are passed through.
+- Destructive commands (`atk git reset --hard`) — user's responsibility. ATK does not guard against this.
+
+## `auto_push` Configuration
+
+New field in the manifest `config` section.
+
+### Manifest Schema
+
+```yaml
+config:
+  auto_commit: true    # Existing (default: true)
+  auto_push: false     # New (default: false)
+```
+
+### Rules
+
+| `auto_commit` | `auto_push` | Remote exists | Behavior |
+|---------------|-------------|---------------|----------|
+| true | true | yes | Commit + push |
+| true | true | no | Commit only, warn "no remote configured" |
+| true | false | any | Commit only (current behavior) |
+| false | true | any | Neither — `auto_push` requires `auto_commit` |
+| false | false | any | Neither (current behavior) |
+
+### Push Semantics
+
+- Pushes the current branch to its upstream tracking branch
+- Command: `git push` (no force, no explicit remote/branch — uses git defaults)
+- On failure: print warning to stderr, do not exit with error
+- On success: silent (consistent with auto_commit behavior)
+
+## Enhanced `atk status` — Repository Section
+
+After the plugin status table, `atk status` displays a repository section.
+
+### Output Format
+
+**With remote:**
+```
+Repository:
+  Branch:      main
+  Remote:      origin -> git@github.com:user/dotfiles-atk.git
+  Sync:        2 ahead, 0 behind
+  Last commit: Add plugin 'sasha-rules' (2m ago)
+  Working dir: clean
+```
+
+**Without remote:**
+```
+Repository:
+  Branch:      main
+  Remote:      (none)
+  Last commit: Add plugin 'sasha-rules' (2m ago)
+  Working dir: clean
+```
+
+**With dirty working directory:**
+```
+Repository:
+  Branch:      main
+  Remote:      origin -> git@github.com:user/dotfiles-atk.git
+  Sync:        0 ahead, 0 behind
+  Last commit: Initialize ATK Home (3d ago)
+  Working dir: 1 modified, 2 untracked
+```
+
+**No remote tracking branch:**
+```
+Repository:
+  Branch:      main
+  Remote:      origin -> git@github.com:user/dotfiles-atk.git
+  Sync:        (no tracking branch)
+  Last commit: Add plugin 'openmemory' (1h ago)
+  Working dir: clean
+```
+
+### Fields
+
+| Field | Source | Notes |
+|-------|--------|-------|
+| Branch | `git branch --show-current` | Current branch name |
+| Remote | `git remote get-url origin` | First remote name + URL. `(none)` if no remotes |
+| Sync | `git rev-list --left-right --count HEAD...@{upstream}` | Ahead/behind upstream. Omitted if no remote. `(no tracking branch)` if remote exists but no tracking |
+| Last commit | `git log -1 --format='%s (%cr)'` | Subject + relative time |
+| Working dir | `git status --porcelain` | `clean` if empty, otherwise count by category |
+
+### Error Handling
+
+If any git query fails (e.g., empty repo with no commits), the Repository section gracefully degrades — show what's available, skip what's not.
+
+## Auto-Push Wiring
+
+Mutations that auto-commit (`add`, `remove`, `upgrade`) gain auto-push:
+
+```
+mutation happens
+  -> if auto_commit:
+       git add -A
+       git commit -m "..."
+       -> if auto_push:
+            git push (best-effort, warn on failure)
+```
+
+### Warning Messages
+
+- No remote: `Warning: auto_push enabled but no remote configured. Run: atk git remote add origin <url>`
+- Push failed: `Warning: auto-push failed: <git error message>`
+
+## Exit Codes
+
+`atk git` uses git's own exit codes (passed through). No new ATK exit codes needed.
+
+For auto-push failures within mutations, the mutation still exits 0 (the commit succeeded).

{atk_cli-0.2.0 → atk_cli-0.2.1}/docs/specs/home-spec.md

@@ -96,6 +96,7 @@ schema_version: "2026-01-22"
 
 config:
   auto_commit: true               # Commit after mutations (default: true)
+  auto_push: false                # Push after auto-commit (default: false)
 
 plugins:
   - name: "OpenMemory"            # Display name (user-friendly)
@@ -165,6 +166,8 @@ Display names (`name` field) have no restrictions—they are for human readabili
 
 If `auto_commit: false`, user must manually commit changes.
 
+If `auto_push: true` and `auto_commit: true` and a remote is configured, ATK pushes after each auto-commit. Push failures warn but do not fail the mutation. If no remote is configured, auto-push silently no-ops with a warning.
+
 ## User Customizations
 
 Users customize plugins via the `custom/` directory inside each plugin.

{atk_cli-0.2.0 → atk_cli-0.2.1}/src/atk/add.py

@@ -10,11 +10,25 @@ from enum import Enum
 from pathlib import Path
 
 import atk.registry as registry_mod
-from atk.git import add_gitignore_exemption, git_add, git_commit, git_ls_remote, write_atk_ref
+from atk.git import (
+    add_gitignore_exemption,
+    git_add,
+    git_commit,
+    git_ls_remote,
+    git_push,
+    write_atk_ref,
+)
 from atk.git_source import fetch_git_plugin, normalize_git_url
 from atk.home import validate_atk_home
 from atk.lifecycle import LifecycleCommandNotDefinedError, run_lifecycle_command
-from atk.manifest_schema import PluginEntry, SourceInfo, SourceType, load_manifest, save_manifest
+from atk.manifest_schema import (
+    ConfigSection,
+    PluginEntry,
+    SourceInfo,
+    SourceType,
+    load_manifest,
+    save_manifest,
+)
 from atk.plugin import load_plugin_schema
 from atk.plugin_schema import PluginMaturity, PluginSchema
 from atk.sanitize import sanitize_directory_name
@@ -299,11 +313,13 @@ def _finalize_add(
         if source.ref:
             write_atk_ref(target_dir, source.ref)
 
-        auto_commit = _update_manifest(atk_home, schema.name, directory, source=source)
+        config = _update_manifest(atk_home, schema.name, directory, source=source)
 
-        if auto_commit:
+        if config.auto_commit:
             git_add(atk_home)
             git_commit(atk_home, f"Add plugin '{schema.name}'")
+            if config.auto_push:
+                git_push(atk_home)
 
         return directory
     except Exception:
@@ -338,7 +354,9 @@ def _cleanup_failed_add(atk_home: Path, target_dir: Path, directory: str, alread
         pass
 
 
-def _update_manifest(atk_home: Path, plugin_name: str, directory: str, source: SourceInfo) -> bool:
+def _update_manifest(
+    atk_home: Path, plugin_name: str, directory: str, source: SourceInfo,
+) -> ConfigSection:
     """Update manifest.yaml with new plugin entry.
 
     Args:
@@ -348,7 +366,7 @@ def _update_manifest(atk_home: Path, plugin_name: str, directory: str, source: S
         source: Source metadata (type, ref, url).
 
     Returns:
-        True if auto_commit is enabled in config, False otherwise.
+        The manifest's config section.
     """
     manifest = load_manifest(atk_home)
 
@@ -358,7 +376,7 @@ def _update_manifest(atk_home: Path, plugin_name: str, directory: str, source: S
     # Write back
     save_manifest(manifest, atk_home)
 
-    return manifest.config.auto_commit
+    return manifest.config
 
 
 

{atk_cli-0.2.0 → atk_cli-0.2.1}/src/atk/cli.py

@@ -13,6 +13,7 @@ from atk import __version__, cli_logger, exit_codes
 from atk.add import AddCancelledError, InstallFailedError, add_plugin
 from atk.banner import print_banner
 from atk.commands.lifecycle import run_lifecycle_cli, run_restart_single_cli, run_uninstall_cli
+from atk.commands.plug import plug_plugin, unplug_plugin
 from atk.commands.preconditions import (
     assert_plugin_or_all,
     require_git,
@@ -21,10 +22,9 @@ from atk.commands.preconditions import (
     require_ready_home,
     stdin_prompt,
 )
-from atk.commands.plug import plug_plugin, unplug_plugin
 from atk.commands.run import run_plugin_script
 from atk.commands.search import filter_registry_plugins, print_search_table
-from atk.commands.status import print_status_table
+from atk.commands.status import print_repo_status, print_status_table
 from atk.commands.upgrade import upgrade_all_plugins, upgrade_single_plugin
 from atk.errors import handle_cli_error
 from atk.git_source import GitPluginNotFoundError, GitSourceError
@@ -726,9 +726,10 @@ def status(
 
     if not results:
         cli_logger.dim("No plugins installed.")
-        raise typer.Exit(exit_codes.SUCCESS)
+    else:
+        print_status_table(results)
 
-    print_status_table(results)
+    print_repo_status(atk_home)
     raise typer.Exit(exit_codes.SUCCESS)
 
 
@@ -815,6 +816,33 @@ def run(
     run_plugin_script(plugin_dir, script, ctx.args)
 
 
+@app.command(
+    name="git",
+    context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
+)
+def git_proxy(ctx: typer.Context) -> None:
+    """Run git commands in ATK Home.
+
+    Thin proxy that passes all arguments to git executed in the ATK Home
+    directory. Useful for managing remotes, pushing, pulling, and inspecting
+    the repository without navigating to it.
+
+    Examples:
+        atk git remote add origin <url>
+        atk git push
+        atk git log --oneline -5
+    """
+    import subprocess
+
+    atk_home = require_ready_home()
+
+    result = subprocess.run(
+        ["git", *ctx.args],
+        cwd=atk_home,
+    )
+    raise typer.Exit(result.returncode)
+
+
 def _show_update_notice() -> None:
     """Show update notice if a newer version is available on PyPI.
 

{atk_cli-0.2.0 → atk_cli-0.2.1}/src/atk/commands/status.py

@@ -1,8 +1,19 @@
 """Status table rendering for the `atk status` command."""
 
+from __future__ import annotations
+
+from pathlib import Path
+
 from rich.console import Console
 from rich.table import Table
 
+from atk.git import (
+    git_ahead_behind,
+    git_get_branch,
+    git_get_remote_url,
+    git_last_commit_info,
+    git_working_dir_status,
+)
 from atk.lifecycle import PluginStatus, PluginStatusResult, PortStatus
 from atk.plugin_schema import PluginMaturity
 
@@ -121,3 +132,47 @@ def print_status_table(results: list[PluginStatusResult]) -> None:
                 "[dim]Note: Port checks verify if something is listening, not that it's the plugin.[/dim]"
             )
 
+
+def print_repo_status(atk_home: Path) -> None:
+    """Print git repository status section after the plugin table."""
+    console.print()
+    console.print("[bold]Repository:[/bold]")
+
+    # Branch
+    branch = git_get_branch(atk_home)
+    branch_str = branch if branch else "(detached)"
+    console.print(f"  Branch:      {branch_str}")
+
+    # Remote
+    remote_info = git_get_remote_url(atk_home)
+    if remote_info:
+        remote_name, remote_url = remote_info
+        console.print(f"  Remote:      {remote_name} -> {remote_url}")
+    else:
+        console.print("  Remote:      [dim](none)[/dim]")
+
+    # Sync (only if remote exists)
+    if remote_info:
+        ab = git_ahead_behind(atk_home)
+        if ab:
+            console.print(f"  Sync:        {ab.ahead} ahead, {ab.behind} behind")
+        else:
+            console.print("  Sync:        [dim](no tracking branch)[/dim]")
+
+    # Last commit
+    commit = git_last_commit_info(atk_home)
+    if commit:
+        console.print(f"  Last commit: {commit.subject} ({commit.relative_time})")
+
+    # Working directory
+    wd = git_working_dir_status(atk_home)
+    if wd.is_clean:
+        console.print("  Working dir: [green]clean[/green]")
+    else:
+        parts = []
+        if wd.modified:
+            parts.append(f"{wd.modified} modified")
+        if wd.untracked:
+            parts.append(f"{wd.untracked} untracked")
+        console.print(f"  Working dir: [yellow]{', '.join(parts)}[/yellow]")
+