hypha-cli 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,141 @@
+# hypha-cli
+
+Command-line tool for managing [Hypha Cloud](https://hypha.aicell.io) resources — workspaces, server apps, and artifacts.
+
+## Installation
+
+```bash
+npm install -g hypha-cli
+```
+
+Requires **Node.js >= 22** (for native WebSocket support).
+
+## Quick Start
+
+```bash
+# Login (opens browser for OAuth)
+hypha login
+
+# Check workspace info
+hypha info
+
+# List services
+hypha services
+
+# List artifacts
+hypha artifacts ls
+
+# Upload a file
+hypha artifacts cp ./data.csv my-model:data/train.csv
+```
+
+## Configuration
+
+Credentials are stored in `~/.hypha/.env`:
+
+```
+HYPHA_SERVER_URL=https://hypha.aicell.io
+HYPHA_TOKEN=<your-token>
+HYPHA_WORKSPACE=<your-workspace>
+```
+
+You can also set these as environment variables, or use global flags:
+
+```bash
+hypha --server https://hypha.aicell.io --workspace my-ws artifacts ls
+```
+
+## Commands
+
+### Workspace Management
+
+```bash
+hypha login [server-url]                    # OAuth login (opens browser)
+hypha token [--expires-in N] [--permission P] [--workspace W] [--json]
+hypha services [--type T] [--include-unlisted] [--json]
+hypha info [--json]
+```
+
+### Apps — Server App Lifecycle
+
+Manage server app definitions (like Docker images) and running instances (like containers).
+
+```bash
+hypha apps list [--json]                    # List installed app definitions
+hypha apps info <app-id> [--json]           # Show app details
+hypha apps install <source> [--id ID] [--manifest P] [--files D...] [--overwrite]
+hypha apps uninstall <app-id>               # Remove app definition
+hypha apps start <app-id> [--timeout N] [--wait]  # Start instance
+hypha apps stop <id> [--all]                # Stop instance(s)
+hypha apps ps [--json]                      # List running instances
+hypha apps logs <instance-id> [--tail N] [--type T]
+```
+
+**Aliases**: `ls` = `list`, `rm` = `uninstall`
+
+`stop` accepts either an instance ID or an app ID. With `--all`, stops all instances of that app.
+
+### Artifacts — Data & File Management
+
+Linux-style commands for managing artifacts (datasets, models, files). Artifact paths use `alias:path/to/file` notation.
+
+```bash
+hypha artifacts ls [artifact[:path]] [--json] [--long]
+hypha artifacts cat <artifact:path>
+hypha artifacts cp <src> <dest> [-r] [--commit]
+hypha artifacts rm <artifact[:path]> [-r] [--force]
+hypha artifacts create <alias> [--type T] [--parent P]
+hypha artifacts info <artifact> [--json]
+hypha artifacts search <query> [--type T] [--limit N] [--json]
+hypha artifacts commit <artifact> [--version V] [--message M]
+hypha artifacts edit <artifact> [--name N] [--description D]
+hypha artifacts discard <artifact>
+```
+
+**Aliases**: `list` = `ls`, `mkdir` = `create`, `find` = `search`
+
+**Shorthand**: `hypha art` = `hypha artifacts`
+
+#### Copy Examples
+
+```bash
+# Upload a single file
+hypha artifacts cp ./data.csv my-model:data/train.csv
+
+# Download a file
+hypha artifacts cp my-model:weights.bin ./local/
+
+# Upload a directory (recursive)
+hypha artifacts cp ./dataset/ my-model:data/ -r
+
+# Upload and auto-commit
+hypha artifacts cp ./results.json my-model:results.json --commit
+```
+
+## Programmatic API
+
+```javascript
+import { connectToHypha, resolveServerUrl, resolveToken } from 'hypha-cli';
+import { uploadFile, downloadFile } from 'hypha-cli';
+import { parseArtifactPath, resolveArtifactId } from 'hypha-cli';
+```
+
+## Development
+
+```bash
+# Build
+yarn workspace hypha-cli build
+
+# Run unit tests (176 tests)
+yarn workspace hypha-cli test
+
+# Run integration tests (requires HYPHA_TOKEN)
+yarn workspace hypha-cli test:integration
+
+# Dev mode (run from source)
+yarn workspace hypha-cli dev -- artifacts ls
+```
+
+## License
+
+See LICENSE in the repository root.

package/bin/postinstall.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+
+/**
+ * postinstall script for hypha-cli
+ *
+ * Detects and removes conflicting Python 'hypha' command.
+ * The Python hypha package installs a 'hypha' console_script for starting
+ * the server, but `python -m hypha.server` is the preferred way to do that.
+ *
+ * npm runs postinstall in a stripped shell (no ~/.zshrc, no conda init, etc),
+ * so `which` can't see all PATH entries. We solve this by running `which -a`
+ * inside a login shell to get the user's full PATH.
+ */
+
+import { execSync } from 'child_process';
+import { existsSync, readFileSync, unlinkSync } from 'fs';
+
+function isPythonHyphaScript(filePath) {
+    try {
+        const head = readFileSync(filePath, 'utf-8').slice(0, 500);
+        return head.includes('python') && head.includes('from hypha');
+    } catch {
+        return false;
+    }
+}
+
+function findConflictingBinaries() {
+    const found = new Set();
+
+    // Detect user's shell
+    const shell = process.env.SHELL || '/bin/sh';
+
+    // Run `which -a hypha` in a login shell to get full PATH (conda, pyenv, etc.)
+    for (const cmd of [
+        `${shell} -l -c 'which -a hypha' 2>/dev/null`,  // login shell (loads ~/.zshrc, conda init, etc.)
+        'which -a hypha 2>/dev/null',                      // plain fallback
+    ]) {
+        try {
+            const output = execSync(cmd, { encoding: 'utf-8', timeout: 10000 }).trim();
+            for (const line of output.split('\n')) {
+                const p = line.trim();
+                if (p && existsSync(p) && isPythonHyphaScript(p)) {
+                    found.add(p);
+                }
+            }
+        } catch {
+            // Shell or which not available
+        }
+    }
+
+    return [...found];
+}
+
+function main() {
+    const conflicts = findConflictingBinaries();
+    if (conflicts.length === 0) return;
+
+    for (const binPath of conflicts) {
+        try {
+            unlinkSync(binPath);
+            console.log(`hypha-cli: removed conflicting Python 'hypha' at ${binPath}`);
+        } catch (err) {
+            if (err.code === 'EACCES') {
+                console.log(`hypha-cli: conflicting Python 'hypha' at ${binPath}`);
+                console.log(`           remove it manually: rm ${binPath}`);
+            }
+        }
+    }
+
+    if (conflicts.length > 0) {
+        console.log(`  (use 'python -m hypha.server' to start the Hypha server instead)`);
+    }
+}
+
+main();

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "hypha-cli",
-    "version": "0.1.0",
+    "version": "0.1.2",
     "description": "Hypha Cloud CLI — manage workspaces, apps, and artifacts",
     "author": "Amun AI AB",
     "license": "SEE LICENSE IN LICENSE",
@@ -18,6 +18,7 @@
         "./cli": "./dist/cli.mjs"
     },
     "scripts": {
+        "postinstall": "node bin/postinstall.mjs",
         "build": "tsc --noEmit && pkgroll",
         "typecheck": "tsc --noEmit",
         "test": "npx tsx test/test-cli-routing.mjs && npx tsx test/test-artifact-path.mjs && npx tsx test/test-apps-commands.mjs && npx tsx test/test-artifacts-commands.mjs && npx tsx test/test-helpers.mjs",