kivault-cli 1.4.1__py3-none-any.whl

kivault_cli/__init__.py

@@ -0,0 +1 @@
+"""KiVault CLI package."""

kivault_cli/app.py

@@ -0,0 +1,363 @@
+from __future__ import annotations
+
+from enum import Enum
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+import re
+import subprocess
+import sys
+import tomllib
+from typing import Any, TypedDict
+
+from agent_skill_dist import (
+    SkillAlreadyExists,
+    SkillDistError,
+    install_bundled_skill,
+    skill_status,
+)
+from agent_skill_dist.cli import already_exists_to_text, install_to_text, status_to_text
+import httpx
+import typer
+
+from kivault_cli.commands import items, public, tags, vaults
+from kivault_cli.commands.identity import whoami
+from kivault_cli.errors import CliError
+from kivault_cli.output import emit
+from kivault_cli.settings import load_settings
+from kivault_cli.utils import help_markup_mode
+
+
+PACKAGE_NAME = "kivault-cli"
+RELEASE_APP = "kivault_cli"
+RELEASE_TAG = "default"
+LATEST_RELEASE_URL = "https://releases.kispace.cc/api/public/latest"
+SKILL_PACKAGE = "kivault_cli"
+SKILL_RESOURCE_ROOT = "bundled_skills"
+SKILL_NAME = "kivault-cli"
+
+
+class SkillTarget(str, Enum):
+    repo = "repo"
+    global_target = "global"
+
+
+class ReleaseInfo(TypedDict):
+    version: str
+    tags: list[str]
+    download_url: str
+    release_notes: str | None
+    created_at: str
+
+
+def _package_version() -> str:
+    pyproject_version = _pyproject_version()
+    if pyproject_version:
+        return pyproject_version
+    try:
+        return version(PACKAGE_NAME)
+    except PackageNotFoundError:
+        return "unknown"
+
+
+def _pyproject_version() -> str | None:
+    pyproject_path = Path(__file__).resolve().parents[1] / "pyproject.toml"
+    if not pyproject_path.exists():
+        return None
+    try:
+        data = tomllib.loads(pyproject_path.read_text(encoding="utf-8"))
+    except (OSError, tomllib.TOMLDecodeError):
+        return None
+    project = data.get("project")
+    if not isinstance(project, dict):
+        return None
+    project_version = project.get("version")
+    if not isinstance(project_version, str):
+        return None
+    return project_version
+
+
+def _version_callback(value: bool) -> None:
+    if not value:
+        return
+    typer.echo(f"kivault {_package_version()}")
+    raise typer.Exit()
+
+
+def _latest_release_url() -> str:
+    return f"{LATEST_RELEASE_URL}?app={RELEASE_APP}&tags={RELEASE_TAG}"
+
+
+def _fetch_latest_release() -> ReleaseInfo:
+    try:
+        response = httpx.get(
+            _latest_release_url(), timeout=30, follow_redirects=True, trust_env=False
+        )
+    except httpx.HTTPError as exc:
+        raise CliError(f"无法获取最新版本信息：{exc}") from exc
+    if response.status_code >= 400:
+        raise CliError(
+            f"无法获取最新版本信息：HTTP {response.status_code} {response.reason_phrase}"
+        )
+    try:
+        payload = response.json()
+    except ValueError as exc:
+        raise CliError("无法解析最新版本信息：服务端返回的不是 JSON。") from exc
+    return _parse_release_info(payload)
+
+
+def _parse_release_info(payload: Any) -> ReleaseInfo:
+    if not isinstance(payload, dict):
+        raise CliError("无法解析最新版本信息：响应不是 JSON object。")
+    version_value = payload.get("version")
+    download_url = payload.get("download_url")
+    if not isinstance(version_value, str) or not version_value:
+        raise CliError("无法解析最新版本信息：缺少 version。")
+    if not isinstance(download_url, str) or not download_url:
+        raise CliError("无法解析最新版本信息：缺少 download_url。")
+    tags_value = payload.get("tags")
+    tags = [str(tag) for tag in tags_value] if isinstance(tags_value, list) else []
+    release_notes_value = payload.get("release_notes")
+    created_at_value = payload.get("created_at")
+    return {
+        "version": version_value,
+        "tags": tags,
+        "download_url": download_url,
+        "release_notes": release_notes_value
+        if isinstance(release_notes_value, str)
+        else None,
+        "created_at": created_at_value if isinstance(created_at_value, str) else "",
+    }
+
+
+def _is_newer_version(latest: str, current: str) -> bool:
+    return _version_parts(latest) > _version_parts(current)
+
+
+def _version_parts(value: str) -> tuple[int, ...]:
+    parts = [int(part) for part in re.findall(r"\d+", value)]
+    return tuple(parts) if parts else (0,)
+
+
+def _install_release(download_url: str) -> None:
+    command = [
+        sys.executable,
+        "-m",
+        "pip",
+        "install",
+        "--upgrade",
+        download_url,
+    ]
+    try:
+        subprocess.run(command, check=True, capture_output=True, text=True)
+    except FileNotFoundError as exc:
+        raise CliError("无法执行 pip：当前 Python 环境不可用。") from exc
+    except subprocess.CalledProcessError as exc:
+        detail = (exc.stderr or exc.stdout or "").strip()
+        message = f"升级失败：pip 退出码 {exc.returncode}"
+        if detail:
+            message = f"{message}\n{detail}"
+        raise CliError(message) from exc
+
+
+app = typer.Typer(
+    no_args_is_help=True,
+    rich_markup_mode=help_markup_mode(),
+    help=(
+        "KiVault 命令行客户端。\n\n"
+        "\b\n示例：\n"
+        "  kivault health\n"
+        "  kivault --server http://127.0.0.1:8000 whoami\n"
+        '  kivault item add-text --vault-id vault_123 --title Note --content "hello"'
+    ),
+)
+skill_app = typer.Typer(
+    no_args_is_help=True,
+    rich_markup_mode=help_markup_mode(),
+    help="安装或查看 KiVault CLI 内置 agent skill。",
+)
+
+
+@app.callback()
+def cli(
+    ctx: typer.Context,
+    server: str | None = typer.Option(
+        None,
+        "--server",
+        help="临时覆盖 KiVault 服务地址；未传时使用 KIVAULT_SERVER_URL 或默认 http://127.0.0.1:8000。",
+    ),
+    json_output: bool = typer.Option(
+        False, "--json", help="输出服务端返回的原始 JSON，便于脚本处理。"
+    ),
+    version_output: bool = typer.Option(
+        False,
+        "--version",
+        callback=_version_callback,
+        is_eager=True,
+        help="显示版本号并退出。",
+    ),
+) -> None:
+    ctx.obj = {
+        "settings": load_settings(server_override=server),
+        "json": json_output,
+    }
+
+
+@app.command()
+def health(ctx: typer.Context) -> None:
+    """检查服务健康状态。
+
+    \b
+    示例：
+      kivault health
+      kivault --server http://127.0.0.1:8000 health
+    """
+    from kivault_cli.client import api
+
+    emit(ctx, api(ctx, auth=False).request("GET", "/api/health"))
+
+
+@app.command()
+def upgrade(
+    ctx: typer.Context,
+    yes: bool = typer.Option(
+        False, "--yes", "-y", help="确认升级。未传时只检查最新版本，不安装。"
+    ),
+) -> None:
+    """检查并升级 KiVault CLI。
+
+    \b
+    示例：
+      kivault upgrade
+      kivault upgrade --yes
+    """
+    current_version = _package_version()
+    release = _fetch_latest_release()
+    is_newer = _is_newer_version(release["version"], current_version)
+    result = {
+        "current_version": current_version,
+        "latest_version": release["version"],
+        "latest_tags": release["tags"],
+        "download_url": release["download_url"],
+        "release_notes": release["release_notes"],
+        "created_at": release["created_at"],
+        "upgrade_available": is_newer,
+        "installed": False,
+    }
+
+    if not ctx.obj.get("json"):
+        typer.echo(f"current: {current_version}")
+        typer.echo(f"latest:  {release['version']}")
+        typer.echo(f"url:     {release['download_url']}")
+
+    if not is_newer:
+        if ctx.obj.get("json"):
+            emit(ctx, result)
+        else:
+            typer.echo("当前已经是最新版本，无需升级。")
+        return
+
+    if not yes:
+        if ctx.obj.get("json"):
+            emit(ctx, result)
+        else:
+            typer.echo("发现新版本。执行 `kivault upgrade --yes` 确认升级。")
+        return
+
+    if not ctx.obj.get("json"):
+        typer.echo("开始升级 KiVault CLI...")
+    _install_release(release["download_url"])
+    result["installed"] = True
+    if ctx.obj.get("json"):
+        emit(ctx, result)
+    else:
+        typer.echo("升级完成。")
+
+
+@skill_app.command("status")
+def skill_install_status(
+    ctx: typer.Context,
+    target: SkillTarget = typer.Option(
+        SkillTarget.repo,
+        "--target",
+        help="安装目标。repo 为当前目录 .agents/skills；global 为 CODEX_HOME skills。",
+    ),
+    output: Path | None = typer.Option(
+        None, "--output", help="自定义 skills 根目录；最终安装到 <output>/kivault-cli。"
+    ),
+) -> None:
+    """查看内置 agent skill 的安装状态。"""
+    try:
+        status = skill_status(
+            package=SKILL_PACKAGE,
+            distribution=PACKAGE_NAME,
+            resource_root=SKILL_RESOURCE_ROOT,
+            skill_name=SKILL_NAME,
+            package_version=_package_version(),
+            target=_skill_dist_target(target),
+            output=output,
+        )
+    except SkillDistError as exc:
+        raise CliError(str(exc)) from exc
+
+    if ctx.obj.get("json"):
+        emit(ctx, status.to_dict())
+    else:
+        typer.echo(status_to_text(status))
+
+
+@skill_app.command("install")
+def install_skill(
+    ctx: typer.Context,
+    target: SkillTarget = typer.Option(
+        SkillTarget.repo,
+        "--target",
+        help="安装目标。repo 为当前目录 .agents/skills；global 为 CODEX_HOME skills。",
+    ),
+    output: Path | None = typer.Option(
+        None, "--output", help="自定义 skills 根目录；最终安装到 <output>/kivault-cli。"
+    ),
+    yes: bool = typer.Option(
+        False, "--yes", "-y", help="目标已存在时允许覆盖。"
+    ),
+) -> None:
+    """安装 KiVault CLI 内置 agent skill。"""
+    try:
+        status = install_bundled_skill(
+            package=SKILL_PACKAGE,
+            distribution=PACKAGE_NAME,
+            resource_root=SKILL_RESOURCE_ROOT,
+            skill_name=SKILL_NAME,
+            package_version=_package_version(),
+            target=_skill_dist_target(target),
+            output=output,
+            yes=yes,
+        )
+    except SkillAlreadyExists as exc:
+        raise CliError(already_exists_to_text(exc)) from exc
+    except SkillDistError as exc:
+        raise CliError(str(exc)) from exc
+
+    if ctx.obj.get("json"):
+        emit(ctx, status.to_dict())
+    else:
+        typer.echo(install_to_text(status))
+
+
+def _skill_dist_target(target: SkillTarget) -> str:
+    return target.value
+
+
+app.command("whoami")(whoami)
+app.add_typer(vaults.app, name="vault")
+app.add_typer(items.app, name="item")
+app.add_typer(tags.app, name="tag")
+app.add_typer(public.app, name="public")
+app.add_typer(skill_app, name="skill")
+
+
+def run() -> None:
+    try:
+        app()
+    except CliError as exc:
+        typer.secho(exc.message, fg=typer.colors.RED, err=True)
+        sys.exit(exc.exit_code)

