agentsquire 0.2.2__tar.gz

agentsquire-0.2.2/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/
+checkouts/
+
+# Local scratch / dev notes (never committed, never published)
+bugs.md
+feedback.md

agentsquire-0.2.2/CHANGELOG.md

@@ -0,0 +1,102 @@
+# Changelog
+
+All notable changes to AgentSquire are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project aims
+to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+The version is declared in two places that are kept in sync by the release
+tooling: `__version__` in `src/agentsquire/__init__.py` and `version` in
+`pyproject.toml`.
+
+## [0.2.2]
+
+### Changed
+- **Source distributions now ship an explicit, minimal file set.** The sdist is
+  scoped with `[tool.hatch.build.targets.sdist]` to `src/`, `tests/`,
+  `CHANGELOG.md`, and the two public docs (`docs/api.md`, `docs/harnesses.md`),
+  plus the always-included `pyproject.toml`/`README.md`/`LICENSE`. Previously the
+  sdist inherited hatchling's default (every VCS-tracked file), so
+  repository-only files could ride along; the wheel was already limited to the
+  package. This is a default-deny allowlist - files not listed never ship.
+
+## [0.2.1]
+
+### Fixed
+- **A pre-existing symlink at a target no longer crashes install/update or
+  gets clobbered (BUG-02).** The classifier and copy guard tested the target
+  with `Path.exists()`, which follows a symlink: a dangling link read as
+  not-installed and then `install` hit `FileExistsError`, while a live link
+  reached `shutil.rmtree` on `update --force` and raised "Cannot call rmtree
+  on a symbolic link". Detection now uses `is_symlink`, so a symlink (dangling
+  or live) classifies as `LOCALLY_MODIFIED` - present but not ours. `install`
+  and `update` (without `--force`) skip it with a reason naming the symlink;
+  `update --force` unlinks the link (never `rmtree`s through it) before
+  writing a real install; `uninstall` leaves it in place with a reason.
+  Symlinking skills into `~/.claude/skills` is a mainstream hand-wired setup,
+  so anyone migrating to `skills install` from it hit this on the first run.
+
+## [0.2.0] - 2026-07-10
+
+### Added
+- **`AGENTSQUIRE_HOME` / `AGENTSQUIRE_PROJECT` root overrides.** When
+  `check_stale` and the mounted `skills` subcommands are wired the production
+  way (no `home=`/`project=` arguments, so each invocation resolves the real
+  roots), these env vars redirect the home and project roots. A consumer's
+  CLI-level test can point the wired hook and the subcommands at fixture
+  directories by setting two variables instead of monkeypatching `Path.home`
+  and chdir. Explicit `home=`/`project=` arguments still take precedence; an
+  empty value is treated as unset (the `NO_COLOR` convention). Documented in
+  the `docs/api.md` "Testing your integration" section.
+
+### Fixed
+- **`check_stale` now surfaces the update notice on non-TTY stderr.** The
+  hook previously required stderr to be an interactive TTY, which silenced
+  it in exactly the case that matters most for an agent-skills tool: an
+  agent harness runs the consumer CLI with captured (non-TTY) stderr and so
+  never saw that an update was available. The interactive-TTY gate is
+  removed; `CI` and `AGENTSQUIRE_NO_UPDATE_CHECK` (presence-disables) remain
+  the escape hatches for pipelines and opt-out. README and `docs/api.md`
+  updated accordingly.
+
+## [0.1.0] - 2026-07-10
+
+Initial release.
+
+### Added
+- **Mountable `skills` command group.** `skills_command_group(package, ...)`
+  returns a ready-made click group with `install`, `status`, `update`, and
+  `uninstall` subcommands that a consumer CLI mounts under its own name, so
+  its users only ever see one tool (e.g. `awiki skills install`). Works with
+  click directly and with typer via `typer.main.get_command`. Every
+  subcommand takes `--scope user|project` and `--harness NAME`.
+- **Skills as package data.** Consumers ship SKILL.md directories (the
+  agentskills.io format) as package data inside their own wheel; skills are
+  enumerated straight from the installed wheel, no source checkout needed.
+  `BundledPackageDataSource` reads them, with structural validation against
+  the agentskills.io spec.
+- **Four harness backends.** Claude Code, pi, Hermes, and opencode, detected
+  by marker directory, each with user and project scopes. Directories and
+  behaviour are recorded in `docs/harnesses.md`; backends resolve exactly
+  the paths documented there.
+- **Copy-with-provenance install model.** Installs are plain copies - no
+  symlinks, no lockfile - stamped with an `agentsquire` provenance block
+  (installer, installer_version, source_package, source_version,
+  content_hash) in the installed SKILL.md frontmatter. The skill body stays
+  byte-identical to what was shipped.
+- **Hash-based status and safe updates.** `status` classifies each skill as
+  not-installed, up-to-date, update-available, or locally-modified using
+  local hash compares only (no network in any verb). `update` refreshes
+  update-available skills and skips locally modified ones unless `--force`;
+  `uninstall` removes only directories whose stamp names the consumer's
+  package. User content is never silently overwritten or deleted.
+- **Notice-only staleness hook.** `check_stale(source, prog_name=...,
+  update_command=...)` prints a single stderr advisory when installed skills
+  are stale. It never prompts, never updates, never touches stdout or the
+  exit code, and swallows its own errors. Gated on stderr being a TTY, `CI`
+  unset or empty, and `AGENTSQUIRE_NO_UPDATE_CHECK` unset or empty.
+- **Python API.** Everything the CLI group does - enumerate, detect, install,
+  status, update, uninstall, staleness check - is available as plain Python;
+  see `docs/api.md`.
+- **`agentsquire.skills` entry-point group.** Consumers may register their
+  package under it; reserved for a future environment-wide listing, changes
+  no behaviour today.

