@mimik/be-project-builder 1.0.0

package/lib/configFiles.js

@@ -0,0 +1,90 @@
+/* eslint-disable no-magic-numbers */
+import { networkInterfaces } from 'os';
+
+let ip;
+
+Object.keys(networkInterfaces()).forEach(group => networkInterfaces()[group].forEach((interf) => {
+  if (interf.family === 'IPv4' && !interf.internal) [ip] = interf.cidr.split('/');
+}));
+const mST = [
+  { key: 'basePath', env: 'CLI_MST_BASE_PATH', message: 'mST BasePath', initial: '/mST/v1' },
+  { key: 'protocol', env: 'CLI_MST_PROTOCOL', message: 'mST Protocol', initial: 'http:' },
+  { key: 'domainName', env: 'CLI_MST_DOMAIN_NAME', message: `mST DomainName (local IP address: ${ip})`, initial: ip || 'localhost' },
+  { key: 'port', env: 'CLI_MST_PORT', message: 'MST Port', type: 'number', initial: 8025 },
+  { key: 'passphrase', env: 'CLI_MST_PASSPHRASE', type: 'invisible', message: 'mST Passphrase (blank = null)', format: val => val === ' ' ? null : val },
+  { key: 'admin.clientId', env: 'CLI_MST_ADMIN_CLIENT_ID', message: 'mST Admin Client ID', initial: '11111111-2222-3333-4444-555555555555' },
+  { key: 'admin.clientSecret', env: 'CLI_MST_ADMIN_CLIENT_SECRET', type: 'invisible', message: 'mST Admin Client Secret (blank = null)', initial: 'a-secret-for-mST', format: val => val === ' ' ? null : val },
+];
+
+const mIT = [
+  { key: 'basePath', env: 'CLI_MIT_BASE_PATH', message: 'mIT BasePath', initial: 'mIT/v1' },
+  { key: 'protocol', env: 'CLI_MIT_PROTOCOL', message: 'mIT Protocol', initial: 'http:' },
+  { key: 'domainName', env: 'CLI_MIT_DOMAIN_NAME', message: 'mIT DomainName', initial: 'localhost' },
+  { key: 'port', env: 'CLI_MIT_PORT', message: 'mIT Port', type: 'number', initial: 8050 },
+];
+
+const mID = [
+  { key: 'basePath', env: 'CLI_MID_BASE_PATH', message: 'mID BasePath', initial: 'mID/v1' },
+  { key: 'protocol', env: 'CLI_MID_PROTOCOL', message: 'mID Protocol', initial: 'http:' },
+  { key: 'domainName', env: 'CLI_MID_DOMAIN_NAME', message: 'mID DomainName', initial: 'localhost' },
+  { key: 'port', env: 'CLI_MID_PORT', message: 'mID Port', type: 'number', initial: 8015 },
+  { key: 'implicit.key', env: 'CLI_MID_IMPLICIT_KEY', type: 'invisible', message: 'mID Implicit Key', initial: 'a-secret-key-for-implicit' },
+  { key: 'implicit.audience', env: 'CLI_MID_IMPLICIT_AUDIENCE', message: 'mID Implicit Audience', initial: 'https://mimik' },
+  { key: 'admin.externalId', env: 'CLI_MID_ADMIN_EXT_ID', message: 'mID Admin External ID', initial: 'admin-test-local-mID' },
+];
+
+const location = [
+  { key: 'url', env: 'CLI_LOCATION_URL', message: 'Location Provider URL', initial: 'http://pro.ip-api.com/json' },
+  { key: 'key', env: 'CLI_LOCATION_KEY', type: 'invisible', message: 'Location Provider Key (blank = null)', format: val => val === ' ' ? null : val },
+];
+
+const keyBitbucket = [
+  { key: 'bitbucket.username', env: 'CLI_BITBUCKET_USERNAME', message: 'Bitbucket username' },
+  { key: 'bitbucket.password', env: 'CLI_BITBUCKET_PASSWORD', type: 'invisible', message: 'Bitbucket password (blank = null)', format: val => val === ' ' ? null : val },
+];
+
+const keySwagger = [
+  { key: 'swaggerhub', env: 'CLI_SWAGGERHUB', type: 'invisible', message: 'Swaggerhub apikey (blank = null)', format: val => val === ' ' ? null : val },
+];
+
+const s3Log = [
+  { key: 'bucketname', env: 'CLI_S3LOG_BUCKET_NAME', message: 'S3 bucket name', initial: 'bucket-tmp-mimikdev-com' },
+  { key: 'region', env: 'CLI_S3LOG_REGION', message: 'Region of the S3 bucket', initial: 'us-west-2' },
+  { key: 'accessKeyId', env: 'CLI_S3LOG_ACCESS_KEY_ID', type: 'invisible', message: 'Access key id of the S3 bucket (blank = null)', format: val => val === ' ' ? null : val },
+  { key: 'secretAccessKey', env: 'CLI_S3LOG_SECRET_ACCESS_KEY', type: 'invisible', message: 'Secret access key of the S3 bucket (blank = null)', format: val => val === ' ' ? null : val },
+  { key: 'maxEvents', env: 'CLI_S3LOG_MAX_EVENTS', message: 'Max logs accumulated before flushing', type: 'number', initial: 1000 },
+  { key: 'timeout', env: 'CLI_S3LOG_TIMEOUT', message: 'Maximum time before flushing (in minute)', type: 'number', initial: 5 },
+  { key: 'maxSize', env: 'CLI_S3LOG_MAX_SIZE', message: 'Maximum size of the accumulated logs before flushing (in MByte)', type: 'number', initial: 5 },
+];
+
+const kinesisLog = [
+  { key: 'streamNameInfo', env: 'CLI_KINESIS_STREAM_NAME_INFO', message: 'Name of the Kinesis stream for info level logs', initial: 'kinesis-stream-tmp-mimikdev-com' },
+  { key: 'streamNameError', env: 'CLI_KINESIS_STREAM_NAME_ERROR', message: 'Name of the Kinesis stream for error level logs', initial: 'kinesis-stream-tmp-mimikdev-com' },
+  { key: 'streamNameOther', env: 'CLI_KINESIS_STREAM_NAME_OTHER', message: 'Name of the Kinesis stream for any other level logs', initial: 'kinesis-stream-tmp-mimikdev-com' },
+  { key: 'region', env: 'CLI_KINESIS_REGION', message: 'Region of the Kinesis stream', initial: 'us-west-2' },
+  { key: 'accessKeyId', env: 'CLI_KINESIS_ACCESS_KEY_ID', type: 'invisible', message: 'Access key id of the Kinesis stream (blank = null)', format: val => val === ' ' ? null : val },
+  { key: 'secretAccessKey', env: 'CLI_KINESIS_SECRET_ACCESS_KEY', type: 'invisible', message: 'Secret access key of the Kinesis stream (blank = null)', format: val => val === ' ' ? null : val },
+  { key: 'maxEvents', env: 'CLI_KINESIS_MAX_EVENTS', message: 'Maximum logs accumulated before flushing', type: 'number', initial: 1000 },
+  { key: 'timeout', env: 'CLI_KINESIS_TIMEOUT', message: 'Maximum time before flushing (in minute)', type: 'number', initial: 5 },
+  { key: 'maxSize', env: 'CLI_KINESIS_MAX_SIZE', message: 'Maximum size of the accumulated logs before flushing (in MByte)', type: 'number', initial: 5 },
+  { key: 'maxRetries', env: 'CLI_KINESIS_MAX_RETRIES', message: 'Maximum retries to connect to Kinesis', type: 'number', initial: 4 },
+  { key: 'httpOptions.socketTimeout', env: 'CLI_KINESIS_HTTP_OPTIONS_SOCKET_TIMEOUT', message: 'Socket timeout for the HTTP handler (in millisecond)', type: 'number', initial: 5000 },
+  { key: 'httpOptions.connectionTimeout', env: 'CLI_KINESIS_HTTP_OPTIONS_CONNECTION_TIMEOUT', message: 'Connection timeout for the HTTP handler (in millisecond)', type: 'number', initial: 5000 },
+];
+
+const sumoLog = [
+  { key: 'default.url', env: 'CLI_SUMOLOGIC_DEFAULT_URL', message: 'Sumologic default URL', initial: 'https://endpoint2.collection.us2.sumologic.com/receiver/v1/http/' },
+  { key: 'default.code', env: 'CLI_SUMOLOGIC_DEFAULT_CODE', type: 'invisible', message: 'Sumologic default code (blank = null)', format: val => val === ' ' ? null : val },
+];
+
+export default {
+  mST,
+  mIT,
+  mID,
+  location,
+  keyBitbucket,
+  keySwagger,
+  s3Log,
+  kinesisLog,
+  sumoLog,
+};

