socialcli 0.3.0__py3-none-any.whl

socialctl/adapters/youtube.py

@@ -0,0 +1,331 @@
+'YouTube Data API v3 resumable video upload.\n\nThe adapter validates one user-supplied video, initializes a resumable upload,\nstreams the original bytes and records the returned resource ID. Upload success\nis distinct from visibility observations. Expected I/O, network and response\nfailures become PostResult errors rather than escaping the adapter boundary.\nKnown credentials are redacted from provider errors.'
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+
+import httpx
+
+from socialctl.adapters.base import ADAPTADORES, Adapter
+from socialctl.adapters.errores import mensaje_de_error
+from socialctl.auth import obtener_token
+from socialctl.brands import Brand
+from socialctl.formatter import (
+    PLATFORM_SPECS,
+    privacidad_efectiva,
+    texto_publicado,
+    youtube_tags,
+)
+from socialctl.models import Platform, PlatformPost, PostResult, PostStatus
+
+URL_UPLOAD = "https://www.googleapis.com/upload/youtube/v3/videos"
+URL_VIDEOS = "https://www.googleapis.com/youtube/v3/videos"
+
+# MIME type declarado en la subida resumible. Este proyecto no detecta el
+# tipo MIME real de cada fichero (los adaptadores no llevan una tabla de
+# extensión→MIME); "video/*" es el valor de comodín que la propia
+# documentación de Google da como ejemplo válido para
+# X-Upload-Content-Type ("The MIME type of the file (e.g., 'video/*')",
+# developers.google.com/youtube/v3/guides/using_resumable_upload_protocol),
+# así que sirve sin necesidad de esa tabla. Se usa el mismo valor en el
+# POST inicial y en el PUT final porque la documentación exige que
+# coincidan ("both of which must match the values provided in the initial
+# request").
+_TIPO_MIME_VIDEO = "video/*"
+
+
+class YouTubeAdapter(Adapter):
+    'Upload one video through the YouTube Data API v3 resumable protocol.'
+
+    platform = Platform.YOUTUBE
+
+    def publish(self, post: PlatformPost, brand: Brand, client: httpx.Client) -> PostResult:
+        'Publish a validated post; convert every failure to an error PostResult.'
+        spec = PLATFORM_SPECS[self.platform]
+        if len(post.media) > spec.max_media:
+            return self._error(
+                f"this endpoint supports at most {spec.max_media} file; "
+                'it does not publish carousels'
+            )
+
+        try:
+            return self._publicar(post, brand, client)
+        except Exception as exc:
+            return self._error(
+                f"an unexpected YouTube error occurred "
+                f"({type(exc).__name__}): {exc}"
+            )
+
+    def _publicar(self, post: PlatformPost, brand: Brand, client: httpx.Client) -> PostResult:
+        'Execute publication with explicit handling of expected failures.'
+        if not post.media:
+            return self._error(
+                'no video to upload: the post has no media attached'
+            )
+
+        video = post.media[0]
+
+        try:
+            token = obtener_token(brand, self.platform, client)
+        except Exception as exc:
+            return self._error(str(exc))
+
+        # El tamaño real del fichero hace falta ya para el POST inicial (la
+        # cabecera X-Upload-Content-Length, ver más abajo), no solo para el
+        # PUT: por eso se calcula aquí, antes de tocar la red, con el mismo
+        # manejo de errores de E/S que antes solo cubría el PUT. Como
+        # beneficio adicional, un fichero ya borrado o ilegible se detecta
+        # antes de gastar una petición de red en abrir una sesión de subida
+        # que no se podría completar.
+        try:
+            tamano = video.path.stat().st_size
+        except FileNotFoundError:
+            return self._error(
+                f"the video file no longer exists on disk: {video.path}"
+            )
+        except IsADirectoryError:
+            return self._error(
+                f"the video path points to a directory, not a file: {video.path}"
+            )
+        except PermissionError:
+            return self._error(
+                f"the video file is not readable: {video.path}"
+            )
+        except OSError as exc:
+            return self._error(
+                f"could not read the video file from disk ({video.path}): {exc}"
+            )
+
+        # privacidad_efectiva() (socialctl/formatter.py) ya resuelve el valor
+        # por defecto ("private") cuando post.privacy no se ha indicado: por
+        # decisión explícita del proyecto, ningún vídeo sale público sin que
+        # el usuario lo pida (el canal tiene ~5000 suscriptores). "public",
+        # "private" y "unlisted" son los tres valores que admite
+        # status.privacyStatus (confirmado con Context7, ver
+        # PLATFORM_SPECS[Platform.YOUTUBE].valores_privacidad).
+        requested_privacy = privacidad_efectiva(post)
+        metadatos = {
+            "snippet": {
+                "title": post.title,
+                "description": texto_publicado(post),
+                "tags": youtube_tags(post),
+            },
+            "status": {"privacyStatus": requested_privacy},
+        }
+
+        try:
+            inicio = client.post(
+                URL_UPLOAD,
+                params={"uploadType": "resumable", "part": "snippet,status"},
+                headers={
+                    "Authorization": f"Bearer {token}",
+                    # Ambas son "Required" en la tabla de cabeceras del paso 1
+                    # del flujo resumible (Step 1 - Start a resumable
+                    # session): el tamaño total del fichero y su MIME type.
+                    "X-Upload-Content-Length": str(tamano),
+                    "X-Upload-Content-Type": _TIPO_MIME_VIDEO,
+                },
+                json=metadatos,
+            )
+        except httpx.TimeoutException:
+            return self._error(
+                'timed out contacting YouTube to '
+                'initialize the upload'
+            )
+        except httpx.HTTPError:
+            return self._error(
+                'could not connect to YouTube to initialize the upload'
+            )
+
+        if inicio.status_code != 200:
+            return self._error(mensaje_de_error(inicio, token))
+
+        destino = inicio.headers.get("Location")
+        if not destino:
+            return self._error('YouTube did not return an upload URL')
+
+        try:
+            with video.path.open("rb") as fichero:
+                subida = client.put(
+                    destino,
+                    headers={
+                        "Authorization": f"Bearer {token}",
+                        "Content-Length": str(tamano),
+                        # "Required" en el paso 3 del flujo resumible (Step 3
+                        # - Upload the video file), y debe coincidir con el
+                        # X-Upload-Content-Type enviado en el POST inicial.
+                        "Content-Type": _TIPO_MIME_VIDEO,
+                    },
+                    content=fichero,
+                    timeout=None,
+                )
+        except FileNotFoundError:
+            return self._error(
+                f"the video file no longer exists on disk: {video.path}"
+            )
+        except IsADirectoryError:
+            return self._error(
+                f"the video path points to a directory, not a file: {video.path}"
+            )
+        except PermissionError:
+            return self._error(
+                f"the video file is not readable: {video.path}"
+            )
+        except OSError as exc:
+            # Cualquier otro fallo de E/S al leer el fichero (disco dañado,
+            # demasiados descriptores abiertos, etc.): no es ninguno de los
+            # casos anteriores, pero tampoco debe escapar como excepción.
+            return self._error(
+                f"could not read the video file from disk ({video.path}): {exc}"
+            )
+        except httpx.InvalidURL as exc:
+            # La URL de subida (`destino`) la devuelve YouTube en la cabecera
+            # `Location` de la respuesta al POST inicial: no es un literal
+            # nuestro, así que puede llegar mal formada (puerto no numérico,
+            # longitud desmesurada, etc.) y `httpx` la rechaza al construir la
+            # petición, antes de llegar a la red.
+            return self._error(
+                f"YouTube returned an invalid upload URL: {exc}"
+            )
+        except httpx.TimeoutException:
+            return self._error(
+                'timed out uploading the video to YouTube'
+            )
+        except httpx.HTTPError:
+            return self._error(
+                'could not connect to YouTube to upload the video'
+            )
+
+        if subida.status_code not in (200, 201):
+            return self._error(mensaje_de_error(subida, token))
+
+        try:
+            recurso_subido = subida.json()
+            video_id = recurso_subido["id"]
+        except json.JSONDecodeError:
+            return self._error(
+                'YouTube returned an invalid JSON response after '
+                'uploading the video'
+            )
+        except KeyError:
+            return self._error(
+                'YouTube returned no video ID after the upload'
+            )
+
+        if not isinstance(video_id, str) or not video_id:
+            return self._error('YouTube returned an invalid video ID after the upload')
+
+        result = PostResult(
+            platform=self.platform,
+            status=PostStatus.PUBLICADO,
+            platform_id=video_id,
+            url=f"https://www.youtube.com/watch?v={video_id}",
+            requested_privacy=requested_privacy,
+        )
+        try:
+            self._apply_observation(result, recurso_subido)
+        except Exception:
+            # The ID is already authoritative. Optional fields in the upload
+            # response can be malformed, but can never turn that confirmed
+            # upload back into a retryable error.
+            result.warnings.append(
+                'The upload was confirmed, but its '
+                'initial visibility could not be interpreted.'
+            )
+        self._readback(result, token, client)
+        return result
+
+    @staticmethod
+    def _observation(
+        resource: object,
+    ) -> tuple[str | None, str | None, str | None, bool] | None:
+        if not isinstance(resource, dict):
+            return None
+        status = resource.get("status")
+        processing = resource.get("processingDetails")
+        status = status if isinstance(status, dict) else {}
+        processing = processing if isinstance(processing, dict) else {}
+        privacy = status.get("privacyStatus")
+        publish_at = status.get("publishAt")
+        processing_status = processing.get("processingStatus")
+        privacy = privacy if isinstance(privacy, str) and privacy else None
+        valid_visibility = privacy is not None
+        if isinstance(publish_at, str) and publish_at:
+            try:
+                parsed_publish_at = datetime.fromisoformat(
+                    publish_at.replace("Z", "+00:00")
+                )
+            except ValueError:
+                publish_at = None
+            else:
+                if parsed_publish_at.utcoffset() is None:
+                    publish_at = None
+        elif publish_at is not None:
+            publish_at = None
+        else:
+            publish_at = None
+        processing_status = (
+            processing_status
+            if isinstance(processing_status, str) and processing_status
+            else None
+        )
+        if not valid_visibility and processing_status is None:
+            return None
+        return privacy, publish_at, processing_status, valid_visibility
+
+    @classmethod
+    def _apply_observation(cls, result: PostResult, resource: object) -> bool:
+        observation = cls._observation(resource)
+        if observation is None:
+            return False
+        privacy, publish_at, processing_status, valid_visibility = observation
+        if valid_visibility:
+            # `privacyStatus` anchors a complete visibility snapshot. Its
+            # absence in a processing-only readback must not erase a status
+            # returned by the upload or move that older status to a new time.
+            result.observed_privacy = privacy
+            result.observed_publish_at = publish_at
+            result.visibility_observed_at = datetime.now(timezone.utc).isoformat()
+        if processing_status is not None:
+            # Processing has no separate timestamp in PostResult. Preserve
+            # the existing visibility timestamp when this is the only field
+            # returned, rather than attributing old privacy data to this GET.
+            result.observed_processing_status = processing_status
+        return True
+
+    def _readback(self, result: PostResult, token: str, client: httpx.Client) -> None:
+        """Read one resource snapshot; upload success remains authoritative."""
+        try:
+            response = client.get(
+                URL_VIDEOS,
+                params={
+                    "id": result.platform_id,
+                    "part": "status,processingDetails",
+                },
+                headers={"Authorization": f"Bearer {token}"},
+            )
+            if response.status_code != 200:
+                result.warnings.append(
+                    'The upload was confirmed, but its '
+                    f"visibility could not be verified (YouTube returned HTTP {response.status_code})."
+                )
+                return
+            payload = response.json()
+            items = payload.get("items") if isinstance(payload, dict) else None
+            resource = items[0] if isinstance(items, list) and items else None
+            if resource is None or not self._apply_observation(result, resource):
+                result.warnings.append(
+                    'The upload was confirmed, but YouTube did not return a '
+                    'usable visibility observation.'
+                )
+        except Exception:
+            result.warnings.append(
+                'The upload was confirmed, but its visibility could not be verified.'
+            )
+
+    def _error(self, mensaje: str) -> PostResult:
+        return PostResult(platform=self.platform, status=PostStatus.ERROR, error=mensaje)
+
+
+ADAPTADORES[Platform.YOUTUBE] = YouTubeAdapter

socialctl/agent_errors.py

@@ -0,0 +1,176 @@
+"""Conservative next-action hints from typed failures, never string guessing."""
+from socialctl.connections.saas_client import MESSAGES, ServiceRejected, TransportFailure
+
+_ACTIONS = {
+    'privacy_acceptance_required': 'user_action',
+    'assistant_consent_required': 'user_action',
+    'platform_not_allowed': 'user_action',
+    'installation_permissions_invalid': 'user_action',
+    'provider_authorization_expired': 'reconnect',
+    'provider_permissions_changed': 'reconnect',
+    'renewal_uncertain': 'reconcile',
+    'renewal_pending': 'retry_later',
+    'renewal_retryable': 'retry_later',
+    'renewal_required': 'user_action',
+    'provider_configuration': 'contact_support',
+    'installation_revoked': 'sign_in',
+    'installation_expired': 'sign_in',
+    'activation_required': 'recover',
+    'subscription_required': 'user_action',
+    'brand_limit': 'user_action',
+    'connection_inactive': 'user_action',
+    'connection_unavailable': 'user_action',
+    'connection_replaced': 'user_action',
+    'connection_changed': 'user_action',
+    'user_authorization_required': 'user_action',
+    'operation_conflict': 'user_action',
+    'operation_rejected': 'inspect',
+    'operation_uncertain': 'reconcile',
+}
+
+
+# Only fixed internal codes acquire action semantics. Provider text is diagnostic,
+# never a command, an expiry signal or evidence that a write was not accepted.
+_CATALOG = {
+    'approval_mismatch': ('user_action', 'The supplied approval does not match this exact preview. Obtain the owner approval before applying.'),
+    'approval_required': ('user_action', 'Show the complete preview and obtain explicit approval of its exact fingerprint.'),
+    'operation_cancelled': ('inspect', 'Approval was cancelled. No write was started by this command.'),
+    'publication_pending': ('user_action', 'Complete or verify this existing submission in the platform; do not upload it again.'),
+    'comment_incomplete': ('reconcile', 'Inspect the existing first-comment attempt and its ChangeSet. Do not upload the media again.'),
+    'validation_failed': ('correct_input', 'Review every blocking validation item in the complete preview before approval.'),
+    'reporting_incomplete': ('inspect', 'Some report observations could not be collected. Inspect the durable result and journal before further action; do not replay a write.'),
+    'native_wait': ('wait', 'Keep this approved job and wait for its delivery window; do not create a duplicate.'),
+    'native_dispatch': ('inspect', 'Inspect the approved route and delivery readiness before dispatching this existing job.'),
+    'native_ui_required': ('user_action', 'Continue the exact approved handoff in the official platform UI. A submitted boundary permits readback only.'),
+    'native_verify': ('reconcile', 'Collect fresh official evidence for this existing job. Scheduling alone does not prove publication.'),
+    'operation_failed': ('inspect', 'Inspect the current state before taking another action.'),
+    'service_rejected': ('inspect', 'Review account status and service availability.'),
+    'local_configuration': ('user_action', 'Check local URL, proxy and CA configuration. No server rejection was received; keep credentials unchanged.'),
+    'invalid_local_state': ('user_action', 'Review arguments, local account state and protected credential storage.'),
+    'read_partial': ('inspect', 'Keep verified observations and inspect coverage before another read.'),
+    'read_deadline': ('adjust_read', 'Keep verified observations; reduce read scope or increase the read budget.'),
+    'response_too_large': ('adjust_read', 'Reduce read scope or page size; do not repeat the same oversized response.'),
+    'read_interrupted': ('inspect', 'Keep verified observations. Resume only if the read is still requested.'),
+    'not_attempted': ('inspect', 'This read was not attempted; inspect completed coverage before continuing.'),
+    'transport_failure': ('retry_later', 'Wait before a bounded read retry. Keep credentials and all verified observations.'),
+    'provider_unavailable': ('retry_later', 'Wait before a bounded read retry; the provider is unavailable.'),
+    'rate_limited': ('retry_later', 'Wait for the provider rate limit before a bounded read retry.'),
+    'authorization_unavailable': ('user_action', 'Review the account authorization; this failure alone does not prove token expiry.'),
+    'permissions_required': ('user_action', 'Review granted permissions and account eligibility with the owner.'),
+    'comments_disabled': ('inspect', 'Comments are disabled on this video. Reconnecting does not enable them; do not change video settings without owner approval.'),
+    'target_unavailable': ('correct_input', 'Verify the requested target and account before another read.'),
+    'request_rejected': ('correct_input', 'Review supported arguments and target before another request.'),
+    'operation_rejected': ('inspect', 'Inspect the target, stored state and approval before another operation.'),
+    'operation_uncertain': ('reconcile', 'Reconcile the existing operation. Do not replay its write.'),
+    'operation_already_verified': ('inspect', 'An identical operation was already verified. No new write was started. Inspect the existing receipt; do not duplicate it.'),
+    'operation_accepted_unverified': ('inspect', 'The provider accepted the operation. Independent verification is unavailable; this is not a rejection. Preserve the receipt and do not replay the write.'),
+    'provider_response_invalid': ('inspect', 'Preserve verified observations and inspect the incomplete provider response.'),
+    'storage_failure': ('repair_storage', 'Inspect local storage and preserve saved observations before recovery.'),
+    'local_data_busy': ('retry_later', 'Another SocialCli operation is using local data. Wait for it to finish, then retry. Do not delete or repair the files.'),
+    'persistence_failed': ('repair_storage', 'Preserve verified observations and repair local persistence before collecting again.'),
+    'unsupported_operation': ('unsupported', 'This integration does not support the requested operation.'),
+    'account_not_configured': ('user_action', 'Ask the owner to select and authorize the intended account; never infer one.'),
+    'invalid_input': ('correct_input', 'Review the supported arguments and explicit workspace.'),
+    'installation_access_required': ('sign_in', 'Ask the owner to sign in to SocialCli again.'),
+    'invalid_report_options': ('correct_input', 'Review the report date, window, item limit and platform.'),
+    'report_workspace_unavailable': ('inspect_workspace', 'Inspect the explicitly selected report workspace.'),
+    'snapshot_identity_mismatch': ('inspect_snapshot', 'Preserve the snapshot and inspect its brand/date binding.'),
+    'snapshot_unreadable': ('inspect_snapshot', 'Preserve the unreadable snapshot before recovery.'),
+    'snapshots_unavailable': ('collect_metrics', 'Collect authorized metrics before requesting a saved-snapshot report.'),
+    'platform_read_unavailable': ('collect_metrics', 'Collect authorized metrics for this platform; retain other verified observations.'),
+}
+
+
+def error_for_code(code: str, *, read_only: bool = True) -> dict:
+    if isinstance(code, str) and code in MESSAGES:
+        action, message = _ACTIONS.get(code, 'inspect'), MESSAGES[code]
+    else:
+        code = code if isinstance(code, str) and code in _CATALOG else 'operation_failed'
+        action, message = _CATALOG[code]
+    if not read_only and (action == 'retry_later' or code in {'read_deadline', 'response_too_large'}):
+        code = 'operation_uncertain'
+        action, message = 'reconcile', 'Verify the existing operation before another write; its outcome may be uncertain.'
+    return {'code':code, 'action':action,
+            'retryable':bool(read_only and action == 'retry_later'),
+            'requires_user_action':action in {'reconnect','sign_in','user_action','contact_support'},
+            'message':message}
+
+
+def error_document(exc: BaseException, *, read_only: bool) -> dict:
+    import httpx
+    from socialctl.read_budget import LocalConfigurationError
+    from socialctl.auth import AuthError
+    from socialctl.read_budget import ReadDeadlineExceeded, ReadResponseTooLarge
+    from socialctl.management.changes import ChangeError
+    from socialctl.management.youtube_resources import ResourceError, ResourceUncertain
+    from socialctl.management.youtube import YouTubeManagementError, YouTubeUpdateUncertain
+    from socialctl.management.meta_comments import CommentError, CommentUncertain
+    from socialctl.management.meta_schema import MetaError, MetaUncertain
+    from socialctl.metricas.base import SinPermiso
+    from socialctl.youtube_data import YouTubeDataBusy, YouTubeDataCleanupError
+
+    # A read flow may refresh a token via POST. A lost response to that operation
+    # cannot be classified as a harmless GET retry merely from the CLI command.
+    if isinstance(exc, TransportFailure) and exc.request_method not in {None,'GET','HEAD','OPTIONS'}:
+        read_only = False
+    if isinstance(exc, httpx.RequestError):
+        try: request = exc.request
+        except RuntimeError: request = None
+        if request is not None and request.method not in {'GET','HEAD','OPTIONS'}:
+            read_only = False
+    if isinstance(exc, ServiceRejected):
+        code = exc.code if exc.code in MESSAGES else {
+            401:'installation_access_required',402:'subscription_required',
+            429:'rate_limited',503:'provider_unavailable'}.get(exc.status,'service_rejected')
+    elif isinstance(exc, (ResourceUncertain, YouTubeUpdateUncertain, CommentUncertain, MetaUncertain)):
+        code = 'operation_uncertain'
+    elif isinstance(exc, (AuthError, YouTubeManagementError, ResourceError, CommentError, MetaError)) and getattr(exc, '_socialcli_error_code', None) is not None:
+        code = exc._socialcli_error_code
+    elif isinstance(exc, ReadDeadlineExceeded): code = 'read_deadline'
+    elif isinstance(exc, ReadResponseTooLarge): code = 'response_too_large'
+    elif isinstance(exc, KeyboardInterrupt): code = 'read_interrupted'
+    elif isinstance(exc, AuthError): code = 'authorization_unavailable'
+    elif isinstance(exc, SinPermiso): code = 'permissions_required'
+    elif isinstance(exc, (LocalConfigurationError,httpx.InvalidURL,httpx.LocalProtocolError,httpx.UnsupportedProtocol)):
+        code = 'local_configuration'
+    elif isinstance(exc, (TransportFailure,httpx.TransportError)): code = 'transport_failure'
+    elif isinstance(exc, ResourceError) and exc.http_status == 403 and exc.provider_reason in {'commentsDisabled', 'quotaExceeded'}:
+        code = 'comments_disabled' if exc.provider_reason == 'commentsDisabled' else 'rate_limited'
+    elif isinstance(exc, httpx.HTTPStatusError) or isinstance(exc, ResourceError) and exc.http_status:
+        status = exc.response.status_code if isinstance(exc,httpx.HTTPStatusError) else exc.http_status
+        if isinstance(exc,httpx.HTTPStatusError) and exc.request.method not in {'GET','HEAD','OPTIONS'}:
+            read_only = False
+        code = ({401:'authorization_unavailable',403:'permissions_required',404:'target_unavailable',
+                429:'rate_limited'}.get(status,'provider_unavailable' if status>=500 else 'request_rejected')
+                if type(status) is int else 'operation_rejected')
+    elif isinstance(exc, httpx.RequestError): code = 'provider_response_invalid'
+    elif isinstance(exc, ChangeError): code = 'operation_rejected'
+    elif isinstance(exc, YouTubeDataBusy): code = 'local_data_busy'
+    elif isinstance(exc, (OSError, YouTubeDataCleanupError)): code = 'storage_failure'
+    elif isinstance(exc, ValueError): code = 'invalid_local_state'
+    else: code = 'operation_failed'
+    return error_for_code(code,read_only=read_only)
+
+
+def with_error_code(wrapper: Exception, cause: BaseException, *, read_only: bool,
+                    fallback: str | None = None) -> Exception:
+    """Keep only a fixed code across a sanitized wrapper, never raw exception data."""
+    code = error_document(cause, read_only=read_only)['code']
+    if code == 'operation_failed' and fallback is not None:
+        code = error_for_code(fallback, read_only=read_only)['code']
+    wrapper._socialcli_error_code = code
+    return wrapper
+
+
+def with_http_error_code(wrapper: Exception, response, *, read_only: bool) -> Exception:
+    import httpx
+    cause = httpx.HTTPStatusError('Provider request rejected', request=response.request,
+                                  response=response)
+    return with_error_code(wrapper, cause, read_only=read_only)
+
+
+def emit_error(exc: Exception, *, read_only: bool) -> None:
+    import json
+    import typer
+    typer.echo(json.dumps({'version': 1, 'status': 'error',
+                           'error': error_document(exc, read_only=read_only)}))

