npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@aiconnect/matrix

v0.21.0

Published

AI Connect Matrix declarative application engine

Readme

AI Connect Matrix

Matrix 0.21.0 is an HTTP engine for self-contained declarative applications. The published engine knows only the S3 connection and the default app: apps and APIs are discovered by convention, with no catalog or configuration file on the server. The CLI and the stdio MCP use the same operational core.

Skills for agents

matrix-apps guides creating, editing and publishing apps via CLI or MCP: routes, redirects, templates, resources, assets and checking the result. The package includes on-demand references and three complete examples. It is the entry point for declarative authoring; the current dataset limit and the locale collision are documented in the references.

matrix-artifacts guides authoring collections of documents and reports as artifact collections ([email protected]). The catalog is the single source of truth for schemas, limits, blocks and codes; the skill routes documents and reports away from matrix-apps and into the matrix artifact command group or the remote app_artifact_catalog|read|publish tools.

matrix-extensions guides authoring Helpers and Modules with the CLI, starting with triage of requests that configuration can already solve. The package in skills/matrix-extensions/ includes the references and examples needed for authoring. matrix-plugins guides the development of engine plugins, with access to the Matrix code and tests: contract, per-installation configuration, effects, integration and consumption by an app. Reference: Matrix 0.10.0.

The skills can be used separately. They are maintained in this repository; the current npm distribution does not include skills/, and the MCP HTTP guide does not load these files automatically. Updating the package or the container does not update copies of skills already installed: updating them is a separate step, from this repository.

Cells fleet

The installation Compose includes celld 0.6.2, with a dedicated local working volume and bucket durability. Matrix 0.19.0 includes the event delivery client; the PollSession project is deployed separately by the operator. That guide covers the public proxy, private credentials, secret injection, deployment, recovery limits and the live proof. The M2 delivery record records production acceptance and the later review corrections.

Project language

English is the official language for authoring Matrix skills, documentation and code. New files — documents, skills, OpenSpec artifacts, reports and code, including comments, logs, diagnostics and help texts — are written in English. This README, AGENTS.md and the skills are already in English; most of docs/ is still in Portuguese: it is existing material, migrated file by file in changes of their own, without mixing languages in the same document. The content of applications and demo data follows the language of each app's audience. The full rules for agents are in AGENTS.md.

Runtime and stack

  • Node.js 24.20.0 LTS and npm 11.19.0;
  • strict TypeScript 6.0.3, ESM/NodeNext and build by tsc;
  • Fastify 5.12.3, Handlebars 4.7.9, Zod 4.5.4 and Pino 10.3.1;
  • markdown-it 15.0.2 (MIT, CommonMark with GFM tables) and yaml 2.9.1 (ISC, YAML 1.2 with positions), for artifact source parsing;
  • Ajv 8.20.0 (MIT), used only by the plugin catalog to check a reported operation input schema against the JSON Schema 2020-12 metaschema;
  • AWS SDK S3 v3 3.1127.0, MCP TypeScript SDK v2 2.0.0 and Supabase JS 2.116.0;
  • Vitest 5.0.0, ESLint 10.10.0/typescript-eslint 8.69.0 and Prettier 3.9.6.

The base image is node:24.20.0-bookworm-slim at manifest sha256:ba849c60be29959425b8734d57b8b4b7d56f98edd9504c9af091d5281095a71e, with linux/amd64 and linux/arm64/v8 variants. The demo's local S3 is MinIO RELEASE.2025-07-23T15-54-02Z, digest sha256:d249d1fb6966de4d8ad26c04754b545205ff15a62e4fd19ebd0f26fa5baacbc0.

Installation and gates

npm ci
npm run check

The separate gates are format:check, lint, typecheck, test and build. The automation in .github/workflows/check.yml uses the same Node/npm and runs npm ci + npm run check.

The npm package @aiconnect/matrix exposes matrix, matrix-mcp and matrix-remote-mcp; the core in dist/ is internal and the engine is distributed exclusively through the Docker image. A consumer pins the currently published npm version and its lockfile:

npm install --save-exact @aiconnect/[email protected]
npm exec matrix -- --version

The release artifact is generated by npm pack and checked before publishing to the registry. The prepack hook recompiles the code before generating the package. Do not use --ignore-scripts in the release. Publish the rehearsed tarball, without reusing files from previous releases. The package includes the files-demo application, its fixed interoperability vector and the users-auth reference administration application. Private applications, bundled dependencies, environment files and secrets stay outside the package. The generic Docker installation is in docs/entregas/matrix-dev-supabase-r4. It has one service, no app/fixture/authoring volume and does not assume an administrative token. No image is pushed to a registry by these commands.

The Matrix 0.18.0 release record tracks the corrected optional streaming release, its validation and verified Docker engine/remote MCP indexes. npm publication, production deployment and app migration remain separate.

The Matrix 0.17.0 release record tracks the Nexus Messaging plugin release for Docker engine/remote MCP and GitHub. That cut excluded npm publication and production deployment.

The Matrix 0.13.0 release receipt records the published GitHub release, engine and remote MCP images for AMD64/ARM64, and verified latest digests. CLI/npm @aiconnect/[email protected] was also published and verified as part of that release; its receipt preserves the distribution state at that time. The public archive is byte-identical to the tested package.

