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

# TestDrive-JSUI — npm Publication

## 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
[![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)