[{"data":1,"prerenderedAt":34},["ShallowReactive",2],{"doc:en:plugins\u002Fsdk":3},{"title":4,"lede":5,"html":6,"headings":7},"The SDK","@escouade-dev\u002Fplugin writes a plugin of Escouade in TypeScript: the protocol’s types, a client that speaks it, inside Escouade in WASM or under Node, a fake Escouade for the plugin’s tests, and the escouade-plugin command. It is under the MIT license, like the protocol’s schema, and depends on nothing.","\u003Ch2 id=\"a-first-plugin\">A first plugin\u003C\u002Fh2>\n\u003Cpre>\u003Ccode class=\"language-sh\">npm create escouade-plugin@latest my-plugin\ncd my-plugin\nnpm install\nnpm test            # its handlers, against the fake Escouade, in memory\nnpm run validate    # the manifest, field by field\nnpm run bench       # the conformance bench, on the real program\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>The command asks for the kind of plugin; \u003Ccode>--kind program\u003C\u002Fcode>, \u003Ccode>--kind rust\u003C\u002Fcode> or \u003Ccode>--kind declarative\u003C\u002Fcode> chooses without asking, \u003Ccode class=\"key\">--id\u003C\u002Fcode> and \u003Ccode class=\"key\">--name\u003C\u002Fcode> give its id and its name.\u003C\u002Fp>\n\u003Cul>\n\u003Cli>\u003Cstrong>A program\u003C\u002Fstrong> (\u003Ccode class=\"key\">program\u003C\u002Fcode>): a TypeScript plugin with its tests. \u003Ccode class=\"key\">src\u002Fplugin.ts\u003C\u002Fcode> says when a ticket is ready to test and refuses force pushes; \u003Ccode class=\"key\">src\u002Fmain.ts\u003C\u002Fcode> starts it; \u003Ccode>npm run build\u003C\u002Fcode> bundles both into \u003Ccode class=\"key\">dist\u002Fplugin.mjs\u003C\u002Fcode>, which \u003Ccode class=\"key\">run.js\u003C\u002Fcode> in the manifest names: Escouade runs it inside the app, in WASM, without Node.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>A module in Rust\u003C\u002Fstrong> (\u003Ccode class=\"key\">rust\u003C\u002Fcode>): the same plugin, on \u003Ca href=\"\u002Fen\u002Fdocs\u002Fplugins\u002Frust\u002F\">the Rust kit\u003C\u002Fa>, with its tests and its \u003Ccode class=\"key\">Cargo.lock\u003C\u002Fcode>. No \u003Ccode class=\"key\">package.json\u003C\u002Fcode>, no \u003Ccode class=\"key\">node_modules\u003C\u002Fcode>.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>A declarative plugin\u003C\u002Fstrong> (\u003Ccode class=\"key\">declarative\u003C\u002Fcode>): a theme, described in the manifest. Nothing runs.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>To try it in Escouade, load its folder in Settings › Plugins, in developer mode. Escouade runs a plugin as its repository holds it, without \u003Ccode>npm install\u003C\u002Fcode>: commit \u003Ccode class=\"key\">dist\u002F\u003C\u002Fcode> before you tag a version.\u003C\u002Fp>\n\u003Ch2 id=\"the-client\">The client\u003C\u002Fh2>\n\u003Cp>The \u003Ccode class=\"key\">program\u003C\u002Fcode> template, as \u003Ccode>npm create escouade-plugin\u003C\u002Fcode> writes it: what the plugin does, apart so that its tests drive it without a process,\u003C\u002Fp>\n\u003Cp>\u003Ccode>sdk\u002Fcreate-escouade-plugin\u002Ftemplates\u002Fprogram\u002Fsrc\u002Fplugin.ts\u003C\u002Fcode>\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-ts\">\u002F\u002F What the plugin does: its handlers, kept apart from main.ts so that the tests drive them without a process.\nimport { createPlugin } from '@escouade-dev\u002Fplugin';\n\nexport const plugin = createPlugin();\n\n\u002F\u002F A fact of permissions.events: a ticket changed columns (its data says from and to).\nplugin.onEvent('ticket.column', (fact, p) => {\n  \u002F\u002F A ticket's fact says its ticket; the fact's type, one for every fact, leaves it optional.\n  if (fact.data.to === 'review') p.log.info(`${fact.ticket?.key ?? ''} is ready to test (${fact.project?.name ?? ''})`);\n});\n\n\u002F\u002F A permission an agent asks for, before the user is asked (permissions.decide). Answer within 500 ms.\nplugin.decidePermission(({ request }) => {\n  const command = typeof request.input?.command === 'string' ? request.input.command : '';\n  if (request.kind === 'command' && \u002F\\bgit\\s+push\\b.*(--force\\b|\\s-f\\b)\u002F.test(command)) {\n    return { decision: 'deny', message: 'No force push in this team: push a new commit instead.' };\n  }\n  \u002F\u002F Leaves it to the user, as without the plugin.\n  return { decision: 'ask' };\n});\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>and the program, which \u003Ccode class=\"key\">run.js\u003C\u002Fcode> names once bundled into \u003Ccode class=\"key\">dist\u002Fplugin.mjs\u003C\u002Fcode>:\u003C\u002Fp>\n\u003Cp>\u003Ccode>sdk\u002Fcreate-escouade-plugin\u002Ftemplates\u002Fprogram\u002Fsrc\u002Fmain.ts\u003C\u002Fcode>\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-ts\">\u002F\u002F The program (run.js in escouade-plugin.json, once bundled): speaks the protocol to Escouade, which runs it inside the\n\u002F\u002F app in WASM; under Node too (the bench of escouade-plugin, a test), on stdin and stdout. start() finds which.\nimport { plugin } from '.\u002Fplugin.ts';\n\nvoid plugin.start();\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cdiv class=\"table\">\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Helper\u003C\u002Fth>\n\u003Cth>What it does\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\u003Ctr>\n\u003Ctd>\u003Ccode>onEvent(name, handler)\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Runs \u003Ccode class=\"key\">handler\u003C\u002Fcode> on each fact of \u003Ccode class=\"key\">name\u003C\u002Fcode>, or of a pattern ending in \u003Ccode class=\"key\">*\u003C\u002Fcode> (\u003Ccode class=\"key\">ticket.*\u003C\u002Fcode>), or of a list. The facts must be in \u003Ccode class=\"key\">permissions.events\u003C\u002Fcode>. A handler that fails goes to the plugin’s journal; the others still run.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>decidePermission(handler)\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Answers \u003Ccode class=\"key\">permissions\u002Fdecide\u003C\u002Fcode>: \u003Ccode class=\"key\">allow\u003C\u002Fcode>, \u003Ccode class=\"key\">deny\u003C\u002Fcode> with a \u003Ccode class=\"key\">message\u003C\u002Fcode>, or \u003Ccode class=\"key\">ask\u003C\u002Fcode>, which leaves it to the user. Without a handler, the answer is \u003Ccode class=\"key\">ask\u003C\u002Fcode>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode class=\"key\">secret(key)\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Asks Escouade for one of its secrets (\u003Ccode class=\"key\">secrets\u002Fget\u003C\u002Fcode>); \u003Ccode class=\"key\">null\u003C\u002Fcode> when none is kept. Another key rejects with the error \u003Ccode class=\"key\">-32001\u003C\u002Fcode>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode class=\"key\">settings(project?)\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Asks for its settings (\u003Ccode class=\"key\">settings\u002Fget\u003C\u002Fcode>); with a project’s id, those its \u003Ccode class=\"key\">.escouade.yml\u003C\u002Fcode> gives it (\u003Ccode class=\"key\">plugins.<id>\u003C\u002Fcode>) go first.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>log.debug\u002Finfo\u002Fwarn\u002Ferror(message)\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>A line of its journal (\u003Ccode class=\"key\">log\u003C\u002Fcode>).\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode class=\"key\">file(path)\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Reads a file of its folder as text (\u003Ccode class=\"key\">files\u002Fread\u003C\u002Fcode>), a subfolder included (\u003Ccode class=\"key\">data\u002Fwords.txt\u003C\u002Fcode>), 256 KB at most, under Node as in WASM: never its manifest, a hidden file or a path that leaves it (\u003Ccode class=\"key\">RpcError\u003C\u002Fcode> \u003Ccode class=\"key\">ERRORS.refused\u003C\u002Fcode>); a missing file fails with \u003Ccode class=\"key\">ERRORS.notFound\u003C\u002Fcode>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>fs.read\u002Ftext\u002Fwrite\u002Fstat\u002Flist\u002Fcanon(file)\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The folders of \u003Ccode class=\"key\">permissions.files\u003C\u002Fcode>, in WASM (\u003Ca href=\"\u002Fen\u002Fdocs\u002Fplugins\u002Fcalls\u002F#the-files\">the files\u003C\u002Fa>).\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>runProgram(params, onOut?)\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Runs a line of \u003Ccode class=\"key\">permissions.commands\u003C\u002Fcode>, in WASM: \u003Ccode class=\"key\">exited\u003C\u002Fcode>, \u003Ccode class=\"key\">write\u003C\u002Fcode>, \u003Ccode class=\"key\">close\u003C\u002Fcode>, \u003Ccode class=\"key\">kill\u003C\u002Fcode> (\u003Ca href=\"\u002Fen\u002Fdocs\u002Fplugins\u002Fcalls\u002F#the-programs-proc\">the programs\u003C\u002Fa>).\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>openStream(p, url, init?)\u003C\u002Fcode>, \u003Ccode>openSocket(p, url, headers?)\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Imported apart: a response read as it comes and a WebSocket, in WASM (\u003Ca href=\"\u002Fen\u002Fdocs\u002Fplugins\u002Fcalls\u002F#the-network\">the network\u003C\u002Fa>).\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>handle(method, handler)\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Serves another method (a later extension point). Throw \u003Ccode>new RpcError(code, message)\u003C\u002Fcode> to answer an error.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>onInitialize(handler)\u003C\u002Fcode>, \u003Ccode class=\"key\">onShutdown(handler)\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Runs at \u003Ccode class=\"key\">initialize\u003C\u002Fcode>, or before the answer to \u003Ccode class=\"key\">shutdown\u003C\u002Fcode> (800 ms at most: Escouade waits a second).\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>call(method, params)\u003C\u002Fcode>, \u003Ccode>notify(method, params)\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>A call or a notification to Escouade, typed for its methods.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode class=\"key\">start()\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Speaks the protocol to Escouade: to its WASM host when the app runs the plugin, on the standard input and output under Node (the bench, a test); the same code on both. Ends the plugin after \u003Ccode class=\"key\">shutdown\u003C\u002Fcode>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\u003C\u002Ftable>\u003C\u002Fdiv>\n\u003Cp>The client answers \u003Ccode class=\"key\">initialize\u003C\u002Fcode> with version 1 of the protocol, whatever is offered (Escouade stops a plugin that does not speak its own), serves batches, answers a method it does not know with \u003Ccode class=\"key\">-32601\u003C\u002Fcode>, and never writes anything but the protocol on its standard output: write your traces on the standard error, which goes to the journal.\u003C\u002Fp>\n\u003Ch2 id=\"the-types\">The types\u003C\u002Fh2>\n\u003Cp>The protocol’s types come from one schema, \u003Ca href=\"\u002Fschemas\u002Fplugin-protocol-1.json\">\u003Ccode>plugin-protocol-1.json\u003C\u002Fcode>\u003C\u002Fa>: its methods, the parameters and answers of each, their delays, the facts and the error codes. The SDK’s TypeScript is generated from it, the manifest’s types from \u003Ca href=\"\u002Fschemas\u002Fplugin-1.json\">\u003Ccode class=\"key\">plugin-1.json\u003C\u002Fcode>\u003C\u002Fa>, and Escouade’s tests hold the core to the same schema: a change on one side without the other fails the tests.\u003C\u002Fp>\n\u003Cdiv class=\"table\">\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Type\u003C\u002Fth>\n\u003Cth>What it is\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\u003Ctr>\n\u003Ctd>\u003Ccode class=\"key\">Fact\u003C\u002Fcode>, \u003Ccode class=\"key\">FactName\u003C\u002Fcode>, \u003Ccode class=\"key\">FACT_NAMES\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>A fact (\u003Ccode class=\"key\">events\u002Ffact\u003C\u002Fcode>): its name, its version, when, and the project, the ticket and the agent by their ids and names.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode class=\"key\">DecideParams\u003C\u002Fcode>, \u003Ccode class=\"key\">PermissionRequest\u003C\u002Fcode>, \u003Ccode class=\"key\">Decision\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>A permission to decide, and the answer.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode class=\"key\">InitializeParams\u003C\u002Fcode>, \u003Ccode class=\"key\">InitializeResult\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The handshake.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode class=\"key\">ToPlugin\u003C\u002Fcode>, \u003Ccode class=\"key\">ToEscouade\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Each method, its parameters and its answer, by direction.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode class=\"key\">TIMEOUTS_MS\u003C\u002Fcode>, \u003Ccode class=\"key\">DEFAULT_TIMEOUT_MS\u003C\u002Fcode>, \u003Ccode class=\"key\">ERRORS\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The delays of Escouade’s calls, and the error codes.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode class=\"key\">Manifest\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode class=\"key\">escouade-plugin.json\u003C\u002Fcode>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\u003C\u002Ftable>\u003C\u002Fdiv>\n\u003Cp>\u003Ccode>@escouade-dev\u002Fplugin\u002Fmanifest-check\u003C\u002Fcode> gives the checks of the manifest that the store and Escouade make: \u003Ccode class=\"key\">validate(manifest)\u003C\u002Fcode> and \u003Ccode>message(error, 'en')\u003C\u002Fcode>.\u003C\u002Fp>\n\u003Ch2 id=\"the-tests\">The tests\u003C\u002Fh2>\n\u003Cp>\u003Ccode>@escouade-dev\u002Fplugin\u002Ftesting\u003C\u002Fcode> gives a fake Escouade, in memory: it sends the plugin the same messages as the app and the bench, without starting a process.\u003C\u002Fp>\n\u003Cp>The template’s tests:\u003C\u002Fp>\n\u003Cp>\u003Ccode>sdk\u002Fcreate-escouade-plugin\u002Ftemplates\u002Fprogram\u002Ftest\u002Fplugin.test.ts\u003C\u002Fcode>\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-ts\">\u002F\u002F The plugin's handlers, driven by the SDK's fake Escouade, in memory. `npm run bench` plays the real program.\nimport assert from 'node:assert\u002Fstrict';\nimport { test } from 'node:test';\nimport { connect } from '@escouade-dev\u002Fplugin\u002Ftesting';\nimport { plugin } from '..\u002Fsrc\u002Fplugin.ts';\n\ntest('it speaks version 1 of the protocol', async () => {\n  const escouade = connect(plugin);\n  const hello = await escouade.initialize();\n  assert.equal(hello.protocolVersion, 1);\n});\n\ntest('a ticket moved to review is said in the journal', async () => {\n  const escouade = connect(plugin);\n  await escouade.initialize();\n  await escouade.fact('ticket.column', { ticket: { key: 'APP-7' }, data: { from: 'doing', to: 'review' } });\n  assert.deepEqual(escouade.logs, [{ level: 'info', message: 'APP-7 is ready to test (Banc)' }]);\n});\n\ntest('a force push is refused, the rest left to the user', async () => {\n  const escouade = connect(plugin);\n  await escouade.initialize();\n  const push = await escouade.decide({ request: { input: { command: 'git push --force origin main' } } });\n  assert.equal(push.decision, 'deny');\n  assert.equal((await escouade.decide()).decision, 'ask');\n});\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>\u003Ccode>fact(name, fields)\u003C\u002Fcode> sends a fact and waits for its handlers; \u003Ccode class=\"key\">decide(fields)\u003C\u002Fcode> asks for a decision; \u003Ccode class=\"key\">call\u003C\u002Fcode> and \u003Ccode class=\"key\">notify\u003C\u002Fcode> send anything else. The fields you give are merged over those of the bench (the project “Banc”, the ticket \u003Ccode class=\"key\">BEN-1\u003C\u002Fcode>, a \u003Ccode>npm test\u003C\u002Fcode> command). The fake keeps what the plugin logged (\u003Ccode class=\"key\">logs\u003C\u002Fcode>), the secrets it asked for (\u003Ccode class=\"key\">secretsAsked\u003C\u002Fcode>) and its traces; \u003Ccode class=\"key\">secrets\u003C\u002Fcode> gives their values, and a key outside them is refused, as in Escouade.\u003C\u002Fp>\n\u003Ch2 id=\"the-command\">The command\u003C\u002Fh2>\n\u003Cp>The SDK installs \u003Ccode class=\"key\">escouade-plugin\u003C\u002Fcode> in the plugin’s \u003Ccode class=\"key\">node_modules\u003C\u002Fcode>, for its npm scripts:\u003C\u002Fp>\n\u003Cdiv class=\"table\">\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Command\u003C\u002Fth>\n\u003Cth>What it does\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\u003Ctr>\n\u003Ctd>\u003Ccode>escouade-plugin validate [folder]\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Reads the manifest and says what is wrong, field by field, and checks that the programs of \u003Ccode class=\"key\">run\u003C\u002Fcode> are in the folder.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>escouade-plugin test [folder]\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ca href=\"\u002Fen\u002Fdocs\u002Fplugins\u002Ftesting\u002F\">The conformance bench\u003C\u002Fa>: Escouade’s own.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>escouade-plugin dev [folder]\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ca href=\"\u002Fen\u002Fdocs\u002Fplugins\u002Ftesting\u002F#the-fake-escouade\">The fake Escouade\u003C\u002Fa>: facts, decisions and calls you type, to a running program.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>escouade-plugin pack [folder]\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The plugin’s archive and its SHA-256.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>escouade-plugin build [folder]\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Compiles \u003Ccode class=\"key\">run.js\u003C\u002Fcode> or \u003Ccode class=\"key\">run.wasm\u003C\u002Fcode> to WASM, as the store does: \u003Ccode>packs\u002F<id>-<version>.wasm\u003C\u002Fcode> and its \u003Ccode class=\"key\">.sha256\u003C\u002Fcode>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>escouade-plugin fetch [folder]\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Downloads the dependencies of a \u003Ccode class=\"key\">run.wasm\u003C\u002Fcode> from crates.io, running nothing of the plugin.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\u003C\u002Ftable>\u003C\u002Fdiv>\n\u003Cp>\u003Ccode class=\"key\">test\u003C\u002Fcode> and \u003Ccode class=\"key\">dev\u003C\u002Fcode> run the \u003Ccode class=\"key\">escouade-plugin\u003C\u002Fcode> that ships with Escouade, so that a plugin is judged by the bench of the app: the one of \u003Ccode class=\"key\">ESCOUADE_PLUGIN_BIN\u003C\u002Fcode>, else the one on the \u003Ccode class=\"key\">PATH\u003C\u002Fcode>, else the app’s (\u003Ccode>%LOCALAPPDATA%\\Escouade\u003C\u002Fcode> on Windows, \u003Ccode class=\"key\">Escouade.app\u003C\u002Fcode> on macOS, \u003Ccode class=\"key\">\u002Fusr\u002Fbin\u003C\u002Fcode> with the \u003Ccode class=\"key\">.deb\u003C\u002Fcode>). Without one, the command says where to get it.\u003C\u002Fp>\n\u003Ch3 id=\"the-archive\">The archive\u003C\u002Fh3>\n\u003Cp>\u003Ccode>escouade-plugin pack\u003C\u002Fcode> writes \u003Ccode>packs\u002F<id>-<version>.tar.gz\u003C\u002Fcode> and its \u003Ccode class=\"key\">.sha256\u003C\u002Fcode>, with every file of the folder but \u003Ccode class=\"key\">.git\u003C\u002Fcode>, \u003Ccode class=\"key\">node_modules\u003C\u002Fcode> and \u003Ccode class=\"key\">packs\u003C\u002Fcode>. The archive is the same, to the byte, from the same files, on any system: the dates are zeroed, and the programs of \u003Ccode class=\"key\">run\u003C\u002Fcode> and the scripts that start with \u003Ccode class=\"key\">#!\u003C\u002Fcode> are executable. A symbolic link, or an archive past 50 MB, is refused, as by the store.\u003C\u002Fp>\n\u003Cp>\u003Ccode>--target windows-x64\u003C\u002Fcode> (or \u003Ccode class=\"key\">macos-arm64\u003C\u002Fcode>, \u003Ccode class=\"key\">linux-x64\u003C\u002Fcode>…) names the archive of one system, \u003Ccode><id>-<version>-windows-x64.tar.gz\u003C\u002Fcode>.\u003C\u002Fp>\n\u003Ch2 id=\"without-node\">Without Node\u003C\u002Fh2>\n\u003Cp>A plugin in JS or TypeScript ships as its bundle, named by \u003Ccode class=\"key\">run.js\u003C\u002Fcode>:\u003C\u002Fp>\n\u003Cp>\u003Ccode>sdk\u002Fcreate-escouade-plugin\u002Ftemplates\u002Fprogram\u002Fescouade-plugin.json\u003C\u002Fcode> (excerpt)\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-json\">  "run": { "js": "dist\u002Fplugin.mjs" },\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>Escouade runs it \u003Cstrong>inside the app, in WASM\u003C\u002Fstrong>, with no Node on the user’s machine: one isolated instance per plugin, which keeps its state from one call to the next like a process. The store compiles the bundle when it is submitted, and the app downloads that module and checks it against the version’s \u003Ccode class=\"key\">version.json\u003C\u002Fcode>; a plugin installed from a folder or a git repository is compiled by the app. The install window says “Runs inside Escouade, isolated”, and \u003Ccode class=\"key\">permissions.network\u003C\u002Fcode> is enforced there: \u003Ccode class=\"key\">fetch\u003C\u002Fcode> goes through Escouade, over https, to those hosts only (see \u003Ca href=\"\u002Fen\u002Fdocs\u002Fplugins\u002Fapi\u002F#a-program-in-wasm\">the protocol\u003C\u002Fa>).\u003C\u002Fp>\n\u003Cul>\n\u003Cli>\u003Cstrong>The same code on both transports\u003C\u002Fstrong>: \u003Ccode class=\"key\">start()\u003C\u002Fcode> speaks to Escouade’s WASM host when the app runs the plugin, on standard input and output under Node (its tests, a plugin started by a command). A plugin written for the SDK runs unchanged on both sides.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Its files\u003C\u002Fstrong>: \u003Ccode>readFileSync(new URL('..\u002Frules.json', globalThis._importMeta_.url), 'utf8')\u003C\u002Fcode> still reads a JSON file at the root of its folder; \u003Ccode class=\"key\">p.file()\u003C\u002Fcode> reads the others. The standard \u003Ccode class=\"key\">fetch\u003C\u002Fcode> serves the network, through Escouade in WASM.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>What the bundle may import\u003C\u002Fstrong>: \u003Ccode class=\"key\">node:fs\u003C\u002Fcode> and \u003Ccode class=\"key\">node:readline\u003C\u002Fcode>, which Escouade serves, and nothing else; it is one file, without \u003Ccode class=\"key\">export\u003C\u002Fcode>. Any other \u003Ccode class=\"key\">import\u003C\u002Fcode> fails its compilation, and \u003Ccode>escouade-plugin validate\u003C\u002Fcode> says so in your language (“the bundle imports node:child_process, which a plugin in WASM does not have (only node:fs, node:readline)”). \u003Ccode class=\"key\">setTimeout\u003C\u002Fcode> and \u003Ccode class=\"key\">clearTimeout\u003C\u002Fcode> exist there.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>SDK 0.3 or later\u003C\u002Fstrong>: a bundle made with SDK 0.2 does not run in WASM; rebuild it (\u003Ccode>npm run build\u003C\u002Fcode>).\u003C\u002Fli>\n\u003Cli>\u003Cstrong>The tools, without Node\u003C\u002Fstrong>: \u003Ccode>escouade-plugin build\u003C\u002Fcode> makes the module as the store does, to check that it compiles; \u003Ccode class=\"key\">test\u003C\u002Fcode> and \u003Ccode class=\"key\">dev\u003C\u002Fcode> play the bundle in WASM, in the app’s host. The Javy that compiles it (9.1.0) is downloaded the first time it is needed into \u003Ccode class=\"key\">~\u002F.escouade\u002Ftools\u003C\u002Fcode> and checked by its hash; the app and \u003Ccode class=\"key\">escouade-plugin\u003C\u002Fcode> share it. Node only serves the author, for \u003Ccode>npm run build\u003C\u002Fcode> and the plugin’s tests; whoever installs it never needs it. No more need to make it an executable (\u003Ccode>deno compile\u003C\u002Fcode>, \u003Ccode>bun build --compile\u003C\u002Fcode>) for people without Node.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>What the plugin can ask for on top\u003C\u002Fstrong>: \u003Ccode class=\"key\">p.fs\u003C\u002Fcode> for the folders of \u003Ccode class=\"key\">permissions.files\u003C\u002Fcode>, \u003Ccode class=\"key\">p.runProgram\u003C\u002Fcode> for the programs of \u003Ccode class=\"key\">permissions.commands\u003C\u002Fcode>, \u003Ccode class=\"key\">openStream\u003C\u002Fcode> and \u003Ccode class=\"key\">openSocket\u003C\u002Fcode> for the network (see \u003Ca href=\"\u002Fen\u002Fdocs\u002Fplugins\u002Fcalls\u002F\">the calls\u003C\u002Fa>). The store no longer publishes a \u003Ccode class=\"key\">run.command\u003C\u002Fcode>.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Ch2 id=\"in-ci\">In CI\u003C\u002Fh2>\n\u003Cpre>\u003Ccode class=\"language-yaml\">jobs:\n  plugin:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions\u002Fcheckout@v4\n      - uses: actions\u002Fsetup-node@v4\n        with: { node-version: 22 }\n      - run: npm ci\n      - run: npm run typecheck && npm test && npm run build\n      - run: npx escouade-plugin validate .\n      # The bench comes with Escouade: install its .deb, or give the path of its escouade-plugin.\n      - run: npx escouade-plugin test .\n        env:\n          ESCOUADE_PLUGIN_BIN: \u002Fusr\u002Fbin\u002Fescouade-plugin\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>Escouade’s CI does the same on the templates of \u003Ccode>npm create escouade-plugin\u003C\u002Fcode>, against the bench of each build.\u003C\u002Fp>\n",[8,12,15,18,21,24,28,31],{"id":9,"text":10,"depth":11},"a-first-plugin","A first plugin",2,{"id":13,"text":14,"depth":11},"the-client","The client",{"id":16,"text":17,"depth":11},"the-types","The types",{"id":19,"text":20,"depth":11},"the-tests","The tests",{"id":22,"text":23,"depth":11},"the-command","The command",{"id":25,"text":26,"depth":27},"the-archive","The archive",3,{"id":29,"text":30,"depth":11},"without-node","Without Node",{"id":32,"text":33,"depth":11},"in-ci","In CI",1793889382344]