@neta-art/cohub-cli 6.1.3 → 6.1.4

package/README.md

@@ -144,6 +144,17 @@ cohub -s <spaceId> spaces turns ls --cursor <nextCursor> --json
 cohub -s <spaceId> spaces turns ls --after <snapshotCursor> --before <snapshotAt> --json
 ```
 
+## Space activity
+
+One-shot overview of a Space: usage summary, per-user contributors, top
+models, and most viewed Apps. Cost figures require space-management access.
+
+```bash
+cohub -s <spaceId> spaces activity
+cohub -s <spaceId> spaces activity 7
+cohub -s <spaceId> spaces activity 365 --json
+```
+
 ## Boards
 
 Board commands use the selected Space and support `-h` at every level:
@@ -273,6 +284,11 @@ Confirm before deleting files or directories.
 
 Publish and manage Work entries from a Space workspace. Public Work URLs require a username and a Space slug.
 
+`--file` and `--dir` take paths relative to the Space workspace — the same paths
+`spaces files ls` shows, not your local filesystem. To publish local build
+output, upload it first (`spaces files upload <dir>`), then publish the
+Space-side path.
+
 ```bash
 cohub profile update --username <username>
 cohub spaces update <spaceId> --slug <space-slug>

package/dist/app-target.d.ts

@@ -0,0 +1,26 @@
+import { type CohubHttpClient } from "@neta-art/cohub";
+/**
+ * `--file` / `--dir` publish targets are paths inside the target Space's
+ * workspace, not local filesystem paths. The publish worker resolves them
+ * under `{storageRoot}/{spaceId}/workspace` and snapshots the bytes into an
+ * immutable artifact.
+ *
+ * The worker surfaces a bare "file or directory not found" without context, so
+ * the CLI checks the target against the Space files API first and fails with
+ * an explicit, self-explanatory error before anything is snapshotted.
+ */
+export type AppTargetCheckError = {
+    status: number;
+    code: string;
+    message: string;
+};
+/**
+ * Verify a Space-relative publish target exists with the expected node type.
+ * Empty targetRef (the Space workspace root, directory publishes only) passes.
+ * Returns null when the target is valid or the check itself cannot run —
+ * the preflight is advisory and must never block a publish the worker can do.
+ */
+export declare function checkAppTarget(client: CohubHttpClient, spaceId: string, target: {
+    targetType: "file" | "directory";
+    targetRef: string;
+}): Promise<AppTargetCheckError | null>;

package/dist/app-target.js

