sloss-cli 1.0.0 → 1.2.0

package/README.md

@@ -1,6 +1,6 @@
 # sloss-cli
 
-Command-line interface for [Sloss](https://github.com/aualdrich/sloss) — a self-hosted IPA/APK distribution server inspired by Diawi.
+Command-line interface for [Sloss](https://github.com/aualdrich/sloss) — a self-hosted build distribution server for Expo apps. Supports iOS and Android.
 
 ## Install
 
@@ -8,38 +8,170 @@ Command-line interface for [Sloss](https://github.com/aualdrich/sloss) — a sel
 npm install -g sloss-cli
 ```
 
-## Quick Start
+Or as a project dependency:
+
+```bash
+npm install --save-dev sloss-cli
+# or
+bun add --dev sloss-cli
+```
+
+## Setup
+
+### 1. Create a Sloss account
+
+Sign up at your team's Sloss instance (e.g. `https://sloss.example.com/signup`). After signing up, you'll receive an API key on the onboarding page. You can also find it under **Settings → API Key**.
+
+### 2. Authenticate the CLI
 
 ```bash
-# Authenticate (saves API key to ~/.config/sloss/credentials.json)
 sloss login
+```
+
+This prompts for your email and password, fetches your API key, and saves it to `~/.config/sloss/credentials.json`. You only need to do this once per machine.
+
+Alternatively, set the `SLOSS_API_KEY` environment variable or pass `--api-key` to any command.
+
+### 3. Add `.sloss.json` to your Expo project
+
+Create a `.sloss.json` file in your Expo project root (next to `app.json`):
+
+```json
+{
+  "type": "expo",
+  "app_name": "MyApp",
+  "bundle_id": "com.mycompany.myapp",
+  "version_file": "app.version.json",
+  "profiles": {
+    "development": {
+      "bundle_id_suffix": ".dev"
+    },
+    "preview": {
+      "bundle_id_suffix": ".preview"
+    },
+    "production": {
+      "bundle_id_suffix": ""
+    }
+  }
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `type` | Always `"expo"` |
+| `app_name` | Display name for the build on Sloss |
+| `bundle_id` | Base bundle identifier |
+| `version_file` | Path to a JSON file containing `version` and `buildNumber` (relative to project root) |
+| `profiles` | Build profile config — `bundle_id_suffix` is appended to `bundle_id` per profile |
+
+### 4. Create `app.version.json`
+
+Sloss reads version info from a dedicated file so the build agent can bump versions independently:
+
+```json
+{
+  "version": "1.0.0",
+  "buildNumber": "1"
+}
+```
+
+Reference this in your `app.json` / `app.config.js` so Expo picks it up:
+
+```js
+// app.config.js
+const version = require('./app.version.json');
+
+module.exports = {
+  expo: {
+    version: version.version,
+    ios: { buildNumber: String(version.buildNumber) },
+    android: { versionCode: parseInt(version.buildNumber, 10) },
+    // ... rest of your config
+  },
+};
+```
+
+## Usage
+
+### Queue a build
+
+From your Expo project directory:
+
+```bash
+# iOS development build (default)
+sloss build
+
+# Android preview build
+sloss build --platform android --profile preview
+
+# Production build with minor version bump
+sloss build --profile production --bump minor
+```
+
+The CLI packages your project via `git archive`, uploads it to Sloss, and a build agent picks it up. You'll get a link to the build page with live logs.
+
+#### Build options
 
-# List recent builds
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--platform <platform>` | `ios` | `ios` or `android` |
+| `--profile <profile>` | `development` | `development`, `preview`, or `production` |
+| `--bump <type>` | `patch` | Version bump for production builds: `patch`, `minor`, or `major` |
+| `--dir <path>` | `.` | Project directory (if not running from project root) |
+
+### List builds
+
+```bash
 sloss list
+sloss list --limit 20
+```
+
+### Get build details
+
+```bash
+sloss info <build-id>
+```
+
+### Upload a pre-built artifact
+
+If you already have an IPA or APK (e.g. from a local build):
 
+```bash
 # Upload an IPA
-sloss upload path/to/App.ipa --platform ios --profile preview
+sloss upload ./build/MyApp.ipa --platform ios --profile preview
 
 # Upload an APK
-sloss upload path/to/app.apk --platform android --profile development
+sloss upload ./build/app-release.apk --platform android --profile production
+```
 
-# Get build details
-sloss info <build-id>
+#### Upload options
 
-# Delete a build
+| Flag | Description |
+|------|-------------|
+| `--platform <platform>` | **Required.** `ios` or `android` |
+| `--profile <profile>` | Build profile: `development`, `preview`, or `production` |
+| `--app-name <name>` | App display name |
+| `--version <version>` | Version string |
+| `--build-number <number>` | Build number |
+
+### Delete a build
+
+```bash
 sloss delete <build-id>
 ```
 
 ## Authentication
 
 API key resolution order (highest → lowest priority):
+
 1. `--api-key` CLI flag
 2. `SLOSS_API_KEY` environment variable
 3. `~/.config/sloss/credentials.json` (saved by `sloss login`)
 
 ## Server URL
 
-URL resolution order:
+URL resolution order (highest → lowest priority):
+
 1. `--url` CLI flag
 2. `SLOSS_URL` environment variable
 3. `~/.config/sloss/credentials.json`
@@ -47,14 +179,54 @@ URL resolution order:
 
 ## Global Options
 
+| Flag | Description |
+|------|-------------|
+| `--api-key <key>` | Override API key |
+| `--url <url>` | Override server URL |
+| `--json` | Output as JSON |
+| `--version` | Show CLI version |
+| `--help` | Show help |
+
+## How It Works
+
+1. `sloss build` reads `.sloss.json` from your project root
+2. Your committed source is packaged into a tarball via `git archive`
+3. The tarball is uploaded to your Sloss server
+4. A build agent picks up the job and builds it locally using Xcode (iOS) or Gradle (Android)
+5. The finished IPA/APK is uploaded back to Sloss
+6. You get a build page with install links and QR codes for on-device installation
+
+## OpenClaw Skill
+
+This package includes an [OpenClaw](https://openclaw.ai) skill so your AI agent can use the Sloss CLI. After installing `sloss-cli`, add the skill directory to your OpenClaw config:
+
+```json5
+// ~/.openclaw/openclaw.json
+{
+  skills: {
+    load: {
+      extraDirs: ["./node_modules/sloss-cli/skills"]
+    }
+  }
+}
+```
+
+Or copy the skill into your workspace:
+
+```bash
+cp -r ./node_modules/sloss-cli/skills/sloss <workspace>/skills/sloss
 ```
---api-key <key>   Override API key
---url <url>       Override server URL
---json            Output as JSON
---version         Show version
---help            Show help
+
+The skill is also available on [ClawHub](https://clawhub.com):
+
+```bash
+clawhub install sloss
 ```
 
+## Related
+
+- **[Sloss Server](https://github.com/aualdrich/sloss)** — The self-hosted distribution server
+
 ## License
 
 MIT

package/bin/sloss.js

@@ -11,6 +11,7 @@ import { listCommand } from '../src/commands/list.js';
 import { uploadCommand } from '../src/commands/upload.js';
 import { infoCommand } from '../src/commands/info.js';
 import { deleteCommand } from '../src/commands/delete.js';
+import { buildCommand } from '../src/commands/build.js';
 
 const program = new Command();
 
@@ -100,4 +101,22 @@ program
     }
   });
 
+// Build command
+program
+  .command('build')
+  .description('Queue a build via the Sloss build agent')
+  .option('--platform <platform>', 'Platform (ios or android)', 'ios')
+  .option('--profile <profile>', 'Build profile (development, preview, production)', 'development')
+  .option('--bump <type>', 'Version bump type for production (patch, minor, major)', 'patch')
+  .option('--dir <path>', 'Project directory (default: current directory)', '.')
+  .action(async (options) => {
+    try {
+      const config = resolveConfig(program.opts());
+      await buildCommand(options, config);
+    } catch (error) {
+      console.error(`Error: ${error.message}`);
+      process.exit(1);
+    }
+  });
+
 program.parse();

package/package.json

@@ -1,22 +1,33 @@
 {
   "name": "sloss-cli",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "CLI for Sloss — a self-hosted IPA/APK distribution server",
   "type": "module",
   "bin": {
-    "sloss": "./bin/sloss.js"
+    "sloss": "bin/sloss.js"
   },
   "files": [
     "bin/",
     "src/",
+    "skills/",
     "README.md"
   ],
-  "keywords": ["sloss", "ios", "android", "ipa", "apk", "build", "distribution", "testflight", "diawi"],
+  "keywords": [
+    "sloss",
+    "ios",
+    "android",
+    "ipa",
+    "apk",
+    "build",
+    "distribution",
+    "testflight",
+    "diawi"
+  ],
   "author": "Front Porch Software",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/aualdrich/sloss-cli.git"
+    "url": "git+https://github.com/aualdrich/sloss-cli.git"
   },
   "engines": {
     "node": ">=18.0.0"

package/skills/sloss/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: sloss
+description: "Build, distribute, and manage Expo app builds (iOS & Android) via the Sloss CLI. Use when queuing builds, listing builds, uploading artifacts, checking build status, or managing the Sloss build server."
+homepage: https://github.com/aualdrich/sloss-cli
+metadata: {"openclaw":{"emoji":"🏭","requires":{"bins":["sloss"]},"install":[{"id":"npm","kind":"node","package":"sloss-cli","bins":["sloss"],"label":"Install Sloss CLI (npm)"}]}}
+---
+
+# Sloss — Build Distribution for Expo Apps
+
+Sloss is a self-hosted build distribution server for Expo apps (iOS & Android). The `sloss` CLI queues builds, uploads artifacts, and manages builds from the terminal.
+
+## Prerequisites
+
+1. `sloss` CLI installed (`sloss --version` to verify)
+2. A Sloss server instance (self-hosted)
+3. An account on the Sloss server with an API key
+
+## Authentication
+
+```bash
+# Login once — saves API key to ~/.config/sloss/credentials.json
+sloss login
+```
+
+API key resolution (highest → lowest priority):
+1. `--api-key` flag
+2. `SLOSS_API_KEY` environment variable
+3. `~/.config/sloss/credentials.json`
+
+Server URL resolution (highest → lowest priority):
+1. `--url` flag
+2. `SLOSS_URL` environment variable
+3. `~/.config/sloss/credentials.json`
+
+## Queue a Build
+
+Run from the Expo project root (requires `.sloss.json` config file):
+
+```bash
+# iOS development build (default)
+sloss build
+
+# Android preview build
+sloss build --platform android --profile preview
+
+# Production build with minor version bump
+sloss build --profile production --bump minor
+
+# Build from a different directory
+sloss build --dir /path/to/expo/project
+```
+
+### Build options
+
+| Flag | Default | Values |
+|------|---------|--------|
+| `--platform` | `ios` | `ios`, `android` |
+| `--profile` | `development` | `development`, `preview`, `production` |
+| `--bump` | `patch` | `patch`, `minor`, `major` |
+| `--dir` | `.` | Path to project root |
+
+### Build flow
+
+1. CLI reads `.sloss.json` from the project root
+2. Source is packaged via `git archive` (respects `.gitignore`)
+3. Tarball is uploaded to the Sloss server
+4. A build agent picks up the job and builds locally (Xcode for iOS, Gradle for Android)
+5. The finished IPA/APK is uploaded back to Sloss
+6. A build page with live logs and install links is available on the server
+
+## List Builds
+
+```bash
+sloss list
+sloss list --limit 20
+```
+
+## Build Details
+
+```bash
+sloss info <build-id>
+```
+
+## Upload a Pre-Built Artifact
+
+If you already have an IPA or APK:
+
+```bash
+# Upload an IPA
+sloss upload ./App.ipa --platform ios --profile preview
+
+# Upload an APK
+sloss upload ./app.apk --platform android --profile development
+```
+
+Upload options:
+
+| Flag | Description |
+|------|-------------|
+| `--platform` | **Required.** `ios` or `android` |
+| `--profile` | `development`, `preview`, or `production` |
+| `--app-name` | App display name |
+| `--version` | Version string |
+| `--build-number` | Build number |
+
+## Delete a Build
+
+```bash
+sloss delete <build-id>
+```
+
+## Project Configuration
+
+### `.sloss.json`
+
+Place in the Expo project root:
+
+```json
+{
+  "type": "expo",
+  "app_name": "MyApp",
+  "bundle_id": "com.example.myapp",
+  "version_file": "app.version.json",
+  "profiles": {
+    "development": { "bundle_id_suffix": ".dev" },
+    "preview": { "bundle_id_suffix": ".preview" },
+    "production": { "bundle_id_suffix": "" }
+  }
+}
+```
+
+### `app.version.json`
+
+```json
+{
+  "version": "1.0.0",
+  "buildNumber": "1"
+}
+```
+
+Reference this in `app.config.js` so Expo picks it up:
+
+```js
+const version = require('./app.version.json');
+module.exports = {
+  expo: {
+    version: version.version,
+    ios: { buildNumber: String(version.buildNumber) },
+    android: { versionCode: parseInt(version.buildNumber, 10) },
+  },
+};
+```
+
+## Global Flags
+
+| Flag | Description |
+|------|-------------|
+| `--api-key <key>` | Override API key |
+| `--url <url>` | Override server URL |
+| `--json` | JSON output |
+| `--version` | Show CLI version |
+| `--help` | Show help |
+
+## Output Formats
+
+All commands support `--json` for structured JSON output:
+
+```bash
+sloss list --json
+sloss info <build-id> --json
+```

package/src/client.js

@@ -61,6 +61,33 @@ export class SlossClient {
     return await this.request('DELETE', `/api/uploads/${id}`);
   }
 
+  async startBuild(tarballPath, metadata = {}) {
+    const fs = await import('fs/promises');
+    const path = await import('path');
+
+    const fileBuffer = await fs.readFile(tarballPath);
+    const fileName = path.basename(tarballPath);
+
+    const formData = new FormData();
+    const blob = new Blob([fileBuffer]);
+    formData.append('tarball', blob, fileName);
+
+    // Add build metadata
+    if (metadata.profile) formData.append('profile', metadata.profile);
+    if (metadata.platform) formData.append('platform', metadata.platform);
+    if (metadata.bump) formData.append('bump', metadata.bump);
+    if (metadata.appName) formData.append('app_name', metadata.appName);
+    if (metadata.bundleId) formData.append('bundle_id', metadata.bundleId);
+    if (metadata.version) formData.append('version', metadata.version);
+    if (metadata.buildNumber) formData.append('build_number', metadata.buildNumber);
+
+    return await this.request('POST', '/api/builds/start', formData);
+  }
+
+  async getBuild(id) {
+    return await this.request('GET', `/api/builds/${id}`);
+  }
+
   async uploadFile(filePath, platform, metadata = {}) {
     const fs = await import('fs/promises');
     const path = await import('path');

package/src/commands/build.js

@@ -0,0 +1,115 @@
+/**
+ * Build command - Tar up the project and queue a remote build via Sloss agent
+ */
+
+import { SlossClient } from '../client.js';
+import { existsSync, readFileSync } from 'fs';
+import { resolve, basename } from 'path';
+import { execSync } from 'child_process';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { formatBuild } from '../format.js';
+
+export async function buildCommand(options, config) {
+  const platform = (options.platform || 'ios').toLowerCase();
+  const profile = (options.profile || 'development').toLowerCase();
+  const bump = options.bump || 'patch';
+  const projectDir = resolve(options.dir || '.');
+
+  // Validate platform
+  if (!['ios', 'android'].includes(platform)) {
+    throw new Error('Platform must be "ios" or "android"');
+  }
+
+  // Validate profile
+  if (!['development', 'preview', 'production'].includes(profile)) {
+    throw new Error('Profile must be "development", "preview", or "production"');
+  }
+
+  // Check for .sloss.json
+  const slossConfigPath = join(projectDir, '.sloss.json');
+  if (!existsSync(slossConfigPath)) {
+    throw new Error(
+      `.sloss.json not found in ${projectDir}\n` +
+      '  Create a .sloss.json config file in your project root.\n' +
+      '  See: https://github.com/aualdrich/sloss#build-agent'
+    );
+  }
+
+  // Read config for display
+  const slossConfig = JSON.parse(readFileSync(slossConfigPath, 'utf8'));
+
+  console.log('╔══════════════════════════════════════════╗');
+  console.log('║ SLOSS BUILD                              ║');
+  console.log('╠══════════════════════════════════════════╣');
+  console.log(`║ app       : ${(slossConfig.app_name || '—').padEnd(27)} ║`);
+  console.log(`║ platform  : ${platform.padEnd(27)} ║`);
+  console.log(`║ profile   : ${profile.padEnd(27)} ║`);
+  console.log(`║ bump      : ${bump.padEnd(27)} ║`);
+  console.log(`║ server    : ${config.baseUrl.padEnd(27)} ║`);
+  console.log('╚══════════════════════════════════════════╝');
+  console.log('');
+
+  // Create tarball
+  console.log('📦 Packaging project...');
+  const tarballPath = join(tmpdir(), `sloss-build-${Date.now()}.tar.gz`);
+
+  // Use git archive if in a git repo (respects .gitignore), otherwise tar with excludes
+  let tarCmd;
+  try {
+    execSync('git rev-parse --git-dir', { cwd: projectDir, stdio: 'pipe' });
+    // git archive from the repo root, only including the project subdir if needed
+    const gitRoot = execSync('git rev-parse --show-toplevel', { cwd: projectDir, encoding: 'utf8' }).trim();
+    const relPath = projectDir.replace(gitRoot, '').replace(/^\//, '');
+
+    if (relPath) {
+      // Project is in a subdirectory — include only that dir
+      tarCmd = `cd "${gitRoot}" && git archive --format=tar HEAD -- "${relPath}" | gzip > "${tarballPath}"`;
+    } else {
+      tarCmd = `cd "${projectDir}" && git archive --format=tar.gz HEAD > "${tarballPath}"`;
+    }
+  } catch {
+    // Not a git repo — fall back to tar with common excludes
+    tarCmd = `cd "${projectDir}" && tar czf "${tarballPath}" --exclude=node_modules --exclude=.git --exclude=ios/build --exclude=android/build .`;
+  }
+
+  execSync(tarCmd, { stdio: 'pipe' });
+
+  // Get tarball size for display
+  const { statSync } = await import('fs');
+  const tarSize = statSync(tarballPath).size;
+  const sizeMB = (tarSize / (1024 * 1024)).toFixed(1);
+  console.log(`   → ${sizeMB} MB`);
+
+  // Read version info from .sloss.json's version_file
+  let version = '';
+  let buildNumber = '';
+  if (slossConfig.version_file) {
+    const versionFilePath = join(projectDir, slossConfig.version_file);
+    if (existsSync(versionFilePath)) {
+      const versionData = JSON.parse(readFileSync(versionFilePath, 'utf8'));
+      version = versionData.version || '';
+      buildNumber = versionData.buildNumber || '';
+    }
+  }
+
+  // Upload tarball to start build
+  console.log('🚀 Queuing build...');
+  const client = new SlossClient(config.baseUrl, config.apiKey);
+  const result = await client.startBuild(tarballPath, {
+    profile,
+    platform,
+    bump,
+    appName: slossConfig.app_name || '',
+    bundleId: slossConfig.bundle_id || '',
+    version,
+    buildNumber,
+  });
+
+  // Clean up tarball
+  const { unlinkSync } = await import('fs');
+  try { unlinkSync(tarballPath); } catch { /* ignore */ }
+
+  console.log('');
+  console.log(formatBuild(result, config.jsonMode));
+}

package/src/format.js

@@ -82,6 +82,22 @@ export function formatUpload(result, jsonMode = false) {
   return lines.join('\n');
 }
 
+export function formatBuild(result, jsonMode = false) {
+  if (jsonMode) {
+    return JSON.stringify(result, null, 2);
+  }
+
+  const lines = [
+    '✅ Build queued!',
+    '',
+    `Build ID:   ${result.id}`,
+    `Status:     ${result.status || 'queued'}`,
+    `Page URL:   ${result.page_url}`,
+  ];
+
+  return lines.join('\n');
+}
+
 export function formatDelete(jsonMode = false) {
   if (jsonMode) {
     return JSON.stringify({ ok: true }, null, 2);