Skip to content

paperclipai/paperclip / skills/paperclip

paperclip

Verified

Use for Paperclip-managed tasks and heartbeats: reading task context, delivering task documents or files, updating completion or blockers, coordinating or delegating work, and following company governance. Includes control plane API operations for assignments, comments, approvals, and routines.

scripts/paperclip-upload-artifact.sh

View on GitHub
#!/usr/bin/env bash

set -euo pipefail

usage() {
  cat <<'EOF'
Usage:
  paperclip-upload-artifact.sh FILE [options]

Uploads a generated file from the current workspace to the current Paperclip
issue, then creates an attachment-backed artifact work product by default.

Required environment for live uploads:
  PAPERCLIP_API_URL, PAPERCLIP_API_KEY, PAPERCLIP_COMPANY_ID, PAPERCLIP_TASK_ID, PAPERCLIP_RUN_ID

Options:
  --issue-id ID          Issue id to attach to (default: PAPERCLIP_TASK_ID)
  --company-id ID        Company id (default: PAPERCLIP_COMPANY_ID)
  --title TEXT           Work product title (default: file basename)
  --summary TEXT         Work product summary
  --content-type TYPE    Override detected upload content type
  --status STATUS        Work product status (default: ready_for_review)
  --chat-comment TEXT    Bind this file to an explicit external-chat response
  --retry-unknown-upload Retry after an unresolved transport failure (duplicate risk)
  --no-work-product      Only upload the issue attachment
  --no-primary           Do not mark the artifact work product primary for its type
  --output FORMAT        markdown or json (default: markdown)
  --dry-run              Print resolved upload settings without calling the API
  --help, -h             Show this help

Examples:
  bash scripts/paperclip-upload-artifact.sh dist/demo.mp4 \
    --title "Demo video render" \
    --summary "MP4 render for board review"

  bash scripts/paperclip-upload-artifact.sh out/walkthrough.webm \
    --title "Walkthrough video" \
    --content-type video/webm

  bash scripts/paperclip-upload-artifact.sh out/result.png \
    --title "Generated image" \
    --chat-comment "Here is the requested image."
EOF
}

require_command() {
  if ! command -v "$1" >/dev/null 2>&1; then
    printf 'Missing required command: %s\n' "$1" >&2
    exit 1
  fi
}

json_bool() {
  if [[ "${1:-0}" == "1" ]]; then
    printf 'true'
  else
    printf 'false'
  fi
}

detect_content_type() {
  local path="$1"
  local lower
  lower="$(printf '%s' "$path" | tr '[:upper:]' '[:lower:]')"

  case "$lower" in
    *.mp4|*.m4v) printf 'video/mp4' ;;
    *.webm) printf 'video/webm' ;;
    *.mov|*.qt) printf 'video/quicktime' ;;
    *.png) printf 'image/png' ;;
    *.jpg|*.jpeg) printf 'image/jpeg' ;;
    *.gif) printf 'image/gif' ;;
    *.webp) printf 'image/webp' ;;
    *.svg) printf 'image/svg+xml' ;;
    *.pdf) printf 'application/pdf' ;;
    *.txt|*.log) printf 'text/plain' ;;
    *.md|*.markdown) printf 'text/markdown' ;;
    *.json) printf 'application/json' ;;
    *.csv) printf 'text/csv' ;;
    *.html|*.htm) printf 'text/html' ;;
    *.zip) printf 'application/zip' ;;
    *)
      if command -v file >/dev/null 2>&1; then
        file --brief --mime-type "$path"
      else
        printf 'application/octet-stream'
      fi
      ;;
  esac
}

sha256_file() {
  local path="$1"
  if command -v sha256sum >/dev/null 2>&1; then
    sha256sum -- "$path" | awk '{print tolower($1)}'
  elif command -v shasum >/dev/null 2>&1; then
    shasum -a 256 -- "$path" | awk '{print tolower($1)}'
  else
    printf 'Missing required command: sha256sum or shasum\n' >&2
    exit 1
  fi
}

sha256_text() {
  local value="$1"
  if command -v sha256sum >/dev/null 2>&1; then
    printf '%s' "$value" | sha256sum | awk '{print tolower($1)}'
  elif command -v shasum >/dev/null 2>&1; then
    printf '%s' "$value" | shasum -a 256 | awk '{print tolower($1)}'
  else
    printf 'Missing required command: sha256sum or shasum\n' >&2
    exit 1
  fi
}

