degardis 1.0.0__tar.gz

degardis-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kambiz Khojasteh
+
+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.

degardis-1.0.0/MANIFEST.in

@@ -0,0 +1,4 @@
+graft docs
+graft examples
+graft tests
+global-exclude __pycache__ *.py[cod]

degardis-1.0.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: degardis
+Version: 1.0.0
+Summary: Compile validated Agent Skill sources into portable, installable bundles.
+Author: Kambiz Khojasteh
+License-Expression: MIT
+Project-URL: Documentation, https://github.com/Khojasteh/degardis/tree/main/docs
+Project-URL: Issues, https://github.com/Khojasteh/degardis/issues
+Project-URL: Repository, https://github.com/Khojasteh/degardis
+Keywords: agent-skills,ai-agents,cli,compiler
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Pillow<13,>=10
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: resvg_py<1.0,>=0.3
+Provides-Extra: release
+Requires-Dist: build>=1.2; extra == "release"
+Requires-Dist: twine>=6; extra == "release"
+Dynamic: license-file
+
+# Degardis
+
+Degardis is a command-line compiler for authors of portable Agent Skills. It
+turns structured YAML sources into self-contained bundles for Claude, Codex,
+Copilot, Cursor, Roo, and ChatGPT. Before writing an artifact, it validates the
+source, selected profiles, generated paths, and generated links.
+
+Authoring stays separate from generated output: edit the source files, validate
+them, and rebuild either an installable folder or a distributable ZIP.
+
+## Quick start
+
+Degardis requires Python 3.10 or later. Install it from PyPI:
+
+```console
+python -m pip install degardis
+degardis --version
+```
+
+For an isolated command-line installation, use `pipx install degardis`.
+
+To work on Degardis from this repository instead:
+
+```console
+python -m pip install -e .
+degardis validate examples/structured-summary
+degardis list examples/structured-summary
+degardis build examples/structured-summary --output .artifacts
+```
+
+The successful build ends with `Summary: 1 skill built as folder.` and reports
+the artifact path. The generated folder is ready to inspect or install:
+
+```text
+.artifacts/structured-summary/
+  SKILL.md
+  agents/openai.yaml
+  references/
+  scripts/
+  assets/
+```
+
+Degardis writes only beneath the requested output root. Rebuilding a skill
+replaces that skill's existing folder and ZIP there, while preserving unrelated
+entries. See [Artifact format](https://github.com/Khojasteh/degardis/blob/main/docs/artifact-format.md#replace-an-artifact)
+before building directly into an agent's skill directory.
+
+Add the example's optional profile or produce a ZIP:
+
+```console
+degardis build examples/structured-summary --profile detailed --output .artifacts
+degardis build examples/structured-summary --zip --output .artifacts
+```
+
+`examples/structured-summary` is the canonical public example used throughout
+the guides and CLI help. It summarizes supplied material from any subject;
+synthetic skills under `tests/fixtures` are compiler test data.
+
+## Companion skills
+
+The [Degardis skills catalog](https://github.com/Khojasteh/degardis-skills)
+contains reusable skills authored with Degardis.
+
+For the smoothest authoring experience, use
+[Degardis Authoring](https://github.com/Khojasteh/degardis-skills/tree/main/skills/degardis-authoring).
+It guides a skill from initial design through review, validation, packaging,
+and installation while applying Degardis conventions across manifests,
+workflows, entries, profiles, scripts, and assets.
+
+## Commands
+
+```console
+degardis list PATH [PATH ...]
+degardis validate PATH [PATH ...]
+degardis build PATH [PATH ...] --output PATH [--profile [SKILL:]PROFILE] [--zip]
+```
+
+Run `degardis COMMAND --help` for exact options and examples. All commands
+accept individual skill directories, directories containing skills at any
+depth, or a mixture of both. This lets a source tree group skills into
+subdirectories while building all of them with one command.
+
+An unqualified profile name applies to every selected skill that defines it.
+`SKILL:PROFILE` selects one owner, and `all` selects all available profiles.
+Supplying explicit selectors replaces manifest defaults for that build.
+
+For exact command behavior, profile selectors, source schemas, and the Python
+API, see the [reference](https://github.com/Khojasteh/degardis/blob/main/docs/reference.md).
+
+## Documentation
+
+| Reader goal                                  | Document                                   |
+| -------------------------------------------- | ------------------------------------------ |
+| Build and install the example                | [Getting started](https://github.com/Khojasteh/degardis/blob/main/docs/getting-started.md) |
+| Understand the source and artifact models    | [Concepts](https://github.com/Khojasteh/degardis/blob/main/docs/concepts.md) |
+| Create or modify a skill                     | [Authoring guide](https://github.com/Khojasteh/degardis/blob/main/docs/authoring-guide.md) |
+| Look up commands, schemas, or the Python API | [Reference](https://github.com/Khojasteh/degardis/blob/main/docs/reference.md) |
+| Inspect and install generated output         | [Artifact format](https://github.com/Khojasteh/degardis/blob/main/docs/artifact-format.md) |
+
+## Development
+
+```console
+python -m unittest discover -s tests -v
+python -m degardis validate examples/structured-summary
+python -m degardis build examples/structured-summary --profile all --output .artifacts
+```

degardis-1.0.0/README.md

@@ -0,0 +1,106 @@
+# Degardis
+
+Degardis is a command-line compiler for authors of portable Agent Skills. It
+turns structured YAML sources into self-contained bundles for Claude, Codex,
+Copilot, Cursor, Roo, and ChatGPT. Before writing an artifact, it validates the
+source, selected profiles, generated paths, and generated links.
+
+Authoring stays separate from generated output: edit the source files, validate
+them, and rebuild either an installable folder or a distributable ZIP.
+
+## Quick start
+
+Degardis requires Python 3.10 or later. Install it from PyPI:
+
+```console
+python -m pip install degardis
+degardis --version
+```
+
+For an isolated command-line installation, use `pipx install degardis`.
+
+To work on Degardis from this repository instead:
+
+```console
+python -m pip install -e .
+degardis validate examples/structured-summary
+degardis list examples/structured-summary
+degardis build examples/structured-summary --output .artifacts
+```
+
+The successful build ends with `Summary: 1 skill built as folder.` and reports
+the artifact path. The generated folder is ready to inspect or install:
+
+```text
+.artifacts/structured-summary/
+  SKILL.md
+  agents/openai.yaml
+  references/
+  scripts/
+  assets/
+```
+
+Degardis writes only beneath the requested output root. Rebuilding a skill
+replaces that skill's existing folder and ZIP there, while preserving unrelated
+entries. See [Artifact format](https://github.com/Khojasteh/degardis/blob/main/docs/artifact-format.md#replace-an-artifact)
+before building directly into an agent's skill directory.
+
+Add the example's optional profile or produce a ZIP:
+
+```console
+degardis build examples/structured-summary --profile detailed --output .artifacts
+degardis build examples/structured-summary --zip --output .artifacts
+```
+
+`examples/structured-summary` is the canonical public example used throughout
+the guides and CLI help. It summarizes supplied material from any subject;
+synthetic skills under `tests/fixtures` are compiler test data.
+
+## Companion skills
+
+The [Degardis skills catalog](https://github.com/Khojasteh/degardis-skills)
+contains reusable skills authored with Degardis.
+
+For the smoothest authoring experience, use
+[Degardis Authoring](https://github.com/Khojasteh/degardis-skills/tree/main/skills/degardis-authoring).
+It guides a skill from initial design through review, validation, packaging,
+and installation while applying Degardis conventions across manifests,
+workflows, entries, profiles, scripts, and assets.
+
+## Commands
+
+```console
+degardis list PATH [PATH ...]
+degardis validate PATH [PATH ...]
+degardis build PATH [PATH ...] --output PATH [--profile [SKILL:]PROFILE] [--zip]
+```
+
+Run `degardis COMMAND --help` for exact options and examples. All commands
+accept individual skill directories, directories containing skills at any
+depth, or a mixture of both. This lets a source tree group skills into
+subdirectories while building all of them with one command.
+
+An unqualified profile name applies to every selected skill that defines it.
+`SKILL:PROFILE` selects one owner, and `all` selects all available profiles.
+Supplying explicit selectors replaces manifest defaults for that build.
+
+For exact command behavior, profile selectors, source schemas, and the Python
+API, see the [reference](https://github.com/Khojasteh/degardis/blob/main/docs/reference.md).
+
+## Documentation
+
+| Reader goal                                  | Document                                   |
+| -------------------------------------------- | ------------------------------------------ |
+| Build and install the example                | [Getting started](https://github.com/Khojasteh/degardis/blob/main/docs/getting-started.md) |
+| Understand the source and artifact models    | [Concepts](https://github.com/Khojasteh/degardis/blob/main/docs/concepts.md) |
+| Create or modify a skill                     | [Authoring guide](https://github.com/Khojasteh/degardis/blob/main/docs/authoring-guide.md) |
+| Look up commands, schemas, or the Python API | [Reference](https://github.com/Khojasteh/degardis/blob/main/docs/reference.md) |
+| Inspect and install generated output         | [Artifact format](https://github.com/Khojasteh/degardis/blob/main/docs/artifact-format.md) |
+
+## Development
+
+```console
+python -m unittest discover -s tests -v
+python -m degardis validate examples/structured-summary
+python -m degardis build examples/structured-summary --profile all --output .artifacts
+```

degardis-1.0.0/degardis/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

degardis-1.0.0/degardis/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+
+raise SystemExit(main())

degardis-1.0.0/degardis/build.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import warnings
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+from .model import DegardisError, DegardisWarning
+from .package import (
+    ArchivePackager,
+    ArtifactWriter,
+    replace_skill_artifacts,
+)
+from .resolver import SkillResolver
+from .validate import bundle_warnings, validate_skill
+
+
+class SkillCompiler:
+    def __init__(self, sources: Path | list[Path]) -> None:
+        self.resolver = SkillResolver(sources)
+        self.writer = ArtifactWriter()
+        self.packager = ArchivePackager()
+
+    def _check_output_path(self, output: Path) -> None:
+        resolved_output = output.resolve()
+        for source in self.resolver.skill_paths:
+            resolved_source = source.resolve()
+            if (
+                resolved_output == resolved_source
+                or resolved_output in resolved_source.parents
+                or resolved_source in resolved_output.parents
+            ):
+                raise DegardisError(
+                    f"Output directory {resolved_output} must not overlap "
+                    f"skill source {resolved_source}"
+                )
+
+    def build(
+        self,
+        output: Path,
+        profiles: list[str] | None = None,
+        as_zip: bool = False,
+    ) -> list[Path]:
+        self._check_output_path(output)
+        validation_errors = [
+            error
+            for skill_path in self.resolver.skill_paths
+            for error in validate_skill(skill_path)
+        ]
+        if validation_errors:
+            raise DegardisError("; ".join(validation_errors))
+        bundles = self.resolver.collect(profiles)
+        if not bundles:
+            raise DegardisError("at least one skill is required")
+        for bundle in bundles:
+            for message in bundle_warnings(bundle):
+                warnings.warn(message, DegardisWarning, stacklevel=2)
+        output.mkdir(parents=True, exist_ok=True)
+        paths: list[Path] = []
+        for bundle in bundles:
+            name = bundle.primary.name
+            with TemporaryDirectory(
+                prefix="degardis-build-",
+            ) as directory:
+                staging_root = Path(directory)
+                staged_folder = staging_root / name
+                self.writer.write_skill(bundle, staged_folder)
+                if as_zip:
+                    destination = output / f"{name}.zip"
+                    staged = staging_root / f"{name}.zip"
+                    self.packager.create(staged_folder, staged)
+                else:
+                    destination = output / name
+                    staged = staged_folder
+                replace_skill_artifacts(
+                    output,
+                    name,
+                    staged,
+                    destination,
+                )
+            paths.append(destination)
+        return paths
+
+
+def build_skills(
+    sources: Path | list[Path],
+    output_dir: Path,
+    profiles: list[str] | None = None,
+    as_zip: bool = False,
+) -> list[Path]:
+    return SkillCompiler(sources).build(output_dir, profiles, as_zip)

degardis-1.0.0/degardis/cli.py

@@ -0,0 +1,197 @@
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+import warnings
+from pathlib import Path
+
+from . import __version__
+from .build import SkillCompiler
+from .model import DegardisError, DegardisWarning
+from .output import (
+    write_build_report,
+    write_profile_matches,
+    write_skill_list,
+    write_validation_report,
+)
+from .registry import discover_skill_paths, load_skill_path, load_skill_profiles
+from .resolver import collect_skills, profile_matches
+from .validate import bundle_warnings, validate_skill
+
+
+HELP_FORMATTER = argparse.RawDescriptionHelpFormatter
+
+
+def _expand_path(value: str) -> Path:
+    """Expand and resolve a CLI path using one uniform policy."""
+    return Path(os.path.expandvars(os.path.expanduser(value))).resolve()
+
+
+def _add_skill_paths(command: argparse.ArgumentParser) -> None:
+    command.add_argument(
+        "paths",
+        nargs="+",
+        type=_expand_path,
+        metavar="PATH",
+        help=(
+            "skill directory, or a directory recursively containing skill "
+            "directories"
+        ),
+    )
+
+
+def parser() -> argparse.ArgumentParser:
+    command = argparse.ArgumentParser(
+        prog="degardis",
+        description="Compile self-contained agent skills into installable bundles.",
+        epilog="""\
+Run `degardis COMMAND -h` for that command's options and examples.
+
+Examples:
+  degardis list examples/structured-summary
+  degardis validate examples/structured-summary
+  degardis build examples/structured-summary --profile detailed --output .artifacts
+""",
+        formatter_class=HELP_FORMATTER,
+    )
+    command.add_argument(
+        "-v",
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    subcommands = command.add_subparsers(
+        dest="command", required=True, title="commands", metavar="COMMAND"
+    )
+
+    build = subcommands.add_parser(
+        "build",
+        help="build one or more self-contained skills",
+        description="Build selected skills into installable skill bundles.",
+        epilog="""\
+Examples:
+  degardis build examples/structured-summary --output .artifacts
+  degardis build examples/structured-summary --profile detailed --output .artifacts
+  degardis build examples/structured-summary --zip --output dist
+""",
+        formatter_class=HELP_FORMATTER,
+    )
+    _add_skill_paths(build)
+    build.add_argument(
+        "--profile",
+        action="append",
+        dest="profiles",
+        metavar="[SKILL:]PROFILE",
+        help=(
+            "profile to include; an unqualified name matches every selected "
+            "skill, and all includes every selected skill's profiles"
+        ),
+    )
+    build.add_argument(
+        "--output",
+        type=_expand_path,
+        required=True,
+        metavar="PATH",
+        help="output directory",
+    )
+    build.add_argument(
+        "--zip",
+        action="store_true",
+        help="output one zip archive per skill instead of an uncompressed folder",
+    )
+
+    validate_command = subcommands.add_parser(
+        "validate",
+        help="validate one or more skill sources",
+        description="Validate explicit skills or recursively discovered skills.",
+        epilog="""\
+Examples:
+  degardis validate examples/structured-summary
+""",
+        formatter_class=HELP_FORMATTER,
+    )
+    _add_skill_paths(validate_command)
+
+    list_command = subcommands.add_parser(
+        "list",
+        help="inspect selected skills and profiles",
+        description="Show metadata and profiles for selected skills.",
+        epilog="""\
+Examples:
+  degardis list examples/structured-summary
+""",
+        formatter_class=HELP_FORMATTER,
+    )
+    _add_skill_paths(list_command)
+    return command
+
+
+def _normalize_help_position(argv: list[str]) -> list[str]:
+    """Let ``-h``/``--help`` work before or after the command name.
+
+    argparse only recognizes ``-h`` on the parser that reaches it, so
+    ``degardis -h build`` shows the top-level help instead of the ``build``
+    command's help that ``degardis build -h`` shows. Moving a leading
+    ``-h``/``--help`` after the command name makes both spellings equivalent.
+    """
+    if (
+        len(argv) >= 2
+        and argv[0] in ("-h", "--help")
+        and not argv[1].startswith("-")
+    ):
+        return [argv[1], argv[0], *argv[2:]]
+    return argv
+
+
+def _run(argv: list[str] | None = None) -> int:
+    tokens = list(sys.argv[1:] if argv is None else argv)
+    args = parser().parse_args(_normalize_help_position(tokens))
+    skill_paths = discover_skill_paths(args.paths)
+
+    if args.command == "list":
+        skills = [load_skill_path(path) for path in skill_paths]
+        details = [(skill, load_skill_profiles(skill)) for skill in skills]
+        write_skill_list(sys.stdout, details)
+        return 0
+
+    if args.command == "validate":
+        results = []
+        for path in skill_paths:
+            skill = load_skill_path(path)
+            errors = validate_skill(path)
+            skill_warnings = (
+                []
+                if errors
+                else bundle_warnings(collect_skills([path])[0])
+            )
+            results.append((skill, errors, skill_warnings))
+        write_validation_report(sys.stdout, results)
+        return int(any(errors for _, errors, _ in results))
+
+    compiler = SkillCompiler(skill_paths)
+    if args.profiles:
+        write_profile_matches(
+            sys.stdout,
+            profile_matches(skill_paths, args.profiles),
+        )
+    with warnings.catch_warnings(record=True) as caught:
+        warnings.simplefilter("always", DegardisWarning)
+        paths = compiler.build(args.output, args.profiles, as_zip=args.zip)
+    for warning in caught:
+        print(f"[WARNING] {warning.message}", file=sys.stderr)
+    skills = [load_skill_path(path) for path in skill_paths]
+    write_build_report(sys.stdout, skills, paths, as_zip=args.zip)
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    try:
+        return _run(argv)
+    except (DegardisError, OSError) as error:
+        print(f"[ERROR] {error}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())