feat(showcase): add the object-less (global) action specimen

#3913 and its follow-up (#4005) fixed object-less action dispatch and the
empty-object-segment route with no live specimen to exercise either. The
showcase is the "one specimen of everything" app, yet every action in it
declared an `objectName` — so the `global` engine key, and both object-less
URL shapes, had nothing in-app that actually ran through them. #4005 could
only verify routing end to end; a real dispatch was never observed.

`showcase_portfolio_snapshot` closes that. It declares no `objectName`, so
`ObjectQLPlugin.actionObjectKey` / AppPlugin's `action.object || 'global'`
key it at `global`, and it is reachable at both shapes. The body is
genuinely object-less — it counts across three objects, so there is no
single record or object it could sensibly hang off — and `locations` is
`global_nav` for the same reason.

Verified live against the running showcase; both URL shapes return
byte-identical single-wrapped results:

  POST /api/v1/actions/global/showcase_portfolio_snapshot
  POST /api/v1/actions//showcase_portfolio_snapshot
  -> 200 {"success":true,"data":{"ok":true,"scope":"global",
          "accounts":15,"projects":5,"invoices":13}}

That is the first live confirmation of all three fixes in this arc acting
together: the canonical `global` key (#3913), the empty-segment route
(#4005), and single-wrap success (#3962).

Two tests pin the specimen in `test/actions.test.ts`, next to the #2169
executability cases. The first is the one that matters: adding an
`objectName` to this action would still build, still pass coverage.test.ts,
and still work — while silently removing the app's only coverage of
object-less dispatch. It asserts the action declares neither `objectName`
nor `object`, and that it remains the only such action. Confirmed the guard
fails when an `objectName` is added.

Showcase build green (Actions 10 -> 11), 60 tests pass, typecheck and
eslint clean. Example package is private, so the changeset releases nothing.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011AvZj6cLX7APd7roh2eK4F

Author: claude

.changeset/showcase-global-action-specimen.md

@@ -0,0 +1,8 @@
+---
+---
+
+Showcase example only, releases nothing: add `showcase_portfolio_snapshot`, the
+first object-less (`global`) action in the app. #3913 and its follow-up fixed
+object-less dispatch and the empty-object-segment route with no live specimen to
+exercise them — the "one specimen of everything" app had no action without an
+`objectName`. This is that specimen.

examples/app-showcase/src/coverage.ts

@@ -95,7 +95,7 @@ export const KIND_COVERAGE: Record<MetadataType, KindCoverage> = {
     status: 'demonstrated',
     files: ['src/ui/actions/index.ts'],
     notes:
-      'Every ActionType (script/url/flow/modal/api/form). `ActionParamGalleryAction` additionally exercises the ADR-0059 param-dialog widgets: one inline param per non-trivial type (richtext/color/date/select/number/autonumber) plus image/file uploads with multiple/accept/maxSize and the upload guard.',
+      "Every ActionType (script/url/flow/modal/api/form). `ActionParamGalleryAction` additionally exercises the ADR-0059 param-dialog widgets: one inline param per non-trivial type (richtext/color/date/select/number/autonumber) plus image/file uploads with multiple/accept/maxSize and the upload guard. `PortfolioSnapshotAction` is the OBJECT-LESS specimen (framework#3913): it declares no `objectName`, so it keys at `global` — the app's only live exerciser of object-less dispatch and of both object-less URL shapes (`/actions/global/:action` and `/actions//:action`).",
   },
   report: { status: 'demonstrated', files: ['src/ui/reports/index.ts'] },
   dataset: { status: 'demonstrated', files: ['src/ui/datasets/index.ts'] },

examples/app-showcase/src/ui/actions/index.ts

@@ -275,6 +275,55 @@ export const ArchiveTaskAction = defineAction({
   refreshAfter: false,
 });
 
+/**
+ * script, **OBJECT-LESS** — the `global` action specimen (framework#3913).
+ *
+ * Every other action here declares an `objectName`. This one deliberately does
+ * NOT, which is the whole point: `objectName` is optional, and an action
+ * without one is an *object-less* action. `AppPlugin` registers it under the
+ * canonical `'global'` engine key (`action.object || 'global'`), and it is
+ * reachable over REST at BOTH object-less URL shapes:
+ *
+ *   POST /api/v1/actions/global/showcase_portfolio_snapshot
+ *   POST /api/v1/actions//showcase_portfolio_snapshot      ← empty object segment
+ *
+ * Why the app needed this: framework#3913 was filed because object-less actions
+ * were unreachable (registered under `'global'`, looked up under `'*'`), and its
+ * follow-up found the empty-segment URL had no route registration at all. Both
+ * were fixed blind — the showcase, the "one specimen of everything" app, had no
+ * object-less action, so neither the dispatch path nor either URL shape had a
+ * live specimen to exercise. This is that specimen.
+ *
+ * The body is genuinely object-less: it counts across SEVERAL objects, so there
+ * is no single record or object the action could sensibly hang off. `location`
+ * is `global_nav` for the same reason — an object-less action has no row and no
+ * record header to render on.
+ */
+export const PortfolioSnapshotAction = defineAction({
+  name: 'showcase_portfolio_snapshot',
+  label: 'Portfolio Snapshot',
+  icon: 'gauge',
+  // NO objectName — this is what makes it an object-less ('global') action.
+  type: 'script',
+  body: {
+    language: 'js',
+    source:
+      "var accounts = await ctx.api.object('showcase_account').count({});" +
+      "var projects = await ctx.api.object('showcase_project').count({});" +
+      "var invoices = await ctx.api.object('showcase_invoice').count({});" +
+      "return { ok: true, scope: 'global', accounts: accounts, projects: projects, invoices: invoices };",
+    capabilities: ['api.read'],
+  },
+  successMessage: 'Portfolio snapshot taken.',
+  locations: ['global_nav'],
+  refreshAfter: false,
+  ai: {
+    exposed: true,
+    description:
+      'Count the accounts, projects and invoices in this workspace. Use when the user asks how big the portfolio is, or for a quick health snapshot across objects.',
+  },
+});
+
 export const allActions = [
   MarkDoneAction,
   OpenDocsAction,
@@ -286,4 +335,5 @@ export const allActions = [
   SubmitForSignoffAction,
   ActionParamGalleryAction,
   ArchiveTaskAction,
+  PortfolioSnapshotAction,
 ];

examples/app-showcase/test/actions.test.ts

@@ -3,7 +3,7 @@
 import { describe, it, expect } from 'vitest';
 import { actionBodyRunnerFactory, QuickJSScriptRunner } from '@objectstack/runtime';
 
-import { allActions, MarkDoneAction } from '../src/ui/actions/index.js';
+import { allActions, MarkDoneAction, PortfolioSnapshotAction } from '../src/ui/actions/index.js';
 
 /**
  * Execution-path coverage for declared actions.
@@ -84,3 +84,73 @@ describe('showcase actions — executability', () => {
     expect(handler).toBeUndefined();
   });
 });
+
+/**
+ * The object-less ("global") action specimen — framework#3913.
+ *
+ * #3913 was filed because object-less actions were unreachable: registered
+ * under the canonical `'global'` key, looked up under `'*'`. Its follow-up then
+ * found that `POST /api/v1/actions//:action` — the empty-object-segment URL the
+ * issue was actually filed against — had no route registration at all. Both
+ * were fixed with **no live specimen**: the showcase is the "one specimen of
+ * everything" app and every action in it declared an `objectName`, so nothing
+ * exercised the object-less dispatch path end to end.
+ *
+ * These tests pin the two properties that make it a specimen. The first is the
+ * one that silently rots: adding an `objectName` to this action would still
+ * build, still pass `coverage.test.ts`, and still work — while quietly removing
+ * the app's only coverage of object-less dispatch.
+ */
+describe('showcase actions — the object-less (`global`) specimen', () => {
+  const runner = new QuickJSScriptRunner();
+
+  it('declares no object, so it keys at `global` (framework#3913)', () => {
+    // This mirrors ObjectQLPlugin.actionObjectKey / AppPlugin's
+    // `action.object || 'global'`: neither field set → the 'global' bucket.
+    const a = PortfolioSnapshotAction as { objectName?: string; object?: string };
+    expect(a.objectName).toBeUndefined();
+    expect(a.object).toBeUndefined();
+
+    // ...and it is the ONLY one, so this test is what keeps the specimen alive.
+    const objectLess = allActions.filter((x) => {
+      const y = x as { objectName?: string; object?: string };
+      return !y.objectName && !y.object;
+    });
+    expect(objectLess.map((x) => x.name)).toEqual(['showcase_portfolio_snapshot']);
+  });
+
+  it('counts across several objects via the sandboxed body', async () => {
+    // An object-less action has no record and no single object to hang off —
+    // this body reads three, which is why it cannot be given an `objectName`.
+    const counts: Record<string, number> = {
+      showcase_account: 15,
+      showcase_project: 5,
+      showcase_invoice: 13,
+    };
+    const seen: string[] = [];
+    const ql = {
+      object: (object: string) => ({
+        count: async () => {
+          seen.push(object);
+          return counts[object] ?? 0;
+        },
+      }),
+    };
+
+    const factory = actionBodyRunnerFactory(runner, { ql, appId: 'showcase' });
+    const handler = factory(PortfolioSnapshotAction as never);
+    expect(typeof handler).toBe('function');
+
+    // No recordId, no record — the object-less invocation shape.
+    const result = await handler!({ params: {}, user: { id: 'u1' } });
+
+    expect(seen).toEqual(['showcase_account', 'showcase_project', 'showcase_invoice']);
+    expect(result).toEqual({
+      ok: true,
+      scope: 'global',
+      accounts: 15,
+      projects: 5,
+      invoices: 13,
+    });
+  });
+});