Make `npm init @google-labs/breadboard` take an existing board and scaffold a working UI

[PaulKinlan]

@paullewis was showing me something today that I think should be the basis of create-breadboard

The create-breadboard npm-init script tries to set up an environment that has a useable UI and a useable board so that you can quickly experiment. To do that I copy an old version of breadboard-web, tweak it and remove some dependencies on kits that aren't public. It works...

My current hypothesis is that people won't want breadboard-web as their app base, it makes a lot of assumptions for testing boards (which is now solved by npx breadboard debug <board>) they will want all the bits set up like the Harness', looking more like a simple app that something like create-react-app might output.

There's a world where we have a UI tool that Paul is creating and a CLI npm init @google-labs/breadboard project-name --board=<url of board> and we just get a fully working app out the back

[dglazkov]

amazing.

[dglazkov]

There's something here, though I am not sure how to best structure it. I want both debugging and the UI to coexist somehow, right? What would be the flow for me to build a thing?

[paullewis]

I have an idea... Need to test the theory a bit, though. Watch this space 😁

[dglazkov]

I drew a sequence diagram of my current mental picture. It doesn't currently include the generated app UI. I will try to draw that next.

sequenceDiagram
    actor Dev
    participant npm
    Dev ->> npm: npm init @google-labs/breadboard
    participant CLI as Breadboard CLI
    npm ->> CLI: <sets up>
    participant TS as Recipe in TypeScript
    npm ->> TS: <creates a template for>
    TS ->> CLI: <reports change>
    participant JSON as Recipe as JSON
    CLI ->> JSON: <compiles TS to JSON>
    CLI -->> Dev: <ready to develop>
    Dev ->> npm: npm run dev
    npm ->> CLI: breadboard debug ./src/recipes
    participant IDE as Breadboard Debugger
    CLI ->> IDE: <starts>
    loop Development Loop
        CLI -->> Dev: <ready for debugging>
        Dev ->> IDE: <play with the recipe, spot bugs, etc.>
        Dev ->> TS: <make edits and save>
        TS ->> CLI: <reports change>
        CLI ->> JSON: <compiles TS to JSON>
        CLI ->> IDE: <reloads>
    end

[dglazkov]

Here's how I see the "Debug" <--> "App" integration, from developer perspective:

sequenceDiagram
    actor Dev
    participant npm
    Dev ->> npm: npm init @google-labs/breadboard
    participant CLI as Breadboard CLI
    npm ->> CLI: <sets up>
    participant TS as Recipe in TypeScript
    npm ->> TS: <creates a template for>
    TS ->> CLI: <reports change>
    participant JSON as Recipe as JSON
    CLI ->> JSON: <compiles TS to JSON>
    CLI -->> Dev: <ready to develop>
    Dev ->> npm: npm run dev
    npm ->> CLI: breadboard dev ./src/recipes
    participant IDE as Breadboard Debugger
    participant App as Generated App
    CLI ->> IDE: <starts>
    loop Development Loop
        CLI -->> Dev: <ready for debugging>
        Dev ->> IDE: <play with the recipe, spot bugs, etc.>
        Dev ->> IDE: click "See App"
        IDE ->> App: <switch view to "App">
        Dev ->> App: <try out the app>
        Dev ->> App: click "Debug"
        App ->> IDE: <switch view to "Debug">
        Dev ->> TS: <make edits and save>
        TS ->> CLI: <reports change>
        CLI ->> JSON: <compiles TS to JSON>
        CLI ->> IDE: <reloads>
    end

[dglazkov]

Okay. I maaay have gotten a bit crazy with mermaid sequence diagrams. But here's the entire flow the way I am imagining

