@mimik/be-project-builder 1.0.0

package/README.md

@@ -0,0 +1,94 @@
+# @mimik/be-project-builder
+
+Interactive project scaffolding tool for mimik backend services. It guides you through configuring core service settings, optional logging/location configs, and (optionally) fetching Swagger definitions to generate controller stubs.
+
+## Requirements
+
+- Node.js >= 24
+
+## Install
+
+If using this in another repo, add it as a dependency and run the entrypoint. For local use:
+
+```sh
+npm install
+```
+
+## Usage
+
+Run with `npx` (no install):
+
+```sh
+npx @mimik/be-project-builder
+```
+
+Or install globally for a `be-project-builder` command:
+
+```sh
+npm install -g @mimik/be-project-builder
+```
+
+```sh
+be-project-builder
+```
+
+You can also run the tool directly with Node:
+
+```sh
+node index.js
+```
+
+You will be prompted for:
+
+- Projects directory (default: `./Projects` under your home directory)
+- Optional location/log/mST/mIT/mID config updates
+- Customer config (from file or Bitbucket)
+- Service details (name, description, type, port, public protocol/domain)
+- Optional Swagger API source (file, Bitbucket, or SwaggerHub)
+
+The tool scaffolds a new service directory with `src/`, `local/`, and `test/` folders and writes config files into the chosen Projects directory.
+
+## What it generates
+
+Typical output structure for a new service:
+
+```
+<Projects>/<service-name>/
+  package.json
+  src/
+    index.js
+    configuration/
+    controllers/
+    processors/
+    models/
+    lib/
+    api/                # only if an API definition was provided
+  local/
+    start-example.json
+    setup.js
+    scripts.js
+    unScripts.js
+    commitMsgCheck.js
+    dotFiles.js
+    testSetup.js
+    jsdoc.json
+  test/
+    normal/
+    detached/
+    src/
+    mock/
+```
+
+## Notes
+
+- API definitions can be loaded from a local file, Bitbucket, or SwaggerHub.
+- When a Swagger definition is supplied, controller stubs are generated based on `x-swagger-router-controller` and `operationId` values.
+- Config prompts write JSON/JSONC/YAML/.env files, preserving JSON comments where applicable.
+
+## Troubleshooting
+
+If you see errors fetching APIs or customer config, verify your Bitbucket/SwaggerHub credentials in the prompted `key.json` file and ensure network access.
+
+## License
+
+No license file found in this repository.

package/eslint.config.js

