finalize doc-translator skill

2026-02-11 19:58:06 +01:00
parent b9d535b926
commit 94b89da533
6 changed files with 142 additions and 142 deletions
--- a/skills/doc-translator/SKILL.md
+++ b/skills/doc-translator/SKILL.md
@@ -72,76 +72,72 @@ If an image download fails, log it and continue. Use a placeholder in the final

 ### 4. Upload Images to Outline

-**IMPORTANT:** Always use Outline MCP tools for all Outline operations. If Outline tools throw errors:
-1. Load the outline skill first: `skill name=outline`
-2. Retry with `skill_mcp` tool for outline operations
-3. Only fallback to direct API calls via `bash` after exhausting MCP options
-
-mcp-outline cannot create attachments. Use direct API calls via `bash` for image uploads only.
-
-**Required env:** `OUTLINE_API_KEY` (read from /run/agenix/outline-key)
-
-For each downloaded image:
+MCP-outline does not support attachment creation. Use the bundled script for image uploads:

 ```bash
-#!/usr/bin/env bash
-set -euo pipefail
+# Upload with optional document association
+bash scripts/upload_image_to_outline.sh "/tmp/doc-images/screenshot.png" "$DOCUMENT_ID"

-IMAGE_PATH="/tmp/doc-images/screenshot.png"
-IMAGE_NAME="$(basename "$IMAGE_PATH")"
-CONTENT_TYPE="image/png"  # Detect from extension: png->image/png, jpg/jpeg->image/jpeg, gif->image/gif, svg->image/svg+xml, webp->image/webp
-
-# 1. Get file size (cross-platform)
-FILESIZE=$(stat -f%z "$IMAGE_PATH" 2>/dev/null || stat -c%s "$IMAGE_PATH")
-
-# 2. Create attachment record
-RESPONSE=$(curl -s -X POST "https://wiki.az-gruppe.com/api/attachments.create" \
-  -H "Authorization: Bearer $OUTLINE_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d "{
-    \"name\": \"$IMAGE_NAME\",
-    \"contentType\": \"$CONTENT_TYPE\",
-    \"size\": $FILESIZE
-  }")
-
-# 3. Extract URLs from response
-UPLOAD_URL=$(echo "$RESPONSE" | jq -r '.data.uploadUrl')
-ATTACHMENT_URL=$(echo "$RESPONSE" | jq -r '.data.attachment.url')
-
-# 4. Check for errors
-if [ "$UPLOAD_URL" = "null" ] || [ -z "$UPLOAD_URL" ]; then
-  echo "ERROR: Failed to create attachment. Response: $RESPONSE" >&2
-  exit 1
-fi
-
-# 5. Upload binary to signed URL
-curl -s -X PUT "$UPLOAD_URL" \
-  -H "Content-Type: $CONTENT_TYPE" \
-  --data-binary "@$IMAGE_PATH"
-
-# 6. Output the attachment URL for use in markdown
-echo "$ATTACHMENT_URL"
+# Upload without document (attach later)
+bash scripts/upload_image_to_outline.sh "/tmp/doc-images/screenshot.png"
 ```

-Replace image references in the translated markdown:
+The script handles API key loading from `/run/agenix/outline-key`, content-type detection, the two-step presigned POST flow, and retries. Output is JSON: `{"success": true, "attachment_url": "https://..."}`.
+
+Replace image references in the translated markdown with the returned `attachment_url`:
 ```markdown
 ![description](ATTACHMENT_URL)
 ```

-**Content-Type detection by extension:**
-
-| Extension | Content-Type |
-|-----------|-------------|
-| `.png` | `image/png` |
-| `.jpg`, `.jpeg` | `image/jpeg` |
-| `.gif` | `image/gif` |
-| `.svg` | `image/svg+xml` |
-| `.webp` | `image/webp` |
+For all other Outline operations (documents, collections, search), use MCP tools (`Outline_*`).

 ### 5. Translate with TEEM Format

 Translate the entire document into each target language. Apply TEEM format to UI elements.

