kitup-sdk 0.1.2__tar.gz

kitup_sdk-0.1.2/.gitignore

@@ -0,0 +1,16 @@
+*.log
+.DS_Store
+.env
+.env.*
+!.env.example
+.local/
+
+node_modules/
+dist/
+coverage/
+*.tsbuildinfo
+
+*.test
+coverage.out
+
+target/

kitup_sdk-0.1.2/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.4
+Name: kitup-sdk
+Version: 0.1.2
+Summary: Shared installer SDK for bundled Agent Skills.
+License: MIT
+Keywords: agent,installer,sdk,skills
+Requires-Python: >=3.14
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: ruff>=0.12.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# kitup Python SDK
+
+Shared installer SDK for bundled Agent Skills.
+
+## Install
+
+```bash
+pip install kitup-sdk
+```
+
+## Use
+
+Use the workflow API for user-facing install commands:
+
+```python
+from kitup import (
+    BaseOptions,
+    InstallOptions,
+    InstallWorkflowOptions,
+    directory_bundle,
+    run_bundled_skill_install,
+)
+
+workflow = run_bundled_skill_install(
+    InstallWorkflowOptions(
+        install=InstallOptions(
+            base=BaseOptions(),
+            app_id="mycli",
+            skill_bundle=directory_bundle("./skills/mycli"),
+            scope="user",
+        ),
+        stdin_tty=True,
+        prompt_scope=True,
+    )
+)
+```
+
+Call `install_bundled_skill` when your CLI already knows the target scope and agents and does not need the interactive workflow surface.

kitup_sdk-0.1.2/README.md

@@ -0,0 +1,38 @@
+# kitup Python SDK
+
+Shared installer SDK for bundled Agent Skills.
+
+## Install
+
+```bash
+pip install kitup-sdk
+```
+
+## Use
+
+Use the workflow API for user-facing install commands:
+
+```python
+from kitup import (
+    BaseOptions,
+    InstallOptions,
+    InstallWorkflowOptions,
+    directory_bundle,
+    run_bundled_skill_install,
+)
+
+workflow = run_bundled_skill_install(
+    InstallWorkflowOptions(
+        install=InstallOptions(
+            base=BaseOptions(),
+            app_id="mycli",
+            skill_bundle=directory_bundle("./skills/mycli"),
+            scope="user",
+        ),
+        stdin_tty=True,
+        prompt_scope=True,
+    )
+)
+```
+
+Call `install_bundled_skill` when your CLI already knows the target scope and agents and does not need the interactive workflow surface.

kitup_sdk-0.1.2/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling>=1.27.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kitup-sdk"
+version = "0.1.2"
+description = "Shared installer SDK for bundled Agent Skills."
+readme = "README.md"
+requires-python = ">=3.14"
+license = { text = "MIT" }
+keywords = ["agent", "skills", "installer", "sdk"]
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.3.0",
+  "ruff>=0.12.0",
+]
+
+[dependency-groups]
+dev = [
+  "pytest>=8.3.0",
+  "ruff>=0.12.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kitup"]
+
+[tool.ruff]
+target-version = "py314"

kitup_sdk-0.1.2/src/kitup/__init__.py

@@ -0,0 +1,95 @@
+from .bundle import (
+    compute_bundle_content_hash,
+    directory_bundle,
+    files_bundle,
+    github_bundle,
+    validate_skill_bundle,
+)
+from .hosts import detect_hosts, load_host_spec, resolve_hosts
+from .install import (
+    install_bundled_skill,
+    plan_bundled_skill,
+    resolve_install_targets,
+    uninstall_bundled_skill,
+    update_bundled_skill,
+)
+from .workflow import (
+    agent_selector_from_flags,
+    classify_install_workflow_exit,
+    install_flag_error,
+    install_workflow_error,
+    parse_install_flags,
+    parse_scope_flag,
+    resolve_install_selection,
+    run_bundled_skill_install,
+    run_bundled_skill_install_with_io,
+)
+from .types import (
+    BaseOptions,
+    GitHubBundleOptions,
+    Host,
+    HostSpec,
+    INSTALL_UX,
+    InstallOptions,
+    InstallReport,
+    InstallSelection,
+    InstallSelectionOptions,
+    InstallWorkflowExit,
+    InstallWorkflowOptions,
+    InstallWorkflowReport,
+    KitupError,
+    ParsedInstallFlags,
+    SkillFile,
+    TargetError,
+    TargetGroup,
+    TargetResult,
+    TargetStatus,
+    UninstallOptions,
+    UninstallReport,
+)
+
+__all__ = [
+    "BaseOptions",
+    "GitHubBundleOptions",
+    "Host",
+    "HostSpec",
+    "INSTALL_UX",
+    "InstallOptions",
+    "InstallReport",
+    "InstallSelection",
+    "InstallSelectionOptions",
+    "InstallWorkflowExit",
+    "InstallWorkflowOptions",
+    "InstallWorkflowReport",
+    "KitupError",
+    "ParsedInstallFlags",
+    "SkillFile",
+    "TargetError",
+    "TargetGroup",
+    "TargetResult",
+    "TargetStatus",
+    "UninstallOptions",
+    "UninstallReport",
+    "compute_bundle_content_hash",
+    "detect_hosts",
+    "directory_bundle",
+    "files_bundle",
+    "github_bundle",
+    "agent_selector_from_flags",
+    "classify_install_workflow_exit",
+    "install_bundled_skill",
+    "install_flag_error",
+    "install_workflow_error",
+    "load_host_spec",
+    "parse_install_flags",
+    "parse_scope_flag",
+    "plan_bundled_skill",
+    "resolve_hosts",
+    "resolve_install_selection",
+    "resolve_install_targets",
+    "run_bundled_skill_install",
+    "run_bundled_skill_install_with_io",
+    "uninstall_bundled_skill",
+    "update_bundled_skill",
+    "validate_skill_bundle",
+]

