zigrix 0.1.0-alpha.3 → 0.1.0-alpha.5

package/README.md

@@ -36,6 +36,36 @@ zigrix onboard
 zigrix doctor
 ```
 
+### Prerequisites: Node.js version
+
+Zigrix requires Node.js **22 or later**. Verify before installing:
+
+```bash
+node --version   # must be v22.x or higher
+```
+
+If you use **nvm**, make sure the correct version is active:
+
+```bash
+nvm use 22        # or: nvm use --lts
+node --version    # confirm v22+
+```
+
+> **Important (nvm users):** `npm link` binds `zigrix` to whichever Node version is active at install time.
+> If you switch node versions later, re-run the install to rebind:
+> ```bash
+> npm run build && npm link
+> ```
+
+### Version mismatch troubleshooting
+
+If `zigrix --version` shows an unexpected version after updating, rebuild and relink:
+
+```bash
+npm run build && npm link
+zigrix --version   # should now match package.json
+```
+
 `zigrix onboard` will:
 1. Create `~/.zigrix/` with default config
 2. Detect OpenClaw and import agents from `openclaw.json`

package/dist/dashboard.d.ts

@@ -0,0 +1,35 @@
+/** Default port for zigrix dashboard */
+export declare const DASHBOARD_DEFAULT_PORT = 3838;
+/**
+ * Resolve the dashboard directory from a given dist index.js path.
+ * Convention: dist/index.js → ../../dashboard (i.e. <package-root>/dashboard)
+ *
+ * The path "../../dashboard" is interpreted relative to the FILE dist/index.js:
+ *   - First ".." removes the filename component  → <pkg>/dist/
+ *   - Second ".." removes the dist directory     → <pkg>/  (package root)
+ *   - "dashboard"                                → <pkg>/dashboard
+ *
+ * Using path.resolve(distIndexPath, '..', '..', 'dashboard') achieves exactly
+ * this because path.resolve treats each ".." as stripping the last segment of
+ * the current accumulated path (including the filename on the first step).
+ */
+export declare function resolveDashboardDir(distIndexPath: string): string;
+/**
+ * Check whether a TCP port is already in use.
+ * Returns true if the port is busy (another process is listening).
+ */
+export declare function isPortBusy(port: number): Promise<boolean>;
+export interface RunDashboardOptions {
+    port?: number;
+}
+/**
+ * Main entry point for `zigrix dashboard`.
+ *
+ * Steps:
+ *  1. Resolve dashboard directory relative to this module's dist path.
+ *  2. Check port availability; fail clearly on conflict.
+ *  3. Auto-install if node_modules is missing.
+ *  4. Auto-build if .next directory is missing.
+ *  5. Spawn `next start -p <port>` in foreground and wait.
+ */
+export declare function runDashboard(options?: RunDashboardOptions): Promise<void>;

package/dist/dashboard.js

@@ -0,0 +1,113 @@
+import { execSync, spawn } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as net from 'node:net';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Default port for zigrix dashboard */
+export const DASHBOARD_DEFAULT_PORT = 3838;
+/**
+ * Resolve the dashboard directory from a given dist index.js path.
+ * Convention: dist/index.js → ../../dashboard (i.e. <package-root>/dashboard)
+ *
+ * The path "../../dashboard" is interpreted relative to the FILE dist/index.js:
+ *   - First ".." removes the filename component  → <pkg>/dist/
+ *   - Second ".." removes the dist directory     → <pkg>/  (package root)
+ *   - "dashboard"                                → <pkg>/dashboard
+ *
+ * Using path.resolve(distIndexPath, '..', '..', 'dashboard') achieves exactly
+ * this because path.resolve treats each ".." as stripping the last segment of
+ * the current accumulated path (including the filename on the first step).
+ */
+export function resolveDashboardDir(distIndexPath) {
+    return path.resolve(distIndexPath, '..', '..', 'dashboard');
+}
+/**
+ * Check whether a TCP port is already in use.
+ * Returns true if the port is busy (another process is listening).
+ */
+export function isPortBusy(port) {
+    return new Promise((resolve) => {
+        const server = net.createServer();
+        server.once('error', (err) => {
+            if (err.code === 'EADDRINUSE') {
+                resolve(true);
+            }
+            else {
+                // Unexpected error — treat as busy to be safe
+                resolve(true);
+            }
+        });
+        server.once('listening', () => {
+            server.close(() => resolve(false));
+        });
+        server.listen(port, '127.0.0.1');
+    });
+}
+/**
+ * Main entry point for `zigrix dashboard`.
+ *
+ * Steps:
+ *  1. Resolve dashboard directory relative to this module's dist path.
+ *  2. Check port availability; fail clearly on conflict.
+ *  3. Auto-install if node_modules is missing.
+ *  4. Auto-build if .next directory is missing.
+ *  5. Spawn `next start -p <port>` in foreground and wait.
+ */
+export async function runDashboard(options = {}) {
+    const port = options.port ?? DASHBOARD_DEFAULT_PORT;
+    // Resolve dashboard directory.
+    // When running from compiled dist/index.js: import.meta.url resolves to
+    // file:///…/dist/index.js, so dirname is …/dist.
+    // ../../dashboard therefore points to <package-root>/dashboard.
+    const selfPath = fileURLToPath(import.meta.url);
+    const dashboardDir = resolveDashboardDir(selfPath);
+    if (!fs.existsSync(dashboardDir)) {
+        throw new Error(`Dashboard directory not found: ${dashboardDir}`);
+    }
+    // --- Port conflict check ---
+    const busy = await isPortBusy(port);
+    if (busy) {
+        throw new Error(`Port ${port} is already in use. ` +
+            `Stop the conflicting process or specify a different port with --port.`);
+    }
+    // --- Auto-install dependencies ---
+    const nodeModulesDir = path.join(dashboardDir, 'node_modules');
+    if (!fs.existsSync(nodeModulesDir)) {
+        console.log('📦 dashboard/node_modules not found — running npm install…');
+        execSync('npm install', { cwd: dashboardDir, stdio: 'inherit' });
+    }
+    // --- Auto-build ---
+    const nextBuildDir = path.join(dashboardDir, '.next');
+    if (!fs.existsSync(nextBuildDir)) {
+        console.log('🔨 dashboard/.next not found — running npm run build…');
+        execSync('npm run build', { cwd: dashboardDir, stdio: 'inherit' });
+    }
+    // --- Launch Next.js in foreground ---
+    console.log(`🚀 Starting zigrix dashboard on http://localhost:${port}`);
+    const nextBin = path.join(dashboardDir, 'node_modules', '.bin', 'next');
+    const child = spawn(nextBin, ['start', '-p', String(port)], {
+        cwd: dashboardDir,
+        stdio: 'inherit',
+        env: { ...process.env },
+    });
+    await new Promise((resolve, reject) => {
+        child.on('exit', (code, signal) => {
+            if (code === 0 || signal === 'SIGINT' || signal === 'SIGTERM') {
+                resolve();
+            }
+            else {
+                reject(new Error(`next start exited with code ${code ?? signal}`));
+            }
+        });
+        child.on('error', (err) => {
+            reject(new Error(`Failed to start next: ${err.message}`));
+        });
+        // Forward SIGINT/SIGTERM to child for clean shutdown
+        const forward = (sig) => {
+            if (!child.killed)
+                child.kill(sig);
+        };
+        process.once('SIGINT', () => forward('SIGINT'));
+        process.once('SIGTERM', () => forward('SIGTERM'));
+    });
+}