The independent CLI setup usability proof records the fresh-installation and legacy-project journeys on the merged source of 2026-09-30, including the tested package, participant answers and limits of the result.

App format

A minimal app needs no resources, APIs or error pages:

apps/hello/
  config.json
  templates/home.html

When the app queries an API, the declaration belongs to the app itself:

apps/blog/
  apis.json
  config.json
  templates/home.html

apis.json maps IDs to {type:"generic", serverUri, accessTokenEnv?}. serverUri can be a URL or an object with a mandatory default and per-environment specializations. Tokens remain only in MATRIX_API_*.

The package/revision includes config.json, apis.json and all non-hidden content of templates/, helpers/, modules/, resources/, datasets/ and public/. .env, hidden directories, tests/ and files outside these conventions are not included. .matrixignore allows explicit glob exclusion and generates a warning that also appears in the publish result. dynamicTemplateIds is accepted only as an obsolete field; conventional templates are already included by default.

Plugins, actions and asynchronous output (Change add-runtime-plugins)

The engine loads an in-code plugin registry (markdown, llm, interest, files, hooklog, nexus-messaging, skillsafe, cells, auth). An app activates plugins through a plugin rule in config.json and declares actions through an action rule; applications without these rules keep the previous behavior. Structural validation does not invoke plugins; availability at the destination is checked by publishing, before any mutation (E_PLUGIN_UNAVAILABLE, E_CONFIG_INVALID naming the destination, W_PLUGIN_AVAILABILITY_UNKNOWN when the destination does not respond).

The Hooklog plugin guide covers public POST submissions, installation credentials, destination selection and capture outcomes. It requires a compatible Hooklog service.

The SkillSafe plugin guide covers anonymous skill ZIP downloads and version metadata through application routes, the installation public URL and per-app override, bounded provider reads, and offline previews. See the runnable example.

The cells guide covers plugin events and signed cell delivery. Operators must configure MATRIX_CELLS_URL and MATRIX_CELLS_SECRET per target environment before publishing a cells application. The relay has bounded retries and no queue; follow-ups still expire by inactivity and disappear on restart.

User authentication by namespace (Change add-auth-namespaces)

The auth plugin supplies login, logout, invitations, sign-up, confirmation, password recovery and profile names. Accounts live in CellD namespaces shared by applications. Each application issues its own session cookie and enables its self-service operations explicitly. Sign-up also requires allowSignup on the namespace. A module calls auth.session to decide whether to serve a private page and how to handle an unavailable directory.

The auth guide covers the authorization matrix, installation settings, session windows, bootstrap, recovery and rollout. Application authors can start from the auth reference and the complete example returned by matrix plugins auth or app_plugin_read. The users-auth application manages namespaces and users under an administrator session in the reserved admin directory.

The host-owned context.cells.call bridge lets operation and service contexts make a signed, plugin-scoped request to the fleet. It makes one attempt within MATRIX_CELLS_CALL_TIMEOUT_MS (2,000 ms by default), using the eight-slot gate shared with event deliveries. A full gate returns capacity immediately. Auth uses this bridge for directory reads and writes. Confirmed actions can carry session cookies and a message, including a stored-record notice after an email delivery failure.

Plugin catalog (Change add-plugin-discovery-and-guidance)

Each plugin carries an authoring guide, src/plugins/<pluginId>.guide.json, which the engine validates at startup and publishes with its registry at GET /__admin/plugins, next to the generated input schema of each operation, the engine version and its default limits. A guide the engine finds invalid is withheld with one log warning; the plugin stays registered. The catalog of one target is read the same way on every surface, through one core:

  • CLI: matrix plugins [--environment <name>] lists the plugins the target registers — version, contract version, name and summary, capabilities with their effects, guide status and operator preparation; matrix plugins <pluginId> [--environment <name>] shows how to activate and use one plugin: the activation to merge, the options with their schema and documentation, the framework limits, each capability with its invocation context, complete examples and the operator prerequisites. The environment defaults to the first declared one other than local, and the administrative credential is MATRIX_ADMIN_TOKEN. --json prints the operation envelope of the MCP tools; the list also keeps its earlier plugins, unusable and error members.
  • Local MCP server: app_plugin_list and app_plugin_read.
  • Remote MCP: app_plugin_list and app_plugin_read, with a target taken from app_list, for any identity that may see that target; no application capability and no execute are needed.

The journey: list, read the detail, merge the plugin into the application's single plugin rule (never a second rule), use the capabilities in their documented contexts, validate and publish. The catalog reports what the target registered when it was read; publication reads the registry again. Registered is neither activated nor ready: operator prerequisites are described, never verified, and nothing runs to produce the catalog. An unavailable registry (E_ENGINE_UNREACHABLE with its reason), a plugin the target does not register (E_PLUGIN_UNAVAILABLE) and a member the client cannot read (W_PLUGIN_AVAILABILITY_UNKNOWN) are never an empty catalog; a guide that is absent, invalid or unsupported warns W_PLUGIN_GUIDE_UNAVAILABLE and the technical facts remain.

The independent remote MCP proof records a fresh agent discovering and activating Markdown, validating and publishing a new app to verified on the merged source, with retained calls and independent HTML/Markdown checks.

