@nimrobo/mcporter-remote 0.1.0

package/src/cli/call-command.ts

@@ -0,0 +1,478 @@
+import { analyzeConnectionError, type ConnectionIssue } from '../error-classifier.js';
+import { wrapCallResult } from '../result-utils.js';
+import { type CallArgsParseResult, parseCallArguments } from './call-arguments.js';
+import { prepareEphemeralServerTarget } from './ephemeral-target.js';
+import { looksLikeHttpUrl, normalizeHttpUrlCandidate } from './http-utils.js';
+import type { IdentifierResolution } from './identifier-helpers.js';
+import {
+  chooseClosestIdentifier,
+  normalizeIdentifier,
+  renderIdentifierResolutionMessages,
+} from './identifier-helpers.js';
+import { saveCallImagesIfRequested } from './image-output.js';
+import { buildConnectionIssueEnvelope } from './json-output.js';
+import { handleList } from './list-command.js';
+import type { OutputFormat } from './output-utils.js';
+import { printCallOutput, tailLogIfRequested } from './output-utils.js';
+import { dumpActiveHandles } from './runtime-debug.js';
+import { dimText, redText, yellowText } from './terminal.js';
+import { resolveCallTimeout, withTimeout } from './timeouts.js';
+import { loadToolMetadata } from './tool-cache.js';
+
+type Runtime = Awaited<ReturnType<typeof import('../runtime.js')['createRuntime']>>;
+
+interface ResolvedCallTarget {
+  server: string;
+  tool: string;
+}
+
+interface PreparedCallRequest extends ResolvedCallTarget {
+  parsed: CallArgsParseResult;
+  hydratedArgs: Record<string, unknown>;
+  timeoutMs: number;
+}
+
+export async function handleCall(runtime: Runtime, args: string[]): Promise<void> {
+  const prepared = await prepareCallRequest(runtime, args);
+  if (!prepared) {
+    return;
+  }
+
+  const invocation = await invokePreparedCall(runtime, prepared);
+  if (!invocation) {
+    return;
+  }
+
+  renderCallResult(invocation.result, prepared.parsed);
+}
+
+async function prepareCallRequest(runtime: Runtime, args: string[]): Promise<PreparedCallRequest | undefined> {
+  const parsed = parseCallArguments(args);
+  await normalizeParsedCallArguments(runtime, parsed);
+  const { server, tool } = await resolveServerAndTool(runtime, parsed);
+
+  if (await maybeDescribeServer(runtime, server, tool, parsed.output)) {
+    return undefined;
+  }
+
+  const timeoutMs = resolveCallTimeout(parsed.timeoutMs);
+  const hydratedArgs = await hydratePositionalArguments(runtime, server, tool, parsed.args, parsed.positionalArgs);
+  return { parsed, server, tool, hydratedArgs, timeoutMs };
+}
+
+async function normalizeParsedCallArguments(runtime: Runtime, parsed: CallArgsParseResult): Promise<void> {
+  let ephemeralSpec = parsed.ephemeral ? { ...parsed.ephemeral } : undefined;
+  const nameHints: string[] = [];
+  const absorbUrlCandidate = (value: string | undefined): string | undefined => {
+    if (!value) {
+      return value;
+    }
+    const normalized = normalizeHttpUrlCandidate(value);
+    if (!normalized) {
+      return value;
+    }
+    if (!ephemeralSpec) {
+      ephemeralSpec = { httpUrl: normalized };
+    } else if (!ephemeralSpec.httpUrl) {
+      ephemeralSpec = { ...ephemeralSpec, httpUrl: normalized };
+    }
+    return undefined;
+  };
+
+  parsed.server = absorbUrlCandidate(parsed.server);
+  parsed.selector = absorbUrlCandidate(parsed.selector);
+
+  if (ephemeralSpec && parsed.server && !looksLikeHttpUrl(parsed.server)) {
+    nameHints.push(parsed.server);
+    parsed.server = undefined;
+  }
+
+  if (ephemeralSpec?.httpUrl && !ephemeralSpec.name && parsed.tool) {
+    const candidate = parsed.selector && !looksLikeHttpUrl(parsed.selector) ? parsed.selector : undefined;
+    if (candidate) {
+      nameHints.push(candidate);
+      parsed.selector = undefined;
+    }
+  }
+
+  const prepared = await prepareEphemeralServerTarget({
+    runtime,
+    target: parsed.server,
+    ephemeral: ephemeralSpec,
+    nameHints,
+    reuseFromSpec: true,
+  });
+
+  parsed.server = prepared.target;
+  if (!parsed.selector) {
+    parsed.selector = prepared.target;
+  }
+}
+
+async function resolveServerAndTool(runtime: Runtime, parsed: CallArgsParseResult): Promise<ResolvedCallTarget> {
+  const target = resolveCallTarget(parsed, { allowMissingTool: true });
+  const server = target.server;
+  let tool = target.tool;
+  if (!server) {
+    throw new Error('Missing server name. Provide it via <server>.<tool> or --server.');
+  }
+  if (!tool) {
+    tool = await inferSingleToolName(runtime, server);
+    if (!tool) {
+      throw new Error('Missing tool name. Provide it via <server>.<tool> or --tool.');
+    }
+  }
+  return { server, tool };
+}
+
+async function invokePreparedCall(
+  runtime: Runtime,
+  prepared: PreparedCallRequest
+): Promise<{ result: unknown; resolvedTool: string } | undefined> {
+  let invocation: { result: unknown; resolvedTool: string };
+  try {
+    invocation = await invokeWithAutoCorrection(
+      runtime,
+      prepared.server,
+      prepared.tool,
+      prepared.hydratedArgs,
+      prepared.timeoutMs
+    );
+  } catch (error) {
+    const issue = maybeReportConnectionIssue(prepared.server, prepared.tool, error);
+    if (prepared.parsed.output === 'json' || prepared.parsed.output === 'raw') {
+      const payload = buildConnectionIssueEnvelope({ server: prepared.server, tool: prepared.tool, error, issue });
+      console.log(JSON.stringify(payload, null, 2));
+      process.exitCode = 1;
+      return undefined;
+    }
+    throw error;
+  }
+  return invocation;
+}
+
+function renderCallResult(result: unknown, parsed: CallArgsParseResult): void {
+  const { callResult: wrapped } = wrapCallResult(result);
+  printCallOutput(wrapped, result, parsed.output);
+  saveCallImagesIfRequested(wrapped, parsed.saveImagesDir);
+  tailLogIfRequested(result, parsed.tailLog);
+  dumpActiveHandles('after call (formatted result)');
+}
+
+export function printCallHelp(): void {
+  const lines = [
+    'Usage: mcporter call <server.tool | url> [arguments] [flags]',
+    '',
+    'Selectors:',
+    '  server.tool            Use a configured server and tool (e.g., linear.list_issues).',
+    '  https://host/mcp.tool  Call a tool by full HTTP URL (auto-registers ad-hoc).',
+    '  --server <name>        Override the server name.',
+    '  --tool <name>          Override the tool name.',
+    '',
+    'Arguments:',
+    '  key=value / key:value  Flag-style named arguments.',
+    '  function-call syntax   \'server.tool(arg: "value", other: 1)\'.',
+    '  --args <json>          Provide a JSON object payload.',
+    '  positional values      Accepted when schema order is known.',
+    '',
+    'Runtime flags:',
+    '  --timeout <ms>         Override the call timeout.',
+    '  --output text|markdown|json|raw  Control formatting.',
+    '  --save-images <dir>    Save image content blocks to a directory.',
+    '  --raw-strings          Keep numeric-looking argument values as strings.',
+    '  --no-coerce            Keep all key/value and positional arguments as raw strings.',
+    '  --tail-log             Stream returned log handles.',
+    '',
+    'Ad-hoc servers:',
+    '  --http-url <url>       Register an HTTP server for this run.',
+    '  --allow-http           Permit plain http:// URLs with --http-url.',
+    '  --stdio <command>      Run a stdio MCP server (repeat --stdio-arg for args).',
+    '  --stdio-arg <value>    Append args to the stdio command (repeatable).',
+    '  --env KEY=value        Inject env vars for stdio servers (repeatable).',
+    '  --cwd <path>           Working directory for stdio servers.',
+    '  --name <value>         Override the display name for ad-hoc servers.',
+    '  --description <text>   Override the description for ad-hoc servers.',
+    '  --persist <path>       Write the ad-hoc definition to config/mcporter.json.',
+    '  --yes                  Skip confirmation prompts when persisting.',
+    '',
+    'Examples:',
+    '  mcporter call linear.list_issues team=ENG limit:5',
+    '  mcporter call "linear.create_issue(title: \\"Bug\\", team: \\"ENG\\")"',
+    '  mcporter call https://api.example.com/mcp.fetch url:https://example.com',
+    '  mcporter call --stdio "bun run ./server.ts" scrape url=https://example.com',
+  ];
+  console.error(lines.join('\n'));
+}
+
+async function maybeDescribeServer(
+  runtime: Awaited<ReturnType<typeof import('../runtime.js')['createRuntime']>>,
+  server: string,
+  tool: string,
+  outputFormat: OutputFormat
+): Promise<boolean> {
+  if (tool === 'list_tools') {
+    console.log(dimText(`[mcporter] ${server}.list_tools is a shortcut for 'mcporter list ${server}'.`));
+    const listArgs = [server];
+    if (outputFormat === 'json') {
+      listArgs.push('--json');
+    }
+    await handleList(runtime, listArgs);
+    return true;
+  }
+  if (tool !== 'help') {
+    return false;
+  }
+  const tools = await runtime.listTools(server, { includeSchema: false, autoAuthorize: false }).catch(() => undefined);
+  if (!tools) {
+    return false;
+  }
+  const hasHelpTool = tools.some((entry) => entry.name === 'help');
+  if (hasHelpTool) {
+    return false;
+  }
+  console.log(dimText(`[mcporter] ${server} does not expose a 'help' tool; showing mcporter list output instead.`));
+  const listArgs = [server];
+  if (outputFormat === 'json') {
+    listArgs.push('--json');
+  }
+  await handleList(runtime, listArgs);
+  return true;
+}
+
+interface ResolveCallTargetOptions {
+  allowMissingTool?: boolean;
+}
+
+function resolveCallTarget(
+  parsed: CallArgsParseResult,
+  options: ResolveCallTargetOptions = {}
+): { server?: string; tool?: string } {
+  const selector = parsed.selector;
+  let server = parsed.server;
+  let tool = parsed.tool;
+
+  if (selector && !server && selector.includes('.')) {
+    const [left, right] = selector.split('.', 2);
+    server = left;
+    tool = right;
+  } else if (selector && !server) {
+    server = selector;
+  } else if (selector && !tool && selector !== server) {
+    tool = selector;
+  }
+
+  if (!server) {
+    throw new Error('Missing server name. Provide it via <server>.<tool> or --server.');
+  }
+  if (!tool && !options.allowMissingTool) {
+    throw new Error('Missing tool name. Provide it via <server>.<tool> or --tool.');
+  }
+
+  return { server, tool };
+}
+
+async function hydratePositionalArguments(
+  runtime: Awaited<ReturnType<typeof import('../runtime.js')['createRuntime']>>,
+  server: string,
+  tool: string,
+  namedArgs: Record<string, unknown>,
+  positionalArgs: unknown[] | undefined
+): Promise<Record<string, unknown>> {
+  if (!positionalArgs || positionalArgs.length === 0) {
+    return namedArgs;
+  }
+  // We need the schema order to know which field each positional argument maps to; pull the
+  // tool list with schemas instead of guessing locally so optional/required order stays correct.
+  const tools = await loadToolMetadata(runtime, server, { includeSchema: true }).catch(() => undefined);
+  if (!tools) {
+    throw new Error('Unable to load tool metadata; name positional arguments explicitly.');
+  }
+  const toolInfo = tools.find((entry) => entry.tool.name === tool);
+  if (!toolInfo) {
+    throw new Error(
+      `Unknown tool '${tool}' on server '${server}'. Double-check the name or run mcporter list ${server}.`
+    );
+  }
+  if (!toolInfo.tool.inputSchema) {
+    throw new Error(`Tool '${tool}' does not expose an input schema; name positional arguments explicitly.`);
+  }
+  const options = toolInfo.options;
+  if (options.length === 0) {
+    throw new Error(`Tool '${tool}' has no declared parameters; remove positional arguments.`);
+  }
+  // Respect whichever parameters the user already supplied by name so positional values only
+  // populate the fields that are still unset.
+  const remaining = options.filter((option) => !(option.property in namedArgs));
+  if (positionalArgs.length > remaining.length) {
+    throw new Error(
+      `Too many positional arguments (${positionalArgs.length}) supplied; only ${remaining.length} parameter${remaining.length === 1 ? '' : 's'} remain on ${tool}.`
+    );
+  }
+  const hydrated: Record<string, unknown> = { ...namedArgs };
+  positionalArgs.forEach((value, index) => {
+    const target = remaining[index];
+    if (!target) {
+      return;
+    }
+    hydrated[target.property] = value;
+  });
+  return hydrated;
+}
+
+type ToolResolution = IdentifierResolution;
+
+async function inferSingleToolName(
+  runtime: Awaited<ReturnType<typeof import('../runtime.js')['createRuntime']>>,
+  server: string
+): Promise<string | undefined> {
+  const tools = await loadToolMetadata(runtime, server, { includeSchema: false });
+  if (tools.length !== 1) {
+    return undefined;
+  }
+  const name = tools[0]?.tool.name;
+  if (!name) {
+    return undefined;
+  }
+  console.log(dimText(`[auto] ${server} exposes a single tool (${name}); using it.`));
+  return name;
+}
+
+async function invokeWithAutoCorrection(
+  runtime: Awaited<ReturnType<typeof import('../runtime.js')['createRuntime']>>,
+  server: string,
+  tool: string,
+  args: Record<string, unknown>,
+  timeoutMs: number
+): Promise<{ result: unknown; resolvedTool: string }> {
+  // Attempt the original request first; if it fails with a "tool not found" we opportunistically retry once with a better match.
+  return attemptCall(runtime, server, tool, args, timeoutMs, true);
+}
+
+async function attemptCall(
+  runtime: Awaited<ReturnType<typeof import('../runtime.js')['createRuntime']>>,
+  server: string,
+  tool: string,
+  args: Record<string, unknown>,
+  timeoutMs: number,
+  allowCorrection: boolean
+): Promise<{ result: unknown; resolvedTool: string }> {
+  try {
+    const result = await withTimeout(runtime.callTool(server, tool, { args, timeoutMs }), timeoutMs);
+    return { result, resolvedTool: tool };
+  } catch (error) {
+    if (error instanceof Error && error.message === 'Timeout') {
+      const timeoutDisplay = `${timeoutMs}ms`;
+      await runtime.close(server).catch(() => {});
+      throw new Error(
+        `Call to ${server}.${tool} timed out after ${timeoutDisplay}. Override MCPORTER_CALL_TIMEOUT or pass --timeout to adjust.`
+      );
+    }
+
+    if (!allowCorrection) {
+      throw error;
+    }
+
+    const resolution = await maybeResolveToolName(runtime, server, tool, error);
+    if (!resolution) {
+      maybeReportConnectionIssue(server, tool, error);
+      throw error;
+    }
+
+    const messages = renderIdentifierResolutionMessages({
+      entity: 'tool',
+      attempted: tool,
+      resolution,
+      scope: server,
+    });
+    if (resolution.kind === 'suggest') {
+      if (messages.suggest) {
+        console.error(dimText(messages.suggest));
+      }
+      throw error;
+    }
+    if (messages.auto) {
+      console.log(dimText(messages.auto));
+    }
+    return attemptCall(runtime, server, resolution.value, args, timeoutMs, false);
+  }
+}
+
+async function maybeResolveToolName(
+  runtime: Awaited<ReturnType<typeof import('../runtime.js')['createRuntime']>>,
+  server: string,
+  attemptedTool: string,
+  error: unknown
+): Promise<ToolResolution | undefined> {
+  const missingName = extractMissingToolFromError(error);
+  if (!missingName) {
+    return undefined;
+  }
+
+  // Only attempt a suggestion if the server explicitly rejected the tool we tried.
+  if (normalizeIdentifier(missingName) !== normalizeIdentifier(attemptedTool)) {
+    return undefined;
+  }
+
+  const tools = await loadToolMetadata(runtime, server, { includeSchema: false }).catch(() => undefined);
+  if (!tools) {
+    return undefined;
+  }
+
+  const resolution = chooseClosestIdentifier(
+    attemptedTool,
+    tools.map((entry) => entry.tool.name)
+  );
+  if (!resolution) {
+    return undefined;
+  }
+  return resolution;
+}
+
+function extractMissingToolFromError(error: unknown): string | undefined {
+  const message = error instanceof Error ? error.message : typeof error === 'string' ? error : undefined;
+  if (!message) {
+    return undefined;
+  }
+  const match = message.match(/Tool\s+([A-Za-z0-9._-]+)\s+not found/i);
+  return match?.[1];
+}
+
+function maybeReportConnectionIssue(server: string, tool: string, error: unknown): ConnectionIssue | undefined {
+  const issue = analyzeConnectionError(error);
+  const detail = summarizeIssueMessage(issue.rawMessage);
+  if (issue.kind === 'auth') {
+    const authCommand = `mcporter auth ${server}`;
+    const hint = `[mcporter] Authorization required for ${server}. Run '${authCommand}'.${detail ? ` (${detail})` : ''}`;
+    console.error(yellowText(hint));
+    return issue;
+  }
+  if (issue.kind === 'offline') {
+    const hint = `[mcporter] ${server} appears offline${detail ? ` (${detail})` : ''}.`;
+    console.error(redText(hint));
+    return issue;
+  }
+  if (issue.kind === 'http') {
+    const status = issue.statusCode ? `HTTP ${issue.statusCode}` : 'an HTTP error';
+    const hint = `[mcporter] ${server}.${tool} responded with ${status}${detail ? ` (${detail})` : ''}.`;
+    console.error(dimText(hint));
+    return issue;
+  }
+  if (issue.kind === 'stdio-exit') {
+    const exit = typeof issue.stdioExitCode === 'number' ? `code ${issue.stdioExitCode}` : 'an unknown status';
+    const signal = issue.stdioSignal ? ` (signal ${issue.stdioSignal})` : '';
+    const hint = `[mcporter] STDIO server for ${server} exited with ${exit}${signal}.`;
+    console.error(redText(hint));
+  }
+  return issue;
+}
+
+function summarizeIssueMessage(message: string): string {
+  if (!message) {
+    return '';
+  }
+  const trimmed = message.trim();
+  if (trimmed.length <= 120) {
+    return trimmed;
+  }
+  return `${trimmed.slice(0, 117)}…`;
+}

