@tloncorp/tlon-skill 0.1.0

package/README.md

@@ -0,0 +1,74 @@
+# Tlon Skill
+
+A CLI tool for interacting with Tlon/Urbit APIs.
+
+## Installation
+
+**npm:**
+```bash
+npm install @tloncorp/tlon-skill
+```
+
+**Direct download (no Node required):**
+```bash
+# macOS ARM64
+curl -L https://registry.npmjs.org/@tloncorp/tlon-skill-darwin-arm64/-/tlon-skill-darwin-arm64-0.1.0.tgz | tar -xz
+mv package/tlon /usr/local/bin/
+
+# macOS x64
+curl -L https://registry.npmjs.org/@tloncorp/tlon-skill-darwin-x64/-/tlon-skill-darwin-x64-0.1.0.tgz | tar -xz
+
+# Linux x64
+curl -L https://registry.npmjs.org/@tloncorp/tlon-skill-linux-x64/-/tlon-skill-linux-x64-0.1.0.tgz | tar -xz
+```
+
+## Configuration
+
+```bash
+export URBIT_URL="https://your-ship.tlon.network"
+export URBIT_SHIP="~your-ship"
+export URBIT_CODE="sampel-ticlyt-migfun-falmel"
+```
+
+## Usage
+
+```bash
+# List your groups
+tlon channels groups
+
+# Get recent mentions
+tlon activity mentions --limit 10
+
+# Fetch DM history
+tlon messages dm ~sampel-palnet --limit 20
+
+# Update your profile
+tlon contacts update-profile --nickname "My Name"
+
+# Create a group
+tlon groups create "My Group" --description "A cool group"
+```
+
+## Features
+
+- **Activity**: Mentions, replies, unreads
+- **Channels**: List DMs, group DMs, subscribed groups
+- **Contacts**: List, get, update profiles
+- **Groups**: Create, join, invite, roles, privacy
+- **Messages**: History, search
+- **DMs**: Send, react, accept/decline
+- **Posts**: React, delete
+- **Notebook**: Post to diary channels
+- **Settings**: Hot-reload plugin config via settings-store
+
+## Documentation
+
+See [SKILL.md](SKILL.md) for full command reference.
+
+## For Hosted Deployments
+
+If you're running this in a hosted/K8s environment with additional features (workspace files, settings-store, click commands), see [@tloncorp/tlonbot](https://github.com/tloncorp/tlonbot).
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: tlon
+description: Interact with Tlon/Urbit API. Use for contacts (get/update profiles), listing channels/groups, fetching message history, posting to channels, sending DMs, and group management.
+---
+
+# Tlon Skill
+
+Use the `tlon` command for all Tlon operations.
+
+## Installation
+
+**npm (Node.js):**
+```bash
+npm install @tloncorp/tlon-skill
+tlon channels groups
+```
+
+**Direct binary (no Node required):**
+```bash
+curl -L https://registry.npmjs.org/@tloncorp/tlon-skill-darwin-arm64/-/tlon-skill-darwin-arm64-0.1.0.tgz | tar -xz
+./package/tlon channels groups
+```
+
+Replace `darwin-arm64` with `darwin-x64` or `linux-x64` as needed.
+
+## Configuration
+
+Set environment variables:
+```bash
+export URBIT_URL="https://your-ship.tlon.network"
+export URBIT_SHIP="~your-ship"
+export URBIT_CODE="sampel-ticlyt-migfun-falmel"
+```
+
+## Commands
+
+### Activity
+
+Check recent notifications and unread counts.
+
+```bash
+tlon activity mentions --limit 10   # Recent mentions (max 25)
+tlon activity replies --limit 10    # Recent replies (max 25)
+tlon activity all --limit 10        # All recent activity (max 25)
+tlon activity unreads               # Unread counts per channel
+```
+
+### Channels
+
+List and manage channels.
+
+```bash
+tlon channels dms                                          # List DM contacts
+tlon channels group-dms                                    # List group DMs (clubs)
+tlon channels groups                                       # List subscribed groups
+tlon channels all                                          # List everything
+tlon channels info chat/~host/slug                         # Get channel details
+tlon channels update chat/~host/slug --title "New Title"   # Update metadata
+tlon channels delete chat/~host/slug                       # Delete a channel
+```
+
+### Contacts
+
+Manage contacts and profiles.
+
+```bash
+tlon contacts list                                   # List all contacts
+tlon contacts self                                   # Get your own profile
+tlon contacts get ~sampel                            # Get a contact's profile
+tlon contacts sync ~ship1 ~ship2                     # Fetch/sync profiles
+tlon contacts add ~sampel                            # Add a contact
+tlon contacts remove ~sampel                         # Remove a contact
+tlon contacts update-profile --nickname "My Name"    # Update your profile
+```
+
+Options: `--nickname`, `--bio`, `--status`, `--avatar`, `--cover`
+
+### Groups
+
+Full group management.
+
+```bash
+# Basics
+tlon groups list                                         # List your groups
+tlon groups info ~host/slug                              # Get group details
+tlon groups create "Name" [--description "..."]          # Create a group
+tlon groups join ~host/slug                              # Join a group
+tlon groups leave ~host/slug                             # Leave a group
+tlon groups delete ~host/slug                            # Delete (host only)
+tlon groups update ~host/slug --title "..." [--description "..."]
+
+# Members
+tlon groups invite ~host/slug ~ship1 ~ship2              # Invite members
+tlon groups kick ~host/slug ~ship1                       # Kick members
+tlon groups ban ~host/slug ~ship1                        # Ban members
+tlon groups unban ~host/slug ~ship1                      # Unban members
+tlon groups accept-join ~host/slug ~ship1                # Accept join request
+tlon groups reject-join ~host/slug ~ship1                # Reject join request
+tlon groups set-privacy ~host/slug public|private|secret # Set privacy
+
+# Roles
+tlon groups add-role ~host/slug role-id --title "..."    # Create a role
+tlon groups delete-role ~host/slug role-id               # Delete a role
+tlon groups update-role ~host/slug role-id --title "..." # Update a role
+tlon groups assign-role ~host/slug role-id ~ship1        # Assign role
+tlon groups remove-role ~host/slug role-id ~ship1        # Remove role
+
+# Channels
+tlon groups add-channel ~host/slug "Name" [--kind chat|diary|heap]
+```
+
+Group format: `~host-ship/group-slug`
+
+### Messages
+
+Read and search message history.
+
+```bash
+tlon messages dm ~sampel --limit 20                      # DM history (max 50)
+tlon messages channel chat/~host/slug --limit 20         # Channel history (max 50)
+tlon messages search "query" --channel chat/~host/slug   # Search messages
+```
+
+Options: `--limit N`, `--resolve-cites`
+
+### DMs
+
+Manage direct messages.
+
+```bash
+# Group DMs (clubs)
+tlon dms send <club-id> "hello"                          # Send to group DM
+tlon dms reply <club-id> ~author/170.141... "reply"      # Reply in group DM
+
+# Management
+tlon dms react ~sampel ~author/170.141... "👍"           # React to a DM
+tlon dms unreact ~sampel ~author/170.141...              # Remove reaction
+tlon dms delete ~sampel ~author/170.141...               # Delete a DM
+tlon dms accept ~sampel                                  # Accept DM invite
+tlon dms decline ~sampel                                 # Decline DM invite
+```
+
+### Posts
+
+Manage channel posts.
+
+```bash
+tlon posts react chat/~host/slug 170.141... "👍"         # React to a post
+tlon posts unreact chat/~host/slug 170.141...            # Remove reaction
+tlon posts delete chat/~host/slug 170.141...             # Delete a post
+```
+
+### Notebook
+
+Post to diary/notebook channels.
+
+```bash
+tlon notebook diary/~host/slug "Title"                   # Post with no body
+tlon notebook diary/~host/slug "Title" --content file.md # Post from file
+tlon notebook diary/~host/slug "Title" --image <url>     # Post with image
+```
+
+### Settings (OpenClaw)
+
+Manage OpenClaw's Tlon plugin config via Urbit settings-store. Changes apply immediately without gateway restart.
+
+```bash
+tlon settings get                                        # Show all settings
+tlon settings set <key> <json-value>                     # Set a value
+tlon settings delete <key>                               # Delete a setting
+
+# DM allowlist
+tlon settings allow-dm ~ship                             # Add to DM allowlist
+tlon settings remove-dm ~ship                            # Remove from allowlist
+
+# Channel controls
+tlon settings allow-channel chat/~host/slug              # Add to watch list
+tlon settings remove-channel chat/~host/slug             # Remove from watch list
+tlon settings open-channel chat/~host/slug               # Set channel to open
+tlon settings restrict-channel chat/~host/slug [~ship1]  # Set restricted
+
+# Authorization
+tlon settings authorize-ship ~ship                       # Add to default auth
+tlon settings deauthorize-ship ~ship                     # Remove from auth
+```
+
+## Notes
+
+- Ship names should include `~` prefix
+- Post IDs are @ud format with dots (e.g. `170.141.184.507...`)
+- DM post IDs include author prefix (`~ship/170.141...`)
+- Channel nests: `<kind>/~<host>/<name>` (chat, diary, or heap)
+
+## Limits
+
+- Activity: max 25 items
+- Messages: max 50 items

