@researchdatabox/redbox-dev-tools 0.0.1-beta.10300 → 0.0.1-beta.10760

package/README.md

@@ -31,11 +31,11 @@ npx @researchdatabox/redbox-dev-tools init redbox-hook-my-client
 This will:
 
 - Generate the standard hook archetype in the current directory
-- Create `src/`, `test/`, `support/`, `assets/`, `views/`, and `language-defaults/`
+- Create `src/`, `test/`, `support/`, `assets/`, `views/`, `language-defaults/`, and `support/bootstrap-data/`
 - Create a `package.json` with the shared Redbox dependency contract
-- Generate starter controller, service, form-config, config, Docker, and test files
+- Generate starter controller, service, form-config, config, migration registry, Docker, development, and test files
 
-The standard archetype is based on the current hook structure used for `redbox-hook-jcu`, but stripped back to generic placeholders so a new client hook can start from the same shape without inheriting client-specific logic.
+The standard archetype is based on the current hook structure used for migrated client hooks such as `redbox-hook-jcu` and `redbox-hook-cqu`, but stripped back to generic placeholders so a new client hook can start from the same shape without inheriting client-specific logic.
 
 The archetype is now backed by file-based Handlebars templates under [templates/hook-archetype](templates/hook-archetype), which gives us a clean path for future variants such as branding-heavy hooks, lighter hooks, or alternate TypeScript setups.
 
@@ -102,6 +102,7 @@ module.exports = hook;
 Hooks should declare only:
 
 - `peerDependencies.@researchdatabox/redbox-core`
+- `devDependencies.@researchdatabox/redbox-core`
 - `devDependencies.@researchdatabox/redbox-dev-tools`
 - direct `dependencies` for hook-owned runtime libraries only
 
@@ -142,6 +143,19 @@ Template variants are selected with `--template`:
 npx @researchdatabox/redbox-dev-tools init redbox-hook-my-client --template standard
 ```
 
+The generated project includes a typed migration registry under `src/migrations`, client customisation slots under `support/bootstrap-data`, `assets`, `views`, and `language-defaults`, and Docker-backed local development scripts:
+
+```bash
+npm run dev:run:build
+npm run dev:run
+```
+
+To mount a local `redbox-portal` checkout while migrating a client hook, set `REDBOX_PORTAL_PATH` in `support/development/core-mount.env` and run:
+
+```bash
+npm run dev:run:core
+```
+
 ### `check`
 
 Validate that the current hook package does not directly pin shared Redbox runtime or toolchain dependencies.
@@ -209,6 +223,14 @@ Optional Angular service scaffold:
 npx @researchdatabox/redbox-dev-tools generate form-component my-widget --app form --with-service
 ```
 
+### `sync-translation`
+
+Read translations from API and write to language defaults files.
+
+```bash
+npx @researchdatabox/redbox-dev-tools sync-translation -a "https://example.com" -l ~/redbox-portal/language-defaults
+```
+
 ### `help`
 
 Show CLI help and usage information.

package/dist/cli.js

@@ -42,12 +42,14 @@ const hook_archetype_1 = require("./templates/hook-archetype");
 const form_config_1 = require("./commands/form-config");
 const completion_1 = require("./completion");
 const cli_parsers_1 = require("./cli-parsers");
+const sync_translation_1 = require("./commands/sync-translation");
 const program = new commander_1.Command();
+const packageJson = readPackageJson(path.resolve(__dirname, '..', 'package.json'));
 // List of dependencies that are common in our legacy hooks but should not be in modern hook packages as they are supplied by redbox-core
 const forbiddenHookDeps = ['axios', 'rxjs', 'lodash', 'mocha', 'chai', 'ts-node', 'typescript'];
 const allowedSharedHookDeps = {
     dependencies: new Set(),
-    devDependencies: new Set(['@researchdatabox/redbox-dev-tools']),
+    devDependencies: new Set(['@researchdatabox/redbox-core', '@researchdatabox/redbox-dev-tools']),
     peerDependencies: new Set(['@researchdatabox/redbox-core']),
 };
 function readPackageJson(pkgPath) {
@@ -80,6 +82,7 @@ function migrateHookDependencyContract(pkg) {
         delete nextPkg.peerDependencies[depName];
     }
     nextPkg.peerDependencies['@researchdatabox/redbox-core'] = nextPkg.peerDependencies['@researchdatabox/redbox-core'] ?? '*';
+    nextPkg.devDependencies['@researchdatabox/redbox-core'] = nextPkg.devDependencies['@researchdatabox/redbox-core'] ?? nextPkg.peerDependencies['@researchdatabox/redbox-core'];
     nextPkg.devDependencies['@researchdatabox/redbox-dev-tools'] = nextPkg.devDependencies['@researchdatabox/redbox-dev-tools'] ?? '*';
     return nextPkg;
 }
