enable-generate-constants 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Doty
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,41 @@
+# enable-generate-constants
+
+CLI tool to query a MongoDB collection and generate constant/permission JSON files
+(e.g., `_permissions.json` or custom target) in specified target package directories.
+
+Output files are written into `<targetFolder>/src/<filename>` if a `src/` folder
+exists, otherwise `<targetFolder>/<filename>`.
+
+## Usage
+
+```sh
+npx enable-generate-constants --collection <collection> --folders <folders> [options]
+```
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `-f, --find <query>` | Optional MongoDB query as JSON or `field=val` pairs (default: `{}`) |
+| `-r, --repoRoot <path>` | Repository root containing `.env` (default: current directory) |
+| `-o, --folders <paths>` | Comma-separated list of folders to write output to (**required**) |
+| `-c, --collection <name>` | MongoDB collection containing codes (**required**) |
+| `-n, --name <field>` | Field name to extract (default: `code`) |
+| `-F, --file <filename>` | Output JSON filename (default: `_permissions.json`) |
+| `-d, --database <name>` | Database name override (defaults to `MONGODB_DATABASE` in `.env`) |
+| `-u, --connectionString <uri>` | MongoDB connection URI override (defaults to `.env`) |
+| `--dry-run` | Query database and display results without writing files |
+| `-h, --help` | Show usage help |
+
+## Examples
+
+```sh
+# Generate permissions for UX packages from feature collection
+npx enable-generate-constants --find "{}" --collection feature --folders ux/saas,ux/portal
+
+# Generate constants with a custom output file and field name
+npx enable-generate-constants --collection roles --name roleKey --file _roles.json --folders packages/auth
+
+# Preview output with --dry-run
+npx enable-generate-constants --collection feature --folders ux/saas --dry-run
+```

