Proposal: Add ability to quickly run starter project on Val Town

[charmaine]

Hey! I'd like to propose adding a Val Town badge to your docs for new users to optionally have the TypeScript Quickstart up and running in 1-click.

I work here at Val Town and it would mean the world to us to have a place in Braintrust's docs / open source repos! We're very open to any edits you'd like us to make here.

Proposed badge in README:

In action:

The main benefits are:

1. Users can see the full example code immediately and optionally fork the example code snippet
2. Users can make changes and have it running in their account in 1-click.
3. Eliminates the need for users to set up their local dev environment (ie. node, npm) and run into errors outside of your SDK's control

We recently did this with Steel's Cookbook and they were stoked about it, so we wanted to try the same for Braintrust. We're all users and huge fans of Braintrust here!

We're happy to help maintain this starter in Val Town as your docs / SDK changes. You're also welcome to fork it so you have full control over the Val Town project and can make any changes as necessary.

This PR should be ready-to-use as-is. We'd love to hear what you think!

[ibolmo]

Hi @charmaine! This is really neat. Could you share if there's a way that we can keep that template up to date via CI/CD?

[charmaine]

Great question! We can definitely do CI/CD. What are you looking to solve with it?

1. Sync the TypeScript snippet in your README to Val Town
2. Detect errors to the Val Town code snippet when you push SDK version updates

We're happy to build CI/CD workflow for you either way! We could have the output directly in the PR, or send it to our shared Slack channel so we can collab on patching it ASAP.

What are you thinking? Also happy to jump on a call to hash out details if that's faster.

[ibolmo]

Yeah indeed, it's so we can have control of the template and avoid drift should things change. For now, if you don't mind sharing some docs so I can learn more about the process.

[charmaine]

The control part's easy - you can fork my val onto your Val Town account and update the badge to link to your val instead.

To avoid drift, the simplest thing would be a notification to remind you to update the val if the README TS code snippet changes. We could also build a one-way sync from the README to the val that you own, if you prefer.

Nobody's asked for this so far so there aren't specific docs about it, but we're happy to build whatever you need! Here are Val Town docs.

[charmaine]

Another idea: We can set you (and anyone else on the team) onto a Braintrust company account in Val Town. The val can be owned by that account. It would be similar to: https://www.val.town/u/mux

[ibolmo]

Thanks! I'll have a look at this by next week.

[charmaine]

Thanks @ibolmo, appreciate it!

[charmaine]

(Let us know if you have any questions while looking over it this week!) 🙏

[ibolmo]

(Let us know if you have any questions while looking over it this week!) 🙏

Will do! We've got a big push to finish something so likely Thur/Fri.

[ibolmo]

@charmaine thanks again for getting this going. I think for us to proceed, I'd like to ask if you all could have a tooling to
use plain files like

sdk/
	integrations/
		val.town/
			README.md
			code.ts

This way on merging main we run something like val update sdk/integrations/val.town. Perhaps we'd need to have an environment variable for the API key set, but that is doable via Github Cl.

I see that you all have a update val endpoint so I think it's doable to try to keep the val up to date as we merge changes.

Is there something like that existing or something the team would like to create? Maybe as a cli in or on top of the SDK?

[charmaine]

@ibolmo Yes definitely! If I'm understanding correctly, calling the API is probably the most straightforward way. I just tested something like this in my fork and it successfully keeps the README and the Val Town code snippet synced.

on:
  pull_request:
  push:
    branches: [main]

jobs:
  trigger_val:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Update val
        env:
          BEARER_TOKEN: ${{ secrets.VAL_TOWN_API_KEY }}
          VAL_ID: "8d826fa8-ec8b-11ef-a782-e6cdfca9ef9f"
          FILE_PATH: "README.md"
        run: |
          # 1. Extract the TypeScript code block between ```typescript and ```
          awk '/^```typescript$/,/^```$/ {
            if ($0 != "```typescript" && $0 != "```") print
          }' "$FILE_PATH" > temp_code.ts

          # 2. Patch all imports to prepend "npm:" if not already present
          sed -i '/import .* from "npm:/!s|\(import .* from "\)\([^"]*\)"|\1npm:\2"|g' temp_code.ts
          
          # 3. Read the extracted (patched) content and convert it to a JSON string
          FILE_CONTENT=$(cat temp_code.ts | jq -R -s .)

          echo "Syncing TypeScript starter code to Val Town"
          curl -X POST "https://api.val.town/v1/vals/$VAL_ID/versions" \
            -H "Authorization: Bearer $BEARER_TOKEN" \
            -H "Content-Type: application/json" \
            -d "{\"code\": $FILE_CONTENT}"

          # 5. Clean up
          rm temp_code.ts

You should be able to use this after you:

• Fork the starter val to your account (or a @braintrust Val Town account with your email as one of the associated addresses)
• Swap out the VAL_ID in js.yml here to your forked val's ID
• Get a Val Town API token with read write access to the val and add it to your GitHub Actions Secrets

The only callout here is that Val Town take npm imports with the npm: prefix, so I patched it directly in the GitHub action yml.

Let me know if this works! Also happy to hop on a call if that's easier. Thanks for your time!

[ibolmo]

Thank you @charmaine would be nice to avoid all that custom code in the action, but I get it :D

I'll come back to get this going likely next week. Thanks for your patience. Between travel and recent flu it's been tough to wrap this up for you all.

[charmaine]

@ibolmo Ah hope you're feeling better! Definitely take your time. Appreciate you for doing this at all! :)

[charmaine]

Bumping this here just in case! (But no rush :))

[ibolmo]

Yep just trying to catch up while I was out last week. I'll get it done for sure 😄