helper_state_directory() {
  printf '%s' "${PAPERCLIP_HELPER_STATE_DIR:-${PAPERCLIP_WORKSPACE_CWD:-$PWD}/.paperclip/artifact-helper}"
}

helper_response_file() {
  local directory
  directory="$(helper_state_directory)"
  # TMPDIR can name a controller-owned directory outside a CLI sandbox.
  (umask 077; mkdir -p "$directory" && mktemp "$directory/response.XXXXXX")
}

request_json() {
  local method="$1"
  local url="$2"
  local body="${3:-}"
  local response_file
  local status_code

  response_file="$(helper_response_file)"
  if [[ -n "$body" ]]; then
    status_code="$(
      curl -sS -X "$method" -w '%{http_code}' -o "$response_file" \
        "$url" \
        -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
        -H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID" \
        -H 'Content-Type: application/json' \
        --data-binary "$body"
    )"
  else
    status_code="$(
      curl -sS -X "$method" -w '%{http_code}' -o "$response_file" \
        "$url" \
        -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
        -H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID"
    )"
  fi

  if [[ "$status_code" -lt 200 || "$status_code" -ge 300 ]]; then
    printf 'Request failed (%s): %s\n' "$status_code" "$url" >&2
    cat "$response_file" >&2
    printf '\n' >&2
    rm -f "$response_file"
    exit 1
  fi

  cat "$response_file"
  rm -f "$response_file"
}

upload_file() {
  local url="$1"
  local path="$2"
  local content_type="$3"
  local escaped_path
  local response_file
  local status_code
  local curl_status=0
  local indeterminate=0

  escaped_path="${path//\\/\\\\}"
  escaped_path="${escaped_path//\"/\\\"}"
  response_file="$(helper_response_file)"
  status_code="$(
    curl -sS -X POST -w '%{http_code}' -o "$response_file" \
      "$url" \
      -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
      -H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID" \
      -F "file=@\"${escaped_path}\";type=${content_type}"
  )" || curl_status=$?

  if [[ "$curl_status" -ne 0 ]]; then
    rm -f "$response_file"
    return 75
  fi

  if [[ "$status_code" -lt 200 || "$status_code" -ge 300 ]]; then
    printf 'Upload failed (%s): %s\n' "$status_code" "$url" >&2
    cat "$response_file" >&2
    printf '\n' >&2
    # The bridge uses a structured 409 outcome after a possibly committed
    # mutation. Keep the marker so the next invocation reconciles by listing.
    if [[ "$status_code" == "409" ]] && jq -e '.outcome == "indeterminate"' "$response_file" >/dev/null 2>&1; then
      indeterminate=1
    fi
    rm -f "$response_file"
    if [[ "$status_code" == "408" || "$status_code" -ge 500 || "$indeterminate" == "1" ]]; then
      return 75
    fi
    return 1
  fi

  cat "$response_file"
  rm -f "$response_file"
}

operation_lock_path=""
operation_lock_owner=""
operation_lock_held=0
operation_state_root=""

process_start_identity() {
  local pid="$1"
  ps -p "$pid" -o lstart= 2>/dev/null | tr -s '[:space:]' ' ' | sed 's/^ //;s/ $//'
}

release_operation_lock() {
  if [[ "$operation_lock_held" == "1" && -n "$operation_lock_path" ]]; then
    local current_owner=""
    current_owner="$(readlink "$operation_lock_path" 2>/dev/null || true)"
    if [[ "$current_owner" == "$operation_lock_owner" ]]; then
      rm -f "$operation_lock_path"
    fi
    operation_lock_held=0
  fi
}

