tegwick
d741661679
Assistant: codex Assistant-Model: gpt-6-astra Assistant-Session: 01a0e77b-9d43-7432-9301-e5cb6ad05ef6
250 lines
10 KiB
Markdown
250 lines
10 KiB
Markdown
# 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.
|
||
|
||
```bash
|
||
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.
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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.
|
||
|
||
```bash
|
||
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`:
|
||
|
||
```markdown
|
||
[](...)
|
||
[](...)
|
||
```
|
||
|
||
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)
|