@intentic/registry-scan 1.310.0 → 1.311.0

package/README.md

@@ -1,85 +1,32 @@
-# @intentic/registry-scan
+# registry-scan
 
-The nightly job behind the [extension registry](seed/README.md). Published to npm because it runs from a
-GitHub Actions inside a public repository this monorepo does not contain. The workflows invoke an exact npm
-version from the `REGISTRY_SCAN_VERSION` repository variable; a moving package tag is not allowed inside the
-admission boundary.
+The CLI behind the extension registry: it finds topic-tagged extension repos, refreshes their facts, proposes listings, and prepares the security audit that admits new code.
 
-The file format it reads and writes lives in [`@intentic/registry`](../../_shared/registry), which the daemon
-and the site's gallery use too, so all three agree by construction rather than by three copies of a zod
-schema staying in step.
-
-## What it does, and what it refuses to do
-
-Scanning GitHub for a topic is **discovery**. Merging a pull request is the **decision**. Keeping those apart
-is the entire design: a topic is a public namespace anybody can join, so a job that listed what it found
-would publish the first malicious repository to tag itself: and the alternative, a submission form on the
-site, is a login, a spam queue and an admin panel standing in for a git commit.
-
-So each run:
-
-1. Searches `topic:intentic-extension`.
-2. Refreshes stars and last-push for **already-listed** entries into `registry.generated.json`, including the
-   listings the topic search never returned (a listing that arrived by pull request has no obligation to
-   carry the topic, and dropping its stars for that would rank it below newcomers for no reason).
-3. For each **unlisted** repo, resolves the default branch to a commit first, then reads the manifest and bundle
-   only at that sha. It proposes a complete candidate `marketplace.json` only when both parse/load there.
-4. Emits warnings for everything it skipped, into the job summary.
-
-It never lists, delists, or changes a trust level. A repository that went briefly private should come back to
-its listing, not to a deletion.
-
-Those are proposal checks, not admission. The protected `extension admission` workflow runs on each executable
-source/review change and accepts one executable subject per pull request. `audit` refuses unpinned, unsafe-host,
-or escaping-path targets. A disposable no-secrets job fetches the exact source and runs Trivy's
-dependency, secret, and misconfiguration scanners. Only then does the intentic agent gate receive an adversarial
-brief covering browser globals/egress, server/process credentials, agent hooks and MCP, bin shadowing,
-image/environment fragments, dependencies, binaries and source-versus-dist. It treats repository content as
-untrusted and forbids executing author code. Either automated check failing, blocking, or remaining unjudged
-fails admission.
-
-A pass runs `attest`, which records both run identities against the exact repository, sha and subdirectory. That
-push changes the PR head, so branch protection evaluates both checks again on the attested commit. Unchanged
-metadata may reuse evidence for the same immutable subject; a changed repository, sha or path, unblocking, or an
-edit to the record reruns admission. After a policy or scanner upgrade, untouched stale rows remain disabled by
-the official registry resolver; touching one schedules just that source, so the catalogue can be refreshed one
-pull request at a time. The privileged jobs fetch only the candidate marketplace JSON; exact source is checked
-out solely on the disposable deterministic runner and is never executed.
-
-Identity is also enforced mechanically. The listing key is `publisher.name` read from the manifest:
-[`extensionIdOf`](../../_shared/extension-manifest/src/manifest.ts): so a repository that copies somebody else's
-manifest collides with their existing listing and is refused here rather than arriving as a pull request that
-looks legitimate.
+```mermaid
+flowchart LR
+    wf["intentic/registry<br/>GitHub Actions"] -->|"npm exec"| cli(["registry-scan"])
+    cli -->|"scan"| gh["GitHub API<br/>topic intentic-extension"]
+    cli -->|"scan"| out["registry.generated.json<br/>.scan/proposals/"]
+    cli -->|"audit"| req["security request<br/>for the intentic gate"]
+    cli -->|"attest"| stamp["review bound to<br/>the candidate sha"]
+```
 
