Proposal: Publish Deft as an NPM + PIP CLI (agent-first distribution)

[orlandobrent]

Motivation

Today Deft is typically consumed via git clone, which makes installation and updates heavier than they need to be (especially across many repos/machines). Publishing Deft as package-manager CLIs provides:

• Easy install (npm i -g ..., npx ..., pipx install ..., uv tool install ...)
• Version pinning (package version == Deft version)
• Consistent entrypoint (deft ...) regardless of environment
• No git workflow friction (no submodules, no clone required)

Desired user experience

Users should be able to install Deft with either ecosystem:

NPM (global / one-off / pinned via Volta)

Global install

• npm i -g <pkg>
• deft --version

One-off execution

• npx <pkg> <command>

Project dev dependency

• npm i -D <pkg>
• npx deft <command>

Volta (pinned, per-user)

• volta install <pkg>
• deft --version

Volta (pinned, per-project)

• Add to package.json:
  • "volta": { "node": "x.y.z", "npm": "a.b.c" }
• npm i -D <pkg>
• npx deft <command>

Note: If we want “pin Deft CLI version” via Volta specifically, we can recommend volta install <pkg>@<version>.

PIP (recommended via uv tool / pipx)

uv tool install (pinned, per-user)

• uv tool install <pkg>
• deft --version

pipx install (pinned, per-user)

• pipx install <pkg>
• deft --version

pip install (fallback)

• pip install <pkg>
• deft --version

In all cases, users get a deft command with the same behavior.

Example CLI usage (what users would actually run)

Assuming the project-local layout and behavior is already solved (see #4), the CLI should support workflows like:

Install / initialize in a repo

• deft install
  • Copies the Deft core assets into ./.deft/core at the pinned version (or latest if unpinned)
  • Ensures ./.deft/cache exists (gitignored)
  • Ensures ./deft/ exists for project overrides

Bootstrap first-time files

• deft bootstrap
  • Creates ./deft/project.md if missing
  • Creates ~/.deft/user.md if missing
  • Does not modify anything inside the packaged assets

Update Deft core version

• deft update
  • Updates ./.deft/core to a newer pinned version (or latest, depending on the repo’s pinning strategy)

Inspect / verify what’s in use

• deft doctor
  • Prints the CLI version (and optionally the core assets version installed in ./.deft/core)
  • Prints which override files were discovered (project + user)
  • Validates expected directories exist and that .deft/cache is ignored

Optional additional “quality of life” examples (if we want them):

• deft resolve
  • Writes a merged bundle to ./.deft/cache/deft.context.md for tools that prefer a single file
• deft --help
  • Lists commands and describes where files are written

Requirements

1. Ship a deft CLI in both NPM and PIP distributions.
2. Include Deft core assets in both package artifacts (markdown directories, templates, etc.).
3. No writes to packaged assets (packages are read-only by design). All output is written to project/user locations as defined in make /deft read-only #4
4. Versioning
   • Package versions should track Deft releases (e.g. deft-cli@0.4.2 corresponds to Deft core 0.4.2).
   • The CLI should be able to report its version (deft --version) and optionally “core asset version” (deft doctor or similar).
5. Parity
   • The NPM and PIP CLIs should expose the same command surface area and flags (as much as practical).

Packaging approach

Maintain two small CLIs (Node + Python) that follow the same behavior spec and test fixtures.

• Pros: best native experience in each ecosystem
• Cons: two implementations to maintain

Implementation notes

NPM packaging

• Ensure markdown assets are published (use files in package.json).
• Provide bin entry so deft is available on PATH.
• Support npx usage cleanly.
• Consider scoped package naming (e.g. @visionik/deft or @visionik/deft-cli).
• Document Volta install/pinning workflows (examples above).

PIP packaging

• Include markdown assets as package data (pyproject config).
• Provide a console script entrypoint (deft).
• Confirm install flows for uv tool install and pipx install.
• Consider naming conflicts on PyPI (deft, deft-cli, etc.).

Acceptance criteria

• deft can be installed via NPM and PIP using common workflows (global + one-off + tool install + Volta).
• Packaged artifacts include the required Deft asset directories.
• deft --version works and matches the package version.
• Running the CLI does not require a git clone of the Deft repo.
• Docs updated to recommend package-based install paths and show both NPM + PIP commands (including Volta + uv).

Deliverables / tasks

• Decide naming for NPM + PyPI packages
• Create NPM package + publish workflow
• Create PIP package + publish workflow
• Ensure assets are included in both distributions
• Provide release process (tag -> publish NPM/PIP)
• Update README with NPM + PIP install instructions (include Volta + uv examples)