hypha-cli 0.1.11 → 0.1.13

package/dist/artifacts-DHPJIrSS.mjs

@@ -0,0 +1,955 @@
+import { statSync, readFileSync, mkdirSync, createWriteStream, readdirSync } from 'fs';
+import { join, dirname, basename } from 'path';
+import { e as hasFlag, p as positionalArgs, f as formatJson, a as formatTable, r as resolveServerUrl, i as getFlag, g as getFlagInt, c as connectToHypha, b as resolveToken, m as printAggregateProgress, n as printProgress, h as humanSize } from './helpers-BC4AKy6a.mjs';
+import { p as parseArtifactPath, b as buildFileUrl, d as determineCpDirection, r as resolveArtifactId } from './artifactPath-DCtvp6Go.mjs';
+import 'os';
+
+function envInt(name, fallback) {
+  const raw = process.env[name];
+  if (!raw) return fallback;
+  const n = parseInt(raw, 10);
+  return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+const DEFAULT_BATCH_SIZE = 200;
+const DEFAULT_CONCURRENCY = 16;
+function chunk(arr, n) {
+  if (n <= 0) throw new Error("chunk size must be positive");
+  const out = [];
+  for (let i = 0; i < arr.length; i += n) {
+    out.push(arr.slice(i, i + n));
+  }
+  return out;
+}
+async function uploadFile(artifactManager, artifactId, localPath, remotePath, onProgress) {
+  const stat = statSync(localPath);
+  const totalBytes = stat.size;
+  onProgress?.({ phase: "reading", bytesTransferred: 0, totalBytes, fileName: remotePath });
+  const putUrl = await artifactManager.put_file({
+    artifact_id: artifactId,
+    file_path: remotePath,
+    _rkwargs: true
+  });
+  if (!putUrl || typeof putUrl !== "string") {
+    throw new Error(`put_file returned invalid URL for ${remotePath}: ${putUrl}`);
+  }
+  const content = readFileSync(localPath);
+  onProgress?.({ phase: "uploading", bytesTransferred: 0, totalBytes, fileName: remotePath });
+  const resp = await fetch(putUrl, {
+    method: "PUT",
+    body: content,
+    headers: {
+      "Content-Type": "application/octet-stream",
+      "Content-Length": String(totalBytes)
+    }
+  });
+  if (!resp.ok) {
+    const body = await resp.text().catch(() => "");
+    throw new Error(`Upload failed for ${remotePath}: ${resp.status} ${resp.statusText} ${body}`);
+  }
+  onProgress?.({ phase: "complete", bytesTransferred: totalBytes, totalBytes, fileName: remotePath });
+}
+async function downloadFile(artifactManager, artifactId, remotePath, localPath, onProgress) {
+  const getResult = await artifactManager.get_file({
+    artifact_id: artifactId,
+    file_path: remotePath,
+    _rkwargs: true
+  });
+  const getUrl = typeof getResult === "string" ? getResult : getResult?.url;
+  if (!getUrl || typeof getUrl !== "string") {
+    throw new Error(`get_file returned invalid result for ${remotePath}: ${JSON.stringify(getResult)}`);
+  }
+  const resp = await fetch(getUrl);
+  if (!resp.ok) {
+    throw new Error(`Download failed for ${remotePath}: ${resp.status} ${resp.statusText}`);
+  }
+  const totalBytes = parseInt(resp.headers.get("content-length") || "0", 10);
+  let bytesTransferred = 0;
+  onProgress?.({ phase: "downloading", bytesTransferred: 0, totalBytes, fileName: remotePath });
+  mkdirSync(dirname(localPath), { recursive: true });
+  const fileStream = createWriteStream(localPath);
+  const reader = resp.body?.getReader();
+  if (!reader) {
+    throw new Error("Response body is not readable");
+  }
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      fileStream.write(value);
+      bytesTransferred += value.length;
+      onProgress?.({
+        phase: "downloading",
+        bytesTransferred,
+        totalBytes: totalBytes || bytesTransferred,
+        fileName: remotePath
+      });
+    }
+  } finally {
+    fileStream.end();
+    reader.releaseLock();
+  }
+  await new Promise((resolve, reject) => {
+    fileStream.on("finish", resolve);
+    fileStream.on("error", reject);
+  });
+  onProgress?.({ phase: "complete", bytesTransferred, totalBytes: totalBytes || bytesTransferred, fileName: remotePath });
+}
+async function uploadFilesBatched(artifactManager, artifactId, files, onProgress, opts = {}) {
+  const batchSize = opts.batchSize ?? envInt("HYPHA_UPLOAD_BATCH", DEFAULT_BATCH_SIZE);
+  const concurrency = opts.concurrency ?? envInt("HYPHA_UPLOAD_CONCURRENCY", DEFAULT_CONCURRENCY);
+  const filesTotal = files.length;
+  const bytesTotal = files.reduce((s, f) => s + f.size, 0);
+  let filesDone = 0;
+  let bytesDone = 0;
+  const emit = (currentFile) => {
+    onProgress?.({ filesDone, filesTotal, bytesDone, bytesTotal, currentFile });
+  };
+  emit(filesTotal > 0 ? files[0].remotePath : "");
+  for (const group of chunk(files, batchSize)) {
+    const paths = group.map((f) => f.remotePath);
+    const result = await artifactManager.put_file({
+      artifact_id: artifactId,
+      file_path: paths,
+      _rkwargs: true
+    });
+    let urlMap;
+    if (result && typeof result === "object" && !Array.isArray(result)) {
+      urlMap = result;
+    } else {
+      urlMap = {};
+      for (const f of group) {
+        const u = await artifactManager.put_file({
+          artifact_id: artifactId,
+          file_path: f.remotePath,
+          _rkwargs: true
+        });
+        if (typeof u !== "string") {
+          throw new Error(`put_file returned unexpected value for ${f.remotePath}`);
+        }
+        urlMap[f.remotePath] = u;
+      }
+    }
+    let cursor = 0;
+    const workers = [];
+    const worker = async () => {
+      while (true) {
+        const i = cursor++;
+        if (i >= group.length) return;
+        const f = group[i];
+        const url = urlMap[f.remotePath];
+        if (!url || typeof url !== "string") {
+          throw new Error(`No presigned URL returned for ${f.remotePath}`);
+        }
+        const body = readFileSync(f.localPath);
+        const resp = await fetch(url, {
+          method: "PUT",
+          body,
+          headers: {
+            "Content-Type": "application/octet-stream",
+            "Content-Length": String(f.size)
+          }
+        });
+        if (!resp.ok) {
+          const text = await resp.text().catch(() => "");
+          throw new Error(`Upload failed for ${f.remotePath}: ${resp.status} ${resp.statusText} ${text}`);
+        }
+        filesDone++;
+        bytesDone += f.size;
+        emit(f.remotePath);
+      }
+    };
+    const n = Math.min(concurrency, group.length);
+    for (let w = 0; w < n; w++) workers.push(worker());
+    await Promise.all(workers);
+  }
+  return filesDone;
+}
+async function uploadDirectory(artifactManager, artifactId, localDir, remoteBase, onProgress) {
+  const relPaths = collectLocalFiles(localDir);
+  const files = relPaths.map((relPath) => {
+    const localPath = join(localDir, relPath);
+    const remotePath = remoteBase ? `${remoteBase}/${relPath}` : relPath;
+    const size = statSync(localPath).size;
+    return { localPath, remotePath, size };
+  });
+  return uploadFilesBatched(artifactManager, artifactId, files, onProgress);
+}
+async function downloadDirectory(artifactManager, artifactId, remotePath, localDir, onProgress) {
+  const files = await artifactManager.list_files({
+    artifact_id: artifactId,
+    dir_path: remotePath || "",
+    _rkwargs: true
+  });
+  const fileList = Array.isArray(files) ? files : files?.items || [];
+  let downloaded = 0;
+  for (const entry of fileList) {
+    if (entry.type === "directory") {
+      const subRemote = remotePath ? `${remotePath}/${entry.name}` : entry.name;
+      const subLocal = join(localDir, entry.name);
+      downloaded += await downloadDirectory(artifactManager, artifactId, subRemote, subLocal, onProgress);
+    } else {
+      const remoteFile = remotePath ? `${remotePath}/${entry.name}` : entry.name;
+      const localFile = join(localDir, entry.name);
+      await downloadFile(artifactManager, artifactId, remoteFile, localFile, onProgress);
+      downloaded++;
+    }
+  }
+  return downloaded;
+}
+const IGNORED_DIRS = /* @__PURE__ */ new Set([
+  "__pycache__",
+  ".git",
+  ".venv",
+  "node_modules",
+  ".idea",
+  ".pytest_cache",
+  ".mypy_cache",
+  "build",
+  "dist"
+]);
+function collectLocalFiles(dir, base = "") {
+  const entries = readdirSync(dir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    if (entry.name.startsWith(".") && entry.name !== ".env.example") continue;
+    if (entry.isDirectory() && IGNORED_DIRS.has(entry.name)) continue;
+    const relPath = base ? `${base}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      files.push(...collectLocalFiles(join(dir, entry.name), relPath));
+    } else {
+      files.push(relPath);
+    }
+  }
+  return files;
+}
+
+function printArtifactsHelp() {
+  console.log(`hypha artifacts \u2014 manage artifacts
+
+Usage: hypha artifacts <command> [options]
+
+Commands:
+  ls [artifact[:path]]           List artifacts or files in artifact
+  cat <artifact>:<path>          Read file content to stdout
+  cp <src> <dest> [-r]           Upload/download files (scp-style)
+  rm <artifact>[:<path>]         Delete artifact or file
+  create <alias> [options]       Create a new artifact
+  info <artifact> [--json]       Show artifact metadata
+  search <query> [options]       Search artifacts
+  commit <artifact> [options]    Commit staged changes
+  edit <artifact> [options]      Edit artifact metadata
+  discard <artifact>             Discard staged changes
+  serve <artifact> [options]     Enable/disable static site hosting
+
+Aliases: list \u2192 ls, mkdir \u2192 create, find \u2192 search
+Shorthand: "hypha art" is an alias for "hypha artifacts"
+
+Artifact addressing:
+  alias                          Artifact in current workspace
+  workspace/alias                Artifact in specific workspace
+  artifact:path/to/file          File inside artifact
+
+Copy examples:
+  hypha art cp ./data.csv model:data/train.csv     Upload file
+  hypha art cp model:weights.bin ./local/           Download file
+  hypha art cp ./dataset/ model:data/ -r            Upload directory
+
+Common options:
+  --json                         Output as JSON
+  --long, -l                     Long listing format (with sizes)
+  --recursive, -r                Recursive operation
+  --force, -f                    Skip confirmation`);
+}
+async function connectAndGetArtifactManager() {
+  const server = await connectToHypha();
+  const am = await server.getService("public/artifact-manager");
+  return { server, am };
+}
+function makeProgressCallback() {
+  return (p) => {
+    if (p.totalBytes > 0) {
+      printProgress(p.fileName, p.bytesTransferred, p.totalBytes);
+    }
+  };
+}
+function makeBatchProgressCallback(label) {
+  return (p) => {
+    printAggregateProgress(label, p.filesDone, p.filesTotal, p.bytesDone, p.bytesTotal);
+  };
+}
+async function fetchWithAuth(url, init) {
+  const token = resolveToken();
+  const headers = new Headers(init?.headers);
+  if (token) {
+    headers.set("Authorization", `Bearer ${token}`);
+  }
+  return fetch(url, { ...init, headers });
+}
+async function artifactsLs(args) {
+  if (hasFlag(args, "--help", "-h")) {
+    console.log(`hypha artifacts ls \u2014 list artifacts or files
+
+Usage: hypha artifacts ls [artifact[:path]] [options]
+
+With no argument, lists all artifacts in the workspace.
+With artifact:path, lists files in the artifact.
+
+Options:
+  --json       Output as JSON
+  --long, -l   Long listing format (with sizes, types)
+
+Alias: hypha artifacts list`);
+    return;
+  }
+  const json = hasFlag(args, "--json");
+  const long = hasFlag(args, "--long", "-l");
+  const pos = positionalArgs(args)[0];
+  if (!pos) {
+    const { server: server2, am: am2 } = await connectAndGetArtifactManager();
+    try {
+      const artifacts = await am2.list({
+        _rkwargs: true
+      });
+      const list = Array.isArray(artifacts) ? artifacts : artifacts?.items || [];
+      if (json) {
+        console.log(formatJson(list));
+        return;
+      }
+      if (list.length === 0) {
+        console.log("No artifacts found.");
+        return;
+      }
+      if (long) {
+        const rows = [["ALIAS", "TYPE", "MODIFIED", "DESCRIPTION"]];
+        for (const art of list) {
+          const manifest = art.manifest || {};
+          rows.push([
+            art.alias || art.id || "",
+            art.type || "",
+            art.last_modified ? new Date(art.last_modified * 1e3).toISOString().slice(0, 10) : "",
+            (manifest.description || "").slice(0, 50)
+          ]);
+        }
+        console.log(formatTable(rows));
+      } else {
+        for (const art of list) {
+          console.log(art.alias || art.id || "");
+        }
+      }
+    } finally {
+      await server2.disconnect();
+    }
+    return;
+  }
+  const parsed = parseArtifactPath(pos);
+  const serverUrl = resolveServerUrl();
+  const { server, am } = await connectAndGetArtifactManager();
+  const workspace = parsed.workspace || server.config.workspace;
+  const artifactId = resolveArtifactId(parsed, server.config.workspace);
+  try {
+    if (!parsed.filePath) {
+      let info;
+      try {
+        info = await am.read({ artifact_id: artifactId, _rkwargs: true });
+      } catch (err) {
+        const msg = String(err?.message || err);
+        if (/not found|does not exist/i.test(msg)) {
+          console.error(`Artifact not found: ${pos}`);
+          process.exit(1);
+        }
+        throw err;
+      }
+      if (info?.type === "collection") {
+        const children = await am.list({ parent_id: artifactId, _rkwargs: true });
+        const list = Array.isArray(children) ? children : children?.items || [];
+        if (json) {
+          console.log(formatJson(list));
+          return;
+        }
+        if (list.length === 0) {
+          console.log("No child artifacts in this collection.");
+          return;
+        }
+        if (long) {
+          const rows = [["ALIAS", "TYPE", "MODIFIED", "DESCRIPTION"]];
+          for (const art of list) {
+            const manifest = art.manifest || {};
+            rows.push([
+              art.alias || art.id || "",
+              art.type || "",
+              art.last_modified ? new Date(art.last_modified * 1e3).toISOString().slice(0, 10) : "",
+              (manifest.description || "").slice(0, 50)
+            ]);
+          }
+          console.log(formatTable(rows));
+        } else {
+          for (const art of list) {
+            console.log(art.alias || art.id || "");
+          }
+        }
+        return;
+      }
+    }
+    const url = buildFileUrl(serverUrl, workspace, parsed.alias, parsed.filePath);
+    const resp = await fetchWithAuth(url);
+    if (!resp.ok) {
+      if (resp.status === 404) {
+        console.error(`Not found: ${pos}`);
+        process.exit(1);
+      }
+      throw new Error(`List files failed: ${resp.status} ${resp.statusText}`);
+    }
+    const data = await resp.json();
+    const files = Array.isArray(data) ? data : data.items || [];
+    if (json) {
+      console.log(formatJson(files));
+      return;
+    }
+    if (files.length === 0) {
+      console.log("No files found.");
+      return;
+    }
+    if (long) {
+      const rows = [["SIZE", "TYPE", "NAME"]];
+      for (const f of files) {
+        rows.push([
+          f.type === "directory" ? "-" : humanSize(f.size || 0),
+          f.type || "file",
+          f.type === "directory" ? `${f.name}/` : f.name
+        ]);
+      }
+      console.log(formatTable(rows));
+    } else {
+      for (const f of files) {
+        console.log(f.type === "directory" ? `${f.name}/` : f.name);
+      }
+    }
+  } finally {
+    await server.disconnect();
+  }
+}
+async function artifactsCat(args) {
+  if (hasFlag(args, "--help", "-h")) {
+    console.log(`hypha artifacts cat \u2014 read file content to stdout
+
+Usage: hypha artifacts cat <artifact>:<path>
+
+Examples:
+  hypha art cat model:README.md
+  hypha art cat ws/model:data/config.json`);
+    return;
+  }
+  const pos = positionalArgs(args)[0];
+  if (!pos) {
+    console.error("Usage: hypha artifacts cat <artifact>:<path>");
+    process.exit(1);
+  }
+  const parsed = parseArtifactPath(pos);
+  if (!parsed.filePath) {
+    console.error("File path required. Use artifact:path/to/file syntax.");
+    process.exit(1);
+  }
+  const serverUrl = resolveServerUrl();
+  const { server } = await connectAndGetArtifactManager();
+  const workspace = parsed.workspace || server.config.workspace;
+  try {
+    const url = buildFileUrl(serverUrl, workspace, parsed.alias, parsed.filePath);
+    const resp = await fetchWithAuth(url, { redirect: "follow" });
+    if (!resp.ok) {
+      if (resp.status === 404) {
+        console.error(`File not found: ${parsed.filePath}`);
+        process.exit(1);
+      }
+      throw new Error(`Read failed: ${resp.status} ${resp.statusText}`);
+    }
+    const reader = resp.body?.getReader();
+    if (!reader) {
+      const text = await resp.text();
+      process.stdout.write(text);
+      return;
+    }
+    const decoder = new TextDecoder();
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      process.stdout.write(decoder.decode(value, { stream: true }));
+    }
+  } finally {
+    await server.disconnect();
+  }
+}
+async function artifactsCp(args) {
+  if (hasFlag(args, "--help", "-h")) {
+    console.log(`hypha artifacts cp \u2014 upload/download files (scp-style)
+
+Usage: hypha artifacts cp <src> <dest> [-r] [--commit]
+
+Options:
+  -r, --recursive    Copy directories recursively
+  --commit           Auto-commit after upload
+
+Examples:
+  hypha art cp ./data.csv model:data/train.csv        Upload file
+  hypha art cp model:weights.bin ./local/              Download file
+  hypha art cp ./dataset/ model:data/ -r               Upload directory
+  hypha art cp ./file.txt model:file.txt --commit      Upload and commit`);
+    return;
+  }
+  const pos = positionalArgs(args, []);
+  const recursive = hasFlag(args, "--recursive", "-r");
+  const autoCommit = hasFlag(args, "--commit");
+  if (pos.length < 2) {
+    console.error("Usage: hypha artifacts cp <src> <dest> [-r] [--commit]");
+    console.error("  Upload:   hypha artifacts cp ./file.txt artifact:path/");
+    console.error("  Download: hypha artifacts cp artifact:path/file.txt ./local/");
+    process.exit(1);
+  }
+  const [src, dest] = pos;
+  const direction = determineCpDirection(src, dest);
+  const { server, am } = await connectAndGetArtifactManager();
+  const onProgress = makeProgressCallback();
+  try {
+    if (direction === "upload") {
+      const parsed = parseArtifactPath(dest);
+      const artifactId = resolveArtifactId(parsed, server.config.workspace);
+      await am.edit({
+        artifact_id: artifactId,
+        stage: true,
+        _rkwargs: true
+      });
+      const stat = statSync(src);
+      if (stat.isDirectory()) {
+        if (!recursive) {
+          console.error("Source is a directory. Use -r to copy directories.");
+          process.exit(1);
+        }
+        const dirLabel = `${basename(src)}/`;
+        const count = await uploadDirectory(
+          am,
+          artifactId,
+          src,
+          parsed.filePath || "",
+          makeBatchProgressCallback(dirLabel)
+        );
+        if (autoCommit) {
+          await am.commit({ artifact_id: artifactId, _rkwargs: true });
+          console.log(`Uploaded ${count} files and committed.`);
+        } else {
+          console.log(`Uploaded ${count} files. Run \`hypha artifacts commit ${parsed.alias}\` to finalize.`);
+        }
+      } else {
+        const remotePath = parsed.filePath || basename(src);
+        await uploadFile(am, artifactId, src, remotePath, onProgress);
+        if (autoCommit) {
+          await am.commit({ artifact_id: artifactId, _rkwargs: true });
+          console.log(`
+Uploaded and committed: ${remotePath}`);
+        } else {
+          console.log(`
+Uploaded: ${remotePath}. Run \`hypha artifacts commit ${parsed.alias}\` to finalize.`);
+        }
+      }
+    } else {
+      const parsed = parseArtifactPath(src);
+      const artifactId = resolveArtifactId(parsed, server.config.workspace);
+      if (!parsed.filePath) {
+        console.error("Source must include a file path (e.g., artifact:path/to/file).");
+        console.error("Use `hypha artifacts ls artifact:` to see available files.");
+        process.exit(1);
+      }
+      if (parsed.filePath.endsWith("/") && recursive) {
+        const count = await downloadDirectory(am, artifactId, parsed.filePath.replace(/\/$/, ""), dest, onProgress);
+        console.log(`
+Downloaded ${count} files to ${dest}`);
+      } else {
+        const localDest = dest.endsWith("/") ? join(dest, basename(parsed.filePath)) : dest;
+        await downloadFile(am, artifactId, parsed.filePath, localDest, onProgress);
+        console.log(`
+Downloaded: ${localDest}`);
+      }
+    }
+  } finally {
+    await server.disconnect();
+  }
+}
+async function artifactsRm(args) {
+  if (hasFlag(args, "--help", "-h")) {
+    console.log(`hypha artifacts rm \u2014 delete artifact or file
+
+Usage: hypha artifacts rm <artifact>[:<path>] [-r] [-f]
+
+Without :path, deletes the entire artifact (requires --force).
+With :path, deletes a single file.
+
+Options:
+  -r, --recursive    Delete recursively (for collections)
+  -f, --force        Skip confirmation for whole-artifact deletion`);
+    return;
+  }
+  const pos = positionalArgs(args)[0];
+  const force = hasFlag(args, "--force", "-f");
+  const recursive = hasFlag(args, "--recursive", "-r");
+  if (!pos) {
+    console.error("Usage: hypha artifacts rm <artifact>[:<path>] [-r] [-f]");
+    process.exit(1);
+  }
+  const parsed = parseArtifactPath(pos);
+  const { server, am } = await connectAndGetArtifactManager();
+  const artifactId = resolveArtifactId(parsed, server.config.workspace);
+  try {
+    if (parsed.filePath) {
+      await am.remove_file({
+        artifact_id: artifactId,
+        file_path: parsed.filePath,
+        _rkwargs: true
+      });
+      console.log(`Removed: ${parsed.filePath}`);
+    } else {
+      if (!force) {
+        console.error(`This will delete the entire artifact "${parsed.alias}". Use --force to confirm.`);
+        process.exit(1);
+      }
+      await am.delete({
+        artifact_id: artifactId,
+        delete_files: true,
+        recursive,
+        _rkwargs: true
+      });
+      console.log(`Deleted: ${parsed.alias}`);
+    }
+  } finally {
+    await server.disconnect();
+  }
+}
+async function artifactsCreate(args) {
+  if (hasFlag(args, "--help", "-h")) {
+    console.log(`hypha artifacts create \u2014 create a new artifact
+
+Usage: hypha artifacts create <alias> [options]
+
+Options:
+  --type <type>       Artifact type (default: generic)
+  --parent <id>       Parent artifact ID (for collections)
+  --json              Output as JSON
+
+Types: generic, collection, application, model, dataset
+
+Alias: hypha artifacts mkdir`);
+    return;
+  }
+  const pos = positionalArgs(args, ["--type", "--parent"])[0];
+  const type = getFlag(args, "--type") || "generic";
+  const parent = getFlag(args, "--parent");
+  const json = hasFlag(args, "--json");
+  if (!pos) {
+    console.error("Usage: hypha artifacts create <alias> [--type T] [--parent P]");
+    console.error("Types: generic, collection, application, model, dataset");
+    process.exit(1);
+  }
+  const { server, am } = await connectAndGetArtifactManager();
+  try {
+    const createOpts = {
+      alias: pos,
+      type,
+      manifest: { name: pos },
+      _rkwargs: true
+    };
+    if (parent) createOpts.parent_id = parent;
+    const result = await am.create(createOpts);
+    if (json) {
+      console.log(formatJson(result));
+    } else {
+      console.log(`Created: ${result.alias || pos} (type: ${type})`);
+    }
+  } finally {
+    await server.disconnect();
+  }
+}
+async function artifactsInfo(args) {
+  if (hasFlag(args, "--help", "-h")) {
+    console.log(`hypha artifacts info \u2014 show artifact metadata
+
+Usage: hypha artifacts info <artifact> [--json]
+
+Options:
+  --json    Output as JSON`);
+    return;
+  }
+  const pos = positionalArgs(args)[0];
+  const json = hasFlag(args, "--json");
+  if (!pos) {
+    console.error("Usage: hypha artifacts info <artifact> [--json]");
+    process.exit(1);
+  }
+  const parsed = parseArtifactPath(pos);
+  const { server, am } = await connectAndGetArtifactManager();
+  const artifactId = resolveArtifactId(parsed, server.config.workspace);
+  try {
+    const info = await am.read({
+      artifact_id: artifactId,
+      _rkwargs: true
+    });
+    if (json) {
+      console.log(formatJson(info));
+    } else {
+      const manifest = info.manifest || {};
+      console.log(`Alias:       ${info.alias || artifactId}`);
+      console.log(`ID:          ${info.id || ""}`);
+      console.log(`Type:        ${info.type || "generic"}`);
+      console.log(`Name:        ${manifest.name || ""}`);
+      console.log(`Description: ${manifest.description || ""}`);
+      console.log(`Workspace:   ${info.workspace || ""}`);
+      if (info.created_at) console.log(`Created:     ${new Date(info.created_at * 1e3).toISOString()}`);
+      if (info.last_modified) console.log(`Modified:    ${new Date(info.last_modified * 1e3).toISOString()}`);
+      if (info.versions?.length) {
+        console.log(`Versions:    ${info.versions.map((v) => v.name || v.version || v).join(", ")}`);
+      }
+      if (info.download_count) console.log(`Downloads:   ${info.download_count}`);
+      if (info.view_count) console.log(`Views:       ${info.view_count}`);
+    }
+  } finally {
+    await server.disconnect();
+  }
+}
+async function artifactsSearch(args) {
+  if (hasFlag(args, "--help", "-h")) {
+    console.log(`hypha artifacts search \u2014 search artifacts
+
+Usage: hypha artifacts search <query> [options]
+
+Options:
+  --type <type>     Filter by artifact type
+  --limit <n>       Max results (default: 20)
+  --json            Output as JSON
+
+Alias: hypha artifacts find`);
+    return;
+  }
+  const pos = positionalArgs(args, ["--type", "--limit"])[0];
+  const type = getFlag(args, "--type");
+  const limit = getFlagInt(args, "--limit") || 20;
+  const json = hasFlag(args, "--json");
+  if (!pos) {
+    console.error("Usage: hypha artifacts search <query> [--type T] [--limit N] [--json]");
+    process.exit(1);
+  }
+  const { server, am } = await connectAndGetArtifactManager();
+  try {
+    const searchOpts = {
+      keywords: pos,
+      limit,
+      _rkwargs: true
+    };
+    if (type) {
+      searchOpts.filters = { type };
+    }
+    const results = await am.list(searchOpts);
+    const list = Array.isArray(results) ? results : results?.items || [];
+    if (json) {
+      console.log(formatJson(list));
+      return;
+    }
+    if (list.length === 0) {
+      console.log("No results found.");
+      return;
+    }
+    const rows = [["ALIAS", "TYPE", "NAME", "DESCRIPTION"]];
+    for (const art of list) {
+      const manifest = art.manifest || {};
+      rows.push([
+        art.alias || art.id || "",
+        art.type || "",
+        manifest.name || "",
+        (manifest.description || "").slice(0, 40)
+      ]);
+    }
+    console.log(formatTable(rows));
+  } finally {
+    await server.disconnect();
+  }
+}
+async function artifactsCommit(args) {
+  if (hasFlag(args, "--help", "-h")) {
+    console.log(`hypha artifacts commit \u2014 commit staged changes
+
+Usage: hypha artifacts commit <artifact> [options]
+
+Options:
+  --version <version>     Version tag (e.g., v1.0)
+  --message, -m <msg>     Commit message`);
+    return;
+  }
+  const pos = positionalArgs(args, ["--version", "--message"])[0];
+  const version = getFlag(args, "--version");
+  const message = getFlag(args, "--message", "-m");
+  if (!pos) {
+    console.error("Usage: hypha artifacts commit <artifact> [--version V] [--message M]");
+    process.exit(1);
+  }
+  const parsed = parseArtifactPath(pos);
+  const { server, am } = await connectAndGetArtifactManager();
+  const artifactId = resolveArtifactId(parsed, server.config.workspace);
+  try {
+    const commitOpts = {
+      artifact_id: artifactId,
+      _rkwargs: true
+    };
+    if (version) commitOpts.version = version;
+    if (message) commitOpts.comment = message;
+    await am.commit(commitOpts);
+    console.log(`Committed: ${parsed.alias}${version ? ` (version: ${version})` : ""}`);
+  } finally {
+    await server.disconnect();
+  }
+}
+async function artifactsEdit(args) {
+  if (hasFlag(args, "--help", "-h")) {
+    console.log(`hypha artifacts edit \u2014 edit artifact metadata
+
+Usage: hypha artifacts edit <artifact> [options]
+
+Options:
+  --name <name>             Update display name
+  --description <desc>      Update description
+  --type <type>             Update artifact type
+  --stage                   Enter staging mode for file operations`);
+    return;
+  }
+  const pos = positionalArgs(args, ["--name", "--description", "--type"])[0];
+  const name = getFlag(args, "--name");
+  const description = getFlag(args, "--description");
+  const type = getFlag(args, "--type");
+  const stage = hasFlag(args, "--stage");
+  if (!pos) {
+    console.error("Usage: hypha artifacts edit <artifact> [--name N] [--description D] [--type T] [--stage]");
+    process.exit(1);
+  }
+  const parsed = parseArtifactPath(pos);
+  const { server, am } = await connectAndGetArtifactManager();
+  const artifactId = resolveArtifactId(parsed, server.config.workspace);
+  try {
+    const editOpts = {
+      artifact_id: artifactId,
+      _rkwargs: true
+    };
+    const manifest = {};
+    if (name) manifest.name = name;
+    if (description) manifest.description = description;
+    if (Object.keys(manifest).length > 0) editOpts.manifest = manifest;
+    if (type) editOpts.type = type;
+    if (stage) editOpts.stage = true;
+    await am.edit(editOpts);
+    console.log(`Updated: ${parsed.alias}`);
+  } finally {
+    await server.disconnect();
+  }
+}
+async function artifactsDiscard(args) {
+  if (hasFlag(args, "--help", "-h")) {
+    console.log(`hypha artifacts discard \u2014 discard staged changes
+
+Usage: hypha artifacts discard <artifact>`);
+    return;
+  }
+  const pos = positionalArgs(args)[0];
+  if (!pos) {
+    console.error("Usage: hypha artifacts discard <artifact>");
+    process.exit(1);
+  }
+  const parsed = parseArtifactPath(pos);
+  const { server, am } = await connectAndGetArtifactManager();
+  const artifactId = resolveArtifactId(parsed, server.config.workspace);
+  try {
+    await am.discard_changes({ artifact_id: artifactId, _rkwargs: true });
+    console.log(`Discarded staged changes: ${parsed.alias}`);
+  } finally {
+    await server.disconnect();
+  }
+}
+async function artifactsServe(args) {
+  if (hasFlag(args, "--help", "-h")) {
+    console.log(`hypha artifacts serve \u2014 enable or disable static site hosting
+
+Usage: hypha artifacts serve <artifact> [options]
+
+Options:
+  --root <dir>       Root directory to serve (default: /)
+  --disable          Disable static site hosting
+
+Examples:
+  hypha art serve my-site                  # Enable \u2014 serve from artifact root
+  hypha art serve my-site --root dist      # Serve from /dist subdirectory
+  hypha art serve my-site --disable        # Disable static site hosting`);
+    return;
+  }
+  const pos = positionalArgs(args, ["--root"])[0];
+  if (!pos) {
+    console.error("Usage: hypha artifacts serve <artifact> [--root <dir>] [--disable]");
+    process.exit(1);
+  }
+  const disable = hasFlag(args, "--disable");
+  const root = getFlag(args, "--root") || "/";
+  const parsed = parseArtifactPath(pos);
+  const { server, am } = await connectAndGetArtifactManager();
+  const artifactId = resolveArtifactId(parsed, server.config.workspace);
+  const serverUrl = resolveServerUrl();
+  const workspace = parsed.workspace || server.config.workspace;
+  try {
+    const config = {
+      view_config: disable ? "disabled" : { root_directory: root }
+    };
+    await am.edit({
+      artifact_id: artifactId,
+      config,
+      _rkwargs: true
+    });
+    if (disable) {
+      console.log(`Static site hosting disabled: ${parsed.alias}`);
+    } else {
+      const url = `${serverUrl}/${workspace}/view/${parsed.alias}`;
+      console.log(`Static site enabled: ${url}`);
+      if (root && root !== "/") {
+        console.log(`  Serving from: ${root}`);
+      }
+    }
+  } finally {
+    await server.disconnect();
+  }
+}
+async function handleArtifactsCommand(args) {
+  const sub = args[0];
+  const commandArgs = args.slice(1);
+  if (!sub || sub === "--help" || sub === "-h") {
+    printArtifactsHelp();
+    return;
+  }
+  if (sub === "ls" || sub === "list") {
+    await artifactsLs(commandArgs);
+  } else if (sub === "cat") {
+    await artifactsCat(commandArgs);
+  } else if (sub === "cp") {
+    await artifactsCp(commandArgs);
+  } else if (sub === "rm") {
+    await artifactsRm(commandArgs);
+  } else if (sub === "create" || sub === "mkdir") {
+    await artifactsCreate(commandArgs);
+  } else if (sub === "info") {
+    await artifactsInfo(commandArgs);
+  } else if (sub === "search" || sub === "find") {
+    await artifactsSearch(commandArgs);
+  } else if (sub === "commit") {
+    await artifactsCommit(commandArgs);
+  } else if (sub === "edit") {
+    await artifactsEdit(commandArgs);
+  } else if (sub === "discard") {
+    await artifactsDiscard(commandArgs);
+  } else if (sub === "serve") {
+    await artifactsServe(commandArgs);
+  } else {
+    console.error(`Unknown artifacts command: ${sub}`);
+    printArtifactsHelp();
+    process.exit(1);
+  }
+}
+
+export { artifactsLs, handleArtifactsCommand };