dgenio / dgenio/contextweaver

[CI] Add Windows and macOS to the test matrix and publish a platform support statement

Open
#441 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

complexity:average developer-experience priority:medium testing
Dominant language
Python
Stars
9
Forks
17
Avg merge
21h 36m
Merged PRs (30d)
22

Description

Summary

CI currently runs on ubuntu-latest only (all jobs in ci.yml), while
the primary adoption paths — Claude Desktop, Cursor, VS Code recipes —
run heavily on macOS and Windows. Add both platforms to the test matrix
(scoped to keep CI cost sane), fix whatever falls out, and publish an
explicit platform support statement in the docs.

Why this matters

  • The gateway's stdio lifecycle (SIGINT/EOF handling), path handling in
    stores (JsonFileArtifactStore, SQLite paths), and console behavior
    (Rich on legacy Windows terminals) are exactly the things that differ
    across platforms — and exactly what a Claude Desktop user on Windows
    hits first.
  • "Tested on Windows/macOS" removes a silent adoption objection for
    desktop users and enterprises; an explicit support statement belongs
    next to the Python-version policy in docs/stability.md.
  • Recipes that say "works with Claude Desktop" implicitly promise
    macOS/Windows support today, without CI backing.

Proposed scope

  • Extend the test job matrix: full Python matrix on Ubuntu (as today),
    plus windows-latest and macos-latest on the newest and oldest
    supported Python (4 added cells, not 8) — fail-fast: false
    preserved.
  • Keep the heavier jobs (drift checks, benchmarks, floor-deps,
    examples/demo) Ubuntu-only; run make test (+ make demo if cheap)
    on the new cells.
  • Fix discovered issues: likely suspects are path separators in stores
    and fixtures, signal handling differences in _mcp_cli.py
    (SIGINT vs CTRL_BREAK_EVENT), tmpfile semantics in store tests,
    and line-ending assumptions in golden files (.gitattributes may be
    needed).
  • docs/stability.md: add a platform support table (Tier 1: Linux;
    Tier 1 after this issue: macOS/Windows for library + stdio gateway).
  • README badge/bullet update once green.

Implementation notes

  • Workflow: .github/workflows/ci.yml test job (currently
    runs-on: ubuntu-latest with a 3.10–3.13 matrix); convert to an
    os/python-version matrix with include/exclude to get the
    4-cell expansion.
  • Golden/byte-identical tests (cards, scorecard fixtures) are the most
    likely cross-platform failures — normalize newlines at comparison
    time rather than weakening the determinism claims.
  • tiktoken wheels exist for win/mac; the offline fallback covers any
    gap.
  • Windows runners are slow: keep their job to pytest -q without
    coverage to bound wall time.

Acceptance criteria

  • CI green on windows-latest and macos-latest for oldest and
    newest supported Python.
  • Any platform-specific fixes covered by tests (not just skipped
    on the failing platform — skips need a written rationale).
  • Platform support statement published in docs/stability.md.
  • CI wall-time impact measured and documented on the PR.

Out of scope

  • Platform-specific packaging (MSI/Homebrew).
  • Windows-specific gateway features (e.g. named-pipe transports).
  • Running the full drift-check suite on non-Linux.

References


Priority: P1 · Effort: M · Impact: Medium

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with .github/workflows/ci.yml and its test job, then run make test on the oldest and newest supported Python versions for the added Windows and macOS cells. Check platform-specific failures in the store, CLI, signal, fixture, and golden-file tests; done means CI is green, fixes have test coverage, docs/stability.md has the support table, and the README and CI timing are updated.

Written by the indexing model from the issue text.

Assessment

Tech stack
github-actions, python
Domain
ci-cd, documentation
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.