Default limits (unit: ms, bytes, calls)

| Limit | Default | Configurable through | | -------------------------------------- | -------------------- | ----------------------------------------------- | | Duration of an external call | 10000 ms | limits.callDurationMs in the plugin options | | Input size of an invocation | 32768 bytes | limits.inputSizeBytes | | Plugin invocations per render | 20 | limits.invocationsPerRender | | Concurrent external calls per instance | 8 | limits.concurrentCalls | | HTTP action body | 65536 bytes | limits.bodyBytes of the action rule | | llm plugin cache TTL | 3600 s (maximum) | ttlSeconds | | Cache ceiling per plugin | 500 entries or 8 MiB | limits.cacheMaxEntries/limits.cacheMaxBytes | | Queries a module requests per render | 3 | engine options | | Combined query ceiling per render | 8 | engine options | | Open event streams per plugin instance | 200 | engine constant; apps cannot set | | Event stream heartbeat after silence | 15000 ms | engine constant; apps cannot set | | Event stream maximum duration | 600000 ms | engine constant; apps cannot set | | Event stream reconnection hint | 3000 ms | engine constant; apps cannot set |

An exceeded limit produces E_LIMIT_EXCEEDED naming the limit, the value and the plugin, and follows the failure policy: error by default, alternative content only in the invocation that declares fallback. Operations with effects are not cached, do not coalesce and have no automatic retry; an unknown outcome is E_RESULT_UNCERTAIN with its own status.

Asynchronous output, escaping and envelope

Plugin helpers can return a Promise; the resolved result is inserted at the exact point of the occurrence (loops and partials included), always as escaped text. Uses outside the contract — block condition, subexpression/argument of another helper, the unescaped {{{ }}} form — are refused by an AST scan during validation and before compilation. The invocation option output="html" inserts an HTML fragment sanitized by default (scripts, handlers and javascript:/data: script schemes removed, preserving the markup authored in the template); raw=true in the same invocation inserts it without sanitization — a per-use option, with no global switch, and the author is responsible for what runs on the application's origin.

Actions respond with JSON (JSON body or Accept preference) or with the declared HTML outcome (onSuccess accepts a redirect; onFailure/onUncertain name a content rule). When an outcome renders, the template receives the _action envelope at the root of the binding — rule name, outcome class, cause code and class, per-field errors, the record identifier and an optional message when confirmed —, written by the engine, absent outside an outcome and not overridable. Capabilities with effects are refused with E_NOT_AUTHORIZED outside the action flow (rendering, preview, onRender and rendered outcome); query, conversion and prompt remain available during rendering. The complete example is in apps/plugins-demo/.

Plugin installation configuration

Each plugin consumes its configuration from its own file, discovered by convention from the registered plugins that declare fields — the existence of a directory or file neither installs nor activates any plugin:

/opt/matrix/plugins/<plugin_id>/.env

MATRIX_PLUGINS_CONFIG_DIR is the only variable that replaces the root; a relative path resolves against the process's working directory, like MATRIX_APPS_DIR. Fields per integration:

| Plugin | Fields (all optional) | | ---------- | ------------------------------------------------------------------------------------ | | llm | MATRIX_PLUGIN_LLM_ENDPOINT, MATRIX_PLUGIN_LLM_API_KEY, MATRIX_PLUGIN_LLM_MODEL | | interest | MATRIX_PLUGIN_INTEREST_DATABASE_URL, MATRIX_PLUGIN_INTEREST_ADMIN_TOKEN | | markdown | none — no file is derived, opened or diagnosed for it |

The auth installation fields cover bootstrap, SendGrid, cookie and proxy policy, and session windows. Their names, defaults and injection points are listed in the auth operator settings.

The interest plugin also needs its registration table in that database, which it does not create: create it with the definition the plugin exports as INTEREST_DDL, reproduced in the operator guide. Without it, every registration fails definitively with E_CONFIG_INVALID and stores nothing.

Per-field precedence. A name defined in the process environment wins over the file — even with an empty value: MATRIX_PLUGIN_LLM_API_KEY="" cancels the secret from the file. A name absent from the process comes from the file; absent from both, it stays absent. The engine does not write to process.env and does not read a general .env: orchestrator interpolation, values injected into the process and the .env that the CLI and the stdio MCP read are distinct mechanisms. The credentials of the APIs that the app declares (accessTokenEnv in apis.json) still come from the process environment and not from this tree. Partial configuration is not an error: what is missing fails at the moment of use with the usual codes (E_CREDENTIALS_MISSING, refusal of the protected action).

Accepted and refused constructs. The file is read by a dedicated parser in a single pass, and the value delivered is what the line says. Accepted: blank lines, # comments, NAME=value assignments (with optional export), values in single quotes, in backticks or unquoted, a comment after the value, spaces and tabs at the ends and around =, CRLF and a last line without a line break. A value with a backslash — a password, for example — goes in single quotes or backticks, or unquoted; never in double quotes, where the backslash is refused because readers of this format disagree on what the line means (\n would become a real line break for some). There is no way to embed a line break in a value. Refused, naming path, line and rule without reproducing the value: a line without =; a name outside the pattern; a quote closing on another line or never closed (which would swallow the next assignment); a backslash inside double quotes; content after the closing quote; a # attached to an unquoted value (it would silently truncate the password); a carriage return in the middle of the line; a repeated name. A field not declared by the plugin — including a field of another plugin or of the engine itself, such as MATRIX_S3_*, MATRIX_PORT or MATRIX_ADMIN_TOKEN — refuses startup naming the field, without changing connection, port, token or log level.

