@platformatic/generators 4.0.0-new-config.2 → 4.0.0-new-config.3

package/index.js

@@ -1,3 +1,3 @@
 export { BaseGenerator } from './lib/base-generator.js'
-export { ImportGenerator } from './lib/import-generator.js'
+export { ImportGenerator, importedConfiguration } from './lib/import-generator.js'
 export * from './lib/utils.js'

package/lib/base-generator.js

@@ -1,20 +1,34 @@
 import { generateDashedName } from '@platformatic/foundation'
+import {
+  capabilityFactories,
+  evaluateConfigurationFile,
+  configurationFileNameFor,
+  listDirectoryEntries,
+  raw,
+  selectConfigurationFileNames,
+  selectLegacyConfigurationFileNames,
+  serializeConfiguration
+} from '@platformatic/foundation/lib/v4/index.js'
+import { builders, generateCode, parseModule } from 'magicast'
 import { readFile } from 'node:fs/promises'
-import { join } from 'node:path'
-import { generateGitignore } from './create-gitignore.js'
-import { MissingEnvVariable, ModuleNeeded, PrepareError } from './errors.js'
-import { FileGenerator } from './file-generator.js'
+import { dirname, join } from 'node:path'
 import {
   convertApplicationNameToPrefix,
+  equivalentSource,
+  findAnyConfigurationFile,
+  readEnvironmentReferences,
+  readEnvFile,
   envStringToObject,
   extractEnvVariablesFromText,
-  flattenObject,
   getApplicationTemplateFromSchemaUrl,
   getLatestNpmVersion,
   getPackageConfigurationObject,
   PLT_ROOT,
   stripVersion
 } from './utils.js'
