@traits-dev/cli 0.3.0 → 0.5.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-4.yaml
 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
@@ -22,6 +22,8 @@ function printCompileUsage(out = process.stderr) {
       "  --model <model>           Model target (required)",
       "  --json                    Output structured JSON",
       "  --strict                  Treat warnings as compile-blocking",
+      "  --budget                  Print estimated token count (chars/4)",
+      "  --budget-limit <tokens>   Warn to stderr if estimate exceeds limit",
       "  --explain                 Include compilation trace output",
       "  --context key=value       Activate context adaptation (repeatable)",
       "  --knowledge-base-dir      Directory containing compiler pattern files",
@@ -52,6 +54,8 @@ function parseCompileArgs(args) {
     model: null,
     strict: false,
     json: false,
+    budget: false,
+    budgetLimit: null,
     explain: false,
     verbose: false,
     noColor: false,
@@ -70,6 +74,10 @@ function parseCompileArgs(args) {
       result.json = true;
       continue;
     }
+    if (arg === "--budget") {
+      result.budget = true;
+      continue;
+    }
     if (arg === "--explain") {
       result.explain = true;
       continue;
@@ -82,7 +90,7 @@ function parseCompileArgs(args) {
       result.noColor = true;
       continue;
     }
-    if (arg === "--model" || arg === "--bundled-profiles-dir" || arg === "--context" || arg === "--knowledge-base-dir") {
+    if (arg === "--model" || arg === "--bundled-profiles-dir" || arg === "--context" || arg === "--knowledge-base-dir" || arg === "--budget-limit") {
       const value = args[index + 1];
       if (!value) return { error: `Missing value for "${arg}"` };
       if (arg === "--model") {
@@ -91,6 +99,12 @@ function parseCompileArgs(args) {
         result.bundledProfilesDir = value;
       } else if (arg === "--knowledge-base-dir") {
         result.knowledgeBaseDir = value;
+      } else if (arg === "--budget-limit") {
+        const parsedBudgetLimit = Number(value);
+        if (!Number.isFinite(parsedBudgetLimit) || parsedBudgetLimit <= 0) {
+          return { error: `Invalid value for "--budget-limit": "${value}"` };
+        }
+        result.budgetLimit = Math.round(parsedBudgetLimit);
       } else {
         const parsedContext = parseContextArg(value);
         if ("error" in parsedContext) return { error: parsedContext.error };
@@ -111,8 +125,14 @@ function parseCompileArgs(args) {
   if (!result.model) {
     return { error: 'Missing required option "--model"' };
   }
+  if (result.budgetLimit != null) {
+    result.budget = true;
+  }
   return { value: result };
 }
+function estimateBudgetTokens(text) {
+  return Math.ceil(String(text ?? "").length / 4);
+}
 function runCompile(args, io = process) {
   const parsed = parseCompileArgs(args);
   if ("error" in parsed) {
@@ -156,10 +176,32 @@ function runCompile(args, io = process) {
     if (options.json) {
       io.stdout.write(`${JSON.stringify(compiled, null, 2)}
 `);
+      if (options.budget) {
+        const budgetEstimate = estimateBudgetTokens(compiled.text);
+        io.stderr.write(`Estimated token count: ${budgetEstimate}
+`);
+        if (options.budgetLimit != null && budgetEstimate > options.budgetLimit) {
+          io.stderr.write(
+            `Warning: Estimated token count ${budgetEstimate} exceeds budget limit ${options.budgetLimit}
+`
+          );
+        }
+      }
       return 0;
     }
     io.stdout.write(`${compiled.text}
 `);
+    if (options.budget) {
+      const budgetEstimate = estimateBudgetTokens(compiled.text);
+      io.stderr.write(`Estimated token count: ${budgetEstimate}
+`);
+      if (options.budgetLimit != null && budgetEstimate > options.budgetLimit) {
+        io.stderr.write(
+          `Warning: Estimated token count ${budgetEstimate} exceeds budget limit ${options.budgetLimit}
+`
+        );
+      }
+    }
     if (options.explain && compiled.trace) {
       io.stdout.write(`
 [TRACE]
@@ -1404,21 +1446,238 @@ 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";
+function printMigrateUsage(out = process.stderr) {
+  out.write(
+    [
+      "Usage:",
+      "  traits migrate <profile-path> [options]",
+      "",
+      "Options:",
+      "  --to <version>            Target schema version (default: v1.5)",
+      "  --output <path>           Output file path (default: <name>.v1.5.yaml)",
+      "  --in-place                Overwrite the source file (requires --force if file exists)",
+      "  --force                   Overwrite existing destination file",
+      "  --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.5",
+    outputPath: null,
+    inPlace: false,
+    force: 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 === "--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") {
+          return {
+            error: `Unsupported "--to" value "${value}". Currently supported: v1.5`
+          };
+        }
+        result.to = "v1.5";
+      } 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.' };
+  }
+  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 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.4") {
+    io.stderr.write(
+      `Error: Migration source schema must be "v1.4". Found "${loaded.schema ?? "unknown"}".
+`
+    );
+    return 1;
+  }
+  const migration = migrateV14ToV15(loaded);
+  const validation = validateResolvedProfile2(migration.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(migration.migrated);
+  writeFileAtomic2(destinationPath, yaml);
+  if (options.json) {
+    io.stdout.write(
+      `${JSON.stringify(
+        {
+          migrated: true,
+          sourcePath,
+          outputPath: destinationPath,
+          fromSchema: "v1.4",
+          toSchema: "v1.5",
+          capabilitiesAdded: migration.capabilitiesAdded,
+          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: ${migration.capabilitiesAdded ? "yes" : "no"}
+`);
+    io.stdout.write(`Validation warnings: ${validation.warnings.length}
+
+`);
+  }
+  io.stdout.write(`Migrated profile schema v1.4 -> v1.5
+`);
+  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",
@@ -1432,6 +1691,7 @@ function parseValidateArgs(args) {
     profilePath: null,
     strict: false,
     json: false,
+    format: "text",
     verbose: false,
     noColor: false,
     bundledProfilesDir: null
@@ -1445,6 +1705,7 @@ function parseValidateArgs(args) {
     }
     if (arg === "--json") {
       result.json = true;
+      result.format = "json";
       continue;
     }
     if (arg === "--verbose") {
@@ -1464,6 +1725,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}"` };
     }
@@ -1475,6 +1750,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) {
@@ -1490,14 +1813,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) {
@@ -1519,14 +1846,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];
 }
@@ -1544,6 +1871,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 (v1.4 -> v1.5)",
       "  validate <profile-path>   Validate a voice profile",
       "",
       "Global flags:",
@@ -1563,7 +1891,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 {
@@ -1609,7 +1937,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;
@@ -1675,6 +2003,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.3.0",
+  "version": "0.5.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.3.0"
+    "@traits-dev/core": "^0.5.0"
   },
   "devDependencies": {
     "@types/node": "^25.2.3",