@xnetjs/cli 0.3.1 → 0.4.0

package/README.md

@@ -2,6 +2,11 @@
 
 CLI tools for schema migration workflows, schema diffing, and data integrity diagnostics.
 
+> **Alpha software.** xNet is released but early: this package is on npm and
+> usable today, but its API can change between releases, sometimes without a
+> migration path. Pin your version. See the
+> [project README](https://github.com/crs48/xNet#readme) for what alpha means here.
+
 ## Installation
 
 ```bash

package/dist/cli.js

@@ -518,7 +518,7 @@ function buildBridgeServer(options, runner = new NodeCommandRunner()) {
   });
 }
 function registerBridgeCommand(program2) {
-  const bridge = program2.command("bridge").description("Run the local agent bridge for XNet's AI chat panel");
+  const bridge = program2.command("bridge").description("Run the local agent bridge for xNet's AI chat panel");
   bridge.command("serve").description("Serve the agent bridge on loopback (default :31416), driving your own agent CLI").option("--agent <command>", "Agent CLI to drive (claude, codex, \u2026)", "claude").option("--host <host>", "Loopback host (default 127.0.0.1)").option("--port <n>", `Port (default ${DEFAULT_BRIDGE_PORT})`, parseIntOption2).option(
     "--allow-origin <origin...>",
     "Browser origins permitted (e.g. https://app.xnet.fyi for the web deployment)"
@@ -528,7 +528,7 @@ function registerBridgeCommand(program2) {
   ).option("--cwd <dir>", "Working directory the agent runs in (default current dir)").option(
     "--upstream <url>",
     "Front a raw OpenAI-compatible server (e.g. http://localhost:11434 for Ollama) instead of a CLI"
-  ).option("--upstream-model <id>", "Model id to request from --upstream (default llama3.2)").option("--code", "Enable POST /run agentic code tasks (worktree \u2192 gate \u2192 checkpoint/PR)").option("--mcp", "Give the agent XNet's workspace tools via `xnet mcp serve`").option(
+  ).option("--upstream-model <id>", "Model id to request from --upstream (default llama3.2)").option("--code", "Enable POST /run agentic code tasks (worktree \u2192 gate \u2192 checkpoint/PR)").option("--mcp", "Give the agent xNet's workspace tools via `xnet mcp serve`").option(
     "--mcp-api-url <url>",
     "xNet local API URL the MCP server talks to (default http://127.0.0.1:31415)"
   ).action(async (options) => {
@@ -555,7 +555,7 @@ function registerBridgeCommand(program2) {
     );
     console.error(`Pairing code: ${handle.pairingToken}`);
     console.error(
-      'In XNet, open the AI panel, select "Local bridge", and paste the pairing code.'
+      'In xNet, open the AI panel, select "Local bridge", and paste the pairing code.'
     );
     const shutdown = () => {
       void handle.stop().then(() => process.exit(0));
@@ -1032,8 +1032,8 @@ import {
 } from "@xnetjs/sync";
 async function getChalk() {
   try {
-    const chalk2 = await import("chalk");
-    return chalk2.default;
+    const chalk3 = await import("chalk");
+    return chalk3.default;
   } catch {
     const identity = (s) => s;
     return {
@@ -1102,114 +1102,114 @@ function formatDuration(ms) {
   return `${(ms / 1e3).toFixed(2)}s`;
 }
 async function doctorCommand(options) {
-  const chalk2 = await getChalk();
-  console.log(chalk2.bold("\nxNet Health Check\n"));
-  console.log(chalk2.dim("\u2500".repeat(50)));
+  const chalk3 = await getChalk();
+  console.log(chalk3.bold("\nxNet Health Check\n"));
+  console.log(chalk3.dim("\u2500".repeat(50)));
   try {
     let dataDir;
     let changes = [];
     try {
       dataDir = findDataDir(options.dataDir);
-      console.log(chalk2.gray(`Data directory: ${dataDir}`));
+      console.log(chalk3.gray(`Data directory: ${dataDir}`));
       changes = loadChangesFromDir(dataDir);
-      console.log(chalk2.gray(`Found ${changes.length} changes`));
+      console.log(chalk3.gray(`Found ${changes.length} changes`));
     } catch {
-      console.log(chalk2.yellow("\nNote: No data directory found."));
-      console.log(chalk2.gray("Use --data-dir to specify a data directory."));
-      console.log(chalk2.gray("Running with demo data...\n"));
+      console.log(chalk3.yellow("\nNote: No data directory found."));
+      console.log(chalk3.gray("Use --data-dir to specify a data directory."));
+      console.log(chalk3.gray("Running with demo data...\n"));
       changes = generateDemoChanges();
     }
     console.log();
-    console.log(chalk2.bold("Checking data integrity..."));
+    console.log(chalk3.bold("Checking data integrity..."));
     const report = options.quick ? await quickIntegrityCheck(changes) : await verifyIntegrity(changes);
     if (options.json) {
       console.log(JSON.stringify(report, null, 2));
       return;
     }
-    printIntegrityResults(report, chalk2, options.verbose);
+    printIntegrityResults(report, chalk3, options.verbose);
     console.log();
-    console.log(chalk2.bold("Analyzing change chains..."));
+    console.log(chalk3.bold("Analyzing change chains..."));
     const orphans = findOrphans(changes);
     const roots = findRoots(changes);
     const heads = findHeads(changes);
     const depth = getChainDepth(changes);
-    console.log(`  ${chalk2.green("\u2713")} Roots: ${roots.length}`);
-    console.log(`  ${chalk2.green("\u2713")} Heads: ${heads.length}`);
-    console.log(`  ${chalk2.green("\u2713")} Depth: ${depth}`);
+    console.log(`  ${chalk3.green("\u2713")} Roots: ${roots.length}`);
+    console.log(`  ${chalk3.green("\u2713")} Heads: ${heads.length}`);
+    console.log(`  ${chalk3.green("\u2713")} Depth: ${depth}`);
     if (orphans.length > 0) {
-      console.log(`  ${chalk2.yellow("\u26A0")} Orphans: ${orphans.length}`);
+      console.log(`  ${chalk3.yellow("\u26A0")} Orphans: ${orphans.length}`);
     } else {
-      console.log(`  ${chalk2.green("\u2713")} Orphans: 0`);
+      console.log(`  ${chalk3.green("\u2713")} Orphans: 0`);
     }
     console.log();
-    console.log(chalk2.bold("Checking schema compatibility..."));
-    console.log(chalk2.gray("  (Schema analysis requires @xnetjs/data integration)"));
+    console.log(chalk3.bold("Checking schema compatibility..."));
+    console.log(chalk3.gray("  (Schema analysis requires @xnetjs/data integration)"));
     console.log();
-    console.log(chalk2.bold("Checking sync state..."));
-    console.log(chalk2.gray("  (Sync analysis requires active SyncProvider)"));
+    console.log(chalk3.bold("Checking sync state..."));
+    console.log(chalk3.gray("  (Sync analysis requires active SyncProvider)"));
     console.log();
-    console.log(chalk2.dim("\u2500".repeat(50)));
+    console.log(chalk3.dim("\u2500".repeat(50)));
     const hasErrors = report.summary.errors > 0;
     const hasWarnings = report.summary.warnings > 0 || orphans.length > 0;
     if (hasErrors) {
-      console.log(chalk2.red(chalk2.bold("Status: UNHEALTHY")));
-      console.log(chalk2.red("  Data integrity issues detected. Run `xnet repair` to fix."));
+      console.log(chalk3.red(chalk3.bold("Status: UNHEALTHY")));
+      console.log(chalk3.red("  Data integrity issues detected. Run `xnet repair` to fix."));
     } else if (hasWarnings) {
-      console.log(chalk2.yellow(chalk2.bold("Status: HEALTHY with warnings")));
-      console.log(chalk2.gray("  Some issues detected but data is intact."));
+      console.log(chalk3.yellow(chalk3.bold("Status: HEALTHY with warnings")));
+      console.log(chalk3.gray("  Some issues detected but data is intact."));
     } else {
-      console.log(chalk2.green(chalk2.bold("Status: HEALTHY")));
-      console.log(chalk2.green("  All checks passed."));
+      console.log(chalk3.green(chalk3.bold("Status: HEALTHY")));
+      console.log(chalk3.green("  All checks passed."));
     }
     console.log();
   } catch (error) {
-    console.error(chalk2.red(`Error: ${error instanceof Error ? error.message : String(error)}`));
+    console.error(chalk3.red(`Error: ${error instanceof Error ? error.message : String(error)}`));
     process.exit(1);
   }
 }
-function printIntegrityResults(report, chalk2, verbose) {
+function printIntegrityResults(report, chalk3, verbose) {
   const { checked, valid, issues, summary, durationMs } = report;
   const percentage = checked > 0 ? Math.round(valid / checked * 100) : 100;
   if (issues.length === 0) {
-    console.log(`  ${chalk2.green("\u2713")} ${checked} changes verified (${percentage}% valid)`);
-    console.log(`  ${chalk2.green("\u2713")} Hash chains intact`);
-    console.log(`  ${chalk2.green("\u2713")} No issues detected`);
-    console.log(chalk2.gray(`  Completed in ${formatDuration(durationMs)}`));
+    console.log(`  ${chalk3.green("\u2713")} ${checked} changes verified (${percentage}% valid)`);
+    console.log(`  ${chalk3.green("\u2713")} Hash chains intact`);
+    console.log(`  ${chalk3.green("\u2713")} No issues detected`);
+    console.log(chalk3.gray(`  Completed in ${formatDuration(durationMs)}`));
   } else {
     console.log(
-      `  ${chalk2.yellow("!")} ${checked} changes checked (${valid} valid, ${checked - valid} issues)`
+      `  ${chalk3.yellow("!")} ${checked} changes checked (${valid} valid, ${checked - valid} issues)`
     );
     if (summary.errors > 0) {
-      console.log(`  ${chalk2.red("\u2717")} ${summary.errors} errors`);
+      console.log(`  ${chalk3.red("\u2717")} ${summary.errors} errors`);
     }
     if (summary.warnings > 0) {
-      console.log(`  ${chalk2.yellow("\u26A0")} ${summary.warnings} warnings`);
+      console.log(`  ${chalk3.yellow("\u26A0")} ${summary.warnings} warnings`);
     }
-    console.log(chalk2.gray(`  Completed in ${formatDuration(durationMs)}`));
+    console.log(chalk3.gray(`  Completed in ${formatDuration(durationMs)}`));
     if (verbose) {
       console.log();
-      console.log(chalk2.bold("Issues by type:"));
+      console.log(chalk3.bold("Issues by type:"));
       for (const [type, count] of Object.entries(summary.byType)) {
         if (count > 0) {
           console.log(`  - ${type}: ${count}`);
         }
       }
       console.log();
-      console.log(chalk2.bold("Details:"));
+      console.log(chalk3.bold("Details:"));
       for (const issue of issues.slice(0, 10)) {
-        const icon = issue.severity === "error" ? chalk2.red("\u2717") : chalk2.yellow("\u26A0");
+        const icon = issue.severity === "error" ? chalk3.red("\u2717") : chalk3.yellow("\u26A0");
         console.log(`  ${icon} [${issue.type}] ${issue.details}`);
         if (issue.repairAction) {
-          console.log(chalk2.gray(`      \u2192 ${issue.repairAction.description}`));
+          console.log(chalk3.gray(`      \u2192 ${issue.repairAction.description}`));
         }
       }
       if (issues.length > 10) {
-        console.log(chalk2.gray(`  ... and ${issues.length - 10} more`));
+        console.log(chalk3.gray(`  ... and ${issues.length - 10} more`));
       }
     }
     if (report.repairable) {
       console.log();
-      console.log(chalk2.cyan(`  Run \`xnet repair\` to fix these issues.`));
+      console.log(chalk3.cyan(`  Run \`xnet repair\` to fix these issues.`));
     }
   }
 }