+#### Address Form (CRITICAL)
+
+**Always use the informal "you" form** in ALL target languages:
+- **German**: Use **"Du"** (informal), NEVER "Sie" (formal)
+- **Czech**: Use **"ty"** (informal), NEVER "vy" (formal)
+- This applies to all translations — documentation should feel approachable and direct
+
+#### Infobox / Callout Formatting
+
+Source documentation often uses admonitions, callouts, or info boxes (e.g., GitHub-style `> [!NOTE]`, Docusaurus `:::note`, or custom HTML boxes). **Convert ALL such elements** to Outline's callout syntax:
+
+```markdown
+:::tip
+Tip or best practice content here.
+
+:::
+
+:::info
+Informational content here.
+
+:::
+
+:::warning
+Warning or caution content here.
+
+:::
+
+:::success
+Success message or positive outcome here.
+
+:::
+```
+
+**Mapping rules** (source → Outline):
+| Source pattern | Outline syntax |
+|---|---|
+| Note, Info, Information | `:::info` |
+| Tip, Hint, Best Practice | `:::tip` |
+| Warning, Caution, Danger, Important | `:::warning` |
+| Success, Done, Check | `:::success` |
+
+**CRITICAL formatting**: The closing `:::` MUST be on its own line with an empty line before it. Content goes directly after the opening line.
+
 #### TEEM Rules

 **Format:** `**English UI Term** (Translation)`
@@ -217,7 +213,7 @@ Use mcp-outline tools to publish:
 |-------|--------|
 | URL fetch fails | Use `question` to ask for alternative URL or manual paste |
 | Image download fails | Continue with placeholder, note in completion report |
-| Outline API error (attachments) | Save markdown to `/tmp/doc-translator-backup-TIMESTAMP.md`, report error |
+| Outline API error (attachments) | Script retries 3x with backoff; on final failure save markdown to `/tmp/doc-translator-backup-TIMESTAMP.md`, report error |
 | Outline API error (document) | Save markdown to `/tmp/doc-translator-backup-TIMESTAMP.md`, report error |
 | Ambiguous UI term | Use `question` to ask user for correct translation |
 | Large document (>5000 words) | Ask user if splitting into multiple docs is preferred |
@@ -254,9 +250,9 @@ Items Needing Review:

 ## Environment Variables

-| Variable | Purpose |
-|----------|---------|
-| `OUTLINE_API_KEY` | Bearer token for wiki.az-gruppe.com API |
+| Variable | Purpose | Source |
+|----------|---------|--------|
+| `OUTLINE_API_KEY` | Bearer token for wiki.az-gruppe.com API | Auto-loaded from `/run/agenix/outline-key` by upload script |

 ## Integration with Other Skills

--- a/skills/doc-translator/scripts/list_outline_collections.sh
+++ b/skills/doc-translator/scripts/list_outline_collections.sh
@@ -1,32 +0,0 @@
-#!/usr/bin/env bash
-# List all collections available in Outline
-#
-# Usage:
-#   list_outline_collections.sh
-#
-# Environment:
-#   OUTLINE_API_KEY - Bearer token for wiki.az-gruppe.com API
-#
-# Output (JSON):
-#   [{"id": "...", "name": "...", "url": "..."}, ...]
-
-set -euo pipefail
-
-# List collections
-RESPONSE=$(curl -s -X POST "https://wiki.az-gruppe.com/api/collections.list" \
-    -H "Authorization: Bearer $OUTLINE_API_KEY" \
-    -H "Content-Type: application/json" \
-    -d '{}')
-
-# Check for errors
-if echo "$RESPONSE" | jq -e '.error' > /dev/null 2>&1; then
-    ERROR_MSG=$(echo "$RESPONSE" | jq -r '.message // "Failed to list collections"')
-    echo "{\"success\": false, \"error\": \"$ERROR_MSG\", \"response\": \"$RESPONSE\"}" >&2
-    exit 1
-fi
-
-# Extract collection list
-COLLECTIONS=$(echo "$RESPONSE" | jq -r '.data[] | {id: .id, name: .name, url: .url}')
-
-# Output as JSON array
-echo "$COLLECTIONS" | jq -s '.'
--- a/skills/doc-translator/scripts/upload_image_to_outline.sh
+++ b/skills/doc-translator/scripts/upload_image_to_outline.sh
@@ -1,26 +1,40 @@
 #!/usr/bin/env bash