package/lib/helpers.js

@@ -0,0 +1,311 @@
+/* eslint default-case: 'off' */
+import { access, stat } from 'fs/promises';
+import { constants, statSync } from 'node:fs';
+import { Base64 } from 'js-base64';
+import Mustache from 'mustache';
+import { PROJECT_DIR } from './common.js';
+import SwaggerClient from 'swagger-client';
+import color from 'ansi-colors';
+import configFiles from './configFiles.js';
+import { configureFile } from './buildfile.js';
+import { getFileByNameSync } from './readFileSync.js';
+import { join } from 'node:path';
+import { load } from 'js-yaml';
+import { parse } from 'comment-json';
+import prompts from 'prompts';
+import { rpRetry } from '@mimik/request-retry';
+
+const API_PROVIDER_BITBUCKET = 'https://api.bitbucket.org/2.0/repositories';
+const API_PROVIDER_SWAGGERHUB = 'https://api.swaggerhub.com/apis';
+const API_SOURCE = '/src';
+
+const { render } = Mustache;
+
+const swaggerOptions = spec => ({
+  spec,
+  allowMetaPatches: false,
+  skipNormalization: true,
+  mode: 'strict',
+});
+
+export const isDirectorySync = (path) => {
+  try {
+    return statSync(path).isDirectory();
+  }
+  catch {
+    return false;
+  }
+};
+
+const opts = {
+  method: 'GET',
+  headers: {},
+  retry: {
+    logLevel: {
+      response: 'info',
+      request: 'info',
+    },
+  },
+};
+
+export const createAPI = async (homeDir, projectDir, service) => {
+  const API = {};
+  let name;
+  let version;
+  let account = 'mimiktech';
+  let provider = 'bitbucket';
+  let content;
+  let destination;
+  const { exist } = await prompts({ type: 'confirm', name: 'exist', message: 'API exists?' });
+
+  API.exist = exist;
+  if (!API.exist) return API;
+  const { location } = await prompts({
+    type: 'select',
+    name: 'location',
+    message: 'Location of the API',
+    choices: [
+      { title: 'File', value: 'filename' },
+      { title: 'Bitbucket', value: 'bitbucket' },
+      { title: 'Swaggerhub', value: 'swaggerhub' },
+    ],
+  });
+  switch (location) {
+    case 'filename': {
+      ({ name } = await prompts({ type: 'text', name: 'name', message: 'API filename' }));
+      content = getFileByNameSync(homeDir, name);
+      ({ version } = content.info);
+      destination = `${account}_swagger-${service.name}_${version}_swagger.json`;
+      break;
+    }
+    case 'bitbucket': {
+      name = `swagger-${service.name}`;
+      ({ version } = await prompts({ type: 'text', name: 'version', message: 'API version', initial: null }));
+      ({ account } = await prompts({ type: 'text', name: 'account', message: 'API account', initial: 'mimiktech' }));
+      const key = await configureFile(join(projectDir, 'key.json'), configFiles.keyBitbucket, { nonInteractive: false, jsonParse: parse });
+      const username = key.values['bitbucket.username'];
+      const password = key.values['bitbucket.password'];
+
+      if (!username || !password) throw new Error('missing values to log to bitbucket');
+      opts.headers.Authorization = `Basic ${Base64.encode(`${username}:${password}`)}`;
+      opts.url = `${API_PROVIDER_BITBUCKET}/${account}/${name}${API_SOURCE}/${version}/swagger.yml`;
+      const result = await rpRetry(opts);
+      const resultJSON = load(result);
+      const apiDefinitionResult = await SwaggerClient.resolve(swaggerOptions(resultJSON));
+
+      if (apiDefinitionResult.errors.length !== 0) throw new Error('errors while resolving definition');
+      content = apiDefinitionResult.spec;
+      destination = `${account}_${name}_${version}_swagger.json`;
+      break;
+    }
+    case 'swaggerhub': {
+      ({ version } = await prompts({ type: 'text', name: 'version', message: 'API version', initial: null }));
+      ({ account } = await prompts({ type: 'text', name: 'account', message: 'API account', initial: 'mimik' }));
+      const key = await configureFile(join(projectDir, 'key.json'), configFiles.keySwagger, { nonInteractive: false, jsonParse: parse });
+      const apiKey = key.values.swaggerhub;
+
+      opts.url = `${API_PROVIDER_SWAGGERHUB}/${account}/${service.type}/${version}?resolved=true`;
+      if (apiKey) opts.headers.Authorization = apiKey;
+      content = await rpRetry(opts);
+      destination = `${account}_swagger-${service.name}_${version}_swagger.json`;
+      provider = location;
+      break;
+    }
+  }
+  Object.assign(API, { location, name, version, account, provider, content, destination });
+  return API;
+};
+
+export const createNewService = async (dir, homeDir, projectDir) => {
+  const { serviceName } = await prompts({ type: 'text', name: 'serviceName', message: 'Name of the service' });
+  if (!serviceName) return null;
+  const service = { name: serviceName };
+
+  if (isDirectorySync(join(projectDir, serviceName))) {
+    service.newService = false;
+    const pack = getFileByNameSync(join(projectDir, serviceName), 'package.json', { throwIfMissing: false });
+
+    if (pack) {
+      service.name = pack.name;
+      service.description = pack.description;
+      service.version = pack.version;
+      service.type = pack.mimik?.type;
+      service.APIVersion = pack.swaggerFile?.version;
+      service.APIAccount = pack.swaggerFile?.account;
+      service.APIProvider = pack.swaggerFile?.provider;
+    }
+    if (isDirectorySync(join(projectDir, serviceName, 'local'))) {
+      const startExample = getFileByNameSync(join(projectDir, serviceName, 'local'), 'start-example.json', { throwIfMissing: false, jsonParse: parse });
+
+      if (startExample) {
+        service.port = startExample.SERVER_PORT;
+        service.protocol = startExample.SERVER_PUBLIC_PROTOCOL;
+        service.domainName = startExample.SERVER_PUBLIC_DOMAIN_NAME;
+      }
+    }
+    return service;
+  }
+  service.newService = true;
+  const { description } = await prompts({ type: 'text', name: 'description', message: 'Description of the service', initial: service.description || null });
+  const { type } = await prompts({ type: 'text', name: 'type', message: 'Type of the service in mST', initial: service.type || null });
+  const { port } = await prompts({ type: 'number', name: 'port', message: 'Service port', initial: service.port || null });
+  const { protocol } = await prompts({ type: 'text', name: 'protocol', message: 'Service public protocol', initial: service.protocol || 'https:' });
+  const { domainName } = await prompts({ type: 'text', name: 'domainName', message: 'Service public domain name (blank = null)', initial: service.domainName || null, format: val => val === ' ' ? null : val });
+
+  Object.assign(service, { name: serviceName, description, type, port, domainName, protocol });
+  return service;
+};
+
+export const createService = async (dir, homeDir, projectDir) => {
+  const { isNewService } = await prompts({ type: 'confirm', name: 'isNewService', message: 'creating or updating a service ?' });
+  const newService = { isNewService };
+  if (isNewService) {
+    const { name } = await prompts({ type: 'text', name: 'name', message: 'name of the service' });
+    const service = {};
+
+    if (isDirectorySync(join(projectDir, name))) {
+      newService.isExisting = true;
+      const pack = getFileByNameSync(join(projectDir, name), 'package.json', { throwIfMissing: false });
+
+      if (pack) {
+        service.name = pack.name;
+        service.description = pack.description;
+        service.version = pack.version;
+        service.type = pack.mimik?.type;
+        service.APIVersion = pack.swaggerFile?.version;
+        service.APIAccount = pack.swaggerFile?.account;
+      }
+      if (isDirectorySync(join(projectDir, name, 'local'))) {
+        const startExample = getFileByNameSync(join(projectDir, name, 'local'), 'start-example.json', { throwIfMissing: false, jsonParse: parse });
+
+        if (startExample) {
+          service.port = startExample.SERVER_PORT;
+          service.protocol = startExample.SERVER_PUBLIC_PROTOCOL;
+          service.domainName = startExample.SERVER_PUBLIC_DOMAIN_NAME;
+        }
+      }
+    }
+    const { description } = await prompts({ type: 'text', name: 'description', message: 'description of the service', initial: service.description || null });
+    const { type } = await prompts({ type: 'text', name: 'type', message: 'type of the service in mST', initial: service.type || null });
+    const { port } = await prompts({ type: 'number', name: 'port', message: 'service port', initial: service.port || null });
+    const { protocol } = await prompts({ type: 'text', name: 'protocol', message: 'service public protocol', initial: service.protocol || 'https:' });
+    const { domainName } = await prompts({ type: 'text', name: 'domainName', message: 'service public domain name (blank = null)', initial: service.domainName || null, format: val => val === ' ' ? null : val });
+    Object.assign(newService, { name, description, type, port, domainName, protocol, old: service });
+  }
+  return newService;
+};
+
+export const createCustomerConfig = async (dir, homeDir, projectDir) => {
+  const existingConfig = getFileByNameSync(projectDir, 'customerConfig.json', { throwIfMissing: false });
+  const configName = join(dir, 'customerConfig.json');
+  let configContent = existingConfig;
+  let customerName;
+  let account;
+  let dirName;
+  let confirm = true;
+
+  if (existingConfig) {
+    ({ confirm } = await prompts({ type: 'confirm', name: 'confirm', message: `Customer config for ${color.green.bold(existingConfig.name)} version ${color.green.bold(existingConfig.version)} already exist, overwriting?` }));
+  }
+  if (confirm) {
+    const { location } = await prompts({
+      type: 'select',
+      name: 'location',
+      message: 'Location of the customer config',
+      choices: [
+        { title: 'File', value: 'filename' },
+        { title: 'Bitbucket', value: 'bitbucket' },
+      ],
+    });
+    switch (location) {
+      case 'filename': {
+        ({ dirName } = await prompts({ type: 'text', name: 'dirName', message: 'Customer config directory', initial: PROJECT_DIR }));
+        configContent = getFileByNameSync(homeDir, join(dirName, 'customerConfig.json'));
+        break;
+      }
+      case 'bitbucket': {
+        ({ customerName } = await prompts({ type: 'text', name: 'customerName', message: 'Customer name', initial: null }));
+        ({ account } = await prompts({ type: 'text', name: 'account', message: 'API account', initial: 'mimiktech' }));
+        const key = await configureFile(join(projectDir, 'key.json'), configFiles.keyBitbucket, { nonInteractive: false, jsonParse: parse });
+        const username = key.values['bitbucket.username'];
+        const password = key.values['bitbucket.password'];
+
+        if (!username || !password) throw new Error('missing values to log to bitbucket');
+        try {
+          const requestOpts = {
+            ...opts,
+            headers: { ...opts.headers, Authorization: `Basic ${Base64.encode(`${username}:${password}`)}` },
+            url: `${API_PROVIDER_BITBUCKET}/${account}/${customerName}-configs/${API_SOURCE}/develop/mst-config.json`,
+          };
+          configContent = await rpRetry(requestOpts);
+        }
+        catch {
+          const requestOpts = {
+            ...opts,
+            headers: { ...opts.headers, Authorization: `Basic ${Base64.encode(`${username}:${password}`)}` },
+            url: `${API_PROVIDER_BITBUCKET}/${account}/${customerName}-configs/${API_SOURCE}/develop/template-mst-config.json`,
+          };
+          configContent = await rpRetry(requestOpts);
+          configContent.name = customerName;
+        }
+        break;
+      }
+    }
+  };
+  return { configName, configContent };
+};
+
+const RESERVED = new Set([
+  'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger', 'default', 'delete', 'do', 'else',
+  'export', 'extends', 'finally', 'for', 'function', 'if', 'import', 'in', 'instanceof', 'new', 'return',
+  'super', 'switch', 'this', 'throw', 'try', 'typeof', 'var', 'void', 'while', 'with', 'yield', 'enum',
+  'await', 'implements', 'package', 'protected', 'static', 'interface', 'private', 'public', 'let',
+]);
+const isValidIdentifier = str => /^[A-Za-z_$][A-Za-z0-9_$]*$/u.test(str) && !RESERVED.has(str);
+
+const toTemplateData = (functionNames) => {
+  const cleaned = functionNames.map((na) => {
+    const name = String(na).trim();
+    if (!isValidIdentifier(name)) throw new Error(`Invalid function name: "${name}"`);
+    return name;
+  });
+  return {
+    functions: cleaned.map((name, i, arr) => ({ name, last: i === arr.length - 1 })),
+  };
+};
+
+export const getControllers = (APIContent, template) => {
+  const controllerNames = {};
+  const controllers = {};
+  const { paths } = APIContent;
+
+  Object.keys(paths).forEach((path) => {
+    Object.keys(paths[path]).forEach((op) => {
+      const controllerFile = paths[path][op]['x-swagger-router-controller'];
+
+      if (controllerFile) {
+        if (controllerNames[controllerFile]) controllerNames[controllerFile].push(paths[path][op].operationId);
+        else controllerNames[controllerFile] = [paths[path][op].operationId];
+      }
+    });
+  });
+  Object.keys(controllerNames).forEach((name) => {
+    if (controllerNames[name]) {
+      const data = toTemplateData(controllerNames[name]);
+
+      controllers[`${name}.js`] = render(template, data);
+    }
+  });
+  return controllers;
+};
+
+export const dirExists = async (dirPath) => {
+  try {
+    await access(dirPath, constants.F_OK);
+    const status = await stat(dirPath);
+    return status.isDirectory();
+  }
+  catch {
+    return false;
+  }
+};

