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

{atk_cli-0.2.1 → 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.1 → atk_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atk-cli
-Version: 0.2.1
+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.1 → 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

atk_cli-0.3.0/skills/release/SKILL.md

@@ -0,0 +1,289 @@
+---
+name: release
+description: Create a new ATK release. Handles pre-flight checks, changelog generation, tagging, pushing, CI verification, and PyPI publication confirmation. Use when asked to cut a release, publish a new version, or ship changes.
+argument-hint: "[version, e.g. 0.3.0]"
+---
+
+# ATK Release Process
+
+You are performing a release of the `atk-cli` package. This is a critical operation — follow every step in order. Do not skip steps. Do not assume success — verify it.
+
+## Versioning Strategy
+
+ATK uses **hatch-vcs**: the version is derived from git tags at build time, not hardcoded.
+
+- Tags follow `vX.Y.Z` (e.g., `v0.2.1`)
+- **Patch** (`Z`): bug fixes, small features, non-breaking changes
+- **Minor** (`Y`): new user-facing features, new commands, behavioral changes
+- **Major** (`X`): breaking changes to CLI interface, manifest schema, or plugin API
+- Pre-`v1.0.0`: minor bumps are for significant milestones; patches are the norm
+
+PyPI receives the version without the `v` prefix (e.g., `0.2.1`).
+
+**CRITICAL**: PyPI does not allow re-uploads. If a version is published, it is permanent. Never force-move a tag that has been pushed. If a mistake is published, bump to the next patch.
+
+---
+
+## Step 0: Determine Version
+
+If version was provided as argument, use `v$ARGUMENTS`. Otherwise:
+
+1. Run `git tag --sort=-v:refname | head -1` to find the current latest tag
+2. Run `git log <latest-tag>..HEAD --oneline` to see what changed
+3. Classify the changes:
+   - Bug fixes only → **patch bump**
+   - New features, new commands → **minor bump**
+   - Breaking CLI/schema changes → **major bump**
+4. Present the proposed version to Sasha with reasoning. Wait for confirmation before proceeding.
+
+---
+
+## Step 1: Pre-Flight Checks
+
+Run ALL of these checks. If ANY fail, stop and report.
+
+### 1a. Clean working tree
+
+```bash
+git status --short
+```
+
+EXPECT: Empty output (no uncommitted changes). If dirty, stop — all changes must be committed before release.
+
+### 1b. On main branch
+
+```bash
+git branch --show-current
+```
+
+EXPECT: `main`. Releases are only cut from main.
+
+### 1c. Up to date with remote
+
+```bash
+git fetch origin main
+git rev-list HEAD..origin/main --count
+```
+
+EXPECT: `0` (no commits on origin/main that we don't have). If behind, stop — pull first.
+
+### 1d. Local checks pass
+
+```bash
+make check
+```
+
+EXPECT: Exit 0. This runs ruff (lint), mypy (types), and pytest (tests). All must be green.
+
+### 1e. CI is green on HEAD
+
+```bash
+gh run list --branch main --limit 3
+```
+
+EXPECT: The most recent CI run for HEAD is `completed` / `success`. If CI hasn't run for the current HEAD yet, wait or trigger it.
+
+### 1f. No open blockers
+
+Check if there are any issues/PRs that should block this release:
+
+```bash
+gh issue list --state open --label "blocker" --limit 5
+```
+
+If blockers exist, report them and ask Sasha whether to proceed.
+
+---
+
+## Step 2: Changelog Analysis
+
+Generate a thorough changelog by analyzing what changed since the last release.
+
+### 2a. Identify the last release
+
+```bash
+git tag --sort=-v:refname | head -1
+```
+
+### 2b. List all commits since last release
+
+```bash
+git log <last-tag>..HEAD --oneline --no-merges
+```
+
+### 2c. Detailed diff summary
+
+```bash
+git diff <last-tag>..HEAD --stat
+```
+
+### 2d. Categorize changes
+
+Read each commit and the diff. Organize into categories:
+
+- **New Features**: new commands, new config options, new behaviors
+- **Bug Fixes**: corrections to existing behavior
+- **Breaking Changes**: anything that changes existing CLI interface, manifest format, or plugin contract
+- **Documentation**: spec updates, roadmap changes, new phase docs
+- **Internal**: refactors, test improvements, CI changes
+
+### 2e. Draft release notes
+
+Write release notes in this format:
+
+```markdown
+## What's New
+
+### <Feature Name>
+<2-3 sentence description with usage example>
+
+### <Feature Name>
+...
+
+## Bug Fixes
+- <one-liner per fix>
+
+## Breaking Changes
+- <one-liner with migration guidance>
+
+## Upgrade
+
+\```bash
+pip install --upgrade atk-cli
+# or
+uv tool upgrade atk-cli
+\```
+
+<Any migration notes if needed>
+```
+
+Present the draft to Sasha for review before proceeding.
+
+---
+
+## Step 3: Manual Testing
+
+Before tagging, manually verify the key changes work. This is NOT optional.
+
+For each new feature or significant change:
+1. State what you're testing and why
+2. Run the actual command against a real (or temporary) ATK Home
+3. Verify the output matches expectations
+4. Report PASS or FAIL with evidence
+
+At minimum, always test:
+- `atk --version` outputs a valid version
+- `atk status` works without errors (if ATK Home exists)
+
+---
+
+## Step 4: Tag and Push
+
+Only proceed here if all previous steps passed and Sasha approved the release notes.
+
+### 4a. Create the tag
+
+```bash
+git tag v<VERSION>
+```
+
+### 4b. Push the commit and tag
+
+```bash
+git push origin main
+git push origin v<VERSION>
+```
+
+The tag push triggers the Publish to PyPI workflow automatically.
+
+---
+
+## Step 5: Wait for CI
+
+Both workflows must succeed before the release is complete.
+
+### 5a. Monitor CI workflow (triggered by push to main)
+
+```bash
+gh run list --branch main --limit 3
+```
+
+Wait until the CI run for the current commit shows `completed` / `success`.
+
+### 5b. Monitor Publish workflow (triggered by tag push)
+
+```bash
+gh run list --workflow publish.yml --limit 3
+```
+
+Wait until the publish run shows `completed` / `success`.
+
+If either workflow fails:
+1. Check logs: `gh run view <run-id> --log | tail -50`
+2. Report the failure to Sasha
+3. Do NOT proceed to creating the GitHub release
+4. If the publish failed, the tag is "burned" — PyPI may or may not have the version. Check with `curl -s https://pypi.org/pypi/atk-cli/<VERSION>/json` before deciding next steps.
+
+---
+
+## Step 6: Verify PyPI Publication
+
+```bash
+curl -s https://pypi.org/pypi/atk-cli/<VERSION>/json | python3 -c "import sys,json; d=json.load(sys.stdin); print('Version:', d['info']['version']); print('Summary:', d['info']['summary'])"
+```
+
+EXPECT: Version matches the release version. If this fails, the publish did not actually land on PyPI — investigate before creating the GitHub release.
+
+---
+
+## Step 7: Create GitHub Release
+
+```bash
+gh release create v<VERSION> --title "v<VERSION> — <Short Title>" --notes "<release notes from Step 2>"
+```
+
+Use a HEREDOC for multi-line notes:
+
+```bash
+gh release create v<VERSION> --title "v<VERSION> — <Title>" --notes "$(cat <<'EOF'
+<release notes here>
+EOF
+)"
+```
+
+---
+
+## Step 8: Post-Release Verification
+
+### 8a. Verify the release page exists
+
+```bash
+gh release view v<VERSION>
+```
+
+### 8b. Verify installability
+
+```bash
+uv pip install atk-cli==<VERSION> --dry-run
+```
+
+### 8c. Report completion
+
+Summarize to Sasha:
+- Version released
+- PyPI URL: `https://pypi.org/project/atk-cli/<VERSION>/`
+- GitHub release URL: `https://github.com/Svtoo/atk/releases/tag/v<VERSION>`
+- CI status: all green
+- Publish status: confirmed on PyPI
+
+---
+
+## Failure Recovery
+
+| Failure | Recovery |
+|---------|----------|
+| CI fails after tag push | Fix the issue, push fix to main, bump to next patch, re-tag |
+| Publish fails but PyPI has the version | The version is burned — create GitHub release as-is |
+| Publish fails and PyPI does NOT have it | Fix issue, delete the tag (`git tag -d v<X> && git push origin :refs/tags/v<X>`), re-tag same commit |
+| Wrong content released | Cannot re-upload to PyPI. Bump patch, fix, release again |
+| Tag pushed to wrong commit | If not yet on PyPI: delete remote tag, re-tag correct commit. If on PyPI: bump patch |

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

@@ -12,6 +12,7 @@ from rich.markdown import Markdown
 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.doctor import run_doctor
 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 (
@@ -361,6 +362,53 @@ def setup(
     raise typer.Exit(exit_codes.SUCCESS)
 
 
+@app.command()
+def doctor() -> None:
+    """Repair ATK Home: keep secrets gitignored and untrack any that leaked.
+
+    Fixes the historical bug where a local plugin's .env could be tracked
+    because its .gitignore exemption was ordered after the secret rule.
+    Safe to run anytime; idempotent.
+    """
+    atk_home = require_initialized_home()
+    manifest = load_manifest(atk_home)
+    if manifest.config.auto_commit:
+        require_git()
+
+    result = run_doctor(
+        atk_home,
+        auto_commit=manifest.config.auto_commit,
+        auto_push=manifest.config.auto_push,
+    )
+
+    if result.gitignore_fixed:
+        cli_logger.success("Re-ordered .gitignore so secret rules stay last")
+    else:
+        cli_logger.info(".gitignore already keeps secrets last")
+
+    if result.untracked_secrets:
+        cli_logger.warning(
+            f"Untracked {len(result.untracked_secrets)} secret file(s) "
+            "(kept on disk):"
+        )
+        for secret in result.untracked_secrets:
+            cli_logger.dim(f"  • {secret}")
+        cli_logger.warning(
+            "These were committed before — ROTATE the affected keys, and note "
+            "they remain in git history (rewrite history if you need them gone)."
+        )
+
+    if result.committed:
+        cli_logger.success("Committed the repair")
+    elif (result.gitignore_fixed or result.untracked_secrets) and not manifest.config.auto_commit:
+        cli_logger.info("Changes staged — commit them when ready (auto_commit is off)")
+
+    if not result.gitignore_fixed and not result.untracked_secrets:
+        cli_logger.success("Nothing to fix — ATK Home is healthy")
+
+    raise typer.Exit(exit_codes.SUCCESS)
+
+
 @app.command()
 def mcp(
     plugin: Annotated[

atk_cli-0.3.0/src/atk/commands/doctor.py

@@ -0,0 +1,75 @@
+"""`atk doctor` — repair an ATK Home's .gitignore and untrack leaked secrets.
+
+Historical bug: per-plugin `!plugins/<name>/**` exemptions were appended AFTER
+the `*.env` rule. Because .gitignore is last-match-wins, those exemptions
+re-included plugin .env files, which `atk add`'s auto-commit then committed.
+
+This migration re-orders the secret rules last (idempotent) and untracks any
+secret files that already slipped into the repo. It does NOT rotate keys or
+rewrite history — both are surfaced to the user as follow-ups.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from atk.git import (
+    git_add,
+    git_commit,
+    git_push,
+    git_rm_cached,
+    list_tracked_secrets,
+    normalize_gitignore,
+)
+
+
+@dataclass
+class DoctorResult:
+    """Outcome of a doctor run, for the CLI to report."""
+
+    gitignore_fixed: bool
+    untracked_secrets: list[str] = field(default_factory=list)
+    committed: bool = False
+
+
+def run_doctor(
+    atk_home: Path,
+    *,
+    auto_commit: bool,
+    auto_push: bool = False,
+) -> DoctorResult:
+    """Repair the ATK Home .gitignore and untrack any committed secret files.
+
+    Order matters: normalise the .gitignore FIRST so the secret files become
+    ignored, THEN `git rm --cached` them — that way the subsequent stage can't
+    re-add a now-ignored file. Commits the repair when auto_commit is on,
+    mirroring the add/remove commands.
+
+    Args:
+        atk_home: Path to the (initialized) ATK Home directory.
+        auto_commit: Whether to commit the repair (from manifest config).
+        auto_push: Whether to push after committing (subordinate to commit).
+
+    Returns:
+        DoctorResult describing what changed.
+    """
+    gitignore_fixed = normalize_gitignore(atk_home)
+
+    tracked_secrets = list_tracked_secrets(atk_home)
+    if tracked_secrets:
+        git_rm_cached(atk_home, tracked_secrets)
+    if gitignore_fixed:
+        git_add(atk_home, [".gitignore"])
+
+    committed = False
+    if (gitignore_fixed or tracked_secrets) and auto_commit:
+        committed = git_commit(atk_home, "atk doctor: keep secrets out of git")
+        if committed and auto_push:
+            git_push(atk_home)
+
+    return DoctorResult(
+        gitignore_fixed=gitignore_fixed,
+        untracked_secrets=tracked_secrets,
+        committed=committed,
+    )