The empty-value trap. Declaring the variable in the orchestrator or in an example as ${VAR:-} or VAR= defines it as empty — and by precedence the file is cancelled: startup without any diagnostic and E_CREDENTIALS_MISSING at use, with the secret visible in the file. The variable either receives a real value or is not declared. Cheap way out of a refused startup: fix or remove the offending file, or point MATRIX_PLUGINS_CONFIG_DIR to a directory without it — without changing versions.

Applied on restart. The configuration is resolved once per engine instance, before serving; changing a file or variable while the process is running changes no integration. The cycle is: edit the mounted file, restart the container, check. There is no file watching and no hot reload.

Mounting. The tree belongs to the operator: mount it read-only at /opt/matrix/plugins, which is the path inside the container — the host source is the left side of the volume, and in the delivered docker-compose.yml it is ./plugins-config (:ro). Prepare the same source that the volume mounts and set its permissions so it is readable by the node user (uid 1000). Symbolic links that resolve are followed in any component of the path — Kubernetes secret mounts are links; a link whose target does not exist is a broken reference and ends startup naming the component, never silently. The delivered compose forwards auth environment values when defined, and .env.example provides commented examples described in docs/auth-plugin.md. See docs/migration-plugin-instance-configuration.md for the adoption and rollback path.

Artifact collections (Change add-artifact-profile-authoring)

A collection of documents and reports — a report, a knowledge base, a set of reference pages — ships as a single Matrix application under a profile version: [email protected], the recommended version for new collections. [email protected] is withdrawn: a collection still pinned to the withdrawn version stays served, can be read, and adopts [email protected] with its sources and addresses. The author writes Markdown sources with a YAML front matter (id, title, summary, category) and a small set of fenced blocks (block callout, block metrics, block details, block artifact-list, block timeline, block bar-chart). The composer reads the sources, regenerates the pages that depend on them and produces a conventional Matrix package. The collection is one application; the content changes are revisions of that application; only an explicit adoption moves the pinned profile version.

Three remote tools cover the journey:

  • app_artifact_catalog — read-only. It returns the registered profile, the supported versions, the source format, the authoring targets and the codes. Call it first, in every session, before reading or editing.
  • app_artifact_read — reads the collection, and the exact source bytes of one artifact in the active revision. Keep the active revision; the next publication uses it as a precondition.
  • app_artifact_publish — accepts a creation (create: true), an update (expectedRevision) or an exclusive adoption (adoptProfile alone). dryRun: true validates the candidate without writing.

The CLI mirrors the same journey in matrix artifact catalog|read|publish, with the same --json envelope and the same precondition semantics. The catalog is the single source of truth for schemas, blocks, limits and codes; the skill and this README do not restate them. Author content may be in any language; declare it in the optional language field. Under [email protected] the interface texts (skip link, filter button, empty states, not-found page, callout tone labels, month names) follow that language, with an en and a pt-BR text set: a pt tag, pt-PT included, uses the pt-BR set and every other tag uses en.

[email protected] also reads without tool vocabulary: no profile signature, an index that lists documents directly when there are no categories, callouts with one heading, a timeline filter only when it changes the selection, and dates formatted for reading. A published collection changes only through an explicit adoption (adoptProfile, simulated first with dryRun), because the adoption changes what readers see.

The collection metadata of [email protected] accepts robots, an object with the two booleans index and follow, written as one robots directive on the index and on every document (the not-found page is always noindex). A creation without it stores { index: true, follow: true }, an update whose collection metadata omits it keeps the active policy, and returning to indexing takes an explicit { index: true, follow: true }. robots is an instruction to search engines, not access control: it does not restrict who can read the pages, the sources or the assets, and it does not make the collection private. Collections created or adopted under [email protected] are recorded in format matrix-artifact-collection/2; the 0.12.0 artifact tools answer E_COLLECTION_FORMAT_UNKNOWN on them and must be upgraded to edit them. See docs/migration-artifact-profile-0.2.0.md.

A collection whose marker is in the active revision is managed: conventional publications (app_publish, app_publish_changes, matrix publish and the local MCP app_publish) are refused with E_MANAGED_COLLECTION before any object is written. The artifact surface is the only path that updates a managed collection. Detection is bounded to the marker in the active revision (R-API-02): a writer that removes the marker leaves a conventional application; a writer that reproduces the exact composition is not distinguished; deleted originals are not recovered.

The remote app_artifact_publish queue holds only among calls served by one instance of the remote service per destination; the CLI, the local MCP server, older writers and other instances are external writers. Returning to a 0.10.0 tool keeps the collections served (they are conventional packages) but offers no artifact authoring and does not recognise the marker; sources stay readable through app_read_file.

See skills/matrix-artifacts for the full authoring flow and docs/remote-mcp-agent-guide.md#authoring-artifact-collections for the remote surface.

Client: CLI and MCP

Check your setup

