parse-sdk 0.1.0__tar.gz → 0.2.0__tar.gz

parse_sdk-0.2.0/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to `parse-sdk` are documented here. This project follows
+[Semantic Versioning](https://semver.org/).
+
+## [0.2.0] — reliable sync and improved CLI workflows
+
+- **Reliable reconciliation:** stronger validation and staged promotion make sync
+  more predictable when schemas or project configuration change.
+- **Consistent API identity:** account and marketplace workflows now handle API
+  selection consistently across `init`, `add`, `remove`, and sync.
+- **Improved CLI automation:** commands provide clearer guidance, predictable
+  JSON output and exit behavior, API selectors for `init`, and more focused sync
+  results.
+- **Project diagnostics:** `parse doctor` performs read-only inspection with
+  fewer assumptions about the local project environment.
+- **Documentation:** refreshed the command reference, SDK-versus-MCP guidance,
+  credential setup, and development workflow.
+
+## [0.1.0] — first public release
+
+Initial public release of the `parse-sdk` runtime + `parse` CLI: a
+dynamic-yet-typed Python SDK that generates a project-local, fully typed client
+for the Parse APIs your key can call.
+
+- **CLI** (`parse`): `init`, `sync`, `login` (API key or browser OAuth via
+  `--web`), `doctor` (diagnose / `--fix`), `list`, `whoami`, `help`, `clean`,
+  and marketplace `add` / `search` / `remove`, plus `[tool.parse]`-driven
+  selective sync.
+- **Typed runtime**: resources, collections, pagination, retries with a
+  wall-clock budget, and host-bound authentication.
+- Ships `py.typed`; supports Python 3.10–3.14.

{parse_sdk-0.1.0 → parse_sdk-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: parse-sdk
-Version: 0.1.0
+Version: 0.2.0
 Summary: Dynamic-yet-typed Python SDK for Parse APIs
 Project-URL: Homepage, https://parse.bot
 Project-URL: Changelog, https://pypi.org/project/parse-sdk/#history
@@ -32,11 +32,21 @@ Description-Content-Type: text/markdown
 
 Typed Python SDK tooling for [Parse](https://parse.bot) APIs.
 
+Requires Python 3.10 or newer.
+
 `parse-sdk` is the shared **runtime + CLI**. It generates a project-local
 `parse_apis` package — a real, installed, editable dependency — that holds the
 typed client for every API your key can call. Your application code imports from
 `parse_apis`; `parse-sdk` provides the runtime bases and errors those clients use.
 
+## SDK and MCP
+
+Use Parse MCP when an agent is discovering or calling APIs ad hoc, or managing
+account-owned server-side variants. Use this SDK for durable, typed Python
+clients committed to an application. Neither requires the other: the SDK can
+use `parse search` and `parse add --marketplace <listing_id>` without creating
+an MCP subscription.
+
 ## Quickstart
 
 In a uv-managed project (`uv init` first if you don't have a `pyproject.toml`):
@@ -46,9 +56,10 @@ uv add parse-sdk            # installs the runtime + `parse` CLI into your proje
 uv run parse init           # prompts for your API key, then scaffolds + syncs parse_apis
 ```
 
-Non-interactive (CI, agents, scripts): authenticate first with
-`uv run parse login --api-key YOUR_KEY` (add `--base-url …` for a non-default
-host), or export `PARSE_API_KEY` — then `uv run parse init` runs without prompts.
+Non-interactive (CI, agents, scripts): export `PARSE_API_KEY`, then run
+`uv run parse init`. `parse login --api-key` persists a key, but is a less-safe
+automation fallback because argv can be recorded in process listings and shell
+history.
 
 `parse init` is the one-time setup. It:
 
@@ -74,8 +85,9 @@ except RateLimitError:
     ...
 ```
 
-(The exact methods are generated from *your* API's spec — `parse_apis/<slug>/README.md`
-and `example.py` document each client's real surface.)
+(The exact methods are generated from *your* API's spec —
+`parse_apis/src/parse_apis/<slug>/README.md` and `example.py` document each
+client's real surface.)
 
 ```bash
 uv run python app.py        # run your app in the project environment
@@ -99,16 +111,17 @@ they just `import parse_apis`.
 
 ```text
 parse_apis/
+  AGENTS.md  CLAUDE.md           # committed, byte-identical agent pointers
   pyproject.toml                 # committed: name="parse-apis", pinned parse-sdk==X
   src/parse_apis/
     __init__.py                  # committed scaffold — re-exports runtime errors
     py.typed                     # committed
-    reddit/__init__.py           # generated (gitignored)
+    reddit_com_api/__init__.py   # generated (gitignored)
     _manifest.json               # generated (gitignored)
     AGENTS.md  CLAUDE.md         # generated cross-API index (gitignored)
 ```
 
-Commit the three scaffold files; the generated payload is per-key (it reveals your API
+Commit the five scaffold files; the generated payload is per-key (it reveals your API
 inventory) and stays gitignored. `parse sync` builds the next payload in a staging tree,
 self-tests it (secret scan, import-model, no-stale-docs), and promotes it with an atomic
 directory swap — a failed sync never leaves broken or secret-bearing files in your project.
@@ -138,14 +151,51 @@ succeeds on a clean checkout.
 
 | Command | What it does |
 | --- | --- |
-| `parse login` | Save API key + base URL to local credentials. No project changes. |
-| `parse init` | One-time: ensure creds, scaffold `parse_apis`, record deps + gitignore, first sync. |
-| `parse sync` | Regenerate the typed payload into `parse_apis/src/parse_apis` (staged + atomic). |
-| `parse clean` | Remove generated payload; keep the committed scaffold. |
+| `parse login` | Save browser OAuth credentials by default, or an API key with `--api-key`. No project changes. |
+| `parse init` | One-time: ensure creds, scaffold `parse_apis`, record deps + gitignore, first sync. Pass slugs to track just those APIs. |
 | `parse list` | Print the APIs the current key can call (no generation). |
+| `parse sync` | Regenerate the typed payload into `parse_apis/src/parse_apis` (staged + atomic). `--check` is a CI dry run. |
+| `parse add` | Add APIs to the repo's synced set (`--marketplace` for shared canonicals; new entries pin the latest usable release, while re-add preserves existing pin/live state), then reconcile. |
+| `parse remove` | Stop syncing APIs (account or marketplace) and prune their generated clients. |
+| `parse search` | Search the Parse marketplace for ready-made APIs. |
+| `parse clean` | Remove generated payload; keep the committed scaffold. |
 | `parse whoami` | Show the current key + base URL. |
+| `parse doctor` | Diagnose the project's SDK install; `--fix` applies safe remediations. |
+| `parse help` | Guided getting-started workflow (`--json` for machine-readable orientation). |
 
-Run `parse <cmd> --help` for full per-command help.
+Run `parse <cmd> --help` for full per-command help — every command's help ends
+with copy-pasteable Examples.
+
+## Agents & automation
+
+The CLI is built to run headless: prompts only fire on an interactive terminal
+(non-TTY runs fail fast with the exact fix), warnings go to stderr, and stdout
+stays machine-parseable under `--json`.
+
+**Machine-readable output.** `parse help --json` is the orientation entrypoint:
+it lists every command with `requires_auth` / `requires_init` facts and (under
+`agent_modes`) which commands accept `--json` — the list is derived from the
+live command registry, so it never goes stale. The `--json` shapes are stable:
+
+| Command | Shape |
+| --- | --- |
+| `whoami --json` | object: `base_url`, `api_key_masked`, `key_configured`, `key_sent_to_host`, `web_login`, `auth_method` |
+| `list --json` | array of `{id, slug, name, modeled, endpoints, resources, version}` |
+| `sync` / `add` / `remove` `--json` | object: `written[] {slug, id, root, status, warnings[]}`, `skipped[] {slug, id, reason}`, `removed[]`, `quarantined[] {slug, id, retained, findings[]}`, `failures[]` — on a gate abort, `{failures}` alone with exit 1; under `sync --check`, `failures` carries every finding (non-empty ⟺ exit 1) |
+| `doctor --json` | object: `ok`, `findings[] {level, title, detail, fix, kind}` |
+| `search --json` | array of `{id, slug, name, source_url, endpoint_count, is_authenticated}` |
+
+**Exit codes.** `0` — success. `1` — the command ran and detected a problem
+(sync's pre-promotion gate abort, `sync --check` findings, `doctor` error-level
+findings, `init` refusing to migrate a legacy tree with non-Parse files, a lost
+concurrent-promote race). `2` — the command couldn't run: usage errors, an
+uninitialized project, missing/withheld credentials or an untrusted host,
+network failures.
+
+**Credentials in automation.** Prefer exporting `PARSE_API_KEY` over passing
+`--api-key` on the command line — argv is visible in process listings and shell
+history. `parse login` (browser OAuth by default; `--web` is explicit) requires an interactive terminal
+and fails fast headless.
 
 ## Versioning
 
@@ -157,8 +207,8 @@ regenerate against the new runtime; `init`/`sync` restamp the pin.
 
 | Var | Default | Notes |
 | --- | --- | --- |
-| `PARSE_API_KEY` | – | Auth for real requests (or use `parse login`). |
-| `PARSE_API_BASE_URL` | `https://api.parse.bot` | Locally: `http://localhost:8001`. |
+| `PARSE_API_KEY` | – | Auth for real requests (or use `parse login`). Preferred over `--api-key` in automation. |
+| `PARSE_ACCESS_TOKEN` | – | OAuth bearer token override (normally managed by interactive `parse login`). |
 
 ## Changelog
 

{parse_sdk-0.1.0 → parse_sdk-0.2.0}/README.md

@@ -2,11 +2,21 @@
 
 Typed Python SDK tooling for [Parse](https://parse.bot) APIs.
 
+Requires Python 3.10 or newer.
+
 `parse-sdk` is the shared **runtime + CLI**. It generates a project-local
 `parse_apis` package — a real, installed, editable dependency — that holds the
 typed client for every API your key can call. Your application code imports from
 `parse_apis`; `parse-sdk` provides the runtime bases and errors those clients use.
 
+## SDK and MCP
+
+Use Parse MCP when an agent is discovering or calling APIs ad hoc, or managing
+account-owned server-side variants. Use this SDK for durable, typed Python
+clients committed to an application. Neither requires the other: the SDK can
+use `parse search` and `parse add --marketplace <listing_id>` without creating
+an MCP subscription.
+
 ## Quickstart
 
 In a uv-managed project (`uv init` first if you don't have a `pyproject.toml`):
@@ -16,9 +26,10 @@ uv add parse-sdk            # installs the runtime + `parse` CLI into your proje
 uv run parse init           # prompts for your API key, then scaffolds + syncs parse_apis
 ```
 
-Non-interactive (CI, agents, scripts): authenticate first with
-`uv run parse login --api-key YOUR_KEY` (add `--base-url …` for a non-default
-host), or export `PARSE_API_KEY` — then `uv run parse init` runs without prompts.
+Non-interactive (CI, agents, scripts): export `PARSE_API_KEY`, then run
+`uv run parse init`. `parse login --api-key` persists a key, but is a less-safe
+automation fallback because argv can be recorded in process listings and shell
+history.
 
 `parse init` is the one-time setup. It:
 
@@ -44,8 +55,9 @@ except RateLimitError:
     ...
 ```
 
-(The exact methods are generated from *your* API's spec — `parse_apis/<slug>/README.md`
-and `example.py` document each client's real surface.)
+(The exact methods are generated from *your* API's spec —
+`parse_apis/src/parse_apis/<slug>/README.md` and `example.py` document each
+client's real surface.)
 
 ```bash
 uv run python app.py        # run your app in the project environment
@@ -69,16 +81,17 @@ they just `import parse_apis`.
 
 ```text
 parse_apis/
+  AGENTS.md  CLAUDE.md           # committed, byte-identical agent pointers
   pyproject.toml                 # committed: name="parse-apis", pinned parse-sdk==X
   src/parse_apis/
     __init__.py                  # committed scaffold — re-exports runtime errors
     py.typed                     # committed
-    reddit/__init__.py           # generated (gitignored)
+    reddit_com_api/__init__.py   # generated (gitignored)
     _manifest.json               # generated (gitignored)
     AGENTS.md  CLAUDE.md         # generated cross-API index (gitignored)
 ```
 
-Commit the three scaffold files; the generated payload is per-key (it reveals your API
+Commit the five scaffold files; the generated payload is per-key (it reveals your API
 inventory) and stays gitignored. `parse sync` builds the next payload in a staging tree,
 self-tests it (secret scan, import-model, no-stale-docs), and promotes it with an atomic
 directory swap — a failed sync never leaves broken or secret-bearing files in your project.
@@ -108,14 +121,51 @@ succeeds on a clean checkout.
 
 | Command | What it does |
 | --- | --- |
-| `parse login` | Save API key + base URL to local credentials. No project changes. |
-| `parse init` | One-time: ensure creds, scaffold `parse_apis`, record deps + gitignore, first sync. |
-| `parse sync` | Regenerate the typed payload into `parse_apis/src/parse_apis` (staged + atomic). |
-| `parse clean` | Remove generated payload; keep the committed scaffold. |
+| `parse login` | Save browser OAuth credentials by default, or an API key with `--api-key`. No project changes. |
+| `parse init` | One-time: ensure creds, scaffold `parse_apis`, record deps + gitignore, first sync. Pass slugs to track just those APIs. |
 | `parse list` | Print the APIs the current key can call (no generation). |
+| `parse sync` | Regenerate the typed payload into `parse_apis/src/parse_apis` (staged + atomic). `--check` is a CI dry run. |
+| `parse add` | Add APIs to the repo's synced set (`--marketplace` for shared canonicals; new entries pin the latest usable release, while re-add preserves existing pin/live state), then reconcile. |
+| `parse remove` | Stop syncing APIs (account or marketplace) and prune their generated clients. |
+| `parse search` | Search the Parse marketplace for ready-made APIs. |
+| `parse clean` | Remove generated payload; keep the committed scaffold. |
 | `parse whoami` | Show the current key + base URL. |
+| `parse doctor` | Diagnose the project's SDK install; `--fix` applies safe remediations. |
+| `parse help` | Guided getting-started workflow (`--json` for machine-readable orientation). |
 
-Run `parse <cmd> --help` for full per-command help.
+Run `parse <cmd> --help` for full per-command help — every command's help ends
+with copy-pasteable Examples.
+
+## Agents & automation
+
+The CLI is built to run headless: prompts only fire on an interactive terminal
+(non-TTY runs fail fast with the exact fix), warnings go to stderr, and stdout
+stays machine-parseable under `--json`.
+
+**Machine-readable output.** `parse help --json` is the orientation entrypoint:
+it lists every command with `requires_auth` / `requires_init` facts and (under
+`agent_modes`) which commands accept `--json` — the list is derived from the
+live command registry, so it never goes stale. The `--json` shapes are stable:
+
+| Command | Shape |
+| --- | --- |
+| `whoami --json` | object: `base_url`, `api_key_masked`, `key_configured`, `key_sent_to_host`, `web_login`, `auth_method` |
+| `list --json` | array of `{id, slug, name, modeled, endpoints, resources, version}` |
+| `sync` / `add` / `remove` `--json` | object: `written[] {slug, id, root, status, warnings[]}`, `skipped[] {slug, id, reason}`, `removed[]`, `quarantined[] {slug, id, retained, findings[]}`, `failures[]` — on a gate abort, `{failures}` alone with exit 1; under `sync --check`, `failures` carries every finding (non-empty ⟺ exit 1) |
+| `doctor --json` | object: `ok`, `findings[] {level, title, detail, fix, kind}` |
+| `search --json` | array of `{id, slug, name, source_url, endpoint_count, is_authenticated}` |
+
+**Exit codes.** `0` — success. `1` — the command ran and detected a problem
+(sync's pre-promotion gate abort, `sync --check` findings, `doctor` error-level
+findings, `init` refusing to migrate a legacy tree with non-Parse files, a lost
+concurrent-promote race). `2` — the command couldn't run: usage errors, an
+uninitialized project, missing/withheld credentials or an untrusted host,
+network failures.
+
+**Credentials in automation.** Prefer exporting `PARSE_API_KEY` over passing
+`--api-key` on the command line — argv is visible in process listings and shell
+history. `parse login` (browser OAuth by default; `--web` is explicit) requires an interactive terminal
+and fails fast headless.
 
 ## Versioning
 
@@ -127,8 +177,8 @@ regenerate against the new runtime; `init`/`sync` restamp the pin.
 
 | Var | Default | Notes |
 | --- | --- | --- |
-| `PARSE_API_KEY` | – | Auth for real requests (or use `parse login`). |
-| `PARSE_API_BASE_URL` | `https://api.parse.bot` | Locally: `http://localhost:8001`. |
+| `PARSE_API_KEY` | – | Auth for real requests (or use `parse login`). Preferred over `--api-key` in automation. |
+| `PARSE_ACCESS_TOKEN` | – | OAuth bearer token override (normally managed by interactive `parse login`). |
 
 ## Changelog
 

{parse_sdk-0.1.0 → parse_sdk-0.2.0}/parse_sdk/__init__.py

@@ -4,7 +4,7 @@ Typed clients are generated by `parse sync` into a project-local
 `parse_apis/` package and imported directly:
 
     import parse_sdk as parse                      # errors / runtime helpers
-    from parse_apis.reddit import Reddit           # generated typed client
+    from parse_apis.reddit_com_api import Reddit   # generated typed client
 
     try:
         reddit = Reddit()                          # picks up `parse login` creds
@@ -37,7 +37,7 @@ from parse_sdk._runtime import (
     UpstreamError,
 )
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 __all__ = [
     "BaseAPI",
     "Resource",

parse_sdk-0.2.0/parse_sdk/_identifiers.py

@@ -0,0 +1,23 @@
+"""Comparison helpers for server-owned API identifiers."""
+from __future__ import annotations
+
+import re
+
+
+_UUID_RE = re.compile(
+    r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-"
+    r"[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
+)
+
+
+def _identifier_key(value: str) -> str:
+    """Return a comparison key without changing opaque identifier semantics."""
+    return value.casefold() if _UUID_RE.fullmatch(value) else value
+
+
+def _same_identifier(left: object, right: object) -> bool:
+    return (
+        isinstance(left, str)
+        and isinstance(right, str)
+        and _identifier_key(left) == _identifier_key(right)
+    )

parse_sdk-0.2.0/parse_sdk/_project.py

@@ -0,0 +1,277 @@
+"""The committed, declarative project config — the ``[tool.parse]`` table in the
+consumer ``pyproject.toml`` that records which APIs this repo wants.
+
+This is the DESIRED-state manifest: committed, reproducible across clones/CI,
+and the source of truth ``parse sync`` reconciles the generated tree to. It is
+distinct from ``parse_apis/_manifest.json`` (the GENERATED uuid→slug map, which
+is gitignored and rebuilt every sync).
+
+  * ``apis`` — the account APIs this repo wants, recorded as *server slugs* (the
+    readable, committed form). A ``scraper_id`` (UUID) is also accepted on read (a
+    tolerant dual-read), so a hand-written UUID — or any future identifier — still
+    resolves and is never mistaken for a missing entry. The key being ABSENT means
+    "all your account APIs" (the post-``init`` default); an explicit list
+    (including the empty list) means exactly those.
+  * ``marketplace`` — locally-downloaded marketplace canonicals, optionally
+    pinned to a release. Unknown fields fail closed: generated projects pin the
+    SDK version, so silently guessing at a newer config contract is unnecessary.
+
+We OWN the ``[tool.parse]`` table: writes regenerate it wholesale from the values
+we just read back, so a hand-edited value (e.g. a slug you added to ``apis``)
+survives, but formatting/comments *inside* the table are normalized. We never
+touch anything outside it.
+"""
+from __future__ import annotations
+
+import json
+import re
+try:
+    import tomllib  # Python 3.11+
+except ModuleNotFoundError:  # 3.10 — tomllib landed in 3.11; tomli is its backport
+    import tomli as tomllib  # type: ignore[no-redef]
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from parse_sdk._identifiers import _identifier_key
+
+
+@dataclass
+class MarketplaceEntry:
+    """A locally-downloaded marketplace canonical recorded for reproducible
+    re-sync. ``scraper_id`` (canonical_scraper_id) is the execution + schema
+    primary key; ``version`` pins execution via the ``API-Snapshot-Version``
+    header."""
+    scraper_id: str
+    slug: str
+    version: Optional[int] = None
+    listing_id: Optional[str] = None
+    source_url: Optional[str] = None
+
+
+@dataclass
+class ProjectConfig:
+    # None  → the `apis` key is absent  → "all your account APIs" (default).
+    # [...] → exactly these account APIs as server slugs; a scraper_id (UUID) is
+    #         also accepted on read ([] = no account APIs).
+    apis: Optional[List[str]] = None
+    marketplace: List[MarketplaceEntry] = field(default_factory=list)
+
+    @property
+    def all_account_mode(self) -> bool:
+        """True when the repo tracks ALL account APIs (apis key absent)."""
+        return self.apis is None
+
+    def account_desired(self, all_account_slugs: List[str]) -> List[str]:
+        """The account server-slugs this repo wants, given the full account set."""
+        return list(all_account_slugs) if self.apis is None else list(self.apis)
+
+
+class ProjectConfigError(ValueError):
+    """The consumer's committed ``[tool.parse]`` desired state is invalid."""
+
+
+# --------------------------------------------------------------------------- #
+# read
+# --------------------------------------------------------------------------- #
+
+def read_project_config(consumer_pyproject: Path) -> ProjectConfig:
+    """Parse ``[tool.parse]`` from the consumer pyproject.
+
+    A missing file/table means the backward-compatible all-account default.
+    Once ``[tool.parse]`` exists, malformed TOML or known fields fail closed:
+    silently widening a broken declaration to all-account can prune or generate
+    clients the user did not request.
+    """
+    try:
+        data = tomllib.loads(consumer_pyproject.read_text())
+    except FileNotFoundError:
+        return ProjectConfig()
+    except OSError as e:
+        raise ProjectConfigError(f"could not read {consumer_pyproject}: {e}") from e
+    except tomllib.TOMLDecodeError as e:
+        raise ProjectConfigError(f"invalid TOML in {consumer_pyproject}: {e}") from e
+
+    tool_tbl = data.get("tool") if isinstance(data, dict) else None
+    if tool_tbl is None:
+        return ProjectConfig()
+    if not isinstance(tool_tbl, dict):
+        raise ProjectConfigError("[tool] must be a table")
+    if "parse" not in tool_tbl:
+        return ProjectConfig()
+    parse_tbl = tool_tbl.get("parse")
+    if not isinstance(parse_tbl, dict):
+        raise ProjectConfigError("[tool.parse] must be a table")
+
+    known_table_fields = {"apis", "marketplace"}
+    _reject_unknown_fields(parse_tbl, known_table_fields, "tool.parse")
+
+    apis: Optional[List[str]] = None
+    if "apis" in parse_tbl:
+        raw = parse_tbl.get("apis")
+        # Entries are server slugs (a scraper_id UUID is also accepted) — both are
+        # plain strings, so no narrowing is needed here; the tolerant dual-read in
+        # `cli._apply_account_selection` resolves either form.
+        if not isinstance(raw, list):
+            raise ProjectConfigError("tool.parse.apis must be an array of non-empty strings")
+        if any(not isinstance(item, str) or not item for item in raw):
+            raise ProjectConfigError("tool.parse.apis must contain only non-empty strings")
+        apis = list(raw)
+
+    marketplace: List[MarketplaceEntry] = []
+    if "marketplace" in parse_tbl:
+        raw_mkt = parse_tbl.get("marketplace")
+        if not isinstance(raw_mkt, list):
+            raise ProjectConfigError("tool.parse.marketplace must be an array of tables")
+        seen_scraper_ids: Dict[str, tuple[int, Optional[int]]] = {}
+        for i, row in enumerate(raw_mkt):
+            where = f"tool.parse.marketplace[{i}]"
+            if not isinstance(row, dict):
+                raise ProjectConfigError(f"{where} must be a table")
+            known_row_fields = {"scraper_id", "slug", "version", "listing_id", "source_url"}
+            _reject_unknown_fields(row, known_row_fields, where)
+            sid, slug = row.get("scraper_id"), row.get("slug")
+            if not isinstance(sid, str) or not sid:
+                raise ProjectConfigError(f"{where}.scraper_id must be a non-empty string")
+            if not isinstance(slug, str) or not slug:
+                raise ProjectConfigError(f"{where}.slug must be a non-empty string")
+            ver = row.get("version")
+            if ver is not None and (
+                    not isinstance(ver, int) or isinstance(ver, bool) or ver < 1):
+                raise ProjectConfigError(f"{where}.version must be a positive integer")
+            sid_key = _identifier_key(sid)
+            if sid_key in seen_scraper_ids:
+                prior_index, prior_version = seen_scraper_ids[sid_key]
+                raise ProjectConfigError(
+                    f"{where}.scraper_id duplicates tool.parse.marketplace"
+                    f"[{prior_index}] for {sid!r} (versions {prior_version!r} and "
+                    f"{ver!r}); each canonical scraper_id must be declared once"
+                )
+            seen_scraper_ids[sid_key] = (i, ver)
+            listing_id = row.get("listing_id")
+            if listing_id is not None and not isinstance(listing_id, str):
+                raise ProjectConfigError(f"{where}.listing_id must be a string")
+            source_url = row.get("source_url")
+            if source_url is not None and not isinstance(source_url, str):
+                raise ProjectConfigError(f"{where}.source_url must be a string")
+            marketplace.append(MarketplaceEntry(
+                scraper_id=sid,
+                slug=slug,
+                version=ver,
+                listing_id=listing_id,
+                source_url=source_url,
+            ))
+    return ProjectConfig(apis=apis, marketplace=marketplace)
+
+
+# --------------------------------------------------------------------------- #
+# write (regenerate the table we own)
+# --------------------------------------------------------------------------- #
+
+def _toml_str(s: str) -> str:
+    """A TOML basic string. Slugs/uuids are tame, but source_url is freer —
+    JSON's string escapes are also valid TOML basic-string escapes."""
+    # json.dumps handles TOML-compatible escapes for C0 controls, quotes, and
+    # backslashes. JSON permits a raw DEL character while TOML does not.
+    return json.dumps(s, ensure_ascii=False).replace("\x7f", "\\u007f")
+
+
+def _reject_unknown_fields(table: dict, known: set, where: str) -> None:
+    """Fail closed on fields this pinned SDK does not understand.
+
+    The CLI owns and regenerates this table. Preserving arbitrary siblings would
+    require a complete lossless TOML editor and still could not distinguish a
+    future field from a destructive typo such as ``apiss``. A clear upgrade
+    error is smaller, deterministic, and cannot widen desired state.
+    """
+    common_typos = {
+        "api": "apis",
+        "marketpalce": "marketplace",
+        "scrapper_id": "scraper_id",
+        "scraperid": "scraper_id",
+        "versoin": "version",
+        "listng_id": "listing_id",
+        "soruce_url": "source_url",
+    }
+    canonical_by_case = {field.casefold(): field for field in known}
+    unknown = sorted(set(table) - known)
+    if not unknown:
+        return
+    details = []
+    for key in unknown:
+        suggestion = canonical_by_case.get(key.casefold())
+        if suggestion is None:
+            candidate = common_typos.get(key.casefold())
+            suggestion = candidate if candidate in known else None
+        details.append(
+            f"{where}.{key}" + (f" (did you mean {suggestion!r}?)" if suggestion else "")
+        )
+    raise ProjectConfigError(
+        "unsupported project configuration field(s): " + ", ".join(details)
+        + "; this project may require a newer parse-sdk — upgrade it before retrying"
+    )
+
+
+def render_parse_table(config: ProjectConfig) -> str:
+    """The full ``[tool.parse]`` block (+ any ``[[tool.parse.marketplace]]``
+    sub-tables). Trailing newline included."""
+    lines: List[str] = [
+        "# Managed by the parse CLI (`parse add` / `parse remove` / `parse sync`).",
+        "# Edit `apis` to curate which of your account APIs this repo syncs;",
+        "# an absent `apis` key means all of them.",
+        "[tool.parse]",
+    ]
+    if config.apis is not None:
+        if config.apis:
+            lines.append("apis = [")
+            for slug in config.apis:
+                lines.append(f"    {_toml_str(slug)},")
+            lines.append("]")
+        else:
+            lines.append("apis = []")
+    for m in config.marketplace:
+        lines.append("")
+        lines.append("[[tool.parse.marketplace]]")
+        lines.append(f"scraper_id = {_toml_str(m.scraper_id)}")
+        lines.append(f"slug = {_toml_str(m.slug)}")
+        if m.version is not None:
+            lines.append(f"version = {int(m.version)}")
+        if m.listing_id:
+            lines.append(f"listing_id = {_toml_str(m.listing_id)}")
+        if m.source_url:
+            lines.append(f"source_url = {_toml_str(m.source_url)}")
+    return "\n".join(lines) + "\n"
+
+
+def _strip_parse_tables(text: str) -> str:
+    """Remove the existing ``[tool.parse]`` / ``[tool.parse.*]`` /
+    ``[[tool.parse.*]]`` blocks (header line through the line before the next
+    table header or EOF), leaving everything else byte-for-byte."""
+    out: List[str] = []
+    skipping = False
+    header_re = re.compile(r"^\s*\[\[?\s*([^\]]+?)\s*\]\]?\s*(?:#.*)?$")
+    for line in text.splitlines(keepends=True):
+        m = header_re.match(line)
+        if m:
+            name = m.group(1)
+            skipping = name == "tool.parse" or name.startswith("tool.parse.")
+        if not skipping:
+            out.append(line)
+    return "".join(out)
+
+
+def write_project_config(consumer_pyproject: Path, config: ProjectConfig) -> None:
+    """Persist ``config`` into the consumer pyproject's ``[tool.parse]`` table,
+    regenerating only that table. Raises ValueError if the result wouldn't be
+    valid TOML (invariant: we never write a broken pyproject)."""
+    original = consumer_pyproject.read_text()
+    stripped = _strip_parse_tables(original).rstrip()
+    block = render_parse_table(config)
+    new = (stripped + "\n\n" + block) if stripped else block
+    try:
+        tomllib.loads(new)
+    except tomllib.TOMLDecodeError as e:  # pragma: no cover — defensive invariant
+        raise ValueError(f"refusing to write pyproject.toml — the [tool.parse] edit "
+                         f"would corrupt it ({e}).") from e
+    consumer_pyproject.write_text(new)