@pleri/olam-cli 0.1.109 → 0.1.111

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/lib/completion-generator.d.ts

@@ -0,0 +1,107 @@
+/**
+ * completion-generator.ts — Commander command-tree → POSIX shell completion script.
+ *
+ * Phase B1 of olam-operator-onboarding-parity (plan
+ * ~/.claude/plans/olam-operator-onboarding-parity.md).
+ *
+ * Decision 4 (plan): runtime-emit from the commander tree, NOT static
+ * fixtures in the tarball. One source of truth: new CLI commands auto-
+ * included in the next `olam completion <shell>` invocation.
+ *
+ * Supported shells: zsh + bash. Other shells throw `UnsupportedShellError`.
+ *
+ * Nesting depth: TWO levels of subcommand dispatch (top-level + one
+ * nested). Covers ~95% of olam's tree (`olam kg build`, `olam auth login`,
+ * `olam workspace list`, etc.). Deeper nesting (`olam world snapshot
+ * restore`) falls through gracefully — top + one level still complete.
+ *
+ * Escaping:
+ *   - zsh: descriptions inside `name:description` syntax need `:` escaped
+ *     (since `:` is the field separator) and `'` doubled (since strings
+ *     are single-quoted).
+ *   - bash: descriptions inside double-quoted strings need `"`, `\`, `$`,
+ *     and backtick escaped.
+ *
+ * Hidden commands (commander's private `_hidden` flag) are excluded:
+ *   - `olam crystallize` is registered with `{ hidden: !isPleriConfigured() }`
+ *     for fresh-install operators.
+ *
+ * Determinism: commander preserves command-registration order in
+ * `Command.commands`. The walk is a pure-functional map → the output is
+ * a deterministic function of the program tree. Snapshot tests rely on
+ * this.
+ */
+import type { Command } from 'commander';
+export interface CommandNode {
+    readonly name: string;
+    readonly description: string;
+    readonly subcommands: ReadonlyArray<CommandNode>;
+}
+export declare class UnsupportedShellError extends Error {
+    constructor(shell: string);
+}
+/**
+ * Walk a commander `Command` recursively, extracting (name, description,
+ * subcommands). Hidden commands (commander's private `_hidden` flag,
+ * set via `.command(..., { hidden: true })`) are excluded.
+ */
+export declare function extractCommandTree(program: Command): CommandNode;
+/**
+ * Emit a zsh completion script.
+ *
+ * Format:
+ *   #compdef <program>
+ *
+ *   _<program>() {
+ *     local -a l1_subs
+ *     l1_subs=(
+ *       '<sub>:<description>'
+ *       ...
+ *     )
+ *     if (( CURRENT == 2 )); then
+ *       _describe '<program> command' l1_subs
+ *       return
+ *     fi
+ *     case $words[2] in
+ *       <sub-with-children>)
+ *         if (( CURRENT == 3 )); then
+ *           local -a l2_subs
+ *           l2_subs=(...)
+ *           _describe '<sub> subcommand' l2_subs
+ *         fi
+ *         ;;
+ *       ...
+ *     esac
+ *   }
+ *
+ *   _<program> "$@"
+ */
+export declare function generateZshCompletion(tree: CommandNode): string;
+/**
+ * Emit a bash completion script.
+ *
+ * Format:
+ *   _<program>_completions() {
+ *     local cur="${COMP_WORDS[COMP_CWORD]}"
+ *     local cword=$COMP_CWORD
+ *     if [[ $cword -eq 1 ]]; then
+ *       COMPREPLY=( $(compgen -W "<sub1> <sub2> ..." -- "$cur") )
+ *       return
+ *     fi
+ *     case "${COMP_WORDS[1]}" in
+ *       <sub-with-children>)
+ *         if [[ $cword -eq 2 ]]; then
+ *           COMPREPLY=( $(compgen -W "<l2-1> <l2-2> ..." -- "$cur") )
+ *         fi
+ *         ;;
+ *     esac
+ *   }
+ *   complete -F _<program>_completions <program>
+ */
+export declare function generateBashCompletion(tree: CommandNode): string;
+/**
+ * Top-level API: walk the commander program + emit a completion script
+ * for the requested shell.
+ */
+export declare function generateCompletion(program: Command, shell: 'zsh' | 'bash'): string;
+//# sourceMappingURL=completion-generator.d.ts.map

