@cubis/foundry 0.3.71 → 0.3.72

package/workflows/powers/c-pro/references/posix-and-platform-apis.md

@@ -0,0 +1,244 @@
+# POSIX and Platform APIs
+
+## File I/O
+
+```c
+#include <fcntl.h>
+#include <unistd.h>
+#include <sys/stat.h>
+
+// Open with explicit permissions
+int fd = open("data.bin", O_RDWR | O_CREAT | O_TRUNC, 0644);
+if (fd == -1) {
+    perror("open");
+    return -1;
+}
+
+// Read with retry on EINTR
+ssize_t safe_read(int fd, void *buf, size_t count) {
+    ssize_t n;
+    do {
+        n = read(fd, buf, count);
+    } while (n == -1 && errno == EINTR);
+    return n;
+}
+
+// Write all bytes (handle partial writes)
+ssize_t write_all(int fd, const void *buf, size_t count) {
+    const uint8_t *p = buf;
+    size_t remaining = count;
+    while (remaining > 0) {
+        ssize_t n = write(fd, p, remaining);
+        if (n == -1) {
+            if (errno == EINTR) continue;
+            return -1;
+        }
+        p += n;
+        remaining -= n;
+    }
+    return count;
+}
+
+// Always close file descriptors
+close(fd);
+```
+
+## Memory-Mapped I/O
+
+```c
+#include <sys/mman.h>
+#include <sys/stat.h>
+#include <fcntl.h>
+
+// Map file for read-only access
+void *map_file_readonly(const char *path, size_t *out_size) {
+    int fd = open(path, O_RDONLY);
+    if (fd == -1) return NULL;
+
+    struct stat st;
+    if (fstat(fd, &st) == -1) { close(fd); return NULL; }
+
+    void *addr = mmap(NULL, st.st_size, PROT_READ, MAP_PRIVATE, fd, 0);
+    close(fd); // fd can be closed after mmap
+    if (addr == MAP_FAILED) return NULL;
+
+    *out_size = st.st_size;
+    return addr;
+}
+
+// Clean up
+munmap(addr, size);
+```
+
+## Signal Handling
+
+```c
+#include <signal.h>
+#include <stdatomic.h>
+
+// Use sig_atomic_t or atomics for signal flags
+static volatile sig_atomic_t shutdown_requested = 0;
+
+void handle_signal(int sig) {
+    (void)sig;
+    shutdown_requested = 1;
+    // ONLY async-signal-safe functions are allowed here:
+    // write(), _exit(), signal(), abort()
+    // DO NOT use printf, malloc, free, etc.
+}
+
+void setup_signals(void) {
+    struct sigaction sa = {
+        .sa_handler = handle_signal,
+        .sa_flags = 0,
+    };
+    sigemptyset(&sa.sa_mask);
+    sigaction(SIGTERM, &sa, NULL);
+    sigaction(SIGINT, &sa, NULL);
+}
+
+// Main loop checks the flag
+while (!shutdown_requested) {
+    process_next_item();
+}
+```
+
+## Process and Fork
+
+```c
+#include <sys/wait.h>
+
+// Fork with proper error handling
+pid_t pid = fork();
+if (pid == -1) {
+    perror("fork");
+    exit(EXIT_FAILURE);
+} else if (pid == 0) {
+    // Child process
+    execvp(argv[0], argv); // replaces child image
+    perror("exec");        // only reached on error
+    _exit(127);            // use _exit, not exit, in child after fork
+} else {
+    // Parent process
+    int status;
+    waitpid(pid, &status, 0);
+    if (WIFEXITED(status)) {
+        int exit_code = WEXITSTATUS(status);
+    }
+}
+```
+
+## Socket Programming
+
+```c
+#include <sys/socket.h>
+#include <netinet/in.h>
+#include <arpa/inet.h>
+
+// TCP server setup
+int create_server(uint16_t port) {
+    int fd = socket(AF_INET, SOCK_STREAM, 0);
+    if (fd == -1) return -1;
+
+    int opt = 1;
+    setsockopt(fd, SOL_SOCKET, SO_REUSEADDR, &opt, sizeof(opt));
+
+    struct sockaddr_in addr = {
+        .sin_family = AF_INET,
+        .sin_port = htons(port),
+        .sin_addr.s_addr = INADDR_ANY,
+    };
+
+    if (bind(fd, (struct sockaddr *)&addr, sizeof(addr)) == -1) {
+        close(fd);
+        return -1;
+    }
+
+    if (listen(fd, SOMAXCONN) == -1) {
+        close(fd);
+        return -1;
+    }
+
+    return fd;
+}
+```
+
+## Platform Abstraction Layer Pattern
+
+```c
+// platform.h — unified interface
+#pragma once
+
+typedef struct platform_file platform_file;
+
+platform_file *platform_open(const char *path, int flags);
+ssize_t platform_read(platform_file *f, void *buf, size_t count);
+void platform_close(platform_file *f);
+uint64_t platform_monotonic_time_ns(void);
+
+// platform_posix.c — POSIX implementation
+#if defined(__linux__) || defined(__APPLE__)
+#include <time.h>
+
+uint64_t platform_monotonic_time_ns(void) {
+    struct timespec ts;
+    clock_gettime(CLOCK_MONOTONIC, &ts);
+    return (uint64_t)ts.tv_sec * 1000000000ULL + ts.tv_nsec;
+}
+#endif
+
+// platform_win32.c — Windows implementation
+#if defined(_WIN32)
+#include <windows.h>
+
+uint64_t platform_monotonic_time_ns(void) {
+    LARGE_INTEGER freq, count;
+    QueryPerformanceFrequency(&freq);
+    QueryPerformanceCounter(&count);
+    return (uint64_t)(count.QuadPart * 1000000000LL / freq.QuadPart);
+}
+#endif
+```
+
+## Error Handling Patterns
+
+```c
+// Return error codes with context struct
+typedef struct {
+    int code;
+    const char *message;
+    const char *file;
+    int line;
+} error_t;
+
+#define ERROR(code, msg) ((error_t){ (code), (msg), __FILE__, __LINE__ })
+#define OK ((error_t){ 0, NULL, NULL, 0 })
+
+error_t process_file(const char *path) {
+    int fd = open(path, O_RDONLY);
+    if (fd == -1) return ERROR(errno, "failed to open file");
+
+    // ...
+    close(fd);
+    return OK;
+}
+
+// Goto-based cleanup (idiomatic C error handling)
+int init_system(void) {
+    int ret = -1;
+    void *buf = malloc(BUF_SIZE);
+    if (!buf) goto out;
+
+    int fd = open("config", O_RDONLY);
+    if (fd == -1) goto cleanup_buf;
+
+    // ... use buf and fd ...
+    ret = 0;
+
+    close(fd);
+cleanup_buf:
+    free(buf);
+out:
+    return ret;
+}
+```

