adapt-project 1.0.0

package/.github/workflows/releases.yml

@@ -0,0 +1,32 @@
+name: Release
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # to be able to publish a GitHub release
+      issues: write # to be able to comment on released issues
+      pull-requests: write # to be able to comment on released pull requests
+      id-token: write # to enable use of OIDC for trusted publishing and npm provenance
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 'lts/*'
+      - name: Update npm
+        run: npm install -g npm@latest
+      - name: Install dependencies
+        run: npm ci
+      - name: Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: npx semantic-release

package/.github/workflows/standardjs.yml

@@ -0,0 +1,13 @@
+name: Standard.js
+on: push
+jobs:
+  default:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@master
+      - uses: actions/setup-node@master
+        with:
+          node-version: 'lts/*'
+          cache: 'npm'
+      - run: npm ci
+      - run: npx standard

package/.github/workflows/tests.yml

@@ -0,0 +1,13 @@
+name: Tests
+on: push
+jobs:
+  default:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@master
+      - uses: actions/setup-node@master
+        with:
+          node-version: 'lts/*'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm test

package/README.md

@@ -0,0 +1,168 @@
+# adapt-project
+
+Node.js library for managing Adapt Learning Framework projects — plugins, schemas, course data, and translations.
+
+## Installation
+
+```bash
+npm install adapt-project
+```
+
+## Overview
+
+`adapt-project` provides a programmatic API for working with Adapt Framework project directories. It handles:
+
+- **Course data** — Load and manage multilingual content structured as hierarchical JSON (`course > menu/page > article > block > component`)
+- **Schemas** — Discover and validate content models using JSON schemas from plugins
+- **Plugins** — Discover installed plugins from the `src/` directory and read their metadata
+- **Translations** — Export translatable strings and import translated content (CSV, JSON, XLIFF)
+
+## Quick Start
+
+```js
+const { Framework } = require('adapt-project');
+
+const framework = new Framework({
+  rootPath: '/path/to/adapt-project'
+}).load();
+
+// Load course data
+const data = framework.getData();
+data.languages.forEach(lang => {
+  const course = lang.getCourseFileItem();
+  console.log(`${lang.name}: ${course.item._id}`);
+});
+
+// Load schemas
+const schemas = framework.getSchemas();
+
+// Discover plugins
+const plugins = framework.getPlugins();
+
+// Export translations
+const translate = framework.getTranslate({
+  masterLang: 'en',
+  format: 'csv'
+});
+await translate.export();
+```
+
+## API
+
+### `Framework`
+
+Main entry point representing an Adapt Framework root directory.
+
+```js
+const framework = new Framework({
+  rootPath: process.cwd(),   // Project root
+  outputPath: './build/',    // Build output directory
+  sourcePath: './src/',      // Source code directory
+  courseDir: 'course',       // Course data subdirectory name
+  jsonext: 'json',           // JSON file extension (json or txt)
+  trackingIdType: 'block',   // Content type to assign tracking IDs to
+  useOutputData: false,      // Read from build output instead of source
+  includedFilter: () => true,// Plugin filter function
+  log: console.log,
+  warn: console.warn
+}).load();
+```
+
+| Method | Returns | Description |
+|---|---|---|
+| `load()` | `Framework` | Load the project's `package.json` |
+| `getData()` | `Data` | Get course data instance |
+| `getPlugins()` | `Plugins` | Discover and load all plugins |
+| `getSchemas()` | `Schemas` | Load all plugin schemas |
+| `getTranslate(options)` | `Translate` | Get translation import/export instance |
+| `makeIncludeFilter()` | `function` | Build a plugin filter from `config.json` build includes/excludes |
+| `applyGlobalsDefaults()` | `Framework` | Apply schema defaults to `_globals` in course data |
+| `applyScreenSizeDefaults()` | `Framework` | Apply schema defaults to `screenSize` in config |
+
+### `Data`
+
+Manages the `course/` folder — config, languages, and all content items.
+
+| Method | Returns | Description |
+|---|---|---|
+| `load()` | `Data` | Scan and load all language directories |
+| `getLanguage(name)` | `Language` | Get a specific language by folder name |
+| `getConfigFileItem()` | `JSONFileItem` | Get the `config.json` file item |
+| `copyLanguage(from, to)` | `Language` | Duplicate a language folder |
+| `checkIds()` | `Data` | Validate `_id` / `_parentId` structure across all languages |
+| `addTrackingIds()` | `Data` | Auto-assign sequential `_trackingId` values |
+| `removeTrackingIds()` | `Data` | Strip `_trackingId` from all items |
+| `save()` | `Data` | Persist all changes to disk |
+
+### `Translate`
+
+Export and import translatable strings identified by schema annotations.
+
+```js
+const translate = framework.getTranslate({
+  masterLang: 'en',
+  targetLang: 'fr',
+  format: 'csv',         // 'csv', 'json', or 'xlf'
+  csvDelimiter: ',',
+  shouldReplaceExisting: false
+});
+
+await translate.export();  // Export master language strings
+await translate.import();  // Import translated strings into target language
+```
+
+Supported formats:
+- **CSV** — One file per content type, with auto-detected encoding and delimiter
+- **JSON** — Single `export.json` with all translatable strings
+- **XLIFF 1.2** — Single `source.xlf` file
+
+## Content Hierarchy
+
+Adapt course content follows this structure:
+
+```
+course/
+  config.json          — Global configuration
+  en/                  — Language folder
+    course.json        — Course metadata and _globals
+    contentObjects.json — Menus and pages
+    articles.json      — Articles within pages
+    blocks.json        — Blocks within articles
+    components.json    — Components within blocks
+```
+
+Each content item has:
+- `_id` — Unique identifier
+- `_type` — Model type (`course`, `menu`, `page`, `article`, `block`, `component`)
+- `_parentId` — Reference to parent item
+- `_trackingId` — Sequential tracking identifier (auto-generated)
+
+## Directory Layout
+
+```
+adapt-project/
+  index.js               — Module exports
+  lib/
+    Framework.js         — Main entry point
+    Data.js              — Course data management
+    Schemas.js           — Schema discovery and validation
+    Plugins.js           — Plugin discovery
+    Translate.js         — Translation export/import
+    JSONFile.js          — JSON file I/O
+    JSONFileItem.js      — JSON sub-item wrapper
+    data/
+      Language.js        — Single language folder
+      LanguageFile.js    — Single language file
+    plugins/
+      Plugin.js          — Plugin representation
+    schema/
+      Schema.js          — Base schema class
+      GlobalsSchema.js   — Global config schema
+      ModelSchema.js     — Content model schema
+      ExtensionSchema.js — Model extension schema
+      ModelSchemas.js    — Schema collection
+```
+
+## License
+
+GPL-3.0

