rawctx 0.1.0__tar.gz

rawctx-0.1.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: rawctx
+Version: 0.1.0
+Summary: rawctx CLI scaffold
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.1.7
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: PyYAML>=6.0.2
+Requires-Dist: jsonschema>=4.23.0
+Requires-Dist: ruamel.yaml>=0.18.6
+
+# rawctx CLI
+
+Python Click-based CLI for rawctx Hub.
+
+## Commands
+
+- `rawctx login [--registry URL] [--id-token JWT] [--token-name NAME] [--expires-in-days N] [--no-browser]`
+- `rawctx logout [--local-only]`
+- `rawctx publish [TARGET_DIR] [--registry URL]`
+- `rawctx search [QUERY] [--format F] [--domain D] [--source S] [--tags CSV] [--page N] [--size N] [--json] [--offline]`
+- `rawctx install PACKAGE_REF [--dest PATH] [--offline] [--force] [--registry URL]`
+- `rawctx info PACKAGE_REF [--json] [--offline] [--registry URL]`
+- `rawctx validate [TARGET] --format auto|manifest|osi`
+- `rawctx pack [TARGET_DIR] --output-dir dist`
+
+## Auth Flow (Auto + Fallback)
+
+1. Run `rawctx login`.
+2. CLI opens (or prints) the OAuth URL from `POST /api/auth/login/github`.
+3. Complete GitHub login in browser.
+4. CLI automatically polls OAuth session status and captures `id_token`.
+5. CLI calls `POST /api/auth/token` and stores API token in `~/.rawctx/config.yaml`.
+
+Manual fallback:
+
+- `rawctx login --id-token '<JWT>'`
+
+## Config and Environment
+
+Config file (default): `~/.rawctx/config.yaml`
+
+```yaml
+registry: "https://api.rawctx.dev"
+auth:
+  token: "rxctx_..."
+  token_id: "uuid"
+  token_name: "rawctx-cli"
+  issued_at: "2026-02-28T00:00:00+00:00"
+profile:
+  username: "owner"
+```
+
+Environment overrides:
+
+- `RAWCTX_CONFIG` (config path)
+- `RAWCTX_REGISTRY` (registry URL)
+- `RAWCTX_TOKEN` (auth token)
+
+Priority: CLI option > env var > config > default.
+
+## Offline Mode
+
+`--offline` is supported for:
+
+- `search`
+- `info`
+- `install`
+
+Cache paths:
+
+- index: `~/.rawctx/cache/packages.json`
+- archives: `~/.rawctx/cache/archives/@scope/name/<version>.rawctx.tar.gz`
+- installs: `~/.rawctx/packages/@scope/name/<version>/`

rawctx-0.1.0/README.md

@@ -0,0 +1,63 @@
+# rawctx CLI
+
+Python Click-based CLI for rawctx Hub.
+
+## Commands
+
+- `rawctx login [--registry URL] [--id-token JWT] [--token-name NAME] [--expires-in-days N] [--no-browser]`
+- `rawctx logout [--local-only]`
+- `rawctx publish [TARGET_DIR] [--registry URL]`
+- `rawctx search [QUERY] [--format F] [--domain D] [--source S] [--tags CSV] [--page N] [--size N] [--json] [--offline]`
+- `rawctx install PACKAGE_REF [--dest PATH] [--offline] [--force] [--registry URL]`
+- `rawctx info PACKAGE_REF [--json] [--offline] [--registry URL]`
+- `rawctx validate [TARGET] --format auto|manifest|osi`
+- `rawctx pack [TARGET_DIR] --output-dir dist`
+
+## Auth Flow (Auto + Fallback)
+
+1. Run `rawctx login`.
+2. CLI opens (or prints) the OAuth URL from `POST /api/auth/login/github`.
+3. Complete GitHub login in browser.
+4. CLI automatically polls OAuth session status and captures `id_token`.
+5. CLI calls `POST /api/auth/token` and stores API token in `~/.rawctx/config.yaml`.
+
+Manual fallback:
+
+- `rawctx login --id-token '<JWT>'`
+
+## Config and Environment
+
+Config file (default): `~/.rawctx/config.yaml`
+
+```yaml
+registry: "https://api.rawctx.dev"
+auth:
+  token: "rxctx_..."
+  token_id: "uuid"
+  token_name: "rawctx-cli"
+  issued_at: "2026-02-28T00:00:00+00:00"
+profile:
+  username: "owner"
+```
+
+Environment overrides:
+
+- `RAWCTX_CONFIG` (config path)
+- `RAWCTX_REGISTRY` (registry URL)
+- `RAWCTX_TOKEN` (auth token)
+
+Priority: CLI option > env var > config > default.
+
+## Offline Mode
+
+`--offline` is supported for:
+
+- `search`
+- `info`
+- `install`
+
+Cache paths:
+
+- index: `~/.rawctx/cache/packages.json`
+- archives: `~/.rawctx/cache/archives/@scope/name/<version>.rawctx.tar.gz`
+- installs: `~/.rawctx/packages/@scope/name/<version>/`

