doorstop-vscode-server 0.1.0__tar.gz

doorstop_vscode_server-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2026 Simon Walbrun
+
+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.

doorstop_vscode_server-0.1.0/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: doorstop-vscode-server
+Version: 0.1.0
+Summary: FastAPI server wrapping the Doorstop Python API for the Doorstop VS Code extension
+Author: Simon Walbrun
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/simonwalbrun-lab/doorstop-vscode-server
+Project-URL: Issues, https://github.com/simonwalbrun-lab/doorstop-vscode-server/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: doorstop>=3.0
+Requires-Dist: fastapi>=0.115
+Requires-Dist: uvicorn[standard]>=0.30
+Requires-Dist: pydantic>=2
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Provides-Extra: build
+Requires-Dist: build; extra == "build"
+Requires-Dist: twine; extra == "build"
+Dynamic: license-file
+
+# doorstop-vscode-server
+
+A small FastAPI server that wraps the [Doorstop](https://pypi.org/project/doorstop/) Python API directly (instead of shelling out to the `doorstop` CLI). It is designed to serve exactly one client — the Doorstop VS Code extension — and answers requests strictly one at a time; there is no concurrent request handling.
+
+## Install (editable, for development)
+
+```bash
+pip install -e .[dev]
+```
+
+## Run
+
+```bash
+python -m doorstop_server --project <path-to-doorstop-project-root> --host 127.0.0.1 --port 7867
+```
+
+or, after installing:
+
+```bash
+doorstop-vscode-server --project <path-to-doorstop-project-root> --host 127.0.0.1 --port 7867
+```
+
+## API
+
+See `src/doorstop_server/routers/` for the endpoint implementations. `GET /health` is the only route that is not serialized behind the request lock.
+
+## Tests
+
+The test suite exercises the real FastAPI app against a temporary Doorstop project (no mocking of Doorstop itself), so it doubles as a pinned-down contract for the HTTP interface — every request/response shape, status code, and error format a test asserts on is something the extension can rely on.
+
+```bash
+pip install -e .[dev]
+pytest
+```
+
+- `tests/conftest.py` — shared fixtures (`client`, `project_root`, `document`) and a `set_item_text` helper for mutating an item directly via the Doorstop API (bypassing the server) to simulate out-of-band edits.
+- `tests/test_serialization.py` — proves the one-request-at-a-time guarantee black-box: fires concurrent `/items` calls and checks for zero UID collisions/gaps, rather than inspecting the lock directly.
+- `tests/test_errors.py` — pins down the structured `{"error": {"code", "message"}}` shape for both expected (`DoorstopError`) and unexpected exceptions.

doorstop_vscode_server-0.1.0/README.md

@@ -0,0 +1,38 @@
+# doorstop-vscode-server
+
+A small FastAPI server that wraps the [Doorstop](https://pypi.org/project/doorstop/) Python API directly (instead of shelling out to the `doorstop` CLI). It is designed to serve exactly one client — the Doorstop VS Code extension — and answers requests strictly one at a time; there is no concurrent request handling.
+
+## Install (editable, for development)
+
+```bash
+pip install -e .[dev]
+```
+
+## Run
+
+```bash
+python -m doorstop_server --project <path-to-doorstop-project-root> --host 127.0.0.1 --port 7867
+```
+
+or, after installing:
+
+```bash
+doorstop-vscode-server --project <path-to-doorstop-project-root> --host 127.0.0.1 --port 7867
+```
+
+## API
+
+See `src/doorstop_server/routers/` for the endpoint implementations. `GET /health` is the only route that is not serialized behind the request lock.
+
+## Tests
+
+The test suite exercises the real FastAPI app against a temporary Doorstop project (no mocking of Doorstop itself), so it doubles as a pinned-down contract for the HTTP interface — every request/response shape, status code, and error format a test asserts on is something the extension can rely on.
+
+```bash
+pip install -e .[dev]
+pytest
+```
+
+- `tests/conftest.py` — shared fixtures (`client`, `project_root`, `document`) and a `set_item_text` helper for mutating an item directly via the Doorstop API (bypassing the server) to simulate out-of-band edits.
+- `tests/test_serialization.py` — proves the one-request-at-a-time guarantee black-box: fires concurrent `/items` calls and checks for zero UID collisions/gaps, rather than inspecting the lock directly.
+- `tests/test_errors.py` — pins down the structured `{"error": {"code", "message"}}` shape for both expected (`DoorstopError`) and unexpected exceptions.

doorstop_vscode_server-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[project]
+name = "doorstop-vscode-server"
+version = "0.1.0"
+authors = [
+  { name="Simon Walbrun" },
+]
+description = "FastAPI server wrapping the Doorstop Python API for the Doorstop VS Code extension"
+readme = "README.md"
+requires-python = ">=3.9"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
+
+
+dependencies = [
+    "doorstop>=3.0",
+    "fastapi>=0.115",
+    "uvicorn[standard]>=0.30",
+    "pydantic>=2",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "httpx>=0.27"]
+build = ["build", "twine"]
+
+[project.scripts]
+doorstop-vscode-server = "doorstop_server.cli:main"
+
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+license = {text = "MIT"}
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+]
+
+[project.urls]
+Homepage = "https://github.com/simonwalbrun-lab/doorstop-vscode-server"
+Issues = "https://github.com/simonwalbrun-lab/doorstop-vscode-server/issues"

doorstop_vscode_server-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

doorstop_vscode_server-0.1.0/src/doorstop_server/__init__.py

@@ -0,0 +1 @@
+"""FastAPI server wrapping the Doorstop Python API."""

doorstop_vscode_server-0.1.0/src/doorstop_server/__main__.py

@@ -0,0 +1,4 @@
+from doorstop_server.cli import main
+
+if __name__ == "__main__":
+    main()

doorstop_vscode_server-0.1.0/src/doorstop_server/app.py

@@ -0,0 +1,22 @@
+from fastapi import FastAPI
+
+from doorstop_server.config import Settings
+from doorstop_server.errors import register_exception_handlers
+from doorstop_server.lock import SerializeRequestsMiddleware
+from doorstop_server.routers import documents, health, items, review, tree
+
+
+def create_app(settings: Settings) -> FastAPI:
+    app = FastAPI(title="doorstop-vscode-server")
+    app.state.settings = settings
+
+    app.add_middleware(SerializeRequestsMiddleware)
+    register_exception_handlers(app)
+
+    app.include_router(health.router)
+    app.include_router(documents.router)
+    app.include_router(items.router)
+    app.include_router(review.router)
+    app.include_router(tree.router)
+
+    return app

doorstop_vscode_server-0.1.0/src/doorstop_server/cli.py

@@ -0,0 +1,27 @@
+import argparse
+
+import uvicorn
+
+from doorstop_server.app import create_app
+from doorstop_server.config import Settings
+
+
+def parse_args(argv=None) -> Settings:
+    parser = argparse.ArgumentParser(prog="doorstop-vscode-server")
+    parser.add_argument("--project", required=True, help="path to the root of the Doorstop project")
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", type=int, default=7867)
+    args = parser.parse_args(argv)
+    return Settings(project_root=args.project, host=args.host, port=args.port)
+
+
+def main(argv=None) -> None:
+    settings = parse_args(argv)
+    app = create_app(settings)
+    # workers=1, no reload: exactly one process, one event loop -- required for
+    # the request-serialization guarantee in lock.py to hold.
+    uvicorn.run(app, host=settings.host, port=settings.port, workers=1, reload=False)
+
+
+if __name__ == "__main__":
+    main()

doorstop_vscode_server-0.1.0/src/doorstop_server/config.py

@@ -0,0 +1,8 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Settings:
+    project_root: str
+    host: str
+    port: int

doorstop_vscode_server-0.1.0/src/doorstop_server/deps.py

@@ -0,0 +1,13 @@
+import doorstop
+from fastapi import Request
+
+from doorstop_server.config import Settings
+from doorstop_server.doorstop_tree import load_tree
+
+
+def get_settings(request: Request) -> Settings:
+    return request.app.state.settings
+
+
+def get_tree(request: Request) -> doorstop.Tree:
+    return load_tree(get_settings(request))

doorstop_vscode_server-0.1.0/src/doorstop_server/doorstop_tree.py

@@ -0,0 +1,20 @@
+import doorstop
+
+from doorstop_server.config import Settings
+
+
+def load_tree(settings: Settings) -> doorstop.Tree:
+    """Build a fresh Tree from disk.
+
+    Rebuilt on every request rather than cached: the user can hand-edit item
+    files in VS Code between two server calls, and a cached tree would
+    silently miss or clobber those edits. ``request_next_number=None`` is the
+    ``--force`` equivalent the CLI uses to skip Doorstop's own numbering
+    server -- safe here because this server is the only process ever
+    mutating the project and every request is fully serialized.
+    """
+    return doorstop.build(
+        cwd=settings.project_root,
+        root=settings.project_root,
+        request_next_number=None,
+    )

doorstop_vscode_server-0.1.0/src/doorstop_server/errors.py

@@ -0,0 +1,34 @@
+from doorstop.common import DoorstopError
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+
+
+class DoorstopApiError(Exception):
+    """A request-level error raised by a route handler (bad input, not found, ...)."""
+
+    def __init__(self, status_code: int, code: str, message: str):
+        super().__init__(message)
+        self.status_code = status_code
+        self.code = code
+        self.message = message
+
+
+def _error_response(status_code: int, code: str, message: str) -> JSONResponse:
+    return JSONResponse(
+        status_code=status_code,
+        content={"error": {"code": code, "message": message}},
+    )
+
+
+def register_exception_handlers(app: FastAPI) -> None:
+    @app.exception_handler(DoorstopApiError)
+    async def handle_api_error(_request: Request, exc: DoorstopApiError) -> JSONResponse:
+        return _error_response(exc.status_code, exc.code, exc.message)
+
+    @app.exception_handler(DoorstopError)
+    async def handle_doorstop_error(_request: Request, exc: DoorstopError) -> JSONResponse:
+        return _error_response(400, "DOORSTOP_ERROR", str(exc))
+
+    @app.exception_handler(Exception)
+    async def handle_unexpected_error(_request: Request, exc: Exception) -> JSONResponse:
+        return _error_response(500, "INTERNAL_ERROR", str(exc))

doorstop_vscode_server-0.1.0/src/doorstop_server/lock.py

@@ -0,0 +1,34 @@
+import asyncio
+
+from starlette.types import ASGIApp, Receive, Scope, Send
+
+_UNLOCKED_PATHS = {"/health"}
+
+
+class SerializeRequestsMiddleware:
+    """Ensures the app answers exactly one request at a time (except /health).
+
+    Implemented as a bare ASGI middleware -- not `@app.middleware("http")`
+    (Starlette's BaseHTTPMiddleware) -- because BaseHTTPMiddleware runs the
+    downstream app inside a separate anyio task/stream that our
+    @app.exception_handler() registrations cannot see through: an unexpected
+    exception raised in a route would bypass the structured {"error": ...}
+    response entirely and blow past this middleware as a raw exception. A plain
+    ASGI middleware just awaits the inner app directly, so by the time control
+    returns here any exception has already been turned into a normal response.
+
+    The lock is created per middleware instance (i.e. per app / per
+    create_app() call), not as a module-level global, so it's always bound to
+    whatever event loop first serves that app.
+    """
+
+    def __init__(self, app: ASGIApp) -> None:
+        self.app = app
+        self.lock = asyncio.Lock()
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http" or scope["path"] in _UNLOCKED_PATHS:
+            await self.app(scope, receive, send)
+            return
+        async with self.lock:
+            await self.app(scope, receive, send)

doorstop_vscode_server-0.1.0/src/doorstop_server/routers/documents.py

@@ -0,0 +1,100 @@
+from pathlib import Path
+
+from doorstop.core import exporter, importer, publisher
+from fastapi import APIRouter, Depends
+
+from doorstop_server.deps import get_tree
+from doorstop_server.errors import DoorstopApiError
+from doorstop_server.schemas import (
+    AddItemRequest,
+    CreateDocumentRequest,
+    DocumentResponse,
+    ExportRequest,
+    ExportResponse,
+    ImportRequest,
+    ItemResponse,
+    PublishRequest,
+    PublishResponse,
+    ReorderIndexResponse,
+    ReorderRequest,
+    ReorderResponse,
+)
+
+router = APIRouter(prefix="/documents")
+
+_EXPORT_EXTENSIONS = {"yaml": ".yml", "csv": ".csv", "tsv": ".tsv", "xlsx": ".xlsx"}
+_PUBLISH_EXTENSIONS = {"markdown": ".md", "html": ".html", "latex": ".tex"}
+
+
+@router.post("", response_model=DocumentResponse)
+async def create_document(body: CreateDocumentRequest, tree=Depends(get_tree)) -> DocumentResponse:
+    document = tree.create_document(
+        body.path,
+        body.prefix,
+        sep=body.separator,
+        digits=body.digits,
+        parent=body.parentPrefix,
+        itemformat=body.itemFormat,
+    )
+    return DocumentResponse(prefix=str(document.prefix), path=document.path)
+
+
+@router.post("/{prefix}/items", response_model=ItemResponse)
+async def add_item(prefix: str, body: AddItemRequest, tree=Depends(get_tree)) -> ItemResponse:
+    document = tree.find_document(prefix)
+    item = document.add_item(level=body.level)
+    return ItemResponse(uid=str(item.uid), path=item.path, level=str(item.level))
+
+
+@router.post("/{prefix}/reorder/index", response_model=ReorderIndexResponse)
+async def ensure_reorder_index(prefix: str, tree=Depends(get_tree)) -> ReorderIndexResponse:
+    document = tree.find_document(prefix)
+    if not document.index:
+        document.index = True
+    return ReorderIndexResponse(prefix=prefix, indexPath=document.index)
+
+
+@router.delete("/{prefix}/reorder/index", status_code=204)
+async def discard_reorder_index(prefix: str, tree=Depends(get_tree)) -> None:
+    document = tree.find_document(prefix)
+    del document.index
+
+
+@router.post("/{prefix}/reorder", response_model=ReorderResponse)
+async def reorder_document(prefix: str, body: ReorderRequest, tree=Depends(get_tree)) -> ReorderResponse:
+    document = tree.find_document(prefix)
+    if body.mode == "auto":
+        document.reorder(manual=False)
+    else:
+        if not document.index:
+            raise DoorstopApiError(
+                409,
+                "NO_REORDER_INDEX",
+                "No index file to reorder from -- call POST /documents/{prefix}/reorder/index first.",
+            )
+        document.reorder(manual=True, automatic=False)
+    return ReorderResponse(prefix=prefix, mode=body.mode)
+
+
+@router.post("/{prefix}/import", response_model=DocumentResponse)
+async def import_into_document(prefix: str, body: ImportRequest, tree=Depends(get_tree)) -> DocumentResponse:
+    document = tree.find_document(prefix)
+    ext = Path(body.sourcePath).suffix
+    importer.import_file(body.sourcePath, document, ext)
+    return DocumentResponse(prefix=str(document.prefix), path=document.path)
+
+
+@router.post("/{prefix}/export", response_model=ExportResponse)
+async def export_document(prefix: str, body: ExportRequest, tree=Depends(get_tree)) -> ExportResponse:
+    document = tree.find_document(prefix)
+    ext = _EXPORT_EXTENSIONS[body.format]
+    path = exporter.export(document, body.destinationPath, ext=ext)
+    return ExportResponse(path=path or body.destinationPath)
+
+
+@router.post("/{prefix}/publish", response_model=PublishResponse)
+async def publish_document(prefix: str, body: PublishRequest, tree=Depends(get_tree)) -> PublishResponse:
+    document = tree.find_document(prefix)
+    ext = _PUBLISH_EXTENSIONS[body.format]
+    path = publisher.publish(document, body.destinationPath, ext=ext)
+    return PublishResponse(path=path or body.destinationPath)

doorstop_vscode_server-0.1.0/src/doorstop_server/routers/health.py

@@ -0,0 +1,11 @@
+from fastapi import APIRouter, Request
+
+from doorstop_server.schemas import HealthResponse
+
+router = APIRouter()
+
+
+@router.get("/health", response_model=HealthResponse)
+async def health(request: Request) -> HealthResponse:
+    settings = request.app.state.settings
+    return HealthResponse(status="ok", projectRoot=settings.project_root)

doorstop_vscode_server-0.1.0/src/doorstop_server/routers/items.py

@@ -0,0 +1,18 @@
+from fastapi import APIRouter, Depends, Response
+
+from doorstop_server.deps import get_tree
+from doorstop_server.schemas import LinkRequest, LinkResponse
+
+router = APIRouter(prefix="/items")
+
+
+@router.post("/{child_uid}/links", response_model=LinkResponse)
+async def link_item(child_uid: str, body: LinkRequest, tree=Depends(get_tree)) -> LinkResponse:
+    child, parent = tree.link_items(child_uid, body.parentUid)
+    return LinkResponse(child=str(child.uid), parent=str(parent.uid))
+
+
+@router.delete("/{child_uid}/links/{parent_uid}", status_code=204)
+async def unlink_item(child_uid: str, parent_uid: str, tree=Depends(get_tree)) -> Response:
+    tree.unlink_items(child_uid, parent_uid)
+    return Response(status_code=204)

doorstop_vscode_server-0.1.0/src/doorstop_server/routers/review.py

@@ -0,0 +1,41 @@
+from typing import Iterator, Optional
+
+from doorstop.core.item import Item
+from doorstop.core.tree import Tree
+from fastapi import APIRouter, Depends
+
+from doorstop_server.deps import get_tree
+from doorstop_server.errors import DoorstopApiError
+from doorstop_server.schemas import ReviewClearRequest
+
+router = APIRouter()
+
+
+def _iter_items(tree: Tree, scope: str, target: Optional[str]) -> Iterator[Item]:
+    """Resolve {scope, target} to items, mirroring doorstop's own CLI disambiguation."""
+    if scope == "all":
+        for document in tree:
+            yield from document
+        return
+    if not target:
+        raise DoorstopApiError(422, "TARGET_REQUIRED", "target is required unless scope is 'all'.")
+    if scope == "document":
+        document = tree.find_document(target)
+        yield from document
+        return
+    yield tree.find_item(target)
+
+
+@router.post("/review", status_code=204)
+async def review_items(body: ReviewClearRequest, tree=Depends(get_tree)) -> None:
+    for item in _iter_items(tree, body.scope, body.target):
+        item.review()
+
+
+@router.post("/clear", status_code=204)
+async def clear_items(body: ReviewClearRequest, tree=Depends(get_tree)) -> None:
+    if body.parents:
+        for parent_uid in body.parents:
+            tree.find_item(parent_uid)
+    for item in _iter_items(tree, body.scope, body.target):
+        item.clear(parents=body.parents)

doorstop_vscode_server-0.1.0/src/doorstop_server/routers/tree.py

@@ -0,0 +1,53 @@
+from doorstop.common import DoorstopError
+from fastapi import APIRouter, Depends
+
+from doorstop_server.deps import get_tree
+from doorstop_server.schemas import DocumentNode, ItemNode, LinkInfo, TreeResponse
+
+router = APIRouter()
+
+
+def _item_links(item, tree) -> list[LinkInfo]:
+    links = []
+    for uid in item.links:
+        try:
+            parent = tree.find_item(uid)
+            suspect = uid.stamp != parent.stamp()
+        except DoorstopError:
+            # Dangling/renamed parent UID - treat as suspect rather than failing the request.
+            suspect = True
+        links.append(LinkInfo(uid=str(uid), suspect=suspect))
+    return links
+
+
+@router.get("/tree", response_model=TreeResponse)
+async def get_tree_structure(tree=Depends(get_tree)) -> TreeResponse:
+    tree.load()
+    documents = [
+        DocumentNode(
+            prefix=str(document.prefix),
+            markerPath=document.config,
+            parentPrefix=document.parent or None,
+            digits=document.digits,
+            separator=document.sep,
+            itemFormat=str(document.itemformat) if document.itemformat else None,
+            items=[
+                ItemNode(
+                    uid=str(item.uid),
+                    path=item.path,
+                    level=str(item.level),
+                    header=str(item.header) if item.header else None,
+                    text=str(item.text) if item.text else None,
+                    active=item.active,
+                    normative=item.normative,
+                    derived=item.derived,
+                    reviewed=item.reviewed,
+                    cleared=item.cleared,
+                    links=_item_links(item, tree),
+                )
+                for item in document
+            ],
+        )
+        for document in tree
+    ]
+    return TreeResponse(documents=documents)