documentation-engine 0.3.0__tar.gz → 0.3.1__tar.gz

documentation_engine-0.3.1/.github/workflows/ci.yml

@@ -0,0 +1,142 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+env:
+  TMPDIR: /tmp
+  TMP: /tmp
+  TEMP: /tmp
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.12"
+
+      - name: Run pytest
+        run: uv run pytest
+
+      - name: Run ruff
+        run: uv run ruff check .
+
+      - name: Verify lockfile is current
+        run: uv lock --check
+
+      - name: Installed CLI smoke test
+        run: ./scripts/installed_cli_smoke.sh
+
+      # The smoke test builds and installs a wheel only. The release workflow
+      # uploads a wheel *and* an sdist, and an index rejects a distribution
+      # whose metadata or long description does not render. Check both
+      # artifacts here rather than during an irreversible upload.
+      - name: Build and check both distributions
+        run: |
+          dist_dir="$(mktemp -d)/dist"
+          uv build --out-dir "$dist_dir"
+          version="$(uv run python -c 'import docsystem; print(docsystem.__version__)')"
+          test -f "$dist_dir/documentation_engine-${version}-py3-none-any.whl"
+          test -f "$dist_dir/documentation_engine-${version}.tar.gz"
+          uvx --from 'twine>=6,<7' twine check --strict "$dist_dir"/*
+
+      # Dogfooding: walk the documented adoption sequence end-to-end against
+      # the public example profile, on a scratch copy so the fixture stays
+      # byte-identical in the repository.
+      - name: Example profile adoption walkthrough
+        run: |
+          profile="$(mktemp -d)/profile"
+          cp -r examples/generic-adopter "$profile"
+          uv run python -m docsystem readiness "$profile" --json
+          uv run python -m docsystem migrate "$profile" --apply
+          uv run python -m docsystem index "$profile" --write
+          uv run python -m docsystem readiness "$profile" --json
+          uv run python -m docsystem context DOC-002 "$profile" --depth 1
+          uv run python -m docsystem context DOC-002 "$profile" --depth 1 --json
+          uv run python -m docsystem changes "$profile" --json
+
+  windows:
+    runs-on: windows-latest
+    env:
+      PYTHONUTF8: "0"
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.12"
+
+      - name: Run Windows CLI tests without Python UTF-8 mode
+        shell: pwsh
+        run: |
+          $env:TMPDIR = $env:RUNNER_TEMP
+          $env:TMP = $env:RUNNER_TEMP
+          $env:TEMP = $env:RUNNER_TEMP
+          uv run pytest tests/test_cli.py tests/test_cli_platform.py `
+            tests/test_context_cli.py tests/test_mcp_adapter.py tests/test_readiness.py
+
+      - name: Installed CLI UTF-8 PowerShell smoke
+        shell: pwsh
+        run: |
+          $env:TMPDIR = $env:RUNNER_TEMP
+          $env:TMP = $env:RUNNER_TEMP
+          $env:TEMP = $env:RUNNER_TEMP
+          Remove-Item Env:PYTHONIOENCODING -ErrorAction SilentlyContinue
+          $dist = Join-Path $env:RUNNER_TEMP "docsystem-dist"
+          $venv = Join-Path $env:RUNNER_TEMP "docsystem-venv"
+          $project = Join-Path $env:RUNNER_TEMP "docsystem-unicode-project"
+          $output = Join-Path $env:RUNNER_TEMP "context.json"
+          $errors = Join-Path $env:RUNNER_TEMP "diagnostics.txt"
+
+          uv build --wheel --out-dir $dist
+          $wheel = Get-ChildItem $dist -Filter "documentation_engine-*.whl" -File
+          if ($wheel.Count -ne 1) { throw "expected exactly one wheel" }
+          uv venv $venv --python 3.12
+          $python = Join-Path $venv "Scripts/python.exe"
+          $docsystem = Join-Path $venv "Scripts/docsystem.exe"
+          uv pip install --python $python $wheel.FullName
+
+          $expectedVersion = (& $python -c "import docsystem; print(docsystem.__version__)").Trim()
+          $reportedVersion = (& $docsystem --version).Trim()
+          if ($reportedVersion -ne "docsystem $expectedVersion") {
+            throw "unexpected version output: $reportedVersion"
+          }
+
+          & $docsystem init $project
+          $architecture = Join-Path $project "plan/architecture"
+          New-Item -ItemType Directory -Path $architecture -Force | Out-Null
+          @"
+          ---
+          id: DOC-001
+          revision: 1
+          ---
+          # Привет
+          ## Резюме
+          Исходный текст остаётся доступен полностью.
+          "@ | Set-Content -Encoding utf8 (Join-Path $architecture "README.md")
+
+          & $docsystem context DOC-001 $project --json |
+            Set-Content -Encoding utf8 $output
+          if ($LASTEXITCODE -ne 0) { throw "context failed with $LASTEXITCODE" }
+          $payload = Get-Content -Raw -Encoding utf8 $output | ConvertFrom-Json
+          if ($payload.documents[0].navigation -notmatch "Привет") {
+            throw "context JSON lost Cyrillic source text"
+          }
+
+          & $docsystem read DOC-001 $project --anchor "отсутствует" 2> $errors
+          if ($LASTEXITCODE -ne 1) { throw "unknown anchor returned $LASTEXITCODE" }
+          $global:LASTEXITCODE = 0
+          $diagnostic = Get-Content -Raw -Encoding utf8 $errors
+          if ($diagnostic -notmatch "отсутствует") {
+            throw "stderr diagnostic was not UTF-8"
+          }

{documentation_engine-0.3.0 → documentation_engine-0.3.1}/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to Documentation Engine are documented in this file.
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-07-19
+
+### Fixed
+
+- CLI stdout and stderr now use UTF-8 independently of the host locale, so
+  redirected or piped Cyrillic and other Unicode Markdown works on Windows
+  without requiring `PYTHONUTF8=1`.
+- Windows CI now runs focused CLI/context/MCP regressions with Python UTF-8
+  mode disabled and verifies an installed wheel through a PowerShell JSON pipe
+  and a Unicode stderr diagnostic.
+
+### Added
+
+- `docsystem --version` reports the installed Documentation Engine version
+  without requiring a project or subcommand.
+
 ## [0.3.0] - 2026-07-15
 
 ### Highlights
@@ -181,7 +197,8 @@ documentation-engine` starts working only after the first successful release.
 - Measured context-reduction methodology and a reproducible consumer-install
   smoke test.
 
-[Unreleased]: https://github.com/Jafa7/DocumentationEngine/compare/v0.3.0...HEAD
+[Unreleased]: https://github.com/Jafa7/DocumentationEngine/compare/v0.3.1...HEAD
+[0.3.1]: https://github.com/Jafa7/DocumentationEngine/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/Jafa7/DocumentationEngine/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/Jafa7/DocumentationEngine/compare/v0.1.2...v0.2.0
 [0.1.2]: https://github.com/Jafa7/DocumentationEngine/compare/v0.1.1...v0.1.2

{documentation_engine-0.3.0 → documentation_engine-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: documentation-engine
-Version: 0.3.0
+Version: 0.3.1
 Summary: Provider-neutral structured Markdown documentation engine.
 Project-URL: Repository, https://github.com/Jafa7/DocumentationEngine
 Project-URL: Documentation, https://github.com/Jafa7/DocumentationEngine/tree/main/docs
@@ -130,12 +130,14 @@ unrelated globally installed `docsystem` executable.
 For a published-package installation:
 
 ```bash
+docsystem --version
 docsystem --help
 ```
 
 For a contributor checkout:
 
 ```bash
+uv run python -m docsystem --version
 uv run python -m docsystem --help
 ```
 
@@ -159,7 +161,8 @@ disposable projection. It does not require MCP.
 [docs/setup-guide.md](docs/setup-guide.md) step by step. It contains the
 connection/adoption flow, required user questions, backup-policy setup and
 checks.
-Do not improvise a local backup path or commit private planning paths.
+Do not improvise a private documentation root or local backup path, and do not
+commit private planning paths.
 
 **If you are a human using an AI agent**, paste this in the project you want to
 connect:
@@ -168,6 +171,11 @@ connect:
 Connect Documentation Engine to this project.
 Repository: https://github.com/Jafa7/DocumentationEngine
 Read docs/setup-guide.md in that repository and follow it exactly.
+Ask me for the exact private-documentation location before creating or moving
+documents. Recommend a dedicated external project directory, but do not invent
+or create a shared workspace path. If private documents already exist inside
+the project, copy and verify them first and leave the original untouched until
+I explicitly authorize its removal.
 Ask me where local disaster-recovery backups should be stored before touching
 ignored/private documentation or local configuration.
 ```

{documentation_engine-0.3.0 → documentation_engine-0.3.1}/README.md

@@ -113,12 +113,14 @@ unrelated globally installed `docsystem` executable.
 For a published-package installation:
 
 ```bash
+docsystem --version
 docsystem --help
 ```
 
 For a contributor checkout:
 
 ```bash
+uv run python -m docsystem --version
 uv run python -m docsystem --help
 ```
 
@@ -142,7 +144,8 @@ disposable projection. It does not require MCP.
 [docs/setup-guide.md](docs/setup-guide.md) step by step. It contains the
 connection/adoption flow, required user questions, backup-policy setup and
 checks.
-Do not improvise a local backup path or commit private planning paths.
+Do not improvise a private documentation root or local backup path, and do not
+commit private planning paths.
 
 **If you are a human using an AI agent**, paste this in the project you want to
 connect:
@@ -151,6 +154,11 @@ connect:
 Connect Documentation Engine to this project.
 Repository: https://github.com/Jafa7/DocumentationEngine
 Read docs/setup-guide.md in that repository and follow it exactly.
+Ask me for the exact private-documentation location before creating or moving
+documents. Recommend a dedicated external project directory, but do not invent
+or create a shared workspace path. If private documents already exist inside
+the project, copy and verify them first and leave the original untouched until
+I explicitly authorize its removal.
 Ask me where local disaster-recovery backups should be stored before touching
 ignored/private documentation or local configuration.
 ```

{documentation_engine-0.3.0 → documentation_engine-0.3.1}/docs/agent-contract.md

@@ -84,6 +84,15 @@ Those files are still source-of-truth operational state. An agent must not
 use a clean git status as evidence that broad filesystem operations are safe:
 ignored files can be destroyed while git remains clean.
 
+Before creating or moving private documentation, the agent must ask the user
+in English for the exact storage path and whether an existing in-repository
+documentation tree must be copied and verified. Recommend a dedicated external
+project directory, but do not infer or create a shared workspace path. Never
+remove the original tree without a separate explicit authorization. Use the
+canonical questions and neutral placeholder from
+[the setup guide](setup-guide.md#step-0-gather-facts) rather than inventing a
+machine-specific example.
+
 Before recursive copy, move, delete or sync commands; generated migrations;
 bulk rewrites; cross-OS shell snippets; or any task that touches ignored
 local-only documentation, the agent must run the project's local backup
@@ -191,6 +200,12 @@ wiring and must never be committed or printed in a report.
 
 ## Prefer `--json` over parsing text
 
+The CLI writes stdout and stderr as strict UTF-8 regardless of the host locale,
+including redirected Windows streams. Callers should decode both streams as
+UTF-8 and must not require `PYTHONUTF8` or locale-specific code pages. JSON
+keeps original Unicode characters rather than ASCII-escaping authored text;
+plain-text reads return the same UTF-8 Markdown content.
+
 `readiness`, `migration-report`, `catalog --explain`, `changes` and
 `context` accept `--json` and print one deterministic JSON value instead of
 tab-separated or prose text. An agent should use `--json` wherever it needs

{documentation_engine-0.3.0 → documentation_engine-0.3.1}/docs/setup-guide.md

@@ -9,7 +9,7 @@ not continue past a failing check — fix it or report the blocker to the user.
 Documentation Engine gives a project a stable Markdown documentation contract:
 
 - project-local `.docsystem.toml` configuration;
-- a configured documentation root such as `plan/`;
+- a configured documentation root inside or outside the repository;
 - stable document IDs and relation metadata;
 - deterministic validation, context packets and projection cache;
 - local-only backup policy for private/ignored documentation state.
@@ -23,15 +23,43 @@ adopting project owns its local policy.
 Establish these before touching files. Ask the user rather than guessing.
 
 1. **Project root** — absolute path of the project to adopt.
-2. **Documentation root** — where the project's Markdown knowledge should live
-   (for example `plan/`, `docs/plan/` or an existing private docs folder).
+2. **Documentation root** — whether private Markdown should remain inside the
+   repository or use a dedicated external project directory, and its exact
+   absolute path. Recommend the external option for private documentation, but
+   do not invent or create a shared workspace path.
 3. **Language** — language of private/local documentation.
 4. **Public vs. private split** — which docs are allowed to be committed and
    which must remain local/ignored.
 5. **Backup destination** — where local disaster-recovery snapshots should be
    stored for ignored documentation/configuration/runtime files.
 
-Ask the backup question explicitly:
+Before creating or moving private documentation, ask these placement questions
+explicitly and in English:
+
+```text
+Where should this project's private documentation be stored?
+
+The recommended option is a dedicated directory outside the project repository,
+for example:
+
+<external-documentation-root>/projects/<project-slug>/
+
+Please provide the exact path. I will not create, move, replace, or delete any
+documentation until the location and migration procedure are explicitly
+confirmed.
+
+Does private documentation already exist inside the project, for example in
+plan/? If so, I will copy and verify it first. The original directory will
+remain untouched until you explicitly authorize its removal.
+```
+
+The path above is a neutral placeholder, not a directory to create literally.
+The user may select an in-repository, local, mounted or network location. Do
+not treat a parent directory as readable authority: an external project root
+authorizes only that exact scope unless the user separately authorizes another
+path.
+
+Ask the backup question separately:
 
 ```text
 Where should this project store local disaster-recovery backups for ignored

{documentation_engine-0.3.0 → documentation_engine-0.3.1}/src/docsystem/__init__.py

@@ -9,7 +9,7 @@ from docsystem.catalog import (
 from docsystem.metadata import DocumentMetadata, MetadataReference
 from docsystem.sections import MarkdownSection
 
-__version__ = "0.3.0"
+__version__ = "0.3.1"
 
 __all__ = [
     "CatalogMembership",

{documentation_engine-0.3.0 → documentation_engine-0.3.1}/src/docsystem/cli.py

@@ -205,6 +205,21 @@ from docsystem.workstream import (
     load_record,
 )
 
+
+def _configure_utf8_stream(stream: object) -> None:
+    """Make one standard text stream deterministic across host locales."""
+
+    reconfigure = getattr(stream, "reconfigure", None)
+    if callable(reconfigure):
+        reconfigure(encoding="utf-8", errors="strict")
+
+
+def _configure_standard_streams() -> None:
+    """Use UTF-8 for CLI output, including redirected Windows streams."""
+
+    _configure_utf8_stream(sys.stdout)
+    _configure_utf8_stream(sys.stderr)
+
 # Version of every `--json` root object. Bump only on a breaking change to
 # an existing field; adding new fields is compatible and does not bump it.
 JSON_SCHEMA_VERSION = 1
@@ -8086,6 +8101,11 @@ def _add_source_options(
 
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"docsystem {__version__}",
+    )
     subparsers = parser.add_subparsers(dest="command", required=True)
     for command, help_text in (
         ("init", "Create configuration and the documentation root."),
@@ -8908,6 +8928,7 @@ def build_parser() -> argparse.ArgumentParser:
 
 
 def main() -> int:
+    _configure_standard_streams()
     args = build_parser().parse_args()
     if args.command == "workspace":
         if args.workspace_command == "list":

documentation_engine-0.3.1/tests/test_cli_platform.py

@@ -0,0 +1,122 @@
+import io
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+from docsystem import __version__
+from docsystem.cli import _configure_utf8_stream, build_parser
+from docsystem.config import CONFIG_FILENAME, DEFAULT_CONFIG
+
+
+def _legacy_locale_environment() -> dict[str, str]:
+    environment = os.environ.copy()
+    environment["PYTHONUTF8"] = "0"
+    environment.pop("PYTHONIOENCODING", None)
+    return environment
+
+
+def _write_unicode_project(project: Path) -> None:
+    (project / CONFIG_FILENAME).write_text(DEFAULT_CONFIG, encoding="utf-8")
+    architecture = project / "plan" / "architecture"
+    architecture.mkdir(parents=True)
+    (architecture / "README.md").write_text(
+        """\
+---
+id: DOC-001
+revision: 1
+---
+# Привет
+## Резюме
+Исходный текст остаётся доступен полностью.
+""",
+        encoding="utf-8",
+    )
+
+
+def test_utf8_stream_configuration_overrides_a_legacy_encoding() -> None:
+    buffer = io.BytesIO()
+    stream = io.TextIOWrapper(buffer, encoding="cp1252", errors="strict")
+
+    _configure_utf8_stream(stream)
+    stream.write("Привет")
+    stream.flush()
+
+    assert stream.encoding.lower() == "utf-8"
+    assert buffer.getvalue().decode("utf-8") == "Привет"
+
+
+def test_global_version_option_uses_the_distribution_version(capsys) -> None:
+    with pytest.raises(SystemExit) as raised:
+        build_parser().parse_args(["--version"])
+
+    assert raised.value.code == 0
+    assert capsys.readouterr().out == f"docsystem {__version__}\n"
+
+
+def test_module_cli_emits_utf8_json_without_python_utf8_mode(tmp_path: Path) -> None:
+    _write_unicode_project(tmp_path)
+
+    result = subprocess.run(
+        [
+            sys.executable,
+            "-m",
+            "docsystem",
+            "context",
+            "DOC-001",
+            str(tmp_path),
+            "--json",
+        ],
+        capture_output=True,
+        env=_legacy_locale_environment(),
+        check=False,
+    )
+
+    assert result.returncode == 0, result.stderr.decode("utf-8")
+    payload = json.loads(result.stdout.decode("utf-8"))
+    assert "# Привет" in payload["documents"][0]["navigation"]
+    assert "резюме" in payload["documents"][0]["omitted_h2"]
+
+
+def test_module_cli_emits_utf8_diagnostics_without_python_utf8_mode(
+    tmp_path: Path,
+) -> None:
+    _write_unicode_project(tmp_path)
+
+    result = subprocess.run(
+        [
+            sys.executable,
+            "-m",
+            "docsystem",
+            "read",
+            "DOC-001",
+            str(tmp_path),
+            "--anchor",
+            "отсутствует",
+        ],
+        capture_output=True,
+        env=_legacy_locale_environment(),
+        check=False,
+    )
+
+    assert result.returncode == 1
+    assert result.stdout == b""
+    assert "отсутствует" in result.stderr.decode("utf-8")
+
+
+def test_module_cli_version_is_available_without_a_subcommand() -> None:
+    result = subprocess.run(
+        [sys.executable, "-m", "docsystem", "--version"],
+        capture_output=True,
+        env=_legacy_locale_environment(),
+        check=False,
+    )
+
+    assert result.returncode == 0
+    assert result.stdout.decode("utf-8").splitlines() == [
+        f"docsystem {__version__}"
+    ]
+    assert result.stderr == b""

{documentation_engine-0.3.0 → documentation_engine-0.3.1}/tests/test_release_workflows.py

@@ -127,6 +127,27 @@ def test_ci_checks_the_sdist_that_the_smoke_test_never_builds(ci: dict) -> None:
     assert "twine check --strict" in body
 
 
+def test_ci_runs_the_cli_utf8_contract_on_windows(ci: dict) -> None:
+    windows = ci["jobs"]["windows"]
+    assert windows["runs-on"] == "windows-latest"
+    assert windows["env"]["PYTHONUTF8"] == "0"
+    body = steps_text(windows)
+    for contract in (
+        "$env:TMPDIR = $env:RUNNER_TEMP",
+        "uv run pytest tests/test_cli.py tests/test_cli_platform.py",
+        "tests/test_context_cli.py tests/test_mcp_adapter.py tests/test_readiness.py",
+        "Remove-Item Env:PYTHONIOENCODING",
+        "uv build --wheel",
+        "docsystem.exe",
+        "--version",
+        "context DOC-001",
+        "ConvertFrom-Json",
+        'read DOC-001 $project --anchor "отсутствует"',
+        "$global:LASTEXITCODE = 0",
+    ):
+        assert contract in body, f"Windows CI lost the {contract!r} contract"
+
+
 # --- Release: trigger and permissions -------------------------------------
 
 

documentation_engine-0.3.0/.github/workflows/ci.yml

@@ -1,65 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-
-permissions:
-  contents: read
-
-env:
-  TMPDIR: /tmp
-  TMP: /tmp
-  TEMP: /tmp
-
-jobs:
-  check:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v7
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@v7
-        with:
-          python-version: "3.12"
-
-      - name: Run pytest
-        run: uv run pytest
-
-      - name: Run ruff
-        run: uv run ruff check .
-
-      - name: Verify lockfile is current
-        run: uv lock --check
-
-      - name: Installed CLI smoke test
-        run: ./scripts/installed_cli_smoke.sh
-
-      # The smoke test builds and installs a wheel only. The release workflow
-      # uploads a wheel *and* an sdist, and an index rejects a distribution
-      # whose metadata or long description does not render. Check both
-      # artifacts here rather than during an irreversible upload.
-      - name: Build and check both distributions
-        run: |
-          dist_dir="$(mktemp -d)/dist"
-          uv build --out-dir "$dist_dir"
-          version="$(uv run python -c 'import docsystem; print(docsystem.__version__)')"
-          test -f "$dist_dir/documentation_engine-${version}-py3-none-any.whl"
-          test -f "$dist_dir/documentation_engine-${version}.tar.gz"
-          uvx --from 'twine>=6,<7' twine check --strict "$dist_dir"/*
-
-      # Dogfooding: walk the documented adoption sequence end-to-end against
-      # the public example profile, on a scratch copy so the fixture stays
-      # byte-identical in the repository.
-      - name: Example profile adoption walkthrough
-        run: |
-          profile="$(mktemp -d)/profile"
-          cp -r examples/generic-adopter "$profile"
-          uv run python -m docsystem readiness "$profile" --json
-          uv run python -m docsystem migrate "$profile" --apply
-          uv run python -m docsystem index "$profile" --write
-          uv run python -m docsystem readiness "$profile" --json
-          uv run python -m docsystem context DOC-002 "$profile" --depth 1
-          uv run python -m docsystem context DOC-002 "$profile" --depth 1 --json
-          uv run python -m docsystem changes "$profile" --json