kitup_sdk-0.1.2/src/kitup/_github.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import json
+import os
+import urllib.parse
+import urllib.request
+
+from ._paths import trim_github_path
+from .types import GitHubBundleOptions, KitupError, SkillFile
+
+
+def fetch_github_directory(options: GitHubBundleOptions) -> list[SkillFile]:
+    files, _ = fetch_github_directory_with_metadata(options)
+    return files
+
+
+def fetch_github_directory_with_metadata(
+    options: GitHubBundleOptions,
+) -> tuple[list[SkillFile], dict[str, object]]:
+    root = trim_github_path(options.path)
+    if not options.owner or not options.repo or not root or not options.ref:
+        raise KitupError("invalid github bundle")
+
+    api_base = _env_base_url("KITUP_GITHUB_API_BASE_URL", "https://api.github.com")
+    raw_base = _env_base_url(
+        "KITUP_GITHUB_RAW_BASE_URL",
+        "https://raw.githubusercontent.com",
+    )
+
+    commit = github_json(
+        f"{api_base}/repos/{_encode_path_part(options.owner)}/"
+        f"{_encode_path_part(options.repo)}/commits/{_encode_path_part(options.ref)}"
+    )
+    resolved_commit = str(commit.get("sha") or "")
+    tree_sha = str(((commit.get("commit") or {}).get("tree") or {}).get("sha") or "")
+    if not resolved_commit or not tree_sha:
+        raise KitupError("invalid github commit")
+
+    tree = github_json(
+        f"{api_base}/repos/{_encode_path_part(options.owner)}/"
+        f"{_encode_path_part(options.repo)}/git/trees/{_encode_path_part(tree_sha)}"
+        "?recursive=1"
+    )
+
+    prefix = f"{root}/"
+    files: list[SkillFile] = []
+    for item in tree.get("tree") or []:
+        if not isinstance(item, dict):
+            continue
+        path = str(item.get("path") or "")
+        if item.get("type") != "blob" or not path.startswith(prefix):
+            continue
+        url = (
+            f"{raw_base}/{_encode_path_part(options.owner)}/"
+            f"{_encode_path_part(options.repo)}/"
+            f"{_encode_path_part(resolved_commit)}/{_encode_path(path)}"
+        )
+        files.append(
+            SkillFile(
+                path=path[len(prefix) :],
+                contents=github_bytes(url),
+                mode=0o755 if item.get("mode") == "100755" else 0o644,
+            )
+        )
+
+    if not files:
+        raise KitupError("github bundle path not found")
+
+    return files, {
+        "source": "github",
+        "source_id": f"github:{options.owner}/{options.repo}/{root}",
+        "version": options.ref,
+        "provenance": {
+            "owner": options.owner,
+            "repo": options.repo,
+            "path": root,
+            "ref": options.ref,
+            "resolvedCommit": resolved_commit,
+        },
+    }
+
+
+def github_json(url: str) -> dict[str, object]:
+    with urllib.request.urlopen(_request(url), timeout=30) as response:
+        return json.loads(response.read().decode("utf-8"))
+
+
+def github_bytes(url: str) -> bytes:
+    with urllib.request.urlopen(_request(url), timeout=30) as response:
+        return response.read()
+
+
+def _request(url: str) -> urllib.request.Request:
+    return urllib.request.Request(url, headers={"User-Agent": "kitup"})
+
+
+def _env_base_url(name: str, fallback: str) -> str:
+    value = os.environ.get(name, "").rstrip("/")
+    return value or fallback
+
+
+def _encode_path(path: str) -> str:
+    return "/".join(_encode_path_part(part) for part in path.split("/"))
+
+
+def _encode_path_part(part: str) -> str:
+    return urllib.parse.quote(part, safe="")

kitup_sdk-0.1.2/src/kitup/_hosts_generated.py

