scorm-review 1.2.0 → 1.3.0

package/README.md

@@ -0,0 +1,361 @@
+# scorm-review
+
+> Inject the **coreview** annotation tool into any SCORM package — no server, no browser extension, no setup needed on the reviewer's end.
+
+---
+
+## Table of Contents
+
+- [What it does](#what-it-does)
+- [How it works](#how-it-works)
+- [Requirements](#requirements)
+- [Installation](#installation)
+  - [Option A — Use with npx (no install)](#option-a--use-with-npx-no-install)
+  - [Option B — Install globally](#option-b--install-globally)
+- [Usage](#usage)
+  - [Convert a SCORM zip](#convert-a-scorm-zip)
+  - [Convert a SCORM folder](#convert-a-scorm-folder)
+  - [Convert a plain HTML file](#convert-a-plain-html-file)
+  - [Specify a custom output path](#specify-a-custom-output-path)
+  - [Show help](#show-help)
+- [Output explained](#output-explained)
+- [What gets changed inside your package](#what-gets-changed-inside-your-package)
+- [How to send to a reviewer](#how-to-send-to-a-reviewer)
+- [CLI reference](#cli-reference)
+- [How it works internally](#how-it-works-internally)
+  - [Entry point detection](#entry-point-detection)
+  - [Script injection](#script-injection)
+  - [coreview.js bundling](#coreviewjs-bundling)
+- [Project structure](#project-structure)
+- [Building from source](#building-from-source)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## What it does
+
+`scorm-review` takes a SCORM package (zip file, unzipped folder, or a standalone HTML file) and injects the **coreview** annotation tool into it. The output is a new file your reviewers can open in any browser and leave comments directly on the slides — no install needed on their end.
+
+```
+Before:  my-course.zip           ← plain SCORM package
+After:   my-course_review.zip    ← same package + annotation panel built in
+```
+
+Reviewers open `index.html` from the output zip and the annotation sidebar appears automatically.
+
+---
+
+## How it works
+
+1. Opens the input (zip, folder, or HTML file)
+2. Finds the HTML entry point (`index.html`)
+3. Injects a `<script>` tag referencing `coreview.js` into that HTML file
+4. Adds `coreview.js` (the annotation tool) next to the entry HTML
+5. Saves the modified package as a new zip (or HTML file for single-file input)
+
+The original file is never modified. A new `_review` file is always created.
+
+---
+
+## Requirements
+
+- [Node.js](https://nodejs.org/) **v18 or higher**
+
+That's all. No other tools, no browser extensions, no server.
+
+To check your Node.js version:
+
+```bash
+node --version
+# Should print v18.x.x or higher
+```
+
+If you don't have Node.js, download the LTS version from [nodejs.org](https://nodejs.org).
+
+---
+
+## Installation
+
+### Option A — Use with npx (no install)
+
+Run it directly without installing anything:
+
+```bash
+npx scorm-review ./my-course.zip
+```
+
+`npx` is included with Node.js. On first run it fetches the package automatically.
+
+### Option B — Install globally
+
+Install once, use from anywhere without the `npx` prefix:
+
+```bash
+npm install -g scorm-review
+```
+
+Then:
+
+```bash
+scorm-review ./my-course.zip
+```
+
+---
+
+## Usage
+
+### Convert a SCORM zip
+
+```bash
+npx scorm-review ./my-course.zip
+```
+
+Output in the same folder:
+
+```
+Input:  my-course.zip
+Output: C:\path\to\my-course_review.zip
+
+Processing SCORM zip... done.
+
+✓ Created: my-course_review.zip (15.2 MB)
+```
+
+### Convert a SCORM folder
+
+If your SCORM package is already unzipped:
+
+```bash
+npx scorm-review ./my-course/
+```
+
+The tool walks the folder, finds `index.html`, injects the annotation tool, and packages everything back into a zip.
+
+### Convert a plain HTML file
+
+For a standalone HTML file (not a SCORM package):
+
+```bash
+npx scorm-review ./page.html
+```
+
+Output: `page_review.html` — the script is embedded inline so no separate `coreview.js` file is needed.
+
+### Specify a custom output path
+
+Use `-o` or `--output` to choose where the output file is saved:
+
+```bash
+npx scorm-review ./my-course.zip -o ./output/my-course_review.zip
+```
+
+The output directory is created automatically if it doesn't exist.
+
+### Show help
+
+```bash
+npx scorm-review --help
+```
+
+---
+
+## Output explained
+
+| Input | Output file | Notes |
+|---|---|---|
+| `my-course.zip` | `my-course_review.zip` | New zip with `coreview.js` added and `index.html` injected |
+| `my-course/` (folder) | `my-course_review.zip` | Folder re-zipped with `coreview.js` added and `index.html` injected |
+| `page.html` | `page_review.html` | Single file — script embedded inline |
+
+The output is always saved **next to the input file** unless you specify `-o`.
+
+---
+
+## What gets changed inside your package
+
+Only two things change inside the output zip compared to the original:
+
+1. **`coreview.js` is added** — placed in the same folder as `index.html`
+2. **One `<script>` tag is added to `index.html`** — injected just before `</body>`
+
+```html
+<!-- Added by scorm-review -->
+<script
+  src="./coreview.js"
+  data-project="scorm-review"
+  data-note="Please review all slides. Check layout, wording, and content."
+  data-start-open="false">
+</script>
+```
+
+Everything else — folder structure, file names, SCORM manifest, assets — is **untouched**.
+
+If a `coreview.js` script tag already exists in the HTML, it is replaced rather than duplicated.
+
+---
+
+## How to send to a reviewer
+
+1. Run `scorm-review` on your SCORM package
+2. Send the `_review.zip` to your reviewer (email, shared drive, etc.)
+3. Reviewer unzips it and opens `index.html` in any modern browser (Chrome, Edge, Firefox, Safari)
+4. The annotation panel appears automatically — they can leave comments on any slide
+5. They share their annotated session back to you (via the coreview export feature)
+
+No installs, no accounts, no browser extensions required on the reviewer's side.
+
+---
+
+## CLI reference
+
+```
+scorm-review <input> [options]
+
+Arguments:
+  <input>              Path to a .zip file, a folder, or a .html file
+
+Options:
+  -o, --output <path>  Custom output file path (default: <name>_review.zip next to input)
+  -h, --help           Show help message
+
+Supported input types:
+  .zip                 SCORM package zip file
+  folder/              Unzipped SCORM package directory
+  .html / .htm         Plain HTML file
+
+Exit codes:
+  0    Success
+  1    Error (path not found, unsupported file type, no HTML entry point found)
+```
+
+---
+
+## How it works internally
+
+### Entry point detection
+
+The tool looks for the HTML entry point in this priority order:
+
+1. `index.html` at the root of the zip/folder
+2. `Index.html` at the root (case-insensitive fallback)
+3. `<subfolder>/index.html` — one level deep (common in SCORM packages where content is inside `scorm_package/`)
+4. Any `.html` file anywhere in the package
+
+If no HTML file is found, the tool exits with an error.
+
+### Script injection
+
+The `<script>` tag is injected just before `</body>`. If the HTML has no `</body>` tag, the script is appended to the end of the file.
+
+Any existing `coreview.js` script tags are removed before injecting the new one — so re-running the tool on an already-injected package is safe and idempotent.
+
+### coreview.js bundling
+
+`coreview.js` is **baked into the CLI binary at build time** using esbuild. This means:
+
+- The CLI is a single file with no runtime file dependencies
+- The same version of the annotation tool ships with every release
+- No network access is needed at runtime — everything is self-contained
+
+---
+
+## Project structure
+
+```
+scorm-review-cli/
+├── src/
+│   ├── cli.ts               # Entry point — argument parsing, file I/O, orchestration
+│   ├── bundler.ts           # Core logic — zip handling, HTML injection, folder packing
+│   └── bundler-template.ts  # Template used during the build to embed coreview.js
+├── dist/                    # Compiled output (generated by build)
+│   └── cli.js               # Single-file compiled CLI (published to npm)
+├── build.mjs                # esbuild build script — compiles + inlines coreview.js
+├── tsconfig.json            # TypeScript configuration
+└── package.json
+```
+
+### Key files
+
+**`src/cli.ts`** — Handles all CLI concerns: argument parsing, input validation, calling the right bundler function, and writing the output file. Contains no bundling logic itself.
+
+**`src/bundler.ts`** — Contains three exported functions:
+- `bundleScormZip(zipBuffer, coreviewScript)` — processes a zip Buffer
+- `bundleScormFolder(folderPath, coreviewScript)` — processes a folder on disk
+- `bundlePlainHtml(htmlBuffer, coreviewScript)` — processes a standalone HTML file
+
+**`build.mjs`** — esbuild script that reads `coreview.js` from disk, base64-encodes it (or inlines it as a string), and substitutes the `__COREVIEW_SCRIPT__` constant at bundle time. The result is `dist/cli.js`, a single portable file with no external dependencies.
+
+---
+
+## Building from source
+
+```bash
+# Install dev dependencies
+npm install
+
+# Build dist/cli.js
+npm run build
+```
+
+The build script (`build.mjs`) uses esbuild to:
+1. Compile TypeScript to JavaScript
+2. Bundle all imports into a single file
+3. Inline `coreview.js` as a string constant at build time
+4. Output `dist/cli.js` with the Node.js shebang line
+
+To test the built binary locally:
+
+```bash
+node dist/cli.js ./samplefolder/sample3.zip
+```
+
+---
+
+## Troubleshooting
+
+**`npx: command not found`**
+
+Node.js is not installed or not on your PATH. Download from [nodejs.org](https://nodejs.org) and reinstall.
+
+---
+
+**`Error: Path not found: ...`**
+
+The file or folder you specified doesn't exist at that path. Check for typos, or use the full absolute path:
+
+```bash
+npx scorm-review "C:\Users\yourname\Desktop\my-course.zip"
+```
+
+---
+
+**`Error: No HTML entry point found`**
+
+The zip doesn't contain an `index.html`. Possible causes:
+- You pointed at a zip that isn't a SCORM package
+- The SCORM package has a non-standard entry point (e.g. `story.html` instead of `index.html`)
+- The `index.html` is nested more than one level deep
+
+Try unzipping manually and pointing the tool at the folder that contains `index.html`:
+
+```bash
+npx scorm-review ./unzipped-course/
+```
+
+---
+
+**`Error: Unsupported file type ".pptx"`**
+
+Only `.zip`, `.html`, `.htm`, and folders are accepted. Other file types are not supported.
+
+---
+
+**Output zip is much larger than the original**
+
+This is expected when the original zip used maximum compression. The tool re-compresses with level 6 (balanced), which may produce a slightly larger file compared to an original that was compressed at level 9. The content is identical.
+
+---
+
+**Running the tool again on a `_review.zip` adds a second injection**
+
+Re-running on an already-processed file is safe — the tool removes any existing `coreview.js` script tag before injecting a new one, so no duplication occurs.

package/dist/cli.js

@@ -9745,19 +9745,52 @@ var import_fs = __toESM(require("fs"));
 var import_path = __toESM(require("path"));
 function findEntryHtml(files) {
   const norm = files.map((f) => f.replace(/\\/g, "/"));
-  if (norm.includes("index.html")) return "index.html";
-  if (norm.includes("Index.html")) return "Index.html";
-  const nested = norm.find((f) => /^[^/]+\/index\.html$/i.test(f));
-  if (nested) return nested;
+  const rootCandidates = [
+    "index.html",
+    "Index.html",
+    "story.html",
+    "Story.html",
+    "index_lms.html",
+    "launch.html",
+    "default.html"
+  ];
+  for (const candidate of rootCandidates) {
+    const match = norm.find((f) => f.toLowerCase() === candidate.toLowerCase());
+    if (match) return match;
+  }
+  const nestedCandidates = ["index.html", "story.html", "index_lms.html", "launch.html", "default.html"];
+  for (const candidate of nestedCandidates) {
+    const match = norm.find((f) => new RegExp(`^[^/]+/${candidate}$`, "i").test(f));
+    if (match) return match;
+  }
+  const rootHtml = norm.find((f) => /^[^/]+\.html?$/i.test(f));
+  if (rootHtml) return rootHtml;
   const anyHtml = norm.find((f) => /\.html?$/i.test(f));
   return anyHtml ?? null;
 }
 function injectCoreviewTag(html) {
   const scriptTag = `<script src="./coreview.js" data-project="scorm-review" data-note="Please review all slides. Check layout, wording, and content." data-start-open="false"></script>`;
   html = html.replace(/<script[^>]*src="[^"]*coreview\.js"[^>]*><\/script>\s*/gi, "");
-  if (/<\/body>/i.test(html)) {
+  const hasBody = /<\/body>/i.test(html);
+  const hasHtml = /<\/html>/i.test(html);
+  if (hasBody && hasHtml) {
+    const bodyIdx = html.search(/<\/body>/i);
+    const htmlIdx = html.search(/<\/html>/i);
+    const betweenBodyAndHtml = html.slice(bodyIdx + "</body>".length, htmlIdx).trim();
+    if (betweenBodyAndHtml.length > 0) {
+      return html.replace(/<\/html>/i, `${scriptTag}
+</html>`);
+    }
     return html.replace(/<\/body>/i, `${scriptTag}
 </body>`);
+  }
+  if (hasBody) {
+    return html.replace(/<\/body>/i, `${scriptTag}
+</body>`);
+  }
+  if (hasHtml) {
+    return html.replace(/<\/html>/i, `${scriptTag}
+</html>`);
   }
   return html + "\n" + scriptTag;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scorm-review",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Convert SCORM zip packages into self-contained review HTML files",
   "main": "dist/cli.js",
   "bin": {