agentsquire-0.2.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TacoTakumi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentsquire-0.2.2/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: agentsquire
+Version: 0.2.2
+Summary: Let a Python package carry its own agent integrations and install them into whatever agent harness is present.
+Author: TacoTakumi
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,agent-skills,claude-code,cli,harness,skills
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: click
+Requires-Dist: pyyaml
+Description-Content-Type: text/markdown
+
+# AgentSquire
+
+A reusable Python library + CLI that lets a Python package carry its own agent
+integrations (Agent Skills) and install them into whatever agent harness is
+present - the executable is the framework.
+
+Your CLI ships its skills as package data inside its own wheel, adds
+`agentsquire` as a plain pip dependency, and mounts a ready-made subcommand
+group. Your users only ever see your tool:
+
+```
+$ awiki skills install
+installed awiki-search -> /home/you/.claude/skills/awiki-search
+```
+
+Supported harnesses at launch: Claude Code, pi, Hermes, and opencode. Detection
+is by marker directory; every operation is local (no network in any verb). Each
+harness's directories, scopes, and behaviour are recorded in
+[docs/harnesses.md](docs/harnesses.md).
+
+## Consumer integration guide
+
+### 1. Ship skills as package data
+
+Lay each skill out as a directory containing a `SKILL.md` (the agentskills.io
+format) under a `skills/` resource inside your importable package:
+
+```
+your_pkg/
+    __init__.py
+    skills/
+        my-skill/
+            SKILL.md
+            reference.md
+```
+
+The skills ride inside your wheel; make sure your build backend includes
+package data (hatchling includes it by default, setuptools needs
+`include-package-data`). No source checkout is needed at run time - skills are
+enumerated straight from the installed wheel.
+
+### 2. Mount the subcommand group
+
+One call returns a click group with `install`, `status`, `update`, and
+`uninstall` subcommands, parameterized by your package name, the resource path
+(default `"skills"`), and the default scope.
+
+For a click CLI:
+
+```python
+import click
+
+from agentsquire.cli import skills_command_group
+
+
+@click.group()
+def cli():
+    """Your CLI."""
+
+
+cli.add_command(skills_command_group("your_pkg", default_scope="user"))
+```
+
+For a typer CLI, mount onto the underlying click command:
+
+```python
+import typer
+import typer.main
+
+from agentsquire.cli import skills_command_group
+
+app = typer.Typer()
+
+
+@app.callback()
+def main():
+    """Your CLI."""
+
+
+cli = typer.main.get_command(app)
+cli.add_command(skills_command_group("your_pkg", default_scope="user"))
+```
+
+Your users now run `your-cli skills install` and friends. Every subcommand
+takes `--scope user|project` (overriding your declared default) and
+`--harness NAME` (default: all detected harnesses).
+
+Choosing the default scope: `user` installs into the harness's per-user
+skills directory and follows the user everywhere - right for general-purpose
+tools. `project` installs into the current project's directory - right for
+skills that only make sense inside a repository that uses your tool.
+
+### 3. Surface updates proactively (optional)
+
+Place the one-call staleness hook at your CLI entry point. When installed
+skills have updates available it prints a single advisory line on stderr,
+for example:
+
+    your-cli: a skills update is available for 1 skill (alpha); run `your-cli skills update`
+
+The hook is notice-only: it never prompts, never reads stdin, and never
+updates anything itself - the explicit `skills update` verb stays the sole
+updater. It writes nothing to stdout, never changes your exit code, and
+swallows its own errors, so it can never break the command it runs inside:
+
+```python
+from agentsquire import BundledPackageDataSource, check_stale
+
+
+def main():
+    check_stale(
+        BundledPackageDataSource("your_pkg"),
+        prog_name="your-cli",
+        update_command="your-cli skills update",
+    )
+    # ... the rest of your entry point
+```
+
+The notice shows unless a suppression gate holds: `CI` set to a non-empty
+value, or `AGENTSQUIRE_NO_UPDATE_CHECK` set to a non-empty value. It is not
+gated on an interactive terminal - it fires on non-TTY stderr too, so an
+agent harness that runs your CLI with captured stderr still sees that an
+update is available. Suppression is presence-disables, the `NO_COLOR`
+convention: any non-empty value disables the notice (`CI=false` and
+`AGENTSQUIRE_NO_UPDATE_CHECK=0` both suppress), while an empty string is
+treated as unset.
+
+### 4. Mark your package as skill-carrying (optional)
+
+One pyproject line registers your package under the `agentsquire.skills`
+entry-point group. Nothing reads it today - it is reserved for a future
+environment-wide listing of skill-carrying packages and changes no behaviour:
+
+```toml
+[project.entry-points."agentsquire.skills"]
+your_pkg = "your_pkg"
+```
+
+## The provenance and update model
+
+Installs are plain copies - no symlinks, no lockfile, no references back into
+site-packages - so an installed skill survives upgrade or removal of your
+package. Each installed `SKILL.md` carries a provenance stamp in its
+frontmatter `metadata.agentsquire` map: `installer`, `installer_version`,
+`source_package`, `source_version`, and `content_hash`. The skill body is
+byte-identical to what you shipped.
+
+`status` classifies every skill by local hash compares only (no network,
+ever): not-installed, up-to-date, update-available (your shipped copy moved
+on), or locally-modified (the user edited the install, the directory carries
+no stamp, or a symlink sits at the target - none of them ours to touch).
+`update` refreshes update-available skills and skips locally modified ones
+unless `--force` is given; `uninstall` removes only directories whose stamp
+names your package. User content is never silently overwritten or deleted -
+a pre-existing symlink at a target (a common hand-wired setup) is reported
+and skipped, never followed or clobbered.
+
+## Python API
+
+Everything the CLI group does is available as plain Python - enumerate,
+detect, install, status, update, uninstall, and the staleness check - with no
+CLI involved. See [docs/api.md](docs/api.md) for the reference.
+
+## License
+
+MIT.