rawctx-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rawctx"
+version = "0.1.0"
+description = "rawctx CLI scaffold"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+  "click>=8.1.7",
+  "httpx>=0.28.1",
+  "PyYAML>=6.0.2",
+  "jsonschema>=4.23.0",
+  "ruamel.yaml>=0.18.6",
+]
+
+[project.scripts]
+rawctx = "rawctx.cli:main"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.setuptools.package-data]
+rawctx = ["schemas/**/*.json"]

rawctx-0.1.0/rawctx/__init__.py

@@ -0,0 +1,3 @@
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

rawctx-0.1.0/rawctx/cli.py

@@ -0,0 +1,34 @@
+import click
+
+from rawctx import __version__
+from rawctx.commands.info import info
+from rawctx.commands.install import install
+from rawctx.commands.login import login, logout
+from rawctx.commands.pack import pack
+from rawctx.commands.publish import publish
+from rawctx.commands.search import search
+from rawctx.commands.validate import validate
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+@click.version_option(version=__version__, prog_name="rawctx")
+@click.option("--debug", is_flag=True, default=False, help="Enable debug mode.")
+@click.pass_context
+def main(ctx: click.Context, debug: bool) -> None:
+    """rawctx CLI."""
+    ctx.ensure_object(dict)
+    ctx.obj["debug"] = debug
+
+
+main.add_command(publish)
+main.add_command(login)
+main.add_command(logout)
+main.add_command(search)
+main.add_command(install)
+main.add_command(info)
+main.add_command(validate)
+main.add_command(pack)
+
+
+if __name__ == "__main__":
+    main()

rawctx-0.1.0/rawctx/commands/__init__.py

@@ -0,0 +1 @@
+"""Command modules for rawctx CLI."""

rawctx-0.1.0/rawctx/commands/common.py

@@ -0,0 +1,5 @@
+import click
+
+
+def not_implemented(command_name: str) -> None:
+    click.echo(f"{command_name}: not implemented in Round 0")

rawctx-0.1.0/rawctx/commands/convert.py

@@ -0,0 +1,8 @@
+import click
+
+from .common import not_implemented
+
+
+@click.command()
+def convert() -> None:
+    not_implemented("convert")

