Headless · @kition/script
Edit pro files with no UI
The same engines as the editors, in a script or on a server: open a file, edit it through typed objects, check it, save it. Headless is free, no key.
Copy for AI
import { openHeadless } from '@kition/script/node'
import '@kition/script/kits/note'
const file = await openHeadless(
process.env.KITION_KIT_NOTE_BINARY!,
'Review.md',
)
const note = await file.model()
// ... edit through typed proxies, then:
await file.save()
await file.shutdown()$ KITION_KITS=…/kition-kits \
KITION_KIT_NOTE_BINARY=…/kition-note \
node examples/sdk-scripts/run-headless.mjs
{
"heading": "Q3 Quarterly review",
"level": 2,
"task": {
"text": "Share the revenue numbers",
"checked": true
},
"text": "# Team notes\n\nRevenue grew in the north.\n…- [x] Share the revenue numbers\n"
}
saved and reopened headless: {"headings":["Team notes",
"Q3 Quarterly review"],"tasks":[{"text":
"Share the revenue numbers","done":true}]}How it works
01- Your scriptopenHeadless(binary, file)
From @kition/script/node. It starts kition-kits serve with the kit and hands you the document’s object model.
- The kitkition-<kit>, with no window
Each kit has a native executable that opens, edits, renders and saves its files. It speaks the Kit Process Protocol over a private socket, with a fresh token per launch, and reaches files only through its host.
- Your filesOne workspace folder
The kit writes a file only when asked to save. Or load the kit’s WebAssembly engine in Node itself, with openKitPackage.
The calls that matter
02openHeadless(binary, file, options)Starts kition-kits serve with the kit’s executable and opens the file; a file that does not exist yet is created for its extension.openKitPackage(dir)Loads a kit package’s WebAssembly engine in Node: open(name, bytes), create(name).file.model({ origin })The document as typed objects, with the origin its changes carry.doc.describe()The object model and every command the kit offers.doc.run(async (context) => …)Load, edit and context.sync(): one batched change per sync; context.commands.run for commands with domain logic.file.save() · saveAs()Writes the file; nothing is written until you ask.file.shutdown()Stops the kit process.import '@kition/script/kits/<kit>'Typings per published kit, generated from its schema (@kition/script/kits/note today).
A complete example
03One script, quarterlyReview, adds a review section with a task to a note, puts “Q3” before its heading and checks the task off. The SDK runs it headless on the Note kit, saves, and reads the file back in a new kit process.
/** Adds a review section with a task, puts "Q3 " before its heading, and checks the task off. */
export async function quarterlyReview(note) {
return note.run(async (context) => {
// A command with domain logic: the kit appends a section at the end of the note.
context.commands.run('block.append', {
markdown: '## Quarterly review\n\n- [ ] Share the revenue numbers',
})
const root = context.root
root.load(['body'])
await context.sync()
// ... find the section, insert "Q3 " before its heading,
// check its task off, then sync
})
}import { openHeadless } from '@kition/script/node'
import { quarterlyReview } from './review.mjs'
// kition-note, reached through kition-kits serve (KITION_KITS)
const file = await openHeadless(binary, path, { stderr: 'inherit' })
let done
try {
const note = await file.model({
origin: { kind: 'extension', principal: 'example:quarterly-review' },
})
const described = await note.describe()
assert.equal(described.capability, 'KitObjectModel 1.0')
assert.equal(described.root, 'Note')
assert.ok(described.commands.some((command) => command.id === 'block.append'))
done = await quarterlyReview(note)
assert.equal(done.heading, 'Q3 Quarterly review')
await file.save()
} finally {
await file.shutdown()
}
// The kit took the edits: they are in the saved file,
// which a new kit process reads.
assert.equal(readFileSync(path, 'utf8'), done.text)
const again = await openHeadless(binary, path, { stderr: 'inherit' })The same script runs in a page, in Node, and headless. In a page it runs through editor.document(); here through the kit’s WebAssembly engine.
import { openKitPackage } from '@kition/script/node'
const notes = await openKitPackage(join(kits, 'note-ui'))
const file = notes.create('Review.md')
const note = await file.model()
const done = await quarterlyReview(note)
const bytes = file.save()Limits and requirements
04- The bundle carries the executables built for its platform in
bin/<platform>/; you can also build them from each kit’s repository (cargo build -p kition-<kit>).openHeadlessalso needskition-kits(KITION_KITS, or on thePATH). - Files are confined to the workspace: nothing outside it, nothing hidden, no link out of it.
- A kit writes a file only when asked to save, and a save commits only while the file is the version the kit read (
file_conflictotherwise); a read-only open refuses writes. - Failures carry a stable reason (
KitProtocolError.reason, the object model’sBatchError).
- Headless is free, no key.
- The same script runs in a page, in Node, and headless.
Give an agent the same kits over MCP: Kits for agents.
See the editors these engines powerScript the files your product handles
npm i @kition/script