install a plugin from a git URL, with no registry involved

the catalogue was the only way a remote plugin could arrive, so "build one and
give it to a friend" had no route. the first real case is a plugin that must
never be listed: fofos/fofos-admin is one website's admin panel, useful to
exactly one person.

MUCH smaller than the todo assumed. fetchPlugin already cloned, validated the
URL, refused to overwrite an existing directory, checked for a manifest and
removed a failed clone. exactly one line tied it to the marketplace — where the
string came from. so this is a source parameter threaded through, and a route.

THE NAME COMES FROM THE REPOSITORY, because appName is the DIRECTORY name and is
never declared in a manifest — the id cannot disagree with where the code sits.
that decision is inherited here rather than remade: the repo name becomes the
directory, the route segment, the table prefix and the sidecar suffix. so it is
checked against ^[a-z0-9]+(-[a-z0-9]+)*$ BEFORE anything is cloned; a half-clone
under an unusable name reads as a broken plugin rather than an absent one.

the URL is validated identically whether it came from the catalogue or from a
person, because the catalogue is not a trust boundary — it is just where a string
came from, and the same string reaches the same argv. what differs is who may
ask: this route is owner-only, and the owner is choosing what code runs rather
than choosing from a list somebody curated. validation is not review, and nothing
here reads what it cloned.

caught by testing: the source reached installPlugin and stopped there — the
fetchPlugin call still had the old two arguments, so a URL install fell back to
the catalogue and failed with "no catalogue entry". the guard tests are what
surfaced it, because the error named the wrong cause.

verified end to end against fofos-admin — cloned, schema applied, mounted, dock
pinned — then purged, since officer-dev is not that website's machine.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Officer-Session: 656f5c85-e49a-4f1f-b9f3-042a04b4d043

src/servers/api/plugins/router.ts

@@ -224,6 +224,58 @@ pluginsRouter.post('/update-all', async (ctx) => {
   });
 });
 
+/*
+  POST /plugins/install-from-url — a plugin that is in no registry.
+
+  The catalogue was the only way a remote plugin could arrive, so "build one and give it to a friend"
+  had no route at all. The first real case is a plugin that must never be listed: fofos-admin is one
+  website's admin panel, useful to exactly one person, and putting it in a public registry to install it
+  would be the wrong shape.
+
+  ── The name comes from the URL, because the name IS the directory ──
+
+  `appName` is taken from the directory a plugin sits in and never declared in its manifest, so the id
+  cannot disagree with where the code is. That decision is made for us here: the repository name becomes
+  the directory, and therefore the id, the route segment, the table prefix and the sidecar suffix. A
+  repository called something unusable as an id is refused before anything is cloned rather than after —
+  a half-clone under a bad name is a plugin the platform reports as broken instead of absent.
+
+  ── Owner-only, and it is not the same owner-only as the rest of this router ──
+
+  Every route here is owner-gated because installing a plugin mounts routes and starts a process. This
+  one also takes an ADDRESS from the caller, so the owner is choosing what code runs, not choosing from
+  a catalogue somebody curated. The URL is validated in `fetch.ts` — https, no credentials, no shell —
+  but validation is not review: nothing here reads what it cloned.
+*/
+pluginsRouter.post('/install-from-url', async (ctx) => {
+  type FromUrl = { url?: string; appName?: string };
+  const body = await ctx.req.json<FromUrl>().catch(() => ({}) as FromUrl);
+  const url = body.url?.trim();
+  if (!url) throw errors.BAD_REQUEST('url is required');
+
+  // `https://host/owner/repo` or `…/repo.git` → `repo`. Derived rather than asked for, so the name and
+  // the address cannot disagree; `appName` in the body only OVERRIDES it, for a repository whose name is
+  // not the id you want.
+  const derived = url
+    .replace(/\.git$/, '')
+    .replace(/\/+$/, '')
+    .split('/')
+    .pop();
+  const appName = body.appName?.trim() || derived;
+
+  // The same shape every other plugin id has. Checked here because everything downstream — the route
+  // segment, the table prefix, the pm2 process name — inherits it, and each of those fails differently.
+  if (!appName || !/^[a-z0-9]+(-[a-z0-9]+)*$/.test(appName)) {
+    throw errors.BAD_REQUEST(
+      `"${appName ?? ''}" is not a usable plugin name. Lowercase letters, digits and single hyphens — ` +
+        'it becomes the directory, the route and the table prefix.',
+    );
+  }
+
+  const result = await installPlugin(appName, undefined, ctx.get('user').id, undefined, url);
+  return ctx.json(result, result.ok ? 200 : 400);
+});
+
 pluginsRouter.post('/:appName/install', async (ctx) => {
   const result = await installPlugin(ctx.req.param('appName'), undefined, ctx.get('user').id);
   return ctx.json(result, result.ok ? 200 : 400);