@xnetjs/cli 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Smothers
+
+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,49 @@
+# @xnetjs/cli
+
+CLI tools for schema migration workflows, schema diffing, and data integrity diagnostics.
+
+## Installation
+
+```bash
+pnpm add -D @xnetjs/cli
+```
+
+## Usage
+
+```bash
+# Show commands
+pnpm --filter @xnetjs/cli dev -- --help
+
+# Analyze schema changes
+pnpm --filter @xnetjs/cli dev -- migrate analyze --from Task@1.0.0 --to Task@2.0.0 --schema-file ./schemas.json
+
+# Generate migration lens code
+pnpm --filter @xnetjs/cli dev -- migrate generate --from Task@1.0.0 --to Task@2.0.0 -o ./migrations/task-v1-v2.ts
+
+# Extract and diff schemas (CI-friendly)
+pnpm --filter @xnetjs/cli dev -- schema extract --output schemas.json
+pnpm --filter @xnetjs/cli dev -- schema diff schemas-main.json schemas-pr.json --fail-on-breaking
+
+# Run integrity checks
+pnpm --filter @xnetjs/cli dev -- doctor --quick
+```
+
+## Commands
+
+- `migrate` -- Analyze schema deltas, generate lens code, and run migration flows
+- `schema` -- Extract schemas and diff schema snapshots for CI gates
+- `doctor` -- Run integrity checks, repair helpers, and import/export diagnostics
+
+## Programmatic API
+
+You can also use utilities directly:
+
+```ts
+import { diffSchemas, generateLensCode } from '@xnetjs/cli'
+```
+
+## Testing
+
+```bash
+pnpm --filter @xnetjs/cli test
+```

package/dist/chunk-IUOECMVU.js

