feat: generate SDK for TypeScript and Python by gaojunran · Pull Request #623 · jdx/usage

gaojunran · 2026-05-04T08:12:35Z

No description provided.

…sive tests - Fix var=true boolean flag typed as Optional[bool] in Python - Fix -- separator ordering for double_dash=required args - Fix Python var flag default type mismatch - Align SDK tests across Python and TypeScript - Add ~30 new Python tests and ~14 new TypeScript tests - Add compile/import validation tests for Python and TypeScript - Mark Rust SDK as coming soon in docs - Add Typer and Click integration links

- Python: add client_edge_cases, config_and_flag_edge_cases, double_dash_automatic - TypeScript: add config_boolean_default_false, config_string_with_default, example_without_lang, flag_edge_cases, global_flags_flags_only, double_dash_automatic

codecov · 2026-05-04T08:15:43Z

Codecov Report

❌ Patch coverage is 96.82660% with 84 lines in your changes missing coverage. Please review.
✅ Project coverage is 79.64%. Comparing base (beb1a66) to head (48bf65c).
⚠️ Report is 12 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/src/sdk/python/mod.rs	97.29%	25 Missing and 7 partials ⚠️
cli/src/cli/generate/sdk.rs	0.00%	22 Missing ⚠️
lib/src/sdk/typescript/types.rs	97.71%	14 Missing and 5 partials ⚠️
lib/src/sdk/typescript/wrappers.rs	97.98%	4 Missing and 2 partials ⚠️
lib/src/sdk/mod.rs	98.92%	1 Missing and 2 partials ⚠️
cli/src/cli/generate/mod.rs	0.00%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #623      +/-   ##
==========================================
+ Coverage   78.94%   79.64%   +0.70%     
==========================================
  Files          49       55       +6     
  Lines        7284    10106    +2822     
  Branches     7284    10106    +2822     
==========================================
+ Hits         5750     8049    +2299     
- Misses       1147     1322     +175     
- Partials      387      735     +348

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Remove Rust SDK module, language enum variant, CLI option, and all snapshot files. Rust SDK will be re-added in a future update.

gemini-code-assist · 2026-05-04T08:18:22Z

Warning

Gemini is experiencing higher than usual traffic and was unable to create the review. Please try again in a few hours by commenting /gemini review.

greptile-apps · 2026-05-04T08:23:49Z

Greptile Summary

This PR adds TypeScript and Python SDK generation to usage-cli, producing type-safe subprocess-wrapper clients from a usage spec. It introduces lib/src/sdk/{typescript,python}/ with types, client, runtime, and entry-point modules, a new usage generate sdk CLI subcommand, integration compile tests, and documentation.

String escaping and comment-newline sanitization (sanitize_py_comment) are applied consistently throughout both generators, and reserved-word collisions are guarded in sanitize_ident.
One remaining gap: two fallback # default: {default_val} comment paths in render_flags_dataclass do not route through sanitize_py_comment, so a spec default containing \ would produce broken Python at import time.
Integration tests skip gracefully when tools are absent; snapshot coverage is thorough.

Confidence Score: 4/5

Safe to merge for the vast majority of specs; a spec whose flag default value contains a literal newline character would generate a broken Python module.

The two unguarded # default: {default_val} comment paths in render_flags_dataclass are the only places where user-controlled content reaches a # line comment without newline sanitization. Every other comment path correctly uses sanitize_py_comment. The fix is a one-line change at each site.

lib/src/sdk/python/mod.rs — the two # default: {default_val} fallback branches in render_flags_dataclass.

Important Files Changed

Filename	Overview
lib/src/sdk/python/mod.rs	Python SDK generator: most escaping/sanitization issues addressed, but `default_val` in two inline `# default:` comment fallback paths is not passed through `sanitize_py_comment`, allowing embedded newlines to break generated Python.
lib/src/sdk/typescript/wrappers.rs	TypeScript client generator: string escaping for bin_name, flag arg names, and full_cmd path elements all look correct.
lib/src/sdk/typescript/types.rs	TypeScript types generator: choice escaping, flag deduplication in Flags extends GlobalFlags, and reserved-word sanitization all correctly implemented.
lib/src/sdk/mod.rs	Shared SDK utilities: escape helpers, ChoiceTypeMap collision detection, and collect_type_imports all look correctly implemented.
cli/src/cli/generate/sdk.rs	New CLI subcommand wiring: language enum dispatch, file output loop, and error handling are straightforward and correct.
lib/tests/sdk_compile.rs	Integration compile tests for both Python and TypeScript — skipped when tools are absent, otherwise comprehensive.

