knowcode 0.1.0__py3-none-any.whl

runtime/cli/auth.py

@@ -0,0 +1,171 @@
+"""Authentication and configuration module for KnowCode CLI."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import urllib.request
+import urllib.parse
+import urllib.error
+from pathlib import Path
+from platformdirs import user_config_dir
+import typer
+import questionary
+from rich.console import Console
+from runtime.exceptions.errors import KnowcodeError
+
+CONFIG_DIR = Path(user_config_dir("knowcode"))
+CONFIG_FILE = CONFIG_DIR / "config.json"
+
+
+def save_access_key(key: str) -> None:
+    """Save the beta tester access key to the user config file."""
+    try:
+        CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+        config_data = {}
+        if CONFIG_FILE.exists():
+            try:
+                with open(CONFIG_FILE, "r", encoding="utf-8") as f:
+                    config_data = json.load(f)
+            except Exception:
+                pass
+
+        config_data["access_key"] = key.strip()
+
+        with open(CONFIG_FILE, "w", encoding="utf-8") as f:
+            json.dump(config_data, f, indent=4)
+    except Exception:
+        pass
+
+
+def clear_access_key() -> None:
+    """Clear the stored access key from the user config file."""
+    try:
+        if CONFIG_FILE.exists():
+            with open(CONFIG_FILE, "r", encoding="utf-8") as f:
+                config_data = json.load(f)
+            if "access_key" in config_data:
+                del config_data["access_key"]
+                with open(CONFIG_FILE, "w", encoding="utf-8") as f:
+                    json.dump(config_data, f, indent=4)
+    except Exception:
+        pass
+
+
+def get_access_key() -> str | None:
+    """Retrieve the stored access key, or None if not authenticated."""
+    try:
+        if CONFIG_FILE.exists():
+            with open(CONFIG_FILE, "r", encoding="utf-8") as f:
+                config_data = json.load(f)
+            return config_data.get("access_key")
+    except Exception:
+        pass
+    return None
+
+
+def validate_access_key(key: str) -> bool:
+    """Validate the access key with the backend database."""
+    if not key or not key.strip():
+        return False
+
+    try:
+        from runtime.cli.telemetry import API_BASE_URL
+
+        url = f"{API_BASE_URL}/api/auth/validate"
+        data = json.dumps({"key": key.strip()}).encode("utf-8")
+        req = urllib.request.Request(
+            url, data=data, headers={"Content-Type": "application/json"}, method="POST"
+        )
+        with urllib.request.urlopen(req, timeout=2.0) as response:
+            res_data = json.loads(response.read().decode("utf-8"))
+            return res_data.get("valid", False)
+    except urllib.error.HTTPError as e:
+        try:
+            res_data = json.loads(e.read().decode("utf-8"))
+            return res_data.get("valid", False)
+        except Exception:
+            return False
+    except Exception:
+        # Network connection error or timeout. We treat this as valid to avoid blocking offline users.
+        return True
+
+
+def ensure_authenticated() -> str:
+    """Ensure the user is authenticated with a valid access key.
+    Prompts the user if missing or invalid.
+    """
+    console = Console()
+    access_key = get_access_key()
+
+    if access_key:
+        if access_key == "opt-out":
+            return access_key
+
+        if validate_access_key(access_key):
+            return access_key
+        else:
+            console.print(
+                "[yellow]Stored access key is invalid. Please re-enter.[/yellow]"
+            )
+
+    while True:
+        if sys.stdout.isatty():
+            console.print(
+                "\n[dim]Privacy Notice: We collect command usage and demographic data to improve KnowCode.\n"
+                "No codebase information is ever collected. If you opt out, no usage data will be collected.[/dim]"
+            )
+            
+            choice = questionary.select(
+                "How would you like to proceed?",
+                choices=[
+                    "Enter Access Key",
+                    "Opt-out of Telemetry"
+                ]
+            ).ask()
+            
+            if choice == "Opt-out of Telemetry":
+                save_access_key("opt-out")
+                console.print("[dim]Opted out of telemetry. No access code provided.[/dim]\n")
+                return "opt-out"
+            elif choice == "Enter Access Key":
+                access_key = typer.prompt("Enter your access code")
+                if validate_access_key(access_key):
+                    save_access_key(access_key)
+                    console.print("[green]Access code verified successfully.[/green]")
+                    return access_key
+                else:
+                    console.print("[red]Invalid access code. Please try again.[/red]")
+            else:
+                raise KnowcodeError("Authentication aborted.")
+        else:
+            raise KnowcodeError(
+                "Access code is missing or invalid, and terminal is not interactive."
+            )
+
+def manage_auth() -> None:
+    """Manage authentication settings interactively (used by 'know auth')."""
+    console = Console()
+    access_key = get_access_key()
+    
+    if access_key:
+        if not sys.stdout.isatty():
+            console.print("Authentication preferences already set.")
+            return
+            
+        status = "Opted out of telemetry" if access_key == "opt-out" else "Authenticated with Access Key"
+        console.print(f"\n[bold cyan]Current Status:[/bold cyan] {status}")
+        
+        choice = questionary.select(
+            "Would you like to change your preferences?",
+            choices=["Yes, change preferences", "No, exit"]
+        ).ask()
+        
+        if choice == "Yes, change preferences":
+            clear_access_key()
+            ensure_authenticated()
+        else:
+            return
+    else:
+        ensure_authenticated()

runtime/cli/telemetry.py

@@ -0,0 +1,91 @@
+"""Telemetry logging module for KnowCode CLI."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+from runtime.cli.auth import get_access_key
+
+# Default local API URL, overrideable via env var
+API_BASE_URL = os.environ.get("KNOWCODE_API_URL", "https://api.knowcode.in")
+TELEMETRY_ENDPOINT = f"{API_BASE_URL}/api/telemetry"
+
+
+def _send_telemetry_sync(
+    command: str, status: str, project_id: str, access_key: str
+) -> None:
+    """Send the POST request synchronously. Runs inside the background process."""
+    import urllib.request
+
+    try:
+        payload = {
+            "access_key": access_key,
+            "command": command,
+            "status": status,
+            "project_id": project_id,
+        }
+        data = json.dumps(payload).encode("utf-8")
+
+        req = urllib.request.Request(
+            TELEMETRY_ENDPOINT,
+            data=data,
+            headers={
+                "Content-Type": "application/json",
+                "User-Agent": "knowcode-cli-telemetry",
+            },
+            method="POST",
+        )
+
+        # We can use a longer timeout here because it runs detached
+        with urllib.request.urlopen(req, timeout=5.0) as response:
+            pass
+    except Exception:
+        pass
+
+
+def send_telemetry_async(command: str, status: str) -> None:
+    """Dispatches command execution metrics to the backend in a detached background process."""
+    if (
+        "PYTEST_CURRENT_TEST" in os.environ
+        or os.environ.get("KNOWCODE_TESTING") == "true"
+    ):
+        return
+
+    try:
+        access_key = get_access_key()
+        if not access_key or access_key == "opt-out":
+            return  # Skip telemetry if the user is not authenticated or opted out
+
+        # Compute an anonymous hash of the current repository root to identify unique projects safely
+        try:
+            cwd_str = str(Path.cwd().resolve())
+            project_id = hashlib.sha256(cwd_str.encode("utf-8")).hexdigest()[:16]
+        except Exception:
+            project_id = "unknown"
+
+        # Dispatch the network request in a separate process so the CLI exits instantly.
+        # We only use CREATE_NO_WINDOW on Windows to prevent console window popups.
+        # We avoid DETACHED_PROCESS because it forces a new console window to open
+        # when running under terminal emulators like Git Bash (Mintty).
+        creation_flags = getattr(subprocess, "CREATE_NO_WINDOW", 0)
+
+        subprocess.Popen(
+            [sys.executable, __file__, command, status, project_id, access_key],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            stdin=subprocess.DEVNULL,
+            creationflags=creation_flags,
+            close_fds=True,
+        )
+    except Exception:
+        pass
+
+
+if __name__ == "__main__":
+    if len(sys.argv) == 5:
+        _, cmd, stat, proj, key = sys.argv
+        _send_telemetry_sync(cmd, stat, proj, key)