package/src/cli/call-expression-parser.ts

@@ -0,0 +1,210 @@
+import { parseExpressionAt } from 'acorn';
+import type {
+  ArrayExpression,
+  CallExpression,
+  Expression,
+  Literal,
+  ObjectExpression,
+  Property,
+  UnaryExpression,
+} from 'estree';
+
+interface ParsedCallExpression {
+  server?: string;
+  tool: string;
+  args: Record<string, unknown>;
+  positionalArgs?: unknown[];
+}
+
+const ACORN_OPTIONS = {
+  ecmaVersion: 'latest' as const,
+  sourceType: 'module' as const,
+};
+
+export function parseCallExpressionFragment(raw: string): ParsedCallExpression | null {
+  const trimmed = raw.trim();
+  const openParen = trimmed.indexOf('(');
+  if (openParen === -1 || !trimmed.endsWith(')')) {
+    return null;
+  }
+
+  const prefix = trimmed.slice(0, openParen).trim();
+  if (!prefix) {
+    throw new Error('Expected a tool name before the argument list.');
+  }
+
+  const argsPortion = trimmed.slice(openParen + 1, -1);
+  const trimmedArgs = argsPortion.trim();
+  const attempts = buildParseAttempts(trimmedArgs);
+  let callExpression: CallExpression | undefined;
+  let parseError: Error | undefined;
+
+  for (const candidate of attempts) {
+    try {
+      const expression = parseExpressionAt(`__call${candidate}`, 0, ACORN_OPTIONS);
+      if (expression.type === 'CallExpression') {
+        callExpression = expression as CallExpression;
+        break;
+      }
+    } catch (error) {
+      parseError = error instanceof Error ? error : new Error(String(error));
+    }
+  }
+
+  if (!callExpression) {
+    const message = parseError?.message ?? 'Unexpected token';
+    throw new Error(`Unable to parse call expression: ${message}`);
+  }
+
+  if (callExpression.arguments.length === 0) {
+    return {
+      ...splitPrefix(prefix),
+      args: {},
+    };
+  }
+
+  if (callExpression.arguments.length === 1 && callExpression.arguments[0]?.type === 'ObjectExpression') {
+    const argument = callExpression.arguments[0];
+    if (!argument || argument.type !== 'ObjectExpression') {
+      throw new Error('Function-call syntax requires named arguments (e.g. issueId: 123).');
+    }
+    const args = extractObject(argument);
+    return { ...splitPrefix(prefix), args };
+  }
+
+  // At this point we know the call expression isn't a plain object literal, so we interpret
+  // whatever arguments remain positionally. We still reuse the literal extractor so nested
+  // arrays/objects stay supported.
+  const positionalArgs = callExpression.arguments.map((argument) => {
+    if (!argument) {
+      throw new Error('Unsupported empty argument in call expression.');
+    }
+    if (argument.type === 'SpreadElement') {
+      throw new Error('Spread elements are not supported in call expressions.');
+    }
+    if (!isSupportedValue(argument as Expression)) {
+      throw new Error(`Unsupported argument expression: ${argument.type}.`);
+    }
+    return extractValue(argument as Expression);
+  });
+
+  return { ...splitPrefix(prefix), args: {}, positionalArgs };
+}
+
+function splitPrefix(prefix: string): { server?: string; tool: string } {
+  const [first, ...rest] = prefix.split('.');
+  if (!first) {
+    throw new Error('Expected a tool name before the argument list.');
+  }
+  if (rest.length === 0) {
+    return { tool: first };
+  }
+  return { server: first, tool: rest.join('.') };
+}
+
+function extractObject(expression: ObjectExpression): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const property of expression.properties) {
+    if (property.type !== 'Property') {
+      throw new Error('Unsupported property type in call expression.');
+    }
+    if (property.kind !== 'init') {
+      throw new Error('Only simple assignments are supported in call expressions.');
+    }
+    if (property.computed) {
+      throw new Error('Computed property names are not supported in call expressions.');
+    }
+    const key = extractKey(property);
+    const rawValue = property.value;
+    if (!rawValue || !isSupportedValue(rawValue)) {
+      throw new Error(`Unsupported argument expression: ${rawValue ? rawValue.type : 'null'}.`);
+    }
+    const value = extractValue(rawValue);
+    result[key] = value;
+  }
+  return result;
+}
+
+function extractKey(property: Property): string {
+  if (property.key.type === 'Identifier') {
+    return property.key.name;
+  }
+  if (property.key.type === 'Literal' && typeof property.key.value === 'string') {
+    return property.key.value;
+  }
+  throw new Error('Invalid argument name in call expression.');
+}
+
+function extractValue(value: Expression): unknown {
+  switch (value.type) {
+    case 'Literal':
+      return (value as Literal).value ?? null;
+    case 'ArrayExpression':
+      return extractArray(value as ArrayExpression);
+    case 'ObjectExpression':
+      return extractObject(value as ObjectExpression);
+    case 'UnaryExpression':
+      return extractUnary(value as UnaryExpression);
+    default:
+      throw new Error(`Unsupported argument expression: ${value.type}.`);
+  }
+}
+
+function extractArray(arrayExpression: ArrayExpression): unknown[] {
+  return arrayExpression.elements.map((element, index) => {
+    if (!element) {
+      throw new Error(`Sparse array entries are not supported (index ${index}).`);
+    }
+    if (element.type === 'SpreadElement') {
+      throw new Error('Spread elements are not supported in call expressions.');
+    }
+    const elementType = (element as { type?: string }).type ?? 'unknown';
+    if (!isSupportedValue(element)) {
+      throw new Error(`Unsupported argument expression: ${elementType}.`);
+    }
+    return extractValue(element as Expression);
+  });
+}
+
+function extractUnary(expression: UnaryExpression): unknown {
+  if (expression.operator === '-' || expression.operator === '+') {
+    const inner = expression.argument;
+    if (inner.type !== 'Literal' || typeof (inner as Literal).value !== 'number') {
+      throw new Error('Unary operators are only supported for numeric literals.');
+    }
+    const numericValue = Number((inner as Literal).value);
+    return expression.operator === '-' ? -numericValue : numericValue;
+  }
+  if (expression.operator === '!') {
+    const inner = expression.argument;
+    if (inner.type !== 'Literal' || typeof (inner as Literal).value !== 'boolean') {
+      throw new Error('Logical negation is only supported for boolean literals.');
+    }
+    return !(inner as Literal).value;
+  }
+  throw new Error(`Unsupported unary operator: ${expression.operator}`);
+}
+
+function buildParseAttempts(trimmedArgs: string): string[] {
+  if (trimmedArgs === '') {
+    return ['()'];
+  }
+  const attempts: string[] = [`(${trimmedArgs})`];
+  const needsObjectWrap =
+    !trimmedArgs.startsWith('{') &&
+    !trimmedArgs.startsWith('({') &&
+    !trimmedArgs.startsWith('[') &&
+    /[A-Za-z0-9_]\s*:/.test(trimmedArgs);
+  if (needsObjectWrap) {
+    attempts.push(`({${trimmedArgs}})`);
+  }
+  return attempts;
+}
+
+function isSupportedValue(node: unknown): node is Expression {
+  if (!node || typeof node !== 'object' || !('type' in node)) {
+    return false;
+  }
+  const type = (node as { type: string }).type;
+  return type === 'Literal' || type === 'ArrayExpression' || type === 'ObjectExpression' || type === 'UnaryExpression';
+}