@researchdatabox/redbox-dev-tools 0.0.1 → 5.0.0-RC2

package/README.md

@@ -1,32 +1,277 @@
 # ReDBox Dev Tools
 
-A command line tool to assist with developing [ReDBox](https://www.redboxresearchdata.com.au) ([Sails.js](https://sailsjs.com)) hooks.
+A development toolkit for creating and maintaining ReDBox customisation hooks.
+
+## Overview
+
+The `@researchdatabox/redbox-dev-tools` package provides shared configuration, generators, and migration tooling for developing ReDBox hook projects. It ensures consistency across hook implementations and simplifies dependency management.
+
+## Features
+
+- **Shared TypeScript configuration**: Pre-configured TypeScript settings and type definitions
+- **Shared configuration**: Base `tsconfig.json` that follows ReDBox conventions
+- **CLI scaffolding**: Quick project initialization with `npx`
+- **Type safety**: Includes ReDBox core types as peer dependency
+- **Version alignment**: Versioned to match ReDBox core releases
 
 ## Installation
 
-Install the tool using npm
+```bash
+npm install --save-dev @researchdatabox/redbox-dev-tools
+```
+
+## Quick Start
+
+Initialize a new hook project:
+
+```bash
+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/`, `language-defaults/`, and `support/bootstrap-data/`
+- Create a `package.json` with the shared Redbox dependency contract
+- 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 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.
+
+## TypeScript Configuration
+
+Your hook project's `tsconfig.json` should extend the shared configuration:
+
+```json
+{
+  "extends": "@researchdatabox/redbox-dev-tools/config/tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "typeRoots": ["node_modules/@types"]
+  },
+  "include": ["src/**/*.ts", "src/**/*.d.ts"]
+}
+```
+
+**Note:** Shared runtime path injection for packages such as `rxjs`, `axios`, `lodash`, and `@researchdatabox/sails-ng-common` is handled by the `run-hook-tsc` and `run-hook-mocha` entrypoints, not by hard-coded hook-local `paths` blocks.
+
+## Compiling TypeScript
+
+Compile your TypeScript code using the toolchain provided by dev tools:
+
+```bash
+node ./node_modules/@researchdatabox/redbox-dev-tools/bin/run-hook-tsc.js -p tsconfig.json
+```
+
+Or add it to your `package.json` scripts:
+
+```json
+{
+  "scripts": {
+    "compile": "node ./node_modules/@researchdatabox/redbox-dev-tools/bin/run-hook-tsc.js -p tsconfig.json"
+  }
+}
+```
+
+Then run:
+
+```bash
+npm run compile
+```
+
+## Archetype Starter Files
+
+```typescript
+import { defineRedboxHook } from '@researchdatabox/redbox-core';
+
+const hook = defineRedboxHook({
+  registerRedboxControllers() {
+    return require('./api/controllers').ControllerExports;
+  },
+  registerRedboxServices() {
+    return require('./api/services').ServiceExports;
+  }
+});
+
+module.exports = hook;
+```
+
+## Shared Dependency Contract
+
+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
+
+Do not directly declare shared Redbox runtime or toolchain packages in a hook if they are already supplied by the core or dev-tools contract. That includes `axios`, `rxjs`, `lodash`, `mocha`, `chai`, `ts-node`, and `typescript`.
+
+`redbox-dev-tools` directly provides the shared hook authoring toolchain:
+
+- `typescript`
+- `ts-node`
+- `mocha`
+- `chai`
+- `@types/node`
+- `@types/mocha`
+- `@types/chai`
+- `@types/lodash`
+
+For hook tests and authoring utilities, `redbox-dev-tools` also exposes shared resolution helpers via `@researchdatabox/redbox-dev-tools/testing` and `@researchdatabox/redbox-dev-tools/runtime-resolver`. These are for development-time use only. Hook runtime code should continue to import normal runtime packages such as `axios` and `rxjs` directly and rely on the Redbox host contract to provide them. The shared TypeScript config prefers resolving those runtime modules from the installed `@researchdatabox/redbox-core` dependency tree, and only falls back to the `redbox-dev-tools` install when package manager flattening hoists them there.
+
+`@researchdatabox/redbox-core` is the runtime compatibility contract for hooks. It supplies the approved shared runtime dependency surface that hook authors may rely on implicitly, including `axios`, `rxjs`, and `lodash`.
+
+## Versioning
+
+This package is versioned to match the ReDBox core release it supports. For example, version `4.5.1` is compatible with ReDBox Portal version `4.5.1`.
+
+## CLI Commands
+
+### `init`
+
+Initialize a new ReDBox hook project from the standard archetype.
+
+```bash
+npx @researchdatabox/redbox-dev-tools init redbox-hook-my-client
+```
+
+Template variants are selected with `--template`:
+
+```bash
+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.
+
+```bash
+npx @researchdatabox/redbox-dev-tools check
+```
+
+### `migrate-hook-dependencies`
+
+Rewrite the current hook `package.json` to the minimal shared dependency contract.
+
+```bash
+npx @researchdatabox/redbox-dev-tools migrate-hook-dependencies
+```
+
+### `install-skills`
+
+Install the bundled agent skills using the `vercel-labs/skills` CLI. Bundled agent skills are curated prompt packs that teach supported agents how to work with ReDBox conventions, file layouts, and workflows. Install them to enable consistent, repo-aware assistance from your agent.
+
+Prerequisites
+
+- Install the external Skills CLI: `npx @vercel/skills --help` (or follow the install instructions in the Skills docs).
+- Authenticate if required by your agent runtime (some agents prompt for login on first run).
+
+Usage
+
+- `-a <agent>`: Target agent runtime (for example `claude-code`).
+- `--skill <pattern>`: Skill name or glob pattern (for example `redbox-*` or `*`).
+- Skills are optional but recommended for consistent guidance and guardrails.
+
+This will:
+
+- Copy the bundled skill definitions from this package into the Skills CLI workspace.
+- Register the skills for the specified agent runtime.
+- Make the skills available for subsequent agent sessions.
+
+```bash
+npx @researchdatabox/redbox-dev-tools install-skills -a claude-code --skill 'redbox-*'
+```
+
+For advanced options, see the `vercel-labs/skills` documentation: https://github.com/vercel-labs/skills
+
+### `migrate-form-config`
+
+Migrate a legacy v4 JavaScript form config to the v5 TypeScript form framework format.
+
+```bash
+npx @researchdatabox/redbox-dev-tools migrate-form-config \
+  --input /path/to/legacy-form.js \
+  --output /path/to/migrated-form.ts
+```
+
+### `generate form-component`
+
+Generate end-to-end scaffold for a new form component in Angular and `sails-ng-common`.
+
+```bash
+npx @researchdatabox/redbox-dev-tools generate form-component my-widget --app form
+```
+
+Optional Angular service scaffold:
+
+```bash
+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.
 
-```$ npm install @researchdatabox/redbox-dev-tools```
+```bash
+npx @researchdatabox/redbox-dev-tools help
+```
 
-## Usage
+### `completion`
 
-```$ redbox-dev-tools <command> <options>```
+Output shell completion scripts for `bash`, `zsh`, `fish`, and `powershell`.
 
-### Available Commands
+```bash
+npx @researchdatabox/redbox-dev-tools completion <shell>
+```
 
-**init**   Initialises a hook code project ready for development
+Install examples:
 
-**help**   Shows this help message or help for a specific command 
+```bash
+# bash
+npx @researchdatabox/redbox-dev-tools completion bash > ~/.local/share/bash-completion/completions/redbox-dev-tools
 
+# zsh
+mkdir -p ~/.zsh/completions
+npx @researchdatabox/redbox-dev-tools completion zsh > ~/.zsh/completions/_redbox-dev-tools
+# then ensure your ~/.zshrc includes:
+# fpath=(~/.zsh/completions $fpath)
+# autoload -U compinit && compinit
 
-## Commands
+# fish
+npx @researchdatabox/redbox-dev-tools completion fish > ~/.config/fish/completions/redbox-dev-tools.fish
 
-### Initialise Hook Code Project
+# powershell
+npx @researchdatabox/redbox-dev-tools completion powershell > ~/.config/powershell/redbox-dev-tools-completion.ps1
+# then source it from your PowerShell profile
+```
 
-#### Usage
-```$ redbox-dev-tools init -p <hook name>```
+## Contributing
 
-#### Flags
+See the main [ReDBox Portal repository](https://github.com/redbox-mint/redbox-portal) for contribution guidelines.
 
-**-p**, **--packageName** <u>name</u>  The NPM package name for the sails hook.
+## License
 
+ISC

package/bin/cli.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+require('../dist/cli.js');

package/bin/run-hook-mocha.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+require('../dist/bin/run-hook-mocha.js');

package/bin/run-hook-tsc.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+require('../dist/bin/run-hook-tsc.js');

package/bin/wrapper-webpack.js

@@ -0,0 +1,168 @@
+// This file is a helper for dev only. It makes it easier to run webpack when parts of the mono repo are in different stages of being built. Refer to the redbox-core webpack.ts for how the hook runs webpack
+const path = require('path');
+const { createRequire } = require('module');
+
+const requireFromHere = createRequire(__filename);
+let redboxCore;
+
+const getRedboxCore = () => {
+  if (redboxCore !== undefined) {
+    return redboxCore;
+  }
+
+  try {
+    redboxCore = require('@researchdatabox/redbox-core');
+  } catch (e) {
+    redboxCore = null;
+  }
+
+  return redboxCore;
+};
+
+const ensureTsNode = () => {
+  try {
+    require('ts-node/register/transpile-only');
+    return true;
+  } catch (e) {
+    return false;
+  }
+};
+
+let defineWebpackHook;
+if (!defineWebpackHook) {
+  try {
+    defineWebpackHook = require('@researchdatabox/redbox-core/dist/hooks/webpack').defineWebpackHook;
+  } catch (e) {}
+}
+if (!defineWebpackHook && ensureTsNode()) {
+  try {
+    defineWebpackHook = requireFromHere('@researchdatabox/redbox-core/src/hooks/webpack.ts').defineWebpackHook;
+  } catch (e) {}
+}
+if (!defineWebpackHook) {
+  const core = getRedboxCore();
+  defineWebpackHook = core && (core.defineWebpackHook || (core.default && core.default.defineWebpackHook));
+}
+
+// Resolve webpack config: prefer exported `Config.webpack.config`, fall back to repo `config/webpack.js`.
+let webpackConfig = [];
+try {
+  // prefer repo config file
+  const repoWebpack = require(path.resolve(process.cwd(), 'config/webpack'));
+  if (repoWebpack && repoWebpack.webpack) {
+    webpackConfig = repoWebpack.webpack.config ? repoWebpack.webpack.config : repoWebpack.webpack;
+  } else {
+    webpackConfig = repoWebpack && repoWebpack.config ? repoWebpack.config : repoWebpack;
+  }
+} catch (e) {
+  // ignore
+}
+if (!webpackConfig || (Array.isArray(webpackConfig) && webpackConfig.length === 0)) {
+  try {
+    const distWebpack = require('@researchdatabox/redbox-core/dist/config/webpack.config');
+    webpackConfig = distWebpack && distWebpack.webpack ? distWebpack.webpack.config : distWebpack.config || distWebpack;
+  } catch (e) {}
+}
+if (!webpackConfig || (Array.isArray(webpackConfig) && webpackConfig.length === 0)) {
+  if (ensureTsNode()) {
+    try {
+      const srcWebpack = requireFromHere('@researchdatabox/redbox-core/src/config/webpack.config.ts');
+      webpackConfig = srcWebpack && srcWebpack.webpack ? srcWebpack.webpack.config : srcWebpack.config || srcWebpack;
+    } catch (e) {}
+  }
+}
+if (!webpackConfig || (Array.isArray(webpackConfig) && webpackConfig.length === 0)) {
+  try {
+    const core = getRedboxCore();
+    const Config = core && (core.Config || (core.default && core.default.Config));
+    if (Config && Config.webpack && Config.webpack.config) {
+      webpackConfig = Config.webpack.config;
+    }
+  } catch (e) {
+    // ignore
+  }
+}
+
+sails = {
+  config: {
+    webpack: {
+      config: webpackConfig,
+    },
+  },
+  log: {
+    info: function (msg, data = null) {
+      console.info(msg, data);
+    },
+    warn: function (msg, data = null) {
+      console.warn(msg, data);
+    },
+    error: function (msg, data = null) {
+      console.error(msg, data);
+    },
+  },
+};
+async function main() {
+  if (!defineWebpackHook) {
+    console.warn('defineWebpackHook not available from @researchdatabox/redbox-core; running webpack directly');
+    // Fallback: run webpack directly using resolved config
+    const webpack = require('webpack');
+
+    if (!sails.config.webpack) {
+      sails.log.warn('sails-hook-webpack: No Webpack options have been defined.');
+      return;
+    }
+
+    if (
+      !sails.config.webpack.config ||
+      (Array.isArray(sails.config.webpack.config) && sails.config.webpack.config.length === 0)
+    ) {
+      sails.log.warn('sails-hook-webpack: Configure your config/webpack.js file.');
+      return;
+    }
+
+    if (process.env.NODE_ENV !== 'docker' || process.env.WEBPACK_SKIP === 'true') {
+      sails.log.warn(`sails-hook-webpack: Configured to skip webpack.`);
+      return;
+    }
+
+    if (process.env.WEBPACK_CSS_MINI === 'true') {
+      try {
+        sails.config.webpack.config[0].optimization.minimize = true;
+        sails.log.info(`Webpack wrapper is configured for CSS minimization.`);
+      } catch (e) {}
+    }
+
+    const compiler = webpack(sails.config.webpack.config);
+
+    const logCompileInfo = (err, stats) => {
+      if (err) {
+        sails.log.error('sails-hook-webpack: Build error: \n\n', err);
+      }
+      try {
+        sails.log[stats.hasErrors() ? 'error' : 'info'](
+          `sails-hook-webpack:\n${stats.toString({ colors: true, chunks: true })}`
+        );
+      } catch (e) {}
+    };
+
+    let called = false;
+    const compileCallback = (err, stats) => {
+      logCompileInfo(err, stats);
+      if (called) return;
+      called = true;
+      if (err || (stats && stats.hasErrors && stats.hasErrors())) {
+        console.error(err || stats.toString());
+        throw new Error('sails-hook-webpack failed');
+      }
+      console.log('Webpack wrapper done!');
+    };
+
+    compiler.run(compileCallback);
+    return;
+  }
+  await defineWebpackHook(sails).initialize(() => {
+    console.log('Webpack wrapper done!');
+  });
+}
+
+main();

package/config/tsconfig.base.json

@@ -0,0 +1,16 @@
+{
+  "extends": "@tsconfig/node24/tsconfig.json",
+  "compilerOptions": {
+    "target": "ES2024",
+    "lib": ["ES2024"],
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "types": ["node"],
+    "inlineSourceMap": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  }
+}

package/dist/bin/run-hook-mocha.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/bin/run-hook-mocha.js

@@ -0,0 +1,49 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const module_1 = __importDefault(require("module"));
+const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
+const typescript_1 = __importDefault(require("typescript"));
+const hook_tsconfig_1 = require("../utils/hook-tsconfig");
+function getResolvedCompilerOptions(projectPath) {
+    const resolvedProjectPath = path_1.default.resolve(process.cwd(), projectPath);
+    const configFile = typescript_1.default.readConfigFile(resolvedProjectPath, typescript_1.default.sys.readFile);
+    if (configFile.error) {
+        throw new Error(typescript_1.default.flattenDiagnosticMessageText(configFile.error.messageText, '\n'));
+    }
+    const parsedConfig = typescript_1.default.parseJsonConfigFileContent(configFile.config, typescript_1.default.sys, path_1.default.dirname(resolvedProjectPath), undefined, resolvedProjectPath);
+    if (parsedConfig.errors.length > 0) {
+        throw new Error(typescript_1.default.flattenDiagnosticMessageText(parsedConfig.errors[0].messageText, '\n'));
+    }
+    const convertedConfig = typescript_1.default.convertToTSConfig(parsedConfig, resolvedProjectPath, typescript_1.default.sys);
+    return convertedConfig.compilerOptions ?? {};
+}
+const redboxCorePackageJson = require.resolve('@researchdatabox/redbox-core/package.json');
+const redboxCoreDir = path_1.default.dirname(redboxCorePackageJson);
+const workspaceNodeModules = path_1.default.resolve(redboxCoreDir, '..', '..', 'node_modules');
+const coreNodeModules = path_1.default.join(redboxCoreDir, 'node_modules');
+const existingNodePath = process.env.NODE_PATH ? process.env.NODE_PATH.split(path_1.default.delimiter) : [];
+const tsNodeProject = process.env.TS_NODE_PROJECT ?? 'tsconfig.json';
+const existingCompilerOptions = process.env.TS_NODE_COMPILER_OPTIONS
+    ? JSON.parse(process.env.TS_NODE_COMPILER_OPTIONS)
+    : {};
+const resolvedCompilerOptions = getResolvedCompilerOptions(tsNodeProject);
+const hookCompilerOptions = (0, hook_tsconfig_1.createHookCompilerOptions)(tsNodeProject);
+process.env.NODE_PATH = [workspaceNodeModules, coreNodeModules, ...existingNodePath]
+    .filter((value, index, values) => value && values.indexOf(value) === index)
+    .join(path_1.default.delimiter);
+process.env.TS_NODE_SKIP_PROJECT = 'true';
+process.env.TS_NODE_COMPILER_OPTIONS = JSON.stringify({
+    ...resolvedCompilerOptions,
+    ...existingCompilerOptions,
+    ...hookCompilerOptions,
+});
+module_1.default._initPaths();
+const result = (0, child_process_1.spawnSync)(process.execPath, [require.resolve('mocha/bin/mocha.js'), ...process.argv.slice(2)], {
+    stdio: 'inherit',
+    env: process.env,
+});
+process.exit(result.status ?? 1);

package/dist/bin/run-hook-tsc.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/bin/run-hook-tsc.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const child_process_1 = require("child_process");
+const hook_tsconfig_1 = require("../utils/hook-tsconfig");
+const args = [...process.argv.slice(2)];
+const projectArgIndex = args.findIndex(arg => arg === '-p' || arg === '--project');
+const projectPath = projectArgIndex >= 0 ? args[projectArgIndex + 1] : 'tsconfig.json';
+const tempTsconfigPath = (0, hook_tsconfig_1.createHookTsConfig)(projectPath ?? 'tsconfig.json');
+if (projectArgIndex >= 0) {
+    args.splice(projectArgIndex, 2, '-p', tempTsconfigPath);
+}
+else {
+    args.unshift('-p', tempTsconfigPath);
+}
+const result = (0, child_process_1.spawnSync)(process.execPath, [require.resolve('typescript/bin/tsc'), ...args], {
+    stdio: 'inherit',
+});
+(0, hook_tsconfig_1.cleanupHookTsConfig)(tempTsconfigPath);
+process.exit(result.status ?? 1);

package/dist/cli-parsers.d.ts

@@ -0,0 +1,9 @@
+import { RouteMapping } from './generators/controller';
+import { ModelAttribute, ModelAssociation } from './generators/model';
+import { NavigationMapping, LanguageDefaultEntry } from './utils/config-helper';
+export declare function parseAttributes(val: string): ModelAttribute[];
+export declare function parseRoutes(val: string): RouteMapping[];
+export declare function parseNavMappings(val: string): NavigationMapping[];
+export declare function parseLanguageDefaults(val: string): LanguageDefaultEntry[];
+export declare function parseBelongsTo(val: string): ModelAssociation[];
+export declare function parseHasMany(val: string): ModelAssociation[];