sanka-cli 0.2.1__tar.gz → 0.2.2__tar.gz

{sanka_cli-0.2.1 → sanka_cli-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sanka-cli
-Version: 0.2.1
+Version: 0.2.2
 Summary: Sanka command-line interface and migration runtime
 Project-URL: Repository, https://github.com/sankaHQ/sanka
 Project-URL: Issues, https://github.com/sankaHQ/sanka/issues
@@ -54,6 +54,19 @@ uv tool install 'sanka-cli[mcp]'
 sanka mcp
 ```
 
+Install the bundled `sanka-cli` skill into an AI coding harness:
+
+```bash
+sanka skill install claude
+sanka skill install codex --scope project
+sanka skill install --scope global
+```
+
+The command prompts for project or global scope when `--scope` is omitted.
+Without a harness argument, it installs into every detected Claude Code or
+Codex CLI. Existing matching installs are left unchanged; different content
+requires `--force`.
+
 The base tool does not install framework migrations or provider drivers.
 Components are immutable GitHub release wheels selected through the extension
 manager:

{sanka_cli-0.2.1 → sanka_cli-0.2.2}/README.md

@@ -24,6 +24,19 @@ uv tool install 'sanka-cli[mcp]'
 sanka mcp
 ```
 
+Install the bundled `sanka-cli` skill into an AI coding harness:
+
+```bash
+sanka skill install claude
+sanka skill install codex --scope project
+sanka skill install --scope global
+```
+
+The command prompts for project or global scope when `--scope` is omitted.
+Without a harness argument, it installs into every detected Claude Code or
+Codex CLI. Existing matching installs are left unchanged; different content
+requires `--force`.
+
 The base tool does not install framework migrations or provider drivers.
 Components are immutable GitHub release wheels selected through the extension
 manager:

{sanka_cli-0.2.1 → sanka_cli-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sanka-cli"
-version = "0.2.1"
+version = "0.2.2"
 description = "Sanka command-line interface and migration runtime"
 readme = "README.md"
 requires-python = ">=3.12"

{sanka_cli-0.2.1 → sanka_cli-0.2.2}/src/sanka_cli/__init__.py

@@ -1,4 +1,4 @@
 # SPDX-License-Identifier: Apache-2.0
 __all__ = ["__version__"]
 
-__version__ = "0.2.1"
+__version__ = "0.2.2"

sanka_cli-0.2.2/src/sanka_cli/commands/skill.py

@@ -0,0 +1,146 @@
+# SPDX-License-Identifier: Apache-2.0
+from __future__ import annotations
+
+import hashlib
+import os
+import shutil
+import tempfile
+from importlib import resources
+from pathlib import Path
+
+import click
+
+import sanka_cli.runtime as runtime
+from sanka_cli.state import CLIState
+
+SKILL_NAME = "sanka-cli"
+HARNESSES = ("claude", "codex")
+CONFIG_ROOTS = {
+    "claude": ("CLAUDE_CONFIG_DIR", ".claude"),
+    "codex": ("CODEX_HOME", ".codex"),
+}
+
+
+def _skill_content() -> bytes:
+    return resources.files("sanka_cli").joinpath("skills", SKILL_NAME, "SKILL.md").read_bytes()
+
+
+def _target_directory(harness: str, scope: str, project_directory: Path) -> Path:
+    environment_name, default_directory = CONFIG_ROOTS[harness]
+    if scope == "project":
+        root = project_directory.resolve() / f".{harness}"
+    else:
+        configured_root = os.environ.get(environment_name)
+        root = (
+            Path(configured_root).expanduser()
+            if configured_root
+            else Path.home() / default_directory
+        )
+    return root / "skills" / SKILL_NAME
+
+
+def _reject_project_symlinks(project_directory: Path, target: Path) -> None:
+    current = project_directory.resolve()
+    for part in (*target.relative_to(current).parts, "SKILL.md"):
+        current /= part
+        if current.is_symlink():
+            raise click.ClickException(
+                f"Refusing project installation through symbolic link: {current}"
+            )
+
+
+def _planned_status(target: Path, content: bytes, *, force: bool) -> str:
+    skill_file = target / "SKILL.md"
+    try:
+        if skill_file.is_file() and skill_file.read_bytes() == content:
+            return "unchanged"
+        if target.exists() and not force:
+            raise click.ClickException(
+                f"{target} already exists with different content; "
+                "rerun with --force to replace SKILL.md."
+            )
+        return "updated" if target.exists() else "installed"
+    except OSError as exc:
+        raise click.ClickException(f"Could not inspect {target}: {exc}") from exc
+
+
+def _write_skill(target: Path, content: bytes) -> None:
+    temporary_path: Path | None = None
+    try:
+        target.mkdir(parents=True, exist_ok=True)
+        with tempfile.NamedTemporaryFile(
+            mode="wb", dir=target, prefix=".SKILL.md.", delete=False
+        ) as file:
+            file.write(content)
+            temporary_path = Path(file.name)
+        os.replace(temporary_path, target / "SKILL.md")
+    except OSError as exc:
+        raise click.ClickException(f"Could not install {SKILL_NAME} at {target}: {exc}") from exc
+    finally:
+        if temporary_path is not None:
+            temporary_path.unlink(missing_ok=True)
+
+
+@click.group()
+def skill() -> None:
+    """Install Sanka skills into supported AI coding harnesses."""
+
+
+@skill.command("install")
+@click.argument("harness", required=False, type=click.Choice(HARNESSES))
+@click.option("--scope", type=click.Choice(["project", "global"]), default=None)
+@click.option(
+    "--project-dir",
+    type=click.Path(exists=True, file_okay=False, path_type=Path),
+    default=Path("."),
+    show_default=True,
+)
+@click.option("--force", is_flag=True, help="Replace a different installed SKILL.md.")
+@click.pass_obj
+def install_skill(
+    state: CLIState,
+    harness: str | None,
+    scope: str | None,
+    project_dir: Path,
+    force: bool,
+) -> None:
+    """Install the sanka-cli skill for Claude Code, Codex, or detected harnesses."""
+    harnesses = [harness] if harness else [name for name in HARNESSES if shutil.which(name)]
+    if not harnesses:
+        raise click.ClickException(
+            "No supported harness detected. Pass `claude` or `codex` explicitly."
+        )
+    resolved_scope = scope or click.prompt(
+        "Install scope",
+        type=click.Choice(["project", "global"]),
+        default="project",
+        err=True,
+    )
+    content = _skill_content()
+    plans: list[tuple[str, Path, str]] = []
+    for harness_name in harnesses:
+        target = _target_directory(harness_name, resolved_scope, project_dir)
+        if resolved_scope == "project":
+            _reject_project_symlinks(project_dir, target)
+        plans.append((harness_name, target, _planned_status(target, content, force=force)))
+
+    installations = []
+    for harness_name, target, status in plans:
+        if status != "unchanged":
+            _write_skill(target, content)
+        installations.append(
+            {
+                "harness": harness_name,
+                "path": str(target),
+                "status": status,
+            }
+        )
+    runtime.emit_payload(
+        {
+            "skill": SKILL_NAME,
+            "scope": resolved_scope,
+            "content_sha256": hashlib.sha256(content).hexdigest(),
+            "installations": installations,
+        },
+        state,
+    )

{sanka_cli-0.2.1 → sanka_cli-0.2.2}/src/sanka_cli/main.py

@@ -10,6 +10,7 @@ from sanka_cli.commands.code import code
 from sanka_cli.commands.migrate import register_migration_passthroughs
 from sanka_cli.commands.profiles import profiles
 from sanka_cli.commands.resources import attach_resource_group
+from sanka_cli.commands.skill import skill
 from sanka_cli.commands.workflows import workflows
 from sanka_cli.output import print_error
 from sanka_cli.state import CLIState
@@ -43,6 +44,7 @@ cli.add_command(profiles)
 cli.add_command(workflows)
 cli.add_command(ai)
 cli.add_command(code)
+cli.add_command(skill)
 
 attach_resource_group(cli, "companies", "/v2/public/companies")
 attach_resource_group(cli, "contacts", "/v2/public/contacts")

sanka_cli-0.2.2/src/sanka_cli/skills/sanka-cli/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: sanka-cli
+description: Use when inspecting, planning, applying, testing, verifying, or monitoring application and data migrations with the sanka command-line interface.
+---
+
+# Sanka CLI
+
+Use `sanka` for application modernization and data movement. Derive the migration mode and destination from the user's task; never assume FastAPI or any other target.
+
+## Choose the migration mode
+
+Run `sanka --help`, the selected command's `--help`, and `sanka extension list --json` before choosing options. Do not guess target names, component IDs, or flags.
+
+- **Application migration:** a source repository is converted to a task-selected framework or runtime. Use target-specific flags only when the task and command help require them.
+- **Data migration:** records move between task-selected systems described by `sanka.yaml`. Use environment references for credentials and install only the required trusted extensions after authorization.
+
+## Application migration
+
+```bash
+sanka scan . --json
+sanka plan . --json
+sanka apply --root . --plan-hash <reviewed-plan-hash> --json
+sanka test . --json
+sanka verify . --json
+```
+
+Add task-specific plan, output, or target options from `sanka plan --help`; the sequence does not imply a particular destination.
+
+## Data migration
+
+Define the source and target in `sanka.yaml`. This is the basic shape; use exact types and options reported by installed extensions:
+
+```yaml
+source:
+  type: <source-type>
+  connection: <path-or-environment-reference>
+target:
+  type: <target-type>
+  connection: <path-or-environment-reference>
+```
+
+Then run:
+
+```bash
+sanka plan --json
+sanka validate --json
+sanka apply --plan-hash <reviewed-plan-hash> --json
+sanka verify --json
+sanka status
+```
+
+`validate` checks source records against the plan without writing to the destination. Review its result before applying. Use `sanka extension --help` when a required source, target, or migration capability is not installed.
+
+## Safety boundary
+
+- Planning must not write to the destination. Review the source, target, mappings, readiness, limitations, output path, and exact `plan_hash`.
+- Get explicit user authorization immediately before `apply`; apply only the reviewed hash.
+- Treat source behavior and the task contract as authoritative. Generated applications require parity verification; data `apply` performs real destination writes.
+- If pre-write testing or validation fails, fix the plan or configuration and re-plan. If post-write verification fails, inspect `status`; never rerun `apply` blindly. Any changed plan requires review and authorization of its new hash.
+- Never silently switch between local and hosted execution. Use the configured profile only when the task selects hosted operation.
+- Use `--bench-candidate <path>` on `sanka apply` only when a benchmark task requests that artifact layout.
+- Do not expose credentials in command arguments, logs, generated files, or reports.

{sanka_cli-0.2.1 → sanka_cli-0.2.2}/tests/test_cli.py

@@ -550,7 +550,7 @@ def test_research_client_uses_public_branded_base_and_unwraps_data() -> None:
         "after": ["2027-01"],
         "locale": ["ja"],
     }
-    assert request.get_header("User-agent") == "sanka-cli/0.2.1"
+    assert request.get_header("User-agent") == "sanka-cli/0.2.2"
     assert timeout == 10.0
 
 

{sanka_cli-0.2.1 → sanka_cli-0.2.2}/tests/test_mcp.py

@@ -21,7 +21,7 @@ def test_root_version_uses_unified_public_version(runner: CliRunner) -> None:
     result = runner.invoke(cli, ["--version"])
 
     assert result.exit_code == 0
-    assert result.output == "sanka, version 0.2.1\n"
+    assert result.output == "sanka, version 0.2.2\n"
 
 
 def test_mcp_client_uses_the_cli_version_in_its_user_agent() -> None:
@@ -29,7 +29,7 @@ def test_mcp_client_uses_the_cli_version_in_its_user_agent() -> None:
 
     client = SankaMigrateApiClient()
 
-    assert client._client.headers["User-Agent"] == "sanka-cli/0.2.1"
+    assert client._client.headers["User-Agent"] == "sanka-cli/0.2.2"
 
 
 def test_mcp_without_extra_has_install_hint(

{sanka_cli-0.2.1 → sanka_cli-0.2.2}/tests/test_sanka_facade.py

@@ -35,7 +35,7 @@ def test_public_facade_version_matches_unified_distribution() -> None:
         == sanka_cli.__version__
         == sanka_cli.mcp.__version__
         == distribution_version("sanka-cli")
-        == "0.2.1"
+        == "0.2.2"
     )
 
 

sanka_cli-0.2.2/tests/test_skill_commands.py

@@ -0,0 +1,219 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+from click.testing import CliRunner
+
+from sanka_cli.main import cli
+
+
+@pytest.fixture
+def runner() -> CliRunner:
+    return CliRunner()
+
+
+def test_install_claude_skill_in_project(runner: CliRunner, tmp_path: Path) -> None:
+    result = runner.invoke(
+        cli,
+        [
+            "--output",
+            "json",
+            "skill",
+            "install",
+            "claude",
+            "--scope",
+            "project",
+            "--project-dir",
+            str(tmp_path),
+        ],
+    )
+
+    assert result.exit_code == 0, result.output
+    skill_file = tmp_path / ".claude" / "skills" / "sanka-cli" / "SKILL.md"
+    assert skill_file.is_file()
+    assert skill_file.read_text().startswith("---\nname: sanka-cli\n")
+    assert json.loads(result.output)["installations"] == [
+        {
+            "harness": "claude",
+            "path": str(skill_file.parent),
+            "status": "installed",
+        }
+    ]
+
+
+@pytest.mark.parametrize(
+    ("harness", "environment_name", "config_directory"),
+    [
+        ("claude", "CLAUDE_CONFIG_DIR", ".claude-test"),
+        ("codex", "CODEX_HOME", ".codex-test"),
+    ],
+)
+def test_install_skill_globally(
+    runner: CliRunner,
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+    harness: str,
+    environment_name: str,
+    config_directory: str,
+) -> None:
+    config_root = tmp_path / config_directory
+    monkeypatch.setenv(environment_name, str(config_root))
+
+    result = runner.invoke(
+        cli,
+        ["--output", "json", "skill", "install", harness, "--scope", "global"],
+    )
+
+    assert result.exit_code == 0, result.output
+    assert (config_root / "skills" / "sanka-cli" / "SKILL.md").is_file()
+
+
+def test_install_prompts_for_scope(runner: CliRunner, tmp_path: Path) -> None:
+    result = runner.invoke(
+        cli,
+        ["--output", "json", "skill", "install", "codex", "--project-dir", str(tmp_path)],
+        input="project\n",
+    )
+
+    assert result.exit_code == 0, result.output
+    assert "Install scope (project, global) [project]:" in result.stderr
+    assert json.loads(result.stdout)["scope"] == "project"
+    assert (tmp_path / ".codex" / "skills" / "sanka-cli" / "SKILL.md").is_file()
+
+
+def test_install_without_harness_detects_available_harnesses(
+    runner: CliRunner,
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    bin_directory = tmp_path / "bin"
+    bin_directory.mkdir()
+    for executable_name in ("claude", "codex"):
+        executable = bin_directory / executable_name
+        executable.touch(mode=0o755)
+    monkeypatch.setenv("PATH", str(bin_directory))
+
+    result = runner.invoke(
+        cli,
+        [
+            "--output",
+            "json",
+            "skill",
+            "install",
+            "--scope",
+            "project",
+            "--project-dir",
+            str(tmp_path),
+        ],
+    )
+
+    assert result.exit_code == 0, result.output
+    payload = json.loads(result.output)
+    assert [item["harness"] for item in payload["installations"]] == ["claude", "codex"]
+
+
+def test_install_is_idempotent_and_refuses_conflicts_without_force(
+    runner: CliRunner,
+    tmp_path: Path,
+) -> None:
+    arguments = [
+        "--output",
+        "json",
+        "skill",
+        "install",
+        "claude",
+        "--scope",
+        "project",
+        "--project-dir",
+        str(tmp_path),
+    ]
+    assert runner.invoke(cli, arguments).exit_code == 0
+
+    unchanged = runner.invoke(cli, arguments)
+    assert unchanged.exit_code == 0
+    assert json.loads(unchanged.output)["installations"][0]["status"] == "unchanged"
+
+    skill_file = tmp_path / ".claude" / "skills" / "sanka-cli" / "SKILL.md"
+    skill_file.write_text("local changes\n")
+    conflict = runner.invoke(cli, arguments)
+    assert conflict.exit_code == 1
+    assert "already exists with different content" in conflict.output
+    assert skill_file.read_text() == "local changes\n"
+
+    updated = runner.invoke(cli, [*arguments, "--force"])
+    assert updated.exit_code == 0
+    assert json.loads(updated.output)["installations"][0]["status"] == "updated"
+    assert skill_file.read_text().startswith("---\nname: sanka-cli\n")
+
+
+def test_detected_harness_conflict_does_not_partially_install(
+    runner: CliRunner,
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    bin_directory = tmp_path / "bin"
+    bin_directory.mkdir()
+    for executable_name in ("claude", "codex"):
+        executable = bin_directory / executable_name
+        executable.touch(mode=0o755)
+    monkeypatch.setenv("PATH", str(bin_directory))
+    codex_skill = tmp_path / ".codex" / "skills" / "sanka-cli" / "SKILL.md"
+    codex_skill.parent.mkdir(parents=True)
+    codex_skill.write_text("local changes\n")
+
+    result = runner.invoke(
+        cli,
+        [
+            "skill",
+            "install",
+            "--scope",
+            "project",
+            "--project-dir",
+            str(tmp_path),
+        ],
+    )
+
+    assert result.exit_code == 1
+    assert not (tmp_path / ".claude" / "skills" / "sanka-cli").exists()
+    assert codex_skill.read_text() == "local changes\n"
+
+
+@pytest.mark.parametrize("symlink_target", ["directory", "file"])
+def test_project_install_refuses_symlinked_destination(
+    runner: CliRunner,
+    tmp_path: Path,
+    symlink_target: str,
+) -> None:
+    outside_directory = tmp_path / "outside"
+    outside_directory.mkdir()
+    outside_file = outside_directory / "outside.md"
+    outside_file.write_text("keep me\n")
+    project = tmp_path / "project"
+    skill_file = project / ".claude" / "skills" / "sanka-cli" / "SKILL.md"
+    if symlink_target == "directory":
+        skill_file.parent.parent.mkdir(parents=True)
+        skill_file.parent.symlink_to(outside_directory, target_is_directory=True)
+    else:
+        skill_file.parent.mkdir(parents=True)
+        skill_file.symlink_to(outside_file)
+
+    result = runner.invoke(
+        cli,
+        [
+            "skill",
+            "install",
+            "claude",
+            "--scope",
+            "project",
+            "--project-dir",
+            str(project),
+            "--force",
+        ],
+    )
+
+    assert result.exit_code == 1
+    assert "symbolic link" in result.output
+    assert outside_file.read_text() == "keep me\n"