@@ -0,0 +1,3 @@
+# Code generated from spec/hosts.json. DO NOT EDIT.
+
+DEFAULT_HOSTS_SPEC_JSON = "{\"$schema\":\"./hosts.schema.json\",\"schemaVersion\":1,\"hosts\":[{\"id\":\"adal\",\"displayName\":\"AdaL\",\"projectSkillsDirs\":[\".adal/skills\"],\"userSkillsDirs\":[\"~/.adal/skills\"],\"detect\":[\"~/.adal\"],\"status\":\"community\"},{\"id\":\"aider-desk\",\"displayName\":\"AiderDesk\",\"projectSkillsDirs\":[\".aider-desk/skills\"],\"userSkillsDirs\":[\"~/.aider-desk/skills\"],\"detect\":[\"~/.aider-desk\"],\"status\":\"community\"},{\"id\":\"amp\",\"displayName\":\"Amp\",\"projectSkillsDirs\":[\".agents/skills\"],\"userSkillsDirs\":[\"~/.config/agents/skills\"],\"detect\":[\"~/.config/amp\",\"~/.config/agents\"],\"status\":\"community\"},{\"id\":\"antigravity\",\"displayName\":\"Antigravity\",\"projectSkillsDirs\":[\".agents/skills\"],\"userSkillsDirs\":[\"~/.gemini/antigravity/skills\"],\"detect\":[\"~/.gemini/antigravity\"],\"status\":\"community\"},{\"id\":\"antigravity-cli\",\"displayName\":\"Antigravity CLI\",\"projectSkillsDirs\":[\".agents/skills\"],\"userSkillsDirs\":[\"~/.gemini/antigravity-cli/skills\"],\"detect\":[\"~/.gemini/antigravity-cli\"],\"status\":\"community\"},{\"id\":\"astrbot\",\"displayName\":\"AstrBot\",\"projectSkillsDirs\":[\"data/skills\"],\"userSkillsDirs\":[\"~/.astrbot/data/skills\"],\"detect\":[\"~/.astrbot\",\"data/skills\",\"~/.astrbot/data\"],\"status\":\"community\"},{\"id\":\"augment\",\"displayName\":\"Augment\",\"projectSkillsDirs\":[\".augment/skills\"],\"userSkillsDirs\":[\"~/.augment/skills\"],\"detect\":[\"~/.augment\"],\"status\":\"community\"},{\"id\":\"autohand-code\",\"displayName\":\"Autohand Code CLI\",\"projectSkillsDirs\":[\".autohand/skills\"],\"userSkillsDirs\":[\"~/.autohand/skills\"],\"detect\":[\"~/.autohand\"],\"status\":\"community\"},{\"id\":\"bob\",\"displayName\":\"IBM Bob\",\"projectSkillsDirs\":[\".bob/skills\"],\"userSkillsDirs\":[\"~/.bob/skills\"],\"detect\":[\"~/.bob\"],\"status\":\"community\"},{\"id\":\"claude-code\",\"displayName\":\"Claude Code\",\"projectSkillsDirs\":[\".claude/skills\"],\"userSkillsDirs\":[\"~/.claude/skills\"],\"detect\":[\"~/.claude\"],\"status\":\"verified\"},{\"id\":\"cline\",\"displayName\":\"Cline\",\"projectSkillsDirs\":[\".agents/skills\",\".cline/skills\",\".clinerules/skills\",\".claude/skills\"],\"userSkillsDirs\":[\"~/.agents/skills\",\"~/.cline/skills\"],\"detect\":[\"~/.cline\",\"~/.agents\"],\"status\":\"documented\"},{\"id\":\"codearts-agent\",\"displayName\":\"CodeArts Agent\",\"projectSkillsDirs\":[\".codeartsdoer/skills\"],\"userSkillsDirs\":[\"~/.codeartsdoer/skills\"],\"detect\":[\"~/.codeartsdoer\"],\"status\":\"community\"},{\"id\":\"codebuddy\",\"displayName\":\"CodeBuddy\",\"projectSkillsDirs\":[\".codebuddy/skills\"],\"userSkillsDirs\":[\"~/.codebuddy/skills\"],\"detect\":[\"~/.codebuddy\",\".codebuddy\"],\"status\":\"community\"},{\"id\":\"codemaker\",\"displayName\":\"Codemaker\",\"projectSkillsDirs\":[\".codemaker/skills\"],\"userSkillsDirs\":[\"~/.codemaker/skills\"],\"detect\":[\"~/.codemaker\"],\"status\":\"community\"},{\"id\":\"codestudio\",\"displayName\":\"Code Studio\",\"projectSkillsDirs\":[\".codestudio/skills\"],\"userSkillsDirs\":[\"~/.codestudio/skills\"],\"detect\":[\"~/.codestudio\"],\"status\":\"community\"},{\"id\":\"codex\",\"displayName\":\"Codex\",\"projectSkillsDirs\":[\".agents/skills\"],\"userSkillsDirs\":[\"~/.agents/skills\",\"~/.codex/skills\"],\"detect\":[\"~/.codex\",\"~/.agents/skills\",\"~/.agents\"],\"status\":\"verified\",\"notes\":[\"Keep both ~/.agents/skills and ~/.codex/skills for compatibility.\"]},{\"id\":\"command-code\",\"displayName\":\"Command Code\",\"projectSkillsDirs\":[\".commandcode/skills\"],\"userSkillsDirs\":[\"~/.commandcode/skills\"],\"detect\":[\"~/.commandcode\"],\"status\":\"community\"},{\"id\":\"continue\",\"displayName\":\"Continue\",\"projectSkillsDirs\":[\".continue/skills\"],\"userSkillsDirs\":[\"~/.continue/skills\"],\"detect\":[\"~/.continue\",\".continue\"],\"status\":\"community\"},{\"id\":\"cortex\",\"displayName\":\"Cortex Code\",\"projectSkillsDirs\":[\".cortex/skills\"],\"userSkillsDirs\":[\"~/.snowflake/cortex/skills\"],\"detect\":[\"~/.snowflake/cortex\"],\"status\":\"community\"},{\"id\":\"crush\",\"displayName\":\"Crush\",\"projectSkillsDirs\":[\".crush/skills\"],\"userSkillsDirs\":[\"~/.config/crush/skills\"],\"detect\":[\"~/.config/crush\"],\"status\":\"community\"},{\"id\":\"cursor\",\"displayName\":\"Cursor\",\"projectSkillsDirs\":[\".agents/skills\",\".cursor/skills\"],\"userSkillsDirs\":[\"~/.cursor/skills\",\"~/.agents/skills\"],\"detect\":[\"~/.cursor\",\"~/.agents\"],\"status\":\"documented\"},{\"id\":\"deepagents\",\"displayName\":\"Deep Agents\",\"projectSkillsDirs\":[\".agents/skills\"],\"userSkillsDirs\":[\"~/.deepagents/agent/skills\"],\"detect\":[\"~/.deepagents\",\"~/.deepagents/agent\"],\"status\":\"community\"},{\"id\":\"devin\",\"displayName\":\"Devin for Terminal\",\"projectSkillsDirs\":[\".devin/skills\"],\"userSkillsDirs\":[\"~/.config/devin/skills\"],\"detect\":[\"~/.config/devin\"],\"status\":\"community\"},{\"id\":\"dexto\",\"displayName\":\"Dexto\",\"projectSkillsDirs\":[\".agents/skills\"],\"userSkillsDirs\":[\"~/.agents/skills\"],\"detect\":[\"~/.dexto\",\"~/.agents\"],\"status\":\"community\"},{\"id\":\"droid\",\"displayName\":\"Droid\",\"projectSkillsDirs\":[\".factory/skills\"],\"userSkillsDirs\":[\"~/.factory/skills\"],\"detect\":[\"~/.factory\"],\"status\":\"community\"},{\"id\":\"eve\",\"displayName\":\"Eve\",\"projectSkillsDirs\":[\"agent/skills\"],\"userSkillsDirs\":[],\"detect\":[\"agent\",\"package.json\"],\"status\":\"community\",\"notes\":[\"Project-only host; userSkillsDirs is intentionally empty.\",\"Detect from Eve project shape; no global skill directory.\"]},{\"id\":\"firebender\",\"displayName\":\"Firebender\",\"projectSkillsDirs\":[\".agents/skills\"],\"userSkillsDirs\":[\"~/.firebender/skills\"],\"detect\":[\"~/.firebender\"],\"status\":\"community\"},{\"id\":\"forgecode\",\"displayName\":\"ForgeCode\",\"projectSkillsDirs\":[\".forge/skills\"],\"userSkillsDirs\":[\"~/.forge/skills\"],\"detect\":[\"~/.forge\"],\"status\":\"community\"},{\"id\":\"gemini-cli\",\"displayName\":\"Gemini CLI\",\"projectSkillsDirs\":[\".agents/skills\",\".gemini/skills\"],\"userSkillsDirs\":[\"~/.gemini/skills\",\"~/.agents/skills\"],\"detect\":[\"~/.gemini\",\"~/.agents\"],\"status\":\"documented\"},{\"id\":\"github-copilot\",\"displayName\":\"GitHub Copilot\",\"projectSkillsDirs\":[\".agents/skills\",\".github/skills\",\".claude/skills\"],\"userSkillsDirs\":[\"~/.copilot/skills\",\"~/.agents/skills\",\"~/.claude/skills\"],\"detect\":[\"~/.copilot\",\"~/.agents\",\"~/.claude\"],\"status\":\"documented\"},{\"id\":\"goose\",\"displayName\":\"Goose\",\"projectSkillsDirs\":[\".goose/skills\"],\"userSkillsDirs\":[\"~/.config/goose/skills\"],\"detect\":[\"~/.config/goose\"],\"status\":\"community\"},{\"id\":\"hermes-agent\",\"displayName\":\"Hermes Agent\",\"projectSkillsDirs\":[\".hermes/skills\"],\"userSkillsDirs\":[\"~/.hermes/skills\"],\"detect\":[\"~/.hermes\"],\"status\":\"community\"},{\"id\":\"iflow-cli\",\"displayName\":\"iFlow CLI\",\"projectSkillsDirs\":[\".iflow/skills\"],\"userSkillsDirs\":[\"~/.iflow/skills\"],\"detect\":[\"~/.iflow\"],\"status\":\"community\"},{\"id\":\"inference-sh\",\"displayName\":\"inference.sh\",\"projectSkillsDirs\":[\".inferencesh/skills\"],\"userSkillsDirs\":[\"~/.inferencesh/skills\"],\"detect\":[\"~/.inferencesh\"],\"status\":\"community\"},{\"id\":\"jazz\",\"displayName\":\"Jazz\",\"projectSkillsDirs\":[\".jazz/skills\"],\"userSkillsDirs\":[\"~/.jazz/skills\"],\"detect\":[\"~/.jazz\",\".jazz\"],\"status\":\"community\"},{\"id\":\"junie\",\"displayName\":\"Junie\",\"projectSkillsDirs\":[\".junie/skills\"],\"userSkillsDirs\":[\"~/.junie/skills\"],\"detect\":[\"~/.junie\"],\"status\":\"community\"},{\"id\":\"kilo\",\"displayName\":\"Kilo Code\",\"projectSkillsDirs\":[\".kilocode/skills\"],\"userSkillsDirs\":[\"~/.kilocode/skills\"],\"detect\":[\"~/.kilocode\"],\"status\":\"community\"},{\"id\":\"kimi-cli\",\"displayName\":\"Kimi Code CLI\",\"projectSkillsDirs\":[\".agents/skills\"],\"userSkillsDirs\":[\"~/.config/agents/skills\",\"~/.agents/skills\"],\"detect\":[\"~/.config/agents\",\"~/.kimi-code\",\"~/.kimi\",\"~/.agents\"],\"status\":\"community\",\"notes\":[\"kimi-code-cli is an alias for the same Kimi Code CLI path family.\"],\"aliases\":[\"kimi-code-cli\"]},{\"id\":\"kiro-cli\",\"displayName\":\"Kiro CLI\",\"projectSkillsDirs\":[\".kiro/skills\"],\"userSkillsDirs\":[\"~/.kiro/skills\"],\"detect\":[\"~/.kiro\"],\"status\":\"community\"},{\"id\":\"kode\",\"displayName\":\"Kode\",\"projectSkillsDirs\":[\".kode/skills\"],\"userSkillsDirs\":[\"~/.kode/skills\"],\"detect\":[\"~/.kode\"],\"status\":\"community\"},{\"id\":\"lingma\",\"displayName\":\"Lingma\",\"projectSkillsDirs\":[\".lingma/skills\"],\"userSkillsDirs\":[\"~/.lingma/skills\"],\"detect\":[\"~/.lingma\"],\"status\":\"community\"},{\"id\":\"loaf\",\"displayName\":\"Loaf\",\"projectSkillsDirs\":[\".agents/skills\"],\"userSkillsDirs\":[\"~/.agents/skills\"],\"detect\":[\"~/.loaf\",\"~/.agents\"],\"status\":\"community\"},{\"id\":\"mcpjam\",\"displayName\":\"MCPJam\",\"projectSkillsDirs\":[\".mcpjam/skills\"],\"userSkillsDirs\":[\"~/.mcpjam/skills\"],\"detect\":[\"~/.mcpjam\"],\"status\":\"community\"},{\"id\":\"mistral-vibe\",\"displayName\":\"Mistral Vibe\",\"projectSkillsDirs\":[\".vibe/skills\"],\"userSkillsDirs\":[\"~/.vibe/skills\"],\"detect\":[\"~/.vibe\"],\"status\":\"community\"},{\"id\":\"moxby\",\"displayName\":\"Moxby\",\"projectSkillsDirs\":[\".moxby/skills\"],\"userSkillsDirs\":[\"~/.moxby/skills\"],\"detect\":[\"~/.moxby\"],\"status\":\"community\"},{\"id\":\"mux\",\"displayName\":\"Mux\",\"projectSkillsDirs\":[\".mux/skills\"],\"userSkillsDirs\":[\"~/.mux/skills\"],\"detect\":[\"~/.mux\"],\"status\":\"community\"},{\"id\":\"neovate\",\"displayName\":\"Neovate\",\"projectSkillsDirs\":[\".neovate/skills\"],\"userSkillsDirs\":[\"~/.neovate/skills\"],\"detect\":[\"~/.neovate\"],\"status\":\"community\"},{\"id\":\"ona\",\"displayName\":\"Ona\",\"projectSkillsDirs\":[\".ona/skills\"],\"userSkillsDirs\":[\"~/.ona/skills\"],\"detect\":[\"~/.ona\"],\"status\":\"community\"},{\"id\":\"openclaw\",\"displayName\":\"OpenClaw\",\"projectSkillsDirs\":[\"skills\"],\"userSkillsDirs\":[\"~/.openclaw/skills\"],\"detect\":[\"~/.openclaw\",\"~/.clawdbot\",\"~/.moltbot\"],\"status\":\"community\"},{\"id\":\"opencode\",\"displayName\":\"OpenCode\",\"projectSkillsDirs\":[\".agents/skills\",\".opencode/skills\",\".claude/skills\"],\"userSkillsDirs\":[\"~/.config/opencode/skills\",\"~/.agents/skills\",\"~/.claude/skills\"],\"detect\":[\"~/.config/opencode\",\"~/.agents\",\"~/.claude\"],\"status\":\"verified\"},{\"id\":\"openhands\",\"displayName\":\"OpenHands\",\"projectSkillsDirs\":[\".openhands/skills\"],\"userSkillsDirs\":[\"~/.openhands/skills\"],\"detect\":[\"~/.openhands\"],\"status\":\"community\"},{\"id\":\"pi\",\"displayName\":\"Pi\",\"projectSkillsDirs\":[\".pi/skills\"],\"userSkillsDirs\":[\"~/.pi/agent/skills\"],\"detect\":[\"~/.pi/agent\"],\"status\":\"community\"},{\"id\":\"pochi\",\"displayName\":\"Pochi\",\"projectSkillsDirs\":[\".pochi/skills\"],\"userSkillsDirs\":[\"~/.pochi/skills\"],\"detect\":[\"~/.pochi\"],\"status\":\"community\"},{\"id\":\"promptscript\",\"displayName\":\"PromptScript\",\"projectSkillsDirs\":[\".agents/skills\"],\"userSkillsDirs\":[],\"detect\":[\".promptscript\",\"promptscript.yaml\"],\"status\":\"community\",\"notes\":[\"Project-only host; userSkillsDirs is intentionally empty.\"]},{\"id\":\"qoder\",\"displayName\":\"Qoder\",\"projectSkillsDirs\":[\".qoder/skills\"],\"userSkillsDirs\":[\"~/.qoder/skills\"],\"detect\":[\"~/.qoder\"],\"status\":\"community\"},{\"id\":\"qoder-cn\",\"displayName\":\"Qoder CN\",\"projectSkillsDirs\":[\".qoder/skills\"],\"userSkillsDirs\":[\"~/.qoder-cn/skills\"],\"detect\":[\"~/.qoder-cn\"],\"status\":\"community\"},{\"id\":\"qwen-code\",\"displayName\":\"Qwen Code\",\"projectSkillsDirs\":[\".qwen/skills\"],\"userSkillsDirs\":[\"~/.qwen/skills\"],\"detect\":[\"~/.qwen\"],\"status\":\"community\"},{\"id\":\"reasonix\",\"displayName\":\"Reasonix\",\"projectSkillsDirs\":[\".reasonix/skills\"],\"userSkillsDirs\":[\"~/.reasonix/skills\"],\"detect\":[\"~/.reasonix\"],\"status\":\"community\"},{\"id\":\"replit\",\"displayName\":\"Replit\",\"projectSkillsDirs\":[\".agents/skills\"],\"userSkillsDirs\":[\"~/.config/agents/skills\"],\"detect\":[\".replit\",\"~/.config/agents\"],\"status\":\"community\"},{\"id\":\"roo\",\"displayName\":\"Roo Code\",\"aliases\":[\"roo-code\"],\"projectSkillsDirs\":[\".roo/skills\",\".agents/skills\"],\"userSkillsDirs\":[\"~/.roo/skills\",\"~/.agents/skills\"],\"detect\":[\"~/.roo\",\"~/.agents\"],\"status\":\"documented\"},{\"id\":\"rovodev\",\"displayName\":\"Rovo Dev\",\"projectSkillsDirs\":[\".rovodev/skills\"],\"userSkillsDirs\":[\"~/.rovodev/skills\"],\"detect\":[\"~/.rovodev\"],\"status\":\"community\"},{\"id\":\"tabnine-cli\",\"displayName\":\"Tabnine CLI\",\"projectSkillsDirs\":[\".tabnine/agent/skills\"],\"userSkillsDirs\":[\"~/.tabnine/agent/skills\"],\"detect\":[\"~/.tabnine\",\"~/.tabnine/agent\"],\"status\":\"community\"},{\"id\":\"terramind\",\"displayName\":\"Terramind\",\"projectSkillsDirs\":[\".terramind/skills\"],\"userSkillsDirs\":[\"~/.terramind/skills\"],\"detect\":[\"~/.terramind\"],\"status\":\"community\"},{\"id\":\"tinycloud\",\"displayName\":\"Tinycloud\",\"projectSkillsDirs\":[\".tinycloud/skills\"],\"userSkillsDirs\":[\"~/.tinycloud/skills\"],\"detect\":[\"~/.tinycloud\"],\"status\":\"community\"},{\"id\":\"trae\",\"displayName\":\"Trae\",\"projectSkillsDirs\":[\".trae/skills\"],\"userSkillsDirs\":[\"~/.trae/skills\"],\"detect\":[\"~/.trae\"],\"status\":\"community\"},{\"id\":\"trae-cn\",\"displayName\":\"Trae CN\",\"projectSkillsDirs\":[\".trae/skills\"],\"userSkillsDirs\":[\"~/.trae-cn/skills\"],\"detect\":[\"~/.trae-cn\"],\"status\":\"community\"},{\"id\":\"universal\",\"displayName\":\"Universal\",\"projectSkillsDirs\":[\".agents/skills\"],\"userSkillsDirs\":[\"~/.agents/skills\",\"~/.config/agents/skills\"],\"detect\":[\"~/.agents\",\"~/.config/agents\"],\"status\":\"community\"},{\"id\":\"warp\",\"displayName\":\"Warp\",\"projectSkillsDirs\":[\".agents/skills\",\".warp/skills\",\".claude/skills\",\".codex/skills\",\".cursor/skills\",\".gemini/skills\",\".copilot/skills\",\".factory/skills\",\".github/skills\",\".opencode/skills\"],\"userSkillsDirs\":[\"~/.agents/skills\",\"~/.warp/skills\",\"~/.claude/skills\",\"~/.codex/skills\",\"~/.cursor/skills\",\"~/.gemini/skills\",\"~/.copilot/skills\",\"~/.factory/skills\",\"~/.github/skills\",\"~/.opencode/skills\"],\"detect\":[\"~/.warp\",\"~/.agents\",\"~/.claude\",\"~/.codex\",\"~/.cursor\",\"~/.gemini\",\"~/.copilot\",\"~/.factory\",\"~/.github\",\"~/.opencode\"],\"status\":\"documented\"},{\"id\":\"windsurf\",\"displayName\":\"Windsurf\",\"projectSkillsDirs\":[\".windsurf/skills\"],\"userSkillsDirs\":[\"~/.codeium/windsurf/skills\"],\"detect\":[\"~/.codeium/windsurf\"],\"status\":\"community\"},{\"id\":\"zed\",\"displayName\":\"Zed\",\"projectSkillsDirs\":[\".agents/skills\"],\"userSkillsDirs\":[\"~/.agents/skills\"],\"detect\":[\"~/.config/zed\",\"~/.agents\"],\"status\":\"community\"},{\"id\":\"zencoder\",\"displayName\":\"Zencoder\",\"projectSkillsDirs\":[\".zencoder/skills\"],\"userSkillsDirs\":[\"~/.zencoder/skills\"],\"detect\":[\"~/.zencoder\"],\"status\":\"community\"},{\"id\":\"zenflow\",\"displayName\":\"Zenflow\",\"projectSkillsDirs\":[\".zencoder/skills\"],\"userSkillsDirs\":[\"~/.zencoder/skills\"],\"detect\":[\"~/.zencoder\"],\"status\":\"community\"}]}"

