Decompose IMS Content Packages (SCORM/IMSCP) into individual Kolibri resources

[rtibbles]

Overview

Migrate the imscp code into ricecooker.

Decompose an IMS Content Package (including SCORM) into individual Kolibri resources, driven by its manifest.

This reverses the original "no dependency zips" decision; shared-library dependency zips return as a follow-up.

Complexity: High
Target branch: main

Context

• The imscp code lives in a separate repo (learningequality/imscp) and should be native to ricecooker.
• IMSCP is the packaging layer under SCORM.
• Its manifest (imsmanifest.xml) is the standardized, tool-independent structure.
• One opaque webcontent zip backs many nodes, so Kolibri's per-resource import pulls the whole package when a single node is selected.
• Wrapping plain media in an HTML5 sandbox strips native affordances — a video should play as a VideoNode, not a <video> in a sandbox.
• The existing reference machinery locates and rewrites references only within a single archive.

The decomposition ladder

Per manifest resource, take the highest rung it safely qualifies for:

1. Native media node (video/audio/pdf/image) — a single media file in a wrapper.
2. KPUB — static article/document HTML.
3. HTML5 zip served via zipcontent — genuinely interactive content.
4. QTI assessment item — assessment content.

Classification runs on one axis: does the resource's meaning survive stripping its JS/CSS?

• Discount SCORM API boilerplate (pipwerks, LMSInitialize, SetValue) before judging interactivity.
• Bias conservative — promote only on high confidence.
• Never promote a resource carrying assessment, score, or tracking semantics.

The crux

Decomposition must rewrite references across resources: a promoted node referenced by a sibling, or a shared library in a dependency zip.

The rewrite emits two new target forms:

• native-node references
• zipcontent-relative dependency paths

Deferred to follow-ups

• Per-tool deep parsers (Storyline, Captivate, Rise, iSpring, Adapt content models).
• Interactivity classification beyond the sanitization-survival test.
• Automatic dependency-zip vendoring for shared HTML5 libraries.

Acceptance Criteria

• An IMSCP/SCORM package imports natively, with the imscp code migrated into ricecooker.
• The manifest drives the node/topic tree.
• A single wrapped media file becomes a native media node.
• A static-article resource becomes a KPUB.
• An interactive resource becomes an HTML5 zip served via zipcontent.
• A resource carrying assessment semantics is never promoted to media or KPUB.
• References between decomposed resources resolve correctly in Kolibri.
• Each decomposed node is backed by its own files, not one shared package zip.

[rtibblesbot]

Watching for resolution on behalf of #337.

[rtibblesbot]

Design review — 4 blocking questions before implementation

I ran the brainstorming pass against the current codebase (pipeline, archive_assets, references.py) and the legacy learningequality/imscp source. The legacy code parses imsmanifest.xml into a topic tree but always wraps every resource as an HTML5AppNode (whole-package zip, or an entrypoint redirect + HTML5_DEPENDENCY_ZIP). This issue asks for something substantially new — the decomposition ladder — so four forks below change what gets built. Each has a recommended default; confirming them (or correcting) unblocks a plan.

1. Where does decomposition live?
The pipeline is single-file → single-node (one File → one node's files). IMSCP decomposition explodes one package into a heterogeneous node subtree (topics + media/KPUB/HTML5/QTI leaves). That does not fit the "new file type = 2 pipeline changes" model, and the pipeline has no concept of emitting a subtree.
Recommend: a chef-facing utility (successor to legacy make_topic_tree, e.g. ricecooker/utils/imscp.py) that a SushiChef calls to expand an IMSCP zip into a node tree, reusing the pipeline per emitted leaf file. Not a convert.py handler. Confirm?

2. Scope boundary with #337 (QTI).
Rung 4 is "QTI assessment item," but #337 ("Handle QTI exercises") owns per-item type='QTI' ingestion (raw_data XML via the internal API, per studio#6002). le_utils only exposes a QTI_ZIP preset today, not per-item.
Recommend: #332 detects assessment/score/tracking semantics and refuses to promote them (keeps them as HTML5 zips), satisfying "never promoted to media or KPUB." Actual type='QTI' item emission is deferred to #337. Confirm #332 does not emit QTI items itself?

3. KPUB from static HTML.
No existing path converts an IMSCP HTML resource (HTML + its referenced assets) into a valid KPUB. DocumentConversionHandler runs pandoc on documents (docx/odt/rtf/md), not HTML-with-assets; KPUBConversionHandler only validates/sanitizes an already-.kpub archive.
Recommend: which is in scope — (a) build a new HTML-article → KPUB packager, (b) pandoc HTML → KPUB, or (c) ship static articles as sanitized HTML5-article zips for now and defer true KPUB generation? This is a large swing in effort.

4. Cross-node reference target form.
AC "references between decomposed resources resolve correctly in Kolibri" needs a concrete rewrite target. There is no node-to-node reference convention in ricecooker today (no content://-style scheme), and archive_assets/references.py only rewrite external URLs and within-archive paths.
Recommend: what exact string should a reference to a promoted sibling rewrite to, and does Kolibri/zipcontent resolve it today? If the scheme doesn't exist yet, this AC can't be fully delivered here and cross-node promotion may need to stay conservative (keep mutually-referencing resources together as one HTML5 zip) until the scheme lands.

Assumptions I'll proceed on if unstated (flag if wrong):

• Classifier operationalizes "meaning survives stripping JS/CSS" as: discount SCORM boilerplate (pipwerks/LMSInitialize/SetValue), run strip_scripts, then promote only when the residual is a single media element (→ media) or static prose/media with no interactive residue (→ KPUB/HTML article); everything else stays an HTML5 zip. Bias conservative.
• Test fixtures migrated from the legacy repo's examples/ (gitta_ims.zip, eventos.zip, test_quiz.zip); pipeline tests land in tests/pipeline/.

Answering 1–4 is enough to write the implementation plan.