package/index.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { runCli } from './src/cli.mjs';
+
+await runCli();

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "enable-generate-constants",
+  "version": "1.0.1",
+  "description": "CLI to query MongoDB and generate constant/permission JSON files.",
+  "type": "module",
+  "module": "./index.mjs",
+  "bin": {
+    "enable-generate-constants": "./index.mjs"
+  },
+  "license": "MIT",
+  "author": "Contributors",
+  "dependencies": {
+    "dotenv": "^16.6.1",
+    "mongodb": "^6.21.0"
+  },
+  "scripts": {
+    "start": "node index.mjs",
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest tests/*.test.mjs"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,12 @@
+import { generateConstants } from './lib.mjs';
+import { parseCliArgs } from './options.mjs';
+
+export const runCli = async (argv = process.argv, log = console.log, exit = process.exit) => {
+  try {
+    const options = parseCliArgs(argv, exit, log);
+    await generateConstants(options, log);
+  } catch (e) {
+    log(`❌ Error: ${e.message}`);
+    exit(1);
+  }
+};

package/src/lib.mjs

@@ -0,0 +1,103 @@
+import { existsSync, statSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { MongoClient } from 'mongodb';
+import dotenv from 'dotenv';
+import { parseQuery } from './options.mjs';
+
+// Format code strings into uppercase constant keys (e.g. "user.read" -> "USER_READ")
+export function toConstantKey(codeValue) {
+  return codeValue
+    .trim()
+    .replace(/[^a-zA-Z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+    .toUpperCase();
+}
+
+// Prefer writing inside target's src/ folder if it exists
+export function resolveOutputDir(targetDir) {
+  const srcDir = join(targetDir, 'src');
+  return existsSync(srcDir) && statSync(srcDir).isDirectory() ? srcDir : targetDir;
+}
+
+// Convert docs list to sorted constant key-value map
+export function mapDocsToConstants(docs, nameField = 'code') {
+  const constants = {};
+  for (const doc of docs) {
+    const val = doc[nameField];
+    if (typeof val !== 'string' || val.trim() === '') continue;
+    constants[toConstantKey(val)] = val;
+  }
+  return Object.fromEntries(
+    Object.entries(constants).sort(([a], [b]) => a.localeCompare(b))
+  );
+}
+
+export async function generateConstants(options, log = console.log, clientOverride = null) {
+  const envPath = join(options.repoRoot, '.env');
+
+  if (existsSync(envPath)) {
+    dotenv.config({ path: envPath });
+  }
+
+  const databaseName =
+    options.database ||
+    process.env.MONGODB_DATABASE;
+
+  if (!databaseName) {
+    throw new Error(
+      'Database name not found. Provide --database or set MONGODB_DATABASE in .env.'
+    );
+  }
+
+  const envName = databaseName.toUpperCase().replace(/-/g, '_');
+  const connectionString =
+    options.connectionString ||
+    process.env[`${envName}_CONNECTIONSTRING`] ||
+    process.env.MONGODB_URI ||
+    process.env.MONGO_URI ||
+    process.env.CONNECTIONSTRING;
+
+  if (!connectionString) {
+    throw new Error(
+      `Connection string not found. Provide --connectionString or set ${envName}_CONNECTIONSTRING / MONGODB_URI in .env.`
+    );
+  }
+
+  const query = parseQuery(options.query);
+  const client = clientOverride || new MongoClient(connectionString);
+
+  try {
+    if (!clientOverride) {
+      await client.connect();
+    }
+    const docs = await client
+      .db(databaseName)
+      .collection(options.collection)
+      .find(query)
+      .toArray();
+
+    const constants = mapDocsToConstants(docs, options.name);
+    const count = Object.keys(constants).length;
+
+    for (const folder of options.folders) {
+      const targetFolder = join(options.repoRoot, folder);
+      const outputDir = resolveOutputDir(targetFolder);
+      const outputPath = join(outputDir, options.file);
+
+      if (options.dryRun) {
+        log(`[DRY RUN] Would generate ${outputPath} with ${count} constants.`);
+      } else {
+        await mkdir(dirname(outputPath), { recursive: true });
+        await writeFile(outputPath, `${JSON.stringify(constants, null, 2)}\n`, 'utf8');
+        log(`Generated ${outputPath} with ${count} constants.`);
+      }
+    }
+
+    return constants;
+  } finally {
+    if (!clientOverride) {
+      await client.close();
+    }
+  }
+}

package/src/options.mjs

@@ -0,0 +1,136 @@
+import { resolve } from 'node:path';
+
+export const DEFAULT_QUERY = '{}';
+export const DEFAULT_NAME_FIELD = 'code';
+export const DEFAULT_FILE_NAME = '_permissions.json';
+
+export const getDefaultOptions = () => ({
+  query: DEFAULT_QUERY,
+  repoRoot: process.cwd(),
+  folders: [],
+  collection: null,
+  name: DEFAULT_NAME_FIELD,
+  file: DEFAULT_FILE_NAME,
+  database: null,
+  connectionString: null,
+  dryRun: false
+});
+
+export const printHelp = (log = console.log) => {
+  log(`
+Usage:
+  npx enable-generate-constants [options]
+
+Options:
+  -f, --find <query>           Optional MongoDB query as JSON or field=value pairs (default: "{}")
+  -r, --repoRoot <path>        Repository root containing .env (default: current directory)
+  -o, --folders <paths>        Comma-separated folders where constant file is written
+  -c, --collection <name>      MongoDB collection containing constant/permission codes
+  -n, --name <field>           Field name to extract (default: "code")
+  -F, --file <filename>        Output JSON filename (default: "_permissions.json")
+  -d, --database <name>        Database name (overrides MONGODB_DATABASE in .env)
+  -u, --connectionString <uri> MongoDB connection URI (overrides .env)
+  --dry-run                    Query and display constants without writing files
+  -h, --help                   Show this help message
+
+Example:
+  npx enable-generate-constants --find "{}" --collection feature --folders ux/saas,ux/portal
+`);
+};
+
+export function parseQuery(queryText = '{}') {
+  const value = (queryText || '{}').trim();
+  if (value.startsWith('{') || value.startsWith('[')) {
+    try {
+      const query = JSON.parse(value);
+      if (query === null || Array.isArray(query) || typeof query !== 'object') {
+        throw new Error('JSON query must be an object.');
+      }
+      return query;
+    } catch (error) {
+      if (error.message === 'JSON query must be an object.') {
+        throw error;
+      }
+      throw new Error(`Invalid JSON passed to --find: ${error.message}`);
+    }
+  }
+
+  const query = {};
+  for (const pair of value.split(',')) {
+    const separator = pair.indexOf('=');
+    if (separator <= 0) {
+      throw new Error(`Invalid --find expression "${pair}". Use field=value or JSON.`);
+    }
+    const key = pair.slice(0, separator).trim();
+    const rawValue = pair.slice(separator + 1).trim();
+    if (!key || !rawValue) {
+      throw new Error(`Invalid --find expression "${pair}". Use field=value or JSON.`);
+    }
+    try {
+      query[key] = JSON.parse(rawValue);
+    } catch {
+      query[key] = rawValue;
+    }
+  }
+  return query;
+}
+
+export function parseCliArgs(argv = process.argv, exit = process.exit, log = console.log) {
+  const args = argv.slice(2);
+  const options = getDefaultOptions();
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--') {
+      continue;
+    } else if (arg === '-h' || arg === '--help') {
+      printHelp(log);
+      exit(0);
+    } else if (arg === '-f' || arg === '--find') {
+      options.query = args[++index];
+    } else if (arg.startsWith('--find=')) {
+      options.query = arg.slice('--find='.length);
+    } else if (arg === '-r' || arg === '--repoRoot' || arg === '--repo-root') {
+      options.repoRoot = resolve(args[++index]);
+    } else if (arg.startsWith('--repoRoot=') || arg.startsWith('--repo-root=')) {
+      options.repoRoot = resolve(arg.slice(arg.indexOf('=') + 1));
+    } else if (arg === '-o' || arg === '--folders') {
+      options.folders = (args[++index] || '').split(',').map((folder) => folder.trim()).filter(Boolean);
+    } else if (arg.startsWith('--folders=')) {
+      options.folders = arg.slice('--folders='.length).split(',').map((folder) => folder.trim()).filter(Boolean);
+    } else if (arg === '-c' || arg === '--collection') {
+      options.collection = args[++index];
+    } else if (arg.startsWith('--collection=')) {
+      options.collection = arg.slice('--collection='.length);
+    } else if (arg === '-n' || arg === '--name') {
+      options.name = args[++index];
+    } else if (arg.startsWith('--name=')) {
+      options.name = arg.slice('--name='.length);
+    } else if (arg === '-F' || arg === '--file') {
+      options.file = args[++index];
+    } else if (arg.startsWith('--file=')) {
+      options.file = arg.slice('--file='.length);
+    } else if (arg === '-d' || arg === '--database') {
+      options.database = args[++index];
+    } else if (arg.startsWith('--database=')) {
+      options.database = arg.slice('--database='.length);
+    } else if (arg === '-u' || arg === '--connectionString' || arg === '--uri') {
+      options.connectionString = args[++index];
+    } else if (arg.startsWith('--connectionString=') || arg.startsWith('--uri=')) {
+      options.connectionString = arg.slice(arg.indexOf('=') + 1);
+    } else if (arg === '--dry-run') {
+      options.dryRun = true;
+    } else {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+  }
+
+  if (options.folders.length === 0) {
+    throw new Error('--folders is required and must contain at least one folder.');
+  }
+  if (!options.collection) {
+    throw new Error('--collection is required.');
+  }
+
+  return options;
+}

package/tests/lib.test.mjs

@@ -0,0 +1,151 @@
+import { describe, it, expect } from '@jest/globals';
+import { mkdtempSync, mkdirSync, rmSync, readFileSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { toConstantKey, resolveOutputDir, mapDocsToConstants, generateConstants } from '../src/lib.mjs';
+
+describe('enable-generate-constants lib', () => {
+  describe('toConstantKey', () => {
+    it('converts dots, dashes, and special characters to uppercase snake_case', () => {
+      expect(toConstantKey('user.read_profile')).toBe('USER_READ_PROFILE');
+      expect(toConstantKey('saas-feature:view-all')).toBe('SAAS_FEATURE_VIEW_ALL');
+      expect(toConstantKey('__leading_and_trailing__')).toBe('LEADING_AND_TRAILING');
+    });
+  });
+
+  describe('resolveOutputDir', () => {
+    it('returns src folder when present in target directory', () => {
+      const dir = mkdtempSync(join(tmpdir(), 'const-test-'));
+      mkdirSync(join(dir, 'src'));
+      try {
+        expect(resolveOutputDir(dir)).toBe(join(dir, 'src'));
+      } finally {
+        rmSync(dir, { recursive: true, force: true });
+      }
+    });
+
+    it('falls back to directory root when src does not exist', () => {
+      const dir = mkdtempSync(join(tmpdir(), 'const-test-'));
+      try {
+        expect(resolveOutputDir(dir)).toBe(dir);
+      } finally {
+        rmSync(dir, { recursive: true, force: true });
+      }
+    });
+  });
+
+  describe('mapDocsToConstants', () => {
+    it('maps and sorts document field values alphabetically by key', () => {
+      const docs = [
+        { code: 'zebra.access' },
+        { code: 'alpha.access' },
+        { code: 'beta.access' },
+        { code: '' },
+        { code: null }
+      ];
+
+      const result = mapDocsToConstants(docs, 'code');
+      expect(Object.keys(result)).toEqual(['ALPHA_ACCESS', 'BETA_ACCESS', 'ZEBRA_ACCESS']);
+      expect(result).toEqual({
+        ALPHA_ACCESS: 'alpha.access',
+        BETA_ACCESS: 'beta.access',
+        ZEBRA_ACCESS: 'zebra.access'
+      });
+    });
+  });
+
+  describe('generateConstants', () => {
+    it('queries client, maps constants, and writes files to target folders', async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), 'gen-const-'));
+      const folderA = join(tempDir, 'pkgA');
+      const folderB = join(tempDir, 'pkgB');
+      mkdirSync(folderA);
+      mkdirSync(join(folderB, 'src'), { recursive: true });
+
+      const fakeDocs = [
+        { code: 'auth.login' },
+        { code: 'auth.logout' }
+      ];
+
+      const mockClient = {
+        db: () => ({
+          collection: () => ({
+            find: () => ({
+              toArray: async () => fakeDocs
+            })
+          })
+        })
+      };
+
+      const options = {
+        query: '{}',
+        repoRoot: tempDir,
+        folders: ['pkgA', 'pkgB'],
+        collection: 'permissions',
+        name: 'code',
+        file: '_permissions.json',
+        database: 'test_db',
+        connectionString: 'mongodb://localhost:27017',
+        dryRun: false
+      };
+
+      try {
+        const result = await generateConstants(options, () => {}, mockClient);
+        expect(result).toEqual({
+          AUTH_LOGIN: 'auth.login',
+          AUTH_LOGOUT: 'auth.logout'
+        });
+
+        const fileA = join(folderA, '_permissions.json');
+        const fileB = join(folderB, 'src', '_permissions.json');
+
+        expect(existsSync(fileA)).toBe(true);
+        expect(existsSync(fileB)).toBe(true);
+
+        const contentA = JSON.parse(readFileSync(fileA, 'utf8'));
+        expect(contentA).toEqual({
+          AUTH_LOGIN: 'auth.login',
+          AUTH_LOGOUT: 'auth.logout'
+        });
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+
+    it('does not write files when dryRun is true', async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), 'gen-const-dry-'));
+      const folderA = join(tempDir, 'pkgA');
+      mkdirSync(folderA);
+
+      const mockClient = {
+        db: () => ({
+          collection: () => ({
+            find: () => ({
+              toArray: async () => [{ code: 'test.code' }]
+            })
+          })
+        })
+      };
+
+      const options = {
+        query: '{}',
+        repoRoot: tempDir,
+        folders: ['pkgA'],
+        collection: 'permissions',
+        name: 'code',
+        file: '_permissions.json',
+        database: 'test_db',
+        connectionString: 'mongodb://localhost:27017',
+        dryRun: true
+      };
+
+      try {
+        await generateConstants(options, () => {}, mockClient);
+        const fileA = join(folderA, '_permissions.json');
+        expect(existsSync(fileA)).toBe(false);
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+  });
+});

package/tests/options.test.mjs

@@ -0,0 +1,87 @@
+import { describe, it, expect } from '@jest/globals';
+import { getDefaultOptions, parseCliArgs, parseQuery } from '../src/options.mjs';
+
+describe('enable-generate-constants options', () => {
+  it('returns expected default options', () => {
+    const opts = getDefaultOptions();
+    expect(opts.query).toBe('{}');
+    expect(opts.folders).toEqual([]);
+    expect(opts.collection).toBe(null);
+    expect(opts.name).toBe('code');
+    expect(opts.file).toBe('_permissions.json');
+    expect(opts.dryRun).toBe(false);
+  });
+
+  describe('parseQuery', () => {
+    it('parses valid JSON object queries', () => {
+      expect(parseQuery('{"active": true}')).toEqual({ active: true });
+    });
+
+    it('throws when JSON query is not an object', () => {
+      expect(() => parseQuery('["not", "object"]')).toThrow('JSON query must be an object.');
+    });
+
+    it('parses key=value string queries', () => {
+      expect(parseQuery('tier=ux,active=true,count=10')).toEqual({
+        tier: 'ux',
+        active: true,
+        count: 10
+      });
+    });
+
+    it('throws on invalid key=value pairs', () => {
+      expect(() => parseQuery('invalidpair')).toThrow('Invalid --find expression');
+    });
+  });
+
+  describe('parseCliArgs', () => {
+    it('parses valid CLI arguments', () => {
+      const opts = parseCliArgs([
+        'node',
+        'index.mjs',
+        '-f',
+        '{"status":"active"}',
+        '-c',
+        'permissions',
+        '-o',
+        'packages/app,packages/core',
+        '-n',
+        'featureCode',
+        '-F',
+        '_constants.json',
+        '-d',
+        'test_db',
+        '-u',
+        'mongodb://localhost:27017',
+        '--dry-run'
+      ]);
+
+      expect(opts.query).toBe('{"status":"active"}');
+      expect(opts.collection).toBe('permissions');
+      expect(opts.folders).toEqual(['packages/app', 'packages/core']);
+      expect(opts.name).toBe('featureCode');
+      expect(opts.file).toBe('_constants.json');
+      expect(opts.database).toBe('test_db');
+      expect(opts.connectionString).toBe('mongodb://localhost:27017');
+      expect(opts.dryRun).toBe(true);
+    });
+
+    it('throws when --folders is missing', () => {
+      expect(() => parseCliArgs(['node', 'index.mjs', '-c', 'features'])).toThrow(
+        '--folders is required and must contain at least one folder.'
+      );
+    });
+
+    it('throws when --collection is missing', () => {
+      expect(() => parseCliArgs(['node', 'index.mjs', '-o', 'packages/app'])).toThrow(
+        '--collection is required.'
+      );
+    });
+
+    it('throws on unknown options', () => {
+      expect(() => parseCliArgs(['node', 'index.mjs', '-c', 'feat', '-o', 'pkg', '--unknown'])).toThrow(
+        'Unknown option: --unknown'
+      );
+    });
+  });
+});