package/dist/lib/completion-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion-generator.d.ts","sourceRoot":"","sources":["../../src/lib/completion-generator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;CAClD;AAED,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,KAAK,EAAE,MAAM;CAI1B;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,WAAW,CAQhE;AA0CD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CA0C/D;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CAgChE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,CAKlF"}

package/dist/lib/completion-generator.js

@@ -0,0 +1,226 @@
+/**
+ * completion-generator.ts — Commander command-tree → POSIX shell completion script.
+ *
+ * Phase B1 of olam-operator-onboarding-parity (plan
+ * ~/.claude/plans/olam-operator-onboarding-parity.md).
+ *
+ * Decision 4 (plan): runtime-emit from the commander tree, NOT static
+ * fixtures in the tarball. One source of truth: new CLI commands auto-
+ * included in the next `olam completion <shell>` invocation.
+ *
+ * Supported shells: zsh + bash. Other shells throw `UnsupportedShellError`.
+ *
+ * Nesting depth: TWO levels of subcommand dispatch (top-level + one
+ * nested). Covers ~95% of olam's tree (`olam kg build`, `olam auth login`,
+ * `olam workspace list`, etc.). Deeper nesting (`olam world snapshot
+ * restore`) falls through gracefully — top + one level still complete.
+ *
+ * Escaping:
+ *   - zsh: descriptions inside `name:description` syntax need `:` escaped
+ *     (since `:` is the field separator) and `'` doubled (since strings
+ *     are single-quoted).
+ *   - bash: descriptions inside double-quoted strings need `"`, `\`, `$`,
+ *     and backtick escaped.
+ *
+ * Hidden commands (commander's private `_hidden` flag) are excluded:
+ *   - `olam crystallize` is registered with `{ hidden: !isPleriConfigured() }`
+ *     for fresh-install operators.
+ *
+ * Determinism: commander preserves command-registration order in
+ * `Command.commands`. The walk is a pure-functional map → the output is
+ * a deterministic function of the program tree. Snapshot tests rely on
+ * this.
+ */
+export class UnsupportedShellError extends Error {
+    constructor(shell) {
+        super(`Unsupported shell: ${shell}. Supported shells: zsh, bash.`);
+        this.name = 'UnsupportedShellError';
+    }
+}
+/**
+ * Walk a commander `Command` recursively, extracting (name, description,
+ * subcommands). Hidden commands (commander's private `_hidden` flag,
+ * set via `.command(..., { hidden: true })`) are excluded.
+ */
+export function extractCommandTree(program) {
+    return {
+        name: program.name(),
+        description: program.description() ?? '',
+        subcommands: program.commands
+            .filter((c) => !isHidden(c))
+            .map((c) => extractCommandTree(c)),
+    };
+}
+function isHidden(cmd) {
+    // Commander stores hidden flag privately. Access defensively in case
+    // the field name changes across versions.
+    const c = cmd;
+    return c._hidden === true;
+}
+/**
+ * Escape a description string for zsh's `name:description` completion
+ * syntax. Three transformations:
+ *   1. Collapse newlines + carriage returns to single spaces (multi-line
+ *      descriptions break single-quoted `'name:description'` syntax —
+ *      a literal `\n` in the source string forces the next line to start
+ *      a new entry without a leading quote → zsh parse error → operator's
+ *      shell rc fails to load; audit finding B-ADV-3).
+ *   2. Double single quotes (single-quoted-string termination).
+ *   3. Backslash-escape colons (field separator in `name:description`).
+ */
+function escapeZsh(s) {
+    return s
+        .replace(/[\r\n]+/g, ' ')
+        .replace(/'/g, "''")
+        .replace(/:/g, '\\:');
+}
+/**
+ * Escape a string for bash double-quoted contexts. Three transformations:
+ *   1. Collapse newlines + carriage returns to single spaces (bash
+ *      double-quoted strings tolerate `\n` but `compgen -W` interprets
+ *      whitespace as word boundaries — a newline silently splits the
+ *      word list; audit finding B-ADV-3).
+ *   2. Backslash-escape `"`, `\`, `$`, backtick (the four chars bash
+ *      interprets inside double quotes).
+ */
+function escapeBash(s) {
+    return s
+        .replace(/[\r\n]+/g, ' ')
+        .replace(/(["\\$`])/g, '\\$1');
+}
+/**
+ * Emit a zsh completion script.
+ *
+ * Format:
+ *   #compdef <program>
+ *
+ *   _<program>() {
+ *     local -a l1_subs
+ *     l1_subs=(
+ *       '<sub>:<description>'
+ *       ...
+ *     )
+ *     if (( CURRENT == 2 )); then
+ *       _describe '<program> command' l1_subs
+ *       return
+ *     fi
+ *     case $words[2] in
+ *       <sub-with-children>)
+ *         if (( CURRENT == 3 )); then
+ *           local -a l2_subs
+ *           l2_subs=(...)
+ *           _describe '<sub> subcommand' l2_subs
+ *         fi
+ *         ;;
+ *       ...
+ *     esac
+ *   }
+ *
+ *   _<program> "$@"
+ */
+export function generateZshCompletion(tree) {
+    const lines = [];
+    lines.push(`#compdef ${tree.name}`);
+    lines.push('');
+    lines.push(`_${tree.name}() {`);
+    lines.push('  local -a l1_subs');
+    lines.push('  l1_subs=(');
+    for (const sub of tree.subcommands) {
+        lines.push(`    '${sub.name}:${escapeZsh(sub.description)}'`);
+    }
+    lines.push('  )');
+    lines.push('');
+    lines.push('  if (( CURRENT == 2 )); then');
+    lines.push(`    _describe '${tree.name} command' l1_subs`);
+    lines.push('    return');
+    lines.push('  fi');
+    lines.push('');
+    const subsWithChildren = tree.subcommands.filter((s) => s.subcommands.length > 0);
+    if (subsWithChildren.length > 0) {
+        lines.push('  case $words[2] in');
+        for (const sub of subsWithChildren) {
+            lines.push(`    ${sub.name})`);
+            lines.push('      if (( CURRENT == 3 )); then');
+            lines.push('        local -a l2_subs');
+            lines.push('        l2_subs=(');
+            for (const s2 of sub.subcommands) {
+                lines.push(`          '${s2.name}:${escapeZsh(s2.description)}'`);
+            }
+            lines.push('        )');
+            lines.push(`        _describe '${sub.name} subcommand' l2_subs`);
+            lines.push('      fi');
+            lines.push('      ;;');
+        }
+        lines.push('  esac');
+    }
+    lines.push('}');
+    lines.push('');
+    lines.push(`_${tree.name} "$@"`);
+    lines.push('');
+    return lines.join('\n');
+}
+/**
+ * Emit a bash completion script.
+ *
+ * Format:
+ *   _<program>_completions() {
+ *     local cur="${COMP_WORDS[COMP_CWORD]}"
+ *     local cword=$COMP_CWORD
+ *     if [[ $cword -eq 1 ]]; then
+ *       COMPREPLY=( $(compgen -W "<sub1> <sub2> ..." -- "$cur") )
+ *       return
+ *     fi
+ *     case "${COMP_WORDS[1]}" in
+ *       <sub-with-children>)
+ *         if [[ $cword -eq 2 ]]; then
+ *           COMPREPLY=( $(compgen -W "<l2-1> <l2-2> ..." -- "$cur") )
+ *         fi
+ *         ;;
+ *     esac
+ *   }
+ *   complete -F _<program>_completions <program>
+ */
+export function generateBashCompletion(tree) {
+    const lines = [];
+    lines.push(`_${tree.name}_completions() {`);
+    lines.push('  local cur="${COMP_WORDS[COMP_CWORD]}"');
+    lines.push('  local cword=$COMP_CWORD');
+    lines.push('');
+    lines.push('  if [[ $cword -eq 1 ]]; then');
+    const l1Names = tree.subcommands.map((s) => s.name).join(' ');
+    lines.push(`    COMPREPLY=( $(compgen -W "${escapeBash(l1Names)}" -- "$cur") )`);
+    lines.push('    return');
+    lines.push('  fi');
+    lines.push('');
+    const subsWithChildren = tree.subcommands.filter((s) => s.subcommands.length > 0);
+    if (subsWithChildren.length > 0) {
+        lines.push('  case "${COMP_WORDS[1]}" in');
+        for (const sub of subsWithChildren) {
+            lines.push(`    ${sub.name})`);
+            lines.push('      if [[ $cword -eq 2 ]]; then');
+            const l2Names = sub.subcommands.map((s) => s.name).join(' ');
+            lines.push(`        COMPREPLY=( $(compgen -W "${escapeBash(l2Names)}" -- "$cur") )`);
+            lines.push('      fi');
+            lines.push('      ;;');
+        }
+        lines.push('  esac');
+    }
+    lines.push('}');
+    lines.push('');
+    lines.push(`complete -F _${tree.name}_completions ${tree.name}`);
+    lines.push('');
+    return lines.join('\n');
+}
+/**
+ * Top-level API: walk the commander program + emit a completion script
+ * for the requested shell.
+ */
+export function generateCompletion(program, shell) {
+    const tree = extractCommandTree(program);
+    if (shell === 'zsh')
+        return generateZshCompletion(tree);
+    if (shell === 'bash')
+        return generateBashCompletion(tree);
+    throw new UnsupportedShellError(shell);
+}
+//# sourceMappingURL=completion-generator.js.map

package/dist/lib/completion-generator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion-generator.js","sourceRoot":"","sources":["../../src/lib/completion-generator.ts"],"names":[],"mappings":"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"}

package/dist/lib/shell-rc.d.ts

@@ -0,0 +1,90 @@
+/**
+ * shell-rc.ts — Idempotent shell-rc file append + timestamped backup.
+ *
+ * Phase C1 of olam-operator-onboarding-parity (plan
+ * ~/.claude/plans/olam-operator-onboarding-parity.md).
+ *
+ * Phase C's `olam setup` wizard offers to add
+ *   eval "$(olam completion zsh)"
+ * to the operator's `~/.zshrc` / `~/.bashrc`. This module is the safety
+ * layer that:
+ *
+ *   1. Grep-checks a marker substring before writing — re-running the
+ *      wizard is a no-op (no duplicate eval lines, no n-times appended).
+ *   2. Backs the file up to `<rcPath>.olam-bak.<ISO-timestamp>` before
+ *      ANY mutation — recoverable if the operator decides they didn't
+ *      want the line.
+ *   3. Writes atomically via tmp-file + rename — `kill -9` mid-write
+ *      can't leave a half-written rc file.
+ *
+ * Decision 6 (plan): mirrors adb's `phase_mise_activation` pattern; the
+ * idempotency + backup pair is the operator-UX floor.
+ *
+ * Risk T4 mitigation (per plan + design doc): the grep-for-marker check
+ * uses `String.includes` not a per-line scan — a marker can match across
+ * whitespace if needed. The backup runs unconditionally before the
+ * append; corrupted rc states are recoverable via `mv <backup> <rcPath>`.
+ */
+export type AppendStatus = 'appended' | 'already-present' | 'no-rc-file';
+export interface AppendResult {
+    readonly status: AppendStatus;
+    /** Path to the timestamped backup file. `null` when `status !== 'appended'`. */
+    readonly backupPath: string | null;
+}
+export interface AppendOptions {
+    /** Absolute path to the operator's shell rc (e.g. `/Users/me/.zshrc`). */
+    readonly rcPath: string;
+    /**
+     * Substring searched for in the rc to detect "already present."
+     * Convention: a short stable token (e.g. `olam completion`) — distinct
+     * enough to avoid collisions with unrelated mentions, short enough that
+     * the operator can edit the exact line shape without breaking
+     * idempotency.
+     */
+    readonly marker: string;
+    /**
+     * The exact line to append. The function adds a trailing newline if
+     * not already present + ensures the previous line of the rc file ends
+     * with a newline (so the appended line isn't concatenated onto the
+     * previous line on rcs that don't end with `\n`).
+     */
+    readonly contentLine: string;
+    /**
+     * Optional clock override for deterministic test timestamps. Defaults
+     * to `() => new Date()`.
+     */
+    readonly clock?: () => Date;
+}
+/**
+ * Append `contentLine` to `rcPath` exactly once.
+ *
+ *   - rcPath doesn't exist           → returns `{status: 'no-rc-file', backupPath: null}`
+ *   - rcPath content already includes the marker substring
+ *                                    → returns `{status: 'already-present', backupPath: null}`
+ *   - otherwise: backup + append
+ *                                    → returns `{status: 'appended', backupPath: <ts-path>}`
+ *
+ * The write is atomic: content is staged to `<rcPath>.olam-tmp.<pid>`
+ * and then `renameSync`'d to `rcPath`. POSIX rename is atomic within a
+ * filesystem; a `kill -9` mid-call leaves either the backup-only state
+ * (no rc change) or the renamed-final state (atomic apply), never a
+ * half-written rc.
+ *
+ * The backup path uses a filesystem-safe ISO timestamp with `:` + `.`
+ * replaced by `-` (avoids colons in filenames on Windows for cross-
+ * platform consumers; not strictly required on macOS / Linux but
+ * cosmetically nicer).
+ */
+export declare function appendIdempotent(opts: AppendOptions): AppendResult;
+/**
+ * Resolve the operator's shell rc path based on `$SHELL`.
+ *
+ *   /bin/zsh, /usr/bin/zsh, /opt/homebrew/bin/zsh → ~/.zshrc
+ *   /bin/bash, /usr/bin/bash                     → ~/.bashrc
+ *   anything else                                → null (caller must surface)
+ *
+ * The caller decides what to do on null — typically Phase C surfaces a
+ * remedy message naming the supported shells.
+ */
+export declare function resolveShellRc(home: string, shellEnv: string | undefined): string | null;
+//# sourceMappingURL=shell-rc.d.ts.map

package/dist/lib/shell-rc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-rc.d.ts","sourceRoot":"","sources":["../../src/lib/shell-rc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAKH,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,iBAAiB,GAAG,YAAY,CAAC;AAEzE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,gFAAgF;IAChF,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED,MAAM,WAAW,aAAa;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,aAAa,GAAG,YAAY,CA0BlE;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAMxF"}

package/dist/lib/shell-rc.js

@@ -0,0 +1,91 @@
+/**
+ * shell-rc.ts — Idempotent shell-rc file append + timestamped backup.
+ *
+ * Phase C1 of olam-operator-onboarding-parity (plan
+ * ~/.claude/plans/olam-operator-onboarding-parity.md).
+ *
+ * Phase C's `olam setup` wizard offers to add
+ *   eval "$(olam completion zsh)"
+ * to the operator's `~/.zshrc` / `~/.bashrc`. This module is the safety
+ * layer that:
+ *
+ *   1. Grep-checks a marker substring before writing — re-running the
+ *      wizard is a no-op (no duplicate eval lines, no n-times appended).
+ *   2. Backs the file up to `<rcPath>.olam-bak.<ISO-timestamp>` before
+ *      ANY mutation — recoverable if the operator decides they didn't
+ *      want the line.
+ *   3. Writes atomically via tmp-file + rename — `kill -9` mid-write
+ *      can't leave a half-written rc file.
+ *
+ * Decision 6 (plan): mirrors adb's `phase_mise_activation` pattern; the
+ * idempotency + backup pair is the operator-UX floor.
+ *
+ * Risk T4 mitigation (per plan + design doc): the grep-for-marker check
+ * uses `String.includes` not a per-line scan — a marker can match across
+ * whitespace if needed. The backup runs unconditionally before the
+ * append; corrupted rc states are recoverable via `mv <backup> <rcPath>`.
+ */
+import { copyFileSync, existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+/**
+ * Append `contentLine` to `rcPath` exactly once.
+ *
+ *   - rcPath doesn't exist           → returns `{status: 'no-rc-file', backupPath: null}`
+ *   - rcPath content already includes the marker substring
+ *                                    → returns `{status: 'already-present', backupPath: null}`
+ *   - otherwise: backup + append
+ *                                    → returns `{status: 'appended', backupPath: <ts-path>}`
+ *
+ * The write is atomic: content is staged to `<rcPath>.olam-tmp.<pid>`
+ * and then `renameSync`'d to `rcPath`. POSIX rename is atomic within a
+ * filesystem; a `kill -9` mid-call leaves either the backup-only state
+ * (no rc change) or the renamed-final state (atomic apply), never a
+ * half-written rc.
+ *
+ * The backup path uses a filesystem-safe ISO timestamp with `:` + `.`
+ * replaced by `-` (avoids colons in filenames on Windows for cross-
+ * platform consumers; not strictly required on macOS / Linux but
+ * cosmetically nicer).
+ */
+export function appendIdempotent(opts) {
+    const { rcPath, marker, contentLine, clock = () => new Date() } = opts;
+    if (!existsSync(rcPath)) {
+        return { status: 'no-rc-file', backupPath: null };
+    }
+    const content = readFileSync(rcPath, 'utf-8');
+    if (content.includes(marker)) {
+        return { status: 'already-present', backupPath: null };
+    }
+    const timestamp = clock().toISOString().replace(/[:.]/g, '-');
+    const backupPath = `${rcPath}.olam-bak.${timestamp}`;
+    copyFileSync(rcPath, backupPath);
+    const separator = content.length === 0 || content.endsWith('\n') ? '' : '\n';
+    const trailing = contentLine.endsWith('\n') ? '' : '\n';
+    const nextContent = `${content}${separator}${contentLine}${trailing}`;
+    // Atomic write: tmp + rename. POSIX rename is atomic within filesystem.
+    const tmpPath = `${rcPath}.olam-tmp.${process.pid}`;
+    writeFileSync(tmpPath, nextContent, { encoding: 'utf-8' });
+    renameSync(tmpPath, rcPath);
+    return { status: 'appended', backupPath };
+}
+/**
+ * Resolve the operator's shell rc path based on `$SHELL`.
+ *
+ *   /bin/zsh, /usr/bin/zsh, /opt/homebrew/bin/zsh → ~/.zshrc
+ *   /bin/bash, /usr/bin/bash                     → ~/.bashrc
+ *   anything else                                → null (caller must surface)
+ *
+ * The caller decides what to do on null — typically Phase C surfaces a
+ * remedy message naming the supported shells.
+ */
+export function resolveShellRc(home, shellEnv) {
+    if (!shellEnv)
+        return null;
+    const basename = path.basename(shellEnv);
+    if (basename === 'zsh')
+        return path.join(home, '.zshrc');
+    if (basename === 'bash')
+        return path.join(home, '.bashrc');
+    return null;
+}
+//# sourceMappingURL=shell-rc.js.map

package/dist/lib/shell-rc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-rc.js","sourceRoot":"","sources":["../../src/lib/shell-rc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC5F,OAAO,IAAI,MAAM,WAAW,CAAC;AAmC7B;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAmB;IAClD,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,GAAG,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,EAAE,GAAG,IAAI,CAAC;IAEvE,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QACxB,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;IACpD,CAAC;IAED,MAAM,OAAO,GAAG,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9C,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QAC7B,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;IACzD,CAAC;IAED,MAAM,SAAS,GAAG,KAAK,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IAC9D,MAAM,UAAU,GAAG,GAAG,MAAM,aAAa,SAAS,EAAE,CAAC;IACrD,YAAY,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAEjC,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAC7E,MAAM,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IACxD,MAAM,WAAW,GAAG,GAAG,OAAO,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,EAAE,CAAC;IAEtE,wEAAwE;IACxE,MAAM,OAAO,GAAG,GAAG,MAAM,aAAa,OAAO,CAAC,GAAG,EAAE,CAAC;IACpD,aAAa,CAAC,OAAO,EAAE,WAAW,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;IAC3D,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAE5B,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,CAAC;AAC5C,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,QAA4B;IACvE,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC3B,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACzC,IAAI,QAAQ,KAAK,KAAK;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACzD,IAAI,QAAQ,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IAC3D,OAAO,IAAI,CAAC;AACd,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pleri/olam-cli",
-  "version": "0.1.109",
+  "version": "0.1.111",
   "type": "module",
   "bin": {
     "olam": "./bin/olam.cjs"