@@ -0,0 +1,71 @@
+import globals from 'globals';
+import importPlugin from 'eslint-plugin-import';
+import js from '@eslint/js';
+import processDoc from '@mimik/eslint-plugin-document-env';
+import stylistic from '@stylistic/eslint-plugin';
+
+const MAX_LENGTH_LINE = 180;
+const MAX_FUNCTION_PARAMETERS = 6;
+const MAX_LINES_IN_FILES = 600;
+const MAX_LINES_IN_FUNCTION = 150;
+const MAX_STATEMENTS_IN_FUNCTION = 47;
+const MIN_KEYS_IN_OBJECT = 10;
+const MAX_COMPLEXITY = 40;
+const ECMA_VERSION = 'latest';
+const MAX_DEPTH = 6;
+const ALLOWED_CONSTANTS = [0, 1, -1];
+
+export default [
+  {
+    ignores: ['mochawesome-report/**', 'node_modules/**', 'dist/**'],
+  },
+  importPlugin.flatConfigs.recommended,
+  stylistic.configs.recommended,
+  js.configs.all,
+  {
+    plugins: {
+      processDoc,
+    },
+    languageOptions: {
+      ecmaVersion: ECMA_VERSION,
+      globals: {
+        ...globals.nodeBuiltin,
+        console: 'readonly',
+        describe: 'readonly',
+        it: 'readonly',
+        require: 'readonly',
+      },
+      sourceType: 'module',
+    },
+    rules: {
+      '@stylistic/brace-style': ['warn', 'stroustrup', { allowSingleLine: true }],
+      '@stylistic/line-comment-position': ['off'],
+      '@stylistic/max-len': ['warn', MAX_LENGTH_LINE, { ignoreComments: true, ignoreStrings: true, ignoreRegExpLiterals: true }],
+      '@stylistic/semi': ['error', 'always'],
+      'capitalized-comments': ['off'],
+      'complexity': ['error', MAX_COMPLEXITY],
+      'curly': ['off'],
+      'id-length': ['error', { exceptions: ['x', 'y', 'z', 'i', 'j', 'k'] }],
+      'import/no-extraneous-dependencies': ['error', { devDependencies: true }],
+      'import/no-unresolved': ['error', { amd: true, caseSensitiveStrict: true, commonjs: true }],
+      'init-declarations': ['off'],
+      'linebreak-style': ['off'],
+      'max-depth': ['error', MAX_DEPTH],
+      'max-lines': ['warn', { max: MAX_LINES_IN_FILES, skipComments: true, skipBlankLines: true }],
+      'max-lines-per-function': ['warn', { max: MAX_LINES_IN_FUNCTION, skipComments: true, skipBlankLines: true }],
+      'max-params': ['error', MAX_FUNCTION_PARAMETERS],
+      'max-statements': ['warn', MAX_STATEMENTS_IN_FUNCTION],
+      'no-confusing-arrow': ['off'],
+      'no-inline-comments': ['off'],
+      'no-magic-numbers': ['error', { ignore: ALLOWED_CONSTANTS, enforceConst: true, detectObjects: true }],
+      'no-process-env': ['error'],
+      'no-ternary': ['off'],
+      'no-undefined': ['off'],
+      'one-var': ['error', 'never'],
+      'processDoc/validate-document-env': ['error'],
+      'quotes': ['warn', 'single'],
+      'sort-imports': ['error', { allowSeparatedGroups: true }],
+      'sort-keys': ['error', 'asc', { caseSensitive: true, minKeys: MIN_KEYS_IN_OBJECT, natural: false, allowLineSeparatedGroups: true }],
+    },
+  },
+];

