@buildlog/openclaw-skill 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 buildlogai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,282 @@
+# @buildlog/openclaw-skill
+
+Record, export, and share your AI coding sessions as replayable buildlogs.
+
+[![npm version](https://badge.fury.io/js/@buildlog%2Fopenclaw-skill.svg)](https://www.npmjs.com/package/@buildlog/openclaw-skill)
+[![ClawHub](https://img.shields.io/badge/ClawHub-buildlog-blue)](https://clawhub.io/skills/buildlog)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Overview
+
+The buildlog skill captures your OpenClaw AI-assisted coding sessions in real-time, creating replayable recordings that can be shared on [buildlog.ai](https://buildlog.ai).
+
+Perfect for:
+- 📚 **Tutorials** — Share how you built something step-by-step
+- 📝 **Documentation** — Create living documentation of complex implementations
+- 🐛 **Debugging** — Review sessions to understand what went wrong
+- 🎓 **Learning** — Study how others approach problems
+
+## Installation
+
+### From ClawHub (Recommended)
+
+```bash
+openclaw skill install buildlog
+```
+
+### From npm
+
+```bash
+npm install @buildlog/openclaw-skill
+```
+
+## Quick Start
+
+Once installed, just talk to OpenClaw:
+
+```
+You: Start a buildlog "Building a REST API"
+🔴 Recording started: "Building a REST API"
+
+You: Create an Express server with TypeScript
+[OpenClaw creates files...]
+
+You: Stop the buildlog
+✅ Recording stopped. 12 exchanges captured.
+Would you like to upload to buildlog.ai?
+
+You: Yes
+✅ Uploaded to buildlog.ai!
+🔗 https://buildlog.ai/b/abc123
+```
+
+## Commands
+
+### Recording
+
+| Command | Description |
+|---------|-------------|
+| `Start a buildlog [title]` | Begin recording a new session |
+| `Stop the buildlog` | End recording and optionally upload |
+| `Pause the buildlog` | Temporarily pause recording |
+| `Resume the buildlog` | Continue a paused recording |
+
+### Exporting
+
+| Command | Description |
+|---------|-------------|
+| `Export this session as a buildlog` | Convert current session to buildlog format |
+| `Export the last [N] messages` | Export a portion of the session |
+
+### Uploading
+
+| Command | Description |
+|---------|-------------|
+| `Upload the buildlog` | Push to buildlog.ai |
+| `Share the buildlog` | Upload and get a shareable link |
+
+### Annotations
+
+| Command | Description |
+|---------|-------------|
+| `Add a note: [text]` | Add commentary to the current point |
+| `Mark this as important` | Flag the current exchange |
+| `Add chapter: [title]` | Create a chapter marker |
+
+### Status
+
+| Command | Description |
+|---------|-------------|
+| `Buildlog status` | Check recording state |
+| `Show buildlog info` | Display current recording details |
+
+## Configuration
+
+Add to your OpenClaw configuration file (`~/.openclaw/config.json`):
+
+```json
+{
+  "skills": {
+    "buildlog": {
+      "apiKey": "your-api-key",
+      "autoUpload": false,
+      "defaultPublic": true,
+      "includeFileContents": true,
+      "maxFileSizeKb": 100
+    }
+  }
+}
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiKey` | string | — | Your buildlog.ai API key (optional for public uploads) |
+| `autoUpload` | boolean | `false` | Automatically upload when recording stops |
+| `defaultPublic` | boolean | `true` | Make buildlogs public by default |
+| `includeFileContents` | boolean | `true` | Include file content snapshots |
+| `maxFileSizeKb` | number | `100` | Maximum file size to include in buildlog |
+
+## Programmatic Usage
+
+You can also use the skill programmatically:
+
+```typescript
+import { 
+  BuildlogRecorder, 
+  BuildlogExporter, 
+  BuildlogUploader 
+} from '@buildlog/openclaw-skill';
+
+// Create a recorder
+const recorder = new BuildlogRecorder({
+  includeFileContents: true,
+  maxFileSizeKb: 100,
+});
+
+// Start recording
+recorder.start('My Session');
+
+// Handle events
+recorder.handleEvent({
+  type: 'user_message',
+  timestamp: Date.now(),
+  data: { content: 'Create a function...' },
+});
+
+// Stop and get buildlog
+const session = recorder.stop();
+const buildlog = recorder.toBuildlog();
+
+// Upload
+const uploader = new BuildlogUploader({ apiKey: 'your-key' });
+const result = await uploader.upload(buildlog);
+
+console.log('Uploaded:', result.url);
+```
+
+### Retroactive Export
+
+Export an existing session history:
+
+```typescript
+import { BuildlogExporter } from '@buildlog/openclaw-skill';
+
+const exporter = new BuildlogExporter({
+  title: 'My Coding Session',
+  tags: ['typescript', 'api'],
+});
+
+const buildlog = exporter.export(sessionHistory);
+```
+
+## Events
+
+The skill emits the following events that you can subscribe to:
+
+```typescript
+skill.recorder.on('started', (event) => {
+  console.log('Recording started:', event.data.title);
+});
+
+skill.recorder.on('stopped', (event) => {
+  console.log('Recording stopped:', event.data.session);
+});
+```
+
+| Event | Description |
+|-------|-------------|
+| `buildlog:started` | Recording began |
+| `buildlog:stopped` | Recording ended |
+| `buildlog:paused` | Recording paused |
+| `buildlog:resumed` | Recording resumed |
+| `buildlog:uploaded` | Buildlog uploaded successfully |
+| `buildlog:error` | An error occurred |
+
+## API Reference
+
+### BuildlogSkill
+
+Main skill class for OpenClaw integration.
+
+```typescript
+const skill = createBuildlogSkill(config);
+await skill.initialize(openClawContext);
+const handled = await skill.handleMessage(ctx, 'start a buildlog');
+skill.dispose();
+```
+
+### BuildlogRecorder
+
+State machine for recording sessions.
+
+```typescript
+const recorder = new BuildlogRecorder(config);
+recorder.start('Title');
+recorder.handleEvent(event);
+recorder.addNote('Important point');
+recorder.addChapter('Setup');
+recorder.pause();
+recorder.resume();
+const session = recorder.stop();
+```
+
+### BuildlogExporter
+
+Convert session history to buildlog format.
+
+```typescript
+const exporter = new BuildlogExporter(options);
+const buildlog = exporter.export(sessionHistory);
+const partial = exporter.exportLastN(sessionHistory, 10);
+```
+
+### BuildlogUploader
+
+Upload buildlogs to buildlog.ai.
+
+```typescript
+const uploader = new BuildlogUploader({ apiKey });
+const result = await uploader.upload(buildlog, options);
+const info = await uploader.getInfo(id);
+await uploader.delete(id);
+```
+
+## Privacy
+
+- 🔒 Buildlogs can be public or private
+- 🔑 API keys are never included in exports
+- 🎛️ You control what gets shared
+- 🗑️ Delete buildlogs anytime at buildlog.ai
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+
+# Watch mode
+npm run dev
+```
+
+## Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.
+
+## License
+
+MIT © [buildlog.ai](https://buildlog.ai)
+
+## Links
+
+- [buildlog.ai](https://buildlog.ai) — View and share buildlogs
+- [Documentation](https://docs.buildlog.ai) — Full documentation
+- [ClawHub](https://clawhub.io/skills/buildlog) — Skill registry listing
+- [GitHub](https://github.com/buildlog/openclaw-skill) — Source code

package/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: buildlog
+description: Record, export, and share your AI coding sessions as replayable buildlogs
+version: 1.0.0
+author: buildlog.ai
+repository: https://github.com/buildlog/openclaw-skill
+homepage: https://buildlog.ai
+---
+
+# Buildlog Skill
+
+Record your OpenClaw coding sessions and share them on buildlog.ai.
+
+## Overview
+
+The buildlog skill captures your AI-assisted coding sessions in real-time, creating replayable recordings that can be shared with others. Perfect for:
+
+- **Tutorials**: Share how you built something step-by-step
+- **Documentation**: Create living documentation of complex implementations
+- **Debugging**: Review sessions to understand what went wrong
+- **Learning**: Study how others approach problems
+
+## Commands
+
+### Recording
+
+- **"Start a buildlog [title]"** — Begin recording a new session
+- **"Stop the buildlog"** — End recording and optionally upload
+- **"Pause the buildlog"** — Temporarily pause recording
+- **"Resume the buildlog"** — Continue a paused recording
+
+### Exporting
+
+- **"Export this session as a buildlog"** — Convert current session to buildlog format
+- **"Export the last [N] messages"** — Export a portion of the session
+
+### Uploading
+
+- **"Upload the buildlog"** — Push to buildlog.ai
+- **"Share the buildlog"** — Upload and get a shareable link
+
+### Annotations
+
+- **"Add a note: [text]"** — Add commentary to the current point
+- **"Mark this as important"** — Flag the current exchange
+- **"Add chapter: [title]"** — Create a chapter marker
+
+### Status
+
+- **"Buildlog status"** — Check recording state
+- **"Show buildlog info"** — Display current recording details
+
+## Configuration
+
+Add to your OpenClaw configuration:
+
+```json
+{
+  "skills": {
+    "buildlog": {
+      "apiKey": "your-api-key",
+      "autoUpload": false,
+      "defaultPublic": true,
+      "includeFileContents": true,
+      "maxFileSizeKb": 100
+    }
+  }
+}
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiKey` | string | — | Your buildlog.ai API key (optional for public uploads) |
+| `autoUpload` | boolean | `false` | Automatically upload when recording stops |
+| `defaultPublic` | boolean | `true` | Make buildlogs public by default |
+| `includeFileContents` | boolean | `true` | Include file content snapshots |
+| `maxFileSizeKb` | number | `100` | Maximum file size to include |
+
+## Events
+
+The skill emits the following events:
+
+- `buildlog:started` — Recording began
+- `buildlog:stopped` — Recording ended
+- `buildlog:paused` — Recording paused
+- `buildlog:resumed` — Recording resumed
+- `buildlog:uploaded` — Buildlog uploaded successfully
+- `buildlog:error` — An error occurred
+
+## Examples
+
+### Basic Recording
+
+```
+You: Start a buildlog "Building a REST API"
+Assistant: 🔴 Recording started: "Building a REST API"
+
+You: Create an Express server with TypeScript
+Assistant: [creates files...]
+
+You: Stop the buildlog
+Assistant: Recording stopped. 12 exchanges captured.
+         Would you like to upload to buildlog.ai?
+```
+
+### Retroactive Export
+
+```
+You: Export this session as a buildlog
+Assistant: Exported 24 exchanges as buildlog.
+         Title: "Untitled Session"
+         Ready to upload?
+```
+
+## Privacy
+
+- Buildlogs can be public or private
+- API keys are never included in exports
+- You control what gets shared
+- Delete buildlogs anytime at buildlog.ai

package/dist/exporter.d.ts

@@ -0,0 +1,110 @@
+import type { Buildlog, BuildlogMetadata, FileChange, TerminalCommand } from './types.js';
+export interface SessionMessage {
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+    timestamp?: number;
+    toolCalls?: Array<{
+        name: string;
+        arguments: Record<string, unknown>;
+        result?: unknown;
+    }>;
+    attachments?: Array<{
+        name: string;
+        content: string;
+        type?: string;
+    }>;
+}
+export interface SessionHistory {
+    messages: SessionMessage[];
+    fileChanges?: FileChange[];
+    terminalCommands?: TerminalCommand[];
+    metadata?: Partial<BuildlogMetadata>;
+}
+export interface ExportOptions {
+    title?: string;
+    description?: string;
+    tags?: string[];
+    includeSystemMessages?: boolean;
+    includeFileContents?: boolean;
+    maxFileSizeKb?: number;
+    lastN?: number;
+    author?: string;
+}
+/**
+ * BuildlogExporter - Convert session history to buildlog format
+ *
+ * Supports retroactive export from session_history
+ */
+export declare class BuildlogExporter {
+    private options;
+    constructor(options?: Partial<ExportOptions>);
+    /**
+     * Export a session history to buildlog format
+     */
+    export(history: SessionHistory): Buildlog;
+    /**
+     * Export only the last N messages
+     */
+    exportLastN(history: SessionHistory, n: number): Buildlog;
+    /**
+     * Export a range of messages
+     */
+    exportRange(history: SessionHistory, start: number, end: number): Buildlog;
+    /**
+     * Merge file changes and terminal commands into the timeline
+     */
+    private convertToEntries;
+    /**
+     * Convert a session message to a buildlog entry
+     */
+    private messageToEntry;
+    /**
+     * Convert a file change to a buildlog entry
+     */
+    private fileChangeToEntry;
+    /**
+     * Convert a terminal command to a buildlog entry
+     */
+    private terminalToEntry;
+    /**
+     * Filter messages based on options
+     */
+    private filterMessages;
+    /**
+     * Build metadata for the buildlog
+     */
+    private buildMetadata;
+    /**
+     * Try to infer a title from the session content
+     */
+    private inferTitle;
+    /**
+     * Try to infer a description from the session
+     */
+    private inferDescription;
+    /**
+     * Try to infer tags from file extensions and content
+     */
+    private inferTags;
+    /**
+     * Detect natural chapter breaks in the content
+     */
+    private detectChapters;
+    /**
+     * Extract a chapter title from a message
+     */
+    private extractChapterTitle;
+    /**
+     * Truncate content to max size
+     */
+    private truncateContent;
+    /**
+     * Generate a unique ID
+     */
+    private generateId;
+}
+/**
+ * Convenience function to export a session
+ */
+export declare function exportSession(history: SessionHistory, options?: ExportOptions): Buildlog;
+//# sourceMappingURL=exporter.d.ts.map

package/dist/exporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exporter.d.ts","sourceRoot":"","sources":["../src/exporter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EAER,gBAAgB,EAChB,UAAU,EACV,eAAe,EAChB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,QAAQ,CAAC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,KAAK,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACnC,MAAM,CAAC,EAAE,OAAO,CAAC;KAClB,CAAC,CAAC;IACH,WAAW,CAAC,EAAE,KAAK,CAAC;QAClB,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC,CAAC;CACJ;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC;IAC3B,gBAAgB,CAAC,EAAE,eAAe,EAAE,CAAC;IACrC,QAAQ,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAQD;;;;GAIG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,OAAO,CAAgB;gBAEnB,OAAO,GAAE,OAAO,CAAC,aAAa,CAAM;IAIhD;;OAEG;IACH,MAAM,CAAC,OAAO,EAAE,cAAc,GAAG,QAAQ;IAazC;;OAEG;IACH,WAAW,CAAC,OAAO,EAAE,cAAc,EAAE,CAAC,EAAE,MAAM,GAAG,QAAQ;IAQzD;;OAEG;IACH,WAAW,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,QAAQ;IAQ1E;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAiExB;;OAEG;IACH,OAAO,CAAC,cAAc;IA4BtB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAsBzB;;OAEG;IACH,OAAO,CAAC,eAAe;IAWvB;;OAEG;IACH,OAAO,CAAC,cAAc;IAgBtB;;OAEG;IACH,OAAO,CAAC,aAAa;IAuBrB;;OAEG;IACH,OAAO,CAAC,UAAU;IAqBlB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAaxB;;OAEG;IACH,OAAO,CAAC,SAAS;IA+CjB;;OAEG;IACH,OAAO,CAAC,cAAc;IA8BtB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAQ3B;;OAEG;IACH,OAAO,CAAC,eAAe;IAQvB;;OAEG;IACH,OAAO,CAAC,UAAU;CAGnB;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,cAAc,EACvB,OAAO,GAAE,aAAkB,GAC1B,QAAQ,CAGV"}