@xova/matrix 0.1.0-rc.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xova
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,198 @@
+# @xova/matrix
+
+Configuration-driven CLI for running and packaging multi-app workspaces.
+
+English · [简体中文](README.zh-CN.md)
+
+Define projects once, then run development, builds, previews, and custom commands by product and environment.
+
+## Features
+
+- Typed configuration for projects, products, variants, and targets
+- Built-in `dev`, `build`, and `preview` targets
+- Target dependencies with `ready` and `completed` conditions
+- `development`, `staging`, and `production` environments
+- Custom environment names such as `qa` and `uat`
+- Layered environment variables with dotenv and shell overrides
+- Interactive product and environment selection
+- Optional build archives under `artifacts`
+
+## Install
+
+Requires Node.js `>=22.18.0`.
+
+```bash
+pnpm add -D @xova/matrix
+```
+
+## Quick start
+
+Create `matrix.config.ts` in the workspace root:
+
+```ts
+import { defineMatrixConfig, defineMatrixEnv } from '@xova/matrix'
+
+export default defineMatrixConfig({
+  projects: {
+    web: {
+      root: './apps/web',
+      targets: {
+        dev: 'vite',
+        build: { command: 'vite build', archive: true },
+        preview: 'vite preview',
+      },
+    },
+  },
+  products: {
+    app: {
+      variants: { web: 'web' },
+    },
+  },
+})
+```
+
+Run it from the directory containing the config file:
+
+```bash
+matrix dev app
+matrix build app --env staging
+matrix plan app --target preview --env production
+matrix doctor
+```
+
+When `product`, target, or `--env` is omitted in an interactive terminal, Matrix prompts for a selection. Interactive selection follows Product → Variant → Target → Environment, and one run selects a single Product. Use `--product` and `--target` to provide explicit selections without relying on positional argument order.
+
+See [`examples/basic`](examples/basic/README.md) for a self-contained example that runs without a framework dependency.
+
+## Configuration
+
+| Concept | Purpose                                                         |
+| ------- | --------------------------------------------------------------- |
+| Project | An application directory and its commands                       |
+| Product | A runnable deliverable composed of variants                     |
+| Variant | A product entry bound to a project                              |
+| Target  | A command such as `dev`, `build`, `preview`, or a custom target |
+
+### Multiple variants
+
+A product can run more than one project and express dependencies per target:
+
+```ts
+export default {
+  products: {
+    app: {
+      variants: {
+        web: 'web',
+        desktop: {
+          project: 'desktop',
+          targets: {
+            dev: { dependsOn: [{ variant: 'web', condition: 'ready' }] },
+            build: { dependsOn: [{ variant: 'web', condition: 'completed' }] },
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+`ready` is useful for continuous targets such as `dev`; `completed` is useful for one-shot targets such as `build`.
+
+### Environments
+
+Use top-level `env` and `$env` for values shared by all products. Put product-specific values under the product when different products assemble the same projects with different backends:
+
+```ts
+export default defineMatrixConfig({
+  projects: {},
+  products: {
+    app: {
+      appId: 'com.example.app',
+      env: { VITE_API_BASE: 'http://localhost:3000' },
+      $env: defineMatrixEnv({
+        staging: { VITE_API_BASE: 'https://staging-api.example.com' },
+        production: { VITE_API_BASE: 'https://api.example.com' },
+      }),
+      variants: {},
+    },
+  },
+})
+```
+
+`defineMatrixEnv()` is syntax sugar for the c12-compatible `$env.<environment>.env` shape. The raw shape remains supported.
+
+Values are merged from low to high precedence:
+
+```text
+global env/$env < product env/$env < .env layers < process.env < MATRIX_*
+```
+
+Product-level environment values are resolved independently for each product. This lets two products reuse the same Desktop project while connecting it to different Web variants or services.
+
+Custom environment names are supported. Define them with the same helper and pass the name explicitly to the CLI:
+
+```ts
+export default defineMatrixConfig({
+  $env: defineMatrixEnv({
+    qa: {
+      VITE_API_BASE: 'https://qa-api.example.com',
+    },
+  }),
+  projects: {},
+  products: {},
+})
+```
+
+```bash
+matrix build app --env qa
+matrix plan app --target preview --env qa
+```
+
+Custom environments are available through `--env`. When running interactively, Matrix adds names found in the top-level and product `$env` configuration to the selector.
+
+Dotenv files are loaded as `.env`, `.env.local`, `.env.<environment>`, and `.env.<environment>.local`. Matrix passes variables such as `VITE_*` and `NUXT_*` to child processes; application frameworks keep ownership of their own runtime configuration.
+
+## Targets and defaults
+
+The built-in targets use these defaults:
+
+| Target    | Environment   | Continuous |
+| --------- | ------------- | ---------- |
+| `dev`     | `development` | Yes        |
+| `build`   | `production`  | No         |
+| `preview` | `production`  | Yes        |
+
+Custom targets are non-continuous by default and use `development` unless `--env` is provided. Project roots default to `.`, target output directories default to `dist`, and archive output defaults to `artifacts`. Archives are disabled by default, are only valid for the build target, and use zip when enabled. A configured archive fails the build when its output directory does not exist.
+
+Interactive Variant selection comes before Target selection. Target options are derived from the common targets available to the selected Variants; use `--variant` to provide the scope in non-interactive runs.
+
+Any configured target can be invoked from the CLI. `test`, `lint`, and `e2e` are common custom targets.
+
+## Commands
+
+```text
+matrix [target] [product] [--variant name] [--env <environment>]
+matrix --product <product> [--target <target>] [--variant name] [--env <environment>]
+matrix dev [product]
+matrix build [product] [--env <environment>] [--archive]
+matrix preview [product] [--env <environment>]
+matrix plan [product] [--target <target>] [--env <environment>]
+matrix doctor
+matrix <custom-target> [product] [--env <environment>]
+```
+
+## Development
+
+Dependency versions are maintained in the pnpm catalog in `pnpm-workspace.yaml`.
+
+```bash
+pnpm install
+pnpm check
+pnpm lint:fix
+```
+
+`pnpm lint:fix` formats JavaScript, TypeScript, and Markdown through ESLint. `pnpm check` runs lint, typecheck, tests, and the production build.
+
+## License
+
+[MIT](LICENSE)

package/README.zh-CN.md

@@ -0,0 +1,198 @@
+# @xova/matrix
+
+面向多应用工作区的配置驱动 CLI。
+
+[English](README.md) · 简体中文
+
+只需定义一次项目，就可以按产品和环境运行开发服务、构建、预览和自定义命令。
+
+## 特性
+
+- 使用类型安全的配置描述项目、产品、变体和目标
+- 内置 `dev`、`build` 和 `preview` 目标
+- 支持带有 `ready` 和 `completed` 条件的目标依赖
+- 内置 `development`、`staging` 和 `production` 环境
+- 支持 `qa`、`uat` 等自定义环境名称
+- 支持 dotenv 和 Shell 覆盖的分层环境变量
+- 支持交互式选择产品和环境
+- 支持将构建结果归档到 `artifacts`
+
+## 安装
+
+需要 Node.js `>=22.18.0`。
+
+```bash
+pnpm add -D @xova/matrix
+```
+
+## 快速开始
+
+在工作区根目录创建 `matrix.config.ts`：
+
+```ts
+import { defineMatrixConfig, defineMatrixEnv } from '@xova/matrix'
+
+export default defineMatrixConfig({
+  projects: {
+    web: {
+      root: './apps/web',
+      targets: {
+        dev: 'vite',
+        build: { command: 'vite build', archive: true },
+        preview: 'vite preview',
+      },
+    },
+  },
+  products: {
+    app: {
+      variants: { web: 'web' },
+    },
+  },
+})
+```
+
+在包含配置文件的目录中运行：
+
+```bash
+matrix dev app
+matrix build app --env staging
+matrix plan app --target preview --env production
+matrix doctor
+```
+
+在交互式终端中，如果省略产品、目标或 `--env`，Matrix 会提示选择。交互式选择顺序为 Product → Variant → Target → Environment，一次运行只选择一个 Product。可以使用 `--product` 和 `--target` 显式指定选择，避免依赖位置参数顺序。
+
+完整的可运行示例见 [`examples/basic`](examples/basic/README.md)，它不依赖具体前端框架。
+
+## 配置
+
+| 概念    | 作用                                   |
+| ------- | -------------------------------------- |
+| Project | 应用目录及其命令                       |
+| Product | 由多个变体组成的可运行交付物           |
+| Variant | 绑定到项目的产品条目                   |
+| Target  | `dev`、`build`、`preview` 或自定义目标 |
+
+### 多变体
+
+一个产品可以运行多个项目，并为不同目标声明依赖：
+
+```ts
+export default {
+  products: {
+    app: {
+      variants: {
+        web: 'web',
+        desktop: {
+          project: 'desktop',
+          targets: {
+            dev: { dependsOn: [{ variant: 'web', condition: 'ready' }] },
+            build: { dependsOn: [{ variant: 'web', condition: 'completed' }] },
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+持续运行的 `dev` 适合使用 `ready`，一次性执行的 `build` 适合使用 `completed`。
+
+### 环境
+
+所有产品共享的变量放在顶层 `env` 和 `$env`。如果不同产品复用相同项目但连接不同后端，则将产品专属变量放在产品内部：
+
+```ts
+export default defineMatrixConfig({
+  projects: {},
+  products: {
+    app: {
+      appId: 'com.example.app',
+      env: { VITE_API_BASE: 'http://localhost:3000' },
+      $env: defineMatrixEnv({
+        staging: { VITE_API_BASE: 'https://staging-api.example.com' },
+        production: { VITE_API_BASE: 'https://api.example.com' },
+      }),
+      variants: {},
+    },
+  },
+})
+```
+
+`defineMatrixEnv()` 是 c12 兼容的 `$env.<environment>.env` 写法的语法糖，底层结构仍然保持不变，也继续支持直接使用原始写法。
+
+变量覆盖优先级从低到高为：
+
+```text
+global env/$env < product env/$env < .env layers < process.env < MATRIX_*
+```
+
+产品级环境变量会为每个产品独立解析。这样多个产品可以复用同一个 Desktop 项目，同时连接不同的 Web 变体或服务。
+
+支持自定义环境名称。使用相同的 helper 定义，并在 CLI 中显式传入环境名：
+
+```ts
+export default defineMatrixConfig({
+  $env: defineMatrixEnv({
+    qa: {
+      VITE_API_BASE: 'https://qa-api.example.com',
+    },
+  }),
+  projects: {},
+  products: {},
+})
+```
+
+```bash
+matrix build app --env qa
+matrix plan app --target preview --env qa
+```
+
+自定义环境可以通过 `--env` 使用。交互式运行时，Matrix 会将顶层和产品级 `$env` 中声明的环境名加入选择器。
+
+dotenv 文件按 `.env`、`.env.local`、`.env.<environment>` 和 `.env.<environment>.local` 加载。Matrix 会将 `VITE_*`、`NUXT_*` 等变量传递给子进程，应用框架继续负责自己的运行时配置。
+
+## 目标和默认值
+
+内置目标的默认值如下：
+
+| 目标      | 环境          | 是否持续运行 |
+| --------- | ------------- | ------------ |
+| `dev`     | `development` | 是           |
+| `build`   | `production`  | 否           |
+| `preview` | `production`  | 是           |
+
+自定义目标默认不会持续运行，未指定 `--env` 时使用 `development`。项目默认使用当前目录，目标输出目录默认为 `dist`，归档输出目录默认为 `artifacts`。归档默认关闭，只允许配置在 build 目标上，启用后默认使用 zip 格式。配置了归档但输出目录不存在时，构建会失败。
+
+交互式运行会先选择 Variant，再选择 Target。Target 选项来自已选 Variant 共同支持的目标；非交互式运行可以使用 `--variant` 提前指定执行范围。
+
+配置中的任意目标都可以通过 CLI 调用。常见的自定义目标包括 `test`、`lint` 和 `e2e`。
+
+## 命令
+
+```text
+matrix [target] [product] [--variant name] [--env <environment>]
+matrix --product <product> [--target <target>] [--variant name] [--env <environment>]
+matrix dev [product]
+matrix build [product] [--env <environment>] [--archive]
+matrix preview [product] [--env <environment>]
+matrix plan [product] [--target <target>] [--env <environment>]
+matrix doctor
+matrix <custom-target> [product] [--env <environment>]
+```
+
+## 开发
+
+依赖版本统一维护在 `pnpm-workspace.yaml` 的 pnpm catalog 中。
+
+```bash
+pnpm install
+pnpm check
+pnpm lint:fix
+```
+
+`pnpm lint:fix` 通过 ESLint 格式化 JavaScript、TypeScript 和 Markdown。`pnpm check` 会依次执行 lint、类型检查、测试和生产构建。
+
+## 许可证
+
+[MIT](LICENSE)

package/bin/matrix.mjs

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+import process from 'node:process'
+import consola from 'consola'
+import { runCli } from '../dist/cli.js'
+
+runCli().catch((error) => {
+  consola.error(error instanceof Error ? error.message : error)
+  process.exitCode = 1
+})

package/dist/archive.js

@@ -0,0 +1 @@
+import e from"node:path";import{randomUUID as t}from"node:crypto";import{createWriteStream as n}from"node:fs";import{mkdir as r,rename as i,stat as a,unlink as o}from"node:fs/promises";import{pipeline as s}from"node:stream/promises";import c from"archiver";async function l(l,u,d){let f;try{f=await a(l)}catch(e){let t=e.code;throw t===`ENOENT`||t===`ENOTDIR`?Error(`Archive source directory does not exist: ${l}`,{cause:e}):e}if(!f.isDirectory())throw Error(`Archive source must be a directory: ${l}`);let p=e.relative(e.resolve(l),e.resolve(u));if(!p||!p.startsWith(`..`)&&!e.isAbsolute(p))throw Error(`Archive destination must be outside source directory: ${u}`);let m=e.dirname(u),h=e.join(m,`.${e.basename(u)}.${t()}.tmp`);await r(m,{recursive:!0});let g;try{let e=n(h),t=c(d===`zip`?`zip`:`tar`,d===`tar.gz`?{gzip:!0,gzipOptions:{level:9}}:void 0);g=s(t,e),t.directory(l,!1),await t.finalize(),await g,await i(h,u)}finally{await g?.catch(()=>void 0),await o(h).catch(e=>{if(e.code!==`ENOENT`)throw e})}}export{l as archiveDirectory};

package/dist/cli-args.js

@@ -0,0 +1 @@
+const e=`matrix [target] [product] [--product name] [--variant name] [--env name] [--target name] [--archive|--no-archive] [-h|--help]`;function t(e,t,n){let r=e[t+1];if(!r||r.startsWith(`-`))throw Error(`Option ${n} requires a value`);return r}function n(e,t){let n=e.split(`,`).map(e=>e.trim());if(n.some(e=>!e))throw Error(`Option ${t} contains an empty variant name`);return n}function r(e){let r={variants:[]},i=[];for(let a=0;a<e.length;a++){let o=e[a];if(!o)throw Error(`Unexpected empty argument`);if(o===`--help`||o===`-h`){r.help=!0;continue}if(o===`--archive`||o===`--no-archive`){let e=o===`--archive`;if(r.archive!==void 0&&r.archive!==e)throw Error(`Options --archive and --no-archive cannot be used together`);if(r.archive===e)throw Error(`Duplicate option: ${o}`);r.archive=e;continue}if(o===`--variant`||o===`-v`){let i=t(e,a,o);r.variants.push(...n(i,o)),a++;continue}if(o===`--product`||o===`--env`||o===`--mode`||o===`--target`){let n=t(e,a,o);if(o===`--product`){if(r.product!==void 0)throw Error(`Duplicate option: --product`);r.product=n}else if(o===`--target`){if(r.target!==void 0)throw Error(`Duplicate option: --target`);r.target=n}else{if(r.env!==void 0)throw Error(`Duplicate option: --env`);r.env=n}a++;continue}if(o.startsWith(`-`))throw Error(`Unknown option: ${o}`);if(i.push(o),i.length>2)throw Error(`Unexpected argument: ${o}`)}if(i[0]&&(r.command=i[0]),i[1]){if(r.product!==void 0)throw Error(`Product was provided more than once`);r.product=i[1]}return r}function i(e){let t=e.product!==void 0||e.target!==void 0||e.env!==void 0||e.variants.length>0||e.archive!==void 0;if(e.help||e.command===`help`){if(t||e.command!==void 0&&e.command!==`help`)throw Error(`Help does not accept execution options`);return}if(e.command===`doctor`){if(e.product!==void 0||e.target!==void 0||e.variants.length>0||e.archive!==void 0)throw Error(`doctor only accepts --env`);return}if(e.command&&e.command!==`plan`&&e.target!==void 0)throw Error(`Target is already selected by command ${e.command}; use --target only with plan or --product`)}export{e as CLI_HELP,r as parseArgs,i as validateCliArgs};

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+//#region src/cli.d.ts
+export declare function runCli(argv?: string[]): Promise<void>;
+//#endregion

package/dist/cli.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import{MATRIX_DEFAULTS as e,defaultEnvironmentForTarget as t}from"./defaults.js";import{listMatrixEnvironments as n,loadMatrixConfig as r}from"./config.js";import{createExecutionPlan as i,validateExecutionGraph as a}from"./plan.js";import{CLI_HELP as o,parseArgs as s,validateCliArgs as c}from"./cli-args.js";import{runExecutionPlan as l}from"./exec.js";import u from"node:process";import{isCancel as d,multiselect as f,outro as p,select as m}from"@clack/prompts";import h from"consola";const g=/token|secret|password|passwd|authorization|cookie|api[_-]?key|private[_-]?key/i;function _(e,t){return{...e,tasks:e.tasks.map(e=>({...e,env:Object.fromEntries(Object.entries(e.env).filter(([e])=>t.has(e)||e.startsWith(`MATRIX_`)).map(([e,t])=>[e,g.test(e)?`***`:t]))}))}}function v(e,t=[]){let n=(t.length?t.map(t=>e.variants[t]).filter(e=>e!==void 0):Object.values(e.variants)).map(e=>new Set(Object.keys(e.targets)));return[...n[0]??/* @__PURE__ */ new Set].filter(e=>n.every(t=>t.has(e))).sort()}function y(e,t){for(let n of t)if(!e.variants[n])throw Error(`Unknown variant for product ${e.key}: ${n}`)}function b(e,t,n=[]){let r=v(t,n),i=r.length?r.join(`, `):`none`;if(!r.includes(e))throw Error(`Unknown command or target for product ${t.key}: ${e}. Available targets: ${i}`)}async function x(e,t){if(!e.product){if(!u.stdin.isTTY||!u.stdout.isTTY)throw Error(`Product is required in non-interactive mode. Try: matrix <target> <product> or matrix --product <product>`);let n=await m({message:`Select product`,options:Object.keys(t).map(e=>({value:e,label:e}))});if(d(n))return null;e.product=n}if(e.product.includes(`,`))throw Error(`Only one product can be selected per run`);if(!t[e.product])throw Error(`Unknown product: ${e.product}`);return e}async function S(t,n){let r=t.target??(t.command&&t.command!==`plan`?t.command:void 0);if(r)return t.target=r,t;let i=v(n,t.variants);if(!i.length)throw Error(`Product ${n.key} has no common targets`);if(!u.stdin.isTTY||!u.stdout.isTTY)return t.target=i.includes(e.target)?e.target:i[0],t;let a=await m({message:`Select target`,initialValue:i.includes(e.target)?e.target:i[0],options:i.map(t=>({value:t,label:t,...t===e.target?{hint:`default`}:{}}))});return d(a)?null:(t.target=a,t)}async function C(e,t){let n=!e.command&&u.stdin.isTTY&&u.stdout.isTTY;if(!e.variants.length&&n&&Object.keys(t.variants).length>1){let n=Object.entries(t.variants),r=await f({message:`Select variants (leave empty to select all)`,options:n.map(([e])=>({value:e,label:e}))});if(d(r))return null;e.variants=r}return e}async function w(e,n,r){if(e.env)return e;let i=t(n);if(u.stdin.isTTY&&u.stdout.isTTY){let t=await m({message:`Select environment`,initialValue:i,options:r.map(e=>({value:e,label:e,...e===i?{hint:`default`}:{}}))});if(d(t))return null;e.env=t}else e.env=i;return e}async function T(d=u.argv.slice(2)){let f=s(d);if(c(f),f.command===`help`||f.help){console.log(o);return}if(f.command===`doctor`){let e=await r({...f.env?{envName:f.env}:{}});a({config:e.config,projects:e.projects,products:e.products,externalEnv:e.externalEnv,cwd:e.cwd,envName:e.envName}),h.success(`Configuration is valid: ${e.configFile??`matrix.config.ts`}`);return}let m=f.target??(f.command&&f.command!==`plan`?f.command:e.target),g=f.env??t(m),v=await r({envName:g}),T=await x(f,v.products);if(!T)return p(`Cancelled`);let E=v.products[T.product];if(!E)throw Error(`Unknown product: ${T.product}`);y(E,T.variants);let D=await C(T,E);if(!D)return p(`Cancelled`);y(E,D.variants);let O=await S(D,E);if(!O)return p(`Cancelled`);let k=O.target;if(O.archive!==void 0&&k!==`build`)throw Error(`Archive options are only valid for the build target: ${k}`);b(k,E,O.variants);let A=await w(O,k,!O.env&&u.stdin.isTTY&&u.stdout.isTTY?await n({productName:O.product}):[]);if(!A)return p(`Cancelled`);let j=A.env===g?v:await r({envName:A.env}),M=j.products[A.product];if(!M)throw Error(`Unknown product: ${A.product}`);y(M,A.variants),b(k,M,A.variants);let N=A.command??k,P=[A.product],F={config:j.config,projects:j.projects,products:j.products,externalEnv:j.externalEnv,cwd:j.cwd,productNames:P,target:k,envName:j.envName},I=A.variants.length?i({...F,variantNames:A.variants}):i(F);if(A.archive!==void 0)for(let e of I.tasks)e.target===`build`&&(e.archive.enabled=A.archive);if(N===`plan`){let e=new Set(Object.keys(j.config.env??{}));for(let t of P)for(let n of Object.keys(j.config.products[t]?.env??{}))e.add(n);console.log(JSON.stringify(_(I,e),null,2));return}h.info(`Plan: ${P[0]} / ${A.variants.length?A.variants.join(`, `):`all variants`} / ${k} / ${j.envName}`);let L=A.variants.length?A.variants:Object.keys(M.variants),R=new Set(L.map(e=>`${P[0]}:${e}:${k}`)),z=I.tasks.filter(e=>!R.has(e.id));z.length&&h.info(`Including dependencies: ${z.map(e=>e.id).join(`, `)}`),await l(I)}export{T as runCli};

package/dist/config.d.ts

@@ -0,0 +1,65 @@
+import { EnvMap, MatrixConfig, NormalizedProduct, NormalizedProject } from "./types.js";
+import { MATRIX_DEFAULTS, defaultEnvironmentForTarget } from "./defaults.js";
+//#region src/config.d.ts
+/**
+ * Provides type inference for a Matrix configuration file.
+ *
+ * @example
+ * ```ts
+ * export default defineMatrixConfig({
+ *   projects: { web: { targets: { build: 'pnpm build' } } },
+ *   products: { app: { variants: { web: 'web' } } },
+ * })
+ * ```
+ */
+export declare function defineMatrixConfig<T extends MatrixConfig>(config: T): T;
+/**
+ * Converts a compact environment map into c12's `$env` configuration shape.
+ *
+ * @example
+ * ```ts
+ * $env: defineMatrixEnv({
+ *   qa: { API_BASE_URL: 'https://qa.example.test' },
+ * })
+ * ```
+ */
+export declare function defineMatrixEnv<T extends Record<string, EnvMap>>(environments: T): { [K in keyof T]: {
+  env: T[K];
+}; };
+/**
+ * Lists built-in and configured environment names without applying dotenv or process overrides.
+ *
+ * When `productName` is provided, product-scoped environments are included only for that
+ * product. This is used by the interactive CLI after product selection.
+ */
+export declare function listMatrixEnvironments(options?: {
+  cwd?: string;
+  configFile?: string;
+  productName?: string;
+}): Promise<string[]>;
+/** Resolves target, identity, and project defaults into execution-ready structures. */
+export declare function normalizeMatrixConfig(raw: MatrixConfig): {
+  config: MatrixConfig;
+  projects: Record<string, NormalizedProject>;
+  products: Record<string, NormalizedProduct>;
+};
+type LoadedMatrixConfig = ReturnType<typeof normalizeMatrixConfig> & {
+  configFile: string | undefined;
+  layers: unknown[] | undefined;
+  cwd: string;
+  envName: string;
+  externalEnv: EnvMap;
+};
+/**
+ * Loads and validates Matrix configuration through c12.
+ *
+ * The selected environment applies c12 `$env` layers and the dotenv files `.env`,
+ * `.env.local`, `.env.<environment>`, and `.env.<environment>.local`.
+ */
+export declare function loadMatrixConfig(options?: {
+  cwd?: string;
+  envName?: string;
+  configFile?: string;
+}): Promise<LoadedMatrixConfig>;
+//#endregion
+export { MATRIX_DEFAULTS, defaultEnvironmentForTarget };

package/dist/config.js

@@ -0,0 +1 @@
+import{MATRIX_DEFAULTS as e,defaultEnvironmentForTarget as t}from"./defaults.js";import{assertMatrixConfig as n}from"./schema.js";import{MATRIX_ENVIRONMENTS as r}from"./types.js";import i from"node:path";import a from"node:process";import{loadConfig as o}from"c12";function s(e){return e}function c(e){return Object.fromEntries(Object.entries(e).map(([e,t])=>[e,{env:t}]))}async function l(e={}){let t=i.resolve(e.cwd??a.cwd()),n=(await o({name:`matrix`,cwd:t,...e.configFile?{configFile:e.configFile}:{},envName:!1,dotenv:!1,omit$Keys:!1,rcFile:!1,packageJson:!1})).config,s=new Set(r);for(let e of Object.keys(n.$env??{}))s.add(e);let c=e.productName?n.products?.[e.productName]:void 0,l=e.productName?c?[c]:[]:Object.values(n.products??{});for(let e of l)for(let t of Object.keys(e.$env??{}))s.add(t);return[...s]}function u(t,n){let r=typeof n==`string`?{command:n}:{...n};if(!r.command)throw Error(`Target ${t} must define a command`);let i=typeof r.archive==`boolean`?{enabled:r.archive,format:e.archive.format}:{enabled:r.archive?.enabled??e.archive.enabled,format:r.archive?.format??e.archive.format},a=e.targets[t];return{...r,name:t,continuous:r.continuous??a?.continuous??!1,outputDir:r.outputDir??e.outputDir,archive:i,dependsOn:(r.dependsOn??[]).map(e=>typeof e==`string`?{variant:e}:e)}}function d(e,t){if(e!==`build`&&typeof t!=`string`&&t.archive!==void 0)throw Error(`Archive is only supported for build targets: ${e}`)}function f(e,t){if(typeof t==`string`)return t;let n=t.readyWhen===void 0?e.readyWhen:{...e.readyWhen,...t.readyWhen},r=typeof e.archive==`object`?e.archive:{enabled:e.archive},i=typeof t.archive==`object`&&t.archive!==null?{...r,...t.archive}:t.archive??r;return{...e,...t,archive:i,...n?{readyWhen:n}:{}}}function p(...e){return Object.assign({},...e.filter(Boolean))}function m(e,t){let n=Object.fromEntries(Object.entries(e.products).map(([e,n])=>{let{$env:r,...i}=n,a=p(n.env,r?.[t]?.env);return[e,{...i,...Object.keys(a).length?{env:a}:{}}]}));return{...e,products:n}}function h(e){let t=Object.fromEntries(Object.entries(e.projects).map(([e,t])=>[e,{...t,id:e,targets:Object.fromEntries(Object.entries(t.targets).map(([e,t])=>(d(e,t),[e,u(e,t)])))}]));return{config:e,projects:t,products:Object.fromEntries(Object.entries(e.products).map(([e,n])=>{let r=Object.fromEntries(Object.entries(n.variants).map(([n,r])=>{let i=typeof r==`string`?{project:r}:r,a=t[i.project];if(!a)throw Error(`Product ${e} variant ${n} references unknown project ${i.project}`);let o=Object.fromEntries(Object.entries(a.targets).map(([e,t])=>{let n=i.targets?.[e];return n!==void 0&&d(e,n),[e,u(e,n===void 0?t:f(t,n))]}));for(let[t,r]of Object.entries(i.targets??{}))if(!(t in o)){if(d(t,r),typeof r==`string`)o[t]=u(t,r);else if(r.command)o[t]=u(t,r);else throw Error(`Variant ${e}/${n} target ${t} must define a command`)}return[n,{...i,id:n,targets:o}]}));return[e,{...n,id:n.id??e,name:n.name??e,slug:n.slug??e,key:e,variants:r}]}))}}async function g(t={}){let r=i.resolve(t.cwd??a.cwd()),s=t.envName??e.environment,c={name:`matrix`,cwd:r,...t.configFile?{configFile:t.configFile}:{},envName:s,dotenv:{fileName:[`.env`,`.env.local`,`.env.${s}`,`.env.${s}.local`]},omit$Keys:!0,rcFile:!1,packageJson:!1},l=await o(c),u=m(n(l.config),s),d=Object.fromEntries(Object.entries(a.env).filter(e=>e[1]!==void 0));return{...h(u),configFile:l.configFile,layers:l.layers,cwd:r,envName:s,externalEnv:d}}export{e as MATRIX_DEFAULTS,t as defaultEnvironmentForTarget,s as defineMatrixConfig,c as defineMatrixEnv,l as listMatrixEnvironments,g as loadMatrixConfig,h as normalizeMatrixConfig};

package/dist/defaults.d.ts

@@ -0,0 +1,30 @@
+//#region src/defaults.d.ts
+/** Default values applied when a Matrix configuration omits optional fields. */
+export declare const MATRIX_DEFAULTS: {
+  readonly target: "dev";
+  readonly environment: "development";
+  readonly projectRoot: ".";
+  readonly outputDir: "dist";
+  readonly artifactsRoot: "artifacts";
+  readonly archive: {
+    readonly enabled: false;
+    readonly format: "zip";
+  };
+  readonly targets: {
+    readonly dev: {
+      readonly environment: "development";
+      readonly continuous: true;
+    };
+    readonly build: {
+      readonly environment: "production";
+      readonly continuous: false;
+    };
+    readonly preview: {
+      readonly environment: "production";
+      readonly continuous: true;
+    };
+  };
+};
+/** Returns the default environment associated with a target name. */
+export declare function defaultEnvironmentForTarget(target: string): string;
+//#endregion

package/dist/defaults.js

@@ -0,0 +1 @@
+const e={target:`dev`,environment:`development`,projectRoot:`.`,outputDir:`dist`,artifactsRoot:`artifacts`,archive:{enabled:!1,format:`zip`},targets:{dev:{environment:`development`,continuous:!0},build:{environment:`production`,continuous:!1},preview:{environment:`production`,continuous:!0}}};function t(t){return e.targets[t]?.environment??e.environment}export{e as MATRIX_DEFAULTS,t as defaultEnvironmentForTarget};

package/dist/exec.js

@@ -0,0 +1 @@
+import{archiveDirectory as e}from"./archive.js";import t from"node:path";import n from"node:process";import r from"consola";import i from"node:net";import{execaCommand as a}from"execa";const o=new Promise(()=>void 0);function s(e){return new Promise(t=>setTimeout(t,e))}function c(e,t){return t.size?Promise.race([e,...t]):e}function l(e,t,n){return new Promise(r=>{let a=i.createConnection({host:e,port:t}),o=!1,s=e=>{o||(o=!0,a.destroy(),r(e))};a.once(`connect`,()=>s(!0)),a.once(`error`,()=>s(!1)),a.setTimeout(n,()=>s(!1))})}async function u(e,t,n){let r=t.readyWhen;if(!r)return;let i=r.timeout??3e4,a=Date.now()+i;for(;;){let i=a-Date.now();if(i<=0)break;if(await c(l(r.host??`127.0.0.1`,r.port,Math.min(1e3,i)),n))return;if(await c(Promise.race([e.then(e=>e),new Promise(e=>setTimeout(e,Math.min(200,Math.max(1,a-Date.now()))))]),n)!==void 0)throw Error(`${t.id} exited before becoming ready`)}throw Error(`Timed out waiting for ${t.id} on port ${r.port}`)}async function d(e,t,n){for(let[n,r]of e)t.has(n)||(t.add(n),r.kill(`SIGTERM`));await Promise.race([Promise.allSettled([...e.values()]),s(5e3)]);for(let[r,i]of e)n.has(r)||(t.add(r),i.kill(`SIGKILL`));await Promise.allSettled([...e.values()])}async function f(i){let s=/* @__PURE__ */ new Map,l=/* @__PURE__ */ new Set,f=/* @__PURE__ */ new Set,p=/* @__PURE__ */ new Set,m=()=>{for(let[e,t]of s)l.has(e)||(l.add(e),t.kill(`SIGTERM`))};n.on(`SIGINT`,m),n.on(`SIGTERM`,m);try{for(let d of i.tasks){for(let e of d.dependsOn){let t=s.get(e.id);if(!t)throw Error(`Dependency ${e.id} was not started`);if(e.condition===`completed`){let n=await c(t,p);if(n.exitCode!==0)throw Error(`${e.id} exited with code ${n.exitCode}`)}else{let n=i.tasks.find(t=>t.id===e.id);if(!n)throw Error(`Dependency task ${e.id} is missing`);await u(t,n,p)}}r.info(`${d.id} → ${d.command}`);let m=a(d.command,{cwd:d.cwd,env:{...n.env,...Object.fromEntries(Object.entries(d.env).map(([e,t])=>[e,String(t)]))},stdio:`inherit`,reject:!1,killDescendants:!0});if(s.set(d.id,m),m.then(()=>f.add(d.id),()=>f.add(d.id)),d.continuous){let e=m.then(e=>{if(l.size||e.exitCode===0)return o;throw Error(`${d.id} exited with code ${e.exitCode}`)});p.add(e),e.catch(()=>void 0)}if(!d.continuous){let n=await c(m,p);if(n.exitCode!==0)throw Error(`${d.id} exited with code ${n.exitCode}`);if(d.target===`build`&&d.archive.enabled){let n=d.archive.format===`zip`?`zip`:`tar.gz`,r=t.join(i.artifactsRoot,d.product,i.envName,`${d.variant}.${n}`);await e(d.outputDir,r,d.archive.format)}}}let d=i.tasks.filter(e=>e.continuous).map(e=>s.get(e.id));return d.length&&await c(Promise.race(d.map(async e=>{let t=await e;if(!l.size&&t.exitCode!==0)throw Error(`Service exited with code ${t.exitCode}`)})),p),{children:s}}finally{i.tasks.some(e=>e.continuous)?await d(s,l,f):await Promise.allSettled([...s.values()]),n.removeListener(`SIGINT`,m),n.removeListener(`SIGTERM`,m)}}export{f as runExecutionPlan};

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { CommandTarget, CreateExecutionPlanInput, EnvMap, EnvironmentConfig, ExecutionPlan, ExecutionTask, MATRIX_ENVIRONMENTS, MatrixConfig, MatrixEnvironment, NormalizedProduct, NormalizedProject, NormalizedTarget, NormalizedVariant, ProductConfig, ProjectConfig, Scalar, SuffixConfig, TargetConfig, TargetDependency, TargetOverride, VariantConfig } from "./types.js";
+import { MATRIX_DEFAULTS, defaultEnvironmentForTarget } from "./defaults.js";
+import { defineMatrixConfig, defineMatrixEnv, listMatrixEnvironments, loadMatrixConfig, normalizeMatrixConfig } from "./config.js";
+import { createExecutionPlan } from "./plan.js";
+import { assertMatrixConfig, matrixConfigSchema } from "./schema.js";
+export { type CommandTarget, type CreateExecutionPlanInput, type EnvMap, type EnvironmentConfig, type ExecutionPlan, type ExecutionTask, MATRIX_DEFAULTS, MATRIX_ENVIRONMENTS, type MatrixConfig, type MatrixEnvironment, type NormalizedProduct, type NormalizedProject, type NormalizedTarget, type NormalizedVariant, type ProductConfig, type ProjectConfig, type Scalar, type SuffixConfig, type TargetConfig, type TargetDependency, type TargetOverride, type VariantConfig, assertMatrixConfig, createExecutionPlan, defaultEnvironmentForTarget, defineMatrixConfig, defineMatrixEnv, listMatrixEnvironments, loadMatrixConfig, matrixConfigSchema, normalizeMatrixConfig };

package/dist/index.js

@@ -0,0 +1 @@
+import{MATRIX_DEFAULTS as e,defaultEnvironmentForTarget as t}from"./defaults.js";import{assertMatrixConfig as n,matrixConfigSchema as r}from"./schema.js";import{MATRIX_ENVIRONMENTS as i}from"./types.js";import{defineMatrixConfig as a,defineMatrixEnv as o,listMatrixEnvironments as s,loadMatrixConfig as c,normalizeMatrixConfig as l}from"./config.js";import{createExecutionPlan as u}from"./plan.js";export{e as MATRIX_DEFAULTS,i as MATRIX_ENVIRONMENTS,n as assertMatrixConfig,u as createExecutionPlan,t as defaultEnvironmentForTarget,a as defineMatrixConfig,o as defineMatrixEnv,s as listMatrixEnvironments,c as loadMatrixConfig,r as matrixConfigSchema,l as normalizeMatrixConfig};

package/dist/plan.d.ts

@@ -0,0 +1,12 @@
+import { CreateExecutionPlanInput, ExecutionPlan } from "./types.js";
+//#region src/plan.d.ts
+/**
+ * Creates an ordered execution plan for one target across selected products or variants.
+ *
+ * Dependencies are expanded recursively and cycles are rejected. Environment values are
+ * merged into each task before the plan is returned.
+ */
+export declare function createExecutionPlan(input: CreateExecutionPlanInput): ExecutionPlan;
+/** Validates every configured product, variant, and target without starting any process. */
+export declare function validateExecutionGraph(input: Omit<CreateExecutionPlanInput, 'productNames' | 'variantNames' | 'target'>): void;
+//#endregion

package/dist/plan.js

@@ -0,0 +1 @@
+import{MATRIX_DEFAULTS as e}from"./defaults.js";import t from"node:path";import n from"node:process";function r(...e){return Object.assign({},...e.filter(Boolean))}function i(){return Object.fromEntries(Object.entries(n.env).filter(e=>e[1]!==void 0))}function a(e,t){return e===void 0||t===void 0?e:`${e}${t}`}function o(...e){let t={};for(let n of e)for(let[e,r]of Object.entries(n??{}))t[e]={...t[e],...r};return t}function s(e,t,n){let r={...e.suffixes?.[n]??{},...t.suffixes?.[n]??{}};return{id:e.id,name:a(t.name??e.name,r.name),slug:a(t.slug??e.slug,r.slug),appId:a(t.appId??e.appId,r.appId)}}function c(e,t){return e.condition??(t.continuous?`ready`:`completed`)}function l(n){let a=/* @__PURE__ */ new Map,l=/* @__PURE__ */ new Set,u=[],d=(f,p,m)=>{let h=`${f}:${p}:${m}`,g=a.get(h);if(g)return g;if(l.has(h))throw Error(`Dependency cycle detected at ${h}`);let _=n.products[f];if(!_)throw Error(`Unknown product: ${f}`);let v=_.variants[p];if(!v)throw Error(`Unknown variant ${p} for product ${f}`);let y=n.projects[v.project];if(!y)throw Error(`Variant ${f}/${p} references unknown project ${v.project}`);let b=v.targets[m];if(!b)throw Error(`Variant ${f}/${p} has no target ${m}`);l.add(h);let x=b.dependsOn.map(e=>{let t=e.target??m,n=_.variants[e.variant];if(!n)throw Error(`Unknown dependency variant ${f}/${e.variant}`);let r=n.targets[t];if(!r)throw Error(`Variant ${f}/${e.variant} has no target ${t}`);return{id:d(f,e.variant,t).id,condition:c(e,r)}});l.delete(h);let S=s({..._,suffixes:o(n.config.suffixes,_.suffixes)},v,n.envName),C=t.resolve(n.cwd,y.root??e.projectRoot),w={id:h,product:f,variant:p,project:v.project,projectRoot:C,target:m,name:S.name,slug:S.slug,...S.appId?{appId:S.appId}:{},command:b.command,cwd:C,env:r(n.config.env,_.env,n.externalEnv??i(),{MATRIX_ENV_NAME:n.envName,MATRIX_PRODUCT_ID:S.id,MATRIX_PRODUCT_NAME:S.name,MATRIX_PRODUCT_SLUG:S.slug}),continuous:b.continuous,archive:b.archive,...b.readyWhen?{readyWhen:b.readyWhen}:{},outputDir:t.resolve(C,b.outputDir),dependsOn:x};return a.set(h,w),u.push(w),w};for(let e of n.productNames){let t=n.products[e];if(!t)throw Error(`Unknown product: ${e}`);let r=n.variantNames?.length?n.variantNames:Object.keys(t.variants);for(let t of r)d(e,t,n.target)}return{envName:n.envName,tasks:u,artifactsRoot:t.resolve(n.cwd,n.config.artifacts?.root??e.artifactsRoot)}}function u(e){for(let[t,n]of Object.entries(e.products))for(let[r,i]of Object.entries(n.variants))for(let n of Object.keys(i.targets))l({...e,productNames:[t],variantNames:[r],target:n})}export{l as createExecutionPlan,u as validateExecutionGraph};

package/dist/schema.d.ts

@@ -0,0 +1,89 @@
+import * as v from "valibot";
+//#region src/schema.d.ts
+/** Runtime schema used to validate a loaded Matrix configuration. */
+export declare const matrixConfigSchema: v.ObjectSchema<{
+  readonly suffixes: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.ObjectSchema<{
+    readonly name: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly slug: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly appId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+  }, undefined>, undefined>, undefined>;
+  readonly env: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnionSchema<[v.StringSchema<undefined>, v.NumberSchema<undefined>, v.BooleanSchema<undefined>], undefined>, undefined>, undefined>;
+  readonly $env: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.ObjectSchema<{
+    readonly env: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnionSchema<[v.StringSchema<undefined>, v.NumberSchema<undefined>, v.BooleanSchema<undefined>], undefined>, undefined>, undefined>;
+  }, undefined>, undefined>, undefined>;
+  readonly projects: v.RecordSchema<v.StringSchema<undefined>, v.ObjectSchema<{
+    readonly root: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly targets: v.RecordSchema<v.StringSchema<undefined>, v.UnionSchema<[v.StringSchema<undefined>, v.ObjectSchema<{
+      readonly command: v.StringSchema<undefined>;
+      readonly continuous: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+      readonly readyWhen: v.OptionalSchema<v.ObjectSchema<{
+        readonly type: v.LiteralSchema<"port", undefined>;
+        readonly host: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly port: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 65535, undefined>]>;
+        readonly timeout: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, undefined>;
+      }, undefined>, undefined>;
+      readonly outputDir: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+      readonly archive: v.OptionalSchema<v.UnionSchema<[v.BooleanSchema<undefined>, v.ObjectSchema<{
+        readonly enabled: v.BooleanSchema<undefined>;
+        readonly format: v.OptionalSchema<v.PicklistSchema<["zip", "tar.gz"], undefined>, undefined>;
+      }, undefined>], undefined>, undefined>;
+      readonly dependsOn: v.OptionalSchema<v.ArraySchema<v.UnionSchema<[v.StringSchema<undefined>, v.ObjectSchema<{
+        readonly variant: v.StringSchema<undefined>;
+        readonly target: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly condition: v.OptionalSchema<v.PicklistSchema<["completed", "ready"], undefined>, undefined>;
+      }, undefined>], undefined>, undefined>, undefined>;
+    }, undefined>], undefined>, undefined>;
+  }, undefined>, undefined>;
+  readonly products: v.RecordSchema<v.StringSchema<undefined>, v.ObjectSchema<{
+    readonly id: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly name: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly slug: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly appId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly env: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnionSchema<[v.StringSchema<undefined>, v.NumberSchema<undefined>, v.BooleanSchema<undefined>], undefined>, undefined>, undefined>;
+    readonly $env: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.ObjectSchema<{
+      readonly env: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnionSchema<[v.StringSchema<undefined>, v.NumberSchema<undefined>, v.BooleanSchema<undefined>], undefined>, undefined>, undefined>;
+    }, undefined>, undefined>, undefined>;
+    readonly suffixes: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.ObjectSchema<{
+      readonly name: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+      readonly slug: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+      readonly appId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, undefined>, undefined>;
+    readonly variants: v.RecordSchema<v.StringSchema<undefined>, v.UnionSchema<[v.StringSchema<undefined>, v.ObjectSchema<{
+      readonly project: v.StringSchema<undefined>;
+      readonly name: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+      readonly slug: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+      readonly appId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+      readonly suffixes: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.ObjectSchema<{
+        readonly name: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly slug: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly appId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+      }, undefined>, undefined>, undefined>;
+      readonly targets: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnionSchema<[v.StringSchema<undefined>, v.ObjectSchema<{
+        readonly command: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly continuous: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+        readonly readyWhen: v.OptionalSchema<v.ObjectSchema<{
+          readonly type: v.LiteralSchema<"port", undefined>;
+          readonly host: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+          readonly port: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 65535, undefined>]>;
+          readonly timeout: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, undefined>;
+        }, undefined>, undefined>;
+        readonly outputDir: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly archive: v.OptionalSchema<v.UnionSchema<[v.BooleanSchema<undefined>, v.ObjectSchema<{
+          readonly enabled: v.BooleanSchema<undefined>;
+          readonly format: v.OptionalSchema<v.PicklistSchema<["zip", "tar.gz"], undefined>, undefined>;
+        }, undefined>], undefined>, undefined>;
+        readonly dependsOn: v.OptionalSchema<v.ArraySchema<v.UnionSchema<[v.StringSchema<undefined>, v.ObjectSchema<{
+          readonly variant: v.StringSchema<undefined>;
+          readonly target: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+          readonly condition: v.OptionalSchema<v.PicklistSchema<["completed", "ready"], undefined>, undefined>;
+        }, undefined>], undefined>, undefined>, undefined>;
+      }, undefined>], undefined>, undefined>, undefined>;
+    }, undefined>], undefined>, undefined>;
+  }, undefined>, undefined>;
+  readonly artifacts: v.OptionalSchema<v.ObjectSchema<{
+    readonly root: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+  }, undefined>, undefined>;
+}, undefined>;
+/** Validates a configuration and throws a Valibot error when it is malformed. */
+export declare function assertMatrixConfig(value: unknown): v.InferOutput<typeof matrixConfigSchema>;
+//#endregion

package/dist/schema.js

@@ -0,0 +1 @@
+import*as e from"valibot";const t=e.union([e.string(),e.number(),e.boolean()]),n=e.optional(e.record(e.string(),t)),r=e.object({name:e.optional(e.string()),slug:e.optional(e.string()),appId:e.optional(e.string())}),i=e.object({variant:e.string(),target:e.optional(e.string()),condition:e.optional(e.picklist([`completed`,`ready`]))}),a=e.union([e.string(),i]),o=e.pipe(e.number(),e.integer(),e.minValue(1),e.maxValue(65535)),s=e.pipe(e.number(),e.integer(),e.minValue(1)),c=e.union([e.string(),e.object({command:e.string(),continuous:e.optional(e.boolean()),readyWhen:e.optional(e.object({type:e.literal(`port`),host:e.optional(e.string()),port:o,timeout:e.optional(s)})),outputDir:e.optional(e.string()),archive:e.optional(e.union([e.boolean(),e.object({enabled:e.boolean(),format:e.optional(e.picklist([`zip`,`tar.gz`]))})])),dependsOn:e.optional(e.array(a))})]),l=e.union([e.string(),e.object({command:e.optional(e.string()),continuous:e.optional(e.boolean()),readyWhen:e.optional(e.object({type:e.literal(`port`),host:e.optional(e.string()),port:o,timeout:e.optional(s)})),outputDir:e.optional(e.string()),archive:e.optional(e.union([e.boolean(),e.object({enabled:e.boolean(),format:e.optional(e.picklist([`zip`,`tar.gz`]))})])),dependsOn:e.optional(e.array(a))})]),u=e.object({root:e.optional(e.string()),targets:e.record(e.string(),c)}),d=e.object({env:n}),f=e.union([e.string(),e.object({project:e.string(),name:e.optional(e.string()),slug:e.optional(e.string()),appId:e.optional(e.string()),suffixes:e.optional(e.record(e.string(),r)),targets:e.optional(e.record(e.string(),l))})]),p=e.object({id:e.optional(e.string()),name:e.optional(e.string()),slug:e.optional(e.string()),appId:e.optional(e.string()),env:n,$env:e.optional(e.record(e.string(),d)),suffixes:e.optional(e.record(e.string(),r)),variants:e.record(e.string(),f)}),m=e.object({suffixes:e.optional(e.record(e.string(),r)),env:n,$env:e.optional(e.record(e.string(),d)),projects:e.record(e.string(),u),products:e.record(e.string(),p),artifacts:e.optional(e.object({root:e.optional(e.string())}))});function h(t){return e.parse(m,t)}export{h as assertMatrixConfig,m as matrixConfigSchema};

package/dist/types.d.ts

@@ -0,0 +1,238 @@
+//#region src/types.d.ts
+/** Values that can be passed to a process as environment variables. */
+export type Scalar = string | number | boolean;
+/** A flat environment variable map. */
+export type EnvMap = Record<string, Scalar>;
+/** Configuration for a project command such as `dev`, `build`, or `preview`. */
+export interface CommandTarget {
+  /** Command to execute from the project's root directory. */
+  command: string;
+  /** Whether the command keeps running after it starts. Defaults from the target name. */
+  continuous?: boolean;
+  /** Readiness probe used by dependent continuous targets. */
+  readyWhen?: {
+    /** Probe type. Port probing is currently supported. */
+    type: 'port';
+    /** Host to probe. Defaults to the local host used by the probe. */
+    host?: string;
+    /** TCP port that must accept a connection. */
+    port: number;
+    /** Maximum time to wait for readiness, in milliseconds. */
+    timeout?: number;
+  };
+  /** Directory to archive, relative to the project root. Defaults to `dist`. */
+  outputDir?: string;
+  /** Whether to archive build output and, optionally, which archive format to use. Only valid on the build target. */
+  archive?: boolean | {
+    enabled: boolean;
+    format?: 'zip' | 'tar.gz';
+  };
+  /** Other variants that must run before this target. */
+  dependsOn?: Array<string | TargetDependency>;
+}
+/** Short target syntax containing only the command. */
+export type TargetConfig = string | CommandTarget;
+/** Partial target configuration used to override a project's target on a variant. */
+export type TargetOverride = string | Partial<CommandTarget>;
+/** Dependency on another variant of the same product. */
+export interface TargetDependency {
+  /** Variant that must be executed first. */
+  variant: string;
+  /** Target to execute on the dependency. Defaults to the current target. */
+  target?: string;
+  /** Dependency condition. Defaults to `ready` for continuous targets and `completed` otherwise. */
+  condition?: 'completed' | 'ready';
+}
+/** A runnable project and the targets it exposes. */
+export interface ProjectConfig {
+  /** Project directory, relative to the Matrix configuration directory. Defaults to `.`. */
+  root?: string;
+  /** Named commands exposed by this project. */
+  targets: Record<string, TargetConfig>;
+}
+/** Configuration for a product variant, or a project name in short form. */
+export type VariantConfig = string | {
+  /** Project used to implement this variant. */
+  project: string;
+  /** Display name used in generated task metadata. */
+  name?: string;
+  /** Slug used in generated task metadata. */
+  slug?: string;
+  /** Application identifier used in generated task metadata. */
+  appId?: string;
+  /** Environment-specific identity suffixes for this variant. */
+  suffixes?: Record<string, SuffixConfig>;
+  /** Target overrides or additional targets for this variant. */
+  targets?: Record<string, TargetOverride>;
+};
+/** Environment-specific suffixes for a product or variant identity. */
+export interface SuffixConfig {
+  /** Text appended to the display name. */
+  name?: string;
+  /** Text appended to the slug. */
+  slug?: string;
+  /** Text appended to the application identifier. */
+  appId?: string;
+}
+/** A product groups variants that are selected and executed together. */
+export interface ProductConfig {
+  /** Stable product identifier. Defaults to the product key. */
+  id?: string;
+  /** Display name. Defaults to the product key. */
+  name?: string;
+  /** Slug. Defaults to the product key. */
+  slug?: string;
+  /** Base application identifier. */
+  appId?: string;
+  /** Base environment variables for every environment. */
+  env?: EnvMap;
+  /** Product-scoped environment overrides loaded by c12's `$env` mechanism. */
+  $env?: Record<string, EnvironmentConfig>;
+  /** Environment-specific identity suffixes. */
+  suffixes?: Record<string, SuffixConfig>;
+  /** Product variants. */
+  variants: Record<string, VariantConfig>;
+}
+/** Configuration for one named environment. */
+export interface EnvironmentConfig {
+  /** Environment variables merged over the parent scope. */
+  env?: EnvMap;
+}
+/** Root Matrix configuration. */
+export interface MatrixConfig {
+  /** Global environment-specific identity suffixes. */
+  suffixes?: Record<string, SuffixConfig>;
+  /** Base environment variables shared by all products. */
+  env?: EnvMap;
+  /** Global environment overrides loaded by c12's `$env` mechanism. */
+  $env?: Record<string, EnvironmentConfig>;
+  /** Reusable projects. */
+  projects: Record<string, ProjectConfig>;
+  /** Products composed from the projects above. */
+  products: Record<string, ProductConfig>;
+  /** Output artifact configuration. */
+  artifacts?: {
+    root?: string;
+  };
+}
+/** Built-in environment names offered by Matrix. Custom names can be added with `$env`. */
+export declare const MATRIX_ENVIRONMENTS: readonly ["development", "staging", "production"];
+/** A built-in Matrix environment name. */
+export type MatrixEnvironment = typeof MATRIX_ENVIRONMENTS[number];
+/** Target after defaults and variant overrides have been resolved. */
+export type NormalizedTarget = Omit<CommandTarget, 'outputDir' | 'dependsOn'> & {
+  name: string;
+  continuous: boolean;
+  outputDir: string;
+  archive: {
+    enabled: boolean;
+    format: 'zip' | 'tar.gz';
+  };
+  dependsOn: TargetDependency[];
+};
+/** Project after its target definitions have been normalized. */
+export type NormalizedProject = Omit<ProjectConfig, 'targets'> & {
+  id: string;
+  targets: Record<string, NormalizedTarget>;
+};
+/** Variant after its project targets and overrides have been normalized. */
+export type NormalizedVariant = Omit<Exclude<VariantConfig, string>, 'targets'> & {
+  id: string;
+  project: string;
+  targets: Record<string, NormalizedTarget>;
+};
+/** Product after identity defaults and variant definitions have been normalized. */
+export type NormalizedProduct = Omit<ProductConfig, 'variants' | 'id' | 'name' | 'slug'> & {
+  id: string;
+  name: string;
+  slug: string;
+  key: string;
+  variants: Record<string, NormalizedVariant>;
+};
+/** One executable task in an {@link ExecutionPlan}. */
+export interface ExecutionTask {
+  /** Stable task identifier. */
+  id: string;
+  /** Product key that owns the task. */
+  product: string;
+  /** Variant key that owns the task. */
+  variant: string;
+  /** Referenced project key. */
+  project: string;
+  /** Absolute project directory. */
+  projectRoot: string;
+  /** Target name. */
+  target: string;
+  /** Resolved display name. */
+  name: string;
+  /** Resolved slug. */
+  slug: string;
+  /** Resolved application identifier, when configured. */
+  appId?: string;
+  /** Command to execute. */
+  command: string;
+  /** Working directory for the command. */
+  cwd: string;
+  /** Environment passed to the command. */
+  env: EnvMap;
+  /** Whether the command is expected to remain running. */
+  continuous: boolean;
+  /** Resolved archive settings. */
+  archive: {
+    enabled: boolean;
+    format: 'zip' | 'tar.gz';
+  };
+  /** Readiness probe, when configured. */
+  readyWhen?: {
+    type: 'port';
+    host?: string;
+    port: number;
+    timeout?: number;
+  };
+  /** Absolute output directory. */
+  outputDir: string;
+  /** Resolved task dependencies and their completion conditions. */
+  dependsOn: Array<{
+    id: string;
+    condition: 'completed' | 'ready';
+  }>;
+}
+/** Ordered executable tasks and their shared artifact destination. */
+export interface ExecutionPlan {
+  /** Environment selected for this plan. */
+  envName: string;
+  /** Tasks in dependency-safe execution order. */
+  tasks: ExecutionTask[];
+  /** Absolute root directory for generated archives. */
+  artifactsRoot: string;
+}
+/** Input accepted by {@link createExecutionPlan}. */
+export interface CreateExecutionPlanInput {
+  /** Resolved root-level configuration values used by planning. */
+  config: {
+    artifacts?: {
+      root?: string;
+    };
+    env?: EnvMap;
+    suffixes?: Record<string, SuffixConfig>;
+  };
+  /** Normalized projects keyed by project name. */
+  projects: Record<string, {
+    root?: string;
+  }>;
+  /** Normalized products keyed by product name. */
+  products: Record<string, NormalizedProduct>;
+  /** External process environment to merge into each task. */
+  externalEnv?: EnvMap;
+  /** Directory containing the Matrix configuration. */
+  cwd: string;
+  /** Products to include in the plan. */
+  productNames: string[];
+  /** Optional variant filter. */
+  variantNames?: string[];
+  /** Target to execute for each selected variant. */
+  target: string;
+  /** Environment used to resolve identity suffixes. */
+  envName: string;
+}
+//#endregion

package/dist/types.js

@@ -0,0 +1 @@
+const e=[`development`,`staging`,`production`];export{e as MATRIX_ENVIRONMENTS};

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@xova/matrix",
+  "type": "module",
+  "version": "0.1.0-rc.0",
+  "description": "A configuration-driven multi-app workspace orchestration engine and CLI.",
+  "license": "MIT",
+  "homepage": "https://github.com/xova-dev/matrix#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xova-dev/matrix.git"
+  },
+  "bugs": {
+    "url": "https://github.com/xova-dev/matrix/issues"
+  },
+  "keywords": [
+    "workspace",
+    "monorepo",
+    "cli",
+    "build",
+    "orchestration"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "import": "./dist/config.js"
+    },
+    "./plan": {
+      "types": "./dist/plan.d.ts",
+      "import": "./dist/plan.js"
+    }
+  },
+  "bin": {
+    "matrix": "./bin/matrix.mjs"
+  },
+  "files": [
+    "bin",
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.11.0",
+    "archiver": "^7.0.1",
+    "c12": "^3.3.0",
+    "consola": "^3.4.2",
+    "execa": "^9.6.0",
+    "valibot": "^1.1.0"
+  },
+  "devDependencies": {
+    "@antfu/eslint-config": "^9.5.1",
+    "@types/archiver": "^6.0.3",
+    "@types/node": "^24.9.2",
+    "eslint": "^10.10.0",
+    "eslint-plugin-format": "^2.0.1",
+    "prettier": "^3.9.8",
+    "publint": "^0.3.24",
+    "tsdown": "^0.23.0",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test:pack": "node scripts/pack-smoke.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "check": "pnpm lint && pnpm typecheck && pnpm test && pnpm build"
+  }
+}