matrix status is the documented, read-only way to answer "does my Matrix CLI work?". It runs in any directory, with or without an application, and reports:

  • the Matrix version;
  • the environment file it selected, step by step (explicit --env-file, project .env, personal file), with the reason each other step was not used;
  • whether matrix.json declares the environments or the conventions do, and the state of the administrative token;
  • per environment, every setting with its variable, its state (set, empty or unset) and its origin — values only for non-secret settings, never for credentials or tokens;
  • per environment, the outcome of each check: storage bucket access, the pointer read, engine liveness, administrative health and, with --path, the page check — each with the observed cause (HTTP status, provider error code, timeout or unreachable endpoint). The storage and engine requests of the diagnosis are bounded (5 seconds for storage, 2 seconds for the engine probes, 5 seconds for a page check), each attempted once.

It states what it did not verify: write permission to the storage, activation and publication are never verified by status, and a successful check is not permission to publish. When the storage answered and the engine did not — or the reverse — the output says which capability was observed and which was not. Without an application, status reads the active pointer of the first application under apps/, in lexical order, as a readability probe; it is labelled as a probe in the human output and reported with reason: "probe" in JSON.

Publication readiness is a separate check:

matrix publish <appId> --environment <name> --dry-run

The human output names this command as its next step, and matrix publish also reports in data.deliveryChange whether the publication would change the active asset delivery — including the case where the files are identical but the delivery base differs, which reactivates the same revision without uploading unchanged files.

matrix status never requires source, variable copying or a second command, and the JSON result (--json) carries the same facts in data.configuration, data.environments[].settings and data.environments[].checks.

Variable names: personal file, project file and matrix.json

A personal file serves several projects, so its variables are not renamed to satisfy one project. When an environment of matrix.json reads a variable that is unset while another configured name would provide the value — the legacy environment-specific form MATRIX_<ENV>_S3_* against the conventional MATRIX_S3_*, or the reverse — matrix status reports W_VARIABLE_NOT_REFERENCED, naming both names and the matrix.json field. Matrix does not substitute one variable for another: the correction is an explicit edit, either aligning the project's references with the names that are set, or setting the variables the project reads. A missing required variable still fails with E_CREDENTIALS_MISSING or E_PUBLIC_BASE_URL_MISSING naming the variable; on the CLI and the local MCP, the message also names the matrix.json field and routes to matrix status --environment <name>.

A matrix.json can be retired when it reproduces exactly what the conventions provide: a single published environment named as MATRIX_ENVIRONMENT resolves (default main), its references equal the conventional variable names, and the prefix, asset delivery, forcePathStyle and engine URL are the ones the conventional variables and defaults produce, with allowPublicRuntime false and no other specialization. A file that does not meet all of these conditions is not redundant; aligning one environment must not redirect another (each environment keeps reading its own names).

In the checkout itself, after npm run build:

node dist/entrypoints/cli.js validate hello --strict --json
node dist/entrypoints/cli.js preview hello / --include-html --json
node dist/entrypoints/cli.js publish hello --environment main --json
node dist/entrypoints/cli.js status hello --environment main --path / --json
node dist/entrypoints/cli.js plugins --environment main              # what the target registers
node dist/entrypoints/cli.js plugins markdown --environment main     # how to activate and use it

From a machine that does not have the application, the complete journey is list → read → edit → validate/publish → status (REQ-CE-04):

node dist/entrypoints/cli.js list --environment main            # what is published at the destination
node dist/entrypoints/cli.js read demo-hello --environment main --json
node dist/entrypoints/cli.js read demo-hello --environment main --into <project>/apps/demo-hello
node dist/entrypoints/cli.js validate demo-hello --project <project> --json
node dist/entrypoints/cli.js publish demo-hello --environment main --project <project> --json
node dist/entrypoints/cli.js status demo-hello --environment main --path / --json

list inventories what is published in the storage of each environment with a destination — it does not require apps/ or matrix.json, never presents an unavailable destination as empty and never queries the application over HTTP (health is confirmed with status --path). read reads the complete package of the active revision, verifies bytes, digests and the recomputed revision, and writes to disk only with --into, which materializes the package with the directory as the package root — the documented journey recovers into <project>/apps/<appId> and operates the project with --project. A recovered package is the published package of a revision, not the original Git repository: history, ignored files and local environment files are not part of it. A file left in apps/<appId>/ that the packaging rules include (conventional role, no segment starting with a dot, outside tests/, not excluded by .matrixignore) enters the next package and changes the revision; the others do not. The local application list of status comes from the project and says nothing about the destination; what inventories a destination is matrix list. The complete capability matrix across the CLI, the stdio MCP and the remote service — including the remote service's transitional divergences — is in docs/capability-matrix.md.

Concurrent read --into recoveries on one host coordinate through an exclusive lock keyed by its canonical destination path in the platform temporary directory. Use the same temporary-directory namespace for commands targeting the same directory. A caller waits up to 10 seconds; after admission, a read without --overwrite checks occupancy again. The lock spans retention, promotion and rollback, and is released on completion or an observed failure. An abruptly terminated process can leave its empty lock directory behind: the timeout diagnostic names it. Confirm no recovery into that destination is running before removing that lock directory. Keep surviving .matrix-read-* work areas under the destination; their promotion.json and retained originals remain available for inspection.

