pacwichpacwich
v0.1.0-test.2

    Migrating from bun-workspaces

    Pacwich is essentially the direct continuation of the package bun-workspaces, a very similar package that was built only to work on top of Bun as a package manager.

    If you are a bun-workspaces user, you can expect minimal to no changes on average beyond the name change, thanks to the fact that Pacwich auto-detects Bun as your package manager from bun.lock and has almost the same CLI and API as bun-workspaces.

    There's a high chance you can simply treat this as a name swap only without issue.

    However, a few small breakages/removals have occurred, highlighted below, and config files have naming changes, including that "root config" will now be generally referred to as "project config". Jump to config changes

    You can also browse some of the feature additions below.

    General Changes

    • Potentially breaking change: The shell option for inline scripts now defaults to "system" instead of "bun", due to this no longer being a Bun-specific package. You can still use "bun" as your shell with any package manager, though it will fail if the bun command is not available.
    • Breaking change: All environment variables used for settings which started with BW_ now start with PACWICH_.
    • Addition: Along with node_modules/pacwich/AGENTS.md, you can access smaller agent files for more specific usage docs under node_modules/pacwich/agents/. Read more
    • Install change: The CLI runs via either npx pacwich or bunx pacwich, but using a global install for a convenient pacwich binary is now more ideal, thanks to the fact that it will delegate running the CLI from a local install if present. bun-workspaces only was encouraged to run via bunx bun-workspaces.

    CLI Changes

    • Removal (warning message temporarily logged): The global option -w|--workspace-root has been removed. This was a pnpm-inspired feature, but this is now Pacwich's default behavior, so the flag is not needed. Pacwich always walks up your directory tree to find a project root.
    • Addition: A new global option --pm to explicitly set a package manager, though default auto-detection or using project config is generally preferred.
    • Addition: Project config can now set defaults.cliScriptOutputStyle to set the default --output-style of the run command, "grouped" only available on a TTY, which falls back to "prefixed".
    • Addition: A CLI command add-skills to add agent skill files to your project
    • Addition: A verify command for the new verify feature described above.

    API Changes

    • Removal (breaking): Project.createScriptCommand() was removed. This was a lower level utility never alluded to in examples and was dependent on Bun-specific details.
    • Deprecation: Project.config.root is renamed to Project.config.project (reference to config such as defined in pacwich.project.ts).
    • Deprecation: Project.mapScriptsToWorkspaces() is deprecated in favor of the new Project.scriptMap property of the same type as the method's return value.
    • Deprecation: Project.mapTagsToWorkspaces() is deprecated in favor of the new Project.tagMap property of the same type as the method's return value.
    • Addition: createFileSystemProject() accepts a packageManager option, similar to the new --pm CLI option, though default auto-detection or using project config is generally preferred.
    • Addition: Project.verify() is the API equivalent of the new CLI verify command.

    MCP Changes

    • Removal (breaking). Project tools have been removed due to being redundant with the CLI. Agents should instead simply read the documentation resources provided and use the CLI for Pacwich operations.

    Config Changes

    The names of your config files have changed, but the new config files are currently backwards compatible with bun-workspaces config files, though some utility names have been deprecated for the root config (see below).

    Of course, for TS/JS files, you'll import utils from "pacwich/config" instead of "bun-workspaces/config".

    Workspace Config

    Workspace config is fully backwards compatible.

    • Rename: bw.workspace.{ts,js,json,jsonc} → pacwich.workspace.{ts,js,json,jsonc}

    Root Config, now "Project Config"

    What was called "root config" in bun-workspaces is now called "project config" in pacwich, to keep the naming simple and consistent with the package's primitives.

    The actual config object value is backwards compatible, with only optional properties added.

    • Rename: bw.root.{ts,js,json,jsonc} → pacwich.project.{ts,js,json,jsonc}
    • Deprecation (imported util): defineRootConfig is deprecated in favor of defineProjectConfig.
    • Deprecation (imported util): mergeRootConfig is deprecated in favor of mergeProjectConfig.
    • Deprecation (imported type): The RootConfig type is deprecated in favor of ProjectConfig. Similar types using "Root" have the same name change to use "Project".
    • Addition (config value): The packageManager value sets the expected package manager, mainly for when multiple lockfiles are present
    • Addition (config value): defaults.cliScriptOutputStyle sets the default --output-style argument for running scripts
    • Addition (config value):: New verify property sets options for the verify feature
    Notes on Deprecated Utilities

    When using a TS/JS file, utility and type names are temporarily backwards compatible, but you're encouraged to move to the new "project" names over the deprecated "root" names:

    // Old: bw.root.ts
import { defineRootConfig, type RootConfig } from 'bun-workspaces/config';

export default defineRootConfig({
  // ... your config
})
    // New: pacwich.project.ts
import { defineProjectConfig, type ProjectConfig } from 'pacwich/config';

export default defineProjectConfig({
  // ... your config
})