Skip to Content
DevelopmentMonorepo

Developing pf

pf is a pnpm workspace. The shipped packages are versioned together by versions.json and published to the cellars registry (https://cellars.staging.pangenea.com/).

PackageNameWhat
packages/kit@pulpfixer/kitShared foundation: detect, exec, ui, config, util, context and the Command / Plugin types. Depends on nothing
packages/plugin-aws@pulpfixer/plugin-awsThe AWS plugin. Depends only on kit
packages/plugin-system@pulpfixer/plugin-systemThe system plugin (pf sys). Depends only on kit
packages/plugin-yubikey@pulpfixer/plugin-yubikeyThe YubiKey plugin. Depends only on kit
packages/preset-cursor@pulpfixer/preset-cursorData only: the standard Cursor extensions and settings. Published alone, not a dependency of core: pf sys apply cursor fetches its latest version
packages/preset-suite@pulpfixer/preset-suiteData only: the pulpfixer suite, a list of extension packages. Published alone: pf sys apply suite fetches its latest version
packages/ext-bg-tone@pulpfixer/ext-bg-toneThe Background Tone extension for Cursor, shipped as a .vsix. Published alone, never a dependency of core: pf sys apply suite and pf update fetch its latest version. Type-checked on its own (it targets the VS Code API)
packages/pulpfixerpulpfixerThe pf binary: built-in commands, agent, host mode, skills, install and update. Depends on kit and every plugin
packages/docs@pulpfixer/docsThis documentation site (Nextra). Private, never published

Dependencies point one way: core to plugins to kit. A plugin never imports core. Anything a plugin needs from core moves into kit.

Each package exports source, types and default conditions. Dev, tests and typecheck run with --conditions=source (straight from src/), while builds and installs use dist/.

Commands

pnpm ask lists every script.

pnpm install pnpm dev -- list # run from source pnpm typecheck && pnpm test && pnpm build pnpm install:local # build and link this checkout as the global pf pnpm docs:dev # this site, on http://localhost:4400 (same as pf docs) pnpm docs:build # build the site and its search index

./pf in the checkout root runs the local source with no build, while the global pf stays as installed. It keeps your current directory, so you can point it at another repo:

./pf dev --dry-run cd ~/some/repo && ~/dev/agents/pulpfixer/pf dev --dry-run

Layout

PathWhat
packages/pulpfixer/src/bin/pf.ts, cli.tsEntry point, banner, dispatch
packages/pulpfixer/src/menu.tsRepo menu, fallback menu, static list
packages/pulpfixer/src/commands/Built-in commands
packages/pulpfixer/src/agent/Coding agent: persona, tool registry, MCP server, launchers
packages/pulpfixer/src/host/Host mode
packages/pulpfixer/src/skills/Skill discovery and runner
packages/pulpfixer/src/plugins/Plugin registry, loader and management
packages/pulpfixer/src/install/, update/Machine setup and update check
packages/kit/src/detect/Repo, stack, docs and staging detection, command resolution
packages/kit/src/ui/Palette, picker, prompts, text helpers
packages/plugin-aws/src/, plugin-system/src/, plugin-yubikey/src/The built-in plugins
packages/preset-cursor/preset.jsonThe Cursor standard that pf sys apply cursor applies
packages/preset-suite/preset.json, packages/ext-bg-tone/The suite (pf sys apply suite) and the Background Tone extension it installs
packages/docs/content/This site’s pages
scripts/Cross-package commands: build, test, release, ver, logo, ask

Adding things

A command. Add packages/pulpfixer/src/commands/<name>.ts, register it in packages/pulpfixer/src/commands/index.ts, show it in packages/pulpfixer/src/menu.ts if it belongs in the menu, and add a test. A shortcut is one entry in SHORTCUTS (Shortcuts).

A stack. Add it to packages/kit/src/detect/stacks.ts with a test in packages/kit/tests/.

A built-in plugin. Create packages/plugin-<name> (copy plugin-aws’s package.json and tsconfig), add it to scripts/build.mjs, to ORDER in scripts/release.mjs, to the core dependencies and to packages/pulpfixer/src/plugins/index.ts, then run pnpm ver init.

A registry plugin. See Writing a plugin. Registry plugins live in the npm prefix ~/.pf/plugins, and core imports them at startup in main(). Failures never stop pf.

Docs

Pages live in packages/docs/content/ as MDX, with a _meta.ts per folder that sets the sidebar order and titles. When you change a command, plugin or the agent, update the matching page. The agent guide also exists in packages/pulpfixer/docs/agent.md, so keep the two in step.

Hosting on AWS Amplify

The site is hosted as a static export. amplify.yml at the repo root builds it with pnpm run build:static (DOCS_EXPORT=1 next build, then the Pagefind index into out/_pagefind) and serves packages/docs/out. In the Amplify console, connect the repo, tick “My app is a monorepo” and set the app root to packages/docs. Without DOCS_EXPORT, pf docs and pnpm docs:build behave as before (a Next server).

Last updated on