sequenceDiagram
    actor Dev
    participant npm
    participant CLI as Breadboard CLI
    participant TS as Recipe in TypeScript
    participant JSON as Recipe as JSON
    participant IDE as Breadboard Debugger
    participant App as Generated App

    Dev ->> npm: npm init @google-labs/breadboard
    npm ->>+ CLI: <sets up>
    npm ->> TS: <creates a template for>
    TS ->> CLI: <reports change>
    CLI ->> JSON: <compiles TS to JSON>
    CLI -->>- Dev: <ready to develop>
    Dev ->> npm: npm run dev
    npm ->>+ CLI: breadboard dev ./src/recipes
    CLI ->>+ IDE: <starts>
    loop Development Loop
        CLI -->> Dev: <ready for debugging>
        Dev ->> IDE: <play with the recipe, spot bugs, etc.>
        Dev ->> IDE: click "See App"
        IDE ->> App: <switch view to "App">
        Dev ->> App: <try out the app>
        Dev ->> App: click "Debug"
        App ->> IDE: <switch view to "Debug">
        Dev ->> TS: <make edits and save>
        TS ->> CLI: <reports change>
        CLI ->> JSON: <compiles TS to JSON>
        CLI ->> IDE: <reloads>
    end
    Dev ->> IDE: Ctrl+C
    IDE -->>- CLI: <stop>
    CLI -->>- Dev: <ready to build>

    Dev ->> npm: npm run build
    npm ->>+ CLI: breadboard build ./src/recipes
    TS ->> CLI: <reports change>
    CLI ->> JSON: <compiles TS to JSON>
    participant Dist as Distributable Code
    CLI ->> Dist: <bundles App>
    CLI -->>- Dev: <ready to deploy>

    Dev ->> npm: npm run serve
    npm ->> npm: npm run build
    npm ->>+ CLI: breadboard serve ./src/recipes
    CLI ->> Dist: <serve distributable App locally>
    CLI -->>- Dev: <ready to deploy>

    Dev ->> npm: npm run deploy
    npm ->> npm: npm run build
    npm ->>+ CLI: breadboard deploy ./src/recipes
    CLI ->> Dist: <deploy distributable App>
    CLI -->>- Dev: <ready for the next thing>

[dglazkov]

Basically, I am seeing four breadboard commands so far (there's more obviously):

• breadboard dev -- sets up the development loop
• breadboard build -- builds an app as distributable code
• breadboard serve -- preview the built app
• breadboard deploy -- deploy the app as cloud function or static site

[paullewis]

Yeah that sounds grand. The challenge is what we do for breadboard build if you go ahead and customise it. We can generate something fresh for you, but I suspect ingesting a modified app would be a bit of a stretch?

[PaulKinlan]

I believe breadboard debug does the development loop you described.

[dglazkov]

I believe breadboard debug does the development loop you described.

Yes! I was trying out dev as a possible replacement, since it has both app view and debug view in it.

[dglazkov]

The challenge is what we do for breadboard build if you go ahead and customise it

yeah. /me scratches head.

[dglazkov]

I think it's time we rebuild create-breadboard to be based on breadboard debug. It should be super-thin at this point. Right?

[PaulKinlan]

I think we need to work out what we want from create-breadboard.

I can see a couple of different scenarios.

1) A place to quickly try recipes - you might need kits etc, so you probably need a full node js project directory. This arguably is just breadboard debug. create-breadboard gets you this kinda already in that you will have an empty project with a recipe in and the UI...

I would say that the above is not what the majority of developers building a web app and want to use breadboard will want. They will want something like a default vite app but with the UI hooked up a bit to get it running - I'm not sure we need the full breadboard debug experience other than a easy way to hand-off. I think we also need:

2) A tool to scaffold out a simple UI to get you started that starts with a decent UI with the tooling you already: (breadbunny?), React/Preact, Lit, Angular. 3) A tool to help you scaffold out a server-side based project.

[dglazkov]

There's one more scenario maybe: a place to quickly get started with building your own recipe. That's probably similar to the first item in your list -- and that's the one I need now (for [redacted] purposes).

[dglazkov]

It seems like we're very, very close here.

[dglazkov]

I tried it just now, and here's what I get:

$ npm init @google-labs/breadboard ./new-project 
node:internal/process/promises:289
            triggerUncaughtException(err, true /* fromPromise */);
            ^

[Error: ENOENT: no such file or directory, scandir '/Users/dimitriglazkov/.npm/_npx/5e3d4b126ca7fd63/node_modules/@google-labs/create-breadboard/assets'] {
  errno: -2,
  code: 'ENOENT',
  syscall: 'scandir',
  path: '/Users/dimitriglazkov/.npm/_npx/5e3d4b126ca7fd63/node_modules/@google-labs/create-breadboard/assets'
}

Node.js v20.5.0
npm ERR! code 1
npm ERR! path /Users/dimitriglazkov/Documents/code/fun/bb
npm ERR! command failed
npm ERR! command sh -c create-breadboard ./new-project

[dglazkov]

Declaring victory, splitting remaining work into #508