Skip to content

chore: fix package.json conventions and overhaul all READMEs for pgpm#7

Merged
pyramation merged 4 commits intomainfrom
chore/fix-package-json-conventions
Apr 16, 2026
Merged

chore: fix package.json conventions and overhaul all READMEs for pgpm#7
pyramation merged 4 commits intomainfrom
chore/fix-package-json-conventions

Conversation

@pyramation
Copy link
Copy Markdown
Contributor

@pyramation pyramation commented Apr 16, 2026

Summary

Two sets of changes:

1. Package.json convention fixes

Aligns all package.json files with the Constructive publishing standards — removing anti-patterns, scoping npm names under @agentic-db/, and clarifying which packages are publishable vs private.

Anti-pattern fixes:

  • packages/rag — removed dist/ prefix from main/module/types (contradicted its own publishConfig.directory: "dist")
  • packages/worker — removed dist/ prefix, removed exports map, added publishConfig.directory: "dist"

Privacy & publishability:

  • Marked provision and worker as private: true
  • Made @agentic-db/cli publishable with standard main/module/types + publishConfig
  • Changed access from "restricted" to "public" for agentic-db and @agentic-db/services

npm name renames (pgpm control files unchanged):

  • agentic-db-services@agentic-db/services
  • agentic-db stays as agentic-db (naked name, no scope — this is the flagship entry point for pgpm)

Housekeeping:

  • Updated stale repo URLs from pyramation-studio/agent-osconstructive-io/agentic-db
  • Lockfile cleaned up (removed stale entries for previously deleted packages)

2. README overhaul — pgpm deployment showcase

Rewrote all README files to showcase pgpm deployment and introduce users to the Constructive platform. All READMEs use pgpm docker start as the primary PostgreSQL setup path, with pgpm docker start --ollama for embedding generation and Docker Compose as a secondary alternative.

Flagship: packages/agentic-db/README.md — comprehensive intro to pgpm + Constructive with quick start, module dependency tree, search capabilities table, and SDK code examples. Ollama section shows pgpm docker start --ollama (CPU) and --ollama --gpu (NVIDIA), with Docker Compose as fallback for users who already have their own LLM running.

Published packages:

  • packages/agentic-db-services/README.md — services module purpose, pgpm deploy instructions
  • sdk/sdk/README.md — install, CRUD, vector/unified/chunk search, relations examples
  • sdk/cli/README.md (new) — install, setup, usage examples with all search types

Private packages:

  • packages/provision/README.md — blueprint schema definitions, provision→export→deploy workflow
  • packages/rag/README.md — RAG CLI tools (search, embed, ask)
  • packages/worker/README.md — auto-embedding worker architecture, references pgpm docker start --ollama
  • packages/integration-tests/README.md (new) — test suite overview
  • packages/cli-e2e-tests/README.md (new) — e2e test suite overview

Root README.md — pgpm quick start, published/private package table, Docker setup section showing pgpm docker commands (including --ollama and --gpu), Docker Compose as alternative, schema development workflow, testing instructions.

Review & Testing Checklist for Human

  • --ollama / --gpu flags depend on constructive-io/constructive#981 — READMEs reference pgpm docker start --ollama and --ollama --gpu, which require the Constructive PR to be merged and pgpm to be republished. Until then, users following these instructions will get an unknown flag error. Merge the Constructive PR first, or adjust the README wording to note these flags are upcoming.
  • CLI bin + publishConfig.directory interactionbin points to ./generated/cli/index.js but publishConfig.directory is dist. When published, npm will resolve bin relative to dist/ — confirm dist/generated/cli/index.js will exist after makage build
  • README code examples are accurate — the SDK/CLI examples in the new READMEs were written based on the generated code but not tested end-to-end. Spot-check that createClient, findMany, vectorEmbedding, searchScore API shapes match the actual generated SDK
  • Relative links between READMEs — the flagship README links to ../../sdk/sdk and ../../sdk/cli; root README links to packages/agentic-db etc. Verify these resolve correctly on GitHub

Notes

  • pgpm .control files are intentionally left unchanged — pgpm deploy uses control file names, not npm package names
  • The libc field removals in the lockfile are pnpm normalization noise, not functional changes
  • @agentic-db/rag keeps publishConfig.access: "public" despite being private: true — harmless but inconsistent; consider removing publishConfig entirely from private packages
  • Docker Compose is intentionally kept as a secondary option: it adds tuned Postgres settings and Ollama for users who already have their own LLM or prefer Compose workflows

Link to Devin session: https://app.devin.ai/sessions/f70461c2d0a74993a271488c3aa077b1
Requested by: @pyramation

- Remove dist/ prefix anti-pattern from rag and worker packages
- Remove exports map anti-pattern from worker package
- Mark provision, worker as private
- Rename agentic-db -> @agentic-db/db (npm name only, pgpm control file unchanged)
- Rename agentic-db-services -> @agentic-db/services (npm name only)
- Make @agentic-db/db, @agentic-db/services, @agentic-db/cli publishable (public)
- Add main/module/types + publishConfig to @agentic-db/cli
- Update repo URLs from pyramation-studio/agent-os to constructive-io/agentic-db
@devin-ai-integration
Copy link
Copy Markdown

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

  • Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
  • Look at CI failures and help fix them

⚙️ Control Options:

  • Disable automatic comment and CI monitoring

- Flagship packages/agentic-db/README.md: comprehensive pgpm + Constructive intro
  with quick start, Docker Compose setup, search capabilities, SDK examples
- Root README.md: updated package table, pgpm quick start, schema dev workflow
- @agentic-db/services: pgpm deployment instructions and module dependencies
- @agentic-db/sdk: install, CRUD, vector/unified/chunk search examples
- @agentic-db/cli: install, setup, usage examples, command reference
- Private packages: provision, export, rag, worker, integration-tests, cli-e2e-tests
- Revert package name from @agentic-db/db back to plain agentic-db (naked name)
- Fix stale badge URLs (pyramation-studio/agent-os -> constructive-io/agentic-db)
@devin-ai-integration devin-ai-integration Bot changed the title chore: fix package.json conventions to follow Constructive standards chore: fix package.json conventions and overhaul all READMEs for pgpm Apr 16, 2026
pgpm docker start already defaults to constructiveio/postgres-plus:18 with
2GB shared memory. Docker Compose is now documented as an optional extra
for Ollama embedding generation only.
Now that pgpm supports --ollama and --gpu flags, update READMEs to
show the pgpm-native way to start Ollama. Docker Compose is kept as
a secondary option for users who already have their own LLM running
or want tuned Postgres settings.
@pyramation pyramation merged commit d5d99d7 into main Apr 16, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant