opencode-skills-collection 4.0.53 → 4.0.54

package/bundled-skills/azure-storage-queue-ts/references/detailed-guide.md

@@ -0,0 +1,530 @@
+# @azure/storage-queue (TypeScript/JavaScript) - Detailed Guide
+
+> This file contains the detailed procedure and reference material extracted from `SKILL.md` for focused loading. The root skill defines activation, examples, safety constraints, and limitations.
+
+## Installation
+
+```bash
+npm install @azure/storage-queue @azure/identity
+```
+
+**Current Version**: 12.x
+**Node.js**: >= 18.0.0
+
+
+## Environment Variables
+
+```bash
+AZURE_STORAGE_ACCOUNT_NAME=<account-name>
+AZURE_STORAGE_ACCOUNT_KEY=<account-key>
+# OR connection string
+AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=...
+```
+
+
+## Authentication
+
+### DefaultAzureCredential (Recommended)
+
+```typescript
+import { QueueServiceClient } from "@azure/storage-queue";
+import { DefaultAzureCredential } from "@azure/identity";
+
+const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME!;
+const client = new QueueServiceClient(
+  `https://${accountName}.queue.core.windows.net`,
+  new DefaultAzureCredential()
+);
+```
+
+### Connection String
+
+```typescript
+import { QueueServiceClient } from "@azure/storage-queue";
+
+const client = QueueServiceClient.fromConnectionString(
+  process.env.AZURE_STORAGE_CONNECTION_STRING!
+);
+```
+
+### StorageSharedKeyCredential (Node.js only)
+
+```typescript
+import { QueueServiceClient, StorageSharedKeyCredential } from "@azure/storage-queue";
+
+const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME!;
+const accountKey = process.env.AZURE_STORAGE_ACCOUNT_KEY!;
+
+const sharedKeyCredential = new StorageSharedKeyCredential(accountName, accountKey);
+const client = new QueueServiceClient(
+  `https://${accountName}.queue.core.windows.net`,
+  sharedKeyCredential
+);
+```
+
+### SAS Token
+
+```typescript
+import { QueueServiceClient } from "@azure/storage-queue";
+
+const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME!;
+const sasToken = process.env.AZURE_STORAGE_SAS_TOKEN!;
+
+const client = new QueueServiceClient(
+  `https://${accountName}.queue.core.windows.net${sasToken}`
+);
+```
+
+
+## Client Hierarchy
+
+```
+QueueServiceClient (account level)
+└── QueueClient (queue level)
+    └── Messages (send, receive, peek, delete)
+```
+
+
+## Queue Operations
+
+### Create Queue
+
+```typescript
+const queueClient = client.getQueueClient("my-queue");
+await queueClient.create();
+
+// Or create if not exists
+await queueClient.createIfNotExists();
+```
+
+### List Queues
+
+```typescript
+for await (const queue of client.listQueues()) {
+  console.log(queue.name);
+}
+
+// With prefix filter
+for await (const queue of client.listQueues({ prefix: "task-" })) {
+  console.log(queue.name);
+}
+```
+
+### Delete Queue
+
+```typescript
+await queueClient.delete();
+
+// Or delete if exists
+await queueClient.deleteIfExists();
+```
+
+### Get Queue Properties
+
+```typescript
+const properties = await queueClient.getProperties();
+console.log("Approximate message count:", properties.approximateMessagesCount);
+console.log("Metadata:", properties.metadata);
+```
+
+### Set Queue Metadata
+
+```typescript
+await queueClient.setMetadata({
+  department: "engineering",
+  priority: "high",
+});
+```
+
+
+## Message Operations
+
+### Send Message
+
+```typescript
+const queueClient = client.getQueueClient("my-queue");
+
+// Simple message
+await queueClient.sendMessage("Hello, World!");
+
+// With options
+await queueClient.sendMessage("Delayed message", {
+  visibilityTimeout: 60, // Hidden for 60 seconds
+  messageTimeToLive: 3600, // Expires in 1 hour
+});
+
+// JSON message (must be string)
+const task = { type: "process", data: { id: 123 } };
+await queueClient.sendMessage(JSON.stringify(task));
+```
+
+### Receive Messages
+
+```typescript
+// Receive up to 32 messages (default: 1)
+const response = await queueClient.receiveMessages({
+  numberOfMessages: 10,
+  visibilityTimeout: 30, // 30 seconds to process
+});
+
+for (const message of response.receivedMessageItems) {
+  console.log("Message ID:", message.messageId);
+  console.log("Content:", message.messageText);
+  console.log("Dequeue Count:", message.dequeueCount);
+  console.log("Pop Receipt:", message.popReceipt);
+
+  // Process the message...
+
+  // Delete after processing
+  await queueClient.deleteMessage(message.messageId, message.popReceipt);
+}
+```
+
+### Peek Messages
+
+Peek without removing from queue (no visibility timeout).
+
+```typescript
+const response = await queueClient.peekMessages({
+  numberOfMessages: 5,
+});
+
+for (const message of response.peekedMessageItems) {
+  console.log("Message ID:", message.messageId);
+  console.log("Content:", message.messageText);
+  // Note: No popReceipt - cannot delete peeked messages
+}
+```
+
+### Update Message
+
+Extend visibility timeout or update content.
+
+```typescript
+// Receive a message
+const response = await queueClient.receiveMessages();
+const message = response.receivedMessageItems[0];
+
+if (message) {
+  // Update content and extend visibility
+  const updateResponse = await queueClient.updateMessage(
+    message.messageId,
+    message.popReceipt,
+    "Updated content",
+    60 // New visibility timeout in seconds
+  );
+
+  // Use new popReceipt for subsequent operations
+  console.log("New pop receipt:", updateResponse.popReceipt);
+}
+```
+
+### Delete Message
+
+```typescript
+// After receiving
+const response = await queueClient.receiveMessages();
+const message = response.receivedMessageItems[0];
+
+if (message) {
+  await queueClient.deleteMessage(message.messageId, message.popReceipt);
+}
+```
+
+### Clear All Messages
+
+```typescript
+await queueClient.clearMessages();
+```
+
+
+## Message Processing Patterns
+
+### Basic Worker Pattern
+
+```typescript
+async function processQueue(queueClient: QueueClient): Promise<void> {
+  while (true) {
+    const response = await queueClient.receiveMessages({
+      numberOfMessages: 10,
+      visibilityTimeout: 30,
+    });
+
+    if (response.receivedMessageItems.length === 0) {
+      // No messages, wait before polling again
+      await sleep(5000);
+      continue;
+    }
+
+    for (const message of response.receivedMessageItems) {
+      try {
+        await processMessage(message.messageText);
+        await queueClient.deleteMessage(message.messageId, message.popReceipt);
+      } catch (error) {
+        console.error(`Failed to process message ${message.messageId}:`, error);
+        // Message will become visible again after timeout
+      }
+    }
+  }
+}
+
+async function processMessage(content: string): Promise<void> {
+  const task = JSON.parse(content);
+  // Process task...
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+```
+
+### Poison Message Handling
+
+```typescript
+const MAX_DEQUEUE_COUNT = 5;
+
+async function processWithPoisonHandling(
+  queueClient: QueueClient,
+  poisonQueueClient: QueueClient
+): Promise<void> {
+  const response = await queueClient.receiveMessages({
+    numberOfMessages: 10,
+    visibilityTimeout: 30,
+  });
+
+  for (const message of response.receivedMessageItems) {
+    if (message.dequeueCount > MAX_DEQUEUE_COUNT) {
+      // Move to poison queue
+      await poisonQueueClient.sendMessage(message.messageText);
+      await queueClient.deleteMessage(message.messageId, message.popReceipt);
+      console.log(`Moved message ${message.messageId} to poison queue`);
+      continue;
+    }
+
+    try {
+      await processMessage(message.messageText);
+      await queueClient.deleteMessage(message.messageId, message.popReceipt);
+    } catch (error) {
+      console.error(`Processing failed (attempt ${message.dequeueCount}):`, error);
+    }
+  }
+}
+```
+
+### Batch Processing with Visibility Extension
+
+```typescript
+async function processBatchWithExtension(queueClient: QueueClient): Promise<void> {
+  const response = await queueClient.receiveMessages({
+    numberOfMessages: 1,
+    visibilityTimeout: 60,
+  });
+
+  const message = response.receivedMessageItems[0];
+  if (!message) return;
+
+  let popReceipt = message.popReceipt;
+
+  // Start visibility extension timer
+  const extensionInterval = setInterval(async () => {
+    try {
+      const updateResponse = await queueClient.updateMessage(
+        message.messageId,
+        popReceipt,
+        message.messageText,
+        60 // Extend by another 60 seconds
+      );
+      popReceipt = updateResponse.popReceipt;
+    } catch (error) {
+      console.error("Failed to extend visibility:", error);
+    }
+  }, 45000); // Extend every 45 seconds
+
+  try {
+    await longRunningProcess(message.messageText);
+    await queueClient.deleteMessage(message.messageId, popReceipt);
+  } finally {
+    clearInterval(extensionInterval);
+  }
+}
+```
+
+
+## Message Encoding
+
+By default, messages are Base64 encoded. You can customize this:
+
+```typescript
+import { QueueClient } from "@azure/storage-queue";
+
+// Custom encoder/decoder for plain text
+const queueClient = new QueueClient(
+  `https://${accountName}.queue.core.windows.net/my-queue`,
+  credential,
+  {
+    messageEncoding: "text", // "base64" (default) or "text"
+  }
+);
+
+// Or with custom encoder
+const customQueueClient = new QueueClient(
+  `https://${accountName}.queue.core.windows.net/my-queue`,
+  credential,
+  {
+    messageEncoding: {
+      encode: (message: string) => Buffer.from(message).toString("base64"),
+      decode: (message: string) => Buffer.from(message, "base64").toString(),
+    },
+  }
+);
+```
+
+
+## SAS Token Generation (Node.js only)
+
+### Generate Queue SAS
+
+```typescript
+import {
+  QueueSASPermissions,
+  generateQueueSASQueryParameters,
+  StorageSharedKeyCredential,
+} from "@azure/storage-queue";
+
+const sharedKeyCredential = new StorageSharedKeyCredential(accountName, accountKey);
+
+const sasToken = generateQueueSASQueryParameters(
+  {
+    queueName: "my-queue",
+    permissions: QueueSASPermissions.parse("raup"), // read, add, update, process
+    startsOn: new Date(),
+    expiresOn: new Date(Date.now() + 3600 * 1000), // 1 hour
+  },
+  sharedKeyCredential
+).toString();
+
+const sasUrl = `https://${accountName}.queue.core.windows.net/my-queue?${sasToken}`;
+```
+
+### Generate Account SAS
+
+```typescript
+import {
+  AccountSASPermissions,
+  AccountSASResourceTypes,
+  AccountSASServices,
+  generateAccountSASQueryParameters,
+} from "@azure/storage-queue";
+
+const sasToken = generateAccountSASQueryParameters(
+  {
+    services: AccountSASServices.parse("q").toString(), // queue
+    resourceTypes: AccountSASResourceTypes.parse("sco").toString(),
+    permissions: AccountSASPermissions.parse("rwdlacupi"),
+    expiresOn: new Date(Date.now() + 24 * 3600 * 1000),
+  },
+  sharedKeyCredential
+).toString();
+```
+
+
+## Error Handling
+
+```typescript
+import { RestError } from "@azure/storage-queue";
+
+try {
+  await queueClient.sendMessage("test");
+} catch (error) {
+  if (error instanceof RestError) {
+    switch (error.statusCode) {
+      case 404:
+        console.log("Queue not found");
+        break;
+      case 400:
+        console.log("Bad request - message too large or invalid");
+        break;
+      case 403:
+        console.log("Access denied");
+        break;
+      case 409:
+        console.log("Queue already exists or being deleted");
+        break;
+      default:
+        console.error(`Storage error ${error.statusCode}: ${error.message}`);
+    }
+  }
+  throw error;
+}
+```
+
+
+## TypeScript Types Reference
+
+```typescript
+import {
+  // Clients
+  QueueServiceClient,
+  QueueClient,
+
+  // Authentication
+  StorageSharedKeyCredential,
+  AnonymousCredential,
+
+  // SAS
+  QueueSASPermissions,
+  AccountSASPermissions,
+  AccountSASServices,
+  AccountSASResourceTypes,
+  generateQueueSASQueryParameters,
+  generateAccountSASQueryParameters,
+
+  // Messages
+  DequeuedMessageItem,
+  PeekedMessageItem,
+  QueueSendMessageResponse,
+  QueueReceiveMessageResponse,
+  QueueUpdateMessageResponse,
+
+  // Queue
+  QueueItem,
+  QueueGetPropertiesResponse,
+
+  // Errors
+  RestError,
+} from "@azure/storage-queue";
+```
+
+
+## Message Limits
+
+| Limit | Value |
+|-------|-------|
+| Max message size | 64 KB |
+| Max visibility timeout | 7 days |
+| Max time-to-live | 7 days (or -1 for infinite) |
+| Max messages per receive | 32 |
+| Default visibility timeout | 30 seconds |
+
+
+## Best Practices
+
+1. **Use DefaultAzureCredential** — Prefer AAD over connection strings/keys
+2. **Always delete after processing** — Prevent duplicate processing
+3. **Handle poison messages** — Move failed messages to a dead-letter queue
+4. **Use appropriate visibility timeout** — Set based on expected processing time
+5. **Extend visibility for long tasks** — Update message to prevent timeout
+6. **Use JSON for structured data** — Serialize objects to JSON strings
+7. **Check dequeueCount** — Detect repeatedly failing messages
+8. **Use batch receive** — Receive multiple messages for efficiency
+
+
+## Platform Differences
+
+| Feature | Node.js | Browser |
+|---------|---------|---------|
+| `StorageSharedKeyCredential` | ✅ | ❌ |
+| SAS generation | ✅ | ❌ |
+| DefaultAzureCredential | ✅ | ❌ |
+| Anonymous/SAS access | ✅ | ✅ |
+| All message operations | ✅ | ✅ |

package/bundled-skills/backend-development-feature-development/SKILL.md

@@ -182,6 +182,12 @@ If issues arise during or after deployment:
 
 Feature description: $ARGUMENTS
 
+## Example
+
+**User request:**
+
+> Coordinate end-to-end feature delivery across backend, frontend, and data.
+
 ## Limitations
 - Use this skill only when the task clearly matches the scope described above.
 - Do not treat the output as a substitute for environment-specific validation, testing, or expert review.

package/bundled-skills/basecamp-automation/SKILL.md

@@ -236,6 +236,12 @@ Basecamp uses page-based pagination on list endpoints:
 ## When to Use
 This skill is applicable to execute the workflow or actions described in the overview.
 
+## Example
+
+**User request:**
+
+> Automate Basecamp project management, to-dos, messages, people, and to-do list organization via Rube MCP (Composio).
+
 ## Limitations
 - Use this skill only when the task clearly matches the scope described above.
 - Do not treat the output as a substitute for environment-specific validation, testing, or expert review.

package/bundled-skills/baseline-ui/SKILL.md

@@ -95,6 +95,12 @@ Enforces an opinionated UI baseline to prevent AI-generated interface slop.
 - SHOULD limit accent color usage to one per view
 - SHOULD use existing theme or Tailwind CSS color tokens before introducing new ones
 
+## Example
+
+**User request:**
+
+> Review this interface with @baseline-ui, identify the highest-impact design problems, and propose an implementation-ready improvement.
+
 ## Limitations
 
 - Use this skill only when the task clearly matches its upstream source and local project context.

package/bundled-skills/bash-pro/SKILL.md

@@ -314,6 +314,12 @@ date_added: '2026-02-27'
 - [Awesome Bash](https://github.com/awesome-lists/awesome-bash) - Curated list of Bash resources and tools
 - [Pure Bash Bible](https://github.com/dylanaraps/pure-bash-bible) - Collection of pure bash alternatives to external commands
 
+## Example
+
+**User request:**
+
+> Write or reviewing Bash scripts for automation, CI/CD, or ops.
+
 ## Limitations
 - Use this skill only when the task clearly matches the scope described above.
 - Do not treat the output as a substitute for environment-specific validation, testing, or expert review.

package/bundled-skills/bdi-mental-states/SKILL.md

@@ -3,6 +3,7 @@ name: bdi-mental-states
 description: This skill should be used when the user asks to "model agent mental states", "implement BDI architecture", "create belief-desire-intention models", "transform RDF to beliefs", "build cognitive agent", or mentions BDI ontology, mental state modeling, rational agency, or neuro-symbolic AI integration.
 risk: critical
 source: community
+date_added: "2026-09-04"
 ---
 
 # BDI Mental State Modeling

package/bundled-skills/beautiful-prose/SKILL.md

@@ -3,6 +3,7 @@ name: beautiful-prose
 description: A hard-edged writing style contract for timeless, forceful English prose without modern AI tics. Use when users ask for prose or rewrites that must be clean, exact, concrete, and free of AI cadence, filler, or therapeutic tone.
 risk: none
 source: community
+date_added: "2026-09-04"
 ---
 
 # Beautiful Prose (Claude Skill)