acquire_operation_lock() {
  local operation_key="$1"
  local attempts=0

  umask 077
  operation_state_root="$(helper_state_directory)"
  mkdir -p "$operation_state_root"
  operation_lock_path="$operation_state_root/$operation_key.lock"
  operation_lock_owner="$$|$(process_start_identity "$$" || true)"
  while ! ln -s "$operation_lock_owner" "$operation_lock_path" 2>/dev/null; do
    local owner_pid=""
    local owner_start=""
    local current_lock_owner=""
    current_lock_owner="$(readlink "$operation_lock_path" 2>/dev/null || true)"
    IFS='|' read -r owner_pid owner_start <<<"$current_lock_owner"
    if [[ "$owner_pid" =~ ^[0-9]+$ ]]; then
      local current_owner_start=""
      current_owner_start="$(process_start_identity "$owner_pid" || true)"
      if ! kill -0 "$owner_pid" 2>/dev/null ||
        [[ -n "$owner_start" && -n "$current_owner_start" && "$owner_start" != "$current_owner_start" ]]; then
        # Serialize stale-lock reclamation separately. Without this guard, two
        # contenders can both observe the old owner and the slower one can
        # delete the faster contender's newly acquired live lock.
        local reclaim_lock_path="$operation_lock_path.reclaim"
        if mkdir "$reclaim_lock_path" 2>/dev/null; then
          local guarded_owner=""
          guarded_owner="$(readlink "$operation_lock_path" 2>/dev/null || true)"
          if [[ "$guarded_owner" == "$current_lock_owner" ]]; then
            rm -f "$operation_lock_path"
          fi
          rmdir "$reclaim_lock_path" 2>/dev/null || true
          continue
        fi
      fi
    fi
    attempts=$((attempts + 1))
    if [[ "$attempts" -ge 400 ]]; then
      printf 'Another matching artifact upload is still in progress; retry after it finishes.\n' >&2
      exit 1
    fi
    sleep 0.05
  done
  operation_lock_held=1
}

file_path=""
issue_id="${PAPERCLIP_TASK_ID:-}"
company_id="${PAPERCLIP_COMPANY_ID:-}"
title=""
summary=""
content_type=""
status="ready_for_review"
chat_comment=""
create_work_product=1
is_primary=1
output_format="markdown"
dry_run=0
retry_unknown_upload=0

while [[ $# -gt 0 ]]; do
  case "$1" in
    --issue-id)
      issue_id="${2:-}"
      shift 2
      ;;
    --company-id)
      company_id="${2:-}"
      shift 2
      ;;
    --title)
      title="${2:-}"
      shift 2
      ;;
    --summary)
      summary="${2:-}"
      shift 2
      ;;
    --content-type)
      content_type="${2:-}"
      shift 2
      ;;
    --status)
      status="${2:-}"
      shift 2
      ;;
    --chat-comment)
      chat_comment="${2:-}"
      shift 2
      ;;
    --no-work-product)
      create_work_product=0
      shift
      ;;
    --retry-unknown-upload)
      retry_unknown_upload=1
      shift
      ;;
    --no-primary)
      is_primary=0
      shift
      ;;
    --output)
      output_format="${2:-}"
      shift 2
      ;;
    --dry-run)
      dry_run=1
      shift
      ;;
    --help|-h)
      usage
      exit 0
      ;;
    --*)
      printf 'Unknown argument: %s\n' "$1" >&2
      usage >&2
      exit 1
      ;;
    *)
      if [[ -n "$file_path" ]]; then
        printf 'Unexpected positional argument: %s\n' "$1" >&2
        usage >&2
        exit 1
      fi
      file_path="$1"
      shift
      ;;
  esac
done

if [[ -z "$file_path" ]]; then
  printf 'Missing file path.\n' >&2
  usage >&2
  exit 1
fi

if [[ ! -f "$file_path" ]]; then
  printf 'Artifact file does not exist: %s\n' "$file_path" >&2
  exit 1
fi

if [[ "$output_format" != "markdown" && "$output_format" != "json" ]]; then
  printf 'Unsupported output format: %s\n' "$output_format" >&2
  exit 1
fi

if [[ -n "$chat_comment" && "$create_work_product" != "1" ]]; then
  printf '%s\n' '--chat-comment requires the attachment-backed work product created by this helper.' >&2
  exit 1
fi

require_command curl
require_command jq

if [[ -z "$title" ]]; then
  title="$(basename "$file_path")"
fi

if [[ -z "$content_type" ]]; then
  content_type="$(detect_content_type "$file_path")"
fi

if [[ "$dry_run" == "1" ]]; then
  create_work_product_json="$(json_bool "$create_work_product")"
  is_primary_json="$(json_bool "$is_primary")"
  jq -n \
    --arg file "$file_path" \
    --arg issueId "$issue_id" \
    --arg companyId "$company_id" \
    --arg title "$title" \
    --arg summary "$summary" \
    --arg contentType "$content_type" \
    --arg status "$status" \
    --arg chatComment "$chat_comment" \
    --argjson createWorkProduct "$create_work_product_json" \
    --argjson isPrimary "$is_primary_json" \
    '{file: $file, issueId: $issueId, companyId: $companyId, title: $title, summary: $summary, contentType: $contentType, status: $status, chatComment: (if $chatComment == "" then null else $chatComment end), createWorkProduct: $createWorkProduct, isPrimary: $isPrimary}'
  exit 0
