Bundles and documents

createFetchHandler builds and serves the install archive automatically. Use buildBundle when you need to inspect or save the generated bytes during an application build. Pass the same mount path where the handler is served.

import { writeFile } from 'node:fs/promises';
import { buildBundle } from '@crouter/plugin';
import { plugin } from './crtr-plugin.js';

const bundle = await buildBundle(plugin, { mountPath: '/crtr' });
await writeFile('commands.json', bundle.commandsJson);
await writeFile('acme.tar', bundle.tar);

buildBundle returns commandsJson, bundleJson, generated memory/ members, uncompressed tar bytes, and an ETag. It runs the manifest validator and throws ManifestInvalidError when the generated command manifest is invalid. buildCommandManifest(plugin, { mountPath }) returns the manifest object when archive bytes are not needed.

The tar has exactly bundle.json, commands.json, and memory/<name>.md members for the documents declared in the memory array of definePlugin. It does not contain plugin.json. For an endpoint install, crouter creates .crouter-plugin/plugin.json from the endpoint, --name, --auth-env, and archive hash.

Documents in the memory array

Add a memory array to definePlugin when the app needs to give agents reusable operating knowledge. Each entry has name, kind, whenAndWhyToRead, body, and optional unlisted. name is a safe relative path without the .md suffix. The package writes the frontmatter required by the archive installer, so the author supplies no YAML.

whenAndWhyToRead is one routing sentence in the form When <circumstance>, this <kind> should be read because <payoff>. Keep the body to knowledge the agent needs to use the application. When the plugin is installed, crouter imports each entry as a public, read-only document owned by an app named after the plugin (an installed plugin is an app on the canvas), together with the generated commands. An agent reads it with crtr canvas read <plugin>/<name>, and whenAndWhyToRead becomes the document's preview. The memory array and whenAndWhyToRead are the plugin API's names; the result is an ordinary canvas document.