@enactprotocol/cli 2.1.28 → 2.1.29

package/src/commands/run/index.ts

@@ -84,6 +84,7 @@ interface RunOptions extends GlobalOptions {
   verbose?: boolean;
   output?: string;
   apply?: boolean;
+  debug?: boolean;
 }
 
 /**
@@ -630,6 +631,84 @@ function displayDryRun(
   newline();
 }
 
+/**
+ * Display debug information about parameter resolution
+ */
+function displayDebugInfo(
+  manifest: ToolManifest,
+  rawInputs: Record<string, unknown>,
+  inputsWithDefaults: Record<string, unknown>,
+  finalInputs: Record<string, unknown>,
+  env: Record<string, string>,
+  command: string[]
+): void {
+  newline();
+  info(colors.bold("Debug: Parameter Resolution"));
+  newline();
+
+  // Show schema information
+  if (manifest.inputSchema?.properties) {
+    info("Schema Properties:");
+    const required = new Set(manifest.inputSchema.required || []);
+    for (const [name, prop] of Object.entries(manifest.inputSchema.properties)) {
+      const propSchema = prop as { type?: string; default?: unknown; description?: string };
+      const isRequired = required.has(name);
+      const hasDefault = propSchema.default !== undefined;
+      const status = isRequired ? colors.error("required") : colors.dim("optional");
+      dim(
+        `  ${name}: ${propSchema.type || "any"} [${status}]${hasDefault ? ` (default: ${JSON.stringify(propSchema.default)})` : ""}`
+      );
+    }
+    newline();
+  }
+
+  // Show raw inputs (what was provided)
+  info("Raw Inputs (provided by user):");
+  if (Object.keys(rawInputs).length === 0) {
+    dim("  (none)");
+  } else {
+    for (const [key, value] of Object.entries(rawInputs)) {
+      dim(`  ${key}: ${JSON.stringify(value)}`);
+    }
+  }
+  newline();
+
+  // Show inputs after defaults applied
+  info("After Defaults Applied:");
+  for (const [key, value] of Object.entries(inputsWithDefaults)) {
+    const wasDefault = rawInputs[key] === undefined;
+    dim(`  ${key}: ${JSON.stringify(value)}${wasDefault ? colors.dim(" (default)") : ""}`);
+  }
+  newline();
+
+  // Show final inputs (after coercion)
+  info("Final Inputs (after validation/coercion):");
+  for (const [key, value] of Object.entries(finalInputs)) {
+    dim(`  ${key}: ${JSON.stringify(value)}`);
+  }
+  newline();
+
+  // Show environment variables
+  if (Object.keys(env).length > 0) {
+    info("Environment Variables:");
+    for (const [key, value] of Object.entries(env)) {
+      // Mask potentially sensitive values
+      const isSensitive =
+        key.toLowerCase().includes("secret") ||
+        key.toLowerCase().includes("key") ||
+        key.toLowerCase().includes("token") ||
+        key.toLowerCase().includes("password");
+      dim(`  ${key}=${isSensitive ? "***" : value}`);
+    }
+    newline();
+  }
+
+  // Show final command
+  info("Final Command:");
+  dim(`  ${command.join(" ")}`);
+  newline();
+}
+
 /**
  * Display execution result
  */
@@ -661,15 +740,30 @@ function displayResult(result: ExecutionResult, options: RunOptions): void {
   } else {
     error(`Execution failed: ${result.error?.message ?? "Unknown error"}`);
 
-    if (result.error?.details) {
+    // Show stdout if present (useful for debugging - command may have printed before failing)
+    if (result.output?.stdout?.trim()) {
       newline();
-      dim(JSON.stringify(result.error.details, null, 2));
+      info("stdout:");
+      console.log(result.output.stdout);
     }
 
-    if (result.output?.stderr) {
+    // Show stderr (the actual error output)
+    if (result.output?.stderr?.trim()) {
       newline();
-      dim("stderr:");
-      dim(result.output.stderr);
+      error("stderr:");
+      console.log(result.output.stderr);
+    }
+
+    // Show additional error details if present (and different from stderr)
+    if (result.error?.details) {
+      const detailsStr = JSON.stringify(result.error.details, null, 2);
+      // Only show if it adds new information (not just duplicating stderr)
+      const stderrInDetails = result.error.details.stderr;
+      if (!stderrInDetails || stderrInDetails !== result.output?.stderr) {
+        newline();
+        dim("Additional details:");
+        dim(detailsStr);
+      }
     }
   }
 }
@@ -908,6 +1002,11 @@ async function runHandler(tool: string, options: RunOptions, ctx: CommandContext
     }
   }
 
