artifact-cafe 0.0.10 → 0.0.11

package/dist/index.js

@@ -182,7 +182,7 @@ var artifactResponseSchema = z3.object({
   id: z3.string(),
   slug: z3.string(),
   title: z3.string(),
-  visibility: z3.enum(["public", "unlisted", "workspace"]),
+  visibility: z3.enum(["public", "unlisted", "workspace", "private"]),
   workspaceId: z3.string().nullable()
 });
 
@@ -396,48 +396,105 @@ var feedbackResponseSchema = z6.object({
   sent: z6.literal(true)
 });
 
-// ../shared/src/me.ts
+// ../shared/src/grants.ts
 import { z as z7 } from "zod";
-var ownArtifactSchema = z7.object({
+var grantRoleSchema = z7.enum(["viewer"]);
+var createGrantSchema = z7.object({
+  email: z7.string().trim().toLowerCase().email().optional(),
+  role: grantRoleSchema.default("viewer"),
+  userId: z7.string().min(1).optional()
+}).refine((body) => Boolean(body.email) !== Boolean(body.userId), {
+  message: "provide exactly one of email or userId"
+});
+var grantSchema = z7.object({
   createdAt: z7.string(),
-  currentVersionNumber: z7.number().nullable(),
-  // Owned artifacts normally never expire; non-null only while an
-  // expiry is still set (e.g. an unclaimed publish surfaced here later).
+  email: z7.string().email().nullable(),
   expiresAt: z7.string().nullable(),
-  // SPEC-2 §8.4 — the containing folder for workspace-owned artifacts;
-  // both null for personal artifacts. `folderId` drives the dashboard's
-  // move control and folder filter; `folderName` is the display label.
-  folderId: z7.string().nullable(),
-  folderName: z7.string().nullable(),
-  // Whether a publish token is still active — revocable from the
-  // dashboard (§6.18); the token itself is never returned.
-  hasPublishToken: z7.boolean(),
   id: z7.string(),
-  openThreads: z7.number(),
-  protected: z7.boolean(),
+  // The subject's avatar once they have an account; null otherwise.
+  image: z7.string().nullable(),
+  // Present on the invited account after redemption / when granting an
+  // existing user; null for a still-pending email invite.
+  name: z7.string().nullable(),
+  redeemedAt: z7.string().nullable(),
+  role: grantRoleSchema,
+  // Shown as "· pending" beside the role until the link is redeemed.
+  status: z7.enum(["pending", "active"]),
+  // Display fragment of the live invitation token, or null once redeemed.
+  tokenPrefix: z7.string().nullable(),
+  userId: z7.string().nullable()
+});
+var createdGrantSchema = grantSchema.extend({
+  url: z7.string().url()
+});
+var grantListResponseSchema = z7.object({
+  grants: z7.array(grantSchema),
+  // The artifact's current general-access value, so the share surface can
+  // render the "General access" line without a second read.
+  visibility: z7.enum(["public", "unlisted", "workspace", "private"])
+});
+var revokeGrantResponseSchema = z7.object({
+  revoked: z7.literal(true)
+});
+var acceptGrantSchema = z7.object({
+  token: z7.string().min(1)
+});
+var acceptGrantResponseSchema = z7.object({
+  artifactId: z7.string(),
+  // The review shell URL to land on, carrying ?invited=1 for the banner.
+  artifactUrl: z7.string().url(),
   slug: z7.string(),
-  title: z7.string(),
-  totalViews: z7.number(),
-  // SPEC §6.20 — messages by others newer than the viewer's last-seen
-  // watermark. 0 for signed-out/API-key-less contexts.
-  unreadComments: z7.number(),
-  updatedAt: z7.string(),
-  url: z7.string(),
-  versionCount: z7.number()
+  title: z7.string()
+});
+var workspaceGuestSchema = z7.object({
+  artifacts: z7.array(
+    z7.object({
+      artifactId: z7.string(),
+      grantId: z7.string(),
+      slug: z7.string(),
+      status: z7.enum(["pending", "active"]),
+      title: z7.string()
+    })
+  ),
+  email: z7.string().nullable(),
+  image: z7.string().nullable(),
+  name: z7.string().nullable(),
+  userId: z7.string().nullable()
+});
+var workspaceGuestListResponseSchema = z7.object({
+  guests: z7.array(workspaceGuestSchema)
 });
-var ownArtifactsResponseSchema = z7.object({
-  artifacts: z7.array(ownArtifactSchema)
+var sharedWithMeArtifactSchema = z7.object({
+  artifactId: z7.string(),
+  slug: z7.string(),
+  title: z7.string(),
+  url: z7.string().url(),
+  // Who shared it, for the "Shared with me" list.
+  workspaceName: z7.string()
 });
-var revokePublishTokenResponseSchema = z7.object({
-  revoked: z7.boolean()
+var sharedWithMeListResponseSchema = z7.object({
+  artifacts: z7.array(sharedWithMeArtifactSchema)
 });
 
-// ../shared/src/owner.ts
+// ../shared/src/me.ts
 import { z as z9 } from "zod";
 
 // ../shared/src/workspaces.ts
 import { z as z8 } from "zod";
 var WORKSPACE_HANDLE_PATTERN = /^[a-z0-9](?:[a-z0-9-]{1,30}[a-z0-9])$/;
+var workspaceHandleUnavailableReasonSchema = z8.enum([
+  "held",
+  "invalid",
+  "reserved",
+  "taken"
+]);
+var workspaceHandleAvailabilitySchema = z8.object({
+  available: z8.boolean(),
+  handle: z8.string(),
+  // Human-readable sentence for the field hint; null when available.
+  message: z8.string().nullable(),
+  reason: workspaceHandleUnavailableReasonSchema.nullable()
+});
 var workspaceRoleSchema = z8.enum(["owner", "admin", "member"]);
 var workspaceInviteRoleSchema = z8.enum(["admin", "member"]);
 var workspaceHandleSchema = z8.string().min(3).max(32).regex(WORKSPACE_HANDLE_PATTERN, {
@@ -456,6 +513,10 @@ var updateWorkspaceSchema = z8.object({
 var workspaceSchema = z8.object({
   createdAt: z8.string(),
   handle: z8.string(),
+  // ISO timestamp when `{handle}.artifact.cafe` was provisioned, or null.
+  // Set by the one-time, self-serve enable flow (§4.4); never auto at
+  // create, and always null for personal workspaces.
+  hostnameProvisionedAt: z8.string().nullable(),
   id: z8.string(),
   // Auto-provisioned solo workspace, one per user: non-deletable, takes
   // no members, renameable like any workspace.
@@ -526,7 +587,8 @@ var folderVisibilitySchema = z8.enum(["public", "workspace"]);
 var artifactVisibilitySchema = z8.enum([
   "public",
   "unlisted",
-  "workspace"
+  "workspace",
+  "private"
 ]);
 var createFolderSchema = z8.object({
   name: z8.string().trim().min(1).max(100),
@@ -579,143 +641,229 @@ var workspaceArtifactSchema = z8.object({
 var workspaceArtifactListResponseSchema = z8.object({
   artifacts: z8.array(workspaceArtifactSchema)
 });
+var workspaceArtifactSearchResultSchema = z8.object({
+  id: z8.string(),
+  slug: z8.string(),
+  title: z8.string()
+});
+var workspaceArtifactSearchResponseSchema = z8.object({
+  results: z8.array(workspaceArtifactSearchResultSchema)
+});
 
-// ../shared/src/owner.ts
-var SLUG_PATTERN = /^[a-z0-9](?:[a-z0-9-]{1,61}[a-z0-9])$/;
-var claimResponseSchema = z9.object({
-  artifactId: z9.string(),
+// ../shared/src/me.ts
+var ownArtifactSchema = z9.object({
+  createdAt: z9.string(),
+  currentVersionNumber: z9.number().nullable(),
+  // Owned artifacts normally never expire; non-null only while an
+  // expiry is still set (e.g. an unclaimed publish surfaced here later).
+  expiresAt: z9.string().nullable(),
+  // SPEC-2 §8.4 — the containing folder for workspace-owned artifacts;
+  // both null for personal artifacts. `folderId` drives the dashboard's
+  // move control and folder filter; `folderName` is the display label.
+  folderId: z9.string().nullable(),
+  folderName: z9.string().nullable(),
+  // Whether a publish token is still active — revocable from the
+  // dashboard (§6.18); the token itself is never returned.
+  hasPublishToken: z9.boolean(),
+  id: z9.string(),
+  openThreads: z9.number(),
+  protected: z9.boolean(),
+  // Who published the current version (falling back to the claiming
+  // owner) — the dashboard shows a name and avatar per artifact so a
+  // shared workspace reads as people's work, not anonymous rows. Null
+  // when the publish was token-only and the artifact is unclaimed.
+  publishedBy: z9.object({ image: z9.string().nullable(), name: z9.string() }).nullable(),
   slug: z9.string(),
   title: z9.string(),
-  url: z9.string().url()
+  totalViews: z9.number(),
+  // SPEC §6.20 — messages by others newer than the viewer's last-seen
+  // watermark. 0 for signed-out/API-key-less contexts.
+  unreadComments: z9.number(),
+  updatedAt: z9.string(),
+  url: z9.string(),
+  versionCount: z9.number(),
+  // SPEC-2 §5.1 — whether the caller clears the manage bar for this
+  // artifact (workspace admin, or the person who first published it).
+  // Only a manager's folder move inherits the folder's visibility, so the
+  // dashboard warns exactly the people the change can actually affect, and
+  // only a manager is offered the Share entry (§5.7).
+  viewerCanManage: z9.boolean(),
+  // SPEC-2 §5.2 — the artifact's own visibility, the single enforcement
+  // source. The dashboard needs it to tell whether a folder move would
+  // widen exposure before it sends the PATCH (§3.4), and to render the lock
+  // glyph on `private` rows and cards (§5.7).
+  visibility: artifactVisibilitySchema
+});
+var ownArtifactsResponseSchema = z9.object({
+  artifacts: z9.array(ownArtifactSchema)
+});
+var revokePublishTokenResponseSchema = z9.object({
+  revoked: z9.boolean()
 });
-var updateArtifactSchema = z9.object({
+
+// ../shared/src/owner.ts
+import { z as z10 } from "zod";
+var SLUG_PATTERN = /^[a-z0-9](?:[a-z0-9-]{1,61}[a-z0-9])$/;
+var claimResponseSchema = z10.object({
+  artifactId: z10.string(),
+  slug: z10.string(),
+  title: z10.string(),
+  url: z10.string().url()
+});
+var updateArtifactSchema = z10.object({
   // SPEC-2 §6.4 — placement + visibility. `folderId: null` clears the
   // folder; `workspaceId: null` moves the artifact out of its workspace
   // (§5.5 ownership transfer).
-  folderId: z9.string().min(1).nullable().optional(),
-  slug: z9.string().min(3).max(63).regex(SLUG_PATTERN, {
+  folderId: z10.string().min(1).nullable().optional(),
+  slug: z10.string().min(3).max(63).regex(SLUG_PATTERN, {
     message: "slug must be lowercase letters, digits, and hyphens, with no leading/trailing hyphen"
   }).optional(),
-  title: z9.string().min(1).max(200).optional(),
+  title: z10.string().min(1).max(200).optional(),
   visibility: artifactVisibilitySchema.optional(),
-  workspaceId: z9.string().min(1).nullable().optional()
+  workspaceId: z10.string().min(1).nullable().optional()
 }).refine(
   (body) => body.title !== void 0 || body.slug !== void 0 || body.visibility !== void 0 || body.folderId !== void 0 || body.workspaceId !== void 0,
   {
     message: "provide at least one of title, slug, visibility, folderId, workspaceId"
   }
 );
-var deleteArtifactResponseSchema = z9.object({
-  deleted: z9.literal(true)
+var deleteArtifactResponseSchema = z10.object({
+  deleted: z10.literal(true)
 });
 
 // ../shared/src/presence.ts
-import { z as z10 } from "zod";
+import { z as z11 } from "zod";
+var AGENT_STATES = ["listening", "editing", "publishing"];
+var agentStateSchema = z11.enum(AGENT_STATES);
 var AGENT_PRESENCE = {
+  editingTtlSeconds: 300,
   heartbeatSeconds: 15,
   shellPollSeconds: 15,
   ttlSeconds: 45
 };
-var agentHeartbeatResponseSchema = z10.object({
-  listening: z10.literal(true),
-  ttlSeconds: z10.number().int().positive()
+var agentHeartbeatBodySchema = z11.object({
+  state: agentStateSchema.optional()
+});
+var agentHeartbeatResponseSchema = z11.object({
+  listening: z11.literal(true),
+  state: agentStateSchema.optional(),
+  ttlSeconds: z11.number().int().positive()
 });
-var agentPresenceSchema = z10.object({
-  listening: z10.boolean(),
-  versionNumber: z10.number().int().positive().nullable()
+var agentPresenceSchema = z11.object({
+  listening: z11.boolean(),
+  state: agentStateSchema.nullable().optional(),
+  versionNumber: z11.number().int().positive().nullable()
 });
 
 // ../shared/src/protection.ts
-import { z as z11 } from "zod";
+import { z as z12 } from "zod";
 var PASSWORD_MIN = 6;
 var PASSWORD_MAX = 128;
-var gatePasswordSchema = z11.string().min(PASSWORD_MIN, `Password must be at least ${PASSWORD_MIN} characters.`).max(PASSWORD_MAX, `Password must be at most ${PASSWORD_MAX} characters.`);
-var setProtectionSchema = z11.object({
+var gatePasswordSchema = z12.string().min(PASSWORD_MIN, `Password must be at least ${PASSWORD_MIN} characters.`).max(PASSWORD_MAX, `Password must be at most ${PASSWORD_MAX} characters.`);
+var setProtectionSchema = z12.object({
   password: gatePasswordSchema.nullable()
 });
-var protectionResponseSchema = z11.object({
-  protected: z11.boolean()
+var protectionResponseSchema = z12.object({
+  protected: z12.boolean()
 });
-var unlockSchema = z11.object({
-  password: z11.string().min(1).max(1024)
+var unlockSchema = z12.object({
+  password: z12.string().min(1).max(1024)
 });
-var unlockResponseSchema = z11.object({
-  unlocked: z11.literal(true)
+var unlockResponseSchema = z12.object({
+  unlocked: z12.literal(true)
 });
 
 // ../shared/src/report.ts
-import { z as z12 } from "zod";
-var reportRequestSchema = z12.object({
-  reason: z12.string().max(1e3).optional()
+import { z as z13 } from "zod";
+var reportRequestSchema = z13.object({
+  reason: z13.string().max(1e3).optional()
 });
-var reportResponseSchema = z12.object({
-  reported: z12.literal(true)
+var reportResponseSchema = z13.object({
+  reported: z13.literal(true)
+});
+
+// ../shared/src/reviewers.ts
+import { z as z14 } from "zod";
+var artifactReviewerSchema = z14.object({
+  avatarUrl: z14.string().nullable(),
+  displayName: z14.string(),
+  // Exactly one of userId/guestId is set, per `kind`.
+  guestId: z14.string().nullable(),
+  // "account", not commentAuthorSchema's "member" — the whole point here is
+  // that these people need not be workspace members. A guest can be named in
+  // a comment but never notified: guest_identities carries a display name and
+  // no email, so there is nowhere to send anything.
+  kind: z14.enum(["account", "guest"]),
+  userId: z14.string().nullable()
+});
+var artifactReviewerListResponseSchema = z14.object({
+  reviewers: z14.array(artifactReviewerSchema)
 });
 
 // ../shared/src/stats.ts
-import { z as z13 } from "zod";
-var avgViewSecondsSchema = z13.number().int().nonnegative().nullable();
-var versionViewStatsSchema = z13.object({
+import { z as z15 } from "zod";
+var avgViewSecondsSchema = z15.number().int().nonnegative().nullable();
+var versionViewStatsSchema = z15.object({
   avgViewSeconds: avgViewSecondsSchema,
   // Views from inside the review shell's iframe vs. direct visits to
   // the render URL. views = embeddedViews + directViews.
-  directViews: z13.number().int().nonnegative(),
-  embeddedViews: z13.number().int().nonnegative(),
+  directViews: z15.number().int().nonnegative(),
+  embeddedViews: z15.number().int().nonnegative(),
   // Distinct hashed viewer IPs across the version's lifetime.
-  uniqueViewers: z13.number().int().nonnegative(),
-  versionNumber: z13.number().int().positive(),
-  views: z13.number().int().nonnegative()
+  uniqueViewers: z15.number().int().nonnegative(),
+  versionNumber: z15.number().int().positive(),
+  views: z15.number().int().nonnegative()
 });
-var dailyViewsSchema = z13.object({
+var dailyViewsSchema = z15.object({
   avgViewSeconds: avgViewSecondsSchema,
   // UTC day, YYYY-MM-DD.
-  day: z13.string(),
-  uniqueViewers: z13.number().int().nonnegative(),
-  views: z13.number().int().nonnegative()
+  day: z15.string(),
+  uniqueViewers: z15.number().int().nonnegative(),
+  views: z15.number().int().nonnegative()
 });
-var artifactStatsResponseSchema = z13.object({
+var artifactStatsResponseSchema = z15.object({
   avgViewSeconds: avgViewSecondsSchema,
-  daily: z13.array(dailyViewsSchema),
+  daily: z15.array(dailyViewsSchema),
   // Distinct hashed viewer IPs across all versions and days.
-  totalUniqueViewers: z13.number().int().nonnegative(),
-  totalViews: z13.number().int().nonnegative(),
-  versions: z13.array(versionViewStatsSchema)
+  totalUniqueViewers: z15.number().int().nonnegative(),
+  totalViews: z15.number().int().nonnegative(),
+  versions: z15.array(versionViewStatsSchema)
 });
 
 // ../shared/src/versions.ts
-import { z as z14 } from "zod";
-var versionSourceSchema = z14.object({
-  agentName: z14.string().nullable(),
-  type: z14.string()
+import { z as z16 } from "zod";
+var versionSourceSchema = z16.object({
+  agentName: z16.string().nullable(),
+  type: z16.string()
 });
-var versionChangesSchema = z14.object({
-  added: z14.array(z14.string()),
-  changed: z14.array(z14.string()),
-  removed: z14.array(z14.string())
+var versionChangesSchema = z16.object({
+  added: z16.array(z16.string()),
+  changed: z16.array(z16.string()),
+  removed: z16.array(z16.string())
 });
-var versionSummarySchema = z14.object({
+var versionSummarySchema = z16.object({
   // Absent for the first version — there is no previous version to diff against.
   changes: versionChangesSchema.nullable(),
-  createdAt: z14.string(),
-  entryUrl: z14.string().url(),
-  fileCount: z14.number().int().nonnegative(),
-  id: z14.string(),
-  isCurrent: z14.boolean(),
+  createdAt: z16.string(),
+  entryUrl: z16.string().url(),
+  fileCount: z16.number().int().nonnegative(),
+  id: z16.string(),
+  isCurrent: z16.boolean(),
   // Author-supplied bullet-point changelog; null when the publish omitted it.
-  notes: z14.string().nullable(),
+  notes: z16.string().nullable(),
   source: versionSourceSchema,
-  totalSizeBytes: z14.number().int().nonnegative(),
-  versionNumber: z14.number().int().positive()
+  totalSizeBytes: z16.number().int().nonnegative(),
+  versionNumber: z16.number().int().positive()
 });
-var versionListResponseSchema = z14.object({
-  versions: z14.array(versionSummarySchema)
+var versionListResponseSchema = z16.object({
+  versions: z16.array(versionSummarySchema)
 });
 
 // src/api.ts
 var ApiRequestError = class extends Error {
-  constructor(status, code, message, retryAfter) {
+  constructor(status2, code, message, retryAfter) {
     super(message);
-    this.status = status;
+    this.status = status2;
     this.code = code;
     this.retryAfter = retryAfter;
     this.name = "ApiRequestError";
@@ -774,13 +922,28 @@ function createApiClient(apiUrl2, publishToken) {
         (d) => commentThreadSchema.parse(d)
       );
     },
-    async agentHeartbeat(artifactId) {
+    async agentHeartbeat(artifactId, state) {
       return request(
         `${base}/api/v1/artifacts/${artifactId}/agent-presence`,
-        { headers, method: "POST" },
+        {
+          ...state ? { body: JSON.stringify({ state }) } : {},
+          headers,
+          method: "POST"
+        },
         (d) => agentHeartbeatResponseSchema.parse(d)
       );
     },
+    // SPEC-2 §6.6 — share an artifact with a person (email or user id).
+    // Authorized by this client's credential: the publish token (an agent
+    // sharing a private draft) or an account key/session. The invitation
+    // URL is returned exactly once, here.
+    async createGrant(artifactId, body) {
+      return request(
+        `${base}/api/v1/artifacts/${artifactId}/grants`,
+        { body: JSON.stringify(body), headers, method: "POST" },
+        (d) => createdGrantSchema.parse(d)
+      );
+    },
     async createSession(body) {
       return request(
         `${base}/api/v1/publish`,
@@ -859,6 +1022,15 @@ function createApiClient(apiUrl2, publishToken) {
         (d) => folderListResponseSchema.parse(d)
       );
     },
+    // SPEC-2 §6.6 — the artifact's grants (no plaintext tokens). Used by
+    // `share --list` and to resolve an email → grant id for `unshare`.
+    async listGrants(artifactId) {
+      return request(
+        `${base}/api/v1/artifacts/${artifactId}/grants`,
+        { headers, method: "GET" },
+        (d) => grantListResponseSchema.parse(d)
+      );
+    },
     async listWorkspaces() {
       return request(
         `${base}/api/v1/workspaces`,
@@ -903,6 +1075,14 @@ function createApiClient(apiUrl2, publishToken) {
         (d) => commentThreadSchema.parse(d)
       );
     },
+    // SPEC-2 §6.6 — revoke a grant; access is gone within the cookie TTL.
+    async revokeGrant(artifactId, grantId) {
+      await request(
+        `${base}/api/v1/artifacts/${artifactId}/grants/${grantId}`,
+        { headers, method: "DELETE" },
+        () => void 0
+      );
+    },
     // SPEC §6.16 — set a password (string) or clear it (null). Authorized
     // by the publish token this client was created with.
     async setProtection(artifactId, password) {
@@ -939,17 +1119,17 @@ import {
   writeFileSync as writeFileSync2
 } from "fs";
 import path2 from "path";
-import { z as z16 } from "zod";
+import { z as z18 } from "zod";
 
 // src/credentials.ts
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { homedir } from "os";
 import path from "path";
-import { z as z15 } from "zod";
+import { z as z17 } from "zod";
 var DEFAULT_API_URL = "https://artifact.cafe";
-var credentialsSchema = z15.object({
-  keys: z15.record(z15.string(), z15.string()),
-  version: z15.literal(1)
+var credentialsSchema = z17.object({
+  keys: z17.record(z17.string(), z17.string()),
+  version: z17.literal(1)
 });
 function credentialsPath() {
   return path.join(homedir(), ".artifactcafe", "credentials");
@@ -999,24 +1179,24 @@ function resolveApiKey(apiUrl2, flag) {
 }
 
 // src/config.ts
-var configSchema = z16.object({
-  apiUrl: z16.string(),
-  artifactId: z16.string(),
-  folder: z16.string().optional(),
-  folderId: z16.string().optional(),
+var configSchema = z18.object({
+  apiUrl: z18.string(),
+  artifactId: z18.string(),
+  folder: z18.string().optional(),
+  folderId: z18.string().optional(),
   // Optional: a folder linked by `link` to an artifact you own carries no
   // token — owner actions authorize via your stored login instead. A first
   // publish still writes the anonymous-mode token here.
-  publishToken: z16.string().optional(),
-  slug: z16.string(),
-  url: z16.string(),
-  workspace: z16.string().optional(),
-  workspaceId: z16.string().optional(),
-  workspaceKind: z16.enum(["personal", "workspace"]).optional()
-});
-var projectConfigSchema = z16.object({
-  folder: z16.string().trim().min(1).optional(),
-  workspace: z16.string().trim().min(1)
+  publishToken: z18.string().optional(),
+  slug: z18.string(),
+  url: z18.string(),
+  workspace: z18.string().optional(),
+  workspaceId: z18.string().optional(),
+  workspaceKind: z18.enum(["personal", "workspace"]).optional()
+});
+var projectConfigSchema = z18.object({
+  folder: z18.string().trim().min(1).optional(),
+  workspace: z18.string().trim().min(1)
 }).strict();
 var CONFIG_DIR = ".artifactcafe";
 var CONFIG_FILE = "config.json";
@@ -1052,7 +1232,7 @@ function readProjectConfig(dir) {
           JSON.parse(readFileSync2(file, "utf8"))
         );
       } catch (error) {
-        const message = error instanceof z16.ZodError ? error.issues[0]?.message ?? "invalid project target" : "invalid JSON";
+        const message = error instanceof z18.ZodError ? error.issues[0]?.message ?? "invalid project target" : "invalid JSON";
         throw new Error(`Invalid ${file}: ${message}.`);
       }
     }
@@ -1239,7 +1419,7 @@ async function comments(opts) {
       `--version must be one of: ${VERSIONS.join(", ")} (got "${opts.version}").`
     );
   }
-  const status = opts.status;
+  const status2 = opts.status;
   const version = opts.version;
   const dir = path4.resolve(opts.dir);
   const target = resolveArtifactTarget(dir, {
@@ -1252,21 +1432,21 @@ async function comments(opts) {
   if (opts.wait) {
     await waitForFeedback(client, ref, {
       json: opts.json,
-      status,
+      status: status2,
       timeoutSeconds: opts.timeout,
       version
     });
     return;
   }
   const data = await client.exportComments(target.artifactId, {
-    status,
+    status: status2,
     version
   });
   if (opts.json) {
     console.log(JSON.stringify(data, null, 2));
     return;
   }
-  printHuman(data, url, status, version);
+  printHuman(data, url, status2, version);
 }
 async function deriveReviewUrl(client, target) {
   const artifact = await client.getArtifact(target.artifactId);
@@ -1328,6 +1508,10 @@ async function waitForFeedback(client, config, opts) {
     await sleep(settleSeconds());
     const settled = await client.exportComments(config.artifactId, query);
     const changed = diffThreads(baseline, settled);
+    try {
+      await client.agentHeartbeat(config.artifactId, "editing");
+    } catch {
+    }
     printWaitResult(config, settled, changed, opts.json);
     return;
   }
@@ -1378,8 +1562,8 @@ ${changed.length} thread${plural} with new feedback \u2014 ${config.url}
     printThread(thread);
   }
 }
-function printHuman(data, url, status, version) {
-  const statusLabel = status === "all" ? "" : `${status} `;
+function printHuman(data, url, status2, version) {
+  const statusLabel = status2 === "all" ? "" : `${status2} `;
   let scope = "across all versions";
   if (version === "current") {
     scope = data.versionNumber === null ? "on the current version" : `on v${data.versionNumber}`;
@@ -1638,17 +1822,26 @@ async function publish(opts) {
   log(
     `  uploading ${session.filesToUpload.length} file(s)` + (session.skippedFiles.length ? `, ${session.skippedFiles.length} unchanged` : "")
   );
-  await inBatches(session.filesToUpload, UPLOAD_CONCURRENCY, async (upload) => {
-    const file = byPath.get(upload.path);
-    if (!file) {
-      throw new Error(`Server asked for unknown file ${upload.path}`);
-    }
-    await uploadFile(
-      upload.uploadUrl,
-      readFileSync4(file.absPath),
-      file.mimeType
+  const presence = startPublishingPresence(client, session.artifactId);
+  try {
+    await inBatches(
+      session.filesToUpload,
+      UPLOAD_CONCURRENCY,
+      async (upload) => {
+        const file = byPath.get(upload.path);
+        if (!file) {
+          throw new Error(`Server asked for unknown file ${upload.path}`);
+        }
+        await uploadFile(
+          upload.uploadUrl,
+          readFileSync4(file.absPath),
+          file.mimeType
+        );
+      }
     );
-  });
+  } finally {
+    presence.stop();
+  }
   const result = await client.finalize(session.publishSessionId);
   const rememberedProjectFile = placement.rememberProjectDefault ? writeProjectConfig(dir, placement.rememberProjectDefault) : null;
   const existingToken = config?.artifactId === result.artifactId ? config.publishToken : void 0;
@@ -1917,6 +2110,16 @@ Publish where? [1-${choices.length}]: `, (answer) => {
     });
   });
 }
+function startPublishingPresence(client, artifactId) {
+  const beat = () => {
+    client.agentHeartbeat(artifactId, "publishing").catch(() => {
+    });
+  };
+  beat();
+  const timer = setInterval(beat, AGENT_PRESENCE.heartbeatSeconds * 1e3);
+  timer.unref();
+  return { stop: () => clearInterval(timer) };
+}
 async function inBatches(items, concurrency, fn) {
   let next = 0;
   const workers = Array.from(
@@ -2526,30 +2729,145 @@ async function changeThreadStatus(opts) {
   console.log(`\u2713 ${verb} ${thread.id} \u2014 now ${thread.status}.`);
 }
 
+// src/share.ts
+import path14 from "path";
+var EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+async function share(opts) {
+  const dir = path14.resolve(opts.dir);
+  const target = resolveArtifactTarget(dir, {
+    apiKey: opts.apiKey,
+    artifact: opts.artifact
+  });
+  const client = createApiClient(target.apiUrl, target.credential);
+  if (opts.list) {
+    const { grants, visibility } = await client.listGrants(target.artifactId);
+    if (opts.json) {
+      console.log(JSON.stringify({ grants, visibility }, null, 2));
+      return;
+    }
+    console.log(`
+General access: ${visibility}`);
+    if (grants.length === 0) {
+      console.log("No one has been invited yet.\n");
+      return;
+    }
+    const label = grants.length === 1 ? "person" : "people";
+    console.log(`${grants.length} ${label} with a grant:
+`);
+    for (const grant of grants) {
+      const who = grant.name && grant.email ? `${grant.name} <${grant.email}>` : grant.name ?? grant.email ?? grant.userId ?? "unknown";
+      console.log(`  ${who} \xB7 ${grant.role} \xB7 ${grant.status}`);
+    }
+    console.log("");
+    return;
+  }
+  if (opts.emails.length === 0) {
+    throw new Error(
+      "Provide at least one email to invite, or --list to see current grants."
+    );
+  }
+  for (const email of opts.emails) {
+    if (!EMAIL_RE.test(email)) {
+      throw new Error(`"${email}" is not a valid email address.`);
+    }
+  }
+  const results = [];
+  for (const email of opts.emails) {
+    const grant = await client.createGrant(target.artifactId, { email });
+    results.push({ email, url: grant.url });
+  }
+  if (opts.json) {
+    console.log(JSON.stringify({ invited: results }, null, 2));
+    return;
+  }
+  console.log("");
+  for (const { email, url } of results) {
+    console.log(`\u2713 Invited ${email}`);
+    console.log(`  ${url}`);
+  }
+  console.log("");
+}
+async function unshare(opts) {
+  const dir = path14.resolve(opts.dir);
+  const target = resolveArtifactTarget(dir, {
+    apiKey: opts.apiKey,
+    artifact: opts.artifact
+  });
+  const client = createApiClient(target.apiUrl, target.credential);
+  const email = opts.email.toLowerCase();
+  const { grants } = await client.listGrants(target.artifactId);
+  const grant = grants.find((g) => g.email?.toLowerCase() === email);
+  if (!grant) {
+    throw new Error(`No active grant for ${opts.email} on this artifact.`);
+  }
+  await client.revokeGrant(target.artifactId, grant.id);
+  if (opts.json) {
+    console.log(JSON.stringify({ email: opts.email, revoked: true }, null, 2));
+    return;
+  }
+  console.log(`
+\u2713 Revoked access for ${opts.email}
+`);
+}
+
+// src/status.ts
+import path15 from "path";
+async function status(opts) {
+  if (!AGENT_STATES.includes(opts.state)) {
+    throw new Error(
+      `State must be one of: ${AGENT_STATES.join(", ")} (got "${opts.state}").`
+    );
+  }
+  const state = opts.state;
+  const dir = path15.resolve(opts.dir);
+  const target = resolveArtifactTarget(dir, {
+    apiKey: opts.apiKey,
+    artifact: opts.artifact
+  });
+  const client = createApiClient(target.apiUrl, target.credential);
+  const res = await client.agentHeartbeat(target.artifactId, state);
+  if (opts.json) {
+    console.log(
+      JSON.stringify(
+        {
+          artifactId: target.artifactId,
+          state,
+          ttlSeconds: res.ttlSeconds
+        },
+        null,
+        2
+      )
+    );
+    return;
+  }
+  const visible = res.ttlSeconds >= 120 ? `~${Math.round(res.ttlSeconds / 60)}m` : `~${res.ttlSeconds}s`;
+  console.log(`\u2713 Presence: ${state} (visible ${visible})`);
+}
+
 // src/update.ts
 import { existsSync as existsSync3, mkdirSync as mkdirSync3, readFileSync as readFileSync5, writeFileSync as writeFileSync3 } from "fs";
 import { createRequire } from "module";
 import { homedir as homedir2 } from "os";
-import path14 from "path";
-import { z as z17 } from "zod";
+import path16 from "path";
+import { z as z19 } from "zod";
 var REGISTRY_LATEST_URL = "https://registry.npmjs.org/artifact-cafe/latest";
 var SKILL_SOURCE_URL = "https://raw.githubusercontent.com/Artifact-Cafe/skill/main/artifact-cafe/SKILL.md";
 var SKILL_UPDATE_COMMAND = "npx skills add artifact-cafe/skill --skill artifact-cafe -g";
 var CHECK_TTL_MS = 24 * 60 * 60 * 1e3;
 var FETCH_TIMEOUT_MS = 2e3;
 var SKILL_VERSION_PATTERN = /\*\*Skill version:\s*(\d+\.\d+\.\d+)\*\*/;
-var cacheSchema = z17.object({
-  checkedAt: z17.number(),
-  cliLatest: z17.string().nullable(),
-  skillLatest: z17.string().nullable(),
-  version: z17.literal(1)
+var cacheSchema = z19.object({
+  checkedAt: z19.number(),
+  cliLatest: z19.string().nullable(),
+  skillLatest: z19.string().nullable(),
+  version: z19.literal(1)
 });
 function cliVersion() {
   const pkg = createRequire(import.meta.url)("../package.json");
   return pkg.version;
 }
 function cachePath() {
-  return path14.join(homedir2(), ".artifactcafe", "update-check.json");
+  return path16.join(homedir2(), ".artifactcafe", "update-check.json");
 }
 function readCache() {
   try {
@@ -2560,7 +2878,7 @@ function readCache() {
 }
 function writeCache(cache) {
   try {
-    mkdirSync3(path14.dirname(cachePath()), { mode: 448, recursive: true });
+    mkdirSync3(path16.dirname(cachePath()), { mode: 448, recursive: true });
     writeFileSync3(cachePath(), `${JSON.stringify(cache, null, 2)}
 `);
   } catch {
@@ -2597,7 +2915,7 @@ async function fetchText(url) {
 }
 async function fetchLatestVersions(previous) {
   const [cli, skill] = await Promise.all([
-    fetchJson(REGISTRY_LATEST_URL).then((body) => z17.object({ version: z17.string() }).parse(body).version).catch(() => null),
+    fetchJson(REGISTRY_LATEST_URL).then((body) => z19.object({ version: z19.string() }).parse(body).version).catch(() => null),
     fetchText(SKILL_SOURCE_URL).then((body) => SKILL_VERSION_PATTERN.exec(body)?.[1] ?? null).catch(() => null)
   ]);
   return {
@@ -2613,7 +2931,7 @@ function installedSkillVersions() {
   const versions = [];
   for (const root of roots) {
     for (const dir of dirs) {
-      const file = path14.join(root, dir, "skills", "artifact-cafe", "SKILL.md");
+      const file = path16.join(root, dir, "skills", "artifact-cafe", "SKILL.md");
       if (!existsSync3(file)) {
         continue;
       }
@@ -3076,6 +3394,47 @@ var listen = defineCommand({
     }
   }
 });
+var statusCmd = defineCommand({
+  args: {
+    "api-key": {
+      description: "Authorize with an account API key (default: stored login)",
+      type: "string"
+    },
+    artifact: {
+      description: "Act on an artifact ID instead of the linked folder",
+      type: "string"
+    },
+    dir: {
+      default: ".",
+      description: "Linked directory to authorize from (default: .)",
+      type: "string"
+    },
+    json: { description: "Machine-readable output", type: "boolean" },
+    state: {
+      description: "What the agent is doing: editing | publishing | listening",
+      required: true,
+      type: "positional"
+    }
+  },
+  meta: {
+    description: "Mark what the agent is doing on the linked artifact",
+    name: "status"
+  },
+  async run({ args }) {
+    try {
+      await status({
+        apiKey: args["api-key"],
+        artifact: args.artifact,
+        dir: args.dir,
+        json: Boolean(args.json),
+        state: args.state
+      });
+    } catch (err) {
+      printCliError(err, Boolean(args.json));
+      process.exit(1);
+    }
+  }
+});
 var protect2 = defineCommand({
   args: {
     "api-key": {
@@ -3361,6 +3720,89 @@ var del = defineCommand({
     }
   }
 });
+var share2 = defineCommand({
+  args: {
+    "api-key": {
+      description: "Authorize with an account API key (default: stored login)",
+      type: "string"
+    },
+    artifact: {
+      description: "Act on an artifact ID instead of the linked folder",
+      type: "string"
+    },
+    dir: {
+      default: ".",
+      description: "Linked directory to authorize from (default: .)",
+      type: "string"
+    },
+    json: { description: "Machine-readable output", type: "boolean" },
+    list: {
+      description: "List current grants instead of inviting",
+      type: "boolean"
+    }
+  },
+  meta: {
+    description: "Share the linked artifact with people by email",
+    name: "share"
+  },
+  async run({ args }) {
+    try {
+      await share({
+        apiKey: args["api-key"],
+        artifact: args.artifact,
+        dir: args.dir,
+        // citty collects bare positionals (the invited emails) in args._.
+        emails: (args._ ?? []).map(String),
+        json: Boolean(args.json),
+        list: Boolean(args.list)
+      });
+    } catch (err) {
+      printCliError(err, Boolean(args.json));
+      process.exit(1);
+    }
+  }
+});
+var unshare2 = defineCommand({
+  args: {
+    "api-key": {
+      description: "Authorize with an account API key (default: stored login)",
+      type: "string"
+    },
+    artifact: {
+      description: "Act on an artifact ID instead of the linked folder",
+      type: "string"
+    },
+    dir: {
+      default: ".",
+      description: "Linked directory to authorize from (default: .)",
+      type: "string"
+    },
+    email: {
+      description: "Email address to revoke",
+      required: true,
+      type: "positional"
+    },
+    json: { description: "Machine-readable output", type: "boolean" }
+  },
+  meta: {
+    description: "Revoke a person's access to the linked artifact",
+    name: "unshare"
+  },
+  async run({ args }) {
+    try {
+      await unshare({
+        apiKey: args["api-key"],
+        artifact: args.artifact,
+        dir: args.dir,
+        email: args.email,
+        json: Boolean(args.json)
+      });
+    } catch (err) {
+      printCliError(err, Boolean(args.json));
+      process.exit(1);
+    }
+  }
+});
 var open = defineCommand({
   args: {
     "api-key": {
@@ -3448,6 +3890,9 @@ var main = defineCommand({
     reopen,
     reply,
     resolve,
+    share: share2,
+    status: statusCmd,
+    unshare: unshare2,
     whoami: whoami2,
     workspaces: workspaces2
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "artifact-cafe",
-  "version": "0.0.10",
+  "version": "0.0.11",
   "description": "Publish AI-generated artifacts for review on artifact.cafe",
   "type": "module",
   "bin": {