package/index.js

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+/* eslint no-console: "off" */
+import { PROJECT_DIR, TAB } from './lib/common.js';
+import { createAPI, createCustomerConfig, createNewService, dirExists, getControllers } from './lib/helpers.js';
+import { dirname, join, resolve } from 'node:path';
+import { parse, stringify } from 'comment-json';
+import Mustache from 'mustache';
+import color from 'ansi-colors';
+import configFiles from './lib/configFiles.js';
+import { configureFile } from './lib/buildfile.js';
+import { fileURLToPath } from 'node:url';
+import { getFileByNameSync } from './lib/readFileSync.js';
+import { homedir } from 'node:os';
+import prompts from 'prompts';
+import { scaffold } from './lib/scaffold.js';
+import { writeFileByNameSync } from './lib/writeFileSync.js';
+
+const { render } = Mustache;
+
+const localDirectory = dirname(fileURLToPath(import.meta.url));
+const scaffoldDirectory = join(localDirectory, './scaffoldFiles');
+const homeDirectory = homedir();
+const prompt = options => prompts(options, {
+  onCancel: () => {
+    console.log(`${color.bold.green('✔')} ${color.bold.green('Canceled')}`);
+    process.exit(0);
+  },
+});
+const { directory } = await prompt({ type: 'text', name: 'directory', message: 'Projects directory', initial: PROJECT_DIR });
+const projectDirectory = resolve(homeDirectory, directory);
+
+let customerConfig;
+
+const pack = getFileByNameSync(scaffoldDirectory, 'package.json');
+const startExample = getFileByNameSync(scaffoldDirectory, 'local/start-example.json', { jsonParse: parse });
+const template = getFileByNameSync(scaffoldDirectory, 'src/mustacheController.txt');
+
+const { changeLoc } = await prompt({ type: 'confirm', name: 'changeLoc', message: 'Change location config?' });
+
+if (changeLoc) {
+  await configureFile(join(projectDirectory, 'locationConfig.json'), configFiles.location, { nonInteractive: false });
+}
+
+const { changeLogs } = await prompt({ type: 'confirm', name: 'changeLogs', message: 'Change log config?' });
+
+if (changeLogs) {
+  await configureFile(join(projectDirectory, 's3Log.json'), configFiles.s3Log, { nonInteractive: false });
+  await configureFile(join(projectDirectory, 'kinesisLog.json'), configFiles.kinesisLog, { nonInteractive: false, jsonParse: parse });
+  await configureFile(join(projectDirectory, 'sumoLog.json'), configFiles.sumoLog, { nonInteractive: false, jsonParse: parse });
+}
+
+const { changeFile } = await prompt({ type: 'confirm', name: 'changeFile', message: 'Change mST, mIT, mID config?' });
+
+if (changeFile) {
+  await configureFile(join(projectDirectory, 'mSTConfig.json'), configFiles.mST, { nonInteractive: false, jsonParse: parse });
+  await configureFile(join(projectDirectory, 'mITConfig.json'), configFiles.mIT, { nonInteractive: false, jsonParse: parse });
+  await configureFile(join(projectDirectory, 'mIDConfig.json'), configFiles.mID, { nonInteractive: false, jsonParse: parse });
+}
+try {
+  customerConfig = await createCustomerConfig(directory, homeDirectory, projectDirectory);
+
+  if (customerConfig.configContent) {
+    writeFileByNameSync(projectDirectory, 'customerConfig.json', customerConfig.configContent);
+    console.log(`${color.bold.green('✔')} ${color.bold('Customer:')} ${color.bold.green(customerConfig.configContent.name)}${color.bold(', version:')} ${color.bold.green(customerConfig.configContent.version)}`);
+  };
+}
+catch (err) { console.log(`${color.bold.red('✖')} ${color.red(err.message)} - ${color.bold.red('no customer configuration: skipping')}`); };
+
+if (!await dirExists(projectDirectory)) {
+  console.log(`${color.bold.red('✖')} ${color.bold.red('Project directory')} ${color.bold.red(projectDirectory)} ${color.bold.red('must be configured')}`);
+  process.exit(1);
+};
+
+const service = await createNewService(directory, homeDirectory, projectDirectory);
+
+if (!service) {
+  console.log(`${color.bold.green('✔')} ${color.bold.green('No service created')}`);
+  process.exit(0);
+}
+
+if (service.newService) {
+  service.version = pack.version;
+  let API;
+
+  try {
+    API = await createAPI(homeDirectory, projectDirectory, service);
+    console.log(`${color.bold.green('✔')} ${color.bold('API:')} ${color.bold.green(API.name)}${color.bold(', version:')} ${color.bold.green(API.version)}`);
+  }
+  catch (err) { console.log(`${color.bold.red('✖')} ${color.red(err.message)} - ${color.bold.red('no API: skipping')}`); };
+
+  pack.name = service.name;
+  pack.description = service.description;
+  pack.mimik = {
+    type: service.type,
+  };
+  if (API) {
+    pack.swaggerFile = {
+      name: API.name,
+      version: API.version,
+      account: API.account,
+      provider: API.provider,
+    };
+    service.APIVersion = API.version;
+  };
+  startExample.SERVER_PORT = service.port;
+  startExample.SERVER_PUBLIC_PROTOCOL = service.protocol;
+  startExample.SERVER_PUBLIC_DOMAIN_NAME = service.domainName;
+  const srcDirectory = {
+    dir: 'src',
+    files: [
+      { name: 'index.js', content: getFileByNameSync(scaffoldDirectory, 'src/index.txt') },
+    ],
+    dirs: [
+      { dir: 'configuration',
+        files: [{ name: 'config.js', content: render(getFileByNameSync(scaffoldDirectory, 'src/mustacheConfig.txt'), { serviceType: service.type }) }],
+      },
+      { dir: 'controllers',
+        files: [{ name: 'infoController.js', content: getFileByNameSync(scaffoldDirectory, 'src/infoController.txt') }],
+      },
+      { dir: 'processors',
+        files: [{ name: 'infoProcessor.js', content: getFileByNameSync(scaffoldDirectory, 'src/infoProcessor.txt') }],
+      },
+      { dir: 'models' },
+      { dir: 'lib',
+        files: [{ name: 'common.js', content: getFileByNameSync(scaffoldDirectory, 'src/common.txt') }],
+      },
+    ],
+  };
+  const mainDirectory = [
+    { dir: '.', files: [{ name: 'package.json', content: JSON.stringify(pack, null, TAB) }] },
+    { dir: 'local',
+      files: [
+        { name: 'unScripts.js', content: getFileByNameSync(scaffoldDirectory, 'local/unScripts.txt') },
+        { name: 'scripts.js', content: getFileByNameSync(scaffoldDirectory, 'local/scripts.txt') },
+        { name: 'setup.js', content: getFileByNameSync(scaffoldDirectory, 'local/setup.txt') },
+        { name: 'testSetup.js', content: getFileByNameSync(scaffoldDirectory, 'local/testSetup.txt') },
+        { name: 'commitMsgCheck.js', content: getFileByNameSync(scaffoldDirectory, 'local/commitMsgCheck.txt') },
+        { name: 'dotFiles.js', content: getFileByNameSync(scaffoldDirectory, 'local/dotFiles.txt') },
+        { name: 'jsdoc.json', content: JSON.stringify(getFileByNameSync(scaffoldDirectory, 'local/jsdoc.json'), null, TAB) },
+        { name: 'start-example.json', content: stringify(startExample, null, TAB) },
+      ],
+    },
+    { dir: 'test',
+      dirs: [
+        { dir: 'normal',
+          files: [{ name: 'http-test.js', content: render(getFileByNameSync(scaffoldDirectory, 'test/mustacheHttp-test-normal.txt'), { SERVICE_TYPE: service.type.toUpperCase() }) }],
+        },
+        { dir: 'detached',
+          files: [{ name: 'http-test.js', content: render(getFileByNameSync(scaffoldDirectory, 'test/mustacheHttp-test-detached.txt'), { SERVICE_TYPE: service.type.toUpperCase() }) }],
+        },
+        { dir: 'src',
+          files: [
+            { name: 'systemEndpoints.js', content: render(getFileByNameSync(scaffoldDirectory, 'test/systemEndpoints.txt'), { SERVICE_TYPE: service.type.toUpperCase() }) },
+            { name: 'common.js', content: render(getFileByNameSync(scaffoldDirectory, 'test/mustacheCommon.txt'), { SERVICE_TYPE: service.type.toUpperCase(), serviceType: service.type }) },
+            { name: 'set-env.js', content: getFileByNameSync(scaffoldDirectory, 'test/set-env.txt') },
+            { name: 'util.js', content: getFileByNameSync(scaffoldDirectory, 'test/util.txt') },
+          ],
+        },
+        { dir: 'mock' },
+      ],
+    },
+  ];
+
+  if (API?.exist) {
+    mainDirectory.push(
+      { dir: 'api',
+        files: [{ name: API.destination, content: JSON.stringify(API.content, null, TAB) }],
+      },
+    );
+    const controllerContents = getControllers(API.content, template);
+
+    Object.keys(controllerContents).forEach((name) => {
+      if (name !== 'infoController.js') {
+        srcDirectory.dirs[srcDirectory.dirs.findIndex(dirsItem => dirsItem.dir === 'controllers')].files.push({ name, content: controllerContents[name] });
+      }
+    });
+  };
+  mainDirectory.push(srcDirectory);
+  try {
+    await scaffold(join(projectDirectory, service.name), mainDirectory);
+    console.log(`${color.bold.green('✔')} ${color.bold.green(service.name)} ${color.bold.green('service created')}`);
+    console.log(`${color.bold.green('✔')} ${color.bold.green('  description:')} ${color.bold.green(service.description)}`);
+    console.log(`${color.bold.green('✔')} ${color.bold.green('  type:')} ${color.bold.green(service.type)}`);
+    console.log(`${color.bold.green('✔')} ${color.bold.green('  version:')} ${color.bold.green(service.version)}`);
+    if (service.APIVersion) {
+      console.log(`${color.bold.green('✔')} ${color.bold.green('  API version:')} ${color.bold.green(service.APIVersion)}`);
+    }
+    else {
+      console.log(`${color.bold.red('✖')} ${color.bold.red('  no API defined')}`);
+    };
+    process.exit(0);
+  }
+  catch (err) { console.log(`${color.bold.red('✖')} ${color.bold.red(err.message)} - ${color.bold.red('skipping')}`); };
+}
+else {
+  console.log(`${color.bold.red('✖')} ${color.bold.red(service.name)} ${color.bold.red('already exists')} - ${color.bold.red('skipping')}`);
+  console.log(`${color.bold.red('✖')} ${color.bold.red('  description:')} ${color.bold.red(service.description)}`);
+  console.log(`${color.bold.red('✖')} ${color.bold.red('  type:')} ${color.bold.red(service.type)}`);
+  console.log(`${color.bold.red('✖')} ${color.bold.red('  version:')} ${color.bold.red(service.version)}`);
+  if (service.APIVersion) {
+    console.log(`${color.bold.red('✖')} ${color.bold.red('  API version:')} ${color.bold.red(service.APIVersion)}`);
+  }
+  else {
+    console.log(`${color.bold.red('✖')} ${color.bold.red('  no API defined')}`);
+  };
+};

