@north-light/crouter-plugin

Author a crtr HTTP plugin from one typed TypeScript command tree. The definition creates the Fetch handler, commands.json, and the archive that crtr pkg plugin install --endpoint accepts. You do not write a manifest, route table, or plugin.json.

Install

npm install @north-light/crouter-plugin

The package is ESM-only. Import it from an ES module or use dynamic import() from CommonJS.

Define a plugin

Create src/crtr-plugin.ts:

import {
  createFetchHandler,
  defineBranch,
  defineLeaf,
  definePlugin,
  field,
  LeafError,
  param,
} from '@north-light/crouter-plugin';

export const plugin = definePlugin({
  name: 'acme',
  description: 'Manage Acme applications.',
  whenToUse: 'you need to create or inspect an Acme application.',
  summary: 'Acme application management',
  rootEntry: {
    concept: 'an Acme application',
    description: 'Create and inspect applications.',
    whenToUse: 'the task is about an Acme application.',
  },
  commands: {
    app: defineBranch({
      description: 'Create and inspect applications.',
      whenToUse: 'you are working with an application.',
      summary: 'application operations',
      children: {
        create: defineLeaf({
          description: 'Create an Acme application.',
          whenToUse: 'an application does not exist yet.',
          summary: 'create an application',
          params: {
            name: param.positional('The application name.', { required: true }),
            region: param.enum(['us-east', 'eu-west'], 'The region for the application.', { default: 'us-east' }),
          },
          output: {
            appId: field.string('The created application id.'),
            url: field.string('The application URL.'),
          },
          effects: ['Creates an Acme application.'],
          handler(input) {
            if (input.name === 'taken') {
              throw new LeafError({
                code: 'name_taken',
                message: 'That application name is already in use.',
                status: 409,
                field: 'name',
              });
            }
            return {
              appId: `app_${input.name}`,
              url: `https://${input.name}.${input.region ?? 'us-east'}.acme.example.com`,
            };
          },
        }),
      },
    }),
  },
});

export default {
  fetch: createFetchHandler(plugin, { token: process.env.ACME_CRTR_TOKEN }),
};

The handler input is inferred from params: name is required and region is optional. Deploy the default export at the URL crtr reaches. The same URL handles GET archive requests and POST command requests.

Install into crtr

Set the same bearer token on the machine that runs crtr, then install the handler's actual mount path:

export ACME_CRTR_TOKEN='replace-with-a-secret'
crtr pkg plugin install --endpoint https://acme.example.com/crtr --name acme --auth-env ACME_CRTR_TOKEN
crtr acme app create my-app --region eu-west

export covers commands you type yourself. An agent's crtr acme … runs inside its broker, whose env comes from the profile env store, not from your shell — so for agents, store the token there too: echo -n "$ACME_CRTR_TOKEN" | crtr profile env set <profile> --name ACME_CRTR_TOKEN. Nodes launched under that profile from then on carry it.

Use the actual mount path in --endpoint. The generated archive declares command paths below that path, while crtr stores the origin for later command calls. Installing only https://acme.example.com would send calls to the origin root instead of /crtr.

Reference

The plugin guide covers commands, parameters, output, errors and streaming, deployment, and bundles and memory documents.