@@ -0,0 +1,55 @@
+import { isHttpErrorCode } from "@neta-art/cohub";
+/** Normalize a user-supplied Space path for comparison with fs entries. */
+function normalizeSpacePath(path) {
+    return path.replace(/^\.\//, "").replace(/\/+$/, "");
+}
+function posixDirname(path) {
+    const index = path.lastIndexOf("/");
+    return index <= 0 ? "" : path.slice(0, index);
+}
+/**
+ * Verify a Space-relative publish target exists with the expected node type.
+ * Empty targetRef (the Space workspace root, directory publishes only) passes.
+ * Returns null when the target is valid or the check itself cannot run —
+ * the preflight is advisory and must never block a publish the worker can do.
+ */
+export async function checkAppTarget(client, spaceId, target) {
+    const targetPath = normalizeSpacePath(target.targetRef);
+    if (!targetPath)
+        return null;
+    try {
+        const tree = await client.space(spaceId).files.list(posixDirname(targetPath));
+        const entry = tree.entries.find((candidate) => candidate.path === targetPath);
+        if (!entry) {
+            return {
+                status: 404,
+                code: "path_not_found",
+                message: `"${targetPath}" does not exist in the Space workspace`,
+            };
+        }
+        const wanted = target.targetType === "directory" ? "dir" : "file";
+        if (entry.type !== wanted) {
+            const foundKind = entry.type === "dir" ? "a directory" : entry.type === "symlink" ? "a symlink" : "a file";
+            const wantedKind = wanted === "dir" ? "a directory" : "a file";
+            return {
+                status: 400,
+                code: entry.type === "symlink" ? "symlink_not_supported" : wanted === "dir" ? "not_a_directory" : "not_a_file",
+                message: `"${targetPath}" is ${foundKind}, but the publish target must be ${wantedKind}`,
+            };
+        }
+        return null;
+    }
+    catch (e) {
+        // The parent directory itself is missing.
+        if (isHttpErrorCode(e, "path_not_found")) {
+            return {
+                status: 404,
+                code: "path_not_found",
+                message: `"${targetPath}" does not exist in the Space workspace`,
+            };
+        }
+        // Advisory preflight: ignore auth/visibility/network noise here and let the
+        // publish request proceed — the worker still reports real failures.
+        return null;
+    }
+}

package/dist/commands/apps.js

@@ -4,6 +4,7 @@ import { error, handleHttp, json as outJson, jsonRequested, ok, table } from "..
 import { resolveSpace } from "../space.js";
 import { downloadApp } from "../app-download.js";
 import { getAppByRef, parseAppRef } from "../app-ref.js";
+import { checkAppTarget } from "../app-target.js";
 import { registerAppCommerce } from "./app-commerce.js";
 const APP_STATUSES = ["published", "disabled"];
 const APP_VISIBILITIES = ["public", "space"];
@@ -64,6 +65,28 @@ function resolveStatus(opts) {
         return error("Conflicting status", "Use only one of --status or --disabled");
     return values[0] ? parseChoice(values[0], "status", APP_STATUSES) : "published";
 }
+/**
+ * Fail early when a Space-relative `--file` / `--dir` target cannot be a valid
+ * publish source. The publish worker resolves targets inside the target
+ * Space's workspace, not on the local filesystem.
+ */
+async function guardAppTarget(client, spaceId, target) {
+    const failure = await checkAppTarget(client, spaceId, target);
+    if (failure) {
+        error(failure.status === 404 ? "Publish target not found" : "Publish target is invalid", `${failure.message} (--${target.targetType === "directory" ? "dir" : "file"} takes a Space workspace path, not a local path).`);
+    }
+}
+/**
+ * Translate the publish worker's bare fs errors (e.g. a target removed between
+ * preflight and snapshot) into the same explicit wording as the preflight.
+ */
+function translateTargetWorkerError(e) {
+    if (!(e instanceof HttpError))
+        return;
+    if (e.code !== "path_not_found" && e.code !== "not_a_directory" && e.code !== "not_a_file" && e.code !== "symlink_not_supported")
+        return;
+    error(e.code === "path_not_found" ? "Publish target not found" : "Publish target is invalid", "The publish target is a Space workspace path; the Space workspace no longer contains a valid target at that path.");
+}
 function resolveVisibility(value) {
     return value ? parseChoice(value, "visibility", APP_VISIBILITIES) : undefined;
 }
@@ -143,6 +166,7 @@ async function publishAppVersion(id, opts) {
         printApp(result.app);
     }
     catch (e) {
+        translateTargetWorkerError(e);
         handleHttp(e);
     }
 }
