skill-automation-package 0.2.2 → 0.3.0

package/README.md

@@ -2,6 +2,20 @@
 
 Portable repo-local skill automation for Codex and Claude Code.
 
+## Quick Start
+
+Install into the repository you are already in, then use the installed runtime immediately. The package is `npx`-first, but the installed runtime still uses Python 3.10+.
+
+```bash
+cd your-repo
+npx skill-automation-package install --target .
+python3 .claude/tools/skill_agent.py auto "add tests" --json
+```
+
+- no setup required beyond `npx` and Python 3.10+
+- works on existing repositories
+- safe: uses bounded managed blocks for generated guidance and ignore rules
+
 The published npm package is `skill-automation-package`. It is a thin installer frontend over the same Python-based automation bundle; the runtime and install core still live in Python.
 This remains a Python-installed automation bundle, not an npm runtime package.
 
@@ -18,14 +32,7 @@ After installation, an agent can:
 - archive low-value skills that stay unused long enough to become cleanup candidates
 - route future Codex and Claude Code sessions through the same workflow
 
-## What It Installs
-
-- `.claude/tools/skill_agent.py`
-- five packaged core default skills under `.claude/skills/`: `project-skill-router/` plus read-only helpers for project summary, repo structure analysis, docs entrypoint guidance, and change summary
-- optional `.claude/tests/test_skill_agent.py`
-- managed automation blocks for `AGENTS.md` and `CLAUDE.md`
-
-## Quick Start
+## Basic Flow
 
 Use the published package to install into another repository:
 
@@ -41,16 +48,10 @@ npx skill-automation-package update --target /path/to/target-repo
 
 Python 3.10 or newer is still required. The npm entrypoint is a thin wrapper around the Python installer and does not replace the Python core.
 
-If you already have this repository checked out locally, the direct Python install path remains fully supported:
-
-```bash
-python3 scripts/install.py --target /path/to/target-repo
-```
-
 `install` always allows reinstall. `update` is version-aware and only reinstalls when the target reports an older installed version.
 Before reinstalling, the wrapper checks `.claude/skill-automation-package.json` in the target repo and reports whether the target is not installed, already at the current version, or behind the current package version.
 
-The installer copies the packaged assets, updates managed blocks in `AGENTS.md` and `CLAUDE.md` unless skipped, writes `.claude/skill-automation-package.json`, and refreshes `.claude/skills/registry.json`.
+The installer copies the packaged assets, updates managed blocks in `AGENTS.md` and `CLAUDE.md` unless skipped, updates a generated-state `.gitignore` block unless disabled, writes `.claude/skill-automation-package.json`, and refreshes `.claude/skills/registry.json`.
 
 Then, inside the target repository, start non-trivial work with:
 
@@ -64,6 +65,13 @@ If you want a preview before writing files:
 python3 .claude/tools/skill_agent.py auto "<task>" --dry-run --json
 ```
 
+## What It Installs
+
+- `.claude/tools/skill_agent.py`
+- five packaged core default skills under `.claude/skills/`: `project-skill-router/` plus read-only helpers for project summary, repo structure analysis, docs entrypoint guidance, and change summary
+- optional `.claude/tests/test_skill_agent.py`
+- managed automation blocks for `AGENTS.md` and `CLAUDE.md`
+
 ## Example Outcomes
 
 Representative `auto` outcomes look like this.
@@ -97,7 +105,7 @@ Create a new skill when no strong match exists:
 
 The exact skill name is inferred from the task, but the flow is stable: reuse when there is a strong match, otherwise scaffold a new reusable local skill and refresh the registry immediately.
 
-## Installation Guide
+## Advanced Installation
 
 Use this package when you want to install the automation bundle into another repository. The published npm package is the default entrypoint, and the direct Python path remains available when you are working from a local checkout of this repository.
 
@@ -118,18 +126,21 @@ Use this package when you want to install the automation bundle into another rep
 npx skill-automation-package install --target /path/to/target-repo
 ```
 
-3. Or, if you already have this repository checked out locally, run the Python installer directly:
+### Manual Installation
+
+If you already have this repository checked out locally, the direct Python install path remains fully supported:
 
 ```bash
 python3 scripts/install.py --target /path/to/target-repo
 ```
 