@@ -0,0 +1,314 @@
+// src/utils/lens-generator.ts
+function indent(code, level) {
+  const spaces = "  ".repeat(level);
+  return code.split("\n").map((line) => line.trim() ? spaces + line : line).join("\n");
+}
+function generateOperationCode(change) {
+  if (!change.suggestedLens) return null;
+  if (change.suggestedLens.startsWith("// TODO")) return null;
+  return change.suggestedLens;
+}
+function generateComment(change) {
+  const riskBadge = change.risk === "breaking" ? "// BREAKING: " : change.risk === "caution" ? "// CAUTION: " : "// ";
+  return `${riskBadge}${change.description}`;
+}
+function generateLensCode(options) {
+  const { diff, sourceIRI, targetIRI, includeComments = true, includeTodos = true } = options;
+  const operations = [];
+  const manualItems = [];
+  let isComplete = true;
+  for (const change of diff.changes) {
+    if (change.risk === "safe" && !change.suggestedLens) {
+      continue;
+    }
+    const operationCode = generateOperationCode(change);
+    if (operationCode) {
+      if (includeComments) {
+        operations.push(generateComment(change));
+      }
+      operations.push(operationCode + ",");
+    } else if (change.risk !== "safe") {
+      isComplete = false;
+      manualItems.push(change.description);
+      if (includeTodos) {
+        operations.push(`// TODO: ${change.description}`);
+        if (change.suggestedLens) {
+          operations.push(change.suggestedLens);
+        }
+        operations.push(`// transform('${change.property}', (v) => /* ... */, (v) => /* ... */),`);
+      }
+    }
+  }
+  const code = `/**
+ * Migration lens: ${sourceIRI} -> ${targetIRI}
+ *
+ * Generated by: xnet migrate generate
+ * Risk level: ${diff.overallRisk.toUpperCase()}
+ * Changes: ${diff.summary.safe} safe, ${diff.summary.caution} caution, ${diff.summary.breaking} breaking
+ *${!isComplete ? "\n * NOTE: This lens requires manual completion. See TODO comments below." : ""}
+ */
+
+import { composeLens, rename, convert, addDefault, remove, transform } from '@xnetjs/data'
+import type { SchemaIRI } from '@xnetjs/data'
+
+const SOURCE: SchemaIRI = '${sourceIRI}' as SchemaIRI
+const TARGET: SchemaIRI = '${targetIRI}' as SchemaIRI
+
+/**
+ * Migrate from ${sourceIRI.split("@")[0].split("/").pop()}@${diff.fromVersion} to @${diff.toVersion}
+ */
+export const lens = composeLens(
+  SOURCE,
+  TARGET,
+${indent(operations.join("\n"), 1)}
+)
+
+export default lens
+`;
+  return {
+    code,
+    isComplete,
+    manualItems
+  };
+}
+function generateLensSnippet(diff) {
+  const operations = [];
+  for (const change of diff.changes) {
+    const operationCode = generateOperationCode(change);
+    if (operationCode) {
+      operations.push(operationCode);
+    }
+  }
+  if (operations.length === 0) {
+    return "// No migration operations needed";
+  }
+  return `composeLens(
+${indent(operations.join(",\n"), 1)}
+)`;
+}
+
+// src/utils/schema-diff.ts
+function getPropertyMap(schema) {
+  const map = /* @__PURE__ */ new Map();
+  for (const prop of schema.properties) {
+    map.set(prop.name, prop);
+  }
+  return map;
+}
+function getDefaultValue(def) {
+  switch (def.type) {
+    case "text":
+      return "''";
+    case "number":
+      return "0";
+    case "checkbox":
+      return "false";
+    case "date":
+      return "null";
+    case "select":
+      return def.options?.[0] ? `'${def.options[0].value}'` : "null";
+    case "multiSelect":
+      return "[]";
+    case "person":
+      return "[]";
+    case "relation":
+      return "[]";
+    case "url":
+      return "null";
+    case "email":
+      return "null";
+    case "phone":
+      return "null";
+    case "file":
+      return "[]";
+    default:
+      return "null";
+  }
+}
+function areTypesCompatible(oldType, newType) {
+  if (oldType === newType) return true;
+  const wideningPairs = [
+    ["text", "url"],
+    ["text", "email"],
+    ["text", "phone"]
+  ];
+  return wideningPairs.some(([from, to]) => oldType === to && newType === from);
+}
+function detectPotentialRename(removedProps, addedProps) {
+  const renames = [];
+  for (const [removedName, removedDef] of removedProps) {
+    for (const [addedName, addedDef] of addedProps) {
+      if (removedDef.type === addedDef.type) {
+        let confidence = 0.5;
+        const removedLower = removedName.toLowerCase();
+        const addedLower = addedName.toLowerCase();
+        if (removedLower.includes(addedLower) || addedLower.includes(removedLower)) {
+          confidence += 0.2;
+        }
+        if (removedDef.required === addedDef.required) {
+          confidence += 0.1;
+        }
+        if (removedDef.type === "select" && addedDef.type === "select") {
+          const oldOptions = new Set(removedDef.options?.map((o) => o.value) ?? []);
+          const newOptions = new Set(addedDef.options?.map((o) => o.value) ?? []);
+          const intersection = new Set([...oldOptions].filter((x) => newOptions.has(x)));
+          if (intersection.size === oldOptions.size && oldOptions.size === newOptions.size) {
+            confidence += 0.2;
+          }
+        }
+        if (confidence >= 0.5) {
+          renames.push({ from: removedName, to: addedName, confidence });
+        }
+      }
+    }
+  }
+  renames.sort((a, b) => b.confidence - a.confidence);
+  const usedFrom = /* @__PURE__ */ new Set();
+  const usedTo = /* @__PURE__ */ new Set();
+  return renames.filter((r) => {
+    if (usedFrom.has(r.from) || usedTo.has(r.to)) return false;
+    usedFrom.add(r.from);
+    usedTo.add(r.to);
+    return true;
+  });
+}
+function diffSchemas(oldSchema, newSchema) {
+  const changes = [];
+  const oldProps = getPropertyMap(oldSchema);
+  const newProps = getPropertyMap(newSchema);
+  const removedProps = /* @__PURE__ */ new Map();
+  const addedProps = /* @__PURE__ */ new Map();
+  for (const [name, def] of oldProps) {
+    if (!newProps.has(name)) {
+      removedProps.set(name, def);
+    }
+  }
+  for (const [name, def] of newProps) {
+    if (!oldProps.has(name)) {
+      addedProps.set(name, def);
+    }
+  }
+  const potentialRenames = detectPotentialRename(removedProps, addedProps);
+  for (const { from, to } of potentialRenames) {
+    const oldDef = removedProps.get(from);
+    const newDef = addedProps.get(to);
+    changes.push({
+      type: "rename",
+      property: from,
+      newProperty: to,
+      risk: "breaking",
+      description: `Renamed property "${from}" to "${to}"`,
+      suggestedLens: `rename('${from}', '${to}')`,
+      oldDefinition: oldDef,
+      newDefinition: newDef
+    });
+    removedProps.delete(from);
+    addedProps.delete(to);
+  }
+  for (const [name, def] of removedProps) {
+    changes.push({
+      type: "remove",
+      property: name,
+      risk: "caution",
+      description: `Removed property "${name}" (${def.type})`,
+      suggestedLens: `remove('${name}')`,
+      oldDefinition: def
+    });
+  }
+  for (const [name, def] of addedProps) {
+    const isRequired = def.required === true;
+    changes.push({
+      type: "add",
+      property: name,
+      risk: isRequired ? "caution" : "safe",
+      description: isRequired ? `Added required property "${name}" (${def.type}) - needs default value` : `Added optional property "${name}" (${def.type})`,
+      suggestedLens: isRequired ? `addDefault('${name}', ${getDefaultValue(def)})` : void 0,
+      newDefinition: def
+    });
+  }
+  for (const [name, oldDef] of oldProps) {
+    const newDef = newProps.get(name);
+    if (!newDef) continue;
+    if (oldDef.type !== newDef.type) {
+      const compatible = areTypesCompatible(oldDef.type, newDef.type);
+      changes.push({
+        type: "modify",
+        property: name,
+        risk: compatible ? "caution" : "breaking",
+        description: `Changed type of "${name}" from ${oldDef.type} to ${newDef.type}`,
+        suggestedLens: compatible ? void 0 : `// TODO: Custom transform for ${oldDef.type} -> ${newDef.type}`,
+        oldDefinition: oldDef,
+        newDefinition: newDef
+      });
+      continue;
+    }
+    if (oldDef.type === "select" && newDef.type === "select") {
+      const oldOptions = new Set(oldDef.options?.map((o) => o.value) ?? []);
+      const newOptions = new Set(newDef.options?.map((o) => o.value) ?? []);
+      const removedOptions = [...oldOptions].filter((o) => !newOptions.has(o));
+      if (removedOptions.length > 0) {
+        changes.push({
+          type: "modify",
+          property: name,
+          risk: "breaking",
+          description: `Removed select options from "${name}": ${removedOptions.join(", ")}`,
+          suggestedLens: `// TODO: Map removed options ${removedOptions.join(", ")} to valid values`,
+          oldDefinition: oldDef,
+          newDefinition: newDef
+        });
+      }
+      const addedOptions = [...newOptions].filter((o) => !oldOptions.has(o));
+      if (addedOptions.length > 0 && removedOptions.length === 0) {
+        changes.push({
+          type: "modify",
+          property: name,
+          risk: "safe",
+          description: `Added select options to "${name}": ${addedOptions.join(", ")}`,
+          oldDefinition: oldDef,
+          newDefinition: newDef
+        });
+      }
+    }
+    if (!oldDef.required && newDef.required) {
+      changes.push({
+        type: "modify",
+        property: name,
+        risk: "caution",
+        description: `Made "${name}" required (was optional) - needs default for existing null values`,
+        suggestedLens: `addDefault('${name}', ${getDefaultValue(newDef)})`,
+        oldDefinition: oldDef,
+        newDefinition: newDef
+      });
+    } else if (oldDef.required && !newDef.required) {
+      changes.push({
+        type: "modify",
+        property: name,
+        risk: "safe",
+        description: `Made "${name}" optional (was required)`,
+        oldDefinition: oldDef,
+        newDefinition: newDef
+      });
+    }
+  }
+  const summary = {
+    safe: changes.filter((c) => c.risk === "safe").length,
+    caution: changes.filter((c) => c.risk === "caution").length,
+    breaking: changes.filter((c) => c.risk === "breaking").length
+  };
+  const overallRisk = summary.breaking > 0 ? "breaking" : summary.caution > 0 ? "caution" : "safe";
+  const autoMigratable = changes.filter((c) => c.risk !== "safe").every((c) => c.suggestedLens && !c.suggestedLens.startsWith("// TODO"));
+  return {
+    fromVersion: oldSchema.version,
+    toVersion: newSchema.version,
+    changes,
+    overallRisk,
+    autoMigratable,
+    summary
+  };
+}
+
+export {
+  generateLensCode,
+  generateLensSnippet,
+  diffSchemas
+};

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node