@groundnuty/macf 0.2.16 → 0.2.18

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

@@ -0,0 +1,168 @@
+import type { MacfAgentConfig } from './config.js';
+/**
+ * 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 declare function generateEnvHelpers(): string;
+/**
+ * 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 declare function generateEnvIdentity(config: MacfAgentConfig): string;
+/**
+ * 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 declare function generateEnvGitHub(config: MacfAgentConfig): string;
+/**
+ * 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 declare function generateEnvCerts(config: MacfAgentConfig): string;
+/**
+ * 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 declare function generateEnvRegistry(config: MacfAgentConfig): string;
+/**
+ * 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 declare function generateEnvTelemetry(config: MacfAgentConfig, env?: NodeJS.ProcessEnv): string;
+/**
+ * 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 declare function generateEnvTmux(config: MacfAgentConfig): string;
+/**
+ * Result of `writeEnvFiles` — lists of file paths that were written and
+ * (currently empty; reserved for PR-C migration logic that may skip
+ * operator-managed files when they already exist) skipped.
+ *
+ * Returned so callers (init.ts, update.ts in PR-C) can log a summary
+ * line ("Wrote 7 env files to .claude/.macf/") without re-deriving the
+ * file list from an external mapping.
+ */
+export interface WriteEnvFilesResult {
+    readonly written: readonly string[];
+    readonly skipped: readonly string[];
+}
+/**
+ * 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 declare function writeEnvFiles(projectDir: string, config: MacfAgentConfig): WriteEnvFilesResult;
+//# sourceMappingURL=env-files.d.ts.map

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"}