fi

if [[ -z "${PAPERCLIP_API_URL:-}" || -z "${PAPERCLIP_API_KEY:-}" || -z "${PAPERCLIP_RUN_ID:-}" ]]; then
  printf 'Missing PAPERCLIP_API_URL, PAPERCLIP_API_KEY, or PAPERCLIP_RUN_ID.\n' >&2
  exit 1
fi

if [[ -z "$issue_id" || -z "$company_id" ]]; then
  printf 'Missing issue or company id. Pass --issue-id/--company-id or set PAPERCLIP_TASK_ID/PAPERCLIP_COMPANY_ID.\n' >&2
  exit 1
fi

api_root="${PAPERCLIP_API_URL%/}"
case "$api_root" in
  */api) api_base="$api_root" ;;
  *) api_base="$api_root/api" ;;
esac
file_sha256="$(sha256_file "$file_path")"
original_filename="$(basename "$file_path")"
operation_key="$(
  sha256_text "$api_base|$company_id|$issue_id|$PAPERCLIP_RUN_ID|$original_filename|$file_sha256|$content_type"
)"
acquire_operation_lock "$operation_key"
trap release_operation_lock EXIT

attachment=""
reused_attachment=0
unknown_upload_marker="$operation_state_root/$operation_key.uncertain"
lookup_attempts=1
if [[ -f "$unknown_upload_marker" && "$retry_unknown_upload" != "1" ]]; then
  lookup_attempts=20
fi
for ((lookup_attempt = 1; lookup_attempt <= lookup_attempts; lookup_attempt++)); do
  existing_attachments="$(request_json GET "$api_base/issues/$issue_id/attachments")"
  attachment="$(
    jq -nc \
      --argjson attachments "$existing_attachments" \
      --arg runId "$PAPERCLIP_RUN_ID" \
      --arg sha256 "$file_sha256" \
      --arg originalFilename "$original_filename" \
      --arg contentType "$content_type" \
      'first(
        $attachments[]
        | select(
            .originatingRunId == $runId
            and ((.sha256 // "") | ascii_downcase) == ($sha256 | ascii_downcase)
            and (.originalFilename // "") == $originalFilename
            and ((.contentType // "") | ascii_downcase) == ($contentType | ascii_downcase)
          )
      ) // empty'
  )"
  if [[ -n "$attachment" ]]; then
    reused_attachment=1
    rm -f "$unknown_upload_marker"
    break
  fi
  if [[ "$lookup_attempt" -lt "$lookup_attempts" ]]; then
    sleep 0.25
  fi
done

if [[ -z "$attachment" && -f "$unknown_upload_marker" && "$retry_unknown_upload" != "1" ]]; then
  printf '%s\n' 'A previous matching upload ended without a definitive response, and Paperclip has not exposed its durable attachment yet.' >&2
  printf '%s\n' 'Retry this command later. If the upload definitely did not commit, pass --retry-unknown-upload to accept the duplicate-file risk.' >&2
  exit 1
fi

if [[ -z "$attachment" ]]; then
  rm -f "$unknown_upload_marker"
  : >"$unknown_upload_marker"
  upload_status=0
  attachment="$(
    upload_file \
      "$api_base/companies/$company_id/issues/$issue_id/attachments" \
      "$file_path" \
      "$content_type"
  )" || upload_status=$?
  if [[ "$upload_status" -ne 0 ]]; then
    if [[ "$upload_status" -ne 75 ]]; then
      rm -f "$unknown_upload_marker"
    fi
    exit 1
  fi
fi

attachment_id="$(jq -r '.id // empty' <<<"$attachment")"
content_path="$(jq -r '.contentPath // empty' <<<"$attachment")"
download_path="$(jq -r '.downloadPath // (if .contentPath then (.contentPath + "?download=1") else "" end)' <<<"$attachment")"
if [[ -z "$attachment_id" || -z "$content_path" || -z "$download_path" ]]; then
  printf 'Upload response did not include attachment path metadata.\n' >&2
  printf '%s\n' "$attachment" >&2
  exit 1
fi
rm -f "$unknown_upload_marker"

work_product="null"
if [[ "$create_work_product" == "1" ]]; then
  is_primary_json="$(json_bool "$is_primary")"
  byte_size="$(jq -r '.byteSize // 0' <<<"$attachment")"
  open_path="$(jq -r '.openPath // .contentPath // empty' <<<"$attachment")"
  original_filename="$(jq -r '.originalFilename // empty' <<<"$attachment")"

  work_product_payload="$(
    jq -nc \
      --arg title "$title" \
      --arg summary "$summary" \
      --arg status "$status" \
      --arg runId "$PAPERCLIP_RUN_ID" \
      --arg attachmentId "$attachment_id" \
      --arg contentType "$content_type" \
      --argjson byteSize "$byte_size" \
      --arg contentPath "$content_path" \
      --arg openPath "$open_path" \
      --arg downloadPath "$download_path" \
      --arg originalFilename "$original_filename" \
      --argjson isPrimary "$is_primary_json" \
      '{
        type: "artifact",
        provider: "paperclip",
        title: $title,
        status: $status,
        reviewState: "none",
        isPrimary: $isPrimary,
        healthStatus: "unknown",
        summary: (if $summary == "" then null else $summary end),
        createdByRunId: $runId,
        metadata: {
          attachmentId: $attachmentId,
          contentType: $contentType,
          byteSize: $byteSize,
          contentPath: $contentPath,
          openPath: $openPath,
          downloadPath: $downloadPath,
          originalFilename: (if $originalFilename == "" then null else $originalFilename end)
        }
      }'
  )"

  work_product="$(
    request_json \
      POST \
      "$api_base/issues/$issue_id/work-products" \
      "$work_product_payload"
  )"
