Skip to content

CONNECTORS.md quickstart still points at .js files after the TypeScript move #67

Description

@tnunamak

packages/polyfill-connectors/CONNECTORS.md is the runnable quickstart for connector contributors, and it still describes the codebase from before the TypeScript migration. Someone following it today copies filenames that do not exist.

The most confusing one is browser-scraper-runtime.js. It appears 10 times across the scaffolded-connector table (lines 52-62) and there is no such file on main under any extension. The rest are real files that changed extension:

CONNECTORS.md says line actual file
connectors/github/index.js 107 connectors/github/index.ts
src/orchestrator.js 108 src/orchestrator.ts
bin/register-all.js 97, 109 bin/register-all.ts
bin/orchestrate.js 94, 110 bin/orchestrate.ts
src/auto-login/<platform>.js 40, 49 .ts

Line 8 also says "31 connectors" and there are 33 manifests.

Renaming the extensions is not enough to make the commands work, which is the part worth getting right. There is no package script for orchestrate or register-all, and while the repo's .nvmrc is Node 25 (which strips types natively), CI pins Node 22 in .github/workflows/polyfill-connectors.yml:47. So node bin/orchestrate.ts runs on your machine and fails on CI. The convention elsewhere in the repo is node --import tsx <file>.ts. Please run each command you document and confirm it works, rather than pattern-matching the rename.

The second half is routing. README.md:94-107 has a "Participate" section linking CONTRIBUTING, MAINTAINERS, openspec, CoC, and SECURITY, with nothing about building a connector. CONTRIBUTING.md:5 invites connector contributions but sends people to reference-implementation/README.md instead. Adding a "Build a connector" link to the README list and a short pointer in CONTRIBUTING would close the loop, since CONNECTORS.md:3-6 already links onward to docs/reference/connector-authoring-guide.md.

Keep runnable mechanics in CONNECTORS.md and semantic rules in the authoring guide. We do not need a third document. If you find yourself wanting to change what a manifest field means, that is an OpenSpec change and not this issue. CONTRIBUTING.md:18-27 describes that path.

Same stale reference shows up in bin/register-all.ts:11,13, docs/reference/local-testing-e2e.md:63, and connectors/slack/README.md:29 if you want to sweep them while you are in there.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions