@neta-art/cohub-cli 8.4.0 → 9.0.0

package/dist/self-update.js

@@ -38,9 +38,9 @@ const readState = () => {
         return {};
     }
 };
-const writeState = () => {
+const writeState = (state) => {
     mkdirSync(dirname(STATE_PATH), { recursive: true });
-    writeFileSync(STATE_PATH, `${JSON.stringify({ lastUpdatedAt: new Date().toISOString() }, null, 2)}\n`);
+    writeFileSync(STATE_PATH, `${JSON.stringify({ checkedAt: new Date().toISOString(), ...state }, null, 2)}\n`);
 };
 const readInstalledVersion = () => {
     try {
@@ -51,19 +51,35 @@ const readInstalledVersion = () => {
         return undefined;
     }
 };
+const parseVersion = (value) => {
+    const match = /^(\d+)\.(\d+)\.(\d+)(-.+)?$/.exec(value.trim());
+    if (!match)
+        return null;
+    const core = [Number(match[1]), Number(match[2]), Number(match[3])];
+    return { core, prerelease: Boolean(match[4]) };
+};
+export function isNewerVersion(candidate, installed) {
+    const next = parseVersion(candidate);
+    if (!next)
+        return false;
+    const current = installed === undefined ? null : parseVersion(installed);
+    if (!current)
+        return true;
+    const [major, minor, patch] = next.core;
+    const [installedMajor, installedMinor, installedPatch] = current.core;
+    const delta = major - installedMajor || minor - installedMinor || patch - installedPatch;
+    return delta === 0 ? current.prerelease && !next.prerelease : delta > 0;
+}
 export function resolveSelfUpdateResult(beforeVersion, afterVersion, updatedByPeer) {
     if (beforeVersion !== undefined && beforeVersion === afterVersion)
         return "current";
     return updatedByPeer ? "updated-by-peer" : "updated";
 }
 export const isCliSelfUpdateDue = () => {
-    const state = readState();
-    if (!state.lastUpdatedAt)
+    const checkedAt = Date.parse(readState().checkedAt ?? "");
+    if (!Number.isFinite(checkedAt))
         return true;
-    const lastUpdatedAt = Date.parse(state.lastUpdatedAt);
-    if (!Number.isFinite(lastUpdatedAt))
-        return true;
-    return Date.now() - lastUpdatedAt >= getIntervalMs();
+    return Date.now() - checkedAt >= getIntervalMs();
 };
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 const acquireLock = async (timeoutMs) => {
@@ -96,9 +112,9 @@ const acquireLock = async (timeoutMs) => {
 const releaseLock = () => {
     rmSync(LOCK_PATH, { recursive: true, force: true });
 };
-const runNpmUpdate = (timeoutMs) => {
+const runNpm = (args, timeoutMs) => {
     return new Promise((resolve, reject) => {
-        const child = spawn("npm", ["install", "-g", `${PACKAGE_NAME}@latest`, "--silent"], {
+        const child = spawn("npm", args, {
             stdio: ["ignore", "pipe", "pipe"],
             env: process.env,
         });
@@ -117,14 +133,14 @@ const runNpmUpdate = (timeoutMs) => {
         });
         child.on("close", (code, signal) => {
             clearTimeout(timer);
+            const stdout = Buffer.concat(stdoutChunks).toString().trim();
             if (code === 0) {
-                resolve();
+                resolve(stdout);
                 return;
             }
-            const stdout = Buffer.concat(stdoutChunks).toString().trim();
             const stderr = Buffer.concat(stderrChunks).toString().trim();
             const detail = [stderr, stdout].filter(Boolean).join("\n");
-            reject(new Error(`npm install -g ${PACKAGE_NAME}@latest failed${signal ? ` (${signal})` : code !== null ? ` (exit ${code})` : ""}${detail ? `:\n${detail}` : ""}`));
+            reject(new Error(`npm ${args.join(" ")} failed${signal ? ` (${signal})` : code !== null ? ` (exit ${code})` : ""}${detail ? `:\n${detail}` : ""}`));
         });
     });
 };
@@ -156,9 +172,29 @@ export async function ensureCliSelfUpdated() {
         if (!isCliSelfUpdateDue()) {
             return resolveSelfUpdateResult(beforeVersion, readInstalledVersion(), true);
         }
-        await runNpmUpdate(timeoutMs);
-        writeState();
-        return resolveSelfUpdateResult(beforeVersion, readInstalledVersion(), false);
+        // Reinstalling briefly removes the `cohub` bin, so only do it for a newer release.
+        let latestVersion;
+        try {
+            latestVersion = await runNpm(["view", `${PACKAGE_NAME}@latest`, "version"], timeoutMs);
+            if (!isNewerVersion(latestVersion, beforeVersion)) {
+                writeState({ installedVersion: beforeVersion, latestVersion, result: "current" });
+                return "current";
+            }
+            await runNpm(["install", "-g", `${PACKAGE_NAME}@${latestVersion}`, "--silent"], timeoutMs);
+        }
+        catch (error) {
+            writeState({
+                installedVersion: beforeVersion,
+                latestVersion,
+                result: "failed",
+                error: (error instanceof Error ? error.message : String(error)).slice(0, 500),
+            });
+            throw error;
+        }
+        const afterVersion = readInstalledVersion();
+        const result = resolveSelfUpdateResult(beforeVersion, afterVersion, false);
+        writeState({ installedVersion: afterVersion, latestVersion, result });
+        return result;
     }
     finally {
         releaseLock();

package/dist/space-files/limit.d.ts

@@ -0,0 +1,2 @@
+export type Limiter = <T>(task: () => Promise<T>) => Promise<T>;
+export declare function createLimiter(concurrency: number): Limiter;

package/dist/space-files/limit.js

@@ -0,0 +1,16 @@
+export function createLimiter(concurrency) {
+    let active = 0;
+    const waiting = [];
+    return async (task) => {
+        if (active >= concurrency)
+            await new Promise((resolve) => waiting.push(resolve));
+        active += 1;
+        try {
+            return await task();
+        }
+        finally {
+            active -= 1;
+            waiting.shift()?.();
+        }
+    };
+}

package/dist/space-files/operands.d.ts

@@ -0,0 +1,16 @@
+export type SpaceOperand = {
+    kind: "space";
+    space: string | null;
+    path: string;
+};
+export type LocalOperand = {
+    kind: "local";
+    path: string;
+};
+export type FileOperand = SpaceOperand | LocalOperand;
+export declare class InvalidFileOperandError extends Error {
+    name: string;
+}
+export declare function normalizeSpacePath(raw: string): string;
+export declare function parseSpaceFileOperand(raw: string): SpaceOperand;
+export declare function parseCopyOperand(raw: string, currentSpaceDeclared: boolean): FileOperand;

package/dist/space-files/operands.js

@@ -0,0 +1,33 @@
+import { posix, resolve } from "node:path";
+import { parseSpaceRef } from "@neta-art/cohub";
+export class InvalidFileOperandError extends Error {
+    name = "InvalidFileOperandError";
+}
+const WORKSPACE_ROOT = "/workspace";
+const isWorkspacePath = (path) => path === WORKSPACE_ROOT || path.startsWith(`${WORKSPACE_ROOT}/`);
+export function normalizeSpacePath(raw) {
+    let path = raw.trim();
+    if (isWorkspacePath(path))
+        path = path.slice(WORKSPACE_ROOT.length + 1);
+    else if (path.startsWith("/"))
+        throw new InvalidFileOperandError(`'${raw}' is not a Space path`);
+    const normalized = posix.normalize(path || ".").replace(/\/+$/, "");
+    return normalized === "." ? "" : normalized;
+}
+function parseSpacePrefix(raw) {
+    const colon = raw.indexOf(":");
+    if (colon <= 0)
+        return null;
+    const space = raw.slice(0, colon);
+    return parseSpaceRef(space) ? { kind: "space", space, path: normalizeSpacePath(raw.slice(colon + 1)) } : null;
+}
+export function parseSpaceFileOperand(raw) {
+    return parseSpacePrefix(raw) ?? { kind: "space", space: null, path: normalizeSpacePath(raw) };
+}
+export function parseCopyOperand(raw, currentSpaceDeclared) {
+    const space = parseSpacePrefix(raw);
+    if (space)
+        return space;
+    const local = !currentSpaceDeclared || (raw.startsWith("/") && !isWorkspacePath(raw));
+    return local ? { kind: "local", path: resolve(raw) } : { kind: "space", space: null, path: normalizeSpacePath(raw) };
+}

package/dist/space-files/transfer.d.ts

@@ -0,0 +1,53 @@
+import { type SpaceFsCopyResult, type SpaceFsCopyStats, type SpaceFsTreeResponse } from "@neta-art/cohub";
+import { type SpaceFiles } from "./upload.js";
+export type CopyOptions = {
+    recursive: boolean;
+    noClobber: boolean;
+    preserveTimestamps: boolean;
+};
+export declare class CopyAbortError extends Error {
+    name: string;
+}
+export declare const emptyCopyResult: () => SpaceFsCopyResult;
+export declare function mergeCopyResults(results: SpaceFsCopyResult[]): SpaceFsCopyResult;
+type SpaceNode = {
+    type: "dir";
+    tree: SpaceFsTreeResponse;
+} | {
+    type: "file";
+} | null;
+export declare function statSpacePath(files: SpaceFiles, path: string): Promise<SpaceNode>;
+export declare function checkDestination(input: {
+    sourceCount: number;
+    display: string;
+    stat: (path: string) => Promise<"dir" | "file" | null>;
+    path: string;
+    parent: string;
+}): Promise<boolean>;
+export declare const spaceNodeType: (files: SpaceFiles, path: string) => Promise<"dir" | "file" | null>;
+export declare const localNodeType: (path: string) => Promise<"dir" | "file" | null>;
+export declare function uploadToSpace(input: {
+    files: SpaceFiles;
+    sources: string[];
+    destination: string;
+    intoDirectory: boolean;
+    options: CopyOptions;
+    onProgress: (stats: SpaceFsCopyStats) => void;
+}): Promise<SpaceFsCopyResult>;
+export declare function downloadFromSpace(input: {
+    sources: Array<{
+        files: SpaceFiles;
+        path: string;
+    }>;
+    destination: string;
+    intoDirectory: boolean;
+    options: CopyOptions;
+    onProgress: (stats: SpaceFsCopyStats) => void;
+}): Promise<SpaceFsCopyResult>;
+export declare function copyLocal(input: {
+    sources: string[];
+    destination: string;
+    intoDirectory: boolean;
+    options: CopyOptions;
+}): Promise<SpaceFsCopyResult>;
+export {};

package/dist/space-files/transfer.js

@@ -0,0 +1,296 @@
+import { randomUUID } from "node:crypto";
+import { createWriteStream } from "node:fs";
+import { cp, lstat, mkdir, readdir, rename, rm, stat, utimes } from "node:fs/promises";
+import { dirname, join, posix } from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { UPLOAD_MAX_FILE_BYTES } from "@neta-art/cohub";
+import { createLimiter } from "./limit.js";
+import { uploadLocalFiles } from "./upload.js";
+export class CopyAbortError extends Error {
+    name = "CopyAbortError";
+}
+export const emptyCopyResult = () => ({
+    files: 0, dirs: 0, symlinks: 0, bytes: 0, paths: [], overwritten: 0, skipped: 0, errors: [],
+});
+export function mergeCopyResults(results) {
+    const merged = emptyCopyResult();
+    for (const result of results) {
+        for (const key of ["files", "dirs", "symlinks", "bytes", "overwritten", "skipped"])
+            merged[key] += result[key];
+        merged.paths.push(...result.paths);
+        merged.errors.push(...result.errors);
+    }
+    return merged;
+}
+const display = (path) => path || ".";
+const targetOf = (source, destination, intoDirectory, join) => {
+    const name = posix.basename(source);
+    return intoDirectory && name ? join(destination, name) : destination;
+};
+const joinSpacePath = (parent, name) => (parent ? `${parent}/${name}` : name);
+const lstatOrNull = (path) => lstat(path).catch(() => null);
+export async function statSpacePath(files, path) {
+    try {
+        return { type: "dir", tree: await files.list(path) };
+    }
+    catch (error) {
+        const { status, code } = error;
+        if (status === 404)
+            return null;
+        if (code === "not_a_directory")
+            return { type: "file" };
+        throw error;
+    }
+}
+export async function checkDestination(input) {
+    const node = await input.stat(input.path);
+    if (input.sourceCount > 1 && node !== "dir")
+        throw new CopyAbortError(`target '${input.display}' is not a directory`);
+    if (!node && input.parent !== input.path && (await input.stat(input.parent)) !== "dir") {
+        throw new CopyAbortError(`cannot create '${input.display}': No such file or directory`);
+    }
+    return node === "dir";
+}
+export const spaceNodeType = async (files, path) => (await statSpacePath(files, path))?.type ?? null;
+export const localNodeType = async (path) => {
+    const stats = await lstatOrNull(path);
+    return stats ? (stats.isDirectory() ? "dir" : "file") : null;
+};
+const isUploadableName = (name) => name.length > 0 && name.length <= 255 && name !== "." && name !== ".." && name.trim() === name &&
+    !/[<>:"/\\|?*]/.test(name) && ![...name].some((char) => char.charCodeAt(0) <= 0x1f);
+export async function uploadToSpace(input) {
+    const { files, options } = input;
+    const result = emptyCopyResult();
+    const fail = (path, code, message) => {
+        result.errors.push({ path, code, message });
+    };
+    const entries = [];
+    const walk = async (localPath, target, stats) => {
+        if (stats.isFile()) {
+            entries.push({ localPath, relativePath: target, size: stats.size });
+            return;
+        }
+        if (!stats.isDirectory()) {
+            result.skipped += 1;
+            return;
+        }
+        const names = await readdir(localPath);
+        await Promise.all(names.map(async (name) => {
+            const child = join(localPath, name);
+            const childStats = await stat(child).catch(() => null);
+            if (childStats)
+                await walk(child, joinSpacePath(target, name), childStats);
+        }));
+    };
+    for (const source of input.sources) {
+        const stats = await stat(source).catch(() => null);
+        if (!stats) {
+            fail(source, "path_not_found", `cannot stat '${source}': No such file or directory`);
+            continue;
+        }
+        if (stats.isDirectory() && !options.recursive) {
+            fail(source, "is_a_directory", `-r not specified; omitting directory '${source}'`);
+            continue;
+        }
+        const target = targetOf(source, input.destination, input.intoDirectory, joinSpacePath);
+        await walk(source, target, stats);
+        result.paths.push(target);
+    }
+    const parents = [...new Set(entries.map((entry) => posix.dirname(entry.relativePath)).map((dir) => (dir === "." ? "" : dir)))];
+    const limit = createLimiter(8);
+    const existing = new Map();
+    await Promise.all(parents.map((dir) => limit(async () => {
+        const node = await statSpacePath(files, dir);
+        if (node?.type === "dir")
+            for (const entry of node.tree.entries)
+                existing.set(entry.path, entry.type);
+    })));
+    const upload = entries.filter((entry) => {
+        const current = existing.get(entry.relativePath);
+        if (current === "dir") {
+            fail(entry.relativePath, "is_a_directory", `cannot overwrite directory '${entry.relativePath}' with non-directory`);
+            return false;
+        }
+        if (current && options.noClobber) {
+            result.skipped += 1;
+            return false;
+        }
+        if (!entry.relativePath.split("/").every(isUploadableName)) {
+            fail(entry.relativePath, "name_invalid", `cannot upload '${entry.localPath}': unsupported file name`);
+            return false;
+        }
+        if (entry.size > UPLOAD_MAX_FILE_BYTES) {
+            fail(entry.relativePath, "file_too_large", `cannot upload '${entry.localPath}': file exceeds the upload size limit`);
+            return false;
+        }
+        if (current)
+            result.overwritten += 1;
+        return true;
+    });
+    const progress = { files: 0, dirs: 0, symlinks: 0, bytes: 0 };
+    await uploadLocalFiles(files, upload, {
+        onUploaded: (entry) => {
+            progress.files += 1;
+            progress.bytes += entry.size;
+            input.onProgress(progress);
+        },
+    });
+    return { ...result, ...progress };
+}
+export async function downloadFromSpace(input) {
+    const { options } = input;
+    const result = emptyCopyResult();
+    const fail = (path, code, message) => {
+        result.errors.push({ path, code, message });
+    };
+    const limit = createLimiter(6);
+    const report = () => input.onProgress(result);
+    const downloadFile = async (files, path, target, mtimeMs) => {
+        const current = await lstatOrNull(target);
+        if (current?.isDirectory())
+            return fail(target, "is_a_directory", `cannot overwrite directory '${target}' with non-directory`);
+        if (current && options.noClobber) {
+            result.skipped += 1;
+            return;
+        }
+        const temp = join(dirname(target), `.cohub-download.${randomUUID().slice(0, 8)}`);
+        try {
+            const bytes = await limit(async () => {
+                const { response } = await files.open(path);
+                let written = 0;
+                if (response.body) {
+                    const body = Readable.fromWeb(response.body);
+                    body.on("data", (chunk) => {
+                        written += chunk.length;
+                    });
+                    await pipeline(body, createWriteStream(temp, { flags: "wx" }));
+                }
+                else {
+                    await pipeline(Readable.from([]), createWriteStream(temp, { flags: "wx" }));
+                }
+                return written;
+            });
+            if (options.preserveTimestamps && mtimeMs !== undefined)
+                await utimes(temp, new Date(), new Date(mtimeMs));
+            await rename(temp, target);
+            result.files += 1;
+            result.bytes += bytes;
+            if (current)
+                result.overwritten += 1;
+            report();
+        }
+        catch (error) {
+            await rm(temp, { force: true });
+            fail(target, "download_failed", `cannot download '${display(path)}': ${error.message}`);
+        }
+    };
+    const downloadDir = async (files, tree, target) => {
+        const current = await lstatOrNull(target);
+        if (current && !current.isDirectory()) {
+            return fail(target, "not_a_directory", `cannot overwrite non-directory '${target}' with directory '${display(tree.path)}'`);
+        }
+        if (!current)
+            await mkdir(target);
+        result.dirs += 1;
+        if (tree.entries.length >= 1000) {
+            fail(target, "listing_truncated", `cannot copy all of '${display(tree.path)}': directories with 1000 or more entries are not fully listed`);
+        }
+        await Promise.all(tree.entries.map(async (entry) => {
+            const child = join(target, entry.name);
+            if (entry.type === "file")
+                return downloadFile(files, entry.path, child, entry.mtimeMs);
+            if (entry.type === "symlink") {
+                result.skipped += 1;
+                return;
+            }
+            const node = await limit(() => statSpacePath(files, entry.path));
+            if (node?.type === "dir")
+                await downloadDir(files, node.tree, child);
+        }));
+    };
+    for (const { files, path } of input.sources) {
+        const node = await statSpacePath(files, path);
+        if (!node) {
+            fail(path, "path_not_found", `cannot stat '${display(path)}': No such file or directory`);
+            continue;
+        }
+        if (node.type === "dir" && !options.recursive) {
+            fail(path, "is_a_directory", `-r not specified; omitting directory '${display(path)}'`);
+            continue;
+        }
+        const target = targetOf(path, input.destination, input.intoDirectory, join);
+        if (node.type === "dir") {
+            await downloadDir(files, node.tree, target);
+        }
+        else {
+            const parent = options.preserveTimestamps ? await statSpacePath(files, posix.dirname(path) === "." ? "" : posix.dirname(path)) : null;
+            const mtimeMs = parent?.type === "dir" ? parent.tree.entries.find((entry) => entry.path === path)?.mtimeMs : undefined;
+            await downloadFile(files, path, target, mtimeMs);
+        }
+        result.paths.push(target);
+    }
+    return result;
+}
+export async function copyLocal(input) {
+    const { options } = input;
+    const result = emptyCopyResult();
+    const fail = (path, code, message) => {
+        result.errors.push({ path, code, message });
+    };
+    for (const source of input.sources) {
+        const stats = await lstatOrNull(source);
+        if (!stats) {
+            fail(source, "path_not_found", `cannot stat '${source}': No such file or directory`);
+            continue;
+        }
+        if (stats.isDirectory() && !options.recursive) {
+            fail(source, "is_a_directory", `-r not specified; omitting directory '${source}'`);
+            continue;
+        }
+        const target = targetOf(source, input.destination, input.intoDirectory, join);
+        if (target === source) {
+            fail(source, "same_file", `'${source}' and '${target}' are the same file`);
+            continue;
+        }
+        if (stats.isDirectory() && target.startsWith(`${source}/`)) {
+            fail(source, "copy_into_itself", `cannot copy a directory, '${source}', into itself, '${target}'`);
+            continue;
+        }
+        try {
+            await cp(source, target, {
+                recursive: true,
+                force: !options.noClobber,
+                errorOnExist: false,
+                preserveTimestamps: options.preserveTimestamps,
+                verbatimSymlinks: true,
+                filter: async (from, to) => {
+                    const node = await lstat(from);
+                    if (node.isDirectory()) {
+                        result.dirs += 1;
+                        return true;
+                    }
+                    const existing = await lstatOrNull(to);
+                    if (existing && options.noClobber) {
+                        result.skipped += 1;
+                        return false;
+                    }
+                    if (existing)
+                        result.overwritten += 1;
+                    if (node.isSymbolicLink())
+                        result.symlinks += 1;
+                    else {
+                        result.files += 1;
+                        result.bytes += node.size;
+                    }
+                    return true;
+                },
+            });
+            result.paths.push(target);
+        }
+        catch (error) {
+            fail(target, "copy_failed", `cannot copy '${source}': ${error.message}`);
+        }
+    }
+    return result;
+}

package/dist/space-files/upload.d.ts

@@ -0,0 +1,14 @@
+import { type CohubHttpClient, type SpaceFsUploadEntry } from "@neta-art/cohub";
+export type SpaceFiles = ReturnType<CohubHttpClient["space"]>["files"];
+export type LocalUploadEntry = {
+    localPath: string;
+    relativePath: string;
+    size: number;
+};
+export declare function uploadLocalFiles(files: SpaceFiles, entries: LocalUploadEntry[], options?: {
+    targetDir?: string;
+    onUploaded?: (entry: LocalUploadEntry) => void;
+}): Promise<{
+    uploaded: SpaceFsUploadEntry[];
+    uploadIds: string[];
+}>;

package/dist/space-files/upload.js

@@ -0,0 +1,53 @@
+import { randomUUID } from "node:crypto";
+import { UPLOAD_MAX_BATCH_BYTES, UPLOAD_MAX_BATCH_FILES, } from "@neta-art/cohub";
+import { putLocalFile } from "../http-put.js";
+import { createLimiter } from "./limit.js";
+const PUT_CONCURRENCY = 4;
+function batches(entries) {
+    const result = [];
+    let batch = [];
+    let bytes = 0;
+    for (const entry of entries) {
+        if (batch.length > 0 && (batch.length >= UPLOAD_MAX_BATCH_FILES || bytes + entry.size > UPLOAD_MAX_BATCH_BYTES)) {
+            result.push(batch);
+            batch = [];
+            bytes = 0;
+        }
+        batch.push(entry);
+        bytes += entry.size;
+    }
+    if (batch.length > 0)
+        result.push(batch);
+    return result;
+}
+export async function uploadLocalFiles(files, entries, options = {}) {
+    const uploaded = [];
+    const uploadIds = [];
+    const limit = createLimiter(PUT_CONCURRENCY);
+    for (const batch of batches(entries)) {
+        const byId = new Map(batch.map((entry) => [randomUUID(), entry]));
+        const plan = await files.createUpload({
+            destination: { kind: "workspace", targetDir: options.targetDir },
+            entries: [...byId].map(([id, entry]) => ({
+                id,
+                name: entry.relativePath.split("/").at(-1) ?? entry.relativePath,
+                relativePath: entry.relativePath,
+                size: entry.size,
+                mimeType: null,
+            })),
+        });
+        await Promise.all(plan.entries.map((item) => limit(async () => {
+            const entry = byId.get(item.id);
+            if (!entry)
+                throw new Error(`Missing upload entry: ${item.id}`);
+            if (item.uploadUrl) {
+                await putLocalFile({ url: item.uploadUrl, filePath: entry.localPath, size: entry.size, headers: item.headers, label: entry.relativePath });
+            }
+            options.onUploaded?.(entry);
+        })));
+        const result = await files.completeUpload(plan.uploadId, { entries: plan.entries.map((item) => ({ id: item.id })) });
+        uploaded.push(...result.uploaded);
+        uploadIds.push(plan.uploadId);
+    }
+    return { uploaded, uploadIds };
+}

package/dist/space.d.ts

@@ -1,4 +1,9 @@
 import type { Command } from "commander";
+export declare class SpaceTargetError extends Error {
+    readonly detail?: string | undefined;
+    name: string;
+    constructor(message: string, detail?: string | undefined);
+}
 /**
  * Cache key aligned with auth: execution token is exclusive (same as
  * `resolveAccessToken`) and never falls back to a local Logto session.
@@ -12,29 +17,26 @@ export declare function identityKeyFrom(input: {
 }): string | null;
 export declare function currentIdentityKey(): string | null;
 /** Exported for tests; production always uses `CACHE_PATH`. */
-export declare function readDefaultSpaceCache(path: string, key: string, now?: number): string | null;
-export declare function clearDefaultSpaceCache(): void;
+export declare function readHomeSpaceCache(path: string, key: string, now?: number): string | null;
+export declare function clearHomeSpaceCache(): void;
 /** Explicit target from `-s/--space` (any ancestor) or `COHUB_SPACE_ID`, else null. */
 export declare function explicitSpace(program: Command): string | null;
-/**
- * Resolve the user's home space when no target is given. Cached locally per
- * identity so repeated invocations skip the network entirely, and memoized
- * in-process so preAction hooks and actions share a single lookup.
- * Network and auth failures propagate so callers can report them faithfully.
- */
-export declare function resolveDefaultSpace(): Promise<string | null>;
+/** Cached per identity and memoized per process. */
+export declare function resolveHomeSpace(): Promise<string>;
+export declare function resolveSpaceRef(value: string): Promise<string>;
+export declare function failSpaceTarget(e: unknown): never;
 /** Shared exit for commands that need a space but resolved none. */
 export declare function missingSpaceError(): never;
-/**
- * Resolve a Space from an optional explicit target, the current directory
- * binding, and finally the user's Home Space.
- */
 export declare function resolveBoundSpace(options?: {
     cwd?: string;
     bindingsPath?: string;
 }): Promise<string | null>;
-export declare function resolveSpaceTarget(target?: string | null, options?: {
+export type SpaceTargetOptions = {
+    /** Only for commands that start new work. */
+    home?: boolean;
     cwd?: string;
     bindingsPath?: string;
-}): Promise<string>;
-export declare function resolveSpace(program: Command): Promise<string>;
+};
+/** Explicit target or `COHUB_SPACE_ID`, then the directory binding, then Home when allowed. */
+export declare function resolveSpaceTarget(target?: string | null, options?: SpaceTargetOptions): Promise<string>;
+export declare function resolveSpace(command: Command, options?: Pick<SpaceTargetOptions, "home">): Promise<string>;