@shortlink-org/portolan 0.2.0 → 0.2.2

package/scripts/local-api.test.mjs

@@ -5,9 +5,10 @@ import { join } from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
 import { rmSync } from "node:fs";
 
-import { classifyRepositoryFailure, diffGeneratedFiles, discoverProject, forgetRepositoryCredential, inspectionRoot, localApiPath, planProject, readLocalSource, resolveRepositoryCommit, storeRepositoryCredential, summarizeProjectTrial, writeProject } from "./local-api.mjs";
+import { classifyRepositoryFailure, diffGeneratedFiles, discoverProject, externalProjectDefaults, forgetRepositoryCredential, inspectionRoot, localApiPath, manifestWithoutProject, manifestWithProject, planProject, readLocalSource, removeProject, resolveRepositoryCommit, starterManifestProject, storeRepositoryCredential, summarizeProjectTrial, undoProjectRemoval, writeProject } from "./local-api.mjs";
 import { installDeliveryPreset, planDeliveryPreset, providerFromRemote, publicDeliveryPreset } from "./delivery-presets.mjs";
 
+const PACKAGE_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 const roots = [];
 afterEach(() => { for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true }); });
 
@@ -66,7 +67,7 @@ describe("local project setup", () => {
     const installed = installDeliveryPreset(root, { provider: "github", revision: preview.revision });
     expect(installed.written).toHaveLength(2);
     expect(installed.status).toBe("installed");
-    expect(readFileSync(join(root, ".github/workflows/portolan-check.yml"), "utf8")).toContain("shortlink-org/portolan@0.2.0");
+    expect(readFileSync(join(root, ".github/workflows/portolan-check.yml"), "utf8")).toContain(`shortlink-org/portolan@${PACKAGE_VERSION}`);
     expect(readFileSync(join(root, ".github/workflows/portolan-pages.yml"), "utf8")).toContain("base: /${{ github.event.repository.name }}/");
     expect(installDeliveryPreset(root, { provider: "github", revision: installed.revision }).written).toEqual([]);
   });
@@ -188,6 +189,18 @@ describe("local project setup", () => {
     expect(discovery.detections.find((item) => item.plugin === "adr")?.selected).toBe(false);
   });
 
+  it("names external projects from the repository or selected component instead of the inspection cache", () => {
+    expect(externalProjectDefaults("https://github.com/batazor/microservice-template-ddd")).toEqual({
+      id: "microservice-template-ddd",
+      name: "Microservice Template Ddd",
+      group: "microservice-template-ddd",
+      component: "microservice-template-ddd",
+      context: "microservice-template-ddd",
+      service: "microservice-template-ddd",
+    });
+    expect(externalProjectDefaults("git@github.com:acme/platform.git", "services/payments").id).toBe("payments");
+  });
+
   it("finds component roots in a monorepo without reading dependency directories", () => {
     const root = workspace();
     mkdirSync(join(root, "services/orders"), { recursive: true });
@@ -208,6 +221,55 @@ describe("local project setup", () => {
     ]);
   });
 
