Blackbox

    Turn an app you already have into a CloudCrane app spec, on your own machine, with none of your code in it.

    Blackbox is our free, open-source tool (MIT) for developers. It turns an app you already have into a CloudCrane app spec: a description of the app with none of its code in it, which builds into the same app every time.

    • It runs on your machine. It reads your code, never runs it, and sends nothing anywhere.
    • The spec holds the app’s look, screens, rules, saved data and journeys. No source code, no file paths.
    • The compiler writes no code and uses no AI: the same spec builds the same page, byte for byte. CloudCrane builds with the same compiler, so what you preview is what people install.

    Use it

    You need Node 22.5 or later. From your app’s folder:

    1. npx @cloudcrane/blackbox extract . --hints blackbox.hints.json --out blackbox
      Write the spec, from your code and your hints.
    2. npx @cloudcrane/blackbox validate blackbox/spec.json
      Check it.
    3. npx @cloudcrane/blackbox build blackbox/spec.json --out app.html
      Build the app's page: the same bytes every time.
    4. npx @cloudcrane/blackbox preview blackbox/spec.json
      See the app as people will, on your machine.

    The code is on GitHub and the package on npm. To see what each step does, watch it on the Blackbox page.

    More detail

    What a spec holds
    • Its look: design tokens (DTCG): colours by role, type, radius.
    • Its screens: A2UI components, bound to the app’s data.
    • Its rules: CEL expressions, with worked examples they must give.
    • What it saves: the shape of the data kept on the phone, and its data version.
    • What it promises: its journeys (what a person does, step by step) and its promises, with the tests that prove them.
    What it reads from your code today
    • Flutter themes: the colours, by role.
    • Pure TypeScript functions, translated into CEL rules, and the literal examples in their tests.

    Everything else (the screens, the saved data, the journeys) comes from your blackbox.hints.json.

    blackbox.hints.json

    Where things are in your code, and the parts Blackbox can’t read yet, written as spec parts:

    • module: the app’s name and what it’s for.
    • theme: your theme file, light or dark, and which of its colours sets which role.
    • rules: the files with your pure functions, and the tests with their examples.
    • surface, data, journeys: the screens, what the app saves, and what a person does in it.
    • Optional: extra tokens, rules, promises, tests, and the sites the app talks to.

    It names your files, so keep it to yourself.

    What stays with you

    extract writes three files. spec.json is the one you share.

    • provenance.json: every part of the spec, pointed at the lines of your code it came from.
    • report.md: what was read from your code and what came from your hints.

    Both name your files, so keep them, and your hints, to yourself.

    The checks
    • extract: refuses a spec that carries code or file paths, or copies your source.
    • validate: checks the schema, the A2UI screens, the rules against their examples, and for leaked code.
    • preview: serves the app on your machine under CloudCrane’s security policy, as a phone gets it.
    When your code changes

    diff lists the parts of the spec whose cited code changed, so you know what to look at again:

    npx @cloudcrane/blackbox diff . --range main..HEAD
    Publishing it

    Give spec.json to your assistant once it’s connected to CloudCrane. It publishes it with publish_spec, and changes it later with update_spec. CloudCrane builds it with the same compiler, and keeps the spec with the version, so anyone can rebuild the same page from it.

    Code a spec can't describe

    What the screens can’t draw, like a game on a canvas, can be the spec’s own code: a coded component, run in a sandboxed frame, given only the inputs it declares. A whole HTML app can be one too. The install screen says so: “Custom code, sandboxed”.

    Need a hand? Read the FAQs or contact us.