@@ -1246,8 +1246,8 @@ function generateDemoChanges() {
   ];
 }
 async function repairCommand(options) {
-  const chalk2 = await getChalk();
-  console.log(chalk2.bold("\nxNet Data Repair\n"));
+  const chalk3 = await getChalk();
+  console.log(chalk3.bold("\nxNet Data Repair\n"));
   try {
     let dataDir;
     let changes = [];
@@ -1255,15 +1255,15 @@ async function repairCommand(options) {
       dataDir = findDataDir(options.dataDir);
       changes = loadChangesFromDir(dataDir);
     } catch {
-      console.log(chalk2.yellow("Note: No data directory found."));
-      console.log(chalk2.gray("Using demo data for illustration.\n"));
+      console.log(chalk3.yellow("Note: No data directory found."));
+      console.log(chalk3.gray("Using demo data for illustration.\n"));
       dataDir = "";
       changes = generateDemoChanges();
     }
-    console.log(chalk2.gray("Running integrity check..."));
+    console.log(chalk3.gray("Running integrity check..."));
     const report = await verifyIntegrity(changes);
     if (report.issues.length === 0) {
-      console.log(chalk2.green("\n\u2713 No issues found. Nothing to repair."));
+      console.log(chalk3.green("\n\u2713 No issues found. Nothing to repair."));
       return;
     }
     console.log(`
@@ -1272,7 +1272,7 @@ Found ${report.issues.length} issues:`);
     console.log(`  - ${report.summary.warnings} warnings`);
     console.log();
     if (options.dryRun) {
-      console.log(chalk2.yellow("DRY RUN - No changes will be made\n"));
+      console.log(chalk3.yellow("DRY RUN - No changes will be made\n"));
     }
     const { remainingIssues, repairCount } = await attemptRepair(changes, report.issues);
     if (options.json) {
@@ -1290,33 +1290,33 @@ Found ${report.issues.length} issues:`);
       );
       return;
     }
-    console.log(chalk2.bold("Repair results:"));
-    console.log(`  ${chalk2.green("\u2713")} Repaired: ${repairCount} issues`);
-    console.log(`  ${chalk2.yellow("!")} Remaining: ${remainingIssues.length} issues`);
+    console.log(chalk3.bold("Repair results:"));
+    console.log(`  ${chalk3.green("\u2713")} Repaired: ${repairCount} issues`);
+    console.log(`  ${chalk3.yellow("!")} Remaining: ${remainingIssues.length} issues`);
     if (remainingIssues.length > 0) {
       console.log();
-      console.log(chalk2.yellow("Issues that require manual intervention:"));
+      console.log(chalk3.yellow("Issues that require manual intervention:"));
       for (const issue of remainingIssues.slice(0, 5)) {
         console.log(`  - [${issue.type}] ${issue.details}`);
       }
       if (remainingIssues.length > 5) {
-        console.log(chalk2.gray(`  ... and ${remainingIssues.length - 5} more`));
+        console.log(chalk3.gray(`  ... and ${remainingIssues.length - 5} more`));
       }
     }
     if (!options.dryRun && dataDir && repairCount > 0) {
       console.log();
-      console.log(chalk2.gray("Note: Writing repaired changes requires NodeStore integration."));
-      console.log(chalk2.gray("Changes are prepared but not written to disk."));
+      console.log(chalk3.gray("Note: Writing repaired changes requires NodeStore integration."));
+      console.log(chalk3.gray("Changes are prepared but not written to disk."));
     }
     console.log();
   } catch (error) {
-    console.error(chalk2.red(`Error: ${error instanceof Error ? error.message : String(error)}`));
+    console.error(chalk3.red(`Error: ${error instanceof Error ? error.message : String(error)}`));
     process.exit(1);
   }
 }
 async function exportCommand(options) {
-  const chalk2 = await getChalk();
-  console.log(chalk2.bold("\nxNet Data Export\n"));
+  const chalk3 = await getChalk();
+  console.log(chalk3.bold("\nxNet Data Export\n"));
   try {
     let dataDir;
     let changes = [];
@@ -1324,14 +1324,14 @@ async function exportCommand(options) {
       dataDir = findDataDir(options.dataDir);
       changes = loadChangesFromDir(dataDir);
     } catch {
-      console.log(chalk2.yellow("Note: No data directory found."));
-      console.log(chalk2.gray("Using demo data for illustration.\n"));
+      console.log(chalk3.yellow("Note: No data directory found."));
+      console.log(chalk3.gray("Using demo data for illustration.\n"));
       dataDir = "";
       changes = generateDemoChanges();
     }
     const outputPath = resolve6(process.cwd(), options.output);
-    console.log(chalk2.gray(`Source: ${dataDir || "demo data"}`));
-    console.log(chalk2.gray(`Output: ${outputPath}`));
+    console.log(chalk3.gray(`Source: ${dataDir || "demo data"}`));
+    console.log(chalk3.gray(`Output: ${outputPath}`));
     console.log();
     const exportData = {
       version: 1,
@@ -1356,26 +1356,26 @@ async function exportCommand(options) {
     } else {
       writeFileSync3(outputPath, content, "utf-8");
     }
-    console.log(chalk2.green(`\u2713 Exported ${changes.length} changes`));
-    console.log(chalk2.gray(`  File size: ${Math.round(content.length / 1024)}KB`));
+    console.log(chalk3.green(`\u2713 Exported ${changes.length} changes`));
+    console.log(chalk3.gray(`  File size: ${Math.round(content.length / 1024)}KB`));
     console.log();
   } catch (error) {
-    console.error(chalk2.red(`Error: ${error instanceof Error ? error.message : String(error)}`));
+    console.error(chalk3.red(`Error: ${error instanceof Error ? error.message : String(error)}`));
     process.exit(1);
   }
 }
 async function importCommand(options) {
-  const chalk2 = await getChalk();
-  console.log(chalk2.bold("\nxNet Data Import\n"));
+  const chalk3 = await getChalk();
+  console.log(chalk3.bold("\nxNet Data Import\n"));
   try {
     const inputPath = resolve6(process.cwd(), options.input);
     if (!existsSync(inputPath)) {
-      console.error(chalk2.red(`Error: Input file not found: ${inputPath}`));
+      console.error(chalk3.red(`Error: Input file not found: ${inputPath}`));
       process.exit(1);
     }
-    console.log(chalk2.gray(`Input: ${inputPath}`));
+    console.log(chalk3.gray(`Input: ${inputPath}`));
     if (options.dryRun) {
-      console.log(chalk2.yellow("\nDRY RUN - No changes will be applied\n"));
+      console.log(chalk3.yellow("\nDRY RUN - No changes will be applied\n"));
     }
     const content = readFileSync(inputPath, "utf-8");
     let importData;
@@ -1390,43 +1390,43 @@ async function importCommand(options) {
       const lines = content.split("\n").filter((l) => l.trim());
       importData = { changes: lines.map((l) => JSON.parse(l)) };
     }
-    console.log(chalk2.gray(`Found ${importData.changes.length} changes to import`));
+    console.log(chalk3.gray(`Found ${importData.changes.length} changes to import`));
     console.log();
     const changes = importData.changes.map((c) => ({
       ...c,
       signature: typeof c.signature === "string" ? new Uint8Array(Buffer.from(c.signature, "base64")) : c.signature
     }));
-    console.log(chalk2.bold("Verifying import data..."));
+    console.log(chalk3.bold("Verifying import data..."));
     const report = await quickIntegrityCheck(changes);
     if (report.issues.length > 0) {
-      console.log(chalk2.yellow(`  \u26A0 ${report.issues.length} integrity issues found`));
+      console.log(chalk3.yellow(`  \u26A0 ${report.issues.length} integrity issues found`));
       if (report.summary.errors > 0) {
-        console.log(chalk2.red(`  ${report.summary.errors} errors may prevent import`));
+        console.log(chalk3.red(`  ${report.summary.errors} errors may prevent import`));
       }
     } else {
-      console.log(chalk2.green("  \u2713 All changes verified"));
+      console.log(chalk3.green("  \u2713 All changes verified"));
     }
     if (options.applyMigrations) {
       console.log();
-      console.log(chalk2.bold("Checking for required migrations..."));
-      console.log(chalk2.gray("  (Migration detection requires schema registry)"));
+      console.log(chalk3.bold("Checking for required migrations..."));
+      console.log(chalk3.gray("  (Migration detection requires schema registry)"));
     }
     console.log();
-    console.log(chalk2.bold("Import summary:"));
+    console.log(chalk3.bold("Import summary:"));
     console.log(`  Changes: ${changes.length}`);
     console.log(`  Roots: ${findRoots(changes).length}`);
     console.log(`  Heads: ${findHeads(changes).length}`);
     console.log(`  Chain depth: ${getChainDepth(changes)}`);
     if (!options.dryRun) {
       console.log();
-      console.log(chalk2.gray("Note: Writing imported changes requires NodeStore integration."));
-      console.log(chalk2.gray("Changes are validated but not written to storage."));
+      console.log(chalk3.gray("Note: Writing imported changes requires NodeStore integration."));
+      console.log(chalk3.gray("Changes are validated but not written to storage."));
     }
     console.log();
-    console.log(chalk2.green("\u2713 Import validation complete"));
+    console.log(chalk3.green("\u2713 Import validation complete"));
     console.log();
   } catch (error) {
-    console.error(chalk2.red(`Error: ${error instanceof Error ? error.message : String(error)}`));
+    console.error(chalk3.red(`Error: ${error instanceof Error ? error.message : String(error)}`));
     process.exit(1);
   }
 }
@@ -1755,8 +1755,8 @@ import { writeFileSync as writeFileSync4, readFileSync as readFileSync2, existsS
 import { resolve as resolve7 } from "path";
 async function getChalk2() {
   try {
-    const chalk2 = await import("chalk");
-    return chalk2.default;
+    const chalk3 = await import("chalk");
+    return chalk3.default;
   } catch {
     const identity = (s) => s;
     return {
@@ -1805,7 +1805,7 @@ function findSchema(schemaIRI, schemas) {
   return null;
 }
 async function analyzeCommand(options) {
-  const chalk2 = await getChalk2();
+  const chalk3 = await getChalk2();
   try {
     const fromParsed = parseSchemaIRI(options.from);
     const toParsed = parseSchemaIRI(options.to);
@@ -1816,8 +1816,8 @@ async function analyzeCommand(options) {
     const fromSchema = findSchema(options.from, schemas);
     const toSchema = findSchema(options.to, schemas);
     if (!fromSchema || !toSchema) {
-      console.log(chalk2.yellow("\nNote: Schema file not provided. Showing example output.\n"));
-      console.log(chalk2.gray("Use --schema-file to load actual schemas from a JSON file.\n"));
+      console.log(chalk3.yellow("\nNote: Schema file not provided. Showing example output.\n"));
+      console.log(chalk3.gray("Use --schema-file to load actual schemas from a JSON file.\n"));
       const mockFromSchema = {
         "@id": `xnet://xnet.fyi/${fromParsed.name}@${fromParsed.version}`,
         "@type": "xnet://xnet.fyi/Schema",
@@ -1846,72 +1846,72 @@ async function analyzeCommand(options) {
           { "@id": `#priority`, name: "priority", type: "text", required: true }
         ]
       };
-      printAnalysisResult(diffSchemas(mockFromSchema, mockToSchema), options.json, chalk2);
+      printAnalysisResult(diffSchemas(mockFromSchema, mockToSchema), options.json, chalk3);
       return;
     }
     const diff = diffSchemas(fromSchema, toSchema);
-    printAnalysisResult(diff, options.json, chalk2);
+    printAnalysisResult(diff, options.json, chalk3);
   } catch (error) {
-    console.error(chalk2.red(`Error: ${error instanceof Error ? error.message : String(error)}`));
+    console.error(chalk3.red(`Error: ${error instanceof Error ? error.message : String(error)}`));
     process.exit(1);
   }
 }
