Define the canonical npm package identity and align metadata #3

Activity

1. adrianbrowning

   marked this as blocking 2 issues on Aug 8, 2026

   • Improve GitHub and npm discoverability documentation #4
   • Publish an agent integration guide and workflow examples #8
2. adrianbrowning commented on Aug 8, 2026

   

   adrianbrowning

   on Aug 8, 2026

   Last edited by adrianbrowning

   OwnerAuthor

   More actions

   This was generated by AI during triage.

   Agent Brief

   Category: enhancement
   Summary: Move mdcode's canonical public npm identity to @gcmdev/mdcode and align all package metadata and public documentation.

   Current behavior:
   The published package is mdcode-ts at version 0.0.4. Package metadata and public examples use inconsistent identities, including mdcode-ts, mdcode, and @gcm/mdcode. The intended @gcmdev/mdcode package does not yet exist on npm, though the maintainer controls that scope.

   Desired behavior:
   @gcmdev/mdcode becomes the single canonical public package identity. All public install instructions, package metadata, repository references, badges, and import examples consistently use it. Existing mdcode-ts consumers receive a documented migration path.

   Key interfaces:

   • Published package manifest — package name, repository, homepage, exports, CLI binary, package files, and discoverability metadata must describe the canonical package.
   • Public installation and import examples — use @gcmdev/mdcode and the documented mdcode CLI consistently.
   • Existing mdcode-ts publication — determine and carry out the maintainer-approved deprecation/redirect strategy.

   Acceptance criteria:

   • @gcmdev/mdcode is reserved/published by the maintainer and exposes the documented CLI and library entry points.
   • Public metadata, README instructions, badges/links, keywords, and imports consistently name @gcmdev/mdcode.
   • A clean install using the documented command provides the mdcode CLI.
   • The current mdcode-ts package has an explicit, documented migration/deprecation treatment.
   • Package contents include the correct README and distributable entry points.

   Out of scope:

   • Renaming the GitHub repository unless independently decided.
   • New CLI features or changes to mdcode behavior.
   • Claiming the npm scope, publishing packages, or setting npm deprecation metadata without the maintainer's authenticated account and final authorization.

   Why this needs a human:
   The maintainer must use the controlled @gcmdev npm scope and make the irreversible publication/deprecation decisions. An agent can prepare and verify the repository changes but cannot complete those account-level actions.
3. adrianbrowning

   added

   enhancementNew feature or requestNew feature or request

   ready-for-humanRequires human implementation or external-account decisionsRequires human implementation or external-account decisions

   on Aug 8, 2026
