qcoder 0.5.0a5__tar.gz → 0.5.0a7__tar.gz

{qcoder-0.5.0a5 → qcoder-0.5.0a7}/CHANGELOG.md

@@ -1,6 +1,30 @@
 # Changelog
 
 
+## 0.5.0a7
+
+- Add local read-only qCoder MCP for Cursor-oriented Explorer Launch workflows.
+- Add MCP tools for local circuit analysis, context-pack generation, counts review, bounded findings, claim boundaries, next checks, and share-safe artifact sanitization.
+- Document the Evidence-Grounded Coding Loop and preserve the manual artifact handoff as launch-required even when local MCP is available.
+- Harden Windows-created inputs by accepting UTF-8 BOM in QASM and JSON paths used by local analysis/review.
+- Improve `qcoder review` error guidance for malformed JSON and Qiskit counts input.
+- Add MCP, share-safe, claim-boundary, and Windows/QASM/Qiskit tests plus release-check MCP stdio rehearsal.
+- Preserve launch boundaries: no public hosted MCP claim, no live service calls from MCP, no token requirement, no autonomous code modification, no QPU/simulator submission, and no runtime/fidelity/backend/QPU/correctness/advantage claims.
+- This is release-candidate preparation only until separately published.
+
+
+## 0.5.0a6
+
+- Add share-safe / redacted artifact mode for artifacts intended for ChatGPT, Cursor, email, GitHub issues, or support threads.
+- Add `--share-safe` / `--redact` to OSS artifact commands and Explorer evidence file output.
+- Emit share-safety metadata in JSON artifacts: `share_safe`, `redactions_applied`, `raw_qasm_included`, `local_paths_included`, and `tokens_included`.
+- Add a visible share-safe note to Markdown artifacts.
+- Fix Windows free-text path redaction, including `C:\Users\...` paths, Windows forward-slash paths, UNC paths, home-relative paths, Linux home paths, and WSL-mounted Windows paths.
+- Preserve normal rich local artifacts by default; share-safe mode is opt-in.
+- Share-safe mode is designed for safer sharing and users should still review artifacts before sharing. It is not a privacy guarantee.
+- Remaining P1 hardening: forward-slash UNC variants, broader Linux root patterns, independent post-scan hardening, and expanded docs wording.
+
+
 ## 0.5.0a5
 
 - Add `qcoder explorer evidence` as the primary Explorer Beta guided-evidence surface.

