paperclipai/paperclip / .agents/skills/paperclip-page
paperclip-page
VerifiedPublish static HTML pages and asset folders to the Paperclip S3/CloudFront page host. Use when asked to deploy, host, or share a persistent page, viewer, prototype, report, or static site without here.now.
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 17.9 KB |
| SKILL.md | skill md | 4.1 KB |
| scripts/publish.shexecutable | script | 11.8 KB |
| scripts/publish.test.mjs | script | 11.1 KB |
scripts/publish.sh
View on GitHub#!/usr/bin/env bash
set -euo pipefail
usage() {
cat <<'EOF'
Usage:
publish.sh <dir> [--slug slug] [--update] [--dry-run]
Publishes a static directory with a root index.html to the configured Paperclip
pages bucket and prints the public URL and S3 prefix.
Required environment for live publish:
PAPERCLIP_PAGE_BUCKET, PAPERCLIP_PAGE_BASE_URL, AWS_REGION, AWS credentials
Optional environment:
PAPERCLIP_PAGE_DEFAULT_PREFIX, PAPERCLIP_PAGE_AWS_PROFILE
PAPERCLIP_PAGE_AWS_ACCESS_KEY_ID, PAPERCLIP_PAGE_AWS_SECRET_ACCESS_KEY,
PAPERCLIP_PAGE_AWS_SESSION_TOKEN
Credential resolution for aws calls made by this helper:
1. PAPERCLIP_PAGE_AWS_ACCESS_KEY_ID + PAPERCLIP_PAGE_AWS_SECRET_ACCESS_KEY
(used only by this helper; ambient AWS_PROFILE/AWS_* identity is untouched)
2. PAPERCLIP_PAGE_AWS_PROFILE (passed as --profile; ambient AWS_* identity
variables are stripped from the helper's aws calls)
3. Ambient AWS credential chain (env keys, profile, instance role)
Options:
--slug SLUG Lowercase URL slug. Allowed: a-z, 0-9, hyphen.
--update Additively overwrite an owned existing prefix. Never deletes.
--dry-run Validate and print the planned target without AWS writes.
--help, -h Show this help.
EOF
}
die() {
printf 'paperclip-page: %s\n' "$*" >&2
exit 1
}
require_command() {
if ! command -v "$1" >/dev/null 2>&1; then
die "missing required command: $1"
fi
}
normalize_base_url() {
local value="$1"
value="${value%/}"
[[ "$value" == https://* ]] || die "PAPERCLIP_PAGE_BASE_URL must be an https URL"
[[ ! "$value" =~ [[:space:]] ]] || die "PAPERCLIP_PAGE_BASE_URL cannot contain whitespace"
printf '%s\n' "$value"
}
validate_segment() {
local value="$1"
local label="$2"
[[ -n "$value" ]] || die "$label cannot be empty"
[[ "${#value}" -le 64 ]] || die "$label is too long; max length is 64 characters"
[[ "$value" =~ ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$ ]] || die "$label must use lowercase letters, digits, and hyphens only"
[[ "$value" != "." && "$value" != ".." ]] || die "$label cannot be a dot segment"
}
normalize_slug() {
local value="$1"
value="${value#/}"
value="${value%/}"
[[ "$value" != *"/"* ]] || die "slug must be one path segment, not a nested path"
validate_segment "$value" "slug"
case "$value" in
404|404-html|index|index-html|root|assets)
die "slug '$value' is reserved"
;;
esac
printf '%s\n' "$value"
}
derive_slug() {
local source_dir="$1"
local base
base="$(basename "$source_dir")"
base="$(printf '%s' "$base" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//; s/-{2,}/-/g')"
if [[ -z "$base" ]]; then
base="paperclip-page"
fi
printf '%.48s\n' "$base" | sed -E 's/-+$//'
}
random_suffix() {
if command -v openssl >/dev/null 2>&1; then
openssl rand -hex 3
else
od -An -N3 -tx1 /dev/urandom | tr -d ' \n'
fi
}
normalize_default_prefix() {
local raw="${1:-}"
local segment
local normalized=""
raw="${raw#/}"
raw="${raw%/}"
[[ "$raw" != *"//"* ]] || die "PAPERCLIP_PAGE_DEFAULT_PREFIX cannot contain empty path segments"
if [[ -z "$raw" ]]; then
printf '\n'
return
fi
IFS='/' read -r -a segments <<<"$raw"
for segment in "${segments[@]}"; do
validate_segment "$segment" "prefix segment"
if [[ -z "$normalized" ]]; then
normalized="$segment"
else
normalized="$normalized/$segment"
fi
done
printf '%s\n' "$normalized"
}
join_prefix() {
local default_prefix="$1"
local slug="$2"
if [[ -n "$default_prefix" ]]; then
printf '%s/%s/\n' "$default_prefix" "$slug"
else
printf '%s/\n' "$slug"
fi
}
aws_base_args=()
aws_env_unset=()
aws_env_overrides=()
aws_cli() {
local name pair
if [[ ${#aws_env_unset[@]} -gt 0 || ${#aws_env_overrides[@]} -gt 0 ]]; then
# Scope the page-uploader identity to this helper's aws calls only, and
# drop the ambient identity variables that would otherwise mix with or
# shadow the configured credential source. Apply the overrides with shell
# builtins in a subshell — passing them to an external `env` command would
# expose the credential values in its argv (world-readable via
# /proc/<pid>/cmdline) while it runs.
(
for name in "${aws_env_unset[@]}"; do unset "$name"; done
for pair in "${aws_env_overrides[@]}"; do export "$pair"; done
exec aws "${aws_base_args[@]}" "$@"
)
else
aws "${aws_base_args[@]}" "$@"
fi
}
object_exists() {
local bucket="$1"
local prefix="$2"
local key
key="$(aws_cli s3api list-objects-v2 \
--bucket "$bucket" \
--prefix "$prefix" \
--max-keys 1 \
--query 'Contents[0].Key' \
--output text)"
[[ "$key" != "None" && -n "$key" ]]
}
assert_safe_source_tree() {
local source_dir="$1"
local found
[[ ! -L "$source_dir" ]] || die "source directory must not be a symlink"
[[ -f "$source_dir/index.html" ]] || die "source directory must contain root index.html"
found="$(find "$source_dir" -type l -print -quit)"
[[ -z "$found" ]] || die "found symlink in source tree: $found"
found="$(
cd "$source_dir"
find . -mindepth 1 \
\( -path './.paperclip-page' -o -path './.paperclip-page/*' \) -prune -o \
\( -name '.*' -o -path '*/.*' \) -print -quit
)"
[[ -z "$found" ]] || die "hidden files and dot paths are not allowed in published content: $found"
}
read_state_value() {
local state_file="$1"
local expression="$2"
jq -r "$expression // empty" "$state_file"
}
assert_update_ownership() {
local source_dir="$1"
local bucket="$2"
local prefix="$3"
local state_file="$source_dir/.paperclip-page/state.json"
local state_bucket
local state_prefix
[[ -f "$state_file" ]] || die "update of an existing prefix requires ownership state at $state_file"
state_bucket="$(read_state_value "$state_file" '.bucket')"
state_prefix="$(read_state_value "$state_file" '.prefix')"
[[ "$state_bucket" == "$bucket" ]] || die "state bucket does not match target bucket"
[[ "$state_prefix" == "$prefix" ]] || die "state prefix does not match target prefix"
}
compute_source_hash() {
local source_dir="$1"
if ! command -v sha256sum >/dev/null 2>&1; then
printf 'unavailable\n'
return
fi
(
cd "$source_dir"
find . -type f ! -path './.paperclip-page/*' -print0 |
LC_ALL=C sort -z |
while IFS= read -r -d '' path; do
sha256sum "$path"
done
) | sha256sum | awk '{print $1}'
}
write_state() {
local source_dir="$1"
local bucket="$2"
local prefix="$3"
local slug="$4"
local url="$5"
local base_url="$6"
local source_hash="$7"
local state_dir="$source_dir/.paperclip-page"
local state_file="$state_dir/state.json"
local temp_file
mkdir -p "$state_dir"
temp_file="$(mktemp "$state_dir/state.json.tmp.XXXXXX")"
jq -n \
--arg bucket "$bucket" \
--arg prefix "$prefix" \
--arg slug "$slug" \
--arg url "$url" \
--arg baseUrl "$base_url" \
--arg publishedAt "$(date -u +'%Y-%m-%dT%H:%M:%SZ')" \
--arg sourceHash "$source_hash" \
'{
bucket: $bucket,
prefix: $prefix,
slug: $slug,
url: $url,
baseUrl: $baseUrl,
publishedAt: $publishedAt,
sourceHash: $sourceHash,
version: 1
}' >"$temp_file"
mv "$temp_file" "$state_file"
}
source_arg=""
slug_arg=""
update=0
dry_run=0
while [[ $# -gt 0 ]]; do
case "$1" in
--slug)
slug_arg="${2:-}"
shift 2
;;
--update)
update=1
shift
;;
--dry-run)
dry_run=1
shift
;;
--help|-h)
usage
exit 0
;;
--*)
die "unknown argument: $1"
;;
*)
if [[ -n "$source_arg" ]]; then
die "unexpected positional argument: $1"
fi
source_arg="$1"
shift
;;
esac
done
[[ -n "$source_arg" ]] || {
usage >&2
exit 1
}
require_command jq
require_command find
require_command sed
[[ -d "$source_arg" ]] || die "source path is not a directory: $source_arg"
source_dir="$(cd "$source_arg" && pwd -P)"
assert_safe_source_tree "$source_dir"
bucket="${PAPERCLIP_PAGE_BUCKET:-}"
base_url="${PAPERCLIP_PAGE_BASE_URL:-}"
region="${AWS_REGION:-}"
default_prefix="$(normalize_default_prefix "${PAPERCLIP_PAGE_DEFAULT_PREFIX:-}")"
[[ -n "$bucket" ]] || die "PAPERCLIP_PAGE_BUCKET is required"
[[ "$bucket" =~ ^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$ ]] || die "PAPERCLIP_PAGE_BUCKET does not look like a valid S3 bucket name"
[[ -n "$base_url" ]] || die "PAPERCLIP_PAGE_BASE_URL is required"
base_url="$(normalize_base_url "$base_url")"
page_access_key_id="${PAPERCLIP_PAGE_AWS_ACCESS_KEY_ID:-}"
page_secret_access_key="${PAPERCLIP_PAGE_AWS_SECRET_ACCESS_KEY:-}"
if [[ -n "$page_access_key_id" || -n "$page_secret_access_key" ]]; then
[[ -n "$page_access_key_id" && -n "$page_secret_access_key" ]] ||
die "PAPERCLIP_PAGE_AWS_ACCESS_KEY_ID and PAPERCLIP_PAGE_AWS_SECRET_ACCESS_KEY must be set together"
[[ -z "${PAPERCLIP_PAGE_AWS_PROFILE:-}" ]] ||
die "set PAPERCLIP_PAGE_AWS_PROFILE or the PAPERCLIP_PAGE_AWS_* key pair, not both"
fi
if [[ -n "${PAPERCLIP_PAGE_AWS_SESSION_TOKEN:-}" && -z "$page_access_key_id" ]]; then
die "PAPERCLIP_PAGE_AWS_SESSION_TOKEN requires the PAPERCLIP_PAGE_AWS_* key pair"
fi
explicit_slug=0
if [[ -n "$slug_arg" ]]; then
explicit_slug=1
slug="$(normalize_slug "$slug_arg")"
else
slug="$(normalize_slug "$(derive_slug "$source_dir")")"
fi
if [[ "$dry_run" == "0" ]]; then
require_command aws
require_command curl
[[ -n "$region" ]] || die "AWS_REGION is required for live publish"
aws_base_args=(--region "$region")
if [[ -n "$page_access_key_id" ]]; then
aws_env_unset=(AWS_PROFILE AWS_SESSION_TOKEN)
aws_env_overrides=(
AWS_ACCESS_KEY_ID="$page_access_key_id"
AWS_SECRET_ACCESS_KEY="$page_secret_access_key"
)
if [[ -n "${PAPERCLIP_PAGE_AWS_SESSION_TOKEN:-}" ]]; then
aws_env_overrides+=(AWS_SESSION_TOKEN="$PAPERCLIP_PAGE_AWS_SESSION_TOKEN")
fi
elif [[ -n "${PAPERCLIP_PAGE_AWS_PROFILE:-}" ]]; then
aws_base_args+=(--profile "$PAPERCLIP_PAGE_AWS_PROFILE")
aws_env_unset=(AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_PROFILE)
fi
fi
prefix="$(join_prefix "$default_prefix" "$slug")"
target_exists=0
if [[ "$update" == "1" ]]; then
assert_update_ownership "$source_dir" "$bucket" "$prefix"
fi
if [[ "$dry_run" == "0" ]]; then
if object_exists "$bucket" "$prefix"; then
target_exists=1
fi
if [[ "$target_exists" == "1" && "$update" == "0" ]]; then
if [[ "$explicit_slug" == "1" ]]; then
die "slug already exists: $slug. Use --update from the owning source directory or choose a new slug."
fi
for _ in 1 2 3 4 5; do
candidate="${slug}-$(random_suffix)"
candidate="$(printf '%.64s' "$candidate" | sed -E 's/-+$//')"
validate_segment "$candidate" "generated slug"
candidate_prefix="$(join_prefix "$default_prefix" "$candidate")"
if ! object_exists "$bucket" "$candidate_prefix"; then
slug="$candidate"
prefix="$candidate_prefix"
target_exists=0
break
fi
done
[[ "$target_exists" == "0" ]] || die "could not find an unused generated slug after 5 attempts"
fi
fi
url="${base_url}/${prefix}"
mode="publish"
if [[ "$update" == "1" ]]; then
mode="update"
fi
if [[ "$dry_run" == "1" ]]; then
cat <<EOF
paperclip-page dry run
mode: $mode
source: $source_dir
bucket: $bucket
prefix: $prefix
url: $url
EOF
exit 0
fi
aws_cli s3 sync "$source_dir/" "s3://$bucket/$prefix" \
--no-follow-symlinks \
--exclude '.paperclip-page/*' \
--cache-control 'public,max-age=60' \
--only-show-errors
source_hash="$(compute_source_hash "$source_dir")"
write_state "$source_dir" "$bucket" "$prefix" "$slug" "$url" "$base_url" "$source_hash"
curl -fsSIL --max-time 20 "$url" >/dev/null
cat <<EOF
paperclip-page published
mode: $mode
url: $url
bucket: $bucket
prefix: $prefix
state: $source_dir/.paperclip-page/state.json
EOF
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |