@omega.js/desktop 0.53.0 → 0.54.1

package/dist/vendor/config/validate.js

@@ -1,39 +1,19 @@
 /**
- * Schema-driven validation for resolved omega.json5 configs.
- *
- * The rule walker (runSchema) carries required/type/match/enum semantics, where match +
- * enum (and itemEnum, the same check per member of an array value) only run on
- * PRESENT values and a conditional `required` function
- * receives the full config. See schema.js for the rule format.
- *
- * validateConfig() layers on top of the walker:
- *   - SHARED_SCHEMA always runs; TARGET_SCHEMAS[options.target] adds that
- *     target's refinements against the same resolved top-level namespace
- *   - `targets` sanity (#886): every key is a target NAME, so it must be a
- *     dir-safe slug, and every entry must be an object declaring a `type` the
- *     framework list knows (an ARRAY is the retired multi-instance form, whose
- *     replacement is a sibling key; >1 backend target is a WARNING)
- *   - the `repo` block (#883): one `provider` from REPO_PROVIDERS, and an `org`
- *     that is a real non-empty string whenever the block is there, because the
- *     org is the owner of every repo the brand's names derive under
- *   - `hosting` (#883) is a WEB target's key: a non-web target carrying it says
- *     something nothing serves, and its provider comes from HOSTING_PROVIDERS
- *   - `cloud.config.authDomain`, when set, must be the brand's OWN host (the
- *     resolved target url, else brand.url): a firebaseapp.com value or a
- *     mismatch is an error, and demo-* (emulator-only) projects are exempt
- *   - retired keys are always errors (see retired-keys.js) — a name that was
- *     renamed outright reads as nothing at all, so it fails loudly instead of
- *     losing its settings silently
- *   - secret-shaped keys are always errors (see secrets.js) — loadConfig
- *     additionally hard-fails on them before any merge happens
- *   - keys the schema does not declare are WARNINGS (#636): the walker only
- *     ever visits declared paths, so a typo — or a live path nobody declared —
- *     used to pass in silence
+ * Schema-driven validation for resolved omega.json5 configs. runSchema walks
+ * the rules (required/type/match/enum/itemEnum, the value checks only on a
+ * PRESENT value; schema.js has the rule format). validateConfig() adds the
+ * target's refinements, the `targets` sanity (each key a dir-safe NAME, each
+ * entry a known `type`), the `repo` block and web-only `hosting`, the brand's
+ * own authDomain, the price and feature shapes, and secret-shaped keys. The
+ * schema is STRICT: a path no rule declares is an error, one line per path,
+ * naming `omega migrate`. The validator knows only the present shape; the
+ * migrate verb is the one code that knows an old name.
  */
 
-const { TARGETS, SHARED_SCHEMA, TARGET_SCHEMAS } = require('./schema.js');
+const { TARGETS, SHARED_SCHEMA, TARGET_SCHEMAS, isCustomTargetEntry } = require('./schema.js');
 const { findSecretKeys } = require('./secrets.js');
-const { findRetiredKeys } = require('./retired-keys.js');
+const { CLIENT_FACT_KEYS } = require('./client-config.js');
+const { RESOLVED_COMPANY_KEYS } = require('./company.js');
 const { isPlainObject } = require('./merge.js');
 const { TARGET_NAME_PATTERN, TARGET_TYPES } = require('./targets.js');
 const { REPO_PROVIDERS, HOSTING_PROVIDERS } = require('./repo.js');
@@ -43,6 +23,14 @@ const { isCountedFeature } = require('../account/features.js');
 // Firebase's own default authDomain shape: a third-party host by definition
 const FIREBASE_AUTH_DOMAIN = /\.firebaseapp\.com$/;
 