+import { generateGitignore } from './create-gitignore.js'
+import { MissingEnvVariable, ModuleNeeded, PrepareError } from './errors.js'
+import { FileGenerator } from './file-generator.js'
 
 /* c8 ignore start */
 const fakeLogger = {
@@ -183,23 +197,7 @@ class BaseGenerator extends FileGenerator {
       if (this.config.isUpdating) {
         // only the packages options may have changed, let's update those
         await this.generateConfigFile()
-        const generatedConfigFile = JSON.parse(this.getFileObject(this.runtimeConfig, '').contents)
-        const fileFromDisk = await this.loadFile({ file: this.runtimeConfig, path: '' })
-        const currentConfigFile = JSON.parse(fileFromDisk.contents)
-        if (currentConfigFile.plugins) {
-          if (generatedConfigFile.plugins && generatedConfigFile.plugins.packages) {
-            currentConfigFile.plugins.packages = generatedConfigFile.plugins.packages
-          } else {
-            // remove packages because new configuration does not have them
-            currentConfigFile.plugins.packages = []
-          }
-        }
-        this.reset()
-        this.addFile({
-          path: '',
-          file: this.runtimeConfig,
-          contents: JSON.stringify(currentConfigFile, null, 2)
-        })
+        await this.#updatePackagesInPlace()
       } else {
         await this.getFastifyVersion()
         await this.getPlatformaticVersion()
@@ -241,9 +239,14 @@ class BaseGenerator extends FileGenerator {
 
   checkEnvVariablesInConfigFile () {
     const excludedEnvs = [PLT_ROOT]
-    const configFileName = this.runtimeConfig
-    const fileObject = this.getFileObject(configFileName)
-    const envVars = extractEnvVariablesFromText(fileObject.contents)
+    const configFileName = this.configurationFileName()
+    /*
+      Read from the configuration the generator built rather than from the file it wrote: the file
+      resolves each placeholder into an expression, so the text no longer carries the `{VAR}` this
+      is looking for. What is being checked is whether the generator declared every variable it
+      used, which is a question about the object.
+    */
+    const envVars = extractEnvVariablesFromText(JSON.stringify(this.generatedConfig ?? {}))
     const envKeys = Object.keys(this.config.env)
     if (envVars.length > 0) {
       for (const ev of envVars) {
@@ -282,7 +285,7 @@ class BaseGenerator extends FileGenerator {
   }
 
   async generateConfigFile () {
-    const configFileName = this.runtimeConfig
+    const configFileName = this.configurationFileName()
     const contents = await this._getConfigFileContents()
     // handle packages
     if (this.packages.length > 0) {
@@ -308,15 +311,203 @@ class BaseGenerator extends FileGenerator {
       })
     }
 
+    /*
+      Kept so that what reads this configuration back reads the object rather than re-parsing the
+      file: the file is a module now, and its values are expressions rather than the literals the
+      generator put in.
+    */
+    this.generatedConfig = contents
+
     this.addFile({
       path: '',
       file: configFileName,
-      contents: JSON.stringify(contents, null, 2)
+      contents: this.serializeConfigFile(contents)
     })
 
     return contents
   }
 
+  /*
+    The v4 per-app form. A capability with a factory is spelled by calling it; one without keeps the
+    stamped plain-object form, which is what the `$schema` marker exists for.
+
+    The placeholders the generator writes are resolved here rather than left as text. v3 substituted
+    `{PLT_API_PORT}` before anything read it, and v4 has no interpolation -- so the scaffolded value
+    becomes the expression it stood for, with the default the generator was going to write into
+    `.env` anyway.
+  */
+  /*
+    An update touches one thing -- which packages the application loads -- and has to leave
+    everything else exactly as the user left it.
+
+    For a v4 configuration that means editing the module rather than rewriting it: its values are
+    expressions, so reading it back and re-emitting would bake `Number(process.env.PORT || 3042)`
+    into whatever the port happens to be on this machine, and would drop every comment with it.
+  */
+  async #updatePackagesInPlace () {
+    const generated = this.generatedConfig ?? {}
+    const packages = generated.plugins?.packages ?? []
+    const existing = await this.#findExistingConfiguration()
+
+    if (!existing) {
+      /*
+        Nothing on disk to update, which is what an "update" of a directory that does not exist yet
+        looks like -- adding an application to a project is one. The generated files stand as they
+        are; resetting here would throw away everything this pass just produced.
+      */
+      return
+    }
+
+    /*
+      Only once there is something to rewrite. An update replaces the configuration and nothing
+      else, so the staged files go -- but a pass that found no configuration is adding an
+      application rather than updating one, and its files are the whole output.
+    */
+    this.reset()
+
+    if (existing.file.endsWith('.json')) {
+      // A v3 project being updated: it is data, and rewriting it loses nothing it carries.
+      const current = JSON.parse(existing.contents)
+
+      if (current.plugins) {
+        current.plugins.packages = packages
+      }
+
+      this.addFile({ path: '', file: existing.file, contents: JSON.stringify(current, null, 2) })
+      return
+    }
+
+    const module = parseModule(existing.contents)
+    const target = module.exports.default
+    // The factory form is a call whose first argument is the configuration; the plain object form
+    // is the configuration itself.
+    const configuration = target?.$type === 'function-call' ? target.$args[0] : target
+
+    if (configuration) {
+      configuration.plugins ??= {}
+      /*
+        Resolved the same way the file itself spells them -- the generator's model still holds
+        `{PLT_X}`, and writing that into a module would put the placeholder's own text where the
+        expression belongs. magicast has its own way of saying "this is source".
+      */
+      configuration.plugins.packages = this.resolveScaffoldedPlaceholders(packages, builders.raw)
+    }
+
+    const updated = generateCode(module).code
+
+    /*
+      An update that changes nothing about the configuration leaves the file alone. Plugin option
+      *values* live in `.env`, so changing one moves nothing here -- and rewriting the file anyway
+      would reprint the block, producing a diff that says something changed when nothing did.
+    */
+    if (equivalentSource(updated, existing.contents)) {
+      this.addFile({ path: '', file: existing.file, contents: existing.contents })
+      return
+    }
+
+    this.addFile({ path: '', file: existing.file, contents: updated })
+  }
+
+  async #findExistingConfiguration () {
+    const entries = await listDirectoryEntries(this.targetDirectory)
+    const file = selectConfigurationFileNames(entries)[0] ?? selectLegacyConfigurationFileNames(entries)[0]
+
+    if (!file) {
+      return null
+    }
+
+    const loaded = await this.loadFile({ file, path: '' })
+
+    return { contents: loaded.contents, file }
+  }
+
+  /*
+    The suffix follows the rule the format sets: `.js` in a "type": "commonjs" package is CommonJS,
+    where `export default` is a syntax error. The generator wrote that package.json a moment ago in
+    this same pass, so it reads its own answer rather than the filesystem's.
+  */
+  configurationFileName () {
+    let module = false
+
+    try {
+      module = JSON.parse(this.getFileObject('package.json', '')?.contents ?? '{}').type === 'module'
+    } catch {
+      // Not generated, or not JSON yet. The unambiguous suffix is the safe answer.
+    }
+
+    return configurationFileNameFor({ module, typescript: this.config.typescript })
+  }
+
+  serializeConfigFile (config) {
+    const { $schema, module: declared, ...rest } = config
+    const module = declared ?? this.module
+    const factory = capabilityFactories[module]
+    const resolved = this.resolveScaffoldedPlaceholders(rest)
+
+    if (!factory) {
+      return `export default ${serializeConfiguration({ $schema, module, ...resolved })}\n`
+    }
+
+    return `import { ${factory} } from '${module}'\n\nexport default ${factory}(${serializeConfiguration(resolved)})\n`
+  }
+
+  resolveScaffoldedPlaceholders (value, expression = raw) {
+    if (typeof value === 'string') {
+      const whole = value.match(/^\{([A-Za-z0-9_]+)\}$/)
+
+      if (!whole) {
+        return value
+      }
+
+      const name = whole[1]
+      const fallback = this.config.env?.[name]
+
+      if (fallback === undefined) {
+        return expression(`process.env.${name}`)
+      }
+
+      /*
+        A numeric default is written into the expression, and `||` rather than `??`: an env file
+        carrying the ordinary empty assignment `PORT=` supplies `''`, which is present, so `??`
+        would not fall back and `Number('')` is an ephemeral port where the reader of that line
+        expects 3042.
+
+        Everything else is a bare reference. Its value lives in `.env` -- the wizard's answers among
+        them -- and copying it into the configuration would put the same fact in two places, where
+        editing one leaves the other saying something else.
+      */
+      /*
+        A boolean default becomes a comparison, because v4 validates without coercion: a bare
+        reference hands the schema the string 'true', which is neither of the things a boolean
+        position accepts. The comparison reproduces the scaffolded default when the variable is
+        absent and lets its opposite flip it, which is what the value was there to express.
+      */
+      if (fallback === 'true' || fallback === true) {
+        return expression(`process.env.${name} !== 'false'`)
+      }
+
+      if (fallback === 'false' || fallback === false) {
+        return expression(`process.env.${name} === 'true'`)
+      }
+
+      return /^[0-9]+$/.test(String(fallback))
+        ? expression(`Number(process.env.${name} || ${fallback})`)
+        : expression(`process.env.${name}`)
+    }
+
+    if (value === null || typeof value !== 'object') {
+      return value
+    }
+
+    if (Array.isArray(value)) {
+      return value.map(entry => this.resolveScaffoldedPlaceholders(entry, expression))
+    }
+
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => [key, this.resolveScaffoldedPlaceholders(entry, expression)])
+    )
+  }
+
   /**
    * Reads the content of package.json and returns it as an object
    * @returns Object
@@ -421,36 +612,77 @@ class BaseGenerator extends FileGenerator {
     this.packages.push(pkg)
   }
 
+  /*
+    Reads a configuration file whichever dialect it is in. A v3 file is data and parses; a v4 one is
+    a module whose values are expressions, so the only way to know what it says is to evaluate it --
+    which is what the loader does, in a worker with an explicit environment.
+  */
+  async readConfigurationFile (path, role = 'root', envRoot = null) {
+    if (path.endsWith('.json')) {
+      return JSON.parse(await readFile(path, 'utf-8'))
+    }
+
+    /*
+      The project's own environment, because the file's values are expressions that read it: a port
+      written as `Number(process.env.PORT || 3042)` evaluates to NaN without it, and the generator
+      would be reading a configuration the project never has.
+    */
+    const env = { ...process.env, ...(await readEnvFile(envRoot ?? dirname(path))) }
+
+    // The role decides how the file is classified, and a root read as an application -- or the
+    // reverse -- is refused rather than silently accepted.
+    const { config } = await evaluateConfigurationFile({ path, env, command: 'start', production: false, role })
+
+    return config
+  }
+
   async loadFromDir (applicationName, runtimeRootPath) {
-    const runtimePkgConfigFileData = JSON.parse(await readFile(join(runtimeRootPath, this.runtimeConfig), 'utf-8'))
+    const runtimePkgConfigFileData = await this.readConfigurationFile(
+      join(runtimeRootPath, await findAnyConfigurationFile(runtimeRootPath)),
+      'root',
+      runtimeRootPath
+    )
     const applicationsPath = runtimePkgConfigFileData.autoload?.path ?? DEFAULT_SERVICES_PATH
-    const applicationPkgJsonFileData = JSON.parse(
-      await readFile(join(runtimeRootPath, applicationsPath, applicationName, 'platformatic.json'), 'utf-8')
+    const applicationRoot = join(runtimeRootPath, applicationsPath, applicationName)
+    // The environment is the runtime's, not the application's: the .env sits at the root beside
+    // the configuration that autoloads it.
+    const applicationPkgJsonFileData = await this.readConfigurationFile(
+      join(applicationRoot, await findAnyConfigurationFile(applicationRoot)),
+      'application',
+      runtimeRootPath
     )
     const runtimeEnv = envStringToObject(await readFile(join(runtimeRootPath, '.env'), 'utf-8'))
     const applicationNamePrefix = convertApplicationNameToPrefix(applicationName)
+    /*
+      Which options read the environment, taken from the source rather than from the loaded value.
+      A v3 configuration carried `"{PLT_X}"` in its data and survived being read as JSON; a v4 one
+      says `process.env.PLT_X` in its code, and reading it here gives whatever that produced in
+      *this* process -- `undefined`, since these are the scaffolded application's variables and not
+      ours. The name is in the file, so that is where it is read from.
+    */
+    const applicationConfigurationFile = join(applicationRoot, await findAnyConfigurationFile(applicationRoot))
+    const environmentReferences = readEnvironmentReferences(await readFile(applicationConfigurationFile, 'utf-8'))
     const plugins = []
     if (applicationPkgJsonFileData.plugins && applicationPkgJsonFileData.plugins.packages) {
-      for (const pkg of applicationPkgJsonFileData.plugins.packages) {
-        const flattened = flattenObject(pkg)
+      for (const [index, pkg] of applicationPkgJsonFileData.plugins.packages.entries()) {
         const output = {
-          name: flattened.name,
+          name: pkg.name,
           options: []
         }
-        if (pkg.options) {
-          Object.entries(flattened)
-            .filter(([key, value]) => key.indexOf('options.') === 0 && flattened[key].startsWith('{PLT_'))
-            .forEach(([key, value]) => {
-              const runtimeEnvVarKey = value.replace(/[{}]/g, '')
-              const applicationEnvVarKey = runtimeEnvVarKey.replace(`PLT_${applicationNamePrefix}_`, '')
-              const option = {
-                name: applicationEnvVarKey,
-                path: key.replace('options.', ''),
-                type: 'string',
-                value: runtimeEnv[runtimeEnvVarKey]
-              }
-              output.options.push(option)
-            })
+
+        const prefix = `plugins.packages.${index}.options.`
+
+        for (const [path, runtimeEnvVarKey] of environmentReferences) {
+          if (!path.startsWith(prefix)) {
+            continue
+          }
+
+          output.options.push({
+            name: runtimeEnvVarKey.replace(`PLT_${applicationNamePrefix}_`, ''),
+            path: path.slice(prefix.length),
+            type: 'string',
+            value: runtimeEnv[runtimeEnvVarKey]
+          })
         }
 
         plugins.push(output)
@@ -459,7 +691,13 @@ class BaseGenerator extends FileGenerator {
 
     return {
       name: applicationName,
-      template: getApplicationTemplateFromSchemaUrl(applicationPkgJsonFileData.$schema),
+      /*
+        A v4 configuration says which capability it is outright -- the factory sets `module` -- and
+        a v3 one says it through the `$schema` URL, which is what that reader is for.
+      */
+      template:
+        applicationPkgJsonFileData.module ??
+        getApplicationTemplateFromSchemaUrl(applicationPkgJsonFileData.$schema),
       fields: [],
       plugins
     }

package/lib/import-generator.js

@@ -1,9 +1,20 @@
 import { findConfigurationFileRecursive, safeRemove } from '@platformatic/foundation'
+import { capabilityFactories } from '@platformatic/foundation/lib/v4/index.js'
 import { spawnSync } from 'node:child_process'
 import { readFile, readdir, stat } from 'node:fs/promises'
-import { dirname, isAbsolute, join, relative, resolve } from 'node:path'
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
 import { BaseGenerator } from './base-generator.js'
 
+export function importedConfiguration (pkg) {
+  const factory = capabilityFactories[pkg]
+
+  if (factory) {
+    return `import { ${factory} } from '${pkg}'\n\nexport default ${factory}({})\n`
+  }
+
+  return `export default {\n  module: '${pkg}'\n}\n`
+}
+
 export class ImportGenerator extends BaseGenerator {
   constructor (options = {}) {
     const { applicationName, module, version, parent: runtime, ...opts } = options
@@ -124,7 +135,7 @@ export class ImportGenerator extends BaseGenerator {
   }
 
   async #generateConfigFile (originalPath, updatedPath) {
-    // Determine if there is a watt.json file in the application path - If it's missing, insert one
+    // Determine if there is a config file in the application path - If it's missing, insert one
     // For import it means we don't update  the file, for copy it means it was already copied in #copy.
     const existingConfig = await findConfigurationFileRecursive(originalPath)
 
@@ -132,21 +143,18 @@ export class ImportGenerator extends BaseGenerator {
       return
     }
 
-    const { module: pkg, version } = this.config
-
-    if (pkg.startsWith('@platformatic/')) {
-      this.addFile({
-        path: '',
-        file: join(updatedPath, this.runtimeConfig),
-        contents: JSON.stringify({ $schema: `https://schemas.platformatic.dev/${pkg}/${version}.json` }, null, 2)
-      })
-    } else {
-      this.addFile({
-        path: '',
-        file: join(updatedPath, this.runtimeConfig),
-        contents: JSON.stringify({ module: pkg }, null, 2)
-      })
-    }
+    const { module: pkg } = this.config
+
+    /*
+      The v4 per-app form rather than a JSON stub. This is the path taken for a capability that
+      ships no generator of its own, so a stub here would leave the wizard writing the old dialect
+      for exactly the applications least likely to be exercised by anything else.
+    */
+    this.addFile({
+      path: '',
+      file: join(updatedPath, 'watt.config.mjs'),
+      contents: importedConfiguration(pkg)
+    })
   }
 
   async #updatePackageJson (originalPath, updatedPath, pkg, version) {
@@ -170,43 +178,37 @@ export class ImportGenerator extends BaseGenerator {
   }
 
   async #updateRuntime (runtime) {
-    const configObject = runtime.getRuntimeConfigFileObject()
-    /* c8 ignore next - else */
-    const config = JSON.parse(configObject?.contents ?? '{}')
-    const envObject = runtime.getRuntimeEnvFileObject()
-    /* c8 ignore next - else */
-    let env = envObject?.contents ?? ''
-
-    // Find which key is being used for the manual applications
-    let key
-    for (const candidate of new Set([runtime.applicationsFolder, 'applications', 'services', 'web'])) {
-      if (Array.isArray(config[candidate])) {
-        key = candidate
-        break
-      }
-    }
-
-    /* c8 ignore next - else */
-    key ??= runtime.applicationsFolder ?? 'applications'
-    const applications = config[key] ?? []
+    /*
+      The configuration the runtime generator built, not a parse of the file it wrote: that file is
+      a module now, and its values are expressions rather than the data this is about to add an
+      entry to. It is written back through the same generator, which knows how to spell it.
+
+      One spelling: the list is `applications`, because the loader refuses the v3 aliases by name.
+      And a literal path rather than v3's `{PLT_APPLICATION_<ID>_PATH}` placeholder plus its `.env`
+      line -- the indirection bought nothing and left the entry pointing at the root itself in
+      every clone missing the gitignored file the value lived in.
+    */
+    const config = runtime.generatedConfig ?? {}
+    const applications = Array.isArray(config.applications) ? config.applications : []
 
     if (!applications.some(application => application.id === this.config.applicationName)) {
+      const base = this.runtime?.targetDirectory ?? this.targetDirectory
+      const absolute = isAbsolute(this.config.applicationPath)
+        ? this.config.applicationPath
+        : resolve(base, this.config.applicationPath)
+      const relativePath = relative(base, absolute)
+
       applications.push({
         id: this.config.applicationName,
-        path: `{${this.config.applicationPathEnvName}}`,
+        // A cross-drive path has no relative spelling; `relative` answers with the absolute one.
+        path: (isAbsolute(relativePath) ? absolute : relativePath).split(sep).join('/'),
         url: this.config.gitUrl
       })
     }
 
-    config[key] = applications
-
-    if (env.length > 0) {
-      env += '\n'
-    }
-    env += `${this.config.applicationPathEnvName}=${this.config.applicationPath}`
+    config.applications = applications
 
     runtime.updateRuntimeConfig(config)
-    runtime.updateRuntimeEnv(env)
   }
 
   async #copy (root) {

package/lib/utils.js

@@ -1,3 +1,10 @@
+import {
+  listDirectoryEntries,
+  selectConfigurationFileNames,
+  selectLegacyConfigurationFileNames
+} from '@platformatic/foundation/lib/v4/index.js'
+import { builders, generateCode, parseModule } from 'magicast'
+import { readFile } from 'node:fs/promises'
 import { EOL } from 'node:os'
 import { join } from 'node:path'
 import { setTimeout } from 'timers/promises'
@@ -180,3 +187,178 @@ export function getApplicationTemplateFromSchemaUrl (schemaUrl) {
   }
   return `@platformatic/${splitted[splitted.length - 2]}`
 }
+
+/*
+  The configuration file in a directory, whichever dialect it is in. A generator reading an existing
+  project meets both: one it scaffolded under v4, and one that predates the switch.
+*/
+export async function findAnyConfigurationFile (directory) {
+  const entries = await listDirectoryEntries(directory)
+
+  return selectConfigurationFileNames(entries)[0] ?? selectLegacyConfigurationFileNames(entries)[0] ?? null
+}
+
+// The environment a project supplies to its own configuration. Absent is the same as empty here:
+// a project without one simply has nothing to layer.
+export async function readEnvFile (directory) {
+  try {
+    return envStringToObject(await readFile(join(directory, '.env'), 'utf-8'))
+  } catch {
+    return {}
+  }
+}
+
+/*
+  Whether two spellings of a module say the same thing. Used to decide that an edit produced no
+  change: the printer reflows what it touches, so comparing the text byte for byte would report a
+  change on every update whether or not one happened.
+*/
+export function equivalentSource (left, right) {
+  /*
+    Whitespace removed rather than collapsed, because the printer's difference is exactly one space:
+    `packages: [{` against `packages: [\n  {`. Two spellings that differ only inside a string
+    literal would compare equal here, and the consequence of that is leaving a file alone whose only
+    change was spaces inside a string -- which is the harmless direction to be wrong in.
+  */
+  return left.replace(/\s/g, '') === right.replace(/\s/g, '')
+}
+
+/*
+  A string to be printed as source rather than as a string literal. Exported so that a caller
+  outside this package can hand one to `resolveScaffoldedPlaceholders` without taking on the AST
+  library itself.
+*/
+export const rawSource = builders.raw
+
+/*
+  Add applications to an existing root configuration by editing the file the user has, rather than
+  by writing a new one from the configuration the loader returned.
+
+  The difference is everything the source says and the loaded configuration does not:
+  `process.env.PLT_SERVER_LOGGER_LEVEL` comes back as `'info'`, a factory call comes back as the
+  object it built, and comments come back not at all. Re-emitting replaces each of those with the
+  value it happened to have on the machine doing the writing.
+
+  Returns `null` when the file's shape cannot be edited in place -- a configuration built by a call,
+  or held in a variable, or an application list that is not a literal array. There is nothing to
+  edit there, and the caller is expected to say so rather than to write something else.
+*/
+export function appendApplications (source, entries, resolveEntry = entry => entry) {
+  const module = parseModule(source)
+  const target = module.exports.default
+  // The plain object form exports the configuration; the factory form passes it as the first argument.
+  const configuration = target?.$type === 'function-call' ? target.$args[0] : target
+
+  if (configuration?.$type !== 'object') {
+    return null
+  }
+
+  // One spelling: the loader refuses `services` and `web` by name, so a file this editor sees
+  // lists its applications under `applications` or not at all.
+  const key = 'applications'
+  const listed = configuration[key] ?? []
+
+  if (!Array.isArray(listed)) {
+    return null
+  }
+
+  const present = new Set(Array.from(listed, entry => entry.id))
+  const added = entries.filter(entry => entry.id && !present.has(entry.id))
+
+  if (added.length === 0) {
+    return source
+  }
+
+  configuration[key] = [...listed, ...added.map(entry => resolveEntry(entry))]
+
+  return generateCode(module).code
+}
+
+// The applications a configuration lists. One spelling: the v3 aliases are refused by the loader.
+export function listedApplications (config) {
+  return config?.applications ?? []
+}
+
+/*
+  The environment variable an expression reads, if it reads one.
+
+  `process.env.NAME` is the bare form; `process.env.NAME ?? ''` and `process.env.NAME || 3042` are
+  what a writer emits when the position needs a fallback. All three name the same variable, and the
+  fallback is not part of the name.
+*/
+function environmentReference (node) {
+  if (!node) {
+    return null
+  }
+
+  if (node.type === 'LogicalExpression') {
+    return environmentReference(node.left)
+  }
+
+  if (node.type !== 'MemberExpression' || node.property?.type !== 'Identifier') {
+    return null
+  }
+
+  const { object } = node
+
+  if (object?.type !== 'MemberExpression' || object.object?.name !== 'process' || object.property?.name !== 'env') {
+    return null
+  }
+
+  return node.property.name
+}
+
+function collectEnvironmentReferences (node, path, found) {
+  if (!node) {
+    return
+  }
+
+  if (node.type === 'ObjectExpression') {
+    for (const property of node.properties) {
+      const key = property.key?.name ?? property.key?.value
+
+      if (key !== undefined) {
+        collectEnvironmentReferences(property.value, [...path, key], found)
+      }
+    }
+
+    return
+  }
+
+  if (node.type === 'ArrayExpression') {
+    node.elements.forEach((element, index) => collectEnvironmentReferences(element, [...path, index], found))
+    return
+  }
+
+  const name = environmentReference(node)
+
+  if (name) {
+    found.set(path.join('.'), name)
+  }
+}
+
+/*
+  Which values in a configuration come from the environment, by their path in it.
+
+  A v3 configuration said this in its data: `"port": "{PORT}"` survives being read as JSON. A v4
+  configuration says it in its code, and reading the file gives you the value the expression
+  produced -- `undefined`, for a variable that is not set in the process doing the reading. So a
+  tool that needs to know *which* variable a setting reads has to look at the source.
+*/
+export function readEnvironmentReferences (source) {
+  const { $ast: ast } = parseModule(source)
+  const found = new Map()
+
+  const declaration = ast.body.find(node => node.type === 'ExportDefaultDeclaration')?.declaration
+
+  if (!declaration) {
+    return found
+  }
+
+  // The plain-object form exports the configuration; a factory or `defineConfig` passes it along.
+  const configuration = declaration.type === 'CallExpression' ? declaration.arguments[0] : declaration
+
+  collectEnvironmentReferences(configuration, [], found)
+
+  return found
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platformatic/generators",
-  "version": "4.0.0-new-config.2",
+  "version": "4.0.0-new-config.3",
   "description": "Main classes and utils for generators.",
   "main": "index.js",
   "type": "module",
@@ -21,9 +21,10 @@
     "change-case-all": "^2.1.0",
     "execa": "^9.6.0",
     "fastify": "^5.0.0",
+    "magicast": "^0.5.4",
     "pino": "^9.9.0",
-    "undici": "^7.27.2",
-    "@platformatic/foundation": "4.0.0-new-config.2"
+    "undici": "^8.5.0",
+    "@platformatic/foundation": "4.0.0-new-config.3"
   },
   "devDependencies": {
     "@types/inquirer": "^9.0.7",