@@ -261,8 +285,8 @@ export function registerApps(program) {
     appsCmd
         .command("publish <slug>")
         .description("Create or publish an app in the target space")
-        .option("--file <path>", "Publish a file (HTML page, board, or any other file)")
-        .option("--dir <path>", "Publish a directory site")
+        .option("--file <path>", "Publish a file (HTML page, board, or any other file) from the Space workspace")
+        .option("--dir <path>", "Publish a directory site from the Space workspace")
         .option("--port <port>", "Publish a public sandbox port")
         .option("--disabled", "Create as disabled")
         .option("--status <status>", "App status: published, disabled")
@@ -281,6 +305,9 @@ export function registerApps(program) {
             return error("Missing target", "Use one of --file, --dir, or --port.");
         const spaceId = resolveSpace(appsCmd);
         const client = createClient();
+        const { targetType, targetRef } = target;
+        if (targetType !== "port")
+            await guardAppTarget(client, spaceId, { targetType, targetRef });
         const status = resolveStatus(opts);
         const meta = withCohubBarMeta({
             meta: parseJsonObject(opts.meta, "meta"),
@@ -306,6 +333,7 @@ export function registerApps(program) {
             printApp(result.app);
         }
         catch (e) {
+            translateTargetWorkerError(e);
             if (!(e instanceof HttpError) || e.status !== 409)
                 handleHttp(e);
             try {
@@ -332,6 +360,7 @@ export function registerApps(program) {
                 printApp(result.app);
             }
             catch (fallbackError) {
+                translateTargetWorkerError(fallbackError);
                 handleHttp(fallbackError);
             }
         }
@@ -340,8 +369,8 @@ export function registerApps(program) {
         .command("update <id>")
         .description("Update app settings")
         .option("--slug <slug>", "New app slug")
-        .option("--file <path>", "Use a file target (HTML page, board, or any other file)")
-        .option("--dir <path>", "Use a directory site target")
+        .option("--file <path>", "Use a file target (HTML page, board, or any other file) from the Space workspace")
+        .option("--dir <path>", "Use a directory site target from the Space workspace")
         .option("--port <port>", "Use a public sandbox port target")
         .option("--disabled", "Set status to disabled")
         .option("--status <status>", "App status: published, disabled")
@@ -364,6 +393,19 @@ export function registerApps(program) {
             return error("Conflicting viewer scopes", "Use either --viewer-scope or --clear-viewer-scopes.");
         const hasMetaUpdate = opts.meta !== undefined || opts.hideCohubBar || opts.showCohubBar;
         const client = createClient();
+        if (target) {
+            // Resolve the app's home Space so the preflight checks the same
+            // workspace the publish worker will read from.
+            try {
+                const current = await client.apps.get(id);
+                const { targetType, targetRef } = target;
+                if (targetType !== "port")
+                    await guardAppTarget(client, current.app.spaceId, { targetType, targetRef });
+            }
+            catch {
+                // The update request below surfaces errors for unknown apps.
+            }
+        }
         let meta;
         if (hasMetaUpdate) {
             let baseMeta = opts.meta !== undefined ? parseJsonObject(opts.meta, "meta") ?? null : undefined;
@@ -407,6 +449,7 @@ export function registerApps(program) {
             printApp(result.app);
         }
         catch (e) {
+            translateTargetWorkerError(e);
             handleHttp(e);
         }
     });

package/dist/commands/space-activity.d.ts

@@ -0,0 +1,26 @@
+import type { SpaceActivityAppRanking, SpaceActivityContributor, SpaceActivityResponse } from "@neta-art/cohub";
+import type { Command } from "commander";
+import { type Row } from "../output.js";
+export type SpaceActivityCliOptions = {
+    json?: boolean;
+};
+type SpaceActivityCommandClient = {
+    space(spaceId: string): {
+        activity: {
+            get(days: number): Promise<SpaceActivityResponse>;
+        };
+    };
+};
+export declare class InvalidSpaceActivityDaysError extends Error {
+    readonly detail: string;
+    constructor(message: string, detail: string);
+}
+/** Shared with the API: any positive day count up to a full leap year. */
+export declare function parseActivityDays(value: string | undefined): number;
+export declare function toContributorRows(items: SpaceActivityContributor[]): Row[];
+export declare function toAppRankingRows(apps: SpaceActivityAppRanking[]): Row[];
+export declare function printActivityReport(activity: SpaceActivityResponse): void;
+export declare function registerSpaceActivity(spacesCmd: Command, dependencies?: {
+    createClient?: () => SpaceActivityCommandClient;
+}): void;
+export {};

package/dist/commands/space-activity.js

@@ -0,0 +1,149 @@
+import { createClient } from "../client.js";
+import { error, handleHttp, json as outJson, jsonRequested, table, } from "../output.js";
+import { resolveSpace } from "../space.js";
+const DEFAULT_DAYS = 30;
+const MAX_DAYS = 365;
+export class InvalidSpaceActivityDaysError extends Error {
+    detail;
+    constructor(message, detail) {
+        super(message);
+        this.detail = detail;
+        this.name = "InvalidSpaceActivityDaysError";
+    }
+}
+/** Shared with the API: any positive day count up to a full leap year. */
+export function parseActivityDays(value) {
+    const raw = (value ?? String(DEFAULT_DAYS)).trim();
+    if (!/^\d+$/.test(raw)) {
+        throw new InvalidSpaceActivityDaysError("Invalid days", "days must be a positive integer");
+    }
+    const days = Number.parseInt(raw, 10);
+    if (days < 1 || days > MAX_DAYS) {
+        throw new InvalidSpaceActivityDaysError("Invalid days", `days must be between 1 and ${MAX_DAYS}`);
+    }
+    return days;
+}
+const formatNumber = (value) => new Intl.NumberFormat("en-US").format(Number(value) || 0);
+const formatCost = (value) => `$${(Number(value) || 0).toFixed(2)}`;
+function relativeTime(timestamp) {
+    if (!timestamp)
+        return "";
+    const at = new Date(timestamp).getTime();
+    if (!Number.isFinite(at))
+        return "";
+    const deltaMs = Date.now() - at;
+    const minutes = Math.round(deltaMs / 60_000);
+    if (minutes < 1)
+        return "just now";
+    if (minutes < 60)
+        return `${minutes}m ago`;
+    const hours = Math.round(minutes / 60);
+    if (hours < 24)
+        return `${hours}h ago`;
+    return `${Math.round(hours / 24)}d ago`;
+}
+export function toContributorRows(items) {
+    return items.map((contributor) => ({
+        name: contributor.profile?.displayName ||
+            contributor.profile?.username ||
+            contributor.userUuid,
+        role: contributor.role ?? "",
+        tokens: formatNumber(contributor.tokens),
+        requests: formatNumber(contributor.requests),
+        sessions: contributor.sessionCount,
+        cost: formatCost(contributor.costTotal),
+        lastActive: relativeTime(contributor.lastActiveAt),
+    }));
+}
+export function toAppRankingRows(apps) {
+    return apps.map((app) => ({
+        title: app.title,
+        status: app.status,
+        views: formatNumber(app.viewCount),
+        id: app.appId,
+    }));
+}
+function hasCost(activity) {
+    return activity.summary.costTotal !== 0;
+}
+export function printActivityReport(activity) {
+    const showCost = hasCost(activity);
+    console.log(`\n  Summary (last ${activity.days} days):`);
+    table([activity.summary], [
+        { key: "totalTokens", label: "Tokens", format: formatNumber },
+        { key: "requestCount", label: "Requests", format: formatNumber },
+        ...(showCost ? [{ key: "costTotal", label: "Cost", format: formatCost }] : []),
+        { key: "successCount", label: "Success", format: formatNumber },
+        { key: "errorCount", label: "Errors", format: formatNumber },
+    ]);
+    if (activity.contributors.items.length > 0) {
+        console.log(`\n  Contributors (${activity.contributors.memberCount} members):`);
+        table(toContributorRows(activity.contributors.items), [
+            { key: "name", label: "Name" },
+            { key: "role", label: "Role" },
+            { key: "tokens", label: "Tokens" },
+            { key: "requests", label: "Requests" },
+            { key: "sessions", label: "Sessions" },
+            ...(showCost ? [{ key: "cost", label: "Cost" }] : []),
+            { key: "lastActive", label: "Last active" },
+        ]);
+    }
+    const { llmModels, generationModels, apps } = activity.rankings;
+    if (llmModels.length > 0) {
+        console.log("\n  Top LLM models:");
+        table(llmModels, [
+            { key: "model", label: "Model" },
+            { key: "provider", label: "Provider" },
+            { key: "totalTokens", label: "Tokens", format: formatNumber },
+            { key: "requestCount", label: "Requests", format: formatNumber },
+            ...(showCost ? [{ key: "costTotal", label: "Cost", format: formatCost }] : []),
+        ]);
+    }
+    if (generationModels.length > 0) {
+        console.log("\n  Top generation models:");
+        table(generationModels, [
+            { key: "model", label: "Model" },
+            { key: "provider", label: "Provider" },
+            { key: "requestCount", label: "Calls", format: formatNumber },
+            ...(showCost ? [{ key: "costTotal", label: "Cost", format: formatCost }] : []),
+        ]);
+    }
+    if (apps.length > 0) {
+        console.log("\n  Most viewed apps:");
+        table(toAppRankingRows(apps), [
+            { key: "title", label: "App" },
+            { key: "views", label: "Views" },
+            { key: "status", label: "Status" },
+            { key: "id", label: "ID" },
+        ]);
+    }
+}
+export function registerSpaceActivity(spacesCmd, dependencies = {}) {
+    spacesCmd
+        .command("activity [days]")
+        .description("Space activity overview: usage, contributors, rankings")
+        .option("--json", "Output as JSON")
+        .action(async (days, opts) => {
+        const spaceId = resolveSpace(spacesCmd);
+        let parsedDays;
+        try {
+            parsedDays = parseActivityDays(days);
+        }
+        catch (cause) {
+            if (cause instanceof InvalidSpaceActivityDaysError) {
+                return error(cause.message, cause.detail);
+            }
+            throw cause;
+        }
+        const client = dependencies.createClient?.() ?? createClient();
+        try {
+            const activity = await client.space(spaceId).activity.get(parsedDays);
+            if (jsonRequested(opts))
+                return outJson(activity);
+            printActivityReport(activity);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+}

package/dist/commands/spaces.js

@@ -8,6 +8,7 @@ import { createClient } from "../client.js";
 import { table, json as outJson, jsonRequested, ok, error, handleHttp, formatEpochMs } from "../output.js";
 import { resolveSpace } from "../space.js";
 import { registerSpaceCommerce } from "./space-commerce.js";
+import { registerSpaceActivity } from "./space-activity.js";
 import { registerSpaceInvitations } from "./space-invitations.js";
 import { registerSpaceTurns } from "./space-turns.js";
 const cliEnv = resolveCohubEnvironment();
@@ -677,6 +678,8 @@ export function registerSpaces(program) {
     });
     // ── spaces commerce ──
     registerSpaceCommerce(spacesCmd);
+    // ── spaces activity ──
+    registerSpaceActivity(spacesCmd);
     // ── spaces usage ──
     spacesCmd
         .command("usage [days]")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neta-art/cohub-cli",
-  "version": "6.1.3",
+  "version": "6.1.4",
   "description": "CLI for Cohub — spaces, sessions, and agent collaboration.",
   "type": "module",
   "license": "Apache-2.0",