fi

chat_response="null"
if [[ -n "$chat_comment" ]]; then
  chat_comment_payload="$(
    jq -nc \
      --arg body "$chat_comment" \
      --arg attachmentId "$attachment_id" \
      '{body: $body, attachmentIds: [$attachmentId]}'
  )"
  chat_response="$(
    request_json \
      POST \
      "$api_base/issues/$issue_id/comments" \
      "$chat_comment_payload"
  )"
  chat_comment_id="$(jq -r '.id // empty' <<<"$chat_response")"
  if [[ -z "$chat_comment_id" ]]; then
    printf 'Chat attachment response did not include a comment id.\n' >&2
    exit 1
  fi
fi

if [[ "$output_format" == "json" ]]; then
  jq -n \
    --argjson attachment "$attachment" \
    --argjson workProduct "$work_product" \
    --argjson chatComment "$chat_response" \
    '{attachment: $attachment, workProduct: $workProduct, chatComment: $chatComment}'
  exit 0
fi

work_product_id="$(jq -r '.id // empty' <<<"$work_product")"

if [[ "$reused_attachment" == "1" ]]; then
  printf 'Reused matching artifact from this run\n\n'
else
  printf 'Uploaded artifact\n\n'
fi
printf -- '- Attachment: [%s](%s)\n' "$title" "$content_path"
printf -- '- Download: [%s](%s)\n' "$title" "$download_path"
printf -- '- Attachment ID: `%s`\n' "$attachment_id"
if [[ -n "$work_product_id" ]]; then
  printf -- '- Work product ID: `%s`\n' "$work_product_id"
fi
if [[ -n "$chat_comment" ]]; then
  printf -- '- Paperclip comment binding: saved. External publication requires an authorized active chat origin; this helper does not confirm provider delivery.\n'
fi
printf '\nFinal comment snippet:\n\n'
printf -- '- Artifact: [%s](%s)\n' "$title" "$content_path"
add-product-e2e-evalpaperclipai/paperclipAdd or extend a Paperclip full-stack runner E2E workflow, fixture, matcher, or report evidence path for local or Daytona execution.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
add-runner-evalpaperclipai/paperclipAdd or extend a Paperclip Runner protocol evaluation definition, roster, assertion, or report fixture with provenance and narrow validation.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
diagnose-why-work-stoppedpaperclipai/paperclipCompatibility entry point for failed, stalled, looping, or over-recovered Paperclip work. Use fix-failed-paperclip-run for the full diagnosis, regression, repair, real verification, and green-PR workflow; honor an explicitly requested diagnosis-only scope.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
fix-failed-paperclip-runpaperclipai/paperclipDiagnose and fix failed, stuck, slow, or incorrectly blocked Paperclip tasks and runs. Use with a task/run URL or failure report to trace the root cause, prove a regression red then green, check second-order effects, verify the real workflow, and deliver a PR with passing checks.Stars: 115kUpdated Claude CodeCodexVerifiedInstall