@kolisachint/hoocode-agent 0.5.25 → 0.5.27

package/dist/core/canvas/scaffold.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Authoring a canvas: the request a person types, the files it writes, and the
+ * brief the model builds from.
+ *
+ * Design: `docs/canvas-extensions-design.md` §9 Phase 3, §13.
+ *
+ * This lives in `core/` rather than beside the other `/new-*` scaffolds because
+ * `/new-canvas` stopped being a file-writing command. Copilot's `/create-canvas`
+ * takes a sentence, has the agent write the extension, and opens it in a panel to
+ * iterate on; matching that means the command has to reach the canvas session to
+ * open, and the agent loop to build. Every decision that does not need either —
+ * what the name is, where the file goes, what goes in it, what the model is told —
+ * is here, testable without a terminal, a fork or a model.
+ */
+import type { MarketplacePlatform } from "../extensions/plugins/formats/types.js";
+/**
+ * Where a canvas extension lives, per platform.
+ *
+ * This does not go through `WorkspaceLayout` like the other scaffolds, and the
+ * reason is that a canvas has no Claude convention to emit into: the surface
+ * exists in Copilot and in hoocode's own `.agents/` tree and nowhere else. A
+ * layout method returning nothing for one adapter would be a worse lie than
+ * naming the two real homes here — these are exactly the roots
+ * `core/canvas/discovery.ts` searches, which is what makes a scaffold live on the
+ * next `/canvas`.
+ */
+export declare const CANVAS_HOMES: Partial<Record<MarketplacePlatform, string[]>>;
+/** Validates a canvas name: lowercase a-z, 0-9, hyphens, no leading/trailing/double hyphens. */
+export declare function validateCanvasName(name: string): string | null;
+/**
+ * Turn a sentence into a directory name.
+ *
+ * Returns undefined when nothing usable survives — an all-punctuation request, or
+ * a sentence of nothing but filler — because inventing `canvas-1` would hide from
+ * the person that we did not understand them.
+ */
+export declare function canvasNameFromDescription(description: string): string | undefined;
+/** What a person asked `/new-canvas` for. */
+export interface CanvasRequest {
+    /** Directory and default canvas id. */
+    name: string;
+    /**
+     * What they want it to do, in their words, or undefined when they only named
+     * one. Present means the model is expected to build it (Copilot's
+     * `/create-canvas` shape); absent means they want the template to edit by hand.
+     */
+    description: string | undefined;
+}
+/**
+ * Parse `/new-canvas`'s argument.
+ *
+ * Three shapes, in the order they are tested:
+ *
+ * - `my-board` — a bare name. Unchanged from before descriptions existed, and
+ *   tested first so it can never be re-read as a one-word description.
+ * - `my-board: a kanban board for the release checklist` — both, when someone
+ *   cares what the directory is called. A colon rather than a flag because the
+ *   rest of the line is prose and a flag parser would have to guess where it ends.
+ * - `a kanban board for the release checklist` — a description, the shape
+ *   `/create-canvas` uses. The name is derived and reported.
+ *
+ * Returns a string when the input cannot become a canvas; the caller shows it.
+ */
+export declare function parseCanvasRequest(input: string): CanvasRequest | string;
+/**
+ * A working single-canvas extension.
+ *
+ * Deliberately complete rather than a stub: a canvas has no passive half — its
+ * name, its actions and its UI all come from running its code — so a scaffold
+ * that does not run teaches nothing and cannot be checked with `/canvas open`.
+ * This one opens, serves a page, answers an action, and closes cleanly, which is
+ * the whole contract; everything past that is the author's.
+ *
+ * Shaped like the catalog extensions hoocode already hosts: the only import is
+ * `@github/copilot-sdk/extension` (host-resolved — never installed, see
+ * `docs/canvas-extensions-design.md` §4.1) plus `node:` builtins, and the UI is
+ * served from an ephemeral loopback port behind a per-instance token so nothing
+ * else on the machine can read it.
+ */
+export declare const CANVAS_ENTRY_TEMPLATE: (name: string) => string;
+/** What {@link scaffoldCanvas} wrote. */
+export interface CanvasScaffoldResult {
+    /** Workspace-relative entry files created, one per platform target. */
+    created: string[];
+    /** Workspace-relative entry files that already existed and were left alone. */
+    skipped: string[];
+}
+/**
+ * Write the template into every platform target that has a canvas home.
+ *
+ * Existing files are never clobbered — they are reported and skipped, so running
+ * `/new-canvas` twice on a canvas you have been editing cannot lose it.
+ */
+export declare function scaffoldCanvas(cwd: string, name: string, platforms: MarketplacePlatform[]): CanvasScaffoldResult;
+/** Where a build brief's canvas is, if opening it worked. */
+export interface CanvasBriefTarget {
+    instanceId: string;
+    url: string | undefined;
+}
+/**
+ * The message the model builds from — hoocode's half of `/create-canvas`.
+ *
+ * A scaffold plus a sentence is not a canvas, and the gap between them is the
+ * agent's work. This is what turns "a kanban board for the release checklist"
+ * into a build task with the contract attached, so the model does not have to
+ * infer the rules of a surface it cannot see from a template it has not read.
+ *
+ * Four of those rules are stated because getting them wrong fails in ways whose
+ * symptom does not name the cause: an installed dependency (the resolver already
+ * provides the SDK, and a `node_modules` here is a §4.1 violation), a
+ * `console.log` (corrupts the JSON-RPC channel and surfaces as "non-protocol
+ * stdout"), a write without a reload (changes nothing at all, because the running
+ * child was forked from the old bytes), and a renamed canvas id.
+ *
+ * That last one is the newest and was found the hard way, by building a canvas
+ * with this command: the scaffold names the canvas after the directory, a model
+ * that thinks of a better name renames the `id`, and the next reload drops the
+ * instance the person is looking at — correctly, since the canvas it was opened
+ * against no longer exists. `displayName` is the half they actually see, so it
+ * is the half to change.
+ */
+export declare function canvasBuildBrief(name: string, description: string, entryPath: string, target: CanvasBriefTarget | undefined): string;
+//# sourceMappingURL=scaffold.d.ts.map