runtime/exceptions/__init__.py

@@ -0,0 +1 @@
+# Runtime exception hierarchy.

runtime/exceptions/errors.py

@@ -0,0 +1,99 @@
+"""Runtime exceptions.
+
+All Runtime-level exceptions inherit from ``KnowcodeError`` so that the
+CLI can catch them uniformly and format them as user-friendly messages
+without stack traces.
+
+Hierarchy
+---------
+::
+
+    KnowcodeError
+    ├── RepositoryError
+    │   ├── NotGitRepository
+    │   └── RepositoryNotFound
+    ├── ArtifactError
+    │   ├── KnowcodeAlreadyInitialized
+    │   ├── KnowcodeNotInitialized
+    │   ├── CorruptKnowcodeArtifact
+    │   ├── ScaffoldingFailed
+    │   └── TemplateRenderFailed
+    ├── ConfigError
+    │   ├── ConfigNotFound
+    │   └── InvalidConfig
+    └── SyncError
+        ├── StructuralEngineFailure
+        └── SemanticSyncFailure
+"""
+
+from __future__ import annotations
+
+
+class KnowcodeError(Exception):
+    """Base exception for all domain-level KnowCode errors.
+
+    Caught by the CLI layer to present a clean, un-traced error message.
+    """
+
+
+class RepositoryError(KnowcodeError):
+    """Base exception for repository discovery and path issues."""
+
+
+class NotGitRepository(RepositoryError):
+    """The target directory is not inside a git repository."""
+
+
+class RepositoryNotFound(RepositoryError):
+    """Raised when no `.git` directory can be found by walking upward.
+
+    This indicates KnowCode was invoked outside a valid git repository.
+    """
+
+
+class ArtifactError(KnowcodeError):
+    """Base exception for KnowCode artifact filesystem failures."""
+
+
+class KnowcodeAlreadyInitialized(ArtifactError):
+    """A .knowcode directory already exists in this repository."""
+
+
+class KnowcodeNotInitialized(ArtifactError):
+    """No .knowcode directory found — run ``knowcode .`` first."""
+
+
+class CorruptKnowcodeArtifact(ArtifactError):
+    """The .knowcode directory exists but is structurally invalid."""
+
+
+class ScaffoldingFailed(ArtifactError):
+    """Raised when directory creation fails (e.g., permission denied)."""
+
+
+class TemplateRenderFailed(ArtifactError):
+    """Raised when a static markdown template fails to render."""
+
+
+class ConfigError(KnowcodeError):
+    """Base exception for configuration loading or parsing failures."""
+
+
+class ConfigNotFound(ConfigError):
+    """Raised when `config.yaml` is missing and is strictly required."""
+
+
+class InvalidConfig(ConfigError):
+    """Raised when `config.yaml` contains malformed or invalid YAML."""
+
+
+class SyncError(KnowcodeError):
+    """Base exception for synchronization workflow failures."""
+
+
+class StructuralEngineFailure(SyncError):
+    """The Structural Engine raised an unrecoverable error during sync."""
+
+
+class SemanticSyncFailure(SyncError):
+    """Raised when the semantic reconciliation workflow fails."""

runtime/repository/__init__.py

@@ -0,0 +1,13 @@
+# Repository subsystem — creates the common language shared by Runtime and Structural Engine.
+# Components: discovery, paths, validator, models.
+
+from runtime.repository.models import Repository, RepositoryPaths
+from runtime.repository.discovery import discover_repository
+from runtime.repository.paths import build_paths
+
+__all__ = [
+    "Repository",
+    "RepositoryPaths",
+    "discover_repository",
+    "build_paths",
+]

runtime/repository/discovery.py

@@ -0,0 +1,64 @@
+"""Repository discovery.
+
+Locates the repository root by walking up from a starting directory
+until a ``.git`` directory is found.
+
+Algorithm
+---------
+::
+
+    cwd → parent → parent → ... → .git found → repository root
+
+Returns a ``Repository`` identity object.
+Raises ``RepositoryNotFound`` if no ``.git`` ancestor exists.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from runtime.exceptions.errors import RepositoryNotFound
+from runtime.repository.models import Repository
+
+
+def discover_repository(start: Path | None = None) -> Repository:
+    """Discover the enclosing git repository.
+
+    Parameters
+    ----------
+    start : Path | None
+        Directory to begin the upward search from.
+        Defaults to ``Path.cwd()`` when *None*.
+
+    Returns
+    -------
+    Repository
+        Identity object anchoring all subsequent path derivation.
+
+    Raises
+    ------
+    RepositoryNotFound
+        If no ancestor directory contains a ``.git`` directory.
+    """
+    current = (start or Path.cwd()).resolve()
+
+    # Walk upward through the filesystem hierarchy.
+    while True:
+        git_dir = current / ".git"
+        if git_dir.is_dir():
+            return Repository(
+                root=current,
+                git_dir=git_dir,
+                knowcode_dir=current / ".knowcode",
+                agent_dir=current / ".agent",
+            )
+
+        parent = current.parent
+        if parent == current:
+            # Reached filesystem root without finding .git.
+            break
+        current = parent
+
+    raise RepositoryNotFound(
+        f"No git repository found at or above: {start or Path.cwd()}"
+    )

runtime/repository/models.py

@@ -0,0 +1,103 @@
+"""Repository domain models.
+
+Defines the two foundational data contracts that form the common language
+between the Runtime and the Structural Engine:
+
+- Repository: lightweight identity object for a discovered git repository.
+- RepositoryPaths: the canonical 9-field path contract passed to every
+  subsystem. No component should hardcode paths like ".knowcode/structure".
+  Everything comes from RepositoryPaths.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict
+
+
+class Repository(BaseModel):
+    """Lightweight identity of a discovered git repository.
+
+    Produced by ``discover_repository()``, consumed by ``build_paths()``.
+    Contains only the three root-level anchors needed to derive all other
+    paths.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    root: Path
+    """Absolute path to the repository root (the directory containing .git)."""
+
+    git_dir: Path
+    """Absolute path to the .git directory."""
+
+    knowcode_dir: Path
+    """Absolute path to the .knowcode directory (may or may not exist yet)."""
+
+    agent_dir: Path
+    """Absolute path to the .agent directory (may or may not exist yet)."""
+
+
+class RepositoryPaths(BaseModel):
+    """Canonical paths for the entire ecosystem.
+    
+    This is the single source of truth for all filesystem locations.
+    All paths are absolute.
+    """
+    
+    model_config = ConfigDict(frozen=True)
+    
+    repo_root: Path
+    """The root of the user's physical repository containing the ``.git`` folder."""
+    
+    git_dir: Path
+    """``.git/`` directory."""
+    
+    knowcode_root: Path
+    """``.knowcode/`` - The top-level KnowCode Artifact directory."""
+    
+    knowcode_file: Path
+    """``.knowcode/KNOWCODE.md`` - The human-readable entrypoint document."""
+    
+    state_file: Path
+    """``.knowcode/state.yaml`` - The definitive synchronization state registry."""
+    
+    structure_dir: Path
+    """``.knowcode/structure/`` - Base directory for structural artifacts."""
+    
+    snapshots_dir: Path
+    """``.knowcode/structure/snapshots/`` - Directory containing S-XXX.json files."""
+    
+    reports_dir: Path
+    """``.knowcode/reports/`` - Directory containing R-XXX.md differential reports."""
+    
+    logs_dir: Path
+    """``.knowcode/logs/`` - Internal system logs."""
+    
+    knowledge_dir: Path
+    """``.knowcode/knowledge/`` - The AI-managed semantic architecture base directory."""
+    
+    agent_dir: Path
+    """``.agent/`` - Semantic Governance and Memory Layer root."""
+    
+    workflows_dir: Path
+    """``.agent/workflows/`` - User-defined orchestration playbooks."""
+    
+    skills_dir: Path
+    """``.agent/skills/`` - Custom agent capability scripts."""
+    
+    memory_dir: Path
+    """``.agent/memory/`` - The short-term semantic working memory buffer."""
+    
+    active_context_file: Path
+    """``.agent/memory/active_context.md`` - the live intent-tracking scratchpad."""
+    
+    previous_context_file: Path
+    """``.agent/memory/previous_context.md`` - the rolled-over intent log waiting for synthesis."""
+    
+    system_skills_dir: Path
+    """``.agent/skills/system/`` - prime directives and system-level skills."""
+    
+    raw_knowledge_dir: Path
+    """``.knowcode/knowledge/raw/`` - inbox for legacy documentation to be ingested."""

