feat: introduce comprehensive dart source file generation

[jwelmac]

Description

This PR introduces a complete TypeScript SDK generation ecosystem for Globe Runtime, establishing a new recommended workflow:

1. Define type-safe SDKs in TypeScript using @globe/runtime_types
2. Generate Dart source files using @globe/dart_source_generator CLI
3. Consume generated SDKs in Dart with clean, type-safe APIs

This significantly improves developer experience by eliminating the need for FFI boilerplate and providing end-to-end type safety across the JavaScript-Dart boundary.

What's New

1. @globe/dart_source_generator - Code Generation CLI

New package with complete implementation:

• TypeScript AST parsing to extract SDK definitions
• Automatic type mapping (TypeScript → Dart)
• Dart wrapper class code generation
• Watch mode, batch processing, verbose logging
• Comprehensive test coverage included

2. @globe/runtime_types - Type-Safe SDK Definition

Enhanced package with full type support:

• index.js (271 lines) - Complete JSDoc type annotations
• index.d.ts (353 lines) - TypeScript declarations
• README.md (366 lines) - Comprehensive API documentation
• Helper functions: defineFunction(), defineSdk(), returnString(), streamString(), etc.

3. packages/globe_runtime/README.md - Updated Documentation

• New "Recommended Approach" section featuring @globe/dart_source_generator
• 4-step tutorial with practical examples
• Clear explanation of bundling approach
• Alternative methods (esbuild, tsup) documented

4. examples/full_example - Complete Working Example

• Full TypeScript SDK definition (full_example.ts)
• Generated Dart wrapper (full_example_source.dart)
• Real-world patterns for streaming and single-value returns
• Demonstrates initialization with parameters

Key Features

✅ AST-based type extraction and code generation
✅ Automatic TypeScript-to-Dart type mapping
✅ Watch mode and batch processing
✅ Preserve comments from JS/TS to Dart (with type conversion)
✅ Real-world working examples

Test Coverage

Comprehensive test suite covering AST parsing, code generation, type mapping, and CLI functionality.

Usage Example

Step 1: Define TypeScript SDK

import { defineSdk, streamString } from "@globe/runtime_types";

export default defineSdk({
  init(apiUrl = "https://api.example.com") {
    return { apiUrl };
  },
  functions: {
    fetchUsers: streamString(async (state, callbackId) => {
      const response = await fetch(state.apiUrl + "/users");
      for await (const chunk of response.body!.values()) {
        Dart.stream_value(callbackId, chunk);
      }
      Dart.stream_value_end(callbackId);
    }),
  },
});

Step 2: Generate Dart Source

npx @globe/dart_source_generator --files src/sdk.ts --output lib/

Step 3: Use in Dart

final sdk = await Sdk.create(apiUrl: 'https://api.custom.com');
final users = await sdk.fetchUsers();
users.listen((user) => print('User: $user'));

Breaking Changes

✅ None - Entirely additive feature set

All existing Globe Runtime functionality remains unchanged and unaffected.

Backward Compatibility

✅ 100% Compatible

• Existing FFI integration patterns still work
• Alternative bundling approaches (esbuild, tsup) still supported
• No changes to core runtime APIs
• New approach is opt-in

[codekeyz]

@jwelmac This is pretty good. I had this in the roadmap, but really excited to see you're thinking in this direction.

I'll give this a proper review sometime today 🔥

[jwelmac]

Thank you @codekeyz.
As the saying goes great minds think alike.

Looking forward to your feedback.

[jwelmac]

@codekeyz
This build issue for MacOS seems to precede this PR

[jwelmac]

@codekeyz
I also noted after some testing that though globe_runtime is marked for Dart/Flutter use it does not work for mobile or web. I am thinking to implement codegeneration code for those platforms as well.
Should I do that here in one go, or should I do that in a follow up PR?

[codekeyz]

@jwelmac There’s currently no plan to support this on the web.

I do intend to add Flutter support, but that depends on successfully compiling V8 (rusty_v8) for mobile, which I haven’t been able to get working yet. For now, you can hold off on any platform-compatibility changes or follow-up work related to that.

[codekeyz]

@codekeyz This build issue for MacOS seems to precede this PR

Yeah, ignore it.

[codekeyz]

@jwelmac I've added some improvements & fixed the build failure. Please rebase your branch so I can review easily.

[jwelmac]

Thanks for the updates and making the init optional. I was seriously contemplating that but thought that was outside the scope of changes here.
I will update the typing to accommodate same.
Thanks again @codekeyz

[jwelmac]

@codekeyz
It has been updated

[jwelmac]

@codekeyz
Added the ability to preserve comments from JS/TS to Dart code