kivault_cli/bundled_skills/kivault-cli/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: kivault-cli
+description: Use the KiVault CLI from this repository to manage KiVault data through the HTTP API. Use when an agent needs to check KiVault health or identity, configure or run the CLI, create/list/update/delete vaults, create/search/export items, upload/download item objects, manage tags, or read public KiVault items and objects. Also use for Chinese requests mentioning KiVault CLI, Vault, Item, Object, Tag, 公开读取, 上传附件, 下载附件, or token/server configuration.
+---
+
+# KiVault CLI
+
+Use this skill to operate the local KiVault command-line client safely and consistently.
+
+## Quick Start
+
+Assume the CLI is installed and available as `kivault`. Check the current CLI version when behavior matters:
+
+```bash
+kivault --version
+kivault --help
+```
+
+Run commands from the user's current working directory unless a file path or repository checkout path requires otherwise.
+
+Set these environment variables for authenticated commands:
+
+```bash
+export KIVAULT_SERVER_URL=http://127.0.0.1:8000
+export KIVAULT_TOKEN=<token>
+```
+
+`KIVAULT_SERVER_URL` defaults to `http://127.0.0.1:8000`. The CLI has no login command and does not persist tokens.
+
+## Operating Rules
+
+- Use `--json` for commands whose output will be parsed by an agent or script.
+- `item list` uses the v2 search endpoint. In `--json` mode it returns a page object with `items`, `limit`, `offset`, and `total`, not a bare array.
+- Use `kivault upgrade` to check the release service. Only run `kivault upgrade --yes` when the user explicitly wants to install the latest wheel.
+- Set `KIVAULT_PLAIN_HELP=1` before help commands when plain text is easier to capture.
+- Never print or echo `KIVAULT_TOKEN`; `whoami` is safe because it reports token presence and server identity.
+- Prefer `--no-wait` for file or object uploads in agent shell tools, then poll with `item object upload-task` or `item object upload-task-wait`.
+- Use `--yes` only for deletes the user explicitly requested.
+- Distinguish text content from file uploads: `--content-file` reads UTF-8 text into `Item.content_text`; binary/PDF/image uploads must use `item add-file` or `item object upload`.
+
+## Workflow
+
+1. Check the server and auth context before mutating data:
+
+```bash
+kivault health
+kivault --version
+kivault whoami
+```
+
+2. Use `vault`, `item`, `item object`, `tag`, or `public` commands depending on the task.
+3. Read [command-guide.md](references/command-guide.md) before composing non-trivial command sequences, uploads, downloads, public access flows, or destructive operations.
+4. Capture IDs from JSON output, then pass those IDs to follow-up commands.
+
+## Common Patterns
+
+Create a vault, add Markdown text, and export it:
+
+```bash
+kivault --json vault create Inbox
+kivault --json item add-text --vault-id <vault-id> --title "Note.md" --content-file ./note.md
+kivault item export <item-id> --format markdown --output ./note.md
+```
+
+Search items with v2 field filters:
+
+```bash
+kivault --json item list -q report --search-field title --search-field object_filename --limit 20
+```
+
+Check for a CLI upgrade without installing:
+
+```bash
+kivault upgrade
+```
+
+Upload a file without long blocking waits:
+
+```bash
+kivault --json item add-file ./document.pdf --vault-id <vault-id> --no-wait
+kivault --json item object upload-task <item-id> <task-id>
+kivault --json item object upload-task-wait <item-id> <task-id>
+```
+
+Download an object:
+
+```bash
+kivault item object download <item-id> <object-id> --output ./document.pdf
+```
+
+## Validation
+
+For CLI code changes, run the project tests:
+
+```bash
+.venv/bin/python -m pytest . -q
+```

