Kiln for VS Code

Open a project you built in Kiln in your editor, work on it with your own tools, and push it back as a new version — without leaving the window.

Getting started

The shortest way in is Open in VS Code, in the ⋯ menu on any project in your Kiln dashboard: it brings you here, asks where to put the folder, and downloads it. Everything below is the manual route, and works just as well.

1. ⌘⇧P / Ctrl+Shift+P → Kiln: Sign in… — paste an access token (make one on the website: account menu → Access tokens), or use your email and password. The token is worth the extra minute: it is named, can expire, and can be revoked on its own, so a lost laptop costs you the laptop rather than the account.
2. Kiln: Open a project… — pick a project, pick a folder
3. It downloads and opens as an ordinary folder: your pages, styles/, scripts/, a README.md and a package.json

It is a real static site, not an export you can only look at. npm run dev in that folder serves it.

1. Edit anything. Save. Then Kiln: Push this project — or click the status bar.

That's the whole loop. What you push shows up in the browser immediately, as a version, so Undo in the site's history reaches it like any other edit.

Asking instead of typing

Kiln: Ask the assistant… opens a panel beside your files. Say what you want changed in ordinary words. It reads the project first — including which files are shared between pages, which is the difference between a tweak and an accidental redesign — then proposes an edit.

Nothing is stored until you accept it. Click a changed file to read it as a real diff against what is stored; accept, and it lands as one version with one label, through the same door your own pushes go through. Your folder is then a version behind, and it offers to pull.

The conversation lives on the server, not in the panel, so it is the same thread in the browser and in the editor — and closing the panel mid-answer costs nothing. Re-open it and the answer is still arriving.

The dropdown in the panel's header chooses which model answers. It lists only what your Kiln can actually reach, so there is nothing in it that fails when you pick it, and your choice is remembered for every project.

Any other folder: straight to the model, on your own keys

Everything above describes a Kiln project — a folder you pulled, where edits are staged, versions are kept, and the server's loop does the work. Guardrails are the product there.

Kiln: Ask the assistant… in any other folder is a different thing entirely, and it is worth being clear about how different:

• It talks directly to the vendor on an API key stored in this editor. The Kiln server is not in the path at all, and nothing you say or send reaches it. Set a key with Kiln: Set a model API key… — it goes into VS Code's SecretStorage, never to disk in plain text and never into a log.
• There is no staging and no accept step. It writes and edits real files immediately, and it runs shell commands you did not individually approve. That is the point of the mode, and it is the whole safety story too: treat it like a terminal somebody else is typing in, and use it on folders where that is what you want.
• There are no ceilings. No round cap, no token limit, no timeout on a command — only the vendor's own limits and your own key's balance.
• What you get instead is visibility and a Stop button. Every tool call appears as it happens, the running cost of the session is in the header, and Stop aborts the request in flight, ends the loop, and kills whatever command is running.
• Nothing is persisted. Close the panel and the conversation is gone.

Which mode you get is decided by the folder: a .kiln/manifest.json (in the folder, or one or two levels inside it) means the Kiln assistant; anything else means this.

Commands

The status bar shows the project, its version, and how many files you have changed. Click it to push when there is something to push, and to see the changes when there is not.

What it will not do to you

Push is a version, never an overwrite. Undo in the browser reaches it, and so does Kiln: History… here.

You can read a change before you send it. The push box has a diff button, and the comparison is against what is stored right now rather than the copy you pulled — those differ exactly when somebody else has been working, which is the one time it matters.

Going back does not throw anything away. The versions after the one you return to stay in the history.

It asks before it overwrites you. Pulling replaces the files on disk, so a pull over unsaved changes stops and says how many are at stake. The button that keeps your work is always the first one.

Every refusal offers the way through it. A version conflict, a missing file that would delete a page, a script that will not parse — each is a decision you're entitled to make, so each is a button rather than a wall. The override is never the default; a dialog answered by reflex should not be what discards work.

A compiled React tree cannot be pushed at all. Its pages are generated from the static source, so storing them back would overwrite the originals with the build. That one has no override, because there is no version of it that is what somebody meant.

The guards that decide what may actually be stored live on the server — not in this extension. It being wrong cannot damage a project.

Running your own Kiln

The extension talks to the hosted instance by default. If you run your own, set it in Settings → Extensions → Kiln, or:

// settings.json
"kiln.api": "https://your-instance/api/v2"

Developing this extension

It is the kiln command-line tool with a face on it. Literally: both are the same kiln-core, so kiln push in a terminal and Kiln: Push this project in the palette are one implementation, not two that agree for a while.

cd vscode
npm run package                              # builds kiln-vscode-<version>.vsix
code --install-extension kiln-vscode-*.vsix --force

npm run package copies cli/lib/ into lib/vendor/ first — a .vsix cannot reach outside its own folder, and duplicating the logic would defeat the point of having one core.

Tests

Two layers, because they answer different questions.

The decisions, in backend/tests/test-extension.js — what each refusal says, which buttons it offers, which one is safe, whether a pull may walk over your work. These are pure functions in lib/present.js and run with the rest of the backend suite.

The editor, in test/ — a real VS Code is downloaded, a real project is pulled into test-workspace/, and the commands are run inside it:

cd vscode
node ../backend/make-fixture.js            # prints the id of a throwaway project
node ../cli/kiln.js pull <that-id> test-workspace   # the suite runs INSIDE this folder
npm test

test-workspace/ is gitignored and does not exist in a fresh clone, so the pull is not optional — without it VS Code opens a folder that is not there and the suite dies reading a manifest rather than testing anything.

That covers the half that only an editor can answer: that activation happens on a pulled folder, that the commands are really registered, that editing a buffer and pushing from the palette lands a version on the server — and that a conflict and an unparseable script are both refused, with the override never the reflex answer.

There is a second, much faster suite that needs neither a fixture nor a signed-in CLI — it checks what a brand-new user meets:

npm run test:fresh

It existed for a while with nothing running it and nothing mentioning it, which is the same as not existing.

It needs a display and a backend on :5000. If you run it from inside VS Code, note that the extension host exports ELECTRON_RUN_AS_NODE=1; inherited, the VS Code being launched starts as plain Node and every flag comes back "bad option". test/runTest.js strips that and the VSCODE_* block before launching.