@traits-dev/cli 0.4.0 → 0.6.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Justin Hambleton
+Copyright (c) 2026 FRNTR, LLC
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,6 +1,6 @@
 # @traits-dev/cli
 
-CLI for traits.dev voice profile workflows: init, validate, compile, eval, and import.
+CLI for traits.dev voice profile workflows: init, validate, compile, eval, import, and migrate.
 
 ## Install
 
@@ -13,7 +13,9 @@ pnpm add -D @traits-dev/cli
 ```bash
 traits init --template resolve profiles/resolve.yaml
 traits validate profiles/resolve.yaml
+traits validate profiles/resolve.yaml --format sarif
 traits compile profiles/resolve.yaml --model gpt-4o
+traits migrate profiles/legacy-v1-5.yaml --to v1.6 --normalize-extends
 traits eval profiles/resolve.yaml --tier 1
 ```
 

package/dist/traits.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 // src/bin/traits.ts
-import fs4 from "fs";
-import path6 from "path";
+import fs5 from "fs";
+import path7 from "path";
 import { fileURLToPath } from "url";
 
 // src/commands/compile.ts
@@ -267,7 +267,7 @@ function printEvalUsage(out = process.stderr) {
       "Options:",
       "  --model <model>           Model target (required)",
       "  --tier <1|2|3>            Highest tier to run (default: highest available)",
-      "  --suite <name>            Built-in baseline suite: support|healthcare|developer",
+      "  --suite <name>            Built-in baseline suite: support|healthcare|developer|educator|advisor",
       "  --provider <name>         Judge provider for Tier 3: auto|openai|anthropic",
       "  --embedding-model <name>  Embedding model for Tier 2 (OpenAI)",
       "  --judge-model <name>      Judge model for Tier 3 provider",
@@ -402,10 +402,12 @@ function parseEvalArgs(args) {
   if (!["auto", "openai", "anthropic"].includes(result.provider)) {
     return { error: 'Invalid "--provider" value. Expected auto, openai, or anthropic.' };
   }
-  if (result.suite != null && !["support", "healthcare", "developer"].includes(
+  if (result.suite != null && !["support", "healthcare", "developer", "educator", "advisor"].includes(
     result.suite
   )) {
-    return { error: 'Invalid "--suite" value. Expected support, healthcare, or developer.' };
+    return {
+      error: 'Invalid "--suite" value. Expected support, healthcare, developer, educator, or advisor.'
+    };
   }
   if (result.suite != null && result.samplesPath != null) {
     return { error: 'Use either "--suite" or "--samples/--scenarios", not both.' };
@@ -443,7 +445,7 @@ function loadSamples(options, cwd) {
     const suite = loadBuiltInEvalSuite(options.suite);
     if (!suite) {
       throw new Error(
-        `Unknown suite "${options.suite}". Expected support, healthcare, or developer.`
+        `Unknown suite "${options.suite}". Expected support, healthcare, developer, educator, or advisor.`
       );
     }
     return suite.scenarios.map((scenario) => ({
@@ -1446,21 +1448,314 @@ function importHelp(out = process.stdout) {
   printImportUsage(out);
 }
 
-// src/commands/validate.ts
+// src/commands/migrate.ts
+import fs4 from "fs";
 import path5 from "path";
+import { loadProfileFile, validateResolvedProfile as validateResolvedProfile2 } from "@traits-dev/core";
+import { renderImportedProfileYAML, toValidationResultObject as toValidationResultObject4 } from "@traits-dev/core/internal";
+var SCHEMA_ORDER = {
+  "v1.4": 0,
+  "v1.5": 1,
+  "v1.6": 2
+};
+function printMigrateUsage(out = process.stderr) {
+  out.write(
+    [
+      "Usage:",
+      "  traits migrate <profile-path> [options]",
+      "",
+      "Options:",
+      "  --to <version>            Target schema version (default: v1.6; supported: v1.5, v1.6)",
+      "  --output <path>           Output file path (default: <name>.<target>.yaml)",
+      "  --in-place                Overwrite the source file (requires --force if file exists)",
+      "  --force                   Overwrite existing destination file",
+      "  --normalize-extends       Convert single-string extends to array form (v1.6 target only)",
+      "  --json                    Output structured JSON summary",
+      "  --verbose                 Include additional command metadata",
+      "  --no-color                Disable colorized output",
+      ""
+    ].join("\n")
+  );
+}
+function parseMigrateArgs(args) {
+  const result = {
+    profilePath: null,
+    to: "v1.6",
+    outputPath: null,
+    inPlace: false,
+    force: false,
+    normalizeExtends: false,
+    json: false,
+    verbose: false,
+    noColor: false
+  };
+  const positionals = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--in-place") {
+      result.inPlace = true;
+      continue;
+    }
+    if (arg === "--force") {
+      result.force = true;
+      continue;
+    }
+    if (arg === "--normalize-extends") {
+      result.normalizeExtends = true;
+      continue;
+    }
+    if (arg === "--json") {
+      result.json = true;
+      continue;
+    }
+    if (arg === "--verbose") {
+      result.verbose = true;
+      continue;
+    }
+    if (arg === "--no-color") {
+      result.noColor = true;
+      continue;
+    }
+    if (arg === "--to" || arg === "--output") {
+      const value = args[index + 1];
+      if (!value) return { error: `Missing value for "${arg}"` };
+      if (arg === "--to") {
+        if (value !== "v1.5" && value !== "v1.6") {
+          return {
+            error: `Unsupported "--to" value "${value}". Currently supported: v1.5, v1.6`
+          };
+        }
+        result.to = value;
+      } else {
+        result.outputPath = value;
+      }
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--")) {
+      return { error: `Unknown option "${arg}"` };
+    }
+    positionals.push(arg);
+  }
+  if (positionals.length !== 1) {
+    return { error: "Expected exactly one profile path argument" };
+  }
+  result.profilePath = positionals[0];
+  if (result.inPlace && result.outputPath) {
+    return { error: 'Use either "--in-place" or "--output", not both.' };
+  }
+  if (result.normalizeExtends && result.to !== "v1.6") {
+    return { error: '"--normalize-extends" requires "--to v1.6".' };
+  }
+  return { value: result };
+}
+function resolveDefaultOutputPath(sourcePath, toVersion) {
+  const ext = path5.extname(sourcePath) || ".yaml";
+  const base = sourcePath.slice(0, sourcePath.length - ext.length);
+  return `${base}.${toVersion}${ext}`;
+}
+function writeFileAtomic2(filePath, contents) {
+  fs4.mkdirSync(path5.dirname(filePath), { recursive: true });
+  const tempFile = path5.join(
+    path5.dirname(filePath),
+    `.${path5.basename(filePath)}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`
+  );
+  fs4.writeFileSync(tempFile, contents, "utf8");
+  fs4.renameSync(tempFile, filePath);
+}
+function migrateV14ToV15(profile) {
+  const migrated = JSON.parse(JSON.stringify(profile));
+  migrated.schema = "v1.5";
+  if (!migrated.capabilities) {
+    migrated.capabilities = {
+      tools: [],
+      constraints: [],
+      handoff: {
+        trigger: "Request requires unavailable operations.",
+        action: "Offer handoff to a human operator."
+      }
+    };
+    return { migrated, capabilitiesAdded: true };
+  }
+  return { migrated, capabilitiesAdded: false };
+}
+function migrateV15ToV16(profile, options) {
+  const migrated = JSON.parse(JSON.stringify(profile));
+  migrated.schema = "v1.6";
+  if (options.normalizeExtends && typeof migrated.extends === "string") {
+    const normalized = migrated.extends.trim();
+    if (normalized.length > 0) {
+      migrated.extends = [normalized];
+      return { migrated, extendsNormalized: true };
+    }
+  }
+  return { migrated, extendsNormalized: false };
+}
+function asSupportedSourceSchema(value) {
+  if (value === "v1.4" || value === "v1.5") return value;
+  return null;
+}
+function runMigrate(args, io = process) {
+  const parsed = parseMigrateArgs(args);
+  if ("error" in parsed) {
+    io.stderr.write(`Error: ${parsed.error}
+
+`);
+    printMigrateUsage(io.stderr);
+    return 1;
+  }
+  const options = parsed.value;
+  if (!options.profilePath) {
+    io.stderr.write("Error: Missing profile path\n\n");
+    printMigrateUsage(io.stderr);
+    return 1;
+  }
+  const sourcePath = path5.resolve(io.cwd(), options.profilePath);
+  const destinationPath = options.inPlace ? sourcePath : options.outputPath ? path5.resolve(io.cwd(), options.outputPath) : resolveDefaultOutputPath(sourcePath, options.to);
+  if (!fs4.existsSync(sourcePath)) {
+    io.stderr.write(`Error: Source profile does not exist: ${sourcePath}
+`);
+    return 1;
+  }
+  if (fs4.existsSync(destinationPath) && !options.force) {
+    io.stderr.write(
+      `Error: Destination file already exists: ${destinationPath}. Use --force to overwrite.
+`
+    );
+    return 1;
+  }
+  let loaded;
+  try {
+    loaded = loadProfileFile(sourcePath);
+  } catch (error) {
+    io.stderr.write(
+      `Error: Failed to read profile: ${error instanceof Error ? error.message : String(error)}
+`
+    );
+    return 1;
+  }
+  if (loaded.schema === "v1.6") {
+    io.stderr.write(
+      'Error: Source profile is already at "v1.6". Nothing to migrate.\n'
+    );
+    return 1;
+  }
+  const sourceSchema = asSupportedSourceSchema(loaded.schema);
+  if (!sourceSchema) {
+    io.stderr.write(
+      `Error: Migration source schema must be "v1.4" or "v1.5". Found "${loaded.schema ?? "unknown"}".
+`
+    );
+    return 1;
+  }
+  if (SCHEMA_ORDER[options.to] < SCHEMA_ORDER[sourceSchema]) {
+    io.stderr.write(
+      `Error: Downgrade is not supported (source "${sourceSchema}" -> target "${options.to}").
+`
+    );
+    return 1;
+  }
+  if (SCHEMA_ORDER[options.to] === SCHEMA_ORDER[sourceSchema]) {
+    io.stderr.write(`Error: Source profile already uses target schema "${options.to}".
+`);
+    return 1;
+  }
+  let migrated = loaded;
+  let capabilitiesAdded = false;
+  let extendsNormalized = false;
+  let currentSchema = sourceSchema;
+  if (currentSchema === "v1.4") {
+    const step = migrateV14ToV15(migrated);
+    migrated = step.migrated;
+    capabilitiesAdded = step.capabilitiesAdded;
+    currentSchema = "v1.5";
+  }
+  if (options.to === "v1.6" && currentSchema === "v1.5") {
+    const step = migrateV15ToV16(migrated, {
+      normalizeExtends: options.normalizeExtends
+    });
+    migrated = step.migrated;
+    extendsNormalized = step.extendsNormalized;
+    currentSchema = "v1.6";
+  }
+  if (currentSchema !== options.to) {
+    io.stderr.write(
+      `Error: Failed to migrate profile to target schema "${options.to}". Final schema: "${currentSchema}".
+`
+    );
+    return 2;
+  }
+  const validation = validateResolvedProfile2(migrated, {
+    strict: false
+  });
+  if (validation.errors.length > 0) {
+    io.stderr.write(
+      `Error: Migrated profile is invalid and was not written (${validation.errors.length} error(s)).
+`
+    );
+    return 2;
+  }
+  const yaml = renderImportedProfileYAML(migrated);
+  writeFileAtomic2(destinationPath, yaml);
+  if (options.json) {
+    io.stdout.write(
+      `${JSON.stringify(
+        {
+          migrated: true,
+          sourcePath,
+          outputPath: destinationPath,
+          fromSchema: sourceSchema,
+          toSchema: options.to,
+          capabilitiesAdded,
+          extendsNormalized,
+          validation: toValidationResultObject4(validation)
+        },
+        null,
+        2
+      )}
+`
+    );
+    return 0;
+  }
+  if (options.verbose) {
+    io.stdout.write(`Source: ${sourcePath}
+`);
+    io.stdout.write(`Output: ${destinationPath}
+`);
+    io.stdout.write(`Capabilities added: ${capabilitiesAdded ? "yes" : "no"}
+`);
+    io.stdout.write(`Extends normalized: ${extendsNormalized ? "yes" : "no"}
+`);
+    io.stdout.write(`Validation warnings: ${validation.warnings.length}
+
+`);
+  }
+  io.stdout.write(`Migrated profile schema ${sourceSchema} -> ${options.to}
+`);
+  io.stdout.write(`Wrote: ${destinationPath}
+`);
+  return 0;
+}
+function migrateHelp(out = process.stdout) {
+  printMigrateUsage(out);
+}
+
+// src/commands/validate.ts
+import path6 from "path";
 import { validateProfile as validateProfile2 } from "@traits-dev/core";
 import {
   formatValidationResult as formatValidationResult4,
-  toValidationResultObject as toValidationResultObject4
+  toValidationResultObject as toValidationResultObject5
 } from "@traits-dev/core/internal";
 function printValidateUsage(out = process.stderr) {
   out.write(
     [
       "Usage:",
-      "  traits validate <profile-path> [--json] [--strict] [--bundled-profiles-dir <dir>]",
+      "  traits validate <profile-path> [options]",
       "",
       "Options:",
       "  --json                   Output structured JSON",
+      "  --format <text|json|sarif> Output format (default: text)",
       "  --strict                 Promote warnings to errors",
       "  --verbose                Include additional command metadata",
       "  --no-color               Disable colorized output",
@@ -1474,6 +1769,7 @@ function parseValidateArgs(args) {
     profilePath: null,
     strict: false,
     json: false,
+    format: "text",
     verbose: false,
     noColor: false,
     bundledProfilesDir: null
@@ -1487,6 +1783,7 @@ function parseValidateArgs(args) {
     }
     if (arg === "--json") {
       result.json = true;
+      result.format = "json";
       continue;
     }
     if (arg === "--verbose") {
@@ -1506,6 +1803,20 @@ function parseValidateArgs(args) {
       index += 1;
       continue;
     }
+    if (arg === "--format") {
+      const nextValue = args[index + 1];
+      if (!nextValue) {
+        return { error: 'Missing value for "--format"' };
+      }
+      const normalized = String(nextValue).toLowerCase();
+      if (normalized !== "text" && normalized !== "json" && normalized !== "sarif") {
+        return { error: 'Invalid "--format" value. Expected text, json, or sarif.' };
+      }
+      result.format = normalized;
+      result.json = normalized === "json";
+      index += 1;
+      continue;
+    }
     if (arg.startsWith("--")) {
       return { error: `Unknown option "${arg}"` };
     }
@@ -1517,6 +1828,54 @@ function parseValidateArgs(args) {
   result.profilePath = positionals[0];
   return { value: result };
 }
+function toRelativePath(cwd, filePath) {
+  const relative = path6.relative(cwd, filePath);
+  if (relative && !relative.startsWith("..")) return relative;
+  return filePath;
+}
+function buildSarifReport(validation, profilePath, cwd) {
+  const diagnostics = [...validation.errors, ...validation.warnings];
+  const uniqueRuleIds = [...new Set(diagnostics.map((diagnostic) => diagnostic.code))];
+  const artifactUri = toRelativePath(cwd, profilePath);
+  const rules = uniqueRuleIds.map((ruleId) => ({
+    id: ruleId,
+    shortDescription: {
+      text: `traits.dev ${ruleId}`
+    }
+  }));
+  const results = diagnostics.map((diagnostic) => ({
+    ruleId: diagnostic.code,
+    level: diagnostic.severity === "error" ? "error" : "warning",
+    message: {
+      text: diagnostic.message
+    },
+    locations: [
+      {
+        physicalLocation: {
+          artifactLocation: {
+            uri: artifactUri
+          }
+        }
+      }
+    ]
+  }));
+  return {
+    version: "2.1.0",
+    $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: "traits.dev",
+            informationUri: "https://github.com/justinhambleton/traits",
+            rules
+          }
+        },
+        results
+      }
+    ]
+  };
+}
 function runValidate(args, io = process) {
   const parsed = parseValidateArgs(args);
   if ("error" in parsed) {
@@ -1532,14 +1891,18 @@ function runValidate(args, io = process) {
     printValidateUsage(io.stderr);
     return 1;
   }
-  const bundledProfilesDir = options.bundledProfilesDir ? path5.resolve(io.cwd(), options.bundledProfilesDir) : path5.resolve(io.cwd(), "profiles");
-  const profilePath = path5.resolve(io.cwd(), options.profilePath);
+  const bundledProfilesDir = options.bundledProfilesDir ? path6.resolve(io.cwd(), options.bundledProfilesDir) : path6.resolve(io.cwd(), "profiles");
+  const profilePath = path6.resolve(io.cwd(), options.profilePath);
   const result = validateProfile2(profilePath, {
     strict: options.strict,
     bundledProfilesDir
   });
-  if (options.json) {
-    io.stdout.write(`${JSON.stringify(toValidationResultObject4(result), null, 2)}
+  if (options.format === "json") {
+    io.stdout.write(`${JSON.stringify(toValidationResultObject5(result), null, 2)}
+`);
+  } else if (options.format === "sarif") {
+    const sarif = buildSarifReport(result, profilePath, io.cwd());
+    io.stdout.write(`${JSON.stringify(sarif, null, 2)}
 `);
   } else {
     if (options.verbose) {
@@ -1561,14 +1924,14 @@ function validateHelp(out = process.stdout) {
 }
 
 // src/bin/traits.ts
-var CLI_DIR = path6.dirname(fileURLToPath(import.meta.url));
+var CLI_DIR = path7.dirname(fileURLToPath(import.meta.url));
 var PACKAGE_JSON_CANDIDATES = [
-  path6.resolve(CLI_DIR, "../package.json"),
-  path6.resolve(CLI_DIR, "../../package.json")
+  path7.resolve(CLI_DIR, "../package.json"),
+  path7.resolve(CLI_DIR, "../../package.json")
 ];
 function resolvePackageJsonPath() {
   for (const candidate of PACKAGE_JSON_CANDIDATES) {
-    if (fs4.existsSync(candidate)) return candidate;
+    if (fs5.existsSync(candidate)) return candidate;
   }
   return PACKAGE_JSON_CANDIDATES[0];
 }
@@ -1586,6 +1949,7 @@ function printRootUsage(out = process.stdout) {
       "  compile <profile-path>    Compile a profile for a target model",
       "  eval <profile-path>       Evaluate profile responses (Tier 1 scaffold)",
       "  import [prompt-path]      Import a profile from an existing system prompt",
+      "  migrate <profile-path>    Migrate profile schema (up to v1.6)",
       "  validate <profile-path>   Validate a voice profile",
       "",
       "Global flags:",
@@ -1605,7 +1969,7 @@ function printRootUsage(out = process.stdout) {
 }
 function readCliVersion() {
   try {
-    const raw = fs4.readFileSync(PACKAGE_JSON_PATH, "utf8");
+    const raw = fs5.readFileSync(PACKAGE_JSON_PATH, "utf8");
     const pkg = JSON.parse(raw);
     return String(pkg.version ?? "0.0.0");
   } catch {
@@ -1651,7 +2015,7 @@ function withGlobalFlags(command, commandArgs, flags) {
   if (flags.noColor && !args.includes("--no-color")) {
     args.push("--no-color");
   }
-  if ((command === "validate" || command === "compile" || command === "eval" || command === "import") && flags.json && !args.includes("--json")) {
+  if ((command === "validate" || command === "compile" || command === "eval" || command === "import" || command === "migrate") && flags.json && !args.includes("--json")) {
     args.push("--json");
   }
   return args;
@@ -1717,6 +2081,13 @@ async function run(argv, io = process) {
     }
     return runImport(commandArgs, io);
   }
+  if (command === "migrate") {
+    if (commandArgs.includes("--help") || commandArgs.includes("-h")) {
+      migrateHelp(io.stdout);
+      return 0;
+    }
+    return runMigrate(commandArgs, io);
+  }
   io.stderr.write(`Error: Unknown command "${command}"
 
 `);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@traits-dev/cli",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "traits.dev command-line interface for voice profile init, validate, compile, eval, and import workflows.",
   "keywords": [
     "traits-dev",
@@ -41,7 +41,7 @@
     "provenance": true
   },
   "dependencies": {
-    "@traits-dev/core": "^0.4.0"
+    "@traits-dev/core": "^0.6.0"
   },
   "devDependencies": {
     "@types/node": "^25.2.3",