4. adrianbrowning commented on Oct 3, 2026

   

   adrianbrowning

   on Oct 3, 2026

   OwnerAuthor

   More actions

   Plan

   Canonical identity: @gcmdev/mdcode. The CLI binary stays mdcode.

   Decisions

   • mdcode-ts: npm deprecate plus a migration note in the README. No shim release.
   • packages/usage: depends on and imports the real name @gcmdev/mdcode (no mdcode alias).
   • First publish: the maintainer publishes 0.1.0 by hand. CI does every release after that.

   Current state (checked 2026-10-03)

   • npm has mdcode-ts@0.0.4 (bin mdcode). @gcmdev/mdcode does not exist yet.
   • The manifest's exports (., ./cli), bin (mdcode → dist/main.js) and files: [dist, README.md] are already correct. npm pack --dry-run lists README, package.json and all dist JS and .d.ts files.
   • @gcm/mdcode no longer appears anywhere in the repo.
   • mdcode-ts still appears in: the package README (badge, about 20 install/import lines), examples/CLI_EXAMPLES.md (about 15), the root package.json filter scripts, the root README, CLAUDE.md, TESTING.md, JSDoc in src/index.ts and src/types.ts, packages/usage/package.json ("mdcode": "workspace:mdcode-ts@*"), pnpm-lock.yaml, and every pending .bumpy/*.md changeset.
   • Line 27 of .bumpy/extract-region-splice-force.md says the docs "now name the published package mdcode-ts". This needs rewriting.

   Repo changes

   These go on branch 3-package-identity, off main.

   1. packages/mdcode/package.json
      • name: "@gcmdev/mdcode"
      • publishConfig.access: "public". A scoped package publishes as restricted by default, which would break a manual npm publish.
      • Add bugs. Set homepage to …/mdcode-ts#readme. Add repository.directory: "packages/mdcode".
      • Add the keywords cli and mdcode-ts, so searches for the old name still find the package.
      • Fix the --filter in the bp script.
   2. Root package.json: fix the --filter in build, dev and test:watch.
   3. packages/usage: change the dependency to "@gcmdev/mdcode": "workspace:*", update imports in library-usage, parser, transform and test-utils, then run pnpm install to refresh the lockfile.
   4. Package README
      • Shields badge: img.shields.io/npm/v/@gcmdev/mdcode, linking to npmjs.com/package/@gcmdev/mdcode.
      • Every install and import uses @gcmdev/mdcode. Use npx @gcmdev/mdcode … and pnpm dlx @gcmdev/mdcode …; both work because the package has a single bin.
      • Add a "Migrating from mdcode-ts" section: swap the dependency, update imports, and note that the mdcode command is unchanged.
   5. Apply the same changes to examples/CLI_EXAMPLES.md, the root README, CLAUDE.md, TESTING.md and the JSDoc examples.
   6. Changesets: rekey every pending changeset to "@gcmdev/mdcode", fix line 27 of extract-region-splice-force.md, and add a minor changeset for the rename. Together with the other pending minors, the first release will be 0.1.0.
   7. Unchanged: GitHub URLs (adrianbrowning/mdcode-ts), since renaming the repo is out of scope, and all CLI and runtime behaviour.

   17-commonmark-fences adds a changeset that isn't on main yet. Whichever branch merges second rekeys it.

   Verification

   • pnpm build, pnpm test and pnpm -r lint:ts all pass.
   • npm pack in packages/mdcode produces gcmdev-mdcode-*.tgz containing README, package.json and the dist entry points.
   • Clean install from that tarball in a fresh temp directory:

     npm init -y && npm i /path/to/gcmdev-mdcode-*.tgz
     npx --no-install mdcode --help    # must resolve the locally installed bin
     npx --no-install mdcode list sample.md
     node -e "import('@gcmdev/mdcode').then(m => console.log(Object.keys(m)))"

     Use --no-install because a plain npx mdcode can fall back to fetching a registry package called mdcode, which would not prove that the scoped package supplied the CLI.
   • Grep for mdcode-ts. The only remaining hits should be GitHub URLs, the migration note and the keyword.

   Maintainer steps (manual first publish)

   npm only lets you configure a trusted publisher for a package that already exists (npm-trust docs: "Package must exist"). bumpy-release.yml publishes through OIDC, so its first run can't create @gcmdev/mdcode. The order below avoids that problem.

   1. Merge the rename PR. Bumpy runs in version-pr mode and opens a PR for @gcmdev/mdcode@0.1.0. Nothing is published at this point.
   2. Don't merge the version PR yet. As an optional safeguard, add a required reviewer to the publish GitHub environment so the publish job can't run without your approval.
   3. Check out the version PR branch and publish:

      pnpm build
      cd packages/mdcode
      npm publish --access public

      This release won't have provenance. Every CI publish after it will.
   4. Configure the trusted publisher for @gcmdev/mdcode on npmjs.com, or with npm trust. Use repo adrianbrowning/mdcode-ts, workflow bumpy-release.yml, environment publish.
   5. Merge the version PR. Bumpy checks the registry with npm info before publishing, so it should skip 0.1.0. Bumpy's handling of the git tag and GitHub release for a skipped version is unverified, so check them afterwards and create them by hand if they're missing. If you added a reviewer in step 2, remove it.
   6. Deprecate the old package:

      npm deprecate mdcode-ts "Renamed to @gcmdev/mdcode: npm i @gcmdev/mdcode"

   If the version PR is merged before step 4, the publish job fails at OIDC authentication without publishing anything. Re-run the job after steps 3 and 4.
5. adrianbrowning

   marked this as blocking on Oct 4, 2026

   • Gate package releases on mdcode documentation and example checks #13
6. adrianbrowning

   unmarked this as blocking on Oct 6, 2026

   • Gate package releases on mdcode documentation and example checks #13
7. adrianbrowning commented on Oct 6, 2026

   

   adrianbrowning

   on Oct 6, 2026

   OwnerAuthor

   More actions

   When the package is renamed, also update RELEASING.md (added in #51): the package name in the trusted-publisher setup and the note that says the name is mdcode-ts until #3 lands. The release workflow, bumpy-release.yml, doesn't contain the package name, so it needs no change.