fix(functions): validate --data JSON client-side with PowerShell quoting hint

ST
2d ago
+174-2

Problem

On Windows PowerShell, passing a JSON --data argument to functions invoke (e.g. through ConvertTo-Json + npx.cmd) can have its embedded double quotes stripped or mangled by the shell before the string ever reaches process.argv. The CLI previously forwarded whatever string it received straight into the HTTP request body with no client-side validation, so the malformed JSON only failed server-side with a confusing error:

Expected property name or '}' in JSON at position 1

Root cause: shell-level, but a code-side mitigation is correct and minimal

This is fundamentally a PowerShell argument-quoting issue — argv level, outside the CLI's control. There's no way for the CLI to recover the quotes PowerShell already stripped. However, the actual problem reported — a confusing, late, server-side failure with no actionable guidance — is fixable here, and this repo already has an established pattern for it (records create, compute deploy --env): validate the JSON client-side with JSON.parse, fail fast with a clear CLIError, and never make the network request on invalid input.

Fix

  • functions invoke --data now runs JSON.parse before sending the request. On failure it throws a CLIError with the message Invalid JSON in --data plus a concrete PowerShell quoting hint (--data '{\"key\":\"value\"}') and points at the new escape hatch.
  • Added --data-file <path> (modeled on compute deploy --env-file) so Windows users can skip inline shell quoting entirely by putting the JSON body in a file.
  • --data and --data-file are mutually exclusive, validated the same way --env/--env-file are in compute deploy.
  • Documented both the new flag and the PowerShell quoting gotcha in the README's functions invoke section.

(The triage note on the issue referenced insforge-skills/skills/insforge-cli/SKILL.md:221 for docs — that path doesn't exist in this repo, so the quoting note was added to this repo's own README instead, next to the existing functions invoke examples.)

Test plan

  • Added src/commands/functions/invoke.test.ts: malformed --data throws Invalid JSON in --data and fetch is never called; valid --data is sent verbatim; --data + --data-file together is rejected before any request.
  • npm run test — all new tests pass; the 5 pre-existing failures (Windows path-separator issues in src/lib/migrations.test.ts and src/lib/local/checkout.test.ts) are unrelated and reproduce identically on main before this change.
  • npx eslint src/commands/functions/invoke.ts src/commands/functions/invoke.test.ts — clean.
  • npm run build — succeeds.

Fixes #272

🤖 Generated with Claude Code

Summary by cubic

Fixes functions invoke so malformed --data JSON fails fast with a clear error instead of a confusing server-side message, and adds --data-file so PowerShell users can skip inline shell quoting.

  • --data and --data-file are mutually exclusive. Empty values (--data '', --data-file '') are treated as present, so they're validated and rejected, not silently ignored.
  • Client-side JSON.parse validates the body before any network request; the --data error includes PowerShell quoting guidance, while --data-file errors name the offending path.
  • --data-file reads the body from a file and strips a leading UTF-8 BOM (PowerShell commonly writes BOM-prefixed UTF-8 files).
  • Tests cover malformed, empty, conflicting, and file-based cases; README documents the new flag and the quoting gotcha.

Summary by CodeRabbit

  • New Features

    • Added --data-file as an alternative to --data when sending JSON with function requests.
    • Updated documentation with file-based examples and a Windows PowerShell quoting note.

  • Bug Fixes

    • Invalid JSON and file-read failures now produce clear errors. Using both body options is rejected.