package/lib/readFileSync.js

@@ -0,0 +1,69 @@
+import { basename, isAbsolute, parse, relative, resolve } from 'node:path';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+
+/**
+ * Return the UTF-8 content of a file by name inside baseDir (SYNC).
+ *
+ * Resolution when `name` has no extension:
+ *   1) <name>         (no extension)
+ *   2) <name>.txt
+ *   3) <name>.json
+ *   4) <name>.js
+ *
+ * If `name` has an extension, it must be one of .txt, .json, .js.
+ *
+ * @param {string} baseDir
+ * @param {string} name
+ * @param {object} [options]
+ * @param {boolean} [options.throwIfMissing=true]
+ * @param {function} [options.jsonParse=JSON.parse] - Use a this JSON parser to handle json files
+ * @returns {string|null} - file content, or null if not found and throwIfMissing=false
+ */
+export const getFileByNameSync = (baseDir, name, options = {}) => {
+  const { throwIfMissing = true, jsonParse = JSON.parse } = options;
+  if (!name) throw new Error('name is required');
+  const base = resolve(baseDir || '');
+
+  // Prevent path traversal & absolute paths
+  const sanitized = name.replace(/^[\\/]+/u, '');
+  const target = resolve(base, sanitized);
+  const rel = relative(base, target);
+
+  if (rel.startsWith('..') || isAbsolute(rel)) {
+    throw new Error(`Invalid name (path traversal): ${name}`);
+  }
+
+  const allowedExts = ['.txt', '.json', '.js'];
+  const parsed = parse(target);
+
+  // Build candidate list
+  const candidates = [];
+  let ext;
+  if (parsed.ext) {
+    ext = parsed.ext.toLowerCase();
+    if (!allowedExts.includes(ext)) {
+      throw new Error(`Unsupported extension '${ext}' (allowed: .txt, .json, .js)`);
+    }
+    candidates.push(target);
+  }
+  else {
+    candidates.push(target); // no extension
+    candidates.push(`${target}.txt`);
+    candidates.push(`${target}.json`);
+    candidates.push(`${target}.js`);
+  }
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate) && statSync(candidate).isFile()) {
+      const content = readFileSync(candidate, 'utf8');
+      if (ext === '.json') return jsonParse(content);
+      return content;
+    }
+  }
+
+  if (throwIfMissing) {
+    const tried = candidates.map(candidate => basename(candidate)).join(', ');
+    throw new Error(`File not found for "${name}" in ${base} (tried: ${tried})`);
+  }
+  return null;
+};

