@intentic/registry 1.223.0 → 1.225.0

package/README.md

@@ -1,6 +1,6 @@
 # @intentic/registry
 
-The **extension-registry file format** — what a registry repo contains, how its two files join, and the order
+The **extension-registry file format**: what a registry repo contains, how its two files join, and the order
 the result is shown in. Published to npm, and depended on by three otherwise-unrelated consumers, which is the
 whole reason it is a package: the daemon that clones a registry, the site that builds the public gallery, and
 the [scanner](../../_tools/registry-scan) that writes the files. One zod schema instead of three that drift.
@@ -10,7 +10,7 @@ below, and [Verification & trust](https://intentic.dev/developers/verify/) for w
 
 ## The shape of it
 
-intentic hosts no extension code, builds none, and signs none. **A registry is a git repo of pointers** —
+intentic hosts no extension code, builds none, and signs none. **A registry is a git repo of pointers**:
 each entry names somebody else's repository at a commit, and installing follows that pointer from the owner's
 sandbox straight to the author's git host. Listing costs a pull request; delisting removes a pointer and
 deletes nothing.
@@ -23,13 +23,13 @@ lists a team's agent plugins and its intentic extensions together.
 
 | File | Written by | Holds |
 | --- | --- | --- |
-| `.claude-plugin/marketplace.json` | humans + protected admission workflow | every decision — what is listed, the exact source, trust level, and source-bound security record |
+| `.claude-plugin/marketplace.json` | humans + protected admission workflow | every decision: what is listed, the exact source, trust level, and source-bound security record |
 | `.claude-plugin/registry.generated.json` | the nightly scanner | only facts read back off the source host: stars, last push |
 
 Keeping the derived data out of the curated file is load-bearing, not tidiness. Star counts in the hand-edited
 file would make every nightly refresh a merge conflict against every open listing pull request, and would bury
 the decision under churn in the review diff. A registry with no generated file is a registry with no stars,
-which renders fine — most registries are a dozen internal extensions in a private repo and run no scanner.
+which renders fine: most registries are a dozen internal extensions in a private repo and run no scanner.
 
 [`resolveRegistry`](src/registry.ts) joins them by entry name into `RegistryEntry`, which is also the daemon's
 browse wire shape, so the app's list and the website's gallery are the same rows in the same order.
@@ -48,7 +48,7 @@ with install disabled and is omitted from the public gallery; it cannot become a
 the runtime backstop behind the registry's required PR check.
 
 A blocked entry stays in the file. Deleting the row hides it from people browsing and tells the people who
-already installed it nothing, which is backwards — they are the ones at risk. Absent on a third-party registry
+already installed it nothing, which is backwards: they are the ones at risk. Absent on a third-party registry
 resolves to `listed`, because a registry that doesn't use the field hasn't asserted anything.
 Third-party registries are their own admission boundary: their non-blocked rows remain installable without
 adopting intentic's gate or policy, and the app states when they carry no audit record.
@@ -56,40 +56,40 @@ adopting intentic's gate or policy, and the app states when they carry no audit
 Installed sandboxes read these states back on a daily comparison, so trust reaches the people past the browse
 moment too: a row turned `blocked` raises an advisory on the installed extension (and, by default, switches it
 off), and `securityFix: true` on an entry marks its pinned commit as fixing a security problem in earlier ones
-— the installed side promotes its update badge from ambient to loud, because there the OLD version is the
+- the installed side promotes its update badge from ambient to loud, because there the OLD version is the
 dangerous one. Both are asserted by pull request, like `trust`, and are worth exactly that review.
 
 ## Tier, and what premium buys into
 
-`tier` is the listing's price: `free` (the default, and the whole story for most rows) or `premium` — the
+`tier` is the listing's price: `free` (the default, and the whole story for most rows) or `premium`, the
 listing opts into the **creator pool**. A premium row needs an intentic membership, both surfaces badge it
 before the click, and installing it **donates a published number of the member's credits to the publisher**
-(once, deduped monthly — updates donate again at most monthly). No usage is metered or reported anywhere;
+(once, deduped monthly: updates donate again at most monthly). No usage is metered or reported anywhere;
 the deliberate install is the whole signal. The economics live in
 [The creator pool](https://intentic.dev/earn/).
 
 ## The mark
 
-A row carries the two display tiers the manifest declares — `logo` (a simple-icons slug) and `icon` (a glyph
-from the app's own set) — and the [scanner](../../_tools/registry-scan) copies whichever is set into the listing it
+A row carries the two display tiers the manifest declares: `logo` (a simple-icons slug) and `icon` (a glyph
+from the app's own set): and the [scanner](../../_tools/registry-scan) copies whichever is set into the listing it
 proposes, exactly as it copies the version. A row with neither is drawn as the extension's initials.
 
 They ride the **curated** file, which looks wrong for a copied value until you ask what the two files are for:
 the mark is part of how a listing presents itself, so it belongs in the row a human reviews and can correct.
-It also has to be here to be worth anything — the gallery and the app's browse list render this row and have
+It also has to be here to be worth anything: the gallery and the app's browse list render this row and have
 no access to the manifest, because the whole point of browsing is that the code has not been cloned yet.
 
 ## The order
 
 [`compareEntries`](src/registry.ts): verified first, then stars, then most-recently-pushed, then name. Stars
-are the obvious sort and the wrong one alone — every listing sits at nought to three of them for months, so a
+are the obvious sort and the wrong one alone: every listing sits at nought to three of them for months, so a
 pure star sort is a random order wearing a merit badge, and it is the most purchasable number on GitHub.
 Recency is what actually does the ordering early on. Stars stay visible; they just don't get to be the
 ranking.
 
 ## Identity
 
-An entry's `name` is `publisher.name` from the manifest — [`extensionIdOf`](../extension-api/src/manifest.ts),
+An entry's `name` is `publisher.name` from the manifest: [`extensionIdOf`](../extension-api/src/manifest.ts),
 the same identity the app installs under. It is derived, never declared by the registry, so a registry entry
 cannot rename or spoof an extension, and a repo that copies somebody else's manifest collides with their
 listing instead of shadowing it.
@@ -107,6 +107,6 @@ exists because neither those signatures nor manifest validation can answer malic
 
 ## Key files
 
-- [src/registry.ts](src/registry.ts) — the file format: what a registry repo contains.
-- [src/source.ts](src/source.ts) — how a sha-pinned pointer names an extension.
-- [src/index.ts](src/index.ts) — the public surface.
+- [src/registry.ts](src/registry.ts), the file format: what a registry repo contains.
+- [src/source.ts](src/source.ts): how a sha-pinned pointer names an extension.
+- [src/index.ts](src/index.ts): the public surface.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@intentic/registry",
-  "version": "1.223.0",
-  "description": "The extension-registry file format — a git repo of sha-pinned pointers, shared by the daemon, the site gallery and the scanner",
+  "version": "1.225.0",
+  "description": "The extension-registry file format, a git repo of sha-pinned pointers, shared by the daemon, the site gallery and the scanner",
   "license": "MIT",
   "type": "module",
   "repository": {

package/src/registry.test.ts

@@ -113,9 +113,9 @@ describe(`resolveRegistry`, () => {
         expect(resolveRegistry(premium, undefined, REGISTRY)[0]?.tier).toBe(`premium`);
     });
 
-    // Blocked rows must survive the resolve — deleting them is what hides a warning from the people who
+    // Blocked rows must survive the resolve: deleting them is what hides a warning from the people who
     /* The staleness rule the checks ride on: a fact is bound to the sha it was derived from, and a listing
-     * repointed since the last scan renders no checks at all — the honest gap — rather than yesterday's verdict
+     * repointed since the last scan renders no checks at all (the honest gap) rather than yesterday's verdict
      * describing today's pointer. */
     it(`joins checks only when they were derived from the sha the listing still pins`, () => {
         const facts = RegistryFactsSchema.parse({

package/src/registry.ts

@@ -4,15 +4,15 @@ import { type RegistryInstall, RegistryInstallSchema, resolveSource } from "./so
 /* THE EXTENSION REGISTRY: a git repo of pointers, and the two files in it.
  *
  * intentic hosts no extension code, builds none, and signs none. A registry is a repository whose
- * `.claude-plugin/marketplace.json` lists pointers to other people's repositories at a commit — so listing
+ * `.claude-plugin/marketplace.json` lists pointers to other people's repositories at a commit, so listing
  * costs a pull request, delisting deletes nothing, and anybody can run their own registry against a private
  * one. That file is Claude Code's plugin-marketplace format deliberately: `kind` and `trust` are intentic's
  * own fields and Claude Code ignores what it doesn't know, so one repo serves both consumers.
  *
- * The split into TWO files is the load-bearing part. `marketplace.json` is hand-edited and is the only place a
+ * The split into TWO files is the part that matters. `marketplace.json` is hand-edited and is the only place a
  * curated decision and source-bound admission are recorded; `registry.generated.json` is bot-written and holds
  * nothing but facts read back off the source host. Keeping star counts out of the curated file is what stops every nightly refresh from
- * being a merge conflict against an open pull request — and it keeps the review diff to the thing being
+ * being a merge conflict against an open pull request, and it keeps the review diff to the thing being
  * decided. A registry that carries no generated file is a registry with no stars, which renders fine. */
 
 // Repo-relative, and the same two strings for the daemon (which clones), the scanner (which commits) and the
@@ -24,7 +24,7 @@ export const REGISTRY_FACTS_FILE = ".claude-plugin/registry.generated.json";
 // field stays editable, so a company points it at an internal registry and never touches this one.
 export const OFFICIAL_REGISTRY_URL = "https://github.com/intentic/registry";
 
-// The GitHub topic an author adds to be found. This is discovery only — appearing in the scan gets you a pull
+// The GitHub topic an author adds to be found. This is discovery only, appearing in the scan gets you a pull
 // request against the registry, never a listing.
 export const REGISTRY_TOPIC = "intentic-extension";
 
@@ -65,7 +65,7 @@ export type RegistrySecurityReview = z.infer<typeof RegistrySecurityReviewSchema
  * - `verified` both automated checks passed and a human also read the source at that sha. Sorted first and badged.
  * - `blocked`  known-malicious or known-broken. It STAYS in the file with a reason rather than being deleted:
  *              removing the row hides it from people browsing and tells the people who already installed it
- *              nothing, which is backwards — they are the ones at risk.
+ *              nothing, which is backwards, they are the ones at risk.
  *
  * Absent on a third-party registry ⇒ `listed`, because a registry that doesn't use the field hasn't asserted
  * anything and shouldn't be read as if it had. */
@@ -74,10 +74,10 @@ export type RegistryTrust = z.infer<typeof RegistryTrustSchema>;
 
 /* WHAT A LISTING COSTS. `free` is the default and the whole story for most rows. `premium` opts the listing
  * into the creator pool: installing it requires an intentic membership and donates a published number of the
- * member's credits to the publisher (once, deduped monthly — an update in a later month donates again), and
+ * member's credits to the publisher (once, deduped monthly, an update in a later month donates again), and
  * both surfaces badge it so the price is visible before the click. No usage is ever metered or reported for
  * this; the deliberate act of installing is the whole signal. On a third-party registry the field still
- * parses but means nothing — the pool only pays listings the platform's members actually install. */
+ * parses but means nothing, the pool only pays listings the platform's members actually install. */
 export const RegistryTierSchema = z.enum(["free", "premium"]);
 export type RegistryTier = z.infer<typeof RegistryTierSchema>;
 
@@ -89,27 +89,27 @@ const RegistryFileEntrySchema = z
         // "extension" installs as the sha-pinned `extension` capability; absent/"plugin" is a Claude Code plugin.
         kind: z.enum(["plugin", "extension"]).optional(),
         trust: RegistryTrustSchema.optional(),
-        // Why it is blocked, or what was checked to verify it — shown verbatim wherever the badge is, because a
+        // Why it is blocked, or what was checked to verify it, shown verbatim wherever the badge is, because a
         // trust state with no stated reason is an opinion the reader can't weigh.
         trustReason: z.string().optional(),
         // Both automated checks' evidence, bound to the complete source identity below. It is deliberately
         // distinct from `trust: verified`: passing admission admits code; verified additionally says a human
         // read it. Keeping those claims apart stops automated verdicts being presented as human review.
         securityReview: RegistrySecurityReviewSchema.optional(),
-        // This listing's pinned commit fixes a security problem in earlier commits — the fast lane: an installed
+        // This listing's pinned commit fixes a security problem in earlier commits, the fast lane: an installed
         // sandbox promotes its "update available" badge from ambient to attention-demanding, because there the OLD
         // version is the dangerous one. Asserted by the pull request like trust, and worth exactly that review.
         securityFix: z.boolean().optional(),
         tier: RegistryTierSchema.optional(),
         category: z.string().optional(),
         /* The mark the row is drawn with, copied off the extension's manifest exactly like the description and
-         * the version — the same three tiers the manifest declares (the author's own inline drawing, then a
+         * the version, the same three tiers the manifest declares (the author's own inline drawing, then a
          * simple-icons slug, then a name from the app's icon set), and none is required.
          *
          * It rides the CURATED file rather than the generated one, which looks wrong for a derived value until you
          * ask what a registry is for: a listing is what a human decided to publish, and the mark is part of how it
          * presents itself, so it belongs in the row a reviewer reads and can strike out. The generated file holds
-         * only what a bot re-reads nightly and nobody reviews. It also has to be here to be of any use at all —
+         * only what a bot re-reads nightly and nobody reviews. It also has to be here to be of any use at all,
          * this is what the gallery and the in-app browse list render, and neither of them has the manifest: the
          * whole point of the row is that the code has NOT been cloned yet.
          *
@@ -166,15 +166,15 @@ export type RegistryFile = z.infer<typeof RegistryFileSchema>;
 /* Facts read off the source host, keyed by the curated entry's name. Deliberately NOT the upstream head sha:
  * the approved sha is the one that runs, updating is a pull request, and a file that advertised "there's a
  * newer commit over there" would be inviting a click that skips the review the whole model rests on. */
-/* What the scan re-derived COLD at the listing's pinned sha — the same questions the daemon's readiness check
+/* What the scan re-derived COLD at the listing's pinned sha, the same questions the daemon's readiness check
  * answers for an author before publishing, asked again by a stranger with nothing but the pointer. That
  * re-derivation is the whole value: an author's own checks describe the directory they ran them in, and these
  * describe what an installer actually gets. `sha` binds the answers to the commit they were read from, so a
- * listing repointed since the last scan renders no stale verdicts — the join drops checks whose sha no longer
+ * listing repointed since the last scan renders no stale verdicts, the join drops checks whose sha no longer
  * matches rather than letting yesterday's answer describe today's pointer. */
 const RegistryChecksSchema = z.object({
     sha: z.string(),
-    // "ok", or the reason it is not, verbatim — a verdict with no stated reason is an opinion.
+    // "ok", or the reason it is not, verbatim, a verdict with no stated reason is an opinion.
     manifest: z.string(),
     // "ok" / "none" (no UI bundle) / the reason the bundle cannot load where it is installed.
     bundle: z.string(),
@@ -187,7 +187,7 @@ export type RegistryChecks = z.infer<typeof RegistryChecksSchema>;
 const RegistryFactsEntrySchema = z.object({
     name: z.string(),
     stars: z.number().int().nonnegative().optional(),
-    // ISO-8601, last push to the source repo's default branch — the tiebreaker that does the real work while
+    // ISO-8601, last push to the source repo's default branch, the tiebreaker that does the real work while
     // every listing still has single-digit stars.
     pushedAt: z.string().optional(),
     checks: RegistryChecksSchema.optional(),
@@ -200,7 +200,7 @@ export const RegistryFactsSchema = z.object({
 export type RegistryFacts = z.infer<typeof RegistryFactsSchema>;
 
 // One row as every surface consumes it: the curated decision, the resolved pointer, and the upstream facts,
-// already joined. This is also the daemon's browse wire shape — the app renders what the site renders.
+// already joined. This is also the daemon's browse wire shape, the app renders what the site renders.
 export const RegistryEntrySchema = z.object({
     name: z.string(),
     description: z.string().optional(),
@@ -217,7 +217,7 @@ export const RegistryEntrySchema = z.object({
     securityFix: z.boolean().optional(),
     tier: RegistryTierSchema,
     category: z.string().optional(),
-    // The mark, as the gallery and the app's browse list draw it — see the curated file's fields above.
+    // The mark, as the gallery and the app's browse list draw it, see the curated file's fields above.
     art: z.string().optional(),
     logo: z.string().optional(),
     icon: z.string().optional(),
@@ -265,7 +265,7 @@ export const isCurrentSecurityReview = (review: RegistrySecurityReview | undefin
     review.deterministic.version === OFFICIAL_DETERMINISTIC_SCANNER_VERSION;
 
 /* Join the curated file to the generated facts. `facts` is undefined for any registry that runs no scanner,
- * which is most of them — a private registry of six internal extensions wants the pointers and nothing else. */
+ * which is most of them, a private registry of six internal extensions wants the pointers and nothing else. */
 export const resolveRegistry = (file: RegistryFile, facts: RegistryFacts | undefined, registryUrl: string): RegistryEntry[] => {
     const byName = new Map(facts?.entries.map((entry) => [entry.name, entry]) ?? []);
     const official = isOfficialRegistryUrl(registryUrl);
@@ -295,7 +295,7 @@ export const resolveRegistry = (file: RegistryFile, facts: RegistryFacts | undef
             ...(install !== undefined ? { install } : {}),
             ...(upstream?.stars !== undefined ? { stars: upstream.stars } : {}),
             ...(upstream?.pushedAt !== undefined ? { pushedAt: upstream.pushedAt } : {}),
-            // Only when derived from the sha this row still points at — a repointed listing renders no checks
+            // Only when derived from the sha this row still points at, a repointed listing renders no checks
             // until the next scan, which is the honest gap rather than yesterday's verdict on today's pointer.
             ...(upstream?.checks !== undefined && upstream.checks.sha === install?.ref ? { checks: upstream.checks } : {}),
         };
@@ -305,7 +305,7 @@ export const resolveRegistry = (file: RegistryFile, facts: RegistryFacts | undef
 /* THE ORDER, and why it isn't just stars.
  *
  * Stars are the obvious sort and the wrong one on day one: every listing will sit at nought to three of them
- * for months, so a pure star sort is a random order wearing a merit badge — and it is the single most
+ * for months, so a pure star sort is a random order wearing a merit badge, and it is the single most
  * purchasable number on GitHub. So: the one field a human actually asserted leads, stars rank within that,
  * and recency breaks the ties that will be the overwhelmingly common case early on. Stars stay VISIBLE
  * either way; a reader can weigh them, they just don't get to be the whole ranking. */

package/src/source.test.ts

@@ -31,7 +31,7 @@ describe(`resolveSource`, () => {
         });
     });
 
-    // An unclonable source is a row we still show — undefined here becomes "not installable", not a dropped entry.
+    // An unclonable source is a row we still show: undefined here becomes "not installable", not a dropped entry.
     it(`gives up on shapes it cannot clone rather than throwing`, () => {
         expect(resolveSource({ source: `npm`, package: `@acme/incidents` }, REGISTRY, undefined)).toBeUndefined();
         expect(resolveSource({ source: `github` }, REGISTRY, undefined)).toBeUndefined();

package/src/source.ts

@@ -2,10 +2,10 @@ import { z } from "zod";
 
 /* WHERE A REGISTRY ENTRY'S CODE LIVES, and how that resolves to something cloneable.
  *
- * A registry never hosts code — an entry is a pointer to somebody else's repository at a commit. `source` is
+ * A registry never hosts code, an entry is a pointer to somebody else's repository at a commit. `source` is
  * that pointer in the shapes Claude Code's plugin-marketplace format already defines, so one registry repo
  * serves both consumers; `resolveSource` maps the shapes we can clone onto the url/ref/path a capability
- * install takes, and returns undefined for the ones we can't (npm, say) rather than dropping the entry —
+ * install takes, and returns undefined for the ones we can't (npm, say) rather than dropping the entry,
  * an entry that exists but can't be installed in a click is information, a missing row is a bug report. */
 
 // The resolved pointer: exactly the fields a plugin- or extension-capability install needs.
@@ -46,14 +46,14 @@ export const resolveSource = (source: unknown, registryUrl: string, pluginRoot:
 
 const FULL_SHA = /^[0-9a-f]{40}$/;
 
-/* Whether this pointer names one immutable commit. An EXTENSION install requires it — extension code runs
+/* Whether this pointer names one immutable commit. An EXTENSION install requires it, extension code runs
  * trusted in the owner's browser, so the approved code and the running code have to be the same object, and a
  * branch name is a promise the upstream can break with a force-push. A registry entry that gives only a branch
  * is still listed and still readable; it just can't be a one-click install, which is the pressure that makes
  * authors pin. Plugins are laxer by design: they load into the agent, not the browser. */
 export const isShaPinned = (install: RegistryInstall | undefined): boolean => install?.ref !== undefined && FULL_SHA.test(install.ref);
 
-// `owner/repo` for a GitHub pointer — what the scanner keys upstream facts by, and what the gallery links to.
+// `owner/repo` for a GitHub pointer, what the scanner keys upstream facts by, and what the gallery links to.
 // Undefined for any host that isn't GitHub, which is a listing we simply carry no stars for.
 export const githubRepoOf = (install: RegistryInstall | undefined): string | undefined => {
     if (install === undefined) {