@hashicorp/kits 0.1.0

package/dist/adapters/codex/installer.js

@@ -0,0 +1,229 @@
+/**
+ * Codex installation helpers.
+ *
+ * Provides utilities for installing primitives to Codex:
+ * - MCP server configuration in ~/.codex/mcp.json
+ * - Environment variable substitution
+ *
+ * Codex does not support subagents or hooks.
+ */
+import * as path from "node:path";
+import { expandPath, pathExists, readFile, writeTransformed, ensureDirectory, } from "../file-operations.js";
+import { CODEX_PATHS } from "./detection.js";
+/**
+ * Read the MCP configuration file.
+ */
+export async function readMcpConfig() {
+    const configPath = expandPath(CODEX_PATHS.mcp);
+    if (!pathExists(configPath)) {
+        return {};
+    }
+    try {
+        const content = await readFile(configPath);
+        return JSON.parse(content);
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Write the MCP configuration file.
+ */
+export async function writeMcpConfig(config) {
+    const configPath = expandPath(CODEX_PATHS.mcp);
+    const configDir = path.dirname(configPath);
+    await ensureDirectory(configDir);
+    await writeTransformed(configPath, JSON.stringify(config, null, 2));
+}
+/**
+ * Process environment variable values.
+ *
+ * Codex uses ${VAR} syntax for environment variable references.
+ */
+export function processEnvValue(value) {
+    return value;
+}
+/**
+ * Transform an MCP server configuration for Codex.
+ *
+ * Codex MCP configuration format:
+ * ```json
+ * {
+ *   "servers": {
+ *     "server-name": {
+ *       "command": "executable",
+ *       "args": ["arg1", "arg2"],
+ *       "env": {
+ *         "VAR": "${VAR}"
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * Note: Full environment variable transformation with sensitivity handling
+ * (env_vars array vs env table) is implemented in transformEnvVars (Phase 7).
+ * This function provides basic passthrough for all env vars using ${VAR} syntax.
+ */
+export function transformMcpServerConfig(config) {
+    // Only stdio transport is supported for Codex MCP servers
+    if (config.transport.type !== "stdio") {
+        throw new Error(`Unsupported transport type: ${config.transport.type}. Codex only supports stdio transport.`);
+    }
+    const entry = {
+        command: config.transport.command,
+    };
+    if (config.transport.args && config.transport.args.length > 0) {
+        entry.args = config.transport.args;
+    }
+    // Basic env var passthrough - full transformation in Phase 7
+    if (config.env && Object.keys(config.env).length > 0) {
+        entry.env = {};
+        for (const [key] of Object.entries(config.env)) {
+            // Use passthrough syntax for all env vars
+            entry.env[key] = `\${${key}}`;
+        }
+    }
+    return entry;
+}
+/**
+ * Transform resolved environment variables to Codex format.
+ *
+ * Codex uses two distinct mechanisms:
+ * - `env_vars` array: Variables passed through from shell environment (passthrough)
+ * - `env` table: Variables with direct values
+ *
+ * Rules (per FR-20.4):
+ * - usePassthrough: true → Add to env_vars array
+ * - usePassthrough: false (has value) → Add to env table
+ */
+export function transformEnvVars(resolved) {
+    const env_vars = [];
+    const env = {};
+    for (const r of resolved) {
+        if (r.usePassthrough) {
+            env_vars.push(r.name);
+        }
+        else if (r.value !== undefined) {
+            env[r.name] = r.value;
+        }
+    }
+    return { env_vars, env };
+}
+/**
+ * Transform resolved headers to Codex format.
+ *
+ * Codex uses specialized fields for HTTP authentication:
+ * - `bearer_token_env_var`: Environment variable containing bearer token (for Authorization headers)
+ * - `env_http_headers`: Table of additional headers with env var references
+ * - `http_headers`: Table of static header values
+ *
+ * Bearer Token Detection:
+ * The adapter detects bearer token patterns in Authorization headers:
+ * 1. Header name is "Authorization" (case-insensitive)
+ * 2. Header is marked sensitive: true
+ * 3. Uses envVar for the token value
+ *
+ * Rules (per FR-21.3):
+ * - Authorization + sensitive + envVar → bearer_token_env_var = "VAR"
+ * - Other headers with envVar → env_http_headers.Header = "$VAR"
+ * - Headers with static value → http_headers.Header = "value"
+ */
+export function transformHeaders(resolved) {
+    let bearer_token_env_var;
+    const env_http_headers = {};
+    const http_headers = {};
+    for (const r of resolved) {
+        // Check for Authorization header with bearer token pattern
+        if (r.name.toLowerCase() === "authorization" && r.sensitive && r.envVar) {
+            bearer_token_env_var = r.envVar;
+        }
+        else if (r.usePassthrough && r.envVar) {
+            env_http_headers[r.name] = `$${r.envVar}`;
+        }
+        else if (r.value !== undefined) {
+            http_headers[r.name] = r.value;
+        }
+    }
+    return { bearer_token_env_var, env_http_headers, http_headers };
+}
+/**
+ * Add an MCP server to the configuration.
+ *
+ * @param namespacedName - The namespaced server name (e.g., "kit.server")
+ * @param config - The MCP server configuration
+ */
+export async function addMcpServer(namespacedName, config) {
+    try {
+        const mcpConfig = await readMcpConfig();
+        if (!mcpConfig.servers) {
+            mcpConfig.servers = {};
+        }
+        mcpConfig.servers[namespacedName] = transformMcpServerConfig(config);
+        await writeMcpConfig(mcpConfig);
+        return {
+            operation: "merge",
+            destination: expandPath(CODEX_PATHS.mcp),
+            success: true,
+        };
+    }
+    catch (error) {
+        return {
+            operation: "merge",
+            destination: expandPath(CODEX_PATHS.mcp),
+            success: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/**
+ * Remove an MCP server from the configuration.
+ *
+ * @param namespacedName - The namespaced server name to remove
+ */
+export async function removeMcpServer(namespacedName) {
+    const mcpConfig = await readMcpConfig();
+    if (!mcpConfig.servers || !mcpConfig.servers[namespacedName]) {
+        return false;
+    }
+    delete mcpConfig.servers[namespacedName];
+    await writeMcpConfig(mcpConfig);
+    return true;
+}
+/**
+ * Get all installed MCP servers for a specific kit.
+ *
+ * @param kitName - The kit name prefix to filter by
+ */
+export async function getKitMcpServers(kitName) {
+    const mcpConfig = await readMcpConfig();
+    if (!mcpConfig.servers) {
+        return [];
+    }
+    const prefix = `${kitName}.`;
+    return Object.keys(mcpConfig.servers).filter((name) => name.startsWith(prefix));
+}
+/**
+ * Remove all MCP servers for a specific kit.
+ *
+ * @param kitName - The kit name prefix to remove
+ */
+export async function removeKitMcpServers(kitName) {
+    const mcpConfig = await readMcpConfig();
+    const removed = [];
+    if (!mcpConfig.servers) {
+        return removed;
+    }
+    const prefix = `${kitName}.`;
+    for (const name of Object.keys(mcpConfig.servers)) {
+        if (name.startsWith(prefix)) {
+            delete mcpConfig.servers[name];
+            removed.push(name);
+        }
+    }
+    if (removed.length > 0) {
+        await writeMcpConfig(mcpConfig);
+    }
+    return removed;
+}
+//# sourceMappingURL=installer.js.map

package/dist/adapters/codex/installer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"installer.js","sourceRoot":"","sources":["../../../src/adapters/codex/installer.ts"],"names":[],"mappings":"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"}

package/dist/adapters/codex/model-mapping.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Codex model mapping.
+ */
+import type { ModelMapping } from "../types.js";
+export declare const codexModelMapping: ModelMapping;
+export declare function getCodexModelMapping(): ModelMapping;
+//# sourceMappingURL=model-mapping.d.ts.map

package/dist/adapters/codex/model-mapping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-mapping.d.ts","sourceRoot":"","sources":["../../../src/adapters/codex/model-mapping.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,eAAO,MAAM,iBAAiB,EAAE,YAM/B,CAAC;AAEF,wBAAgB,oBAAoB,IAAI,YAAY,CAEnD"}

package/dist/adapters/codex/model-mapping.js

@@ -0,0 +1,14 @@
+/**
+ * Codex model mapping.
+ */
+export const codexModelMapping = {
+    fast: "gpt-5.1-codex-mini",
+    standard: "gpt-5.2-codex",
+    power: "gpt-5.1-codex-max",
+    auto: null,
+    inherit: null,
+};
+export function getCodexModelMapping() {
+    return codexModelMapping;
+}
+//# sourceMappingURL=model-mapping.js.map

package/dist/adapters/codex/model-mapping.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-mapping.js","sourceRoot":"","sources":["../../../src/adapters/codex/model-mapping.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,MAAM,CAAC,MAAM,iBAAiB,GAAiB;IAC7C,IAAI,EAAE,oBAAoB;IAC1B,QAAQ,EAAE,eAAe;IACzB,KAAK,EAAE,mBAAmB;IAC1B,IAAI,EAAE,IAAI;IACV,OAAO,EAAE,IAAI;CACd,CAAC;AAEF,MAAM,UAAU,oBAAoB;IAClC,OAAO,iBAAiB,CAAC;AAC3B,CAAC"}

package/dist/adapters/codex/tool-mapping.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Codex tool mapping.
+ *
+ * Maps canonical tool identifiers to Codex's native tool names.
+ * Codex has limited tool support compared to Claude Code.
+ */
+import type { ToolMapping } from "../types.js";
+/**
+ * Codex tool mapping.
+ *
+ * Codex uses snake_case naming for tools and has more limited
+ * tool support than Claude Code.
+ */
+export declare const codexToolMapping: ToolMapping;
+/**
+ * Get the Codex tool mapping.
+ */
+export declare function getCodexToolMapping(): ToolMapping;
+//# sourceMappingURL=tool-mapping.d.ts.map

package/dist/adapters/codex/tool-mapping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-mapping.d.ts","sourceRoot":"","sources":["../../../src/adapters/codex/tool-mapping.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,WAY9B,CAAC;AAEF;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,WAAW,CAEjD"}

package/dist/adapters/codex/tool-mapping.js

@@ -0,0 +1,32 @@
+/**
+ * Codex tool mapping.
+ *
+ * Maps canonical tool identifiers to Codex's native tool names.
+ * Codex has limited tool support compared to Claude Code.
+ */
+/**
+ * Codex tool mapping.
+ *
+ * Codex uses snake_case naming for tools and has more limited
+ * tool support than Claude Code.
+ */
+export const codexToolMapping = {
+    shell: "shell",
+    read: "read_file",
+    write: "write_file",
+    edit: "edit_file",
+    grep: "search",
+    glob: "find_files",
+    list: "list_directory",
+    webfetch: "web_fetch",
+    websearch: "web_search",
+    todo: "task_list",
+    ask: "ask_user",
+};
+/**
+ * Get the Codex tool mapping.
+ */
+export function getCodexToolMapping() {
+    return codexToolMapping;
+}
+//# sourceMappingURL=tool-mapping.js.map

package/dist/adapters/codex/tool-mapping.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-mapping.js","sourceRoot":"","sources":["../../../src/adapters/codex/tool-mapping.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAgB;IAC3C,KAAK,EAAE,OAAO;IACd,IAAI,EAAE,WAAW;IACjB,KAAK,EAAE,YAAY;IACnB,IAAI,EAAE,WAAW;IACjB,IAAI,EAAE,QAAQ;IACd,IAAI,EAAE,YAAY;IAClB,IAAI,EAAE,gBAAgB;IACtB,QAAQ,EAAE,WAAW;IACrB,SAAS,EAAE,YAAY;IACvB,IAAI,EAAE,WAAW;IACjB,GAAG,EAAE,UAAU;CAChB,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,mBAAmB;IACjC,OAAO,gBAAgB,CAAC;AAC1B,CAAC"}

package/dist/adapters/command-parser.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Command parsing utilities for canonical command format.
+ *
+ * Parses and validates commands in the canonical format:
+ *
+ * ```markdown
+ * ---
+ * description: Brief description (required)
+ * argumentHint: [OPTIONAL_ARGS] (optional)
+ * ---
+ *
+ * Command prompt content here.
+ * ```
+ */
+import type { CommandFrontmatter } from "./types.js";
+/**
+ * Error thrown when command parsing fails.
+ */
+export declare class CommandParseError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parse and validate command frontmatter from markdown content.
+ *
+ * Validates that the content has:
+ * - YAML frontmatter block (required)
+ * - `description` field in frontmatter (required)
+ * - Non-empty body content (required)
+ *
+ * @param content - Raw markdown content with frontmatter
+ * @returns Validated CommandFrontmatter
+ * @throws CommandParseError if validation fails
+ */
+export declare function parseCommandFrontmatter(content: string): CommandFrontmatter;
+/**
+ * Extract the body content from a command markdown file.
+ *
+ * Returns the content after the YAML frontmatter block.
+ * If no frontmatter is present, returns the entire content.
+ *
+ * @param content - Raw markdown content
+ * @returns Body content (trimmed)
+ */
+export declare function extractCommandBody(content: string): string;
+/**
+ * Strip a specific field from the YAML frontmatter.
+ *
+ * Returns the original content with the specified field removed from frontmatter.
+ * If the field doesn't exist or there's no frontmatter, returns content unchanged.
+ *
+ * @param content - Raw markdown content with frontmatter
+ * @param field - Field name to strip (e.g., "argumentHint")
+ * @returns Content with field removed from frontmatter
+ */
+export declare function stripFrontmatterField(content: string, field: string): string;
+/**
+ * Rename a frontmatter field within the YAML block.
+ *
+ * Returns content unchanged if the field is not present or no frontmatter exists.
+ */
+export declare function renameFrontmatterField(content: string, from: string, to: string): string;
+/**
+ * Validate command content without parsing.
+ *
+ * Checks that the content meets all canonical format requirements.
+ *
+ * @param content - Raw markdown content
+ * @returns true if valid
+ * @throws CommandParseError if validation fails
+ */
+export declare function validateCommandContent(content: string): boolean;
+//# sourceMappingURL=command-parser.d.ts.map

package/dist/adapters/command-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-parser.d.ts","sourceRoot":"","sources":["../../src/adapters/command-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI5B;AA6ED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,kBAAkB,CAwC3E;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAG1D;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CA6B5E;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,GACT,MAAM,CA6BR;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAI/D"}

package/dist/adapters/command-parser.js

@@ -0,0 +1,222 @@
+/**
+ * Command parsing utilities for canonical command format.
+ *
+ * Parses and validates commands in the canonical format:
+ *
+ * ```markdown
+ * ---
+ * description: Brief description (required)
+ * argumentHint: [OPTIONAL_ARGS] (optional)
+ * ---
+ *
+ * Command prompt content here.
+ * ```
+ */
+/**
+ * Error thrown when command parsing fails.
+ */
+export class CommandParseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CommandParseError";
+    }
+}
+/**
+ * Regex to match YAML frontmatter block.
+ * Matches content between --- delimiters at the start of the file.
+ */
+const FRONTMATTER_REGEX = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/;
+/**
+ * Regex to match a YAML key-value pair.
+ * Supports alphanumeric keys with hyphens and underscores.
+ */
+const YAML_KEY_VALUE_REGEX = /^([\w-]+):\s*(.*)$/;
+/**
+ * Parse raw frontmatter and body from markdown content.
+ *
+ * @param content - Raw markdown content
+ * @returns Object with frontmatter record, body string, and hasFrontmatter flag
+ */
+function parseRaw(content) {
+    const match = content.match(FRONTMATTER_REGEX);
+    if (!match || !match[1] || match[2] === undefined) {
+        return {
+            frontmatter: {},
+            body: content,
+            hasFrontmatter: false,
+        };
+    }
+    const frontmatterYaml = match[1];
+    const body = match[2];
+    // Parse YAML frontmatter
+    const frontmatter = {};
+    const lines = frontmatterYaml.split("\n");
+    for (const line of lines) {
+        const kvMatch = line.match(YAML_KEY_VALUE_REGEX);
+        if (kvMatch && kvMatch[1] && kvMatch[2] !== undefined) {
+            const key = kvMatch[1];
+            let value = kvMatch[2].trim();
+            // Handle quoted strings
+            if (typeof value === "string" && value.startsWith('"') && value.endsWith('"')) {
+                value = value.slice(1, -1);
+            }
+            else if (typeof value === "string" && value.startsWith("'") && value.endsWith("'")) {
+                value = value.slice(1, -1);
+            }
+            else if (value === "true") {
+                value = true;
+            }
+            else if (value === "false") {
+                value = false;
+            }
+            else if (typeof value === "string" && value !== "" && !isNaN(Number(value))) {
+                value = Number(value);
+            }
+            frontmatter[key] = value;
+        }
+    }
+    return {
+        frontmatter,
+        body,
+        hasFrontmatter: true,
+    };
+}
+/**
+ * Parse and validate command frontmatter from markdown content.
+ *
+ * Validates that the content has:
+ * - YAML frontmatter block (required)
+ * - `description` field in frontmatter (required)
+ * - Non-empty body content (required)
+ *
+ * @param content - Raw markdown content with frontmatter
+ * @returns Validated CommandFrontmatter
+ * @throws CommandParseError if validation fails
+ */
+export function parseCommandFrontmatter(content) {
+    const { frontmatter, body, hasFrontmatter } = parseRaw(content);
+    // Validate frontmatter exists
+    if (!hasFrontmatter) {
+        throw new CommandParseError("command missing YAML frontmatter; expected ---\\n...\\n--- at start of file");
+    }
+    // Validate description exists and is non-empty
+    const description = frontmatter["description"];
+    if (description === undefined || description === null) {
+        throw new CommandParseError("command missing required 'description' field in frontmatter");
+    }
+    if (typeof description !== "string") {
+        throw new CommandParseError(`command 'description' must be a string; got ${typeof description}`);
+    }
+    if (description.trim() === "") {
+        throw new CommandParseError("command 'description' field cannot be empty");
+    }
+    // Validate body exists and is non-empty
+    if (body.trim() === "") {
+        throw new CommandParseError("command body cannot be empty; content after frontmatter is required");
+    }
+    // Extract argumentHint (camelCase in YAML)
+    const argumentHint = frontmatter["argumentHint"];
+    const result = {
+        description: description.trim(),
+    };
+    if (argumentHint !== undefined && argumentHint !== null) {
+        if (typeof argumentHint !== "string") {
+            throw new CommandParseError(`command 'argumentHint' must be a string; got ${typeof argumentHint}`);
+        }
+        result.argumentHint = argumentHint.trim();
+    }
+    return result;
+}
+/**
+ * Extract the body content from a command markdown file.
+ *
+ * Returns the content after the YAML frontmatter block.
+ * If no frontmatter is present, returns the entire content.
+ *
+ * @param content - Raw markdown content
+ * @returns Body content (trimmed)
+ */
+export function extractCommandBody(content) {
+    const { body } = parseRaw(content);
+    return body.trim();
+}
+/**
+ * Strip a specific field from the YAML frontmatter.
+ *
+ * Returns the original content with the specified field removed from frontmatter.
+ * If the field doesn't exist or there's no frontmatter, returns content unchanged.
+ *
+ * @param content - Raw markdown content with frontmatter
+ * @param field - Field name to strip (e.g., "argumentHint")
+ * @returns Content with field removed from frontmatter
+ */
+export function stripFrontmatterField(content, field) {
+    const match = content.match(FRONTMATTER_REGEX);
+    if (!match || !match[1] || match[2] === undefined) {
+        // No frontmatter, return unchanged
+        return content;
+    }
+    const frontmatterYaml = match[1];
+    const body = match[2];
+    // Filter out lines that match the field
+    const lines = frontmatterYaml.split("\n");
+    const filteredLines = lines.filter((line) => {
+        const kvMatch = line.match(YAML_KEY_VALUE_REGEX);
+        if (kvMatch && kvMatch[1]) {
+            return kvMatch[1] !== field;
+        }
+        return true;
+    });
+    // If no lines changed, return original
+    if (filteredLines.length === lines.length) {
+        return content;
+    }
+    // Reconstruct the content
+    const newFrontmatter = filteredLines.join("\n");
+    return `---\n${newFrontmatter}\n---\n${body}`;
+}
+/**
+ * Rename a frontmatter field within the YAML block.
+ *
+ * Returns content unchanged if the field is not present or no frontmatter exists.
+ */
+export function renameFrontmatterField(content, from, to) {
+    const match = content.match(FRONTMATTER_REGEX);
+    if (!match || !match[1] || match[2] === undefined) {
+        return content;
+    }
+    const frontmatterYaml = match[1];
+    const body = match[2];
+    let changed = false;
+    const lines = frontmatterYaml.split("\n");
+    const renamedLines = lines.map((line) => {
+        const kvMatch = line.match(YAML_KEY_VALUE_REGEX);
+        if (kvMatch && kvMatch[1] && kvMatch[2] !== undefined) {
+            if (kvMatch[1] === from) {
+                changed = true;
+                return `${to}: ${kvMatch[2]}`;
+            }
+        }
+        return line;
+    });
+    if (!changed) {
+        return content;
+    }
+    const newFrontmatter = renamedLines.join("\n");
+    return `---\n${newFrontmatter}\n---\n${body}`;
+}
+/**
+ * Validate command content without parsing.
+ *
+ * Checks that the content meets all canonical format requirements.
+ *
+ * @param content - Raw markdown content
+ * @returns true if valid
+ * @throws CommandParseError if validation fails
+ */
+export function validateCommandContent(content) {
+    // parseCommandFrontmatter performs all validation
+    parseCommandFrontmatter(content);
+    return true;
+}
+//# sourceMappingURL=command-parser.js.map

package/dist/adapters/command-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-parser.js","sourceRoot":"","sources":["../../src/adapters/command-parser.ts"],"names":[],"mappings":"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"}