@nospt/plugin-dev-ai-hub-common 1.1.3 → 1.2.0-rc1

package/README.md

@@ -35,16 +35,18 @@ interface ResourceSummary {
   childCount?: number; // = children.length
   helpText?: string;
   annotations: Record<string, string>;
+  recommended?: boolean; // curation overlay, set by the backend router — never by toResourceSummary
 }
 ```
 
-`toResourceSummary(entity)` maps one `Entity`; `toResourceSummaries(entities)` maps a whole catalog read and resolves containment in both directions (ADR-0015). Both are exported here so the backend router and the test fixtures cannot disagree about them.
+`toResourceSummary(entity)` maps one `Entity`; `toResourceSummaries(entities)` maps a whole catalog read and resolves containment in both directions (ADR-0015). Both are exported here so the backend router and the test fixtures cannot disagree about them. Neither ever sets `recommended` — that is plugin-owned curation state, merged onto the summary by the backend router after mapping (ADR-0017), not derived from the catalog entity.
 
 ## Also in here
 
 - **The `ResourceType` vocabulary** — `skill`, `agent`, `hook`, `mcp-config`, `plugin`, `marketplace` — and the rules derived from it: which body shape a type renders as (`mcp-config` is JSON, the rest markdown), whether its body is a downloadable artifact or merely a pointer, and its per-framework install paths.
 - **Framework tokens and normalisation**, so `claude-code` means the same thing on both sides.
 - **Telemetry schemas** for the event contract.
+- **The permission contract** — `devAiHubBackofficeReadPermission` (read the backoffice) and `devAiHubBackofficeCuratePermission` (write curation state), plus the `RecommendationInput` schema validated on the write path.
 
 ## Full documentation
 

package/config.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "devAiHub": {
+      "type": "object",
+      "properties": {
+        "frameworks": {
+          "type": "object",
+          "properties": {
+            "custom": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "object",
+                "properties": {
+                  "displayName": {
+                    "type": "string",
+                    "description": "Display label. Defaults to the key when omitted."
+                  },
+                  "icon": {
+                    "type": "string",
+                    "description": "Icon shown beside the label. Any browser-loadable source — an absolute URL, an app-served static path, or a data URI. Rendered as an `<img>`, so it is not theme-inverted the way the built-in monochrome brand marks are: supply an image that reads on both light and dark backgrounds. A neutral icon is used when omitted."
+                  }
+                }
+              },
+              "description": "Frameworks this deployment recognises beyond the ones built into the plugin — an internal assistant, a tool too new or too niche to ship in code. Keyed by the token authors write in an AiResource's `spec.agents` (or the `devaihub.io/compatible-frameworks` annotation); keys are normalised (trimmed, lowercased) before matching.\n\nRegistering a custom framework **activates the allow-list** (`devAiHub.frameworks.allowed`, declared by `@nospt/plugin-dev-ai-hub-backend`) even when `allowed` is omitted: the effective set becomes the plugin's built-in frameworks plus these keys, and any other token is dropped. With `allowed` also set, the effective set is `allowed` plus these keys.\n\nA key that collides with a built-in token or one of its aliases (`claude-code`, `claude`, …) is ignored with a logged warning — built-ins stay authoritative so their install paths cannot be lost.\n\nCustom frameworks are discovery-only: they appear as badges, as \"Works with\" entries and in the AI Tool filter, but never produce a generated install path or launcher, because the plugin knows no filesystem convention for them. The `all` wildcard on a resource never expands into them — a resource must name the token explicitly (ADR-0018).\n\nDeclared here rather than in the backend or frontend plugin's own `config.d.ts`: the backend needs the names to gate the served payload, the frontend needs `displayName`/`icon` to render, and `backstage-cli`'s config schema collector only walks a package's actual `dependencies`/`devDependencies` — since neither plugin package depends on the other, a declaration in just one of them would be invisible to the other. Both already depend on this common package, so declaring it here is what makes one declaration serve both (ADR-0018).",
+              "deepVisibility": "frontend"
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/dist/curation.cjs.js

@@ -0,0 +1,16 @@
+'use strict';
+
+var zod = require('zod');
+
+const RECOMMENDED_TAG = "recommended";
+const RecommendationInputSchema = zod.z.object({
+  recommended: zod.z.boolean()
+});
+const ExclusionInputSchema = zod.z.object({
+  excluded: zod.z.boolean()
+});
+
+exports.ExclusionInputSchema = ExclusionInputSchema;
+exports.RECOMMENDED_TAG = RECOMMENDED_TAG;
+exports.RecommendationInputSchema = RecommendationInputSchema;
+//# sourceMappingURL=curation.cjs.js.map

package/dist/curation.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"curation.cjs.js","sources":["../src/curation.ts"],"sourcesContent":["import { z } from 'zod';\n\n/**\n * The catalog tag that recommends a resource from its own definition\n * (ADR-0020). A resource carrying it is recommended regardless of the\n * `curation` table, and the backoffice cannot un-recommend it — the author\n * removes the tag instead.\n */\nexport const RECOMMENDED_TAG = 'recommended';\n\n/**\n * The write body for `PUT /curation/:ref/recommendation` (ADR-0017).\n *\n * `recommended: false` clears the flag rather than deleting the row, so\n * `curated_by`/`curated_at` still say who last touched this resource even\n * after it is un-recommended — the same \"never forget who curated this\"\n * requirement #68 states for demote and hide.\n */\nexport const RecommendationInputSchema = z.object({\n  recommended: z.boolean(),\n});\nexport type RecommendationInput = z.infer<typeof RecommendationInputSchema>;\n\n/**\n * The write body for `PUT /curation/:ref/exclusion` (#68, ADR-0019).\n *\n * `excluded: false` restores the resource to the hub but keeps the row, so\n * `excluded_by`/`excluded_at` still record the most recent exclusion — the\n * same \"never forget who curated this\" requirement that shapes\n * `RecommendationInputSchema`.\n */\nexport const ExclusionInputSchema = z.object({\n  excluded: z.boolean(),\n});\nexport type ExclusionInput = z.infer<typeof ExclusionInputSchema>;\n\n/** One resource's curation record, as stored by `CurationStore`. */\nexport interface CurationRecord {\n  entityRef: string;\n  recommended: boolean;\n  curatedBy?: string;\n  curatedAt: string;\n  /**\n   * Excluded resources are dropped from `GET /resources` entirely rather\n   * than flagged for the frontend to skip (ADR-0019), so this is only ever\n   * observed by the backoffice, which asks for them explicitly.\n   */\n  excluded: boolean;\n  /**\n   * Who last changed this resource's exclusion state, and when. Tracked\n   * separately from `curatedBy`/`curatedAt` so a later recommendation cannot\n   * overwrite the exclusion's attribution. Both are `undefined` until the\n   * first exclusion write; while `excluded` is `true` they name whoever\n   * excluded it.\n   */\n  excludedBy?: string;\n  excludedAt?: string;\n}\n"],"names":["z"],"mappings":";;;;AAQO,MAAM,eAAA,GAAkB;AAUxB,MAAM,yBAAA,GAA4BA,MAAE,MAAA,CAAO;AAAA,EAChD,WAAA,EAAaA,MAAE,OAAA;AACjB,CAAC;AAWM,MAAM,oBAAA,GAAuBA,MAAE,MAAA,CAAO;AAAA,EAC3C,QAAA,EAAUA,MAAE,OAAA;AACd,CAAC;;;;;;"}

package/dist/curation.esm.js

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+
+const RECOMMENDED_TAG = "recommended";
+const RecommendationInputSchema = z.object({
+  recommended: z.boolean()
+});
+const ExclusionInputSchema = z.object({
+  excluded: z.boolean()
+});
+
+export { ExclusionInputSchema, RECOMMENDED_TAG, RecommendationInputSchema };
+//# sourceMappingURL=curation.esm.js.map

package/dist/curation.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"curation.esm.js","sources":["../src/curation.ts"],"sourcesContent":["import { z } from 'zod';\n\n/**\n * The catalog tag that recommends a resource from its own definition\n * (ADR-0020). A resource carrying it is recommended regardless of the\n * `curation` table, and the backoffice cannot un-recommend it — the author\n * removes the tag instead.\n */\nexport const RECOMMENDED_TAG = 'recommended';\n\n/**\n * The write body for `PUT /curation/:ref/recommendation` (ADR-0017).\n *\n * `recommended: false` clears the flag rather than deleting the row, so\n * `curated_by`/`curated_at` still say who last touched this resource even\n * after it is un-recommended — the same \"never forget who curated this\"\n * requirement #68 states for demote and hide.\n */\nexport const RecommendationInputSchema = z.object({\n  recommended: z.boolean(),\n});\nexport type RecommendationInput = z.infer<typeof RecommendationInputSchema>;\n\n/**\n * The write body for `PUT /curation/:ref/exclusion` (#68, ADR-0019).\n *\n * `excluded: false` restores the resource to the hub but keeps the row, so\n * `excluded_by`/`excluded_at` still record the most recent exclusion — the\n * same \"never forget who curated this\" requirement that shapes\n * `RecommendationInputSchema`.\n */\nexport const ExclusionInputSchema = z.object({\n  excluded: z.boolean(),\n});\nexport type ExclusionInput = z.infer<typeof ExclusionInputSchema>;\n\n/** One resource's curation record, as stored by `CurationStore`. */\nexport interface CurationRecord {\n  entityRef: string;\n  recommended: boolean;\n  curatedBy?: string;\n  curatedAt: string;\n  /**\n   * Excluded resources are dropped from `GET /resources` entirely rather\n   * than flagged for the frontend to skip (ADR-0019), so this is only ever\n   * observed by the backoffice, which asks for them explicitly.\n   */\n  excluded: boolean;\n  /**\n   * Who last changed this resource's exclusion state, and when. Tracked\n   * separately from `curatedBy`/`curatedAt` so a later recommendation cannot\n   * overwrite the exclusion's attribution. Both are `undefined` until the\n   * first exclusion write; while `excluded` is `true` they name whoever\n   * excluded it.\n   */\n  excludedBy?: string;\n  excludedAt?: string;\n}\n"],"names":[],"mappings":";;AAQO,MAAM,eAAA,GAAkB;AAUxB,MAAM,yBAAA,GAA4B,EAAE,MAAA,CAAO;AAAA,EAChD,WAAA,EAAa,EAAE,OAAA;AACjB,CAAC;AAWM,MAAM,oBAAA,GAAuB,EAAE,MAAA,CAAO;AAAA,EAC3C,QAAA,EAAU,EAAE,OAAA;AACd,CAAC;;;;"}

package/dist/index.cjs.js

@@ -1,11 +1,20 @@
 'use strict';
 
+var curation = require('./curation.cjs.js');
+var permissions = require('./permissions.cjs.js');
 var resources = require('./resources.cjs.js');
+var sorting = require('./sorting.cjs.js');
 var telemetry = require('./telemetry.cjs.js');
 var toResourceSummary = require('./toResourceSummary.cjs.js');
 
 
 
+exports.ExclusionInputSchema = curation.ExclusionInputSchema;
+exports.RECOMMENDED_TAG = curation.RECOMMENDED_TAG;
+exports.RecommendationInputSchema = curation.RecommendationInputSchema;
+exports.devAiHubBackofficeCuratePermission = permissions.devAiHubBackofficeCuratePermission;
+exports.devAiHubBackofficeReadPermission = permissions.devAiHubBackofficeReadPermission;
+exports.devAiHubPermissions = permissions.devAiHubPermissions;
 exports.AGENT_LINK_CAPABLE_FRAMEWORKS = resources.AGENT_LINK_CAPABLE_FRAMEWORKS;
 exports.ANNOTATION_COMPATIBLE_FRAMEWORKS = resources.ANNOTATION_COMPATIBLE_FRAMEWORKS;
 exports.ANNOTATION_HELP = resources.ANNOTATION_HELP;
@@ -37,8 +46,17 @@ exports.hasDownloadableArtifact = resources.hasDownloadableArtifact;
 exports.isRenderableContainment = resources.isRenderableContainment;
 exports.isResourceType = resources.isResourceType;
 exports.normalizeFramework = resources.normalizeFramework;
+exports.parseCustomFrameworks = resources.parseCustomFrameworks;
+exports.resolveAllowedFrameworks = resources.resolveAllowedFrameworks;
 exports.resolveCapableFrameworks = resources.resolveCapableFrameworks;
 exports.showsContentSection = resources.showsContentSection;
+exports.DEFAULT_SORT_MODE = sorting.DEFAULT_SORT_MODE;
+exports.NATURAL_SORT_DIRECTION = sorting.NATURAL_SORT_DIRECTION;
+exports.SORT_MODES = sorting.SORT_MODES;
+exports.SortModeEnum = sorting.SortModeEnum;
+exports.isSortMode = sorting.isSortMode;
+exports.sortResources = sorting.sortResources;
+exports.usageScore = sorting.usageScore;
 exports.TelemetryActionEnum = telemetry.TelemetryActionEnum;
 exports.TelemetryEventInputSchema = telemetry.TelemetryEventInputSchema;
 exports.isParseableEntityRef = toResourceSummary.isParseableEntityRef;

package/dist/index.cjs.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.cjs.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/index.d.ts

@@ -1,6 +1,100 @@
 import { z } from 'zod';
+import * as _backstage_plugin_permission_common from '@backstage/plugin-permission-common';
 import { Entity } from '@backstage/catalog-model';
 
+/**
+ * The catalog tag that recommends a resource from its own definition
+ * (ADR-0020). A resource carrying it is recommended regardless of the
+ * `curation` table, and the backoffice cannot un-recommend it — the author
+ * removes the tag instead.
+ */
+declare const RECOMMENDED_TAG = "recommended";
+/**
+ * The write body for `PUT /curation/:ref/recommendation` (ADR-0017).
+ *
+ * `recommended: false` clears the flag rather than deleting the row, so
+ * `curated_by`/`curated_at` still say who last touched this resource even
+ * after it is un-recommended — the same "never forget who curated this"
+ * requirement #68 states for demote and hide.
+ */
+declare const RecommendationInputSchema: z.ZodObject<{
+    recommended: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    recommended: boolean;
+}, {
+    recommended: boolean;
+}>;
+type RecommendationInput = z.infer<typeof RecommendationInputSchema>;
+/**
+ * The write body for `PUT /curation/:ref/exclusion` (#68, ADR-0019).
+ *
+ * `excluded: false` restores the resource to the hub but keeps the row, so
+ * `excluded_by`/`excluded_at` still record the most recent exclusion — the
+ * same "never forget who curated this" requirement that shapes
+ * `RecommendationInputSchema`.
+ */
+declare const ExclusionInputSchema: z.ZodObject<{
+    excluded: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    excluded: boolean;
+}, {
+    excluded: boolean;
+}>;
+type ExclusionInput = z.infer<typeof ExclusionInputSchema>;
+/** One resource's curation record, as stored by `CurationStore`. */
+interface CurationRecord {
+    entityRef: string;
+    recommended: boolean;
+    curatedBy?: string;
+    curatedAt: string;
+    /**
+     * Excluded resources are dropped from `GET /resources` entirely rather
+     * than flagged for the frontend to skip (ADR-0019), so this is only ever
+     * observed by the backoffice, which asks for them explicitly.
+     */
+    excluded: boolean;
+    /**
+     * Who last changed this resource's exclusion state, and when. Tracked
+     * separately from `curatedBy`/`curatedAt` so a later recommendation cannot
+     * overwrite the exclusion's attribution. Both are `undefined` until the
+     * first exclusion write; while `excluded` is `true` they name whoever
+     * excluded it.
+     */
+    excludedBy?: string;
+    excludedAt?: string;
+}
+
+/**
+ * Opening the Dev AI Hub backoffice (ADR-0016).
+ *
+ * Held in `-common` because both sides need the same identity: the backend
+ * registers it so the Backstage RBAC plugin can list and grant it, and the
+ * frontend checks it to decide whether the surface exists for this user at all.
+ *
+ * Read-only on purpose. Every governance capability that writes — curation
+ * (#68, ADR-0017), tool visibility (#85) — gets its own permission rather
+ * than riding on this one, so "can see the backoffice" never silently
+ * becomes "can change the catalog's presentation".
+ */
+declare const devAiHubBackofficeReadPermission: _backstage_plugin_permission_common.BasicPermission;
+/**
+ * Changing a resource's curation state — currently just "recommended"
+ * (ADR-0017), later also demote/hide (#68) — from the backoffice.
+ *
+ * Scoped to the capability, not to one action: a future demote or hide
+ * reuses this permission rather than minting one each, the same way granting
+ * someone curation trust once covers whichever curation actions the backoffice
+ * exposes. Separate from `dev-ai-hub.backoffice.read` so seeing the backoffice
+ * never implies being able to write to it.
+ */
+declare const devAiHubBackofficeCuratePermission: _backstage_plugin_permission_common.BasicPermission;
+/**
+ * Every permission this plugin owns, for bulk registration with the backend's
+ * permissions registry. New permissions must be added here or the RBAC plugin
+ * will not offer them.
+ */
+declare const devAiHubPermissions: _backstage_plugin_permission_common.BasicPermission[];
+
 /**
  * The v2 read contract: AiResource vocabulary, the flat ResourceSummary
  * returned by the backend, and the shared framework resolver (ADR-0003).
@@ -53,16 +147,74 @@ type FrameworkToken = (typeof KNOWN_FRAMEWORKS)[number];
 declare function normalizeFramework(token: string): string;
 /**
  * Narrow a resource's frameworks to a deployment-level allow-list
- * (`devAiHub.frameworks.allowed`). Omitting the config key (`allowed` is
- * `undefined`) permits every framework; an explicit empty list permits none,
- * so a deployment can suppress framework exposure entirely. Both sides are
- * normalised (aliases resolved) before comparison.
+ * (`devAiHub.frameworks.allowed`, unioned with the `custom` keys). Omitting
+ * the config key (`allowed` is `undefined`) permits every framework; an
+ * explicit empty list permits none, so a deployment can suppress framework
+ * exposure entirely. Both sides are normalised (aliases resolved) before
+ * comparison.
  *
  * The `all` wildcard is expanded to the allow-list itself before filtering, so
  * a resource that declares `all` degrades to "every permitted host" rather
- * than disappearing entirely.
+ * than disappearing entirely — minus `custom`, which `all` never reaches
+ * (ADR-0018): the wildcard means "every host the plugin knows", and claiming
+ * an internal assistant on every universal resource would be an assertion the
+ * author never made.
  */
-declare function filterAllowedFrameworks(frameworks: string[], allowed: string[] | undefined): string[];
+declare function filterAllowedFrameworks(frameworks: string[], allowed: string[] | undefined, custom?: readonly string[]): string[];
+/**
+ * A deployment-registered framework (`devAiHub.frameworks.custom`) — a tool
+ * the plugin does not ship knowledge of, named by the token its authors write
+ * in `spec.agents` (ADR-0018).
+ */
+interface CustomFramework {
+    /** Normalised token matched against a resource's declared frameworks. */
+    name: string;
+    /** Display label. Falls back to `name` when the config omits `displayName`. */
+    displayName: string;
+    /** Browser-loadable icon source; `undefined` selects the neutral fallback. */
+    icon?: string;
+}
+/** The raw per-token shape of `devAiHub.frameworks.custom`. */
+interface CustomFrameworkConfig {
+    displayName?: string;
+    icon?: string;
+}
+interface ParsedCustomFrameworks {
+    frameworks: CustomFramework[];
+    /**
+     * Human-readable reasons entries were dropped. The backend logs these; the
+     * frontend ignores them, but both run the same parse so they can never
+     * disagree about which tokens exist.
+     */
+    warnings: string[];
+}
+/**
+ * Parse `devAiHub.frameworks.custom` into the registry both sides read.
+ *
+ * Entries are dropped rather than rejected wholesale — one malformed entry
+ * must not take out a deployment's whole framework registry — and each drop
+ * carries a reason:
+ *
+ * - a key that normalises to empty has nothing to match against;
+ * - a key that collides with a built-in token or alias (`claude-code`,
+ *   `claude`) is ignored so built-ins stay authoritative: custom frameworks
+ *   are install-suppressed, and letting one shadow `claude-code` would
+ *   silently strip Claude's install paths;
+ * - a duplicate after normalisation keeps the first entry, since the second
+ *   would otherwise win non-deterministically.
+ */
+declare function parseCustomFrameworks(raw: unknown): ParsedCustomFrameworks;
+/**
+ * The allow-list actually applied, once `custom` is taken into account
+ * (ADR-0018). Registering a custom framework activates the gate even when
+ * `allowed` is omitted — otherwise the deployment would have registered a
+ * token that nothing distinguishes from the unknown tokens beside it.
+ *
+ * - no custom frameworks → `allowed` unchanged (including `undefined`);
+ * - `allowed` set → `allowed` ∪ custom;
+ * - `allowed` omitted → every built-in ∪ custom.
+ */
+declare function resolveAllowedFrameworks(allowed: string[] | undefined, custom: readonly string[]): string[] | undefined;
 /**
  * The minimal structural shape of an AiResource entity that the read helpers
  * need. A real `@backstage/catalog-model` `Entity` satisfies it, but keeping
@@ -133,22 +285,24 @@ interface ResourceSummary {
     sourceLocation?: string;
     frameworks: string[];
     /**
-     * True when an active deployment allow-list (`devAiHub.frameworks.allowed`)
-     * left this resource with no frameworks — either it removed the ones the
-     * author declared, or the allow-list itself is empty. Lets the UI tell
-     * "author declared nothing" (`frameworks: []`, show neutral install
-     * defaults) apart from "the deployment suppressed them" (hide generated
-     * install paths and launchers; Copy/Download still work).
+     * True when this resource has no generated install path to offer — either
+     * an active deployment allow-list (`devAiHub.frameworks.allowed`) left it
+     * with no frameworks, or every framework it does have is a custom,
+     * discovery-only one (ADR-0018). Lets the UI tell "author declared nothing"
+     * (`frameworks: []`, show neutral install defaults) apart from "nothing
+     * installable remains" (hide generated install paths and launchers;
+     * Copy/Download still work).
      */
     frameworksRestricted?: boolean;
     /**
      * The framework set that install-path and launcher generation must be
-     * scoped to, when it differs from `frameworks`. Only set for a resource
-     * that declared no frameworks (which otherwise means "every host") under an
-     * active allow-list: it holds the allow-list itself, so a bare resource
-     * cannot produce launchers for tools the deployment disallowed. Kept
-     * separate from `frameworks` so this inferred set never renders as a
-     * compatibility badge the author never claimed.
+     * scoped to, when it differs from `frameworks`. Two cases set it: a
+     * resource that declared no frameworks (which otherwise means "every host")
+     * under an active allow-list, where it holds the allow-list itself so a
+     * bare resource cannot produce launchers for disallowed tools; and a
+     * resource carrying custom frameworks, where it holds the remainder once
+     * those are removed (ADR-0018). Kept separate from `frameworks` so neither
+     * inferred set renders as a compatibility badge the author never claimed.
      */
     installFrameworks?: string[];
     version?: string;
@@ -170,6 +324,47 @@ interface ResourceSummary {
     childCount?: number;
     helpText?: string;
     annotations: Record<string, string>;
+    /**
+     * True when the resource is recommended from either source: its catalog
+     * tags carry `RECOMMENDED_TAG` (set by `toResourceSummary`, ADR-0020), or
+     * the backend router overlaid it from the `curation` table (ADR-0017).
+     * `undefined` and `false` both mean "not recommended"; only `true` renders
+     * the badge.
+     */
+    recommended?: boolean;
+    /**
+     * True when `recommended` comes from the entity's own `RECOMMENDED_TAG`
+     * (ADR-0020). Such a recommendation is owned by the resource's author, so
+     * the backoffice cannot remove it — only removing the tag can.
+     */
+    recommendedByTag?: boolean;
+    /**
+     * True when a curator recommended this resource in the backoffice — a
+     * `curation` row (ADR-0017). Can be true alongside `recommendedByTag`, for
+     * a row recorded before the author added the tag; the backoffice then
+     * offers to clear it, so that removing the tag really un-recommends.
+     */
+    recommendedByCuration?: boolean;
+    /**
+     * When the plugin first saw this resource, as an ISO timestamp — set by the
+     * backend router from its own `resource_first_seen` table (ADR-0021), since
+     * the catalog exposes no creation date. `undefined` for a resource that
+     * already existed when tracking began; the "Newest" sort ranks those as
+     * the oldest.
+     */
+    firstSeenAt?: string;
+    /**
+     * Set by the backend router from the `curation` table (ADR-0019), and only
+     * ever present when the caller explicitly asked for excluded resources via
+     * `?includeExcluded=true`. The default `GET /resources` response omits
+     * excluded resources entirely rather than flagging them, so on the browse
+     * page this field is always `undefined`.
+     */
+    excluded?: boolean;
+    /** Who last excluded this resource, for the backoffice's exclusion list. */
+    excludedBy?: string;
+    /** When it was last excluded, ISO-8601. */
+    excludedAt?: string;
 }
 interface ResourceListResponse {
     items: ResourceSummary[];
@@ -413,6 +608,64 @@ declare const TelemetryEventInputSchema: z.ZodObject<{
 type TelemetryEventInput = z.infer<typeof TelemetryEventInputSchema>;
 /** Raw per-action counts for one resource, as returned by `GET /telemetry/:ref`. */
 type TelemetryCounts = Record<TelemetryAction, number>;
+/**
+ * Raw per-action counts for every resource that has recorded at least one
+ * telemetry event, keyed by `entityRef`, as returned by `GET /telemetry`
+ * (#83 backoffice overview). A resource with no events at all is simply
+ * absent from the map — the caller already has the full resource list and
+ * can treat a missing key as zero, so the response only carries entries
+ * that mean something.
+ */
+type TelemetrySummary = Record<string, TelemetryCounts>;
+
+/**
+ * The named sort modes exposed on the browse page (issue #102). `usage` is
+ * the composite "most popular" score; `newest` orders by when the plugin
+ * first saw each resource (ADR-0021); `name` is the alphabetical fallback
+ * every list needs.
+ *
+ * The raw per-counter modes (installs, downloads, views) and "Recommended
+ * first" were dropped: `usage` already folds the counters into one ranking,
+ * and recommended resources are pinned in their own section above the grid,
+ * so sorting by the flag would only reorder a list it no longer contains.
+ *
+ * Deliberately no `framework` mode: `frameworks` is a multi-value array per
+ * resource, so a resource compatible with several tools has no single sort
+ * position — that dimension is a filter (the AI Tool dropdown), not a sort.
+ */
+declare const SortModeEnum: z.ZodEnum<["usage", "newest", "name"]>;
+type SortMode = z.infer<typeof SortModeEnum>;
+declare const SORT_MODES: readonly SortMode[];
+declare function isSortMode(value: unknown): value is SortMode;
+type SortDirection = 'asc' | 'desc';
+/**
+ * The default sort mode when no configuration is set and the mode a deployer
+ * gets on an unrecognised `devAiHub.ui.defaultSort` value (soft fallback —
+ * a typo'd config value must never blank the page).
+ */
+declare const DEFAULT_SORT_MODE: SortMode;
+/**
+ * Each mode's "obvious" direction — usage and newest rank highest (most
+ * popular, most recent) first, name reads A-Z. The dropdown and direction toggle reset to this whenever the user
+ * switches mode.
+ */
+declare const NATURAL_SORT_DIRECTION: Record<SortMode, SortDirection>;
+declare function usageScore(counts: TelemetryCounts | undefined): number;
+/**
+ * Sort resources by the given mode and direction. `counts` is the shared
+ * page-level telemetry summary map (entityRef -> raw counts) — a resource
+ * absent from the map is treated as all-zero, per `TelemetrySummary`'s
+ * contract.
+ *
+ * Every mode tie-breaks on Name (A-Z) so equal-scoring resources — the
+ * common case for a catalog with little or no telemetry yet — render in a
+ * predictable, stable order rather than arbitrary fetch order. The `name`
+ * mode itself has no primary key to break ties on, so it tie-breaks on
+ * `entityRef` instead (see `compareNames`).
+ *
+ * Pure and allocation-light: does not mutate `resources`.
+ */
+declare function sortResources(resources: readonly ResourceSummary[], mode: SortMode, direction: SortDirection, counts: Map<string, TelemetryCounts>): ResourceSummary[];
 
 /**
  * Whether a string is a parseable entity ref. The frontend links `owner` to
@@ -444,13 +697,16 @@ declare function toResourceSummary(entity: Entity): ResourceSummary | undefined;
  *
  * `opts.allowedFrameworks` (from `devAiHub.frameworks.allowed`) narrows every
  * summary's `frameworks` to the permitted set — undefined/empty allows all.
- * Applied here so the served payload is the single choke point: badges, the
- * "Works with" section, the framework filter and install-path generation all
- * read the already-filtered list.
+ * `opts.customFrameworks` (the keys of `devAiHub.frameworks.custom`) joins
+ * that set and, on its own, activates it (ADR-0018). Applied here so the
+ * served payload is the single choke point: badges, the "Works with" section,
+ * the framework filter and install-path generation all read the
+ * already-filtered list.
  */
 declare function toResourceSummaries(entities: Entity[], opts?: {
     allowedFrameworks?: string[];
+    customFrameworks?: string[];
 }): ResourceSummary[];
 
-export { AGENT_LINK_CAPABLE_FRAMEWORKS, ANNOTATION_COMPATIBLE_FRAMEWORKS, ANNOTATION_HELP, DEVAIHUB_ANNOTATION_PREFIX, INSTALLABLE_FRAMEWORKS, KNOWN_FRAMEWORKS, MARKETPLACE_CAPABLE_FRAMEWORKS, MARKETPLACE_MEMBER_TYPES, MCP_LINK_CAPABLE_FRAMEWORKS, PLUGIN_MEMBER_TYPES, PROMPT_LINK_CAPABLE_FRAMEWORKS, RESOURCE_TYPES, RESOURCE_TYPE_REGISTRY, TelemetryActionEnum, TelemetryEventInputSchema, expandInstallFrameworks, filterAllowedFrameworks, getAgentInstallLinks, getBodyShape, getFrameworks, getInstallSteps, getMarketplaceAddCommands, getMarketplaceInstallTemplate, getMarketplaceRepoSlug, getMarketplaceTeamSnippet, getMcpInstallLinks, getPromptInstallLinks, getResourceInstallTarget, hasCopyableBody, hasDownloadableArtifact, isParseableEntityRef, isRenderableContainment, isResourceType, normalizeFramework, resolveCapableFrameworks, showsContentSection, toResourceSummaries, toResourceSummary };
-export type { AiResourceEntityLike, BodyShape, FrameworkToken, InstallMode, MarketplaceAddCommand, ResourceDeepLink, ResourceInstallStep, ResourceInstallTarget, ResourceListResponse, ResourceSummary, ResourceType, ResourceTypeIcon, ResourceTypeInfo, TelemetryAction, TelemetryCounts, TelemetryEventInput };
+export { AGENT_LINK_CAPABLE_FRAMEWORKS, ANNOTATION_COMPATIBLE_FRAMEWORKS, ANNOTATION_HELP, DEFAULT_SORT_MODE, DEVAIHUB_ANNOTATION_PREFIX, ExclusionInputSchema, INSTALLABLE_FRAMEWORKS, KNOWN_FRAMEWORKS, MARKETPLACE_CAPABLE_FRAMEWORKS, MARKETPLACE_MEMBER_TYPES, MCP_LINK_CAPABLE_FRAMEWORKS, NATURAL_SORT_DIRECTION, PLUGIN_MEMBER_TYPES, PROMPT_LINK_CAPABLE_FRAMEWORKS, RECOMMENDED_TAG, RESOURCE_TYPES, RESOURCE_TYPE_REGISTRY, RecommendationInputSchema, SORT_MODES, SortModeEnum, TelemetryActionEnum, TelemetryEventInputSchema, devAiHubBackofficeCuratePermission, devAiHubBackofficeReadPermission, devAiHubPermissions, expandInstallFrameworks, filterAllowedFrameworks, getAgentInstallLinks, getBodyShape, getFrameworks, getInstallSteps, getMarketplaceAddCommands, getMarketplaceInstallTemplate, getMarketplaceRepoSlug, getMarketplaceTeamSnippet, getMcpInstallLinks, getPromptInstallLinks, getResourceInstallTarget, hasCopyableBody, hasDownloadableArtifact, isParseableEntityRef, isRenderableContainment, isResourceType, isSortMode, normalizeFramework, parseCustomFrameworks, resolveAllowedFrameworks, resolveCapableFrameworks, showsContentSection, sortResources, toResourceSummaries, toResourceSummary, usageScore };
+export type { AiResourceEntityLike, BodyShape, CurationRecord, CustomFramework, CustomFrameworkConfig, ExclusionInput, FrameworkToken, InstallMode, MarketplaceAddCommand, ParsedCustomFrameworks, RecommendationInput, ResourceDeepLink, ResourceInstallStep, ResourceInstallTarget, ResourceListResponse, ResourceSummary, ResourceType, ResourceTypeIcon, ResourceTypeInfo, SortDirection, SortMode, TelemetryAction, TelemetryCounts, TelemetryEventInput, TelemetrySummary };

package/dist/index.esm.js

@@ -1,4 +1,7 @@
-export { AGENT_LINK_CAPABLE_FRAMEWORKS, ANNOTATION_COMPATIBLE_FRAMEWORKS, ANNOTATION_HELP, DEVAIHUB_ANNOTATION_PREFIX, INSTALLABLE_FRAMEWORKS, KNOWN_FRAMEWORKS, MARKETPLACE_CAPABLE_FRAMEWORKS, MARKETPLACE_MEMBER_TYPES, MCP_LINK_CAPABLE_FRAMEWORKS, PLUGIN_MEMBER_TYPES, PROMPT_LINK_CAPABLE_FRAMEWORKS, RESOURCE_TYPES, RESOURCE_TYPE_REGISTRY, expandInstallFrameworks, filterAllowedFrameworks, getAgentInstallLinks, getBodyShape, getFrameworks, getInstallSteps, getMarketplaceAddCommands, getMarketplaceInstallTemplate, getMarketplaceRepoSlug, getMarketplaceTeamSnippet, getMcpInstallLinks, getPromptInstallLinks, getResourceInstallTarget, hasCopyableBody, hasDownloadableArtifact, isRenderableContainment, isResourceType, normalizeFramework, resolveCapableFrameworks, showsContentSection } from './resources.esm.js';
+export { ExclusionInputSchema, RECOMMENDED_TAG, RecommendationInputSchema } from './curation.esm.js';
+export { devAiHubBackofficeCuratePermission, devAiHubBackofficeReadPermission, devAiHubPermissions } from './permissions.esm.js';
+export { AGENT_LINK_CAPABLE_FRAMEWORKS, ANNOTATION_COMPATIBLE_FRAMEWORKS, ANNOTATION_HELP, DEVAIHUB_ANNOTATION_PREFIX, INSTALLABLE_FRAMEWORKS, KNOWN_FRAMEWORKS, MARKETPLACE_CAPABLE_FRAMEWORKS, MARKETPLACE_MEMBER_TYPES, MCP_LINK_CAPABLE_FRAMEWORKS, PLUGIN_MEMBER_TYPES, PROMPT_LINK_CAPABLE_FRAMEWORKS, RESOURCE_TYPES, RESOURCE_TYPE_REGISTRY, expandInstallFrameworks, filterAllowedFrameworks, getAgentInstallLinks, getBodyShape, getFrameworks, getInstallSteps, getMarketplaceAddCommands, getMarketplaceInstallTemplate, getMarketplaceRepoSlug, getMarketplaceTeamSnippet, getMcpInstallLinks, getPromptInstallLinks, getResourceInstallTarget, hasCopyableBody, hasDownloadableArtifact, isRenderableContainment, isResourceType, normalizeFramework, parseCustomFrameworks, resolveAllowedFrameworks, resolveCapableFrameworks, showsContentSection } from './resources.esm.js';
+export { DEFAULT_SORT_MODE, NATURAL_SORT_DIRECTION, SORT_MODES, SortModeEnum, isSortMode, sortResources, usageScore } from './sorting.esm.js';
 export { TelemetryActionEnum, TelemetryEventInputSchema } from './telemetry.esm.js';
 export { isParseableEntityRef, toResourceSummaries, toResourceSummary } from './toResourceSummary.esm.js';
 //# sourceMappingURL=index.esm.js.map

package/dist/index.esm.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.esm.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;"}
+{"version":3,"file":"index.esm.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;"}

package/dist/permissions.cjs.js

@@ -0,0 +1,21 @@
+'use strict';
+
+var pluginPermissionCommon = require('@backstage/plugin-permission-common');
+
+const devAiHubBackofficeReadPermission = pluginPermissionCommon.createPermission({
+  name: "dev-ai-hub.backoffice.read",
+  attributes: { action: "read" }
+});
+const devAiHubBackofficeCuratePermission = pluginPermissionCommon.createPermission({
+  name: "dev-ai-hub.backoffice.curate",
+  attributes: { action: "update" }
+});
+const devAiHubPermissions = [
+  devAiHubBackofficeReadPermission,
+  devAiHubBackofficeCuratePermission
+];
+
+exports.devAiHubBackofficeCuratePermission = devAiHubBackofficeCuratePermission;
+exports.devAiHubBackofficeReadPermission = devAiHubBackofficeReadPermission;
+exports.devAiHubPermissions = devAiHubPermissions;
+//# sourceMappingURL=permissions.cjs.js.map

package/dist/permissions.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.cjs.js","sources":["../src/permissions.ts"],"sourcesContent":["import { createPermission } from '@backstage/plugin-permission-common';\n\n/**\n * Opening the Dev AI Hub backoffice (ADR-0016).\n *\n * Held in `-common` because both sides need the same identity: the backend\n * registers it so the Backstage RBAC plugin can list and grant it, and the\n * frontend checks it to decide whether the surface exists for this user at all.\n *\n * Read-only on purpose. Every governance capability that writes — curation\n * (#68, ADR-0017), tool visibility (#85) — gets its own permission rather\n * than riding on this one, so \"can see the backoffice\" never silently\n * becomes \"can change the catalog's presentation\".\n */\nexport const devAiHubBackofficeReadPermission = createPermission({\n  name: 'dev-ai-hub.backoffice.read',\n  attributes: { action: 'read' },\n});\n\n/**\n * Changing a resource's curation state — currently just \"recommended\"\n * (ADR-0017), later also demote/hide (#68) — from the backoffice.\n *\n * Scoped to the capability, not to one action: a future demote or hide\n * reuses this permission rather than minting one each, the same way granting\n * someone curation trust once covers whichever curation actions the backoffice\n * exposes. Separate from `dev-ai-hub.backoffice.read` so seeing the backoffice\n * never implies being able to write to it.\n */\nexport const devAiHubBackofficeCuratePermission = createPermission({\n  name: 'dev-ai-hub.backoffice.curate',\n  attributes: { action: 'update' },\n});\n\n/**\n * Every permission this plugin owns, for bulk registration with the backend's\n * permissions registry. New permissions must be added here or the RBAC plugin\n * will not offer them.\n */\nexport const devAiHubPermissions = [\n  devAiHubBackofficeReadPermission,\n  devAiHubBackofficeCuratePermission,\n];\n"],"names":["createPermission"],"mappings":";;;;AAcO,MAAM,mCAAmCA,uCAAA,CAAiB;AAAA,EAC/D,IAAA,EAAM,4BAAA;AAAA,EACN,UAAA,EAAY,EAAE,MAAA,EAAQ,MAAA;AACxB,CAAC;AAYM,MAAM,qCAAqCA,uCAAA,CAAiB;AAAA,EACjE,IAAA,EAAM,8BAAA;AAAA,EACN,UAAA,EAAY,EAAE,MAAA,EAAQ,QAAA;AACxB,CAAC;AAOM,MAAM,mBAAA,GAAsB;AAAA,EACjC,gCAAA;AAAA,EACA;AACF;;;;;;"}

package/dist/permissions.esm.js

@@ -0,0 +1,17 @@
+import { createPermission } from '@backstage/plugin-permission-common';
+
+const devAiHubBackofficeReadPermission = createPermission({
+  name: "dev-ai-hub.backoffice.read",
+  attributes: { action: "read" }
+});
+const devAiHubBackofficeCuratePermission = createPermission({
+  name: "dev-ai-hub.backoffice.curate",
+  attributes: { action: "update" }
+});
+const devAiHubPermissions = [
+  devAiHubBackofficeReadPermission,
+  devAiHubBackofficeCuratePermission
+];
+
+export { devAiHubBackofficeCuratePermission, devAiHubBackofficeReadPermission, devAiHubPermissions };
+//# sourceMappingURL=permissions.esm.js.map

package/dist/permissions.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.esm.js","sources":["../src/permissions.ts"],"sourcesContent":["import { createPermission } from '@backstage/plugin-permission-common';\n\n/**\n * Opening the Dev AI Hub backoffice (ADR-0016).\n *\n * Held in `-common` because both sides need the same identity: the backend\n * registers it so the Backstage RBAC plugin can list and grant it, and the\n * frontend checks it to decide whether the surface exists for this user at all.\n *\n * Read-only on purpose. Every governance capability that writes — curation\n * (#68, ADR-0017), tool visibility (#85) — gets its own permission rather\n * than riding on this one, so \"can see the backoffice\" never silently\n * becomes \"can change the catalog's presentation\".\n */\nexport const devAiHubBackofficeReadPermission = createPermission({\n  name: 'dev-ai-hub.backoffice.read',\n  attributes: { action: 'read' },\n});\n\n/**\n * Changing a resource's curation state — currently just \"recommended\"\n * (ADR-0017), later also demote/hide (#68) — from the backoffice.\n *\n * Scoped to the capability, not to one action: a future demote or hide\n * reuses this permission rather than minting one each, the same way granting\n * someone curation trust once covers whichever curation actions the backoffice\n * exposes. Separate from `dev-ai-hub.backoffice.read` so seeing the backoffice\n * never implies being able to write to it.\n */\nexport const devAiHubBackofficeCuratePermission = createPermission({\n  name: 'dev-ai-hub.backoffice.curate',\n  attributes: { action: 'update' },\n});\n\n/**\n * Every permission this plugin owns, for bulk registration with the backend's\n * permissions registry. New permissions must be added here or the RBAC plugin\n * will not offer them.\n */\nexport const devAiHubPermissions = [\n  devAiHubBackofficeReadPermission,\n  devAiHubBackofficeCuratePermission,\n];\n"],"names":[],"mappings":";;AAcO,MAAM,mCAAmC,gBAAA,CAAiB;AAAA,EAC/D,IAAA,EAAM,4BAAA;AAAA,EACN,UAAA,EAAY,EAAE,MAAA,EAAQ,MAAA;AACxB,CAAC;AAYM,MAAM,qCAAqC,gBAAA,CAAiB;AAAA,EACjE,IAAA,EAAM,8BAAA;AAAA,EACN,UAAA,EAAY,EAAE,MAAA,EAAQ,QAAA;AACxB,CAAC;AAOM,MAAM,mBAAA,GAAsB;AAAA,EACjC,gCAAA;AAAA,EACA;AACF;;;;"}