devtime-ei 0.1.0__py3-none-any.whl

devtime/__init__.py

@@ -0,0 +1,9 @@
+"""DevTime - local-first Engineering Intelligence for repository memory."""
+
+__version__ = "0.1.0"
+
+# Version metadata (Builder Edition, Chapter 20).
+EVIDENCE_MODEL = "2026.06.1"
+FIXTURE_SUITE = "2026.06.1"
+RISK_MODEL = "preview-1"
+MCP_SCHEMA = "0.1"

devtime/ai/local.py

@@ -0,0 +1,11 @@
+"""Placeholder for a local model provider (e.g. Ollama) - disabled in V0."""
+
+from __future__ import annotations
+
+from devtime.ai.providers import DisabledProvider
+
+
+class LocalModelProvider(DisabledProvider):
+    """Local provider stub. Stays disabled until a user explicitly configures it."""
+
+    name = "local"

devtime/ai/prompts.py

@@ -0,0 +1,24 @@
+"""Prompt guard for AI narration (Builder Edition, Chapter 15).
+
+The model narrates governed memory; it does not invent rationale or upgrade
+confidence.
+"""
+
+PROMPT_GUARD = """SYSTEM:
+You narrate governed repository memory.
+Use only the claims, evidence, decisions, and uncertainty provided.
+Do not invent rationale.
+Do not upgrade confidence.
+Preserve uncertainty.
+If decision evidence is missing, say it is missing.
+
+INPUT:
+{context_pack_json}
+
+OUTPUT:
+A concise explanation for the developer.
+"""
+
+
+def build_prompt(context_pack_json: str) -> str:
+    return PROMPT_GUARD.format(context_pack_json=context_pack_json)

devtime/ai/providers.py