kitup_sdk-0.1.2/src/kitup/_metadata.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+
+def write_install_metadata(
+    target_dir: Path,
+    *,
+    app_id: str,
+    skill_name: str,
+    digest: str,
+    source: str,
+    source_id: str | None = None,
+    version: str | None = None,
+    provenance: dict[str, object] | None = None,
+) -> None:
+    payload = {
+        "schemaVersion": 1,
+        "appId": app_id,
+        "skillName": skill_name,
+        "source": source,
+        "hash": digest,
+    }
+    if source_id is not None:
+        payload["sourceId"] = source_id
+    if version is not None:
+        payload["version"] = version
+    if provenance is not None:
+        payload["provenance"] = provenance
+    (target_dir / ".kitup.json").write_text(
+        json.dumps(payload, indent=2) + "\n", encoding="utf-8"
+    )
+
+
+def read_install_metadata(target_dir: Path) -> dict[str, object] | None:
+    metadata_file = target_dir / ".kitup.json"
+    if not metadata_file.exists():
+        return None
+    try:
+        payload = json.loads(metadata_file.read_text(encoding="utf-8"))
+    except OSError, ValueError:
+        return None
+    if not isinstance(payload, dict):
+        return None
+    return payload

kitup_sdk-0.1.2/src/kitup/_paths.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from .types import KitupError
+
+
+def skip_name(name: str) -> bool:
+    return (
+        name == ".git"
+        or name == ".kitup.json"
+        or name == ".DS_Store"
+        or name.endswith(".swp")
+        or name.endswith("~")
+    )
+
+
+def normalize_bundle_path(value: str) -> str | None:
+    if not value or "\\" in value or value.startswith("/") or value[1:2] == ":":
+        raise KitupError(f"invalid skill file path: {value}")
+
+    parts = value.split("/")
+    for part in parts:
+        if not part or part in {".", ".."}:
+            raise KitupError(f"invalid skill file path: {value}")
+        if skip_name(part):
+            return None
+
+    return "/".join(parts)
+
+
+def resolve_path(path: str, *, cwd: str | None = None) -> Path:
+    resolved = Path(path)
+    if not resolved.is_absolute() and cwd is not None:
+        resolved = Path(cwd) / resolved
+    return resolved
+
+
+def trim_github_path(path: str) -> str:
+    return path.strip("/")