@@ -104,7 +107,7 @@ function findForbiddenHookDeps(pkg) {
 program
     .name('redbox-dev-tools')
     .description('CLI for ReDBox hook development and code generation')
-    .version('1.0.0')
+    .version(packageJson.version ?? '0.0.0')
     .option('--root <path>', 'ReDBox repo root directory (required for generators)')
     .option('--core-types-root <path>', 'Override core-types package root')
     .option('--angular-root <path>', 'Override angular projects root')
@@ -131,6 +134,7 @@ program
 (0, form_config_1.registerMigrateFigshareConfigCommand)(program);
 (0, form_config_1.registerClientFormConfigCommand)(program);
 (0, form_config_1.registerQuestionTreeDiagramCommand)(program);
+(0, sync_translation_1.registerSyncTranslationCommand)(program);
 program
     .command('init [name]')
     .description('Initialize a new ReDBox hook project from the standard archetype')

package/dist/commands/form-config.js

@@ -267,7 +267,6 @@ function createMigratedFigsharePublishingConfig(brand, figshareApi, figshareApiE
         },
         record: {
             articleIdPath: mapping.recordFigArticleId ?? 'metadata.figshare_article_id',
-            articleUrlPaths: Array.isArray(mapping.recordFigArticleURL) ? mapping.recordFigArticleURL : [mapping.recordFigArticleURL ?? 'metadata.figshare_article_location'],
             dataLocationsPath: mapping.recordDataLocations ?? 'metadata.dataLocations',
             statusPath: 'metadata.figshareStatus',
             errorPath: 'metadata.figshareError',
@@ -280,7 +279,6 @@ function createMigratedFigsharePublishingConfig(brand, figshareApi, figshareApiE
             selectedFlagPath: 'selected'
         },
         authors: {
-            source: 'defaultRedboxContributors',
             uniqueBy: mapping.recordAuthorUniqueBy ?? 'email',
             externalNameField: mapping.recordAuthorExternalName ?? 'text_full_name',
             maxInlineAuthors: 50,
@@ -293,11 +291,10 @@ function createMigratedFigsharePublishingConfig(brand, figshareApi, figshareApiE
             keywords: { kind: 'path', path: 'metadata.finalKeywords', defaultValue: [] },
             funding: { kind: 'path', path: 'metadata.funder' },
             license: { source: { kind: 'path', path: mapping.recordLicensePath ?? 'metadata.license' }, matchBy: 'urlContains', required: true },
-            categories: { source: { kind: 'path', path: mapping.recordCategoryPath ?? 'metadata.forCodes', defaultValue: [] }, mappingStrategy: 'for2020Mapping' },
+            categories: { source: { kind: 'path', path: mapping.recordCategoryPath ?? 'metadata.forCodes', defaultValue: [] } },
             customFields: []
         },
         categories: {
-            strategy: 'for2020Mapping',
             mappingTable: ((figshareForMapping.FORMapping ?? []).map((entry) => ({
                 sourceCode: String(entry.redboxCode ?? entry.sourceCode ?? ''),
                 figshareCategoryId: Number(entry.figshareCategoryId ?? entry.figCode ?? 0)
@@ -307,11 +304,8 @@ function createMigratedFigsharePublishingConfig(brand, figshareApi, figshareApiE
         assets: {
             enableHostedFiles: true,
             enableLinkFiles: true,
-            dedupeStrategy: 'sourceId',
             staging: {
-                tempDir: String(figshareApi.attachmentsFigshareTempDir ?? ''),
-                cleanupPolicy: 'deleteAfterSuccess',
-                diskSpaceThresholdBytes: 1073741824
+                cleanupPolicy: 'deleteAfterSuccess'
             }
         },
         embargo: {
@@ -320,7 +314,6 @@ function createMigratedFigsharePublishingConfig(brand, figshareApi, figshareApiE
             accessRights: {
                 accessRights: { kind: 'path', path: 'metadata.accessRights' },
                 fullEmbargoUntil: { kind: 'path', path: 'metadata.embargoUntil' },
-                fileEmbargoUntil: { kind: 'path', path: 'metadata.embargoUntil' },
                 reason: { kind: 'path', path: 'metadata.embargoReason' }
             }
         },
@@ -329,7 +322,6 @@ function createMigratedFigsharePublishingConfig(brand, figshareApi, figshareApiE
             uploadedFilesCleanupDelay: typeof mapping.scheduleUploadedFilesCleanupJob === 'string' ? mapping.scheduleUploadedFilesCleanupJob : 'in 5 minutes'
         },
         workflow: {
-            transitionRules: [],
             transitionJob: {
                 enabled: String(mapping.figshareScheduledTransitionRecordWorkflowFromArticlePropertiesJob?.enabled ?? 'false') === 'true',
                 namedQuery: String(mapping.figshareScheduledTransitionRecordWorkflowFromArticlePropertiesJob?.namedQuery ?? ''),
@@ -346,7 +338,12 @@ function createMigratedFigsharePublishingConfig(brand, figshareApi, figshareApiE
         },
         writeBack: {
             articleId: 'metadata.figshare_article_id',
-            articleUrls: ['metadata.figshare_article_location'],
+            // The legacy article URL paths are write targets, so they belong to writeBack.
+            articleUrls: Array.isArray(mapping.recordFigArticleURL)
+                ? mapping.recordFigArticleURL
+                : [typeof mapping.recordFigArticleURL === 'string' && mapping.recordFigArticleURL.trim() !== ''
+                        ? mapping.recordFigArticleURL
+                        : 'metadata.figshare_article_location'],
             extraFields: []
         },
         migrationReport: {

package/dist/commands/sync-translation.d.ts

@@ -0,0 +1,12 @@
+import { Command } from "commander";
+type MetaEntryKey = string;
+declare const contentFormats: readonly ["plain", "html"];
+type ContentFormats = typeof contentFormats[number];
+type MetaEntryValue = {
+    category?: string;
+    description?: string;
+    contentFormat?: ContentFormats;
+};
+export type MetaEntries = Record<MetaEntryKey, MetaEntryValue>;
+export declare function registerSyncTranslationCommand(program: Command): void;
+export {};

package/dist/commands/sync-translation.js

@@ -0,0 +1,160 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerSyncTranslationCommand = registerSyncTranslationCommand;
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const contentFormats = ["plain", "html"];
+function isContentFormat(value) {
+    return contentFormats.some(contentFormat => contentFormat === value);
+}
+function firstNonEmptyString(...value) {
+    for (const item of value) {
+        if (typeof item === 'string' && item.length > 0) {
+            return item;
+        }
+    }
+    return undefined;
+}
+function registerSyncTranslationCommand(program) {
+    program
+        .command('sync-translation')
+        .description('Read translations from API and write to language defaults files.')
+        .requiredOption('-l, --language-defaults <path>', 'Path to the language-defaults directory containing locales and meta json files.')
+        .requiredOption('-a, --api-base <url>', 'Base url for the API to obtain translations.')
+        .action(async (options) => {
+        try {
+            const globalOptions = program.opts();
+            const langDefaultsPath = node_path_1.default.resolve(options.languageDefaults);
+            const apiBaseUrl = options.apiBase;
+            if (!langDefaultsPath) {
+                throw new Error(`Must provide language-defaults path.`);
+            }
+            if (!apiBaseUrl) {
+                throw new Error(`Must provide api-base url.`);
+            }
+            // Read files
+            const langDefaultsMetaPath = node_path_1.default.resolve(langDefaultsPath, 'meta.json');
+            console.log(`Load translation meta file ${langDefaultsMetaPath}`);
+            const langDefaultsMetaData = JSON.parse(await promises_1.default.readFile(langDefaultsMetaPath, { encoding: 'utf8' }));
+            const langDefaultsLocales = (await promises_1.default.readdir(langDefaultsPath, { withFileTypes: true }))
+                .filter(dirent => dirent.isDirectory())
+                .map(dirent => dirent.name);
+            const langDefaultsLocaleTranslationData = [];
+            for (const locale of langDefaultsLocales) {
+                const p = node_path_1.default.resolve(langDefaultsPath, locale, 'translation.json');
+                const data = JSON.parse(await promises_1.default.readFile(p, { encoding: 'utf8' }));
+                console.log(`Load translation locale file ${p}`);
+                langDefaultsLocaleTranslationData.push({ locale, data });
+            }
+            // Read urls
+            const translationUrl = new URL('/default/rdmp/locales/__locale__/translation.json', apiBaseUrl);
+            const entriesUrl = new URL('/default/rdmp/app/i18n/entries', apiBaseUrl);
+            console.log(`Load translation entries url ${entriesUrl}`);
+            const entriesResponse = await fetch(entriesUrl, { signal: AbortSignal.timeout(5000) });
+            if (!entriesResponse.ok) {
+                throw new Error(`Could not fetch translation entries: status ${entriesResponse.status} body ${await entriesResponse.text()}`);
+            }
+            const entriesData = await entriesResponse.json();
+            const translationData = [];
+            for (const langDefaultsLocale of langDefaultsLocales) {
+                const translationLocaleUrl = translationUrl.toString().replace('/__locale__/', `/${langDefaultsLocale}/`);
+                console.log(`Load translation locale url ${translationLocaleUrl}`);
+                const translationResponse = await fetch(translationLocaleUrl, { signal: AbortSignal.timeout(5000) });
+                if (!translationResponse.ok) {
+                    throw new Error(`Could not fetch translation locale: status ${translationResponse.status} body ${await translationResponse.text()}`);
+                }
+                translationData.push({
+                    locale: langDefaultsLocale,
+                    data: await translationResponse.json()
+                });
+            }
+            // Merge locale data
+            // Maintain _meta in translation.json file, but don't update it from remote meta.
+            const translationMerged = {};
+            for (const { locale, data } of langDefaultsLocaleTranslationData) {
+                if (locale in translationMerged) {
+                    throw new Error(`Duplicate locale ${locale}`);
+                }
+                const translationDataFromUrl = translationData.find(i => i.locale === locale) ?? { locale, data: {} };
+                const dataOnlyStrings = {};
+                for (const [key, value] of Object.entries(translationDataFromUrl.data)) {
+                    if (typeof value === 'string') {
+                        dataOnlyStrings[key] = value;
+                    }
+                    else {
+                        console.log(`Dropped key '${key}' with non-string value ${JSON.stringify(value)}`);
+                    }
+                }
+                const newData = { ...data, ...dataOnlyStrings };
+                if (globalOptions.dryRun) {
+                    const changes = Object.entries(newData)
+                        .filter(([key, value]) => data[key] !== value)
+                        .map(([key, value]) => [key, { 'original': data[key], 'new': value }]);
+                    if (changes.length > 0) {
+                        console.log({ locale, changes: Object.fromEntries(changes) });
+                    }
+                }
+                translationMerged[locale] = newData;
+            }
+            if (globalOptions.dryRun) {
+                console.log('[dry-run] Translation data merged; no file written.');
+            }
+            else {
+                // Write merged data back to locale file
+                for (const [locale, data] of Object.entries(translationMerged)) {
+                    const p = node_path_1.default.resolve(langDefaultsPath, locale, 'translation.json');
+                    console.log(`Writing updated translation data to ${p}`);
+                    await promises_1.default.writeFile(p, JSON.stringify(data, null, 2));
+                }
+            }
+            // Merge meta, in highest to lowest priority order:
+            // remote meta, _meta key from the translation, existing meta entry.
+            // Use a calculated value for description and category if they are not provided.
+            const metaMerged = {};
+            for (const [locale, localeTranslation] of Object.entries(translationMerged)) {
+                const entriesLocale = entriesData.filter(e => e.locale === locale);
+                for (const key of Object.keys(localeTranslation)) {
+                    if (key === '_meta' || key.startsWith('_meta.')) {
+                        continue;
+                    }
+                    const entriesItems = entriesLocale.filter(e => e.key === key);
+                    const entriesItem = entriesItems.length > 0 ? entriesItems[0] : undefined;
+                    const translationItem = localeTranslation[key] ?? "";
+                    const translationMetaItem = ('_meta' in localeTranslation && localeTranslation['_meta'] !== null && typeof localeTranslation['_meta'] === 'object') ? localeTranslation['_meta'][key] : undefined;
+                    const metaItem = langDefaultsMetaData[key];
+                    // Populate the meta data.
+                    const contentFormatRaw = firstNonEmptyString(entriesItem?.contentFormat, translationMetaItem?.contentFormat, metaItem?.contentFormat);
+                    let contentFormat = isContentFormat(contentFormatRaw) ? contentFormatRaw : undefined;
+                    // Don't guess whether the translation value is html or plain, leave it as-is.
+                    const description = firstNonEmptyString(entriesItem?.description, translationMetaItem?.description, metaItem?.description, `Translation for ${key}`);
+                    const keySplit = key.split(/[_\-:.@]+/).filter(i => !!i);
+                    const category = firstNonEmptyString(entriesItem?.category, translationMetaItem?.category, metaItem?.category, keySplit.length > 0 ? keySplit[0] : undefined);
+                    const newItem = { category, description, contentFormat };
+                    if (globalOptions.dryRun && JSON.stringify(metaItem) !== JSON.stringify(newItem)) {
+                        console.log({ key, metaItem, translationItem, entriesItem, newItem });
+                    }
+                    if (Object.keys(newItem).length > 0 && Object.values(newItem).some(v => !!v)) {
+                        metaMerged[key] = newItem;
+                    }
+                }
+            }
+            if (globalOptions.dryRun) {
+                console.log('[dry-run] Meta merged; no file written. Changed entries printed above.');
+            }
+            else {
+                // Write merged meta back to file
+                console.log(`Writing updated meta to ${langDefaultsMetaPath}`);
+                await promises_1.default.writeFile(langDefaultsMetaPath, JSON.stringify(metaMerged, null, 2));
+            }
+            console.log(`\n🛠️  Ran sync-translation`);
+            console.log('\n✅ Done!\n');
+        }
+        catch (error) {
+            console.error(`\n❌ Error: `, error);
+            process.exit(1);
+        }
+    });
+}

package/dist/templates/hook-archetype.js

@@ -32,11 +32,16 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.generateHookArchetype = generateHookArchetype;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
-const sails_ng_common_1 = require("@researchdatabox/sails-ng-common");
+const handlebars_1 = __importDefault(require("handlebars"));
+const handlebars = handlebars_1.default.create();
+handlebars.registerHelper('json', (value) => JSON.stringify(value));
 function toPascalCase(value) {
     return value
         .split(/[^A-Za-z0-9]+/)
@@ -70,7 +75,7 @@ function walkTemplateFiles(dir) {
 }
 function renderTemplate(sourcePath, context) {
     const templateSource = fs.readFileSync(sourcePath, 'utf8');
-    const template = (0, sails_ng_common_1.handlebarsCompile)(templateSource, { noEscape: true });
+    const template = handlebars.compile(templateSource, { noEscape: true });
     return template(context);
 }
 function toOutputRelativePath(templateRoot, filePath) {
@@ -142,7 +147,7 @@ function buildTemplateContext(options) {
         hookShortName,
         hookPascalName,
         description: options.description ?? `ReDBox hook for ${hookPascalName}`,
-        integrationDirName: hookShortName,
+        integrationDirName: `hook-${hookShortName}`,
         redboxCoreVersion: readDependencyPackageVersion(packageRoot, 'redbox-core'),
         redboxDevToolsVersion: readOwnPackageVersion(packageRoot),
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@researchdatabox/redbox-dev-tools",
-  "version": "0.0.1-beta.10300",
+  "version": "0.0.1-beta.10760",
   "description": "ReDBox customisation dev tools - shared configuration, generators, and migration tooling",
   "type": "commonjs",
   "main": "index.js",
@@ -44,8 +44,8 @@
   },
   "homepage": "https://github.com/redbox-mint/redbox-portal/tree/v4.5.1#readme",
   "dependencies": {
-    "@researchdatabox/redbox-core": "0.0.1-beta.10300",
-    "@researchdatabox/sails-ng-common": "0.0.1-beta.10300",
+    "@researchdatabox/redbox-core": "0.0.1-beta.10760",
+    "@researchdatabox/sails-ng-common": "0.0.1-beta.10760",
     "@tsconfig/node24": "24.0.4",
     "@types/chai": "5.2.3",
     "@types/lodash": "4.17.24",

package/templates/hook-archetype/standard/.gitignore.hbs

@@ -2,3 +2,4 @@ dist
 node_modules
 .tmp
 coverage
+support/development/.tmp

package/templates/hook-archetype/standard/.npmignore.hbs

@@ -1,3 +1,4 @@
 src
 test
-support
+support/*
+!support/prepare-minio.sh

package/templates/hook-archetype/standard/AGENTS.md.hbs

@@ -1,9 +1,18 @@
 # {{packageName}} Agent Guide
 
-This hook follows the standard ReDBox hook archetype generated by `@researchdatabox/redbox-dev-tools init`.
+This hook follows the richer ReDBox client hook archetype generated by `@researchdatabox/redbox-dev-tools init`.
 
 Keep these rules in place unless the user explicitly asks to change the hook model.
 
+## Project Shape
+
+- `src/index.ts` is the hook entry point and compiles to `dist/index.js`.
+- `src/config/` contains config returned from `registerRedboxConfig()`.
+- `src/form-config/` contains typed form definitions returned from `registerRedboxFormConfigs()`.
+- `src/migrations/` contains the synchronous hook migration registry.
+- `support/bootstrap-data/`, `assets/`, `views/`, and `language-defaults/` hold client material used by the Docker harness and hook runtime.
+- `support/development/` and `support/integration-testing/` contain the local portal and Mocha harnesses.
+
 ## Dependency Contract
 
 - `@researchdatabox/redbox-core` is the runtime compatibility anchor.
@@ -27,8 +36,16 @@ Use the existing scripts in `package.json`.
 
 Do not replace the custom `run-hook-tsc` or `run-hook-mocha` entrypoints with plain `tsc` or `mocha`.
 
+## Config And Migrations
+
+Prefer returning config from `registerRedboxConfig()` instead of mutating `sails.config` in `configure()`.
+
+Keep `registerRedboxMigrations()` synchronous. Add new migration modules to `src/migrations/index.ts`, and give each migration a unique hook-prefixed, sortable name such as `{{packageName}}:20260703T000000-seed-client-defaults`.
+
 ## Docker Runtime
 
 The docker compose files intentionally set `NODE_PATH` so a mounted hook can resolve host-provided runtime dependencies from the Redbox portal dependency tree.
 
 Do not remove that unless the runtime install model changes deliberately.
+
+For mounted-core development, update `support/development/core-mount.env` or pass `REDBOX_PORTAL_PATH` in the environment, then use `npm run dev:run:core`. Do not hand-edit the generated `support/development/.tmp/core-mount.env` file.

package/templates/hook-archetype/standard/Dockerfile.hbs

@@ -1,24 +1,27 @@
-ARG REDBOX_BASE_IMAGE=qcifengineering/redbox-portal:develop-pdfgen
+ARG REDBOX_PORTAL_IMAGE=qcifengineering/redbox-portal:develop-pdfgen
 
-FROM ${REDBOX_BASE_IMAGE} AS builder
+FROM ${REDBOX_PORTAL_IMAGE} AS builder
 
 USER root
 
-COPY {{packageName}} /opt/{{packageName}}
-COPY redbox-portal/packages/redbox-core /opt/redbox-portal/packages/redbox-core
-COPY redbox-portal/packages/sails-ng-common /opt/redbox-portal/packages/sails-ng-common
-COPY redbox-portal/packages/redbox-dev-tools /opt/redbox-portal/packages/redbox-dev-tools
+COPY . /opt/{{packageName}}
 
 RUN --mount=type=cache,target=/root/.npm \
   cd /opt/{{packageName}} \
-  && npm install --include=dev --ignore-scripts --legacy-peer-deps \
+  && npm install --include=dev --ignore-scripts --strict-peer-deps \
   && npm run compile \
+  && HOOK_TARBALL="$(npm pack --pack-destination /tmp --silent)" \
   && cd /opt/redbox-portal \
-  && npm install --legacy-peer-deps --ignore-scripts /opt/{{packageName}} \
-  && mkdir -p /opt/redbox-portal/language-defaults \
-  && if [ -d /opt/{{packageName}}/language-defaults ]; then cp -a /opt/{{packageName}}/language-defaults/. /opt/redbox-portal/language-defaults/; fi
+  && npm install --legacy-peer-deps --ignore-scripts "/tmp/${HOOK_TARBALL}" \
+  && rm -f "/tmp/${HOOK_TARBALL}" \
+  && mkdir -p /opt/redbox-portal/views /opt/redbox-portal/assets /opt/redbox-portal/.tmp/public /opt/redbox-portal/language-defaults /opt/redbox-portal/bootstrap-data \
+  && if [ -d /opt/{{packageName}}/views ]; then cp -a /opt/{{packageName}}/views/. /opt/redbox-portal/views/; fi \
+  && if [ -d /opt/{{packageName}}/assets ]; then cp -a /opt/{{packageName}}/assets/. /opt/redbox-portal/assets/; fi \
+  && if [ -d /opt/{{packageName}}/assets ]; then cp -a /opt/{{packageName}}/assets/. /opt/redbox-portal/.tmp/public/; fi \
+  && if [ -d /opt/{{packageName}}/language-defaults ]; then cp -a /opt/{{packageName}}/language-defaults/. /opt/redbox-portal/language-defaults/; fi \
+  && if [ -d /opt/{{packageName}}/support/bootstrap-data ]; then cp -a /opt/{{packageName}}/support/bootstrap-data/. /opt/redbox-portal/bootstrap-data/; fi
 
-FROM ${REDBOX_BASE_IMAGE} AS {{packageName}}
+FROM ${REDBOX_PORTAL_IMAGE} AS {{packageName}}
 USER root
 
 COPY --from=builder --chown=node:node --chmod='u=rwx,g=rx,o=rx' /opt/redbox-portal /opt/redbox-portal

package/templates/hook-archetype/standard/README.md.hbs

@@ -1,13 +1,11 @@
 # {{packageName}}
 
-A generated ReDBox hook archetype.
+A generated ReDBox client hook archetype.
 
-This project keeps its dependency declarations intentionally small:
-
-- `@researchdatabox/redbox-core` is the ReDBox runtime compatibility contract
-- `@researchdatabox/redbox-dev-tools` provides the shared compile and unit-test toolchain
-- direct `dependencies` are reserved for hook-owned runtime libraries only
-- the generated package versions assume `redbox-core` and `redbox-dev-tools` are installed from npm, not from a sibling `redbox-portal` checkout
+This project is shaped for migrating v4 client customisation hooks to the
+current ReDBox hook contract. It includes TypeScript registrations for config,
+form configs, services, controllers, and migrations, plus Docker-backed
+development and Mocha integration harnesses.
 
 ## Development
 
@@ -19,21 +17,41 @@ npm run test:unit
 
 Local installs intentionally allow lifecycle scripts so native modules and other postinstall hooks can run. Use `npm install --ignore-scripts` only in controlled CI or container contexts where that trade-off is deliberate.
 
-For the docker-backed portal harness:
+For the image-backed portal harness:
 
 ```bash
 npm run dev:run:build
 npm run dev:run
 ```
 
-The development compose stack expects a locally trusted CA certificate at `support/development/certs/dev-ca.pem` and mounts it with `NODE_EXTRA_CA_CERTS`. Generate that certificate with your local CA tooling, for example `mkcert -CAROOT`, before starting the stack.
+To test against a local `redbox-portal` checkout, set `REDBOX_PORTAL_PATH` in
+`support/development/core-mount.env` and run:
+
+```bash
+npm run dev:run:core
+```
+
+The helper script resolves relative paths from this hook root, validates the
+portal checkout, installs missing dependencies, compiles the hook, compiles the
+portal server packages, and writes the resolved path to
+`support/development/.tmp/core-mount.env` for Docker Compose.
+
+## Dependency Contract
+
+- `@researchdatabox/redbox-core` is the runtime compatibility contract
+- `@researchdatabox/redbox-dev-tools` provides the shared compile and unit-test toolchain
+- direct `dependencies` are reserved for hook-owned runtime libraries only
+- shared packages such as `axios`, `rxjs`, `lodash`, `mocha`, `chai`, `ts-node`, and `typescript` should not be pinned directly here
 
 ## Structure
 
 - `src/index.ts`: hook entrypoint using `defineRedboxHook()`
 - `src/api/controllers`: hook controllers
 - `src/api/services`: hook services
-- `src/config`: configuration and reusable form definition helpers
+- `src/config`: configuration and reusable form definition helpers registered through `registerRedboxConfig()`
 - `src/form-config`: form config exports
+- `src/migrations`: synchronous hook migration registry
+- `support/bootstrap-data`: bootstrap data copied into the portal image/harness
+- `assets`, `views`, and `language-defaults`: client customisation material copied or resolved by the hook runtime
 - `test/unit`: fast hook-local TypeScript tests
 - `test/integration`: portal integration tests

package/templates/hook-archetype/standard/assets/default/.gitkeep

@@ -0,0 +1 @@
+

package/templates/hook-archetype/standard/assets/images/.gitkeep

@@ -0,0 +1 @@
+

package/templates/hook-archetype/standard/assets/styles/.gitkeep

@@ -0,0 +1 @@
+

package/templates/hook-archetype/standard/language-defaults/README.md.hbs

@@ -0,0 +1,10 @@
+This folder contains hook-provided i18n defaults that can seed the database
+and serve as runtime fallbacks when the database has no matching value.
+
+Expected structure:
+
+- `language-defaults/<lng>/translation.json`
+- `language-defaults/meta.json` for optional category/description metadata
+
+Keep generated client locale assets out of this folder; those belong under
+the portal asset build output, not in the hook source.

package/templates/hook-archetype/standard/language-defaults/en/translation.json.hbs

@@ -0,0 +1,3 @@
+{
+  "@{{hookShortName}}-hook-status": "{{hookPascalName}} hook ready"
+}

package/templates/hook-archetype/standard/language-defaults/meta.json.hbs

@@ -0,0 +1,6 @@
+{
+  "{{hookShortName}}-hook-status": {
+    "category": "{{hookShortName}}",
+    "description": "Example translation seeded by {{packageName}}"
+  }
+}

package/templates/hook-archetype/standard/package.json.hbs

@@ -9,18 +9,22 @@
     "hasControllers": true,
     "hasServices": true,
     "hasConfig": true,
-    "hasFormConfigs": true
+    "hasFormConfigs": true,
+    "hasMigrations": true
   },
   "scripts": {
     "compile": "node ./node_modules/@researchdatabox/redbox-dev-tools/bin/run-hook-tsc.js -p tsconfig.json",
     "test": "npm run test:unit && npm run test:integration:mocha",
-    "test:unit": "TS_NODE_PROJECT=./test/tsconfig.json npm run compile && node ./node_modules/@researchdatabox/redbox-dev-tools/bin/run-hook-mocha.js --config ./test/unit/.mocharc.cjs ./test/unit",
-    "test:integration:mocha": "npm run compile &&docker compose -f ./support/integration-testing/docker-compose.mocha.yml up --build --menu=false --abort-on-container-exit --exit-code-from redboxportal",
+    "test:unit": "TS_NODE_PROJECT=./test/tsconfig.json npm run compile && node ./node_modules/@researchdatabox/redbox-dev-tools/bin/run-hook-mocha.js --config ./test/unit/.mocharc.cjs \"./test/unit/**/*.test.ts\"",
+    "test:integration:mocha": "npm run compile && docker compose -f ./support/integration-testing/docker-compose.mocha.yml up --build --menu=false --abort-on-container-exit --exit-code-from redboxportal",
     "test:integration:mocha:clean": "docker compose -f ./support/integration-testing/docker-compose.mocha.yml down -v --remove-orphans --timeout 180",
-    "dev:run": "docker compose -f ./support/development/docker-compose.yml up --menu=false --abort-on-container-exit --exit-code-from rbportal",
-    "dev:run:build": "docker compose -f ./support/development/docker-compose.yml build",
+    "dev:run:prepare": "mkdir -p ./support/development/.tmp/attachments/staging ./support/development/.tmp/mongo ./support/development/.tmp/minio/data",
+    "dev:run": "npm run dev:run:prepare && docker compose -f ./support/development/docker-compose.yml up --menu=false --abort-on-container-exit --exit-code-from rbportal",
+    "dev:run:build": "docker compose -f ./support/development/docker-compose.yml build --pull",
     "dev:run:clean": "docker compose -f ./support/development/docker-compose.yml down -v --remove-orphans --timeout 180",
-    "dev:run:prepare": "mkdir -p ./support/development/.tmp/attachments/staging"
+    "dev:run:core:prepare": "bash ./support/development/prepare-core-mount.sh",
+    "dev:run:core": "npm run dev:run:core:prepare && docker compose --env-file ./support/development/.tmp/core-mount.env -f ./support/development/docker-compose.yml -f ./support/development/docker-compose.core-mount.yml up --menu=false --abort-on-container-exit --exit-code-from rbportal",
+    "dev:run:core:clean": "REDBOX_PORTAL_PATH=/tmp/unused docker compose -f ./support/development/docker-compose.yml -f ./support/development/docker-compose.core-mount.yml down -v --remove-orphans --timeout 180"
   },
   "keywords": [
     "sails",