Skip to content

v0.1.7

Choose a tag to compare

View all tags
@ruslanmv ruslanmv released this 12 Sep 10:33
· 10 commits to master since this release
v0.1.7
62e53f4

Matrix CLI — v0.1.7 Release Notes

This release focuses on reliable local installs, clearer diagnostics, and first-class support for MCP connectors. It pairs with the SDK improvements (v0.1.10) so the CLI “just works” on fresh machines—especially on macOS.

Highlights

  • Auto-clone from manifest
    When the Hub plan returns artifacts: [], the CLI (via the SDK) now discovers repositories from the manifest and clones them by default. No extra flags required.

  • Smarter runner discovery
    The install path can now source a runner from:

    • runner_b64 / runner_url on the plan (relative URLs resolved against provenance).
    • Embedded runner objects.
    • Embedded manifests (direct runner or v1 server URL → connector).
    • An existing runner.json (including shallow search).
    • MCP registration (synthesizes a connector when a server.url is present).

  • Hardened networking (great on macOS)
    HTTP fetches prefer the OS trust store via truststore, with a certifi fallback. Fewer TLS surprises; better behavior behind corporate proxies.

  • Actionable logs & UX
    Consistent INFO/DEBUG logs across install, run, ps, logs, doctor, and stop. You’ll see what was planned, what was fetched, and why a path was taken.

New

  • install auto-discovers repo(s) from:

    • repository / repositories in manifest (embedded or fetched from provenance).
    • Lockfile provenance (when the Hub embeds a source_url).

  • Connector synthesis when the plan/manifest includes an MCP server:

    • The CLI will generate a minimal connector runner.json if needed, so run can attach to the remote SSE endpoint immediately.

  • GitHub URL normalization:

    • github.com/.../blob/<branch>/path → raw.githubusercontent.com/.../<branch>/path
    • raw.githubusercontent.com/.../refs/heads/<branch>/path → .../<branch>/path

  • Safer git defaults:

    • If no ref is provided in the manifest, we omit it and let git use the repository’s default branch (no more forced master).

Changed

  • Errors during artifact fetch are now surfaced as typed failures (propagated from the SDK), yielding clearer messages instead of silent skips.

  • Deterministic runner discovery order with explicit, per-strategy logging (so you can tell which strategy produced your runner.json).

  • Consistent command messages:

    • install prints plan/installer summaries.
    • run clearly distinguishes local processes vs. connectors (pid 0).
    • doctor summarizes status and common misconfigurations.

Fixed

  • Situations where no repos were cloned because the Hub didn’t enumerate artifacts.
  • Relative runner_url not resolving against provenance in certain plans.
  • Logs that previously contained stray format placeholders or unhelpful messages.
  • TLS trust issues on macOS when fetching manifests/runners from GitHub.

Quality-of-Life

  • Better defaults: shallow search for runner.json skips node_modules, .venv, .git, __pycache__.
  • Atomic writes for runner.json; traversal-safe path handling when writing files.
  • More helpful logs and ps outputs for connectors (clearly shows “no local process”).

Environment variables & Flags

Advanced tuning (the CLI passes these through to the SDK):

  • MATRIX_SDK_DEBUG=1 — verbose DEBUG logs in CLI + installer pipeline.
  • MATRIX_SDK_HTTP_TIMEOUT=15 — fetch timeout (seconds).
  • MATRIX_SDK_MANIFEST_DOMAINS — allow-list for manifest fetches
    e.g. raw.githubusercontent.com,github.com,codeload.github.com
  • MATRIX_SDK_ENABLE_CONNECTOR=1 — enable connector synthesis strategies (default on).
  • MATRIX_SDK_RUNNER_SEARCH_DEPTH=2 — depth for shallow runner.json search.

Common flags remain unchanged (e.g., --alias, --target). No breaking CLI flag changes.

macOS Notes

  • Uses macOS system trust (Keychain) via truststore when available, with certifi fallback.
  • Atomic file operations are APFS-friendly.
  • Shallow directory scanning avoids heavyweight folders during discovery.

Upgrade Guide

  • No breaking changes to CLI commands.
  • If your manifests previously omitted ref, that’s now fine—the default branch will be used automatically.
  • To debug installs, export MATRIX_SDK_DEBUG=1 and re-run install; logs will pinpoint planning, repo discovery, and runner selection.

Known Limitations

  • Connector mode (pid=0) intentionally does not spawn a local process. logs will be empty unless your connector server emits logs elsewhere.
  • If you restrict MATRIX_SDK_MANIFEST_DOMAINS, ensure any provenance URLs are included—or repository discovery via manifest fetch will be skipped.

Thanks

Big thanks to folks who reported empty artifacts / no-clone issues, relative URL edge cases, and macOS truststore hiccups—your reports shaped this release.

—

v0.1.7 makes the CLI more forgiving, more transparent, and much easier to use on fresh machines. If you hit anything odd, run with MATRIX_SDK_DEBUG=1, capture the output of install → run → doctor, and share it—we’ve made the logs specifically to speed up troubleshooting.

Assets 4
Loading