@omega.js/desktop 0.53.0 → 0.54.1

package/dist/vendor/devkit/ci-workflows.js

@@ -5,17 +5,17 @@
  * That is correct for a STANDALONE target (the target dir is the git root) and dead on
  * arrival inside a brand monorepo: GitHub executes workflows from the REPO
  * ROOT's `.github/workflows/` only, so `targets/extension/.github/workflows/publish.yml`
- * never runs — CI builds and store publishes silently do not exist.
+ * never runs: CI builds and store publishes silently do not exist.
  *
  * In a monorepo the target's workflow is COMPOSED into the root dir instead: one
  * file per target (`<target>-<workflow>.yml`), every post-checkout `run:` step scoped
- * to the target's path, regenerated from the framework template on every setup — so
+ * to the target's path, regenerated from the framework template on every setup, so
  * a re-run updates the target's own file and can never duplicate a job. Each target's
  * runs also get their own concurrency group, so one target's deploy never cancels
  * another's.
  *
  * Scoping is by working directory, not by a `paths:` trigger filter: OMEGA
- * workflows carry NO push triggers by design (deliberate deploys — D13), and a
+ * workflows carry NO push triggers by design (deliberate deploys, D13), and a
  * path filter on a dispatch-only workflow filters nothing. It is declared PER
  * STEP, not as a workflow-level `defaults.run.working-directory`: that would
  * also scope the steps that run before actions/checkout (and the jobs that never
@@ -23,7 +23,7 @@
  *
  * Composition RECONCILES (#636): the enabled target set derives the composed
  * file set, so a target the brand's config no longer enables has its composed
- * files DELETED (reconcileComposedWorkflows) — the ratified example of a
+ * files DELETED (reconcileComposedWorkflows): the ratified example of a
  * dropped config key becoming a real removal.
  */
 const path = require('path');
@@ -68,7 +68,7 @@ const INSTALL_WORKSPACE_FLAG = '--workspace .';
  * an unscoped artifact upload collects an empty repo-root path.
  *
  * Named per action on purpose: a blanket "any input called path" rule would
- * rewrite inputs that mean something else — `actions/checkout`'s `path:` names
+ * rewrite inputs that mean something else: `actions/checkout`'s `path:` names
  * where to CLONE the repo, not a file in it. An action missing from this table
  * is left alone; add it here when a template starts using it.
  */
@@ -164,7 +164,7 @@ function composeWorkflow(contents, options) {
   // (and its own engines.node pin) sits beside it.
   composed = renderInstallWorkspace(composed, { composed: true });
 
-  // Display name carries the target — two targets' runs are told apart in the
+  // Display name carries the target: two targets' runs are told apart in the
   // Actions list, where only the workflow name shows.
   composed = composed.replace(/^name:[ \t]*(.*)$/m, (full, value) => `name: ${value.trim()} (${targetPath})`);
 
@@ -173,7 +173,7 @@ function composeWorkflow(contents, options) {
   composed = composed.replace(/^(concurrency:\n(?:[ \t]+.*\n)*?[ \t]+group:[ \t]*)(.*)$/m, (full, prefix, value) => `${prefix}${targetName}-${value.trim()}`);
 
   // Every `run:` step that follows its job's checkout executes in the target dir
-  // (`uses:` actions — checkout and friends — stay at the repo root, which is
+  // (`uses:` actions, checkout and friends, stay at the repo root, which is
   // what they want).
   composed = scopeRunSteps(composed, targetPath);
 
@@ -238,12 +238,12 @@ function composeTargetWorkflows(options) {
 /**
  * Delete the composed workflows of targets this brand no longer has (#636).
  * Composing is per-target and a dropped target's framework never runs again, so
- * the file it wrote at the brand root would outlive it forever — a workflow
+ * the file it wrote at the brand root would outlive it forever: a workflow
  * Actions still lists and still dispatches for a target that is gone.
  *
  * The brand root's `.github/workflows/` is a MIXED dir: the brand's own
  * human-authored workflows live beside the composed ones. So a file goes only
- * past a DOUBLE lock — it carries the GENERATED header (which also NAMES the
+ * past a DOUBLE lock: it carries the GENERATED header (which also NAMES the
  * target it was composed for) AND it is named the composed way,
  * `<target>-<framework file>.yml`. A human file matches neither and is never
  * even a candidate; nothing here reads or edits one.
@@ -283,14 +283,14 @@ function reconcileComposedWorkflows(options) {
       jetpack.remove(file);
     }
     result.removed.push(`.github/workflows/${name}`);
-    logger.log(`Removed .github/workflows/${name} — ${owned.targetPath} is no longer a target of this brand`);
+    logger.log(`Removed .github/workflows/${name}: ${owned.targetPath} is no longer a target of this brand`);
   }
 
   return result;
 }
 
 /**
- * The workflow file name to dispatch for a target — composed in a brand monorepo,
+ * The workflow file name to dispatch for a target: composed in a brand monorepo,
  * the framework's own name standalone. The ONE place deploy verbs and the
  * compose step agree on the name.
  * @param {object} options
@@ -324,7 +324,7 @@ function composedWorkflowNameFor(name, workflow) {
 // A workflow-level `defaults.run.working-directory` reads cleaner but applies to
 // EVERY run step, including the ones that execute before actions/checkout (the
 // git config step, a matrix-resolving step) and the jobs that never check out at
-// all — the target dir does not exist there yet, and the job dies on step 1.
+// all: the target dir does not exist there yet, and the job dies on step 1.
 function scopeRunSteps(contents, targetPath) {
   const lines = contents.split('\n');
   const output = [];
@@ -343,7 +343,7 @@ function scopeRunSteps(contents, targetPath) {
 
   for (const line of lines) {
     const indent = line.search(/\S/);
-    // Comments and blank lines never close a block — they belong to what follows
+    // Comments and blank lines never close a block; they belong to what follows
     const structural = indent >= 0 && !line.trimStart().startsWith('#');
 
     // A top-level key closes any open steps list and says whether we are in `jobs:`
@@ -417,8 +417,8 @@ function actionOf(step, keyIndent) {
   return line ? line.slice(line.indexOf('uses:') + 5).trim().split('@')[0] : null;
 }
 
-// `hashFiles()` globs from GITHUB_WORKSPACE wherever it appears — no step key
-// moves it — so a composed target workflow's patterns carry the target path or match
+// `hashFiles()` globs from GITHUB_WORKSPACE wherever it appears (no step key
+// moves it), so a composed target workflow's patterns carry the target path or match
 // nothing at all.
 function scopeHashFiles(step, targetPath) {
   return step.map((line) => line.replace(/hashFiles\(([^)]*)\)/g, (full, args) => {
@@ -491,7 +491,7 @@ function scopeValue(value, targetPath) {
 }
 
 // A target-relative path/glob. Absolute paths and expression-built values name
-// something other than a file in the checkout — those are left as written.
+// something other than a file in the checkout; those are left as written.
 function joinTargetPath(value, targetPath) {
   const trimmed = value.trim();
   const scoped = trimmed.replace(/^\.\//, '');
@@ -503,7 +503,7 @@ function joinTargetPath(value, targetPath) {
   return `${targetPath}/${scoped}`;
 }
 
-// Declare `working-directory` on one run step's lines — a step that already
+// Declare `working-directory` on one run step's lines. A step that already
 // declares its own is left alone.
 function scopeRunStep(step, keyIndent, targetPath) {
   const pad = ' '.repeat(keyIndent);
@@ -544,11 +544,11 @@ function sweepTargetCopy(context) {
     jetpack.remove(targetCopy);
     pruneEmptyDirs(path.dirname(targetCopy), targetDir);
     result.removed.push(`.github/workflows/${name}`);
-    logger.log(`Removed ${targetPath}/.github/workflows/${name} — GitHub only runs workflows from the repo root`);
+    logger.log(`Removed ${targetPath}/.github/workflows/${name}: GitHub only runs workflows from the repo root`);
     return;
   }
 
-  logger.warn(`Kept ${targetPath}/.github/workflows/${name} — it differs from the current framework template (your edits, or an older framework version), and GitHub NEVER runs a workflow from a target dir. Compare it against ${composedName}, move anything it still needs, then delete ${targetPath}/.github/workflows/${name}`);
+  logger.warn(`Kept ${targetPath}/.github/workflows/${name}: it differs from the current framework template (your edits, or an older framework version), and GitHub NEVER runs a workflow from a target dir. Compare it against ${composedName}, move anything it still needs, then delete ${targetPath}/.github/workflows/${name}`);
 }
 
 // Is every line of the target's copy a line the current template still ships, in
@@ -559,7 +559,7 @@ function sweepTargetCopy(context) {
 // same file minus those lines, #334). A line the consumer ADDED or CHANGED is a
 // line no template of this framework ever shipped, so it fails here and the
 // copy is kept. Accepted blind spot: an edit that ONLY deletes lines is still a
-// subsequence and gets swept — bounded, because a target-dir workflow never runs
+// subsequence and gets swept. Bounded, because a target-dir workflow never runs
 // and the composed root file is regenerated from the current template.
 function isFrameworkGeneration(existing, rendered) {
   const template = rendered.split('\n');
@@ -587,7 +587,7 @@ function pruneEmptyDirs(dir, rootDir) {
   }
 }
 
-// posix-style target path — this string ends up inside a YAML workflow.
+// posix-style target path: this string ends up inside a YAML workflow.
 function relativePath(from, to) {
   return path.relative(from, to).split(path.sep).join('/');
 }
@@ -596,14 +596,14 @@ function relativePath(from, to) {
 // the file is framework-owned AND which target it belongs to, which is what
 // makes the reconcile able to tell a composed file from a brand's own workflow
 // without guessing from the name alone.
-const generatedMark = (targetPath) => `# GENERATED by the ${targetPath} framework scaffold — do not edit.`;
-// Reading accepts the LEGACY wording too (`# GENERATED by \`omega setup\` for
-// <targetPath> — do not edit.`): a target dropped before the rewording keeps its
-// old-header file forever, which is exactly the file the reconcile exists to
-// remove. Composing only ever writes the current sentence.
-const GENERATED_MARK = /^# GENERATED by (?:the (\S+) framework scaffold|`omega setup` for (\S+)) — do not edit\.$/;
-
-// Which target a brand-root workflow file was composed for — null when the file
+const generatedMark = (targetPath) => `# GENERATED by the ${targetPath} framework scaffold. Do not edit.`;
+// Reading also accepts the older forms (the `omega setup` wording, the em dash
+// separator): a dropped target keeps its old-header file forever, which is exactly
+// the file the reconcile exists to remove. Composing only ever writes the current
+// sentence.
+const GENERATED_MARK = /^# GENERATED by (?:the (\S+) framework scaffold|`omega setup` for (\S+))(?:\. Do| \u2014 do) not edit\.$/;
+
+// Which target a brand-root workflow file was composed for, null when the file
 // is not a composed one. BOTH locks must hold: the generation mark on line 1,
 // and the `<target>-<framework file>.yml` naming the compose writes.
 function composedWorkflowOwner(name, contents) {
@@ -633,4 +633,4 @@ function header(targetPath) {
   ].join('\n');
 }
 
-module.exports = { composeWorkflow, composeTargetWorkflows, composedWorkflowName, composedWorkflowNameFor, reconcileComposedWorkflows, renderInstallFirewall, renderInstallWorkspace, FIREWALL_ACTION, FIREWALL_STEP_ID, FIREWALL_TOKEN, INSTALL_WORKSPACE_TOKEN, INSTALL_WORKSPACE_FLAG };
+module.exports = { composeWorkflow, composeTargetWorkflows, composedWorkflowName, composedWorkflowNameFor, composedWorkflowOwner, reconcileComposedWorkflows, renderInstallFirewall, renderInstallWorkspace, FIREWALL_ACTION, FIREWALL_STEP_ID, FIREWALL_TOKEN, INSTALL_WORKSPACE_TOKEN, INSTALL_WORKSPACE_FLAG };

package/dist/vendor/devkit/cli-router.js

@@ -27,6 +27,7 @@ const jetpack = require('fs-jetpack');
  * @param {string} config.commandsDir - Absolute directory of command modules — <name>.js exporting `async (options) => {}`
  * @param {Object<string, string[]>} [config.aliases] - Command name → positional/flag aliases (e.g. `{ install: ['-i', 'i', '--install'] }`)
  * @param {string} [config.defaultCommand='help'] - Command used when no positional or flag alias matches
+ * @param {Function} [config.fallback] - `(command) => handler|null`: the handler for a command with no file, else null for the unknown answer
  * @returns {Function} Main class — bins do `new Main(argv)` then `await main.process(argv)`
  */
 function createCliRouter(config) {
@@ -35,6 +36,7 @@ function createCliRouter(config) {
   const commandsDir = config.commandsDir;
   const aliases = config.aliases || {};
   const defaultCommand = config.defaultCommand || 'help';
+  const fallback = config.fallback || null;
 
   if (!commandsDir) {
     throw new Error('[devkit cli-router] commandsDir is required');
@@ -114,14 +116,18 @@ function createCliRouter(config) {
 
     // Get the command file path
     const commandFile = path.join(commandsDir, `${command}.js`);
+    const exists = jetpack.exists(commandFile);
 
-    if (!jetpack.exists(commandFile)) {
-      // Built-in help (a framework's own commands/help.js would have won above)
-      if (command === 'help') {
-        printHelp();
-        return;
-      }
+    // Built-in help (a framework's own commands/help.js would have won above)
+    if (!exists && command === 'help') {
+      printHelp();
+      return;
+    }
+
+    // A router can own verbs it keeps no file for; a null handler is the unknown answer
+    const handler = !exists && fallback ? fallback(command) : null;
 
+    if (!exists && !handler) {
       // Unknown command: name the valid surface and fail loud — the old path
       // threw a doubled "Error executing… Error: Command…" with no listing.
       // An empty listing means the dist itself is broken, not a typo — say so.
@@ -137,7 +143,7 @@ function createCliRouter(config) {
 
     try {
       // Execute the command
-      const Command = require(commandFile);
+      const Command = handler || require(commandFile);
       await Command(options);
     } catch (e) {
       // The command's own error is the only surface — no wrapper prefix, no

package/dist/vendor/devkit/defaults-engine.js

@@ -1,40 +1,8 @@
-// applyDefaults(config) — the shared OMEGA defaults-scaffolding engine.
-//
-// Every framework ships a defaults tree (src/defaults/ → dist/defaults/) that
-// setup copies into the consumer project. This is the single plain-fs engine
-// every framework's scaffold runs.
-//
-// File-map rules: minimatch patterns (dot:true) matched against the RAW path
-// relative to defaultsDir, last-match-wins option merging. Per-rule options:
-//   overwrite  bool|fn(item)  default true — write even if the destination exists
-//   skip       bool|fn(item)  default false — never process this file
-//   name       fn(item)       rename the output file
-//   path       fn(item)       re-destination the output (relative dir)
-//   template   object         render `{{ key.path }}` tokens with this data
-//                             (tolerant: unknown keys survive verbatim, so GitHub
-//                             Actions' `${{ secrets.X }}` passes through)
-//   merge      bool           JSON5 defaults-merge with the existing file, written
-//                             through @omega.js/config's comment-preserving editor
-//                             (only the differing keys change; comments stay)
-//   mergeLines bool           OMEGA marker-section line merge (.env/.gitignore/AGENTS.md)
-//   retire     bool           brand-context per-target doc retirement: NEVER scaffold
-//                             the file; an existing framework-owned-only copy is
-//                             DELETED (one-time heal — the brand root is the doc
-//                             home), a copy carrying consumer content stays with a
-//                             loud move-it warning (never destroyed)
-//
-// Engine built-ins (not expressed in the file map):
-//   - `_.name` segments lose the leading `_` (dotfiles ship past npm's filter)
-//   - non-final segments starting `_` (but not `_.`) are ARCHIVE dirs — skipped
-//     (reference material that ships in the framework package, e.g. desktop's `_mas/`)
-//   - `.gitkeep` creates the destination directory, the file itself never copies
-//   - `.DS_Store` never copies
-//   - text writes are skipped when the destination is byte-identical (idempotent
-//     re-runs report zero writes)
-//   - a destination carrying the OMEGA section markers when the current template
-//     no longer does is a PRIOR-GENERATION generated file: framework-owned, so
-//     `retire` sweeps it and `overwrite: false` still heals it
-//   - binary files (by extension) copy verbatim — never templated/merged/transformed
+// applyDefaults(config): the ONE plain-fs defaults-scaffolding engine every
+// framework's scaffold runs, copying its defaults tree into the consumer
+// project. The file-map options (overwrite, skip, name, path, template, merge,
+// mergeLines, retire), the built-ins and the minimatch matching rules live in
+// docs/devkit/index.md.
 
 const path = require('path');
 const fs = require('fs');
@@ -264,12 +232,10 @@ function isFrameworkOwned(existing, rendered) {
   return existing.trim() === rendered.trim();
 }
 
-// A generation change: the destination carries the OMEGA marker grammar — which
-// only this framework's own scaffold writes — while the current template has
-// dropped it. That file is a PRIOR GENERATION's generated copy (e.g. the
-// content-bearing CLAUDE.md written before it became the one-line `@AGENTS.md`
-// pointer), so comparing it against the current render can never match and the
-// framework, not the consumer, owns it.
+// A generation change: the destination carries the OMEGA marker grammar (only
+// this framework's scaffold writes it) while the current template dropped it.
+// That file is a PRIOR GENERATION's copy: it can never match the current
+// render, and the framework, not the consumer, owns it.
 function isLegacyMarkerArtifact(existing, rendered) {
   return hasSectionMarkers(existing) && !hasSectionMarkers(rendered);
 }

package/dist/vendor/devkit/deploy-snapshot.js

@@ -59,6 +59,7 @@ const { setTimeout: delay } = require('node:timers/promises');
 const jetpack = require('fs-jetpack');
 const { resolveCompany, COMPANY_RESOLVED_FILE } = require('../config/index.js');
 const { gitAuthEnv, scrubToken } = require('./git-auth.js');
+const { composedWorkflowOwner } = require('./ci-workflows.js');
 
 // Constants
 const API_BASE = 'https://api.github.com';
@@ -342,7 +343,9 @@ async function defaultBranchOf({ owner, repo, token, fetchFn = fetch }) {
  * this write exists, and it is the only write a deploy ever makes to a default
  * branch (Ian, 2026-09-14: "if all we are pushing to main is the gh workflow
  * files that's fine"). Each file's bytes are compared with what the branch
- * holds; when every one matches, nothing is written at all.
+ * holds; when every one matches, nothing is written at all. A branch file
+ * that carries the GENERATED header and is no longer composed (a renamed or
+ * dropped target) is RETIRED in the same commit; a hand-written one never is.
  *
  * Through the git DATA api, never a working-tree commit: blobs, a tree on top
  * of the branch's own, a commit whose parent is its head. An EMPTY repo (no
@@ -356,14 +359,14 @@ async function defaultBranchOf({ owner, repo, token, fetchFn = fetch }) {
  * @param {string} options.token - The GitHub token.
  * @param {Function} [options.fetchFn] - Injectable fetch (tests).
  * @param {object} [options.logger] - Logger with `log` (silent when omitted).
- * @returns {Promise<{ pushed: string[], sha: string|null }>} What was written.
+ * @returns {Promise<{ pushed: string[], removed: string[], sha: string|null }>} What was written.
  */
 async function pushWorkflowFiles({ brandRoot, owner, repo, branch, token, fetchFn = fetch, logger }) {
   const files = composedWorkflowFiles(brandRoot);
 
   if (files.length === 0) {
     if (logger) logger.log(`No composed workflow in ${brandRoot}/${WORKFLOWS_DIR}: ${branch} is untouched.`);
-    return { pushed: [], sha: null };
+    return { pushed: [], removed: [], sha: null };
   }
 
   const call = async (route, init) => {
@@ -399,9 +402,31 @@ async function pushWorkflowFiles({ brandRoot, owner, repo, branch, token, fetchF
     }
   }
 
-  if (changed.length === 0) {
+  // What the branch holds that this brand no longer composes. The same double
+  // lock as the local prune: the GENERATED header and the composed naming, so
+  // a hand-written workflow is never a candidate. No listing means no files.
+  const composed = new Set(files.map((file) => file.name));
+  const listing = await read(
+    await call(`/contents/${WORKFLOWS_DIR}?ref=${encodeURIComponent(branch)}`),
+    [200, 404],
+    `Listing ${WORKFLOWS_DIR}`,
+  );
+  const retired = [];
+
+  for (const entry of listing || []) {
+    if (entry.type !== 'file' || !entry.name.endsWith('.yml') || composed.has(entry.name)) {
+      continue;
+    }
+
+    const held = await read(await call(`/contents/${entry.path}?ref=${encodeURIComponent(branch)}`), [200], `Reading ${entry.name}`);
+    if (composedWorkflowOwner(entry.name, Buffer.from(held.content || '', 'base64').toString('utf8'))) {
+      retired.push({ name: entry.name, path: entry.path });
+    }
+  }
+
+  if (changed.length === 0 && retired.length === 0) {
     if (logger) logger.log(`${owner}/${repo}#${branch} already carries ${files.map((file) => file.name).join(', ')}: nothing pushed to ${branch}.`);
-    return { pushed: [], sha: null };
+    return { pushed: [], removed: [], sha: null };
   }
 
   // The head this commit sits on. A repo with no commit at all answers 404, and
@@ -422,15 +447,21 @@ async function pushWorkflowFiles({ brandRoot, owner, repo, branch, token, fetchF
     );
     tree.push({ path: file.path, mode: '100644', type: 'blob', sha: blob.sha });
   }
+  for (const file of retired) {
+    tree.push({ path: file.path, mode: '100644', type: 'blob', sha: null });
+  }
 
-  const names = changed.map((file) => file.name).join(', ');
+  const names = [
+    ...(changed.length ? [`compose ${changed.map((file) => file.name).join(', ')}`] : []),
+    ...(retired.length ? [`retire ${retired.map((file) => file.name).join(', ')}`] : []),
+  ].join(', ');
   const written = await read(
     await call('/git/trees', { method: 'POST', body: JSON.stringify({ ...(baseTree ? { base_tree: baseTree } : {}), tree }) }),
     [201],
     'Writing the tree',
   );
   const commit = await read(
-    await call('/git/commits', { method: 'POST', body: JSON.stringify({ message: `chore(ci): compose ${names}`, tree: written.sha, parents }) }),
+    await call('/git/commits', { method: 'POST', body: JSON.stringify({ message: `chore(ci): ${names}`, tree: written.sha, parents }) }),
     [201],
     'Writing the commit',
   );
@@ -444,10 +475,14 @@ async function pushWorkflowFiles({ brandRoot, owner, repo, branch, token, fetchF
   );
 
   if (logger) {
-    logger.log(`Pushed ${changed.map((file) => `${file.name} (${file.reason})`).join(', ')} to ${owner}/${repo}#${branch} as ${shortSha(commit.sha)}: GitHub registers a workflow from the default branch.`);
+    const touched = [
+      ...changed.map((file) => `${file.name} (${file.reason})`),
+      ...retired.map((file) => `${file.name} (retired)`),
+    ];
+    logger.log(`Pushed ${touched.join(', ')} to ${owner}/${repo}#${branch} as ${shortSha(commit.sha)}: GitHub registers a workflow from the default branch.`);
   }
 
-  return { pushed: changed.map((file) => file.name), sha: commit.sha };
+  return { pushed: changed.map((file) => file.name), removed: retired.map((file) => file.name), sha: commit.sha };
 }
 
 /**

package/dist/vendor/devkit/env-lines.js

@@ -0,0 +1,183 @@
+/**
+ * The .env line grammar the marker engine merges by and every in-place key
+ * writer sets keys by: logical lines (a quoted value spanning several physical
+ * lines is one unit), the key a line assigns, the double-quote normalization,
+ * and the replace-or-append of a key's lines. dotenv is the reader every OMEGA loader
+ * uses, so it is the judge: a normalized line must read back to the same value,
+ * and a key's winning line is its LAST one, as dotenv reads it.
+ */
+const dotenv = require('dotenv');
+const { envLine } = require('../config/index.js');
+
+// An assignment dotenv accepts: optional indent and `export `, then KEY=
+const ASSIGNMENT = /^(\s*(?:export\s+)?)([\w.-]+)\s*=(.*)$/s;
+const QUOTED_OPEN = /^\s*(?:export\s+)?[\w.-]+\s*=\s*(["'`])/;
+
+/**
+ * The index of the quote closing a value opened at `from`, as dotenv picks it:
+ * a quote after a backslash may close the value or be passed, the first quote
+ * after no backslash cannot be passed, and dotenv takes the LAST closing
+ * candidate followed on its line by only whitespace or a `# comment`, so
+ * `K="x\"` reads `x\`. -1 when none closes it.
+ *
+ * @param {string} text
+ * @param {string} quote - `"`, `'` or a backtick
+ * @param {number} from - First index after the opening quote
+ * @returns {number}
+ */
+function closingQuote(text, quote, from) {
+  const lineRest = /[^\S\n]*(?:#[^\n]*)?(?:\n|$)/y;
+  let close = -1;
+  for (let i = from; i < text.length; i += 1) {
+    if (text[i] !== quote) continue;
+    lineRest.lastIndex = i + 1;
+    if (lineRest.test(text)) close = i;
+    if (text[i - 1] !== '\\') break;
+  }
+  return close;
+}
+
+/**
+ * Group physical lines into logical ones: a quoted value that closes on a later
+ * line joins those lines (newlines kept) into one unit, so it moves and
+ * survives whole. An unterminated quote stays line by line, as dotenv reads it.
+ *
+ * @param {string[]} lines - The file split on `\n`
+ * @returns {string[]}
+ */
+function joinEnvUnits(lines) {
+  const units = [];
+  for (let i = 0; i < lines.length; i += 1) {
+    const open = lines[i].match(QUOTED_OPEN);
+    const rest = open ? lines.slice(i).join('\n') : '';
+    const close = open ? closingQuote(rest, open[1], open[0].length) : -1;
+    if (close < 0) {
+      units.push(lines[i]);
+      continue;
+    }
+
+    const end = i + rest.slice(0, close).split('\n').length - 1;
+    units.push(lines.slice(i, end + 1).join('\n'));
+    i = end;
+  }
+  return units;
+}
+
+/**
+ * The key a line assigns, or null for a comment, a blank, or anything else.
+ *
+ * @param {string} line
+ * @returns {string|null}
+ */
+function envKey(line) {
+  const match = line.match(ASSIGNMENT);
+  return match ? match[2] : null;
+}
+
+// The inline comment after a raw value: past the closing quote of a quoted
+// value, from the first `#` of an unquoted one.
+function trailingComment(raw) {
+  let rest = raw;
+  if (raw[0] === "'" || raw[0] === '`') {
+    const close = closingQuote(raw, raw[0], 1);
+    if (close >= 0) rest = raw.slice(close + 1);
+  }
+  const hash = rest.indexOf('#');
+  return hash < 0 ? '' : rest.slice(hash).trim();
+}
+
+/**
+ * Normalize one .env line to the double-quoted form: `KEY=raw` and `KEY='x'`
+ * become `KEY="..."`, an inline comment kept; an empty value becomes `KEY=""`;
+ * a double-quoted value, a comment and a blank are left alone. The rewrite
+ * happens only when dotenv reads the same value back; otherwise the line stays.
+ *
+ * @param {string} line - One logical line
+ * @returns {string}
+ */
+function normalizeEnvLine(line) {
+  const match = line.match(ASSIGNMENT);
+  if (!match) return line;
+  const [, prefix, key, rawValue] = match;
+  const raw = rawValue.trim();
+
+  if (raw === '') return `${prefix}${key}=""`;
+  if (raw.startsWith('"')) return line;
+
+  const value = dotenv.parse(line)[key];
+  if (value === undefined) return line;
+
+  let quoted;
+  try {
+    quoted = envLine(key, value);
+  } catch (e) {
+    // envLine refuses a value dotenv would read back changed: the line stays
+    return line;
+  }
+  const comment = trailingComment(raw);
+  const candidate = `${prefix}${quoted}${comment ? ` ${comment}` : ''}`;
+  return dotenv.parse(candidate)[key] === value ? candidate : line;
+}
+
+/**
+ * The line that sets `key`: the LAST one, the value dotenv reads.
+ *
+ * @param {string[]} lines
+ * @param {string} key
+ * @returns {string} - `KEY=""` when no line sets it
+ */
+function findKeyLine(lines, key) {
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    if (envKey(lines[i]) === key) return lines[i];
+  }
+  return `${key}=""`;
+}
+
+// A placeholder, `# KEY=""` or a bare `# KEY=`, → KEY; any other comment → null.
+function parsePlaceholderKey(trimmed) {
+  const match = trimmed.match(/^#\s*([A-Za-z_][A-Za-z0-9_]*)=\s*(?:"")?\s*$/);
+  return match ? match[1] : null;
+}
+
+/**
+ * Set keys in .env content by logical line: the first unit assigning a key, or
+ * its `# KEY=""` placeholder, becomes the given line and every later one drops,
+ * so dotenv reads the new value; a key the content never had is appended.
+ * Every other line keeps its place.
+ *
+ * @param {string} content - Current file content ('' for none)
+ * @param {Object<string, string>} lineFor - KEY to its whole line, e.g. envLine's
+ * @returns {string} The new content, ending in exactly one newline
+ */
+function setEnvLines(content, lineFor) {
+  const body = content.replace(/(?:\r?\n)+$/, '');
+  const seen = new Set();
+
+  const out = joinEnvUnits(body === '' ? [] : body.split(/\r?\n/)).flatMap((unit) => {
+    const key = envKey(unit) ?? parsePlaceholderKey(unit.trim());
+    if (key === null || !Object.hasOwn(lineFor, key)) return [unit];
+    if (seen.has(key)) return [];
+    seen.add(key);
+    return [lineFor[key]];
+  });
+  for (const key of Object.keys(lineFor)) {
+    if (!seen.has(key)) out.push(lineFor[key]);
+  }
+  return `${out.join('\n')}\n`;
+}
+
+// The framework's own .env comment grammar: a boxed group header or a
+// `# KEY=""` placeholder. Regenerated from the template, never a consumer's note.
+function isMachineComment(trimmed) {
+  return /^# ── .* ──$/.test(trimmed) || parsePlaceholderKey(trimmed) !== null;
+}
+
+// KEY= / KEY="" / KEY='' (whitespace tolerated) count as empty.
+function envValueIsEmpty(line) {
+  const eqIdx = line.indexOf('=');
+  if (eqIdx < 0) return true;
+  const value = line.slice(eqIdx + 1).trim();
+  return value === '' || value === '""' || value === "''";
+}
+
+module.exports = { joinEnvUnits, envKey, normalizeEnvLine, findKeyLine, parsePlaceholderKey, isMachineComment, envValueIsEmpty, setEnvLines };