datacharter 0.3.0__tar.gz → 0.3.2__tar.gz

{datacharter-0.3.0 → datacharter-0.3.2}/CHANGELOG.md

@@ -5,6 +5,23 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.3.2] - 2026-07-24
+
+### Fixed
+
+- `datacharter init` then `datacharter serve` failed with a `CharterError`: the
+  scaffolded charter uses an empty `sources: {}`, which the loader wrongly
+  rejected as "must be a non-empty mapping". A fresh workspace is now servable —
+  add sources afterward via `charter.yaml` or the in-app source manager.
+
+## [0.3.1] - 2026-07-24
+
+### Changed
+
+- Internal: extracted the origin/host request guard (DC-SEC-006) from the
+  server into an importable `datacharter.server.security` module. No behavior
+  change; the existing anti-DNS-rebinding / cross-origin protections are intact.
+
 ## [0.3.0] - 2026-07-24
 
 ### Added

{datacharter-0.3.0 → datacharter-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: datacharter
-Version: 0.3.0
+Version: 0.3.2
 Summary: Charter your data — contract-governed local data exploration, powered by DuckDB
 Project-URL: Homepage, https://github.com/datacharter/datacharter
 Project-URL: Repository, https://github.com/datacharter/datacharter
@@ -59,6 +59,20 @@ profiling. Every answer shows which source columns it read; ask questions in
 plain language or serve the whole thing to an AI agent over [MCP](docs/mcp.md),
 with PII masked from the model — all on your machine.
 
+## What you can do
+
+- **Drop a file, query it instantly.** Drag a CSV, Parquet, or JSON onto the window and run SQL on it right away — no import, no schema setup.
+- **Join across sources — no pipelines.** Query and JOIN a Postgres table, a Parquet file, and a Snowflake table in a *single* SQL statement. No ETL, no copying everything into a warehouse first.
+- **Connect all your data.** Postgres, MySQL, SQLite, SQL Server, BigQuery, Snowflake, files on S3/GCS/Azure, and Iceberg/Delta tables — all through one engine.
+- **See answers as you type.** Live results preview while you write SQL, one-click auto-charts, and a profiling panel (missing values, distributions, outliers) — no separate BI tool.
+- **Ask in plain English (optional).** Turn a question into SQL and an answer with the built-in agent — bring your own model, or run one fully local with no API key.
+- **Keep sensitive data away from the AI.** Mark PII columns once; the agent and any connected AI see masked values (`•••`) while you still see the real data locally. Flip **Agent view** to see exactly what the model sees.
+- **Safe by design.** The engine is read-only by construction — no query can write, delete, or touch the filesystem — so pointing an AI (or a teammate) at your real databases can't do damage.
+- **Point AI tools at your data, safely.** A governed MCP server exposes read-only, PII-masked query tools to Cursor, Cline, or your own agent.
+- **Trust every answer.** Each result shows exactly which source columns it read — so you always know where a number came from.
+- **Save, reuse, export.** Snapshot a result as a reusable local table; export to CSV, Parquet, JSON, or XLSX.
+- **Governance you can automate.** Catch schema/PII drift in CI, auto-detect PII columns, diff data across sources, and define certified metrics — from the command line.
+
 ![DataCharter — live SQL preview, auto-charts, per-query provenance, and PII masking](https://raw.githubusercontent.com/datacharter/datacharter/main/brand/demo.gif)
 
 **Status: pre-release.** V1 in development.
@@ -66,59 +80,57 @@ with PII masked from the model — all on your machine.
 ## Quick start
 
 ```sh
-# Try it instantly on generated demo data — no config, nothing to install globally:
-uvx datacharter serve
-# → opens a local workspace on http://127.0.0.1:8321
+# Try it instantly on generated demo data — no install, no config:
+uvx datacharter serve          # needs `uv` → https://astral.sh/uv
+# → serves at http://127.0.0.1:8321 (open it in your browser)
 
 # Or install it:
-pip install datacharter
+pip install datacharter        # Python 3.11+
+
+# Start your own workspace:
+datacharter init               # scaffolds charter.yaml, queries/, .env.example
+# → add a source: edit charter.yaml, or use the "Sources" panel in the UI
+datacharter serve              # → http://127.0.0.1:8321
+```
+
+Then, once it's running, **drag a CSV, Parquet, or JSON file onto the window** to
+query it instantly — no config needed.
 
-# Start a real workspace:
-datacharter init            # scaffolds charter.yaml, queries/, .env.example
-datacharter serve           # explore in your browser
+**Optional natural-language agent** — point it at any OpenAI-compatible endpoint:
 
-# Natural-language agent — bring your own endpoint…
-export OPENAI_BASE_URL=...  # any OpenAI-compatible API
+```sh
+export OPENAI_BASE_URL=...     # any OpenAI-compatible API
 export OPENAI_API_KEY=...
 datacharter serve
-# …or run fully local (no API key, no data leaves your machine):
-datacharter serve --local   # uses Ollama (qwen3:8b by default)
 ```
 
-Drop a CSV, Parquet, or JSON file onto the window to query it instantly.
+…or run **fully local** — no API key, no data leaves your machine (requires
+[Ollama](https://ollama.com)):
 
-## Why
+```sh
+ollama pull qwen3:8b           # once
+datacharter serve --local      # qwen3:8b by default (--model to change)
+```
+
+## Why DataCharter
 
 - **Your contracts are the catalog.** `charter.yaml` describes sources, tables,
-  and PII fields — the same contract spec your data team already writes.
-- **One engine, every source.** Postgres, MySQL, SQLite, BigQuery, SQL Server,
-  S3/GCS/Azure files, Iceberg, Delta — federated joins across all of them, with
-  filters and projections pushed down where the data lives — even across a
-  cross-source join, each leg is filtered at its source. Snowflake is supported
-  via connector extract (`datacharter[snowflake]`) with filters/projections
-  pushed into the extract. Every source's tables are exposed under one flat
-  `source__table` naming scheme.
-- **Local-first.** One process, your machine, no cloud dependency. Optional
-  `--local` agent mode runs a small open model via Ollama — no API key, no data
-  leaves your machine.
+  and PII fields — the same contract spec your data team already writes, so
+  there's no separate metadata store to maintain.
+- **Real federation, not just a shared connection.** Filters and projections are
+  pushed down to each source — even across a cross-source join, every leg is
+  filtered where its data lives. (Snowflake runs via connector extract,
+  `datacharter[snowflake]`, with the same pushdown into the extract.)
+- **Local-first.** One process, your machine, no cloud dependency. The optional
+  `--local` agent runs a small open model via Ollama — no API key, no data leaves
+  your machine.
 - **The workspace is a directory.** `charter.yaml` + `queries/*.sql` +
   `.env.example` — commit it, clone it, `datacharter serve`. Your team's whole
   exploration environment travels as a repo; secrets and local state never do.
 
-## More than a viewer
-
-DataCharter governs and audits your data, not just displays it — see the
-[CLI reference](docs/cli.md) for the full command set:
-
-- **Governed MCP server** — `datacharter mcp` exposes read-only, PII-masked query
-  tools to any MCP client (Cursor, Cline, or your own agent).
-- **Contracts you can check** — `datacharter drift` exits non-zero when a declared
-  table or PII column disappears; `datacharter scan` detects PII columns to add.
-- **Answers that show their work** — every result reports the source columns it
-  read; `datacharter diff` compares relations across sources; `datacharter metric`
-  runs governed metric definitions.
-- **Privacy-first** — `serve --offline` runs with no outbound network, and the
-  model never sees raw PII (flip **Agent view** in the UI to see exactly what it does).
+DataCharter governs and audits your data, not just displays it. The full command
+set (`drift`, `scan`, `diff`, `metric`, `mcp`, and more) is in the
+[CLI reference](docs/cli.md); the security model is in [security](docs/security.md).
 
 ## Built on
 

datacharter-0.3.2/README.md

@@ -0,0 +1,115 @@
+# DataCharter
+
+> Explore all your data locally, in one place — contract-governed data exploration, powered by DuckDB
+
+[![PyPI](https://img.shields.io/pypi/v/datacharter)](https://pypi.org/project/datacharter/)
+[![Python](https://img.shields.io/pypi/pyversions/datacharter)](https://pypi.org/project/datacharter/)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue)](LICENSE)
+
+Contract-governed local data exploration, **powered by [DuckDB](https://duckdb.org)**.
+Define your sources as data contracts
+([ODCS](https://bitol-io.github.io/open-data-contract-standard/)-compatible YAML),
+query them through DuckDB's SQL federation engine with real source pushdowns,
+and explore in a local web UI — SQL editor with live preview, auto-charts,
+profiling. Every answer shows which source columns it read; ask questions in
+plain language or serve the whole thing to an AI agent over [MCP](docs/mcp.md),
+with PII masked from the model — all on your machine.
+
+## What you can do
+
+- **Drop a file, query it instantly.** Drag a CSV, Parquet, or JSON onto the window and run SQL on it right away — no import, no schema setup.
+- **Join across sources — no pipelines.** Query and JOIN a Postgres table, a Parquet file, and a Snowflake table in a *single* SQL statement. No ETL, no copying everything into a warehouse first.
+- **Connect all your data.** Postgres, MySQL, SQLite, SQL Server, BigQuery, Snowflake, files on S3/GCS/Azure, and Iceberg/Delta tables — all through one engine.
+- **See answers as you type.** Live results preview while you write SQL, one-click auto-charts, and a profiling panel (missing values, distributions, outliers) — no separate BI tool.
+- **Ask in plain English (optional).** Turn a question into SQL and an answer with the built-in agent — bring your own model, or run one fully local with no API key.
+- **Keep sensitive data away from the AI.** Mark PII columns once; the agent and any connected AI see masked values (`•••`) while you still see the real data locally. Flip **Agent view** to see exactly what the model sees.
+- **Safe by design.** The engine is read-only by construction — no query can write, delete, or touch the filesystem — so pointing an AI (or a teammate) at your real databases can't do damage.
+- **Point AI tools at your data, safely.** A governed MCP server exposes read-only, PII-masked query tools to Cursor, Cline, or your own agent.
+- **Trust every answer.** Each result shows exactly which source columns it read — so you always know where a number came from.
+- **Save, reuse, export.** Snapshot a result as a reusable local table; export to CSV, Parquet, JSON, or XLSX.
+- **Governance you can automate.** Catch schema/PII drift in CI, auto-detect PII columns, diff data across sources, and define certified metrics — from the command line.
+
+![DataCharter — live SQL preview, auto-charts, per-query provenance, and PII masking](https://raw.githubusercontent.com/datacharter/datacharter/main/brand/demo.gif)
+
+**Status: pre-release.** V1 in development.
+
+## Quick start
+
+```sh
+# Try it instantly on generated demo data — no install, no config:
+uvx datacharter serve          # needs `uv` → https://astral.sh/uv
+# → serves at http://127.0.0.1:8321 (open it in your browser)
+
+# Or install it:
+pip install datacharter        # Python 3.11+
+
+# Start your own workspace:
+datacharter init               # scaffolds charter.yaml, queries/, .env.example
+# → add a source: edit charter.yaml, or use the "Sources" panel in the UI
+datacharter serve              # → http://127.0.0.1:8321
+```
+
+Then, once it's running, **drag a CSV, Parquet, or JSON file onto the window** to
+query it instantly — no config needed.
+
+**Optional natural-language agent** — point it at any OpenAI-compatible endpoint:
+
+```sh
+export OPENAI_BASE_URL=...     # any OpenAI-compatible API
+export OPENAI_API_KEY=...
+datacharter serve
+```
+
+…or run **fully local** — no API key, no data leaves your machine (requires
+[Ollama](https://ollama.com)):
+
+```sh
+ollama pull qwen3:8b           # once
+datacharter serve --local      # qwen3:8b by default (--model to change)
+```
+
+## Why DataCharter
+
+- **Your contracts are the catalog.** `charter.yaml` describes sources, tables,
+  and PII fields — the same contract spec your data team already writes, so
+  there's no separate metadata store to maintain.
+- **Real federation, not just a shared connection.** Filters and projections are
+  pushed down to each source — even across a cross-source join, every leg is
+  filtered where its data lives. (Snowflake runs via connector extract,
+  `datacharter[snowflake]`, with the same pushdown into the extract.)
+- **Local-first.** One process, your machine, no cloud dependency. The optional
+  `--local` agent runs a small open model via Ollama — no API key, no data leaves
+  your machine.
+- **The workspace is a directory.** `charter.yaml` + `queries/*.sql` +
+  `.env.example` — commit it, clone it, `datacharter serve`. Your team's whole
+  exploration environment travels as a repo; secrets and local state never do.
+
+DataCharter governs and audits your data, not just displays it. The full command
+set (`drift`, `scan`, `diff`, `metric`, `mcp`, and more) is in the
+[CLI reference](docs/cli.md); the security model is in [security](docs/security.md).
+
+## Built on
+
+DataCharter stands on excellent open-source foundations:
+
+- **[DuckDB](https://duckdb.org)** — the analytical engine at our core:
+  federation (`ATTACH`), file formats, Iceberg/Delta, encryption, autocomplete.
+- **[Open Data Contract Standard](https://bitol-io.github.io/open-data-contract-standard/)** /
+  [datacontract.com](https://datacontract-specification.com/) — the contract format `charter.yaml` speaks.
+- **[Model Context Protocol](https://modelcontextprotocol.io)** — the open protocol
+  the `datacharter mcp` server speaks to agents and MCP clients.
+- **[Vega-Lite](https://vega.github.io/vega-lite/)** — declarative charting.
+- **[Monaco Editor](https://microsoft.github.io/monaco-editor/)** — the SQL editor.
+- **[TanStack Table & Virtual](https://tanstack.com/)** — the virtualized results grid.
+- And the Python & React ecosystems — FastAPI, pydantic, httpx, keyring, and
+  ruamel.yaml on the backend; React and Vite on the front.
+
+Testing uses **[VidaiMock](https://github.com/vidaiUK/VidaiMock)**, an
+Apache-2.0 mock LLM server, as the offline agent endpoint in CI.
+
+DuckDB is a trademark of the DuckDB Foundation. DataCharter is an independent
+project and is not affiliated with or endorsed by the DuckDB Foundation.
+
+## License
+
+[Apache-2.0](LICENSE)

{datacharter-0.3.0 → datacharter-0.3.2}/src/datacharter/__init__.py

@@ -1,3 +1,3 @@
 """DataCharter — contract-governed local data exploration."""
 
-__version__ = "0.3.0"
+__version__ = "0.3.2"

{datacharter-0.3.0 → datacharter-0.3.2}/src/datacharter/contracts/loader.py

@@ -52,8 +52,10 @@ def load_charter(workspace: Path | str, filename: str = CHARTER_FILE) -> Charter
             f"{filename}: unsupported version {version!r}; expected {SUPPORTED_VERSION}."
         )
     sources_raw = raw.get("sources")
-    if not isinstance(sources_raw, dict) or not sources_raw:
-        raise CharterError(f"{filename}: 'sources' must be a non-empty mapping of name -> source.")
+    if sources_raw is None:  # a fresh `datacharter init` workspace: add sources later
+        sources_raw = {}
+    if not isinstance(sources_raw, dict):
+        raise CharterError(f"{filename}: 'sources' must be a mapping of name -> source.")
 
     resolver = SecretResolver(workspace)
     warnings: list[str] = []

{datacharter-0.3.0 → datacharter-0.3.2}/src/datacharter/server/app.py

@@ -9,7 +9,6 @@ import uuid
 from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
 from pathlib import Path
-from urllib.parse import urlparse
 
 from fastapi import FastAPI, Request, UploadFile
 from fastapi.responses import FileResponse, JSONResponse, StreamingResponse
@@ -27,14 +26,11 @@ from datacharter.engine.guard import QueryNotAllowed
 from datacharter.engine.session import DEFAULT_ROW_LIMIT, Engine, EngineError, QueryTimeout
 from datacharter.engine.statekey import resolve_state_key
 from datacharter.models import QueryResult, Source, SourceType
-from datacharter.server import llm_admin, source_admin
+from datacharter.server import llm_admin, security, source_admin
 
 HEARTBEAT_S = 1.0
 DEFAULT_TIMEOUT_S = 60.0
 
-# Hostnames that always denote this machine (anti-DNS-rebinding allowlist).
-_LOOPBACK_HOSTS = frozenset({"localhost", "127.0.0.1", "::1"})
-_ALL_INTERFACES = frozenset({"0.0.0.0", "::"})
 _MAX_UPLOAD_BYTES = 512 * 1024 * 1024  # 512 MB cap on a single upload
 
 
@@ -90,7 +86,7 @@ def create_app(
     """
     workspace = Path(workspace).resolve()
     loaded = charter if charter is not None else load_charter(workspace)
-    allowed_hosts = _allowed_hosts(host)
+    allowed = security.allowed_hosts(host)
     state_key = _state_key()
 
     @asynccontextmanager
@@ -114,21 +110,15 @@ def create_app(
     @app.middleware("http")
     async def _origin_guard(request: Request, call_next):
         """Reject DNS-rebinding (bad Host) and cross-site browser requests (CSRF)."""
-        host_name = (request.headers.get("host") or "").rsplit(":", 1)[0].strip("[]").lower()
-        if allowed_hosts is not None and host_name and host_name not in allowed_hosts:
+        if not security.host_allowed(request, allowed):
             return _error(403, "forbidden_host", "Host not allowed.")
         path = request.url.path
-        if path.startswith("/api/") and path != "/api/health":
-            origin = request.headers.get("origin")
-            if origin:
-                origin_host = (urlparse(origin).hostname or "").lower()
-                if origin_host not in (allowed_hosts or _LOOPBACK_HOSTS):
-                    return _error(403, "forbidden_origin", "Cross-origin request rejected.")
-            if (request.headers.get("sec-fetch-site") or "").lower() in (
-                "cross-site",
-                "cross-origin",
-            ):
-                return _error(403, "forbidden_origin", "Cross-site request rejected.")
+        if (
+            path.startswith("/api/")
+            and path != "/api/health"
+            and not security.origin_allowed(request, allowed)
+        ):
+            return _error(403, "forbidden_origin", "Cross-origin request rejected.")
         return await call_next(request)
 
     @app.exception_handler(QueryNotAllowed)
@@ -364,13 +354,6 @@ def create_app(
     return app
 
 
-def _allowed_hosts(host: str) -> frozenset[str] | None:
-    """Host-header allowlist for the bind address; None = all interfaces (skip)."""
-    if host.lower() in _ALL_INTERFACES:
-        return None  # explicit network opt-in (D4) — Host allowlist can't apply
-    return _LOOPBACK_HOSTS | {host.lower()}
-
-
 def _state_key() -> str | None:
     """Encryption key for the local state DB (D8) — see engine.statekey."""
     return resolve_state_key()

datacharter-0.3.2/src/datacharter/server/security.py

@@ -0,0 +1,56 @@
+"""Anti-DNS-rebinding / cross-origin request guards (DC-SEC-006).
+
+Pure predicates shared by the core server and any HTTP transport built on the same
+governed toolbox: they decide allow/deny from request headers, they do not build
+responses. `host_allowed` blocks DNS-rebinding (a bad `Host`); `origin_allowed`
+blocks cross-site browser requests (a foreign `Origin` / `Sec-Fetch-Site`).
+"""
+
+from __future__ import annotations
+
+from urllib.parse import urlparse
+
+from starlette.requests import Request
+
+__all__ = [
+    "LOOPBACK_HOSTS",
+    "ALL_INTERFACES",
+    "allowed_hosts",
+    "host_allowed",
+    "origin_allowed",
+    "is_request_allowed",
+]
+
+# Hostnames that always denote this machine.
+LOOPBACK_HOSTS = frozenset({"localhost", "127.0.0.1", "::1"})
+ALL_INTERFACES = frozenset({"0.0.0.0", "::"})
+_CROSS_SITE = frozenset({"cross-site", "cross-origin"})
+
+
+def allowed_hosts(host: str) -> frozenset[str] | None:
+    """Host-header allowlist for a bind address; None = all interfaces (skip)."""
+    if host.lower() in ALL_INTERFACES:
+        return None  # explicit network opt-in (D4) — a Host allowlist can't apply
+    return LOOPBACK_HOSTS | {host.lower()}
+
+
+def host_allowed(request: Request, allowed: frozenset[str] | None) -> bool:
+    """False iff the `Host` header names a host outside the allowlist."""
+    host_name = (request.headers.get("host") or "").rsplit(":", 1)[0].strip("[]").lower()
+    return not (allowed is not None and host_name and host_name not in allowed)
+
+
+def origin_allowed(request: Request, allowed: frozenset[str] | None) -> bool:
+    """False iff a cross-site `Origin` or `Sec-Fetch-Site` header is present."""
+    origin = request.headers.get("origin")
+    if origin:
+        origin_host = (urlparse(origin).hostname or "").lower()
+        if origin_host not in (allowed or LOOPBACK_HOSTS):
+            return False
+    return (request.headers.get("sec-fetch-site") or "").lower() not in _CROSS_SITE
+
+
+def is_request_allowed(request: Request, allowed: frozenset[str] | None) -> bool:
+    """Both guards — for endpoints (e.g. MCP over HTTP) that want the full check on
+    every request, regardless of path."""
+    return host_allowed(request, allowed) and origin_allowed(request, allowed)

{datacharter-0.3.0 → datacharter-0.3.2}/tests/contracts/test_loader.py

@@ -16,6 +16,24 @@ def test_minimal_file_source_loads(tmp_path):
     assert charter.warnings == []
 
 
+def test_empty_sources_loads_as_fresh_workspace(tmp_path):
+    # `datacharter init` scaffolds `sources: {}`; a fresh workspace must be servable
+    # (sources are added later, via charter.yaml or the in-app source manager).
+    charter = load_charter(write_charter(tmp_path, "version: 1\nsources: {}\n"))
+    assert charter.sources == []
+
+
+def test_null_sources_loads_as_empty(tmp_path):
+    charter = load_charter(write_charter(tmp_path, "version: 1\nsources:\n"))
+    assert charter.sources == []
+
+
+def test_non_mapping_sources_rejected(tmp_path):
+    ws = write_charter(tmp_path, "version: 1\nsources:\n  - a\n  - b\n")
+    with pytest.raises(CharterError, match=r"'sources' must be a mapping"):
+        load_charter(ws)
+
+
 def test_env_reference_resolution(tmp_path, monkeypatch):
     monkeypatch.setenv("PG_PW", "resolved-pw-value")
     ws = write_charter(

datacharter-0.3.2/tests/server/test_security.py

@@ -0,0 +1,52 @@
+from starlette.requests import Request
+
+from datacharter.server.security import (
+    allowed_hosts,
+    host_allowed,
+    is_request_allowed,
+    origin_allowed,
+)
+
+
+def _req(headers: dict) -> Request:
+    raw = [(k.lower().encode(), v.encode()) for k, v in headers.items()]
+    return Request({"type": "http", "headers": raw})
+
+
+def test_allowed_hosts_includes_loopback_and_bind():
+    ah = allowed_hosts("127.0.0.1")
+    assert ah is not None and "127.0.0.1" in ah and "localhost" in ah
+
+
+def test_all_interfaces_disables_allowlist():
+    assert allowed_hosts("0.0.0.0") is None
+
+
+def test_loopback_host_allowed():
+    assert host_allowed(_req({"host": "127.0.0.1:8765"}), allowed_hosts("127.0.0.1")) is True
+
+
+def test_foreign_host_rejected():
+    assert host_allowed(_req({"host": "evil.example.com"}), allowed_hosts("127.0.0.1")) is False
+
+
+def test_cross_origin_rejected():
+    ah = allowed_hosts("127.0.0.1")
+    assert origin_allowed(_req({"origin": "http://evil.example.com"}), ah) is False
+
+
+def test_cross_site_secfetch_rejected():
+    ah = allowed_hosts("127.0.0.1")
+    assert origin_allowed(_req({"sec-fetch-site": "cross-site"}), ah) is False
+
+
+def test_same_origin_allowed():
+    req = _req({"origin": "http://127.0.0.1", "sec-fetch-site": "same-origin"})
+    assert origin_allowed(req, allowed_hosts("127.0.0.1")) is True
+
+
+def test_is_request_allowed_combines_host_and_origin():
+    ah = allowed_hosts("127.0.0.1")
+    assert is_request_allowed(_req({"host": "127.0.0.1:8765"}), ah) is True
+    bad = _req({"host": "127.0.0.1", "origin": "http://evil.example.com"})
+    assert is_request_allowed(bad, ah) is False

{datacharter-0.3.0 → datacharter-0.3.2}/tests/test_cli_init.py

@@ -44,6 +44,29 @@ def test_demo_workspace_loads_and_queries_end_to_end(tmp_path):
         assert len(result.rows) == 2
 
 
+def test_plain_init_charter_loads_as_empty(tmp_path):
+    # Regression: plain `init` scaffolds `sources: {}`; the scaffolded charter MUST
+    # load. 0.3.1 shipped an init template that `load_charter` then refused.
+    assert main(["init", str(tmp_path)]) == 0
+    charter = load_charter(tmp_path)
+    assert charter.sources == []
+
+
+def test_plain_init_workspace_serves_end_to_end(tmp_path):
+    # The real user path `init` -> `serve`: create_app must boot on a fresh empty
+    # workspace and the sources API returns an empty list (sources added later).
+    from fastapi.testclient import TestClient
+
+    from datacharter.server import create_app
+
+    assert main(["init", str(tmp_path)]) == 0
+    app = create_app(tmp_path)
+    with TestClient(app, base_url="http://127.0.0.1") as c:
+        resp = c.get("/api/sources")
+        assert resp.status_code == 200
+        assert resp.json()["sources"] == []
+
+
 def test_serve_workspace_resolution_prefers_existing_charter(tmp_path):
     from datacharter.cli import _resolve_serve_workspace, main
 

datacharter-0.3.0/README.md

@@ -1,103 +0,0 @@
-# DataCharter
-
-> Explore all your data locally, in one place — contract-governed data exploration, powered by DuckDB
-
-[![PyPI](https://img.shields.io/pypi/v/datacharter)](https://pypi.org/project/datacharter/)
-[![Python](https://img.shields.io/pypi/pyversions/datacharter)](https://pypi.org/project/datacharter/)
-[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue)](LICENSE)
-
-Contract-governed local data exploration, **powered by [DuckDB](https://duckdb.org)**.
-Define your sources as data contracts
-([ODCS](https://bitol-io.github.io/open-data-contract-standard/)-compatible YAML),
-query them through DuckDB's SQL federation engine with real source pushdowns,
-and explore in a local web UI — SQL editor with live preview, auto-charts,
-profiling. Every answer shows which source columns it read; ask questions in
-plain language or serve the whole thing to an AI agent over [MCP](docs/mcp.md),
-with PII masked from the model — all on your machine.
-
-![DataCharter — live SQL preview, auto-charts, per-query provenance, and PII masking](https://raw.githubusercontent.com/datacharter/datacharter/main/brand/demo.gif)
-
-**Status: pre-release.** V1 in development.
-
-## Quick start
-
-```sh
-# Try it instantly on generated demo data — no config, nothing to install globally:
-uvx datacharter serve
-# → opens a local workspace on http://127.0.0.1:8321
-
-# Or install it:
-pip install datacharter
-
-# Start a real workspace:
-datacharter init            # scaffolds charter.yaml, queries/, .env.example
-datacharter serve           # explore in your browser
-
-# Natural-language agent — bring your own endpoint…
-export OPENAI_BASE_URL=...  # any OpenAI-compatible API
-export OPENAI_API_KEY=...
-datacharter serve
-# …or run fully local (no API key, no data leaves your machine):
-datacharter serve --local   # uses Ollama (qwen3:8b by default)
-```
-
-Drop a CSV, Parquet, or JSON file onto the window to query it instantly.
-
-## Why
-
-- **Your contracts are the catalog.** `charter.yaml` describes sources, tables,
-  and PII fields — the same contract spec your data team already writes.
-- **One engine, every source.** Postgres, MySQL, SQLite, BigQuery, SQL Server,
-  S3/GCS/Azure files, Iceberg, Delta — federated joins across all of them, with
-  filters and projections pushed down where the data lives — even across a
-  cross-source join, each leg is filtered at its source. Snowflake is supported
-  via connector extract (`datacharter[snowflake]`) with filters/projections
-  pushed into the extract. Every source's tables are exposed under one flat
-  `source__table` naming scheme.
-- **Local-first.** One process, your machine, no cloud dependency. Optional
-  `--local` agent mode runs a small open model via Ollama — no API key, no data
-  leaves your machine.
-- **The workspace is a directory.** `charter.yaml` + `queries/*.sql` +
-  `.env.example` — commit it, clone it, `datacharter serve`. Your team's whole
-  exploration environment travels as a repo; secrets and local state never do.
-
-## More than a viewer
-
-DataCharter governs and audits your data, not just displays it — see the
-[CLI reference](docs/cli.md) for the full command set:
-
-- **Governed MCP server** — `datacharter mcp` exposes read-only, PII-masked query
-  tools to any MCP client (Cursor, Cline, or your own agent).
-- **Contracts you can check** — `datacharter drift` exits non-zero when a declared
-  table or PII column disappears; `datacharter scan` detects PII columns to add.
-- **Answers that show their work** — every result reports the source columns it
-  read; `datacharter diff` compares relations across sources; `datacharter metric`
-  runs governed metric definitions.
-- **Privacy-first** — `serve --offline` runs with no outbound network, and the
-  model never sees raw PII (flip **Agent view** in the UI to see exactly what it does).
-
-## Built on
-
-DataCharter stands on excellent open-source foundations:
-
-- **[DuckDB](https://duckdb.org)** — the analytical engine at our core:
-  federation (`ATTACH`), file formats, Iceberg/Delta, encryption, autocomplete.
-- **[Open Data Contract Standard](https://bitol-io.github.io/open-data-contract-standard/)** /
-  [datacontract.com](https://datacontract-specification.com/) — the contract format `charter.yaml` speaks.
-- **[Model Context Protocol](https://modelcontextprotocol.io)** — the open protocol
-  the `datacharter mcp` server speaks to agents and MCP clients.
-- **[Vega-Lite](https://vega.github.io/vega-lite/)** — declarative charting.
-- **[Monaco Editor](https://microsoft.github.io/monaco-editor/)** — the SQL editor.
-- **[TanStack Table & Virtual](https://tanstack.com/)** — the virtualized results grid.
-- And the Python & React ecosystems — FastAPI, pydantic, httpx, keyring, and
-  ruamel.yaml on the backend; React and Vite on the front.
-
-Testing uses **[VidaiMock](https://github.com/vidaiUK/VidaiMock)**, an
-Apache-2.0 mock LLM server, as the offline agent endpoint in CI.
-
-DuckDB is a trademark of the DuckDB Foundation. DataCharter is an independent
-project and is not affiliated with or endorsed by the DuckDB Foundation.
-
-## License
-
-[Apache-2.0](LICENSE)