package/dist/core/canvas/scaffold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../../src/core/canvas/scaffold.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wCAAwC,CAAC;AAGlF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,EAAE,OAAO,CAAC,MAAM,CAAC,mBAAmB,EAAE,MAAM,EAAE,CAAC,CAGvE,CAAC;AAEF,gGAAgG;AAChG,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM9D;AA+GD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAsBjF;AAED,6CAA6C;AAC7C,MAAM,WAAW,aAAa;IAC7B,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,GAAG,MAAM,CAkBxE;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,qBAAqB,0BAkFjC,CAAC;AAEF,yCAAyC;AACzC,MAAM,WAAW,oBAAoB;IACpC,uEAAuE;IACvE,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,+EAA+E;IAC/E,OAAO,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,mBAAmB,EAAE,GAAG,oBAAoB,CAiBhH;AAED,6DAA6D;AAC7D,MAAM,WAAW,iBAAiB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,gBAAgB,CAC/B,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,iBAAiB,GAAG,SAAS,GACnC,MAAM,CAsCR","sourcesContent":["/**\n * Authoring a canvas: the request a person types, the files it writes, and the\n * brief the model builds from.\n *\n * Design: `docs/canvas-extensions-design.md` §9 Phase 3, §13.\n *\n * This lives in `core/` rather than beside the other `/new-*` scaffolds because\n * `/new-canvas` stopped being a file-writing command. Copilot's `/create-canvas`\n * takes a sentence, has the agent write the extension, and opens it in a panel to\n * iterate on; matching that means the command has to reach the canvas session to\n * open, and the agent loop to build. Every decision that does not need either —\n * what the name is, where the file goes, what goes in it, what the model is told —\n * is here, testable without a terminal, a fork or a model.\n */\n\nimport { existsSync, mkdirSync, writeFileSync } from \"node:fs\";\nimport { dirname, join } from \"node:path\";\nimport type { MarketplacePlatform } from \"../extensions/plugins/formats/types.js\";\nimport { CANVAS_ENTRY_FILE } from \"./discovery.js\";\n\n/**\n * Where a canvas extension lives, per platform.\n *\n * This does not go through `WorkspaceLayout` like the other scaffolds, and the\n * reason is that a canvas has no Claude convention to emit into: the surface\n * exists in Copilot and in hoocode's own `.agents/` tree and nowhere else. A\n * layout method returning nothing for one adapter would be a worse lie than\n * naming the two real homes here — these are exactly the roots\n * `core/canvas/discovery.ts` searches, which is what makes a scaffold live on the\n * next `/canvas`.\n */\nexport const CANVAS_HOMES: Partial<Record<MarketplacePlatform, string[]>> = {\n\tagents: [\".agents\", \"extensions\"],\n\tgithub: [\".github\", \"extensions\"],\n};\n\n/** Validates a canvas name: lowercase a-z, 0-9, hyphens, no leading/trailing/double hyphens. */\nexport function validateCanvasName(name: string): string | null {\n\tif (!name) return \"name is required\";\n\tif (!/^[a-z0-9-]+$/.test(name)) return \"name must be lowercase a-z, 0-9, and hyphens only\";\n\tif (name.startsWith(\"-\") || name.endsWith(\"-\")) return \"name must not start or end with a hyphen\";\n\tif (name.includes(\"--\")) return \"name must not contain consecutive hyphens\";\n\treturn null;\n}\n\n/**\n * Words dropped wherever they appear, because they carry no subject.\n *\n * Only grammar, never subject matter: a list that reached further would start\n * deciding which of someone's nouns mattered.\n */\nconst FILLER = new Set([\n\t\"a\",\n\t\"about\",\n\t\"across\",\n\t\"an\",\n\t\"and\",\n\t\"are\",\n\t\"as\",\n\t\"at\",\n\t\"by\",\n\t\"be\",\n\t\"can\",\n\t\"for\",\n\t\"from\",\n\t\"i\",\n\t\"in\",\n\t\"is\",\n\t\"into\",\n\t\"it\",\n\t\"its\",\n\t\"me\",\n\t\"my\",\n\t\"of\",\n\t\"on\",\n\t\"one\",\n\t\"or\",\n\t\"our\",\n\t\"over\",\n\t\"so\",\n\t\"that\",\n\t\"the\",\n\t\"their\",\n\t\"them\",\n\t\"then\",\n\t\"this\",\n\t\"to\",\n\t\"us\",\n\t\"we\",\n\t\"which\",\n\t\"via\",\n\t\"when\",\n\t\"where\",\n\t\"while\",\n\t\"with\",\n\t\"you\",\n\t\"your\",\n]);\n\n/**\n * Words that open a request rather than describe one.\n *\n * People type `/new-canvas` as an instruction — \"create a…\", \"build me a…\",\n * \"help me…\", \"I want to…\" — and the opening clause was landing in the directory\n * name: `create-lightweight-games`, `help-compare-two`, `want-review-pull`. On a\n * spread of twelve realistic descriptions, seven produced a name that named the\n * request instead of the thing.\n *\n * These are dropped anywhere, not only at the front, because \"add a canvas that\n * shows X\" buries one in the middle.\n */\nconst REQUEST_WORDS = new Set([\n\t\"add\",\n\t\"build\",\n\t\"could\",\n\t\"create\",\n\t\"design\",\n\t\"generate\",\n\t\"give\",\n\t\"help\",\n\t\"let\",\n\t\"make\",\n\t\"need\",\n\t\"new\",\n\t\"please\",\n\t\"produce\",\n\t\"set\",\n\t\"show\",\n\t\"something\",\n\t\"up\",\n\t\"want\",\n\t\"would\",\n]);\n\n/** Counting words: \"compare two benchmark runs\" is about the runs. */\nconst CARDINALS = new Set([\"two\", \"three\", \"four\", \"five\", \"six\", \"seven\", \"eight\", \"nine\", \"ten\"]);\n\n/** How many words a derived name keeps. Enough to be recognisable, short enough to type. */\nconst DERIVED_NAME_WORDS = 3;\n\n/**\n * Whether a word is probably a verb form rather than the thing being described.\n *\n * Crude on purpose — no part-of-speech tagger for a directory name. It exists\n * because a participle sits between the request and its subject and pushes the\n * subject out of a three-word name: \"a dashboard **showing** flaky tests\" became\n * `dashboard-showing-flaky`, and \"a spreadsheet for **tracking** API latency\"\n * became `spreadsheet-tracking-api`. The length floor spares short words where\n * the ending is a coincidence (`feed`, `used`, `ring`).\n */\nfunction looksLikeVerbForm(word: string): boolean {\n\treturn word.length > 4 && (word.endsWith(\"ing\") || word.endsWith(\"ed\"));\n}\n\n/**\n * Turn a sentence into a directory name.\n *\n * Returns undefined when nothing usable survives — an all-punctuation request, or\n * a sentence of nothing but filler — because inventing `canvas-1` would hide from\n * the person that we did not understand them.\n */\nexport function canvasNameFromDescription(description: string): string | undefined {\n\tconst words = description\n\t\t.toLowerCase()\n\t\t.replace(/[^a-z0-9]+/g, \" \")\n\t\t.trim()\n\t\t.split(\" \")\n\t\t.filter((word) => word.length > 0);\n\n\tconst content = words.filter((word) => !FILLER.has(word) && !REQUEST_WORDS.has(word) && !CARDINALS.has(word));\n\t// \"canvas\" is dropped only when something else remains: \"/new-canvas a canvas\"\n\t// should still produce `canvas` rather than nothing.\n\tconst named = content.filter((word) => word !== \"canvas\");\n\tlet kept = named.length > 0 ? named : content;\n\n\t// Prefer nouns — but only while enough of them remain. Where they do not, the\n\t// participle *is* the subject (\"a canvas for onboarding\") and dropping it would\n\t// leave nothing worth naming.\n\tconst nouns = kept.filter((word) => !looksLikeVerbForm(word));\n\tif (nouns.length >= 2) kept = nouns;\n\n\tconst name = kept.slice(0, DERIVED_NAME_WORDS).join(\"-\");\n\treturn validateCanvasName(name) === null ? name : undefined;\n}\n\n/** What a person asked `/new-canvas` for. */\nexport interface CanvasRequest {\n\t/** Directory and default canvas id. */\n\tname: string;\n\t/**\n\t * What they want it to do, in their words, or undefined when they only named\n\t * one. Present means the model is expected to build it (Copilot's\n\t * `/create-canvas` shape); absent means they want the template to edit by hand.\n\t */\n\tdescription: string | undefined;\n}\n\n/**\n * Parse `/new-canvas`'s argument.\n *\n * Three shapes, in the order they are tested:\n *\n * - `my-board` — a bare name. Unchanged from before descriptions existed, and\n *   tested first so it can never be re-read as a one-word description.\n * - `my-board: a kanban board for the release checklist` — both, when someone\n *   cares what the directory is called. A colon rather than a flag because the\n *   rest of the line is prose and a flag parser would have to guess where it ends.\n * - `a kanban board for the release checklist` — a description, the shape\n *   `/create-canvas` uses. The name is derived and reported.\n *\n * Returns a string when the input cannot become a canvas; the caller shows it.\n */\nexport function parseCanvasRequest(input: string): CanvasRequest | string {\n\tconst trimmed = input.trim();\n\tif (trimmed.length === 0) return \"name or description is required\";\n\n\tif (validateCanvasName(trimmed) === null) return { name: trimmed, description: undefined };\n\n\tconst colon = trimmed.indexOf(\":\");\n\tif (colon > 0) {\n\t\tconst name = trimmed.slice(0, colon).trim();\n\t\tconst description = trimmed.slice(colon + 1).trim();\n\t\tif (validateCanvasName(name) === null && description.length > 0) return { name, description };\n\t}\n\n\tconst derived = canvasNameFromDescription(trimmed);\n\tif (!derived) {\n\t\treturn `could not derive a directory name from that. Give one explicitly: /new-canvas <name>: ${trimmed}`;\n\t}\n\treturn { name: derived, description: trimmed };\n}\n\n/**\n * A working single-canvas extension.\n *\n * Deliberately complete rather than a stub: a canvas has no passive half — its\n * name, its actions and its UI all come from running its code — so a scaffold\n * that does not run teaches nothing and cannot be checked with `/canvas open`.\n * This one opens, serves a page, answers an action, and closes cleanly, which is\n * the whole contract; everything past that is the author's.\n *\n * Shaped like the catalog extensions hoocode already hosts: the only import is\n * `@github/copilot-sdk/extension` (host-resolved — never installed, see\n * `docs/canvas-extensions-design.md` §4.1) plus `node:` builtins, and the UI is\n * served from an ephemeral loopback port behind a per-instance token so nothing\n * else on the machine can read it.\n */\nexport const CANVAS_ENTRY_TEMPLATE = (name: string): string => `\\\n// A canvas extension. Run it with: /canvas open ${name}\n//\n// The \"@github/copilot-sdk/extension\" import is resolved by the host at fork\n// time. Do not install it, and do not add a node_modules here.\nimport { createCanvas, CanvasError, joinSession } from \"@github/copilot-sdk/extension\";\nimport { randomBytes } from \"node:crypto\";\nimport { createServer } from \"node:http\";\n\n// The canvas's identity, in one place. An open instance is bound to this id, so\n// changing it drops the canvas anyone is currently looking at — rename the\n// canvas with \\`/canvas rename\\`, or change NAME alone if you only want a\n// different label on the page.\nconst ID = \"${name}\";\nconst NAME = \"${name}\";\n\n/** Per-instance state. A canvas can be opened more than once at a time. */\nconst instances = new Map();\n\nconst session = await joinSession({\n\tcanvases: [\n\t\tcreateCanvas({\n\t\t\tid: ID,\n\t\t\tdisplayName: NAME,\n\t\t\tdescription: \"TODO: one sentence — the agent reads this to decide whether to open it.\",\n\t\t\tactions: [\n\t\t\t\t{\n\t\t\t\t\tname: \"add_note\",\n\t\t\t\t\tdescription: \"TODO: describe what the agent can do to this canvas.\",\n\t\t\t\t\tinputSchema: {\n\t\t\t\t\t\ttype: \"object\",\n\t\t\t\t\t\tproperties: { text: { type: \"string\" } },\n\t\t\t\t\t\trequired: [\"text\"],\n\t\t\t\t\t},\n\t\t\t\t\thandler: (ctx) => {\n\t\t\t\t\t\tconst entry = instances.get(ctx.instanceId);\n\t\t\t\t\t\t// CanvasError carries a code the host shows verbatim; a bare\n\t\t\t\t\t\t// throw arrives as an opaque internal error instead.\n\t\t\t\t\t\tif (!entry) throw new CanvasError(\"no_instance\", \\`Instance \"\\${ctx.instanceId}\" is not open.\\`);\n\t\t\t\t\t\tentry.notes.push(ctx.input.text);\n\t\t\t\t\t\treturn { notes: entry.notes.length };\n\t\t\t\t\t},\n\t\t\t\t},\n\t\t\t],\n\t\t\topen: async (ctx) => {\n\t\t\t\tconst token = randomBytes(32).toString(\"base64url\");\n\t\t\t\tconst notes = [];\n\t\t\t\tconst server = createServer((req, res) => {\n\t\t\t\t\tconst url = new URL(req.url ?? \"/\", \"http://127.0.0.1\");\n\t\t\t\t\tif (url.searchParams.get(\"token\") !== token) {\n\t\t\t\t\t\tres.writeHead(403, { \"Content-Type\": \"text/plain\" });\n\t\t\t\t\t\tres.end(\"forbidden\");\n\t\t\t\t\t\treturn;\n\t\t\t\t\t}\n\t\t\t\t\tres.writeHead(200, { \"Content-Type\": \"text/html; charset=utf-8\" });\n\t\t\t\t\tres.end(\n\t\t\t\t\t\t\\`<!doctype html><meta charset=\"utf-8\"><title>\\${NAME}</title>\\` +\n\t\t\t\t\t\t\t\\`<p>\\${notes.length} note(s). TODO: build the UI.\\`,\n\t\t\t\t\t);\n\t\t\t\t});\n\t\t\t\t// Port 0 on 127.0.0.1: an ephemeral port, reachable only from this machine.\n\t\t\t\tawait new Promise((resolve) => server.listen(0, \"127.0.0.1\", resolve));\n\t\t\t\tconst { port } = server.address();\n\t\t\t\tinstances.set(ctx.instanceId, { server, notes });\n\t\t\t\treturn {\n\t\t\t\t\turl: \\`http://127.0.0.1:\\${port}/?token=\\${token}\\`,\n\t\t\t\t\ttitle: NAME,\n\t\t\t\t};\n\t\t\t},\n\t\t\tonClose: async (ctx) => {\n\t\t\t\tconst entry = instances.get(ctx.instanceId);\n\t\t\t\t// Called for an abandoned open too, so the instance may be unknown.\n\t\t\t\tif (!entry) return;\n\t\t\t\tinstances.delete(ctx.instanceId);\n\t\t\t\tawait new Promise((resolve) => entry.server.close(resolve));\n\t\t\t},\n\t\t}),\n\t],\n});\n\n// stdout is the protocol channel. Use session.log, never console.log.\nawait session.log(\\`\\${ID} ready\\`);\n`;\n\n/** What {@link scaffoldCanvas} wrote. */\nexport interface CanvasScaffoldResult {\n\t/** Workspace-relative entry files created, one per platform target. */\n\tcreated: string[];\n\t/** Workspace-relative entry files that already existed and were left alone. */\n\tskipped: string[];\n}\n\n/**\n * Write the template into every platform target that has a canvas home.\n *\n * Existing files are never clobbered — they are reported and skipped, so running\n * `/new-canvas` twice on a canvas you have been editing cannot lose it.\n */\nexport function scaffoldCanvas(cwd: string, name: string, platforms: MarketplacePlatform[]): CanvasScaffoldResult {\n\tconst created: string[] = [];\n\tconst skipped: string[] = [];\n\tfor (const platform of platforms) {\n\t\tconst home = CANVAS_HOMES[platform];\n\t\tif (!home) continue;\n\t\tconst relative = join(...home, name, CANVAS_ENTRY_FILE);\n\t\tconst absolute = join(cwd, relative);\n\t\tif (existsSync(absolute)) {\n\t\t\tskipped.push(relative);\n\t\t\tcontinue;\n\t\t}\n\t\tmkdirSync(dirname(absolute), { recursive: true });\n\t\twriteFileSync(absolute, CANVAS_ENTRY_TEMPLATE(name), \"utf8\");\n\t\tcreated.push(relative);\n\t}\n\treturn { created, skipped };\n}\n\n/** Where a build brief's canvas is, if opening it worked. */\nexport interface CanvasBriefTarget {\n\tinstanceId: string;\n\turl: string | undefined;\n}\n\n/**\n * The message the model builds from — hoocode's half of `/create-canvas`.\n *\n * A scaffold plus a sentence is not a canvas, and the gap between them is the\n * agent's work. This is what turns \"a kanban board for the release checklist\"\n * into a build task with the contract attached, so the model does not have to\n * infer the rules of a surface it cannot see from a template it has not read.\n *\n * Four of those rules are stated because getting them wrong fails in ways whose\n * symptom does not name the cause: an installed dependency (the resolver already\n * provides the SDK, and a `node_modules` here is a §4.1 violation), a\n * `console.log` (corrupts the JSON-RPC channel and surfaces as \"non-protocol\n * stdout\"), a write without a reload (changes nothing at all, because the running\n * child was forked from the old bytes), and a renamed canvas id.\n *\n * That last one is the newest and was found the hard way, by building a canvas\n * with this command: the scaffold names the canvas after the directory, a model\n * that thinks of a better name renames the `id`, and the next reload drops the\n * instance the person is looking at — correctly, since the canvas it was opened\n * against no longer exists. `displayName` is the half they actually see, so it\n * is the half to change.\n */\nexport function canvasBuildBrief(\n\tname: string,\n\tdescription: string,\n\tentryPath: string,\n\ttarget: CanvasBriefTarget | undefined,\n): string {\n\tconst lines = [\n\t\t`/new-canvas: build a canvas extension named \"${name}\".`,\n\t\t\"\",\n\t\t\"What the person asked for, in their words:\",\n\t\t`  ${description}`,\n\t\t\"\",\n\t\t`A working template is already at ${entryPath}. Edit it until it does what was asked.`,\n\t];\n\n\tif (target) {\n\t\tlines.push(\n\t\t\t\"\",\n\t\t\ttarget.url\n\t\t\t\t? `It is already open at ${target.url} (instance ${target.instanceId}), so the person is watching it as you work.`\n\t\t\t\t: `It is already open as instance ${target.instanceId}.`,\n\t\t\t`After every edit, call reload_canvas with extensionId \"${name}\". A write to the file changes nothing on its own — the running process was forked from the old code. Reloading hands back a NEW url; give it to the person, because the tab they have open dies with the old process.`,\n\t\t);\n\t} else {\n\t\tlines.push(\n\t\t\t\"\",\n\t\t\t`It is not open — the person will run /canvas open ${name} when they want to look. Build it anyway; you can check it runs by reading it carefully rather than by opening it yourself.`,\n\t\t);\n\t}\n\n\tlines.push(\n\t\t\"\",\n\t\t\"The contract this surface runs under, which is not yours to change:\",\n\t\t'- The only non-`node:` import allowed is \"@github/copilot-sdk/extension\". The host resolves it when it forks the extension. Do not install anything, and do not add a package.json or node_modules in the extension directory.',\n\t\t\"- stdout is the JSON-RPC channel. Use `session.log(...)`; a `console.log` corrupts the protocol.\",\n\t\t\"- Do not change the canvas's `id` (the template holds it in `ID`). An open instance is bound to it, so renaming it drops the canvas the person is watching on your next reload. Change `NAME` for a nicer label — that is the one they see — and if the directory name itself is wrong, say so and let them run `/canvas rename`, which moves everything at once.\",\n\t\t\"- After a reload, read the action list it reports back. That is the host telling you which of your actions it can actually see, and it is the only confirmation an action you just wrote is really callable.\",\n\t\t\"- Serve the UI from the loopback server the template already starts. Keep the per-instance token check, and keep `onClose` shutting the server down — that is what stops a port outliving the session.\",\n\t\t\"- Everything in `actions: [...]` becomes callable by you through invoke_canvas_action once it is open, so give each action a real description and inputSchema. That list is how you drive the canvas; the person drives the same state through the page.\",\n\t\t\"\",\n\t\t\"Build the thing that was asked for, not a stub: leave no TODO behind, and make the page render real state rather than a placeholder.\",\n\t);\n\treturn lines.join(\"\\n\");\n}\n"]}

