@omega.js/manager 0.1.0

package/dist/lib/framework-bin.js

@@ -0,0 +1,156 @@
+/**
+ * Resolve a framework's `omega` bin FILE via the node_modules directory climb
+ * from where the target declares it. A manual walk (not require.resolve) because
+ * exports-restricted packages don't expose ./package.json. Shared by the
+ * brand-root fan-out commands (`omega test`, `omega deploy`).
+ *
+ * Also the ONE place those commands decide HOW to run a verb on a target, so
+ * the framework lane and the custom-target lane (#603) never drift apart:
+ * a framework target dispatches through its own `omega <verb>` bin with the
+ * brand's flags forwarded; a custom target runs `npm run <verb>` in its dir
+ * with NO flags (a package script has no contract for them) and steps aside
+ * loudly when it declares no such script.
+ *
+ * A backend in CUSTOM-SERVER mode (#584) takes the script lane for the verbs
+ * its framework cannot serve — `omega deploy` is a Functions deploy and
+ * `omega test` is the emulator lane, and both REFUSE in that mode. It stays a
+ * framework target for everything else; a container host's publish command is
+ * the brand's to name, and its `deploy` script is where it names it.
+ *
+ * A framework that does not SERVE a verb at all takes the same lane
+ * (SCRIPT_LANE_VERBS): dispatching it would only print "Unknown command".
+ */
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { findTarget } = require('../vendor/devkit/omega-bin.js');
+const { targetScripts } = require('./custom-target.js');
+
+// The verbs @omega.js/backend serves through Firebase and therefore refuses in
+// custom-server mode (#584) — the fan-outs take the script lane for these, and
+// only these. `build`, `update` and the rest are mode-agnostic.
+const FIREBASE_ONLY_VERBS = new Set(['deploy', 'test']);
+
+// Framework → the verbs its CLI has no command for, which the fan-outs must
+// run as the target's own script instead (#603). EMPTY today: every framework
+// serves every fan-out verb, @omega.js/extension's `build` included since
+// [#81](https://github.com/Omega-JS-Stack/omega/issues/81) gave it the verb
+// its siblings already had. The mechanism stays for the next gap.
+const SCRIPT_LANE_VERBS = {};
+
+// The verbs NO framework CLI honors `--dry-run` for (checked against web,
+// backend and desktop `build`/`clean`: none reads the flag). Forwarding it
+// would really build — or really CLEAN — under a flag whose whole promise is
+// that nothing happens, so the dry run stops at the plan for the framework
+// lane too, exactly as it already does for the script lane. `deploy` is the
+// counter-case and stays off this list: every framework deploy reads the flag
+// and prints its own dispatch plan.
+const NO_FRAMEWORK_DRY_RUN_VERBS = new Set(['build', 'clean']);
+
+/**
+ * @param {string} fromDir - Directory to climb from (where the dep is declared)
+ * @param {string} name - Framework package name ('@omega.js/web', …)
+ * @returns {string|null} - Absolute bin path, or null when not installed
+ */
+function resolveFrameworkBin(fromDir, name) {
+  const resolved = resolveFrameworkPackage(fromDir, name);
+  if (!resolved) return null;
+
+  const bin = typeof resolved.pkg.bin === 'string' ? resolved.pkg.bin : (resolved.pkg.bin || {}).omega;
+  return bin ? path.join(resolved.dir, bin) : null;
+}
+
+/**
+ * The framework package itself, via the same climb — for readers of its
+ * manifest declarations (`projectScripts`, the workspace target heal).
+ *
+ * @param {string} fromDir - Directory to climb from (where the dep is declared)
+ * @param {string} name - Framework package name ('@omega.js/web', …)
+ * @returns {{ dir: string, pkg: object }|null} - null when not installed
+ */
+function resolveFrameworkPackage(fromDir, name) {
+  let dir = path.resolve(fromDir);
+
+  while (true) {
+    const pkgDir = path.join(dir, 'node_modules', name);
+    const pkgPath = path.join(pkgDir, 'package.json');
+
+    if (fs.existsSync(pkgPath)) {
+      return { dir: pkgDir, pkg: JSON.parse(fs.readFileSync(pkgPath, 'utf8')) };
+    }
+
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * How the brand-root fan-out should run `verb` on one discovered target.
+ *
+ * @param {object} entry - A discoverTargets entry ({ name, dir, path, target, custom, projectType }).
+ * @param {string} verb - The verb ('deploy', 'test', …).
+ * @param {string[]} [forwarded] - Brand-level flags to forward (framework lane only).
+ * @param {object} [options]
+ * @param {boolean} [options.dryRun] - The run is a dry run: any lane that cannot
+ *   hand the flag on returns kind:'plan' instead of a command.
+ * @returns {{ kind: 'framework'|'custom'|'plan'|'skip'|'error', label?: string,
+ *   command?: string, args?: string[], framework?: string, detail?: string }}
+ */
+function resolveTargetRun(entry, verb, forwarded = [], options = {}) {
+  // The SCRIPT lane — the target's own `npm run <verb>`, which is the whole
+  // verb surface of a custom target and the fallback for a framework that
+  // cannot serve this one.
+  const scriptLane = () => {
+    const scripts = targetScripts(entry.path);
+    if (!scripts[verb]) {
+      return { kind: 'skip', detail: `no "${verb}" script in ${entry.dir}/package.json` };
+    }
+
+    // A framework target honors --dry-run itself; a package script has no
+    // such contract and the flag is not forwarded to it, so the dry run stops
+    // HERE and reports the plan. Running a real deploy under --dry-run would
+    // be the worst possible reading of the flag.
+    if (options.dryRun) {
+      return { kind: 'plan', detail: `would run npm run ${verb} in ${entry.dir}` };
+    }
+
+    return { kind: 'custom', command: 'npm', args: ['run', verb], label: `npm run ${verb}` };
+  };
+
+  if (entry.custom || (entry.projectType === 'custom' && FIREBASE_ONLY_VERBS.has(verb))) {
+    return scriptLane();
+  }
+
+  const target = findTarget(entry.path);
+  if (!target || target.kind !== 'framework') {
+    return { kind: 'error', detail: 'no framework dependency detected (target-root package.json)' };
+  }
+
+  // A verb this framework's CLI has no command for is the target's script to
+  // run, not a bin dispatch that would fail on "Unknown command"
+  if (SCRIPT_LANE_VERBS[target.name]?.has(verb)) {
+    return scriptLane();
+  }
+
+  const binPath = resolveFrameworkBin(target.dir, target.name);
+  if (!binPath) {
+    return { kind: 'error', detail: `${target.name} is not installed (node_modules climb from ${target.dir} found no bin)` };
+  }
+
+  // A verb its own CLI has no --dry-run for stops at the plan HERE, like the
+  // script lane — the flag is never forwarded to a bin that would ignore it
+  if (options.dryRun && NO_FRAMEWORK_DRY_RUN_VERBS.has(verb)) {
+    return { kind: 'plan', framework: target.name, detail: `would run omega ${verb} in ${entry.dir}` };
+  }
+
+  return {
+    kind: 'framework',
+    framework: target.name,
+    command: process.execPath,
+    args: [binPath, verb, ...forwarded],
+    label: `omega ${verb} ${forwarded.join(' ')}`.trimEnd(),
+  };
+}
+
+module.exports = { resolveFrameworkBin, resolveFrameworkPackage, resolveTargetRun };

package/dist/lib/gitignore.js

@@ -0,0 +1,63 @@
+/**
+ * Shared gitignore ensure — the secrets store, the environment env files, run
+ * output, and the run logs never get committed. Used by the workspace service
+ * (brand roots) and runCompany (the company root, which no service pass touches).
+ *
+ * The scaffold writes every entry into a NEW brand's .gitignore; this heals
+ * every root that predates an entry, on its next manage run (#197: `logs/`;
+ * [#586](https://github.com/Omega-JS-Stack/omega/issues/586): `.env.*`).
+ */
+
+const { join } = require('node:path');
+const jetpack = require('fs-jetpack');
+
+const IGNORE_ENTRY = '.omega/';
+
+// Every entry a root's .gitignore must carry: the aliases that already satisfy
+// it, and the comment introducing a freshly added one (matching the scaffold's).
+const ENTRIES = [
+  {
+    entry: IGNORE_ENTRY,
+    aliases: ['.omega', '.omega/'],
+    comment: '# Omega manager state (durable IDs + per-run output)',
+  },
+  {
+    entry: 'logs/',
+    aliases: ['logs', 'logs/'],
+    comment: '# Run logs (truncated on every launch — never committed)',
+  },
+  {
+    // `.env` itself is the scaffold's, and every brand already carries it; this
+    // is the environment OVERLAY half (#586), which is just as much a secret
+    entry: '.env.*',
+    aliases: ['.env.*', '.env*'],
+    comment: '# Secrets — the environment overlays beside .env',
+  },
+];
+
+/**
+ * Ensure `.omega/`, `logs/` and `.env.*` are listed in {rootDir}/.gitignore.
+ * Idempotent — only the missing entries get appended, each under its own comment.
+ *
+ * @param {string} rootDir - Directory whose .gitignore gets the entries
+ * @returns {'present'|'added'}
+ */
+function ensureOmegaIgnored(rootDir) {
+  const gitignorePath = join(rootDir, '.gitignore');
+  const existing = jetpack.read(gitignorePath) || '';
+
+  const lines = existing.split('\n').map((line) => line.trim());
+  const missing = ENTRIES.filter(({ aliases }) => !lines.some((line) => aliases.includes(line)));
+
+  if (missing.length === 0) {
+    return 'present';
+  }
+
+  const separator = existing.length > 0 && !existing.endsWith('\n') ? '\n' : '';
+  const block = missing.map(({ entry, comment }) => `\n${comment}\n${entry}\n`).join('');
+  jetpack.write(gitignorePath, existing + separator + block);
+
+  return 'added';
+}
+
+module.exports = { ensureOmegaIgnored, IGNORE_ENTRY };