@soleur/opencode 0.0.0-stage → 1.0.0

package/skills/community/scripts/linkedin-community.sh

@@ -0,0 +1,750 @@
+#!/usr/bin/env bash
+# linkedin-community.sh -- LinkedIn API wrapper for community operations
+#
+# Usage: linkedin-community.sh <command> [args]
+# Commands:
+#   post-content --text "<text>" [--author "<urn>"]  - Post to LinkedIn (person or company page)
+#   fetch-metrics                  - Fetch aggregate Company Page metrics (org read scopes)
+#   fetch-activity                 - Fetch recent Company Page post metadata (org read scopes)
+#
+# fetch-metrics / fetch-activity history: implemented 2026-06-15. The prior
+# "requires Marketing Developer Platform (MDP) partner approval" premise was
+# incorrect — the org token already carries the read scopes
+# (r_organization_social, rw_organization_admin, r_organization_followers).
+# Collection is aggregate-only: share statistics + a single follower total +
+# recent org-authored post metadata. NO per-member data, NO follower-list
+# extraction, NO demographic facets.
+#
+# Environment variables (required):
+#   LINKEDIN_ACCESS_TOKEN      - OAuth 2.0 Bearer token for personal posts (60-day TTL)
+#   LINKEDIN_ORG_ACCESS_TOKEN  - OAuth 2.0 Bearer token for organization/company page
+#                                operations. Required for fetch-metrics/fetch-activity
+#                                (org read scopes: r_organization_social,
+#                                rw_organization_admin) and for org posts
+#                                (w_organization_social, --author urn:li:organization:*).
+#   LINKEDIN_ORG_ID            - Numeric organization id. Required for
+#                                fetch-metrics/fetch-activity (builds the org URN).
+#   LINKEDIN_PERSON_URN    - Person URN for posting (urn:li:person:{id}), optional if --author provided
+#   LINKEDIN_ALLOW_POST    - Set to "true" to enable posting (safety guard, default: disabled)
+#
+# Exit codes:
+#   0 - Success
+#   1 - General error
+#   2 - Retryable error (rate limit exhaustion)
+#
+# Output: JSON to stdout
+# Errors: Messages to stderr, exit 1
+
+set -euo pipefail
+
+# (#7797) Xtrace refusal -- the FIRST thing after `set …`, so nothing above it is
+# traced. This script ships to installed Soleur CLIs: the terminal it runs in
+# belongs to the founder, and `bash -x` would print their live LinkedIn
+# credentials. The `:+x` form tests non-emptiness WITHOUT expanding the value, so
+# the guard cannot leak the thing it is refusing over. CONDITIONAL, and that is
+# measured rather than inherited: every credential this file handles is bound
+# BEFORE the prologue runs (this script's own credential check reads them from
+# the environment, it never acquires one at runtime), so the guard can never be
+# empty while a credential is live -- and a founder tracing with none set keeps
+# full tracing.
+# Refusal goes to STDOUT, not stderr: agent runtimes surface stdout and swallow
+# stderr (constitution.md > Code Style > Always), and a swallowed security refusal
+# leaves the user with a bare `exit 78` and no text at all.
+case "$-" in
+  *x*)
+    if [ -n "${LINKEDIN_ACCESS_TOKEN:+x}${LINKEDIN_ORG_ACCESS_TOKEN:+x}" ]; then
+      printf 'Refusing to run under `bash -x`: LINKEDIN_ACCESS_TOKEN, LINKEDIN_ORG_ACCESS_TOKEN are set, and tracing would print them to your terminal. To trace safely, unset all of them and re-run.\n'
+      exit 78
+    fi
+    ;;
+esac
+
+# (#7873) `--disable` closes ~/.curlrc and `--noproxy '*'` closes the proxy
+# variables, but NEITHER touches the trust store or the TLS session-key log. On an
+# installed CLI the environment belongs to someone who is not us, so
+# a substituted `CURL_CA_BUNDLE` is a clean MITM of the founder's platform
+# token with every other guard fully intact, and `SSLKEYLOGFILE` is passive
+# decryption with no MITM at all. Matches the line in scripts/betterstack-query.sh.
+unset SSLKEYLOGFILE CURL_CA_BUNDLE SSL_CERT_FILE SSL_CERT_DIR CURL_HOME \
+      HOSTALIASES LOCALDOMAIN RES_OPTIONS
+
+# --- Transport-confinement diagnostics (#7873) --------------------------------
+# Every credentialed `curl` below carries `--disable --noproxy '*'` and discards
+# curl's own stderr (which can carry the URL). A failed request then has four
+# competing causes the founder cannot tell apart: the xtrace refusal, the proxy
+# this script deliberately bypassed, a ~/.curlrc that `--disable` dropped, or an
+# ordinary network failure. So each failure emits ONE structured marker carrying
+# all four discriminators, beside a human line that names the bypass instead of
+# blaming the founder's connectivity.
+SOLEUR_TRANSPORT_SCRIPT="linkedin-community.sh"
+SOLEUR_TRANSPORT_PLATFORM="LinkedIn"
+
+# The request helpers below run inside `$(...)`, where fd 1 is the capture pipe.
+# Save the script's real stdout so the marker reaches the founder's terminal (and
+# the always-on PostToolUse Bash extractor) instead of being swallowed into a
+# variable. The marker is on stdout BY DESIGN -- the call sites' `2>/dev/null` is
+# what keeps curl's URL-carrying stderr out of the transcript, and it must not be
+# able to suppress the diagnostic too.
+exec 3>&1
+
+# Which proxy variables are non-empty, or `none`.
+proxy_env_names() {
+  local names="" n
+  for n in HTTP_PROXY HTTPS_PROXY ALL_PROXY NO_PROXY http_proxy https_proxy all_proxy no_proxy; do
+    if [[ -n "${!n-}" ]]; then
+      names="${names},${n}"
+    fi
+  done
+  if [[ -z "$names" ]]; then
+    printf 'none'
+  else
+    printf '%s' "${names#,}"
+  fi
+}
+
+# True when a proxy this script deliberately bypasses is configured. NO_PROXY
+# alone is not one -- it only ever narrows proxying, so it cannot be the cause.
+proxy_bypassed() {
+  [[ -n "${HTTP_PROXY:-}${HTTPS_PROXY:-}${ALL_PROXY:-}${http_proxy:-}${https_proxy:-}${all_proxy:-}" ]]
+}
+
+# One line, eight fields, on the saved stdout.
+#
+# Two fields were literals in the first cut and are now MEASURED (#7898 review):
+# `noproxy_applied` was the constant "true", which ASSERTS the property instead of
+# observing it -- dropping --noproxy from a call site left the diagnostic still
+# claiming it was applied. It now reports whether a proxy was actually configured
+# for this request to bypass, which is the fact a reader needs. `refusal` was the
+# constant "none" at every call site, so the cause it exists to discriminate could
+# never appear; it now carries `env-rebind-refused` and `xtrace-credential-bound`.
+#
+# `tls_env_cleared` is new. The prologue unsets CURL_CA_BUNDLE/SSL_CERT_FILE et al,
+# which is correct against an attacker and BREAKS a founder whose corporate CA
+# arrives that way -- curl then exits 60 and, without this field, the event is
+# indistinguishable from an ordinary network failure.
+emit_transport_diag() {
+  local curl_exit="$1" refusal="$2" surface="installed-cli" curlrc="false" noproxy="false"
+  # The hosted sandbox always sets this (agent-env.ts > AGENT_ENV_OVERRIDES); an
+  # installed CLI does not. A label on the event, not a gate on behaviour.
+  if [[ -n "${CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC:-}" ]]; then
+    surface="in-sandbox"
+  fi
+  if [[ -f "${HOME:-}/.curlrc" ]]; then
+    curlrc="true"
+  fi
+  if proxy_bypassed; then
+    noproxy="true"
+  fi
+  printf 'SOLEUR_TRANSPORT_DIAG surface=%s script=%s curl_exit=%s refusal=%s proxy_env=%s curlrc_present=%s noproxy_applied=%s tls_env_cleared=%s\n' \
+    "$surface" "$SOLEUR_TRANSPORT_SCRIPT" "$curl_exit" "$refusal" \
+    "$(proxy_env_names)" "$curlrc" "$noproxy" "true" >&3
+}
+
+# Replaces the bare "Check your network connection and try again." on a
+# credentialed-curl failure. With a proxy set, that line blames the founder for a
+# bypass this script chose.
+report_transport_failure() {
+  local curl_exit="${1:-unknown}"
+  local detail="${2:-Failed to connect to the ${SOLEUR_TRANSPORT_PLATFORM} API.}"
+  emit_transport_diag "$curl_exit" "none"
+  echo "Error: ${detail}" >&2
+  # Ordered by how specific the evidence is. Each arm names something THIS script
+  # did, so the founder is never told to go debug their own network for a choice
+  # made here. The bare "check your connection" line is the LAST resort, not the
+  # default -- it was the default in the first cut, which meant a founder whose
+  # corporate CA or curlrc we had just discarded was blamed for it (#7898 review).
+  if [[ "$curl_exit" == "60" || "$curl_exit" == "35" || "$curl_exit" == "77" ]]; then
+    # 60 peer-certificate, 35 TLS handshake, 77 CA-bundle unreadable.
+    echo "This looks like a TLS trust failure. This script deliberately clears CURL_CA_BUNDLE, SSL_CERT_FILE, SSL_CERT_DIR and SSLKEYLOGFILE before the request, because those variables can redirect or expose a request carrying your ${SOLEUR_TRANSPORT_PLATFORM} credential." >&2
+    echo "If your machine needs a corporate CA to reach ${SOLEUR_TRANSPORT_PLATFORM}, that is not currently supported -- please open an issue at https://github.com/jikig-ai/soleur/issues." >&2
+  elif proxy_bypassed; then
+    echo "This request deliberately bypasses your proxy ($(proxy_env_names)), because a proxy can redirect a request carrying your ${SOLEUR_TRANSPORT_PLATFORM} token." >&2
+    echo "If you need Soleur to reach ${SOLEUR_TRANSPORT_PLATFORM} through your proxy, that is not currently supported -- please open an issue at https://github.com/jikig-ai/soleur/issues." >&2
+  elif [[ -f "${HOME:-}/.curlrc" ]]; then
+    echo "You have a ~/.curlrc, and this request deliberately ignores it (--disable), because a curlrc can redirect a request carrying your ${SOLEUR_TRANSPORT_PLATFORM} token. If it configures a proxy or a CA bundle you need, that is why this failed." >&2
+    echo "That is not currently supported -- please open an issue at https://github.com/jikig-ai/soleur/issues." >&2
+  else
+    echo "Check your network connection and try again." >&2
+  fi
+}
+
+# readonly (#7898 review): `cmd_verify` and friends run `set -a; source "$env_file"; set +a`
+# BELOW this line, so a plain assignment here is rebindable by the repo's .env --
+# which retargets the credentialed request while every transport flag stays intact.
+# That is the "--disable and --noproxy are intact and irrelevant" shape this change
+# exists to close, one layer up. readonly makes the destination non-rebindable.
+readonly LINKEDIN_API="https://api.linkedin.com"
+LINKEDIN_API_VERSION="202602"
+LINKEDIN_POST_MAX_LENGTH=3000
+
+# --- Bearer transport (#7843) ---
+# The access token is written into curl's STDIN config channel (`--config -`), never its
+# argument list, where every local user would read it from /proc/<pid>/cmdline. That
+# channel is line-oriented, so a token holding a quote and a newline could append a
+# `url = "..."` directive and make curl issue a second request. The guard refuses
+# anything outside the token alphabet BEFORE the value is formatted into the stream, and
+# never echoes it.
+_bearer_ok() { local LC_ALL=C; case "${1:-}" in ''|*[!A-Za-z0-9._~+/=-]*) return 1 ;; esac; }
+
+# Every authenticated request goes through here: ONE place owns the transport flags
+# (`--disable` first, `--noproxy '*'`), the token-shape guard and the header. Returns 120
+# with zero curl calls when the token is unusable; callers map that to a refusal. The
+# token is read as LINKEDIN_ACCESS_TOKEN at call time, so the function-local org-token
+# rebinding in cmd_fetch_metrics / cmd_fetch_activity keeps working.
+linkedin_authed_curl() {
+  _bearer_ok "${LINKEDIN_ACCESS_TOKEN:-}" || return 120
+  curl --disable --noproxy '*' "$@" --config - \
+    < <(printf 'header = "Authorization: Bearer %s"\n' "$LINKEDIN_ACCESS_TOKEN")
+}
+
+# --- Dependency checks ---
+
+require_jq() {
+  if ! command -v jq &>/dev/null; then
+    echo "Error: jq is required but not installed." >&2
+    echo "Install it: https://jqlang.github.io/jq/download/" >&2
+    exit 1
+  fi
+}
+
+# --- Credential validation ---
+
+require_credentials() {
+  if [[ -z "${LINKEDIN_ACCESS_TOKEN:-}" ]]; then
+    echo "Error: Missing LinkedIn credentials: LINKEDIN_ACCESS_TOKEN" >&2
+    echo "" >&2
+    echo "To configure:" >&2
+    echo "  1. Run: linkedin-setup.sh generate-token" >&2
+    echo "  2. Or set LINKEDIN_ACCESS_TOKEN manually" >&2
+    echo "  3. Run: linkedin-setup.sh verify" >&2
+    exit 1
+  fi
+}
+
+# Require the organization read credentials for fetch-metrics/fetch-activity.
+# Fails LOUD with `exit 1` (NOT `return 1`): the script runs `set -euo pipefail`,
+# and a `return 1` consumed in a conditional/pipeline does NOT terminate, which
+# would re-open the silent fall-through. Mirrors require_credentials (exit 1),
+# NOT cmd_post_content's return-1 guard.
+#
+# NEVER silent-fallback to the personal LINKEDIN_ACCESS_TOKEN — that token is
+# live in the cron spawn env and lacks the org read scopes; falling back yields
+# an opaque 401/400 instead of a clear "missing org creds" error
+# (learning 2026-04-26-linkedin-org-token-fallback-silent-400.md).
+require_org_credentials() {
+  local missing=()
+  [[ -n "${LINKEDIN_ORG_ACCESS_TOKEN:-}" ]] || missing+=("LINKEDIN_ORG_ACCESS_TOKEN")
+  # Fail-closed numeric check: a non-numeric (or unset) org id must never be
+  # interpolated into the request URL. When unset/empty the message names the
+  # bare var (matching the existing unset path); when set-but-non-numeric it
+  # names the constraint so the operator can fix it.
+  if [[ -z "${LINKEDIN_ORG_ID:-}" ]]; then
+    missing+=("LINKEDIN_ORG_ID")
+  elif [[ ! "${LINKEDIN_ORG_ID}" =~ ^[0-9]+$ ]]; then
+    missing+=("LINKEDIN_ORG_ID (must be numeric)")
+  fi
+  if (( ${#missing[@]} > 0 )); then
+    echo "Error: Missing LinkedIn organization credentials: ${missing[*]}" >&2
+    echo "fetch-metrics/fetch-activity read the operator's own Company Page" >&2
+    echo "aggregate insights and require the org token + org id." >&2
+    echo "Set LINKEDIN_ORG_ACCESS_TOKEN (org read scopes) and LINKEDIN_ORG_ID." >&2
+    exit 1
+  fi
+}
+
+# --- Response handler ---
+
+# Handle HTTP response status codes from LinkedIn API
+# Arguments: http_code body endpoint depth retry_cmd...
+# On 2xx: validates JSON, echoes body to stdout
+# On 429: sleeps and invokes retry_cmd (caller with incremented depth)
+# On error: prints diagnostic to stderr, exits 1 (or 2 for rate limit exhaustion)
+handle_response() {
+  local http_code="$1"
+  local body="$2"
+  local endpoint="$3"
+  local depth="$4"
+  shift 4
+  local -a retry_cmd=("$@")
+
+  case "$http_code" in
+    2[0-9][0-9])
+      # LinkedIn POST /rest/posts returns 201 with empty body -- that is valid
+      if [[ -n "$body" ]] && ! echo "$body" | jq . >/dev/null 2>&1; then
+        echo "Error: LinkedIn API returned malformed JSON for ${endpoint}" >&2
+        exit 1
+      fi
+      echo "$body"
+      ;;
+    401)
+      echo "Error: LinkedIn API returned 401 Unauthorized for ${endpoint}." >&2
+      echo "Your access token may be expired (60-day TTL)." >&2
+      echo "" >&2
+      echo "To fix:" >&2
+      echo "  1. Run: linkedin-setup.sh validate-credentials" >&2
+      echo "  2. If expired, run: linkedin-setup.sh generate-token" >&2
+      exit 1
+      ;;
+    403)
+      local message
+      message=$(echo "$body" | jq -r '.message // .code // "Access denied"' 2>/dev/null || echo "Access denied")
+      echo "Error: LinkedIn API returned 403 Forbidden for ${endpoint}: ${message}" >&2
+      exit 1
+      ;;
+    429)
+      if (( depth >= 3 )); then
+        echo "Error: LinkedIn API rate limit exceeded after 3 retries for ${endpoint}." >&2
+        exit 2
+      fi
+      echo "Rate limited. Retrying after 5s (attempt $((depth + 1))/3)..." >&2
+      sleep 5
+      "${retry_cmd[@]}"
+      ;;
+    *)
+      local message
+      message=$(echo "$body" | jq -r '.message // .code // "Unknown error"' 2>/dev/null || echo "Unknown error")
+      echo "Error: LinkedIn API returned HTTP ${http_code} for ${endpoint}: ${message}" >&2
+      exit 1
+      ;;
+  esac
+}
+
+# --- GET request helper ---
+
+# Make an authenticated GET request to the LinkedIn API
+# Arguments: endpoint [depth] [extra_header]
+#   extra_header - optional single "Name: value" header (e.g. the
+#                  "X-RestLi-Method: FINDER" header the Posts author-finder
+#                  requires). Forwarded on the 429-retry recursion so a retry
+#                  never silently drops it.
+# Retries on 429 up to 3 times
+get_request() {
+  local endpoint="$1"
+  local depth="${2:-0}"
+  local extra_header="${3:-}"
+
+  if (( depth >= 3 )); then
+    echo "Error: LinkedIn API rate limit exceeded after 3 retries for ${endpoint}." >&2
+    exit 2
+  fi
+
+  local url="${LINKEDIN_API}${endpoint}"
+
+  local -a header_args=()
+  if [[ -n "$extra_header" ]]; then
+    header_args=(-H "$extra_header")
+  fi
+
+  local response http_code body
+  local __curl_rc=0
+  response=$(linkedin_authed_curl -s -w "\n%{http_code}" \
+    -H "X-Restli-Protocol-Version: 2.0.0" \
+    -H "LinkedIn-Version: ${LINKEDIN_API_VERSION}" \
+    "${header_args[@]}" \
+    "$url" 2>/dev/null) || __curl_rc=$?
+  if (( __curl_rc == 120 )); then
+    echo "Error: LinkedIn access token has an unexpected shape; refusing to send it." >&2
+    exit 1
+  fi
+  if (( __curl_rc != 0 )); then
+    report_transport_failure "$__curl_rc" "Failed to connect to LinkedIn API."
+    exit 1
+  fi
+
+  http_code=$(echo "$response" | tail -1)
+  body=$(echo "$response" | sed '$d')
+
+  handle_response "$http_code" "$body" "$endpoint" "$depth" \
+    get_request "$endpoint" "$((depth + 1))" "$extra_header"
+}
+
+# --- POST request helper ---
+
+# Make an authenticated POST request to the LinkedIn API
+# Arguments: endpoint json_body [depth]
+# Captures response headers via temp file to extract x-restli-id
+# Only retries on 429 (POST is not idempotent)
+post_request() {
+  local endpoint="$1"
+  local json_body="$2"
+  local depth="${3:-0}"
+
+  local url="${LINKEDIN_API}${endpoint}"
+
+  local header_file
+  header_file=$(mktemp) || { echo "Error: Failed to create temp file." >&2; exit 1; }
+  # shellcheck disable=SC2064
+  trap "rm -f '$header_file'" EXIT
+
+  local response http_code body
+  local __curl_rc=0
+  response=$(linkedin_authed_curl -s -w "\n%{http_code}" \
+    -D "$header_file" \
+    -H "X-Restli-Protocol-Version: 2.0.0" \
+    -H "LinkedIn-Version: ${LINKEDIN_API_VERSION}" \
+    -H "Content-Type: application/json" \
+    -X POST -d "$json_body" \
+    "$url" 2>/dev/null) || __curl_rc=$?
+  if (( __curl_rc == 120 )); then
+    rm -f "$header_file"
+    echo "Error: LinkedIn access token has an unexpected shape; refusing to send it." >&2
+    exit 1
+  fi
+  if (( __curl_rc != 0 )); then
+    rm -f "$header_file"
+    report_transport_failure "$__curl_rc" "Failed to connect to LinkedIn API."
+    exit 1
+  fi
+
+  http_code=$(echo "$response" | tail -1)
+  body=$(echo "$response" | sed '$d')
+
+  # On 429, retry (rate limit returned before post is created)
+  if [[ "$http_code" == "429" ]]; then
+    rm -f "$header_file"
+    handle_response "$http_code" "$body" "$endpoint" "$depth" \
+      post_request "$endpoint" "$json_body" "$((depth + 1))"
+    return
+  fi
+
+  # For non-429 errors on POST, fail immediately (non-idempotent)
+  if [[ ! "$http_code" =~ ^2[0-9][0-9]$ ]]; then
+    rm -f "$header_file"
+    handle_response "$http_code" "$body" "$endpoint" "$depth"
+    return
+  fi
+
+  # Success: extract x-restli-id from response headers
+  local restli_id=""
+  if [[ -f "$header_file" ]]; then
+    restli_id=$(grep -i '^x-restli-id:' "$header_file" | sed 's/^[^:]*: *//' | tr -d '\r' || true)
+  fi
+  rm -f "$header_file"
+
+  # Return JSON with post URN
+  if [[ -n "$restli_id" ]]; then
+    jq -n --arg id "$restli_id" '{"post_urn": $id}'
+  else
+    echo '{"post_urn": null}' >&2
+    echo "Warning: Post created but x-restli-id header not found in response." >&2
+    # Still return valid JSON
+    echo '{}'
+  fi
+}
+
+# --- LinkedIn "Little Text Format" handling ---
+#
+# The Posts API commentary field is "Little Text Format": the characters
+# \ | { } [ ] ( ) < > * ~ are reserved, and LinkedIn silently TRUNCATES the
+# post at the first unescaped occurrence (observed 2026-06-10: nine org posts
+# cut mid-sentence at the first "(", which also dropped the trailing article
+# links). '#' and '@' stay unescaped so hashtags and mentions keep their
+# linking behavior; '_' stays unescaped because escaping it corrupts URLs
+# (utm_source=...) and it does not trigger the truncation failure class.
+
+sanitize_commentary() {
+  # Markdown-source artifacts that must not reach LinkedIn verbatim: strip
+  # whole-line HTML comments (e.g. markdownlint directives), unwrap
+  # <https://...> autolinks (angle brackets are reserved characters), and
+  # drop trailing horizontal rules / blank lines.
+  sed -e '/^[[:space:]]*<!--.*-->[[:space:]]*$/d' \
+      -e 's/<\(https\{0,1\}:\/\/[^>]*\)>/\1/g' |
+    awk '{ lines[++n] = $0 }
+         END {
+           while (n > 0 && (lines[n] ~ /^[[:space:]]*$/ || lines[n] ~ /^[[:space:]]*-{3,}[[:space:]]*$/)) n--
+           for (i = 1; i <= n; i++) print lines[i]
+         }'
+}
+
+escape_little_text() {
+  local t="$1"
+  t="${t//\\/\\\\}"
+  t="${t//|/\\|}"
+  t="${t//\{/\\\{}"
+  t="${t//\}/\\\}}"
+  t="${t//\[/\\[}"
+  t="${t//\]/\\]}"
+  t="${t//(/\\(}"
+  t="${t//)/\\)}"
+  t="${t//</\\<}"
+  t="${t//>/\\>}"
+  t="${t//\*/\\*}"
+  t="${t//\~/\\~}"
+  printf '%s' "$t"
+}
+
+# --- Commands ---
+
+cmd_post_content() {
+  # Guard: require explicit opt-in to post.
+  if [[ "${LINKEDIN_ALLOW_POST:-}" != "true" ]]; then
+    echo "Error: LINKEDIN_ALLOW_POST is not set to 'true'." >&2
+    echo "Set LINKEDIN_ALLOW_POST=true to enable posting." >&2
+    return 1
+  fi
+
+  local text=""
+  local author_override=""
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --text)
+        text="${2:-}"
+        if [[ -z "$text" ]]; then
+          echo "Error: --text requires a non-empty value." >&2
+          exit 1
+        fi
+        shift 2
+        ;;
+      --author)
+        author_override="${2:-}"
+        if [[ -z "$author_override" ]]; then
+          echo "Error: --author requires a non-empty value." >&2
+          exit 1
+        fi
+        shift 2
+        ;;
+      *)
+        echo "Error: Unknown option '$1'" >&2
+        echo "Usage: linkedin-community.sh post-content --text \"<text>\" [--author \"<urn>\"]" >&2
+        exit 1
+        ;;
+    esac
+  done
+
+  if [[ -z "$text" ]]; then
+    echo "Error: --text is required." >&2
+    echo "Usage: linkedin-community.sh post-content --text \"<text>\"" >&2
+    exit 1
+  fi
+
+  # Strip markdown-source artifacts before the length check (the limit
+  # applies to visible characters; Little Text escape backslashes added
+  # below do not count toward it).
+  text=$(printf '%s\n' "$text" | sanitize_commentary)
+
+  if (( ${#text} > LINKEDIN_POST_MAX_LENGTH )); then
+    echo "Error: Post text is ${#text} characters, exceeds LinkedIn's ${LINKEDIN_POST_MAX_LENGTH}-character limit." >&2
+    exit 1
+  fi
+
+  local escaped_text
+  escaped_text=$(escape_little_text "$text")
+
+  # Build request body (--author overrides default LINKEDIN_PERSON_URN)
+  local author="${author_override:-${LINKEDIN_PERSON_URN:-}}"
+  if [[ -z "$author" ]]; then
+    echo "Error: No author specified. Provide --author or set LINKEDIN_PERSON_URN." >&2
+    exit 1
+  fi
+
+  # Normalize bare person IDs: LinkedIn API requires full URN (urn:li:person:<id>).
+  # LINKEDIN_PERSON_URN is often stored as just the ID portion without the prefix.
+  if [[ "$author" != urn:* ]]; then
+    author="urn:li:person:${author}"
+  fi
+
+  # Organization posts require w_organization_social scope -- use LINKEDIN_ORG_ACCESS_TOKEN.
+  if [[ "$author" == urn:li:organization:* ]]; then
+    if [[ -z "${LINKEDIN_ORG_ACCESS_TOKEN:-}" ]]; then
+      echo "Error: LINKEDIN_ORG_ACCESS_TOKEN is required for organization posts (w_organization_social scope)." >&2
+      echo "Set LINKEDIN_ORG_ACCESS_TOKEN to a token with w_organization_social scope." >&2
+      exit 1
+    fi
+    LINKEDIN_ACCESS_TOKEN="$LINKEDIN_ORG_ACCESS_TOKEN"
+  fi
+
+  local json_body
+  json_body=$(jq -n \
+    --arg author "$author" \
+    --arg text "$escaped_text" \
+    '{
+      author: $author,
+      commentary: $text,
+      visibility: "PUBLIC",
+      distribution: {
+        feedDistribution: "MAIN_FEED",
+        targetEntities: [],
+        thirdPartyDistributionChannels: []
+      },
+      lifecycleState: "PUBLISHED",
+      isReshareDisabledByAuthor: false
+    }')
+
+  local result
+  result=$(post_request "/rest/posts" "$json_body")
+
+  echo "$result"
+  echo "Post created successfully." >&2
+}
+
+# Fetch aggregate Company Page metrics: lifetime share statistics + a single
+# follower total. Aggregate-only — no demographic facets, no per-member data.
+cmd_fetch_metrics() {
+  # Defense-in-depth: re-check org creds as the FIRST line (dispatch also checks).
+  # The personal LINKEDIN_ACCESS_TOKEN is live in the spawn env, so a direct
+  # call to this function must not be able to fall through to it.
+  require_org_credentials
+
+  # Scope the org token function-locally so get_request's Bearer header uses it
+  # WITHOUT leaking into the personal path (safer than cmd_post_content's global
+  # mutation at the org-post branch).
+  local LINKEDIN_ACCESS_TOKEN="$LINKEDIN_ORG_ACCESS_TOKEN"
+
+  local org_urn="urn%3Ali%3Aorganization%3A${LINKEDIN_ORG_ID}"
+
+  # --- Aggregate share statistics (lifetime). ---
+  local share_body
+  share_body=$(get_request \
+    "/rest/organizationalEntityShareStatistics?q=organizationalEntity&organizationalEntity=${org_urn}")
+
+  # Shape validation BEFORE any `// 0` fallbacks (silent-failure HIGH-1):
+  # handle_response validated only JSON parseability, not shape. An empty
+  # `.elements` (e.g. token lacks ADMINISTRATOR role) or a wrong shape must NOT
+  # render as fake zeros — emit an explicit error and exit 1.
+  if ! echo "$share_body" | jq -e '(.elements[0].totalShareStatistics | type) == "object"' >/dev/null 2>&1; then
+    echo "Error: organizationalEntityShareStatistics returned no usable totalShareStatistics for org ${LINKEDIN_ORG_ID}." >&2
+    echo "The org token may lack the ADMINISTRATOR role, or the response shape changed." >&2
+    exit 1
+  fi
+
+  local share_statistics
+  share_statistics=$(echo "$share_body" | jq '
+    .elements[0].totalShareStatistics as $s |
+    {
+      impressions: ($s.impressionCount // 0),
+      unique_impressions: ($s.uniqueImpressionsCount // 0),
+      clicks: ($s.clickCount // 0),
+      likes: ($s.likeCount // 0),
+      comments: ($s.commentCount // 0),
+      shares: ($s.shareCount // 0),
+      engagement: ($s.engagement // 0)
+    }')
+
+  # --- Single follower total via networkSizes. ---
+  # Partial-failure policy (silent-failure HIGH-2): the networkSizes call must
+  # not abort the (more important) share-stats result. Run it in a subshell whose
+  # non-zero exit is tolerated; on failure total_followers degrades to null with
+  # a stderr warning rather than get_request's default `exit`.
+  local total_followers="null"
+  local network_body
+  if network_body=$(get_request \
+    "/rest/networkSizes/${org_urn}?edgeType=COMPANY_FOLLOWED_BY_MEMBER" 2>/dev/null); then
+    local size
+    size=$(echo "$network_body" | jq -r '.firstDegreeSize // empty' 2>/dev/null || true)
+    if [[ "$size" =~ ^[0-9]+$ ]]; then
+      # Only a clean non-negative integer is trusted: it is injected via
+      # `--argjson total_followers` into the final emit, where a non-numeric
+      # value would crash jq under set -e and defeat the degrade-to-null
+      # contract. Anything else degrades to null (same path as a failed fetch).
+      total_followers="$size"
+    elif [[ -n "$size" ]]; then
+      echo "Warning: networkSizes returned non-numeric firstDegreeSize ('${size}') for org ${LINKEDIN_ORG_ID}; total_followers=null." >&2
+    else
+      echo "Warning: networkSizes returned no firstDegreeSize for org ${LINKEDIN_ORG_ID}; total_followers=null." >&2
+    fi
+  else
+    echo "Warning: networkSizes call failed for org ${LINKEDIN_ORG_ID}; total_followers=null." >&2
+  fi
+
+  jq -n \
+    --arg org_id "$LINKEDIN_ORG_ID" \
+    --argjson total_followers "$total_followers" \
+    --argjson share_statistics "$share_statistics" \
+    '{
+      org_id: $org_id,
+      total_followers: $total_followers,
+      share_statistics: $share_statistics
+    }'
+}
+
+# Fetch recent Company Page post metadata via the Posts author-finder.
+# Aggregate-only — post metadata, no commenter/liker identities.
+cmd_fetch_activity() {
+  require_org_credentials
+
+  local LINKEDIN_ACCESS_TOKEN="$LINKEDIN_ORG_ACCESS_TOKEN"
+
+  local org_urn="urn%3Ali%3Aorganization%3A${LINKEDIN_ORG_ID}"
+
+  # The Posts author-finder requires the X-RestLi-Method: FINDER header, threaded
+  # through get_request's optional 3rd arg (forwarded on the 429 recursion).
+  local posts_body
+  posts_body=$(get_request \
+    "/rest/posts?author=${org_urn}&q=author&count=10&sortBy=LAST_MODIFIED" \
+    0 \
+    "X-RestLi-Method: FINDER")
+
+  # Shape validation BEFORE the `.elements[]` iteration: mirrors
+  # cmd_fetch_metrics's guard. A missing/null `.elements` (e.g. token lacks the
+  # required role, or the response shape changed) makes `.elements[]` crash jq
+  # ("Cannot iterate over null", exit 5) under set -e — emit an explicit error
+  # and exit 1 instead. A present-but-empty `elements: []` still succeeds and
+  # yields `{"posts": []}`.
+  if ! echo "$posts_body" | jq -e '(.elements | type) == "array"' >/dev/null 2>&1; then
+    echo "Error: posts author-finder returned no usable elements array for org ${LINKEDIN_ORG_ID}." >&2
+    echo "The org token may lack the required role, or the response shape changed." >&2
+    exit 1
+  fi
+
+  # commentary is operator-authored Page-public post text. If a post @mentions a
+  # member it flows to the digest, but the LIA's no-@mention posting TOM bounds
+  # this — no inbound filter needed. Emit metadata only; no author/commenter/
+  # liker identities. `//` fallbacks preserve each post even if a field is absent
+  # (learning 2026-03-10-jq-generator-silent-data-loss.md).
+  echo "$posts_body" | jq '
+    {
+      posts: [
+        .elements[] | {
+          id: .id,
+          commentary: (.commentary // null),
+          published_at: (.publishedAt // .createdAt // null),
+          lifecycle_state: (.lifecycleState // null)
+        }
+      ]
+    }'
+}
+
+# --- Main ---
+
+main() {
+  local command="${1:-}"
+  shift || true
+
+  if [[ -z "$command" ]]; then
+    echo "Usage: linkedin-community.sh <command> [args]" >&2
+    echo "" >&2
+    echo "Commands:" >&2
+    echo "  post-content --text \"<text>\" [--author \"<urn>\"]  - Post to LinkedIn" >&2
+    echo "  fetch-metrics                 - Fetch aggregate Company Page metrics (org read scopes)" >&2
+    echo "  fetch-activity                - Fetch recent Company Page post metadata (org read scopes)" >&2
+    exit 1
+  fi
+
+  require_jq
+
+  case "$command" in
+    fetch-metrics)
+      require_org_credentials
+      cmd_fetch_metrics
+      ;;
+    fetch-activity)
+      require_org_credentials
+      cmd_fetch_activity
+      ;;
+    post-content)
+      require_credentials
+      cmd_post_content "$@"
+      ;;
+    *)
+      echo "Error: Unknown command '${command}'" >&2
+      echo "Run 'linkedin-community.sh' without arguments for usage." >&2
+      exit 1
+      ;;
+  esac
+}
+
+# Guard: allow sourcing without executing main (for test harness)
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+  main "$@"
+fi