@team-codeme/crud-forge 0.0.0-stage → 1.0.0

package/src/parser/jdl-parser.js

@@ -0,0 +1,171 @@
+const _ = require('lodash');
+
+/**
+ * Standard default audit fields matching JHipster/TW-Hipster conventions.
+ */
+const DEFAULT_AUDIT_FIELDS = [
+  { fieldName: 'createdBy', fieldType: 'String', fieldTypeIsEnum: false, fieldValidateRules: [], comment: null },
+  { fieldName: 'createdDate', fieldType: 'Instant', fieldTypeIsEnum: false, fieldValidateRules: [], comment: null },
+  { fieldName: 'lastModifiedBy', fieldType: 'String', fieldTypeIsEnum: false, fieldValidateRules: [], comment: null },
+  { fieldName: 'lastModifiedDate', fieldType: 'Instant', fieldTypeIsEnum: false, fieldValidateRules: [], comment: null }
+];
+
+/** Injected when `@ActiveStatus` is present and the entity does not already declare `isActive`. */
+const ACTIVE_STATUS_FIELD = {
+  fieldName: 'isActive',
+  fieldType: 'Boolean',
+  fieldTypeIsEnum: false,
+  fieldValidateRules: [],
+  comment: null
+};
+
+/** GDL entity annotations with implemented generator behavior. */
+const SUPPORTED_GDL_ANNOTATIONS = new Set(['Audited', 'Searchable', 'ActiveStatus']);
+
+/** JDL entity annotations with implemented generator behavior. */
+const SUPPORTED_JDL_ANNOTATIONS = new Set(['EnableAudit', 'Searchable', 'ActiveStatus']);
+
+function parseEntityAnnotations(annotationsStr = '') {
+  return [...annotationsStr.matchAll(/@(\w+)/g)].map((m) => m[1]);
+}
+
+function annotationSet(annotations) {
+  return new Set(annotations);
+}
+
+/**
+ * Parses JDL file contents.
+ * @param {string} jdlContent - Raw JDL content string.
+ * @param {object} preferences - Developer configuration settings.
+ * @returns {{entities: Array, enums: Array, relationships: Array}}
+ */
+function parseJdl(jdlContent, preferences = {}) {
+  const entities = {};
+  const enums = {};
+  const relationships = [];
+
+  // Remove block comments
+  const cleanContent = jdlContent.replace(/\/\*[\s\S]*?\*\//g, '');
+
+  // Helper check for line comment index
+  function isCommented(content, index) {
+    const lastNewline = content.lastIndexOf('\n', index);
+    const lineStart = lastNewline === -1 ? 0 : lastNewline + 1;
+    const line = content.substring(lineStart, index);
+    return line.trim().startsWith('//');
+  }
+
+  // 1. Parse Enums
+  const enumRegex = /enum\s+(\w+)\s*\{([^}]+)\}/g;
+  let enumMatch;
+  while ((enumMatch = enumRegex.exec(cleanContent)) !== null) {
+    if (isCommented(cleanContent, enumMatch.index)) continue;
+    const enumName = enumMatch[1];
+    const values = enumMatch[2]
+      .trim()
+      .split(',')
+      .map(v => v.trim().split('(')[0].trim())
+      .filter(Boolean);
+    enums[enumName] = { name: enumName, values: values.map(v => ({ name: v })) };
+  }
+
+  // Determine audit fields based on config preferences
+  let auditFieldsToUse = DEFAULT_AUDIT_FIELDS;
+  if (preferences.fields && preferences.fields.audit && Array.isArray(preferences.fields.audit.names)) {
+    auditFieldsToUse = preferences.fields.audit.names.map(name => {
+      const type = (name.toLowerCase().endsWith('date') || /(?:At|_at)$/.test(name)) ? 'Instant' : 'String';
+      return { fieldName: name, fieldType: type, fieldTypeIsEnum: false, fieldValidateRules: [], comment: null };
+    });
+  }
+
+  // 2. Parse Entities and Fields
+  const entityRegex = /((?:@\w+\s+)*)entity\s+(\w+)\s*\{([^}]+)\}/g;
+  let entityMatch;
+  while ((entityMatch = entityRegex.exec(cleanContent)) !== null) {
+    if (isCommented(cleanContent, entityMatch.index)) continue;
+
+    const annotations = parseEntityAnnotations(entityMatch[1] || '');
+    const flags = annotationSet(annotations);
+    const hasAuditAnnotation = flags.has('EnableAudit');
+    const hasActiveStatus = flags.has('ActiveStatus');
+    const hasSearchable = flags.has('Searchable');
+    const entityName = entityMatch[2];
+    const fieldsContent = entityMatch[3];
+
+    const fields = [];
+    const fieldLines = fieldsContent
+      .split('\n')
+      .map(l => l.trim())
+      .filter(line => line && !line.startsWith('//'));
+
+    fieldLines.forEach(line => {
+      const fieldMatch = line.match(/^(\w+)\s+([\w<>]+)(.*)/);
+      if (fieldMatch) {
+        const fieldName = fieldMatch[1];
+        const fieldType = fieldMatch[2];
+        const restOfLine = fieldMatch[3] || '';
+
+        let validations = restOfLine;
+        let comment = null;
+
+        const commentIndex = restOfLine.indexOf('//');
+        if (commentIndex !== -1) {
+          validations = restOfLine.substring(0, commentIndex).trim();
+          comment = restOfLine.substring(commentIndex + 2).trim();
+        }
+
+        fields.push({
+          fieldName,
+          fieldType,
+          fieldTypeIsEnum: !!enums[fieldType],
+          fieldValidateRules: validations.split(/\s+/).filter(Boolean),
+          comment
+        });
+      }
+    });
+
+    if (hasActiveStatus && !fields.some((f) => f.fieldName === 'isActive')) {
+      fields.push({ ...ACTIVE_STATUS_FIELD });
+    }
+
+    if (hasAuditAnnotation && preferences.fields?.audit?.enabled !== false) {
+      fields.push(...auditFieldsToUse);
+    }
+
+    entities[entityName] = {
+      name: entityName,
+      fields,
+      annotations,
+      searchable: hasSearchable,
+      activeStatus: hasActiveStatus,
+      audited: hasAuditAnnotation
+    };
+  }
+
+  // 3. Parse Relationships
+  const relationshipRegex = /relationship\s+(OneToOne|ManyToOne|OneToMany|ManyToMany)\s*\{\s*(\w+)(?:[({](\w+)[)}])?\s+to\s+(\w+)(?:[({](\w+)[)}])?\s*\}/g;
+  let relMatch;
+  while ((relMatch = relationshipRegex.exec(cleanContent)) !== null) {
+    if (isCommented(cleanContent, relMatch.index)) continue;
+    relationships.push({
+      type: relMatch[1],
+      from: { name: relMatch[2], fieldName: relMatch[3] },
+      to: { name: relMatch[4], fieldName: relMatch[5] }
+    });
+  }
+
+  return {
+    entities: Object.values(entities),
+    enums: Object.values(enums),
+    relationships
+  };
+}
+
+module.exports = {
+  parseJdl,
+  DEFAULT_AUDIT_FIELDS,
+  ACTIVE_STATUS_FIELD,
+  SUPPORTED_GDL_ANNOTATIONS,
+  SUPPORTED_JDL_ANNOTATIONS,
+  parseEntityAnnotations
+};