-4. The installer will:
+### What The Installer Writes
 
 - copy `.claude/tools/skill_agent.py`
 - copy the packaged core default skills under `.claude/skills/`
 - optionally copy `.claude/tests/test_skill_agent.py`
 - insert managed automation blocks into `AGENTS.md` and `CLAUDE.md`
+- insert a managed generated-state block into `.gitignore` unless disabled
 - write `.claude/skill-automation-package.json`
 - refresh `.claude/skills/registry.json`
 
@@ -175,17 +186,24 @@ You should see the packaged core skills in the list, including the router, and `
 - Skip the packaged test file: `python3 scripts/install.py --target /path/to/target-repo --no-tests`
 - Skip managed `AGENTS.md`: `python3 scripts/install.py --target /path/to/target-repo --skip-agents`
 - Skip managed `CLAUDE.md`: `python3 scripts/install.py --target /path/to/target-repo --skip-claude`
+- Disable `.gitignore` updates: `python3 scripts/install.py --target /path/to/target-repo --gitignore-mode none`
+- Ignore the whole local-only install: `python3 scripts/install.py --target /path/to/target-repo --gitignore-mode local-only`
 
 ## Managed File Behavior
 
 - If `AGENTS.md` or `CLAUDE.md` does not exist, install creates the file and inserts the managed block.
 - If both package markers already exist, install replaces only the content inside that managed block.
 - If the markers are missing, install appends the managed block to the end of the existing file.
+- By default, install also creates or updates a managed `.gitignore` block for generated state only.
+- Use `--gitignore-mode none` to leave `.gitignore` untouched, or `--gitignore-mode local-only` when the whole install should stay local to one checkout.
 - `--dry-run` previews the install result without creating the target directory or writing package files, and its status lines use `Would ...` wording for changes that are only being previewed.
+- Dry-run output includes package file groups for files that would be created, updated, left unchanged, or reported as previously installed but no longer shipped.
+- Dry-run output also reports whether each managed guidance file would be created, replaced, appended, left unchanged, or skipped.
 
 ## Target Repo Git Hygiene
 
 Decide up front whether the installed automation should be shared through version control or kept local to one checkout.
+The default installer policy is shared-friendly: it adds only generated-state patterns to `.gitignore`.
 
 ### Shared Automation In Version Control
 
@@ -198,7 +216,7 @@ Usually commit:
 - `.claude/tests/test_skill_agent.py` when installed
 - `AGENTS.md` and `CLAUDE.md` when you want the managed guidance blocks shared with the team
 
-Usually ignore:
+The installer adds this generated-state block by default:
 
 ```gitignore
 .claude/skills/registry.json
@@ -219,10 +237,11 @@ Use this when the install is only for one developer checkout and should not affe
 
 Typical approach:
 
-- install with `--skip-agents --skip-claude` if you do not want top-level guidance files touched
+- install with `--gitignore-mode local-only`
+- add `--skip-agents --skip-claude` if you do not want top-level guidance files touched
 - ignore the installed automation tree and any optional managed docs
 
-Example:
+The local-only mode manages this block:
 
 ```gitignore
 .claude/
@@ -257,7 +276,17 @@ npx skill-automation-package update --target /path/to/target-repo
 
 - `update` is a version-aware reinstall, not a partial update.
 - `update` blocks implicit downgrade attempts; use `install` only when you intentionally want to replace the target with the current package version.
-- If install metadata is malformed, `update` stops and asks you to use `install` for a deliberate reinstall.
+- If install metadata is malformed, incomplete, for a different package, or missing a usable asset list, `update` stops and asks you to use `install` for a deliberate reinstall.
+
+Metadata recovery behavior:
+
+| State | `install` behavior | `update` behavior |
+| --- | --- | --- |
+| Missing metadata | Proceeds as a new install | Stops and asks for `install` |
+| Same version | Reinstalls deliberately | No-ops |
+| Older version | Reinstalls deliberately | Runs reinstall |
+| Newer version | Warns and reinstalls deliberately | Blocks downgrade |
+| Malformed or incomplete metadata | Warns and reinstalls deliberately | Stops and asks for `install` |
 
 What gets updated in place:
 
@@ -364,6 +393,18 @@ Do not update `CLAUDE.md`:
 python3 scripts/install.py --target /path/to/target-repo --skip-claude
 ```
 
