markitect-main/roadmap/testdrive-jsui-publication/PLAN.md

TestDrive-JSUI — npm Publication

Current disposition — 2026-09-28

Status: blocked. Tracked by MARKITECT-WP-0002; its T01 readiness-definition task is complete. This section supersedes the historical assumptions and commands below. Existing P.1–P.9 remain the release checklist; no new workstream is needed.

Package scope and ownership (P.1 complete)

Option B is already implemented. .gitmodules records the standalone coulomb/testdrive-jsui repository at capabilities/testdrive-jsui; Markitect consumes its pinned commit b8f13b4ae5e80e76a162187613b67cbdc3a65171. Publish from the standalone repository. Do not publish this repo's root package.json or create a Markitect v1.0.0 tag for the library.

The package manifest declares the unscoped name testdrive-jsui, MIT licensing, a JavaScript markdown editor with CJS/ESM/browser bundles and CSS, and the required marked peer range ^11.0.0 || ^12.0.0 || ^13.0.0. Its allowlist is dist/, README, LICENSE, and CHANGELOG (plus npm's package metadata). Python adapters and PyPI distribution are separate from this npm release. The standalone owner must resolve P.3's Python STANDALONE_PLAN.md; an npm bundle alone does not satisfy that plan's Python packaging acceptance.

Versioning

Use the library manifest's 1.0.0 as the candidate, not proof of publication. Before release, the standalone maintainer must check registry ownership and whether that version already exists. Preserve published versions; use a new patch for compatible fixes, a minor for compatible features, and a major for breaking public API changes. Match the manifest, lockfile, changelog, tag, and release artifact. Create v1.0.0 only in the standalone repository after the candidate passes verification, or use the next appropriate unused version.

Existing release steps and acceptance

Step	Current disposition / evidence required
P.1	Done: standalone repository and gitlink already exist.
P.2	Blocked in this checkout: the submodule is uninitialized, so make -n testdrive-jsui-test-all exits 2 with no matching target. Initialize the pinned submodule, install its documented dependencies, run its JS/Python integration checks, and verify actual Markitect view/edit behavior. Historical counts are not current test evidence.
P.3	Standalone owner must explicitly reconcile the Python standalone plan; do not silently archive it as satisfied by npm.
P.4	In the standalone checkout, run lint, Jest, production build, pack, isolated tarball install, consumer smoke checks, and publish dry-run. Check every advertised entry point and the exact file list.
P.5	Tag the verified standalone commit; align the changelog with the actual release date and version.
P.6	Standalone maintainer verifies registry ownership/access, publishes the verified candidate, and records registry plus CDN receipts. Route credential needs through warden route before requesting access; no credentials belong in this record.
P.7	Install the published version in a clean directory and verify editor initialization, edit/view behavior, CSS, and supported peer dependencies.
P.8	Create the release on the standalone repo's actual forge, with verified package/CDN links. The historical GitHub destination is not established by this checkout.
P.9	Add badges only after publication is verified; name the person responsible for the one-week follow-up.

Readiness evidence and unresolved gates

Read-only inspection of the clean standalone checkout at 701341d7fa520f860245e28eb16d44b767fd116b found the four advertised JS/CSS entry files present, but types: dist/index.d.ts points to a missing file. The pinned commit advertises that same declaration path. The standalone owner must generate and test declarations or remove the unsupported promise before release. Also test CJS consumption explicitly: the manifest combines type: module with a .cjs.js entry name. File presence does not prove loading.

The standalone JSUI-WP-0002 records 68 passing Jest tests and build evidence from July 8. Its checklist still leaves post-publication verification open; that historical readiness result is not proof of an npm release. This review has not rerun those tests or checked registry availability.

For P.4, inspect npm pack --dry-run --json, then install the actual tarball in an isolated consumer directory. Exercise ESM, CommonJS, and browser loading with the supported marked peer and CSS. Confirm declarations resolve if advertised. Source maps currently exist and the changelog explicitly promises them, so review their contents and inclusion intentionally; the older blanket exclusion below is not the current packaging decision. Run npm publish --dry-run only after lint, build, tests, and consumer checks pass. Record exact command results and artifact/version identity before releasing.

Historical plan (retained for context)

Context

TestDrive-JSUI is a JavaScript-first markdown editor library living at capabilities/testdrive-jsui/. Phases 1–6 (build system, bundling, testing, migration) are complete. 84 tests pass (68 JS + 15 Python + 1 fixes). Single source of truth: capabilities/testdrive-jsui/js/.

This workstream covers the remaining work to publish the library to npm and close out the capability.

Source: capabilities/testdrive-jsui/TODO.md (Phases 7–9) Package name: testdrive-jsui (to be confirmed in P.1) Current version: 1.0.0

---

Tasks

P.1 — Pre-publication: decide repository structure

The library currently lives inside the markitect monorepo. Before publishing to npm, decide whether it ships from here or from a dedicated repo.

Options:

• A: Publish directly from capabilities/testdrive-jsui/ — simpler, no repo split
• B: Extract to a standalone testdrive-jsui repo — cleaner for npm consumers

Record the decision and proceed accordingly.

Acceptance: Decision recorded; if B, standalone repo created and code copied.

---

P.2 — Pre-publication: verify Markitect integration

Confirm the main Markitect application still works correctly with the current capability code before publishing.

cd /home/worsch/markitect-main
make testdrive-jsui-test-all   # 84 tests must pass
# Manually verify view and edit modes in the running Markitect app

Acceptance: All 84 tests pass; view and edit modes confirmed working.

---

P.3 — Pre-publication: decide STANDALONE_PLAN.md

STANDALONE_PLAN.md exists in the capability but its status is unclear. Either:

• Implement it (if it describes meaningful standalone work)
• Explicitly archive it with a note that the standalone use case is covered by the npm package

Acceptance: File updated with a clear status note; or deleted if obsolete.

---

P.4 — Pre-publication: pack and dry-run

Run the full pre-publish checklist.

cd capabilities/testdrive-jsui
npm run lint          # zero errors
npm test              # all 84 tests pass
npm run build:prod    # clean production build
npm pack              # creates testdrive-jsui-1.0.0.tgz
npm install ./testdrive-jsui-1.0.0.tgz --dry-run   # verify install
npm publish --dry-run  # verify what will be published

Review --dry-run output: confirm only intended files are included (check .npmignore or files field in package.json).

Acceptance: npm publish --dry-run succeeds with expected file list; no test files, source maps, or internal docs included unintentionally.

---

P.5 — Pre-publication: create release tag

git tag -a v1.0.0 -m "Release testdrive-jsui v1.0.0"
# (push tag to remote when ready)

Acceptance: Tag v1.0.0 exists on main; CHANGELOG.md entry present for 1.0.0.

---

P.6 — Publication: publish to npm

cd capabilities/testdrive-jsui
npm login   # if not already logged in
npm publish

Then verify:

• Package visible at https://www.npmjs.com/package/testdrive-jsui
• Wait 5–10 minutes, then check CDN availability:
  • https://cdn.jsdelivr.net/npm/testdrive-jsui@1.0.0/dist/testdrive-jsui.min.js
  • https://unpkg.com/testdrive-jsui@1.0.0/dist/testdrive-jsui.min.js

Acceptance: Package installable via npm install testdrive-jsui.

---

P.7 — Publication: fresh install test

In a clean temporary directory, install from npm and verify the library works with a minimal HTML file.

mkdir /tmp/testdrive-test && cd /tmp/testdrive-test
npm install testdrive-jsui marked
# Open standalone.html equivalent, confirm editor initialises

Acceptance: new TestDriveJSUI({...}) works in a fresh install with no reference to the capability source directory.

---

P.8 — Publication: GitHub release

Create a GitHub release from the v1.0.0 tag with:

• Release notes (summary from CHANGELOG.md 1.0.0 entry)
• Link to npm package
• Link to CDN URLs (jsdelivr, unpkg)

Acceptance: GitHub release published and visible.

---

P.9 — Post-publication: README badges and monitoring

Add npm badges to capabilities/testdrive-jsui/README.md:

[![npm version](https://badge.fury.io/js/testdrive-jsui.svg)](...)
[![npm downloads](https://img.shields.io/npm/dm/testdrive-jsui.svg)](...)

Set a reminder to check download stats after 1 week. Demo page and GitHub Pages are optional — do only if there's a specific audience to point at it.

Acceptance: README has version and download count badges; committed.

---

Task order

P.1 (repo decision)
P.2 (Markitect integration check)   ← can run in parallel with P.1
P.3 (STANDALONE_PLAN decision)      ← can run in parallel
     ↓
P.4 (pack + dry-run)   ← needs P.1, P.2, P.3 all done
P.5 (release tag)      ← can run with P.4
     ↓
P.6 (publish)
P.7 (fresh install test)
P.8 (GitHub release)
P.9 (badges + monitoring)

Out of scope

• Adding new features before publication (ship what's there)
• Ruby or Java adapters (optional integrations, not blocking publication)
• Paid npm features (keep on free tier)