Create a connector

puppi connector new writes a connector package for a type this repository does not ship. You replace the placeholder OpenAPI document, generate the client, and register the module in defineConfig.

The type is a connection name: lowercase letters, digits, and dashes, starting with a letter. postgres, filesystem, s3, and http are reserved and refused.

Create the package

From the repository root, after the CLI is built (pnpm -r build, or pnpm --filter @puppi/cli... build):

node cli/bin/puppi.js connector new acme connectors/acme

The second argument is the directory. The default is a directory named after the type. Existing files are left in place unless you pass --force.

File	Role
package.json	@puppi/adapter-<type>. Runtime dependency is @puppi/adapter-http.
src/define.ts	defineConnector: type, docs URL, auth, versions, config, secrets.
src/index.ts	Default-exports that definition and exports Client.
openapi.json	A placeholder GET /ping. Replace it with the vendor’s document.
src/openapi.ts, src/operations.ts	Generated from openapi.json.
test/client.test.ts	Conformance test against the placeholder spec.
README.md, tsconfig.json, test/tsconfig.json, .gitignore	Package scaffolding.

Inside this repository the scaffold’s version ranges do not install. In the new package.json, set @puppi/adapter-http and @puppi/adapter-conformance to workspace:*, then run pnpm install from the repository root.

Point it at the vendor

Replace openapi.json with the vendor’s document, trimmed to the operations this package calls. Then, from the package directory:

pnpm generate

That rewrites src/openapi.ts and src/operations.ts. Leave those two files generated. Edit src/define.ts for the identity (docs URL, auth scheme, API versions, config, secrets) and src/index.ts for check() and the list methods.

define.ts imports nothing generated. Client extends the HTTP client’s OpenApiClient and implements check(). A list method yields pages. An asset calls that method.

Register it

Register the module in defineConfig the same way as a catalog connector. Add the directory name to the connectors list in the repository README. A test in this repository checks that list against the directories on disk.

The catalog is regenerated from define.ts when the docs site builds.