cct-cli 0.7.9.0__py3-none-any.whl

calc_terminal/workspace.py

@@ -0,0 +1,593 @@
+"""
+CCT Project Workspace (spec section 16).
+
+Before this module, generated content scattered across at least two
+independently-hardcoded, inconsistently-named directories:
+  - calc_terminal/scires.py wrote PNG snapshots to  ~/cct_exports
+  - calc_terminal/report.py wrote notebook exports to ~/CCT_exports
+(note the casing difference alone — these were never the same folder,
+even by accident, on a case-sensitive filesystem).
+
+This module gives every generated artifact ONE home:
+  <config.workspace_directory>/<category>/<filename>
+using the workspace_directory that's already been a real, working
+config.py field since the last session (Settings item 8). Nothing
+generated by AI/commands should "disappear into chat history" the way
+the spec puts it — it should land in a place the person can browse.
+
+Categories match the spec's list (section 16): simulations, images,
+graphs, reports, scripts, research, calculations, projects. Not every
+category has a producer wired up yet — see WIRED_INTO below for the
+honest current state.
+"""
+
+import os
+import sys
+import time
+from . import config as cctconfig
+
+CATEGORIES = [
+    "simulations", "images", "graphs", "reports",
+    "scripts", "research", "calculations", "projects",
+]
+
+# Set by ui/app.py._open_folder()/_close_folder() whenever the user opens
+# or closes a project via the Explorer sidebar's "Open Folder". When a
+# project is open, it — not the fixed config.workspace_directory — is
+# what root_dir()/resolve_writable_path() treat as "the workspace", so
+# relative paths the AI creates ("demo.py", "src/main.py", ...) land
+# inside the project the user actually has open in the File Explorer
+# instead of a separate, always-there ~/cct_workspace folder the user
+# never sees on screen. This was the literal bug in the review: AI
+# writes always resolved to a hardcoded directory regardless of which
+# folder was open. `None` (the default, and what a fresh session/the
+# classic non-UI REPL always has) means "no project open" and root_dir()
+# falls back to config.workspace_directory exactly as it always did —
+# no behavior change for anyone who never opens a folder.
+_active_project_root = None
+
+
+def set_active_project(path):
+    """Called by the UI the moment a folder is opened/closed via the
+    Explorer sidebar. `path=None` clears it back to the configured
+    workspace_directory fallback."""
+    global _active_project_root
+    if path is None:
+        _active_project_root = None
+        return
+    _active_project_root = os.path.abspath(os.path.expanduser(str(path)))
+
+
+def active_project():
+    """The currently open IDE project folder, or None if none is open."""
+    return _active_project_root
+
+# What's actually wired into the workspace right now vs. still landing
+# in an ad hoc location. Read by cmd_workspace so the UI can say so
+# honestly instead of implying every category is populated.
+WIRED_INTO = {
+    "simulations": "calc_terminal/scires.py — render_atom(), render_orbital()",
+    "graphs": "calc_terminal/scires.py — render_orbital_grid(), render_bonding()",
+    "reports": "calc_terminal/report.py — export_pdf() / export_markdown() (via default_export_dir)",
+    "images": None,
+    "scripts": None,
+    "research": None,
+    "calculations": None,
+    "projects": None,
+}
+
+
+# ---------------------------------------------------------------- STRICT FIX v0.7.9.6 --
+# File-creation permission model (spec §14): EXPLICIT_ONLY.
+# A user-provided path means "work here", not "populate this location".
+# category_dir() no longer creates directories as a side effect of being
+# read; only an explicit write (ensure=True / path_for / ensure_category_dir)
+# may create a directory. summary()/list_category() therefore never
+# scaffold unwanted folders inside an existing project.
+FILE_CREATION_POLICY = "EXPLICIT_ONLY"
+
+
+def root_dir(*, ensure=False):
+    """The active workspace root: the currently open IDE project folder
+    if one is open (see set_active_project()), otherwise the configured
+    workspace_directory fallback.
+
+    STRICT FIX v0.7.9.6: directory creation is now explicit-only. Callers
+    that intend to WRITE must pass ensure=True; read-only callers
+    (summary, list_category, path resolution for reads) must leave
+    ensure=False (the default) so merely inspecting or opening an
+    existing folder never creates files or subdirectories inside it.
+    When ensure=False the directory is returned verbatim even if it does
+    not yet exist — callers that need to list it handle the missing-dir
+    case themselves (returning an empty listing).
+
+    v0.7.9.0 fix preserved: creation is best-effort."""
+    if _active_project_root is not None:
+        d = _active_project_root
+    else:
+        cfg = cctconfig.get_config()
+        d = os.path.expanduser(cfg.workspace_directory)
+    if ensure:
+        try:
+            os.makedirs(d, exist_ok=True)
+        except OSError:
+            pass  # unwritable/protected root — callers fail honestly per-op
+    return d
+
+
+def category_dir(category, *, ensure=False):
+    """Return the path for a workspace category.
+
+    STRICT FIX v0.7.9.6: by default does NOT create the directory. Pass
+    ensure=True only when the caller is about to write a file there
+    (path_for, default_export_dir, scires._export_dir). Read paths
+    (list_category, summary) use ensure=False so dashboards and
+    inspections never scaffold the 8 default folders inside a user's
+    existing project."""
+    if category not in CATEGORIES:
+        raise ValueError(f"Unknown workspace category: {category!r}. Valid: {CATEGORIES}")
+    d = os.path.join(root_dir(ensure=ensure), category)
+    if ensure:
+        try:
+            os.makedirs(d, exist_ok=True)
+        except OSError:
+            pass  # see root_dir(): creation is best-effort, never fatal
+    return d
+
+
+def ensure_category_dir(category):
+    """Explicit creation helper — only call when the user explicitly
+    requested a file in this category or the requested operation
+    necessarily requires it. Returns the ensured directory."""
+    return category_dir(category, ensure=True)
+
+
+def path_for(category, filename):
+    """Resolve (and ensure the directory exists for) a file that's
+    about to be written into the workspace. Callers still do their own
+    actual file writing — this just gives them the one correct path.
+
+    This is an EXPLICIT creation path — the caller's intent is to write,
+    so the category directory is ensured."""
+    return os.path.join(category_dir(category, ensure=True), filename)
+
+
+# Directories a write/delete/rename should never resolve into, even if
+# the model asks nicely with a plausible-sounding reason — a narrow,
+# named blocklist, not a claim of a full sandbox (spec section 20 asks
+# for "prevent path traversal", not "prevent all filesystem access").
+_BLOCKED_ROOTS = (
+    "/etc", "/sys", "/proc", "/boot", "/dev", "/System", "/Library",
+    "C:\\Windows", "C:\\Program Files", "C:\\Program Files (x86)",
+)
+
+
+def find_matching_workspace_path(query_path: str, base_dir: str = None) -> str:
+    """Automate file path resolution: find real matching file in workspace.
+
+    If query_path is 'index.html' or 'calculator/index.html', but the actual file
+    is at '<base>/projects/calculator/index.html', finds and returns the real path.
+    """
+    if not query_path or not str(query_path).strip():
+        return ""
+    base = base_dir or root_dir()
+    if not os.path.isdir(base):
+        return ""
+
+    raw_clean = str(query_path).strip().replace("\\", "/")
+    # If starts with fake roots like /workspace/ or /project/, strip them
+    for prefix in ("/workspace/", "workspace/", "/project/", "project/"):
+        if raw_clean.lower().startswith(prefix):
+            raw_clean = raw_clean[len(prefix):]
+            break
+
+    clean_query = os.path.normpath(raw_clean.lstrip("/\\"))
+    # 1. Direct path check
+    direct = os.path.normpath(os.path.join(base, clean_query))
+    if os.path.exists(direct):
+        return direct
+
+    # 2. Search workspace
+    target_name = os.path.basename(clean_query).lower()
+    target_subpath = clean_query.replace("\\", "/").lower()
+
+    exact_name_matches = []
+    suffix_matches = []
+    fuzzy_matches = []
+
+    skip_dirs = {".git", "node_modules", "__pycache__", ".venv", "venv", ".pytest_cache", "dist", "build"}
+    for root, dirs, files in os.walk(base):
+        dirs[:] = [d for d in dirs if d not in skip_dirs and not d.startswith(".")]
+        # Also check directories if query might be a folder
+        for d in dirs:
+            full_d = os.path.join(root, d)
+            rel_d = os.path.relpath(full_d, base).replace("\\", "/").lower()
+            if rel_d == target_subpath or rel_d.endswith("/" + target_subpath) or d.lower() == target_name:
+                fuzzy_matches.append(full_d)
+
+        for f in files:
+            full_f = os.path.join(root, f)
+            rel_f = os.path.relpath(full_f, base).replace("\\", "/").lower()
+            if rel_f.endswith(target_subpath):
+                suffix_matches.append(full_f)
+            elif f.lower() == target_name:
+                exact_name_matches.append(full_f)
+            elif target_name in f.lower() or target_subpath in rel_f:
+                fuzzy_matches.append(full_f)
+
+    if suffix_matches:
+        return suffix_matches[0]
+    if exact_name_matches:
+        return exact_name_matches[0]
+    if fuzzy_matches:
+        return fuzzy_matches[0]
+    return ""
+
+
+def resolve_writable_path(path):
+    """Turn a model- or user-supplied path into a safe absolute path,
+    for use by anything that creates/writes/deletes/renames a real
+    file (calc_terminal/agent.py's write_file/delete_file/rename_file/
+    create_folder tools).
+
+    - A relative path resolves against the workspace root (root_dir()),
+      not the process's current working directory, so "src/main.py"
+      means the same real location regardless of how CCT was launched.
+    - Automated path resolution: if the path is relative or points to
+      a subfolder file like "index.html" or "calculator/index.html",
+      it scans the active workspace to find the real matching path.
+    - An absolute path is honored as given (normalized) — same as any
+      other AI-IDE agent operating with the OS user's own permissions.
+    - Raises ValueError (never silently substitutes a "safe" path) if
+      the resolved path lands in a clearly-dangerous system root, or
+      outside of both the workspace root and the user's home directory
+      — the two places CCT has any real business writing.
+    """
+    if not path or not str(path).strip():
+        raise ValueError("No path given.")
+    expanded = os.path.expanduser(str(path).strip())
+    base = root_dir()
+
+    # If exact absolute path exists, use it
+    if os.path.isabs(expanded) and os.path.exists(expanded):
+        resolved = os.path.normpath(expanded)
+    else:
+        # Automated path resolution: match file in workspace
+        auto_found = find_matching_workspace_path(expanded, base)
+        if auto_found:
+            resolved = auto_found
+        elif os.path.isabs(expanded):
+            resolved = os.path.normpath(expanded)
+        else:
+            resolved = os.path.normpath(os.path.join(base, expanded))
+
+    for blocked in _BLOCKED_ROOTS:
+        blocked_norm = _norm_ci(blocked)
+        if resolved_ci := _norm_ci(resolved):
+            if resolved_ci == blocked_norm or resolved_ci.startswith(blocked_norm + os.sep):
+                raise ValueError(f"Refusing to touch a protected system path: {resolved}")
+
+    home = os.path.expanduser("~")
+    in_workspace = resolved == base or resolved.startswith(base + os.sep)
+    in_home = resolved == home or resolved.startswith(home + os.sep)
+    if not (in_workspace or in_home):
+        raise ValueError(
+            f"'{resolved}' is outside both the workspace ({base}) and your home "
+            "directory — refusing to write there. Use a path under one of those."
+        )
+    return resolved
+
+
+def _norm_ci(path):
+    """Normalized + case-insensitive form of a path for protected-root
+    comparison. Windows filesystems are case-insensitive ('C:/WINDOWS'
+    and 'C:/Windows' are the same directory), so every blocklist
+    comparison must go through this — a plain startswith() silently
+    missed C:/WINDOWS/System32."""
+    return os.path.normcase(os.path.normpath(os.path.abspath(
+        os.path.expanduser(str(path)))))
+
+
+def path_is_protected(path):
+    """True when `path` sits inside (or equals) one of the protected
+    system roots — used by projects.forget_protected() to purge bad
+    recent-workspace entries and by detect_workspace() to refuse
+    adopting e.g. C:\\WINDOWS\\System32 as a workspace. Never raises.
+    Comparison is case-insensitive via _norm_ci()."""
+    try:
+        norm = _norm_ci(path)
+    except Exception:
+        return False
+    for blocked in _BLOCKED_ROOTS:
+        b = _norm_ci(blocked)
+        if norm == b or norm.startswith(b + os.sep):
+            return True
+    return False
+
+
+def resolve_readable_path(path):
+    """Resolve a path for READ-ONLY tool access (read_file, archive_list,
+    archive_validate, search). Read-only access is safe anywhere except
+    the named protected system roots, so this accepts absolute paths
+    anywhere on disk — an attached file on another drive can be listed
+    without first being copied into the workspace. Raises ValueError for
+    blocked roots and empty paths only."""
+    if not path or not str(path).strip():
+        raise ValueError("No path given.")
+    expanded = os.path.expanduser(str(path).strip())
+    base = root_dir()
+
+    if os.path.isabs(expanded) and os.path.exists(expanded):
+        resolved = os.path.normpath(expanded)
+    else:
+        auto_found = find_matching_workspace_path(expanded, base)
+        if auto_found:
+            resolved = auto_found
+        elif os.path.isabs(expanded):
+            resolved = os.path.normpath(expanded)
+        else:
+            resolved = os.path.normpath(os.path.join(base, expanded))
+
+    for blocked in _BLOCKED_ROOTS:
+        blocked_norm = _norm_ci(blocked)
+        resolved_ci = _norm_ci(resolved)
+        if resolved_ci == blocked_norm or resolved_ci.startswith(blocked_norm + os.sep):
+            raise ValueError(f"Refusing to read a protected system path: {resolved}")
+    return resolved
+
+
+def resolve_tool_path(path, for_write=False):
+    """Resolve a model-supplied path for a tool call: strict
+    resolve_writable_path rules for mutations, relaxed read-only rules
+    (any non-blocked location) for reads."""
+    if for_write:
+        return resolve_writable_path(path)
+    try:
+        return resolve_writable_path(path)
+    except ValueError:
+        return resolve_readable_path(path)
+
+
+def list_category(category):
+    d = category_dir(category)
+    out = []
+    try:
+        names = sorted(os.listdir(d))
+    except OSError:
+        # Unreadable/uncreatable category dir (e.g. CAT launched from a
+        # protected directory) — an empty listing, never a crash.
+        return out
+    for name in names:
+        full = os.path.join(d, name)
+        try:
+            if os.path.isfile(full):
+                st = os.stat(full)
+                out.append({
+                    "name": name,
+                    "path": full,
+                    "size": st.st_size,
+                    "mtime": st.st_mtime,
+                })
+        except OSError:
+            continue
+    return out
+
+
+def list_all():
+    return {cat: list_category(cat) for cat in CATEGORIES}
+
+
+def summary():
+    """One line per non-empty category, newest file first-ish, for a
+    quick /workspace overview without dumping every file.
+
+    v0.7.9.0 fix: per-category failures (PermissionError et al.) are
+    skipped, so the startup dashboard can always compose — launching
+    `cat` from C:\\WINDOWS\\System32 used to crash the whole app here."""
+    lines = []
+    for cat in CATEGORIES:
+        try:
+            files = list_category(cat)
+        except Exception:
+            continue
+        if not files:
+            continue
+        files.sort(key=lambda f: f["mtime"], reverse=True)
+        newest = files[0]
+        age = time.time() - newest["mtime"]
+        when = "just now" if age < 60 else f"{int(age // 60)}m ago" if age < 3600 else f"{int(age // 3600)}h ago"
+        lines.append((cat, len(files), newest["name"], when))
+    return lines
+
+
+# =============================================== v0.7.7 workspace preview ==
+# Automatic workspace detection (spec section 1) + git helpers used by
+# the Project Header (spec section 9). Everything below is additive.
+
+
+def app_directory():
+    """The CCT application's own source directory (the folder that
+    holds main.py + calc_terminal/). Used by detection to avoid
+    declaring CCT itself to be the user's workspace."""
+    try:
+        base = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+        if os.path.exists(os.path.join(base, "main.py")):
+            return os.path.abspath(base)
+    except Exception:
+        pass
+    return os.path.abspath(os.getcwd())
+
+
+def git_root(start=None):
+    """The nearest enclosing git repository root for `start` (or the
+    current working directory), via `git rev-parse --show-toplevel`.
+    Returns None when git isn't installed or `start` isn't in a
+    repository — never raises."""
+    start = os.path.abspath(start or os.getcwd())
+    import subprocess
+    try:
+        out = subprocess.run(
+            ["git", "-C", start, "rev-parse", "--show-toplevel"],
+            capture_output=True, text=True, timeout=15,
+            encoding="utf-8", errors="replace")
+        if out.returncode == 0:
+            root = out.stdout.strip()
+            return os.path.abspath(root) if root else None
+    except Exception:
+        pass
+    return None
+
+
+def git_branch(path):
+    """Current branch of the repo containing `path`, or None."""
+    import subprocess
+    try:
+        out = subprocess.run(
+            ["git", "-C", path, "branch", "--show-current"],
+            capture_output=True, text=True, timeout=15,
+            encoding="utf-8", errors="replace")
+        branch = out.stdout.strip()
+        return branch or None
+    except Exception:
+        return None
+
+
+def git_status_summary(path):
+    """Short `git status --porcelain` summary: (changed, added,
+    deleted) counts, or None when not a repo. Honest — counts real
+    porcelain entries only."""
+    import subprocess
+    try:
+        out = subprocess.run(
+            ["git", "-C", path, "status", "--porcelain"],
+            capture_output=True, text=True, timeout=20,
+            encoding="utf-8", errors="replace")
+        if out.returncode != 0:
+            return None
+        changed = added = deleted = 0
+        for line in out.stdout.splitlines():
+            code = line[:2].strip()
+            if code.startswith("A") or code.startswith("??"):
+                added += 1
+            elif code.startswith("D"):
+                deleted += 1
+            elif code:
+                changed += 1
+        return {"changed": changed, "added": added, "deleted": deleted}
+    except Exception:
+        return None
+
+
+def _vscode_workspace(cwd):
+    """VS Code currently-open workspace (spec section 1, priority 2):
+    a `*.code-workspace` file in the working directory (its "folders"
+    paths are the real workspace folders), else a `.vscode/` marker
+    folder meaning "this directory is the VS Code workspace". Returns
+    the first valid folder path, or None."""
+    try:
+        for name in sorted(os.listdir(cwd)):
+            if name.endswith(".code-workspace"):
+                full = os.path.join(cwd, name)
+                try:
+                    with open(full, "r", encoding="utf-8") as f:
+                        import json
+                        data = json.load(f)
+                    for folder in (data or {}).get("folders", []):
+                        p = folder.get("path", "")
+                        if not p:
+                            continue
+                        p = os.path.abspath(os.path.join(cwd, p))
+                        if os.path.isdir(p):
+                            return p
+                except Exception:
+                    continue
+                return cwd
+        if os.path.isdir(os.path.join(cwd, ".vscode")):
+            return cwd
+    except Exception:
+        pass
+    return None
+
+
+def detect_workspace(cwd=None):
+    """Automatic workspace detection (spec section 1) — returns the
+    first valid workspace path in this priority order, or None:
+
+      1. the current terminal working directory (when it isn't CCT's
+         own app folder — a project-looking cwd is the workspace);
+      2. the VS Code workspace (.code-workspace file / .vscode marker);
+      3. the git repository root;
+      4. the directory CCT was launched from;
+      5. the last opened workspace (projects.last_opened()).
+
+    Pure function: never mutates state, never writes files. Callers
+    decide what to do with the result.
+
+    v0.7.9.0 fix: candidates inside protected system roots
+    (C:\\Windows, C:\\Program Files, ...) are skipped entirely —
+    launching `cat` from PowerShell's default C:\\WINDOWS\\System32 used
+    to adopt System32 as the workspace (and even record it into recent
+    history), which then crashed generated-file creation with
+    PermissionError."""
+    cwd = os.path.abspath(cwd or os.getcwd())
+    app_dir = app_directory()
+    try:
+        def _protected(path):
+            norm = _norm_ci(path)
+            for blocked in _BLOCKED_ROOTS:
+                b = _norm_ci(blocked)
+                if norm == b or norm.startswith(b + os.sep):
+                    return True
+            return False
+
+        candidates = []
+        # 1 — cwd itself, unless it IS the app or a protected system dir.
+        if cwd != app_dir and not _protected(cwd):
+            candidates.append(cwd)
+        # 2 — VS Code workspace.
+        vsc = _vscode_workspace(cwd)
+        if vsc and vsc not in candidates:
+            candidates.append(vsc)
+        # 3 — git root.
+        gr = git_root(cwd)
+        if gr and gr not in candidates:
+            candidates.append(gr)
+        # 4 — launch directory (when it differs from cwd and isn't
+        #    the app folder).
+        try:
+            launch = os.path.abspath(os.path.dirname(sys.argv[0]) or cwd)
+            if launch != cwd and launch != app_dir and launch not in candidates:
+                candidates.append(launch)
+        except Exception:
+            pass
+        # 5 — last opened workspace.
+        try:
+            from . import projects
+            last = projects.last_opened()
+            if last and last not in candidates:
+                candidates.append(last)
+        except Exception:
+            pass
+        for path in candidates:
+            if os.path.isdir(path) and not _protected(path):
+                return os.path.abspath(path)
+    except Exception:
+        pass
+    return None
+
+
+def auto_load_workspace():
+    """Run detection once at startup and, if a workspace was found,
+    load it: record it in recent history and make it the active
+    project root (the same state _open_folder would set). Returns the
+    detected path, or None. Idempotent — safe to call from both UIs."""
+    try:
+        path = detect_workspace()
+        if not path:
+            return None
+        from . import projects
+        projects.record_opened(path)
+        set_active_project(path)
+        return path
+    except Exception:
+        return None