package/lib/scaffold.js

@@ -0,0 +1,108 @@
+import { PERM_DIR, PERM_FILE } from './common.js';
+import { access, mkdir, rm, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+
+const normalizeContent = (content) => {
+  if (content === null) return '';
+  return content;
+};
+
+/* eslint-disable no-await-in-loop */
+const createNodes = async (base, nodes, ctx) => {
+  for (const node of nodes) {
+    if (typeof node === 'string') {
+      const dirPath = join(base, node);
+      await mkdir(dirPath, { recursive: true, mode: ctx.dirMode });
+      ctx.createdDirs.push(dirPath);
+    }
+    else {
+      if (!node || typeof node !== 'object' || !node.dir) {
+        throw new Error(`Invalid plan entry: ${JSON.stringify(node)}`);
+      }
+
+      const dirPath = join(base, node.dir);
+      await mkdir(dirPath, { recursive: true, mode: ctx.dirMode });
+      ctx.createdDirs.push(dirPath);
+
+      if (Array.isArray(node.files)) {
+        for (const file of node.files) {
+          if (!file || typeof file.name !== 'string' || !file.name) {
+            throw new Error(`Invalid file entry under ${node.dir}: ${JSON.stringify(file)}`);
+          }
+          const filePath = join(dirPath, file.name);
+          await writeFile(filePath, normalizeContent(file.content), { mode: ctx.fileMode, flag: 'wx' });
+          ctx.createdFiles.push(filePath);
+        }
+      }
+
+      if (Array.isArray(node.dirs) && node.dirs.length) {
+        await createNodes(dirPath, node.dirs, ctx);
+      }
+    }
+  }
+};
+/* eslint-enable no-await-in-loop */
+
+const exists = async (node) => {
+  try {
+    await access(node);
+    return true;
+  }
+  catch { return false; }
+};
+
+/**
+ * Create a project directory with subdirectories and files.
+ *
+ * If the root directory already exists, throws an Error.
+ *
+ * @param {string} rootName - Name or path of the root directory to create.
+ * @param {Array<Object|string>} plan - Structure to create under the root.
+ *   - string: treated as a subdirectory name
+ *   - object: { dir: string, files?: Array<{name:string, content?:string|Uint8Array}>, dirs?: Array<Object|string> }
+ * @param {object} [options]
+ * @param {number} [options.dirMode=0o755] - Mode for directories
+ * @param {number} [options.fileMode=0o644] - Mode for files
+ * @param {boolean} [options.cleanupOnError=true] - Remove root if creation fails mid-way
+ * @returns {Promise<{root:string, createdDirs:string[], createdFiles:string[]}>}
+ */
+export const scaffold = async (rootName, plan, options = {}) => {
+  const dirMode = options.dirMode ?? PERM_DIR;
+  const fileMode = options.fileMode ?? PERM_FILE;
+  const cleanupOnError = options.cleanupOnError ?? true;
+
+  if (!rootName || typeof rootName !== 'string') {
+    throw new Error('rootName must be a non-empty string');
+  }
+  const root = resolve(rootName);
+
+  if (await exists(root)) {
+    throw new Error(`Directory already exists: ${root}`);
+  }
+
+  const createdDirs = [];
+  const createdFiles = [];
+
+  try {
+    // Create root
+    await mkdir(root, { recursive: false, mode: dirMode });
+    createdDirs.push(root);
+
+    // Normalize plan to array
+    const nodes = Array.isArray(plan) ? plan : [plan];
+    await createNodes(root, nodes, { dirMode, fileMode, createdDirs, createdFiles });
+
+    return { root, createdDirs, createdFiles };
+  }
+  catch (err) {
+    if (cleanupOnError) {
+      try {
+        await rm(root, { recursive: true, force: true });
+      }
+      catch {
+        // ignore cleanup errors
+      }
+    }
+    throw err;
+  }
+};

package/lib/writeFileSync.js

@@ -0,0 +1,70 @@
+import { PERM_DIR, PERM_FILE, TAB } from './common.js';
+import { dirname, extname, isAbsolute, relative, resolve } from 'node:path';
+import { mkdirSync, writeFileSync } from 'node:fs';
+
+/**
+ * Write a text file under baseDir.
+ * - Allowed extensions: (none => txt), .txt, .json, .js
+ * - Optionally throw if the file already exists.
+ *
+ * @param {string} baseDir
+ * @param {string} name                 // e.g. "welcome", "config.json", "script.js"
+ * @param {string|object} content       // objects auto-JSON stringified for .json
+ * @param {object} [options]
+ * @param {boolean} [options.throwIfExists=false] - If true, error when file exists
+ * @param {boolean} [options.createDirs=true] - Create parent dirs if missing
+ * @param {number}  [options.mode=0o644] - File permissions
+ * @param {number}  [options.jsonIndent=2] - Spaces for JSON pretty print
+ * @param {boolean} [options.newlineAtEof=true] - Ensure trailing newline
+ * @param {function} [options.JSONStringify=JSON.stringify] - Use a this JSON stringifier to handle json files
+ * @returns {string} - absolute path written
+ */
+export const writeFileByNameSync = (baseDir, name, content, options = {}) => {
+  const {
+    throwIfExists = false,
+    createDirs = true,
+    mode = PERM_FILE,
+    jsonIndent = TAB,
+    newlineAtEof = true,
+    jsonStringify = JSON.stringify,
+  } = options;
+
+  if (!baseDir || !name) throw new Error('baseDir and name are required');
+
+  // Normalize & protect against path traversal
+  const base = resolve(baseDir);
+  const sanitized = name.replace(/^[\\/]+/u, '');
+  const target = resolve(base, sanitized);
+  const rel = relative(base, target);
+  if (rel.startsWith('..') || isAbsolute(rel)) {
+    throw new Error(`Invalid name (path traversal): ${name}`);
+  }
+
+  // Validate extension
+  const ext = extname(target).toLowerCase();
+  const allowed = ['', '.txt', '.json', '.js'];
+  if (!allowed.includes(ext)) {
+    throw new Error(
+      `Unsupported extension '${ext || '(none)'}' (allowed: no ext, .txt, .json, .js)`,
+    );
+  }
+
+  // Ensure parent directories
+  if (createDirs) mkdirSync(dirname(target), { recursive: true, mode: PERM_DIR });
+
+  // Prepare content
+  let data;
+  if (ext === '.json' && typeof content !== 'string') {
+    data = jsonStringify(content, null, jsonIndent);
+  }
+  else {
+    data = String(content ?? '');
+  }
+  if (newlineAtEof && !data.endsWith('\n')) data += '\n';
+
+  // Write; 'wx' fails if file exists, 'w' overwrites
+  const flag = throwIfExists ? 'wx' : 'w';
+  writeFileSync(target, data, { encoding: 'utf8', mode, flag });
+
+  return target;
+};