+Do not update `.gitignore`:
+
+```bash
+python3 scripts/install.py --target /path/to/target-repo --gitignore-mode none
+```
+
+Use a local-only `.gitignore` policy:
+
+```bash
+python3 scripts/install.py --target /path/to/target-repo --gitignore-mode local-only
+```
+
 ## Package Layout
 
 - `assets/.claude/tools/skill_agent.py`: resolver, search, scaffold, usage tracking, refresh review/update, and prune CLI

package/bin/skill-automation-package.js

@@ -7,6 +7,7 @@ const fs = require("fs");
 const path = require("path");
 
 const MIN_PYTHON = { major: 3, minor: 10 };
+const PACKAGE_NAME = "skill-automation-package";
 const INSTALL_METADATA_PATH = path.join(".claude", "skill-automation-package.json");
 
 function main() {
@@ -145,10 +146,35 @@ function detectInstallState(targetRoot, currentVersion) {
   try {
     const raw = fs.readFileSync(metadataPath, "utf8");
     const metadata = JSON.parse(raw);
+    if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
+      return { status: "unknown", targetRoot, metadataPath, reason: "invalid-shape" };
+    }
+
+    if (typeof metadata.name !== "string" || metadata.name.trim() === "") {
+      return { status: "unknown", targetRoot, metadataPath, reason: "missing-name" };
+    }
+    const installedName = metadata.name.trim();
+    if (installedName !== PACKAGE_NAME) {
+      return {
+        status: "unknown",
+        targetRoot,
+        metadataPath,
+        reason: "wrong-package",
+        installedName,
+      };
+    }
+
     if (typeof metadata.version !== "string" || metadata.version.trim() === "") {
       return { status: "unknown", targetRoot, metadataPath, reason: "missing-version" };
     }
 
+    if (!Array.isArray(metadata.assets)) {
+      return { status: "unknown", targetRoot, metadataPath, reason: "invalid-assets" };
+    }
+    if (!metadata.assets.every((asset) => typeof asset === "string" && asset.trim() !== "")) {
+      return { status: "unknown", targetRoot, metadataPath, reason: "invalid-assets" };
+    }
+
     const installedVersion = metadata.version.trim();
     const installedParsed = parseVersion(installedVersion);
     const currentParsed = parseVersion(currentVersion);
@@ -252,12 +278,7 @@ function printLifecycleSafety() {
 
 function describeUnknownMetadata(state, mode, currentVersion) {
   const metadataPath = state?.metadataPath || INSTALL_METADATA_PATH;
-  const reasonLabel = {
-    "invalid-json": "could not be parsed as JSON",
-    "missing-version": "does not contain a usable version",
-    "invalid-version": "contains a version that could not be compared",
-  };
-  const detail = reasonLabel[state?.reason] || "could not be compared";
+  const detail = describeMetadataProblem(state);
 
   if (mode === "install") {
     return `skill-automation-package: existing install metadata at ${metadataPath} ${detail}; reinstalling with version ${currentVersion}.`;
@@ -266,6 +287,19 @@ function describeUnknownMetadata(state, mode, currentVersion) {
   return `skill-automation-package: existing install metadata at ${metadataPath} ${detail}; use install to force a reinstall.`;
 }
 
+function describeMetadataProblem(state) {
+  const reasonLabel = {
+    "invalid-json": "could not be parsed as JSON",
+    "invalid-shape": "is not a JSON object",
+    "missing-name": "does not contain a usable package name",
+    "wrong-package": `belongs to package "${state?.installedName || "(unknown)"}" instead of ${PACKAGE_NAME}`,
+    "missing-version": "does not contain a usable version",
+    "invalid-version": "contains a version that could not be compared",
+    "invalid-assets": "does not contain a usable assets list",
+  };
+  return reasonLabel[state?.reason] || "could not be compared";
+}
+
 function printUsage(subcommand) {
   if (subcommand) {
     console.error(`skill-automation-package: unsupported subcommand "${subcommand}".`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skill-automation-package",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Portable repo-local skill automation bundle for Codex and Claude Code.",
   "bin": {
     "skill-automation-package": "bin/skill-automation-package.js"
@@ -29,8 +29,9 @@
     "test:wrapper": "node --test tests/node/wrapper.test.js",
     "test:assets": "PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s assets/.claude/tests -p 'test_*.py'",
     "install:dry-run": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/install.py --target /tmp/skill-automation-package-dry-run --dry-run",
+    "release:integrity": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/check_release_integrity.py",
     "sync-assets": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/sync_assets.py",
-    "release:check": "npm run test && npm run test:assets && npm run test:wrapper && npm run install:dry-run && npm pack --dry-run --cache /tmp/skill-automation-package-npm-cache"
+    "release:check": "npm run test && npm run test:assets && npm run test:wrapper && npm run release:integrity && npm run install:dry-run && npm pack --dry-run --cache /tmp/skill-automation-package-npm-cache"
   },
   "managed_assets": [
     ".claude/tools/skill_agent.py",

package/scripts/install.py

@@ -5,6 +5,7 @@ import argparse
 import json
 import subprocess
 import sys
+from dataclasses import dataclass
 from datetime import datetime
 from pathlib import Path
 
@@ -21,6 +22,7 @@ from package_layout import (
     PackageLayout,
     TEMPLATES_ROOT,
     copy_assets,
+    iter_asset_files,
     load_package_layout,
 )
 
@@ -34,6 +36,44 @@ CLAUDE_MARKERS = (
     "<!-- SKILL-AUTOMATION:CLAUDE:END -->",
 )
 
+GITIGNORE_MARKERS = (
+    "# SKILL-AUTOMATION:GITIGNORE:START",
+    "# SKILL-AUTOMATION:GITIGNORE:END",
+)
+
+GITIGNORE_PATTERNS = {
+    "generated": (
+        "# Generated skill automation state",
+        ".claude/skills/registry.json",
+        ".claude/skills/usage.json",
+        ".claude/skills/_archived/",
+        ".claude/skill-automation-package.json",
+        ".claude/**/__pycache__/",
+        ".claude/**/*.pyc",
+    ),
+    "local-only": (
+        "# Local-only skill automation install",
+        ".claude/",
+        "AGENTS.md",
+        "CLAUDE.md",
+    ),
+}
+
+
+@dataclass(frozen=True, slots=True)
+class ManagedBlockPlan:
+    changed: bool
+    state: str
+    updated: str
+
+
+@dataclass(frozen=True, slots=True)
+class PackageFilePreview:
+    would_create: tuple[Path, ...]
+    would_update: tuple[Path, ...]
+    unchanged: tuple[Path, ...]
+    stale: tuple[Path, ...]
+
 
 def main() -> int:
     parser = build_parser()
@@ -52,11 +92,11 @@ def main() -> int:
         executable_assets=layout.executable_assets,
         dry_run=args.dry_run,
     )
-    wrote_agents = False
-    wrote_claude = False
+    agents_plan = ManagedBlockPlan(changed=False, state="skipped", updated="")
+    claude_plan = ManagedBlockPlan(changed=False, state="skipped", updated="")
 
     if not args.skip_agents:
-        wrote_agents = install_managed_block(
+        agents_plan = install_managed_block(
             target_file=target / "AGENTS.md",
             template_path=TEMPLATES_ROOT / "agents_block.md",
             markers=AGENTS_MARKERS,
@@ -65,7 +105,7 @@ def main() -> int:
         )
 
     if not args.skip_claude:
-        wrote_claude = install_managed_block(
+        claude_plan = install_managed_block(
             target_file=target / "CLAUDE.md",
             template_path=TEMPLATES_ROOT / "claude_block.md",
             markers=CLAUDE_MARKERS,
@@ -73,6 +113,12 @@ def main() -> int:
             dry_run=args.dry_run,
         )
 
+    gitignore_plan = install_gitignore_block(
+        target_file=target / ".gitignore",
+        mode=args.gitignore_mode,
+        dry_run=args.dry_run,
+    )
+
     manifest_path = target / ".claude" / "skill-automation-package.json"
     wrote_manifest = write_install_manifest(
         manifest_path=manifest_path,
@@ -90,12 +136,26 @@ def main() -> int:
     agents_label = "Would update AGENTS.md" if args.dry_run else "Updated AGENTS.md"
     claude_label = "Would update CLAUDE.md" if args.dry_run else "Updated CLAUDE.md"
     manifest_label = "Would write install manifest" if args.dry_run else "Wrote install manifest"
+    copied_label = "Would copy files" if args.dry_run else "Copied files"
+    gitignore_label = "Would update .gitignore" if args.dry_run else "Updated .gitignore"
     print(f"Installed skill automation package {layout.version} into {target}")
-    print(f"Copied files: {len(copied_files)}")
-    print(f"{agents_label}: {'yes' if wrote_agents else 'no'}")
-    print(f"{claude_label}: {'yes' if wrote_claude else 'no'}")
+    print(f"{copied_label}: {len(copied_files)}")
+    print(f"{agents_label}: {'yes' if agents_plan.changed else 'no'}")
+    print(f"{claude_label}: {'yes' if claude_plan.changed else 'no'}")
+    print(f"{gitignore_label}: {'yes' if gitignore_plan.changed else 'no'}")
     print(f"{manifest_label}: {'yes' if wrote_manifest else 'no'}")
     print(f"Refreshed registry: {'yes' if refreshed else 'no'}")
+    if args.dry_run:
+        print_dry_run_preview(
+            build_package_file_preview(
+                layout=layout,
+                target_root=target,
+                asset_paths=selected_assets,
+            ),
+            agents_state=agents_plan.state,
+            claude_state=claude_plan.state,
+            gitignore_state=gitignore_plan.state,
+        )
     return 0
 
 
@@ -129,6 +189,16 @@ def build_parser() -> argparse.ArgumentParser:
         action="store_true",
         help="Preview the installation without writing files.",
     )
+    parser.add_argument(
+        "--gitignore-mode",
+        choices=("generated", "local-only", "none"),
+        default="generated",
+        help=(
+            "Manage a package-owned .gitignore block. `generated` ignores only "
+            "generated state, `local-only` ignores the whole local install, and "
+            "`none` leaves .gitignore untouched."
+        ),
+    )
     return parser
 
 
@@ -139,16 +209,85 @@ def install_managed_block(
     markers: tuple[str, str],
     title: str,
     dry_run: bool,
-) -> bool:
+) -> ManagedBlockPlan:
+    plan = build_managed_block_plan(
+        target_file=target_file,
+        template_path=template_path,
+        markers=markers,
+        title=title,
+    )
+    if not dry_run:
+        target_file.parent.mkdir(parents=True, exist_ok=True)
+        target_file.write_text(plan.updated, encoding="utf-8")
+    return plan
+
+
+def build_managed_block_plan(
+    *,
+    target_file: Path,
+    template_path: Path,
+    markers: tuple[str, str],
+    title: str,
+) -> ManagedBlockPlan:
     block = template_path.read_text(encoding="utf-8").strip() + "\n"
     start_marker, end_marker = markers
     existing = target_file.read_text(encoding="utf-8") if target_file.exists() else ""
     updated = upsert_block(existing, block, start_marker, end_marker, title)
+    state = classify_managed_block_state(existing, updated, start_marker, end_marker)
+    return ManagedBlockPlan(changed=updated != existing, state=state, updated=updated)
+
+
+def install_gitignore_block(
+    *,
+    target_file: Path,
+    mode: str,
+    dry_run: bool,
+) -> ManagedBlockPlan:
+    if mode == "none":
+        return ManagedBlockPlan(changed=False, state="skipped", updated="")
+
+    block = build_gitignore_block(mode)
+    existing = target_file.read_text(encoding="utf-8") if target_file.exists() else ""
+    updated = upsert_block(
+        existing,
+        block,
+        GITIGNORE_MARKERS[0],
+        GITIGNORE_MARKERS[1],
+        "",
+    )
+    state = classify_managed_block_state(
+        existing,
+        updated,
+        GITIGNORE_MARKERS[0],
+        GITIGNORE_MARKERS[1],
+    )
 
     if not dry_run:
         target_file.parent.mkdir(parents=True, exist_ok=True)
         target_file.write_text(updated, encoding="utf-8")
-    return updated != existing
+    return ManagedBlockPlan(changed=updated != existing, state=state, updated=updated)
+
+
+def build_gitignore_block(mode: str) -> str:
+    patterns = GITIGNORE_PATTERNS[mode]
+    return "\n".join([GITIGNORE_MARKERS[0], *patterns, GITIGNORE_MARKERS[1]]) + "\n"
+
+
+def classify_managed_block_state(
+    existing: str,
+    updated: str,
+    start_marker: str,
+    end_marker: str,
+) -> str:
+    if updated == existing:
+        return "unchanged"
+    if not existing.strip():
+        return "create"
+    start_index = existing.find(start_marker)
+    end_index = existing.find(end_marker)
+    if start_index != -1 and end_index != -1 and end_index >= start_index:
+        return "replace"
+    return "append"
 
 
 def upsert_block(
@@ -204,5 +343,94 @@ def refresh_registry(target: Path) -> None:
     )
 
 
+def build_package_file_preview(
+    *,
+    layout: PackageLayout,
+    target_root: Path,
+    asset_paths: list[Path],
+) -> PackageFilePreview:
+    current_assets: set[Path] = set()
+    would_create: list[Path] = []
+    would_update: list[Path] = []
+    unchanged: list[Path] = []
+
+    for source_path, relative_path in iter_asset_files(ASSETS_ROOT, asset_paths):
+        current_assets.add(relative_path)
+        target_path = target_root / relative_path
+        if not target_path.exists():
+            would_create.append(relative_path)
+            continue
+        if files_match(source_path, target_path):
+            unchanged.append(relative_path)
+            continue
+        would_update.append(relative_path)
+
+    stale = [
+        path
+        for path in read_previous_install_assets(target_root)
+        if path not in current_assets and (target_root / path).exists()
+    ]
+
+    return PackageFilePreview(
+        would_create=tuple(sorted(would_create)),
+        would_update=tuple(sorted(would_update)),
+        unchanged=tuple(sorted(unchanged)),
+        stale=tuple(sorted(stale)),
+    )
+
+
+def files_match(source_path: Path, target_path: Path) -> bool:
+    if not target_path.is_file():
+        return False
+    return source_path.read_bytes() == target_path.read_bytes()
+
+
+def read_previous_install_assets(target_root: Path) -> list[Path]:
+    manifest_path = target_root / ".claude" / "skill-automation-package.json"
+    if not manifest_path.exists():
+        return []
+    try:
+        payload = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return []
+    assets = payload.get("assets")
+    if not isinstance(assets, list):
+        return []
+
+    previous: list[Path] = []
+    for value in assets:
+        if not isinstance(value, str):
+            continue
+        path = Path(value)
+        if path.is_absolute():
+            continue
+        previous.append(path)
+    return previous
+
+
+def print_dry_run_preview(
+    preview: PackageFilePreview,
+    *,
+    agents_state: str,
+    claude_state: str,
+    gitignore_state: str,
+) -> None:
+    print("Package file preview:")
+    print_preview_paths("would create", preview.would_create)
+    print_preview_paths("would update", preview.would_update)
+    print_preview_paths("unchanged", preview.unchanged)
+    print_preview_paths("previously installed but no longer shipped", preview.stale)
+    print("Managed file preview:")
+    print(f"  AGENTS.md: {agents_state}")
+    print(f"  CLAUDE.md: {claude_state}")
+    print(f"  .gitignore: {gitignore_state}")
+
+
+def print_preview_paths(label: str, paths: tuple[Path, ...]) -> None:
+    print(f"  {label}: {len(paths)}")
+    for path in paths:
+        print(f"    - {path}")
+
+
 if __name__ == "__main__":
     raise SystemExit(main())