-# Upload an image to an Outline document via signed URL
+# Upload an image to Outline via presigned POST (two-step flow)
 #
 # Usage:
-#   upload_image_to_outline.sh <image_path> <document_id>
+#   upload_image_to_outline.sh <image_path> [document_id]
 #
 # Environment:
 #   OUTLINE_API_KEY - Bearer token for wiki.az-gruppe.com API
+#                     Auto-loaded from /run/agenix/outline-key if not set
 #
-# Output (JSON):
-#   {"success": true, "attachment_url": "https://...", "document_id": "..."}
-#   OR
+# Output (JSON to stdout):
+#   {"success": true, "attachment_url": "https://..."}
+# Error (JSON to stderr):
 #   {"success": false, "error": "error message"}

 set -euo pipefail

-if [ $# -ne 2 ]; then
-    echo '{"success": false, "error": "Usage: upload_image_to_outline.sh <image_path> <document_id>"}' >&2
+MAX_RETRIES=3
+RETRY_DELAY=2
+
+if [ $# -lt 1 ] || [ $# -gt 2 ]; then
+    echo '{"success": false, "error": "Usage: upload_image_to_outline.sh <image_path> [document_id]"}' >&2
    exit 1
 fi

 IMAGE_PATH="$1"
-DOCUMENT_ID="$2"
+DOCUMENT_ID="${2:-}"
+
+if [ -z "${OUTLINE_API_KEY:-}" ]; then
+    if [ -f /run/agenix/outline-key ]; then
+        OUTLINE_API_KEY=$(cat /run/agenix/outline-key)
+        export OUTLINE_API_KEY
+    else
+        echo '{"success": false, "error": "OUTLINE_API_KEY not set and /run/agenix/outline-key not found"}' >&2
+        exit 1
+    fi
+fi

 # Check if file exists
 if [ ! -f "$IMAGE_PATH" ]; then
@@ -31,60 +45,72 @@ fi
 # Extract image name and extension
 IMAGE_NAME="$(basename "$IMAGE_PATH")"
 EXTENSION="${IMAGE_NAME##*.}"
-IMAGE_NAME_BASE="${IMAGE_NAME%.*}"

 # Detect content type by extension
-case "$EXTENSION" in
-    png)   CONTENT_TYPE="image/png" ;;
-    jpg|jpeg) CONTENT_TYPE="image/jpeg" ;;
-    gif)   CONTENT_TYPE="image/gif" ;;
-    svg)   CONTENT_TYPE="image/svg+xml" ;;
-    webp)  CONTENT_TYPE="image/webp" ;;
-    *)     CONTENT_TYPE="application/octet-stream" ;;
+case "${EXTENSION,,}" in
+    png)       CONTENT_TYPE="image/png" ;;
+    jpg|jpeg)  CONTENT_TYPE="image/jpeg" ;;
+    gif)       CONTENT_TYPE="image/gif" ;;
+    svg)       CONTENT_TYPE="image/svg+xml" ;;
+    webp)      CONTENT_TYPE="image/webp" ;;
+    *)         CONTENT_TYPE="application/octet-stream" ;;
 esac

-# Get file size (cross-platform: macOS uses stat -f%z, Linux uses stat -c%s)
-FILESIZE=$(stat -f%z "$IMAGE_PATH" 2>/dev/null || stat -c%s "$IMAGE_PATH" 2>/dev/null)
+FILESIZE=$(stat -c%s "$IMAGE_PATH" 2>/dev/null || stat -f%z "$IMAGE_PATH" 2>/dev/null)

 if [ -z "$FILESIZE" ]; then
    echo "{\"success\": false, \"error\": \"Failed to get file size for: $IMAGE_PATH\"}" >&2
    exit 1
 fi