package/dist/core/canvas/scaffold.js

@@ -0,0 +1,376 @@
+/**
+ * Authoring a canvas: the request a person types, the files it writes, and the
+ * brief the model builds from.
+ *
+ * Design: `docs/canvas-extensions-design.md` §9 Phase 3, §13.
+ *
+ * This lives in `core/` rather than beside the other `/new-*` scaffolds because
+ * `/new-canvas` stopped being a file-writing command. Copilot's `/create-canvas`
+ * takes a sentence, has the agent write the extension, and opens it in a panel to
+ * iterate on; matching that means the command has to reach the canvas session to
+ * open, and the agent loop to build. Every decision that does not need either —
+ * what the name is, where the file goes, what goes in it, what the model is told —
+ * is here, testable without a terminal, a fork or a model.
+ */
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { CANVAS_ENTRY_FILE } from "./discovery.js";
+/**
+ * Where a canvas extension lives, per platform.
+ *
+ * This does not go through `WorkspaceLayout` like the other scaffolds, and the
+ * reason is that a canvas has no Claude convention to emit into: the surface
+ * exists in Copilot and in hoocode's own `.agents/` tree and nowhere else. A
+ * layout method returning nothing for one adapter would be a worse lie than
+ * naming the two real homes here — these are exactly the roots
+ * `core/canvas/discovery.ts` searches, which is what makes a scaffold live on the
+ * next `/canvas`.
+ */
+export const CANVAS_HOMES = {
+    agents: [".agents", "extensions"],
+    github: [".github", "extensions"],
+};
+/** Validates a canvas name: lowercase a-z, 0-9, hyphens, no leading/trailing/double hyphens. */
+export function validateCanvasName(name) {
+    if (!name)
+        return "name is required";
+    if (!/^[a-z0-9-]+$/.test(name))
+        return "name must be lowercase a-z, 0-9, and hyphens only";
+    if (name.startsWith("-") || name.endsWith("-"))
+        return "name must not start or end with a hyphen";
+    if (name.includes("--"))
+        return "name must not contain consecutive hyphens";
+    return null;
+}
+/**
+ * Words dropped wherever they appear, because they carry no subject.
+ *
+ * Only grammar, never subject matter: a list that reached further would start
+ * deciding which of someone's nouns mattered.
+ */
+const FILLER = new Set([
+    "a",
+    "about",
+    "across",
+    "an",
+    "and",
+    "are",
+    "as",
+    "at",
+    "by",
+    "be",
+    "can",
+    "for",
+    "from",
+    "i",
+    "in",
+    "is",
+    "into",
+    "it",
+    "its",
+    "me",
+    "my",
+    "of",
+    "on",
+    "one",
+    "or",
+    "our",
+    "over",
+    "so",
+    "that",
+    "the",
+    "their",
+    "them",
+    "then",
+    "this",
+    "to",
+    "us",
+    "we",
+    "which",
+    "via",
+    "when",
+    "where",
+    "while",
+    "with",
+    "you",
+    "your",
+]);
+/**
+ * Words that open a request rather than describe one.
+ *
+ * People type `/new-canvas` as an instruction — "create a…", "build me a…",
+ * "help me…", "I want to…" — and the opening clause was landing in the directory
+ * name: `create-lightweight-games`, `help-compare-two`, `want-review-pull`. On a
+ * spread of twelve realistic descriptions, seven produced a name that named the
+ * request instead of the thing.
+ *
+ * These are dropped anywhere, not only at the front, because "add a canvas that
+ * shows X" buries one in the middle.
+ */
+const REQUEST_WORDS = new Set([
+    "add",
+    "build",
+    "could",
+    "create",
+    "design",
+    "generate",
+    "give",
+    "help",
+    "let",
+    "make",
+    "need",
+    "new",
+    "please",
+    "produce",
+    "set",
+    "show",
+    "something",
+    "up",
+    "want",
+    "would",
+]);
+/** Counting words: "compare two benchmark runs" is about the runs. */
+const CARDINALS = new Set(["two", "three", "four", "five", "six", "seven", "eight", "nine", "ten"]);
+/** How many words a derived name keeps. Enough to be recognisable, short enough to type. */
+const DERIVED_NAME_WORDS = 3;
+/**
+ * Whether a word is probably a verb form rather than the thing being described.
+ *
+ * Crude on purpose — no part-of-speech tagger for a directory name. It exists
+ * because a participle sits between the request and its subject and pushes the
+ * subject out of a three-word name: "a dashboard **showing** flaky tests" became
+ * `dashboard-showing-flaky`, and "a spreadsheet for **tracking** API latency"
+ * became `spreadsheet-tracking-api`. The length floor spares short words where
+ * the ending is a coincidence (`feed`, `used`, `ring`).
+ */
+function looksLikeVerbForm(word) {
+    return word.length > 4 && (word.endsWith("ing") || word.endsWith("ed"));
+}
+/**
+ * Turn a sentence into a directory name.
+ *
+ * Returns undefined when nothing usable survives — an all-punctuation request, or
+ * a sentence of nothing but filler — because inventing `canvas-1` would hide from
+ * the person that we did not understand them.
+ */
+export function canvasNameFromDescription(description) {
+    const words = description
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, " ")
+        .trim()
+        .split(" ")
+        .filter((word) => word.length > 0);
+    const content = words.filter((word) => !FILLER.has(word) && !REQUEST_WORDS.has(word) && !CARDINALS.has(word));
+    // "canvas" is dropped only when something else remains: "/new-canvas a canvas"
+    // should still produce `canvas` rather than nothing.
+    const named = content.filter((word) => word !== "canvas");
+    let kept = named.length > 0 ? named : content;
+    // Prefer nouns — but only while enough of them remain. Where they do not, the
+    // participle *is* the subject ("a canvas for onboarding") and dropping it would
+    // leave nothing worth naming.
+    const nouns = kept.filter((word) => !looksLikeVerbForm(word));
+    if (nouns.length >= 2)
+        kept = nouns;
+    const name = kept.slice(0, DERIVED_NAME_WORDS).join("-");
+    return validateCanvasName(name) === null ? name : undefined;
+}
+/**
+ * Parse `/new-canvas`'s argument.
+ *
+ * Three shapes, in the order they are tested:
+ *
+ * - `my-board` — a bare name. Unchanged from before descriptions existed, and
+ *   tested first so it can never be re-read as a one-word description.
+ * - `my-board: a kanban board for the release checklist` — both, when someone
+ *   cares what the directory is called. A colon rather than a flag because the
+ *   rest of the line is prose and a flag parser would have to guess where it ends.
+ * - `a kanban board for the release checklist` — a description, the shape
+ *   `/create-canvas` uses. The name is derived and reported.
+ *
+ * Returns a string when the input cannot become a canvas; the caller shows it.
+ */
+export function parseCanvasRequest(input) {
+    const trimmed = input.trim();
+    if (trimmed.length === 0)
+        return "name or description is required";
+    if (validateCanvasName(trimmed) === null)
+        return { name: trimmed, description: undefined };
+    const colon = trimmed.indexOf(":");
+    if (colon > 0) {
+        const name = trimmed.slice(0, colon).trim();
+        const description = trimmed.slice(colon + 1).trim();
+        if (validateCanvasName(name) === null && description.length > 0)
+            return { name, description };
+    }
+    const derived = canvasNameFromDescription(trimmed);
+    if (!derived) {
+        return `could not derive a directory name from that. Give one explicitly: /new-canvas <name>: ${trimmed}`;
+    }
+    return { name: derived, description: trimmed };
+}
+/**
+ * A working single-canvas extension.
+ *
+ * Deliberately complete rather than a stub: a canvas has no passive half — its
+ * name, its actions and its UI all come from running its code — so a scaffold
+ * that does not run teaches nothing and cannot be checked with `/canvas open`.
+ * This one opens, serves a page, answers an action, and closes cleanly, which is
+ * the whole contract; everything past that is the author's.
+ *
+ * Shaped like the catalog extensions hoocode already hosts: the only import is
+ * `@github/copilot-sdk/extension` (host-resolved — never installed, see
+ * `docs/canvas-extensions-design.md` §4.1) plus `node:` builtins, and the UI is
+ * served from an ephemeral loopback port behind a per-instance token so nothing
+ * else on the machine can read it.
+ */
+export const CANVAS_ENTRY_TEMPLATE = (name) => `\
+// A canvas extension. Run it with: /canvas open ${name}
+//
+// The "@github/copilot-sdk/extension" import is resolved by the host at fork
+// time. Do not install it, and do not add a node_modules here.
+import { createCanvas, CanvasError, joinSession } from "@github/copilot-sdk/extension";
+import { randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+
+// The canvas's identity, in one place. An open instance is bound to this id, so
+// changing it drops the canvas anyone is currently looking at — rename the
+// canvas with \`/canvas rename\`, or change NAME alone if you only want a
+// different label on the page.
+const ID = "${name}";
+const NAME = "${name}";
+
+/** Per-instance state. A canvas can be opened more than once at a time. */
+const instances = new Map();
+
+const session = await joinSession({
+	canvases: [
+		createCanvas({
+			id: ID,
+			displayName: NAME,
+			description: "TODO: one sentence — the agent reads this to decide whether to open it.",
+			actions: [
+				{
+					name: "add_note",
+					description: "TODO: describe what the agent can do to this canvas.",
+					inputSchema: {
+						type: "object",
+						properties: { text: { type: "string" } },
+						required: ["text"],
+					},
+					handler: (ctx) => {
+						const entry = instances.get(ctx.instanceId);
+						// CanvasError carries a code the host shows verbatim; a bare
+						// throw arrives as an opaque internal error instead.
+						if (!entry) throw new CanvasError("no_instance", \`Instance "\${ctx.instanceId}" is not open.\`);
+						entry.notes.push(ctx.input.text);
+						return { notes: entry.notes.length };
+					},
+				},
+			],
+			open: async (ctx) => {
+				const token = randomBytes(32).toString("base64url");
+				const notes = [];
+				const server = createServer((req, res) => {
+					const url = new URL(req.url ?? "/", "http://127.0.0.1");
+					if (url.searchParams.get("token") !== token) {
+						res.writeHead(403, { "Content-Type": "text/plain" });
+						res.end("forbidden");
+						return;
+					}
+					res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+					res.end(
+						\`<!doctype html><meta charset="utf-8"><title>\${NAME}</title>\` +
+							\`<p>\${notes.length} note(s). TODO: build the UI.\`,
+					);
+				});
+				// Port 0 on 127.0.0.1: an ephemeral port, reachable only from this machine.
+				await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+				const { port } = server.address();
+				instances.set(ctx.instanceId, { server, notes });
+				return {
+					url: \`http://127.0.0.1:\${port}/?token=\${token}\`,
+					title: NAME,
+				};
+			},
+			onClose: async (ctx) => {
+				const entry = instances.get(ctx.instanceId);
+				// Called for an abandoned open too, so the instance may be unknown.
+				if (!entry) return;
+				instances.delete(ctx.instanceId);
+				await new Promise((resolve) => entry.server.close(resolve));
+			},
+		}),
+	],
+});
+
+// stdout is the protocol channel. Use session.log, never console.log.
+await session.log(\`\${ID} ready\`);
+`;
+/**
+ * Write the template into every platform target that has a canvas home.
+ *
+ * Existing files are never clobbered — they are reported and skipped, so running
+ * `/new-canvas` twice on a canvas you have been editing cannot lose it.
+ */
+export function scaffoldCanvas(cwd, name, platforms) {
+    const created = [];
+    const skipped = [];
+    for (const platform of platforms) {
+        const home = CANVAS_HOMES[platform];
+        if (!home)
+            continue;
+        const relative = join(...home, name, CANVAS_ENTRY_FILE);
+        const absolute = join(cwd, relative);
+        if (existsSync(absolute)) {
+            skipped.push(relative);
+            continue;
+        }
+        mkdirSync(dirname(absolute), { recursive: true });
+        writeFileSync(absolute, CANVAS_ENTRY_TEMPLATE(name), "utf8");
+        created.push(relative);
+    }
+    return { created, skipped };
+}
+/**
+ * The message the model builds from — hoocode's half of `/create-canvas`.
+ *
+ * A scaffold plus a sentence is not a canvas, and the gap between them is the
+ * agent's work. This is what turns "a kanban board for the release checklist"
+ * into a build task with the contract attached, so the model does not have to
+ * infer the rules of a surface it cannot see from a template it has not read.
+ *
+ * Four of those rules are stated because getting them wrong fails in ways whose
+ * symptom does not name the cause: an installed dependency (the resolver already
+ * provides the SDK, and a `node_modules` here is a §4.1 violation), a
+ * `console.log` (corrupts the JSON-RPC channel and surfaces as "non-protocol
+ * stdout"), a write without a reload (changes nothing at all, because the running
+ * child was forked from the old bytes), and a renamed canvas id.
+ *
+ * That last one is the newest and was found the hard way, by building a canvas
+ * with this command: the scaffold names the canvas after the directory, a model
+ * that thinks of a better name renames the `id`, and the next reload drops the
+ * instance the person is looking at — correctly, since the canvas it was opened
+ * against no longer exists. `displayName` is the half they actually see, so it
+ * is the half to change.
+ */
+export function canvasBuildBrief(name, description, entryPath, target) {
+    const lines = [
+        `/new-canvas: build a canvas extension named "${name}".`,
+        "",
+        "What the person asked for, in their words:",
+        `  ${description}`,
+        "",
+        `A working template is already at ${entryPath}. Edit it until it does what was asked.`,
+    ];
+    if (target) {
+        lines.push("", target.url
+            ? `It is already open at ${target.url} (instance ${target.instanceId}), so the person is watching it as you work.`
+            : `It is already open as instance ${target.instanceId}.`, `After every edit, call reload_canvas with extensionId "${name}". A write to the file changes nothing on its own — the running process was forked from the old code. Reloading hands back a NEW url; give it to the person, because the tab they have open dies with the old process.`);
+    }
+    else {
+        lines.push("", `It is not open — the person will run /canvas open ${name} when they want to look. Build it anyway; you can check it runs by reading it carefully rather than by opening it yourself.`);
+    }
+    lines.push("", "The contract this surface runs under, which is not yours to change:", '- The only non-`node:` import allowed is "@github/copilot-sdk/extension". The host resolves it when it forks the extension. Do not install anything, and do not add a package.json or node_modules in the extension directory.', "- stdout is the JSON-RPC channel. Use `session.log(...)`; a `console.log` corrupts the protocol.", "- Do not change the canvas's `id` (the template holds it in `ID`). An open instance is bound to it, so renaming it drops the canvas the person is watching on your next reload. Change `NAME` for a nicer label — that is the one they see — and if the directory name itself is wrong, say so and let them run `/canvas rename`, which moves everything at once.", "- After a reload, read the action list it reports back. That is the host telling you which of your actions it can actually see, and it is the only confirmation an action you just wrote is really callable.", "- Serve the UI from the loopback server the template already starts. Keep the per-instance token check, and keep `onClose` shutting the server down — that is what stops a port outliving the session.", "- Everything in `actions: [...]` becomes callable by you through invoke_canvas_action once it is open, so give each action a real description and inputSchema. That list is how you drive the canvas; the person drives the same state through the page.", "", "Build the thing that was asked for, not a stub: leave no TODO behind, and make the page render real state rather than a placeholder.");
+    return lines.join("\n");
+}
+//# sourceMappingURL=scaffold.js.map

