Working without Node: kits, preview and build from the sidebar

[fcapolini]

Markout is pitched at people who write HTML — designers who code, backend
developers with a templating layer they'd rather not have, anyone maintaining a
server-rendered app. Almost none of them have Node, and none of them want it.

As of markout-vscode 0.6.1, none of them need it. Install the extension, open
a folder of HTML files, and the Markout view in the activity bar installs
kits, previews your pages and builds your site. There is no terminal in that,
and no npm.

Write-up: docs/design/without-node.md
· the page for somebody using it: the Markout
sidebar

The gap this closes

Kits were the gap. A kit is an npm package, so installing one meant having npm.
There was a fallback for the no-project case that asked npm root -g, and it
did not work for the audience it was built for: the language server is a child
of the extension host, an editor launched from the Dock has a PATH with no
Homebrew, nvm, fnm or volta in it, and a Mac with two npms has two global roots
where npm root -g answers truthfully about the wrong one. Every failure looked
the same — no kits, silently, and a page reporting every tag the kit defines as
unknown.

So the mechanism built for the non-npm audience required npm, on a PATH they
do not have, in a copy that might not be the one that answers.

What is there now

Kits, with checkboxes. Tick one and it is fetched and pinned; untick it and
it goes. No npm is involved and none is needed — a kit is .htm and CSS,
fetched over HTTPS and checked against the checksum the registry published.
Markout's own kits are offered first; searching the whole registry is a separate,
deliberate step, because a kit's code compiles into every page that imports it.

Preview serves your pages and reloads as you save. It runs on the copy of
Node your editor is already running, so nothing looks for node on a PATH and
nothing has to be there. Build writes the finished site to dist/.

Updates are offered, never applied. A newer version shows as 1.0.0 → 1.1.0
with accept and decline beside it, declining is remembered for that version, and
the number still waiting is a badge on the icon rather than a notification for a
thing nobody has to act on today.

Installed kits go in .markout/kits/, in the project, resolved by the
compiler. discoverKits already walked up looking for node_modules
directories, so this is one more rung on a walk that existed — which means the
CLI gets it for free, and a build driven from the sidebar is reproducible by
hand with markout build. The extension only ever fetches; it never resolves.
That is the property that matters: the editor cannot be more permissive than
the build.

Two alternatives lost. npm i -g behind a checkbox builds the no-npm experience
on npm, and puts a machine-wide toggle in a per-project sidebar. A store the
extension owns under globalStorageUri is one the CLI cannot read, so
diagnostics go green on pages that will not build — found at deploy rather than
while typing.

The boundary, stated plainly

The sidebar builds pages that render in the browser, and it does not render on
a server. Both buttons work in that one delivery mode: Build compiles and
stops, Preview serves exactly what Build writes. Of Markout's three ways to
deliver a
page,
this is the third.

That follows from the premise rather than being a limitation. Prerendered and
served are both a render, and a render is Node executing your page — so a
button offering either would be offering something its user cannot deploy, and
would run a kit's code on their machine to do it.

The loss that is real is content in the HTML for a crawler that will not run
JavaScript. markout prerender is the answer, and it wants Node on the machine
that runs the build — a CI job will do, and it does not have to be yours.

The part we didn't expect

Kits are small enough to commit. bootstrap-kit is 164 KB and std-kit is
28 KB — .htm and CSS, text that diffs, no native binaries, no postinstall. A
project that checks .markout/kits/ into git has no install step at all:
clone, open, works, offline, and it keeps working when a registry does not.
Nobody commits node_modules, so this option does not exist for any of the
frameworks we benchmark against.

It is not the default, for the reason below. Deleting one line from
.markout/.gitignore is the whole opt-in.

The open questions, answered

The six this proposal opened with all have answers now, and the reasoning is in
the design doc:

1. Pins, not ranges. A range lets two clones of one repository build two
   different things, which is the failure this audience is least equipped to
   diagnose. A range in kits.json is refused with an error naming the rule,
   rather than resolved silently. Bumps are offered one click at a time instead.
2. Committing .markout/kits/ is supported, documented, and nobody's
   default. This follows from pinning rather than competing with it: a pin
   plus markout restore already makes a clone deterministic, which was the
   property committing was going to buy. What it gives up is clone, open,
   works, offline becoming clone, restore, works, offline — and a shared
   download cache under ~/.markout/cache makes every project after the first
   offline again.
3. kits.json lists kits and nothing else, initially — under a kits key
   rather than as the file's whole content, so the next thing the project wants
   to record does not need the format to change shape.
4. markout restore exists. It is the one command the whole arrangement
   needs from a terminal, and it needs Node only on the machine that runs it.
5. markout add <kit> exists too, so the CLI does write .markout/. The
   alternative was a manifest only the sidebar could satisfy, which puts CI in
   the position of being unable to build a clone. The installer itself lives in
   the CLI behind a subpath the extension imports, so the checkbox and the
   command cannot drift.
6. Unticking a kit a page still imports is refused, and the refusal names
   the pages.

One thing not on that list turned out to be the largest single improvement to
the onboarding path, and it is a consequence of the manifest rather than of the
sidebar. A missing kit used to report "unknown tag <bs-navbar>" — unactionable
for somebody who has never installed a package. Now the compiler knows the
difference between a tag nobody declared and a tag belonging to a kit the
project asked for and has not got, and says so:

kit "@markout-lang/bootstrap-kit" is declared in ".markout/kits.json" and is
not installed -- run "markout restore" to fetch what the manifest asks for

That is the compiler's message, so the editor, markout build and CI all say
it.

What would help

If you are in the no-Node group this was built for: install it, tick a kit, and
tell us whether it worked on your machine. That is the report we cannot produce
ourselves, and every failure mode above was discovered by somebody's machine
behaving differently from ours.

And if you have built editor tooling that installs things on a user's behalf,
we'd still like to hear where it went wrong for you.