@hyphaene/hexa-ts-kit 1.9.0 → 1.10.0

package/dist/{chunk-OI2LN5K5.js → chunk-IBVI6IS2.js}

@@ -852,6 +852,10 @@ var ContractsScaffoldConfigSchema = z.object({
 var ProjectConfigSchema = z.object({
   type: z.enum(["contracts-lib", "nestjs-bff", "vue-frontend"])
 });
+var VaultConfigSchema = z.object({
+  schemaPath: z.string()
+  // Path to vault.schema.json relative to repo root
+});
 var HexaTsKitConfigSchema = z.object({
   project: ProjectConfigSchema,
   lint: z.object({
@@ -860,7 +864,8 @@ var HexaTsKitConfigSchema = z.object({
   }).optional(),
   scaffold: z.object({
     contracts: ContractsScaffoldConfigSchema.optional()
-  }).optional()
+  }).optional(),
+  vault: VaultConfigSchema.optional()
 });
 var CONFIG_FILE_NAME = ".hexa-ts-kit.yaml";
 function loadConfig(repoPath) {
@@ -924,6 +929,9 @@ function getDisabledRules(config) {
 function getDisabledVaultRules(config) {
   return config.lint?.vault?.disabledRules ?? [];
 }
+function getVaultConfig(config) {
+  return config.vault ?? null;
+}
 
 // src/lib/contracts/permissions-extractor.ts
 import { readFileSync as readFileSync2, existsSync as existsSync3 } from "fs";
@@ -3316,6 +3324,8 @@ async function scaffoldCommand(type, path, options) {
 }
 
 export {
+  loadConfig,
+  getVaultConfig,
   lintCore,
   lintCommand,
   analyzeCore,

package/dist/cli.js

@@ -1,9 +1,11 @@
 #!/usr/bin/env node
 import {
   analyzeCommand,
+  getVaultConfig,
   lintCommand,
+  loadConfig,
   scaffoldCommand
-} from "./chunk-OI2LN5K5.js";
+} from "./chunk-IBVI6IS2.js";
 
 // src/cli.ts
 import { program } from "commander";
@@ -257,6 +259,533 @@ function padEnd(str, length) {
   return str.length >= length ? str.slice(0, length - 1) + " " : str + " ".repeat(length - str.length);
 }
 
+// src/vault/extractors/json-schema.ts
+import { execSync } from "child_process";
+import { existsSync, readFileSync as readFileSync2 } from "fs";
+import { join } from "path";
+function extractFromJsonSchema(source, version, options) {
+  const { schemaPath, cwd = process.cwd() } = options;
+  let jsonContent;
+  const isGitRef = options.isGitRef ?? isLikelyGitRef(source);
+  if (isGitRef) {
+    jsonContent = readFromGit(source, schemaPath, cwd);
+  } else {
+    jsonContent = readFromFilesystem(source, schemaPath);
+  }
+  const jsonSchema = JSON.parse(jsonContent);
+  const root = convertJsonSchemaToSchemaNode(
+    jsonSchema,
+    jsonSchema.definitions
+  );
+  return {
+    root,
+    sourceFile: schemaPath,
+    version
+  };
+}
+function isLikelyGitRef(source) {
+  if (source === "HEAD" || source.startsWith("HEAD")) return true;
+  if (source === "main" || source === "master" || source === "develop")
+    return true;
+  if (source.startsWith("origin/")) return true;
+  if (source.startsWith("refs/")) return true;
+  if (source.match(/^[a-f0-9]{7,40}$/)) return true;
+  if (source.match(/^v?\d+\.\d+/)) return true;
+  if (source.startsWith(".") || source.startsWith("/") || source.startsWith("~"))
+    return false;
+  if (source.includes("/") && !source.startsWith("origin/")) return false;
+  return false;
+}
+function readFromGit(gitRef, schemaPath, cwd) {
+  let fullRef;
+  if (gitRef.includes(":") && gitRef.endsWith(".json")) {
+    fullRef = gitRef;
+  } else if (gitRef.includes(":")) {
+    fullRef = gitRef;
+  } else {
+    fullRef = `${gitRef}:${schemaPath}`;
+  }
+  try {
+    const content = execSync(`git show "${fullRef}"`, {
+      cwd,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    return content;
+  } catch (error) {
+    const errorMsg = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `Cannot read schema from git ref "${fullRef}": ${errorMsg}`
+    );
+  }
+}
+function readFromFilesystem(repoPath, schemaPath) {
+  const fullPath = join(repoPath, schemaPath);
+  if (!existsSync(fullPath)) {
+    throw new Error(
+      `Schema file not found: ${fullPath}
+Run 'npm run vault:build' to generate it.`
+    );
+  }
+  return readFileSync2(fullPath, "utf-8");
+}
+function convertJsonSchemaToSchemaNode(schema, definitions) {
+  const localDefs = { ...definitions, ...schema.definitions };
+  if (schema.$ref) {
+    const refPath = schema.$ref.replace("#/definitions/", "");
+    const refSchema = localDefs?.[refPath];
+    if (refSchema) {
+      return convertJsonSchemaToSchemaNode(refSchema, localDefs);
+    }
+    return { type: "unknown" };
+  }
+  const type = Array.isArray(schema.type) ? schema.type[0] : schema.type;
+  switch (type) {
+    case "string":
+      if (schema.enum) {
+        return {
+          type: "enum",
+          enumValues: schema.enum.map(String)
+        };
+      }
+      return { type: "string" };
+    case "number":
+    case "integer":
+      return { type: "number" };
+    case "boolean":
+      return { type: "boolean" };
+    case "array":
+      if (schema.items) {
+        return {
+          type: "array",
+          arrayItemType: convertJsonSchemaToSchemaNode(schema.items, localDefs)
+        };
+      }
+      return { type: "array" };
+    case "object": {
+      const children = {};
+      const requiredSet = new Set(schema.required ?? []);
+      if (schema.properties) {
+        for (const [key, propSchema] of Object.entries(schema.properties)) {
+          if (key.startsWith("$") || key === "definitions") continue;
+          const propDefs = { ...localDefs, ...propSchema.definitions };
+          const propNode = convertJsonSchemaToSchemaNode(propSchema, propDefs);
+          children[key] = requiredSet.has(key) ? propNode : { ...propNode, optional: true };
+        }
+      }
+      return { type: "object", children };
+    }
+    default: {
+      if (schema.properties) {
+        const children = {};
+        const requiredSet = new Set(schema.required ?? []);
+        for (const [key, propSchema] of Object.entries(schema.properties)) {
+          if (key.startsWith("$") || key === "definitions") continue;
+          const propDefs = { ...localDefs, ...propSchema.definitions };
+          const propNode = convertJsonSchemaToSchemaNode(propSchema, propDefs);
+          children[key] = requiredSet.has(key) ? propNode : { ...propNode, optional: true };
+        }
+        return { type: "object", children };
+      }
+      return { type: "unknown" };
+    }
+  }
+}
+function gitRefExists(ref, cwd) {
+  try {
+    execSync(`git rev-parse --verify "${ref}"`, {
+      cwd,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function getCurrentBranch(cwd) {
+  try {
+    return execSync("git rev-parse --abbrev-ref HEAD", {
+      cwd,
+      encoding: "utf-8"
+    }).trim();
+  } catch {
+    return "HEAD";
+  }
+}
+function fileExistsAtRef(ref, filePath, cwd) {
+  try {
+    execSync(`git show "${ref}:${filePath}"`, {
+      cwd,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/vault/diff.ts
+function diffSchemas(source, target, sourceVersion, targetVersion) {
+  const changes = [];
+  compareNodes(source, target, "", changes);
+  const hasBreakingChanges = changes.some(
+    (c) => c.type === "removed" || c.type === "changed"
+  );
+  return {
+    sourceVersion,
+    targetVersion,
+    changes,
+    hasBreakingChanges
+  };
+}
+function compareNodes(source, target, path, changes) {
+  if (!source && target) {
+    changes.push({
+      path: path || "(root)",
+      type: "added",
+      newValue: target
+    });
+    return;
+  }
+  if (source && !target) {
+    changes.push({
+      path: path || "(root)",
+      type: "removed",
+      oldValue: source
+    });
+    return;
+  }
+  if (!source || !target) {
+    return;
+  }
+  if (source.type !== target.type) {
+    changes.push({
+      path: path || "(root)",
+      type: "changed",
+      oldValue: source,
+      newValue: target
+    });
+    return;
+  }
+  if (source.type === "enum" && target.type === "enum") {
+    const sourceValues = new Set(source.enumValues ?? []);
+    const targetValues = new Set(target.enumValues ?? []);
+    for (const val of targetValues) {
+      if (!sourceValues.has(val)) {
+        changes.push({
+          path: `${path}[enum:${val}]`,
+          type: "added",
+          newValue: { type: "enum", enumValues: [val] }
+        });
+      }
+    }
+    for (const val of sourceValues) {
+      if (!targetValues.has(val)) {
+        changes.push({
+          path: `${path}[enum:${val}]`,
+          type: "removed",
+          oldValue: { type: "enum", enumValues: [val] }
+        });
+      }
+    }
+    return;
+  }
+  if (source.optional !== target.optional) {
+    changes.push({
+      path,
+      type: "changed",
+      oldValue: source,
+      newValue: target
+    });
+  }
+  if (source.type === "array" && target.type === "array") {
+    compareNodes(
+      source.arrayItemType,
+      target.arrayItemType,
+      `${path}[]`,
+      changes
+    );
+    return;
+  }
+  if (source.type === "object" && target.type === "object") {
+    const sourceKeys = new Set(Object.keys(source.children ?? {}));
+    const targetKeys = new Set(Object.keys(target.children ?? {}));
+    for (const key of targetKeys) {
+      const childPath = path ? `${path}.${key}` : key;
+      if (!sourceKeys.has(key)) {
+        changes.push({
+          path: childPath,
+          type: "added",
+          newValue: target.children[key]
+        });
+      } else {
+        compareNodes(
+          source.children[key],
+          target.children[key],
+          childPath,
+          changes
+        );
+      }
+    }
+    for (const key of sourceKeys) {
+      if (!targetKeys.has(key)) {
+        const childPath = path ? `${path}.${key}` : key;
+        changes.push({
+          path: childPath,
+          type: "removed",
+          oldValue: source.children[key]
+        });
+      }
+    }
+  }
+}
+function formatType(node) {
+  switch (node.type) {
+    case "string":
+      return "string";
+    case "number":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "array":
+      if (node.arrayItemType) {
+        return `${formatType(node.arrayItemType)}[]`;
+      }
+      return "array";
+    case "enum":
+      if (node.enumValues) {
+        return `enum(${node.enumValues.join(" | ")})`;
+      }
+      return "enum";
+    case "object":
+      if (node.children) {
+        const keys = Object.keys(node.children).filter((k) => k !== "__ref");
+        if (keys.length <= 3) {
+          return `{ ${keys.join(", ")} }`;
+        }
+        return `{ ${keys.slice(0, 3).join(", ")}, ... }`;
+      }
+      return "object";
+    default:
+      return "unknown";
+  }
+}
+
+// src/commands/vault-diff.ts
+function getSchemaPath(cwd) {
+  const configResult = loadConfig(cwd);
+  if (!configResult.success) {
+    throw new Error(
+      `Cannot load .hexa-ts-kit.yaml: ${configResult.error}
+Add vault.schemaPath to your config file.`
+    );
+  }
+  const vaultConfig = getVaultConfig(configResult.config);
+  if (!vaultConfig) {
+    throw new Error(
+      `Missing vault config in .hexa-ts-kit.yaml
+Add:
+  vault:
+    schemaPath: path/to/vault.schema.json`
+    );
+  }
+  return vaultConfig.schemaPath;
+}
+async function vaultDiffCommand(sourceRef, targetRef, options) {
+  const format = options.format ?? "console";
+  const cwd = options.cwd ?? process.cwd();
+  let schemaPath;
+  try {
+    schemaPath = getSchemaPath(cwd);
+  } catch (error) {
+    console.error(
+      `Error: ${error instanceof Error ? error.message : String(error)}`
+    );
+    process.exit(1);
+  }
+  if (!gitRefExists(sourceRef, cwd)) {
+    console.error(`Error: Git ref "${sourceRef}" does not exist`);
+    process.exit(1);
+  }
+  if (!gitRefExists(targetRef, cwd)) {
+    console.error(`Error: Git ref "${targetRef}" does not exist`);
+    process.exit(1);
+  }
+  if (!fileExistsAtRef(sourceRef, schemaPath, cwd)) {
+    console.error(
+      `Error: vault.schema.json not found at "${sourceRef}:${schemaPath}"
+The schema file may not exist in this version. Run 'npm run vault:build' on that branch first.`
+    );
+    process.exit(1);
+  }
+  if (!fileExistsAtRef(targetRef, schemaPath, cwd)) {
+    console.error(
+      `Error: vault.schema.json not found at "${targetRef}:${schemaPath}"
+The schema file may not exist in this version. Run 'npm run vault:build' on that branch first.`
+    );
+    process.exit(1);
+  }
+  try {
+    const extractOpts = { schemaPath, isGitRef: true, cwd };
+    const sourceSchema = extractFromJsonSchema(
+      sourceRef,
+      sourceRef,
+      extractOpts
+    );
+    const targetSchema = extractFromJsonSchema(
+      targetRef,
+      targetRef,
+      extractOpts
+    );
+    const result = diffSchemas(
+      sourceSchema.root,
+      targetSchema.root,
+      sourceSchema.version,
+      targetSchema.version
+    );
+    if (format === "json") {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      printConsoleOutput(result);
+    }
+    if (result.hasBreakingChanges) {
+      process.exit(1);
+    }
+  } catch (error) {
+    console.error(
+      `Error: ${error instanceof Error ? error.message : String(error)}`
+    );
+    process.exit(1);
+  }
+}
+async function vaultExtractCommand(source, options) {
+  const format = options.format ?? "json";
+  const cwd = options.cwd ?? process.cwd();
+  let schemaPath;
+  try {
+    schemaPath = getSchemaPath(cwd);
+  } catch (error) {
+    console.error(
+      `Error: ${error instanceof Error ? error.message : String(error)}`
+    );
+    process.exit(1);
+  }
+  try {
+    let schema;
+    if (source === ".") {
+      schema = extractFromJsonSchema(cwd, "local", {
+        schemaPath,
+        isGitRef: false
+      });
+    } else if (gitRefExists(source, cwd)) {
+      if (!fileExistsAtRef(source, schemaPath, cwd)) {
+        console.error(
+          `Error: vault.schema.json not found at "${source}:${schemaPath}"`
+        );
+        process.exit(1);
+      }
+      schema = extractFromJsonSchema(source, source, {
+        schemaPath,
+        isGitRef: true,
+        cwd
+      });
+    } else {
+      schema = extractFromJsonSchema(source, "path", {
+        schemaPath,
+        isGitRef: false
+      });
+    }
+    if (format === "json") {
+      console.log(JSON.stringify(schema, null, 2));
+    } else {
+      console.log(`Schema from ${schema.sourceFile} (${schema.version}):
+`);
+      printSchemaTree(schema.root, 0);
+    }
+  } catch (error) {
+    console.error(
+      `Error: ${error instanceof Error ? error.message : String(error)}`
+    );
+    process.exit(1);
+  }
+}
+function printConsoleOutput(result) {
+  console.log(`
+Vault Schema Diff`);
+  console.log(`Source: ${result.sourceVersion}`);
+  console.log(`Target: ${result.targetVersion}`);
+  console.log("\u2500".repeat(50));
+  if (result.changes.length === 0) {
+    console.log("\n\u2713 No changes detected");
+    return;
+  }
+  const added = result.changes.filter((c) => c.type === "added");
+  const removed = result.changes.filter((c) => c.type === "removed");
+  const changed = result.changes.filter((c) => c.type === "changed");
+  if (added.length > 0) {
+    console.log("\n+ Added:");
+    for (const change of added) {
+      const type = change.newValue ? formatType(change.newValue) : "unknown";
+      console.log(`  ${change.path}: ${type}`);
+    }
+  }
+  if (removed.length > 0) {
+    console.log("\n- Removed:");
+    for (const change of removed) {
+      const type = change.oldValue ? formatType(change.oldValue) : "unknown";
+      console.log(`  ${change.path}: ${type}`);
+    }
+  }
+  if (changed.length > 0) {
+    console.log("\n~ Changed:");
+    for (const change of changed) {
+      const oldType = change.oldValue ? formatType(change.oldValue) : "unknown";
+      const newType = change.newValue ? formatType(change.newValue) : "unknown";
+      console.log(`  ${change.path}: ${oldType} \u2192 ${newType}`);
+    }
+  }
+  console.log("\n" + "\u2500".repeat(50));
+  console.log(
+    `Summary: +${added.length} -${removed.length} ~${changed.length}`
+  );
+  if (result.hasBreakingChanges) {
+    console.log("\n\u26A0 Breaking changes detected (removals or type changes)");
+  }
+}
+function printSchemaTree(node, indent) {
+  const prefix = "  ".repeat(indent);
+  if (node.type === "object" && node.children) {
+    for (const [key, child] of Object.entries(node.children)) {
+      if (key === "__ref") continue;
+      const opt = child.optional ? "?" : "";
+      console.log(`${prefix}${key}${opt}: ${formatType(child)}`);
+      if (child.type === "object" && child.children) {
+        printSchemaTree(child, indent + 1);
+      }
+    }
+  } else {
+    console.log(`${prefix}${formatType(node)}`);
+  }
+}
+async function vaultQuickDiffCommand(options) {
+  const cwd = options.cwd ?? process.cwd();
+  const currentBranch = getCurrentBranch(cwd);
+  const baseBranch = gitRefExists("main", cwd) ? "main" : gitRefExists("master", cwd) ? "master" : null;
+  if (!baseBranch) {
+    console.error("Error: Cannot find main or master branch");
+    process.exit(1);
+  }
+  if (currentBranch === baseBranch) {
+    console.log(`Already on ${baseBranch}, nothing to diff`);
+    return;
+  }
+  console.log(`Comparing ${baseBranch} \u2192 ${currentBranch}
+`);
+  await vaultDiffCommand(baseBranch, currentBranch, options);
+}
+
 // src/cli.ts
 var require2 = createRequire(import.meta.url);
 var { version: VERSION } = require2("../package.json");
@@ -286,4 +815,9 @@ program.command("scaffold <type> <path>").description("Generate a colocated feat
 program.command("analyze-bff <bff-path>").description(
   "Analyze BFF to extract endpoint \u2192 permission \u2192 apiService mappings"
 ).option("-o, --output <file>", "Output JSON file path").option("--format <type>", "Output format: json, table", "json").action(analyzeBffCommand);
+program.command("vault:diff <source-ref> <target-ref>").description(
+  "Compare Vault schemas between two git refs (branches, tags, commits)"
+).option("-f, --format <type>", "Output format: console, json", "console").option("--cwd <path>", "Working directory (git repo)").action(vaultDiffCommand);
+program.command("vault:quick-diff").alias("vault:qd").description("Compare current branch vault schema against main/master").option("-f, --format <type>", "Output format: console, json", "console").option("--cwd <path>", "Working directory (git repo)").action(vaultQuickDiffCommand);
+program.command("vault:extract <source>").description("Extract and display Vault schema from git ref or path").option("-f, --format <type>", "Output format: json, tree", "json").option("--cwd <path>", "Working directory (git repo)").action(vaultExtractCommand);
 program.parse();

package/dist/mcp-server.js

@@ -3,7 +3,7 @@ import {
   analyzeCore,
   lintCore,
   scaffoldCore
-} from "./chunk-OI2LN5K5.js";
+} from "./chunk-IBVI6IS2.js";
 
 // src/mcp-server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyphaene/hexa-ts-kit",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "TypeScript dev kit for Claude Code agents: architecture linting, scaffolding, knowledge analysis",
   "type": "module",
   "bin": {