@alcyone-labs/arg-parser 2.5.0 → 2.7.0

package/README.md

@@ -27,6 +27,7 @@ A modern, type-safe command line argument parser with built-in MCP (Model Contex
     - [Async Custom Parser Support](#async-custom-parser-support)
     - [Zod Schema Flags (Structured JSON Validation)](#zod-schema-flags-structured-json-validation)
     - [Type Conversion Examples](#type-conversion-examples)
+  - [DXT Package User Configuration & Path Handling](#dxt-package-user-configuration--path-handling)
   - [Hierarchical CLIs (Sub-Commands)](#hierarchical-clis-sub-commands)
     - [MCP Exposure Control](#mcp-exposure-control)
   - [Flag Inheritance (`inheritParentFlags`)](#flag-inheritance-inheritparentflags)
@@ -44,6 +45,9 @@ A modern, type-safe command line argument parser with built-in MCP (Model Contex
     - [Common Pitfalls to Avoid](#common-pitfalls-to-avoid)
   - [Automatic MCP Server Mode (`--s-mcp-serve`)](#automatic-mcp-server-mode---s-mcp-serve)
   - [MCP Transports](#mcp-transports)
+    - [Adding custom HTTP routes (e.g., /health)](#adding-custom-http-routes-eg-health)
+    - [CORS and Authentication for streamable-http](#cors-and-authentication-for-streamable-http)
+    - [Multiple transports and improved logging](#multiple-transports-and-improved-logging)
   - [MCP Logging Configuration](#mcp-logging-configuration)
     - [Enhanced Logging (Recommended)](#enhanced-logging-recommended)
     - [Simple Logging Configuration](#simple-logging-configuration)
@@ -70,6 +74,8 @@ A modern, type-safe command line argument parser with built-in MCP (Model Contex
   - [Typical Errors](#typical-errors)
 - [System Flags & Configuration](#system-flags--configuration)
 - [Changelog](#changelog)
+  - [v2.7.0](#v270)
+  - [v2.6.0](#v260)
   - [v2.5.0](#v250)
   - [v2.4.2](#v242)
   - [v2.4.1](#v241)
@@ -86,70 +92,6 @@ A modern, type-safe command line argument parser with built-in MCP (Model Contex
 - [Backlog](#backlog)
   - [(known) Bugs / DX improvement points](#known-bugs--dx-improvement-points)
 
-- [Features Overview](#features-overview)
-- [Installation](#installation)
-- [Quick Start: The Unified `addTool` API](#quick-start-the-unified-addtool-api)
-- [How to Run It](#how-to-run-it)
-  - [Setting Up System-Wide CLI Access](#setting-up-system-wide-cli-access)
-- [Parsing Command-Line Arguments](#parsing-command-line-arguments)
-  - [Automatic Argument Detection](#automatic-argument-detection)
-  - [Cannonical Usage Pattern](#cannonical-usage-pattern)
-  - [Top-level await](#top-level-await)
-  - [Promise-based parsing](#promise-based-parsing)
-- [Migrating from v1.x to the v2.0 `addTool` API](#migrating-from-v1x-to-the-v20-addtool-api)
-  - [Before v2.0: Separate Definitions](#before-v20-separate-definitions)
-  - [After v2.0: The Unified `addTool()` Method](#after-v20-the-unified-addtool-method)
-- [Core Concepts](#core-concepts)
-  - [Defining Flags](#defining-flags)
-  - [Type Handling and Validation](#type-handling-and-validation)
-    - [Supported Type Formats](#supported-type-formats)
-    - [Runtime Type Validation](#runtime-type-validation)
-    - [Automatic Type Processing](#automatic-type-processing)
-    - [Async Custom Parser Support](#async-custom-parser-support)
-    - [Zod Schema Flags (Structured JSON Validation)](#zod-schema-flags-structured-json-validation)
-    - [Type Conversion Examples](#type-conversion-examples)
-  - [Hierarchical CLIs (Sub-Commands)](#hierarchical-clis-sub-commands)
-    - [MCP Exposure Control](#mcp-exposure-control)
-  - [Flag Inheritance (`inheritParentFlags`)](#flag-inheritance-inheritparentflags)
-- [MCP & Claude Desktop Integration](#mcp--claude-desktop-integration)
-  - [Output Schema Support](#output-schema-support)
-    - [Basic Usage](#basic-usage)
-    - [Predefined Schema Patterns](#predefined-schema-patterns)
-    - [Custom Zod Schemas](#custom-zod-schemas)
-    - [MCP Version Compatibility](#mcp-version-compatibility)
-    - [Automatic Error Handling](#automatic-error-handling)
-  - [Writing Effective MCP Tool Descriptions](#writing-effective-mcp-tool-descriptions)
-    - [Best Practices for Tool Descriptions](#best-practices-for-tool-descriptions)
-    - [Complete Example: Well-Documented Tool](#complete-example-well-documented-tool)
-    - [Parameter Description Guidelines](#parameter-description-guidelines)
-    - [Common Pitfalls to Avoid](#common-pitfalls-to-avoid)
-  - [Automatic MCP Server Mode (`--s-mcp-serve`)](#automatic-mcp-server-mode---s-mcp-serve)
-  - [MCP Transports](#mcp-transports)
-  - [MCP Log Path Configuration](#mcp-log-path-configuration)
-  - [MCP Resources - Real-Time Data Feeds](#mcp-resources---real-time-data-feeds) ⭐
-  - [Automatic Console Safety](#automatic-console-safety)
-  - [Generating DXT Packages (`--s-build-dxt`)](#generating-dxt-packages---s-build-dxt)
-  - [Logo Configuration](#logo-configuration)
-    - [Supported Logo Sources](#supported-logo-sources)
-  - [How DXT Generation Works](#how-dxt-generation-works)
-  - [DXT Bundling Strategies](#dxt-bundling-strategies)
-    - [Standard Approach (Recommended for Most Projects)](#standard-approach-recommended-for-most-projects)
-    - [Native Dependencies Approach](#native-dependencies-approach)
-- [Typical Errors](#typical-errors)
-- [System Flags & Configuration](#system-flags--configuration)
-- [Changelog](#changelog)
-  - [v2.3.0](#v230)
-  - [v2.2.1](#v221)
-  - [v2.2.0](#v220)
-  - [v2.1.1](#v211)
-  - [v2.1.0](#v210)
-  - [v2.0.0](#v200)
-  - [v1.3.0](#v130)
-  - [v1.2.0](#v120)
-  - [v1.1.0](#v110)
-- [Backlog](#backlog)
-  - [(known) Bugs / DX improvement points](#known-bugs--dx-improvement-points)
-
 ## Features Overview
 
 - **Unified Tool Architecture**: Define tools once with `addTool()` and they automatically function as both CLI subcommands and MCP tools.
@@ -399,9 +341,9 @@ yarn unlink
 
 ArgParser's `parse()` method is async and automatically handles both synchronous and asynchronous handlers:
 
-### Automatic Argument Detection
+### Auto-Execution versus Import: No More Boilerplate
 
-`parse()` can now be called without arguments for improved developer experience:
+ArgParser now provides auto-execution ability that eliminates the need for boilerplate code to check if your script is being run directly vs. imported. This enables use cases such as programmatically loading the CLI and scanning for tools or testing it from another script via the --s-enable-fuzzy flag or your own script.
 
 ```typescript
 const cli = ArgParser.withMcp({
@@ -410,32 +352,27 @@ const cli = ArgParser.withMcp({
   handler: async (ctx) => ({ success: true, data: ctx.args }),
 });
 
-// You can call parse() without arguments
-// Automatically detects Node.js environment and uses process.argv.slice(2)
-async function main() {
-  try {
-    const result = await cli.parse(); // No arguments needed!
-    console.log("Success:", result);
-  } catch (error) {
-    console.error("Error:", error.message);
-    process.exit(1);
-  }
-}
-```
+// Now, this will NOT automatically execute the parser if the script is imported, but will execute if called directly:
+await cli.parse(undefined, {
+  importMetaUrl: import.meta.url
+}).catch(handleError);
 
-**How it works:**
 
-- ✅ **Auto-detection**: When `parse()` is called without arguments, ArgParser automatically detects if it's running in Node.js
-- ✅ **Smart fallback**: Uses `process.argv.slice(2)` automatically in Node.js environments
-- ✅ **User-friendly warning**: Shows a helpful warning in CLI mode to inform users about the behavior
-- ✅ **Error handling**: Throws a clear error in non-Node.js environments when arguments are required
-- ✅ **Backward compatible**: Explicit arguments still work exactly as before
+// Or, using the manual APIs:
+await cli.parseIfExecutedDirectly(import.meta.url).catch((error) => {
+  console.error("Fatal error:", error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});
+```
 
-**When warnings are shown:**
+**Replaces previously confusing patterns:**
 
-- ✅ CLI mode (when `appCommandName` is set)
-- ❌ Library/programmatic usage (no `appCommandName`)
-- ❌ MCP mode (warnings suppressed for clean MCP output)
+```typescript
+// Brittle and breaks in sandboxes
+if (import.meta.url === `file://${process.argv[1]}`) {
+  await cli.parse().catch(handleError);
+}
+```
 
 ### Cannonical Usage Pattern
 
@@ -609,7 +546,14 @@ Flags are defined using the `IFlag` interface within the `flags` array of a tool
 interface IFlag {
   name: string; // Internal name (e.g., 'verbose')
   options: string[]; // Command-line options (e.g., ['--verbose', '-v'])
-  type: "string" | "number" | "boolean" | "array" | "object" | Function | ZodSchema;
+  type:
+    | "string"
+    | "number"
+    | "boolean"
+    | "array"
+    | "object"
+    | Function
+    | ZodSchema;
   description?: string; // Help text
   mandatory?: boolean | ((args: any) => boolean); // Whether the flag is required
   defaultValue?: any; // Default value if not provided
@@ -618,9 +562,153 @@ interface IFlag {
   validate?: (value: any, parsedArgs?: any) => boolean | string | void; // Custom validation function
   allowMultiple?: boolean; // Allow the flag to be provided multiple times
   env?: string; // Links the flag to an environment variable for DXT packages, will automatically generate user_config entries in the DXT manifest and fill the flag value to the ENV value if found (process.env)
+  dxtOptions?: DxtOptions; // Customizes how this flag appears in DXT package user_config
+}
+
+interface DxtOptions {
+  type?: "string" | "directory" | "file" | "boolean" | "number"; // UI input type in Claude Desktop
+  title?: string; // Display name in Claude Desktop (defaults to formatted flag name)
+  sensitive?: boolean; // Whether to hide the value in UI (defaults to true for security)
+  default?: any; // Default value for the user_config entry
+  min?: number; // Minimum value (for number types)
+  max?: number; // Maximum value (for number types)
+}
+```
+
+### DXT Package User Configuration & Path Handling
+
+ArgParser v2.5.0 introduces comprehensive DXT (Desktop Extension Toolkit) support with rich user interfaces, automatic path resolution, and context-aware development tools.
+
+#### Enhanced dxtOptions
+
+When generating DXT packages with `--s-build-dxt`, you can create rich user configuration interfaces using `dxtOptions`:
+
+```typescript
+import { ArgParser, DxtPathResolver } from "@alcyone-labs/arg-parser";
+
+const parser = new ArgParser()
+  .withMcp({
+    name: "file-processor",
+    version: "1.0.0",
+    logPath: "${HOME}/logs/file-processor.log", // DXT variables supported!
+  })
+  .addFlag({
+    name: "input-file",
+    description: "File to process",
+    type: "string",
+    mandatory: true,
+    dxtOptions: {
+      type: "file",
+      title: "Select Input File",
+    },
+  })
+  .addFlag({
+    name: "output-dir",
+    description: "Output directory for processed files",
+    type: "string",
+    dxtOptions: {
+      type: "directory",
+      localDefault: "${DOCUMENTS}/processed-files", // Smart defaults with DXT variables
+      title: "Output Directory",
+    },
+  })
+  .addFlag({
+    name: "api-key",
+    description: "API authentication key",
+    type: "string",
+    env: "API_KEY",
+    dxtOptions: {
+      type: "string",
+      sensitive: true, // Excluded from DXT manifest for security
+      title: "API Key",
+    },
+  })
+  .addFlag({
+    name: "quality",
+    description: "Processing quality (1-100)",
+    type: "number",
+    dxtOptions: {
+      type: "number",
+      min: 1,
+      max: 100,
+      localDefault: 85,
+      title: "Quality (%)",
+    },
+  })
+  .addFlag({
+    name: "parallel",
+    description: "Enable parallel processing",
+    type: "boolean",
+    dxtOptions: {
+      type: "boolean",
+      localDefault: true,
+      title: "Parallel Processing",
+    },
+  });
+```
+
+#### DXT Variables & Path Resolution
+
+ArgParser automatically resolves paths based on your runtime environment:
+
+```typescript
+// DXT variables work everywhere - in flags, MCP config, and code
+const logPath = "${HOME}/logs/app.log";
+const configPath = "${DOCUMENTS}/myapp/config.json";
+const resourcePath = "${__dirname}/templates/default.hbs";
+
+// Helper functions for common patterns
+const userDataPath = DxtPathResolver.createUserDataPath("cache.db");
+const tempPath = DxtPathResolver.createTempPath("processing.tmp");
+const configPath = DxtPathResolver.createConfigPath("settings.json");
+
+// Context detection
+const context = DxtPathResolver.detectContext();
+if (context.isDxt) {
+  console.log("Running in DXT environment");
+} else {
+  console.log("Running in development");
 }
 ```
 
+**Supported DXT Variables:**
+
+- `${HOME}` - User's home directory
+- `${DOCUMENTS}` - Documents folder
+- `${DOWNLOADS}` - Downloads folder
+- `${DESKTOP}` - Desktop folder
+- `${__dirname}` - Entry point directory (DXT package root in DXT)
+- `${pathSeparator}` - Platform-specific path separator
+- `${DXT_DIR}` - DXT package directory (DXT only)
+- `${EXTENSION_DIR}` - Extension root directory (DXT only)
+
+#### dxtOptions Properties
+
+| Property       | Type                                                         | Description                                      |
+| -------------- | ------------------------------------------------------------ | ------------------------------------------------ |
+| `type`         | `'string' \| 'file' \| 'directory' \| 'boolean' \| 'number'` | UI component type                                |
+| `sensitive`    | `boolean`                                                    | Mark as sensitive (excluded from manifest)       |
+| `localDefault` | `string \| number \| boolean`                                | Default for development (supports DXT variables) |
+| `multiple`     | `boolean`                                                    | Allow multiple values                            |
+| `min` / `max`  | `number`                                                     | Validation constraints                           |
+| `title`        | `string`                                                     | Custom display name                              |
+
+#### Security & Best Practices
+
+- **Sensitive Data**: Use `sensitive: true` for passwords, API keys, tokens
+- **Smart Defaults**: Use DXT variables in `localDefault` for portable paths
+- **Type Safety**: Match `dxtOptions.type` with flag `type` for validation
+- **Cross-Platform**: Use `${pathSeparator}` for platform-independent paths
+
+#### Comprehensive Documentation
+
+For detailed guides and examples:
+
+- **[DXT Path Handling Guide](./docs/DXT_PATH_HANDLING.md)** - Complete path resolution guide
+- **[dxtOptions API Documentation](./docs/DXT_OPTIONS_API.md)** - Full API reference with examples
+- **[DXT Migration Guide](./docs/DXT_MIGRATION.md)** - Migrate existing applications
+- **[DXT Practical Examples](./docs/DXT_EXAMPLES.md)** - Real-world usage patterns
+
 ### Type Handling and Validation
 
 ArgParser provides **strong typing** for flag definitions with comprehensive validation at both compile-time and runtime. The `type` property accepts multiple formats and ensures type safety throughout your application.
@@ -1207,6 +1295,14 @@ my-tool --s-mcp-serve --s-mcp-transports '[{"type":"stdio"},{"type":"sse","port"
 # Single transport with custom options
 my-tool --s-mcp-serve --s-mcp-transport sse --s-mcp-port 3000 --s-mcp-host 0.0.0.0
 
+# Streamable HTTP CORS/auth via CLI flags (JSON strings)
+my-tool --s-mcp-serve \
+  --s-mcp-transport streamable-http \
+  --s-mcp-port 3002 --s-mcp-path /api/mcp \
+  --s-mcp-cors '{"origins":["http://localhost:5173"],"credentials":true,"methods":["GET","POST","OPTIONS"],"maxAge":600}' \
+  --s-mcp-auth '{"required":true,"scheme":"jwt","jwt":{"algorithms":["HS256"],"secret":"$MY_JWT_SECRET"},"publicPaths":["/health"]}'
+
+
 # Custom log path via CLI flag (logs to specified file instead of ./logs/mcp.log)
 my-tool --s-mcp-serve --s-mcp-log-path /var/log/my-mcp-server.log
 
@@ -1214,6 +1310,130 @@ my-tool --s-mcp-serve --s-mcp-log-path /var/log/my-mcp-server.log
 const parser = ArgParser.withMcp({
   mcp: {
     serverInfo: { name: 'my-tool', version: '1.0.0' },
+
+```
+
+### CORS and Authentication for streamable-http
+
+CORS is often required when connecting a Web UI to an MCP server over HTTP.
+
+- Programmatic transport config:
+
+```ts
+import type { McpTransportConfig } from "@alcyone-labs/arg-parser";
+
+const defaultTransports: McpTransportConfig[] = [{
+  type: "streamable-http",
+  port: 3002,
+  path: "/api/mcp",
+  cors: {
+    origins: ["http://localhost:5173", /^https?:\/\/example\.com$/],
+    methods: ["GET","POST","OPTIONS"],
+    headers: ["Content-Type","Authorization","MCP-Session-Id"],
+    exposedHeaders: ["MCP-Session-Id"],
+    credentials: true,
+    maxAge: 600,
+  },
+  auth: {
+    required: true,
+    scheme: "jwt", // or "bearer"
+    // Bearer allowlist:
+    // allowedTokens: ["token1","token2"],
+    // JWT verification (HS256):
+    // jwt: { algorithms: ["HS256"], secret: process.env.JWT_SECRET },
+    // JWT verification (RS256 with static public key):
+    // jwt: { algorithms: ["RS256"], publicKey: process.env.RS256_PUBLIC_KEY },
+    // JWT verification (RS256 with dynamic JWKS):
+    // jwt: { algorithms: ["RS256"], getPublicKey: async (header)=>{ /* fetch JWKS and return PEM */ } },
+    publicPaths: ["/health"],
+    protectedPaths: undefined, // if set, only listed paths require auth
+    // Optional custom validator to add extra checks
+    validator: async (req, token) => true,
+  },
+}];
+```
+
+- CLI flags (JSON strings):
+
+```bash
+my-tool --s-mcp-serve \
+  --s-mcp-transport streamable-http \
+  --s-mcp-port 3002 --s-mcp-path /api/mcp \
+  --s-mcp-cors '{"origins":["http://localhost:5173"],"credentials":true,"methods":["GET","POST","OPTIONS"],"maxAge":600}' \
+  --s-mcp-auth '{"required":true,"scheme":"jwt","jwt":{"algorithms":["HS256"],"secret":"'$JWT_SECRET'"},"publicPaths":["/health"]}'
+```
+
+- Express hook for custom routes:
+
+```ts
+httpServer: {
+  configureExpress: (app) => {
+    app.get("/health", (_req, res) => res.json({ ok: true }));
+  },
+}
+```
+
+See examples:
+- examples/streamable-http/secure-mcp.ts (HS256)
+- examples/streamable-http/rs256-mcp.ts (RS256)
+- examples/streamable-http/jwks-mcp.ts (JWKS)
+- examples/streamable-http/bearer-mcp.ts (Bearer)
+- examples/streamable-http/productized-mcp.ts (token + session usage)
+
+#### TypeScript types
+
+- CorsOptions
+
+```ts
+export type CorsOptions = {
+  origins?: "*" | string | RegExp | Array<string | RegExp>;
+  methods?: string[];
+  headers?: string[];
+  exposedHeaders?: string[];
+  credentials?: boolean;
+  maxAge?: number;
+};
+```
+
+- AuthOptions and JwtVerifyOptions
+
+```ts
+export type JwtVerifyOptions = {
+  algorithms?: ("HS256" | "RS256")[];
+  secret?: string;        // HS256
+  publicKey?: string;     // RS256 static
+  getPublicKey?: (header: Record<string, unknown>, payload: Record<string, unknown>) => Promise<string> | string; // RS256 dynamic
+  audience?: string | string[];
+  issuer?: string | string[];
+  clockToleranceSec?: number;
+};
+
+export type AuthOptions = {
+  required?: boolean; // default true for MCP endpoint
+  scheme?: "bearer" | "jwt";
+  allowedTokens?: string[]; // simple bearer allowlist
+  validator?: (req: any, token: string | undefined) => boolean | Promise<boolean>;
+  jwt?: JwtVerifyOptions;
+  publicPaths?: string[];     // paths that skip auth
+  protectedPaths?: string[];  // if provided, only these paths require auth
+  customMiddleware?: (req: any, res: any, next: any) => any; // full control hook
+};
+```
+
+- HttpServerOptions
+
+```ts
+export type HttpServerOptions = {
+  configureExpress?: (app: any) => void;
+};
+```
+
+Notes:
+- When credentials are true, Access-Control-Allow-Origin echoes the request Origin rather than using "*".
+- You can manage CORS for non-MCP routes in configureExpress.
+- Use publicPaths to allow some routes without auth; use protectedPaths to only require auth for certain routes.
+
+
     log: {
       level: 'debug',       // Capture all log levels
       logToFile: '/var/log/my-mcp-server.log',
@@ -1221,9 +1441,28 @@ const parser = ArgParser.withMcp({
     }
     // LEGACY: logPath: '/var/log/my-mcp-server.log'  // Still works
   }
+
+### Adding custom HTTP routes (e.g., /health)
+
+Use the httpServer.configureExpress(app) hook to register routes before MCP endpoints are bound. Example:
+
+```ts
+const cli = ArgParser.withMcp({
+  mcp: {
+    serverInfo: { name: "my-mcp", version: "1.0.0" },
+    defaultTransports: [
+      { type: "streamable-http", port: 3002, path: "/api/mcp", auth: { required: true, publicPaths: ["/health"] } }
+    ],
+    httpServer: { configureExpress: (app) => app.get("/health", (_req, res) => res.json({ ok: true })) },
+  }
 });
+```
+
+- To make a route public (no auth), add it to auth.publicPaths.
+- CORS headers for non-MCP paths can be applied by your own middleware inside the hook if desired.
+
+### Multiple transports and improved logging
 
-# Multiple transports and improved logging (configured via --s-mcp-serve system flag)
 const cli = ArgParser.withMcp({
   appName: 'multi-tool',
   appCommandName: 'multi-tool',
@@ -1407,9 +1646,9 @@ const cli = ArgParser.withMcp({
         ctx.logger.mcpError(`Shutting down: ${ctx.reason}`);
         await cleanupResources();
         await closeDatabase();
-      }
-    }
-  }
+      },
+    },
+  },
 });
 ```
 
@@ -1422,6 +1661,7 @@ const cli = ArgParser.withMcp({
 **Context Properties:**
 
 Each lifecycle event receives a context object with:
+
 - `getFlag(name)`: Access parsed CLI flags and environment variables
 - `logger`: MCP-compliant logger instance for the current context
 - `serverInfo`: Server information (name, version, description)
@@ -1824,6 +2064,47 @@ ArgParser includes built-in `--s-*` flags for development, debugging, and config
 
 ## Changelog
 
+### v2.7.0
+
+**Feat**
+
+**MCP**:
+
+- Add support for CORS and authentication options, enabling powerful tools to serve Web UIs and publicly exposed APIs
+- Add supports for configuring express by exposing the app before it runs
+
+**CLI**:
+
+- Add support for NOT automatically executing the CLI if the script is imported, but will execute if called directly as a CLI. This enables use cases such as programmatically loading the CLI and scanning for tools or testing it from another script via the --s-enable-fuzzy flag or your own script.
+
+### v2.6.0
+
+**Feat**
+
+**DXT**:
+
+- Improve how paths and dynamic variables are handled when bundling into a DXT, to improve compatibility and reduce paths that will fail in a sandbox when the CLI / MCP expects path available on the system. Dynamic path resolution with `${VARIABLE}` syntax supporting `${HOME}`, `${DOCUMENTS}`, `${__dirname}`, `${DXT_DIR}`, and more. Context-aware path resolution with `DxtPathResolver.createUserDataPath()`, `createTempPath()`, `createConfigPath()`.
+- Add new IFlag.dxtOption set of options for each flag to allow finer control on how the flags are perceived on the DXT manifest / Claude Desktop.
+
+Read more her: [DXT Package User Configuration & Path Handling](#dxt-package-user-configuration--path-handling)
+
+**Fixes and Changes**
+
+**DXT**:
+
+- Improve handling of sensitive env variable, they were previously always showing as sensitive.
+
+**Known Limitations**
+
+**DXT**:
+
+The DXT bundling / packing / unpacking / launching process is notoriously early and brittle. There are many reasons something is not working, but **MOST** importantly it will not work if:
+
+1. You are bundling a package in a mono-repo (you will need to temporarily create a pnpm-workspace.yaml file for example to break the hierarchy)
+2. You do _not_ hard-install your node_modules as detailed in the documentation (it will only work if the node_modules are hard installed)
+3. In some cases if your CLI entrypoint does not run a main loop (see documentation for working examples)
+4. If you use PATH-dependent variables (for example relying on ~/.config/path/to/some.json). This has been addressed in v2.6.0, but you have to make sure you use the correct patterns (see documentation)
+
 ### v2.5.0
 
 **Feat**
@@ -1852,7 +2133,7 @@ ArgParser includes built-in `--s-*` flags for development, debugging, and config
 - MCP client now sanitizes the method names to ensure spec-compliants MCP behavior, names that collision will be logged
 - There were some use-cases where the DXT bundling failed, this new release addresses all of them, namely:
   1. Output structure will match that of the input so relative files (for example DB migrations) will work
-  2.
+  2. Deeper folder structure was previously not working
 - DXT bundling now supports including resources via options: `{dxt: {include: ['TSDown blob-like paths']}`
 - Logger was improved to support log level via `options:{ log: {} }` so you can set it to level: 'debug' and the MCP log will contain 100% of the console output, logPath setting was not impacted
 
@@ -1946,8 +2227,8 @@ Make sure to clearly identify if you need to include the node_modules or not. In
 - [x] Upgrade to Zod/V4 (V4 does not support functions well, this will take more time, not a priority)
 - [ ] Add System flags to args.systemArgs
 - [ ] Improve flag options collision prevention
-- [ ] Add support for locales / translations
 - [ ] (potentially) add support for fully typed parsed output, this has proven very challenging
+- [ ] Add support for locales / translations
 
 ### (known) Bugs / DX improvement points