package/bin/tlon-run.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+
+// Map of platform+arch to package name
+const PLATFORMS = {
+  "darwin-arm64": "@tloncorp/tlon-skill-darwin-arm64",
+  "darwin-x64": "@tloncorp/tlon-skill-darwin-x64",
+  "linux-x64": "@tloncorp/tlon-skill-linux-x64",
+};
+
+function getBinaryPath() {
+  const platform = process.platform;
+  const arch = process.arch;
+  const key = `${platform}-${arch}`;
+
+  // Check for local binary (dev mode)
+  const localBinary = join(__dirname, "tlon");
+  if (existsSync(localBinary)) {
+    return localBinary;
+  }
+
+  const packageName = PLATFORMS[key];
+  if (!packageName) {
+    console.error(`Unsupported platform: ${platform}-${arch}`);
+    console.error(`Supported platforms: ${Object.keys(PLATFORMS).join(", ")}`);
+    process.exit(1);
+  }
+
+  try {
+    // Try to resolve the platform-specific package
+    const packagePath = require.resolve(`${packageName}/package.json`);
+    const binaryPath = join(dirname(packagePath), "tlon-run");
+    
+    if (!existsSync(binaryPath)) {
+      throw new Error(`Binary not found at ${binaryPath}`);
+    }
+    
+    return binaryPath;
+  } catch (err) {
+    console.error(`Failed to find binary for ${platform}-${arch}`);
+    console.error(`Package ${packageName} may not be installed.`);
+    console.error(`Try: npm install ${packageName}`);
+    process.exit(1);
+  }
+}
+
+const binaryPath = getBinaryPath();
+const args = process.argv.slice(2);
+
+const result = spawnSync(binaryPath, args, {
+  stdio: "inherit",
+  env: process.env,
+});
+
+if (result.error) {
+  console.error(`Failed to run binary: ${result.error.message}`);
+  process.exit(1);
+}
+
+process.exit(result.status ?? 1);

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@tloncorp/tlon-skill",
+  "version": "0.1.0",
+  "description": "Tlon/Urbit skill for OpenClaw agents",
+  "type": "module",
+  "bin": {
+    "tlon-run": "./bin/tlon-run.js"
+  },
+  "files": [
+    "bin/",
+    "SKILL.md"
+  ],
+  "scripts": {
+    "build": "bun build scripts/main.ts --compile --outfile dist/tlon-run",
+    "build:all": "node scripts/build-all.js",
+    "dev:link": "bun run build:all && cp \"npm/$(node -e 'console.log(process.platform + \"-\" + process.arch)')/tlon\" bin/",
+    "test": "bun test"
+  },
+  "optionalDependencies": {
+    "@tloncorp/tlon-skill-darwin-arm64": "0.1.0",
+    "@tloncorp/tlon-skill-darwin-x64": "0.1.0",
+    "@tloncorp/tlon-skill-linux-x64": "0.1.0"
+  },
+  "dependencies": {
+    "@tloncorp/api": "git+https://github.com/tloncorp/api-beta.git#main",
+    "@urbit/aura": "^3.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tloncorp/tlon-skill.git"
+  },
+  "license": "MIT"
+}