netizen-cli 0.10.0__py3-none-any.whl

netizen_cli/builtin_skills.py

@@ -0,0 +1,93 @@
+"""Locate and validate package-local Skills without touching user Codex state."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from urllib.parse import unquote, urlsplit
+
+from markdown_it import MarkdownIt
+import yaml
+
+
+BUILTIN_SKILL_NAMES = ("netizen-user-guide", "netizen-lark")
+
+
+class BuiltinSkillError(RuntimeError):
+    """The imported installation cannot provide its complete built-in Skills."""
+
+
+def builtin_skill_root(
+    *,
+    package_file: Path | None = None,
+) -> Path:
+    """Resolve from the actual imported package, never cwd, PATH or an instance.
+
+    Wheels contain their resources beside the modules. An explicit source-tree
+    import (including an editable install) uses the canonical repository tree.
+    An incomplete installed resource tree fails instead of using another copy.
+    """
+    module = (package_file or Path(__file__)).resolve()
+    source = module.parent / "resources"
+    if source.exists() or source.is_symlink():
+        if source.is_symlink():
+            raise BuiltinSkillError(f"package resources directory is a symlink: {source}")
+        return validate_builtin_skills(source)
+    source = module.parent.parent
+    if module.parent.name != "netizen_cli" or not (source / "pyproject.toml").is_file():
+        raise BuiltinSkillError("cannot identify the installed Netizen resources")
+    return validate_builtin_skills(source)
+
+
+def validate_builtin_skills(source_root: Path) -> Path:
+    """Require both self-contained Skill trees, including referenced resources."""
+    raw_root = source_root.resolve() / "skills"
+    if raw_root.is_symlink() or not raw_root.is_dir():
+        raise BuiltinSkillError(f"built-in Skills directory is unavailable: {raw_root}")
+    for name in BUILTIN_SKILL_NAMES:
+        skill = raw_root / name
+        if skill.is_symlink() or not skill.is_dir():
+            raise BuiltinSkillError(f"built-in Skill is unavailable: {skill}")
+        entry = skill / "SKILL.md"
+        if entry.is_symlink():
+            raise BuiltinSkillError(f"built-in Skill contains a symlink: {entry}")
+        try:
+            text = entry.read_text(encoding="utf-8")
+            sections = text.split("---", 2)
+            metadata = yaml.safe_load(sections[1]) if text.startswith("---\n") else None
+        except (OSError, IndexError, UnicodeError, yaml.YAMLError) as error:
+            raise BuiltinSkillError(f"invalid built-in Skill: {entry}") from error
+        if (
+            not isinstance(metadata, dict)
+            or metadata.get("name") != name
+            or not isinstance(metadata.get("description"), str)
+            or not metadata["description"].strip()
+        ):
+            raise BuiltinSkillError(f"invalid built-in Skill metadata: {entry}")
+        for path in skill.rglob("*"):
+            if path.is_symlink():
+                raise BuiltinSkillError(f"built-in Skill contains a symlink: {path}")
+            if path.is_file():
+                try:
+                    if not path.read_bytes():
+                        raise BuiltinSkillError(f"built-in Skill contains an empty file: {path}")
+                    if path.suffix.lower() == ".md":
+                        _validate_resources(skill, path)
+                except (OSError, UnicodeError) as error:
+                    raise BuiltinSkillError(f"built-in Skill resource is unreadable: {path}") from error
+    return raw_root
+
+
+def _validate_resources(skill: Path, document: Path) -> None:
+    for block in MarkdownIt().parse(document.read_text(encoding="utf-8")):
+        for token in block.children or ():
+            target = token.attrGet("href") or token.attrGet("src")
+            if not target:
+                continue
+            url = urlsplit(target)
+            if url.scheme or url.netloc or not url.path:
+                continue
+            resource = (document.parent / unquote(url.path)).resolve()
+            if not resource.is_relative_to(skill) or not resource.exists():
+                raise BuiltinSkillError(
+                    f"built-in Skill reference is missing or outside its tree: {document} -> {target}"
+                )

netizen_cli/cards/__init__.py

@@ -0,0 +1,105 @@
+"""Stable public entry points for Channel cards and callback decoding."""
+
+from .callbacks import (
+    ACTION_VERSION,
+    CardActionError,
+    MAX_ENCODED_MODEL_ID_CHARS,
+    MAX_MODEL_ID_CHARS,
+    REPLY_CARD_ACTION_VERSION,
+    SettingsCardActionError,
+    TURN_FILE_ACTION_VERSION,
+    TurnFileCardLimitError,
+    fetched_card_topic_id,
+    goal_generation,
+    scope_from_fetched_card,
+)
+from .reply import (
+    TURN_FILE_CARD_JSON_LIMIT_BYTES,
+    TURN_FILE_MANIFEST_LIMIT,
+    activity_step_display,
+    decode_turn_file_action,
+    is_turn_file_action,
+    reply_card,
+    reply_card_from_manifest,
+    turn_files_card,
+    turn_files_card_from_manifest,
+    turn_progress_card,
+    turn_progress_card_from_manifest,
+)
+from .controls import (
+    ArchivedSessionCardItem,
+    MAX_SETTING_ID_CHARS,
+    MAX_THREAD_NAME_CHARS,
+    SESSIONS_PAGE_SIZE,
+    SessionCardItem,
+    archive_binding_card,
+    archived_sessions_card,
+    archived_sessions_delete_binding_card,
+    binding_configured_card,
+    binding_created_card,
+    binding_lifecycle_result_card,
+    config_card,
+    context_mode_display,
+    decode_button_action,
+    decode_card_form,
+    decode_settings_form,
+    delete_binding_card,
+    error_card,
+    goal_card,
+    new_binding_card,
+    rename_binding_card,
+    sessions_card,
+    sessions_delete_binding_card,
+    settings_card,
+    side_topic_card,
+)
+
+__all__ = [
+    "ACTION_VERSION",
+    "ArchivedSessionCardItem",
+    "CardActionError",
+    "MAX_ENCODED_MODEL_ID_CHARS",
+    "MAX_MODEL_ID_CHARS",
+    "MAX_SETTING_ID_CHARS",
+    "MAX_THREAD_NAME_CHARS",
+    "REPLY_CARD_ACTION_VERSION",
+    "SESSIONS_PAGE_SIZE",
+    "SessionCardItem",
+    "SettingsCardActionError",
+    "TURN_FILE_ACTION_VERSION",
+    "TURN_FILE_CARD_JSON_LIMIT_BYTES",
+    "TURN_FILE_MANIFEST_LIMIT",
+    "TurnFileCardLimitError",
+    "activity_step_display",
+    "archive_binding_card",
+    "archived_sessions_card",
+    "archived_sessions_delete_binding_card",
+    "binding_configured_card",
+    "binding_created_card",
+    "binding_lifecycle_result_card",
+    "config_card",
+    "context_mode_display",
+    "decode_button_action",
+    "decode_card_form",
+    "decode_settings_form",
+    "decode_turn_file_action",
+    "delete_binding_card",
+    "error_card",
+    "fetched_card_topic_id",
+    "goal_card",
+    "goal_generation",
+    "is_turn_file_action",
+    "new_binding_card",
+    "rename_binding_card",
+    "reply_card",
+    "reply_card_from_manifest",
+    "scope_from_fetched_card",
+    "sessions_card",
+    "sessions_delete_binding_card",
+    "settings_card",
+    "side_topic_card",
+    "turn_files_card",
+    "turn_files_card_from_manifest",
+    "turn_progress_card",
+    "turn_progress_card_from_manifest",
+]