package/lib/buildfile.js

@@ -0,0 +1,290 @@
+/* eslint-disable no-process-env, processDoc/validate-document-env */
+import * as JSONC from 'comment-json';
+import * as yaml from 'yaml';
+import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, extname, resolve } from 'node:path';
+import { TAB } from './common.js';
+import dotenv from 'dotenv';
+import prompts from 'prompts';
+
+const detectFormat = (filePath) => {
+  const ext = extname(filePath).toLowerCase();
+  if (ext === '.json' || ext === '.jsonc') return 'json';
+  if (ext === '.yaml' || ext === '.yml') return 'yaml';
+  return 'env';
+};
+
+const fileExists = async (part) => {
+  try {
+    await access(part);
+    return true;
+  }
+  catch { return false; }
+};
+
+const parseByFormat = (text, format, options) => {
+  if (!text) return {};
+  if (format === 'json') {
+    if (options.preserveComments) {
+      return JSONC.parse(text);
+    }
+    return options.jsonParse ? options.jsonParse(text) : JSON.parse(text);
+  }
+  if (format === 'yaml') return yaml.parse(text) ?? {};
+  return dotenv.parse(text);
+};
+
+const quoteEnv = (str) => {
+  if (/^[A-Za-z0-9_./:@-]+$/u.test(str)) return str;
+  return `"${str.replace(/\\/gu, '\\\\').replace(/"/gu, '\\"').replace(/\n/gu, '\\n')}"`;
+};
+
+const serializeEnv = (flatObj) => {
+  const lines = [];
+  const keys = Object.keys(flatObj).sort();
+
+  for (const key of keys) {
+    const val = flatObj[key];
+    lines.push(`${key}=${quoteEnv(String(val ?? ''))}`);
+  }
+  lines.push('');
+  return lines.join('\n');
+};
+
+const stringifyByFormat = (obj, format, options = {}) => {
+  if (format === 'json') {
+    if (options.preserveComments) {
+      return `${JSONC.stringify(obj, null, TAB)}\n`;
+    }
+    return `${JSON.stringify(obj, null, TAB)}\n`;
+  }
+  if (format === 'yaml') return yaml.stringify(obj);
+  return serializeEnv(obj);
+};
+
+const deepGet = (obj, key) => {
+  if (!obj || !key) return undefined;
+  const parts = key.split('.');
+  let cur = obj;
+  for (const part of parts) {
+    if (cur === null || typeof cur !== 'object') return undefined;
+    cur = cur[part];
+  }
+  return cur;
+};
+
+const deepSet = (obj, key, value) => {
+  const parts = key.split('.');
+  let cur = obj;
+  for (let i = 0; i < parts.length - 1; i += 1) {
+    const part = parts[i];
+    if (typeof cur[part] !== 'object' || cur[part] === null) cur[part] = {};
+    cur = cur[part];
+  }
+  cur[parts[parts.length - 1]] = value;
+};
+
+const getByPath = (obj, key, format) => {
+  if (format === 'env') return obj?.[key];
+  return deepGet(obj, key);
+};
+
+const setByPath = (obj, key, value, format) => {
+  if (format === 'env') {
+    obj[key] = value ?? '';
+    return;
+  }
+  deepSet(obj, key, value);
+};
+
+/**
+ * Manage comments tracking previous values:
+ * - Add old value as comment (no duplicates)
+ * - Remove any comment that matches the new value
+ */
+const managePreviousValueComments = (obj, key, oldValue, newValue) => {
+  const parts = key.split('.');
+  let cur = obj;
+
+  // Navigate to parent object
+  for (let i = 0; i < parts.length - 1; i += 1) {
+    const part = parts[i];
+    if (typeof cur[part] !== 'object' || cur[part] === null) return;
+    cur = cur[part];
+  }
+
+  const prop = parts[parts.length - 1];
+  const oldCommentText = `${prop}: ${JSON.stringify(oldValue)}`;
+  const newCommentText = `${prop}: ${JSON.stringify(newValue)}`;
+
+  // Get existing before comments for this property
+  const symbolKey = Symbol.for(`before:${prop}`);
+  const existingComments = cur[symbolKey] || [];
+
+  // Filter and process comments
+  const updatedComments = existingComments.filter((comm) => {
+    if (comm.type === 'LineComment' || comm.type === 'BlockComment') {
+      const trimmed = comm.value.trim();
+      // Remove comment if it matches the new value being set
+      if (trimmed === newCommentText) {
+        return false;
+      }
+    }
+    return true;
+  });
+
+  // Check if old value already exists in comments
+  const oldValueExists = updatedComments.some((comment) => {
+    if (comment.type === 'LineComment' || comment.type === 'BlockComment') {
+      return comment.value.trim() === oldCommentText;
+    }
+    return false;
+  });
+
+  // Add old value as comment if not already present and not same as new value
+  if (!oldValueExists && oldValue !== newValue) {
+    const newComment = { type: 'LineComment', value: ` ${oldCommentText}` };
+    updatedComments.push(newComment);
+  }
+
+  cur[symbolKey] = updatedComments;
+};
+
+const mapType = (type) => {
+  switch (type) {
+    case 'text':
+    case 'password':
+    case 'invisible':
+    case 'number':
+    case 'confirm':
+      return type;
+    default:
+      return 'text';
+  }
+};
+
+const basicValidator = (type) => {
+  if (type === 'number') {
+    return val => (val === '' || val === undefined || Number.isFinite(Number(val))) ? true : 'Enter a number';
+  }
+  return () => true;
+};
+
+const pickKeys = (obj, keys, format) => {
+  const out = {};
+
+  for (const k of keys) out[k] = format === 'env' ? obj[k] : deepGet(obj, k);
+  return out;
+};
+
+const clone = val => JSON.parse(JSON.stringify(val ?? {}));
+
+/**
+ * Configure a file by prompting for values with defaults from:
+ *   1) existing file content (if any)
+ *   2) environment variables (mapped per item)
+ *
+ * @param {string} filePath - Absolute or relative path to the config file.
+ *                            Supports .json/.jsonc (with comments), .yaml/.yml, and .env
+ * @param {Array<{
+ *   key: string,                // config key; dot.path supported for JSON/YAML, flat for .env
+ *   env?: string,               // environment variable name to use as fallback default
+ *   message?: string,           // prompt label (defaults to key)
+ *   type?: "text"|"password"|"number"|"confirm",  // default: "text"
+ *   validate?: (value)=>true|string,              // optional extra validation
+ *   format?: (value)=>true|string                 // optional format
+ *   initial?: any               // optional hard default if neither file nor env present
+ * }>} items
+ * @param {object} [options]
+ * @param {boolean} [options.nonInteractive=false] - If true, writes defaults without prompting
+ * @param {boolean} [options.createDirs=true] - Create parent dirs if missing
+ * @param {boolean} [options.preserveComments=true] - Preserve comments in JSON/JSONC files
+ * @param {boolean} [options.trackChanges=true] - Add comments for previous values when modified
+ * @param {function} [options.jsonParse=null] - Custom JSON parser (ignored if preserveComments is true)
+ * @returns {Promise<{written: boolean, format: "json"|"yaml"|"env", values: Record<string,any>}>}
+ */
+export const configureFile = async (filePath, items, options = {}) => {
+  const {
+    nonInteractive = false,
+    createDirs = true,
+    preserveComments = true,
+    trackChanges = true,
+    jsonParse = null,
+  } = options;
+  const abs = resolve(filePath);
+  const format = detectFormat(abs);
+
+  // 1) Read existing content (if any)
+  const exists = await fileExists(abs);
+  const fileData = exists ? await readFile(abs, 'utf8') : null;
+  const current = exists ? parseByFormat(fileData, format, { preserveComments, jsonParse }) : {};
+
+  // 2) Build prompt models with defaults: file > env > initial
+  const questions = [];
+  for (const item of items) {
+    const { key, env, message, type = 'text', validate, initial } = item;
+    const formatVal = item.format;
+
+    const fileVal = getByPath(current, key, format);
+    const envVal = env ? process.env[env] : undefined;
+    const defVal = fileVal ?? envVal ?? initial;
+
+    const question = {
+      name: key,
+      type: nonInteractive ? null : mapType(type),
+      message: message ?? key,
+      initial: type === 'number' && typeof defVal === 'string' ? Number(defVal) : defVal,
+      validate: validate ? validate : basicValidator(type),
+      format: formatVal,
+    };
+    if (!formatVal) delete question.format;
+    questions.push(question);
+  }
+
+  // 3) Get answers (or synthesize from defaults if noninteractive)
+  let answers = {};
+  const onCancel = () => process.exit(1);
+
+  if (nonInteractive) {
+    for (const question of questions) {
+      answers[question.name] = question.initial;
+    }
+  }
+  else {
+    const resp = await prompts(questions, { onCancel });
+    answers = resp || {};
+  }
+
+  // Merge answers onto current (preserve other keys and comments)
+  const merged = preserveComments && format === 'json' ? current : clone(current);
+  for (const item of items) {
+    const { key, type } = item;
+    let val = answers[key];
+
+    if (typeof val !== 'undefined') {
+      if (type === 'number' && typeof val === 'string' && val.trim() !== '') {
+        const num = Number(val);
+        if (!Number.isNaN(num)) val = num;
+      }
+
+      // Track previous value as comment if it changed
+      if (trackChanges && format === 'json' && preserveComments) {
+        const oldVal = getByPath(merged, key, format);
+        if (oldVal !== undefined && oldVal !== val) {
+          managePreviousValueComments(merged, key, oldVal, val);
+        }
+      }
+
+      setByPath(merged, key, val, format);
+    }
+  }
+
+  // 4) Write back to disk
+  if (createDirs) {
+    await mkdir(dirname(abs), { recursive: true });
+  }
+  const out = stringifyByFormat(merged, format, { preserveComments });
+  await writeFile(abs, out, 'utf8');
+
+  return { written: true, format, values: pickKeys(merged, items.map(i => i.key), format) };
+};

package/lib/common.js

@@ -0,0 +1,13 @@
+const TAB = 2;
+
+const PERM_FILE = 0o644;
+const PERM_DIR = 0o755;
+
+const PROJECT_DIR = './Projects';
+
+export {
+  PERM_FILE,
+  PERM_DIR,
+  PROJECT_DIR,
+  TAB,
+};