_{Reviews (12): Last reviewed commit: "style: apply formatting after render" | Re-trigger Greptile}

- P2: re-export CliResult/CliRunner from Python __init__.py and CliResult from TypeScript index.ts - P2: escape */ in JSDoc and triple-quote in Python docstrings to prevent premature termination from user-supplied spec text - P2: fix unreachable "True"/"False"/"None" in sanitize_py_ident (heck::AsSnakeCase lowercases before match) - P2: remove incorrect await from docs synchronous API example

Replace spawnSync with spawn + Promise wrapper in runtime.ts. All exec() methods now return Promise<CliResult> and are marked async, which is more idiomatic for Node.js and avoids blocking the event loop on subprocess calls. Update docs examples to use await. Update all TypeScript snapshots.

…types - P1: escape backslashes and double quotes in Python string defaults (config props, arg defaults, flag defaults, VERSION/ABOUT/AUTHOR, bin_path). Add escape_py_string() and escape_ts_string() helpers. - P2: export CliError from TypeScript index.ts - P2: stop emitting empty XxxFlags extends GlobalFlags {} interfaces in types.ts when subcommands only have global flags with no local flags — client.ts already uses GlobalFlags directly in this case

- Python: escape choice values, cmd path elements, flag_arg_name, negate flag names in string literals; escape alias docstrings - TypeScript: escape choice values in type unions, cmd path elements in subcmd_path, bin_name in constructor, flag_arg_name, negate flag names in string literals Note: flag short names (char type) cannot contain " or \ so they do not need escaping.

…gment - Python: render multi-part exec docstrings as proper multiline docstrings instead of single-line with embedded \n - docs: fix broken sentence from Rust SDK removal (child_process.spawn / not -> child_process.spawn, not)

Python render_command_types was generating {name}Flags dataclasses for subcommands that only inherit global flags (no local flags). Since client.py uses GlobalFlags directly for these cases, the generated dataclass was dead code. Now only emit Flags dataclass when there are local visible flags, matching the TypeScript fix.

jdx · 2026-05-04T12:11:53Z

 #[cfg(feature = "docs")]
 pub mod docs;
 pub mod parse;
+#[cfg(feature = "sdk")]


Why add a feature?

Why add a feature?

I found it relatively independent and make it a feature. Should we remove it?

…t comment

gaojunran · 2026-05-17T13:57:04Z

@greptileai

…ze newlines in Python comments

gaojunran · 2026-05-17T14:16:09Z

@greptileai

greptile-apps · 2026-05-17T14:25:27Z

+    if has_global_flags {
+        w.line("");
+        w.line("/** Global flags available on all subcommands. */");
+        w.line("export interface GlobalFlags {");
+        w.indent();
+        for flag in &root_global_flags {
+            let prop = flag_property_name(flag);
+            let ts_type = flag_ts_simple(flag);
+            let optional = if flag.required { "" } else { "?" };
+            let mut doc_parts = Vec::new();
+            if let Some(help) = &flag.help {
+                doc_parts.push(help.clone());
+            }
+            if let Some(env) = &flag.env {
+                doc_parts.push(format!("Environment variable: {env}"));
+            }
+            if !doc_parts.is_empty() {
+                w.line(&format!("/** {} */", escape_jsdoc(&doc_parts.join(". "))));
+            }
+            w.line(&format!("{prop}{optional}: {ts_type};"));
+        }
+        w.dedent();
+        w.line("}");
+    }


GlobalFlags drops choice type constraints for global flags with choices

flag_ts_simple is used to render the GlobalFlags interface and always returns string for any value flag, regardless of whether the flag has a choices constraint. A global flag declared as flag "--env <env>" global=#true { choices "dev" "prod" } would generate env?: string in GlobalFlags instead of env?: EnvChoice. The Python generator correctly calls flag_py_type(flag, "", choice_types) (using cmd_name = "" to match the root-level choice entry) for the equivalent GlobalFlags dataclass, so there is a concrete asymmetry between the two targets.

The fix is to replace flag_ts_simple with flag_ts_type(flag, "", choice_types) (passing "" as the cmd_name, consistent with how root-level choice entries are stored) for the GlobalFlags rendering loop.

greptile-apps · 2026-05-17T14:29:04Z