package/src/presets/pmb-test.js

@@ -0,0 +1,139 @@
+const fs = require('fs-extra');
+const path = require('path');
+const crypto = require('crypto');
+const { literalObject, stringLiteral, numberLiteral, withoutComments } = require('./static-source');
+const { sanitizeProxyRoutes } = require('../config/proxy-routes');
+
+function extractPmbPreset(source) {
+  const root = fs.realpathSync(path.resolve(source));
+  const fingerprints = {};
+  function read(relative) {
+    const file = path.resolve(root, relative);
+    if (!file.startsWith(root + path.sep) || !fs.existsSync(file)) throw new Error(`Missing PMB source file: ${file}`);
+    if (!fs.realpathSync(file).startsWith(root + path.sep)) throw new Error(`PMB source file points outside source project: ${relative}`);
+    const content = fs.readFileSync(file, 'utf8');
+    fingerprints[relative] = crypto.createHash('sha256').update(content).digest('hex');
+    return content;
+  }
+  const angular = JSON.parse(read('angular.json'));
+  const candidates = Object.entries(angular.projects || {}).filter(([, p]) => (p.architect || p.targets)?.build);
+  const chosen = candidates.find(([name]) => name === angular.defaultProject) || (candidates.length === 1 ? candidates[0] : null);
+  if (!chosen) throw new Error('PMB angular.json: cannot determine the application project.');
+  const targets = chosen[1].architect || chosen[1].targets;
+  const development = targets.build.configurations?.development;
+  const environmentFile = development?.fileReplacements?.find(item => item.replace.endsWith('/environment.ts'))?.with;
+  if (!environmentFile) throw new Error('PMB angular.json: development environment file replacement is missing.');
+  const scripts = JSON.parse(read('package.json')).scripts || {};
+  if (!/--configuration(?:=|\s+)development\b/.test(scripts.dev || '')) {
+    throw new Error('PMB package.json: dev script must explicitly select the development configuration.');
+  }
+  const proxyFlag = /--proxy-config(?:=|\s+)([\w./-]+)(?=\s|$)/.exec(scripts.dev);
+  if (scripts.dev.includes('--proxy-config') && !proxyFlag) throw new Error('PMB dev script has a dynamic or unsupported proxy path; use a literal project-relative path.');
+  const proxyFile = proxyFlag?.[1] || targets.serve?.configurations?.development?.proxyConfig || targets.serve?.options?.proxyConfig;
+  if (!proxyFile) throw new Error('PMB development proxy configuration is missing.');
+  const portFlag = /--port(?:=|\s+)(\d+)(?=\s|$)/.exec(scripts.dev);
+  if (scripts.dev.includes('--port') && !portFlag) throw new Error('PMB dev script has a dynamic or unsupported port; use a literal port number.');
+  const port = Number(portFlag?.[1] || targets.serve?.configurations?.development?.port || targets.serve?.options?.port || 4200);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error('Invalid PMB development port.');
+  const values = literalObject(read(environmentFile), 'environment', environmentFile);
+  const string = key => stringLiteral(values[key], `${environmentFile}: ${key}`);
+  if (values.useMockAuth !== 'false') throw new Error(`${environmentFile}: useMockAuth must be false for pmb-test.`);
+  if (string('kcClientSecret') !== '') throw new Error('PMB frontend client requires a secret. Cannot generate a public-client preset; no secret was imported.');
+  const realm = string('kcRealm');
+  const clientId = string('kcClientId');
+  if (!/^[\w.-]+$/.test(realm) || !/^[\w.-]+$/.test(clientId)) throw new Error('PMB realm and client ID must be nonempty identifiers.');
+  const tokenPath = string('sso');
+  if (tokenPath !== `/realms/${realm}/protocol/openid-connect/token` || string('kcUrl') !== tokenPath.replace(/\/token$/, '')) {
+    throw new Error('PMB OIDC paths no longer match the supported public-client password flow.');
+  }
+  if (string('apiBaseUrl') !== '/' || string('keycloakBaseUrl') !== '') throw new Error('PMB development API bases are no longer relative; review the importer before refreshing.');
+  const routes = sanitizeProxyRoutes(JSON.parse(read(proxyFile)), proxyFile);
+  if (!routes['/realms'] || !routes['/api/v1']) throw new Error(`${proxyFile}: /realms and /api/v1 routes are required.`);
+  if (routes['/realms'].pathRewrite || routes['/api/v1'].pathRewrite) throw new Error('Rewritten PMB OIDC/admin base paths need an explicit importer update.');
+  const authSource = withoutComments(read('src/app/core/auth/auth.service.ts'));
+  const probeExpression = /const ACCESS_TOKEN_EXPIRY_PROBE_INTERVAL_MS\s*=\s*([^;]+);/.exec(authSource)?.[1].trim();
+  const probeInterval = numberLiteral(probeExpression, 'ACCESS_TOKEN_EXPIRY_PROBE_INTERVAL_MS');
+  for (const pattern of [/set\(['"]grant_type['"],\s*['"]password['"]\)/, /set\(['"]grant_type['"],\s*['"]refresh_token['"]\)/,
+    /SIGN_IN_OIDC_SCOPE\s*=\s*['"]openid['"]/, /set\(['"]client_id['"],\s*config.clientId\)/, /['"]\/logout['"]/]) {
+    if (!pattern.test(authSource)) throw new Error('PMB auth.service.ts has an unsupported authentication flow. Review it before refreshing.');
+  }
+  const interceptor = withoutComments(read('src/app/core/auth/auth.interceptor.ts'));
+  if (!interceptor.includes("delete('X-Tenant-ID')") || !interceptor.includes('Bearer ${')) throw new Error('PMB bearer/tenant header behavior changed; review the importer.');
+  const access = withoutComments(read('src/app/core/auth/access-control.service.ts'));
+  const adminCheck = /readonly isUserAdmin\s*=\s*computed(?:<boolean>)?\([\s\S]*?\n\s*\}\);/.exec(access)?.[0];
+  const adminRoles = [...(adminCheck || '').matchAll(/role\s*===\s*['"]([^'"]+)['"]/g)].map(match => match[1]);
+  if (!adminRoles.length) throw new Error('Cannot determine PMB admin roles from access-control.service.ts.');
+  const base = 'src/app/domains/admin/modules/apps/micro-functions/referenceModule/entities/province';
+  const model = withoutComments(read(`${base}/province.model.ts`));
+  const service = withoutComments(read(`${base}/service/province.service.ts`));
+  const resource = /resourceUrl\s*=\s*(['"])([^'"]+)\1/.exec(service)?.[2];
+  if (!resource?.endsWith('/api/provinces')) throw new Error('Province client no longer exposes the expected /api/provinces resource.');
+  const route = Object.keys(routes).filter(key => resource === key || resource.startsWith(key + '/')).sort((a, b) => b.length - a.length)[0];
+  if (!route) throw new Error(`No development proxy route for Province resource ${resource}.`);
+  let backendPath = resource;
+  for (const [pattern, replacement] of Object.entries(routes[route].pathRewrite || {})) backendPath = backendPath.replace(new RegExp(pattern), replacement);
+  const microservice = /^\/([\w-]+)\/api\/provinces$/.exec(backendPath)?.[1];
+  if (!microservice) throw new Error(`Unsupported Province backend path: ${backendPath}`);
+  const iface = /interface IProvince\s*\{([\s\S]*?)\}/.exec(model)?.[1];
+  if (!iface) throw new Error('Province model interface is missing.');
+  const fields = [...iface.matchAll(/(\w+)\??:\s*([^;]+);/g)];
+  const audits = ['createdBy', 'createdDate', 'lastModifiedBy', 'lastModifiedDate'];
+  const types = { String: 'string', string: 'string', boolean: 'bool', 'dayjs.Dayjs': 'datetime' };
+  const declarations = fields.filter(([, name]) => name !== 'id').map(([, name, rawType]) => {
+    const type = rawType.replace(/\s*\|\s*null/g, '').trim();
+    if (!types[type]) throw new Error(`Unsupported Province field type for ${name}; update the sample mapping.`);
+    return { name, type: types[type] };
+  });
+  if (!declarations.some(field => field.name === 'provinceName')) throw new Error('Province sample fields changed.');
+  const audited = audits.every(name => declarations.some(field => field.name === name));
+  const gdl = '// PMB reference-data sample derived from its Province model/client.\n' +
+    '// Backend reads/writes still depend on your account permissions.\n' +
+    `${audited ? '@Audited\n' : ''}entity Province {\n` +
+    declarations.filter(field => !audited || !audits.includes(field.name)).map(field => `  ${field.type} ${field.name}`).join('\n') + '\n}\n';
+  const services = {};
+  for (const [key, entry] of Object.entries(routes)) {
+    if (!key.startsWith('/services/')) continue;
+    const rewrite = entry.pathRewrite?.['^' + key];
+    services[key.slice('/services/'.length)] = { target: entry.target, ...(rewrite !== undefined ? { pathRewrite: rewrite } : {}) };
+  }
+  services[microservice] = { target: routes[route].target, pathRewrite: '/' + microservice };
+  // Use the route actually used by the source client if historical aliases disagree.
+  routes['/services/' + microservice] = {
+    ...routes[route], pathRewrite: { ['^/services/' + microservice]: '/' + microservice },
+  };
+  // The generated admin client uses its own prefix; strip it before PMB's /api/v1.
+  routes['/services/keycloak-admin'] = { ...routes['/api/v1'], pathRewrite: { '^/services/keycloak-admin': '' } };
+  // This secondary realm requires credentials and is not part of the imported login.
+  delete routes['/pmb-dad-mock-module'];
+  const config = {
+    project: { name: 'PMB Development Test' },
+    input: { file: './gdl/example.gdl', type: 'gdl' },
+    output: { directory: '.', overwritePolicy: 'fail' },
+    validation: true,
+    fuse: { enabled: true, cleanLayout: true, includePrebuilt: false },
+    api: { baseUrl: '/api', microservice, services },
+    proxy: { write: 'both', routes },
+    devServer: { port },
+    mock: { enabled: false },
+    auth: {
+      provider: 'keycloak', serverUrl: routes['/realms'].target, realm, clientId,
+      useMockAuth: false, adminRoles,
+      session: { idleTimeoutMs: numberLiteral(values.sessionIdleTimeoutMs, 'sessionIdleTimeoutMs'), statusProbeIntervalMs: probeInterval },
+      provision: { enabled: false, adapter: 'admin-service', adminServiceUrl: routes['/api/v1'].target },
+    },
+    iam: { enabled: false },
+  };
+  return { config, gdl, metadata: {
+    preset: 'pmb-test', version: 1, importedAt: new Date().toISOString(), source: root,
+    sourceFiles: fingerprints, environmentFile, proxyFile,
+    sample: { entity: 'Province', sourceResource: resource, backendUrl: routes[route].target + backendPath },
+    limitations: [
+      'Login and backend API availability have not been established by source extraction.',
+      'Province fields come from the frontend model; backend write constraints are not verified.',
+      'DAD secondary login, confidential internal client, and privileged IAM management are not imported.',
+      'Non-admin screen permissions and PMB-specific profile/business context require separate verification.',
+    ],
+  } };
+}
+
+module.exports = { extractPmbPreset };

package/src/presets/static-source.js

@@ -0,0 +1,73 @@
+// Read a restricted literal object from TypeScript without evaluating source code.
+// Dynamic expressions are deliberately rejected for the settings we import.
+function withoutComments(source) {
+  let out = '';
+  let quote = null;
+  for (let i = 0; i < source.length; i++) {
+    const char = source[i];
+    if (quote) {
+      out += char;
+      if (char === '\\') out += source[++i] || '';
+      else if (char === quote) quote = null;
+    } else if (['"', "'", '`'].includes(char)) {
+      quote = char; out += char;
+    } else if (source.slice(i, i + 2) === '//') {
+      while (i < source.length && source[i] !== '\n') i++;
+      out += '\n';
+    } else if (source.slice(i, i + 2) === '/*') {
+      i += 2;
+      while (i < source.length && source.slice(i, i + 2) !== '*/') {
+        out += source[i] === '\n' ? '\n' : ' '; i++;
+      }
+      i++; out += ' ';
+    } else out += char;
+  }
+  return out;
+}
+
+function literalObject(source, name, file) {
+  const text = withoutComments(source);
+  const match = new RegExp(`\\b(?:const|let)\\s+${name}\\s*=\\s*\\{`).exec(text);
+  if (!match) throw new Error(`Cannot statically read ${name} in ${file}; expected a literal object.`);
+  const values = Object.create(null);
+  let start = match.index + match[0].length;
+  let depth = 0;
+  let quote = null;
+  function add(end) {
+    const entry = text.slice(start, end).trim();
+    if (!entry) return;
+    const property = /^(\w+)\s*:\s*([\s\S]+)$/.exec(entry);
+    if (!property || Object.hasOwn(values, property[1])) throw new Error(`Unsupported or duplicate property in ${file}. Use explicit environment settings.`);
+    values[property[1]] = property[2].trim();
+  }
+  for (let i = start; i < text.length; i++) {
+    const char = text[i];
+    if (quote) {
+      if (char === '\\') i++;
+      else if (char === quote) quote = null;
+    } else if (['"', "'", '`'].includes(char)) quote = char;
+    else if (char === '}' && depth === 0) { add(i); return values; }
+    else if ('{[('.includes(char)) depth++;
+    else if ('}])'.includes(char)) depth--;
+    else if (char === ',' && depth === 0) { add(i); start = i + 1; }
+  }
+  throw new Error(`Unterminated ${name} object in ${file}.`);
+}
+
+function stringLiteral(expression, label) {
+  // No interpolation, escapes, or executable expressions; URLs and identifiers need none.
+  const match = /^(['"])([^'"\\\r\n]*)\1$/.exec(expression || '');
+  if (!match) throw new Error(`Cannot statically read ${label}; expected a quoted string.`);
+  return match[2];
+}
+
+function numberLiteral(expression, label) {
+  if (!/^\d+(?:\s*\*\s*\d+)*$/.test(expression || '')) {
+    throw new Error(`Cannot statically read ${label}; expected a number or multiplication of numbers.`);
+  }
+  const number = expression.split('*').reduce((total, part) => total * Number(part.trim()), 1);
+  if (!Number.isSafeInteger(number)) throw new Error(`Invalid number for ${label}.`);
+  return number;
+}
+
+module.exports = { withoutComments, literalObject, stringLiteral, numberLiteral };

package/src/presets/store.js

@@ -0,0 +1,96 @@
+const fs = require('fs-extra');
+const path = require('path');
+const os = require('os');
+const YAML = require('yaml');
+const { extractPmbPreset } = require('./pmb-test');
+const { validateConfig } = require('../config/load-config');
+const { validateBlueprint } = require('../validator/blueprint-validator');
+const { parseGdl } = require('../parser/gdl-parser');
+
+function presetDirectory(name) {
+  if (name !== 'pmb-test') throw new Error(`Unknown preset "${name}". Supported optional preset: pmb-test.`);
+  const home = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+  if (!path.isAbsolute(home)) throw new Error('XDG_CONFIG_HOME must be an absolute directory.');
+  return path.join(home, 'crudforge/presets', name);
+}
+
+function assertSecretFree(value, prefix = '') {
+  if (!value || typeof value !== 'object') return;
+  for (const [key, item] of Object.entries(value)) {
+    if (!key.endsWith('Env') && /secret|password|access.?token|refresh.?token|authorization|cookie/i.test(key) &&
+        item !== '' && item !== null && item !== false) {
+      throw new Error(`Preset contains a credential field: ${prefix}${key}. Remove it; credentials are never persisted in presets.`);
+    }
+    assertSecretFree(item, prefix + key + '.');
+  }
+}
+
+function validatePreset(preset, label) {
+  validateConfig(preset.config, label);
+  assertSecretFree(preset.config);
+  if (preset.config.input?.file !== './gdl/example.gdl' || preset.config.output?.directory !== '.') {
+    throw new Error(`${label}: preset paths must be ./gdl/example.gdl and output.directory: .`);
+  }
+  if (preset.config.auth?.provision?.enabled !== false || preset.config.auth?.useMockAuth !== false) {
+    throw new Error(`${label}: pmb-test requires real authentication with provisioning disabled.`);
+  }
+  const errors = validateBlueprint(preset.gdl, true);
+  if (errors.length || !parseGdl(preset.gdl, preset.config).entities.length) {
+    throw new Error(`${label}: invalid preset GDL. ${errors.join('\n')}`);
+  }
+}
+
+async function loadPreset(name) {
+  const directory = presetDirectory(name);
+  if (!await fs.pathExists(directory)) throw new Error(`Preset not found: ${directory}. Initialize with --preset ${name} --source <PMB-project> first.`);
+  const result = {
+    config: YAML.parse(await fs.readFile(path.join(directory, 'config.yml'), 'utf8')),
+    gdl: await fs.readFile(path.join(directory, 'example.gdl'), 'utf8'),
+    metadata: await fs.readJson(path.join(directory, 'metadata.json')),
+  };
+  validatePreset(result, directory);
+  return result;
+}
+
+async function importPreset(name, source, { refresh = false } = {}) {
+  const directory = presetDirectory(name);
+  if (!source) throw new Error('Specify --source <PMB-project> to import or refresh a preset.');
+  // Extract and validate without executing PMB code, and before touching the registry.
+  const preset = extractPmbPreset(source);
+  validatePreset(preset, directory);
+  const parent = path.dirname(directory);
+  await fs.ensureDir(parent);
+  const lock = directory + '.lock';
+  try { await fs.mkdir(lock); } catch (error) {
+    if (error.code === 'EEXIST') throw new Error(`Preset import already in progress: ${lock}. Remove the lock only if that process has stopped.`);
+    throw error;
+  }
+  let stage;
+  try {
+    const exists = await fs.pathExists(directory);
+    if (exists && !refresh) throw new Error(`Preset already exists: ${directory}. Reuse it without --source, or run "crudforge preset refresh ${name} --source <PMB-project>".`);
+    if (!exists && refresh) throw new Error(`Preset not found: ${directory}. Use "crudforge init <project> --preset ${name} --source <PMB-project>" first.`);
+    stage = await fs.mkdtemp(path.join(parent, `.${name}-import-`));
+    await fs.writeFile(path.join(stage, 'config.yml'), '# Reusable PMB development preset. No credentials.\n' + YAML.stringify(preset.config));
+    await fs.writeFile(path.join(stage, 'example.gdl'), preset.gdl);
+    await fs.writeJson(path.join(stage, 'metadata.json'), preset.metadata, { spaces: 2 });
+    let backup;
+    if (exists) {
+      backup = directory + '.backup-' + new Date().toISOString().replace(/[:.]/g, '-') + '-' + path.basename(stage).slice(-6);
+      await fs.rename(directory, backup);
+    }
+    try { await fs.rename(stage, directory); } catch (error) {
+      if (backup) await fs.rename(backup, directory);
+      throw error;
+    }
+    console.log(`Saved preset: ${directory}`);
+    if (backup) console.log(`Previous preset retained: ${backup}`);
+    for (const limitation of preset.metadata.limitations) console.log(`PMB preset: ${limitation}`);
+    return preset;
+  } finally {
+    if (stage) await fs.remove(stage);
+    await fs.remove(lock);
+  }
+}
+
+module.exports = { presetDirectory, loadPreset, importPreset, validatePreset };

package/src/provision/admin-service.js

@@ -0,0 +1,148 @@
+const { request, ProvisionHttpError } = require('./http');
+
+const OWNED_ATTRIBUTE = 'crudforge.owned';
+
+function baseUrl(adminServiceUrl) {
+  return String(adminServiceUrl || '').replace(/\/+$/, '');
+}
+
+function authHeaders(token) {
+  return { Authorization: `Bearer ${token}` };
+}
+
+async function adminServiceRequest({ adminServiceUrl, token, method, path, json }) {
+  const url = `${baseUrl(adminServiceUrl)}${path}`;
+  const response = await request({
+    method,
+    url,
+    headers: authHeaders(token),
+    json,
+  });
+  if (response.status === 401) {
+    throw new Error(
+      `Admin service at ${baseUrl(adminServiceUrl)} rejected the token (HTTP 401). Authorization header is required; use a Keycloak bearer token.`
+    );
+  }
+  if (response.status === 403) {
+    const detail =
+      response.body && typeof response.body === 'object' ? response.body.error || JSON.stringify(response.body) : '';
+    throw new Error(
+      `Admin service at ${baseUrl(adminServiceUrl)} denied access (HTTP 403)${
+        detail ? `: ${detail}` : ''
+      }. This wrapper requires realm role KEYCLOAK_ADMIN_ACCESS (not only Keycloak realm-admin). Native Keycloak Admin REST can still be used with auth.provision.adapter: keycloak-admin-rest.`
+    );
+  }
+  return response;
+}
+
+async function listClients(ctx) {
+  const response = await adminServiceRequest({ ...ctx, method: 'GET', path: '/api/v1/clients' });
+  if (response.status >= 400) {
+    throw new ProvisionHttpError(`GET /api/v1/clients failed (HTTP ${response.status})`, response.status, response.body);
+  }
+  return Array.isArray(response.body) ? response.body : response.body?.clients || [];
+}
+
+async function listRoles(ctx) {
+  const response = await adminServiceRequest({ ...ctx, method: 'GET', path: '/api/v1/roles' });
+  if (response.status >= 400) {
+    throw new ProvisionHttpError(`GET /api/v1/roles failed (HTTP ${response.status})`, response.status, response.body);
+  }
+  return Array.isArray(response.body) ? response.body : response.body?.roles || [];
+}
+
+async function listUsers(ctx) {
+  const response = await adminServiceRequest({
+    ...ctx,
+    method: 'GET',
+    path: '/api/v1/users?page=0&size=100',
+  });
+  if (response.status >= 400) {
+    throw new ProvisionHttpError(`GET /api/v1/users failed (HTTP ${response.status})`, response.status, response.body);
+  }
+  if (Array.isArray(response.body)) {
+    return response.body;
+  }
+  return response.body?.users || response.body?.content || [];
+}
+
+function createUnsupported(kind, name) {
+  return new Error(
+    `Cannot create ${kind} "${name}" through the admin-service adapter. Published contract at GET / only documents GET /api/v1/clients, GET /api/v1/roles, GET /api/v1/users, user update/attributes/password, and GET user roles. Set auth.provision.adapter to keycloak-admin-rest and auth.serverUrl to the Keycloak base URL to create clients, realm roles, users, and role assignments.`
+  );
+}
+
+async function runAdminServiceBootstrap({
+  adminServiceUrl,
+  token,
+  desired,
+  dryRun,
+  resetExistingPasswords,
+  resolveUserPassword,
+}) {
+  const ctx = { adminServiceUrl, token };
+  const plan = [];
+  const result = { adapter: 'admin-service', created: [], skipped: [], errors: [] };
+
+  const [clients, roles, users] = await Promise.all([listClients(ctx), listRoles(ctx), listUsers(ctx)]);
+  plan.push(`Found ${clients.length} clients, ${roles.length} roles, ${users.length} users via admin service.`);
+
+  const clientId = desired.clientId;
+  const clientMatch = clients.find((client) => (client.clientId || client.client_id || client.id) === clientId);
+  if (!clientMatch) {
+    throw createUnsupported('client', clientId);
+  }
+  plan.push(`Client "${clientId}" already exists on admin service; create is not in the published contract.`);
+  result.skipped.push({ type: 'client', id: clientId });
+
+  for (const roleName of desired.roles) {
+    const exists = roles.some((role) => (role.name || role.roleName) === roleName);
+    if (!exists) {
+      throw createUnsupported('role', roleName);
+    }
+    result.skipped.push({ type: 'role', id: roleName });
+  }
+
+  for (const user of desired.users) {
+    const existing = users.find((entry) => (entry.username || entry.preferred_username) === user.username);
+    if (!existing) {
+      throw createUnsupported('user', user.username);
+    }
+    result.skipped.push({ type: 'user', id: user.username });
+    if (resetExistingPasswords) {
+      const userId = existing.id || existing.userId;
+      if (!userId) {
+        throw new Error(`User "${user.username}" exists but has no id; cannot reset password.`);
+      }
+      if (dryRun) {
+        plan.push(`Dry run: would POST /api/v1/users/${userId}/password (resetExistingPasswords).`);
+      } else {
+        const password = resolveUserPassword(user);
+        const response = await adminServiceRequest({
+          ...ctx,
+          method: 'POST',
+          path: `/api/v1/users/${userId}/password`,
+          json: { value: password, temporary: !!user.temporaryPassword },
+        });
+        if (response.status >= 400) {
+          throw new ProvisionHttpError(
+            `Reset password for "${user.username}" failed (HTTP ${response.status})`,
+            response.status,
+            response.body
+          );
+        }
+        plan.push(`Reset password for existing user "${user.username}" via admin service.`);
+      }
+    }
+  }
+
+  return { plan, result, ownedAttribute: OWNED_ATTRIBUTE };
+}
+
+module.exports = {
+  runAdminServiceBootstrap,
+  listClients,
+  listRoles,
+  listUsers,
+  OWNED_ATTRIBUTE,
+};