package/dist/core/canvas/scaffold.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.js","sourceRoot":"","sources":["../../../src/core/canvas/scaffold.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Authoring a canvas: the request a person types, the files it writes, and the\n * brief the model builds from.\n *\n * Design: `docs/canvas-extensions-design.md` §9 Phase 3, §13.\n *\n * This lives in `core/` rather than beside the other `/new-*` scaffolds because\n * `/new-canvas` stopped being a file-writing command. Copilot's `/create-canvas`\n * takes a sentence, has the agent write the extension, and opens it in a panel to\n * iterate on; matching that means the command has to reach the canvas session to\n * open, and the agent loop to build. Every decision that does not need either —\n * what the name is, where the file goes, what goes in it, what the model is told —\n * is here, testable without a terminal, a fork or a model.\n */\n\nimport { existsSync, mkdirSync, writeFileSync } from \"node:fs\";\nimport { dirname, join } from \"node:path\";\nimport type { MarketplacePlatform } from \"../extensions/plugins/formats/types.js\";\nimport { CANVAS_ENTRY_FILE } from \"./discovery.js\";\n\n/**\n * Where a canvas extension lives, per platform.\n *\n * This does not go through `WorkspaceLayout` like the other scaffolds, and the\n * reason is that a canvas has no Claude convention to emit into: the surface\n * exists in Copilot and in hoocode's own `.agents/` tree and nowhere else. A\n * layout method returning nothing for one adapter would be a worse lie than\n * naming the two real homes here — these are exactly the roots\n * `core/canvas/discovery.ts` searches, which is what makes a scaffold live on the\n * next `/canvas`.\n */\nexport const CANVAS_HOMES: Partial<Record<MarketplacePlatform, string[]>> = {\n\tagents: [\".agents\", \"extensions\"],\n\tgithub: [\".github\", \"extensions\"],\n};\n\n/** Validates a canvas name: lowercase a-z, 0-9, hyphens, no leading/trailing/double hyphens. */\nexport function validateCanvasName(name: string): string | null {\n\tif (!name) return \"name is required\";\n\tif (!/^[a-z0-9-]+$/.test(name)) return \"name must be lowercase a-z, 0-9, and hyphens only\";\n\tif (name.startsWith(\"-\") || name.endsWith(\"-\")) return \"name must not start or end with a hyphen\";\n\tif (name.includes(\"--\")) return \"name must not contain consecutive hyphens\";\n\treturn null;\n}\n\n/**\n * Words dropped wherever they appear, because they carry no subject.\n *\n * Only grammar, never subject matter: a list that reached further would start\n * deciding which of someone's nouns mattered.\n */\nconst FILLER = new Set([\n\t\"a\",\n\t\"about\",\n\t\"across\",\n\t\"an\",\n\t\"and\",\n\t\"are\",\n\t\"as\",\n\t\"at\",\n\t\"by\",\n\t\"be\",\n\t\"can\",\n\t\"for\",\n\t\"from\",\n\t\"i\",\n\t\"in\",\n\t\"is\",\n\t\"into\",\n\t\"it\",\n\t\"its\",\n\t\"me\",\n\t\"my\",\n\t\"of\",\n\t\"on\",\n\t\"one\",\n\t\"or\",\n\t\"our\",\n\t\"over\",\n\t\"so\",\n\t\"that\",\n\t\"the\",\n\t\"their\",\n\t\"them\",\n\t\"then\",\n\t\"this\",\n\t\"to\",\n\t\"us\",\n\t\"we\",\n\t\"which\",\n\t\"via\",\n\t\"when\",\n\t\"where\",\n\t\"while\",\n\t\"with\",\n\t\"you\",\n\t\"your\",\n]);\n\n/**\n * Words that open a request rather than describe one.\n *\n * People type `/new-canvas` as an instruction — \"create a…\", \"build me a…\",\n * \"help me…\", \"I want to…\" — and the opening clause was landing in the directory\n * name: `create-lightweight-games`, `help-compare-two`, `want-review-pull`. On a\n * spread of twelve realistic descriptions, seven produced a name that named the\n * request instead of the thing.\n *\n * These are dropped anywhere, not only at the front, because \"add a canvas that\n * shows X\" buries one in the middle.\n */\nconst REQUEST_WORDS = new Set([\n\t\"add\",\n\t\"build\",\n\t\"could\",\n\t\"create\",\n\t\"design\",\n\t\"generate\",\n\t\"give\",\n\t\"help\",\n\t\"let\",\n\t\"make\",\n\t\"need\",\n\t\"new\",\n\t\"please\",\n\t\"produce\",\n\t\"set\",\n\t\"show\",\n\t\"something\",\n\t\"up\",\n\t\"want\",\n\t\"would\",\n]);\n\n/** Counting words: \"compare two benchmark runs\" is about the runs. */\nconst CARDINALS = new Set([\"two\", \"three\", \"four\", \"five\", \"six\", \"seven\", \"eight\", \"nine\", \"ten\"]);\n\n/** How many words a derived name keeps. Enough to be recognisable, short enough to type. */\nconst DERIVED_NAME_WORDS = 3;\n\n/**\n * Whether a word is probably a verb form rather than the thing being described.\n *\n * Crude on purpose — no part-of-speech tagger for a directory name. It exists\n * because a participle sits between the request and its subject and pushes the\n * subject out of a three-word name: \"a dashboard **showing** flaky tests\" became\n * `dashboard-showing-flaky`, and \"a spreadsheet for **tracking** API latency\"\n * became `spreadsheet-tracking-api`. The length floor spares short words where\n * the ending is a coincidence (`feed`, `used`, `ring`).\n */\nfunction looksLikeVerbForm(word: string): boolean {\n\treturn word.length > 4 && (word.endsWith(\"ing\") || word.endsWith(\"ed\"));\n}\n\n/**\n * Turn a sentence into a directory name.\n *\n * Returns undefined when nothing usable survives — an all-punctuation request, or\n * a sentence of nothing but filler — because inventing `canvas-1` would hide from\n * the person that we did not understand them.\n */\nexport function canvasNameFromDescription(description: string): string | undefined {\n\tconst words = description\n\t\t.toLowerCase()\n\t\t.replace(/[^a-z0-9]+/g, \" \")\n\t\t.trim()\n\t\t.split(\" \")\n\t\t.filter((word) => word.length > 0);\n\n\tconst content = words.filter((word) => !FILLER.has(word) && !REQUEST_WORDS.has(word) && !CARDINALS.has(word));\n\t// \"canvas\" is dropped only when something else remains: \"/new-canvas a canvas\"\n\t// should still produce `canvas` rather than nothing.\n\tconst named = content.filter((word) => word !== \"canvas\");\n\tlet kept = named.length > 0 ? named : content;\n\n\t// Prefer nouns — but only while enough of them remain. Where they do not, the\n\t// participle *is* the subject (\"a canvas for onboarding\") and dropping it would\n\t// leave nothing worth naming.\n\tconst nouns = kept.filter((word) => !looksLikeVerbForm(word));\n\tif (nouns.length >= 2) kept = nouns;\n\n\tconst name = kept.slice(0, DERIVED_NAME_WORDS).join(\"-\");\n\treturn validateCanvasName(name) === null ? name : undefined;\n}\n\n/** What a person asked `/new-canvas` for. */\nexport interface CanvasRequest {\n\t/** Directory and default canvas id. */\n\tname: string;\n\t/**\n\t * What they want it to do, in their words, or undefined when they only named\n\t * one. Present means the model is expected to build it (Copilot's\n\t * `/create-canvas` shape); absent means they want the template to edit by hand.\n\t */\n\tdescription: string | undefined;\n}\n\n/**\n * Parse `/new-canvas`'s argument.\n *\n * Three shapes, in the order they are tested:\n *\n * - `my-board` — a bare name. Unchanged from before descriptions existed, and\n *   tested first so it can never be re-read as a one-word description.\n * - `my-board: a kanban board for the release checklist` — both, when someone\n *   cares what the directory is called. A colon rather than a flag because the\n *   rest of the line is prose and a flag parser would have to guess where it ends.\n * - `a kanban board for the release checklist` — a description, the shape\n *   `/create-canvas` uses. The name is derived and reported.\n *\n * Returns a string when the input cannot become a canvas; the caller shows it.\n */\nexport function parseCanvasRequest(input: string): CanvasRequest | string {\n\tconst trimmed = input.trim();\n\tif (trimmed.length === 0) return \"name or description is required\";\n\n\tif (validateCanvasName(trimmed) === null) return { name: trimmed, description: undefined };\n\n\tconst colon = trimmed.indexOf(\":\");\n\tif (colon > 0) {\n\t\tconst name = trimmed.slice(0, colon).trim();\n\t\tconst description = trimmed.slice(colon + 1).trim();\n\t\tif (validateCanvasName(name) === null && description.length > 0) return { name, description };\n\t}\n\n\tconst derived = canvasNameFromDescription(trimmed);\n\tif (!derived) {\n\t\treturn `could not derive a directory name from that. Give one explicitly: /new-canvas <name>: ${trimmed}`;\n\t}\n\treturn { name: derived, description: trimmed };\n}\n\n/**\n * A working single-canvas extension.\n *\n * Deliberately complete rather than a stub: a canvas has no passive half — its\n * name, its actions and its UI all come from running its code — so a scaffold\n * that does not run teaches nothing and cannot be checked with `/canvas open`.\n * This one opens, serves a page, answers an action, and closes cleanly, which is\n * the whole contract; everything past that is the author's.\n *\n * Shaped like the catalog extensions hoocode already hosts: the only import is\n * `@github/copilot-sdk/extension` (host-resolved — never installed, see\n * `docs/canvas-extensions-design.md` §4.1) plus `node:` builtins, and the UI is\n * served from an ephemeral loopback port behind a per-instance token so nothing\n * else on the machine can read it.\n */\nexport const CANVAS_ENTRY_TEMPLATE = (name: string): string => `\\\n// A canvas extension. Run it with: /canvas open ${name}\n//\n// The \"@github/copilot-sdk/extension\" import is resolved by the host at fork\n// time. Do not install it, and do not add a node_modules here.\nimport { createCanvas, CanvasError, joinSession } from \"@github/copilot-sdk/extension\";\nimport { randomBytes } from \"node:crypto\";\nimport { createServer } from \"node:http\";\n\n// The canvas's identity, in one place. An open instance is bound to this id, so\n// changing it drops the canvas anyone is currently looking at — rename the\n// canvas with \\`/canvas rename\\`, or change NAME alone if you only want a\n// different label on the page.\nconst ID = \"${name}\";\nconst NAME = \"${name}\";\n\n/** Per-instance state. A canvas can be opened more than once at a time. */\nconst instances = new Map();\n\nconst session = await joinSession({\n\tcanvases: [\n\t\tcreateCanvas({\n\t\t\tid: ID,\n\t\t\tdisplayName: NAME,\n\t\t\tdescription: \"TODO: one sentence — the agent reads this to decide whether to open it.\",\n\t\t\tactions: [\n\t\t\t\t{\n\t\t\t\t\tname: \"add_note\",\n\t\t\t\t\tdescription: \"TODO: describe what the agent can do to this canvas.\",\n\t\t\t\t\tinputSchema: {\n\t\t\t\t\t\ttype: \"object\",\n\t\t\t\t\t\tproperties: { text: { type: \"string\" } },\n\t\t\t\t\t\trequired: [\"text\"],\n\t\t\t\t\t},\n\t\t\t\t\thandler: (ctx) => {\n\t\t\t\t\t\tconst entry = instances.get(ctx.instanceId);\n\t\t\t\t\t\t// CanvasError carries a code the host shows verbatim; a bare\n\t\t\t\t\t\t// throw arrives as an opaque internal error instead.\n\t\t\t\t\t\tif (!entry) throw new CanvasError(\"no_instance\", \\`Instance \"\\${ctx.instanceId}\" is not open.\\`);\n\t\t\t\t\t\tentry.notes.push(ctx.input.text);\n\t\t\t\t\t\treturn { notes: entry.notes.length };\n\t\t\t\t\t},\n\t\t\t\t},\n\t\t\t],\n\t\t\topen: async (ctx) => {\n\t\t\t\tconst token = randomBytes(32).toString(\"base64url\");\n\t\t\t\tconst notes = [];\n\t\t\t\tconst server = createServer((req, res) => {\n\t\t\t\t\tconst url = new URL(req.url ?? \"/\", \"http://127.0.0.1\");\n\t\t\t\t\tif (url.searchParams.get(\"token\") !== token) {\n\t\t\t\t\t\tres.writeHead(403, { \"Content-Type\": \"text/plain\" });\n\t\t\t\t\t\tres.end(\"forbidden\");\n\t\t\t\t\t\treturn;\n\t\t\t\t\t}\n\t\t\t\t\tres.writeHead(200, { \"Content-Type\": \"text/html; charset=utf-8\" });\n\t\t\t\t\tres.end(\n\t\t\t\t\t\t\\`<!doctype html><meta charset=\"utf-8\"><title>\\${NAME}</title>\\` +\n\t\t\t\t\t\t\t\\`<p>\\${notes.length} note(s). TODO: build the UI.\\`,\n\t\t\t\t\t);\n\t\t\t\t});\n\t\t\t\t// Port 0 on 127.0.0.1: an ephemeral port, reachable only from this machine.\n\t\t\t\tawait new Promise((resolve) => server.listen(0, \"127.0.0.1\", resolve));\n\t\t\t\tconst { port } = server.address();\n\t\t\t\tinstances.set(ctx.instanceId, { server, notes });\n\t\t\t\treturn {\n\t\t\t\t\turl: \\`http://127.0.0.1:\\${port}/?token=\\${token}\\`,\n\t\t\t\t\ttitle: NAME,\n\t\t\t\t};\n\t\t\t},\n\t\t\tonClose: async (ctx) => {\n\t\t\t\tconst entry = instances.get(ctx.instanceId);\n\t\t\t\t// Called for an abandoned open too, so the instance may be unknown.\n\t\t\t\tif (!entry) return;\n\t\t\t\tinstances.delete(ctx.instanceId);\n\t\t\t\tawait new Promise((resolve) => entry.server.close(resolve));\n\t\t\t},\n\t\t}),\n\t],\n});\n\n// stdout is the protocol channel. Use session.log, never console.log.\nawait session.log(\\`\\${ID} ready\\`);\n`;\n\n/** What {@link scaffoldCanvas} wrote. */\nexport interface CanvasScaffoldResult {\n\t/** Workspace-relative entry files created, one per platform target. */\n\tcreated: string[];\n\t/** Workspace-relative entry files that already existed and were left alone. */\n\tskipped: string[];\n}\n\n/**\n * Write the template into every platform target that has a canvas home.\n *\n * Existing files are never clobbered — they are reported and skipped, so running\n * `/new-canvas` twice on a canvas you have been editing cannot lose it.\n */\nexport function scaffoldCanvas(cwd: string, name: string, platforms: MarketplacePlatform[]): CanvasScaffoldResult {\n\tconst created: string[] = [];\n\tconst skipped: string[] = [];\n\tfor (const platform of platforms) {\n\t\tconst home = CANVAS_HOMES[platform];\n\t\tif (!home) continue;\n\t\tconst relative = join(...home, name, CANVAS_ENTRY_FILE);\n\t\tconst absolute = join(cwd, relative);\n\t\tif (existsSync(absolute)) {\n\t\t\tskipped.push(relative);\n\t\t\tcontinue;\n\t\t}\n\t\tmkdirSync(dirname(absolute), { recursive: true });\n\t\twriteFileSync(absolute, CANVAS_ENTRY_TEMPLATE(name), \"utf8\");\n\t\tcreated.push(relative);\n\t}\n\treturn { created, skipped };\n}\n\n/** Where a build brief's canvas is, if opening it worked. */\nexport interface CanvasBriefTarget {\n\tinstanceId: string;\n\turl: string | undefined;\n}\n\n/**\n * The message the model builds from — hoocode's half of `/create-canvas`.\n *\n * A scaffold plus a sentence is not a canvas, and the gap between them is the\n * agent's work. This is what turns \"a kanban board for the release checklist\"\n * into a build task with the contract attached, so the model does not have to\n * infer the rules of a surface it cannot see from a template it has not read.\n *\n * Four of those rules are stated because getting them wrong fails in ways whose\n * symptom does not name the cause: an installed dependency (the resolver already\n * provides the SDK, and a `node_modules` here is a §4.1 violation), a\n * `console.log` (corrupts the JSON-RPC channel and surfaces as \"non-protocol\n * stdout\"), a write without a reload (changes nothing at all, because the running\n * child was forked from the old bytes), and a renamed canvas id.\n *\n * That last one is the newest and was found the hard way, by building a canvas\n * with this command: the scaffold names the canvas after the directory, a model\n * that thinks of a better name renames the `id`, and the next reload drops the\n * instance the person is looking at — correctly, since the canvas it was opened\n * against no longer exists. `displayName` is the half they actually see, so it\n * is the half to change.\n */\nexport function canvasBuildBrief(\n\tname: string,\n\tdescription: string,\n\tentryPath: string,\n\ttarget: CanvasBriefTarget | undefined,\n): string {\n\tconst lines = [\n\t\t`/new-canvas: build a canvas extension named \"${name}\".`,\n\t\t\"\",\n\t\t\"What the person asked for, in their words:\",\n\t\t`  ${description}`,\n\t\t\"\",\n\t\t`A working template is already at ${entryPath}. Edit it until it does what was asked.`,\n\t];\n\n\tif (target) {\n\t\tlines.push(\n\t\t\t\"\",\n\t\t\ttarget.url\n\t\t\t\t? `It is already open at ${target.url} (instance ${target.instanceId}), so the person is watching it as you work.`\n\t\t\t\t: `It is already open as instance ${target.instanceId}.`,\n\t\t\t`After every edit, call reload_canvas with extensionId \"${name}\". A write to the file changes nothing on its own — the running process was forked from the old code. Reloading hands back a NEW url; give it to the person, because the tab they have open dies with the old process.`,\n\t\t);\n\t} else {\n\t\tlines.push(\n\t\t\t\"\",\n\t\t\t`It is not open — the person will run /canvas open ${name} when they want to look. Build it anyway; you can check it runs by reading it carefully rather than by opening it yourself.`,\n\t\t);\n\t}\n\n\tlines.push(\n\t\t\"\",\n\t\t\"The contract this surface runs under, which is not yours to change:\",\n\t\t'- The only non-`node:` import allowed is \"@github/copilot-sdk/extension\". The host resolves it when it forks the extension. Do not install anything, and do not add a package.json or node_modules in the extension directory.',\n\t\t\"- stdout is the JSON-RPC channel. Use `session.log(...)`; a `console.log` corrupts the protocol.\",\n\t\t\"- Do not change the canvas's `id` (the template holds it in `ID`). An open instance is bound to it, so renaming it drops the canvas the person is watching on your next reload. Change `NAME` for a nicer label — that is the one they see — and if the directory name itself is wrong, say so and let them run `/canvas rename`, which moves everything at once.\",\n\t\t\"- After a reload, read the action list it reports back. That is the host telling you which of your actions it can actually see, and it is the only confirmation an action you just wrote is really callable.\",\n\t\t\"- Serve the UI from the loopback server the template already starts. Keep the per-instance token check, and keep `onClose` shutting the server down — that is what stops a port outliving the session.\",\n\t\t\"- Everything in `actions: [...]` becomes callable by you through invoke_canvas_action once it is open, so give each action a real description and inputSchema. That list is how you drive the canvas; the person drives the same state through the page.\",\n\t\t\"\",\n\t\t\"Build the thing that was asked for, not a stub: leave no TODO behind, and make the page render real state rather than a placeholder.\",\n\t);\n\treturn lines.join(\"\\n\");\n}\n"]}