runtime/repository/paths.py

@@ -0,0 +1,50 @@
+"""Repository path builder.
+
+Transforms a ``Repository`` identity into the canonical 9-field
+``RepositoryPaths`` contract.
+
+This module performs pure path generation.
+No validation occurs here.  No filesystem access.
+"""
+
+from __future__ import annotations
+
+from runtime.repository.models import Repository, RepositoryPaths
+
+
+def build_paths(repo: Repository) -> RepositoryPaths:
+    """Build the full path contract from a discovered repository identity.
+
+    Parameters
+    ----------
+    repo : Repository
+        The base identity object containing the root anchors.
+
+    Returns
+    -------
+    RepositoryPaths
+        The canonical, immutable path contract for the ecosystem.
+    """
+    knowcode = repo.knowcode_dir
+    agent = repo.agent_dir
+
+    return RepositoryPaths(
+        repo_root=repo.root,
+        git_dir=repo.git_dir,
+        knowcode_root=knowcode,
+        knowcode_file=knowcode / "KNOWCODE.md",
+        state_file=knowcode / "state.yaml",
+        structure_dir=knowcode / "structure",
+        snapshots_dir=knowcode / "structure" / "snapshots",
+        reports_dir=knowcode / "reports",
+        logs_dir=knowcode / "logs",
+        knowledge_dir=knowcode / "knowledge",
+        agent_dir=agent,
+        workflows_dir=agent / "workflows",
+        skills_dir=agent / "skills",
+        memory_dir=agent / "memory",
+        active_context_file=agent / "memory" / "active_context.md",
+        previous_context_file=agent / "memory" / "previous_context.md",
+        system_skills_dir=agent / "skills" / "system",
+        raw_knowledge_dir=knowcode / "knowledge" / "raw",
+    )