+  it("splits corroborated Go cmd entrypoints into deployable services", () => {
+    const root = workspace();
+    const platform = join(root, "services/platform");
+    mkdirSync(platform, { recursive: true });
+    writeFileSync(join(platform, "go.mod"), "module example.com/platform\nrequire github.com/go-redis/redis v6.15.9+incompatible\n");
+    for (const service of ["api", "billing", "book", "user"]) {
+      mkdirSync(join(platform, "cmd", service), { recursive: true });
+      mkdirSync(join(platform, "ops/dockerfile"), { recursive: true });
+      writeFileSync(join(platform, "cmd", service, `${service}.go`), "package main\nfunc main() {}\n");
+      writeFileSync(join(platform, "ops/dockerfile", `${service}.Dockerfile`), `FROM golang\nRUN go build -o app ./cmd/${service}\n`);
+    }
+    for (const service of ["billing", "book", "user"]) {
+      mkdirSync(join(platform, "internal", service, "infrastructure/rpc"), { recursive: true });
+      writeFileSync(join(platform, "internal", service, "infrastructure/rpc", `${service}.proto`), `syntax = "proto3"; package ${service}; service ${service}RPC {}\n`);
+      mkdirSync(join(platform, "internal", service, "domain"), { recursive: true });
+      writeFileSync(join(platform, "internal", service, "domain", `${service}.go`), `package domain\ntype ${service[0].toUpperCase() + service.slice(1)} struct{}\n`);
+    }
+    mkdirSync(join(platform, "internal/db/redis"), { recursive: true });
+    mkdirSync(join(platform, "internal/di"), { recursive: true });
+    writeFileSync(join(platform, "internal/db/redis/redis.go"), "package redisdb\nimport redis \"github.com/go-redis/redis\"\nfunc Open() { _ = redis.NewClient(nil) }\n");
+    writeFileSync(join(platform, "internal/di/book.go"), "package di\nimport _ \"example.com/platform/internal/db\"\n");
+
+    const discovery = discoverProject(root, "services/platform");
+    expect(discovery.deployables.map(({ slug, confidence }) => [slug, confidence])).toEqual([
+      ["api", "high"], ["billing", "high"], ["book", "high"], ["user", "high"],
+    ]);
+
+    const manifest = JSON.parse(readFileSync(join(root, "portolan.json"), "utf8"));
+    const plan = planProject(root, manifest, {
+      root: "services/platform", id: "platform", name: "Platform", group: "platform", component: "platform", componentKind: "application", plugins: ["project", "go-domain", "proto", "redis"],
+    });
+    expect(plan.project).toMatchObject({ group: "platform", components: ["api", "billing", "book", "user"] });
+    expect(plan.project).not.toHaveProperty("component");
+    expect(plan.steps[0].options.components.map((component) => component.slug)).toEqual(["api", "billing", "book", "user"]);
+    expect(plan.steps.filter((step) => step.plugin === "proto").map((step) => [step.options.service, step.options.out])).toEqual([
+      ["billing", "proto-billing.json"], ["book", "proto-book.json"], ["user", "proto-user.json"],
+    ]);
+    expect(plan.steps.filter((step) => step.plugin === "redis").map((step) => [step.options.service, step.options.out])).toEqual([
+      ["book", "redis-book.json"],
+    ]);
+    expect(plan.steps.filter((step) => step.plugin === "go-domain").map((step) => [step.options.service, step.options.scope, step.options.store, step.options.peers, step.options.out])).toEqual([
+      ["api", "api", undefined, { billing: "platform.billing", book: "platform.book", user: "platform.user" }, "go-domain-api.json"],
+      ["billing", "billing", undefined, { billing: "platform.billing", book: "platform.book", user: "platform.user" }, "go-domain-billing.json"],
+      ["book", "book", "redis", { billing: "platform.billing", book: "platform.book", user: "platform.user" }, "go-domain-book.json"],
+      ["user", "user", undefined, { billing: "platform.billing", book: "platform.book", user: "platform.user" }, "go-domain-user.json"],
+    ]);
+    expect(plan.steps[0].options.groupKind).toBe("system");
+  });
+
   it("only offers the Go domain extractor when the layout contains an aggregate root", () => {
     const root = workspace();
     mkdirSync(join(root, "services/billing/internal/domain/invoice"), { recursive: true });
@@ -232,6 +294,14 @@ describe("local project setup", () => {
     expect(discovery.detections.find((item) => item.plugin === "sql")?.evidence).toBe("2 repository packages");
   });
 
+  it("accepts a feature domain package named domain", () => {
+    const root = workspace();
+    mkdirSync(join(root, "services/billing/internal/invoice/domain"), { recursive: true });
+    writeFileSync(join(root, "services/billing/internal/invoice/domain/invoice.go"), "package domain\n\ntype Invoice struct{}\n");
+    const discovery = discoverProject(root, "services/billing");
+    expect(discovery.detections.find((item) => item.plugin === "go-domain")?.evidence).toBe("internal/invoice/domain/invoice.go");
+  });
+
   it("offers the River extractor when the Go module uses River", () => {
     const root = workspace();
     writeFileSync(join(root, "services/billing/go.mod"), "module example.com/billing\nrequire github.com/riverqueue/river v0.26.0\n");
@@ -382,6 +452,131 @@ describe("local project setup", () => {
     expect(() => writeProject(root, { ...request, id: "another" })).toThrow(/already exists/);
   });
 
+  it("removes a project's complete catalog slice without touching its neighbour", () => {
+    const manifest = {
+      sources: ["portolan/*.json", "services/billing/portolan/*.json"],
+      defaultCatalog: "portolan",
+      catalogs: [
+        { id: "portolan", title: "Portolan", sources: ["portolan/*.json"], contexts: ["portolan"], projects: ["portolan"] },
+        { id: "billing", title: "Billing", sources: ["services/billing/portolan/*.json"], contexts: ["finance"], projects: ["billing"] },
+      ],
+      projects: [
+        { id: "portolan", name: "Portolan", root: ".", group: "portolan", component: "portolan" },
+        { id: "billing", name: "Billing", root: "services/billing", group: "finance", component: "billing" },
+      ],
+      extract: [
+        { plugin: "project", in: ".", out: "portolan", options: {} },
+        { plugin: "commands", in: "scripts", out: "portolan", options: {} },
+        { plugin: "project", in: "services/billing", out: "services/billing/portolan", options: {} },
+      ],
+      verify: [
+        { plugin: "otel", in: ".", out: "portolan", options: {} },
+        { plugin: "otel", in: "services/billing", out: "services/billing/portolan", options: {} },
+      ],
+      generate: [
+        { plugin: "markdown", catalog: "portolan", out: "docs", options: {} },
+        { plugin: "markdown", catalog: "billing", out: "docs/billing", options: {} },
+      ],
+    };
+    const result = manifestWithoutProject(manifest, "portolan");
+    expect(result.manifest.projects.map((project) => project.id)).toEqual(["billing"]);
+    expect(result.manifest.sources).toEqual(["services/billing/portolan/*.json"]);
+    expect(result.manifest.extract.map((step) => step.out)).toEqual(["services/billing/portolan"]);
+    expect(result.manifest.verify.map((step) => step.out)).toEqual(["services/billing/portolan"]);
+    expect(result.manifest.catalogs.map((catalog) => catalog.id)).toEqual(["billing"]);
+    expect(result.manifest.defaultCatalog).toBe("billing");
+    expect(result.manifest.generate.map((step) => step.catalog)).toEqual(["billing"]);
+    expect(result.removedOutputs).toEqual(["docs"]);
+  });
+
+  it("keeps a valid empty-workspace source and replaces it when a project is added", () => {
+    const removed = manifestWithoutProject({
+      sources: ["portolan/*.json"],
+      projects: [{ id: "portolan", name: "Portolan", root: ".", group: "portolan", component: "portolan" }],
+      extract: [{ plugin: "project", in: ".", out: "portolan", options: {} }],
+      generate: [{ plugin: "markdown", out: "docs", options: {} }],
+    }, "portolan");
+    expect(removed.manifest).toMatchObject({ sources: ["portolan/*.json"], projects: [], extract: [] });
+    expect(removed.removedOutputs).toEqual(["docs"]);
+
+    const added = planProject(workspace(), { sources: ["portolan/*.json"], projects: [], extract: [] }, {
+      root: "services/billing", id: "aviaadmin", name: "Avia Admin", group: "avia", groupKind: "bounded-context", component: "aviaadmin", plugins: ["project"],
+    });
+    expect(added.project).toMatchObject({ id: "aviaadmin", group: "avia", groupKind: "bounded-context" });
+    expect(added.steps[0].options).toMatchObject({ group: "avia", groupKind: "bounded-context" });
+    const manifest = { sources: ["portolan/*.json"], projects: [], extract: [] };
+    expect(manifestWithProject(manifest, added).sources).toEqual(["services/billing/portolan/*.json"]);
+  });
+
+  it("does not duplicate an existing external fetch when a project is re-added", () => {
+    const fetch = { repo: "https://github.com/acme/orders", commit: "a".repeat(40), paths: [] };
+    const manifest = {
+      sources: ["vendor/repos/*/*/git.repo.json"], projects: [],
+      extract: [{ plugin: "git", in: "vendor", out: "vendor/repos", options: { cache: "vendor/repos", repos: [fetch] } }],
+    };
+    const plan = {
+      project: { id: "orders", root: "vendor/repos/acme/orders", group: "orders", component: "orders" },
+      steps: [{ plugin: "project", in: "vendor/repos/acme/orders", out: "vendor/repos/acme/orders/portolan", options: {} }],
+      source: "vendor/repos/**/portolan/*.json", fetch,
+    };
+    expect(manifestWithProject(manifest, plan).extract[0].options.repos).toEqual([fetch]);
+  });
+
+  it("adds the project slice to the default catalog profile", () => {
+    const root = workspace();
+    const manifest = {
+      sources: ["portolan/*.json"],
+      defaultCatalog: "company",
+      catalogs: [{ id: "company", title: "Company", sources: ["portolan/*.json"], contexts: ["platform"], projects: ["portolan"] }],
+      projects: [{ id: "portolan", root: ".", group: "platform", component: "portolan" }],
+      extract: [],
+    };
+    const added = planProject(root, manifest, {
+      root: "services/billing", id: "billing", name: "Billing", group: "finance", component: "billing", plugins: ["project"],
+    });
+    expect(manifestWithProject(manifest, added).catalogs[0]).toMatchObject({
+      sources: ["portolan/*.json", "services/billing/portolan/*.json"],
+      contexts: ["platform", "finance"],
+      projects: ["portolan", "billing"],
+    });
+  });
+
+  it("replaces a starter atomically after project discovery succeeds", () => {
+    const root = workspace();
+    const manifest = JSON.parse(readFileSync(join(root, "portolan.json"), "utf8"));
+    Object.assign(manifest, {
+      sources: ["portolan/*.json"],
+      projects: [{ id: "starter", name: "Starter", root: ".", group: "starter", component: "starter" }],
+      extract: [{ plugin: "project", in: ".", out: "portolan", options: { group: "starter", component: "starter" } }],
+    });
+    writeFileSync(join(root, "portolan.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+    expect(starterManifestProject(manifest)?.id).toBe("starter");
+    const result = writeProject(root, {
+      root: "services/billing", id: "aviaadmin", name: "Avia Admin", group: "avia", contextName: "Aviation", contextSummary: "Flight administration.", classification: "core", groupKind: "bounded-context", component: "aviaadmin", componentKind: "service", replaceStarter: true, plugins: ["project"],
+    });
+    const written = JSON.parse(readFileSync(join(root, "portolan.json"), "utf8"));
+    expect(result.replacedProject?.id).toBe("starter");
+    expect(written.projects.map((project) => project.id)).toEqual(["aviaadmin"]);
+    expect(starterManifestProject(written)).toBeNull();
+    expect(written.sources).toEqual(["services/billing/portolan/*.json"]);
+    expect(written.extract).toHaveLength(1);
+    expect(written.extract[0].options).toMatchObject({ group: "avia", groupName: "Aviation", groupSummary: "Flight administration.", classification: "core", groupKind: "bounded-context", componentKind: "service" });
+  });
+
+  it("undoes a project removal only while the manifest is unchanged", () => {
+    const root = workspace();
+    writeProject(root, { root: "services/billing", id: "billing", name: "Billing", group: "finance", component: "billing", plugins: ["project"] });
+    mkdirSync(join(root, "services/billing/portolan"), { recursive: true });
+    writeFileSync(join(root, "services/billing/portolan/project.json"), "generated slice\n");
+    const removed = removeProject(root, "billing");
+    expect(JSON.parse(readFileSync(join(root, "portolan.json"), "utf8")).projects).toEqual([]);
+    expect(existsSync(join(root, "services/billing/portolan/project.json"))).toBe(false);
+    expect(undoProjectRemoval(root, removed.undoToken)).toEqual({ restored: true });
+    expect(JSON.parse(readFileSync(join(root, "portolan.json"), "utf8")).projects[0].id).toBe("billing");
+    expect(readFileSync(join(root, "services/billing/portolan/project.json"), "utf8")).toBe("generated slice\n");
+    expect(() => undoProjectRemoval(root, removed.undoToken)).toThrow(/can no longer be undone/);
+  });
+
   it("plans a pinned external repository through the built-in git fetcher", () => {
     const root = workspace();
     const repository = "https://github.com/acme/platform.git";

package/scripts/package-smoke.mjs

@@ -2,16 +2,32 @@
 // This catches accidental cwd coupling before the same package reaches npm.
 
 import { execFileSync } from "node:child_process";
-import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, renameSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const root = resolve(fileURLToPath(new URL("..", import.meta.url)));
-const cli = resolve(root, "cli/portolan.mjs");
 const fixture = mkdtempSync(resolve(tmpdir(), "portolan-package-smoke-"));
+const install = mkdtempSync(resolve(tmpdir(), "portolan-package-install-"));
 
 try {
+  // Exercise the tarball from a real node_modules path. Node permits native
+  // TypeScript stripping in a checkout but rejects it below node_modules, so
+  // invoking the source-tree CLI did not catch broken published entry graphs.
+  const tarball = execFileSync("npm", ["pack", "--ignore-scripts", "--pack-destination", install], {
+    cwd: root,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "inherit"],
+  }).trim().split("\n").at(-1);
+  const scope = resolve(install, "node_modules/@shortlink-org");
+  mkdirSync(scope, { recursive: true });
+  execFileSync("tar", ["-xzf", resolve(install, tarball), "-C", scope]);
+  const installed = resolve(scope, "portolan");
+  renameSync(resolve(scope, "package"), installed);
+  symlinkSync(resolve(root, "node_modules"), resolve(installed, "node_modules"), process.platform === "win32" ? "junction" : "dir");
+  const cli = resolve(installed, "cli/portolan.mjs");
+
   writeFileSync(resolve(fixture, "package.json"), '{"name":"package-smoke","version":"1.0.0"}\n');
   writeFileSync(resolve(fixture, "README.md"), "# Package smoke\n");
   // A Go domain layout: init should notice it and wire the extractor without being asked.
@@ -34,6 +50,7 @@ try {
   console.log("package smoke: init, generate, check, and build passed outside the repository");
 } finally {
   rmSync(fixture, { recursive: true, force: true });
+  rmSync(install, { recursive: true, force: true });
 }
 
 function run(command, args) {

package/scripts/plugin-host.mjs

@@ -41,7 +41,7 @@ const HOST_LIMITS = Object.freeze({
  *   gets no filesystem at all, which is what a generator and a describe
  *   request should get. A process plugin is unaffected: it already has the
  *   whole machine.
- * @returns {Promise<{files: {name: string, contents: string}[], describe?: object}>}
+ * @returns {Promise<{files: {name: string, contents: string, encoding?: "base64"}[], describe?: object}>}
  */
 export async function runPlugin(plugin, request, requestedLimits = {}, access = {}) {
   const limits = lowerLimits(requestedLimits);
@@ -158,7 +158,7 @@ export function validateResponse(name, response) {
       throw new Error(`plugin ${name}: files[${index}] is not an object`);
     }
     const keys = Object.keys(file);
-    if (keys.some((key) => !["name", "contents"].includes(key))) {
+    if (keys.some((key) => !["name", "contents", "encoding"].includes(key))) {
       throw new Error(`plugin ${name}: files[${index}] has unsupported properties`);
     }
     if (typeof file.name !== "string" || !safeFileName(file.name)) {
@@ -167,17 +167,28 @@ export function validateResponse(name, response) {
     if (typeof file.contents !== "string") {
       throw new Error(`plugin ${name}: files[${index}].contents is not a string`);
     }
+    if (file.encoding !== undefined && file.encoding !== "base64") {
+      throw new Error(`plugin ${name}: files[${index}].encoding is not supported`);
+    }
+    if (file.encoding === "base64" && !validBase64(file.contents)) {
+      throw new Error(`plugin ${name}: files[${index}].contents is not valid base64`);
+    }
     if (seen.has(file.name)) {
       throw new Error(`plugin ${name}: duplicate output file ${file.name}`);
     }
     seen.add(file.name);
-    return { name: file.name, contents: file.contents };
+    return { name: file.name, contents: file.contents, ...(file.encoding ? { encoding: file.encoding } : {}) };
   });
 
   if (response.describe !== undefined) validateDescriptor(name, response.describe);
   return { files, ...(response.describe === undefined ? {} : { describe: response.describe }) };
 }
 
+function validBase64(value) {
+  return value.length % 4 === 0
+    && /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value);
+}
+
 function safeFileName(name) {
   if (!name || name.includes("\0") || isAbsolute(name) || /^[A-Za-z]:[\\/]/.test(name)) return false;
   const parts = name.split(/[\\/]/);

package/scripts/plugin-host.test.mjs

@@ -13,6 +13,14 @@ describe("plugin response validation", () => {
     });
   });
 
+  it("accepts canonical base64 files and rejects malformed binary output", () => {
+    expect(validateResponse("fixture", { files: [{ name: "image.png", contents: "iVBORw==", encoding: "base64" }] })).toEqual({
+      files: [{ name: "image.png", contents: "iVBORw==", encoding: "base64" }],
+    });
+    expect(() => validateResponse("fixture", { files: [{ name: "image.png", contents: "not base64", encoding: "base64" }] })).toThrow("not valid base64");
+    expect(() => validateResponse("fixture", { files: [{ name: "image.png", contents: "x", encoding: "binary" }] })).toThrow("encoding is not supported");
+  });
+
   it.each(["../secret", "/tmp/result", "C:\\tmp\\result", "a/../../secret", "./result"])(
     "rejects unsafe output name %s",
     (name) => {

package/scripts/schema.mjs

@@ -207,6 +207,13 @@ function compose() {
             minLength: 1,
             description: "Component slug inside the group.",
           },
+          components: {
+            type: "array",
+            minItems: 2,
+            uniqueItems: true,
+            items: { type: "string", minLength: 1 },
+            description: "Deployable component slugs discovered inside one repository-backed project.",
+          },
           groupKind: {
             enum: ["bounded-context", "system", "product", "team", "namespace"],
             description: "Semantic role of the project's top-level group.",

package/src/app/CatalogApp.tsx

@@ -98,7 +98,13 @@ function ChatLoading() {
  * way out the router already says the next address, and the page leaving
  * must keep drawing the one it was.
  */
-function AppRoutes({ location }: { location: Location }) {
+function AppRoutes({
+  location,
+  onOpenSearch,
+}: {
+  location: Location;
+  onOpenSearch: () => void;
+}) {
   return (
     <Routes location={location}>
       <Route path="/" element={<Overview />} />
@@ -200,7 +206,10 @@ function AppRoutes({ location }: { location: Location }) {
         }
       />
       <Route path="/index.html" element={<Navigate to="/" replace />} />
-      <Route path="*" element={<NotFoundPage />} />
+      <Route
+        path="*"
+        element={<NotFoundPage onOpenSearch={onOpenSearch} />}
+      />
     </Routes>
   );
 }
@@ -354,7 +363,10 @@ function Shell() {
               {...page}
               className="min-h-0 flex-1 overflow-hidden"
             >
-              <AppRoutes location={location} />
+              <AppRoutes
+                location={location}
+                onOpenSearch={() => setPalette(true)}
+              />
             </m.main>
           </AnimatePresence>
           <SidebarDrawer />
@@ -392,7 +404,10 @@ function Shell() {
                 {...page}
                 className="h-full overflow-hidden"
               >
-                <AppRoutes location={location} />
+                <AppRoutes
+                  location={location}
+                  onOpenSearch={() => setPalette(true)}
+                />
               </m.main>
             </AnimatePresence>
           </Panel>

package/src/app/CommandPalette.tsx

@@ -31,6 +31,7 @@ import { pageContains, selectionPath } from "../selection/pages";
 import { selectionHash } from "../selection/hash";
 import { selectionFor } from "../selection/model";
 import { useSelectionStore } from "../selection/store";
+import { CatIllustration } from "../components/CatIllustration";
 
 const ITEMS = paletteItems(catalog);
 
@@ -247,8 +248,12 @@ export function CommandPalette({
           </div>
 
           {shown === 0 ? (
-            <div className="glow mono px-4 py-8 text-center text-muted">
-              no match
+            <div className="cat-search-empty glow">
+              <CatIllustration scene="search" className="cat-search-illustration" />
+              <div className="mono">
+                <div className="text-ink">no match</div>
+                <div className="mt-1 text-faint">try another name or a kind prefix</div>
+              </div>
             </div>
           ) : (
             /* `static` because the list is the palette: there is no closed

package/src/app/toast.tsx

@@ -11,17 +11,19 @@ import { AnimatePresence, m, rise } from "../lib/motion";
 
 interface ToastState {
   message: string | null;
+  action: { label: string; run: () => void } | null;
   /** Bumped per call, so the same message twice restarts the timer. */
   nonce: number;
-  say: (message: string) => void;
+  say: (message: string, action?: { label: string; run: () => void }) => void;
   clear: () => void;
 }
 
 export const useToastStore = create<ToastState>()((set) => ({
   message: null,
+  action: null,
   nonce: 0,
-  say: (message) => set((s) => ({ message, nonce: s.nonce + 1 })),
-  clear: () => set({ message: null }),
+  say: (message, action) => set((s) => ({ message, action: action ?? null, nonce: s.nonce + 1 })),
+  clear: () => set({ message: null, action: null }),
 }));
 
 const SHOWN_MS = 4000;
@@ -29,13 +31,14 @@ const SHOWN_MS = 4000;
 export function Toaster() {
   const message = useToastStore((s) => s.message);
   const nonce = useToastStore((s) => s.nonce);
+  const action = useToastStore((s) => s.action);
   const clear = useToastStore((s) => s.clear);
 
   useEffect(() => {
     if (!message) return;
-    const timer = setTimeout(clear, SHOWN_MS);
+    const timer = setTimeout(clear, action ? 10_000 : SHOWN_MS);
     return () => clearTimeout(timer);
-  }, [message, nonce, clear]);
+  }, [message, nonce, action, clear]);
 
   // It rises in and sinks out. A second message while one is up swaps the
   // text in place: the box is the same box, only its line changed.
@@ -49,9 +52,10 @@ export function Toaster() {
           /* Bottom RIGHT, not left: the foot of the sidebar is where Problems
              and the build line are pinned, and a message that covers them for
              four seconds hides the one row that promised never to leave. */
-          className="mono pointer-events-none fixed right-4 bottom-4 z-50 max-w-80 rounded-control border px-3 py-2 shadow-md border-line bg-canvas text-ink"
+          className="mono fixed right-4 bottom-4 z-50 flex max-w-96 items-center gap-3 rounded-control border px-3 py-2 shadow-md border-line bg-canvas text-ink"
         >
-          {message}
+          <span>{message}</span>
+          {action ? <button type="button" className="tbtn shrink-0 px-2 py-1 text-accent" onClick={() => { action.run(); clear(); }}>{action.label}</button> : null}
         </m.div>
       )}
     </AnimatePresence>

package/src/catalog.test.ts

@@ -290,6 +290,39 @@ describe("validateCatalog: flow frames", () => {
     expect(() => validateCatalog(bad)).toThrow(/job handoff with no message/);
   });
 
+  it("validates that a response reverses the rpc request it names", () => {
+    const good = clone();
+    const flow = good.flows[0]!;
+    const request = walkSteps(flow.steps).find((step) => step.kind === "rpc")!;
+    flow.steps.push({
+      type: "step",
+      id: "response-test",
+      from: request.to,
+      to: request.from,
+      kind: "response",
+      label: "Response",
+      status: request.status,
+      replyTo: request.id,
+    });
+    expect(() => validateCatalog(good)).not.toThrow();
+
+    const bad = clone();
+    const badRequest = walkSteps(bad.flows[0]!.steps).find(
+      (step) => step.kind === "rpc",
+    )!;
+    bad.flows[0]!.steps.push({
+      type: "step",
+      id: "response-test",
+      from: badRequest.to,
+      to: badRequest.from,
+      kind: "response",
+      label: "Response",
+      status: "declared",
+      replyTo: "missing-request",
+    });
+    expect(() => validateCatalog(bad)).toThrow(/not an rpc request/);
+  });
+
   it("rejects an alt with a single branch", () => {
     const { bad, node } = alt();
     node.branches = node.branches.slice(0, 1);