rawctx-0.1.0/rawctx/commands/info.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+from dataclasses import asdict
+import json
+from typing import Any
+
+import click
+
+from rawctx.config import ConfigStore, cache_key, load_package_cache, resolve_registry, resolve_token, save_package_cache, upsert_cache_entry
+from rawctx.registry.client import RegistryClient, RegistryError
+from rawctx.registry.models import PackageDetail, VersionInfo, parse_package_ref
+
+
+@click.command()
+@click.argument("package_ref", required=True)
+@click.option("--json", "json_output", is_flag=True, default=False)
+@click.option("--offline", is_flag=True, default=False)
+@click.option("--registry", "registry_override", default=None, help="Registry base URL")
+def info(package_ref: str, json_output: bool, offline: bool, registry_override: str | None) -> None:
+    try:
+        parsed = parse_package_ref(package_ref)
+    except ValueError as exc:
+        raise click.UsageError(str(exc)) from exc
+
+    store = ConfigStore()
+    config = store.load()
+    cache = load_package_cache(store.paths)
+
+    package: PackageDetail
+    versions: list[VersionInfo]
+
+    if offline:
+        package, versions = _load_offline(cache, parsed.scope, parsed.name)
+    else:
+        registry = resolve_registry(cli_registry=registry_override, config=config)
+        token = resolve_token(config)
+        client = RegistryClient(registry=registry, token=token)
+        try:
+            package = client.get_package(scope=parsed.scope, name=parsed.name)
+            versions, _meta = client.list_versions(scope=parsed.scope, name=parsed.name, page=1, size=100)
+            upsert_cache_entry(
+                cache,
+                scope=parsed.scope,
+                name=parsed.name,
+                package=asdict(package),
+                versions=[asdict(item) for item in versions],
+            )
+            save_package_cache(store.paths, cache)
+        except RegistryError as exc:
+            raise click.ClickException(str(exc)) from exc
+        finally:
+            client.close()
+
+    selected_version = None
+    if parsed.version:
+        selected_version = next((item for item in versions if item.version == parsed.version), None)
+        if selected_version is None:
+            raise click.ClickException(f"Version not found: {parsed.normalized}")
+
+    if json_output:
+        payload = {
+            "package": asdict(package),
+            "versions": [asdict(item) for item in versions],
+            "selected_version": asdict(selected_version) if selected_version else None,
+        }
+        click.echo(json.dumps(payload, indent=2))
+        return
+
+    click.echo(f"Package: {package.package_name}")
+    click.echo(f"Description: {package.description or '-'}")
+    click.echo(f"Format: {package.format}")
+    click.echo(f"Source: {package.source or '-'}  Domain: {package.domain or '-'}")
+    click.echo(f"Downloads: {package.download_count}  Stars: {package.star_count}")
+    click.echo(f"Tags: {', '.join(package.tags) if package.tags else '-'}")
+
+    if selected_version:
+        click.echo(f"Version: {selected_version.version} ({selected_version.status})")
+        if selected_version.model_summary:
+            summary = selected_version.model_summary
+            click.echo(
+                "Model summary: "
+                f"datasets={summary.get('dataset_count', 0)} "
+                f"measures={summary.get('measure_count', 0)} "
+                f"dimensions={summary.get('dimension_count', 0)} "
+                f"relationships={summary.get('relationship_count', 0)}"
+            )
+    else:
+        if versions:
+            click.echo("Versions: " + ", ".join(item.version for item in versions))
+        else:
+            click.echo("Versions: -")
+
+
+def _load_offline(cache: dict[str, dict[str, Any]], scope: str, name: str) -> tuple[PackageDetail, list[VersionInfo]]:
+    entry = cache.get(cache_key(scope, name))
+    if not entry:
+        raise click.ClickException(f"No cached package found for @{scope}/{name}")
+
+    package_raw = entry.get("package")
+    if not isinstance(package_raw, dict):
+        raise click.ClickException(f"Cached package data is invalid for @{scope}/{name}")
+
+    versions_raw = entry.get("versions")
+    versions: list[VersionInfo] = []
+    if isinstance(versions_raw, list):
+        for item in versions_raw:
+            if isinstance(item, dict):
+                versions.append(VersionInfo.from_api(item))
+
+    return PackageDetail.from_api(package_raw), versions