kitup_sdk-0.1.2/src/kitup/bundle.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from ._github import fetch_github_directory
+from ._paths import normalize_bundle_path, resolve_path, skip_name
+from .types import (
+    BundleFile,
+    GitHubBundleOptions,
+    KitupError,
+    NormalizedSkillBundle,
+    SkillFile,
+    SkillInfo,
+)
+
+
+@dataclass(frozen=True)
+class DirectoryBundle:
+    path: str
+
+
+@dataclass(frozen=True)
+class FilesBundle:
+    files: list[SkillFile]
+
+
+@dataclass(frozen=True)
+class GitHubBundle:
+    options: GitHubBundleOptions
+
+
+SkillBundle = DirectoryBundle | FilesBundle | GitHubBundle
+
+
+def directory_bundle(path: str) -> DirectoryBundle:
+    return DirectoryBundle(path=path)
+
+
+def files_bundle(files: list[SkillFile]) -> FilesBundle:
+    return FilesBundle(files=files)
+
+
+def github_bundle(options: GitHubBundleOptions) -> GitHubBundle:
+    return GitHubBundle(options=options)
+
+
+def validate_skill_bundle(bundle: SkillBundle, cwd: str | None = None) -> SkillInfo:
+    try:
+        normalized = normalize_skill_bundle(bundle, cwd=cwd)
+    except Exception:
+        return SkillInfo(valid=False, error_code="invalid-skill-bundle")
+
+    return validate_normalized_skill_bundle(normalized)
+
+
+def validate_normalized_skill_bundle(normalized: NormalizedSkillBundle) -> SkillInfo:
+    skill_md = normalized.by_path.get("SKILL.md")
+    if skill_md is None:
+        return SkillInfo(valid=False, error_code="missing-skill-md")
+
+    try:
+        content = skill_md.bytes.decode("utf-8")
+    except UnicodeDecodeError:
+        return SkillInfo(valid=False, error_code="invalid-frontmatter")
+
+    match = re.match(r"^---\r?\n([\s\S]*?)\r?\n---\r?\n", content)
+    if match is None:
+        return SkillInfo(valid=False, error_code="invalid-frontmatter")
+
+    fields = _parse_frontmatter(match.group(1))
+    skill_name = fields.get("name", "")
+    description = fields.get("description", "")
+    if not _valid_skill_name(skill_name) or not description or len(description) > 1024:
+        return SkillInfo(valid=False, error_code="invalid-frontmatter")
+
+    return SkillInfo(valid=True, skill_name=skill_name, description=description)
+
+
+def compute_bundle_content_hash(bundle: SkillBundle, cwd: str | None = None) -> str:
+    normalized = normalize_skill_bundle(bundle, cwd=cwd)
+    return compute_normalized_bundle_content_hash(normalized)
+
+
+def compute_normalized_bundle_content_hash(normalized: NormalizedSkillBundle) -> str:
+    digest = hashlib.sha256()
+    for file in normalized.files:
+        digest.update(file.path.encode("utf-8"))
+        digest.update(b"\0")
+        digest.update(file.bytes)
+        digest.update(b"\0")
+    return f"sha256:{digest.hexdigest()}"
+
+
+def normalize_skill_bundle(
+    bundle: SkillBundle, cwd: str | None = None
+) -> NormalizedSkillBundle:
+    if isinstance(bundle, DirectoryBundle):
+        return normalize_directory_bundle(bundle.path, cwd=cwd)
+    if isinstance(bundle, FilesBundle):
+        return normalize_files_bundle(bundle.files)
+    if isinstance(bundle, GitHubBundle):
+        return normalize_files_bundle(fetch_github_directory(bundle.options))
+    raise KitupError(f"unsupported bundle: {type(bundle)!r}")
+
+
+def normalize_directory_bundle(
+    path: str, cwd: str | None = None
+) -> NormalizedSkillBundle:
+    root = resolve_path(path, cwd=cwd)
+    if not root.is_dir():
+        raise KitupError(f"invalid bundle directory: {root}")
+    files: list[SkillFile] = []
+
+    for current_root, dirnames, filenames in os.walk(root):
+        dirnames[:] = sorted(name for name in dirnames if not skip_name(name))
+        for filename in sorted(filenames):
+            if skip_name(filename):
+                continue
+            source = Path(current_root) / filename
+            relative = source.relative_to(root).as_posix()
+            files.append(
+                SkillFile(
+                    path=relative,
+                    contents=source.read_bytes(),
+                    mode=source.stat().st_mode & 0o777,
+                )
+            )
+
+    return normalize_files_bundle(files)
+
+
+def normalize_files_bundle(files: list[SkillFile]) -> NormalizedSkillBundle:
+    by_path: dict[str, BundleFile] = {}
+    for file in files:
+        normalized_path = normalize_bundle_path(file.path)
+        if normalized_path is None:
+            continue
+        if normalized_path in by_path:
+            raise KitupError(f"duplicate skill file: {normalized_path}")
+        by_path[normalized_path] = BundleFile(
+            path=normalized_path,
+            bytes=file.contents.encode("utf-8")
+            if isinstance(file.contents, str)
+            else file.contents,
+            mode=file.mode or 0o644,
+        )
+
+    normalized_files = [by_path[path] for path in sorted(by_path)]
+    return NormalizedSkillBundle(files=normalized_files, by_path=by_path)
+
+
+def copy_normalized_bundle(files: list[BundleFile], target_dir: str | Path) -> None:
+    destination_root = Path(target_dir)
+    destination_root.mkdir(parents=True, exist_ok=True)
+    for file in files:
+        destination = destination_root / file.path
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        destination.write_bytes(file.bytes)
+        destination.chmod(file.mode)
+
+
+def _parse_frontmatter(content: str) -> dict[str, str]:
+    fields: dict[str, str] = {}
+    for line in content.splitlines():
+        if ":" not in line:
+            continue
+        key, value = line.split(":", 1)
+        fields[key] = value.strip()
+    return fields
+
+
+def _valid_skill_name(name: str) -> bool:
+    return re.fullmatch(r"[a-z0-9]+(?:-[a-z0-9]+)*", name) is not None