@pugi/cli 0.1.0-beta.1 → 0.1.0-beta.100

package/dist/core/mcp/orchestrator-config.js

@@ -0,0 +1,192 @@
+/**
+ * Pugi MCP orchestrator config (Trust Sprint item 7).
+ *
+ * BEFORE this module the customer had to wire three independent gates
+ * to actually run the orchestrator surface successfully:
+ *
+ *   PUGI_MCP_EXEC_ENABLED=1   (env)   — gates pugi.run + pugi.dispatch
+ *   --allow-bash              (flag)  — surfaces the bash permission class
+ *   PUGI_MCP_PUGI_BIN=...     (env)   — points the dispatcher at a binary
+ *
+ * Missing any one of the three produced an opaque "tool refused" or
+ * "binary not found" error that nobody could correlate back to the
+ * three-knob configuration. Codex deep-research 2026-06-04 logged this
+ * as a discipline gap.
+ *
+ * AFTER this module the customer flips ONE switch:
+ *
+ *   PUGI_MCP_ORCHESTRATOR=1
+ *
+ * Or one flag:
+ *
+ *   pugi mcp serve --orchestrator-bundle
+ *
+ * Either form:
+ *   - enables exec gating on pugi.run + pugi.dispatch,
+ *   - turns on the bash permission class (equivalent to --allow-bash),
+ *   - auto-resolves `pugi` from PATH (or the local dev binary when
+ *     invoked from a monorepo checkout).
+ *
+ * The legacy multi-knob configuration continues to work as deprecated
+ * aliases. When the legacy combo is observed at boot we emit a stderr
+ * warning so operators know they should migrate.
+ *
+ * Scope rule: this module is ADDITIVE. It does not modify
+ * orchestrator-tools.ts or the dispatch handler (other agent owns
+ * those files in PUGI-VERIFY-GATE).
+ */
+import { existsSync } from 'node:fs';
+import { dirname, isAbsolute, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+import { warnDeprecation } from '../../runtime/deprecation-warning.js';
+/**
+ * Resolve the effective orchestrator configuration from inputs.
+ *
+ * Single source of truth for the gate-collapse logic. `runtime/commands/
+ * mcp.ts` consumes the result; tests call this function directly.
+ */
+export function resolveOrchestratorConfig(input) {
+    const env = input.env;
+    const bundleViaEnv = env.PUGI_MCP_ORCHESTRATOR === '1';
+    const bundleViaFlag = input.bundleFlag;
+    const bundleEnabled = bundleViaEnv || bundleViaFlag;
+    const execViaLegacyEnv = env.PUGI_MCP_EXEC_ENABLED === '1';
+    const publishViaLegacyEnv = env.PUGI_MCP_PUBLISH_ENABLED === '1';
+    const deployViaLegacyEnv = env.PUGI_MCP_DEPLOY_ENABLED === '1';
+    const bashViaFlag = input.bashFlag;
+    // Bundle implies exec + bash. Publish + deploy stay opt-in even under
+    // bundle because they cross network boundaries (npm publish, ssh
+    // deploy) — operator should still flip them deliberately.
+    const execEnabled = bundleEnabled || execViaLegacyEnv;
+    const publishEnabled = publishViaLegacyEnv;
+    const deployEnabled = deployViaLegacyEnv;
+    const bashAllowed = bundleEnabled || bashViaFlag;
+    // Emit deprecation warning the first time we see the OLD multi-flag
+    // combo without the bundle flag. We only warn if the operator clearly
+    // intended the orchestrator surface (at least one legacy env set) so
+    // bare engine-surface runs stay silent.
+    if (!bundleEnabled && execViaLegacyEnv) {
+        warnDeprecation('PUGI_MCP_EXEC_ENABLED', 'PUGI_MCP_ORCHESTRATOR=1', 'Single flag enables exec + bash + auto-resolves the pugi binary in one step.');
+    }
+    const { pugiBin, pugiBinSource } = resolvePugiBin({
+        envOverride: env.PUGI_MCP_PUGI_BIN ?? null,
+        workspaceRoot: input.workspaceRoot,
+        resolveBinary: input.resolveBinary ?? defaultBinaryResolver,
+    });
+    return {
+        bundleEnabled,
+        execEnabled,
+        publishEnabled,
+        deployEnabled,
+        bashAllowed,
+        pugiBin,
+        source: {
+            bundleViaEnv,
+            bundleViaFlag,
+            execViaLegacyEnv,
+            publishViaLegacyEnv,
+            deployViaLegacyEnv,
+            bashViaFlag,
+            pugiBinSource,
+        },
+    };
+}
+/**
+ * Resolve the `pugi` binary path. Layered fallback so operators get a
+ * working dispatcher whether they `npm i -g @pugi/cli`-ed it (PATH),
+ * baked it into env (CI), or are running from a monorepo checkout
+ * (where `pugi` is not on PATH but `dist/index.js` exists).
+ */
+function resolvePugiBin(input) {
+    if (input.envOverride && input.envOverride.length > 0) {
+        return { pugiBin: input.envOverride, pugiBinSource: 'env' };
+    }
+    const fromPath = input.resolveBinary('pugi');
+    if (fromPath && fromPath.length > 0) {
+        return { pugiBin: fromPath, pugiBinSource: 'path-lookup' };
+    }
+    const devBinary = findMonorepoDevBinary(input.workspaceRoot);
+    if (devBinary) {
+        return { pugiBin: devBinary, pugiBinSource: 'monorepo-dev-binary' };
+    }
+    // Last-resort fallback. The downstream `execFile` will throw ENOENT
+    // with a path readable error; better that than us swallowing the
+    // intent of "operator wanted orchestrator mode" silently.
+    return { pugiBin: 'pugi', pugiBinSource: 'fallback' };
+}
+/**
+ * Walk up from the workspace root looking for the monorepo pugi-cli
+ * checkout. Used when an operator runs `pugi mcp serve --orchestrator-
+ * bundle` from inside a freshly-cloned `pugi-io/pugi` repo without a
+ * global install. Skipped for non-monorepo workspaces (returns null
+ * quickly when the expected marker files are absent).
+ */
+function findMonorepoDevBinary(workspaceRoot) {
+    const candidates = [];
+    // Common shapes: workspaceRoot IS the monorepo, or workspaceRoot is
+    // a sibling sub-app of pugi-cli. Limit the walk to two levels up.
+    let current = workspaceRoot;
+    for (let i = 0; i < 4; i += 1) {
+        candidates.push(resolve(current, 'apps/pugi-cli/dist/index.js'));
+        candidates.push(resolve(current, 'apps/pugi-cli/bin/run.js'));
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    for (const candidate of candidates) {
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+/**
+ * Default `which`-backed binary resolver. Mirrors the pattern used by
+ * `resolveExecutablePath` in `runtime/commands/mcp.ts`. Returns null
+ * on any failure — the caller falls back to the next layer.
+ */
+function defaultBinaryResolver(command) {
+    if (isAbsolute(command)) {
+        return existsSync(command) ? command : null;
+    }
+    if (command.includes('/') || command.includes('\\'))
+        return null;
+    try {
+        const out = execFileSync('/usr/bin/which', [command], {
+            stdio: ['ignore', 'pipe', 'ignore'],
+            encoding: 'utf8',
+            timeout: 5000,
+        }).trim();
+        return out.length > 0 ? out : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Compose a human-readable diagnostic line per resolved config. Used
+ * by `pugi mcp serve --orchestrator*` startup output and `pugi doctor`
+ * so operators can verify which gates ended up live.
+ */
+export function describeOrchestratorConfig(config) {
+    const lines = [];
+    lines.push(`bundle: ${config.bundleEnabled ? 'on' : 'off'}`);
+    lines.push(`exec: ${config.execEnabled ? 'on' : 'off'}`);
+    lines.push(`publish: ${config.publishEnabled ? 'on' : 'off'}`);
+    lines.push(`deploy: ${config.deployEnabled ? 'on' : 'off'}`);
+    lines.push(`bash surfaced: ${config.bashAllowed ? 'on' : 'off'}`);
+    lines.push(`pugi binary: ${config.pugiBin} (source: ${config.source.pugiBinSource})`);
+    return lines;
+}
+/**
+ * Exported for tests so the dev-binary fallback can be exercised
+ * without invoking the full resolver. Kept internal to the module
+ * otherwise.
+ */
+export const _internalForTests = {
+    findMonorepoDevBinary,
+    resolvePugiBin,
+    currentModuleDir: () => dirname(fileURLToPath(import.meta.url)),
+};
+//# sourceMappingURL=orchestrator-config.js.map