agentsquire-0.2.2/README.md

@@ -0,0 +1,166 @@
+# AgentSquire
+
+A reusable Python library + CLI that lets a Python package carry its own agent
+integrations (Agent Skills) and install them into whatever agent harness is
+present - the executable is the framework.
+
+Your CLI ships its skills as package data inside its own wheel, adds
+`agentsquire` as a plain pip dependency, and mounts a ready-made subcommand
+group. Your users only ever see your tool:
+
+```
+$ awiki skills install
+installed awiki-search -> /home/you/.claude/skills/awiki-search
+```
+
+Supported harnesses at launch: Claude Code, pi, Hermes, and opencode. Detection
+is by marker directory; every operation is local (no network in any verb). Each
+harness's directories, scopes, and behaviour are recorded in
+[docs/harnesses.md](docs/harnesses.md).
+
+## Consumer integration guide
+
+### 1. Ship skills as package data
+
+Lay each skill out as a directory containing a `SKILL.md` (the agentskills.io
+format) under a `skills/` resource inside your importable package:
+
+```
+your_pkg/
+    __init__.py
+    skills/
+        my-skill/
+            SKILL.md
+            reference.md
+```
+
+The skills ride inside your wheel; make sure your build backend includes
+package data (hatchling includes it by default, setuptools needs
+`include-package-data`). No source checkout is needed at run time - skills are
+enumerated straight from the installed wheel.
+
+### 2. Mount the subcommand group
+
+One call returns a click group with `install`, `status`, `update`, and
+`uninstall` subcommands, parameterized by your package name, the resource path
+(default `"skills"`), and the default scope.
+
+For a click CLI:
+
+```python
+import click
+
+from agentsquire.cli import skills_command_group
+
+
+@click.group()
+def cli():
+    """Your CLI."""
+
+
+cli.add_command(skills_command_group("your_pkg", default_scope="user"))
+```
+
+For a typer CLI, mount onto the underlying click command:
+
+```python
+import typer
+import typer.main
+
+from agentsquire.cli import skills_command_group
+
+app = typer.Typer()
+
+
+@app.callback()
+def main():
+    """Your CLI."""
+
+
+cli = typer.main.get_command(app)
+cli.add_command(skills_command_group("your_pkg", default_scope="user"))
+```
+
+Your users now run `your-cli skills install` and friends. Every subcommand
+takes `--scope user|project` (overriding your declared default) and
+`--harness NAME` (default: all detected harnesses).
+
+Choosing the default scope: `user` installs into the harness's per-user
+skills directory and follows the user everywhere - right for general-purpose
+tools. `project` installs into the current project's directory - right for
+skills that only make sense inside a repository that uses your tool.
+
+### 3. Surface updates proactively (optional)
+
+Place the one-call staleness hook at your CLI entry point. When installed
+skills have updates available it prints a single advisory line on stderr,
+for example:
+
+    your-cli: a skills update is available for 1 skill (alpha); run `your-cli skills update`
+
+The hook is notice-only: it never prompts, never reads stdin, and never
+updates anything itself - the explicit `skills update` verb stays the sole
+updater. It writes nothing to stdout, never changes your exit code, and
+swallows its own errors, so it can never break the command it runs inside:
+
+```python
+from agentsquire import BundledPackageDataSource, check_stale
+
+
+def main():
+    check_stale(
+        BundledPackageDataSource("your_pkg"),
+        prog_name="your-cli",
+        update_command="your-cli skills update",
+    )
+    # ... the rest of your entry point
+```
+
+The notice shows unless a suppression gate holds: `CI` set to a non-empty
+value, or `AGENTSQUIRE_NO_UPDATE_CHECK` set to a non-empty value. It is not
+gated on an interactive terminal - it fires on non-TTY stderr too, so an
+agent harness that runs your CLI with captured stderr still sees that an
+update is available. Suppression is presence-disables, the `NO_COLOR`
+convention: any non-empty value disables the notice (`CI=false` and
+`AGENTSQUIRE_NO_UPDATE_CHECK=0` both suppress), while an empty string is
+treated as unset.
+
+### 4. Mark your package as skill-carrying (optional)
+
+One pyproject line registers your package under the `agentsquire.skills`
+entry-point group. Nothing reads it today - it is reserved for a future
+environment-wide listing of skill-carrying packages and changes no behaviour:
+
+```toml
+[project.entry-points."agentsquire.skills"]
+your_pkg = "your_pkg"
+```
+
+## The provenance and update model
+
+Installs are plain copies - no symlinks, no lockfile, no references back into
+site-packages - so an installed skill survives upgrade or removal of your
+package. Each installed `SKILL.md` carries a provenance stamp in its
+frontmatter `metadata.agentsquire` map: `installer`, `installer_version`,
+`source_package`, `source_version`, and `content_hash`. The skill body is
+byte-identical to what you shipped.
+
+`status` classifies every skill by local hash compares only (no network,
+ever): not-installed, up-to-date, update-available (your shipped copy moved
+on), or locally-modified (the user edited the install, the directory carries
+no stamp, or a symlink sits at the target - none of them ours to touch).
+`update` refreshes update-available skills and skips locally modified ones
+unless `--force` is given; `uninstall` removes only directories whose stamp
+names your package. User content is never silently overwritten or deleted -
+a pre-existing symlink at a target (a common hand-wired setup) is reported
+and skipped, never followed or clobbered.
+
+## Python API
+
+Everything the CLI group does is available as plain Python - enumerate,
+detect, install, status, update, uninstall, and the staleness check - with no
+CLI involved. See [docs/api.md](docs/api.md) for the reference.
+
+## License
+
+MIT.