-# Create attachment record
+REQUEST_BODY=$(jq -n \
+    --arg name "$IMAGE_NAME" \
+    --arg contentType "$CONTENT_TYPE" \
+    --argjson size "$FILESIZE" \
+    --arg documentId "$DOCUMENT_ID" \
+    'if $documentId == "" then
+        {name: $name, contentType: $contentType, size: $size}
+    else
+        {name: $name, contentType: $contentType, size: $size, documentId: $documentId}
+    end')
+
+# Step 1: Create attachment record
 RESPONSE=$(curl -s -X POST "https://wiki.az-gruppe.com/api/attachments.create" \
    -H "Authorization: Bearer $OUTLINE_API_KEY" \
    -H "Content-Type: application/json" \
-    -d "{
-        \"name\": \"$IMAGE_NAME\",
-        \"contentType\": \"$CONTENT_TYPE\",
-        \"size\": $FILESIZE,
-        \"documentId\": \"$DOCUMENT_ID\"
-    }")
+    -d "$REQUEST_BODY")

-# Extract URLs from response
 UPLOAD_URL=$(echo "$RESPONSE" | jq -r '.data.uploadUrl // empty')
 ATTACHMENT_URL=$(echo "$RESPONSE" | jq -r '.data.attachment.url // empty')

-# Check for errors
-if [ -z "$UPLOAD_URL" ] || [ "$UPLOAD_URL" = "null" ]; then
+if [ -z "$UPLOAD_URL" ]; then
    ERROR_MSG=$(echo "$RESPONSE" | jq -r '.message // "Failed to create attachment"')
-    echo "{\"success\": false, \"error\": \"$ERROR_MSG\", \"response\": \"$RESPONSE\"}" >&2
+    echo "{\"success\": false, \"error\": \"$ERROR_MSG\", \"response\": $(echo "$RESPONSE" | jq -c .)}" >&2
    exit 1
 fi

-# Upload binary to signed URL
-UPLOAD_RESPONSE=$(curl -s -w "%{http_code}" -X POST "$UPLOAD_URL" \
-    -H "Content-Type: $CONTENT_TYPE" \
-    --data-binary "@$IMAGE_PATH")
+FORM_ARGS=()
+while IFS= read -r line; do
+    key=$(echo "$line" | jq -r '.key')
+    value=$(echo "$line" | jq -r '.value')
+    FORM_ARGS+=(-F "$key=$value")
+done < <(echo "$RESPONSE" | jq -c '.data.form | to_entries[]')

-# Extract HTTP status code (last 3 characters)
-HTTP_CODE="${UPLOAD_RESPONSE: -3}"
+# Step 2: Upload binary to presigned URL with retry
+for attempt in $(seq 1 "$MAX_RETRIES"); do
+    HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" -X POST "$UPLOAD_URL" \
+        "${FORM_ARGS[@]}" \
+        -F "file=@$IMAGE_PATH")

-if [ "$HTTP_CODE" != "200" ] && [ "$HTTP_CODE" != "201" ]; then
-    echo "{\"success\": false, \"error\": \"Upload failed with HTTP $HTTP_CODE\", \"upload_url\": \"$UPLOAD_URL\"}" >&2
-    exit 1
-fi
+    if [ "$HTTP_CODE" = "200" ] || [ "$HTTP_CODE" = "201" ] || [ "$HTTP_CODE" = "204" ]; then
+        echo "{\"success\": true, \"attachment_url\": \"$ATTACHMENT_URL\"}"
+        exit 0
+    fi

-# Output success result
-echo "{\"success\": true, \"attachment_url\": \"$ATTACHMENT_URL\", \"document_id\": \"$DOCUMENT_ID\"}"
+    if [ "$attempt" -lt "$MAX_RETRIES" ]; then
+        sleep "$((RETRY_DELAY * attempt))"
+    fi
+done
+
+echo "{\"success\": false, \"error\": \"Upload failed after $MAX_RETRIES attempts (last HTTP $HTTP_CODE)\"}" >&2
+exit 1
--- a/skills/skill-creator/scripts/init_skill.py
+++ b/skills/skill-creator/scripts/init_skill.py
@@ -6,8 +6,8 @@ Usage:
    init_skill.py <skill-name> --path <path>

 Examples:
-    init_skill.py my-new-skill --path ~/.config/opencode/skill
-    init_skill.py my-api-helper --path .opencode/skill
+    init_skill.py my-new-skill --path ~/.config/opencode/skills
+    init_skill.py my-api-helper --path .opencode/skills
    init_skill.py custom-skill --path /custom/location
 """