rawctx-0.1.0/rawctx/commands/install.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+from dataclasses import asdict
+from io import BytesIO
+from pathlib import Path
+import shutil
+import tarfile
+from typing import Any
+
+import click
+
+from rawctx.config import ConfigStore, cache_key, load_package_cache, resolve_registry, resolve_token, save_package_cache, upsert_cache_entry
+from rawctx.registry.client import RegistryClient, RegistryError
+from rawctx.registry.models import choose_latest_version, is_valid_semver, parse_package_ref
+
+
+@click.command()
+@click.argument("package_ref", required=True)
+@click.option("--dest", "dest_path", default=None, help="Install destination root")
+@click.option("--offline", is_flag=True, default=False)
+@click.option("--force", is_flag=True, default=False)
+@click.option("--registry", "registry_override", default=None, help="Registry base URL")
+def install(
+    package_ref: str,
+    dest_path: str | None,
+    offline: bool,
+    force: bool,
+    registry_override: str | None,
+) -> None:
+    try:
+        parsed = parse_package_ref(package_ref)
+    except ValueError as exc:
+        raise click.UsageError(str(exc)) from exc
+
+    store = ConfigStore()
+    config = store.load()
+    cache = load_package_cache(store.paths)
+
+    destination_root = Path(dest_path).expanduser().resolve() if dest_path else None
+    if destination_root is not None:
+        destination_root.mkdir(parents=True, exist_ok=True)
+
+    selected_version: str
+    archive_bytes: bytes | None = None
+    archive_path: Path | None = None
+
+    if offline:
+        selected_version = _select_offline_version(cache, store.paths.archives_dir, parsed.scope, parsed.name, parsed.version)
+        archive_path = store.paths.archive_path(parsed.scope, parsed.name, selected_version)
+        if not archive_path.exists():
+            raise click.ClickException(f"No cached archive found for @{parsed.scope}/{parsed.name}@{selected_version}")
+    else:
+        registry = resolve_registry(cli_registry=registry_override, config=config)
+        token = resolve_token(config)
+        client = RegistryClient(registry=registry, token=token)
+        try:
+            package = client.get_package(scope=parsed.scope, name=parsed.name)
+            versions, _meta = client.list_versions(scope=parsed.scope, name=parsed.name, page=1, size=100)
+            selected_version = parsed.version or _select_latest_version([item.version for item in versions])
+            if not selected_version:
+                raise click.ClickException(f"No installable version found for @{parsed.scope}/{parsed.name}")
+
+            download = client.request_download(scope=parsed.scope, name=parsed.name, version=selected_version)
+            download_url = str(download.get("download_url") or "")
+            if not download_url:
+                raise click.ClickException("Registry did not return download_url")
+
+            archive_bytes = client.download_bytes(download_url=download_url)
+            archive_path = store.paths.archive_path(parsed.scope, parsed.name, selected_version)
+            archive_path.parent.mkdir(parents=True, exist_ok=True)
+            archive_path.write_bytes(archive_bytes)
+
+            upsert_cache_entry(
+                cache,
+                scope=parsed.scope,
+                name=parsed.name,
+                package=asdict(package),
+                versions=[asdict(item) for item in versions],
+            )
+            save_package_cache(store.paths, cache)
+        except RegistryError as exc:
+            raise click.ClickException(str(exc)) from exc
+        finally:
+            client.close()
+
+    if archive_path is None:
+        raise click.ClickException("archive path resolution failed")
+
+    install_target = store.paths.install_path(parsed.scope, parsed.name, selected_version, destination=destination_root)
+    if install_target.exists():
+        if not force:
+            raise click.ClickException(f"Install target already exists: {install_target}. Use --force to overwrite.")
+        shutil.rmtree(install_target)
+
+    install_target.mkdir(parents=True, exist_ok=True)
+    _extract_archive(
+        archive_bytes=archive_bytes if archive_bytes is not None else archive_path.read_bytes(),
+        target_dir=install_target,
+    )
+
+    click.echo(f"Installed @{parsed.scope}/{parsed.name}@{selected_version} -> {install_target}")
+
+
+def _select_offline_version(
+    cache: dict[str, dict[str, Any]],
+    archives_root: Path,
+    scope: str,
+    name: str,
+    preferred_version: str | None,
+) -> str:
+    if preferred_version:
+        return preferred_version
+
+    entry = cache.get(cache_key(scope, name), {})
+    candidates: list[str] = []
+    versions = entry.get("versions")
+    if isinstance(versions, list):
+        for item in versions:
+            if isinstance(item, dict):
+                candidate = item.get("version")
+                if isinstance(candidate, str) and is_valid_semver(candidate):
+                    candidates.append(candidate)
+
+    archive_dir = archives_root / f"@{scope}" / name
+    if archive_dir.exists():
+        for file_path in archive_dir.glob("*.rawctx.tar.gz"):
+            version = file_path.name.removesuffix(".rawctx.tar.gz")
+            if is_valid_semver(version):
+                candidates.append(version)
+
+    selected = _select_latest_version(candidates)
+    if not selected:
+        raise click.ClickException(f"No cached versions found for @{scope}/{name}")
+    return selected
+
+
+def _select_latest_version(versions: list[str]) -> str | None:
+    return choose_latest_version(versions)
+
+
+def _extract_archive(*, archive_bytes: bytes, target_dir: Path) -> None:
+    try:
+        with tarfile.open(fileobj=BytesIO(archive_bytes), mode="r:gz") as tar:
+            for member in tar.getmembers():
+                if not member.name.startswith("package/"):
+                    continue
+                relative = Path(member.name).relative_to("package")
+                if not relative.parts:
+                    continue
+
+                destination = (target_dir / relative).resolve()
+                if target_dir not in destination.parents and destination != target_dir:
+                    raise click.ClickException(f"Unsafe archive entry: {member.name}")
+
+                if member.isdir():
+                    destination.mkdir(parents=True, exist_ok=True)
+                    continue
+
+                destination.parent.mkdir(parents=True, exist_ok=True)
+                extracted = tar.extractfile(member)
+                if extracted is None:
+                    continue
+                destination.write_bytes(extracted.read())
+    except tarfile.TarError as exc:
+        raise click.ClickException(f"Invalid package archive: {exc}") from exc