socialctl/agent_guide.py

@@ -0,0 +1,23 @@
+"""Topic selection keeps advanced contracts available without bloating bootstrap."""
+from importlib.resources import files
+import re
+
+TOPICS={
+    'setup':('Install the reviewed candidate','Authorize the installation, then the social account','Persist and recover','Publication gate','Explicit approval and preflight'),
+    'publish':('Publication gate','Temporary Instagram media','Canonical publishing workflow','Check supplied media locally','Explicit approval and preflight'),
+    'schedule':('Publication gate','Temporary Instagram media','Scheduling and temporary media','Native scheduling input examples (offline)','Explicit approval and preflight'),
+    'inbox':('Publication gate','Read metrics and prepare engagement','Read diagnostics','Comment API corrections','Explicit approval and preflight','Resumable batches and reply context'),
+    'errors':('Persist and recover','Recovery and error actions','Read diagnostics','Comment API corrections','Explicit approval and preflight','Resumable batches and reply context'),
+    'permissions':('Installation connection access',),
+}
+
+
+def guide(topic):
+    if topic not in TOPICS and topic!='all':
+        raise ValueError('Choose a guide topic: '+', '.join(TOPICS)+', all.')
+    full=files('socialctl.ui').joinpath('assets/agent-manual.md').read_text(encoding='utf-8')
+    if topic=='all':return full
+    sections=re.split(r'(?=^## )',full,flags=re.MULTILINE)
+    chosen=[section for section in sections if any(section.startswith('## '+heading) for heading in TOPICS[topic])]
+    return ('# SocialCli agent guide: '+topic+'\n\n'+''.join(chosen)+
+            '\nNext: socialcli agent-guide publish; socialcli agent-guide schedule; socialcli agent-guide inbox; socialcli agent-guide errors.\n')

socialctl/approval_cli.py

@@ -0,0 +1,27 @@
+"""Explicit approval transport shared by terminal and noninteractive commands."""
+import sys
+
+import typer
+
+
+class ApprovalRequired(ValueError):
+    """The caller supplied no explicit noninteractive approval."""
+
+
+def read_approval(value=None, *, approval_stdin=False, prompt='Enter the exact fingerprint to approve'):
+    """Read one explicitly authorized source; an open pipe is never implicit consent."""
+    if value is not None and approval_stdin:
+        raise ValueError('Choose --approval-fingerprint OR --approval-stdin, not both.')
+    if value is not None:
+        return value
+    if approval_stdin:
+        typer.echo(f"{prompt} (--approval-stdin):")
+        value = sys.stdin.readline(4097)
+        if not value:
+            raise typer.Abort()
+        if len(value) > 4096 or not value.strip():
+            raise ValueError('Exact approval missing or invalid on stdin.')
+        return value.strip()
+    if not sys.stdin.isatty():
+        raise ApprovalRequired('Noninteractive approval required: show the complete preview, then pass --approval-fingerprint DIGEST or explicitly pipe one approval line with --approval-stdin. No input was read.')
+    return typer.prompt(prompt)