engmem 0.1.1__tar.gz

engmem-0.1.1/.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# Every change needs a review from the owner.
+* @AlejandroKolio

engmem-0.1.1/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,41 @@
+name: Bug report
+description: Something behaved differently from what the output claimed
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Please redact anything private. Document titles, ticket ids, and matched text
+        from your store often quote proprietary work — replace them with placeholders.
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: The command you ran and its full output, redacted as needed.
+      render: shell
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected instead
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: engmem version and Python version
+      placeholder: "engmem 0.1.0, Python 3.13 on macOS 15"
+    validations:
+      required: true
+
+  - type: textarea
+    id: store-shape
+    attributes:
+      label: Store shape
+      description: >-
+        Roughly how many documents, and anything unusual about them — nested
+        directories, hand-written front matter, documents predating engmem.

engmem-0.1.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: true

engmem-0.1.1/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,32 @@
+name: Feature request
+description: Propose a change to what engmem does
+labels: [enhancement]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        engmem is deliberately small: plain files, no database, no derived index, one
+        runtime dependency. `ENGMEM-SPEC.md` §9 lists what was considered and cut, and
+        why — worth reading first, since a proposal it already covers needs to argue
+        against the recorded reason rather than restate the idea.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: The problem
+      description: What went wrong in real use. Not the solution yet — the situation.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What you propose
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: What you considered and rejected
+      description: Including doing nothing.

engmem-0.1.1/.github/dependabot.yml

@@ -0,0 +1,12 @@
+version: 2
+updates:
+  # The actions in ci.yml and release.yml are third-party code running with repository
+  # access. A tag can be moved under you; this is what keeps the pinned versions current.
+  # It does not reach `pypa/gh-action-pypi-publish@release/v1` — a branch has no version
+  # to raise, so the action that mints the PyPI token is the one this never reports on.
+  # That trade-off is argued at the `uses:` line in release.yml.
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: monthly
+    open-pull-requests-limit: 3

engmem-0.1.1/.github/pull_request_template.md

@@ -0,0 +1,13 @@
+## What this changes
+
+<!-- The behaviour, in a sentence or two. Why, not just what. -->
+
+## Checklist
+
+- [ ] A failing test was written first and observed to fail (ENGMEM-SPEC.md §10, principle I)
+- [ ] `uv run pytest -q` is green
+- [ ] No existing assertion was weakened to make something pass
+- [ ] Comments explain *why*, in a line or two — long rationale went to the spec instead
+- [ ] Examples in tests and docs are invented, with no real ticket, repository, class, or
+      business term from any private codebase
+- [ ] Runtime dependencies unchanged (still `pyyaml` only), or the reason is stated here

engmem-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,136 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+# a fork's pull request runs with this token; nothing here needs to write
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # POSIX-only tests (chmod-based permission checks, symlink containment)
+        # skip themselves on Windows via tests/conftest.py rather than failing.
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install the project and its dev group
+        run: uv sync --group dev --python ${{ matrix.python-version }}
+
+      - name: Run the test suite
+        run: uv run --python ${{ matrix.python-version }} pytest -q
+
+  runtime-dependencies:
+    # engmem's runtime is pyyaml and markdown-it-py, nothing else. A dev-only tool
+    # leaking into the runtime dependency set is a defect this catches before
+    # release, not after.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - run: uv build --wheel
+      - name: Assert the wheel requires nothing beyond the two declared dependencies
+        run: |
+          python - <<'PY'
+          import pathlib, zipfile
+          wheel = next(pathlib.Path("dist").glob("*.whl"))
+          names = zipfile.ZipFile(wheel).namelist()
+          meta = zipfile.ZipFile(wheel).read(
+              next(n for n in names if n.endswith("METADATA"))
+          ).decode()
+          requires = sorted(
+              line.split(":", 1)[1].strip()
+              for line in meta.splitlines()
+              if line.startswith("Requires-Dist:")
+          )
+          print("Requires-Dist:", requires)
+          assert requires == ["markdown-it-py", "pyyaml"], (
+              f"runtime dependencies drifted: {requires}"
+          )
+          PY
+
+  packaging:
+    # What ships is not what is committed. hatchling reads `.gitignore`, so a file can be
+    # ignored and still tracked — `.coverage` was, and rode into every sdist and every
+    # source archive until it was untracked. Both halves are asserted here, on every pull
+    # request: the release workflow would only learn after a tag was cut, and a published
+    # version cannot be re-uploaded.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - run: uv build --sdist
+
+      - name: Assert the sdist ships exactly the expected top-level entries
+        run: |
+          python - <<'PY'
+          import pathlib, tarfile
+          # An allowlist, not a list of forbidden names: a denylist only catches the stray
+          # file someone already thought of, and rots silently as new ones appear. Growing
+          # a top-level entry is deliberate, so failing here is the review, not the bug.
+          ALLOWED = {
+              ".github", ".gitignore", "CONTRIBUTING.md", "ENGMEM-SPEC.md", "LICENSE",
+              "PKG-INFO", "README.md", "SECURITY.md", "docs", "pyproject.toml",
+              "src", "tests", "tools", "uv.lock",
+          }
+          sdist = next(pathlib.Path("dist").glob("*.tar.gz"))
+          top = {
+              name.split("/", 1)[1].split("/", 1)[0]
+              for name in tarfile.open(sdist).getnames()
+              if "/" in name
+          }
+          assert not top - ALLOWED, f"unexpected entries in the sdist: {sorted(top - ALLOWED)}"
+          assert not ALLOWED - top, f"entries missing from the sdist: {sorted(ALLOWED - top)}"
+          print(f"{sdist.name}: {len(top)} top-level entries, all expected")
+          PY
+
+      - name: Assert no ignored-class file is tracked
+        run: |
+          python - <<'PY'
+          import subprocess
+          tracked = sorted(subprocess.run(
+              ["git", "ls-files"], capture_output=True, text=True, check=True
+          ).stdout.split())
+          # `--no-index` is the point: it answers "would this be ignored", which is exactly
+          # the question `git add` never asks again once a file is tracked.
+          ignored = subprocess.run(
+              ["git", "check-ignore", "--no-index", *tracked],
+              capture_output=True, text=True,
+          ).stdout.split()
+          assert not ignored, f"tracked files that .gitignore says to ignore: {ignored}"
+          print(f"{len(tracked)} tracked files, none ignored-class")
+          PY
+
+  # The single check branch protection should require. Requiring the matrix jobs by name
+  # means every matrix change silently blocks every PR: the named check stops appearing
+  # and nothing reports it.
+  ci:
+    if: always()
+    needs: [test, runtime-dependencies, packaging]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Fail unless every job succeeded
+        run: |
+          echo "test: ${{ needs.test.result }}"
+          echo "runtime-dependencies: ${{ needs.runtime-dependencies.result }}"
+          echo "packaging: ${{ needs.packaging.result }}"
+          [ "${{ needs.test.result }}" = "success" ] \
+            && [ "${{ needs.runtime-dependencies.result }}" = "success" ] \
+            && [ "${{ needs.packaging.result }}" = "success" ]

