replicas-cli 0.2.224 → 0.2.226

package/dist/index.mjs

@@ -8364,7 +8364,7 @@ var LINEAR_ABILITY = {
 
 // ../shared/src/default-skills/replicas-agent/abilities/media.ts
 var SECTION6 = `### Media
-Share screenshots, screen recordings, generated diagrams, and audio clips inline in the Replicas chat (and as references in external messages).
+Share screenshots, screen recordings, generated diagrams, and audio clips inline in the Replicas chat and natively embedded in external messages.
 
 **Reference:** \`references/MEDIA.md\`
 
@@ -8374,7 +8374,7 @@ Use this when:
 - You need to embed media in a Slack/Linear/GitHub message AND keep a referenceable copy in the Replicas dashboard`;
 var REFERENCE6 = `# Media (Screenshots, Recordings, Audio)
 
-This guide covers how to share screenshots, screen recordings, generated diagrams, and audio clips with the user inline in the Replicas chat.
+This guide covers how to share screenshots, screen recordings, generated diagrams, and audio clips \u2014 both inline in the Replicas chat and natively embedded in external surfaces (Slack, Linear, GitHub).
 
 ## Prerequisites
 
@@ -8390,7 +8390,7 @@ Upload to Replicas in these cases \u2014 and **only** these cases:
 
 If none of these apply, don't upload.
 
-## Uploading
+## Uploading to Replicas
 
 \`\`\`bash
 replicas media upload <path-to-file> [<path-to-file> ...]
@@ -8400,47 +8400,185 @@ Pass one or more file paths. Uploading several files in a single invocation is p
 
 For each file, the CLI prints two lines:
 
-1. \`![filename](<api-url>)\` \u2014 the chat embed (renders inline in Replicas chat only; see below).
+1. \`![filename](<api-url>)\` \u2014 the chat embed (renders inline in Replicas chat **only** \u2014 see below).
 2. \`View in Replicas: <deep-link>\` \u2014 a per-file dashboard URL of the form \`https://tryreplicas.com/workspaces/<workspace-id>?mode=media&media=<media-id>\` that opens directly to that specific file.
 
 Match each "View in Replicas" line to the embed line directly above it \u2014 that's the deep link for that file.
 
-## How to use the output
+## The two URLs the CLI gives you \u2014 and where each one is allowed
 
-### CRITICAL: the markdown embed URL is for Replicas chat only
+| URL | What it is | Where it's allowed |
+|---|---|---|
+| \`https://api.tryreplicas.com/v1/media/<id>\` (inside \`![\u2026](\u2026)\`) | Authenticated API redirect to a presigned blob \u2014 requires the Replicas chat session | **Only** in the Replicas chat reply. Nowhere else. |
+| \`https://tryreplicas.com/workspaces/<workspace-id>?mode=media&media=<media-id>\` | Public dashboard deep link to the media tab, scrolled to that specific file | Everywhere external \u2014 Slack, GitHub, Linear, PR bodies, comments, emails. |
 
-The URL inside \`![filename](...)\` points at \`api.tryreplicas.com/v1/media/<id>\`. This is **not a public URL** \u2014 it requires the Replicas chat's authenticated session, which resolves it to a presigned download. Anywhere else (Slack, Linear, GitHub, a browser tab the user opens directly, a customer copy-pasting from chat), it returns \`{"error":"Missing authorization token"}\` and renders as a broken image.
+### NEVER link the API redirect URL outside the Replicas chat reply
 
-**Never paste this URL outside your Replicas chat reply.** Not in Slack messages, not in Linear comments, not in PR descriptions or commit messages, not in external docs \u2014 nowhere a non-Replicas surface will render it.
+The \`api.tryreplicas.com/v1/media/<id>\` URL is **not public**. It's an authenticated redirect that only resolves to a presigned download when the Replicas chat session token is present. Anywhere else (Slack, Linear, GitHub, a browser tab the user opens directly, a customer copy-pasting from chat) it returns \`{"error":"Missing authorization token"}\` and renders as a broken image.
 
-### Always render dashboard URLs as \`[View in Replicas](<url>)\` hyperlinks
+This rule has no exceptions:
+- \u274C Never paste it in a Slack message \u2014 upload the actual bytes via the 3-step \`files.getUploadURLExternal\` \u2192 POST bytes \u2192 \`files.completeUploadExternal\` flow instead (see below).
+- \u274C Never paste it in a GitHub PR description, issue body, review comment, or commit message.
+- \u274C Never paste it in a Linear issue body or comment \u2014 upload via Linear's \`fileUpload\` mutation instead (see below).
+- \u274C Never link to it from any external doc, email, or external chat.
+- \u274C Never include it as a "backup link" in case the dashboard link breaks \u2014 it will always break externally.
 
-Whenever you share a workspace dashboard URL \u2014 in chat or anywhere else \u2014 format it as a markdown hyperlink labeled **View in Replicas**:
+### ALWAYS link the dashboard URL \u2014 never the API URL \u2014 when referencing media externally
+
+When you reference an uploaded file from anywhere outside the Replicas chat reply, the link must be the dashboard form:
 
-\`\`\`markdown
-[View in Replicas](https://tryreplicas.com/workspaces/<workspace-id>?mode=media&media=<media-id>)
+\`\`\`
+https://tryreplicas.com/workspaces/<workspace-id>?mode=media&media=<media-id>
 \`\`\`
 
-Never paste the raw URL. Raw URLs look unpolished.
+Both query params are required:
+- \`mode=media\` opens the media tab in the dashboard.
+- \`media=<media-id>\` scrolls to and opens that specific file.
 
-Two flavors of dashboard URL the CLI gives you:
+Never link \`tryreplicas.com/workspaces/<id>?mode=media\` without the \`media=<id>\` param when you have a specific file in mind \u2014 that lands on the gallery, not the file. Never link the bare workspace URL.
 
-- **Per-file deep link** (default \u2014 what \`replicas media upload\` prints): \`...?mode=media&media=<media-id>\` opens the dashboard scrolled to that specific file. Use this whenever you're linking to *one* file.
-- **Media tab link** (no \`media=\` param): \`...?mode=media\` opens the workspace's media tab listing all files. Use this only when you're pointing at the collection, not a specific file (rare \u2014 you almost always have a specific file in mind).
+Always render as a markdown / mrkdwn hyperlink labeled **View in Replicas** \u2014 never paste a raw URL.
 
-### In your Replicas chat reply
+## In your Replicas chat reply
 
 Include each markdown embed line **verbatim** where you want that file to render inline. The chat substitutes each one with an embedded image, video, or audio player. Multiple embeds can appear in a single reply.
 
-After (or alongside) the embeds, include a \`[View in Replicas](<deep-link>)\` hyperlink for each file using the per-file URL the CLI printed for that file. This lets the user jump to the specific item in the media tab.
+After (or alongside) the embeds, include a \`[View in Replicas](<deep-link>)\` hyperlink for each file using the per-file dashboard URL from the CLI. This lets the user jump to the specific item in the media tab.
+
+## On external platforms \u2014 upload natively AND link the dashboard
+
+Sharing media externally is a **two-step requirement** for every file:
+
+1. **Upload the raw bytes natively to that platform** so the recipient sees the media embedded inline in the message itself.
+2. **Link the Replicas dashboard deep link** (\`?mode=media&media=<id>\` form) so the user can jump straight to the workspace.
+
+A link alone is not enough. A native upload alone is not enough. Do both.
+
+The one exception is GitHub, which has no public image upload API \u2014 there, the dashboard link is the only option (see below).
+
+### Slack \u2014 embed natively via the 3-step external file upload flow
+
+A Slack message that just contains a \`tryreplicas.com\` link is not acceptable when the message is supposed to show an image. The recipient should see the image inline in the thread.
 
-### On external platforms (Slack, Linear, GitHub, etc.)
+Slack deprecated the single-shot \`files.upload\` endpoint. The raw HTTP replacement is a 3-step flow: reserve an upload URL with \`files.getUploadURLExternal\`, POST the bytes to it, then share into the channel/thread with \`files.completeUploadExternal\`. (\`files.uploadV2\` is **only** an SDK convenience wrapper \u2014 it is NOT a real Web API HTTP endpoint and \`POST https://slack.com/api/files.uploadV2\` will return \`unknown_method\`.)
 
-Always include a \`[View in Replicas](<deep-link>)\` hyperlink \u2014 use the per-file deep link the CLI printed for that file (\`...?mode=media&media=<media-id>\`), so the recipient lands directly on that specific item.
+\`\`\`bash
+FILE=/abs/path/to/screenshot.png
+FILENAME=$(basename "$FILE")
+LENGTH=$(stat -c%s "$FILE" 2>/dev/null || stat -f%z "$FILE")
+
+# 1. Reserve an upload URL + file ID.
+RESERVE=$(curl -s -G "https://slack.com/api/files.getUploadURLExternal" \\
+  -H "Authorization: Bearer $SLACK_BOT_TOKEN" \\
+  --data-urlencode "filename=$FILENAME" \\
+  --data-urlencode "length=$LENGTH")
+UPLOAD_URL=$(echo "$RESERVE" | jq -r '.upload_url')
+FILE_ID=$(echo "$RESERVE" | jq -r '.file_id')
+
+# 2. POST the raw bytes to the reserved URL.
+#    Do not use -F / multipart here \u2014 the presigned URL expects the bytes
+#    directly in the request body.
+curl -s -X POST "$UPLOAD_URL" \\
+  -H "Content-Type: application/octet-stream" \\
+  --data-binary @"$FILE"
+
+# 3. Complete the upload, sharing it into the channel/thread with the dashboard link.
+curl -s -X POST "https://slack.com/api/files.completeUploadExternal" \\
+  -H "Authorization: Bearer $SLACK_BOT_TOKEN" \\
+  -H "Content-Type: application/json; charset=utf-8" \\
+  -d "{
+    \\"files\\": [{\\"id\\": \\"$FILE_ID\\", \\"title\\": \\"Screenshot\\"}],
+    \\"channel_id\\": \\"CHANNEL_ID\\",
+    \\"thread_ts\\": \\"THREAD_TS\\",
+    \\"initial_comment\\": \\"<https://tryreplicas.com/workspaces/<workspace-id>?mode=media&media=<media-id>|View in Replicas>\\"
+  }"
+\`\`\`
 
-For platforms that support native uploads (Slack \`files.upload\`, Linear attachments, etc.), upload the raw bytes there too so the recipient sees the media inline in addition to the Replicas link. GitHub PRs/issues do not have a public upload API, so the \`View in Replicas\` link is the canonical way to share media there \u2014 do not commit screenshots to the repo and do not use placeholder URLs.
+Notes:
+- All three steps are required; do not try to POST to \`https://slack.com/api/files.uploadV2\` \u2014 that endpoint does not exist on the Web API.
+- \`initial_comment\` uses Slack mrkdwn (\`<url|label>\`), not GitHub-flavored markdown.
+- Omit \`thread_ts\` only when you genuinely want a top-level channel post.
+- For multiple files in the same message, run steps 1\u20132 per file and pass all \`{id, title}\` objects in the \`files\` array of a single \`files.completeUploadExternal\` call \u2014 they share into the thread together.
+- If you also need to post a separate text reply in the thread, send it with \`chat.postMessage\` after the upload \u2014 but the upload itself must carry the image.
 
-Do **not** include the \`![filename](https://api.tryreplicas.com/...)\` markdown embed in external messages. It will render as a broken image / 401 for the recipient.
+Never paste the \`api.tryreplicas.com/v1/media/<id>\` URL into a Slack message body or \`initial_comment\` \u2014 it will render as a broken image attempt.
+
+### Linear \u2014 embed natively via the GraphQL \`fileUpload\` mutation
+
+Linear comments and issue bodies support markdown image embeds, but the image URL must be publicly accessible \u2014 so you upload the file to Linear's storage first, then reference the returned \`assetUrl\` in markdown. Three steps:
+
+Use \`jq\` to build the JSON bodies \u2014 the GraphQL variables (\`size\`, \`filename\`, the comment body) need to be real JSON values, not unquoted placeholders, and \`jq -n --argjson / --arg\` is the safest way to interpolate shell values without quoting bugs.
+
+\`\`\`bash
+FILE=/abs/path/to/screenshot.png
+FILENAME=$(basename "$FILE")
+SIZE=$(stat -c%s "$FILE" 2>/dev/null || stat -f%z "$FILE")
+CONTENT_TYPE=image/png
+ISSUE_UUID=...           # the Linear issue's UUID
+WORKSPACE_ID=...         # the Replicas workspace ID
+MEDIA_ID=...             # the media ID printed by \`replicas media upload\`
+
+# 1. Ask Linear for an upload URL + assetUrl.
+RESERVE=$(curl -s -X POST https://api.linear.app/graphql \\
+  -H "Authorization: Bearer $LINEAR_ACCESS_TOKEN" \\
+  -H "Content-Type: application/json" \\
+  -d "$(jq -n \\
+    --argjson size "$SIZE" \\
+    --arg contentType "$CONTENT_TYPE" \\
+    --arg filename "$FILENAME" \\
+    '{
+      query: "mutation($size: Int!, $contentType: String!, $filename: String!) { fileUpload(size: $size, contentType: $contentType, filename: $filename) { uploadFile { uploadUrl assetUrl headers { key value } } } }",
+      variables: { size: $size, contentType: $contentType, filename: $filename }
+    }')")
+UPLOAD_URL=$(echo "$RESERVE" | jq -r '.data.fileUpload.uploadFile.uploadUrl')
+ASSET_URL=$(echo "$RESERVE" | jq -r '.data.fileUpload.uploadFile.assetUrl')
+
+# 2. PUT the bytes to uploadUrl, replaying every header Linear returned.
+#    Linear's presigned URL requires the exact Content-Type / Cache-Control /
+#    etc. it gave you back, so forward each {key, value} from the headers array.
+HEADER_ARGS=()
+while IFS=$'\\t' read -r k v; do
+  HEADER_ARGS+=(-H "$k: $v")
+done < <(echo "$RESERVE" | jq -r '.data.fileUpload.uploadFile.headers[] | "\\(.key)\\t\\(.value)"')
+
+curl -s -X PUT "$UPLOAD_URL" \\
+  "\${HEADER_ARGS[@]}" \\
+  --data-binary @"$FILE"
+
+# 3. Reference assetUrl inline in the comment body, alongside the dashboard link.
+BODY=$(printf '![screenshot](%s)\\n\\n[View in Replicas](https://tryreplicas.com/workspaces/%s?mode=media&media=%s)' \\
+  "$ASSET_URL" "$WORKSPACE_ID" "$MEDIA_ID")
+
+curl -s -X POST https://api.linear.app/graphql \\
+  -H "Authorization: Bearer $LINEAR_ACCESS_TOKEN" \\
+  -H "Content-Type: application/json" \\
+  -d "$(jq -n \\
+    --arg issueId "$ISSUE_UUID" \\
+    --arg body "$BODY" \\
+    '{
+      query: "mutation($issueId: String!, $body: String!) { commentCreate(input: { issueId: $issueId, body: $body }) { success } }",
+      variables: { issueId: $issueId, body: $body }
+    }')"
+\`\`\`
+
+The same flow works for issue bodies (use \`issueCreate\` / \`issueUpdate\` with the same markdown body).
+
+Never paste the \`api.tryreplicas.com/v1/media/<id>\` URL into a Linear body or comment \u2014 it will render as a broken image to anyone outside your Replicas chat.
+
+### GitHub \u2014 link the dashboard deep link (no public upload API exists)
+
+GitHub has **no public API** for uploading images to PRs or issues. Their web UI uses an undocumented internal endpoint that's not available to API clients. So for GitHub specifically, the only correct way to share media is the dashboard deep link, rendered as a markdown hyperlink:
+
+\`\`\`markdown
+[View in Replicas](https://tryreplicas.com/workspaces/<workspace-id>?mode=media&media=<media-id>)
+\`\`\`
+
+Do **not**:
+- Commit screenshots as files to the repo as a workaround.
+- Use placeholder image URLs.
+- Embed the \`api.tryreplicas.com/v1/media/<id>\` URL in markdown \u2014 it renders as a broken image for every viewer.
+
+This applies to PR descriptions, PR review comments, issue bodies, issue comments, and commit messages.
 
 ## Recording defaults
 
@@ -8861,14 +8999,42 @@ curl -s "https://slack.com/api/search.messages?query=YOUR_SEARCH_QUERY" \\
 
 ### Uploading Files
 
+Slack deprecated \`files.upload\`; the raw HTTP replacement is a 3-step flow. (\`files.uploadV2\` is **only** an SDK convenience wrapper and is NOT a real Web API HTTP endpoint \u2014 \`POST https://slack.com/api/files.uploadV2\` returns \`unknown_method\`.)
+
 \`\`\`bash
-curl -s -X POST "https://slack.com/api/files.uploadV2" \\
+FILE=/path/to/file
+FILENAME=$(basename "$FILE")
+LENGTH=$(stat -c%s "$FILE" 2>/dev/null || stat -f%z "$FILE")
+
+# 1. Reserve an upload URL + file ID.
+RESERVE=$(curl -s -G "https://slack.com/api/files.getUploadURLExternal" \\
   -H "Authorization: Bearer $SLACK_BOT_TOKEN" \\
-  -F "channel_id=CHANNEL_ID" \\
-  -F "file=@/path/to/file" \\
-  -F "title=File title"
+  --data-urlencode "filename=$FILENAME" \\
+  --data-urlencode "length=$LENGTH")
+UPLOAD_URL=$(echo "$RESERVE" | jq -r '.upload_url')
+FILE_ID=$(echo "$RESERVE" | jq -r '.file_id')
+
+# 2. POST the raw bytes to the reserved URL.
+#    Do not use -F / multipart here \u2014 the presigned URL expects the bytes
+#    directly in the request body.
+curl -s -X POST "$UPLOAD_URL" \\
+  -H "Content-Type: application/octet-stream" \\
+  --data-binary @"$FILE"
+
+# 3. Complete the upload and share into a channel (and optionally a thread).
+curl -s -X POST "https://slack.com/api/files.completeUploadExternal" \\
+  -H "Authorization: Bearer $SLACK_BOT_TOKEN" \\
+  -H "Content-Type: application/json; charset=utf-8" \\
+  -d "{
+    \\"files\\": [{\\"id\\": \\"$FILE_ID\\", \\"title\\": \\"File title\\"}],
+    \\"channel_id\\": \\"CHANNEL_ID\\",
+    \\"thread_ts\\": \\"OPTIONAL_THREAD_TS\\",
+    \\"initial_comment\\": \\"Optional message body\\"
+  }"
 \`\`\`
 
+Omit \`thread_ts\` and/or \`initial_comment\` if you don't need them.
+
 ### Other Operations
 
 You can list channels, read channel history, add reactions, and perform any other operation supported by the Slack Web API using the same authentication pattern.
@@ -8933,7 +9099,7 @@ var HOOK_EXEC_MAX_BUFFER_BYTES = 10 * 1024 * 1024;
 var REPLICAS_CONFIG_FILENAMES = ["replicas.json", "replicas.yaml", "replicas.yml"];
 
 // ../shared/src/cli-version.ts
-var CLI_VERSION = "0.2.224";
+var CLI_VERSION = "0.2.226";
 
 // ../shared/src/engine/environment.ts
 var DESKTOP_NOVNC_PORT = 6080;
@@ -9038,6 +9204,7 @@ function workspaceConfigWithPrFollowups(config2, prFollowups = config2?.capabili
 var WORKSPACE_FILE_UPLOAD_MAX_SIZE_BYTES = 20 * 1024 * 1024;
 var WORKSPACE_FILE_CONTENT_MAX_SIZE_BYTES = 1 * 1024 * 1024;
 var WORKSPACE_SIDEBAR_VIEWS = ["owned", "shared", "team", "automation", "integrations", "api"];
+var ONE_DAY_MS = 24 * 60 * 60 * 1e3;
 
 // ../shared/src/audit-log.ts
 var AUDIT_LOG_ACTION = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "replicas-cli",
-  "version": "0.2.224",
+  "version": "0.2.226",
   "description": "CLI for managing Replicas workspaces - SSH into cloud dev environments with automatic port forwarding",
   "main": "dist/index.mjs",
   "bin": {