+  // Debug mode - show detailed parameter resolution info
+  if (options.debug) {
+    displayDebugInfo(manifest, inputs, inputsWithDefaults, finalInputs, envVars, command);
+  }
+
   // Dry run mode
   if (options.dryRun) {
     displayDryRun(
@@ -1060,6 +1159,7 @@ export function configureRunCommand(program: Command): void {
     .option("--local", "Only resolve from local sources")
     .option("-r, --remote", "Skip local resolution and fetch from registry")
     .option("--dry-run", "Show what would be executed without running")
+    .option("--debug", "Show detailed parameter and environment variable resolution")
     .option("-v, --verbose", "Show progress spinners and detailed output")
     .option("--json", "Output result as JSON")
     .action(async (tool: string, options: RunOptions) => {

package/src/commands/validate/index.ts

@@ -0,0 +1,344 @@
+/**
+ * enact validate command
+ *
+ * Validate a SKILL.md file for common issues and best practices.
+ */
+
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { type ToolManifest, tryResolveTool } from "@enactprotocol/shared";
+import type { Command } from "commander";
+import type { CommandContext, GlobalOptions } from "../../types";
+import { colors, dim, error, formatError, info, newline, success, symbols } from "../../utils";
+
+interface ValidateOptions extends GlobalOptions {
+  fix?: boolean;
+}
+
+interface ValidationIssue {
+  level: "error" | "warning" | "info";
+  message: string;
+  suggestion?: string;
+}
+
+/**
+ * Extract parameter names from a command template
+ */
+function extractCommandParams(command: string): string[] {
+  const params: string[] = [];
+  const regex = /\$\{([^}:]+)(?::[^}]+)?\}/g;
+  let match: RegExpExecArray | null;
+  match = regex.exec(command);
+  while (match !== null) {
+    if (match[1] && !params.includes(match[1])) {
+      params.push(match[1]);
+    }
+    match = regex.exec(command);
+  }
+  return params;
+}
+
+/**
+ * Validate a tool manifest
+ */
+function validateManifest(manifest: ToolManifest, sourceDir: string): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  // Check name format
+  if (!manifest.name) {
+    issues.push({
+      level: "error",
+      message: "Missing 'name' field",
+      suggestion: "Add a name in format: namespace/category/tool",
+    });
+  } else if (!manifest.name.includes("/")) {
+    issues.push({
+      level: "warning",
+      message: `Name '${manifest.name}' should follow hierarchical format`,
+      suggestion: "Use format: namespace/category/tool (e.g., alice/utils/formatter)",
+    });
+  }
+
+  // Check version
+  if (!manifest.version) {
+    issues.push({
+      level: "warning",
+      message: "Missing 'version' field",
+      suggestion: "Add a version using semver (e.g., 1.0.0)",
+    });
+  }
+
+  // Check description
+  if (!manifest.description) {
+    issues.push({
+      level: "warning",
+      message: "Missing 'description' field",
+      suggestion: "Add a clear description for discoverability",
+    });
+  }
+
+  // Check base image
+  if (manifest.from) {
+    if (manifest.from.endsWith(":latest")) {
+      issues.push({
+        level: "warning",
+        message: `Base image '${manifest.from}' uses :latest tag`,
+        suggestion: "Pin to a specific version (e.g., python:3.12-slim instead of python:latest)",
+      });
+    }
+  } else if (manifest.command) {
+    issues.push({
+      level: "info",
+      message: "No 'from' field specified, will use alpine:latest",
+      suggestion: "Consider specifying a base image for reproducibility",
+    });
+  }
+
+  // Check command vs instruction tool
+  if (!manifest.command) {
+    // Instruction-based tool
+    issues.push({
+      level: "info",
+      message: "No 'command' field - this is an LLM instruction tool",
+    });
+  } else {
+    // Command-based tool - validate parameters
+    const commandParams = extractCommandParams(manifest.command);
+    const schemaProperties = manifest.inputSchema?.properties
+      ? Object.keys(manifest.inputSchema.properties)
+      : [];
+    const requiredParams = manifest.inputSchema?.required || [];
+
+    // Check for command params not in schema
+    for (const param of commandParams) {
+      if (!schemaProperties.includes(param)) {
+        issues.push({
+          level: "error",
+          message: `Command uses \${${param}} but it's not defined in inputSchema.properties`,
+          suggestion: `Add '${param}' to inputSchema.properties`,
+        });
+      }
+    }
+
+    // Check for required params without command usage (potential issue)
+    for (const param of requiredParams) {
+      if (!commandParams.includes(param)) {
+        issues.push({
+          level: "info",
+          message: `Required parameter '${param}' is not used in command template`,
+          suggestion: "This is fine if you access it via environment or files",
+        });
+      }
+    }
+
+    // Check for optional params without defaults
+    for (const prop of schemaProperties) {
+      if (!requiredParams.includes(prop)) {
+        const propSchema = manifest.inputSchema?.properties?.[prop] as
+          | { default?: unknown }
+          | undefined;
+        if (propSchema?.default === undefined) {
+          issues.push({
+            level: "warning",
+            message: `Optional parameter '${prop}' has no default value`,
+            suggestion: "Add a default value or it will be empty string in commands",
+          });
+        }
+      }
+    }
+
+    // Check for double-quoting in command
+    if (
+      manifest.command.includes("'${") ||
+      manifest.command.includes('"${') ||
+      (manifest.command.includes("${") &&
+        (manifest.command.includes("}'") || manifest.command.includes('}"')))
+    ) {
+      issues.push({
+        level: "warning",
+        message: "Command may have manual quotes around parameters",
+        suggestion: "Enact auto-quotes parameters. Remove manual quotes around ${param}",
+      });
+    }
+  }
+
+  // Check timeout
+  if (!manifest.timeout && manifest.command) {
+    issues.push({
+      level: "info",
+      message: "No 'timeout' specified, using default (5 minutes)",
+      suggestion: "Consider setting an explicit timeout for long-running tools",
+    });
+  }
+
+  // Check for common file patterns
+  if (manifest.command) {
+    // Python tools
+    if (manifest.command.includes("python") && manifest.from?.includes("python")) {
+      const mainPy = resolve(sourceDir, "main.py");
+      if (manifest.command.includes("/workspace/main.py") && !existsSync(mainPy)) {
+        issues.push({
+          level: "error",
+          message: "Command references /workspace/main.py but main.py not found",
+          suggestion: "Create main.py or update the command path",
+        });
+      }
+    }
+
+    // Node tools
+    if (manifest.command.includes("node") && manifest.from?.includes("node")) {
+      const indexJs = resolve(sourceDir, "index.js");
+      const mainJs = resolve(sourceDir, "main.js");
+      if (
+        manifest.command.includes("/workspace/index.js") &&
+        !existsSync(indexJs) &&
+        !existsSync(mainJs)
+      ) {
+        issues.push({
+          level: "warning",
+          message: "Command references /workspace/index.js but index.js not found",
+          suggestion: "Create index.js or update the command path",
+        });
+      }
+    }
+  }
+
+  // Check env declarations
+  if (manifest.env) {
+    for (const [key, envDef] of Object.entries(manifest.env)) {
+      if (envDef.secret && !envDef.description) {
+        issues.push({
+          level: "info",
+          message: `Secret '${key}' has no description`,
+          suggestion: "Add a description to help users understand what this secret is for",
+        });
+      }
+    }
+  }
+
+  return issues;
+}
+
+/**
+ * Display validation results
+ */
+function displayResults(issues: ValidationIssue[], toolPath: string): void {
+  const errors = issues.filter((i) => i.level === "error");
+  const warnings = issues.filter((i) => i.level === "warning");
+  const infos = issues.filter((i) => i.level === "info");
+
+  newline();
+
+  if (issues.length === 0) {
+    success(`${symbols.success} ${toolPath} - No issues found!`);
+    return;
+  }
+
+  info(`Validation results for ${toolPath}:`);
+  newline();
+
+  // Display errors
+  for (const issue of errors) {
+    console.log(`  ${colors.error(`${symbols.error} ERROR:`)} ${issue.message}`);
+    if (issue.suggestion) {
+      dim(`    → ${issue.suggestion}`);
+    }
+  }
+
+  // Display warnings
+  for (const issue of warnings) {
+    console.log(`  ${colors.warning(`${symbols.warning} WARNING:`)} ${issue.message}`);
+    if (issue.suggestion) {
+      dim(`    → ${issue.suggestion}`);
+    }
+  }
+
+  // Display info
+  for (const issue of infos) {
+    console.log(`  ${colors.info(`${symbols.info} INFO:`)} ${issue.message}`);
+    if (issue.suggestion) {
+      dim(`    → ${issue.suggestion}`);
+    }
+  }
+
+  newline();
+
+  // Summary
+  const summary: string[] = [];
+  if (errors.length > 0) summary.push(`${errors.length} error${errors.length > 1 ? "s" : ""}`);
+  if (warnings.length > 0)
+    summary.push(`${warnings.length} warning${warnings.length > 1 ? "s" : ""}`);
+  if (infos.length > 0) summary.push(`${infos.length} info`);
+
+  if (errors.length > 0) {
+    error(`Found ${summary.join(", ")}`);
+  } else if (warnings.length > 0) {
+    console.log(colors.warning(`Found ${summary.join(", ")}`));
+  } else {
+    success(`Found ${summary.join(", ")} - looking good!`);
+  }
+}
+
+/**
+ * Validate command handler
+ */
+function validateHandler(toolPath: string, _options: ValidateOptions, ctx: CommandContext): void {
+  const resolvedPath = resolve(ctx.cwd, toolPath);
+
+  // Check if path exists
+  if (!existsSync(resolvedPath)) {
+    error(`Path not found: ${resolvedPath}`);
+    process.exit(1);
+  }
+
+  // Resolve the tool
+  const resolution = tryResolveTool(resolvedPath);
+
+  if (!resolution) {
+    error(`Could not find SKILL.md in: ${resolvedPath}`);
+    dim("Make sure the directory contains a valid SKILL.md file.");
+    process.exit(1);
+  }
+
+  // Validate the manifest
+  const issues = validateManifest(resolution.manifest, resolution.sourceDir);
+
+  // Display results
+  displayResults(issues, toolPath);
+
+  // Exit with error if there are errors
+  const hasErrors = issues.some((i) => i.level === "error");
+  if (hasErrors) {
+    process.exit(1);
+  }
+}
+
+/**
+ * Configure the validate command
+ */
+export function configureValidateCommand(program: Command): void {
+  program
+    .command("validate")
+    .description("Validate a SKILL.md file for common issues")
+    .argument("[path]", "Path to tool directory", ".")
+    .option("-v, --verbose", "Show detailed output")
+    .option("--json", "Output result as JSON")
+    .action((toolPath: string, options: ValidateOptions) => {
+      const ctx: CommandContext = {
+        cwd: process.cwd(),
+        options,
+        isCI: Boolean(process.env.CI),
+        isInteractive: process.stdout.isTTY ?? false,
+      };
+
+      try {
+        validateHandler(toolPath, options, ctx);
+      } catch (err) {
+        error(formatError(err));
+        if (options.verbose && err instanceof Error && err.stack) {
+          dim(err.stack);
+        }
+        process.exit(1);
+      }
+    });
+}

package/src/index.ts

@@ -30,12 +30,13 @@ import {
   configureSignCommand,
   configureTrustCommand,
   configureUnyankCommand,
+  configureValidateCommand,
   configureVisibilityCommand,
   configureYankCommand,
 } from "./commands";
 import { error, formatError } from "./utils";
 
-export const version = "2.1.28";
+export const version = "2.1.29";
 
 // Export types for external use
 export type { GlobalOptions, CommandContext } from "./types";
@@ -85,6 +86,9 @@ async function main() {
   // MCP integration commands
   configureMcpCommand(program);
 
+  // Validation command
+  configureValidateCommand(program);
+
   // Global error handler - handle Commander's help/version exits gracefully
   program.exitOverride((err) => {
     // Commander throws errors for help, version, and other "exit" scenarios

package/src/types.ts

@@ -16,6 +16,8 @@ export interface GlobalOptions {
   quiet?: boolean;
   /** Run without making changes (preview mode) */
   dryRun?: boolean;
+  /** Enable debug mode - show detailed parameter and environment information */
+  debug?: boolean;
 }
 
 /**

package/tests/commands/init.test.ts

@@ -565,7 +565,7 @@ describe("init command", () => {
 
       // Should be comprehensive but not excessive
       const lines = content.split("\n").length;
-      expect(lines).toBeLessThan(250); // Comprehensive guide under 250 lines
+      expect(lines).toBeLessThan(350); // Comprehensive guide under 350 lines (includes base image docs, troubleshooting)
       expect(lines).toBeGreaterThan(100); // But not too sparse
 
       // Clean up

package/tests/commands/validate.test.ts

@@ -0,0 +1,81 @@
+/**
+ * Tests for the validate command
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { Command } from "commander";
+import { configureValidateCommand } from "../../src/commands/validate";
+
+// Test fixtures directory
+const FIXTURES_DIR = join(import.meta.dir, "..", "fixtures", "validate-cmd");
+
+describe("validate command", () => {
+  beforeAll(() => {
+    mkdirSync(FIXTURES_DIR, { recursive: true });
+  });
+
+  afterAll(() => {
+    if (existsSync(FIXTURES_DIR)) {
+      rmSync(FIXTURES_DIR, { recursive: true, force: true });
+    }
+  });
+
+  describe("command configuration", () => {
+    test("configures validate command on program", () => {
+      const program = new Command();
+      configureValidateCommand(program);
+
+      const validateCmd = program.commands.find((cmd) => cmd.name() === "validate");
+      expect(validateCmd).toBeDefined();
+    });
+
+    test("has correct description", () => {
+      const program = new Command();
+      configureValidateCommand(program);
+
+      const validateCmd = program.commands.find((cmd) => cmd.name() === "validate");
+      expect(validateCmd?.description()).toBe("Validate a SKILL.md file for common issues");
+    });
+
+    test("accepts optional path argument", () => {
+      const program = new Command();
+      configureValidateCommand(program);
+
+      const validateCmd = program.commands.find((cmd) => cmd.name() === "validate");
+      const args = validateCmd?.registeredArguments ?? [];
+      expect(args.length).toBeGreaterThanOrEqual(1);
+      expect(args[0]?.name()).toBe("path");
+    });
+
+    test("path argument defaults to current directory", () => {
+      const program = new Command();
+      configureValidateCommand(program);
+
+      const validateCmd = program.commands.find((cmd) => cmd.name() === "validate");
+      const args = validateCmd?.registeredArguments ?? [];
+      expect(args[0]?.defaultValue).toBe(".");
+    });
+
+    test("has --verbose option", () => {
+      const program = new Command();
+      configureValidateCommand(program);
+
+      const validateCmd = program.commands.find((cmd) => cmd.name() === "validate");
+      const opts = validateCmd?.options ?? [];
+      const verboseOpt = opts.find((o) => o.long === "--verbose");
+      expect(verboseOpt).toBeDefined();
+    });
+
+    test("has --json option", () => {
+      const program = new Command();
+      configureValidateCommand(program);
+
+      const validateCmd = program.commands.find((cmd) => cmd.name() === "validate");
+      const opts = validateCmd?.options ?? [];
+      const jsonOpt = opts.find((o) => o.long === "--json");
+      expect(jsonOpt).toBeDefined();
+    });
+  });
+});