@@ -0,0 +1,41 @@
+"""Local AI provider layer (Builder Edition, Chapter 15).
+
+AI is optional, explicit, and never the truth layer. V0 ships a disabled provider
+by default and never calls AI automatically.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class AIProvider(Protocol):
+    name: str
+
+    def is_configured(self) -> bool: ...
+
+    def generate(self, prompt: str, *, max_tokens: int) -> str: ...
+
+
+class DisabledProvider:
+    name = "none"
+
+    def is_configured(self) -> bool:
+        return False
+
+    def generate(self, prompt: str, *, max_tokens: int) -> str:
+        raise RuntimeError("AI is disabled. Enable explicitly before generating.")
+
+
+def default_provider() -> AIProvider:
+    return DisabledProvider()
+
+
+def ai_status() -> dict:
+    provider = default_provider()
+    return {
+        "ai": "Disabled" if not provider.is_configured() else "Enabled",
+        "provider": provider.name,
+        "automatic_ai_calls": "Disabled",
+        "data_sent": "Nothing",
+    }

devtime/assets/devtimeignore.starter

@@ -0,0 +1,23 @@
+# Secrets
+.env
+.env.*
+*.pem
+*.key
+*.p12
+*.pfx
+id_rsa
+id_ed25519
+secrets.*
+credentials.*
+service-account*.json
+
+# Generated
+node_modules/
+dist/
+build/
+coverage/
+.next/
+.cache/
+
+# VCS
+.git/

devtime/cli.py

@@ -0,0 +1,374 @@
+"""DevTime CLI (Builder Edition, Chapter 4 + Appendix A).
+
+The CLI is the first product surface. It must make trust visible.
+
+Exit codes (Appendix A):
+  0 success | 1 general error | 2 not initialized | 3 scan failed
+  4 migration failed | 5 privacy boundary violation | 6 fixture assertion failed
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from devtime import __version__, paths
+
+app = typer.Typer(
+    help="DevTime - local-first Engineering Intelligence", no_args_is_help=True
+)
+console = Console()
+
+claim_app = typer.Typer(help="Inspect and govern claims.")
+decision_app = typer.Typer(help="Record human decisions.")
+mcp_app = typer.Typer(help="Local read-only MCP server.")
+app.add_typer(claim_app, name="claim")
+app.add_typer(decision_app, name="decision")
+app.add_typer(mcp_app, name="mcp")
+
+
+# --------------------------------------------------------------------------- #
+# Initialization
+# --------------------------------------------------------------------------- #
+
+@app.command()
+def init() -> None:
+    """Create .devtime, config, and SQLite database."""
+    from devtime.db.migrations import init_repo
+
+    init_repo()
+    console.print("[green]DevTime initialized.[/green] Local memory at .devtime/devtime.sqlite")
+    console.print("AI disabled. Cloud disabled. Telemetry off. MCP read-only.")
+
+
+@app.command()
+def status() -> None:
+    """Show local storage, AI, cloud, telemetry, MCP, and scan status."""
+    from devtime.output.terminal import print_status
+
+    print_status()
+
+
+@app.command()
+def doctor(
+    privacy: bool = typer.Option(False, "--privacy", help="Show privacy and boundary checks."),
+) -> None:
+    """Run environment and repository checks."""
+    from devtime.privacy import privacy_report
+
+    report = privacy_report()
+    console.print("[bold]Privacy check[/bold]\n")
+    console.print("[green]Good:[/green]")
+    for item in report["good"]:
+        console.print(f"  - {item}")
+    if report["warning"]:
+        console.print("[yellow]Warning:[/yellow]")
+        for item in report["warning"]:
+            console.print(f"  - {item}")
+    if report["recommended"]:
+        console.print("[bold]Recommended:[/bold]")
+        for item in report["recommended"]:
+            console.print(f"  {item}")
+
+
+# --------------------------------------------------------------------------- #
+# Scanning
+# --------------------------------------------------------------------------- #
+
+@app.command()
+def scan(
+    refresh: bool = typer.Option(False, "--refresh", help="Recompute concepts, claims, scores."),
+    show_ignored: bool = typer.Option(False, "--show-ignored", help="(reserved)"),
+) -> None:
+    """Scan repository and update local memory."""
+    from devtime.scanner.signals import run_scan
+
+    try:
+        result = run_scan(refresh=refresh, progress=True)
+    except Exception as exc:  # noqa: BLE001
+        console.print(f"[red]Scan failed:[/red] {exc}")
+        raise typer.Exit(code=3)
+    console.print(
+        f"[green]Scan complete.[/green] Scanned {result.file_count} files, "
+        f"{result.signal_count} signals, {result.concept_count} concepts "
+        f"in {result.duration_seconds}s."
+    )
+    console.print(
+        f"Pruned directories: {result.pruned_dirs}   "
+        f"Skipped/ignored files: {result.skipped_files}"
+    )
+    console.print("Supported V0 concept families: 6 (closed ontology).")
+    for w in result.framework_warnings:
+        console.print(f"[yellow]{w}[/yellow]")
+    console.print("Nothing left this machine. Run [bold]dtc concepts[/bold] to inspect.")
+
+
+# --------------------------------------------------------------------------- #
+# Understanding
+# --------------------------------------------------------------------------- #
+
+@app.command()
+def concepts() -> None:
+    """List detected concepts."""
+    from devtime.output.terminal import print_concepts
+
+    print_concepts()
+
+
+@app.command()
+def explain(concept: str) -> None:
+    """Explain a concept from evidence."""
+    from devtime.output.terminal import print_explanation
+
+    print_explanation(concept)
+
+
+@app.command()
+def evidence(concept: str) -> None:
+    """Show evidence for a concept."""
+    from devtime.output.terminal import print_evidence
+
+    print_evidence(concept)
+
+
+@app.command()
+def debt() -> None:
+    """Show top Understanding Debt by concept."""
+    from devtime.output.terminal import print_debt
+
+    print_debt()
+
+
+@app.command()
+def understand() -> None:
+    """Show Understanding Debt across concepts (alias of debt)."""
+    from devtime.output.terminal import print_debt
+
+    print_debt()
+
+
+# --------------------------------------------------------------------------- #
+# Risk
+# --------------------------------------------------------------------------- #
+
+@app.command()
+def risk(
+    diff: bool = typer.Option(False, "--diff", help="Review current diff against memory."),
+    base: str = typer.Option("HEAD", "--base", help="Base ref for the diff."),
+    fmt: str = typer.Option("text", "--format", help="text or markdown."),
+) -> None:
+    """Review local changes against repository memory."""
+    import subprocess
+
+    from devtime.db import connection, repository
+    from devtime.intelligence.risk import (
+        STATE_REVIEW_FAILED,
+        parse_unified_diff,
+        review_diff,
+        review_failed,
+    )
+    from devtime.output.markdown import render_risk_review
+
+    if not paths.is_initialized():
+        console.print("[red]Not initialized.[/red] Run dtc init.")
+        raise typer.Exit(code=2)
+
+    # Git failure must surface as review_failed, never as "no findings".
+    try:
+        # --relative emits paths relative to the current directory, so diff paths
+        # match scan-root-relative evidence even when the scan root is a subdirectory
+        # of the git repository (e.g. running the demo from examples/demo-saas).
+        proc = subprocess.run(
+            ["git", "diff", "--relative", base],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except FileNotFoundError:
+        console.print(render_risk_review(review_failed("git executable not found")), markup=False)
+        raise typer.Exit(code=1)
+
+    if proc.returncode != 0:
+        reason = (proc.stderr or "git diff returned a non-zero exit code").strip()
+        console.print(render_risk_review(review_failed(reason)), markup=False)
+        raise typer.Exit(code=1)
+
+    info = parse_unified_diff(proc.stdout)
+    conn = connection.connect()
+    try:
+        intelligence = repository.load_all_concepts(conn)
+    finally:
+        conn.close()
+
+    review = review_diff(info, intelligence)
+    console.print(render_risk_review(review), markup=False)
+    if review.state == STATE_REVIEW_FAILED:
+        raise typer.Exit(code=1)
+
+
+# --------------------------------------------------------------------------- #
+# AI workflow
+# --------------------------------------------------------------------------- #
+
+@app.command()
+def context(
+    concept: str,
+    mode: str = typer.Option("risk", "--mode", help="overview|risk|implementation|testing|onboarding|security"),
+    copy: bool = typer.Option(False, "--copy", help="(reserved) copy to clipboard"),
+) -> None:
+    """Generate a Context Pack for humans or AI agents."""
+    from devtime.output.terminal import print_context
+
+    print_context(concept, mode)
+
+
+# --------------------------------------------------------------------------- #
+# Memory: claims and decisions
+# --------------------------------------------------------------------------- #
+
+@claim_app.command("show")
+def claim_show(claim_id: str) -> None:
+    """Inspect a claim, evidence, confidence, and uncertainty."""
+    from devtime.db import connection
+
+    conn = connection.connect()
+    try:
+        row = conn.execute("SELECT * FROM claims WHERE id = ?", (claim_id,)).fetchone()
+        if not row:
+            console.print(f"[yellow]No claim[/yellow] {claim_id}")
+            return
+        console.print(dict(row))
+    finally:
+        conn.close()
+
+
+@claim_app.command("challenge")
+def claim_challenge(claim_id: str) -> None:
+    """Mark a claim as challenged."""
+    from devtime.db import connection
+
+    conn = connection.connect()
+    try:
+        cur = conn.execute(
+            "UPDATE claims SET state = 'challenged' WHERE id = ?", (claim_id,)
+        )
+        conn.commit()
+        if cur.rowcount:
+            console.print(f"[green]Claim {claim_id} challenged.[/green]")
+        else:
+            console.print(f"[yellow]No claim[/yellow] {claim_id}")
+    finally:
+        conn.close()
+
+
+@claim_app.command("confirm")
+def claim_confirm(claim_id: str) -> None:
+    """Confirm a claim (human confirmation)."""
+    from devtime.db import connection
+
+    conn = connection.connect()
+    try:
+        cur = conn.execute(
+            "UPDATE claims SET state = 'confirmed', created_by = 'human' WHERE id = ?",
+            (claim_id,),
+        )
+        conn.commit()
+        if cur.rowcount:
+            console.print(f"[green]Claim {claim_id} confirmed.[/green]")
+        else:
+            console.print(f"[yellow]No claim[/yellow] {claim_id}")
+    finally:
+        conn.close()
+
+
+@decision_app.command("add")
+def decision_add(
+    title: str = typer.Option(..., "--title", help="Decision title."),
+    body: str = typer.Option(..., "--body", help="Why this behavior exists or changed."),
+    concept: str = typer.Option(None, "--concept", help="Concept slug to attach to."),
+) -> None:
+    """Record why a behavior exists or changed."""
+    from devtime.db import connection, repository
+
+    conn = connection.connect()
+    try:
+        did = repository.add_decision(conn, title, body, concept)
+        console.print(f"[green]Decision recorded[/green] ({did}).")
+    finally:
+        conn.close()
+
+
+# --------------------------------------------------------------------------- #
+# MCP
+# --------------------------------------------------------------------------- #
+
+@mcp_app.command("start")
+def mcp_start() -> None:
+    """Preview planned read-only MCP tools. Does NOT start a server in V0."""
+    from devtime.mcp.server import describe_server
+
+    console.print(describe_server())
+    # Honest exit: nothing was started, so a command named "start" returns nonzero.
+    raise typer.Exit(code=1)
+
+
+@mcp_app.command("preview")
+def mcp_preview() -> None:
+    """Preview planned read-only MCP tools (transport not implemented in V0)."""
+    from devtime.mcp.server import describe_server
+
+    console.print(describe_server())
+
+
+@mcp_app.command("status")
+def mcp_status() -> None:
+    """Inspect MCP permissions and clients."""
+    from devtime.mcp.server import describe_permissions
+
+    console.print(describe_permissions())
+
+
+# --------------------------------------------------------------------------- #
+# Export and reset
+# --------------------------------------------------------------------------- #
+
+@app.command()
+def export(fmt: str = typer.Option("json", "--format", help="json or markdown.")) -> None:
+    """Export reviewable memory."""
+    from devtime.output.json_export import export_memory
+
+    if not paths.is_initialized():
+        console.print("[red]Not initialized.[/red]")
+        raise typer.Exit(code=2)
+    console.print(export_memory(fmt))
+
+
+@app.command()
+def reset(
+    yes: bool = typer.Option(False, "--yes", help="Skip confirmation."),
+) -> None:
+    """Delete local memory after confirmation."""
+    import shutil
+
+    if not paths.is_initialized():
+        console.print("Nothing to reset.")
+        return
+    if not yes:
+        confirm = typer.confirm("Delete all local DevTime memory? Source code is untouched.")
+        if not confirm:
+            console.print("Aborted.")
+            return
+    shutil.rmtree(paths.devtime_dir())
+    console.print("[green]Local memory deleted.[/green] Source code untouched.")
+
+
+@app.command()
+def version() -> None:
+    """Show DevTime version."""
+    console.print(f"DevTime CLI: {__version__}")
+
+
+if __name__ == "__main__":
+    app()

devtime/config.py

@@ -0,0 +1,67 @@
+"""Configuration loading and defaults (Builder Edition, Chapter 5)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from devtime import paths
+
+DEFAULT_CONFIG: dict[str, Any] = {
+    "version": 1,
+    "repository": {
+        "name": None,
+        "root": ".",
+    },
+    "scanner": {
+        "max_file_size_kb": 512,
+        "follow_symlinks": False,
+        "respect_gitignore": True,
+        "respect_devtimeignore": True,
+        "include_tests": True,
+        "include_docs": True,
+    },
+    "privacy": {
+        "ai_enabled": False,
+        "cloud_enabled": False,
+        "telemetry_enabled": False,
+        "store_ask_history": False,
+        "store_source_excerpts": False,
+    },
+    "context_packs": {
+        "default_mode": "risk",
+        "include_evidence_paths": True,
+        "include_source_excerpts": False,
+    },
+    "mcp": {
+        "enabled": False,
+        "bind": "127.0.0.1",
+        "read_only": True,
+        "expose_source": False,
+    },
+}
+
+
+def default_config_yaml() -> str:
+    return yaml.safe_dump(DEFAULT_CONFIG, sort_keys=False)
+
+
+def _deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    out = dict(base)
+    for key, value in (override or {}).items():
+        if isinstance(value, dict) and isinstance(out.get(key), dict):
+            out[key] = _deep_merge(out[key], value)
+        else:
+            out[key] = value
+    return out
+
+
+def load_config(root: Path | None = None) -> dict[str, Any]:
+    """Load config.yaml merged over defaults. Missing file returns defaults."""
+    path = paths.config_path(root)
+    if not path.exists():
+        return dict(DEFAULT_CONFIG)
+    loaded = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    return _deep_merge(DEFAULT_CONFIG, loaded)

devtime/db/connection.py

@@ -0,0 +1,16 @@
+"""SQLite connection helpers."""
+
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+
+from devtime import paths
+
+
+def connect(root: Path | None = None) -> sqlite3.Connection:
+    """Open the local memory database with sane defaults."""
+    conn = sqlite3.connect(paths.db_path(root))
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA foreign_keys = ON;")
+    return conn

devtime/db/migrations.py

@@ -0,0 +1,114 @@
+"""Database initialization and migrations (Builder Edition, Chapter 20).
+
+Every release can change what users believe, so migrations must preserve
+decisions, challenged claims, rejected claims, and human confirmations.
+V0 ships a single schema version; the migration framework is in place so later
+versions can back up and migrate without losing memory.
+"""
+
+from __future__ import annotations
+
+import shutil
+import sqlite3
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+
+from devtime import __version__, config, paths
+from devtime.db import connection
+
+SCHEMA_VERSION = 1
+SCHEMA_FILE = Path(__file__).with_name("schema.sql")
+IGNORE_STARTER = (
+    Path(__file__).resolve().parents[1] / "assets" / "devtimeignore.starter"
+)
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _ensure_dirs(root: Path | None = None) -> None:
+    paths.devtime_dir(root).mkdir(parents=True, exist_ok=True)
+    paths.backups_dir(root).mkdir(parents=True, exist_ok=True)
+    paths.logs_dir(root).mkdir(parents=True, exist_ok=True)
+
+
+def _write_starter_files(root: Path | None = None) -> None:
+    cfg = paths.config_path(root)
+    if not cfg.exists():
+        cfg.write_text(config.default_config_yaml(), encoding="utf-8")
+    ignore = paths.ignore_path(root)
+    if not ignore.exists() and IGNORE_STARTER.exists():
+        ignore.write_text(IGNORE_STARTER.read_text(encoding="utf-8"), encoding="utf-8")
+
+
+def current_version(conn: sqlite3.Connection) -> int:
+    row = conn.execute(
+        "SELECT name FROM sqlite_master WHERE type='table' AND name='schema_migrations'"
+    ).fetchone()
+    if row is None:
+        return 0
+    res = conn.execute("SELECT MAX(version) AS v FROM schema_migrations").fetchone()
+    return int(res["v"]) if res and res["v"] is not None else 0
+
+
+def _apply_schema(conn: sqlite3.Connection) -> None:
+    conn.executescript(SCHEMA_FILE.read_text(encoding="utf-8"))
+
+
+def init_repo(root: Path | None = None) -> str:
+    """Create local DevTime memory safely. Returns the repository id."""
+    _ensure_dirs(root)
+    _write_starter_files(root)
+
+    conn = connection.connect(root)
+    try:
+        _apply_schema(conn)
+        version = current_version(conn)
+        if version < SCHEMA_VERSION:
+            conn.execute(
+                "INSERT OR IGNORE INTO schema_migrations(version, applied_at) VALUES (?, ?)",
+                (SCHEMA_VERSION, _now()),
+            )
+
+        root_path = str((root or paths.repo_root()).resolve())
+        existing = conn.execute("SELECT id FROM repositories LIMIT 1").fetchone()
+        if existing:
+            repo_id = existing["id"]
+            conn.execute(
+                "UPDATE repositories SET root_path = ?, updated_at = ? WHERE id = ?",
+                (root_path, _now(), repo_id),
+            )
+        else:
+            repo_id = f"repo-{uuid.uuid4().hex[:12]}"
+            conn.execute(
+                "INSERT INTO repositories(id, root_path, created_at, updated_at) "
+                "VALUES (?, ?, ?, ?)",
+                (repo_id, root_path, _now(), _now()),
+            )
+        conn.commit()
+        return repo_id
+    finally:
+        conn.close()
+
+
+def backup_database(from_version: int, root: Path | None = None) -> Path | None:
+    """Create a pre-migration backup (Chapter 20 migration flow step 2)."""
+    db = paths.db_path(root)
+    if not db.exists():
+        return None
+    dest = paths.backups_dir(root) / f"devtime-before-schema-{from_version}.sqlite"
+    shutil.copy2(db, dest)
+    return dest
+
+
+def get_repository_id(root: Path | None = None) -> str | None:
+    if not paths.is_initialized(root):
+        return None
+    conn = connection.connect(root)
+    try:
+        row = conn.execute("SELECT id FROM repositories LIMIT 1").fetchone()
+        return row["id"] if row else None
+    finally:
+        conn.close()