package/eslint.config.js

@@ -0,0 +1,10 @@
+import { FlatCompat } from '@eslint/eslintrc'
+
+const compat = new FlatCompat()
+
+export default [
+  ...compat.extends('standard'),
+  {
+    ignores: ['node_modules/']
+  }
+]

package/index.js

@@ -0,0 +1,13 @@
+import Framework from './lib/Framework.js'
+import Data from './lib/Data.js'
+import Plugins from './lib/Plugins.js'
+import Schemas from './lib/Schemas.js'
+import Translate from './lib/Translate.js'
+
+export {
+  Framework,
+  Data,
+  Plugins,
+  Schemas,
+  Translate
+}

package/lib/Data.js

@@ -0,0 +1,185 @@
+import path from 'path'
+import fs from 'fs-extra'
+import globs from 'globs'
+import JSONFile from './JSONFile.js'
+import Language from './data/Language.js'
+
+/**
+ * @typedef {import('./Framework')} Framework
+ * @typedef {import('./JSONFileItem')} JSONFileItem
+ */
+
+/**
+ * This class represents the course folder. It contains references to the config.json,
+ * all languages, each language file and subsequently each language file item.
+ * It is filename agnostic, except for config.[jsonext], such that there are no
+ * hard references to the other file names, allowing any filename to be used with the
+ * appropriate [jsonext] file extension (usually txt or json).
+ * It assumes all language files are located at course/[langName]/*.[jsonext] and
+ * the config file is located at course/config.[jsonext].
+ * It has _id and _parentId structure checking and _trackingId management included.
+ */
+class Data {
+  /**
+   * @param {Object} options
+   * @param {Framework} options.framework
+   * @param {string} options.sourcePath
+   * @param {string} options.courseDir
+   * @param {string} options.jsonext
+   * @param {string} options.trackingIdType
+   * @param {function} options.log
+   */
+  constructor ({
+    framework = null,
+    sourcePath = null,
+    courseDir = null,
+    jsonext = 'json',
+    trackingIdType = 'block',
+    log = console.log
+  } = {}) {
+    /** @type {Framework} */
+    this.framework = framework
+    /** @type {string} */
+    this.sourcePath = sourcePath
+    /** @type {string} */
+    this.courseDir = courseDir
+    /** @type {string} */
+    this.jsonext = jsonext
+    /** @type {string} */
+    this.trackingIdType = trackingIdType
+    /** @type {function} */
+    this.log = log
+    /** @type {JSONFile} */
+    this.configFile = null
+    /** @type {[Language]} */
+    this.languages = null
+    /** @type {string} */
+    this.coursePath = path.join(this.sourcePath, this.courseDir).replace(/\\/g, '/')
+  }
+
+  /** @returns {Data} */
+  load () {
+    this.languages = globs.sync(path.join(this.coursePath, '*/')).map(languagePath => {
+      const language = new Language({
+        framework: this.framework,
+        languagePath,
+        courseDir: this.courseDir,
+        jsonext: this.jsonext,
+        trackingIdType: this.trackingIdType,
+        log: this.log
+      })
+      language.load()
+      return language
+    }).filter(lang => lang.isValid)
+    this.configFile = new JSONFile({
+      framework: this.framework,
+      path: path.join(this.coursePath, `config.${this.jsonext}`),
+      jsonext: this.jsonext
+    })
+    this.configFile.load()
+    return this
+  }
+
+  /** @type {boolean} */
+  get hasChanged () {
+    return this.languages.some(language => language.hasChanged)
+  }
+
+  /** @type {[string]} */
+  get languageNames () {
+    return this.languages.map(language => language.name)
+  }
+
+  /**
+   * Fetch a Language instance by name.
+   * @param {string} name
+   * @returns {Language}
+   */
+  getLanguage (name) {
+    const language = this.languages.find(language => language.name === name)
+    if (!language) {
+      const err = new Error(`Cannot find language '${name}'.`)
+      err.number = 10004
+      throw err
+    }
+    return language
+  }
+
+  /**
+   * Returns a JSONFileItem representing the course/config.json file object.
+   * @returns {JSONFileItem}
+   * */
+  getConfigFileItem () {
+    return this.configFile.firstFileItem
+  }
+
+  /**
+   * @param {string} fromName
+   * @param {string} toName
+   * @param {boolean} replace
+   * @returns {Language}
+   */
+  copyLanguage (fromName, toName, replace = false) {
+    const fromLang = this.getLanguage(fromName)
+    const newPath = (`${fromLang.rootPath}/${toName}/`).replace(/\\/g, '/')
+
+    if (this.languageNames.includes(toName) && !replace) {
+      const err = new Error(`Folder already exists. ${newPath}`)
+      err.number = 10003
+      throw err
+    }
+
+    let toLang
+    if (this.languageNames.includes(toName)) {
+      toLang = this.getLanguage(toName)
+    } else {
+      toLang = new Language({
+        framework: this.framework,
+        languagePath: newPath,
+        courseDir: this.courseDir,
+        jsonext: this.jsonext,
+        trackingIdType: this.trackingIdType
+      })
+      this.languages.push(toLang)
+    }
+
+    fs.mkdirpSync(newPath)
+
+    fromLang.files.forEach(file => {
+      const pathParsed = path.parse(file.path.replace(/\\/g, '/'))
+      const newLocation = `${newPath}${pathParsed.name}${pathParsed.ext}`
+      fs.removeSync(newLocation)
+      fs.copyFileSync(file.path, newLocation)
+    })
+
+    toLang.load()
+    return toLang
+  }
+
+  /** @returns {Data} */
+  checkIds () {
+    this.languages.forEach(lang => lang.checkIds())
+    return this
+  }
+
+  /** @returns {Data} */
+  addTrackingIds () {
+    this.languages.forEach(lang => lang.addTrackingIds())
+    return this
+  }
+
+  /** @returns {Data} */
+  removeTrackingIds () {
+    this.languages.forEach(lang => lang.removeTrackingIds())
+    return this
+  }
+
+  /** @returns {Data} */
+  save () {
+    this.configFile.save()
+    this.languages.forEach(language => language.save())
+    return this
+  }
+}
+
+export default Data