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

{atk_cli-0.2.0 → atk_cli-0.3.0}/.gitignore

@@ -207,4 +207,10 @@ marimo/_lsp/
 __marimo__/
 
 .idea
-img
+img
+
+# Derived skill copies (source of truth: skills/)
+.claude/skills/
+
+# Codanna index
+.codanna/

atk_cli-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,90 @@
+# Contributing to ATK
+
+Thanks for your interest. ATK is an early-stage tool — contributions are welcome.
+
+## Getting started
+
+```bash
+git clone https://github.com/Svtoo/atk
+cd atk
+uv sync --dev
+make install-hooks   # Install pre-commit hook
+make sync-skills     # Copy skills to agent directories
+```
+
+## Development workflow
+
+### Pre-commit hook
+
+`make install-hooks` installs a git pre-commit hook that:
+
+1. Runs `make check` (ruff lint, mypy type-check, pytest) — commit is blocked if any fail
+2. Runs `make sync-skills` — copies skills to agent-specific directories
+
+The hook is local (`.git/hooks/pre-commit`) and not tracked in git. Run `make install-hooks` after cloning.
+
+### Skills
+
+ATK includes skills (structured prompts) for AI coding agents. The source of truth is `skills/<name>/SKILL.md` at the project root. Skills are agent-agnostic — they work with any agent that supports structured prompts.
+
+`make sync-skills` copies skills to agent-specific directories where they are discoverable:
+
+| Agent | Target directory | Discovery |
+|-------|-----------------|-----------|
+| Claude Code | `.claude/skills/<name>/SKILL.md` | Auto-discovered as `/name` slash commands |
+
+The agent directories (`.claude/skills/`) are gitignored — they contain derived copies, not source files. Always edit `skills/<name>/SKILL.md`, never the copies.
+
+To add a new skill: create `skills/<your-skill>/SKILL.md` and run `make sync-skills`.
+
+## Making changes
+
+- Open an issue first for non-trivial changes.
+- Keep PRs focused — one concern per PR.
+- Match existing code style (ruff + mypy strict).
+
+## Tests
+
+All code changes must include automated tests.
+
+```bash
+# Run the full test suite
+uv run pytest
+
+# Lint and type-check
+uv run ruff check src tests
+uv run mypy src
+
+# All of the above in one command
+make check
+```
+
+If you're adding a command or changing CLI behaviour, also test it manually:
+
+```bash
+uv run atk <your command>
+```
+
+The CI must pass before a PR is merged.
+
+## Releases
+
+Releases are managed via the `/release` skill (or `make release` for manual local builds). See `skills/release/SKILL.md` for the full process.
+
+Key points:
+- Versioning uses **hatch-vcs** — version is derived from git tags (`vX.Y.Z`), not hardcoded
+- CI runs on push to `main`; publish to PyPI triggers on tag push matching `v*.*.*`
+- PyPI does not allow re-uploads — once a version is published, it is permanent
+
+## Submitting a PR
+
+1. Fork and create a branch from `main`.
+2. Write or update tests for your change.
+3. Run `make check` — all must pass.
+4. Open a PR with a clear description of what changed and why.
+
+## Adding a registry plugin
+
+Submit a PR to [atk-registry](https://github.com/Svtoo/atk-registry), not this repo.
+See the registry README for schema requirements.
+

atk_cli-0.3.0/Makefile

@@ -0,0 +1,49 @@
+.PHONY: test check release install-local install-pypi uninstall sync-skills install-hooks
+
+# TDD cycle - run often
+test:
+	uv run pytest
+
+# Pre-commit validation - lint, type check, tests
+check:
+	uv run ruff check src tests
+	uv run mypy src
+	uv run pytest
+
+# Sync skills from skills/ to agent-specific directories
+# Source of truth: skills/<name>/SKILL.md
+# Currently supported agents: Claude Code (.claude/skills/)
+sync-skills:
+	@mkdir -p .claude/skills
+	@for dir in skills/*/; do \
+		name=$$(basename "$$dir"); \
+		mkdir -p ".claude/skills/$$name"; \
+		cp "$$dir"SKILL.md ".claude/skills/$$name/SKILL.md" 2>/dev/null || true; \
+	done
+	@echo "Skills synced to .claude/skills/"
+
+# Install git pre-commit hook that runs check + sync-skills
+install-hooks:
+	@echo '#!/bin/sh' > .git/hooks/pre-commit
+	@echo 'make check || exit 1' >> .git/hooks/pre-commit
+	@echo 'make sync-skills' >> .git/hooks/pre-commit
+	@chmod +x .git/hooks/pre-commit
+	@echo "Pre-commit hook installed."
+
+# Build and publish to PyPI
+release:
+	uv build
+	uv publish
+
+# Install from local source — editable, so changes are live without reinstalling
+install-local:
+	uv tool install --editable . --reinstall
+
+# Uninstall (works after either install-local or install-pypi)
+uninstall:
+	uv tool uninstall atk-cli
+
+# Install stable release from PyPI
+install-pypi:
+	uv tool install atk-cli --reinstall
+

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atk-cli
-Version: 0.2.0
+Version: 0.3.0
 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.3.0}/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.3.0}/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.3.0/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.3.0}/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.3.0/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.3.0}/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.3.0}/skills/create-atk-plugin/SKILL.md

@@ -248,6 +248,22 @@ mcp:
 **Idempotency rule**: Always build from scratch. Always `rm -rf` and fresh clone/install — no conditional
 "if exists, pull; else clone" logic.
 
+**External package managers silently skip when already installed — you MUST force re-install.** Bare
+`uv tool install pkg@latest`, `npm install -g pkg@latest`, and `pip install pkg` are no-ops once the
+package is present, even if upstream has shipped a newer version. The user runs `atk install <plugin>`
+expecting an upgrade and gets nothing. Required flags per manager:
+
+| Manager | Wrong (silently skips) | Right (always pulls latest) |
+|---|---|---|
+| uv tool | `uv tool install pkg@latest` | `uv tool install pkg@latest --reinstall` |
+| Homebrew | `brew install pkg` | `brew upgrade pkg \|\| brew install pkg` |
+| npm global | `npm install -g pkg@latest` | `npm install -g pkg@latest --force` |
+| pipx | `pipx install pkg` | `pipx install pkg --force` |
+| cargo | `cargo install pkg` | `cargo install pkg --force` |
+
+If your install relies on a `curl ... \| sh` install script (codanna-style), that's usually fine —
+those scripts typically replace the binary unconditionally. But verify before shipping.
+
 Use `set -e` in `install.sh`: fail fast on errors.
 
 ### start