-## Layout
+- Runs in the registry repository's workflows, which [seed/](seed) holds, pinned to one exact published version. Nothing in this repo runs it.
+- `scan` reads `.claude-plugin/marketplace.json`, searches GitHub for the `intentic-extension` topic and reads each repo's root `intentic-extension.json` at an exact commit. It rewrites the facts file in place and leaves one directory per new extension under `.scan/proposals/`, holding a candidate `marketplace.json` and the pull request's text, so the workflow only moves whole files.
+- Nothing merges automatically. A proposal enters as `trust: "listed"`, `verified` is a separate human edit, and delisting stays manual. Gone, archived or broken listings become warnings for a maintainer.
+- `audit` validates a registry diff and lists every changed executable source; `attest` records a passing gate run against those exact shas. Registry content is untrusted data, and no author code runs anywhere in the chain.
+- `github.ts` sits behind an interface, so the decision logic in `scan.ts` is tested with no network or token.
 
-| Path | What it is |
-| --- | --- |
-| [src/scan.ts](src/scan.ts) | The decision logic, pure and fully unit-tested against a fake reader. |
-| [src/audit.ts](src/audit.ts) | Diff-to-check policy and source-bound attestation. |
-| [src/github.ts](src/github.ts) | The four REST reads, behind an interface so the above needs no network. |
-| [src/cli.ts](src/cli.ts) | The IO: read the checkout, write the facts file and the proposal directories. |
-| [seed/](seed) | What the registry repository itself contains: the curated file, the author-facing README, and the workflow that calls this. |
+## Key files
 
-`seed/` is a starting point, not a synced copy: push it once to create the registry repository, then it lives
-its own life over there. The one coupling that matters is the workflow's `npx` line, which is why this
-package is published.
+- [src/cli.ts](src/cli.ts) — the `scan`, `audit` and `attest` commands and their inputs.
+- [src/scan.ts](src/scan.ts) — discovery, fact refresh and listing proposals.
+- [src/audit.ts](src/audit.ts) — admission problems, audit targets and the attestation.
+- [src/outputs.ts](src/outputs.ts) — everything the scan writes for the workflow to pick up.
 
-## Running it against a checkout
+## Commands
 
 ```sh
-GITHUB_TOKEN=… REGISTRY_DIR=/path/to/registry-checkout node dist/cli.js
-node dist/cli.js audit --base /path/to/base.json --candidate /path/to/candidate.json
-node dist/cli.js attest --base /path/to/base.json --candidate /path/to/candidate.json --run-id GATE_RUN --scan-run-id WORKFLOW_RUN
+pnpm --filter @intentic/registry-scan test
+GITHUB_TOKEN=… REGISTRY_DIR=<registry checkout> pnpm --filter @intentic/registry-scan scan   # after build
 ```
-
-`SCANNED_AT` overrides the timestamp so a re-run against a fixed input produces a fixed output. A token is
-required: the search and contents endpoints are rate-limited to approximately nothing without one.
-
-## Key files
-
-- [src/scan.ts](src/scan.ts): finding extensions and resolving each to a sha.
-- [src/audit.ts](src/audit.ts): identifying executable changes and preparing the intentic gate.
-- [src/github.ts](src/github.ts): the API half.
-- [src/outputs.ts](src/outputs.ts): what the job writes.
-- [src/cli.ts](src/cli.ts): the entry point the nightly job runs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentic/registry-scan",
-  "version": "1.310.0",
+  "version": "1.311.0",
   "description": "The nightly scan behind the extension registry, finds topic-tagged repos, refreshes upstream facts, and proposes listings as pull requests",
   "license": "MIT",
   "type": "module",
@@ -20,8 +20,8 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@intentic/extension-manifest": "1.310.0",
-    "@intentic/registry": "1.310.0",
+    "@intentic/extension-manifest": "1.311.0",
+    "@intentic/registry": "1.311.0",
     "zod": "4.5.4"
   },
   "devDependencies": {