dgconvert 0.1.0__tar.gz

dgconvert-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+.pytest_cache/
+.ruff_cache/
+.vscode/

dgconvert-0.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+All notable changes to this project will be documented in this file. See [conventional commits](https://www.conventionalcommits.org/) for commit guidelines.
+
+- - -
+## 0.1.0 - 2026-08-19
+#### Features
+- (**cog**) add cocogitto changelog generation - (1b31be7) - ScriptAutomate, *Claude Sonnet 5*
+- add build/publish just recipes and trim the sdist - (0073681) - ScriptAutomate
+- add PyPI package metadata (MIT license, urls, classifiers) - (08e6afc) - ScriptAutomate
+- add body_snatchers module, sourced from docufig.seed.yaml - (f127c52) - ScriptAutomate
+- extract generic helper modules from dg-tgdp - (be68511) - ScriptAutomate, *Claude Sonnet 5*
+#### Documentation
+- remove references to sibling repos, make dgconvert standalone - (cfc6172) - ScriptAutomate
+- adopt helper-library architecture and drop nox-style runner - (dc1ca93) - ScriptAutomate, *Claude Sonnet 5*
+#### Miscellaneous Chores
+- drop authors from pyproject.toml - (dd2b421) - ScriptAutomate
+- scaffold python project with spec-kit, uv, justfile, and devcontainer - (e1fef62) - ScriptAutomate, *Claude Sonnet 5*
+#### Style
+- normalize justfile formatting via just --fmt - (2d3f732) - ScriptAutomate
+
+- - -
+
+Changelog generated by [cocogitto](https://github.com/cocogitto/cocogitto).

dgconvert-0.1.0/DESIGN.md

@@ -0,0 +1,239 @@
+# dgconvert design — a helper library, not a runner
+
+Status: extracted (2026-08-08) — the four generic modules plus the
+incremental-conversion driver described below now live in
+`dgconvert/src/dgconvert/`, per the extraction plan at the bottom of this
+document. Seed repos depend on `dgconvert` as a real dependency rather
+than owning their own copies. Originally drafted 2026-07-16 against a
+still-inline reference implementation. Supersedes an earlier
+fixed-pipeline architecture and an even earlier nox-style-runner draft
+of this document. The compatibility contract, language decision
+(Python, uv-managed), and verification strategy from that original plan
+carry over unchanged.
+
+## Terminology
+
+- **Garden** — a directory of notes (`notes/*.md`).
+- **Greenhouse** — a DocsGarden workspace rooted at `docufig.json`,
+  containing one or more gardens.
+- **Seed** — a pre-created garden, ready to be planted into a greenhouse.
+  A seed is described by its own `docufig.seed.json` (license,
+  topHierarchy, source provenance, bodySnatchers).
+- **Seedbank** — a registry of seeds (a separate, not-yet-built dgpkm
+  feature; not something dgconvert or a seed repo needs to know about).
+
+`dgconvert` produces **seeds**. See dgpkm's own documentation for the
+full terminology writeup.
+
+## Core idea
+
+Every seed repo owns its own conversion: its `docufig.seed.json`
+(declarative — license, topHierarchy, source repo info) plus a plain
+Python script that reads that config and drives the conversion
+(imperative — fetch, transform, write, verify). **dgconvert is not a
+task runner and does not discover or execute anything on a seed
+repo's behalf** — an earlier draft of this document proposed a nox-style
+`seedfile.py` + task-discovery model; that was rejected in favor of
+dgconvert being nothing more than a plain library that a seed's own
+script imports.
+
+This mirrors the reasoning that was already settled before dgconvert had
+any code: sources vary too widely (GitHub docs repos, MediaWiki, ebooks,
+CSV data files) for a fixed pipeline or task-discovery convention to fit
+all of them — a seed's own script is already the right level of control,
+and dgconvert's job is only to make that script short.
+
+## What a seed repo looks like
+
+| File / dir | Role | Owned by |
+|---|---|---|
+| `docufig.seed.json` | **What** the seed is: name, license, topHierarchy, source repo/owner info, bodySnatchers. dgpkm's schema; validated by `dgpkm doctor schema seed`. | seed maintainer, dgpkm-schema-shaped |
+| `src/<pkg>/convert.py` (or similar) | **How** it's built: fetch, transform, write, verify. Imports `dgconvert` for the parts that are the same across every seed. | seed maintainer |
+| `notes/*.md` | The output: the garden itself. | generated |
+
+The first real seed repo built against this pattern is dgconvert's
+reference implementation — its own conversion modules were the working
+prototype this library gets generalized from, not a consumer built
+against an already-finished dgconvert.
+
+## Library API surface
+
+Extracted 1:1 from a first seed's own generic modules (originally
+prototyped, working, with zero source-specific imports — extraction was
+a house-move, not a redesign):
+
+- **`dgconvert.frontmatter`** — single-line frontmatter emission and a
+  parser that mirrors dgpkm's own. Two verified constraints drive this:
+  dgpkm's frontmatter delimiter split (`strings.SplitN(content, "---",
+  3)` in Go) is **not line-anchored**, so a value containing the literal
+  substring `"---"` truncates the frontmatter block early — every
+  emitted value is sanitized to a single line with `"---"` replaced; and
+  dgpkm requires `id:` to be present and `created`/`updated` to be
+  epoch-ms integers. No YAML library is used — round-tripping through a
+  real YAML parser reintroduces exactly the failure mode this avoids
+  (folded scalars, auto-quoting) and can't guarantee output matches
+  dgpkm's naive line-based reader.
+- **`dgconvert.slugs`** — dotted-hierarchy slug joining and
+  wikilink/Dendron-link builders. Always **alias-after**
+  (`[[slug#anchor|Display]]`) — dgpkm cannot parse Dendron's alias-first
+  on-disk form.
+- **`dgconvert.links`** — markdown-link scanning and rewriting via a
+  caller-supplied resolver callback, plus `defeat_md_regex`: dgpkm's
+  backlinks extractor matches **any** `](....md)` or `](....md#anchor)`,
+  including full external URLs, and does not skip fenced code blocks —
+  a link to unconverted or external content that bare-ends in `.md`
+  gets a harmless query string appended (`?ref_type=tags`) to defeat the
+  regex, confirmed necessary against real converted content (several
+  files reference other projects' `CHANGELOG.md`/`README.md` by full
+  URL with no query string).
+- **`dgconvert.dgpkm`** — a `dgpkm` binary subprocess wrapper.
+  `dgpkm doctor backlinks` and `dgpkm doctor schema <type>` **always
+  exit 0**, even with findings — findings are only visible in
+  stdout/stderr text (`Found N broken link(s)`, `✗ ...`). This module
+  parses that text so a conversion script can fail loudly (non-zero
+  exit) when its output isn't doctor-clean.
+- **`dgconvert.incremental`** — the create/skip/update/delete driver,
+  extracted once a second, independent consumer needed the same shape.
+  State lives **in each note's frontmatter** (a `sourceFileHash` sha256
+  key), not a separate state file. Re-running after new upstream
+  source: unchanged hash → skip (byte-identical, `created`/`updated`
+  both preserved); changed hash → rewrite in place (same `id`, same
+  `created`, bumped `updated`); source gone → delete the note and
+  report it. Callers supply a per-item `build()` closure (called only
+  for new/changed items, never for a skip) returning `(frontmatter,
+  body, extra)`; source-specific concerns (index-note generation, a
+  source's own path→slug table) stay in the seed repo, only the loop
+  itself is generic.
+- **`dgconvert.body_snatchers`** — find/replace content transforms,
+  sourced directly from a seed's own `docufig.seed.yaml` (`bodySnatchers`
+  is a required field in dgpkm's own seed schema, not decorative), so a
+  seed's Python code never keeps a second, hand-maintained copy in sync
+  with that already-schema-validated manifest.
+
+## Seed-specific code stays in the seed repo
+
+Everything that only makes sense for one source format lives in the seed
+repo, never in dgconvert: a source's own index/manifest model, its own
+path→slug table, its attribution text, its kind-index-note builders have
+no dgconvert equivalent and shouldn't get one — a future MediaWiki or
+ebook seed will have an equally source-specific module of its own, built
+the same way, using the same generic library pieces above.
+
+## Non-Markdown sources: markitdown
+
+Planned dependency (not yet added — no seed has needed it yet):
+[`microsoft/markitdown`](https://github.com/microsoft/markitdown), for
+converting non-Markdown sources (PDFs, Office docs, HTML scrapes, etc.)
+into Markdown before the rest of the pipeline (frontmatter, slugs, link
+rewriting) applies. Kept as an optional extra (`dgconvert[markitdown]`)
+rather than a base dependency, since most seeds don't need it (e.g. one
+real seed handles its CSV files by fencing them as code blocks rather
+than converting them).
+
+## Bundling the `dgpkm` binary
+
+Open design question, not yet solved: `dgconvert.dgpkm` needs a `dgpkm`
+binary to shell out to. Today this is solved by an environment variable
+(`DGPKM_BIN`, falling back to `dgpkm` on `PATH`) and a documented
+limitation that no devcontainer bundles one, because dgpkm has no
+distributable releases yet.
+
+**Recommendation once dgpkm does cut releases:** a separate,
+platform-tagged PyPI package (e.g. `dgpkm-bin`) that vendors the compiled
+binary as wheel data — one wheel per platform, built in dgpkm's own
+release CI, the same pattern `ruff`/`uv` use for their own Rust binaries.
+`dgconvert` would depend on it, with resolution order `DGPKM_BIN` env var
+→ `dgpkm` on `PATH` → the bundled binary. This keeps dgconvert's own
+dependency footprint honest (it depends on a real published artifact, not
+a hand-rolled download-on-first-run step) and requires no changes to the
+`dgconvert.dgpkm` module's public interface — only its binary-discovery
+order gains a third fallback.
+
+## Dependencies
+
+Kept deliberately minimal. `pyyaml` is a base dependency:
+`frontmatter.emit_note`'s `extra` passthrough (arbitrary
+provenance/source fields a seed's own frontmatter model doesn't cover,
+e.g. a task-tracking source format's own metadata or a nested custom
+object) needs real YAML serialization to round-trip nested values
+correctly — dgpkm's own frontmatter reader is a real YAML parser too
+(`go.yaml.in/yaml/v4`, both directions), so this isn't working around a
+naive reader the way the known-field emitter still does; also used by
+`dgconvert.body_snatchers` to read a seed's own `docufig.seed.yaml`
+directly. Slugs, link rewriting, hashing, and subprocess handling remain
+stdlib-only. Planned additions, both as extras rather than base
+dependencies:
+
+- `markitdown` — non-Markdown source conversion (see above).
+- A future `dgpkm-bin` platform wheel (see above), once it exists.
+
+Dev dependencies: `pytest`, `ruff`.
+
+## Toolchain parity
+
+uv-managed, `.justfile` mirroring dgpkm's own
+(`build-devcontainer` gated on `USE_CONTAINER_DEV`,
+`sync`/`fmt`/`lint`/`test`/`check`, cocogitto conventional commits),
+`.devcontainer/` (Python base image, uv, just, cocogitto). Unlike seed
+repos, **dgconvert uses Spec Kit** (`.specify/`, this repo's `.claude/`
+skills) for its own development — seed repos deliberately don't, since
+they're conversion/data repos, not spec-driven feature work.
+
+## Extraction plan — done (2026-08-08)
+
+1. ~~Move the first seed's own generic modules into
+   `dgconvert/src/dgconvert/{frontmatter,slugs,links,dgpkm}.py`
+   verbatim~~ — done, plus one real addition: `frontmatter.emit_note`
+   gained an optional `extra` parameter (arbitrary passthrough YAML,
+   sorted-key, real-YAML-serialized) that the first seed doesn't use but
+   a second, independent consumer needs for fields with no dgpkm-native
+   equivalent. `dgpkm.verify`'s schema check also gained an off switch
+   (`check_schema=None`) since not every `dgconvert` consumer is itself
+   a seed with a `docufig.seed.json` to validate.
+2. ~~Point the first seed's `pyproject.toml` at `dgconvert` as a
+   dependency~~ — done (a real dependency, editable during local
+   development). Verified behavior-preserving: its own source-specific
+   test suite (the tests that didn't move to `dgconvert`) still passes,
+   and a real re-run against its already-converted `notes/` garden
+   produces a byte-identical `git diff` (confirmed against the
+   pre-refactor code as a baseline, not just the tests).
+3. ~~Extract `run_convert`'s incremental-diff shape into
+   `dgconvert.incremental`~~ — done, once a second, independent consumer
+   needed the same create/skip/update/delete-by-hash shape.
+   Source-specific concerns (index-note generation, a source's own
+   path→slug table) stayed in that seed's own repo as originally
+   planned; only the loop itself (a per-item `build()` closure plus
+   id/created/updated bookkeeping) is generic.
+4. ~~Write the corresponding `dgconvert` test suite by moving~~ — done
+   (`tests/test_{frontmatter,slugs,links}.py`), plus a new
+   `tests/test_incremental.py` for the newly-generic driver (the first
+   seed's own incremental test stayed in place there, since it still
+   exercises source-specific behavior through the shared driver).
+5. A `specs/` feature spec via `/speckit-specify` was **not** written for
+   this extraction — it happened as part of a larger, time-boxed
+   migration task rather than dgconvert's own spec-driven workflow.
+   Worth backfilling if dgconvert's process requires it retroactively.
+6. ~~Extract `apply_body_snatchers` into `dgconvert.body_snatchers`,
+   sourced from `docufig.seed.yaml` directly~~ — done, once a second,
+   independent consumer needed the identical shape a first seed already
+   had. Went one step further than the other extractions: rather than
+   just deduplicating the apply function, `load()` reads a seed's
+   `bodySnatchers` directly from its already-schema-validated
+   `docufig.seed.yaml`, eliminating a real hand-sync bug class (a
+   seed's Python-side transform table drifting out of sync with its own
+   manifest, seen in practice) instead of just moving where the
+   duplication lived.
+
+## Open questions
+
+1. ~~Exact package/module names for the extracted pieces~~ — settled:
+   `dgconvert.frontmatter`, `dgconvert.slugs`, `dgconvert.links`,
+   `dgconvert.dgpkm`, `dgconvert.incremental`, `dgconvert.body_snatchers`.
+2. Whether `dgconvert.dgpkm`'s binary-discovery fallback chain should be
+   configurable per-project or hardcoded to the `DGPKM_BIN` → `PATH` →
+   bundled order.
+3. Whether the incremental-diff pattern (state-in-frontmatter,
+   create/skip/update/delete) generalizes cleanly to a source that isn't
+   a flat file tree (e.g. a paginated API), or needs a second, distinct
+   pattern for that case — genuinely unknown until a seed of that shape
+   exists.

dgconvert-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ScriptAutomate
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dgconvert-0.1.0/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.5
+Name: dgconvert
+Version: 0.1.0
+Summary: Helper library for building dgpkm-compatible seeds (frontmatter, slugs, link rewriting, dgpkm doctor verification)
+Project-URL: Homepage, https://github.com/ScriptAutomate/dgconvert
+Project-URL: Repository, https://github.com/ScriptAutomate/dgconvert
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.12
+Requires-Dist: pyyaml>=6
+Description-Content-Type: text/markdown
+
+# dgconvert
+
+A small Python **helper library** for building
+[dgpkm](https://github.com/ScriptAutomate/dgpkm)-compatible **seeds**
+(pre-created gardens, ready to plant into a greenhouse).
+
+`dgconvert` is not a task runner. Each seed repo owns its own
+`docufig.seed.json` and its own plain-Python conversion script;
+`dgconvert` supplies the pieces every seed needs regardless of source
+format — dotted-slug file naming, single-line frontmatter with stable
+ids, markdown-link → dgpkm-wikilink rewriting, and a wrapper that
+verifies output with `dgpkm doctor`.
+
+See `DESIGN.md` for the full architecture and the verified
+dgpkm-compatibility constraints it's built against. The library was
+generalized out of a first seed's own inline conversion code once a
+second, independent seed needed the same pieces.
+
+## Installing
+
+```bash
+uv add dgconvert
+# or
+pip install dgconvert
+```
+
+## Development
+
+Managed with [uv](https://docs.astral.sh/uv/) and [just](https://just.systems/),
+using [Spec Kit](https://github.com/github/spec-kit) for feature specs
+(`specs/`, `.specify/`) — unlike seed repos, which don't use Spec Kit:
+
+```bash
+just            # list tasks
+just sync       # uv sync
+just test       # uv run pytest
+just check      # format + lint
+```
+
+Container-based development mirrors dgpkm: set `USE_CONTAINER_DEV` to
+`podman`, `docker`, or `container`, then `just build-devcontainer` once and
+every build/test recipe runs inside the dev container automatically.
+
+## License
+
+[MIT](LICENSE)

dgconvert-0.1.0/README.md

@@ -0,0 +1,46 @@
+# dgconvert
+
+A small Python **helper library** for building
+[dgpkm](https://github.com/ScriptAutomate/dgpkm)-compatible **seeds**
+(pre-created gardens, ready to plant into a greenhouse).
+
+`dgconvert` is not a task runner. Each seed repo owns its own
+`docufig.seed.json` and its own plain-Python conversion script;
+`dgconvert` supplies the pieces every seed needs regardless of source
+format — dotted-slug file naming, single-line frontmatter with stable
+ids, markdown-link → dgpkm-wikilink rewriting, and a wrapper that
+verifies output with `dgpkm doctor`.
+
+See `DESIGN.md` for the full architecture and the verified
+dgpkm-compatibility constraints it's built against. The library was
+generalized out of a first seed's own inline conversion code once a
+second, independent seed needed the same pieces.
+
+## Installing
+
+```bash
+uv add dgconvert
+# or
+pip install dgconvert
+```
+
+## Development
+
+Managed with [uv](https://docs.astral.sh/uv/) and [just](https://just.systems/),
+using [Spec Kit](https://github.com/github/spec-kit) for feature specs
+(`specs/`, `.specify/`) — unlike seed repos, which don't use Spec Kit:
+
+```bash
+just            # list tasks
+just sync       # uv sync
+just test       # uv run pytest
+just check      # format + lint
+```
+
+Container-based development mirrors dgpkm: set `USE_CONTAINER_DEV` to
+`podman`, `docker`, or `container`, then `just build-devcontainer` once and
+every build/test recipe runs inside the dev container automatically.
+
+## License
+
+[MIT](LICENSE)

dgconvert-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[project]
+name = "dgconvert"
+version = "0.1.0"
+description = "Helper library for building dgpkm-compatible seeds (frontmatter, slugs, link rewriting, dgpkm doctor verification)"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "pyyaml>=6",
+]
+
+[project.urls]
+Homepage = "https://github.com/ScriptAutomate/dgconvert"
+Repository = "https://github.com/ScriptAutomate/dgconvert"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "ruff>=0.8",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/dgconvert"]
+
+[tool.hatch.build.targets.sdist]
+# Hatchling's sdist default is "everything git-tracks" -- excludes the
+# repo's own dev/agent tooling (Claude Code skills, Spec Kit scaffolding,
+# devcontainer, justfile) that a consumer installing this library from
+# PyPI has no use for. The wheel (tool.hatch.build.targets.wheel above)
+# was already correctly scoped to just src/dgconvert/ without any of
+# this needing to be said twice.
+exclude = [
+    ".claude",
+    ".specify",
+    ".devcontainer",
+    ".justfile",
+    "cog.toml",
+]
+
+[tool.ruff]
+src = ["src", "tests"]
+line-length = 100
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

dgconvert-0.1.0/src/dgconvert/__init__.py

@@ -0,0 +1,5 @@
+"""dgconvert — a helper library for building dgpkm-compatible seeds."""
+
+from importlib.metadata import version as _version
+
+__version__ = _version("dgconvert")

dgconvert-0.1.0/src/dgconvert/body_snatchers.py

@@ -0,0 +1,39 @@
+"""Body-snatcher (find/replace) content transforms, sourced from a
+seed's own docufig.seed.yaml.
+
+`bodySnatchers` is a required field in dgpkm's own seed config JSON
+Schema (validated by `dgpkm doctor schema seed`), not a decorative
+one -- so it's read directly from that already-schema-validated
+manifest rather than requiring a seed's own Python code to keep a
+second, hand-maintained copy in sync (a real, seen-in-practice failure
+mode: a seed's manifest drifting out of sync with its own Python-side
+transform table after a code-only change, caught only by a direct
+question, not by any tooling).
+
+Generalized out of two seeds' identical apply_body_snatchers once a
+second seed needed the exact same shape a first one already had --
+the same "second consumer" trigger this library's other modules were
+each generalized under.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+
+def load(seed_config_path: Path) -> tuple[tuple[str, str], ...]:
+    """Reads bodySnatchers from a seed's docufig.seed.yaml. Each entry's
+    {find, replace} shape matches dgpkm's own seed config JSON Schema
+    exactly. A missing bodySnatchers key (defensive -- the schema
+    requires it, but this shouldn't hard-fail a caller that hasn't
+    validated yet) behaves like an empty list."""
+    data = yaml.safe_load(seed_config_path.read_text(encoding="utf-8")) or {}
+    return tuple((s["find"], s["replace"]) for s in data.get("bodySnatchers", []))
+
+
+def apply(text: str, snatchers: tuple[tuple[str, str], ...]) -> str:
+    for find, replace in snatchers:
+        text = text.replace(find, replace)
+    return text

dgconvert-0.1.0/src/dgconvert/dgpkm.py

@@ -0,0 +1,62 @@
+"""Wraps the `dgpkm` binary for verification.
+
+`dgpkm doctor backlinks` and `dgpkm doctor schema <type>` always exit 0,
+even when they report findings -- findings are only visible in
+stdout/stderr text ("Found N broken link(s)", "✗ ..."). This module
+parses that text so the converter can fail loudly (non-zero exit) when a
+conversion isn't doctor-clean, which dgpkm itself won't do for you.
+
+Generalized beyond its original prototype in one way: `verify`'s schema
+check is now optional (`check_schema=None` skips it) since not every
+consumer has a `docufig.seed.json` to validate -- a standalone
+converter tool can write straight into a greenhouse's root garden,
+not a separate seed.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from pathlib import Path
+
+
+def dgpkm_bin() -> str:
+    return os.environ.get("DGPKM_BIN", "dgpkm")
+
+
+def _run(args: list[str], cwd: Path) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        [dgpkm_bin(), *args],
+        cwd=cwd,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+
+def verify(root: Path, *, check_schema: str | None = "seed") -> list[str]:
+    """Run dgpkm doctor checks against the garden at `root`. Returns a list
+    of human-readable problem descriptions (empty = clean).
+
+    `check_schema` names the config type to pass to `dgpkm doctor schema
+    <type>` (e.g. "seed" for a `docufig.seed.json`); pass None to skip
+    that check entirely for a tool that has no such config file.
+    """
+    problems: list[str] = []
+
+    backlinks = _run(["doctor", "backlinks"], root)
+    if backlinks.returncode != 0:
+        problems.append(f"dgpkm doctor backlinks failed to run:\n{backlinks.stderr}")
+    elif "All backlinks are valid" not in backlinks.stdout:
+        problems.append(f"backlinks: broken links found\n{backlinks.stdout}")
+
+    if check_schema:
+        schema = _run(["doctor", "schema", check_schema], root)
+        if schema.returncode != 0:
+            problems.append(f"dgpkm doctor schema {check_schema} failed to run:\n{schema.stderr}")
+        elif "✓" not in schema.stdout or "✗" in schema.stderr:
+            problems.append(
+                f"{check_schema} config schema invalid:\n{schema.stdout}{schema.stderr}"
+            )
+
+    return problems