onehouse-cli 0.2.0__tar.gz → 0.3.0__tar.gz

{onehouse_cli-0.2.0 → onehouse_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: onehouse-cli
-Version: 0.2.0
+Version: 0.3.0
 Summary: A command-line tool for the full Onehouse API
 Author-email: Sagar Lakshmipathy <18vidhyasagar@gmail.com>
 License: Proprietary
@@ -33,6 +33,20 @@ pip install onehouse-cli
 
 The SDK dependency (`onehouse-python-sdk[resources]`) is installed automatically.
 
+## AI agent integration
+
+The package bundles a skill that teaches AI coding agents how to use `oh`. Install it for your agent:
+
+```bash
+oh install agent-skill --claude    # ~/.claude/skills/onehouse-cli
+oh install agent-skill --cursor    # ~/.cursor/skills/onehouse-cli
+oh install agent-skill --codex     # ~/.agents/skills/onehouse-cli
+oh install agent-skill --all       # all of the above
+oh install agent-skill --all --dry-run
+```
+
+Re-run the command after `pip install --upgrade onehouse-cli` to refresh the skill. To read the skill without installing it, run `oh skill`.
+
 ## Setup
 
 **Configure credentials:**

{onehouse_cli-0.2.0 → onehouse_cli-0.3.0}/README.md

@@ -10,6 +10,20 @@ pip install onehouse-cli
 
 The SDK dependency (`onehouse-python-sdk[resources]`) is installed automatically.
 
+## AI agent integration
+
+The package bundles a skill that teaches AI coding agents how to use `oh`. Install it for your agent:
+
+```bash
+oh install agent-skill --claude    # ~/.claude/skills/onehouse-cli
+oh install agent-skill --cursor    # ~/.cursor/skills/onehouse-cli
+oh install agent-skill --codex     # ~/.agents/skills/onehouse-cli
+oh install agent-skill --all       # all of the above
+oh install agent-skill --all --dry-run
+```
+
+Re-run the command after `pip install --upgrade onehouse-cli` to refresh the skill. To read the skill without installing it, run `oh skill`.
+
 ## Setup
 
 **Configure credentials:**

onehouse_cli-0.3.0/onehouse_cli/__init__.py

@@ -0,0 +1,32 @@
+"""
+Onehouse CLI - A command-line tool for executing SQL commands against the Onehouse API.
+"""
+
+try:
+    # For Python 3.8+
+    from importlib.metadata import version
+except ImportError:
+    # For Python 3.7
+    from importlib_metadata import version
+
+try:
+    __version__ = version("onehouse-cli")
+except Exception:
+    # Fallback version if package is not installed
+    __version__ = "0.0.0.dev"
+
+__all__ = ["cli_main", "configure_main"]
+
+
+# Imported lazily (PEP 562) so that pulling in a leaf module does not drag in
+# the whole command tree — and with it the SDK dependency. This keeps
+# `oh-skill` readable on an install where onehouse-python-sdk is missing,
+# which is precisely when someone needs the usage guide.
+def __getattr__(name):
+    if name == "cli_main":
+        from .cli import main
+        return main
+    if name == "configure_main":
+        from .configure import main
+        return main
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

{onehouse_cli-0.2.0 → onehouse_cli-0.3.0}/onehouse_cli/cli.py

@@ -5,7 +5,6 @@ Global options (--profile, --timeout, --output) are propagated to every
 subcommand via the Click context object (ctx.obj).
 """
 
-import sys
 import click
 
 from . import __version__
@@ -22,10 +21,21 @@ from .commands import (
     job,
     service_principal,
     api_token,
+    install,
+    skill as skill_cmd,
     sql as sql_cmd,
 )
 
 
+_EPILOG = """\
+Agents and new users: run `oh skill` for a complete usage guide covering
+credential setup, the SQL each command emits, and destructive-operation safety.
+
+Note: deletes execute immediately with no confirmation prompt. Use --show-sql
+on any command to preview the statement without running it.
+"""
+
+
 class CliContext:
     def __init__(self, profile: str | None, timeout: int, output: str):
         self.profile = profile
@@ -33,7 +43,10 @@ class CliContext:
         self.output = output
 
 
-@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+@click.group(
+    context_settings={"help_option_names": ["-h", "--help"]},
+    epilog=_EPILOG,
+)
 @click.version_option(__version__, "-v", "--version")
 @click.option(
     "--profile", "-p",
@@ -75,10 +88,14 @@ cli.add_command(job.job)
 cli.add_command(service_principal.service_principal, name="service-principal")
 cli.add_command(api_token.api_token, name="api-token")
 cli.add_command(sql_cmd.sql)
+cli.add_command(skill_cmd.skill)
+cli.add_command(install.install)
 
 
 def main() -> None:
-    sys.exit(cli(standalone_mode=False) or 0)
+    # Standalone mode turns Click errors into a one-line `Error: ...` message
+    # and the conventional exit code (1 = failure, 2 = usage error).
+    cli()
 
 
 if __name__ == "__main__":

onehouse_cli-0.3.0/onehouse_cli/commands/install.py

@@ -0,0 +1,77 @@
+"""Install bundled assets into other tools.
+
+  oh install agent-skill --claude     ~/.claude/skills/onehouse-cli
+  oh install agent-skill --cursor     ~/.cursor/skills/onehouse-cli
+  oh install agent-skill --codex      ~/.agents/skills/onehouse-cli
+  oh install agent-skill --all        every platform above
+
+All three read the open agent skills layout (a directory holding SKILL.md),
+so every target receives an identical copy of the bundled skill.
+"""
+
+from pathlib import Path
+import shutil
+
+import click
+
+from .skill import SKILL_NAME, skill_dir
+
+# Platform flag -> skills root, relative to the user's home directory.
+PLATFORMS = {
+    "claude": Path(".claude") / "skills",
+    "cursor": Path(".cursor") / "skills",
+    "codex": Path(".agents") / "skills",
+}
+
+
+def install_path(platform: str) -> Path:
+    """Directory the skill is copied to for ``platform``."""
+    return Path.home() / PLATFORMS[platform] / SKILL_NAME
+
+
+@click.group("install")
+def install():
+    """Install bundled assets into other tools."""
+
+
+@install.command("agent-skill")
+@click.option("--claude", is_flag=True, help="Install for Claude Code (~/.claude/skills).")
+@click.option("--cursor", is_flag=True, help="Install for Cursor (~/.cursor/skills).")
+@click.option("--codex", is_flag=True, help="Install for OpenAI Codex CLI (~/.agents/skills).")
+@click.option("--all", "all_", is_flag=True, help="Install for every supported platform.")
+@click.option("--dry-run", is_flag=True, help="Print what would be written without writing it.")
+def agent_skill(claude, cursor, codex, all_, dry_run):
+    """Install the onehouse-cli skill for AI coding agents.
+
+    Re-run after upgrading onehouse-cli to refresh the installed copy; an
+    existing copy is replaced.
+    """
+    selected = {"claude": claude, "cursor": cursor, "codex": codex}
+    targets = list(PLATFORMS) if all_ else [p for p, on in selected.items() if on]
+    if not targets:
+        raise click.UsageError("Choose at least one of --claude, --cursor, --codex, or --all.")
+
+    src = skill_dir()
+    if not (src / "SKILL.md").is_file():
+        raise click.ClickException(
+            "No bundled skill found. This build of onehouse-cli may predate the "
+            "skill, or package data was excluded at build time."
+        )
+    files = sorted(p.relative_to(src) for p in src.rglob("*") if p.is_file())
+
+    for platform in targets:
+        dest = install_path(platform)
+        if dry_run:
+            action = "replace" if dest.exists() else "create"
+            click.echo(f"[dry-run] {platform}: would {action} {dest}")
+            for rel in files:
+                click.echo(f"  {dest / rel}")
+            continue
+        if dest.exists():
+            shutil.rmtree(dest)
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copytree(src, dest)
+        click.echo(f"{platform}: installed {dest}")
+
+    if not dry_run:
+        click.echo("Restart the agent, or start a new session, to load the skill.")

onehouse_cli-0.3.0/onehouse_cli/commands/skill.py

@@ -0,0 +1,86 @@
+"""Serve the bundled agent skill.
+
+The skill ships inside the wheel, so ``oh skill`` works on any machine where
+the CLI is installed — no download, no repo checkout, no path resolution.
+
+Discovery paths, cheapest first:
+  oh skill                 print SKILL.md to stdout (agents: start here)
+  oh skill --list          list bundled documents
+  oh skill references/...  print a specific reference document
+  oh skill --path          print the on-disk directory
+
+To install the skill for an agent, use ``oh install agent-skill``.
+"""
+
+from pathlib import Path
+
+import click
+
+SKILL_NAME = "onehouse-cli"
+
+
+def skill_dir() -> Path:
+    """Absolute path to the bundled skill directory."""
+    return Path(__file__).resolve().parent.parent / "skills" / SKILL_NAME
+
+
+def _read(relative: str) -> str:
+    root = skill_dir()
+    target = (root / relative).resolve()
+    # Keep `oh skill ../../etc/passwd` from escaping the bundle. Compare path
+    # components, not strings, so a sibling like `onehouse-cli-x/` is rejected.
+    if target != root and root not in target.parents:
+        raise click.ClickException(f"Invalid document path: {relative}")
+    if not target.is_file():
+        raise click.ClickException(
+            f"No such document: {relative}. Run 'oh skill --list' to see what's bundled."
+        )
+    return target.read_text()
+
+
+def _documents() -> list[str]:
+    root = skill_dir()
+    if not root.is_dir():
+        return []
+    return sorted(str(p.relative_to(root)) for p in root.rglob("*.md"))
+
+
+@click.command("skill")
+@click.argument("document", required=False)
+@click.option("--path", "show_path", is_flag=True,
+              help="Print the on-disk path of the bundled skill and exit.")
+@click.option("--list", "do_list", is_flag=True,
+              help="List the bundled documents.")
+def skill(document, show_path, do_list):
+    """Print the agent usage guide for this CLI.
+
+    With no arguments, prints SKILL.md — a complete guide to installing,
+    configuring, and safely operating this CLI.
+    """
+    root = skill_dir()
+    if not root.is_dir():
+        raise click.ClickException(
+            "No bundled skill found. This build of onehouse-cli may predate the "
+            "skill, or package data was excluded at build time."
+        )
+
+    if show_path:
+        click.echo(str(root))
+        return
+
+    if do_list:
+        for name in _documents():
+            click.echo(name)
+        return
+
+    click.echo(_read(document or "SKILL.md"))
+
+
+def standalone() -> None:
+    """Entry point for the `oh-skill` script.
+
+    Deliberately separate from `oh skill`: this module imports nothing beyond
+    click and pathlib, so the guide stays readable even when the SDK
+    dependency is missing and `oh` itself cannot start.
+    """
+    skill(standalone_mode=True)