-function printAnalysisResult(diff, json, chalk2) {
+function printAnalysisResult(diff, json, chalk3) {
   if (json) {
     console.log(JSON.stringify(diff, null, 2));
     return;
   }
-  console.log(chalk2.bold(`
+  console.log(chalk3.bold(`
 Schema changes: ${diff.fromVersion} \u2192 ${diff.toVersion}
 `));
   if (diff.changes.length === 0) {
-    console.log(chalk2.green("No changes detected."));
+    console.log(chalk3.green("No changes detected."));
     return;
   }
   const breaking = diff.changes.filter((c) => c.risk === "breaking");
   const caution = diff.changes.filter((c) => c.risk === "caution");
   const safe = diff.changes.filter((c) => c.risk === "safe");
   if (breaking.length > 0) {
-    console.log(chalk2.red(chalk2.bold("BREAKING CHANGES:")));
+    console.log(chalk3.red(chalk3.bold("BREAKING CHANGES:")));
     for (const change of breaking) {
-      console.log(chalk2.red(`  - ${change.type.toUpperCase()}: ${change.description}`));
+      console.log(chalk3.red(`  - ${change.type.toUpperCase()}: ${change.description}`));
     }
     console.log();
   }
   if (caution.length > 0) {
-    console.log(chalk2.yellow(chalk2.bold("CAUTION:")));
+    console.log(chalk3.yellow(chalk3.bold("CAUTION:")));
     for (const change of caution) {
-      console.log(chalk2.yellow(`  - ${change.type.toUpperCase()}: ${change.description}`));
+      console.log(chalk3.yellow(`  - ${change.type.toUpperCase()}: ${change.description}`));
     }
     console.log();
   }
   if (safe.length > 0) {
-    console.log(chalk2.green(chalk2.bold("SAFE:")));
+    console.log(chalk3.green(chalk3.bold("SAFE:")));
     for (const change of safe) {
-      console.log(chalk2.green(`  - ${change.type.toUpperCase()}: ${change.description}`));
+      console.log(chalk3.green(`  - ${change.type.toUpperCase()}: ${change.description}`));
     }
     console.log();
   }
-  console.log(chalk2.bold("Summary:"));
+  console.log(chalk3.bold("Summary:"));
   console.log(
-    `  ${chalk2.red(`${diff.summary.breaking} breaking`)} | ${chalk2.yellow(`${diff.summary.caution} caution`)} | ${chalk2.green(`${diff.summary.safe} safe`)}`
+    `  ${chalk3.red(`${diff.summary.breaking} breaking`)} | ${chalk3.yellow(`${diff.summary.caution} caution`)} | ${chalk3.green(`${diff.summary.safe} safe`)}`
   );
   console.log();
   if (diff.changes.some((c) => c.suggestedLens)) {
-    console.log(chalk2.bold("Suggested lens:"));
-    console.log(chalk2.dim("\u2500".repeat(40)));
+    console.log(chalk3.bold("Suggested lens:"));
+    console.log(chalk3.dim("\u2500".repeat(40)));
     console.log(generateLensSnippet(diff));
-    console.log(chalk2.dim("\u2500".repeat(40)));
+    console.log(chalk3.dim("\u2500".repeat(40)));
     console.log();
   }
   if (diff.autoMigratable) {
-    console.log(chalk2.green("\u2713 Automatic migration possible"));
+    console.log(chalk3.green("\u2713 Automatic migration possible"));
   } else {
-    console.log(chalk2.yellow("\u26A0 Manual intervention required for some changes"));
+    console.log(chalk3.yellow("\u26A0 Manual intervention required for some changes"));
   }
 }
 async function generateCommand(options) {
-  const chalk2 = await getChalk2();
+  const chalk3 = await getChalk2();
   try {
     const fromParsed = parseSchemaIRI(options.from);
     const toParsed = parseSchemaIRI(options.to);
@@ -1924,7 +1924,7 @@ async function generateCommand(options) {
     const from = fromSchema ?? createMockSchema(fromParsed.name, fromParsed.version, "from");
     const to = toSchema ?? createMockSchema(toParsed.name, toParsed.version, "to");
     if (!fromSchema || !toSchema) {
-      console.log(chalk2.yellow("\nNote: Using mock schemas for demonstration.\n"));
+      console.log(chalk3.yellow("\nNote: Using mock schemas for demonstration.\n"));
     }
     const diff = diffSchemas(from, to);
     const sourceIRI = from["@id"];
@@ -1939,24 +1939,24 @@ async function generateCommand(options) {
     if (options.output) {
       const outputPath = resolve7(process.cwd(), options.output);
       if (existsSync2(outputPath) && !options.force) {
-        console.error(chalk2.red(`Error: File already exists: ${outputPath}`));
-        console.error(chalk2.gray("Use --force to overwrite."));
+        console.error(chalk3.red(`Error: File already exists: ${outputPath}`));
+        console.error(chalk3.gray("Use --force to overwrite."));
         process.exit(1);
       }
       writeFileSync4(outputPath, generated.code, "utf-8");
-      console.log(chalk2.green(`
+      console.log(chalk3.green(`
 \u2713 Generated lens written to: ${outputPath}`));
     } else {
       console.log(generated.code);
     }
     if (!generated.isComplete) {
-      console.log(chalk2.yellow("\n\u26A0 Manual completion required:"));
+      console.log(chalk3.yellow("\n\u26A0 Manual completion required:"));
       for (const item of generated.manualItems) {
-        console.log(chalk2.yellow(`  - ${item}`));
+        console.log(chalk3.yellow(`  - ${item}`));
       }
     }
   } catch (error) {
-    console.error(chalk2.red(`Error: ${error instanceof Error ? error.message : String(error)}`));
+    console.error(chalk3.red(`Error: ${error instanceof Error ? error.message : String(error)}`));
     process.exit(1);
   }
 }
@@ -1994,43 +1994,43 @@ function createMockSchema(name, version, type) {
   }
 }
 async function runCommand(options) {
-  const chalk2 = await getChalk2();
+  const chalk3 = await getChalk2();
   if (!options.dryRun && !options.apply) {
-    console.error(chalk2.red("Error: Must specify either --dry-run or --apply"));
+    console.error(chalk3.red("Error: Must specify either --dry-run or --apply"));
     process.exit(1);
   }
   if (options.dryRun && options.apply) {
-    console.error(chalk2.red("Error: Cannot specify both --dry-run and --apply"));
+    console.error(chalk3.red("Error: Cannot specify both --dry-run and --apply"));
     process.exit(1);
   }
   try {
-    console.log(chalk2.blue(`
+    console.log(chalk3.blue(`
 Migration: ${options.from} \u2192 ${options.to}
 `));
     if (options.dryRun) {
-      console.log(chalk2.yellow("DRY RUN - No changes will be applied\n"));
-      console.log(chalk2.gray("Would migrate nodes:"));
-      console.log(chalk2.gray("  - Scan data directory for nodes with schema " + options.from));
-      console.log(chalk2.gray("  - Apply migration lens to each node"));
-      console.log(chalk2.gray("  - Update schema version to " + options.to));
+      console.log(chalk3.yellow("DRY RUN - No changes will be applied\n"));
+      console.log(chalk3.gray("Would migrate nodes:"));
+      console.log(chalk3.gray("  - Scan data directory for nodes with schema " + options.from));
+      console.log(chalk3.gray("  - Apply migration lens to each node"));
+      console.log(chalk3.gray("  - Update schema version to " + options.to));
       console.log();
-      console.log(chalk2.dim("Note: Full migration requires --data-dir and --lens-file options"));
-      console.log(chalk2.dim("      or a configured NodeStore with registered lenses."));
+      console.log(chalk3.dim("Note: Full migration requires --data-dir and --lens-file options"));
+      console.log(chalk3.dim("      or a configured NodeStore with registered lenses."));
     } else {
-      console.log(chalk2.yellow("APPLY MODE - Changes will be written\n"));
-      console.log(chalk2.gray("Would apply migration:"));
-      console.log(chalk2.gray("  - Load nodes with schema " + options.from));
-      console.log(chalk2.gray("  - Transform using migration lens"));
-      console.log(chalk2.gray("  - Write updated nodes with schema " + options.to));
+      console.log(chalk3.yellow("APPLY MODE - Changes will be written\n"));
+      console.log(chalk3.gray("Would apply migration:"));
+      console.log(chalk3.gray("  - Load nodes with schema " + options.from));
+      console.log(chalk3.gray("  - Transform using migration lens"));
+      console.log(chalk3.gray("  - Write updated nodes with schema " + options.to));
       console.log();
-      console.log(chalk2.dim("Note: Full migration requires --data-dir and --lens-file options"));
-      console.log(chalk2.dim("      or a configured NodeStore with registered lenses."));
+      console.log(chalk3.dim("Note: Full migration requires --data-dir and --lens-file options"));
+      console.log(chalk3.dim("      or a configured NodeStore with registered lenses."));
     }
     console.log();
-    console.log(chalk2.green("\u2713 Migration command parsed successfully"));
-    console.log(chalk2.gray("  Full implementation requires NodeStore integration."));
+    console.log(chalk3.green("\u2713 Migration command parsed successfully"));
+    console.log(chalk3.gray("  Full implementation requires NodeStore integration."));
   } catch (error) {
-    console.error(chalk2.red(`Error: ${error instanceof Error ? error.message : String(error)}`));
+    console.error(chalk3.red(`Error: ${error instanceof Error ? error.message : String(error)}`));
     process.exit(1);
   }
 }
@@ -2047,6 +2047,78 @@ function registerMigrateCommand(program2) {
   });
 }
 
+// src/commands/publish.ts
+import { mkdir as mkdir4, readFile as readFile4, writeFile as writeFile3 } from "fs/promises";
+import { dirname as dirname4, join as join8, resolve as resolve8 } from "path";
+import { buildStaticSite } from "@xnetjs/publish";
+import chalk2 from "chalk";
+function assertPublication(value) {
+  if (typeof value !== "object" || value === null) {
+    throw new Error("publication file must be a JSON object");
+  }
+  const file = value;
+  if (!file.meta || typeof file.meta.siteUrl !== "string" || typeof file.meta.title !== "string") {
+    throw new Error("publication file needs `meta.siteUrl` and `meta.title`");
+  }
+  if (!Array.isArray(file.posts)) throw new Error("publication file needs a `posts` array");
+  for (const [i, post] of file.posts.entries()) {
+    if (typeof post?.slug !== "string" || post.slug === "") {
+      throw new Error(`posts[${i}] needs a non-empty \`slug\``);
+    }
+    if (typeof post.title !== "string") throw new Error(`posts[${i}] needs a \`title\``);
+    if (typeof post.html !== "string") {
+      throw new Error(`posts[${i}] needs rendered \`html\` (see renderPost() in @xnetjs/publish)`);
+    }
+  }
+}
+function registerPublishCommand(program2) {
+  const publish = program2.command("publish").description("Render a publication to a static site (HTML, RSS, sitemap)");
+  publish.command("static", { isDefault: true }).description("Write a self-contained static site to a directory").requiredOption("--input <path>", "Publication JSON (meta + posts with rendered html)").option("--out <dir>", "Output directory", "dist/publish").option("--dry-run", "List the files that would be written without writing them").action(async (opts) => {
+    const inputPath = resolve8(opts.input);
+    const outDir = resolve8(opts.out);
+    let parsed;
+    try {
+      parsed = JSON.parse(await readFile4(inputPath, "utf8"));
+    } catch (error) {
+      console.error(chalk2.red(`Could not read ${inputPath}: ${error.message}`));
+      process.exitCode = 1;
+      return;
+    }
+    let file;
+    try {
+      assertPublication(parsed);
+      file = parsed;
+    } catch (error) {
+      console.error(chalk2.red(error.message));
+      process.exitCode = 1;
+      return;
+    }
+    const site = buildStaticSite({
+      meta: file.meta,
+      posts: file.posts,
+      css: file.css,
+      head: file.head
+    });
+    const published = file.posts.filter((p) => Boolean(p.publishedAt)).length;
+    const drafts = file.posts.length - published;
+    if (opts.dryRun) {
+      for (const path of [...site.keys()].sort()) console.log(join8(outDir, path));
+      console.log(chalk2.dim(`${site.size} file(s), not written (--dry-run)`));
+      return;
+    }
+    for (const [path, contents] of site) {
+      const target = join8(outDir, path);
+      await mkdir4(dirname4(target), { recursive: true });
+      await writeFile3(target, contents, "utf8");
+    }
+    console.log(chalk2.green(`Published ${published} post(s) to ${outDir}`));
+    if (drafts > 0) {
+      console.log(chalk2.dim(`${drafts} draft(s) skipped (no publishedAt)`));
+    }
+    console.log(chalk2.dim("Serve this directory from any static host \u2014 no hub required."));
+  });
+}
+
 // src/commands/schema.ts
 import { writeFileSync as writeFileSync5, readFileSync as readFileSync3, existsSync as existsSync3 } from "fs";
 function extractSchemas() {
@@ -2210,4 +2282,5 @@ registerCodeCommand(program);
 registerDataCommand(program);
 registerPluginCommand(program);
 registerConnectorCommand(program);
+registerPublishCommand(program);
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xnetjs/cli",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "xNet CLI - Schema migrations, diagnostics, and development tools",
   "license": "MIT",
   "repository": {
@@ -15,8 +15,8 @@
   },
   "exports": {
     ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
     }
   },
   "files": [
@@ -31,18 +31,20 @@
   "dependencies": {
     "chalk": "^5.3.0",
     "commander": "^12.0.0",
-    "@xnetjs/core": "2.5.0",
-    "@xnetjs/crypto": "2.5.0",
-    "@xnetjs/data": "2.5.0",
-    "@xnetjs/devkit": "1.0.0",
-    "@xnetjs/identity": "2.5.0",
-    "@xnetjs/plugins": "2.5.0",
-    "@xnetjs/runtime": "0.5.5",
-    "@xnetjs/sqlite": "2.5.0",
-    "@xnetjs/sync": "2.5.0"
+    "@xnetjs/core": "3.0.0",
+    "@xnetjs/crypto": "3.0.0",
+    "@xnetjs/data": "3.0.0",
+    "@xnetjs/devkit": "1.0.1",
+    "@xnetjs/identity": "3.0.0",
+    "@xnetjs/plugins": "3.0.0",
+    "@xnetjs/publish": "0.1.0",
+    "@xnetjs/runtime": "0.6.0",
+    "@xnetjs/sqlite": "3.0.0",
+    "@xnetjs/sync": "3.0.0"
   },
   "devDependencies": {
     "tsup": "^8.0.0",
+    "yjs": "^13.6.0",
     "tsx": "^4.0.0",
     "typescript": "^5.4.0",
     "vitest": "^4.0.0"