@groundnuty/macf 0.2.17 → 0.2.18

package/dist/cli/env-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-files.d.ts","sourceRoot":"","sources":["../../src/cli/env-files.ts"],"names":[],"mappings":"AAyCA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAiHnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAwB3C;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CA6BnE;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAkEjE;AAMD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CA+BhE;AAMD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAuCnE;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,eAAe,EACvB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,CA8DR;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAiC/D;AAMD;;;;;;;;GAQG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,eAAe,GACtB,mBAAmB,CA2BrB"}

package/dist/cli/env-files.js

@@ -0,0 +1,585 @@
+/**
+ * Per-concern env-file generators for the multi-file workspace env layout
+ * (groundnuty/macf#342). PR-A of a 4-PR sequence:
+ *
+ *   PR-A (this PR)  — pure generators only; no init/update wiring
+ *   PR-B            — refactor claude.sh to source the per-concern files
+ *                     + wire writers into init/update
+ *   PR-C            — migration: detect legacy monolithic claude.sh +
+ *                     compat with settings.local.json env block
+ *   PR-D            — operator docs
+ *
+ * Each generator takes a `MacfAgentConfig` and returns the textual content
+ * for one per-concern env file written under `<workspace>/.claude/.macf/`.
+ *
+ * Concern boundaries (operator-managed vs macf-managed) come from #342:
+ *   env.identity   — macf-managed   — identity vars (set BEFORE tmux self-wrap)
+ *   env.github     — macf-managed   — App creds + GH_TOKEN mint + git ident
+ *                                     (EMPTY in local-mode per DR-024)
+ *   env.certs      — macf-managed   — cert + log paths
+ *   env.registry   — macf-managed   — MACF_REGISTRY_TYPE + per-type vars
+ *   env.telemetry  — operator-managed — OTel gates + endpoint
+ *                                       (MINIMAL when MACF_OTEL_DISABLED=1)
+ *   env.tmux       — operator-managed — MACF_TMUX_SESSION + MACF_TMUX_WINDOW
+ *                                       (MINIMAL when neither set in config)
+ *
+ * **Pure functions** — no file I/O, no side effects. Disk writes land in
+ * PR-B's `writeEnvFiles()` helper.
+ *
+ * **Faithful reproduction** — each generator emits the SAME export-line
+ * shapes as the existing monolithic `claude-sh.ts`. The per-concern logic
+ * is duplicated here rather than imported from `claude-sh.ts` because the
+ * existing helpers (`registryEnvLines`, `caPathLines`,
+ * `githubAppEnvLines`, `githubTokenAndIdentityLines`) are file-private.
+ * PR-B will extract a shared util module and dedup.
+ *
+ * **Schema versioning** — each emitted file carries a `# schema_version: 1`
+ * comment near the top so PR-C's migration tool (and any future bumps) can
+ * detect the format version without parsing.
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+// ---------------------------------------------------------------------------
+// Headers
+// ---------------------------------------------------------------------------
+/**
+ * Header text for macf-managed files. Mirrors the warning shape in
+ * `claude-sh.ts`'s `MANAGED_HEADER_LINES` so operators see consistent
+ * "do not edit" framing across all generated files. Edit the canonical
+ * generator and re-run `macf update`.
+ */
+function managedHeaderLines(generator) {
+    return [
+        '# This file is managed by `macf`. Do not edit directly — edits are',
+        '# overwritten on the next `macf update`. The template lives at',
+        `# groundnuty/macf:src/cli/env-files.ts (\`${generator}\`). To change`,
+        '# the generated content, file an issue or PR against that file, then',
+        '# run `macf update` here.',
+        '#',
+        '# This file is sourced (not executed) by claude.sh; vars use `export`',
+        '# so they propagate to claude\'s child processes.',
+    ];
+}
+/**
+ * Header text for operator-managed files. Softer wording than the macf-
+ * managed variant — operators are free to edit, and `macf update`
+ * preserves their changes (PR-B + PR-C wire that contract; this file just
+ * declares the intent in the header).
+ */
+function operatorHeaderLines(generator) {
+    return [
+        `# This file is operator-editable. \`macf update\` will preserve your`,
+        `# edits as long as the file exists; the canonical default content`,
+        `# is generated by ${generator} in groundnuty/macf:src/cli/env-files.ts`,
+        '# and re-emitted only when the file is missing entirely.',
+        '#',
+        '# This file is sourced (not executed) by claude.sh; vars use `export`',
+        '# so they propagate to claude\'s child processes.',
+    ];
+}
+/**
+ * Header text for the `env._helpers` library file. Macf-managed (operators
+ * shouldn't override the helper definitions ad-hoc), but framed as a
+ * library/sourced-utility rather than a config file — no var exports, just
+ * function definitions consumed by sibling env.* files.
+ */
+function libraryHeaderLines(generator) {
+    return [
+        '# This file is managed by `macf`. Do not edit directly — edits are',
+        '# overwritten on the next `macf update`. The template lives at',
+        `# groundnuty/macf:src/cli/env-files.ts (\`${generator}\`). To change`,
+        '# the generated content, file an issue or PR against that file, then',
+        '# run `macf update` here.',
+        '#',
+        '# This is a LIBRARY file: it defines shell FUNCTIONS used by the other',
+        '# env.* files when claude.sh sources them. The underscore prefix sorts',
+        '# this file BEFORE alphabetical-letter siblings under `env.*`, so the',
+        '# functions are defined before any caller is sourced (function-not-',
+        '# defined hazard guard).',
+    ];
+}
+const SCHEMA_VERSION_LINE = '# schema_version: 1';
+/**
+ * Assemble final file content from header + body lines. Joins with `\n`
+ * and ensures trailing newline. The schema_version line goes right after
+ * the header so it's the first non-comment-block content.
+ */
+function assemble(header, body) {
+    return [
+        ...header,
+        SCHEMA_VERSION_LINE,
+        '',
+        ...body,
+        '',
+    ].join('\n');
+}
+// ---------------------------------------------------------------------------
+// Local-mode + path helpers (mirrored from claude-sh.ts; PR-B dedup target)
+// ---------------------------------------------------------------------------
+/**
+ * True when this config runs in local-registry mode (DR-024 / macf#322).
+ * Mirrored from `claude-sh.ts`'s file-private `isLocalMode`.
+ */
+function isLocalMode(cfg) {
+    return cfg.registry.type === 'local';
+}
+/**
+ * Compute POSIX-style dirname without pulling in node:path. Mirrored from
+ * `claude-sh.ts`'s file-private `posixDirname`. The launcher always runs
+ * on POSIX-shaped filesystems (DR-024 §threat model).
+ */
+function posixDirname(p) {
+    const idx = p.lastIndexOf('/');
+    if (idx < 0)
+        return '.';
+    if (idx === 0)
+        return '/';
+    return p.slice(0, idx);
+}
+// ---------------------------------------------------------------------------
+// env._helpers — macf-managed; library file, sourced first per alphabetical order
+// ---------------------------------------------------------------------------
+/**
+ * Generate `.claude/.macf/env._helpers` content.
+ *
+ * Defines shell helper FUNCTIONS used by sibling env.* files. The
+ * underscore prefix sorts this file BEFORE alphabetical-letter siblings
+ * (`env.certs`, `env.github`, `env.identity`, etc.), so when claude.sh
+ * sources `env.*` in alphabetical order via shell glob, this file's
+ * functions are defined before any caller is sourced.
+ *
+ * Currently exports one helper:
+ *
+ *   macf_settings_get(var_name)
+ *     Reads `.env.<var_name>` from `<workspace>/.claude/settings.local.json`
+ *     via jq. Returns empty string if the file/key is missing or jq isn't
+ *     installed. Used by:
+ *       - env.identity   — 3-layer settings priority for MACF_AGENT_NAME / ROLE
+ *       - env.telemetry  — 4-layer endpoint chain for MACF_OTEL_ENDPOINT
+ *
+ * **No exports** — this is a function-definition file. Sourcing it has
+ * no observable effect beyond making functions callable in the sourcing
+ * shell. macf#313 introduced the helper inline in claude.sh; macf#342
+ * extracted it here so multiple env.* files can share it without each
+ * file having to redeclare it (PR-A had `macf_settings_get` duplicated
+ * inside generateEnvIdentity to make env.identity self-contained;
+ * macf#342 PR-B moves the single source-of-truth into env._helpers).
+ *
+ * Pure function — no I/O. Doesn't take a config arg because the helper
+ * body is config-independent (it reads from settings.local.json at
+ * runtime, not from baked values).
+ */
+export function generateEnvHelpers() {
+    const body = [
+        '# Generator: generateEnvHelpers (env-files.ts)',
+        '#',
+        '# Sourced by claude.sh BEFORE any sibling env.* file (underscore prefix',
+        '# sorts before alphabetical letters in shell glob expansion). Defines',
+        '# helper functions used by env.identity (3-layer priority for AGENT_NAME',
+        '# / ROLE) and env.telemetry (4-layer endpoint chain). Single source of',
+        '# truth — pre-#342 the helper was inlined in claude.sh; pre-#342 PR-B',
+        '# it was duplicated inside generateEnvIdentity. This file dedupes both.',
+        '',
+        '# Settings-driven identity helper (macf#313). Reads `.env.<NAME>` from',
+        '# .claude/settings.local.json via jq; returns empty string if file/key',
+        '# missing or jq absent. Identity-override blocks use it to prefer',
+        '# operator-edited settings.local.json over baked defaults, without',
+        '# forcing operators to edit any generated env.* file.',
+        'macf_settings_get() {',
+        '  local var_name="$1"',
+        '  if [ -f "$SCRIPT_DIR/.claude/settings.local.json" ] && command -v jq >/dev/null 2>&1; then',
+        '    jq -r ".env.${var_name} // empty" "$SCRIPT_DIR/.claude/settings.local.json" 2>/dev/null',
+        '  fi',
+        '}',
+    ];
+    return assemble(libraryHeaderLines('generateEnvHelpers'), body);
+}
+// ---------------------------------------------------------------------------
+// env.identity — macf-managed
+// ---------------------------------------------------------------------------
+/**
+ * Generate `.claude/.macf/env.identity` content.
+ *
+ * The 5 identity vars currently set BEFORE the tmux self-wrap in
+ * `claude-sh.ts`:
+ *
+ *   MACF_WORKSPACE_DIR  — absolute path to the workspace (cross-repo cwd
+ *                          safety, see #161 + coordination.md)
+ *   MACF_PROJECT        — project name
+ *   MACF_AGENT_NAME     — agent identifier (with 3-layer settings priority)
+ *   MACF_AGENT_ROLE     — agent role (with 3-layer settings priority)
+ *   MACF_AGENT_TYPE     — `permanent` | `worker`
+ *
+ * MACF_AGENT_NAME and MACF_AGENT_ROLE preserve the post-#313 settings-driven
+ * 3-layer priority (env > settings.local.json > baked default). Reading
+ * settings.local.json requires the `macf_settings_get` helper, which is
+ * defined in `env._helpers` (sourced before this file alphabetically by
+ * claude.sh's `for f in env.*` glob — underscore prefix sorts first).
+ *
+ * **Note on SCRIPT_DIR**: `MACF_WORKSPACE_DIR=$SCRIPT_DIR` requires that
+ * the sourcing script (claude.sh) sets SCRIPT_DIR before sourcing. That
+ * contract is documented in claude.sh; this file trusts it.
+ */
+export function generateEnvIdentity(config) {
+    const body = [
+        `# Generator: generateEnvIdentity (env-files.ts)`,
+        `# Sourced by claude.sh BEFORE the tmux self-wrap so identity vars are`,
+        `# present in the env captured by the \`-e VAR=VAL\` pass-through (macf#340).`,
+        '#',
+        '# `macf_settings_get` is defined in env._helpers (sourced first per',
+        '# alphabetical order — underscore prefix sorts before letters). Calls',
+        '# below resolve at runtime against the function defined there.',
+        '',
+        '# Cross-repo path resolution (#140 + #161). Runtime templates reference',
+        '# $MACF_WORKSPACE_DIR for absolute-path commands so cd-ing to another',
+        '# repo doesn\'t break helper invocations.',
+        'export MACF_WORKSPACE_DIR="$SCRIPT_DIR"',
+        `export MACF_PROJECT="${config.project}"`,
+        `export MACF_AGENT_TYPE="${config.agent_type}"`,
+        '',
+        '# Settings-driven identity overrides (macf#313). Three-layer priority:',
+        '#   1. Already-set env var (operator: `MACF_AGENT_NAME=foo ./claude.sh`)',
+        '#   2. .claude/settings.local.json `env` block',
+        '#   3. Baked default from macf init/update (this generated file)',
+        `MACF_AGENT_NAME="\${MACF_AGENT_NAME:-$(macf_settings_get MACF_AGENT_NAME)}"`,
+        `MACF_AGENT_NAME="\${MACF_AGENT_NAME:-${config.agent_name}}"`,
+        'export MACF_AGENT_NAME',
+        `MACF_AGENT_ROLE="\${MACF_AGENT_ROLE:-$(macf_settings_get MACF_AGENT_ROLE)}"`,
+        `MACF_AGENT_ROLE="\${MACF_AGENT_ROLE:-${config.agent_role}}"`,
+        'export MACF_AGENT_ROLE',
+    ];
+    return assemble(managedHeaderLines('generateEnvIdentity'), body);
+}
+// ---------------------------------------------------------------------------
+// env.github — macf-managed; EMPTY in local-mode
+// ---------------------------------------------------------------------------
+/**
+ * Generate `.claude/.macf/env.github` content.
+ *
+ * Emits APP_ID / INSTALL_ID / KEY_PATH App-cred exports + the relative-
+ * path resolver + the fail-loud `macf-gh-token.sh` invocation + git
+ * author/committer name exports.
+ *
+ * **Empty placeholder in local-mode** (cfg.registry.type === 'local',
+ * DR-024). The body is just the header + schema_version + a comment
+ * explaining why — no GitHub App tokens are minted in local-registry
+ * mode (commits land as the local user, not as `app/<bot>[bot]`). The
+ * absence of GH_TOKEN-mint logic is what makes local-mode work without
+ * GitHub credentials.
+ */
+export function generateEnvGitHub(config) {
+    if (isLocalMode(config)) {
+        const body = [
+            '# Generator: generateEnvGitHub (env-files.ts)',
+            '#',
+            '# Intentionally empty for local-mode workspace. Per DR-024 / macf#322,',
+            '# local-registry mode does not mint a GitHub App installation token —',
+            '# coordination uses the local registry file at $MACF_REGISTRY_PATH, and',
+            '# commits land as the local user (not as `app/<bot>[bot]`). No APP_ID,',
+            '# INSTALL_ID, KEY_PATH, GH_TOKEN, or GIT_AUTHOR_NAME/GIT_COMMITTER_NAME',
+            '# are exported. See DR-024 §"Routing trade-offs".',
+            `echo "Starting ${config.agent_name} (${config.agent_role}) [local-registry mode]..."`,
+        ];
+        return assemble(managedHeaderLines('generateEnvGitHub'), body);
+    }
+    const githubApp = config.github_app;
+    // Defensive — schema marks github_app optional, but non-local mode
+    // requires it (init.ts enforces the pairing at write time per
+    // config.ts comments). If it's missing here, the workspace config is
+    // broken; surface that visibly rather than emitting partial exports.
+    if (!githubApp) {
+        const body = [
+            '# Generator: generateEnvGitHub (env-files.ts)',
+            '#',
+            '# WARNING: this workspace config has registry.type !== "local" but no',
+            '# `github_app` block. Re-run `macf init --force` to repair.',
+        ];
+        return assemble(managedHeaderLines('generateEnvGitHub'), body);
+    }
+    const body = [
+        '# Generator: generateEnvGitHub (env-files.ts)',
+        '',
+        '# GitHub App credentials. KEY_PATH is resolved against $SCRIPT_DIR if',
+        '# relative (cross-repo cwd safety per #140 + #161 — without this, cd-ing',
+        '# to another repo breaks the token helper and triggers the attribution',
+        '# trap).',
+        `export APP_ID="${githubApp.app_id}"`,
+        `export INSTALL_ID="${githubApp.install_id}"`,
+        `export KEY_PATH="${githubApp.key_path}"`,
+        'case "$KEY_PATH" in',
+        '  /*) ;;  # already absolute',
+        '  *) KEY_PATH="$SCRIPT_DIR/$KEY_PATH" ;;',
+        'esac',
+        'export KEY_PATH',
+        '',
+        '# Bot token generation — fail loud. The helper validates the ghs_ prefix',
+        '# and surfaces diagnostics (clock drift, bad key, wrong App/install ID).',
+        '# Do NOT inline the bare CLI here — without pipefail, a failed fetch piped',
+        '# through jq would succeed, GH_TOKEN would become "null", and Claude Code',
+        '# would silently fall back to stored `gh auth login` as the user. See the',
+        '# attribution-trap section of coordination.md Token & Git Hygiene.',
+        'GH_TOKEN=$("$SCRIPT_DIR/.claude/scripts/macf-gh-token.sh" \\',
+        '    --app-id "$APP_ID" --install-id "$INSTALL_ID" --key "$KEY_PATH") || {',
+        '  echo "FATAL: bot token generation failed — see stderr above." >&2',
+        '  exit 1',
+        '}',
+        'export GH_TOKEN',
+        '',
+        `export GIT_AUTHOR_NAME="${config.agent_name}[bot]"`,
+        `export GIT_COMMITTER_NAME="${config.agent_name}[bot]"`,
+        '',
+        `echo "Starting ${config.agent_name} (${config.agent_role})..."`,
+    ];
+    return assemble(managedHeaderLines('generateEnvGitHub'), body);
+}
+// ---------------------------------------------------------------------------
+// env.certs — macf-managed
+// ---------------------------------------------------------------------------
+/**
+ * Generate `.claude/.macf/env.certs` content.
+ *
+ * CA + agent cert paths + log path. Local-mode CAs live next to the
+ * registry file (`~/.macf/registry/<project>.ca.{crt,key}`), GitHub-mode
+ * CAs live under `~/.macf/certs/<project>/`. Both modes need
+ * MACF_CA_CERT/MACF_CA_KEY exported for channel-server mTLS.
+ */
+export function generateEnvCerts(config) {
+    const lines = [
+        '# Generator: generateEnvCerts (env-files.ts)',
+        '',
+    ];
+    if (isLocalMode(config)) {
+        // Pre-resolve the local-registry directory at template time so the
+        // generated file doesn't need to expand `~`. Tilde already resolved
+        // in cfg.registry.path (init.ts uses os.homedir()).
+        const registryPath = config.registry.type === 'local' ? config.registry.path : '';
+        const registryDir = posixDirname(registryPath);
+        lines.push(`export MACF_CA_CERT="${registryDir}/${config.project}.ca.crt"`, `export MACF_CA_KEY="${registryDir}/${config.project}.ca.key"`);
+    }
+    else {
+        lines.push(`export MACF_CA_CERT="$HOME/.macf/certs/${config.project}/ca-cert.pem"`, `export MACF_CA_KEY="$HOME/.macf/certs/${config.project}/ca-key.pem"`);
+    }
+    lines.push('export MACF_AGENT_CERT="$SCRIPT_DIR/.macf/certs/agent-cert.pem"', 'export MACF_AGENT_KEY="$SCRIPT_DIR/.macf/certs/agent-key.pem"', 'export MACF_LOG_PATH="$SCRIPT_DIR/.macf/logs/channel.log"');
+    return assemble(managedHeaderLines('generateEnvCerts'), lines);
+}
+// ---------------------------------------------------------------------------
+// env.registry — macf-managed
+// ---------------------------------------------------------------------------
+/**
+ * Generate `.claude/.macf/env.registry` content.
+ *
+ * MACF_REGISTRY_TYPE + per-type vars. Mirrors `claude-sh.ts`'s
+ * `registryEnvLines` exhaustive switch (so a new RegistryConfig variant
+ * fails the build here too, forcing a paired update).
+ */
+export function generateEnvRegistry(config) {
+    const body = [
+        '# Generator: generateEnvRegistry (env-files.ts)',
+        '#',
+        '# The plugin\'s src/config.ts reads MACF_REGISTRY_TYPE + per-type vars',
+        '# on startup; without them the plugin falls back to a hardcoded default',
+        '# repo and 403s every registry op on consumers in other scopes.',
+        '# See macf#178.',
+        '',
+    ];
+    switch (config.registry.type) {
+        case 'repo':
+            body.push(`export MACF_REGISTRY_TYPE="repo"`, `export MACF_REGISTRY_REPO="${config.registry.owner}/${config.registry.repo}"`);
+            break;
+        case 'org':
+            body.push(`export MACF_REGISTRY_TYPE="org"`, `export MACF_REGISTRY_ORG="${config.registry.org}"`);
+            break;
+        case 'profile':
+            body.push(`export MACF_REGISTRY_TYPE="profile"`, `export MACF_REGISTRY_USER="${config.registry.user}"`);
+            break;
+        case 'local':
+            body.push(`export MACF_REGISTRY_TYPE="local"`, `export MACF_REGISTRY_PATH="${config.registry.path}"`);
+            break;
+    }
+    return assemble(managedHeaderLines('generateEnvRegistry'), body);
+}
+// ---------------------------------------------------------------------------
+// env.telemetry — operator-managed; MINIMAL when MACF_OTEL_DISABLED=1
+// ---------------------------------------------------------------------------
+/**
+ * Generate `.claude/.macf/env.telemetry` content.
+ *
+ * The 3 OTel mandatory gates + per-signal exporters + endpoint resolution.
+ * Mirrors `claude-sh.ts`'s `otelTelemetryLines` (including the same
+ * shell-unsafe-char rejection on MACF_OTEL_ENDPOINT and the same default
+ * endpoint `http://localhost:14318` per macf-devops-toolkit canonical k3d
+ * topology).
+ *
+ * **Minimal placeholder when `MACF_OTEL_DISABLED=1`** (operator opt-out at
+ * template-time per macf#197). Body shrinks to header + schema_version +
+ * a comment explaining the opt-out — no OTel exports emitted, so sourcing
+ * the file is a no-op.
+ *
+ * @param env — defaults to `process.env`; tests inject a fake.
+ */
+export function generateEnvTelemetry(config, env = process.env) {
+    if (env['MACF_OTEL_DISABLED'] === '1' || env['MACF_OTEL_DISABLED'] === 'true') {
+        const body = [
+            '# Generator: generateEnvTelemetry (env-files.ts)',
+            '#',
+            '# Telemetry intentionally disabled (MACF_OTEL_DISABLED=1 at',
+            '# `macf init` / `macf update` time). No OTel exporters or gates',
+            '# are configured; sourcing this file is a no-op. See macf#197.',
+            '#',
+            '# To re-enable: re-run `macf update` without MACF_OTEL_DISABLED set.',
+        ];
+        return assemble(operatorHeaderLines('generateEnvTelemetry'), body);
+    }
+    const endpoint = env['MACF_OTEL_ENDPOINT'] ?? 'http://localhost:14318';
+    // Same allowlist pattern as otelTelemetryLines in claude-sh.ts. The
+    // endpoint value gets embedded verbatim in a shell double-quoted export.
+    if (/["$`\\\n\r]/.test(endpoint)) {
+        throw new Error(`MACF_OTEL_ENDPOINT contains a shell-unsafe character. ` +
+            `Got: ${JSON.stringify(endpoint)}. ` +
+            `Expected a plain URL like http://host:port.`);
+    }
+    const body = [
+        '# Generator: generateEnvTelemetry (env-files.ts)',
+        '#',
+        '# Claude Code native OTEL telemetry → observability stack',
+        '# (macf#197 + macf#245). Three telemetry signal gates — each',
+        '# independent, ALL required for the corresponding signal to emit:',
+        '#   CLAUDE_CODE_ENABLE_TELEMETRY        — master telemetry gate',
+        '#   CLAUDE_CODE_ENHANCED_TELEMETRY_BETA — additional gate for traces',
+        '#   OTEL_TRACES_EXPORTER=otlp           — emit traces',
+        '#   OTEL_METRICS_EXPORTER=otlp          — emit metrics',
+        '#   OTEL_LOGS_EXPORTER=otlp             — emit logs',
+        '# Without the per-signal exporter env vars, that signal silently emits',
+        '# nothing even if the master gate is on (#245 surfaced the metrics+logs',
+        '# gap — only traces had the exporter set; metrics + logs were dark).',
+        '#',
+        '# Endpoint override has two layers (groundnuty/macf#282):',
+        '#   - Template-time: MACF_OTEL_ENDPOINT=<url> at `macf init` /',
+        '#     `macf update` bakes a different default into this file',
+        '#   - Run-time: OTEL_EXPORTER_OTLP_ENDPOINT=<url> in the shell',
+        '#     BEFORE invoking ./claude.sh overrides the baked default',
+        'export CLAUDE_CODE_ENABLE_TELEMETRY=1',
+        'export CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1',
+        'export OTEL_TRACES_EXPORTER=otlp',
+        'export OTEL_METRICS_EXPORTER=otlp',
+        'export OTEL_LOGS_EXPORTER=otlp',
+        // 4-layer endpoint resolution chain (macf#313). Requires
+        // macf_settings_get to be defined upstream — env.identity defines it,
+        // and PR-B's claude.sh sources env.identity before env.telemetry.
+        `MACF_OTEL_ENDPOINT="\${MACF_OTEL_ENDPOINT:-$(macf_settings_get MACF_OTEL_ENDPOINT)}"`,
+        `MACF_OTEL_ENDPOINT="\${MACF_OTEL_ENDPOINT:-${endpoint}}"`,
+        'export OTEL_EXPORTER_OTLP_ENDPOINT="${OTEL_EXPORTER_OTLP_ENDPOINT:-$MACF_OTEL_ENDPOINT}"',
+        'export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf',
+        `export OTEL_SERVICE_NAME="macf-agent-${config.agent_name}"`,
+        `export OTEL_RESOURCE_ATTRIBUTES="gen_ai.agent.name=${config.agent_name},gen_ai.agent.role=${config.agent_role},service.namespace=macf"`,
+    ];
+    return assemble(operatorHeaderLines('generateEnvTelemetry'), body);
+}
+// ---------------------------------------------------------------------------
+// env.tmux — operator-managed; MINIMAL when neither tmux_session nor _window set
+// ---------------------------------------------------------------------------
+/**
+ * Generate `.claude/.macf/env.tmux` content.
+ *
+ * MACF_TMUX_SESSION + MACF_TMUX_WINDOW for the on-notify wake path
+ * (macf#185). When the channel server's onNotify handler fires, it shells
+ * out to `tmux-send-to-claude.sh <session>:<window> <prompt>` to inject
+ * the notification as the TUI's next input turn.
+ *
+ * **Minimal placeholder when neither field is set in config.** The wake
+ * path falls back to auto-detect from $TMUX in that case (existing
+ * behavior — no env var needed). Avoids generating an empty-export file.
+ */
+export function generateEnvTmux(config) {
+    const hasSession = config.tmux_session !== undefined;
+    const hasWindow = config.tmux_window !== undefined;
+    if (!hasSession && !hasWindow) {
+        const body = [
+            '# Generator: generateEnvTmux (env-files.ts)',
+            '#',
+            '# No MACF_TMUX_SESSION or MACF_TMUX_WINDOW configured for this agent.',
+            '# The on-notify wake path (macf#185) auto-detects from $TMUX when the',
+            '# channel server is launched inside a tmux pane; otherwise no-ops',
+            '# silently. To target a specific named pane (e.g., agent launched',
+            '# outside tmux by a supervisor), set tmux_session / tmux_window in',
+            '# `.macf/macf-agent.json` and re-run `macf update`.',
+        ];
+        return assemble(operatorHeaderLines('generateEnvTmux'), body);
+    }
+    const body = [
+        '# Generator: generateEnvTmux (env-files.ts)',
+        '#',
+        '# tmux session:window for the on-notify wake path (macf#185). The',
+        '# channel server\'s onNotify handler shells out to tmux-send-to-claude.sh',
+        '# <session>:<window> <prompt> to inject notifications into the TUI.',
+        '',
+    ];
+    if (hasSession) {
+        body.push(`export MACF_TMUX_SESSION="${config.tmux_session}"`);
+    }
+    if (hasWindow) {
+        body.push(`export MACF_TMUX_WINDOW="${config.tmux_window}"`);
+    }
+    return assemble(operatorHeaderLines('generateEnvTmux'), body);
+}
+/**
+ * Write all 7 per-concern env files into `<projectDir>/.claude/.macf/`.
+ *
+ *   env._helpers   — library file (sourced first per alphabetical order)
+ *   env.certs      — cert + log paths
+ *   env.github     — App creds + GH_TOKEN mint (empty-comment in local-mode)
+ *   env.identity   — MACF_PROJECT / MACF_AGENT_NAME / ROLE / TYPE / WORKSPACE_DIR
+ *   env.registry   — MACF_REGISTRY_TYPE + per-type vars
+ *   env.telemetry  — OTel gates + endpoint (operator-managed)
+ *   env.tmux       — MACF_TMUX_SESSION / MACF_TMUX_WINDOW (operator-managed)
+ *
+ * **Always emits all 7 files** — even when the concern is empty (e.g.,
+ * env.tmux with no tmux_session set, env.github in local-mode). The
+ * generators emit a header + comment explaining the empty case. This
+ * keeps the on-disk layout uniform across configs, so claude.sh's
+ * source-loop pattern (`for f in env.*; do source "$f"; done`) is
+ * deterministic — no "did the file get skipped" branching for the
+ * sourcing script to consider.
+ *
+ * **Mode 0644** — these are sourced, not executed; no execute bit needed.
+ *
+ * **Overwrites unconditionally** — macf-managed files have a managed
+ * header warning operators not to edit. Operator-managed files
+ * (env.telemetry, env.tmux) get overwritten too in PR-B because PR-C
+ * hasn't added the preserve-existing logic yet. Init's contract is
+ * "fresh write"; update's preserve-existing contract lands in PR-C.
+ *
+ * **Creates `.claude/.macf/`** with mkdir -p semantics. The directory
+ * may not exist on a fresh init (the `.claude/` parent often does
+ * because of `settings.json` / `rules/`, but `.macf/` under it is new
+ * to PR-B).
+ *
+ * @returns Lists of absolute file paths for caller logging. `skipped`
+ *   is reserved for PR-C and currently always empty.
+ */
+export function writeEnvFiles(projectDir, config) {
+    const absDir = resolve(projectDir);
+    const envDir = join(absDir, '.claude', '.macf');
+    mkdirSync(envDir, { recursive: true });
+    // Order in this list is purely for `written` array stability — the
+    // on-disk filesystem order is what claude.sh's `for f in env.*` glob
+    // sees, and shell glob sorts lexicographically (env._helpers first
+    // because `_` < lowercase letters in ASCII).
+    const files = [
+        { name: 'env._helpers', content: generateEnvHelpers() },
+        { name: 'env.identity', content: generateEnvIdentity(config) },
+        { name: 'env.github', content: generateEnvGitHub(config) },
+        { name: 'env.certs', content: generateEnvCerts(config) },
+        { name: 'env.registry', content: generateEnvRegistry(config) },
+        { name: 'env.telemetry', content: generateEnvTelemetry(config) },
+        { name: 'env.tmux', content: generateEnvTmux(config) },
+    ];
+    const written = [];
+    for (const { name, content } of files) {
+        const path = join(envDir, name);
+        writeFileSync(path, content, { mode: 0o644 });
+        written.push(path);
+    }
+    return { written, skipped: [] };
+}
+//# sourceMappingURL=env-files.js.map

package/dist/cli/env-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-files.js","sourceRoot":"","sources":["../../src/cli/env-files.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAG1C,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;;;;GAKG;AACH,SAAS,kBAAkB,CAAC,SAAiB;IAC3C,OAAO;QACL,oEAAoE;QACpE,gEAAgE;QAChE,6CAA6C,SAAS,gBAAgB;QACtE,sEAAsE;QACtE,2BAA2B;QAC3B,GAAG;QACH,uEAAuE;QACvE,mDAAmD;KACpD,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAS,mBAAmB,CAAC,SAAiB;IAC5C,OAAO;QACL,sEAAsE;QACtE,mEAAmE;QACnE,qBAAqB,SAAS,0CAA0C;QACxE,0DAA0D;QAC1D,GAAG;QACH,uEAAuE;QACvE,mDAAmD;KACpD,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAS,kBAAkB,CAAC,SAAiB;IAC3C,OAAO;QACL,oEAAoE;QACpE,gEAAgE;QAChE,6CAA6C,SAAS,gBAAgB;QACtE,sEAAsE;QACtE,2BAA2B;QAC3B,GAAG;QACH,wEAAwE;QACxE,wEAAwE;QACxE,uEAAuE;QACvE,qEAAqE;QACrE,0BAA0B;KAC3B,CAAC;AACJ,CAAC;AAED,MAAM,mBAAmB,GAAG,qBAAqB,CAAC;AAElD;;;;GAIG;AACH,SAAS,QAAQ,CACf,MAAyB,EACzB,IAAuB;IAEvB,OAAO;QACL,GAAG,MAAM;QACT,mBAAmB;QACnB,EAAE;QACF,GAAG,IAAI;QACP,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,8EAA8E;AAC9E,4EAA4E;AAC5E,8EAA8E;AAE9E;;;GAGG;AACH,SAAS,WAAW,CAAC,GAAoB;IACvC,OAAO,GAAG,CAAC,QAAQ,CAAC,IAAI,KAAK,OAAO,CAAC;AACvC,CAAC;AAED;;;;GAIG;AACH,SAAS,YAAY,CAAC,CAAS;IAC7B,MAAM,GAAG,GAAG,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAC/B,IAAI,GAAG,GAAG,CAAC;QAAE,OAAO,GAAG,CAAC;IACxB,IAAI,GAAG,KAAK,CAAC;QAAE,OAAO,GAAG,CAAC;IAC1B,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AACzB,CAAC;AAED,8EAA8E;AAC9E,kFAAkF;AAClF,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,kBAAkB;IAChC,MAAM,IAAI,GAAG;QACX,gDAAgD;QAChD,GAAG;QACH,yEAAyE;QACzE,uEAAuE;QACvE,0EAA0E;QAC1E,wEAAwE;QACxE,uEAAuE;QACvE,yEAAyE;QACzE,EAAE;QACF,wEAAwE;QACxE,wEAAwE;QACxE,mEAAmE;QACnE,oEAAoE;QACpE,uDAAuD;QACvD,uBAAuB;QACvB,uBAAuB;QACvB,8FAA8F;QAC9F,6FAA6F;QAC7F,MAAM;QACN,GAAG;KACJ,CAAC;IACF,OAAO,QAAQ,CAAC,kBAAkB,CAAC,oBAAoB,CAAC,EAAE,IAAI,CAAC,CAAC;AAClE,CAAC;AAED,8EAA8E;AAC9E,8BAA8B;AAC9B,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAuB;IACzD,MAAM,IAAI,GAAG;QACX,iDAAiD;QACjD,uEAAuE;QACvE,8EAA8E;QAC9E,GAAG;QACH,qEAAqE;QACrE,uEAAuE;QACvE,gEAAgE;QAChE,EAAE;QACF,yEAAyE;QACzE,uEAAuE;QACvE,2CAA2C;QAC3C,yCAAyC;QACzC,wBAAwB,MAAM,CAAC,OAAO,GAAG;QACzC,2BAA2B,MAAM,CAAC,UAAU,GAAG;QAC/C,EAAE;QACF,wEAAwE;QACxE,0EAA0E;QAC1E,gDAAgD;QAChD,kEAAkE;QAClE,6EAA6E;QAC7E,wCAAwC,MAAM,CAAC,UAAU,IAAI;QAC7D,wBAAwB;QACxB,6EAA6E;QAC7E,wCAAwC,MAAM,CAAC,UAAU,IAAI;QAC7D,wBAAwB;KACzB,CAAC;IACF,OAAO,QAAQ,CAAC,kBAAkB,CAAC,qBAAqB,CAAC,EAAE,IAAI,CAAC,CAAC;AACnE,CAAC;AAED,8EAA8E;AAC9E,iDAAiD;AACjD,8EAA8E;AAE9E;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAuB;IACvD,IAAI,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,GAAG;YACX,+CAA+C;YAC/C,GAAG;YACH,wEAAwE;YACxE,uEAAuE;YACvE,yEAAyE;YACzE,wEAAwE;YACxE,yEAAyE;YACzE,mDAAmD;YACnD,kBAAkB,MAAM,CAAC,UAAU,KAAK,MAAM,CAAC,UAAU,6BAA6B;SACvF,CAAC;QACF,OAAO,QAAQ,CAAC,kBAAkB,CAAC,mBAAmB,CAAC,EAAE,IAAI,CAAC,CAAC;IACjE,CAAC;IAED,MAAM,SAAS,GAAG,MAAM,CAAC,UAAU,CAAC;IACpC,mEAAmE;IACnE,8DAA8D;IAC9D,qEAAqE;IACrE,qEAAqE;IACrE,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,MAAM,IAAI,GAAG;YACX,+CAA+C;YAC/C,GAAG;YACH,uEAAuE;YACvE,6DAA6D;SAC9D,CAAC;QACF,OAAO,QAAQ,CAAC,kBAAkB,CAAC,mBAAmB,CAAC,EAAE,IAAI,CAAC,CAAC;IACjE,CAAC;IAED,MAAM,IAAI,GAAG;QACX,+CAA+C;QAC/C,EAAE;QACF,uEAAuE;QACvE,0EAA0E;QAC1E,wEAAwE;QACxE,UAAU;QACV,kBAAkB,SAAS,CAAC,MAAM,GAAG;QACrC,sBAAsB,SAAS,CAAC,UAAU,GAAG;QAC7C,oBAAoB,SAAS,CAAC,QAAQ,GAAG;QACzC,qBAAqB;QACrB,8BAA8B;QAC9B,0CAA0C;QAC1C,MAAM;QACN,iBAAiB;QACjB,EAAE;QACF,0EAA0E;QAC1E,0EAA0E;QAC1E,4EAA4E;QAC5E,2EAA2E;QAC3E,2EAA2E;QAC3E,oEAAoE;QACpE,8DAA8D;QAC9D,2EAA2E;QAC3E,qEAAqE;QACrE,UAAU;QACV,GAAG;QACH,iBAAiB;QACjB,EAAE;QACF,2BAA2B,MAAM,CAAC,UAAU,QAAQ;QACpD,8BAA8B,MAAM,CAAC,UAAU,QAAQ;QACvD,EAAE;QACF,kBAAkB,MAAM,CAAC,UAAU,KAAK,MAAM,CAAC,UAAU,OAAO;KACjE,CAAC;IACF,OAAO,QAAQ,CAAC,kBAAkB,CAAC,mBAAmB,CAAC,EAAE,IAAI,CAAC,CAAC;AACjE,CAAC;AAED,8EAA8E;AAC9E,2BAA2B;AAC3B,8EAA8E;AAE9E;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAuB;IACtD,MAAM,KAAK,GAAa;QACtB,8CAA8C;QAC9C,EAAE;KACH,CAAC;IAEF,IAAI,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC;QACxB,mEAAmE;QACnE,oEAAoE;QACpE,oDAAoD;QACpD,MAAM,YAAY,GAChB,MAAM,CAAC,QAAQ,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/D,MAAM,WAAW,GAAG,YAAY,CAAC,YAAY,CAAC,CAAC;QAC/C,KAAK,CAAC,IAAI,CACR,wBAAwB,WAAW,IAAI,MAAM,CAAC,OAAO,UAAU,EAC/D,uBAAuB,WAAW,IAAI,MAAM,CAAC,OAAO,UAAU,CAC/D,CAAC;IACJ,CAAC;SAAM,CAAC;QACN,KAAK,CAAC,IAAI,CACR,0CAA0C,MAAM,CAAC,OAAO,eAAe,EACvE,yCAAyC,MAAM,CAAC,OAAO,cAAc,CACtE,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,IAAI,CACR,iEAAiE,EACjE,+DAA+D,EAC/D,2DAA2D,CAC5D,CAAC;IAEF,OAAO,QAAQ,CAAC,kBAAkB,CAAC,kBAAkB,CAAC,EAAE,KAAK,CAAC,CAAC;AACjE,CAAC;AAED,8EAA8E;AAC9E,8BAA8B;AAC9B,8EAA8E;AAE9E;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAuB;IACzD,MAAM,IAAI,GAAa;QACrB,iDAAiD;QACjD,GAAG;QACH,wEAAwE;QACxE,yEAAyE;QACzE,iEAAiE;QACjE,iBAAiB;QACjB,EAAE;KACH,CAAC;IAEF,QAAQ,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;QAC7B,KAAK,MAAM;YACT,IAAI,CAAC,IAAI,CACP,kCAAkC,EAClC,8BAA8B,MAAM,CAAC,QAAQ,CAAC,KAAK,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,GAAG,CAC/E,CAAC;YACF,MAAM;QACR,KAAK,KAAK;YACR,IAAI,CAAC,IAAI,CACP,iCAAiC,EACjC,6BAA6B,MAAM,CAAC,QAAQ,CAAC,GAAG,GAAG,CACpD,CAAC;YACF,MAAM;QACR,KAAK,SAAS;YACZ,IAAI,CAAC,IAAI,CACP,qCAAqC,EACrC,8BAA8B,MAAM,CAAC,QAAQ,CAAC,IAAI,GAAG,CACtD,CAAC;YACF,MAAM;QACR,KAAK,OAAO;YACV,IAAI,CAAC,IAAI,CACP,mCAAmC,EACnC,8BAA8B,MAAM,CAAC,QAAQ,CAAC,IAAI,GAAG,CACtD,CAAC;YACF,MAAM;IACV,CAAC;IAED,OAAO,QAAQ,CAAC,kBAAkB,CAAC,qBAAqB,CAAC,EAAE,IAAI,CAAC,CAAC;AACnE,CAAC;AAED,8EAA8E;AAC9E,sEAAsE;AACtE,8EAA8E;AAE9E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,oBAAoB,CAClC,MAAuB,EACvB,MAAyB,OAAO,CAAC,GAAG;IAEpC,IAAI,GAAG,CAAC,oBAAoB,CAAC,KAAK,GAAG,IAAI,GAAG,CAAC,oBAAoB,CAAC,KAAK,MAAM,EAAE,CAAC;QAC9E,MAAM,IAAI,GAAG;YACX,kDAAkD;YAClD,GAAG;YACH,6DAA6D;YAC7D,iEAAiE;YACjE,gEAAgE;YAChE,GAAG;YACH,sEAAsE;SACvE,CAAC;QACF,OAAO,QAAQ,CAAC,mBAAmB,CAAC,sBAAsB,CAAC,EAAE,IAAI,CAAC,CAAC;IACrE,CAAC;IAED,MAAM,QAAQ,GAAG,GAAG,CAAC,oBAAoB,CAAC,IAAI,wBAAwB,CAAC;IAEvE,oEAAoE;IACpE,yEAAyE;IACzE,IAAI,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CACb,wDAAwD;YACtD,QAAQ,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI;YACpC,6CAA6C,CAChD,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GAAG;QACX,kDAAkD;QAClD,GAAG;QACH,2DAA2D;QAC3D,8DAA8D;QAC9D,mEAAmE;QACnE,iEAAiE;QACjE,sEAAsE;QACtE,uDAAuD;QACvD,wDAAwD;QACxD,qDAAqD;QACrD,wEAAwE;QACxE,yEAAyE;QACzE,sEAAsE;QACtE,GAAG;QACH,2DAA2D;QAC3D,gEAAgE;QAChE,8DAA8D;QAC9D,gEAAgE;QAChE,+DAA+D;QAC/D,uCAAuC;QACvC,8CAA8C;QAC9C,kCAAkC;QAClC,mCAAmC;QACnC,gCAAgC;QAChC,yDAAyD;QACzD,sEAAsE;QACtE,kEAAkE;QAClE,sFAAsF;QACtF,8CAA8C,QAAQ,IAAI;QAC1D,0FAA0F;QAC1F,kDAAkD;QAClD,wCAAwC,MAAM,CAAC,UAAU,GAAG;QAC5D,sDAAsD,MAAM,CAAC,UAAU,sBAAsB,MAAM,CAAC,UAAU,0BAA0B;KACzI,CAAC;IACF,OAAO,QAAQ,CAAC,mBAAmB,CAAC,sBAAsB,CAAC,EAAE,IAAI,CAAC,CAAC;AACrE,CAAC;AAED,8EAA8E;AAC9E,iFAAiF;AACjF,8EAA8E;AAE9E;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAAC,MAAuB;IACrD,MAAM,UAAU,GAAG,MAAM,CAAC,YAAY,KAAK,SAAS,CAAC;IACrD,MAAM,SAAS,GAAG,MAAM,CAAC,WAAW,KAAK,SAAS,CAAC;IAEnD,IAAI,CAAC,UAAU,IAAI,CAAC,SAAS,EAAE,CAAC;QAC9B,MAAM,IAAI,GAAG;YACX,6CAA6C;YAC7C,GAAG;YACH,uEAAuE;YACvE,uEAAuE;YACvE,mEAAmE;YACnE,mEAAmE;YACnE,oEAAoE;YACpE,qDAAqD;SACtD,CAAC;QACF,OAAO,QAAQ,CAAC,mBAAmB,CAAC,iBAAiB,CAAC,EAAE,IAAI,CAAC,CAAC;IAChE,CAAC;IAED,MAAM,IAAI,GAAa;QACrB,6CAA6C;QAC7C,GAAG;QACH,mEAAmE;QACnE,2EAA2E;QAC3E,qEAAqE;QACrE,EAAE;KACH,CAAC;IACF,IAAI,UAAU,EAAE,CAAC;QACf,IAAI,CAAC,IAAI,CAAC,6BAA6B,MAAM,CAAC,YAAY,GAAG,CAAC,CAAC;IACjE,CAAC;IACD,IAAI,SAAS,EAAE,CAAC;QACd,IAAI,CAAC,IAAI,CAAC,4BAA4B,MAAM,CAAC,WAAW,GAAG,CAAC,CAAC;IAC/D,CAAC;IACD,OAAO,QAAQ,CAAC,mBAAmB,CAAC,iBAAiB,CAAC,EAAE,IAAI,CAAC,CAAC;AAChE,CAAC;AAoBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,UAAU,aAAa,CAC3B,UAAkB,EAClB,MAAuB;IAEvB,MAAM,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACnC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;IAChD,SAAS,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAEvC,mEAAmE;IACnE,qEAAqE;IACrE,mEAAmE;IACnE,6CAA6C;IAC7C,MAAM,KAAK,GAAqD;QAC9D,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,kBAAkB,EAAE,EAAE;QACvD,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,mBAAmB,CAAC,MAAM,CAAC,EAAE;QAC9D,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,iBAAiB,CAAC,MAAM,CAAC,EAAE;QAC1D,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,gBAAgB,CAAC,MAAM,CAAC,EAAE;QACxD,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,mBAAmB,CAAC,MAAM,CAAC,EAAE;QAC9D,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,oBAAoB,CAAC,MAAM,CAAC,EAAE;QAChE,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,eAAe,CAAC,MAAM,CAAC,EAAE;KACvD,CAAC;IAEF,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,KAAK,EAAE,CAAC;QACtC,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAChC,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QAC9C,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrB,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;AAClC,CAAC"}

package/dist/cli/index.js

@@ -147,6 +147,10 @@ What the flags actually control:
   --yes       skip the unified Proceed? prompt; non-interactive bypass
   --confirm   explicit opt-in to the unified preview-then-prompt flow
               (also the default for bare \`macf update\`; --yes overrides)
+  --no-migrate-env-files
+              skip the macf#342 monolithic→multi-file claude.sh migration
+              AND env-file refresh (operator opt-out for hand-modified
+              launchers; does NOT roll back already-migrated workspaces)
   --dry-run   show diff + would-bump list, write nothing
 
 Implication for reproducible bootstrap (cv-e2e-test, harness pinning, etc.):
@@ -161,9 +165,15 @@ Implication for reproducible bootstrap (cv-e2e-test, harness pinning, etc.):
     .option('--actions', 'Bump only the macf-actions version pin', false)
     .option('--yes', 'Skip the unified Proceed? prompt; non-interactive bypass', false)
     .option('--confirm', 'Explicit opt-in to the unified preview-then-prompt flow (also the default; --yes overrides)', false)
+    .option('--no-migrate-env-files', 'Skip the macf#342 monolithic→multi-file claude.sh migration AND env-file refresh (operator opt-out)', false)
     .option('--dry-run', 'Show the diff but do not write the config', false)
     .option('--dir <path>', 'Project directory (defaults to auto-discovery from cwd)')
     .action(async (opts) => {
+    // Commander's --no-<flag> convention sets opts.migrateEnvFiles = false
+    // when --no-migrate-env-files is passed (the default is `true` because
+    // of the leading `--no-` in the option name). Translate to the more
+    // intuitive opt-out shape used inside `update()`.
+    const noMigrateEnvFiles = opts.migrateEnvFiles === false;
     const code = await update(resolveProjectDir(opts.dir), {
         all: opts.all,
         cli: opts.cli,
@@ -172,6 +182,7 @@ Implication for reproducible bootstrap (cv-e2e-test, harness pinning, etc.):
         yes: opts.yes,
         dryRun: opts.dryRun,
         confirm: opts.confirm,
+        noMigrateEnvFiles,
     });
     process.exitCode = code;
 });