+                } else if flag.var {
+                    // var flag with a default — list defaults are mutable and forbidden in dataclasses.
+                    // use None and preserve the intended default in a comment.
+                    format!("{prop_name}: Optional[{py_type}] = None  # default: {default_val}")
+                } else {


Both fallback comment paths embed default_val directly into a # ... line comment without sanitizing newlines. A spec default like default="first second" would emit second as a bare Python expression, causing a NameError at import time. All other help-comment sites in this file use sanitize_py_comment.

Suggested change

} else if flag.var {

// var flag with a default — list defaults are mutable and forbidden in dataclasses.

// use None and preserve the intended default in a comment.

format!("{prop_name}: Optional[{py_type}] = None # default: {default_val}")

} else {

} else if flag.var {

// var flag with a default — list defaults are mutable and forbidden in dataclasses.

// use None and preserve the intended default in a comment.

format!("{prop_name}: Optional[{py_type}] = None # default: {}", sanitize_py_comment(default_val))

} else {

gaojunran and others added 8 commits May 3, 2026 18:20

feat: generate SDK for TypeScript, Python and Rust

01c2f47

fix: misc

57596ce

fix: misc

de299aa

fix: misc

9f90083

Merge branch 'jdx:main' into main

218b88d

Merge branch 'jdx:main' into main

65bde86

refactor(sdk): remove Rust SDK generation code and snapshots

44a8480

Remove Rust SDK module, language enum variant, CLI option, and all snapshot files. Rust SDK will be re-added in a future update.

gaojunran force-pushed the feat-sdk-python-ts branch from f9986cc to 44a8480 Compare May 4, 2026 08:17

greptile-apps Bot reviewed May 4, 2026

View reviewed changes

Comment thread lib/src/sdk/python/runtime.rs

Comment thread lib/src/sdk/typescript/mod.rs

Comment thread lib/src/sdk/typescript/wrappers.rs

Comment thread lib/src/sdk/python/mod.rs

Comment thread docs/cli/sdk.md Outdated

gaojunran added 2 commits May 4, 2026 16:35

gaojunran force-pushed the feat-sdk-python-ts branch from 059c78e to 5b958fc Compare May 4, 2026 08:42

greptile-apps Bot reviewed May 4, 2026

View reviewed changes

Comment thread lib/src/sdk/python/mod.rs Outdated

greptile-apps Bot reviewed May 4, 2026

View reviewed changes

Comment thread lib/src/sdk/typescript/wrappers.rs Outdated

Comment thread lib/src/sdk/typescript/types.rs

Comment thread lib/src/sdk/typescript/wrappers.rs

gaojunran added 2 commits May 4, 2026 17:40

gaojunran force-pushed the feat-sdk-python-ts branch 2 times, most recently from 20bf555 to 6c483d9 Compare May 4, 2026 10:51

greptile-apps Bot reviewed May 4, 2026

View reviewed changes

Comment thread lib/src/sdk/typescript/types.rs

gaojunran force-pushed the feat-sdk-python-ts branch from 1f8596e to dd222a2 Compare May 4, 2026 11:05

gaojunran closed this May 4, 2026

gaojunran reopened this May 4, 2026

gaojunran marked this pull request as ready for review May 4, 2026 11:38

jdx reviewed May 4, 2026

View reviewed changes

junrangao added 3 commits May 17, 2026 21:49

refactor(lib): remove sdk feature and enable by default

9747ab7

style(python): remove unused Union import and clarify var-flag defaul…

79a9828

…t comment

test(python): update snapshots after Union import removal

f88897a

greptile-apps Bot reviewed May 17, 2026

View reviewed changes

Comment thread lib/src/sdk/typescript/types.rs

Comment thread lib/src/sdk/python/mod.rs

gaojunran marked this pull request as draft May 17, 2026 14:05

junrangao added 2 commits May 17, 2026 22:08

fix(sdk): guard internal member names in TS sanitize_ident and saniti…

37b2a51

…ze newlines in Python comments

style: apply formatting after render

48bf65c

greptile-apps Bot reviewed May 17, 2026

View reviewed changes

Uh oh!

Conversation

gaojunran commented May 4, 2026

Uh oh!

codecov Bot commented May 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

gemini-code-assist Bot commented May 4, 2026

Uh oh!

greptile-apps Bot commented May 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 4/5

Important Files Changed

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jdx May 4, 2026

Choose a reason for hiding this comment

Uh oh!

gaojunran May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jdx May 5, 2026

Choose a reason for hiding this comment

Uh oh!

gaojunran commented May 17, 2026

Uh oh!

Uh oh!

Uh oh!

gaojunran commented May 17, 2026

Uh oh!

greptile-apps Bot May 17, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot May 17, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

codecov Bot commented May 4, 2026 •

edited

Loading

greptile-apps Bot commented May 4, 2026 •

edited

Loading

gaojunran May 5, 2026 •

edited

Loading