+// The company facts the loader fills: a staged compose output carries them on
+// purpose, and the loader refuses a TYPED one in a brand or company file.
+const RESOLVED_PATHS = RESOLVED_COMPANY_KEYS.map((key) => `company.${key}`);
+
+// The build facts a surface bakes AFTER the load: declared only for
+// `decorated: true`, the re-validation of a baked config (a desktop boot).
+const BUILD_FACT_PATHS = CLIENT_FACT_KEYS;
+
 /**
  * Read a dotted path out of a config object — the path resolver the schema
  * walk and the env presence checker (env-rules.js) share.
@@ -419,24 +407,23 @@ function validateFeatures(config) {
 }
 
 /**
- * The LEAF paths of a resolved config the schema does not declare (#636).
- *
- * A rule declares its own path AND everything beneath it — an `object`/`array`
- * rule is a declared subtree (brand.address's postal fields, an open provider
- * map), which is what keeps a brand's own data out of this list. An empty
- * object/array is itself a leaf, declared when the schema declares anything
- * below it (`certificates: {}` against certificates.enabled).
- *
- * The `targets` subtree is skipped whole: those keys belong to a framework or,
- * for a custom target (#603), to the brand — the targets-sanity check above is
- * what polices that namespace.
- *
- * @param {object} config - The resolved config object.
+ * The LEAF paths of a config the schema does not declare. A rule declares its
+ * own path; an `object`/`array` rule opens its whole subtree only when no rule
+ * is declared beneath it (or it says `open: true`), so a section with typed
+ * keys stays closed. An empty object/array (or a `false` off switch) is a leaf,
+ * declared when the schema declares anything below it. `targets` is skipped
+ * whole: each target's own load judges its entry.
+ * @param {object} config - The config object.
  * @param {object[]} schema - Rule array in the schema.js entry format.
+ * @param {string[]} [written] - Paths framework code wrote onto a decorated config, each open.
  * @returns {string[]} Undeclared leaf paths, in config order.
  */