In a consumer with the dependency installed, the same commands use npm exec matrix -- ... or npm scripts, without an internal node_modules path. matrix --help, matrix <command> --help and matrix --version do not run an operation.

The CLI loads at most one environment file, in this order: --env-file <path> (resolved from the current directory and required to exist), <project>/.env and, exclusively in the CLI, the personal file $XDG_CONFIG_HOME/matrix/.env — or ~/.config/matrix/.env, when XDG_CONFIG_HOME is absent, empty or relative, using an absolute HOME or the home directory registered for the account. A project .env, even an empty one, rules out the personal file; different files are never combined; values from the process environment prevail over the chosen file, even as an empty string. This works the same in Fish, sh and MCP hosts, without source or set -a, and no value is shown. The human output reports the loaded path and only the names overridden. The absence of an automatic file is silent; a selected file that exists but cannot be read exits with code 2 naming the path. matrix-mcp reads --env-file and the project .env and does not use the personal file.

matrix.json is optional. Without it, the client discovers apps/, uses MATRIX_ENGINE_URL to reach the engine (default http://localhost:<MATRIX_PORT>, with port 3000) and offers local plus the destination named by MATRIX_ENVIRONMENT (default main) with MATRIX_S3_*. In this conventional destination, MATRIX_ASSET_DELIVERY selects direct or proxy and uses direct by default; MATRIX_PUBLIC_BASE_URL provides the public HTTP(S) base required in direct mode. The file remains useful only to specialize multiple environments. The name local is reserved for the folder source: MATRIX_ENVIRONMENT=local keeps only that environment in the client without a file and is refused when starting a published engine. matrix.json.apps is ignored with W_DEPRECATED; matrix.json.apis is refused with E_REFERENCE_MISSING and a hint pointing to apps/<appId>/apis.json.

In matrix.json, each destination accepts assetDelivery: "direct" | "proxy" and publicBaseUrlEnv. Omitting the mode selects direct; the variable named in publicBaseUrlEnv must contain an absolute HTTP(S) URL, without query or fragment. A missing or invalid base produces E_PUBLIC_BASE_URL_MISSING before creating the S3 client, uploading or activating a pointer. The hint indicates the expected variable and the alternative assetDelivery: "proxy". The S3 endpoint and the browser base are independent settings; no public URL is inferred from the endpoint.

publish accepts the optional guard --expected-revision, plus --dry-run, --check-path and --accept-status 200,302 or --accept-status 200-399. A publication becomes verified only when the engine returns the correct revision and the functional response passes. By default, a status below 500 passes; failure produces functional_failed, E_FUNCTIONAL_CHECK_FAILED and data.check, with the pointer already on the new revision. The result exposes the intent in data.requestedAssetDelivery. data.assetDelivery and data.urls.assets describe only the confirmed active delivery; both are null when there is no active publication or when the activation is unknown. In a conflict or a failure before activation, these fields keep describing the preserved pointer. The guard compares the active content revision to protect concurrent operators; it is not the Matrix package version and it is not mandatory in the normal flow.

data.destination identifies the sanitized endpoint, bucket and prefix in publish; status includes the same data per environment. In status, engine.reachable comes from the public /__live probe, while engine.admin reports whether /__admin/health responded. Inaccessible storage and unavailable admin are distinct warnings; implicit publication records are labeled as local history and do not confirm the current pointer.

The MCP advertises app_validate, app_preview, app_publish, app_status, app_delete, app_plugin_list and app_plugin_read. .mcp.json points to the checkout; in another project, configure the locally installed bin with node_modules/.bin/matrix-mcp --project /absolute/path [--env-file /path/.env]. The host's env block may contain non-secret settings such as MATRIX_LOG_LEVEL; the project .env provides the rest. stdout is exclusive to the protocol/JSON; logs go to stderr. The MCP schemas derive from the same Zod schemas as the CLI. Do not import or run internal paths under dist/ in consumers.

The matrix-remote-mcp executable offers a separate, authenticated surface with no filesystem access by the client. It advertises exactly app_list, app_read, app_files, app_read_file, app_validate, app_publish, app_publish_changes, app_status, app_delete, app_artifact_catalog, app_artifact_read, app_artifact_publish, app_plugin_list and app_plugin_read; it does not offer preview. To edit an existing application, app_files lists the files of the active revision without content, app_read_file reads one whole text file and app_publish_changes publishes only the named files: the service composes the candidate from the active revision and preserves every file the change set does not name, byte for byte. Each entry carries the digest the author read (expectedSha256), so a file changed since then conflicts with E_REVISION_CONFLICT, and repeating an identical change set is safe. Published binary files are preserved while no entry names them. Writes in app_validate, app_publish and app_publish_changes, including dryRun, carry exactly one of content for UTF-8 text and contentBase64 for complete bytes, only under public/. A deletion carries neither content field. Use canonical standard base64 with required padding and no data: prefix; ASCII space, tab, LF and CR are stripped, while URL-safe - and _ are refused. Text at known non-textual extensions or over an intact stored binary is refused; unknown extensions keep accepting text. For binary replacement, take expectedSha256 from app_files; an addition expects null. Successful text/binary write entries report final sha256 and bytes, including alreadyApplied and successful dry runs. Limits count decoded file/package bytes, with an independent HTTP body limit. Use inline base64 for icons and other files of a few KB. The practical size depends on the client and model; larger files may be slow to emit or emitted incorrectly. For those cases, prefer the CLI or an external URL. Compare the returned sha256 with the digest of the original file. Binary reading remains unavailable; app_read refuses binary reconstruction and points to app_files + textual app_read_file + app_publish_changes. Complete republication requires holding the binary bytes. The shared MIME map serves .webp and .avif as image/webp and image/avif on the next publication, including through the CLI. Version 0.20.0 is the release cut; distribution receipts are recorded in the release record. Deployment remains separate. app_publish remains the complete replacement, used to create an application or to replace it as a whole. Write coordination holds among the calls of a single service instance, so deploy one instance per destination; the CLI, the local MCP and other instances are external writers. Targets and destinations are resolved on the server, and the schemas do not accept endpoint, bucket, credentials or host paths. A valid identity from the configured issuer has full access by default; optional restrictions through grants limit access per application+target pair with the capabilities read, publish, delete and execute, and the listing describes the effective policy. The service delivers the public connection page at GET / and the Supabase consent at /oauth/consent, with a warning for self-registered clients; deletion derives its state from the final observation of the destination and resumes when the same call is repeated. See the agent guide, the operation and connection guide and the 0.6.0 migration.

Engine by conventions

The dist/entrypoints/engine.js process selects exactly one mode:

  • folder: MATRIX_APPS_DIR defined; local API environment and optional MATRIX_ROOT_APP;
  • published: MATRIX_S3_* connection defined; MATRIX_ROOT_APP required.

Mixing MATRIX_APPS_DIR and the S3 connection, omitting both or omitting a minimum input ends startup naming the variables. In published mode:

| Variable | Default | | --------------------------------------------------------------------------------------------------------------------- | ----------- | | MATRIX_S3_ENDPOINT, MATRIX_S3_BUCKET, MATRIX_S3_ACCESS_KEY_ID, MATRIX_S3_SECRET_ACCESS_KEY, MATRIX_ROOT_APP | required | | MATRIX_S3_REGION | us-east-1 | | MATRIX_S3_PREFIX | matrix | | MATRIX_ENVIRONMENT | main | | MATRIX_PORT | 3000 | | MATRIX_POINTER_TTL_SECONDS | 10 | | MATRIX_LOG_LEVEL | info | | MATRIX_ADMIN_TOKEN | unset |

GET /__live always responds {"ok":true}. Without a token, /__admin/* is unavailable, but pages and assets keep working; the publish invalidation produces W_INVALIDATE_FAILED and verification waits for the TTL. GET / redirects with 302 to the default app. An empty bucket returns 404 until the first publication. Valid IDs are looked up on demand and missing pointers are cached negatively.

The active pointer decides the delivery of published assets. In the default direct mode, _staticServer uses <publicBaseUrl>/<environment>/<appId>/assets/<revision>; in the explicit proxy mode it uses /_assets/<appId>/<revision>. The engine endpoint remains available in both modes and reads the authenticated S3, with the manifest type and Cache-Control: public, max-age=604800. Mutable assets from the folder source use Cache-Control: no-store. Mode and base are activated in current.json, without changing the revision's immutable manifest. Changing only mode/base reactivates the same revision without re-uploading identical objects.

0.2.0 pointers without assetDelivery keep the previous semantics: a present publicBaseUrl is interpreted as direct; an absent one as proxy. status shows the active delivery with assetsUrl, the configuration of the next publish and inherited: true when the choice came from this transition rule. HEAD resolves exactly like GET, with the same status and headers and no body; other methods remain 405.

API response cache

The engine serves API queries from a local, in-memory, per-instance cache. The boundary between the engine and the storage is asynchronous and replaceable at composition (ApiCacheProvider); the default provider is the local one below. There is no Memcached, no shared cache, no invalidation broadcast between replicas and no new external service: an installation that configures nothing keeps starting as before.

| Variable | Default | Rule | | ------------------------------ | ---------- | ------------------------------------------------------------------ | | MATRIX_API_CACHE_MAX_ENTRIES | 1000 | Integer ≥ 1; zero, a negative or a non-integer value ends startup. | | MATRIX_API_CACHE_MAX_BYTES | 33554432 | Integer ≥ 1; the startup failure names the variable and the rule. |

The defaults — 1000 entries and 32 MiB — are a sizing hypothesis, not a measurement: no memory limit is declared anywhere in the repository to anchor them. The two variables exist to correct the hypothesis without changing code. No value removes the ceiling.

Counted bytes are the exact sum of the stored text plus the entry name — a count of what the cache holds, not a heap or process RSS ceiling. The generation map stays outside this count, under its own ceiling (it reuses MATRIX_API_CACHE_MAX_ENTRIES).

Release of expired entries. The provider sweeps expired entries on two fronts: a small batch at each write and a fixed 60 s interval. An expired entry leaves even without a new query, and early discard (by ceiling or reclaim) is legitimate behavior. The routine ends with the engine. The worst case for an entry that an invalidation made unreachable is the declared TTL plus one sweep interval — and the TTL the application declares has no ceiling. Discard under pressure is by effective recency, not by validity: an old write that lands late may temporarily evict a useful entry; the effect is reduced capacity — never exceeding the ceiling, never serving a stale value.

Administrative invalidation. POST /__admin/cache/invalidate keeps responding 200 with {"ok":true,"app":...,"scope":...} when all portions of the scope complete. If any portion did not confirm, the response becomes 503 with {"ok":false,"error":"invalidate_incomplete","app":...,"scope":...,"completed":[...],"failed":[...]}. The invalidation took effect even when the reclaim did not confirm — no later query is served from the old value; the 503 reports the confirmation, not the effect. Whoever depends on a portion should judge it by completed, not by the aggregate status (the pointer scope, used by publishing, is not fallible today and never receives 503).

Deadlines. Cache operations have engine deadlines: 250 ms for lookup and write, 1000 ms for reclaim — a hypothesis anchored in the timeouts the product already declares (API query 10 s, pointer 10 s), not a measurement. The deadline is for waiting and reporting, not cancellation: a write reported as failed by deadline may land later — it lands on a name that no future query composes.

Render envelope and compatibility. The client tool does not need to be upgraded together. The per-query field with the cache outcome (cacheOutcome) is an on-request enrichment: the /__admin/render endpoint emits the field only when the request declares __cacheOutcome=true (this version's preview declares it). A previous CLI/MCP declares nothing, receives today's envelope field by field and keeps passing its own parser; engine and tool can be upgraded in any order. The four combinations: an old client against an old engine is today's behavior; an old client against a new engine receives today's envelope; a new client against an old engine sends the parameter, does not receive the field and the preview comes out complete (the field is optional); a new client against a new engine receives the per-query outcome. The limit that remains: a future field inside modules[] or errors[] is still refused by this version's client.

Actual reach. This delivery is not a distributed cache: there is no Memcached, no cache shared between replicas, no invalidation broadcast, the entry name is per instance at this stage, and the pointer, app, manifest and artifact caches remain without a budget.

Local demonstration

Installation and demonstration are separate flows. The demo keeps the mini-blog, the mock and MinIO:

docker compose -f examples/docker-compose.yml up --build -d --wait
cp .env.example .env
npm run build
npm run test:asset-delivery:s3
node dist/entrypoints/cli.js validate hello --json
node dist/entrypoints/cli.js publish hello --environment main --json
node dist/entrypoints/cli.js publish blog --environment main --json
curl http://localhost:3002/hello/
curl http://localhost:3002/blog/
docker compose -f examples/docker-compose.yml down

The same engine-main serves both without editing or restarting. apps/hello/apis.json and apps/blog/apis.json prove separate namespaces; the antesdadecisao mini-blog keeps the previous journeys. Only engine-local mounts apps/; engine-main reads the authenticated bucket.

Security, compatibility and migration

Extensions are trusted code and run in-process; there is no sandbox. Helpers/modules accept the documented CommonJS forms, without implicit symbols or per-app npm dependencies. Handlebars keeps escaping by default; deliberate HTML uses {{{ }}}.

The destination default keeps a private runtime and public assets. allowPublicRuntime: true preserves the explicit D-029 exception and emits exactly one W_PUBLIC_RUNTIME; it neither creates a bucket/policy nor exposes credentials. The Supabase integration uses separate S3 endpoint and public HTTP base settings.

0.2.0 does not run 0.1.0 artifacts under any compatibility promise. Adapt and republish; do not edit old releases. To update asset delivery, see docs/migration-0.3.0.md; the previous migration remains in docs/migration-0.2.0.md. To distribute the tools, see docs/migration-0.4.0.md; for remote authoring, docs/migration-0.5.0.md; for default access, deletion and the public page, docs/migration-0.6.0.md. See also CHANGELOG.md.

Publishing and removals (0.9.0)

The published package replaces the complete application. The CLI and the local MCP refuse omitted active files, including in the dry run, without upload or activation. Recover missing files with matrix read, or acknowledge intentional removals with matrix publish --allow-removals (allowRemovals: true in local app_publish). The remote MCP keeps its existing protection. The comparison reflects the active revision as read; it is not a lock. --expected-revision checks the pointer at the start and narrows, but does not eliminate, the concurrent activation window. Confirm uncertain activations with matrix status. See the migration.

Files plugin

The bundled files plugin adds bounded JSON/Base64 uploads to a dedicated S3 bucket, public downloads and per-file capability deletion. Start with the operator and authoring guide, the encrypted envelope format, and the complete browser example. Delivery evidence distinguishes local verification from deployment.

Named file downloads

The bundled files plugin 1.1.0 accepts an optional public fileName for plain uploads and serves new plain objects with their declared MIME. Keys remain unchanged; old clients and encrypted uploads remain supported. See the files operator guide for validation, immutable-name reconciliation, CORS and rollout requirements. This source change does not constitute a new engine release.

Nexus messaging plugin

The bundled nexus-messaging 1.1.0 plugin receives signed Nexus webhooks and serves a bounded memory buffer to browser tabs through polling or optional server-sent events. Polling remains the default; stream mode requires a verified public proxy path. See the operator guide, demo and delivery record. Requires a single engine instance. Matrix 0.18.0 distributes it; activation of streaming in published applications requires its own public-path trial.