zigrix 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,184 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright
+owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities
+that control, are controlled by, or are under common control with that entity.
+For the purposes of this definition, "control" means (i) the power, direct or
+indirect, to cause the direction or management of such entity, whether by
+contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including
+but not limited to software source code, documentation source, and
+configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or
+translation of a Source form, including but not limited to compiled object
+code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form,
+made available under the License, as indicated by a copyright notice that is
+included in or attached to the work (an example is provided in the Appendix
+below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that
+is based on (or derived from) the Work and for which the editorial revisions,
+annotations, elaborations, or other modifications represent, as a whole, an
+original work of authorship. For the purposes of this License, Derivative Works
+shall not include works that remain separable from, or merely link (or bind by
+name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original
+version of the Work and any modifications or additions to that Work or
+Derivative Works thereof, that is intentionally submitted to Licensor for
+inclusion in the Work by the copyright owner or by an individual or Legal
+Entity authorized to submit on behalf of the copyright owner. For the purposes
+of this definition, "submitted" means any form of electronic, verbal, or
+written communication sent to the Licensor or its representatives, including
+but not limited to communication on electronic mailing lists, source code
+control systems, and issue tracking systems that are managed by, or on behalf
+of, the Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise designated in
+writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf
+of whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable copyright license to
+reproduce, prepare Derivative Works of, publicly display, publicly perform,
+sub-license, and distribute the Work and such Derivative Works in Source or
+Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this
+section) patent license to make, have made, use, offer to sell, sell, import,
+and otherwise transfer the Work, where such license applies only to those
+patent claims licensable by such Contributor that are necessarily infringed by
+their Contribution(s) alone or by combination of their Contribution(s) with the
+Work to which such Contribution(s) was submitted. If You institute patent
+litigation against any entity (including a cross-claim or counterclaim in a
+lawsuit) alleging that the Work or a Contribution incorporated within the Work
+constitutes direct or contributory patent infringement, then any patent
+licenses granted to You under this License for that Work shall terminate as of
+the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or
+Derivative Works thereof in any medium, with or without modifications, and in
+Source or Object form, provided that You meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative Works a copy
+of this License; and
+
+(b) You must cause any modified files to carry prominent notices stating that
+You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works that You
+distribute, all copyright, patent, trademark, and attribution notices from the
+Source form of the Work, excluding those notices that do not pertain to any
+part of the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its distribution, then
+any Derivative Works that You distribute must include a readable copy of the
+attribution notices contained within such NOTICE file, excluding those notices
+that do not pertain to any part of the Derivative Works, in at least one of the
+following places: within a NOTICE text file distributed as part of the
+Derivative Works; within the Source form or documentation, if provided along
+with the Derivative Works; or, within a display generated by the Derivative
+Works, if and wherever such third-party notices normally appear. The contents
+of the NOTICE file are for informational purposes only and do not modify the
+License. You may add Your own attribution notices within Derivative Works that
+You distribute, alongside or as an addendum to the NOTICE text from the Work,
+provided that such additional attribution notices cannot be construed as
+modifying the License.
+
+You may add Your own copyright statement to Your modifications and may provide
+additional or different license terms and conditions for use, reproduction, or
+distribution of Your modifications, or for any such Derivative Works as a
+whole, provided Your use, reproduction, and distribution of the Work otherwise
+complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any
+Contribution intentionally submitted for inclusion in the Work by You to the
+Licensor shall be under the terms and conditions of this License, without any
+additional terms or conditions. Notwithstanding the above, nothing herein shall
+supersede or modify the terms of any separate license agreement you may have
+executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names,
+trademarks, service marks, or product names of the Licensor, except as required
+for reasonable and customary use in describing the origin of the Work and
+reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
+writing, Licensor provides the Work (and each Contributor provides its
+Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied, including, without limitation, any warranties
+or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any risks
+associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in
+tort (including negligence), contract, or otherwise, unless required by
+applicable law (such as deliberate and grossly negligent acts) or agreed to in
+writing, shall any Contributor be liable to You for damages, including any
+direct, indirect, special, incidental, or consequential damages of any
+character arising as a result of this License or out of the use or inability to
+use the Work (including but not limited to damages for loss of goodwill, work
+stoppage, computer failure or malfunction, or any and all other commercial
+damages or losses), even if such Contributor has been advised of the
+possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or
+Derivative Works thereof, You may choose to offer, and charge a fee for,
+acceptance of support, warranty, indemnity, or other liability obligations
+and/or rights consistent with this License. However, in accepting such
+obligations, You may act only on Your own behalf and on Your sole
+responsibility, not on behalf of any other Contributor, and only if You agree
+to indemnify, defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason of your
+accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following boilerplate
+notice, with the fields enclosed by brackets "[]" replaced with your own
+identifying information. (Don't include the brackets!) The text should be
+enclosed in the appropriate comment syntax for the file format. We also
+recommend that a file or class name and description of purpose be included on
+the same "printed page" as the copyright notice for easier identification
+within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,128 @@
+# Zigrix
+
+Zigrix is a **multi-project parallel task orchestration CLI** for agent-assisted development workflows.
+
+It turns ad-hoc delegation into a file-backed, inspectable flow with:
+- global runtime state (`~/.zigrix/`) — tasks are not project-bound
+- task dispatch and finalization with full orchestration metadata
+- agent registry + participation control
+- rule/template validation and recovery
+- evidence merge + final report rendering
+- OpenClaw integration (skill registration + PATH stabilization)
+- release-friendly Node/TypeScript packaging
+
+## Current status
+- Stage: **alpha, productization in progress**
+- Main implementation: **Node/TypeScript at repository root**
+- Legacy reference: **Python prototype under `legacy-python/`**
+- Supported first: **macOS, Linux**
+- Packaging path: **GitHub Releases + install.sh**, npm publish prepared for manual follow-up
+
+## Intended user model
+- **Human operator:** install Zigrix, run `zigrix onboard`, and stop there unless recovery or advanced maintenance is needed.
+- **OpenClaw agents:** use the operational Zigrix commands (`task`, `worker`, `evidence`, `report`, `pipeline`, and low-level config surfaces) after onboarding.
+- **Advanced maintenance:** `zigrix configure` for reconfiguration, `zigrix reset` for recovery.
+
+See `docs/onboarding-ownership-model.md` for the product-direction source of truth.
+
+## Quick start
+
+```bash
+# Install and onboard (one-time human setup)
+./install.sh
+zigrix onboard
+
+# Verify readiness
+zigrix doctor
+```
+
+`zigrix onboard` will:
+1. Create `~/.zigrix/` with default config
+2. Detect OpenClaw and import agents from `openclaw.json`
+3. Seed rule files from `orchestration/rules/`
+4. Ensure `zigrix` is reachable from PATH (creates symlink if needed)
+5. Register zigrix skill packs into OpenClaw's `~/.openclaw/skills/`
+
+## What Zigrix can do today
+- **dispatch** tasks with full orchestration metadata (replaces `dev_dispatch.py`)
+- **finalize** tasks with evidence merge and execution unit checks (replaces `dev_finalize.py`)
+- validate, inspect, change, diff, and reset config
+- manage agent registry and orchestration membership
+- validate, render, edit, diff, and reset rules/templates
+- create and track tasks with append-only event history
+- manage worker/evidence/report lifecycle
+- detect stale tasks, verify state consistency, and recover state
+- **configure** agents, rules, PATH, skills, and workspace after initial setup
+
+## Recovery-first operations
+Reset one broken template:
+```bash
+zigrix template reset workerPrompt --yes
+```
+
+Reset all config back to defaults:
+```bash
+zigrix reset config --yes
+```
+
+Reset runtime state only:
+```bash
+zigrix reset state --yes
+```
+
+## Documentation map
+- `docs/quickstart.md`
+- `docs/onboarding-ownership-model.md`
+- `docs/product-decisions.md`
+- `docs/cli-spec.md`
+- `docs/openclaw-integration.md`
+- `docs/concepts.md`
+- `docs/runtime-flow.md`
+- `docs/state-layout.md`
+- `docs/troubleshooting.md`
+- `docs/v1-scope.md`
+- `docs/non-goals.md`
+- `docs/install.md`
+- `docs/release-process.md`
+- `docs/versioning.md`
+- `docs/known-limitations.md`
+- `docs/npm-publish-manual.md`
+
+## Repository layout
+```text
+zigrix/
+├─ src/                # Node/TS main implementation
+├─ tests/              # test coverage
+├─ skills/             # OpenClaw skill packs
+├─ examples/           # example workflows
+├─ scripts/            # smoke / release helpers
+├─ docs/               # product + architecture docs
+├─ legacy-python/      # reference prototype only
+└─ .github/            # CI + issue/PR templates
+```
+
+## Product stance
+- local-first
+- config-first
+- recoverable by default
+- OpenClaw-friendly, not OpenClaw-dependent in the core
+- stability before speculative expansion
+
+## Non-goals right now
+- hosted control plane
+- GUI/TUI product surface
+- generalized plugin SDK
+- automatic npm publish execution
+- Windows-first support
+
+## Contributing
+See `CONTRIBUTING.md`.
+
+## Support
+See `SUPPORT.md`.
+
+## Security
+See `SECURITY.md`.
+
+## License
+Apache-2.0

package/dist/agents/registry.d.ts

@@ -0,0 +1,28 @@
+import { type ZigrixConfig } from '../config/schema.js';
+export type AgentMutationResult = {
+    config: ZigrixConfig;
+    changed: boolean;
+    agentId: string;
+};
+export declare function listAgents(config: ZigrixConfig): Array<{
+    id: string;
+    label: string;
+    role: string;
+    runtime: string;
+    enabled: boolean;
+    participant: boolean;
+    excluded: boolean;
+}>;
+export declare function addAgent(config: ZigrixConfig, params: {
+    id: string;
+    role: string;
+    runtime: string;
+    label?: string;
+    enabled?: boolean;
+    include?: boolean;
+}): AgentMutationResult;
+export declare function removeAgent(config: ZigrixConfig, agentId: string): AgentMutationResult;
+export declare function includeAgent(config: ZigrixConfig, agentId: string): AgentMutationResult;
+export declare function excludeAgent(config: ZigrixConfig, agentId: string): AgentMutationResult;
+export declare function setAgentEnabled(config: ZigrixConfig, agentId: string, enabled: boolean): AgentMutationResult;
+export declare function setAgentRole(config: ZigrixConfig, agentId: string, role: string): AgentMutationResult;

package/dist/agents/registry.js

@@ -0,0 +1,98 @@
+import { zigrixConfigSchema } from '../config/schema.js';
+function assertAgentExists(config, agentId) {
+    if (!config.agents.registry[agentId]) {
+        throw new Error(`agent not found: ${agentId}`);
+    }
+}
+function unique(items) {
+    return [...new Set(items)];
+}
+export function listAgents(config) {
+    return Object.entries(config.agents.registry)
+        .map(([id, agent]) => ({
+        id,
+        label: agent.label,
+        role: agent.role,
+        runtime: agent.runtime,
+        enabled: agent.enabled,
+        participant: config.agents.orchestration.participants.includes(id),
+        excluded: config.agents.orchestration.excluded.includes(id),
+    }))
+        .sort((a, b) => a.id.localeCompare(b.id));
+}
+export function addAgent(config, params) {
+    if (config.agents.registry[params.id]) {
+        throw new Error(`agent already exists: ${params.id}`);
+    }
+    const next = structuredClone(config);
+    next.agents.registry[params.id] = {
+        label: params.label ?? params.id,
+        role: params.role,
+        runtime: params.runtime,
+        enabled: params.enabled ?? true,
+        metadata: {},
+    };
+    if (params.include) {
+        next.agents.orchestration.participants = unique([...next.agents.orchestration.participants, params.id]);
+        next.agents.orchestration.excluded = next.agents.orchestration.excluded.filter((item) => item !== params.id);
+    }
+    return {
+        config: zigrixConfigSchema.parse(next),
+        changed: true,
+        agentId: params.id,
+    };
+}
+export function removeAgent(config, agentId) {
+    assertAgentExists(config, agentId);
+    const next = structuredClone(config);
+    delete next.agents.registry[agentId];
+    next.agents.orchestration.participants = next.agents.orchestration.participants.filter((item) => item !== agentId);
+    next.agents.orchestration.excluded = next.agents.orchestration.excluded.filter((item) => item !== agentId);
+    return {
+        config: zigrixConfigSchema.parse(next),
+        changed: true,
+        agentId,
+    };
+}
+export function includeAgent(config, agentId) {
+    assertAgentExists(config, agentId);
+    const next = structuredClone(config);
+    next.agents.orchestration.participants = unique([...next.agents.orchestration.participants, agentId]);
+    next.agents.orchestration.excluded = next.agents.orchestration.excluded.filter((item) => item !== agentId);
+    return {
+        config: zigrixConfigSchema.parse(next),
+        changed: true,
+        agentId,
+    };
+}
+export function excludeAgent(config, agentId) {
+    assertAgentExists(config, agentId);
+    const next = structuredClone(config);
+    next.agents.orchestration.excluded = unique([...next.agents.orchestration.excluded, agentId]);
+    next.agents.orchestration.participants = next.agents.orchestration.participants.filter((item) => item !== agentId);
+    return {
+        config: zigrixConfigSchema.parse(next),
+        changed: true,
+        agentId,
+    };
+}
+export function setAgentEnabled(config, agentId, enabled) {
+    assertAgentExists(config, agentId);
+    const next = structuredClone(config);
+    next.agents.registry[agentId].enabled = enabled;
+    return {
+        config: zigrixConfigSchema.parse(next),
+        changed: true,
+        agentId,
+    };
+}
+export function setAgentRole(config, agentId, role) {
+    assertAgentExists(config, agentId);
+    const next = structuredClone(config);
+    next.agents.registry[agentId].role = role;
+    return {
+        config: zigrixConfigSchema.parse(next),
+        changed: true,
+        agentId,
+    };
+}

package/dist/config/defaults.d.ts

@@ -0,0 +1,66 @@
+export declare const ZIGRIX_HOME: string;
+export declare const defaultConfig: {
+    readonly paths: {
+        readonly baseDir: string;
+        readonly tasksDir: string;
+        readonly evidenceDir: string;
+        readonly promptsDir: string;
+        readonly eventsFile: string;
+        readonly indexFile: string;
+        readonly runsDir: string;
+        readonly rulesDir: string;
+    };
+    readonly workspace: {
+        readonly projectsBaseDir: "";
+    };
+    readonly agents: {
+        readonly registry: {};
+        readonly orchestration: {
+            readonly participants: readonly [];
+            readonly excluded: readonly [];
+        };
+    };
+    readonly rules: {
+        readonly scales: {
+            readonly simple: {
+                readonly requiredRoles: readonly ["orchestrator"];
+                readonly optionalRoles: readonly ["qa"];
+            };
+            readonly normal: {
+                readonly requiredRoles: readonly ["orchestrator", "qa"];
+                readonly optionalRoles: readonly ["frontend", "backend"];
+            };
+            readonly risky: {
+                readonly requiredRoles: readonly ["orchestrator", "qa", "security"];
+                readonly optionalRoles: readonly ["frontend", "backend", "infra"];
+            };
+        };
+        readonly completion: {
+            readonly requireQa: true;
+            readonly requireEvidence: true;
+            readonly requireUserReport: true;
+        };
+        readonly stale: {
+            readonly defaultHours: 24;
+        };
+    };
+    readonly templates: {
+        readonly workerPrompt: {
+            readonly format: "markdown";
+            readonly version: 1;
+            readonly placeholders: readonly ["taskId", "title", "scale", "agentId", "description"];
+            readonly body: "## Worker Assignment: {{taskId}}\n- title: {{title}}\n- scale: {{scale}}\n- agent: {{agentId}}\n- description: {{description}}";
+        };
+        readonly finalReport: {
+            readonly format: "markdown";
+            readonly version: 1;
+            readonly placeholders: readonly ["taskId", "title", "status", "summary"];
+            readonly body: "## Final Report: {{taskId}}\n- title: {{title}}\n- status: {{status}}\n- summary: {{summary}}";
+        };
+    };
+    readonly runtime: {
+        readonly outputMode: "text";
+        readonly jsonIndent: 2;
+    };
+};
+export type DefaultConfig = typeof defaultConfig;

package/dist/config/defaults.js

@@ -0,0 +1,58 @@
+import path from 'node:path';
+import os from 'node:os';
+export const ZIGRIX_HOME = process.env.ZIGRIX_HOME ?? path.join(os.homedir(), '.zigrix');
+export const defaultConfig = {
+    paths: {
+        baseDir: ZIGRIX_HOME,
+        tasksDir: path.join(ZIGRIX_HOME, 'tasks'),
+        evidenceDir: path.join(ZIGRIX_HOME, 'evidence'),
+        promptsDir: path.join(ZIGRIX_HOME, 'prompts'),
+        eventsFile: path.join(ZIGRIX_HOME, 'tasks.jsonl'),
+        indexFile: path.join(ZIGRIX_HOME, 'index.json'),
+        runsDir: path.join(ZIGRIX_HOME, 'runs'),
+        rulesDir: path.join(ZIGRIX_HOME, 'rules'),
+    },
+    workspace: {
+        projectsBaseDir: '',
+    },
+    agents: {
+        registry: {},
+        orchestration: {
+            participants: [],
+            excluded: [],
+        },
+    },
+    rules: {
+        scales: {
+            simple: { requiredRoles: ['orchestrator'], optionalRoles: ['qa'] },
+            normal: { requiredRoles: ['orchestrator', 'qa'], optionalRoles: ['frontend', 'backend'] },
+            risky: { requiredRoles: ['orchestrator', 'qa', 'security'], optionalRoles: ['frontend', 'backend', 'infra'] },
+        },
+        completion: {
+            requireQa: true,
+            requireEvidence: true,
+            requireUserReport: true,
+        },
+        stale: {
+            defaultHours: 24,
+        },
+    },
+    templates: {
+        workerPrompt: {
+            format: 'markdown',
+            version: 1,
+            placeholders: ['taskId', 'title', 'scale', 'agentId', 'description'],
+            body: '## Worker Assignment: {{taskId}}\n- title: {{title}}\n- scale: {{scale}}\n- agent: {{agentId}}\n- description: {{description}}',
+        },
+        finalReport: {
+            format: 'markdown',
+            version: 1,
+            placeholders: ['taskId', 'title', 'status', 'summary'],
+            body: '## Final Report: {{taskId}}\n- title: {{title}}\n- status: {{status}}\n- summary: {{summary}}',
+        },
+    },
+    runtime: {
+        outputMode: 'text',
+        jsonIndent: 2,
+    },
+};

package/dist/config/load.d.ts

@@ -0,0 +1,13 @@
+import { type ZigrixConfig } from './schema.js';
+export type LoadedConfig = {
+    config: ZigrixConfig;
+    configPath: string | null;
+    baseDir: string;
+};
+export declare function loadConfig(options?: {
+    baseDir?: string;
+    configPath?: string;
+}): LoadedConfig;
+export declare function writeConfigFile(targetPath: string, config: ZigrixConfig): string;
+export declare function writeDefaultConfig(baseDir?: string, force?: boolean): string;
+export declare function getConfigValue(config: ZigrixConfig, dottedPath?: string): unknown;

package/dist/config/load.js

@@ -0,0 +1,96 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import YAML from 'yaml';
+import { defaultConfig, ZIGRIX_HOME } from './defaults.js';
+import { zigrixConfigSchema } from './schema.js';
+const CONFIG_CANDIDATES = [
+    'zigrix.config.json',
+    'zigrix.config.yaml',
+    'zigrix.config.yml',
+];
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function deepMerge(base, override) {
+    if (!isObject(base) || !isObject(override)) {
+        return override ?? base;
+    }
+    const merged = { ...base };
+    for (const [key, value] of Object.entries(override)) {
+        const current = merged[key];
+        if (isObject(current) && isObject(value)) {
+            merged[key] = deepMerge(current, value);
+        }
+        else {
+            merged[key] = value;
+        }
+    }
+    return merged;
+}
+function parseConfigFile(filePath) {
+    const raw = fs.readFileSync(filePath, 'utf8');
+    if (filePath.endsWith('.yaml') || filePath.endsWith('.yml')) {
+        return YAML.parse(raw);
+    }
+    return JSON.parse(raw);
+}
+function resolveConfigPath(baseDir, explicitPath) {
+    if (explicitPath) {
+        return path.resolve(explicitPath);
+    }
+    for (const candidate of CONFIG_CANDIDATES) {
+        const fullPath = path.join(baseDir, candidate);
+        if (fs.existsSync(fullPath)) {
+            return fullPath;
+        }
+    }
+    return null;
+}
+function applyEnvOverrides(config) {
+    const copy = structuredClone(config);
+    if (process.env.ZIGRIX_OUTPUT_MODE === 'text' || process.env.ZIGRIX_OUTPUT_MODE === 'json') {
+        copy.runtime.outputMode = process.env.ZIGRIX_OUTPUT_MODE;
+    }
+    if (process.env.ZIGRIX_JSON_INDENT) {
+        const indent = Number(process.env.ZIGRIX_JSON_INDENT);
+        if (!Number.isNaN(indent)) {
+            copy.runtime.jsonIndent = indent;
+        }
+    }
+    return copy;
+}
+export function loadConfig(options) {
+    const baseDir = path.resolve(options?.baseDir ?? ZIGRIX_HOME);
+    const configPath = resolveConfigPath(baseDir, options?.configPath);
+    const parsed = configPath ? parseConfigFile(configPath) : {};
+    const merged = deepMerge(structuredClone(defaultConfig), parsed);
+    const withEnv = applyEnvOverrides(merged);
+    const result = zigrixConfigSchema.parse(withEnv);
+    return { config: result, configPath, baseDir };
+}
+export function writeConfigFile(targetPath, config) {
+    const resolvedPath = path.resolve(targetPath);
+    fs.mkdirSync(path.dirname(resolvedPath), { recursive: true });
+    fs.writeFileSync(resolvedPath, `${JSON.stringify(zigrixConfigSchema.parse(config), null, 2)}\n`, 'utf8');
+    return resolvedPath;
+}
+export function writeDefaultConfig(baseDir, force = false) {
+    const resolvedBase = path.resolve(baseDir ?? ZIGRIX_HOME);
+    const targetPath = path.join(resolvedBase, 'zigrix.config.json');
+    if (fs.existsSync(targetPath) && !force) {
+        throw new Error(`config already exists: ${targetPath}`);
+    }
+    fs.mkdirSync(resolvedBase, { recursive: true });
+    return writeConfigFile(targetPath, structuredClone(defaultConfig));
+}
+export function getConfigValue(config, dottedPath) {
+    if (!dottedPath)
+        return config;
+    return dottedPath.split('.').reduce((acc, key) => {
+        if (acc && typeof acc === 'object' && key in acc) {
+            return acc[key];
+        }
+        return undefined;
+    }, config);
+}

package/dist/config/mutate.d.ts

@@ -0,0 +1,10 @@
+import type { ZigrixConfig } from './schema.js';
+export declare function parseConfigInput(raw: string): unknown;
+export declare function getValueAtPath(value: unknown, dottedPath?: string): unknown;
+export declare function setValueAtPath<T extends Record<string, unknown>>(target: T, dottedPath: string, nextValue: unknown): T;
+export declare function resetValueAtPath(config: ZigrixConfig, dottedPath?: string): ZigrixConfig;
+export declare function diffValues(current: unknown, baseline: unknown): {
+    changed: boolean;
+    current: unknown;
+    baseline: unknown;
+};