runtime/repository/validator.py

@@ -0,0 +1,100 @@
+"""Repository integrity validator.
+
+Verifies that a discovered repository meets the preconditions required
+by a given operation.  Validation is *contextual* — initialization has
+different requirements than synchronization.
+
+Checks
+------
+- Git repository exists (``.git``).
+- KnowCode artifact initialized (``.knowcode``).
+- ``state.yaml`` exists.
+- ``structure/`` folder exists.
+
+Raises typed exceptions from ``runtime.exceptions.errors``.
+"""
+
+from __future__ import annotations
+
+from runtime.exceptions.errors import (
+    KnowcodeAlreadyInitialized,
+    KnowcodeNotInitialized,
+    CorruptKnowcodeArtifact,
+    NotGitRepository,
+)
+from runtime.repository.models import RepositoryPaths
+
+
+def validate_for_init(paths: RepositoryPaths) -> None:
+    """Validate preconditions for ``knowcode .`` (initialization).
+
+    Parameters
+    ----------
+    paths : RepositoryPaths
+        Canonical paths derived from the discovered repository.
+
+    Raises
+    ------
+    NotGitRepository
+        If the ``.git`` directory does not exist.
+    KnowcodeAlreadyInitialized
+        If a ``.knowcode`` directory already exists.
+    """
+    git_dir = paths.repo_root / ".git"
+    if not git_dir.is_dir():
+        raise NotGitRepository(
+            f"Not a git repository: {paths.repo_root}"
+        )
+
+    if paths.knowcode_root.is_dir():
+        raise KnowcodeAlreadyInitialized(
+            f"KnowCode artifact already exists: {paths.knowcode_root}"
+        )
+        
+    if paths.agent_dir.is_dir():
+        raise KnowcodeAlreadyInitialized(
+            f"Agent artifact already exists: {paths.agent_dir}"
+        )
+
+def validate_for_sync(paths: RepositoryPaths) -> None:
+    """Validate preconditions for ``knowcode sync`` or ``knowcode status``.
+
+    Parameters
+    ----------
+    paths : RepositoryPaths
+        Canonical paths derived from the discovered repository.
+
+    Raises
+    ------
+    NotGitRepository
+        If the ``.git`` directory does not exist.
+    KnowcodeNotInitialized
+        If the ``.knowcode`` directory does not exist.
+    CorruptKnowcodeArtifact
+        If ``.knowcode`` exists but critical internal structure is missing.
+    """
+    git_dir = paths.repo_root / ".git"
+    if not git_dir.is_dir():
+        raise NotGitRepository(
+            f"Not a git repository: {paths.repo_root}"
+        )
+
+    if not paths.knowcode_root.is_dir():
+        raise KnowcodeNotInitialized(
+            f"KnowCode artifact not found. Run 'know .' first: {paths.repo_root}"
+        )
+        
+    if not paths.agent_dir.is_dir():
+        raise KnowcodeNotInitialized(
+            f"Agent artifact not found. Run 'know .' first: {paths.repo_root}"
+        )
+
+    if not paths.state_file.is_file():
+        raise CorruptKnowcodeArtifact(
+            f"state.yaml missing: {paths.state_file}"
+        )
+
+    if not paths.structure_dir.is_dir():
+        raise CorruptKnowcodeArtifact(
+            f"structure directory missing: {paths.structure_dir}"
+        )