package/workflows/powers/changelog-generator/POWER.md

@@ -2,105 +2,169 @@
 ---
 inclusion: manual
 name: changelog-generator
-description: Automatically creates user-facing changelogs from git commits by analyzing commit history, categorizing changes, and transforming technical commits into clear, customer-friendly release notes. Turns hours of manual changelog writing into minutes of automated generation.
+description: Generate changelogs from conventional commits, semantic versioning, release notes, and automated version management workflows.
+license: Apache-2.0
+metadata:
+  author: cubis-foundry
+  version: "3.0"
+compatibility: Claude Code, Codex, GitHub Copilot, Gemini CLI
 ---
 
 # Changelog Generator
 
-This skill transforms technical git commits into polished, user-friendly changelogs that your customers and users will actually understand and appreciate.
+## Purpose
 
-## When to Use This Skill
+Guide changelog generation, release notes writing, and version management using conventional commits and semantic versioning.
 
-- Preparing release notes for a new version
-- Creating weekly or monthly product update summaries
-- Documenting changes for customers
-- Writing changelog entries for app store submissions
-- Generating update notifications
-- Creating internal release documentation
-- Maintaining a public changelog/product updates page
+## When to Use
 
-## What This Skill Does
+- Generating a CHANGELOG.md from commit history
+- Writing release notes for a new version
+- Setting up automated versioning workflows
+- Reviewing commit message format and conventions
+- Planning a release with breaking changes
 
-1. **Scans Git History**: Analyzes commits from a specific time period or between versions
-2. **Categorizes Changes**: Groups commits into logical categories (features, improvements, bug fixes, breaking changes, security)
-3. **Translates Technical → User-Friendly**: Converts developer commits into customer language
-4. **Formats Professionally**: Creates clean, structured changelog entries
-5. **Filters Noise**: Excludes internal commits (refactoring, tests, etc.)
-6. **Follows Best Practices**: Applies changelog guidelines and your brand voice
+## Instructions
 
-## How to Use
+### Step 1 — Follow Conventional Commits
 
-### Basic Usage
+**Format**: `<type>(<scope>): <description>`
 
-From your project repository:
+| Type       | SemVer Bump | When                                   |
+| ---------- | ----------- | -------------------------------------- |
+| `feat`     | Minor       | New feature for users                  |
+| `fix`      | Patch       | Bug fix for users                      |
+| `docs`     | None        | Documentation only                     |
+| `style`    | None        | Formatting, no logic change            |
+| `refactor` | None        | Code restructuring, no behavior change |
+| `perf`     | Patch       | Performance improvement                |
+| `test`     | None        | Adding or fixing tests                 |
+| `build`    | None        | Build system or dependencies           |
+| `ci`       | None        | CI/CD configuration                    |
+| `chore`    | None        | Maintenance tasks                      |
 
-```
-Create a changelog from commits since last release
-```
+**Breaking changes**: Add `!` after type or `BREAKING CHANGE:` in footer:
 
 ```
-Generate changelog for all commits from the past week
-```
+feat!: remove deprecated API endpoints
 
