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
script.ts · from docs/sdk/script.md
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()
output · examples/sdk-scripts/run-headless.mjs
$ 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
  1. Your scriptopenHeadless(binary, file)

    From @kition/script/node. It starts kition-kits serve with the kit and hands you the document’s object model.

  2. 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.

  3. 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

02

A complete example

03

One 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.

kition-sdk · examples/sdk-scripts
review.mjs
/** 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
  })
}
run-headless.mjs
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 in Node, with no executable

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.

run-node.mjs · 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>). openHeadless also needs kition-kits (KITION_KITS, or on the PATH).
  • 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_conflict otherwise); a read-only open refuses writes.
  • Failures carry a stable reason (KitProtocolError.reason, the object model’s BatchError).
  • 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 power

Script the files your product handles

npm i @kition/script