pm-ts-starter

TypeScript reference extension for pm-cli covering all 9 SDK capability types in one fully-typed index.ts.

Each capability is a small, SAFE, inert demo with teaching comments. Copy the ones you need into your own extension and delete the rest.

Installation

pm install github.com/unbraind/pm-ts-starter --global

Capabilities Demonstrated

Every capability declared in manifest.json is demonstrated in index.ts. Each maps to one or more register*/hooks.* calls on the typed ExtensionApi.

| # | Capability | ExtensionApi call(s) | What the demo registers | |---|---|---|---| | 1 | commands | registerCommand, registerFlags | pm hello, pm ts-starter info; plus an inert --ts-starter-tag flag added to native list | | 2 | renderers | registerRenderer | json renderer override that reshapes only the ts_starter-tagged payload, passing everything else through | | 3 | hooks | hooks.beforeCommand, hooks.afterCommand, hooks.onWrite, hooks.onRead, hooks.onIndex | All five lifecycle hooks (observe-only; opt-in logging via PM_TS_STARTER_VERBOSE) | | 4 | schema | registerItemFields, registerItemTypes, registerMigration | Optional field ts_starter_ref, a Spike item type, and a no-op migration ts-starter-noop | | 5 | importers | registerImporter, registerExporter | pm ts-starter-demo import / pm ts-starter-demo export (both inert) | | 6 | search | registerSearchProvider, registerVectorStoreAdapter | Search provider ts-starter-prefix (ID-prefix match) and in-memory vector store adapter ts-starter-memory | | 7 | parser | registerParser | Pass-through parser override for the native list command | | 8 | preflight | registerPreflight | Pass-through preflight decision override (no behavior change) | | 9 | services | registerService | Pass-through override of the output_format core service |

Commands

pm hello

pm hello
pm hello --name World --loud

pm ts-starter info

pm ts-starter info

Importer / exporter command paths

registerImporter("ts-starter-demo") and registerExporter("ts-starter-demo") auto-create:

pm ts-starter-demo import
pm ts-starter-demo export

The defineExtension helper + zero-runtime-coupling pattern

defineExtension is the SDK's typed identity helper — it returns its argument unchanged but constrains it to the ExtensionModule shape so TypeScript can type-check activate(api) and the metadata fields against the real SDK.

It is imported as a type only (import type). A standalone-installed extension loads only its own dist/ at runtime, so @unbrained/pm-cli is not resolvable as a runtime value; importing the real function would crash at activation. We provide a trivial identity implementation and rely on the type import for full compile-time checking with zero runtime coupling to the CLI package. The real CLI supplies the live api object when it calls activate.

Using as a Template

1. Clone this repo
2. Edit index.ts — remove capabilities you don't need
3. Update manifest.json name and capabilities
4. npm install && npm run build
5. pm install ./path/to/dir --project

License

MIT

Release Automation

This package is release-ready for GitHub, npm, and Bun-compatible installs. CI runs type checking, build, production dependency audit, package packing, Bun install verification, and pm-changelog validation. The daily release workflow publishes only when commits exist after the latest release tag and uses pm-changelog to generate CHANGELOG.md and GitHub release notes.