cloudtifact 0.2.3 → 0.2.4

package/dist/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import fs, { createWriteStream, existsSync, lstatSync, realpathSync, statSync, watch } from "node:fs";
+import fs, { createWriteStream, existsSync, lstatSync, readFileSync, realpathSync, statSync, watch } from "node:fs";
 import { chmod, mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -6013,6 +6013,18 @@ const auditActionSchema = _enum([
 	"space.updated",
 	"space.moved",
 	"space.deleted",
+	"space.archived",
+	"space.unarchived",
+	"space.trashed",
+	"space.restored",
+	"page.added",
+	"space.filed",
+	"folder.created",
+	"folder.renamed",
+	"folder.moved",
+	"folder.deleted",
+	"folder.restored",
+	"space.merged",
 	"space.link_changed",
 	"space.person_added",
 	"space.person_changed",
@@ -6045,6 +6057,132 @@ const listAuditOutput = object({
 	next: number$1().nullable(),
 	nextId: string().nullable().optional()
 });
+/**
+* GET /v1/live-spaces, read only for what the CLI shows (Shared with me): the spaces you can open, in your workspaces
+* and the ones people added you to elsewhere. The full shape is in cloud-contract.
+*/
+const listOpenableSpacesOutput = object({ liveSpaces: array(object({
+	id: string(),
+	name: string(),
+	workspace: workspaceSchema,
+	url: string(),
+	createdBy: string().nullable().optional(),
+	lastActivityAt: number$1().nullable()
+})) });
+const activityActionSchema = _enum([
+	"space.created",
+	"space.archived",
+	"space.unarchived",
+	"space.trashed",
+	"space.restored",
+	"page.added",
+	"space.filed",
+	"folder.created",
+	"folder.renamed",
+	"folder.moved",
+	"folder.deleted",
+	"folder.restored",
+	"space.merged"
+]);
+const activityFolderSchema = object({
+	id: string(),
+	name: string()
+});
+const activityEventSchema = object({
+	id: string(),
+	action: activityActionSchema,
+	actor: userSchema.nullable(),
+	via: string().nullable(),
+	/** The space it was done to, name as it reads now. Null only for folder.* events (v=2). */
+	space: object({
+		id: string(),
+		name: string()
+	}).nullable(),
+	/** page.added: the page's folder in the space ("pricing-d/") and its title. */
+	page: object({
+		path: string(),
+		title: string().nullable()
+	}).nullable(),
+	/** folder.*: the folder, name as it reads now (folder.renamed: the name it got). */
+	folder: activityFolderSchema.nullable().optional(),
+	/**
+	* space.filed and folder.moved: where it was and where it went (null: the top level). folder.renamed: the names.
+	* space.merged: the space merged in.
+	*/
+	from: activityFolderSchema.nullable().optional(),
+	to: activityFolderSchema.nullable().optional(),
+	/** Set when this was itself an Undo: the id of the event it undid. */
+	undoes: string().nullable(),
+	/** Whether the caller can undo it now: it's still the way it left things, and they may do the opposite. */
+	canUndo: boolean(),
+	/** Someone already undid it (an event below it in the list says so). */
+	undone: boolean(),
+	createdAt: number$1()
+});
+object({
+	/** Only what this person did (their handle). */
+	person: string().max(64).optional(),
+	before: number().int().positive().optional(),
+	beforeId: string().max(64).optional(),
+	limit: number().int().min(1).max(100).default(50),
+	/** 2: include folder events (space.filed, folder.*), whose space may be null. Omitted: only ACTIVITY_V1_ACTIONS. */
+	v: number().int().optional()
+});
+const listActivityOutput = object({
+	events: array(activityEventSchema),
+	next: number$1().nullable(),
+	nextId: string().nullable()
+});
+const undoActivityOutput = object({ event: activityEventSchema });
+/** "archived “Q4 board pack”", for "Jack (with Claude) archived “Q4 board pack”" (byPerson). */
+function describeActivity(e) {
+	const name = `“${e.space?.name ?? "a space"}”`;
+	const folder = `the folder “${e.folder?.name ?? "folder"}”`;
+	const place = (f) => f ? `“${f.name}”` : "the top level";
+	switch (e.action) {
+		case "space.created": return `made ${name}`;
+		case "space.archived": return `archived ${name}`;
+		case "space.unarchived": return `brought ${name} back from the archive`;
+		case "space.trashed": return `moved ${name} to the Trash`;
+		case "space.restored": return `restored ${name} from the Trash`;
+		case "page.added": return e.undoes ? `took the page “${e.page?.title ?? e.page?.path ?? "page"}” out of ${name}` : `added the page “${e.page?.title ?? e.page?.path ?? "page"}” to ${name}`;
+		case "space.filed": return e.to ? `moved ${name} to “${e.to.name}”` : `moved ${name} to the top level`;
+		case "folder.created": return `made ${folder}`;
+		case "folder.renamed": return `renamed the folder “${e.from?.name ?? "folder"}” to “${e.to?.name ?? e.folder?.name ?? "folder"}”`;
+		case "folder.moved": return e.to ? `moved ${folder} into ${place(e.to)}` : `moved ${folder} to the top level`;
+		case "folder.deleted": return `removed ${folder} (what was in it moved up a level)`;
+		case "folder.restored": return `brought back ${folder}`;
+		case "space.merged": return e.undoes ? `took “${e.from?.name ?? "a space"}” back out of ${name}` : `merged “${e.from?.name ?? "a space"}” into ${name} as a page`;
+	}
+}
+/** A folder's name: one line, no "/" (paths like "Product plans/Pricing" are names joined by "/"). */
+const folderNameSchema = string().trim().min(1).max(80).refine((n) => !n.includes("/"), "a folder name can't have a / in it");
+const folderDescriptionSchema = string().trim().max(300);
+const folderSchema = object({
+	id: string(),
+	parentId: string().nullable(),
+	name: string(),
+	/** One line people and agents read before filing something here. */
+	description: string().nullable(),
+	/** Its names from the top, joined by "/": "Product plans/Pricing". */
+	path: string(),
+	/** Spaces directly inside it that aren't archived or in the Trash. */
+	spaces: number$1().int(),
+	createdAt: number$1()
+});
+const listFoldersOutput = object({ folders: array(folderSchema) });
+object({
+	name: folderNameSchema,
+	parentId: string().max(64).nullable().optional(),
+	description: folderDescriptionSchema.nullable().optional()
+});
+object({
+	name: folderNameSchema.optional(),
+	description: folderDescriptionSchema.nullable().optional(),
+	/** Move it inside another folder (null: to the top level). A folder can't go inside itself. */
+	parentId: string().max(64).nullable().optional()
+});
+object({ folderId: string().max(64).nullable() });
 const viewersSchema = object({
 	files: boolean(),
 	history: boolean(),
@@ -6084,12 +6222,55 @@ const spaceSchema = object({
 	createdAt: number$1(),
 	createdBy: string().optional(),
 	updatedAt: number$1().nullable().optional(),
-	snapshotUrl: string().nullable().optional()
+	snapshotUrl: string().nullable().optional(),
+	archivedAt: number$1().nullable().optional(),
+	/** The project its latest version belongs to, when the client said (versionSchema.project). */
+	project: string().nullable().optional(),
+	deletedAt: number$1().nullable().optional(),
+	favorite: number$1().int().nullable().optional(),
+	openedAt: number$1().nullable().optional(),
+	/** The folder it's listed in (folderSchema), or null: the workspace's top level. Missing from older servers. */
+	folderId: string().nullable().optional(),
+	/** Tidy up merged it into another space as a page: that space and the page's folder there. Its links open it. */
+	mergedInto: object({
+		id: string(),
+		page: string()
+	}).nullable().optional()
+});
+const tidySpaceSchema = object({
+	id: string(),
+	name: string(),
+	/** The latest version (0: nothing published yet) and when anything last changed. */
+	latestVersion: number$1().int(),
+	updatedAt: number$1(),
+	/** Can go into another space as a page: no comments, uploads or data of its own that the page would leave behind. */
+	canMerge: boolean()
+});
+const tidyOutput = object({
+	lookAlikes: array(object({
+		/** What they share, as people read it ("Pricing proposal"). */
+		topic: string(),
+		/** The space the others go into: the first one made, so its link (and its comments) stay. */
+		into: tidySpaceSchema,
+		spaces: array(tidySpaceSchema)
+	})),
+	finished: array(object({
+		space: tidySpaceSchema,
+		/** "Nothing new in 45 days", "Empty for 9 days". */
+		why: string()
+	}))
+});
+object({ into: string().max(64) });
+const mergeSpaceOutput = object({
+	space: spaceSchema,
+	page: string()
 });
 object({
 	workspace: workspaceSlugSchema,
 	name: string().min(1).max(100),
-	visibility: visibilitySchema.default("public")
+	visibility: visibilitySchema.default("public"),
+	/** List it in this folder of the workspace (folderSchema.id); omitted: the top level. */
+	folderId: string().max(64).optional()
 });
 object({
 	name: string().min(1).max(100).optional(),
@@ -6178,8 +6359,35 @@ const visitorsOutput = object({
 		referrer: string().nullable()
 	}))
 });
-object({ workspace: workspaceSlugSchema.optional() });
+const spaceStatusSchema = _enum([
+	"active",
+	"archived",
+	"trash"
+]);
+object({
+	workspace: workspaceSlugSchema.optional(),
+	status: spaceStatusSchema.default("active")
+});
+object({ spaces: array(spaceIdSchema).max(500) });
+const favoritesOutput = object({ spaces: array(spaceIdSchema) });
 const listSpacesOutput = object({ spaces: array(spaceSchema) });
+object({
+	q: string().trim().min(1).max(200),
+	workspace: workspaceSlugSchema.optional(),
+	limit: number().int().min(1).max(50).default(10)
+});
+const findSpacesOutput = object({ spaces: array(spaceSchema.extend({
+	/** Pages (HTML and Markdown files) in its latest version. */
+	pages: number$1().int(),
+	/** 0 to 1. */
+	score: number$1(),
+	/** Close enough to publish into without being told (topicMatch in find.ts). */
+	strong: boolean(),
+	/** The page whose title matched better than the space's name, if any. */
+	page: string().nullable()
+})) });
+/** A project's name as a client sends it: the repo folder's name or what the person typed. */
+const projectNameSchema = string().trim().min(1).max(100);
 const MAX_FILE_BYTES = 16777216;
 const manifest = array(object({
 	path: filePathSchema,
@@ -6191,7 +6399,15 @@ const diffSchema = object({
 	changed: array(string()),
 	removed: array(string())
 });
-object({ files: manifest });
+/**
+* A folder inside the space ("pricing-d/") that these files replace, keeping every file outside it: how a page is
+* added to a space that holds other pages. Every path must start with it. Omitted: the files are the whole space.
+*/
+const pushPrefixSchema = string().max(100).regex(/^[a-z0-9][a-z0-9._-]*(\/[a-z0-9][a-z0-9._-]*)*\/$/, "a folder like pricing-d/, lowercase, ending in /");
+object({
+	files: manifest,
+	prefix: pushPrefixSchema.optional()
+});
 const pushPlanOutput = object({
 	baseVersion: number$1().int(),
 	missing: array(sha256Schema),
@@ -6200,12 +6416,18 @@ const pushPlanOutput = object({
 object({
 	files: manifest,
 	message: string().max(500).optional(),
-	baseVersion: number$1().int().min(0).optional()
+	baseVersion: number$1().int().min(0).optional(),
+	prefix: pushPrefixSchema.optional(),
+	project: projectNameSchema.optional()
 });
 const versionSchema = object({
 	number: number$1().int(),
 	message: string().nullable(),
 	pushedBy: userSchema,
+	/** The tool the person used (agentLabel); null: the website. Missing from older servers. */
+	via: string().nullable().optional(),
+	/** The project it belongs to, when the client said. */
+	project: string().nullable().optional(),
 	added: number$1().int(),
 	changed: number$1().int(),
 	removed: number$1().int(),
@@ -6244,6 +6466,7 @@ const fileHistoryOutput = object({ entries: array(object({
 	]),
 	sha256: string().nullable(),
 	pushedBy: userSchema,
+	via: string().nullable().optional(),
 	createdAt: number$1()
 })) });
 const headOutput = object({
@@ -6531,6 +6754,11 @@ const AGENT_NAMES = {
 };
 /** "claude-code" -> "Claude Code"; unknown ids are shown as-is. */
 const agentLabel = (via) => AGENT_NAMES[via] ?? via;
+/**
+* Whether `via` is the person themselves rather than an agent acting for them: the website (null), the CLI typed by
+* hand ("cli"), or our own mobile app ("mobile"). Their reads count as reading, and notifications don't add "via ...".
+*/
+const isPersonVia = (via) => via === null || via === "cli" || via === "mobile";
 const discordId = string().regex(/^\d{5,25}$/);
 const discordName = string().trim().min(1).max(100);
 const discordPersonSchema = object({
@@ -6729,6 +6957,13 @@ const discordChatOutput = object({
 	liveUrl: string().optional()
 });
 object({ messages: array(discordMessageSchema) });
+/**
+* A person and the tool they used, for lines that say who did something: "Jack (with Claude)". The person is always
+* the subject; their own hands (the website, the CLI typed by hand, the mobile app) add nothing.
+*/
+function byPerson(name, via) {
+	return via && !isPersonVia(via) ? `${name} (with ${agentLabel(via)})` : name;
+}
 //#endregion
 //#region ../contract/src/sources.ts
 const MAX_SOURCE_BYTES = 26214400;
@@ -7216,11 +7451,33 @@ function createClient(opts) {
 		removeMember: (slug, handle) => call("DELETE", `/v1/workspaces/${enc$3(slug)}/members/${enc$3(handle)}`, null),
 		acceptInvite: (slug) => call("POST", `/v1/workspaces/${enc$3(slug)}/accept`, null),
 		declineInvite: (slug) => call("POST", `/v1/workspaces/${enc$3(slug)}/decline`, null),
-		listSpaces: (query = {}) => call("GET", `/v1/spaces${query.workspace ? `?workspace=${enc$3(query.workspace)}` : ""}`, listSpacesOutput),
+		listSpaces: (query = {}) => {
+			const params = new URLSearchParams();
+			if (query.workspace) params.set("workspace", query.workspace);
+			if (query.status && query.status !== "active") params.set("status", query.status);
+			const qs = params.toString();
+			return call("GET", `/v1/spaces${qs ? `?${qs}` : ""}`, listSpacesOutput);
+		},
+		findSpaces: (query) => {
+			const params = new URLSearchParams({ q: query.q });
+			if (query.workspace) params.set("workspace", query.workspace);
+			if (query.limit) params.set("limit", String(query.limit));
+			return call("GET", `/v1/spaces/find?${params}`, findSpacesOutput);
+		},
 		createSpace: (input) => call("POST", "/v1/spaces", spaceSchema, input),
 		getSpace: (id) => call("GET", space(id), spaceSchema),
 		updateSpace: (id, input) => call("PATCH", space(id), spaceSchema, input),
-		deleteSpace: (id) => call("DELETE", space(id), null),
+		deleteSpace: (id, opts = {}) => call("DELETE", `${space(id)}${opts.forever ? "?forever=1" : ""}`, null),
+		restoreSpace: (id) => call("POST", `${space(id)}/restore`, spaceSchema),
+		archiveSpace: (id) => call("POST", `${space(id)}/archive`, spaceSchema),
+		unarchiveSpace: (id) => call("POST", `${space(id)}/unarchive`, spaceSchema),
+		favoriteSpace: (id) => call("PUT", `${space(id)}/favorite`, null),
+		fileSpace: (id, folderId) => call("PUT", `${space(id)}/folder`, spaceSchema, { folderId }),
+		/** Puts this space into another as a page (Tidy up); it's archived and its links open the page there. */
+		mergeSpace: (id, into) => call("POST", `${space(id)}/merge`, mergeSpaceOutput, { into }),
+		unfavoriteSpace: (id) => call("DELETE", `${space(id)}/favorite`, null),
+		orderFavorites: (input) => call("PUT", "/v1/me/favorites", favoritesOutput, input),
+		openedSpace: (id) => call("POST", `${space(id)}/opened`, null),
 		moveSpace: (id, input) => call("POST", `${space(id)}/move`, moveSpaceOutput, input),
 		head: (id) => call("GET", `${space(id)}/head`, headOutput),
 		unlockSpace: (id, input) => call("POST", `${space(id)}/unlock`, unlockSpaceOutput, input),
@@ -7326,6 +7583,22 @@ function createClient(opts) {
 		listDiscordLinks: (spaceId) => call("GET", `/v1/spaces/${enc$3(spaceId)}/discord`, listDiscordLinksOutput),
 		discordChat: (spaceId, threadId, all = false) => call("GET", `/v1/spaces/${enc$3(spaceId)}/discord/${enc$3(threadId)}${all ? "?all=1" : ""}`, discordChatOutput),
 		unlinkDiscordThread: (spaceId, threadId) => send("DELETE", `/v1/spaces/${enc$3(spaceId)}/discord/${enc$3(threadId)}`),
+		listOpenableSpaces: () => call("GET", "/v1/live-spaces", listOpenableSpacesOutput),
+		listActivity: (slug, query = {}) => {
+			const q = new URLSearchParams({ v: "2" });
+			if (query.person) q.set("person", query.person);
+			if (query.before) q.set("before", String(query.before));
+			if (query.before && query.beforeId) q.set("beforeId", query.beforeId);
+			if (query.limit) q.set("limit", String(query.limit));
+			return call("GET", `/v1/workspaces/${enc$3(slug)}/activity?${q}`, listActivityOutput);
+		},
+		listFolders: (slug) => call("GET", `/v1/workspaces/${enc$3(slug)}/folders`, listFoldersOutput),
+		/** Tidy up: your look-alike spaces that could be one, and the ones that look finished. */
+		tidy: (slug) => call("GET", `/v1/workspaces/${enc$3(slug)}/tidy`, tidyOutput),
+		createFolder: (slug, input) => call("POST", `/v1/workspaces/${enc$3(slug)}/folders`, folderSchema, input),
+		updateFolder: (slug, id, input) => call("PATCH", `/v1/workspaces/${enc$3(slug)}/folders/${enc$3(id)}`, folderSchema, input),
+		deleteFolder: (slug, id) => call("DELETE", `/v1/workspaces/${enc$3(slug)}/folders/${enc$3(id)}`, null),
+		undoActivity: (slug, eventId) => call("POST", `/v1/workspaces/${enc$3(slug)}/activity/${enc$3(eventId)}/undo`, undoActivityOutput),
 		listAudit: (slug, query = {}) => {
 			const q = new URLSearchParams();
 			if (query.before) q.set("before", String(query.before));
@@ -7337,6 +7610,82 @@ function createClient(opts) {
 	};
 }
 new TextEncoder();
+new Set("a an and the of for to in on at by with from new draft copy final v1 v2 v3 page pages html index untitled my our".split(" "));
+/** A folder name for a page added to a space: "Pricing proposal D.html" → "pricing-proposal-d". */
+function pageSlug(text) {
+	return text.toLowerCase().normalize("NFKD").replace(/[̀-ͯ]/g, "").replace(/\.html?$/, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60).replace(/-+$/, "") || "page";
+}
+//#endregion
+//#region ../contract/src/folders.ts
+const norm = (s) => s.trim().toLowerCase().replace(/\s+/g, " ");
+const parts = (path) => path.split("/").map((p) => p.trim()).filter(Boolean);
+/** True for "/" and "": the top level, outside every folder. Words like "top" are folder names (one may be called Top). */
+const isTopLevel = (path) => ["", "/"].includes(norm(path));
+/**
+* The folder a path names: its id, its whole path (any case), or a name only one folder has. Null when none does or
+* when a bare name fits several (say which with the whole path).
+*/
+function findFolder(folders, path) {
+	const byId = folders.find((f) => f.id === path.trim());
+	if (byId) return byId;
+	const want = parts(path).map(norm).join("/");
+	const exact = folders.find((f) => norm(f.path) === want);
+	if (exact) return exact;
+	if (want.includes("/")) return null;
+	const named = folders.filter((f) => norm(f.name) === want);
+	return named.length === 1 ? named[0] ?? null : null;
+}
+/** Folders whose path looks like what was typed, best first: for "no folder called …, did you mean …". */
+function closeFolders(folders, path, limit = 3) {
+	const words = norm(path).split(/[\s/]+/).filter(Boolean);
+	return folders.map((f) => {
+		const p = norm(f.path);
+		return {
+			f,
+			score: words.filter((w) => p.includes(w)).length + (p.includes(norm(path)) ? 2 : 0)
+		};
+	}).filter((x) => x.score > 0).sort((a, b) => b.score - a.score || a.f.path.length - b.f.path.length).slice(0, limit).map((x) => x.f);
+}
+/** The message when a path names no folder: close matches, and how to make it. */
+function noFolderMessage(folders, path, make) {
+	const near = closeFolders(folders, path);
+	const named = folders.filter((f) => norm(f.name) === norm(path));
+	if (named.length > 1) return `More than one folder is called "${path.trim()}": ${named.map((f) => `"${f.path}"`).join(", ")}. Give the whole path.`;
+	return [
+		`No folder called "${path.trim()}".`,
+		near.length ? `Close: ${near.map((f) => `"${f.path}"`).join(", ")}.` : "",
+		`To make it: ${make}`
+	].filter(Boolean).join(" ");
+}
+/**
+* Makes the folders a path names that don't exist yet, top down ("Deals/Enterprise" makes Deals if needed, then
+* Enterprise in it), and returns the last one, plus which were new.
+*/
+async function ensureFolderPath(client, slug, path, description) {
+	let folders = (await client.listFolders(slug)).folders;
+	const names = parts(path);
+	if (!names.length) throw new Error("Give the folder a name.");
+	const made = [];
+	let parent = null;
+	for (const [i, name] of names.entries()) {
+		const sofar = names.slice(0, i + 1).map(norm).join("/");
+		let at = folders.find((f) => norm(f.path) === sofar) ?? null;
+		if (!at) {
+			at = await client.createFolder(slug, {
+				name,
+				parentId: parent?.id ?? null,
+				...i === names.length - 1 && description ? { description } : {}
+			});
+			made.push(at);
+			folders = [...folders, at];
+		}
+		parent = at;
+	}
+	return {
+		folder: parent,
+		made
+	};
+}
 //#endregion
 //#region ../contract/src/guest-writes.ts
 /**
@@ -11072,6 +11421,29 @@ function findInitRoot(from = process.cwd()) {
 		dir = parent;
 	}
 }
+/**
+* The project work belongs to, recorded on each version: CLOUDTIFACT_PROJECT, else the name of the git repo above
+* `from` (a worktree counts as its main repo), else null.
+*/
+function projectName(from = process.cwd(), env = process.env) {
+	const named = env.CLOUDTIFACT_PROJECT?.trim();
+	if (named) return named.slice(0, 100);
+	let dir = path.resolve(from);
+	for (;;) {
+		const git = path.join(dir, ".git");
+		if (existsSync(git)) {
+			try {
+				const m = /^gitdir:\s*(.+)$/m.exec(readFileSync(git, "utf8"));
+				const main = m?.[1] ? /^(.*)[\\/]\.git[\\/]worktrees[\\/]/.exec(m[1].trim()) : null;
+				if (main?.[1]) return path.basename(main[1]);
+			} catch {}
+			return path.basename(dir);
+		}
+		const parent = path.dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
 function parseRepoConfig(raw, file = REPO_CONFIG_FILE) {
 	const bad = (why) => /* @__PURE__ */ new Error(`${file}: ${why}`);
 	if (!raw || typeof raw !== "object") throw bad("expected a JSON object");
@@ -11226,6 +11598,8 @@ function versionsData(versions) {
 		version: v.number,
 		at: iso(v.createdAt),
 		by: v.pushedBy.handle,
+		via: v.via ?? null,
+		project: v.project ?? null,
 		added: v.added,
 		changed: v.changed,
 		removed: v.removed,
@@ -11735,7 +12109,10 @@ async function pushTarget(client, target, initial, opts = {}) {
 	const planAndUpload = async () => {
 		const manifest = manifestOf(files);
 		const bySha = new Map(files.map((f) => [f.sha256, f]));
-		const plan = await client.pushPlan(target.spaceId, { files: manifest });
+		const plan = await client.pushPlan(target.spaceId, {
+			files: manifest,
+			...opts.prefix ? { prefix: opts.prefix } : {}
+		});
 		if (opts.dryRun || isEmptyDiff(plan.diff)) return {
 			plan,
 			manifest
@@ -11767,7 +12144,9 @@ async function pushTarget(client, target, initial, opts = {}) {
 		result = await client.createVersion(target.spaceId, {
 			files: manifest,
 			message: opts.message,
-			baseVersion: plan.baseVersion
+			baseVersion: plan.baseVersion,
+			...opts.prefix ? { prefix: opts.prefix } : {},
+			...opts.project ? { project: opts.project } : {}
 		});
 	} catch (err) {
 		if (!(err instanceof ApiError && err.status === 409)) throw err;
@@ -11781,7 +12160,9 @@ async function pushTarget(client, target, initial, opts = {}) {
 		result = await client.createVersion(target.spaceId, {
 			files: manifest,
 			message: opts.message,
-			baseVersion: plan.baseVersion
+			baseVersion: plan.baseVersion,
+			...opts.prefix ? { prefix: opts.prefix } : {},
+			...opts.project ? { project: opts.project } : {}
 		});
 	}
 	if (!result.version) return {
@@ -11820,6 +12201,7 @@ async function pushRepo(client, repo, opts = {}) {
 			});
 			const r = await pushTarget(client, target, files, {
 				...opts,
+				project: opts.project ?? projectName(repo.root),
 				recollect: async () => (await collect(repo.docsDir)).files
 			});
 			results.push(r);
@@ -11860,9 +12242,10 @@ function commentsUrl(shareUrl) {
 * app, with a Comment button in the corner) and with the comment panel already open. A private page has only the
 * app link, which members open inside the Cloudtifact viewer.
 */
-function linkLines(space) {
-	if (space.shareUrl) return [`Page: ${space.shareUrl}`, `With comments: ${commentsUrl(space.shareUrl)}`];
-	return [`Link: ${space.url}`, `Private: only members of the ${space.workspace.slug} workspace can open it. To make it public, change visibility in the space settings on the website.`];
+function linkLines(space, prefix) {
+	const share = space.shareUrl && prefix ? space.shareUrl + prefix : space.shareUrl;
+	if (share) return [`Page: ${share}`, `With comments: ${commentsUrl(share)}`];
+	return [`Link: ${prefix ? `${space.url}/${prefix}index.html` : space.url}`, `Private: only members of the ${space.workspace.slug} workspace can open it. To make it public, change visibility in the space settings on the website.`];
 }
 /** A local, relative reference, or null for absolute URLs, data:, anchors, etc. Drops ?query and #hash. */
 function localRef(raw) {
@@ -11986,7 +12369,44 @@ async function publishToSpace(client, spaceId, bundle, opts) {
 		});
 		await applyGuestWrites(client, spaceId, opts.folder, { log: opts.log });
 	}
-	return pushTarget(client, { spaceId }, bundle.files, { message: opts.message });
+	const prefix = opts.prefix;
+	const files = prefix ? bundle.files.map((f) => ({
+		...f,
+		path: prefix + f.path
+	})) : bundle.files;
+	return pushTarget(client, { spaceId }, files, {
+		message: opts.message,
+		prefix,
+		project: opts.project
+	});
+}
+/**
+* The space new work belongs in: an active space in the workspace you can publish to, whose name matches the page
+* strongly (topicMatch), with the same who-can-see as asked for. A private page never lands in a public space, and a
+* public one never in a private space: publishing doesn't change who can see anything. Null: make a new space.
+*/
+async function findHome(client, title, opts) {
+	return (await client.findSpaces({
+		q: title,
+		workspace: opts.workspace,
+		limit: 10
+	}).catch((e) => {
+		if (e instanceof ApiError && (e.status === 404 || e.status === 400)) return { spaces: [] };
+		throw e;
+	})).spaces.find((s) => s.strong && s.kind === "repo" && s.permissions.canPush && !s.passwordProtected && s.visibility === "public" === opts.public) ?? null;
+}
+/** A folder for the page in the space that no other page uses: "pricing-d/", else "pricing-d-2/", ... */
+async function freePrefix(client, space, name) {
+	const taken = /* @__PURE__ */ new Set();
+	if (space.latestVersion > 0) {
+		const latest = await client.getVersion(space.id, "latest");
+		for (const f of latest.files) taken.add(f.path.split("/")[0] ?? "");
+	}
+	const base = pageSlug(name);
+	for (let i = 1;; i++) {
+		const slug = i === 1 ? base : `${base}-${i}`;
+		if (!taken.has(slug) && !taken.has(`${slug}.html`)) return `${slug}/`;
+	}
 }
 const artifactsPath = (env = process.env) => path.join(globalConfigDir(env), "artifacts.json");
 async function readArtifacts(env = process.env) {
@@ -12062,7 +12482,7 @@ function tokenSpace(token) {
 //#endregion
 //#region src/version.ts
 /** This CLI's version, from package.json at build time (tsdown.config.ts). Unbuilt (tests, tsx): "0.0.0-dev". */
-const VERSION = "0.2.3";
+const VERSION = "0.2.4";
 /**
 * Sent on every API request, so the API can tell which CLI version is calling (and one day tell an old one to
 * upgrade). Without it Node sends just "node", which is what 0.2.2 and older send. The sign-in page shows it too.
@@ -12343,6 +12763,25 @@ function chatsToMarkdown(spaceName, chats) {
 	return `${out.join("\n").trimEnd()}\n`;
 }
 //#endregion
+//#region src/folders.ts
+/** The folder a path names, or null for "/" (the top level). Unknown paths fail with close matches and the fix. */
+async function folderFor(client, slug, path) {
+	if (isTopLevel(path)) return null;
+	const { folders } = await client.listFolders(slug);
+	const f = findFolder(folders, path);
+	if (!f) throw new CliError(noFolderMessage(folders, path, `cloudtifact folder create "${path.trim()}"`));
+	return f;
+}
+/** "Product plans › Pricing": a path as people read it. */
+const shownPath = (f) => f ? f.path.replaceAll("/", " › ") : "the top level";
+/** The tree as indented lines: name, how many spaces, what it's for. */
+function treeLines(folders) {
+	return folders.map((f) => {
+		const depth = f.path.split("/").length - 1;
+		return `${"  ".repeat(depth)}▤ ${f.name}  ${f.spaces}${f.description ? `  · ${f.description}` : ""}`;
+	});
+}
+//#endregion
 //#region src/hooks.ts
 const SCRIPT_INSTALL_BIN = "\"$HOME/.cloudtifact/bin/cloudtifact\"";
 /** The command every harness runs after a file edit. Reads the hook payload on stdin, always exits 0. */
@@ -12779,6 +13218,7 @@ When you make an HTML page for the user, run \`cloudtifact publish <file.html>\`
 - To update it, edit the same file and publish it again: new version, same link.
 - Keep supporting files next to the HTML (or in subfolders) and reference them with relative paths (\`style.css\`, \`img/logo.png\`). Absolute paths and files outside the page's folder aren't included.
 - Pages are private by default; add \`--public\` on the first publish for a link anyone can open. \`cloudtifact artifacts\` lists what you've published.
+- New work joins the space already about the same topic, as a page, instead of making another space: \`publish\` finds it (same workspace, same who-can-see) and prints \`Looks like "<space>"\`. Tell the user where it went. To check first, run \`cloudtifact find "<title>" --toon\`; \`--add-to <id>\` adds the page to a space you pick, \`--new\` makes a separate space when the user wants one.
 
 ## Space files
 
@@ -12788,6 +13228,18 @@ People can add files to a space for the work (chat exports, emails, PDFs, spread
 
 Spaces live in workspaces (personal or team; the user can belong to several). \`cloudtifact publish\` and \`cloudtifact init\` create new spaces in the current workspace and print which one; pass \`--workspace <slug>\` to pick another. \`cloudtifact workspace list\` shows the user's workspaces (current one marked); \`cloudtifact workspace use <slug>\` switches the default. Pushing to an existing space doesn't need a workspace. Only change the default when the user asks.
 
+## Folders
+
+A workspace's spaces can sit in folders (any depth, like "Deals/Enterprise"); everyone in it shares them. \`cloudtifact folders --toon\` lists every path, how many spaces it holds and what goes there: read the descriptions before filing.
+
+- File a new space with \`publish --folder "<path>"\` when the user named a folder, \`.cloudtifact.json\` says one, or a folder's description clearly says it's where this goes. Otherwise leave it out and say where it went. An unknown folder fails with close matches: don't make one to get past it.
+- When the user asks, you can make, rename, describe and move folders and move spaces: \`cloudtifact folder create "<path>" [--description "<what goes here>"]\` (makes the folders the path needs), \`folder rename <path> <name>\`, \`folder describe <path> "<text>"\`, \`folder move <path> <to-path or />\`, and \`cloudtifact move <space> <folder-path or />\`. Never on your own: suggest it and let the user decide.
+- Every change is in the workspace's Activity under the user's name, with Undo (\`cloudtifact activity\`, \`cloudtifact undo <id>\`). Moving never changes a space's link or who can open it. Only the person can remove a folder, in the Cloudtifact app.
+
+## Putting spaces away
+
+When the user asks to archive, clear out or tidy up spaces, run \`cloudtifact archive <id>\`: the space leaves every list while its link, comments and data keep working, and \`cloudtifact unarchive <id>\` (or publishing to it again) brings it back. Never try to delete a space: only the person can, in the Cloudtifact app. \`cloudtifact favorite <id>\` pins a space at the top of the user's own sidebar.
+
 ## Space databases
 
 Every space has its own SQLite database, shared by all its pages. Commands take \`--space <id>\` (default: the first target in \`.cloudtifact.json\`) and \`--toon\` / \`--json\`:
@@ -13212,7 +13664,7 @@ const program = new Command().name("cloudtifact").description("Publish pages and
 		const tty = !!process.stdout.isTTY && !!process.stderr.isTTY;
 		if (updateNoticeOff({
 			env: process.env,
-			current: "0.2.3",
+			current: "0.2.4",
 			format,
 			command: cmd.name(),
 			tty
@@ -13500,7 +13952,7 @@ program.command("init").description("Link this repo to a space (creating one in
 	console.log("Next: `cloudtifact push`");
 	if (opts.hooks) await hooksInstall(root, {});
 }));
-program.command("push").description("Upload changed files and record a new version on every target").option("-m, --message <message>", "version message").option("--dry-run", "show what would change, upload nothing").option("-q, --quiet", "print nothing unless something fails").option("--no-db", "don't run the docs folder's db/*.sql files").addOption(new Option("--if-changed-path <file>", "only push if this file is inside the docs folder").hideHelp()).action(run(async (opts) => {
+program.command("push").description("Upload changed files and record a new version on every target").option("-m, --message <message>", "version message").option("--dry-run", "show what would change, upload nothing").option("-q, --quiet", "print nothing unless something fails").option("--no-db", "don't run the docs folder's db/*.sql files").option("--project <name>", "the project this work belongs to (default: the git repo's name)").addOption(new Option("--if-changed-path <file>", "only push if this file is inside the docs folder").hideHelp()).action(run(async (opts) => {
 	const repo = await loadRepo();
 	if (opts.ifChangedPath && !isInside(repo.docsDir, opts.ifChangedPath)) return;
 	const { client } = await getClient();
@@ -13508,6 +13960,7 @@ program.command("push").description("Upload changed files and record a new versi
 		message: opts.message,
 		dryRun: opts.dryRun,
 		db: opts.db,
+		project: opts.project,
 		log: opts.quiet ? void 0 : (l) => console.log(l)
 	})).some((r) => r.status === "error")) process.exitCode = 1;
 }));
@@ -13722,7 +14175,9 @@ for (const [name, verb] of [["resolve", "Resolved"], ["unresolve", "Reopened"]])
 	const c = await (name === "resolve" ? client.resolveComment(commentId) : client.unresolveComment(commentId));
 	console.log(`${verb} ${c.id} on ${c.path}.`);
 }));
-program.command("publish").description("Publish an HTML page (with the files it references) or a folder; prints its link").argument("<path>", "an .html file or a folder with index.html").option("--public", "anyone with the link can view (only when first published; default: private)").option("--name <name>", "space name (default: the page's <title>, else the file name)").option("--workspace <slug>", "workspace for a new space (default: the current one, see `workspace list`)").option("--space <id>", "publish into this existing space (id or link) instead of making one").option("--entry <file>", "folder only: the page to publish as index.html").option("-m, --message <message>", "version message").option("--no-db", "don't run the db/*.sql files next to the page").action(run(async (target, opts) => {
+program.command("publish").description("Publish an HTML page (with the files it references) or a folder; prints its link").argument("<path>", "an .html file or a folder with index.html").option("--public", "anyone with the link can view (only when first published; default: private)").option("--name <name>", "space name (default: the page's <title>, else the file name)").option("--workspace <slug>", "workspace for a new space (default: the current one, see `workspace list`)").option("--space <id>", "publish as this existing space's main page (id or link), replacing its files").option("--add-to <id>", "add it as a page in this existing space (id or link), keeping the space's other pages").option("--new", "make a new space, even when an existing one looks like the same topic").option("--folder <path>", "file a new space in this folder, like \"Deals/Enterprise\" (see `cloudtifact folders`)").option("--project <name>", "the project this work belongs to (default: the git repo it's in)").option("--entry <file>", "folder only: the page to publish as index.html").option("-m, --message <message>", "version message").option("--no-db", "don't run the db/*.sql files next to the page").action(run(async (target, opts) => {
+	if (opts.space && opts.addTo) throw new CliError("Pass --space or --add-to, not both.");
+	if ((opts.space || opts.addTo) && opts.new) throw new CliError("--new makes a new space; drop --space/--add-to.");
 	const abs = path.resolve(target);
 	if (!existsSync(abs)) throw new CliError(`${target} does not exist.`);
 	const isDir = statSync(abs).isDirectory();
@@ -13733,32 +14188,78 @@ program.command("publish").description("Publish an HTML page (with the files it
 	const { client, baseUrl, config, account } = await getClient();
 	const saved = lookupArtifact(await readArtifacts(), abs, baseUrl);
 	let space = null;
-	if (opts.space) {
+	let prefix;
+	if (opts.addTo) {
+		space = await client.getSpace(spaceIdOrThrow(opts.addTo));
+		prefix = saved?.spaceId === space.id && saved.prefix ? saved.prefix : await freePrefix(client, space, path.basename(abs));
+		if (saved?.spaceId !== space.id || saved.prefix !== prefix) await saveArtifact(abs, {
+			spaceId: space.id,
+			apiUrl: baseUrl,
+			createdAt: Date.now(),
+			prefix,
+			...account ? { handle: account.handle } : {}
+		});
+	} else if (opts.space) {
 		space = await client.getSpace(spaceIdOrThrow(opts.space));
 		if (saved?.spaceId !== space.id) await saveArtifact(abs, {
 			spaceId: space.id,
 			apiUrl: baseUrl,
 			createdAt: Date.now()
 		});
-	} else if (saved) {
+	} else if (saved && !opts.new) {
 		space = await client.getSpace(saved.spaceId).catch((e) => {
 			if (e instanceof ApiError && e.status === 404) return null;
 			throw e;
 		});
 		if (!space && saved.handle && account && saved.handle !== account.handle) throw new CliError(`This page was published as @${saved.handle} (space ${saved.spaceId}); you don't have access as @${account.handle}. Run it with --account ${saved.handle}.`);
+		if (space) prefix = saved.prefix;
 		if (!space) console.error(`Space ${saved.spaceId} is gone; creating a new one.`);
 		else if (opts.workspace && opts.workspace !== space.workspace.slug) console.error(`note: this page is already published in ${space.workspace.slug}; --workspace only applies to new spaces.`);
 		else if (opts.public && !space.shareUrl) console.error("note: --public only applies when first published; this artifact stays private.");
 	}
+	let newIn;
+	const newSpaceWorkspace = async () => newIn ??= await workspaceForNewSpace(client, opts.workspace, config.workspace);
 	if (!space) {
 		const name = opts.name ?? bundle.title ?? path.basename(abs);
-		const cur = await workspaceForNewSpace(client, opts.workspace, config.workspace);
+		const cur = await newSpaceWorkspace();
 		console.error(workspaceLine(cur));
+		const home = opts.new ? null : await findHome(client, name, {
+			workspace: cur.workspace.slug,
+			public: !!opts.public
+		});
+		if (home) {
+			space = await client.getSpace(home.id);
+			prefix = await freePrefix(client, space, path.basename(abs));
+			console.error(`Looks like "${space.name}" (${space.id}): adding it there as a page. Use --new for a separate space.`);
+			await saveArtifact(abs, {
+				spaceId: space.id,
+				apiUrl: baseUrl,
+				createdAt: Date.now(),
+				prefix,
+				...account ? { handle: account.handle } : {}
+			});
+		}
+	}
+	let filed;
+	if (opts.folder) {
+		if (space && prefix !== void 0) console.error(`note: it's a page in "${space.name}", so it stays where that space is; --folder was not used.`);
+		else if (space) console.error(`note: "${space.name}" is already published; --folder only files a new space. To move it: cloudtifact move ${space.id} "${opts.folder}"`);
+		else filed = await folderFor(client, (await newSpaceWorkspace()).workspace.slug, opts.folder).catch((e) => {
+			if (!(e instanceof CliError)) throw e;
+			console.error(`warning: ${e.message}; publishing it at the top level instead.`);
+			return null;
+		});
+	}
+	if (!space) {
+		const name = opts.name ?? bundle.title ?? path.basename(abs);
+		const cur = await newSpaceWorkspace();
 		space = await client.createSpace({
 			workspace: cur.workspace.slug,
 			name,
-			visibility: opts.public ? "public" : "members"
+			visibility: opts.public ? "public" : "members",
+			...filed ? { folderId: filed.id } : {}
 		});
+		if (filed) console.error(`Filed in ${shownPath(filed)}`);
 		await saveArtifact(abs, {
 			spaceId: space.id,
 			apiUrl: baseUrl,
@@ -13768,6 +14269,8 @@ program.command("publish").description("Publish an HTML page (with the files it
 	}
 	const r = await publishToSpace(client, space.id, bundle, {
 		folder: pageFolder(abs, isDir),
+		prefix,
+		project: opts.project ?? projectName(path.dirname(abs)),
 		message: opts.message,
 		db: opts.db,
 		log: (l) => console.log(l),
@@ -13776,7 +14279,31 @@ program.command("publish").description("Publish an HTML page (with the files it
 	const n = bundle.files.length;
 	if (r.status === "pushed") console.log(`Published "${space.name}" v${r.version} (${n} file${n === 1 ? "" : "s"}; ${summarize(r.diff)})`);
 	else console.log(`No changes since v${space.latestVersion}: "${space.name}"`);
-	for (const line of linkLines(space)) console.log(line);
+	for (const line of linkLines(space, prefix)) console.log(line);
+}));
+program.command("find").description("Find the spaces a topic already lives in, best match first, so new work can go in as a page").argument("<words...>", "what it's about, like a title").option("--workspace <slug>", "only this workspace (default: all of yours)").option("--toon", "print TOON (compact, for agents)").option("--json", "print JSON").action(run(async (words, opts) => {
+	const { client } = await getClient();
+	const { spaces } = await client.findSpaces({
+		q: words.join(" "),
+		workspace: opts.workspace,
+		limit: 10
+	});
+	const format = resolveFormat(opts);
+	const rows = spaces.map((s) => ({
+		id: s.id,
+		name: s.name,
+		workspace: s.workspace.slug,
+		pages: s.pages,
+		match: s.strong ? "strong" : "weak",
+		page: s.page,
+		visibility: s.visibility,
+		canPublish: s.permissions.canPush,
+		link: s.shareUrl ?? s.url
+	}));
+	if (format !== "text") return printData(format, { spaces: rows });
+	if (!rows.length) return console.log("Nothing matches. `cloudtifact publish` will make a new space.");
+	for (const r of rows) console.log(`${r.id}  ${r.name}  ${r.pages} page${r.pages === 1 ? "" : "s"} · ${r.workspace}${r.match === "strong" ? " · same topic" : ""}${r.page ? ` · page "${r.page}"` : ""}`);
+	console.log("Add a page to one: cloudtifact publish <file> --add-to <id>");
 }));
 program.command("artifacts").description("List pages published with `cloudtifact publish`").option("--toon", "print TOON (compact, for agents)").option("--json", "print JSON").action(run(async (opts) => {
 	const map = await readArtifacts();
@@ -13816,7 +14343,7 @@ program.command("versions").description("List a space's versions, newest first")
 		versions: rows
 	});
 	if (!rows.length) return console.log("Nothing pushed yet.");
-	for (const v of rows) console.log(`v${v.version}  ${v.at} UTC  @${v.by}  +${v.added} ~${v.changed} -${v.removed}${v.message ? `  ${v.message}` : ""}`);
+	for (const v of rows) console.log(`v${v.version}  ${v.at} UTC  ${byPerson(`@${v.by}`, v.via)}${v.project ? ` · ${v.project}` : ""}  +${v.added} ~${v.changed} -${v.removed}${v.message ? `  ${v.message}` : ""}`);
 }));
 program.command("settings").description("Show a space's guest and visitor switches, or flip them (space admins; the same switches as in the app)").option("--space <id>", "space id or link (default: the first target in .cloudtifact.json)").option(SETTINGS[0].option, SETTINGS[0].label).option(SETTINGS[1].option, `${SETTINGS[1].label} (off keeps the database private from visitors)`).option(SETTINGS[2].option, SETTINGS[2].label).option("--toon", "print TOON (compact, for agents)").option("--json", "print JSON").action(run(async (opts) => {
 	const { spaceId } = await pickSpace(opts.space);
@@ -13827,6 +14354,187 @@ program.command("settings").description("Show a space's guest and visitor switch
 	if (format !== "text") return printData(format, settingsData(space));
 	process.stdout.write(settingsText(space));
 }));
+for (const [name, on] of [["archive", true], ["unarchive", false]]) program.command(name).description(on ? "Archive a space: it leaves every list, its link, comments and data keep working, and a new version brings it back" : "Bring an archived space back into the lists").argument("[space]", "space id or link (default: the first target in .cloudtifact.json)").option("--space <id>", "space id or link (same as the argument)").option("--json", "print JSON").action(run(async (arg, opts) => {
+	const { spaceId } = await pickSpace(arg ?? opts.space);
+	const { client } = await getClient();
+	const space = on ? await client.archiveSpace(spaceId) : await client.unarchiveSpace(spaceId);
+	if (opts.json) return printData("json", {
+		id: space.id,
+		name: space.name,
+		archived: on,
+		link: space.url
+	});
+	console.log(on ? `Archived "${space.name}". It's out of the lists; the link still works: ${space.url}\nUndo: cloudtifact unarchive ${space.id}` : `"${space.name}" is back in the lists: ${space.url}`);
+}));
+program.command("spaces").description("List spaces: the ones you made, the ones shared with you, or the ones waiting on you").option("--mine", "only the ones you made (Made by me)").option("--shared", "only the ones people in other workspaces shared with you (Shared with me)").option("--waiting", "comment threads waiting on you, by space (Waiting on me)").option("--workspace <slug>", "which workspace (default: your default one)").option("--folder <path>", "only the spaces in this folder (\"/\" for the ones in no folder)").option("--toon", "print TOON (compact, for agents)").option("--json", "print JSON").action(run(async (opts) => {
+	const { client, config } = await getClient();
+	const me = await client.me();
+	const format = resolveFormat(opts);
+	const mineSlugs = new Set(me.workspaces.map((w) => w.slug));
+	if (opts.shared) {
+		const rows = (await client.listOpenableSpaces()).liveSpaces.filter((s) => !mineSlugs.has(s.workspace.slug)).map((s) => ({
+			id: s.id,
+			name: s.name,
+			workspace: s.workspace.slug,
+			link: s.url
+		}));
+		if (format !== "text") return printData(format, { spaces: rows });
+		if (!rows.length) return console.log("Nobody has shared a space with you from another workspace.");
+		for (const r of rows) console.log(`${r.id}  ${r.name}  · ${r.workspace}`);
+		return;
+	}
+	const slug = requireWorkspace(me.workspaces, {
+		flag: opts.workspace,
+		saved: config.workspace
+	}).workspace.slug;
+	if (opts.waiting) {
+		const w = await client.waiting(slug, { limit: 50 });
+		const rows = w.threads.map((t) => ({
+			space: t.space.id,
+			name: t.space.name,
+			thread: t.thread.id,
+			why: t.mentioned ? "mentioned you" : t.reason === "owner" ? "on a space you started" : "you wrote in it",
+			at: iso(t.lastAt)
+		}));
+		if (format !== "text") return printData(format, {
+			workspace: slug,
+			total: w.total,
+			threads: rows
+		});
+		if (!rows.length) return console.log("Nothing is waiting on you.");
+		for (const r of rows) console.log(`${r.space}  ${r.name}  · ${r.why} · ${r.at} UTC`);
+		console.log(`Read one: cloudtifact comments --space <id>`);
+		return;
+	}
+	const [{ spaces }, { folders }] = await Promise.all([client.listSpaces({ workspace: slug }), client.listFolders(slug).catch(() => ({ folders: [] }))]);
+	const only = opts.folder === void 0 ? void 0 : (await folderFor(client, slug, opts.folder))?.id ?? null;
+	const pathOf = new Map(folders.map((f) => [f.id, f.path]));
+	const rows = spaces.filter((s) => s.kind !== "app" && (!opts.mine || s.createdBy === me.user.id)).filter((s) => only === void 0 || (s.folderId ?? null) === only).map((s) => ({
+		id: s.id,
+		name: s.name,
+		folder: s.folderId ? pathOf.get(s.folderId) ?? null : null,
+		project: s.project ?? null,
+		visibility: s.visibility,
+		link: s.shareUrl ?? s.url
+	}));
+	if (format !== "text") return printData(format, {
+		workspace: slug,
+		spaces: rows
+	});
+	if (!rows.length) return console.log(opts.mine ? "You haven't made a space here yet." : "No spaces yet.");
+	for (const r of rows) console.log(`${r.id}  ${r.name}${r.folder ? `  ▤ ${r.folder}` : ""}${r.project ? `  · ${r.project}` : ""}`);
+}));
+program.command("activity").description("What people did to the spaces of a workspace, newest first, with the id to undo each").option("--workspace <slug>", "which workspace (default: your default one)").option("--person <handle>", "only what this person did").option("-n, --limit <n>", "how many to show", "20").option("--toon", "print TOON (compact, for agents)").option("--json", "print JSON").action(run(async (opts) => {
+	const { client, config } = await getClient();
+	const cur = requireWorkspace((await client.me()).workspaces, {
+		flag: opts.workspace,
+		saved: config.workspace
+	});
+	const { events } = await client.listActivity(cur.workspace.slug, {
+		person: opts.person?.replace(/^@/, ""),
+		limit: Math.min(100, Math.max(1, Number(opts.limit) || 20))
+	});
+	const rows = events.map((e) => ({
+		id: e.id,
+		at: iso(e.createdAt),
+		what: `${byPerson(e.actor ? e.actor.name ?? `@${e.actor.handle}` : "A deleted account", e.via)} ${describeActivity(e)}`,
+		space: e.space?.id ?? null,
+		folder: e.folder?.id ?? null,
+		canUndo: e.canUndo,
+		undone: e.undone
+	}));
+	const format = resolveFormat(opts);
+	if (format !== "text") return printData(format, {
+		workspace: cur.workspace.slug,
+		events: rows
+	});
+	if (!rows.length) return console.log("Nothing yet.");
+	for (const r of rows) console.log(`${r.id}  ${r.at} UTC  ${r.what}${r.undone ? "  (undone)" : r.canUndo ? "" : "  (can't undo)"}`);
+	if (rows.some((r) => r.canUndo)) console.log("Undo one: cloudtifact undo <id>");
+}));
+program.command("undo").description("Undo a change from `cloudtifact activity`: brings back, restores, or takes out an added page").argument("<id>", "the change's id, from `cloudtifact activity`").option("--workspace <slug>", "which workspace (default: your default one)").action(run(async (id, opts) => {
+	const { client, config } = await getClient();
+	const cur = requireWorkspace((await client.me()).workspaces, {
+		flag: opts.workspace,
+		saved: config.workspace
+	});
+	const { event } = await client.undoActivity(cur.workspace.slug, id);
+	console.log(`Undone: ${byPerson(event.actor ? event.actor.name ?? `@${event.actor.handle}` : "You", event.via)} ${describeActivity(event)}`);
+}));
+/** The workspace a folder command works in. */
+async function folderWorkspace(opts) {
+	const { client, config } = await getClient();
+	return {
+		client,
+		slug: requireWorkspace((await client.me()).workspaces, {
+			flag: opts.workspace,
+			saved: config.workspace
+		}).workspace.slug
+	};
+}
+program.command("folders").description("The workspace's folders: every path, how many spaces, and what each is for (read it before filing)").option("--workspace <slug>", "which workspace (default: your default one)").option("--toon", "print TOON (compact, for agents)").option("--json", "print JSON").action(run(async (opts) => {
+	const { client, slug } = await folderWorkspace(opts);
+	const { folders } = await client.listFolders(slug);
+	const format = resolveFormat(opts);
+	if (format !== "text") return printData(format, {
+		workspace: slug,
+		folders: folders.map((f) => ({
+			id: f.id,
+			path: f.path,
+			spaces: f.spaces,
+			description: f.description
+		}))
+	});
+	if (!folders.length) return console.log("No folders yet. Make one: cloudtifact folder create \"Product plans\"");
+	for (const l of treeLines(folders)) console.log(l);
+}));
+const folder = program.command("folder").description("Make, rename, describe or move folders (each change is in Activity, with Undo)");
+folder.command("create").description("Make a folder; a path like \"Deals/Enterprise\" makes the folders it needs").argument("<path>", "the folder's path").option("--description <text>", "what goes in it (people and agents read this before filing)").option("--workspace <slug>", "which workspace (default: your default one)").action(run(async (p, opts) => {
+	const { client, slug } = await folderWorkspace(opts);
+	const { folder: f, made } = await ensureFolderPath(client, slug, p, opts.description);
+	if (!made.length) {
+		console.log(`"${f.path}" is already there (${f.id}).`);
+		if (opts.description) console.error(`note: its description wasn't changed. To change it: cloudtifact folder describe "${f.path}" "…"`);
+		return;
+	}
+	console.log(`Made ${made.map((m) => `"${m.path}"`).join(", ")} (${f.id}).`);
+}));
+folder.command("rename").description("Rename a folder").argument("<path>", "the folder's path or id").argument("<name>", "its new name").option("--workspace <slug>", "which workspace (default: your default one)").action(run(async (p, name, opts) => {
+	const { client, slug } = await folderWorkspace(opts);
+	const f = await folderFor(client, slug, p);
+	if (!f) throw new CliError("The top level can't be renamed.");
+	const next = await client.updateFolder(slug, f.id, { name });
+	console.log(`Renamed "${f.path}" to "${next.path}".`);
+}));
+folder.command("describe").description("Say what goes in a folder (people and agents read it before filing); empty text clears it").argument("<path>", "the folder's path or id").argument("<text>", "one line").option("--workspace <slug>", "which workspace (default: your default one)").action(run(async (p, text, opts) => {
+	const { client, slug } = await folderWorkspace(opts);
+	const f = await folderFor(client, slug, p);
+	if (!f) throw new CliError("The top level has no description.");
+	await client.updateFolder(slug, f.id, { description: text.trim() || null });
+	console.log(text.trim() ? `Described "${f.path}".` : `Cleared the description of "${f.path}".`);
+}));
+folder.command("move").description("Move a folder (and everything in it) into another one, or to the top level with \"/\"").argument("<path>", "the folder's path or id").argument("<to>", "where: a folder path, or \"/\" for the top level").option("--workspace <slug>", "which workspace (default: your default one)").action(run(async (p, to, opts) => {
+	const { client, slug } = await folderWorkspace(opts);
+	const f = await folderFor(client, slug, p);
+	if (!f) throw new CliError("The top level can't move.");
+	const into = await folderFor(client, slug, to);
+	const next = await client.updateFolder(slug, f.id, { parentId: into?.id ?? null });
+	console.log(`Moved "${f.name}" to ${shownPath(into)}: now "${next.path}".`);
+}));
+program.command("move").description("Move a space into a folder, or to the top level with \"/\"; its link and who can open it stay the same").argument("<space>", "space id or link").argument("<folder>", "a folder path like \"Product plans/Pricing\", or \"/\"").action(run(async (ref, to) => {
+	const { client } = await getClient();
+	const space = await client.getSpace(spaceIdOrThrow(ref));
+	const into = await folderFor(client, space.workspace.slug, to);
+	await client.fileSpace(space.id, into?.id ?? null);
+	console.log(`Moved "${space.name}" to ${shownPath(into)}. Undo: cloudtifact activity`);
+}));
+program.command("favorite").description("Add a space to your favorites, at the top of your sidebar (only you see them)").argument("[space]", "space id or link (default: the first target in .cloudtifact.json)").option("--space <id>", "space id or link (same as the argument)").option("--remove", "take it off your favorites").action(run(async (arg, opts) => {
+	const { spaceId } = await pickSpace(arg ?? opts.space);
+	const { client } = await getClient();
+	if (opts.remove) await client.unfavoriteSpace(spaceId);
+	else await client.favoriteSpace(spaceId);
+	console.log(opts.remove ? `Removed ${spaceId} from your favorites.` : `Added ${spaceId} to your favorites.`);
+}));
 program.command("upload").description("Upload files of any type into a space (up to 100 MB each); download them anywhere you sign in").argument("<files...>").option("--space <id>", "space id or link (default: the first target in .cloudtifact.json)").action(run(async (files, opts) => {
 	const { spaceId } = await pickSpace(opts.space, { noRepo: "Pass --space <id>, or run inside a linked repo." });
 	const { client } = await getClient();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cloudtifact",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Publish pages and docs to Cloudtifact as links people comment on, with every version kept and the comments handed back to your agent.",
   "license": "MIT",
   "author": "The Cloudtifact authors",