engmem-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,114 @@
+name: Release
+
+# A tag is the only trigger. `ci.yml` runs on pushes to main and on pull requests,
+# neither of which a tag push is — so this workflow re-runs the suite itself rather
+# than trusting that main was green when the tag was cut.
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  guard:
+    # Two things that cannot be undone once uploaded: a version number that does not
+    # match its tag, and a release built from a red tree. PyPI refuses a re-upload of
+    # an existing version, so both are caught here or not at all.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Assert the tag matches the version in pyproject.toml
+        run: |
+          python - <<'PY'
+          import os, pathlib, tomllib
+          tag = os.environ["GITHUB_REF_NAME"]
+          version = tomllib.loads(
+              pathlib.Path("pyproject.toml").read_text(encoding="utf-8")
+          )["project"]["version"]
+          print(f"tag={tag} version={version}")
+          assert tag == f"v{version}", (
+              f"tag {tag} does not match pyproject version {version} — "
+              f"expected v{version}"
+          )
+          PY
+
+      - name: Run the test suite
+        run: uv run pytest -q
+
+  build:
+    needs: guard
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Build the sdist and the wheel
+        run: uv build
+
+      - name: Re-assert the sdist ships exactly the expected top-level entries
+        # `ci.yml`'s packaging job owns this rule and runs it on every pull request, which
+        # is where it can still be acted on. Repeated here only because the artefact this
+        # job uploads is the one that gets published, and a published version is final.
+        run: |
+          python - <<'PY'
+          import pathlib, tarfile
+          ALLOWED = {
+              ".github", ".gitignore", "CONTRIBUTING.md", "ENGMEM-SPEC.md", "LICENSE",
+              "PKG-INFO", "README.md", "SECURITY.md", "docs", "pyproject.toml",
+              "src", "tests", "tools", "uv.lock",
+          }
+          sdist = next(pathlib.Path("dist").glob("*.tar.gz"))
+          top = {
+              name.split("/", 1)[1].split("/", 1)[0]
+              for name in tarfile.open(sdist).getnames()
+              if "/" in name
+          }
+          assert not top - ALLOWED, f"unexpected entries in the sdist: {sorted(top - ALLOWED)}"
+          assert not ALLOWED - top, f"entries missing from the sdist: {sorted(ALLOWED - top)}"
+          print(f"{sdist.name}: {len(top)} top-level entries, all expected")
+          PY
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+
+    # Trusted Publishing: PyPI trusts this repository, this workflow file and this
+    # environment, and mints a short-lived token per run. There is no long-lived API
+    # token in repository secrets, so there is nothing to leak or rotate.
+    environment:
+      name: pypi
+      url: https://pypi.org/p/engmem
+
+    permissions:
+      id-token: write # the OIDC token PyPI verifies; nothing else is needed
+
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        # `release/v1` is a BRANCH, not a tag — deliberately, and it is PyPA's documented
+        # form: security fixes reach this job without a manual bump. The cost is that
+        # Dependabot has no version to raise, so the one action holding `id-token: write`
+        # is also the one action nothing reports on. Read its release notes before trusting
+        # a run you did not expect.
+        uses: pypa/gh-action-pypi-publish@release/v1

