[{"data":1,"prerenderedAt":33},["ShallowReactive",2],{"doc:en:plugins\u002Fexamples":3},{"title":4,"lede":5,"html":6,"headings":7},"Example plugins","Five complete plugins to read, copy and install: a theme, a Discord webhook with no code, Slack and a team’s rules in TypeScript, and Goose, a harness described with no code. They are Escouade’s own plugins, on its store; each one passes the conformance bench on every change.","\u003Ch2 id=\"where-to-find-them\">Where to find them\u003C\u002Fh2>\n\u003Cp>They are in the \u003Ccode class=\"key\">plugins\u002F\u003C\u002Fcode> folder of Escouade’s repository, one folder per plugin (\u003Ccode class=\"key\">plugins\u002Fslack\u002F\u003C\u002Fcode>…), each readable on its own with its manifest, its README, its LICENSE (MIT), its CHANGELOG and its tests: \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fguillaume-gagnaire\u002Fescouade\u002Ftree\u002Fmain\u002Fplugins\" rel=\"noopener\">https:\u002F\u002Fgithub.com\u002Fguillaume-gagnaire\u002Fescouade\u002Ftree\u002Fmain\u002Fplugins\u003C\u002Fa>. The store publishes them as \u003Ccode>dev.escouade.high-contrast\u003C\u002Fcode>, \u003Ccode class=\"key\">dev.escouade.discord\u003C\u002Fcode>, \u003Ccode class=\"key\">dev.escouade.slack\u003C\u002Fcode>, \u003Ccode>dev.escouade.team-rules\u003C\u002Fcode> and \u003Ccode class=\"key\">dev.escouade.goose\u003C\u002Fcode>, taken from these folders at their tags \u003Ccode>plugins\u002F<folder>\u002Fv1.2.3\u003C\u002Fcode> (see \u003Ca href=\"\u002Fen\u002Fdocs\u002Fplugins\u002Fpublishing\u002F\">Publishing a plugin\u003C\u002Fa>).\u003C\u002Fp>\n\u003Cp>To make one yours, copy its folder and give it an id of your own (\u003Ccode>io.github.<your-login>.slack\u003C\u002Fcode>): \u003Ccode class=\"key\">dev.escouade.*\u003C\u002Fcode> is kept for Escouade’s own plugins, and the store takes it from Escouade’s repository alone.\u003C\u002Fp>\n\u003Cdiv class=\"table\">\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Example\u003C\u002Fth>\n\u003Cth>What it shows\u003C\u002Fth>\n\u003Cth>Kind\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\u003Ctr>\n\u003Ctd>High contrast\u003C\u002Ftd>\n\u003Ctd>A theme, dark and light, and a palette of project colors\u003C\u002Ftd>\n\u003Ctd>Declarative\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>Discord\u003C\u002Ftd>\n\u003Ctd>Tickets to review and agents waiting, in a Discord channel\u003C\u002Ftd>\n\u003Ctd>Declarative\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>Slack\u003C\u002Ftd>\n\u003Ctd>The same in Slack, in each project’s channel, with a secret in the keychain\u003C\u002Ftd>\n\u003Ctd>TypeScript program\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>Team rules\u003C\u002Ftd>\n\u003Ctd>The agents’ commands allowed or denied by a file of the repository\u003C\u002Ftd>\n\u003Ctd>TypeScript program\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>Goose\u003C\u002Ftd>\n\u003Ctd>An agent that speaks ACP, added as a harness\u003C\u002Ftd>\n\u003Ctd>Declarative\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>Linear\u003C\u002Ftd>\n\u003Ctd>A source of the Kanban, on the kit\u003C\u002Ftd>\n\u003Ctd>Rust module\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\u003C\u002Ftable>\u003C\u002Fdiv>\n\u003Cp>The code shown here is the repository’s: a test of the site checks it has not changed since.\u003C\u002Fp>\n\u003Cdiv class=\"callout note\">\u003Cp class=\"callout-title\">Note\u003C\u002Fp>\u003Cp>Slack and Team rules are \u003Ccode class=\"key\">run.js\u003C\u002Fcode> plugins since their 2.0.0: Escouade runs their \u003Ccode class=\"key\">dist\u002Fplugin.mjs\u003C\u002Fcode> inside the app, in WASM, with no Node on the machine (see \u003Ca href=\"\u002Fen\u002Fdocs\u002Fplugins\u002Fapi\u002F#a-program-in-wasm\">the protocol\u003C\u002Fa>). They need Escouade 2.2.0 or later (\u003Ccode class=\"key\">escouade.min\u003C\u002Fcode>); their 1.x versions, started through Node, stay on the store for the versions before. Node only serves their authors, to build and test them.\u003C\u002Fp>\n\u003C\u002Fdiv>\n\u003Ch2 id=\"trying-them\">Trying them\u003C\u002Fh2>\n\u003Cp>Install them from the store, in \u003Cstrong>Plugins\u003C\u002Fstrong>. To change one: “In development”, pick an example’s folder; it is loaded in place and read again when it changes. Enter its secrets in the “Settings” tab of its page.\u003C\u002Fp>\n\u003Cp>To check them as the repository’s CI does: each one passes its tests (and, in TypeScript, its typecheck; its \u003Ccode class=\"key\">dist\u002Fplugin.mjs\u003C\u002Fcode> is compared to the build of \u003Ccode class=\"key\">src\u002F\u003C\u002Fcode>), then \u003Ccode>escouade-plugin validate\u003C\u002Fcode> and the bench, with \u003Ccode class=\"key\">--first-party\u003C\u002Fcode> for their reserved ids (see \u003Ca href=\"\u002Fen\u002Fdocs\u002Fplugins\u002Ftesting\u002F\">Testing a plugin\u003C\u002Fa>).\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-sh\">npx tsc -p sdk\u002Fplugin\u002Ftsconfig.json\nESCOUADE_PLUGIN_BIN=\u002Fpath\u002Fto\u002Fescouade-plugin node plugins\u002Fci.mjs\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Ch2 id=\"high-contrast\">High contrast\u003C\u002Fh2>\n\u003Cp>A theme with no code: values for the window’s tokens, dark and light, and a palette for project colors. Escouade filters each value before it sets it; a token left out keeps Escouade’s. See \u003Ca href=\"\u002Fen\u002Fdocs\u002Fplugins\u002Fthemes\u002F\">Themes\u003C\u002Fa>.\u003C\u002Fp>\n\u003Cp>\u003Ccode>plugins\u002Fhigh-contrast\u002Fescouade-plugin.json\u003C\u002Fcode>\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-json\">{\n  "$schema": "https:\u002F\u002Fescouade.dev\u002Fschemas\u002Fplugin-1.json",\n  "id": "dev.escouade.high-contrast",\n  "name": { "fr": "Contraste élevé", "en": "High contrast" },\n  "version": "1.1.0",\n  "description": {\n    "fr": "Un thème à fort contraste, clair et sombre : texte pur, bordures nettes, couleurs d'état franches.",\n    "en": "A high-contrast theme, light and dark: pure text, sharp borders, plain status colors."\n  },\n  "author": { "name": "Escouade", "url": "https:\u002F\u002Fescouade.dev" },\n  "license": "MIT",\n  "repository": "https:\u002F\u002Fgithub.com\u002Fguillaume-gagnaire\u002Fescouade\u002Ftree\u002Fmain\u002Fplugins\u002Fhigh-contrast",\n  "escouade": { "api": "1", "min": "2.1.0" },\n  "contributes": {\n    "themes": [\n      {\n        "id": "high-contrast",\n        "name": { "fr": "Contraste élevé", "en": "High contrast" },\n        "dark": {\n          "--frame": "#000000",\n          "--panel": "color-mix(in oklch, var(--p) 4%, #050505)",\n          "--raise": "#141414",\n          "--raise-2": "#1f1f1f",\n          "--well": "#000000",\n          "--line": "#8a8a8a",\n          "--line-2": "#b0b0b0",\n          "--line-3": "#d8d8d8",\n          "--text": "#ffffff",\n          "--soft": "#f0f0f0",\n          "--muted": "#d0d0d0",\n          "--dim": "#b8b8b8",\n          "--p-ink": "#ffd400",\n          "--ring": "#ffd400",\n          "--run": "#4dff88",\n          "--wait": "#ffb000",\n          "--done": "#7ab8ff",\n          "--add": "#4dff88",\n          "--del": "#ff6b6b"\n        },\n        "light": {\n          "--frame": "#ffffff",\n          "--panel": "#ffffff",\n          "--raise": "#f2f2f2",\n          "--raise-2": "#e6e6e6",\n          "--well": "#ffffff",\n          "--line": "#5c5c5c",\n          "--line-2": "#3d3d3d",\n          "--line-3": "#1f1f1f",\n          "--text": "#000000",\n          "--soft": "#0a0a0a",\n          "--muted": "#262626",\n          "--dim": "#3d3d3d",\n          "--p-ink": "#0040c0",\n          "--ring": "#0040c0",\n          "--run": "#006b2e",\n          "--wait": "#8a4b00",\n          "--done": "#0040c0",\n          "--add": "#006b2e",\n          "--del": "#b00020"\n        },\n        "projectColors": ["#ffd400", "#00e0ff", "#ff5cf0", "#7cff4f", "#ff8a00", "#b48cff"]\n      }\n    ]\n  }\n}\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>Pick it in Settings › Application, “Colors” row.\u003C\u002Fp>\n\u003Ch2 id=\"discord\">Discord\u003C\u002Fh2>\n\u003Cp>Two declared webhooks, no program: a ticket moved to “To review”, and an agent waiting for your answer. The Discord webhook’s address is a secret: it stays in the system’s keychain and never shows in the journal. See \u003Ca href=\"\u002Fen\u002Fdocs\u002Fplugins\u002Fevents\u002F#a-webhook-without-code\">Events\u003C\u002Fa>.\u003C\u002Fp>\n\u003Cp>\u003Ccode>plugins\u002Fdiscord\u002Fescouade-plugin.json\u003C\u002Fcode>\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-json\">{\n  "$schema": "https:\u002F\u002Fescouade.dev\u002Fschemas\u002Fplugin-1.json",\n  "id": "dev.escouade.discord",\n  "name": "Discord",\n  "version": "1.1.0",\n  "description": {\n    "fr": "Les tickets à tester et les agents qui attendent, dans un salon Discord : un webhook, sans code.",\n    "en": "Tickets to test and agents waiting, in a Discord channel: a webhook, no code."\n  },\n  "author": { "name": "Escouade", "url": "https:\u002F\u002Fescouade.dev" },\n  "license": "MIT",\n  "repository": "https:\u002F\u002Fgithub.com\u002Fguillaume-gagnaire\u002Fescouade\u002Ftree\u002Fmain\u002Fplugins\u002Fdiscord",\n  "escouade": { "api": "1", "min": "2.1.0" },\n  "permissions": {\n    "events": ["ticket.column", "agent.status"],\n    "network": ["discord.com"],\n    "secrets": ["webhook"]\n  },\n  "contributes": {\n    "secrets": [{ "key": "webhook", "title": { "fr": "Adresse du webhook Discord", "en": "Discord webhook URL" } }],\n    "webhooks": [\n      {\n        "url": "{{secrets.webhook}}",\n        "events": ["ticket.column"],\n        "when": { "data.to": "review" },\n        "body": {\n          "content": "🧪 **{{ticket.key}}** to test: {{ticket.title}} ({{project.name}})",\n          "allowed_mentions": { "parse": [] }\n        }\n      },\n      {\n        "url": "{{secrets.webhook}}",\n        "events": ["agent.status"],\n        "when": { "data.status": "waiting" },\n        "body": {\n          "content": "✋ **{{agent.name}}** waits for you ({{project.name}})",\n          "allowed_mentions": { "parse": [] }\n        }\n      }\n    ]\n  }\n}\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>In Discord, create the webhook in the channel’s settings (Integrations › Webhooks), then paste its address in the plugin’s “Settings” tab. \u003Ccode class=\"key\">when\u003C\u002Fcode> lets through only the move to “To review” and the \u003Ccode class=\"key\">waiting\u003C\u002Fcode> status; the other moves and statuses say nothing. An empty \u003Ccode class=\"key\">allowed_mentions\u003C\u002Fcode>: an \u003Ccode class=\"key\">@everyone\u003C\u002Fcode> in the title of a ticket from elsewhere (a public issue) shows without notifying the channel.\u003C\u002Fp>\n\u003Ch2 id=\"slack\">Slack\u003C\u002Fh2>\n\u003Cp>A TypeScript program, written with the \u003Ca href=\"\u002Fen\u002Fdocs\u002Fplugins\u002Fsdk\u002F\">SDK\u003C\u002Fa>. It posts in each project’s channel: the one \u003Ccode class=\"key\">channels.json\u003C\u002Fcode> gives, else \u003Ccode>escouade-<project name>\u003C\u002Fcode>. The bot’s token (\u003Ccode class=\"key\">xoxb-…\u003C\u002Fcode>) is asked of Escouade on each fact (\u003Ccode class=\"key\">secrets\u002Fget\u003C\u002Fcode>), never written in a file.\u003C\u002Fp>\n\u003Cp>\u003Ccode>plugins\u002Fslack\u002Fescouade-plugin.json\u003C\u002Fcode>\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-json\">{\n  "$schema": "https:\u002F\u002Fescouade.dev\u002Fschemas\u002Fplugin-1.json",\n  "id": "dev.escouade.slack",\n  "name": "Slack",\n  "version": "2.0.0",\n  "description": {\n    "fr": "Les tickets à tester et les agents qui attendent, dans le salon Slack de chaque projet.",\n    "en": "Tickets to test and agents waiting, in each project's Slack channel."\n  },\n  "author": { "name": "Escouade", "url": "https:\u002F\u002Fescouade.dev" },\n  "license": "MIT",\n  "repository": "https:\u002F\u002Fgithub.com\u002Fguillaume-gagnaire\u002Fescouade\u002Ftree\u002Fmain\u002Fplugins\u002Fslack",\n  "escouade": { "api": "1", "min": "2.2.0" },\n  "run": { "js": "dist\u002Fplugin.mjs" },\n  "activation": ["event:ticket.column", "event:agent.status"],\n  "permissions": {\n    "events": ["ticket.column", "agent.status"],\n    "network": ["slack.com"],\n    "secrets": ["token"]\n  },\n  "contributes": {\n    "secrets": [{ "key": "token", "title": { "fr": "Jeton du bot Slack (xoxb-…)", "en": "Slack bot token (xoxb-…)" } }]\n  }\n}\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>\u003Ccode>plugins\u002Fslack\u002Fchannels.json\u003C\u002Fcode>\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-json\">{\n  "Escouade": "escouade-dev"\n}\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>\u003Ccode>plugins\u002Fslack\u002Fsrc\u002Fplugin.ts\u003C\u002Fcode>\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-ts\">\u002F\u002F Slack: the tickets to test and the agents waiting, in each project's channel. The bot's token is kept in the\n\u002F\u002F system's keychain (permissions.secrets), never in a file; the channel of a project comes from channels.json, or\n\u002F\u002F from the project's name (escouade-<name>).\nimport { readFileSync } from 'node:fs';\nimport { createPlugin, type Fact, type Plugin } from '@escouade-dev\u002Fplugin';\n\nexport interface Options {\n  \u002F** The channel of each project, by the project's name. *\u002F\n  channels?: Record<string, string>;\n}\n\n\u002F** channels.json, beside escouade-plugin.json (src\u002F and dist\u002F are one level below it). *\u002F\nfunction readChannels(): Record<string, string> {\n  try {\n    return JSON.parse(readFileSync(new URL('..\u002Fchannels.json', globalThis._importMeta_.url), 'utf8'));\n  } catch {\n    return {};\n  }\n}\n\n\u002F** The channel of a project: the one channels.json gives it, else escouade-<its name>, as Slack writes names. *\u002F\nexport function channelOf(project: string, channels: Record<string, string>): string {\n  const named = channels[project];\n  if (named) return named.replace(\u002F^#\u002F, '');\n  const slug = project\n    .normalize('NFD')\n    .replace(\u002F[̀-ͯ]\u002Fg, '')\n    .toLowerCase()\n    .replace(\u002F[^a-z0-9_-]+\u002Fg, '-')\n    .replace(\u002F^-+|-+$\u002Fg, '');\n  return `escouade-${slug || 'project'}`.slice(0, 80);\n}\n\n\u002F** A text from elsewhere (a ticket's title may come from a public issue), as Slack asks: `<!channel>` or `<@U…>` in it\n * is shown, never a mention that notifies. *\u002F\nexport const escaped = (text: string) => text.replace(\u002F&\u002Fg, '&').replace(\u002F<\u002Fg, '<').replace(\u002F>\u002Fg, '>');\n\n\u002F** What a fact says in Slack, or nothing for the facts it keeps quiet about. *\u002F\nexport function textOf(fact: Fact): string | null {\n  if (fact.name === 'ticket.column' && fact.data.to === 'review') {\n    return `:test_tube: *${escaped(fact.ticket?.key ?? '')}* to test: ${escaped(fact.ticket?.title ?? '')}`;\n  }\n  if (fact.name === 'agent.status' && fact.data.status === 'waiting') {\n    return `:raised_hand: *${escaped(fact.agent?.name ?? 'An agent')}* waits for you`;\n  }\n  return null;\n}\n\nexport function slack(options: Options = {}): Plugin {\n  const channels = options.channels ?? readChannels();\n\n  return createPlugin().onEvent(['ticket.column', 'agent.status'], async (fact, p) => {\n    const text = textOf(fact);\n    if (!text || !fact.project) return;\n    const token = await p.secret('token');\n    if (!token) return p.log.warn('no Slack token kept: nothing sent (Plugins › Slack › Settings)');\n    \u002F\u002F A bot token, never anything else, goes to Slack (and never into the journal).\n    if (!token.startsWith('xoxb-')) return p.log.warn('the token kept is not a Slack bot token (xoxb-…): nothing sent');\n    const channel = channelOf(fact.project.name, channels);\n    try {\n      const res = await fetch('https:\u002F\u002Fslack.com\u002Fapi\u002Fchat.postMessage', {\n        method: 'POST',\n        headers: { authorization: `Bearer ${token}`, 'content-type': 'application\u002Fjson; charset=utf-8' },\n        body: JSON.stringify({ channel, text }),\n      });\n      const answer = (await res.json()) as { ok: boolean; error?: string };\n      if (answer.ok) p.log.info(`posted in #${channel}`);\n      else p.log.warn(`Slack refused the message in #${channel}: ${answer.error ?? res.status}`);\n    } catch (e) {\n      p.log.error(`Slack could not be reached: ${(e as Error).message}`);\n    }\n  });\n}\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>\u003Ccode>plugins\u002Fslack\u002Fsrc\u002Fmain.ts\u003C\u002Fcode>\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-ts\">\u002F\u002F The program Escouade starts (run in escouade-plugin.json): speaks the protocol on stdin and stdout.\nimport { slack } from '.\u002Fplugin.ts';\n\nvoid slack().start();\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>In Slack, create an app with a bot that has the \u003Ccode class=\"key\">chat:write\u003C\u002Fcode> scope, invite it to the channels, then paste its token in the plugin’s “Settings” tab. Without a token, the journal says so and nothing is sent. A ticket’s title is escaped (\u003Ccode class=\"key\">&\u003C\u002Fcode>, \u003Ccode class=\"key\"><\u003C\u002Fcode>, \u003Ccode class=\"key\">>\u003C\u002Fcode>) as Slack asks: a \u003Ccode class=\"key\"><!channel>\u003C\u002Fcode> from a public issue shows without notifying anyone.\u003C\u002Fp>\n\u003Cp>Its tests drive its handlers against the SDK’s fake Escouade and a fake Slack, with no network (\u003Ccode>npm test\u003C\u002Fcode>). \u003Ccode>npm run build\u003C\u002Fcode> bundles \u003Ccode class=\"key\">src\u002F\u003C\u002Fcode> into \u003Ccode class=\"key\">dist\u002Fplugin.mjs\u003C\u002Fcode>, which \u003Ccode class=\"key\">run.js\u003C\u002Fcode> names: committed, it is the bundle the store compiles to WASM, without \u003Ccode>npm install\u003C\u002Fcode>. \u003Ccode class=\"key\">start()\u003C\u002Fcode> speaks to Escouade’s WASM host, or on standard input and output under Node (its tests, the bench). Its \u003Ccode class=\"key\">fetch\u003C\u002Fcode> to \u003Ccode>slack.com\u002Fapi\u002Fchat.postMessage\u003C\u002Fcode> goes through Escouade, which lets it reach \u003Ccode class=\"key\">slack.com\u003C\u002Fcode> and its subdomains only, over https; \u003Ccode class=\"key\">channels.json\u003C\u002Fcode>, a JSON file at the root of its folder, is given to it at its start, and \u003Ccode class=\"key\">readFileSync\u003C\u002Fcode> reads it as under Node.\u003C\u002Fp>\n\u003Ch2 id=\"team-rules\">Team rules\u003C\u002Fh2>\n\u003Cp>A TypeScript program that decides permissions before they reach you (see \u003Ca href=\"\u002Fen\u002Fdocs\u002Fplugins\u002Fpermission-rules\u002F\">Permission rules\u003C\u002Fa>). Its rules are in \u003Ccode class=\"key\">rules.json\u003C\u002Fcode>, a file of the plugin’s repository that the team reviews like its code. A line that holds a denied command is denied, even after a \u003Ccode class=\"key\">&&\u003C\u002Fcode> or a \u003Ccode class=\"key\">&\u003C\u002Fcode>; a line made only of allowed commands is allowed, unless it holds a substitution (\u003Ccode class=\"key\">$(…)\u003C\u002Fcode>, backquotes, \u003Ccode class=\"key\">$VAR\u003C\u002Fcode>), a redirection (\u003Ccode class=\"key\">>\u003C\u002Fcode>, \u003Ccode class=\"key\"><\u003C\u002Fcode>), an escape, which would slip something else behind an allowed start, or an \u003Ccode class=\"key\">--output\u003C\u002Fcode> (with it, \u003Ccode>git diff\u003C\u002Fcode> and \u003Ccode>git log\u003C\u002Fcode> write a file); the rest goes to the user. A rule compares the start of a command: \u003Ccode class=\"key\">deny\u003C\u002Fcode> is a safety net (\u003Ccode>sudo rm -rf\u003C\u002Fcode> slips past it and goes to the user), and \u003Ccode class=\"key\">allow\u003C\u002Fcode> allows any arguments.\u003C\u002Fp>\n\u003Cp>\u003Ccode>plugins\u002Fteam-rules\u002Fescouade-plugin.json\u003C\u002Fcode>\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-json\">{\n  "$schema": "https:\u002F\u002Fescouade.dev\u002Fschemas\u002Fplugin-1.json",\n  "id": "dev.escouade.team-rules",\n  "name": { "fr": "Règles de l'équipe", "en": "Team rules" },\n  "version": "2.0.0",\n  "description": {\n    "fr": "Autorise ou refuse les commandes des agents selon les règles de l'équipe, écrites dans rules.json.",\n    "en": "Allows or denies the agents' commands by the team's rules, written in rules.json."\n  },\n  "author": { "name": "Escouade", "url": "https:\u002F\u002Fescouade.dev" },\n  "license": "MIT",\n  "repository": "https:\u002F\u002Fgithub.com\u002Fguillaume-gagnaire\u002Fescouade\u002Ftree\u002Fmain\u002Fplugins\u002Fteam-rules",\n  "escouade": { "api": "1", "min": "2.2.0" },\n  "run": { "js": "dist\u002Fplugin.mjs" },\n  "activation": ["event:request.permission"],\n  "permissions": { "decide": true }\n}\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>\u003Ccode>plugins\u002Fteam-rules\u002Frules.json\u003C\u002Fcode>\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-json\">{\n  "deny": [\n    "rm -rf",\n    "git reset --hard",\n    { "command": "git push --force", "message": "No force push in this team: push a new commit instead." },\n    { "command": "git push -f", "message": "No force push in this team: push a new commit instead." }\n  ],\n  "allow": ["npm test", "npm run lint", "cargo test", "cargo nextest", "git status", "git diff", "git log"]\n}\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>\u003Ccode>plugins\u002Fteam-rules\u002Fsrc\u002Fplugin.ts\u003C\u002Fcode>\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-ts\">\u002F\u002F Team rules: the agents' commands allowed or denied by rules.json, a file of the plugin's repository that the team\n\u002F\u002F keeps under review like its code. A command that holds a denied one is denied; a command made only of allowed ones is\n\u002F\u002F allowed; anything else goes to the user, as without the plugin. A refusal of any plugin wins.\nimport { readFileSync } from 'node:fs';\nimport { createPlugin, type Decision, type Plugin } from '@escouade-dev\u002Fplugin';\n\nexport interface Rules {\n  \u002F** Commands denied, by their start: a text, or a text and the message the agent is given. *\u002F\n  deny: Array<string | { command: string; message?: string }>;\n  \u002F** Commands allowed, by their start. *\u002F\n  allow: string[];\n}\n\n\u002F** rules.json, beside escouade-plugin.json (src\u002F and dist\u002F are one level below it): read once, a decision has 500 ms. *\u002F\nexport function readRules(): Rules {\n  return JSON.parse(readFileSync(new URL('..\u002Frules.json', globalThis._importMeta_.url), 'utf8'));\n}\n\n\u002F** The commands of a line: `cd app && rm -rf build` is two, each judged on its own (`&` too, which sends one away). *\u002F\nexport function commandsOf(line: string): string[] {\n  return line\n    .split(\u002F&&|\\|\\||[;|&\\n]\u002F)\n    .map((c) => c.trim().replace(\u002F\\s+\u002Fg, ' '))\n    .filter(Boolean);\n}\n\n\u002F** What makes a line more than its commands: a substitution (`$(…)`, backquotes, `$VAR`), a redirection (`>`, `<`,\n * `<(…)`), an escape. A rule judges a command by its start, so a line that holds one of these is never allowed:\n * `git diff > ~\u002F.bashrc` starts like `git diff`. *\u002F\nconst HIDDEN = \u002F[`$<>\\\\]\u002F;\n\n\u002F** An option that makes a command write a file of its own choosing: `git diff --output=~\u002F.bashrc`, `git log --output …`\n * (git takes no abbreviation of it). A redirection by another name: a line that holds it, its quotes taken out as the\n * shell takes them out, is never allowed. *\u002F\nconst WRITES = \u002F(^|\\s)--output(=|\\s|$)\u002F;\nconst writes = (line: string) => WRITES.test(line.replace(\u002F["']\u002Fg, ''));\n\n\u002F** Whether `command` starts with `rule`, word for word (`npm testing` is not `npm test`). *\u002F\nconst startsWith = (command: string, rule: string) => command === rule || command.startsWith(rule + ' ');\n\nexport function decide(rules: Rules, line: string): Decision {\n  const commands = commandsOf(line);\n  for (const rule of rules.deny) {\n    const { command, message } = typeof rule === 'string' ? { command: rule, message: undefined } : rule;\n    if (commands.some((c) => startsWith(c, command))) {\n      return { decision: 'deny', message: message ?? `The team's rules forbid \\`${command}\\`.` };\n    }\n  }\n  const plain = !HIDDEN.test(line) && !writes(line);\n  if (plain && commands.length > 0 && commands.every((c) => rules.allow.some((rule) => startsWith(c, rule)))) {\n    return { decision: 'allow' };\n  }\n  return { decision: 'ask' };\n}\n\nexport function teamRules(rules: Rules = readRules()): Plugin {\n  return createPlugin().decidePermission(({ request }) => {\n    const line = request.input?.command;\n    \u002F\u002F Only commands: an edit or a fetch goes to the user.\n    if (request.kind !== 'command' || typeof line !== 'string') return { decision: 'ask' };\n    return decide(rules, line);\n  });\n}\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>\u003Ccode>plugins\u002Fteam-rules\u002Fsrc\u002Fmain.ts\u003C\u002Fcode>\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-ts\">\u002F\u002F The program Escouade starts (run in escouade-plugin.json): speaks the protocol on stdin and stdout.\nimport { teamRules } from '.\u002Fplugin.ts';\n\nvoid teamRules().start();\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>The rules are read once, at start: a decision has 500 ms. In WASM, \u003Ccode class=\"key\">rules.json\u003C\u002Fcode> is given to it at its start with the other JSON files at the root of its folder; it starts nothing and reaches no network (it has no \u003Ccode class=\"key\">permissions.network\u003C\u002Fcode>). An edit or a file read is not a command, and goes to the user.\u003C\u002Fp>\n\u003Ch2 id=\"linear\">Linear\u003C\u002Fh2>\n\u003Cp>A source of the Kanban in Rust: the kit’s \u003Ccode class=\"key\">Hosts\u003C\u002Fcode> answers the protocol, and the plugin gives its kind and its client. The \u003Ccode>npm create escouade-plugin -- --kind rust\u003C\u002Fcode> template, shorter, starts from a blank page; Linear shows a real service. It is read in \u003Ca href=\"\u002Fen\u002Fdocs\u002Fplugins\u002Frust\u002F#writing-a-source\">the Rust kit\u003C\u002Fa>, and its code is in \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fguillaume-gagnaire\u002Fescouade\u002Ftree\u002Fmain\u002Fplugins\u002Flinear\" rel=\"noopener\">\u003Ccode class=\"key\">plugins\u002Flinear\u003C\u002Fcode>\u003C\u002Fa>.\n\u003Ccode>plugins\u002Flinear\u002Fsrc\u002Flib.rs\u003C\u002Fcode> (excerpt)\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-rust\">impl SourceKind for LinearSource {\n    fn id(&self) -> &str {\n        ID\n    }\n    fn name(&self) -> &str {\n        S\n    }\n    fn client(&self, http: reqwest::Client, account: &Credentials) -> Box<dyn TicketSource> {\n        let base = account.api.clone().filter(|a| !a.trim().is_empty());\n        Box::new(Linear::new(http, account, base.as_deref().unwrap_or(API)))\n    }\n}\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Ch2 id=\"goose\">Goose\u003C\u002Fh2>\n\u003Cp>A harness without code: Goose, Block’s open source agent, described over ACP. The ACP plugin shipped with Escouade launches it and shows its conversation; the manifest says its modes, its mode that changes nothing, its model option and the names of its tools. Goose writes its files itself: no agent of a private project starts on it. See \u003Ca href=\"\u002Fen\u002Fdocs\u002Fplugins\u002Fharnesses\u002F\">A described ACP harness\u003C\u002Fa>.\u003C\u002Fp>\n\u003Cp>\u003Ccode>plugins\u002Fgoose\u002Fescouade-plugin.json\u003C\u002Fcode>\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-json\">{\n  "$schema": "https:\u002F\u002Fescouade.dev\u002Fschemas\u002Fplugin-1.json",\n  "id": "dev.escouade.goose",\n  "name": "Goose",\n  "version": "1.0.0",\n  "description": {\n    "fr": "Goose, l'agent open source de Block, comme harness : décrit par ACP, sans code.",\n    "en": "Goose, Block's open source agent, as a harness: described over ACP, no code."\n  },\n  "author": { "name": "Escouade", "url": "https:\u002F\u002Fescouade.dev" },\n  "license": "MIT",\n  "repository": "https:\u002F\u002Fgithub.com\u002Fguillaume-gagnaire\u002Fescouade\u002Ftree\u002Fmain\u002Fplugins\u002Fgoose",\n  "escouade": { "api": "1", "min": "2.1.0" },\n  "contributes": {\n    "harnesses": [\n      {\n        "id": "goose",\n        "name": "Goose",\n        "speaker": "Goose",\n        "writer": "Goose",\n        "locate": { "names": ["goose"] },\n        "tested": { "oldest": "1.57.0", "newest": "1.57.0" },\n        "caps": {\n          "modes": [\n            {\n              "id": "default",\n              "meaning": {\n                "fr": "Goose demande avant chaque outil (son mode approve). Il écrit les fichiers lui-même, sans les faire passer par Escouade.",\n                "en": "Goose asks before each tool (its approve mode). It writes files by itself, without passing them through Escouade."\n              }\n            },\n            {\n              "id": "acceptEdits",\n              "meaning": {\n                "fr": "Goose ne demande que pour ce qu'il juge sensible (son mode smart_approve) ; Escouade accepte ses écritures dans le dossier de l'agent.",\n                "en": "Goose asks only for what it deems sensitive (its smart_approve mode); Escouade accepts its writes in the agent's folder."\n              }\n            },\n            {\n              "id": "bypassPermissions",\n              "meaning": {\n                "fr": "Goose ne demande rien (son mode auto) : commandes, fichiers, tout le disque. Pas de bac à sable.",\n                "en": "Goose asks nothing (its auto mode): commands, files, the whole disk. No sandbox."\n              }\n            }\n          ],\n          "readOnly": true\n        },\n        "accountVar": "GOOSE_PATH_ROOT",\n        "install": {\n          "windows": "Invoke-WebRequest -Uri https:\u002F\u002Fraw.githubusercontent.com\u002Faaif-goose\u002Fgoose\u002Fmain\u002Fdownload_cli.ps1 -OutFile download_cli.ps1; .\u002Fdownload_cli.ps1",\n          "unix": "curl -fsSL https:\u002F\u002Fgithub.com\u002Faaif-goose\u002Fgoose\u002Freleases\u002Fdownload\u002Fstable\u002Fdownload_cli.sh | CONFIGURE=false bash"\n        },\n        "updateCommand": "goose update",\n        "acp": {\n          "args": ["acp"],\n          "fs": false,\n          "modes": { "default": "approve", "acceptEdits": "smart_approve", "bypassPermissions": "auto" },\n          "readOnlyMode": "chat",\n          "modelOption": "model",\n          "questionsInText": true,\n          "tools": { "shell": "Bash", "write": "Write", "edit": "Edit", "text_editor": "Edit", "read": "Read", "tree": "Glob" }\n        }\n      }\n    ]\n  }\n}\n\u003C\u002Fcode>\u003C\u002Fpre>\n",[8,12,15,18,21,24,27,30],{"id":9,"text":10,"depth":11},"where-to-find-them","Where to find them",2,{"id":13,"text":14,"depth":11},"trying-them","Trying them",{"id":16,"text":17,"depth":11},"high-contrast","High contrast",{"id":19,"text":20,"depth":11},"discord","Discord",{"id":22,"text":23,"depth":11},"slack","Slack",{"id":25,"text":26,"depth":11},"team-rules","Team rules",{"id":28,"text":29,"depth":11},"linear","Linear",{"id":31,"text":32,"depth":11},"goose","Goose",1793889382557]