package/dist/index.js

@@ -21,6 +21,7 @@ import { loadRunRecord } from './runner/store.js';
 import { ensureBaseState, resolvePaths } from './state/paths.js';
 import { applyStalePolicy, createTask, findStaleTasks, listTaskEvents, listTasks, loadTask, rebuildIndex, recordTaskProgress, updateTaskStatus, } from './state/tasks.js';
 import { verifyState } from './state/verify.js';
+import { runDashboard, DASHBOARD_DEFAULT_PORT } from './dashboard.js';
 const STATUS_MAP = {
     start: 'IN_PROGRESS',
     report: 'REPORTED',
@@ -57,11 +58,12 @@ function loadRuntime(options) {
     const loaded = loadConfig({ baseDir: options.baseDir, configPath: options.config });
     return { ...loaded, paths: resolvePaths(loaded.config) };
 }
+const { version: pkgVersion } = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf-8'));
 const program = new Command();
 program
     .name('zigrix')
     .description('Zigrix — multi-project parallel task orchestration CLI')
-    .version('0.1.0-alpha.0');
+    .version(pkgVersion);
 const config = program.command('config').description('Inspect Zigrix config');
 const agent = program.command('agent').description('Manage Zigrix agent registry and orchestration membership');
 const rule = program.command('rule').description('Inspect and validate rule assets');
@@ -785,6 +787,20 @@ program
     const loaded = loadConfig({ baseDir: options.baseDir, configPath: options.config });
     printValue(loadRunRecord(loaded.config, runIdOrPath), true);
 });
+// ─── dashboard ──────────────────────────────────────────────────────────────
+program
+    .command('dashboard')
+    .description('Start the zigrix web dashboard (Next.js) in the foreground')
+    .option('--port <n>', `TCP port to listen on (default: ${DASHBOARD_DEFAULT_PORT})`, String(DASHBOARD_DEFAULT_PORT))
+    .action(async (options) => {
+    const port = parseInt(options.port, 10);
+    if (isNaN(port) || port < 1 || port > 65535) {
+        console.error(`Invalid port: ${options.port}`);
+        process.exitCode = 1;
+        return;
+    }
+    await runDashboard({ port });
+});
 program.parseAsync(process.argv).catch((error) => {
     console.error(error instanceof Error ? error.message : String(error));
     process.exitCode = 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zigrix",
-  "version": "0.1.0-alpha.3",
+  "version": "0.1.0-alpha.5",
   "type": "module",
   "description": "Multi-project parallel task orchestration CLI for agent-assisted development",
   "license": "Apache-2.0",