engmem-0.1.1/.gitignore

@@ -0,0 +1,45 @@
+# Build and environment
+.venv/
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.pyc
+.pytest_cache/
+.env
+
+# Editors and OS
+.idea/
+.vscode/
+.DS_Store
+
+# engmem's own installed output: `engmem install` writes these into the working
+# repository (`--agent copilot-ide`, or `--agent claude --local`). They are generated
+# copies of src/engmem/templates/, so committing them guarantees a stale duplicate.
+.github/prompts/
+.github/copilot-instructions.md
+.claude/
+
+# A store must never live inside this repository, but nothing stops one from being
+# pointed here. These are the two things it would leave: the documents themselves, and
+# the search log — which records the queries, and a query quotes the work.
+# Anchored to the root on purpose: unanchored, `sessions/` would also swallow
+# tests/fixtures/sessions/, the golden documents search ranking is defined against.
+/sessions/
+/telemetry.jsonl
+
+# Never commit: working notes and raw session transcripts may quote private material
+# from whatever codebase the tool was used on.
+.tmp/
+chat-transcript-*.md
+
+# Agent tool configuration: local convenience, not part of the project.
+CLAUDE.md
+
+# Coverage databases and stray CI logs: never project content. Adding a pattern
+# here does nothing for a file git already tracks -- `.coverage` was tracked, and
+# shipped in every sdist and source archive until it was untracked.
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/

engmem-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,71 @@
+# Contributing
+
+## Getting set up
+
+The project uses [uv](https://docs.astral.sh/uv/). Python 3.11 or newer.
+
+    uv sync --group dev
+    uv run pytest -q
+
+The test suite is the whole check — it runs offline, needs no fixtures beyond the
+repository, and finishes in seconds.
+
+## Pull requests
+
+Branch, push, open a PR against `main`. One check gates the merge: **`ci`**, which
+passes only when the test matrix (Linux, macOS, Windows × Python 3.11–3.13) and the
+runtime-dependency job both succeed.
+
+Squash merge is the only merge method; write the PR title as the commit message you
+want in the history.
+
+## Releases
+
+The version lives in `pyproject.toml` only; `engmem.__version__` reads it from the
+installed package metadata. Until 1.0 every release bumps the patch number:
+
+    uv version --bump patch
+    git commit -am "release: v$(uv version --short)"
+    git tag "v$(uv version --short)" && git push --tags
+
+The tag triggers `release.yml`, which refuses a tag that does not match `pyproject.toml`,
+re-runs the suite, builds, and publishes to PyPI.
+
+## What the tests enforce
+
+Some tests exist to protect invariants rather than behaviour. If one of these fails,
+the fix is usually the change, not the test.
+
+- **Two runtime dependencies.** The wheel must require `pyyaml` and `markdown-it-py`
+  and nothing else. A new runtime import fails `runtime-dependencies` in CI. Dev-only
+  tools belong in the `dev` dependency group.
+- **No network.** `tests/conftest.py` blocks sockets for the entire suite.
+- **stdout is protocol-only.** `test_stdout_is_protocol_only.py` walks the AST and
+  fails if anything prints to stdout outside the output layer — the MCP server shares
+  that stream, and one stray `print` corrupts every message on it.
+- **Docs match the code.** `test_docs_match_the_code.py` checks that names, constants,
+  and CLI flags quoted in the documentation still exist.
+- **Fixtures land as bytes.** `write_file` in `tests/conftest.py` writes exactly the
+  text it is given. Text mode translates every `\n` to `\r\n` on Windows, so a test
+  pinning a document's line endings, byte-order mark, or exact bytes was handed a
+  document it never asked for — and the failure only ever showed up on the Windows leg.
+  Where the bytes matter, write them through `write_file` or `write_bytes`; a bare
+  `path.write_text(...)` is fine only when the test does not care what lands on disk.
+
+## Fixtures and examples
+
+Every fixture, example, and document in this repository is invented. Do not add
+material from real work — not a class name, not a ticket number, not a paraphrased
+incident, in tests or docs alike. If you need a scenario, make one up; the existing
+fixtures under `tests/fixtures/sessions/` show the shape.
+
+This is not decorative. The store is designed to hold things people cannot publish,
+so the project itself has to demonstrate the discipline it asks for.
+
+## Style
+
+Match the surrounding code. Comments explain why something is not the obvious choice;
+anything a reader can get from the code itself does not need a comment.
+
+Documentation is prose, not bullet dumps. If a change alters behaviour described in
+`README.md` or `ENGMEM-SPEC.md`, update it in the same PR.