kivault_cli/bundled_skills/kivault-cli/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "KiVault CLI"
+  short_description: "Use the KiVault command-line client"
+  default_prompt: "Use $kivault-cli to manage KiVault vaults, items, objects, tags, and public reads."

kivault_cli/bundled_skills/kivault-cli/references/command-guide.md

@@ -0,0 +1,171 @@
+# KiVault CLI Command Guide
+
+Use this reference for command composition. Assume the CLI is installed as `kivault`; do not run it through `python main.py` unless the user explicitly asks to work from a source checkout.
+
+## Environment
+
+Authenticated commands need `KIVAULT_TOKEN`.
+
+```bash
+export KIVAULT_SERVER_URL=http://127.0.0.1:8000
+export KIVAULT_TOKEN=<token>
+```
+
+Use `--server <url>` to override the server for one command:
+
+```bash
+kivault --server http://127.0.0.1:8000 whoami
+```
+
+Check the CLI version:
+
+```bash
+kivault --version
+```
+
+Check or install the latest wheel from the KiSpace release service:
+
+```bash
+kivault upgrade
+kivault upgrade --yes
+```
+
+`upgrade` reads `https://releases.kispace.cc/api/public/latest?app=kivault_cli&tags=default`. Without `--yes`, it only reports `current`, `latest`, and the wheel URL. Use `--yes` only when the user explicitly approves installing the latest wheel.
+
+Use `--json` when the next step needs IDs or structured data:
+
+```bash
+kivault --json item list --vault-id <vault-id>
+```
+
+For `item list`, JSON output is a v2 search page object:
+
+```json
+{"items": [], "limit": 50, "offset": 0, "total": 0}
+```
+
+## Health and Identity
+
+```bash
+kivault health
+kivault whoami
+```
+
+`health` does not require auth. `whoami` calls `/api/whoami` and reports current server URL plus whether `KIVAULT_TOKEN` is set.
+
+## Vaults
+
+```bash
+kivault --json vault list
+kivault --json vault create Inbox
+kivault --json vault create Public --visibility public --default-level public --description "公开资料"
+kivault --json vault get <vault-id>
+kivault --json vault update <vault-id> --name Archive
+kivault --json vault update <vault-id> --visibility public --default-level public
+kivault --json vault delete <vault-id> --yes
+```
+
+Vault visibility values are `private` and `public`. Default item level values are `public`, `private`, `sensitive`, and `danger`.
+
+## Items
+
+List and search:
+
+```bash
+kivault --json item list --vault-id <vault-id> --limit 50
+kivault --json item list --keyword "deploy note" --type markdown
+kivault --json item list -q report --search-field title --search-field object_filename
+kivault --json item list --tag-id <tag-id> --level private
+```
+
+`item list` calls `/api/v2/items/search`. Use `--search-field` to constrain keyword matching; repeat it for multiple fields. Valid search fields are `title`, `content`, `metadata`, `object_filename`, and `object_key`.
+
+Create text or Markdown:
+
+```bash
+kivault --json item add-text --vault-id <vault-id> --title "Note" --content "hello"
+kivault --json item add-text --vault-id <vault-id> --title "Note.md" --content-file ./note.md
+```
+
+Use `item create` when more fields are needed:
+
+```bash
+kivault --json item create --vault-id <vault-id> --title "Web clip" --type markdown --source-url https://example.com --source-type web --metadata '{"kind":"clip"}'
+```
+
+Update, read, export, delete:
+
+```bash
+kivault --json item get <item-id>
+kivault --json item update <item-id> --title "New title"
+kivault --json item update <item-id> --content-file ./note.md --tag-id <tag-a> --tag-id <tag-b>
+kivault item export <item-id> --format markdown --output ./item.md
+kivault --json item export <item-id> --format json
+kivault --json item delete <item-id> --yes
+```
+
+Item type values are `text`, `markdown`, `html`, `web_page`, `image`, `audio`, `video`, `pdf`, `document`, `spreadsheet`, `structured_data`, `file`, and `other`. Status values are `active`, `archived`, and `deleted`.
+
+## File Items and Objects
+
+Create an item and upload an initial attachment:
+
+```bash
+kivault --json item add-file ./document.pdf --vault-id <vault-id> --no-wait
+```
+
+Add one or more objects to an existing item:
+
+```bash
+kivault --json item object upload <item-id> ./a.pdf ./b.png --no-wait
+kivault --json item object upload-multipart <item-id> ./a.pdf ./b.md --no-wait
+```
+
+Both upload commands create asynchronous upload tasks. The current implementation sends base64 JSON payloads; `upload-multipart` is a compatibility command name.
+
+Check or wait for a task:
+
+```bash
+kivault --json item object upload-task <item-id> <task-id>
+kivault --json item object upload-task-wait <item-id> <task-id> --poll-interval 1 --timeout 600
+```
+
+List, inspect, download, or delete objects:
+
+```bash
+kivault --json item object list <item-id>
+kivault --json item object get <item-id> <object-id>
+kivault item object download <item-id> <object-id> --output ./document.pdf
+kivault --json item object delete <item-id> <object-id> --yes
+```
+
+Upload limits from the README: each file must be under 100 MB, and one task can include at most 20 files.
+
+## Tags
+
+```bash
+kivault --json tag list
+kivault --json tag create research --color '#3b82f6'
+kivault --json tag update <tag-id> --name reading
+kivault --json tag add <tag-id> <item-id>
+kivault --json tag remove <tag-id> <item-id>
+kivault --json tag delete <tag-id> --yes
+```
+
+## Public Reads
+
+Public commands do not require auth. They work only when the vault is public, the item level is public, and the item status is active.
+
+```bash
+kivault --json public item <item-id>
+kivault public download-object <item-id> <object-id> --output ./file.pdf
+```
+
+## Help
+
+Use plain help for command discovery:
+
+```bash
+KIVAULT_PLAIN_HELP=1 kivault item create --help
+KIVAULT_PLAIN_HELP=1 kivault item object upload --help
+```