@intentic/registry 1.176.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Artur Kurowski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,82 @@
+# @intentic/registry
+
+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.
+
+See [Publish & the marketplace](https://intentic.dev/docs/extensions/publish/) for the author-facing version
+of everything below.
+
+## The shape of it
+
+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.
+
+The file is `.claude-plugin/marketplace.json`, Claude Code's plugin-marketplace format, deliberately.
+`kind` and `trust` are intentic's own fields and Claude Code ignores what it doesn't recognise, so one repo
+lists a team's agent plugins and its intentic extensions together.
+
+## Two files, and why
+
+| File | Written by | Holds |
+| --- | --- | --- |
+| `.claude-plugin/marketplace.json` | humans, via pull request | every decision — what is listed, and at which commit and trust level |
+| `.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.
+
+[`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.
+
+## Trust, and what each state claims
+
+`listed` is the honest default: the pointer resolves, the manifest parses, the publisher owns the source repo,
+and **nobody read the code**. `verified` means a human read the source at that commit. `blocked` means
+known-malicious or known-broken, with the reason alongside.
+
+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
+resolves to `listed`, because a registry that doesn't use the field hasn't asserted anything.
+
+## 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
+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
+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
+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),
+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.
+
+[`isShaPinned`](src/source.ts) is the other half: an extension install requires a full 40-character commit sha,
+because extension code runs trusted in the owner's browser and a branch name is a promise the upstream can
+break with a force-push. A registry entry without one still lists and still reads; it just can't be installed
+in a click.
+
+## 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.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./registry.js";
+export * from "./source.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./registry.js";
+export * from "./source.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC"}

package/dist/registry.d.ts