{qcoder-0.5.0a5/src/qcoder.egg-info → qcoder-0.5.0a7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qcoder
-Version: 0.5.0a5
+Version: 0.5.0a7
 Summary: Quantum circuit analysis and structured feature extraction tools.
 Author-email: Quantum Ready Solutions <support@qcoder.ai>
 Maintainer-email: Quantum Ready Solutions <support@qcoder.ai>
@@ -15,6 +15,8 @@ Classifier: Intended Audience :: Science/Research
 Classifier: Topic :: Scientific/Engineering
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -40,6 +42,7 @@ The current public local path is **qCoder OSS**. OSS commands run locally and do
 - `qcoder batch`
 - `qcoder context`
 - `qcoder review`
+- `qcoder mcp` (local read-only Cursor MCP tools)
 - `qcoder explorer` (Explorer Beta account-backed status/demo/evidence checks)
 - `qcoder student` (temporary compatibility alias for Explorer Beta)
 - `qcoder pro` (archived pilot/bootstrap client contract; non-confidential local plumbing only, not a current public product path)
@@ -77,6 +80,24 @@ qcoder context path/to/circuit.qasm --out-json preflight.context.json --out-md p
 qcoder review --counts-json counts.json --format qiskit_counts --preflight-json preflight.context.json --out-json execution.review.json --out-md execution.review.md
 ```
 
+For artifacts you intend to paste into ChatGPT, Cursor, email, GitHub issues, or support threads, add `--share-safe`:
+
+```bash
+qcoder analyze path/to/circuit.qasm --json --share-safe
+qcoder context path/to/circuit.qasm --out-json preflight.context.json --out-md preflight.context.md --share-safe
+qcoder review --counts-json counts.json --format qiskit_counts --preflight-json preflight.context.json --out-json execution.review.json --out-md execution.review.md --share-safe
+```
+
+Share-safe mode is designed for safer sharing: it redacts local paths and token/header-like strings, adds `share_safe=true`, and marks raw QASM/local paths/tokens as not included. Review artifacts before sharing; this is not a guarantee that all sensitive project content has been removed.
+
+Local Cursor MCP:
+
+```bash
+qcoder mcp serve
+```
+
+The MCP server uses explicit user-selected local inputs only. It reads, inspects, explains, bounds, and recommends; it does not execute circuits, modify user code, read arbitrary files, call live services, or require tokens. See [Explorer Evidence-Grounded Coding Loop](examples/08_explorer_evidence_grounded_coding_loop.md) for the manual artifact loop, Cursor MCP setup, and claim boundaries.
+
 Explorer Beta compatibility checks and archived Pro bootstrap:
 
 ```bash
@@ -85,6 +106,7 @@ qcoder explorer demo
 qcoder explorer evidence
 qcoder explorer evidence --qasm path/to/circuit.qasm
 qcoder explorer evidence --context-json preflight.context.json
+qcoder explorer evidence --qasm path/to/circuit.qasm --out-json explorer.json --out-md explorer.md --share-safe
 qcoder pro --help
 ```
 

{qcoder-0.5.0a5 → qcoder-0.5.0a7}/README.md

@@ -10,6 +10,7 @@ The current public local path is **qCoder OSS**. OSS commands run locally and do
 - `qcoder batch`
 - `qcoder context`
 - `qcoder review`
+- `qcoder mcp` (local read-only Cursor MCP tools)
 - `qcoder explorer` (Explorer Beta account-backed status/demo/evidence checks)
 - `qcoder student` (temporary compatibility alias for Explorer Beta)
 - `qcoder pro` (archived pilot/bootstrap client contract; non-confidential local plumbing only, not a current public product path)
@@ -47,6 +48,24 @@ qcoder context path/to/circuit.qasm --out-json preflight.context.json --out-md p
 qcoder review --counts-json counts.json --format qiskit_counts --preflight-json preflight.context.json --out-json execution.review.json --out-md execution.review.md
 ```
 
+For artifacts you intend to paste into ChatGPT, Cursor, email, GitHub issues, or support threads, add `--share-safe`:
+
+```bash
+qcoder analyze path/to/circuit.qasm --json --share-safe
+qcoder context path/to/circuit.qasm --out-json preflight.context.json --out-md preflight.context.md --share-safe
+qcoder review --counts-json counts.json --format qiskit_counts --preflight-json preflight.context.json --out-json execution.review.json --out-md execution.review.md --share-safe
+```
+
+Share-safe mode is designed for safer sharing: it redacts local paths and token/header-like strings, adds `share_safe=true`, and marks raw QASM/local paths/tokens as not included. Review artifacts before sharing; this is not a guarantee that all sensitive project content has been removed.
+
+Local Cursor MCP:
+
+```bash
+qcoder mcp serve
+```
+
+The MCP server uses explicit user-selected local inputs only. It reads, inspects, explains, bounds, and recommends; it does not execute circuits, modify user code, read arbitrary files, call live services, or require tokens. See [Explorer Evidence-Grounded Coding Loop](examples/08_explorer_evidence_grounded_coding_loop.md) for the manual artifact loop, Cursor MCP setup, and claim boundaries.
+
 Explorer Beta compatibility checks and archived Pro bootstrap:
 
 ```bash
@@ -55,6 +74,7 @@ qcoder explorer demo
 qcoder explorer evidence
 qcoder explorer evidence --qasm path/to/circuit.qasm
 qcoder explorer evidence --context-json preflight.context.json
+qcoder explorer evidence --qasm path/to/circuit.qasm --out-json explorer.json --out-md explorer.md --share-safe
 qcoder pro --help
 ```
 

{qcoder-0.5.0a5 → qcoder-0.5.0a7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qcoder"
-version = "0.5.0a5"
+version = "0.5.0a7"
 description = "Quantum circuit analysis and structured feature extraction tools."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -23,6 +23,8 @@ classifiers = [
     "Topic :: Scientific/Engineering",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
 ]
 dependencies = ["numpy"]
 

{qcoder-0.5.0a5 → qcoder-0.5.0a7}/src/qcoder/__init__.py

@@ -1,3 +1,3 @@
 __all__ = []
-__version__ = "0.5.0a5"
+__version__ = "0.5.0a7"
 file = __file__

{qcoder-0.5.0a5 → qcoder-0.5.0a7}/src/qcoder/cli.py

@@ -3,11 +3,17 @@ from __future__ import annotations
 import argparse
 import json
 import sys
+from json import JSONDecodeError
 from pathlib import Path
 
 from qcoder.pipelines.analyze import analyze_qasm
 from qcoder.pipelines.context import write_preflight_context
 from qcoder.pipelines.review import write_execution_review
+from qcoder.core.share_safe import (
+    make_share_safe_payload,
+    render_share_safe_note,
+    render_share_safe_provenance,
+)
 from qcoder.explorer.derived_evidence import (
     ExplorerDerivedEvidenceRequestError,
     build_derived_evidence_request_from_context_json,
@@ -100,6 +106,13 @@ def _cmd_analyze(argv: list[str]) -> int:
         help="Include derived feature_profiles in JSON output (requires --json for analyze)",
     )
     p.add_argument("--json", action="store_true", help="Emit machine-readable JSON")
+    p.add_argument(
+        "--share-safe",
+        "--redact",
+        dest="share_safe",
+        action="store_true",
+        help="Redact local paths and sensitive runtime details in JSON output intended for sharing.",
+    )
     args = p.parse_args(argv)
 
     if args.profiles and not args.json:
@@ -120,9 +133,12 @@ def _cmd_analyze(argv: list[str]) -> int:
     )
 
     if args.json:
+        payload = report.to_json_dict(include_guidance=args.guidance, include_profiles=args.profiles)
+        if args.share_safe:
+            payload = make_share_safe_payload(payload)
         print(
             json.dumps(
-                report.to_json_dict(include_guidance=args.guidance, include_profiles=args.profiles),
+                payload,
                 indent=2,
                 sort_keys=True,
             )
@@ -131,7 +147,9 @@ def _cmd_analyze(argv: list[str]) -> int:
 
     ex = report.example
     rc = report.run_config
-    print(f"file: {ex.qasm_path}")
+    print(f"file: {'<redacted-local-path>' if args.share_safe else ex.qasm_path}")
+    if args.share_safe:
+        print("share_safe: true")
     print(f"format: {ex.ir.source_format}")
     if ex.name:
         print(f"name: {ex.name}")
@@ -218,6 +236,13 @@ def _cmd_context(argv: list[str]) -> int:
         action="store_true",
         help="Include full feature glossary/appendix in context artifacts (default: selected structural features only)",
     )
+    p.add_argument(
+        "--share-safe",
+        "--redact",
+        dest="share_safe",
+        action="store_true",
+        help="Write artifacts designed for safer sharing by redacting local paths and sensitive runtime details.",
+    )
     args = p.parse_args(argv)
 
     write_preflight_context(
@@ -229,9 +254,12 @@ def _cmd_context(argv: list[str]) -> int:
         include_full_features=args.full_features,
         circuit_id=args.circuit_id,
         circuit_name=args.circuit_name,
+        share_safe=args.share_safe,
     )
-    print(f"Wrote preflight context JSON to {args.out_json}", file=sys.stderr)
-    print(f"Wrote preflight context Markdown to {args.out_md}", file=sys.stderr)
+    json_label = "<redacted-local-path>" if args.share_safe else args.out_json
+    md_label = "<redacted-local-path>" if args.share_safe else args.out_md
+    print(f"Wrote preflight context JSON to {json_label}", file=sys.stderr)
+    print(f"Wrote preflight context Markdown to {md_label}", file=sys.stderr)
     return 0
 
 
@@ -248,17 +276,66 @@ def _cmd_review(argv: list[str]) -> int:
     p.add_argument("--preflight-json", default=None, help="Optional preflight context JSON path for linkage/checks")
     p.add_argument("--out-json", required=True, help="Output execution review JSON path")
     p.add_argument("--out-md", required=True, help="Output execution review Markdown path")
+    p.add_argument(
+        "--share-safe",
+        "--redact",
+        dest="share_safe",
+        action="store_true",
+        help="Write artifacts designed for safer sharing by redacting local paths and sensitive runtime details.",
+    )
     args = p.parse_args(argv)
 
-    write_execution_review(
-        counts_json=args.counts_json,
-        counts_format=args.counts_format,
-        preflight_json=args.preflight_json,
-        out_json=args.out_json,
-        out_md=args.out_md,
+    try:
+        write_execution_review(
+            counts_json=args.counts_json,
+            counts_format=args.counts_format,
+            preflight_json=args.preflight_json,
+            out_json=args.out_json,
+            out_md=args.out_md,
+            share_safe=args.share_safe,
+        )
+    except JSONDecodeError as exc:
+        print(
+            f"qcoder review: input JSON could not be parsed at line {exc.lineno}, column {exc.colno}. "
+            "Check that the counts/preflight file is UTF-8 JSON.",
+            file=sys.stderr,
+        )
+        return 2
+    except ValueError as exc:
+        print(
+            f"qcoder review: {exc}. For Qiskit counts, use --format qiskit_counts with a JSON object "
+            'like {"00": 10, "11": 6} or {"counts": {"00": 10, "11": 6}}.',
+            file=sys.stderr,
+        )
+        return 2
+    json_label = "<redacted-local-path>" if args.share_safe else args.out_json
+    md_label = "<redacted-local-path>" if args.share_safe else args.out_md
+    print(f"Wrote execution review JSON to {json_label}", file=sys.stderr)
+    print(f"Wrote execution review Markdown to {md_label}", file=sys.stderr)
+    return 0
+
+
+def _cmd_mcp(argv: list[str]) -> int:
+    p = argparse.ArgumentParser(
+        prog="qcoder mcp",
+        add_help=True,
+        description=(
+            "Local read-only qCoder MCP for Cursor. Uses explicit user-selected inputs only; "
+            "does not execute circuits, modify code, use tokens, or call live services."
+        ),
     )
-    print(f"Wrote execution review JSON to {args.out_json}", file=sys.stderr)
-    print(f"Wrote execution review Markdown to {args.out_md}", file=sys.stderr)
+    sub = p.add_subparsers(dest="mcp_command")
+    p_serve = sub.add_parser("serve", help="Serve qCoder tools over MCP stdio.")
+    p_serve.set_defaults(mcp_command="serve")
+    args = p.parse_args(argv)
+    if args.mcp_command is None:
+        p.print_help()
+        return 0
+    if args.mcp_command == "serve":
+        from qcoder.mcp.server import serve_stdio
+
+        return serve_stdio()
+    p.print_help()
     return 0
 
 
@@ -318,14 +395,20 @@ def _format_summary_value(value: str | int | float | bool) -> str:
     return str(value)
 
 
-def _print_raw_payload_json(payload: dict[str, object] | None) -> None:
-    print(json.dumps(payload or {}, indent=2, sort_keys=True))
+def _print_raw_payload_json(payload: dict[str, object] | None, *, share_safe: bool = False) -> None:
+    out = payload or {}
+    if share_safe:
+        out = make_share_safe_payload(out)
+    print(json.dumps(out, indent=2, sort_keys=True))
 
 
-def _write_json_payload(path: str, payload: dict[str, object] | None) -> None:
+def _write_json_payload(path: str, payload: dict[str, object] | None, *, share_safe: bool = False) -> None:
+    out = payload or {}
+    if share_safe:
+        out = make_share_safe_payload(out)
     out_path = Path(path)
     out_path.parent.mkdir(parents=True, exist_ok=True)
-    out_path.write_text(json.dumps(payload or {}, indent=2, sort_keys=True), encoding="utf-8")
+    out_path.write_text(json.dumps(out, indent=2, sort_keys=True), encoding="utf-8")
 
 
 def _is_scalar(value: object) -> bool:
@@ -468,6 +551,11 @@ def _render_student_evidence_markdown(payload: dict[str, object] | None) -> str:
         "# qCoder Explorer Beta Guided Evidence",
         "",
     ]
+    if payload and payload.get("share_safe") is True:
+        lines.append(render_share_safe_note().strip())
+        lines.append("")
+        lines.append(render_share_safe_provenance(payload).strip())
+        lines.append("")
     for line in _summarize_student_evidence_payload(payload):
         lines.append(f"- {line}")
     if payload:
@@ -490,10 +578,13 @@ def _render_student_evidence_markdown(payload: dict[str, object] | None) -> str:
     return "\n".join(lines)
 
 
-def _write_markdown_payload(path: str, payload: dict[str, object] | None) -> None:
+def _write_markdown_payload(path: str, payload: dict[str, object] | None, *, share_safe: bool = False) -> None:
+    out = payload or {}
+    if share_safe:
+        out = make_share_safe_payload(out)
     out_path = Path(path)
     out_path.parent.mkdir(parents=True, exist_ok=True)
-    out_path.write_text(_render_student_evidence_markdown(payload), encoding="utf-8")
+    out_path.write_text(_render_student_evidence_markdown(out), encoding="utf-8")
 
 
 def _run_student_builtin_review_check(
@@ -577,6 +668,7 @@ def _run_student_evidence_check(
     context_json_path: str | None = None,
     out_json: str | None = None,
     out_md: str | None = None,
+    share_safe: bool = False,
 ) -> int:
     request_payload: dict[str, object] | None = None
     if qasm_path and context_json_path:
@@ -618,11 +710,11 @@ def _run_student_evidence_check(
         return 2
 
     if json_output:
-        _print_raw_payload_json(response.payload)
+        _print_raw_payload_json(response.payload, share_safe=share_safe)
         if out_json:
-            _write_json_payload(out_json, response.payload)
+            _write_json_payload(out_json, response.payload, share_safe=share_safe)
         if out_md:
-            _write_markdown_payload(out_md, response.payload)
+            _write_markdown_payload(out_md, response.payload, share_safe=share_safe)
         return 0 if response.status_code == 200 else 1 if response.status_code in {401, 403} else 2
 
     if response.status_code == 200:
@@ -637,11 +729,11 @@ def _run_student_evidence_check(
         for line in _summarize_student_evidence_payload(response.payload):
             print(f"  {line}")
         if out_json:
-            _write_json_payload(out_json, response.payload)
-            print(f"  wrote_json: {out_json}")
+            _write_json_payload(out_json, response.payload, share_safe=share_safe)
+            print(f"  wrote_json: {'<redacted-local-path>' if share_safe else out_json}")
         if out_md:
-            _write_markdown_payload(out_md, response.payload)
-            print(f"  wrote_md: {out_md}")
+            _write_markdown_payload(out_md, response.payload, share_safe=share_safe)
+            print(f"  wrote_md: {'<redacted-local-path>' if share_safe else out_md}")
         return 0
     if response.status_code == 401:
         print(
@@ -724,6 +816,13 @@ def _cmd_explorer(argv: list[str], *, compatibility_alias: bool = False) -> int:
     )
     p_evidence.add_argument("--out-json", default=None, help="Write Explorer evidence response JSON.")
     p_evidence.add_argument("--out-md", default=None, help="Write Explorer evidence response Markdown.")
+    p_evidence.add_argument(
+        "--share-safe",
+        "--redact",
+        dest="share_safe",
+        action="store_true",
+        help="Write output artifacts with explicit share-safe metadata and local-sensitive details redacted.",
+    )
     p_evidence.set_defaults(explorer_command="evidence")
 
     args = p.parse_args(argv)
@@ -749,6 +848,7 @@ def _cmd_explorer(argv: list[str], *, compatibility_alias: bool = False) -> int:
             context_json_path=args.context_json,
             out_json=args.out_json,
             out_md=args.out_md,
+            share_safe=args.share_safe,
         )
 
     p.print_help()
@@ -1140,14 +1240,15 @@ def _cmd_pro(argv: list[str]) -> int:
 
 def _print_root_help() -> None:
     print(
-        "usage: qcoder [--version | -V] [-h] {analyze,batch,context,review,explorer,pro,student} ...\n\n"
+        "usage: qcoder [--version | -V] [-h] {analyze,batch,context,review,mcp,explorer,pro,student} ...\n\n"
         "Quantum circuit analysis CLI.\n\n"
         "positional arguments:\n"
-        "  {analyze,batch,context,review,explorer,pro,student}  subcommand\n\n"
+        "  {analyze,batch,context,review,mcp,explorer,pro,student}  subcommand\n\n"
         "  analyze          Analyze a QASM file (feature extraction + metadata + run config).\n"
         "  batch            Batch extract a directory to JSONL (requires --out).\n"
         "  context          Build deterministic preflight context artifacts.\n"
         "  review           Build deterministic execution review artifacts from counts.\n"
+        "  mcp              Serve local read-only qCoder tools for Cursor over MCP stdio.\n"
         "  explorer         Explorer Beta status/demo/evidence checks.\n"
         "  pro              Archived Pro client-contract shell (not current public product).\n"
         "  student          Compatibility alias for Explorer Beta checks.\n\n"
@@ -1179,6 +1280,8 @@ def main(argv: list[str] | None = None) -> int:
         return _cmd_context(rest)
     if cmd == "review":
         return _cmd_review(rest)
+    if cmd == "mcp":
+        return _cmd_mcp(rest)
     if cmd == "explorer":
         return _cmd_explorer(rest)
     if cmd == "pro":
@@ -1187,7 +1290,7 @@ def main(argv: list[str] | None = None) -> int:
         return _cmd_student(rest)
 
     print(
-        f"qcoder: unknown subcommand {cmd!r} (expected analyze, batch, context, review, explorer, pro, or student)",
+        f"qcoder: unknown subcommand {cmd!r} (expected analyze, batch, context, review, mcp, explorer, pro, or student)",
         file=sys.stderr,
     )
     print("Run `qcoder --help` for usage.", file=sys.stderr)

{qcoder-0.5.0a5 → qcoder-0.5.0a7}/src/qcoder/core/run_config.py

@@ -60,9 +60,15 @@ class RunConfig:
         )
 
     def to_dict(self) -> dict:
+        analysis_backend = "local_gpu" if self.backend == "GPU" else "local_cpu"
         return {
             "processor": self.processor,
             "backend": self.backend,
+            "analysis_backend": analysis_backend,
+            "local_analysis_backend": analysis_backend,
+            "backend_meaning": (
+                "local analysis backend; not a simulator, QPU, or hardware execution backend"
+            ),
             "precision": self.precision,
             "threshold": self.threshold,
         }