aixand-skill-manager 0.1.0b0__tar.gz

aixand_skill_manager-0.1.0b0/.python-version

@@ -0,0 +1 @@
+3.11

aixand_skill_manager-0.1.0b0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

aixand_skill_manager-0.1.0b0/MANIFEST.in

@@ -0,0 +1,9 @@
+include README.md
+include dev.py dev.sh dev.ps1
+recursive-include docs *
+recursive-include examples *
+recursive-include tests *.py
+recursive-include tests/fixtures *.json
+include dev.py dev.sh dev.ps1 development.toml requirements-dev.lock .python-version
+global-exclude __pycache__ *.py[cod]
+include development-constraints.txt

aixand_skill_manager-0.1.0b0/PKG-INFO

@@ -0,0 +1,259 @@
+Metadata-Version: 2.4
+Name: aixand-skill-manager
+Version: 0.1.0b0
+Summary: Local native skill authoring, immutable whole-directory releases, and export
+License-Expression: Apache-2.0
+Project-URL: Repository, https://github.com/Aixand/manager-suite
+Project-URL: Issues, https://github.com/Aixand/manager-suite/issues
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aixand-prompt-manager<0.2,>=0.1.0b0
+Requires-Dist: aixand-lib-filesystem<0.2,>=0.1.0b0
+Requires-Dist: PyYAML<7,>=6.0.3
+Provides-Extra: github
+Requires-Dist: aixand-lib-github-source<0.2,>=0.1.0b0; extra == "github"
+Provides-Extra: dev
+Requires-Dist: build<2,>=1; extra == "dev"
+Dynamic: license-file
+
+# Skill Manager
+
+For automatic imports into manager-owned storage, publisher updates, user edits,
+and reconciliation, use [managed registrations](docs/managed.md). Existing source
+registration and draft APIs below retain their filesystem-authoring behavior.
+
+Development and installation work from this directory independently of the
+Manager Suite checkout. See [standalone development](docs/development.md).
+
+Standalone local management of native `SKILL.md` directories. Installable as
+`aixand-skill-manager==0.1.0b0`; import `skill_manager`; run `skill-manager` or
+`python -m skill_manager`. Python 3.11+ and PyYAML 6.0.3–6.x are required. This MVP
+uses descriptor-relative access and locks on POSIX; atomic directory commits use
+Linux `renameat2(RENAME_NOREPLACE)` or macOS `renameatx_np(RENAME_EXCL)` with
+filesystem support. Unsupported environments
+receive a structured error before directory publication.
+
+Skill Manager registers explicit sources, inspects and edits drafts, validates
+native metadata, publishes whole-directory snapshots, compares versions, and
+exports to an explicit consumer directory. It works independently of Agent Manager,
+Suite, provider credentials, and model services.
+
+Accepted-content updates, reconciliation, and history use the public package
+lifecycle SDK from `aixand-prompt-manager>=0.1.0b0,<0.2`. The dependency is one-way:
+Prompt Manager remains independently usable and does not import Skill Manager.
+Native skill validation, manifests/blobs, release references, and filesystem
+export remain owned here. Existing stores require no migration. See
+[the integration contract](docs/prompt-manager-integration.md).
+
+GitHub acquisition is optional: install `aixand-skill-manager[github]` to use the
+standalone `aixand-lib-github-source` library. Creation, local imports, stored skills,
+history, and releases work without it. Skill Manager owns its acquisition policy
+and retained jobs. See
+[GitHub sources](docs/github-sources.md).
+
+Store locking and Windows pinned-path access use the standalone
+`aixand-lib-filesystem` library. The `.locks/store.lock` path and locking
+protocol coordinate concurrent store users.
+
+## Install and verify
+
+```sh
+python3 -m venv /tmp/skill-manager-env
+/tmp/skill-manager-env/bin/python -m pip install .
+/tmp/skill-manager-env/bin/skill-manager --help
+/tmp/skill-manager-env/bin/python -B -m unittest discover -s tests -v
+```
+
+Use a temporary home during experiments. Selection order is explicit `Manager(home)`
+or `--home`, then `SKILL_MANAGER_HOME`, then
+`${XDG_DATA_HOME:-~/.local/share}/aixand/manager/skill`. Construction, listing an absent
+store, and inspection do not create the store. Registration persists paths and
+ownership metadata without copying source files. Sources default to read-only.
+
+## Public library
+
+The [version 1 Python SDK](docs/python-sdk.md) provides explicit per-skill handles,
+registration returning effective content/status, and revision-pinned resolutions.
+The [project connection workflow](docs/projects.md) adds nested collection import,
+explicit project skill directories, guarded updates, project variants, and recovery.
+The existing record APIs below retain JSON-compatible mapping/list results;
+file reads return original bytes. `SkillError(code, message, *, uncertain=False,
+operation_id=None, recovery=None)` exposes those attributes and `to_dict()`.
+
+```python
+from pathlib import Path
+from skill_manager import Manager
+
+m = Manager("/tmp/skill-store")
+root = Path("/tmp/my-skills")
+root.mkdir(exist_ok=True)
+m.register_source("local", [root], writable=True, owner={"kind": "local"})
+entry = m.create_draft("local", "review-notes", {
+    "SKILL.md": {"content": b"---\nname: review-notes\ndescription: Review notes when preparing a meeting.\n---\nRead the supplied notes.\n",
+                 "executable": False},
+    "references/checklist.md": {"content": b"Check dates and unresolved actions.\n",
+                                "executable": False},
+})
+edited = m.save_file(entry["id"], "references/checklist.md",
+                     b"Check dates, owners, and unresolved actions.\n",
+                     expected_digest=entry["digest"])
+assert m.validate(edited["id"])["valid"]
+release = m.release(edited["id"], "v1", expected_digest=edited["digest"])
+resolved = m.resolve(release["reference"])
+receipt = m.export(resolved["reference"], "/tmp/review-notes")
+assert receipt["digest"] == release["digest"]
+```
+
+| Method | Arguments and behavior |
+| --- | --- |
+| `register_source` | `(identifier, paths, *, label=None, writable=False, owner=None, expected_revision=None)`; create-only with null guard; existing registration needs its observed revision. |
+| `source`, `sources` | `(identifier)` / `()`; include location availability; corrupt registrations remain isolated in lists. |
+| `unregister_source` | `(identifier, *, expected_revision)`; removes registration, retains files and releases. |
+| `catalog` | `()`; source descriptors and source-scoped draft entries, with isolated diagnostics. |
+| `show`, `read_file`, `validate` | `(entry_id_or_release)` / `(entry_id_or_release, relative_path)` / `(entry_id_or_release)`; inspection, bytes, and validation. |
+| `create_draft` | `(source_id, name, files, *, path=None)`; each file supplies `content: bytes`, `executable: bool`; `path` selects a registered root when several exist. |
+| `save_file` | `(entry_id, relative_path, content, *, executable=False, expected_digest)`; add/replace one file under a complete-draft guard. |
+| `release` | `(entry_id, version, *, expected_digest)`; explicit publication; immutable label. |
+| `resolve` | `(reference)`; validates captured manifest and blobs, independent of sources. |
+| `releases` | `(source_id=None, name=None)`; retained versions, including removed sources, with isolated errors. |
+| `diff` | `(before, after)`; draft IDs or release references; all file, permission, directory, and metadata changes. |
+| `export` | `(reference, destination)`; absent package directory or identical existing package. |
+
+Select drafts by the catalog `id`; names alone are ambiguous. Entry identity includes
+the store, source ID, and canonical absolute package directory. Discovery checks a
+registered root containing `SKILL.md`, otherwise its immediate directory children
+containing `SKILL.md`. It never recursively searches projects. Missing registrations
+and unavailable roots remain visible. Pointing at an existing skill supports direct
+inspection; draft creation requires a collection root.
+
+For an explicit fork of a plugin skill, read its files through `read_file`, retain
+the manifest executable flags, and pass them to `create_draft` in a writable source.
+Create any empty supporting directories separately; inspection and release capture
+them. Ordinary catalog, inspection, and validation do not edit plugin caches.
+
+Invalid frontmatter remains editable with `digest_kind="draft-files"`; the repair
+digest covers all raw files and directories. Complete valid drafts use
+`digest_kind="package"`. Publication requires complete metadata and containment
+validation. Filesystem hazards without a safe digest require explicit filesystem
+repair (for example, removing a symlink) before guarded editing. Deleting `SKILL.md`
+removes an external directory from bounded discovery; restore it directly before
+selecting the draft again. Existing published releases remain independent.
+
+## CLI
+
+Results are strict JSON by default; `--json` is accepted at each command. Errors
+are JSON on stderr. Exit codes: 0 success, 2 validation/conflict/not-found or an
+invalid validation result, 3 unsupported, 4 uncertain, 1 other operational failure.
+Argument syntax errors are structured validation errors with exit 2. JSON inputs accept inline JSON or
+`@PATH`; `none` is the explicit null revision token.
+
+```sh
+skill-manager --home /tmp/skill-store source register examples ./examples --json
+skill-manager --home /tmp/skill-store source list --json
+skill-manager --home /tmp/skill-store source show examples --json
+skill-manager --home /tmp/skill-store catalog --json
+# Copy the entry id and digest from the catalog result:
+skill-manager --home /tmp/skill-store show ENTRY --json
+skill-manager --home /tmp/skill-store show ENTRY --file assets/badge.png --json
+skill-manager --home /tmp/skill-store validate ENTRY --json
+skill-manager --home /tmp/skill-store release ENTRY --version v1 --expected-digest DIGEST --json
+skill-manager --home /tmp/skill-store releases --source examples --name csv-audit --json
+skill-manager --home /tmp/skill-store resolve examples/csv-audit@v1 --json
+skill-manager --home /tmp/skill-store diff examples/csv-audit@v1 ENTRY --json
+skill-manager --home /tmp/skill-store export examples/csv-audit@v1 /tmp/csv-audit --json
+```
+
+Writable authoring also supports `draft create SOURCE NAME --files @files.json`
+with `{ "SKILL.md": { "content_b64": "...", "executable": false } }`, and
+`draft save ENTRY RELATIVE --file PATH --expected-digest DIGEST [--executable]`.
+Remove a registration with `source unregister ID --expected-revision REV`.
+Replacing a source registration requires that same guard; `--writable` is explicit
+on each replacement.
+
+## Format, release, and export contract
+
+Native frontmatter follows the [Agent Skills specification](https://agentskills.io/specification).
+Required fields are `name` and `description`; optional fields are `license`,
+`compatibility`, string-to-string `metadata`, and string `allowed-tools`. The name
+matches the package basename. Safe YAML rejects duplicate keys, custom object tags,
+aliases, and anchors. Unknown fields belong inside `metadata`. These restrictions
+keep validation deterministic and bounded. Instructions and supporting content
+remain original bytes; validation never executes scripts or calls a model.
+
+All symlinks and special files are rejected, including internal symlinks and resource
+root ancestors that are symlinks. No-follow descriptor-relative reads recheck types
+and containment. Portable paths reject absolute/drive paths, backslashes, traversal,
+control characters, Windows reserved components, trailing dots/spaces, and case or
+Unicode normalization collisions. Hidden regular files and all supporting directories,
+including empty directories, are included.
+
+The `skill-manager/package-1` manifest contains exactly `schema`, `name`, `metadata`,
+sorted `directories`, and sorted `files`. Each file records `path`, raw byte `size`,
+raw-byte `digest`, and `executable`. Any native execute bit means executable; exports
+use 0755/0644 files and 0755 directories. Timestamps, ownership, and other permission
+bits do not affect the identity. The package digest hashes the entire strict canonical
+UTF-8 JSON manifest. Script-only, asset-only, executable-only, and directory-only
+changes therefore change its identity. See [storage details](docs/storage.md).
+
+Release references are `source/name@version` or `source/name@sha256:HEX`.
+Resolve an older label explicitly to select its previous content. A label can never
+be rebound. Repeating publication with the same label/content returns the original
+record. Digest references require an existing publication in that source/name
+namespace and return the lexicographically first matching label's captured
+publication provenance. Source unregister/removal/reuse cannot rewrite that record.
+
+Export requires an existing caller-owned parent and a destination basename equal to
+the recorded name. The complete staged sibling package is verified before atomic
+no-replace publication. Different existing content is a conflict; there is no merge
+or overwrite. An identical existing package succeeds with `status="identical"`.
+Failure preserves previous destination content, including a competing empty directory.
+
+Limits: 4096 file/directory entries, 64 MiB per file, 256 MiB total bytes, 32 path
+components, 4096 UTF-8 path bytes, 255 bytes per component, 1 MiB `SKILL.md` metadata
+inspection, and 64 MiB per stored JSON record. Exceeding a limit gives an actionable
+diagnostic. Captures hold bytes in memory. These are local MVP limits, not additional
+requirements of the Agent Skills specification.
+
+Store mutations use one advisory lock per canonical store, serializing revision
+comparison and commit. Directory publication also rejects noncooperating competing
+destinations. Source writers outside Skill Manager are detected through capture
+checks; they do not participate in its advisory lock. Files are fsynced before
+commit; full power-loss durability, hostile-writer synchronization across stores,
+and automatic orphan-blob/staging garbage collection are outside this MVP.
+
+The [CSV audit example](examples/csv-audit/SKILL.md) includes a script, reference,
+CSV, binary PNG, hidden settings, and an empty supporting directory. Provider-native
+activation and managed profile assignments belong to Agent Manager. No skill
+flattening into developer instructions, remote synchronization, marketplace,
+cloud hosting, or plugin-manager implementation is included.
+
+## Local developer commands
+
+Inside the manager-suites source checkout, run from this directory with
+Python 3.11+ and uv:
+
+```sh
+./dev.sh develop --local
+./dev.sh check
+./dev.sh test
+./dev.sh build
+```
+
+Use `.\dev.ps1` on Windows. Each package owns its development environment and
+helper; these commands do not invoke suite-wide checks. See the
+[development guide](docs/development.md) for wheel-based setup without sibling
+sources, lock updates, build outputs, and the separate suite release lifecycle.
+
+### Default storage location
+
+The default product directory is `${XDG_DATA_HOME:-~/.local/share}/aixand/manager/skill`.
+Set `AIXAND_MANAGER_ROOT=/custom/managers` to use `/custom/managers/skill`
+without changing the data location of unrelated applications. Unset, empty, or
+relative `XDG_DATA_HOME` values fall back to `~/.local/share`.
+Explicit CLI/SDK paths and product-specific environment overrides take precedence;
+these paths are used directly. Existing configured storage paths remain supported.
+Agent and Conversation config overrides remain separate from their state-home overrides.
+Default path resolution creates no directories and does not move or adopt old stores.
+To keep using an existing store, supply its original path explicitly. Native provider
+homes connected by the user and operating-system temporary files retain their locations.