-```
-Create release notes for version 2.5.0
+BREAKING CHANGE: /v1/users endpoint has been removed. Use /v2/users instead.
 ```
 
-### With Specific Date Range
+### Step 2 — Generate Changelog
 
-```
-Create a changelog for all commits between March 1 and March 15
-```
+**Changelog format** (Keep a Changelog style):
+
+```markdown
+# Changelog
 
-### With Custom Guidelines
+## [2.1.0] - 2025-01-15
 
+### Added
+
+- User profile image upload (#234)
+- Dark mode support for dashboard (#256)
+
+### Fixed
+
+- Login timeout on slow connections (#245)
+- Currency formatting for Japanese Yen (#249)
+
+### Changed
+
+- Increased password minimum length to 12 characters (#251)
+
+## [2.0.0] - 2024-12-01
+
+### Breaking Changes
+
+- Removed deprecated /v1/users endpoint — use /v2/users (#230)
+
+### Added
+
+- New user roles system with RBAC (#220)
 ```
-Create a changelog for commits since v2.4.0, using my changelog 
-guidelines from CHANGELOG_STYLE.md
-```
 
-## Example
+**Mapping rules**:
+
+- `feat` → **Added**
+- `fix` → **Fixed**
+- `feat!` / `BREAKING CHANGE` → **Breaking Changes**
+- `perf` → **Performance**
+- `refactor` with user-visible changes → **Changed**
+- `deprecate` → **Deprecated**
+- `remove` → **Removed**
+
+### Step 3 — Semantic Versioning
+
+**MAJOR.MINOR.PATCH** (e.g., 2.1.3):
+
+- **MAJOR**: Breaking changes (API removal, incompatible changes)
+- **MINOR**: New features (backward-compatible additions)
+- **PATCH**: Bug fixes (backward-compatible fixes)
+
+**Pre-release versions**: `2.1.0-beta.1`, `2.1.0-rc.1`
+
+**Rules**:
 
-**User**: "Create a changelog for commits from the past 7 days"
+- Version 0.x.y is for initial development (anything may change)
+- First stable release is 1.0.0
+- Never change a released version — create a new one
+
+### Step 4 — Write Release Notes
+
+**Release notes structure**:
+
+1. **Headline** — one sentence summarizing the release theme
+2. **Highlights** — 2-3 most important changes with context
+3. **Full changelog** — categorized list of all changes
+4. **Migration guide** — for breaking changes, step-by-step upgrade instructions
+5. **Contributors** — acknowledge contributors
+
+**Good highlights**:
 
-**Output**:
 ```markdown
-# Updates - Week of March 10, 2024
+### Highlights
 
-## ✨ New Features
+**Dark Mode** — The dashboard now supports dark mode, automatically
+matching your system preference. Toggle manually in Settings → Appearance.
 
-- **Team Workspaces**: Create separate workspaces for different 
-  projects. Invite team members and keep everything organized.
+**Faster Search** — Search results now load 3x faster thanks to a new
+indexing strategy. No changes needed on your end.
+```
+
+### Step 5 — Automate the Workflow
 
-- **Keyboard Shortcuts**: Press ? to see all available shortcuts. 
-  Navigate faster without touching your mouse.
+**CI pipeline**:
 
-## 🔧 Improvements
+1. Lint commit messages on PR (reject non-conventional)
+2. On merge to main: determine version bump from commits
+3. Generate changelog entry
+4. Bump version in package.json / pyproject.toml
+5. Create git tag
+6. Create GitHub Release with release notes
+7. Publish to package registry
 
-- **Faster Sync**: Files now sync 2x faster across devices
-- **Better Search**: Search now includes file contents, not just titles
+## Output Format
+
+```
+## Version
+[version number and bump reasoning]
 
-## 🐛 Fixes
+## Changelog Entry
+[formatted changelog in Keep a Changelog style]
 
-- Fixed issue where large images wouldn't upload
-- Resolved timezone confusion in scheduled posts
-- Corrected notification badge count
+## Release Notes
+[user-facing summary with highlights and migration guide]
 ```
 
-**Inspired by:** Manik Aggarwal's use case from Lenny's Newsletter
+## Examples
 
-## Tips
+**User**: "Generate a changelog for our latest release"
 
-- Run from your git repository root
-- Specify date ranges for focused changelogs
-- Use your CHANGELOG_STYLE.md for consistent formatting
-- Review and adjust the generated changelog before publishing
-- Save output directly to CHANGELOG.md
+**Response approach**: Scan commits since last tag. Categorize by type. Generate changelog in Keep a Changelog format. Determine version bump (major/minor/patch). Write release highlights.
 
-## Related Use Cases
+**User**: "We have breaking API changes — how do we release this?"
 
-- Creating GitHub release notes
-- Writing app store update descriptions
-- Generating email updates for users
-- Creating social media announcement posts
+**Response approach**: Bump major version. Write migration guide with before/after examples. Add deprecation notices in the previous minor release if possible. Generate changelog with Breaking Changes section first.
 ````