-function findUndeclaredPaths(config, schema) {
-  const declared = schema.map((rule) => rule.path);
+function findUndeclaredPaths(config, schema, written = []) {
+  const paths = [...schema.map((rule) => rule.path), ...written];
+  const open = schema
+    .filter((rule) => /\b(object|array)\b/.test(rule.type || '') && (rule.open || !paths.some((other) => other.startsWith(`${rule.path}.`))))
+    .map((rule) => rule.path)
+    .concat(written);
   const found = [];
 
   const walk = (value, path) => {
@@ -444,9 +431,10 @@ function findUndeclaredPaths(config, schema) {
       Object.keys(value).forEach((key) => walk(value[key], `${path}.${key}`));
       return;
     }
-    if (!declared.some((rule) => rule === path || path.startsWith(`${rule}.`) || rule.startsWith(`${path}.`))) {
-      found.push(path);
-    }
+    const declared = paths.includes(path)
+      || open.some((rule) => path.startsWith(`${rule}.`))
+      || paths.some((rule) => rule.startsWith(`${path}.`));
+    if (!declared) found.push(path);
   };
 
   Object.keys(isPlainObject(config) ? config : {})
@@ -456,25 +444,69 @@ function findUndeclaredPaths(config, schema) {
   return found;
 }
 
+/**
+ * The rules a target's resolved config answers to: shared + its refinements.
+ * @param {string} [target] - Canonical target name; omitted = shared only.
+ * @returns {object[]}
+ */
+function schemaFor(target) {
+  if (target && !TARGETS.includes(target)) {
+    throw new Error(`Unknown target "${target}": must be one of [${TARGETS.join(', ')}]`);
+  }
+
+  return target ? [...SHARED_SCHEMA, ...TARGET_SCHEMAS[target]] : SHARED_SCHEMA;
+}
+
+/**
+ * The paths a config carries that no rule declares, for one target's view:
+ * what the strict check fails, for a caller (a converter) that drops them.
+ * @param {object} config - A resolved config (a target's keys at the top level).
+ * @param {object} [options]
+ * @param {string} [options.target]
+ * @returns {string[]} Undeclared leaf paths, in config order.
+ */
+function undeclaredPaths(config, options) {
+  return findUndeclaredPaths(config, schemaFor((options || {}).target), RESOLVED_PATHS);
+}
+
+/**
+ * Every path of an AUTHORED config (one omega.json5 as written) the strict
+ * schema refuses: the whole file, `targets` left to its targets, then each
+ * framework target entry the way its own load sees it (hoisted to the top
+ * level). A target's OWN file names its type, since its top level is that
+ * target's layer. A custom target's keys are its own; an unknown type is the
+ * targets check's to report.
+ * @param {object} config - One file's parsed config.
+ * @param {object} [options]
+ * @param {string} [options.target] - The type whose own file this is.
+ * @returns {string[]} Dotted paths as the file spells them.
+ */
+function undeclaredAuthoredPaths(config, options) {
+  const found = undeclaredPaths(config, { target: (options || {}).target });
+  const targets = isPlainObject(config) && isPlainObject(config.targets) ? config.targets : {};
+
+  for (const [name, entry] of Object.entries(targets)) {
+    if (!isPlainObject(entry) || isCustomTargetEntry(entry) || !TARGETS.includes(entry.type)) continue;
+    found.push(...undeclaredPaths(entry, { target: entry.type }).map((dotted) => `targets.${name}.${dotted}`));
+  }
+
+  return found;
+}
+
 /**
  * Validate a resolved config: shared schema + optional target refinements +
  * targets-key sanity + secret-shaped-key detection.
  * @param {object} config - The resolved config object.
  * @param {object} [options]
  * @param {string} [options.target] - Canonical target name; adds TARGET_SCHEMAS[target].
+ * @param {boolean} [options.decorated] - The config already carries a build's
+ *   facts (a baked config, validated again at boot).
  * @returns {{ errors: string[], warnings: string[] }}
  */
 function validateConfig(config, options) {
   options = options || {};
 
-  if (options.target && !TARGETS.includes(options.target)) {
-    throw new Error(`Unknown target "${options.target}" — must be one of [${TARGETS.join(', ')}]`);
-  }
-
-  const schema = options.target
-    ? [...SHARED_SCHEMA, ...TARGET_SCHEMAS[options.target]]
-    : SHARED_SCHEMA;
-
+  const schema = schemaFor(options.target);
   const errors = runSchema(config, schema);
   const warnings = [];
 
@@ -573,25 +605,13 @@ function validateConfig(config, options) {
   // ─── the features catalog and the values products name (#647) ──────────
   validateFeatures(config).forEach((error) => errors.push(error));
 
-  // ─── undeclared paths (#636) ───────────────────────────────────────────
-  // A warning, never an error: a brand config outliving one framework version
-  // must still build, and the finding is what closes the gap — either the key
-  // is dead, or the schema owes it a rule.
-  const undeclared = findUndeclaredPaths(config, schema);
-  if (undeclared.length > 0) {
-    warnings.push(
-      'config carries keys the schema does not declare — nothing reads them, so a typo looks exactly like a '
-      + `feature. Remove them, or give each one a rule in @omega.js/config's schema.js `
-      + `(docs/shared/config.md → Validation): ${undeclared.join(', ')}`,
-    );
-  }
-
-  // ─── retired keys (#142) ───────────────────────────────────────────────
-  findRetiredKeys(config).forEach(({ path, replacement, why }) => {
+  // ─── the schema is strict ──────────────────────────────────────────────
+  // A key nothing declares is a key nothing reads: a typo or a legacy shape.
+  // One line per path, so a brand sees every key it has to move or delete.
+  findUndeclaredPaths(config, schema, options.decorated ? [...RESOLVED_PATHS, ...BUILD_FACT_PATHS] : RESOLVED_PATHS).forEach((path) => {
     errors.push(
-      `config.${path} is retired — the key is now "${replacement}" (${why}). `
-      + `Rename it; there is no dual-read, so the old name is silently ignored `
-      + `(docs/shared/config.md → "Migration — legacy configs")`,
+      `config.${path} is not a key the schema declares. Remove it, or if it is a legacy key run `
+      + '`npx omega migrate` at the brand root (report) and `--execute` to convert (docs/shared/config.md → Validation)',
     );
   });
 
@@ -610,4 +630,4 @@ function formatErrors(errors) {
   return errors.map((e, i) => `  ${i + 1}. ${e}`).join('\n');
 }
 
-module.exports = { validateConfig, runSchema, formatErrors, getPath, resolvedBrandHost };
+module.exports = { validateConfig, undeclaredPaths, undeclaredAuthoredPaths, runSchema, formatErrors, getPath, resolvedBrandHost };

package/dist/vendor/devkit/agents-md.js

@@ -0,0 +1,233 @@
+/**
+ * The ONE builder of a project-root AGENTS.md, a brand root and a framework
+ * used alone alike, written through the one marker engine: the Default section
+ * imports the installed manager's AGENTS.md (which imports the omega map from
+ * the docs the manager ships), the Custom section holds the project's own
+ * notes, verbatim. Every older shape converges once, its notes kept under
+ * Custom. A brand target carries none: its brand root is the doc home.
+ */
+const { join } = require('node:path');
+const fs = require('node:fs');
+const jetpack = require('fs-jetpack');
+const { mergeLineBasedFiles, hasSectionMarkers, getCustomSection, isShipped, sectionMarkers, DEFAULT_MARKER } = require('./merge-line-files');
+
+const FILE_NAME = 'AGENTS.md';
+const GUIDE_SUBPATH = 'node_modules/@omega.js/manager/AGENTS.md';
+const IMPORT_LINE = `@${GUIDE_SUBPATH}`;
+// The retired scope-level link: an import of it is healed away and the link
+// itself removed.
+const RETIRED_SUBPATH = 'node_modules/@omega.js/AGENTS.md';
+
+const SCOPE_PREFIXES = ['', '../', '../../', '../../../'];
+
+// The skeleton heading earlier builders wrote under the import.
+const NOTES_HEADING = /^# .+: (project|brand) notes$/;
+
+/**
+ * Is this line an import of the manager's AGENTS.md or the retired scope link
+ * (any relative depth)?
+ *
+ * @param {string} line - A single file line
+ * @returns {boolean}
+ */
+function isImportLine(line) {
+  const trimmed = line.trim();
+  return trimmed.startsWith('@') && (trimmed.endsWith(GUIDE_SUBPATH) || trimmed.endsWith(RETIRED_SUBPATH));
+}
+
+/**
+ * The @omega.js scope directory serving this project: its own node_modules
+ * normally, an ancestor's when hoisted (npm workspaces). Only a scope holding
+ * the manager counts: an empty dir from a partial install would leave the
+ * import dangling while the real scope sits a level up.
+ *
+ * @param {string} root - Absolute project root
+ * @returns {{prefix: string, scopeDir: string}|null}
+ */
+function findScope(root) {
+  for (const prefix of SCOPE_PREFIXES) {
+    const scopeDir = join(root, prefix, 'node_modules', '@omega.js');
+    if (jetpack.exists(join(scopeDir, 'manager')) === 'dir') {
+      return { prefix, scopeDir };
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolve the import line for THIS project: the depth that reaches the scope
+ * holding the manager. Falls back to the canonical project-local path when
+ * the manager is not installed, so the line still names where the docs live.
+ *
+ * @param {string} root - Absolute project root
+ * @returns {string} - The `@<relative path>` import line
+ */
+function resolveImportLine(root) {
+  const scope = findScope(root);
+  return scope ? `@${scope.prefix}${GUIDE_SUBPATH}` : IMPORT_LINE;
+}
+
+/**
+ * Remove the retired `node_modules/@omega.js/AGENTS.md` link (or a stale file
+ * in its place) from the scope serving this brand.
+ *
+ * @param {string} brandRoot - Absolute brand monorepo root
+ * @param {{ dryRun?: boolean }} [options] - dryRun: the same verdict, nothing removed
+ * @returns {'removed'|'absent'} - What happened
+ */
+function removeRetiredLink(brandRoot, { dryRun = false } = {}) {
+  const scope = findScope(brandRoot);
+  const link = scope && join(scope.scopeDir, 'AGENTS.md');
+  if (!link || !fs.lstatSync(link, { throwIfNoEntry: false })) {
+    return 'absent';
+  }
+  if (!dryRun) {
+    fs.rmSync(link, { force: true });
+  }
+  return 'removed';
+}
+
+/**
+ * Render a fresh project-root AGENTS.md: the import under the Default marker,
+ * then the Custom marker and nothing below it.
+ *
+ * @param {string} [importLine] - The resolved import line
+ * @returns {string} - Full file content
+ */
+function renderAgentsMd(importLine = IMPORT_LINE) {
+  const { defaultMarker, customMarker } = sectionMarkers(FILE_NAME);
+  return `${defaultMarker}\n${importLine}\n\n${customMarker}\n`;
+}
+
+/**
+ * Is this the retired per-framework template? It OPENS with the `#` Default
+ * marker; a file that merely quotes the markers in its notes is not one.
+ *
+ * @param {string} content - The AGENTS.md content
+ * @returns {boolean}
+ */
+function isRetiredTemplate(content) {
+  return content.split('\n')[0].trim() === DEFAULT_MARKER && hasSectionMarkers(content);
+}
+
+/**
+ * The notes a consumer wrote in an AGENTS.md of any shape, trimmed: the Custom
+ * section of a marked or retired-template file, else the whole file, minus
+ * every line a framework wrote (the import, the skeleton heading, shipped
+ * boilerplate).
+ *
+ * @param {string} content - The AGENTS.md content
+ * @returns {string} - '' when the file holds nothing the framework did not write
+ */
+function consumerNotes(content) {
+  const source = hasSectionMarkers(content, FILE_NAME)
+    ? getCustomSection(content, FILE_NAME)
+    : isRetiredTemplate(content) ? getCustomSection(content) : content;
+  return source.split('\n')
+    .filter((line) => !isImportLine(line) && !NOTES_HEADING.test(line.trim()) && !isShipped(line, FILE_NAME))
+    .join('\n')
+    .trim();
+}
+
+/**
+ * Ensure the project-root AGENTS.md is the marked shape with the resolved
+ * import. A marked file goes through the engine (the Default section healed,
+ * the Custom section verbatim); any other shape converges, its notes landing
+ * under Custom in order.
+ *
+ * @param {string} root - Absolute project root
+ * @param {{ dryRun?: boolean }} [options] - dryRun: the same verdict, nothing written
+ * @returns {'present'|'created'|'healed'|'converged'} - What happened
+ */
+function ensureAgentsMd(root, { dryRun = false } = {}) {
+  const file = join(root, FILE_NAME);
+  const template = renderAgentsMd(resolveImportLine(root));
+  const existing = jetpack.read(file);
+
+  if (existing === undefined) {
+    if (!dryRun) jetpack.write(file, template);
+    return 'created';
+  }
+
+  const marked = hasSectionMarkers(existing, FILE_NAME);
+  const next = mergeLineBasedFiles(marked ? existing : consumerNotes(existing), template, FILE_NAME);
+  if (next === existing) {
+    return 'present';
+  }
+  if (!dryRun) jetpack.write(file, next);
+  return marked ? 'healed' : 'converged';
+}
+
+/**
+ * Keep a brand target free of any AGENTS.md: the brand root is its doc home. A
+ * copy holding nothing the consumer wrote is removed; one with notes stays.
+ *
+ * @param {string} targetDir - Absolute brand target root
+ * @returns {'absent'|'removed'|'kept'} - What happened
+ */
+function retireAgentsMd(targetDir) {
+  const file = join(targetDir, 'AGENTS.md');
+  const existing = jetpack.read(file);
+
+  if (existing === undefined) {
+    return 'absent';
+  }
+  if (consumerNotes(existing)) {
+    return 'kept';
+  }
+  jetpack.remove(file);
+  return 'removed';
+}
+
+/**
+ * A framework scaffold's AGENTS.md step, recorded into the defaults engine's
+ * result and logged the way the engine logs: a standalone project root gets
+ * the builder's file; a brand target gets none.
+ *
+ * @param {object} options
+ * @param {string} options.outputDir - Absolute project or target root
+ * @param {boolean} options.standalone - True when no brand root sits above it
+ * @param {{written: string[], merged: string[], skipped: string[], removed: string[]}} options.result - The engine result to record into
+ * @param {object} [options.logger] - `{ log, warn }` (defaults to console)
+ */
+function scaffoldAgentsMd({ outputDir, standalone, result, logger = console }) {
+  if (!standalone) {
+    const verdict = retireAgentsMd(outputDir);
+    if (verdict === 'removed') {
+      result.removed.push('AGENTS.md');
+      logger.warn('Retired AGENTS.md: a brand target carries none, the brand root AGENTS.md is the one doc home');
+    } else if (verdict === 'kept') {
+      result.skipped.push('AGENTS.md');
+      logger.warn('Kept AGENTS.md: it carries consumer content. A brand target carries no AGENTS.md: move those notes under the Custom marker of the brand root AGENTS.md, then delete the file');
+    }
+    return;
+  }
+
+  const verdict = ensureAgentsMd(outputDir);
+  if (verdict === 'created') {
+    result.written.push('AGENTS.md');
+    logger.log('Scaffolded → AGENTS.md');
+  } else if (verdict === 'healed') {
+    result.merged.push('AGENTS.md');
+    logger.log('Healed → AGENTS.md: the Default section imports the manager, your Custom section kept');
+  } else if (verdict === 'converged') {
+    result.merged.push('AGENTS.md');
+    logger.warn('Converged AGENTS.md to the marker sections: the manager import under Default, your notes under Custom');
+  } else {
+    result.skipped.push('AGENTS.md');
+  }
+}
+
+module.exports = {
+  GUIDE_SUBPATH,
+  IMPORT_LINE,
+  RETIRED_SUBPATH,
+  isImportLine,
+  findScope,
+  resolveImportLine,
+  removeRetiredLink,
+  renderAgentsMd,
+  ensureAgentsMd,
+  retireAgentsMd,
+  scaffoldAgentsMd,
+};

package/dist/vendor/devkit/attach-log-file.js

@@ -25,7 +25,8 @@
 // Two attaches on ONE tee stack the same way: a second attach of a DIFFERENT path pushes a
 // layer on top of the first instead of replacing it, so a verb that runs another verb in
 // process (`omega test` running `omega deploy`) keeps teeing both files. Detach order is
-// LIFO, and the module-level `detach()` pops the newest layer.
+// LIFO, and the module-level `detach()` pops the newest layer. A harness that runs a verb
+// takes `mark()` first and calls the restore it returns after, never a blind `detach()`.
 //
 // Skipped in CI: a runner has its own log capture and wants no logs/ left in the workspace.
 // `attachInCI: true` opts out of that skip, for a sink whose file is the POINT rather than
@@ -142,8 +143,20 @@ function createTee() {
     return detach;
   }
 
+  // A harness around a verb restores to the mark instead of popping blind: a run can
+  // push one layer, several, or none, and only what it pushed comes off, newest first.
+  function mark() {
+    const kept = layers.slice();
+    return function restore() {
+      for (const layer of layers.slice().reverse()) {
+        if (!kept.includes(layer)) { layer.detach(); }
+      }
+    };
+  }
+
   return {
     attach,
+    mark,
     detach: () => {
       const newest = layers[layers.length - 1];
       if (newest) { newest.detach(); }
@@ -265,6 +278,7 @@ function attachLogFile(filePath, options) {
 
 module.exports = attachLogFile;
 module.exports.detach         = singleton.detach;
+module.exports.mark           = singleton.mark;
 module.exports.stripAnsi      = stripAnsi;
 module.exports.createTee      = createTee;
 module.exports.createChildLog = createChildLog;