@@ -0,0 +1,77 @@
+import { z } from "zod";
+export declare const REGISTRY_FILE = ".claude-plugin/marketplace.json";
+export declare const REGISTRY_FACTS_FILE = ".claude-plugin/registry.generated.json";
+export declare const OFFICIAL_REGISTRY_URL = "https://github.com/intentic/registry";
+export declare const REGISTRY_TOPIC = "intentic-extension";
+export declare const RegistryTrustSchema: z.ZodEnum<{
+    blocked: "blocked";
+    listed: "listed";
+    verified: "verified";
+}>;
+export type RegistryTrust = z.infer<typeof RegistryTrustSchema>;
+export declare const RegistryFileSchema: z.ZodObject<{
+    name: z.ZodString;
+    metadata: z.ZodOptional<z.ZodObject<{
+        pluginRoot: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    plugins: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        version: z.ZodOptional<z.ZodString>;
+        kind: z.ZodOptional<z.ZodEnum<{
+            extension: "extension";
+            plugin: "plugin";
+        }>>;
+        trust: z.ZodOptional<z.ZodEnum<{
+            blocked: "blocked";
+            listed: "listed";
+            verified: "verified";
+        }>>;
+        trustReason: z.ZodOptional<z.ZodString>;
+        category: z.ZodOptional<z.ZodString>;
+        logo: z.ZodOptional<z.ZodString>;
+        icon: z.ZodOptional<z.ZodString>;
+        homepage: z.ZodOptional<z.ZodURL>;
+        source: z.ZodUnknown;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type RegistryFile = z.infer<typeof RegistryFileSchema>;
+export declare const RegistryFactsSchema: z.ZodObject<{
+    scannedAt: z.ZodString;
+    entries: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        stars: z.ZodOptional<z.ZodNumber>;
+        pushedAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type RegistryFacts = z.infer<typeof RegistryFactsSchema>;
+export declare const RegistryEntrySchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    version: z.ZodOptional<z.ZodString>;
+    kind: z.ZodEnum<{
+        extension: "extension";
+        plugin: "plugin";
+    }>;
+    trust: z.ZodEnum<{
+        blocked: "blocked";
+        listed: "listed";
+        verified: "verified";
+    }>;
+    trustReason: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodString>;
+    logo: z.ZodOptional<z.ZodString>;
+    icon: z.ZodOptional<z.ZodString>;
+    homepage: z.ZodOptional<z.ZodString>;
+    install: z.ZodOptional<z.ZodObject<{
+        url: z.ZodString;
+        ref: z.ZodOptional<z.ZodString>;
+        path: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    stars: z.ZodOptional<z.ZodNumber>;
+    pushedAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type RegistryEntry = z.infer<typeof RegistryEntrySchema>;
+export declare const resolveRegistry: (file: RegistryFile, facts: RegistryFacts | undefined, registryUrl: string) => RegistryEntry[];
+export declare const compareEntries: (a: RegistryEntry, b: RegistryEntry) => number;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAmBxB,eAAO,MAAM,aAAa,oCAAoC,CAAC;AAC/D,eAAO,MAAM,mBAAmB,2CAA2C,CAAC;AAI5E,eAAO,MAAM,qBAAqB,yCAAyC,CAAC;AAI5E,eAAO,MAAM,cAAc,uBAAuB,CAAC;AAanD,eAAO,MAAM,mBAAmB;;;;EAA4C,CAAC;AAC7E,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AA6BhE,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;iBAI7B,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAa9D,eAAO,MAAM,mBAAmB;;;;;;;iBAG9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAIhE,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;iBAiB9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAIhE,eAAO,MAAM,eAAe,SAAU,YAAY,SAAS,aAAa,GAAG,SAAS,eAAe,MAAM,KAAG,aAAa,EAqBxH,CAAC;AASF,eAAO,MAAM,cAAc,MAAO,aAAa,KAAK,aAAa,KAAG,MAWnE,CAAC"}

package/dist/registry.js

@@ -0,0 +1,84 @@
+import { z } from "zod";
+import { RegistryInstallSchema, resolveSource } from "./source.js";
+export const REGISTRY_FILE = ".claude-plugin/marketplace.json";
+export const REGISTRY_FACTS_FILE = ".claude-plugin/registry.generated.json";
+export const OFFICIAL_REGISTRY_URL = "https://github.com/intentic/registry";
+export const REGISTRY_TOPIC = "intentic-extension";
+export const RegistryTrustSchema = z.enum(["verified", "listed", "blocked"]);
+const RegistryFileEntrySchema = z.object({
+    name: z.string(),
+    description: z.string().optional(),
+    version: z.string().optional(),
+    kind: z.enum(["plugin", "extension"]).optional(),
+    trust: RegistryTrustSchema.optional(),
+    trustReason: z.string().optional(),
+    category: z.string().optional(),
+    logo: z.string().optional(),
+    icon: z.string().optional(),
+    homepage: z.url().optional(),
+    source: z.unknown(),
+});
+export const RegistryFileSchema = z.object({
+    name: z.string(),
+    metadata: z.object({ pluginRoot: z.string().optional() }).optional(),
+    plugins: z.array(RegistryFileEntrySchema),
+});
+const RegistryFactsEntrySchema = z.object({
+    name: z.string(),
+    stars: z.number().int().nonnegative().optional(),
+    pushedAt: z.string().optional(),
+});
+export const RegistryFactsSchema = z.object({
+    scannedAt: z.string(),
+    entries: z.array(RegistryFactsEntrySchema),
+});
+export const RegistryEntrySchema = z.object({
+    name: z.string(),
+    description: z.string().optional(),
+    version: z.string().optional(),
+    kind: z.enum(["plugin", "extension"]),
+    trust: RegistryTrustSchema,
+    trustReason: z.string().optional(),
+    category: z.string().optional(),
+    logo: z.string().optional(),
+    icon: z.string().optional(),
+    homepage: z.string().optional(),
+    install: RegistryInstallSchema.optional(),
+    stars: z.number().int().nonnegative().optional(),
+    pushedAt: z.string().optional(),
+});
+export const resolveRegistry = (file, facts, registryUrl) => {
+    const byName = new Map(facts?.entries.map((entry) => [entry.name, entry]) ?? []);
+    return file.plugins.map((plugin) => {
+        const upstream = byName.get(plugin.name);
+        const install = resolveSource(plugin.source, registryUrl, file.metadata?.pluginRoot);
+        return {
+            name: plugin.name,
+            kind: plugin.kind ?? "plugin",
+            trust: plugin.trust ?? "listed",
+            ...(plugin.description !== undefined ? { description: plugin.description } : {}),
+            ...(plugin.version !== undefined ? { version: plugin.version } : {}),
+            ...(plugin.trustReason !== undefined ? { trustReason: plugin.trustReason } : {}),
+            ...(plugin.category !== undefined ? { category: plugin.category } : {}),
+            ...(plugin.logo !== undefined ? { logo: plugin.logo } : {}),
+            ...(plugin.icon !== undefined ? { icon: plugin.icon } : {}),
+            ...(plugin.homepage !== undefined ? { homepage: plugin.homepage } : {}),
+            ...(install !== undefined ? { install } : {}),
+            ...(upstream?.stars !== undefined ? { stars: upstream.stars } : {}),
+            ...(upstream?.pushedAt !== undefined ? { pushedAt: upstream.pushedAt } : {}),
+        };
+    });
+};
+export const compareEntries = (a, b) => {
+    if ((a.trust === "verified") !== (b.trust === "verified")) {
+        return a.trust === "verified" ? -1 : 1;
+    }
+    if ((a.stars ?? 0) !== (b.stars ?? 0)) {
+        return (b.stars ?? 0) - (a.stars ?? 0);
+    }
+    if ((a.pushedAt ?? "") !== (b.pushedAt ?? "")) {
+        return (b.pushedAt ?? "").localeCompare(a.pushedAt ?? "");
+    }
+    return a.name.localeCompare(b.name);
+};
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"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"}

package/dist/source.d.ts

@@ -0,0 +1,11 @@
+import { z } from "zod";
+export declare const RegistryInstallSchema: z.ZodObject<{
+    url: z.ZodString;
+    ref: z.ZodOptional<z.ZodString>;
+    path: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type RegistryInstall = z.infer<typeof RegistryInstallSchema>;
+export declare const resolveSource: (source: unknown, registryUrl: string, pluginRoot: string | undefined) => RegistryInstall | undefined;
+export declare const isShaPinned: (install: RegistryInstall | undefined) => boolean;
+export declare const githubRepoOf: (install: RegistryInstall | undefined) => string | undefined;
+//# sourceMappingURL=source.d.ts.map

package/dist/source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../src/source.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAWxB,eAAO,MAAM,qBAAqB;;;;iBAIhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAMpE,eAAO,MAAM,aAAa,WAAY,OAAO,eAAe,MAAM,cAAc,MAAM,GAAG,SAAS,KAAG,eAAe,GAAG,SAsBtH,CAAC;AASF,eAAO,MAAM,WAAW,YAAa,eAAe,GAAG,SAAS,KAAG,OAAmE,CAAC;AAIvI,eAAO,MAAM,YAAY,YAAa,eAAe,GAAG,SAAS,KAAG,MAAM,GAAG,SAM5E,CAAC"}

package/dist/source.js

@@ -0,0 +1,38 @@
+import { z } from "zod";
+export const RegistryInstallSchema = z.object({
+    url: z.string(),
+    ref: z.string().optional(),
+    path: z.string().optional(),
+});
+export const resolveSource = (source, registryUrl, pluginRoot) => {
+    if (typeof source === "string") {
+        const relative = source.replace(/^\.\//, "");
+        const root = pluginRoot?.replace(/^\.\//, "").replace(/\/$/, "");
+        return { url: registryUrl, path: root !== undefined && root !== "" ? `${root}/${relative}` : relative };
+    }
+    if (typeof source !== "object" || source === null) {
+        return undefined;
+    }
+    const s = source;
+    const ref = s.sha ?? s.ref;
+    if (s.source === "github" && typeof s.repo === "string") {
+        return { url: `https://github.com/${s.repo}.git`, ...(ref !== undefined ? { ref } : {}) };
+    }
+    if (s.source === "url" && typeof s.url === "string") {
+        return { url: s.url, ...(ref !== undefined ? { ref } : {}) };
+    }
+    if (s.source === "git-subdir" && typeof s.url === "string" && typeof s.path === "string") {
+        return { url: s.url, path: s.path, ...(ref !== undefined ? { ref } : {}) };
+    }
+    return undefined;
+};
+const FULL_SHA = /^[0-9a-f]{40}$/;
+export const isShaPinned = (install) => install?.ref !== undefined && FULL_SHA.test(install.ref);
+export const githubRepoOf = (install) => {
+    if (install === undefined) {
+        return undefined;
+    }
+    const match = /^https:\/\/github\.com\/([^/]+)\/(.+?)(?:\.git)?$/.exec(install.url);
+    return match === null ? undefined : `${match[1]}/${match[2]}`;
+};
+//# sourceMappingURL=source.js.map

package/dist/source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.js","sourceRoot":"","sources":["../src/source.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@intentic/registry",
+  "version": "1.176.3",
+  "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": {
+    "type": "git",
+    "url": "git+https://github.com/intentic/intentic.git",
+    "directory": "_sandbox/registry"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": {
+        "@intentic/src": "./src/index.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "@intentic/src": "./src/index.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "dependencies": {
+    "tslib": "2.8.1",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@typescript/native-preview": "7.0.0-dev.20260707.2",
+    "vitest": "4.1.10",
+    "@intentic/tsconfig": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsgo",
+    "typecheck": "tsgo --noEmit -p tsconfig.test.json",
+    "watch": "tsgo --build --watch",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./registry.js";
+export * from "./source.js";

package/src/registry.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from "vitest";
+import { compareEntries, type RegistryEntry, RegistryFactsSchema, RegistryFileSchema, resolveRegistry } from "./registry.js";
+
+const SHA = "9f2c1ab0d4e5f60718293a4b5c6d7e8f90a1b2c3";
+const REGISTRY = "https://github.com/intentic/registry";
+
+const file = RegistryFileSchema.parse({
+    name: `intentic`,
+    plugins: [
+        { name: `incidents`, kind: `extension`, trust: `verified`, source: { source: `github`, repo: `acme/incidents`, sha: SHA } },
+        { name: `linear`, kind: `extension`, source: { source: `github`, repo: `acme/linear`, sha: SHA } },
+        { name: `evil`, kind: `extension`, trust: `blocked`, trustReason: `exfiltrates workspace secrets`, source: { source: `github`, repo: `bad/evil` } },
+    ],
+});
+
+describe(`resolveRegistry`, () => {
+    it(`joins upstream facts onto the curated entries by name`, () => {
+        const facts = RegistryFactsSchema.parse({
+            scannedAt: `2026-08-01T00:00:00.000Z`,
+            entries: [{ name: `linear`, stars: 42, pushedAt: `2026-07-30T12:00:00Z` }],
+        });
+        const entries = resolveRegistry(file, facts, REGISTRY);
+        expect(entries.find((entry) => entry.name === `linear`)).toMatchObject({ stars: 42, pushedAt: `2026-07-30T12:00:00Z` });
+        // A curated entry the scanner has no facts for is still a complete row.
+        expect(entries.find((entry) => entry.name === `incidents`)?.stars).toBeUndefined();
+    });
+
+    // Most registries are six internal extensions in a private repo and run no scanner at all.
+    it(`resolves with no generated file at all`, () => {
+        expect(resolveRegistry(file, undefined, REGISTRY)).toHaveLength(3);
+    });
+
+    it(`defaults an unstated trust to listed and an unstated kind to plugin`, () => {
+        const entries = resolveRegistry(RegistryFileSchema.parse({ name: `x`, plugins: [{ name: `a`, source: `./a` }] }), undefined, REGISTRY);
+        expect(entries[0]).toMatchObject({ trust: `listed`, kind: `plugin` });
+    });
+
+    // Blocked rows must survive the resolve — deleting them is what hides a warning from the people who
+    // already installed the thing.
+    it(`keeps a blocked entry, with its reason`, () => {
+        const blocked = resolveRegistry(file, undefined, REGISTRY).find((entry) => entry.name === `evil`);
+        expect(blocked).toMatchObject({ trust: `blocked`, trustReason: `exfiltrates workspace secrets` });
+    });
+});
+
+describe(`compareEntries`, () => {
+    const entry = (over: Partial<RegistryEntry>): RegistryEntry => ({ name: `x`, kind: `extension`, trust: `listed`, ...over });
+
+    it(`puts verified first even when it has fewer stars`, () => {
+        const sorted = [entry({ name: `popular`, stars: 900 }), entry({ name: `checked`, trust: `verified`, stars: 1 })].toSorted(compareEntries);
+        expect(sorted.map((e) => e.name)).toEqual([`checked`, `popular`]);
+    });
+
+    it(`ranks by stars within a trust tier`, () => {
+        const sorted = [entry({ name: `few`, stars: 3 }), entry({ name: `many`, stars: 30 })].toSorted(compareEntries);
+        expect(sorted.map((e) => e.name)).toEqual([`many`, `few`]);
+    });
+
+    // The common case at launch: everything on zero stars, so recency is what actually orders the page.
+    it(`breaks star ties on recency, then on name`, () => {
+        const sorted = [
+            entry({ name: `stale`, pushedAt: `2026-01-01T00:00:00Z` }),
+            entry({ name: `fresh`, pushedAt: `2026-07-31T00:00:00Z` }),
+            entry({ name: `undated` }),
+        ].toSorted(compareEntries);
+        expect(sorted.map((e) => e.name)).toEqual([`fresh`, `stale`, `undated`]);
+    });
+});

package/src/registry.ts

@@ -0,0 +1,161 @@
+import { z } from "zod";
+import { type RegistryInstall, RegistryInstallSchema, resolveSource } from "./source.js";
+
+/* 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
+ * 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
+ * human decision is 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
+ * 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
+// site build (which fetches them raw).
+export const REGISTRY_FILE = ".claude-plugin/marketplace.json";
+export const REGISTRY_FACTS_FILE = ".claude-plugin/registry.generated.json";
+
+// The default the Extensions tab browses and the gallery is built from. A default, not a gate: the browse
+// 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
+// request against the registry, never a listing.
+export const REGISTRY_TOPIC = "intentic-extension";
+
+/* WHAT A LISTING CLAIMS, and precisely what it doesn't.
+ *
+ * - `listed`   the pointer resolves, the manifest parses, the publisher owns the source repo. NO claim about
+ *              the code. This is the honest default and what the scanner's pull requests propose.
+ * - `verified` a human read the source at that sha. Sorted first, badged in both surfaces.
+ * - `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.
+ *
+ * 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. */
+export const RegistryTrustSchema = z.enum(["verified", "listed", "blocked"]);
+export type RegistryTrust = z.infer<typeof RegistryTrustSchema>;
+
+const RegistryFileEntrySchema = z.object({
+    name: z.string(),
+    description: z.string().optional(),
+    version: z.string().optional(),
+    // "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
+    // trust state with no stated reason is an opinion the reader can't weigh.
+    trustReason: z.string().optional(),
+    category: z.string().optional(),
+    /* The mark the row is drawn with, copied off the extension's manifest by the scanner exactly like the
+     * description and the version — the same two tiers the manifest declares (a simple-icons slug, then a name
+     * from the app's icon set), and neither 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 —
+     * 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. */
+    logo: z.string().optional(),
+    icon: z.string().optional(),
+    homepage: z.url().optional(),
+    source: z.unknown(),
+});
+
+export const RegistryFileSchema = z.object({
+    name: z.string(),
+    metadata: z.object({ pluginRoot: z.string().optional() }).optional(),
+    plugins: z.array(RegistryFileEntrySchema),
+});
+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. */
+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
+    // every listing still has single-digit stars.
+    pushedAt: z.string().optional(),
+});
+
+export const RegistryFactsSchema = z.object({
+    scannedAt: z.string(),
+    entries: z.array(RegistryFactsEntrySchema),
+});
+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.
+export const RegistryEntrySchema = z.object({
+    name: z.string(),
+    description: z.string().optional(),
+    version: z.string().optional(),
+    kind: z.enum(["plugin", "extension"]),
+    trust: RegistryTrustSchema,
+    trustReason: z.string().optional(),
+    category: z.string().optional(),
+    // The mark, as the gallery and the app's browse list draw it — see the curated file's fields above.
+    logo: z.string().optional(),
+    icon: z.string().optional(),
+    homepage: z.string().optional(),
+    // Absent = a source the registry format can express but this daemon can't clone (npm, say). The row still
+    // renders; the install button doesn't.
+    install: RegistryInstallSchema.optional(),
+    stars: z.number().int().nonnegative().optional(),
+    pushedAt: z.string().optional(),
+});
+export type RegistryEntry = z.infer<typeof RegistryEntrySchema>;
+
+/* 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. */
+export const resolveRegistry = (file: RegistryFile, facts: RegistryFacts | undefined, registryUrl: string): RegistryEntry[] => {
+    const byName = new Map(facts?.entries.map((entry) => [entry.name, entry]) ?? []);
+    return file.plugins.map((plugin) => {
+        const upstream = byName.get(plugin.name);
+        const install: RegistryInstall | undefined = resolveSource(plugin.source, registryUrl, file.metadata?.pluginRoot);
+        return {
+            name: plugin.name,
+            kind: plugin.kind ?? "plugin",
+            trust: plugin.trust ?? "listed",
+            ...(plugin.description !== undefined ? { description: plugin.description } : {}),
+            ...(plugin.version !== undefined ? { version: plugin.version } : {}),
+            ...(plugin.trustReason !== undefined ? { trustReason: plugin.trustReason } : {}),
+            ...(plugin.category !== undefined ? { category: plugin.category } : {}),
+            ...(plugin.logo !== undefined ? { logo: plugin.logo } : {}),
+            ...(plugin.icon !== undefined ? { icon: plugin.icon } : {}),
+            ...(plugin.homepage !== undefined ? { homepage: plugin.homepage } : {}),
+            ...(install !== undefined ? { install } : {}),
+            ...(upstream?.stars !== undefined ? { stars: upstream.stars } : {}),
+            ...(upstream?.pushedAt !== undefined ? { pushedAt: upstream.pushedAt } : {}),
+        };
+    });
+};
+
+/* 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
+ * 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. */
+export const compareEntries = (a: RegistryEntry, b: RegistryEntry): number => {
+    if ((a.trust === "verified") !== (b.trust === "verified")) {
+        return a.trust === "verified" ? -1 : 1;
+    }
+    if ((a.stars ?? 0) !== (b.stars ?? 0)) {
+        return (b.stars ?? 0) - (a.stars ?? 0);
+    }
+    if ((a.pushedAt ?? "") !== (b.pushedAt ?? "")) {
+        return (b.pushedAt ?? "").localeCompare(a.pushedAt ?? "");
+    }
+    return a.name.localeCompare(b.name);
+};

package/src/source.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vitest";
+import { githubRepoOf, isShaPinned, resolveSource } from "./source.js";
+
+const SHA = "9f2c1ab0d4e5f60718293a4b5c6d7e8f90a1b2c3";
+const REGISTRY = "https://github.com/intentic/registry";
+
+describe(`resolveSource`, () => {
+    it(`reads a bare string as a path inside the registry repo, with pluginRoot prepended`, () => {
+        expect(resolveSource(`./incidents`, REGISTRY, undefined)).toEqual({ url: REGISTRY, path: `incidents` });
+        expect(resolveSource(`incidents`, REGISTRY, `./plugins/`)).toEqual({ url: REGISTRY, path: `plugins/incidents` });
+    });
+
+    it(`points a github source at the repo, preferring sha over ref`, () => {
+        expect(resolveSource({ source: `github`, repo: `acme/incidents`, sha: SHA, ref: `main` }, REGISTRY, undefined)).toEqual({
+            url: `https://github.com/acme/incidents.git`,
+            ref: SHA,
+        });
+    });
+
+    it(`carries url and git-subdir sources through`, () => {
+        expect(resolveSource({ source: `url`, url: `https://gitlab.com/acme/x.git`, ref: SHA }, REGISTRY, undefined)).toEqual({
+            url: `https://gitlab.com/acme/x.git`,
+            ref: SHA,
+        });
+        expect(resolveSource({ source: `git-subdir`, url: `https://github.com/acme/tools.git`, path: `ext/a`, sha: SHA }, REGISTRY, undefined)).toEqual({
+            url: `https://github.com/acme/tools.git`,
+            path: `ext/a`,
+            ref: SHA,
+        });
+    });
+
+    // 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();
+        expect(resolveSource(undefined, REGISTRY, undefined)).toBeUndefined();
+        expect(resolveSource(null, REGISTRY, undefined)).toBeUndefined();
+        expect(resolveSource(42, REGISTRY, undefined)).toBeUndefined();
+    });
+});
+
+describe(`isShaPinned`, () => {
+    it(`accepts only a full 40-character sha`, () => {
+        expect(isShaPinned({ url: `x`, ref: SHA })).toBe(true);
+        expect(isShaPinned({ url: `x`, ref: SHA.slice(0, 7) })).toBe(false);
+        expect(isShaPinned({ url: `x`, ref: `main` })).toBe(false);
+        expect(isShaPinned({ url: `x`, ref: SHA.toUpperCase() })).toBe(false);
+        expect(isShaPinned({ url: `x` })).toBe(false);
+        expect(isShaPinned(undefined)).toBe(false);
+    });
+});
+
+describe(`githubRepoOf`, () => {
+    it(`extracts owner/repo with or without the .git suffix, and only for github`, () => {
+        expect(githubRepoOf({ url: `https://github.com/acme/incidents.git` })).toBe(`acme/incidents`);
+        expect(githubRepoOf({ url: `https://github.com/acme/incidents` })).toBe(`acme/incidents`);
+        expect(githubRepoOf({ url: `https://gitlab.com/acme/incidents.git` })).toBeUndefined();
+        expect(githubRepoOf(undefined)).toBeUndefined();
+    });
+});

package/src/source.ts

@@ -0,0 +1,64 @@
+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
+ * 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 —
+ * 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.
+export const RegistryInstallSchema = z.object({
+    url: z.string(),
+    ref: z.string().optional(),
+    path: z.string().optional(),
+});
+export type RegistryInstall = z.infer<typeof RegistryInstallSchema>;
+
+/* A relative path means the code lives inside the registry repo itself, and metadata.pluginRoot prepends (the
+ * Claude Code spec). Every other shape points outward at a repo of its own. Kept as `unknown` on the way in:
+ * the format is somebody else's and gains shapes we don't know, and a source we can't read must degrade to
+ * "not installable from here" rather than failing the whole file to parse. */
+export const resolveSource = (source: unknown, registryUrl: string, pluginRoot: string | undefined): RegistryInstall | undefined => {
+    if (typeof source === "string") {
+        const relative = source.replace(/^\.\//, "");
+        const root = pluginRoot?.replace(/^\.\//, "").replace(/\/$/, "");
+        return { url: registryUrl, path: root !== undefined && root !== "" ? `${root}/${relative}` : relative };
+    }
+    if (typeof source !== "object" || source === null) {
+        return undefined;
+    }
+    const s = source as { source?: string; repo?: string; url?: string; path?: string; ref?: string; sha?: string };
+    // An exact sha pins harder than a ref when both are present.
+    const ref = s.sha ?? s.ref;
+    if (s.source === "github" && typeof s.repo === "string") {
+        return { url: `https://github.com/${s.repo}.git`, ...(ref !== undefined ? { ref } : {}) };
+    }
+    if (s.source === "url" && typeof s.url === "string") {
+        return { url: s.url, ...(ref !== undefined ? { ref } : {}) };
+    }
+    if (s.source === "git-subdir" && typeof s.url === "string" && typeof s.path === "string") {
+        return { url: s.url, path: s.path, ...(ref !== undefined ? { ref } : {}) };
+    }
+    return undefined;
+};
+
+const FULL_SHA = /^[0-9a-f]{40}$/;
+
+/* 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.
+// 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) {
+        return undefined;
+    }
+    const match = /^https:\/\/github\.com\/([^/]+)\/(.+?)(?:\.git)?$/.exec(install.url);
+    return match === null ? undefined : `${match[1]}/${match[2]}`;
+};