rawctx-0.1.0/rawctx/commands/login.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+import click
+
+from rawctx.config import ConfigStore, resolve_registry, resolve_token
+from rawctx.registry.auth import (
+    login_with_id_token,
+    logout_auth,
+    start_oauth_login,
+    wait_for_oauth_id_token,
+)
+from rawctx.registry.client import RegistryClient, RegistryError
+
+
+@click.command()
+@click.option("--registry", "registry_override", default=None, help="Registry base URL")
+@click.option("--id-token", default=None, help="JWT id_token from OAuth callback")
+@click.option("--token-name", default="rawctx-cli", show_default=True, help="Name for the generated API token")
+@click.option("--expires-in-days", type=int, default=None, help="Token expiration in days")
+@click.option("--no-browser", is_flag=True, default=False, help="Do not open browser automatically")
+def login(
+    registry_override: str | None,
+    id_token: str | None,
+    token_name: str,
+    expires_in_days: int | None,
+    no_browser: bool,
+) -> None:
+    store = ConfigStore()
+    config = store.load()
+    registry = resolve_registry(cli_registry=registry_override, config=config)
+    config.registry = registry
+
+    client = RegistryClient(registry=registry)
+    try:
+        login_info = start_oauth_login(client=client, open_browser=not no_browser)
+    except RegistryError as exc:
+        client.close()
+        raise click.ClickException(str(exc)) from exc
+
+    click.echo(f"Open this URL and sign in with GitHub:\n{login_info.authorize_url}")
+
+    provided_token = id_token.strip() if id_token else ""
+    if not provided_token:
+        if login_info.session_id:
+            click.echo("Waiting for OAuth login to complete in browser...")
+            try:
+                provided_token = wait_for_oauth_id_token(
+                    client=client,
+                    session_id=login_info.session_id,
+                    poll_interval_seconds=login_info.poll_interval_seconds,
+                )
+            except RegistryError as exc:
+                raise click.ClickException(str(exc)) from exc
+        else:
+            click.echo("Automatic token capture is unavailable on this registry.")
+            click.echo("After login, copy the id_token and paste it below.")
+            provided_token = click.prompt("id_token", type=str).strip()
+
+    if not provided_token:
+        client.close()
+        raise click.ClickException("id_token is required")
+
+    try:
+        token_info = login_with_id_token(
+            client=client,
+            store=store,
+            config=config,
+            id_token=provided_token,
+            token_name=token_name,
+            expires_in_days=expires_in_days,
+        )
+    except RegistryError as exc:
+        raise click.ClickException(str(exc)) from exc
+    finally:
+        client.close()
+
+    click.echo(f"Login succeeded. API token saved to {store.paths.config_path}")
+    click.echo(f"Token id: {token_info.id}")
+
+
+@click.command()
+@click.option("--local-only", is_flag=True, default=False, help="Delete local token only")
+def logout(local_only: bool) -> None:
+    store = ConfigStore()
+    config = store.load()
+
+    if not config.auth.token:
+        click.echo("No local auth token found.")
+        return
+
+    registry = resolve_registry(cli_registry=None, config=config)
+    token = resolve_token(config)
+
+    client: RegistryClient | None = None
+    if not local_only and token:
+        client = RegistryClient(registry=registry, token=token)
+
+    try:
+        had_token, revoked = logout_auth(
+            client=client,
+            store=store,
+            config=config,
+            local_only=local_only,
+        )
+    except RegistryError as exc:
+        raise click.ClickException(str(exc)) from exc
+    finally:
+        if client is not None:
+            client.close()
+
+    if not had_token:
+        click.echo("No local auth token found.")
+        return
+
+    if local_only:
+        click.echo("Logged out locally.")
+    elif revoked:
+        click.echo("Token revoked on server and removed locally.")
+    else:
+        click.echo("Local token removed. Server token could not be revoked.")

rawctx-0.1.0/rawctx/commands/pack.py

@@ -0,0 +1,26 @@
+from pathlib import Path
+
+import click
+
+from rawctx.commands.validate import validate_target
+from rawctx.packaging.builder import build_package_archive
+from rawctx.packaging.manifest import ValidationError
+
+
+@click.command()
+@click.argument("target_dir", required=False, default=".")
+@click.option("--output-dir", default="dist", show_default=True)
+def pack(target_dir: str, output_dir: str) -> None:
+    target_path = Path(target_dir).expanduser().resolve()
+    if not target_path.is_dir():
+        raise click.UsageError("pack target must be a directory")
+
+    try:
+        validation_result = validate_target(target_path, "auto")
+        if validation_result.manifest is None:
+            raise click.ClickException("manifest validation did not produce a manifest")
+        build = build_package_archive(target_path, Path(output_dir), manifest=validation_result.manifest)
+    except ValidationError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    click.echo(f"package created: {build.archive_path}")