@robbeverhelst/do 0.0.1 → 1.2.0

package/README.md

@@ -1,12 +1,15 @@
-# @do/cli
+# @robbeverhelst/do
 
 `do` — an agent-drivable command-line client over the **do** public API
 (`/api/v1`). A thin HTTP client: per-tenant API-key auth, the same validation and
 RLS wall as the web app, no direct database access.
 
+> Published to npm as **`@robbeverhelst/do`** (the `@do` scope is taken); the
+> installed command is `do`. The workspace package is named `@do/cli` internally.
+
 ```sh
-bunx @do/cli help
-bunx @do/cli today
+bunx @robbeverhelst/do help
+bunx @robbeverhelst/do today
 ```
 
 ## Scope (v1)

package/dist/do.js

@@ -19,7 +19,14 @@ var __export = (target, all) => {
 import { homedir } from "os";
 
 // src/args.ts
-var GLOBAL_BOOLEAN_FLAGS = ["json", "quiet", "verbose", "help", "version"];
+var GLOBAL_BOOLEAN_FLAGS = [
+  "json",
+  "quiet",
+  "verbose",
+  "help",
+  "version",
+  "allow-destructive"
+];
 var SHORT_ALIASES = {
   h: "help",
   q: "quiet",
@@ -4577,6 +4584,7 @@ var calendarEventLinks = pgTable("calendar_event_links", {
 var apiKeys = pgTable("api_keys", {
   id: text("id").primaryKey(),
   tenantId: text("tenant_id").notNull().references(() => tenants.id),
+  userId: text("user_id").references(() => users.id),
   name: text("name").notNull(),
   prefix: text("prefix").notNull(),
   keyHash: text("key_hash").notNull().unique(),
@@ -20037,6 +20045,31 @@ var ingestSyncResultSchema = exports_external.object({
   skipped: exports_external.number().int().nonnegative(),
   resources: exports_external.array(ingestResourceResultSchema)
 });
+// ../../packages/schema/src/contracts/github.ts
+var GITHUB_RESOURCES = ["commits", "pull_requests", "issues"];
+var githubResourceSchema = exports_external.enum(GITHUB_RESOURCES);
+var githubBase = {
+  repo: exports_external.string().min(1),
+  url: exports_external.string().min(1)
+};
+var githubCommitValueSchema = exports_external.object({
+  ...githubBase,
+  sha: exports_external.string().min(1),
+  message: exports_external.string().default("")
+}).strict();
+var githubPullRequestValueSchema = exports_external.object({
+  ...githubBase,
+  number: exports_external.number().int().positive(),
+  title: exports_external.string().default(""),
+  state: exports_external.string().min(1),
+  merged: exports_external.boolean().default(false)
+}).strict();
+var githubIssueValueSchema = exports_external.object({
+  ...githubBase,
+  number: exports_external.number().int().positive(),
+  title: exports_external.string().default(""),
+  state: exports_external.string().min(1)
+}).strict();
 // ../../packages/schema/src/contracts/strava.ts
 var stravaActivitySchema = exports_external.object({
   id: exports_external.number(),
@@ -20097,7 +20130,23 @@ var apiKeyScopeSchema = exports_external.enum([
   "notes:read",
   "notes:write",
   "contacts:read",
-  "contacts:write"
+  "contacts:write",
+  "projects:read",
+  "projects:write",
+  "routines:read",
+  "routines:write",
+  "settings:read",
+  "settings:write",
+  "calendar:read",
+  "members:read",
+  "members:write",
+  "sharing:read",
+  "sharing:write",
+  "comments:read",
+  "comments:write",
+  "roles:read",
+  "links:read",
+  "links:write"
 ]);
 var apiKeySchema = createSelectSchema(apiKeys, {
   scopes: exports_external.array(apiKeyScopeSchema),
@@ -20115,6 +20164,7 @@ var createApiKeyResultSchema = apiKeyPublicSchema.extend({ key: exports_external
 var apiKeyContextSchema = exports_external.object({
   apiKeyId: exports_external.string(),
   tenantId: exports_external.string(),
+  userId: exports_external.string().nullable(),
   scopes: exports_external.array(apiKeyScopeSchema)
 });
 // ../../packages/schema/src/contracts/webhooks.ts
@@ -20965,7 +21015,7 @@ function parseCapture(input) {
 
 // src/meta.ts
 var CLI_NAME = "do";
-var VERSION = "0.0.0";
+var VERSION = "1.2.0";
 var API_PREFIX = "/api/v1";
 var DEFAULT_API_URL = "http://localhost:3001";
 
@@ -20984,6 +21034,12 @@ class DoClient {
   patch(path, body) {
     return this.request("PATCH", path, { body });
   }
+  put(path, body) {
+    return this.request("PUT", path, { body });
+  }
+  delete(path) {
+    return this.request("DELETE", path, {});
+  }
   url(path, query) {
     const origin = this.opts.apiUrl.replace(/\/+$/, "");
     const url2 = new URL(`${origin}${API_PREFIX}${path}`);
@@ -21127,7 +21183,15 @@ var ENTITIES = [
     canGet: true,
     listFlags: [
       { name: "filter", description: "all (default) or unsorted (the GTD inbox)", query: "filter" }
-    ]
+    ],
+    write: {
+      scope: "tasks:write",
+      createSchema: createTaskInputSchema,
+      createInput: "CreateTaskInput",
+      updateSchema: updateTaskInputSchema,
+      updateInput: "UpdateTaskInput",
+      canDelete: true
+    }
   },
   {
     name: "habits",
@@ -21135,22 +21199,79 @@ var ENTITIES = [
     readScope: "habits:read",
     returns: "HabitSummary",
     canGet: true,
-    listFlags: []
+    listFlags: [],
+    write: {
+      scope: "habits:write",
+      createSchema: createHabitInputSchema,
+      createInput: "CreateHabitInput",
+      updateSchema: updateHabitInputSchema,
+      updateInput: "UpdateHabitInput",
+      canDelete: true
+    }
   },
   {
-    name: "occurrences",
-    path: "/occurrences",
-    readScope: "occurrences:read",
-    returns: "Occurrence",
-    canGet: false,
-    listFlags: [
-      {
-        name: "template-id",
-        description: "ULID of the recurring template (required)",
-        required: true,
-        query: "templateId"
-      }
-    ]
+    name: "projects",
+    path: "/projects",
+    readScope: "projects:read",
+    returns: "ProjectView",
+    canGet: true,
+    listFlags: [],
+    write: {
+      scope: "projects:write",
+      createSchema: createProjectInputSchema,
+      createInput: "CreateProjectInput",
+      updateSchema: updateProjectInputSchema,
+      updateInput: "UpdateProjectInput",
+      canDelete: true
+    }
+  },
+  {
+    name: "routines",
+    path: "/routines",
+    readScope: "routines:read",
+    returns: "RoutineView",
+    canGet: true,
+    listFlags: [],
+    write: {
+      scope: "routines:write",
+      createSchema: createRoutineInputSchema,
+      createInput: "CreateRoutineInput",
+      updateSchema: updateRoutineInputSchema,
+      updateInput: "UpdateRoutineInput",
+      canDelete: true
+    }
+  },
+  {
+    name: "notes",
+    path: "/notes",
+    readScope: "notes:read",
+    returns: "Note",
+    canGet: true,
+    listFlags: [],
+    write: {
+      scope: "notes:write",
+      createSchema: createNoteInputSchema,
+      createInput: "CreateNoteInput",
+      updateSchema: updateNoteInputSchema,
+      updateInput: "UpdateNoteInput",
+      canDelete: true
+    }
+  },
+  {
+    name: "contacts",
+    path: "/contacts",
+    readScope: "contacts:read",
+    returns: "Contact",
+    canGet: true,
+    listFlags: [],
+    write: {
+      scope: "contacts:write",
+      createSchema: createContactInputSchema,
+      createInput: "CreateContactInput",
+      updateSchema: updateContactInputSchema,
+      updateInput: "UpdateContactInput",
+      canDelete: true
+    }
   },
   {
     name: "shopping-lists",
@@ -21158,7 +21279,15 @@ var ENTITIES = [
     readScope: "shopping:read",
     returns: "ShoppingList",
     canGet: true,
-    listFlags: []
+    listFlags: [],
+    write: {
+      scope: "shopping:write",
+      createSchema: createShoppingListInputSchema,
+      createInput: "CreateShoppingListInput",
+      updateSchema: updateShoppingListInputSchema,
+      updateInput: "UpdateShoppingListInput",
+      canDelete: true
+    }
   },
   {
     name: "inventory-items",
@@ -21166,7 +21295,15 @@ var ENTITIES = [
     readScope: "inventory:read",
     returns: "InventoryItem",
     canGet: true,
-    listFlags: []
+    listFlags: [],
+    write: {
+      scope: "inventory:write",
+      createSchema: createInventoryItemInputSchema,
+      createInput: "CreateInventoryItemInput",
+      updateSchema: updateInventoryItemInputSchema,
+      updateInput: "UpdateInventoryItemInput",
+      canDelete: true
+    }
   },
   {
     name: "recipes",
@@ -21174,7 +21311,15 @@ var ENTITIES = [
     readScope: "meals:read",
     returns: "Recipe",
     canGet: true,
-    listFlags: []
+    listFlags: [],
+    write: {
+      scope: "meals:write",
+      createSchema: createRecipeInputSchema,
+      createInput: "CreateRecipeInput",
+      updateSchema: updateRecipeInputSchema,
+      updateInput: "UpdateRecipeInput",
+      canDelete: true
+    }
   },
   {
     name: "meal-plans",
@@ -21182,23 +21327,30 @@ var ENTITIES = [
     readScope: "meals:read",
     returns: "MealPlan",
     canGet: true,
-    listFlags: []
-  },
-  {
-    name: "notes",
-    path: "/notes",
-    readScope: "notes:read",
-    returns: "Note",
-    canGet: true,
-    listFlags: []
+    listFlags: [],
+    write: {
+      scope: "meals:write",
+      createSchema: createMealPlanInputSchema,
+      createInput: "CreateMealPlanInput",
+      updateSchema: updateMealPlanInputSchema,
+      updateInput: "UpdateMealPlanInput",
+      canDelete: true
+    }
   },
   {
-    name: "contacts",
-    path: "/contacts",
-    readScope: "contacts:read",
-    returns: "Contact",
-    canGet: true,
-    listFlags: []
+    name: "occurrences",
+    path: "/occurrences",
+    readScope: "occurrences:read",
+    returns: "Occurrence",
+    canGet: false,
+    listFlags: [
+      {
+        name: "template-id",
+        description: "ULID of the recurring template (required)",
+        required: true,
+        query: "templateId"
+      }
+    ]
   },
   {
     name: "webhooks",
@@ -21210,6 +21362,18 @@ var ENTITIES = [
   }
 ];
 var entityByName = (name) => ENTITIES.find((e) => e.name === name);
+function entityOperations(e) {
+  const ops = ["list"];
+  if (e.canGet)
+    ops.push("get");
+  if (e.write?.createSchema)
+    ops.push("create");
+  if (e.write?.updateSchema)
+    ops.push("update");
+  if (e.write?.canDelete)
+    ops.push("delete");
+  return ops;
+}
 
 // src/registry.ts
 var GLOBAL_FLAGS = [
@@ -21227,7 +21391,17 @@ var GLOBAL_FLAGS = [
     description: "API origin; overrides DO_API_URL and the config file."
   },
   { name: "help", type: "boolean", description: "Show help for the command." },
-  { name: "version", type: "boolean", description: "Print the CLI version." }
+  { name: "version", type: "boolean", description: "Print the CLI version." },
+  {
+    name: "data",
+    type: "string",
+    description: `JSON object body for create/update (e.g. --data '{"title":"Buy milk"}').`
+  },
+  {
+    name: "allow-destructive",
+    type: "boolean",
+    description: "Permit a destructive verb (delete/revoke/remove-member). Off by default \u2014 a guardrail for autonomous agents."
+  }
 ];
 var COMMAND_SPECS = [
   {
@@ -21288,6 +21462,199 @@ var COMMAND_SPECS = [
     scopes: ["habits:write"],
     returns: "HabitSummary"
   },
+  {
+    path: ["settings", "get"],
+    summary: "Show the caller's settings for the Space.",
+    args: [],
+    flags: [],
+    scopes: ["settings:read"],
+    returns: "UserSettings",
+    notes: "Needs a key minted while logged in (it carries the user identity)."
+  },
+  {
+    path: ["settings", "update"],
+    summary: "Patch the caller's settings.",
+    args: [],
+    flags: [{ name: "data", type: "string", description: "JSON of fields to change." }],
+    scopes: ["settings:write"],
+    returns: "UserSettings"
+  },
+  {
+    path: ["invite", "create"],
+    summary: "Create a Space invite (email/link/guest).",
+    args: [],
+    flags: [
+      {
+        name: "data",
+        type: "string",
+        description: 'JSON CreateInviteInput, e.g. {"type":"link"} or {"type":"email","email":"a@b.c"}.'
+      }
+    ],
+    scopes: ["members:write"],
+    returns: "Invite"
+  },
+  {
+    path: ["invite", "list"],
+    summary: "List the Space's invites.",
+    args: [],
+    flags: [],
+    scopes: ["members:read"],
+    returns: "Invite"
+  },
+  {
+    path: ["invite", "revoke"],
+    summary: "Revoke an invite (destructive).",
+    args: [{ name: "id", required: true, description: "Invite ULID." }],
+    flags: [
+      { name: "allow-destructive", type: "boolean", description: "Required to actually revoke." }
+    ],
+    scopes: ["members:write"],
+    returns: "None",
+    notes: "Destructive \u2014 gated behind --allow-destructive + a members:write key."
+  },
+  {
+    path: ["member", "list"],
+    summary: "List the Space's members.",
+    args: [],
+    flags: [],
+    scopes: ["members:read"],
+    returns: "MemberView"
+  },
+  {
+    path: ["member", "role"],
+    summary: "Set a member's role.",
+    args: [{ name: "id", required: true, description: "Member ULID (tenant_members.id)." }],
+    flags: [
+      { name: "role", type: "string", description: "Base role: owner|admin|member|guest." },
+      { name: "data", type: "string", description: "JSON SetMemberRoleInput (overrides --role)." }
+    ],
+    scopes: ["members:write"],
+    returns: "MemberView"
+  },
+  {
+    path: ["member", "remove"],
+    summary: "Remove a member from the Space (destructive).",
+    args: [{ name: "id", required: true, description: "Member ULID." }],
+    flags: [
+      { name: "allow-destructive", type: "boolean", description: "Required to actually remove." }
+    ],
+    scopes: ["members:write"],
+    returns: "None",
+    notes: "Destructive \u2014 gated behind --allow-destructive + a members:write key."
+  },
+  {
+    path: ["share"],
+    summary: "Share a node with a member or role.",
+    args: [{ name: "node", required: true, description: "Node ULID to share." }],
+    flags: [
+      { name: "to", type: "string", description: "Subject ULID (member id, or role id)." },
+      {
+        name: "cap",
+        type: "string",
+        description: "Capability: view|comment|edit|admin.",
+        default: "view"
+      },
+      {
+        name: "subject-type",
+        type: "string",
+        description: "member (default) or role.",
+        default: "member"
+      }
+    ],
+    scopes: ["sharing:write"],
+    returns: "NodeGrantView"
+  },
+  {
+    path: ["share", "list"],
+    summary: "List the grants on a node.",
+    args: [{ name: "node", required: true, description: "Node ULID." }],
+    flags: [],
+    scopes: ["sharing:read"],
+    returns: "NodeGrantView"
+  },
+  {
+    path: ["share", "revoke"],
+    summary: "Revoke a node grant (destructive).",
+    args: [
+      { name: "node", required: true, description: "Node ULID." },
+      { name: "grant", required: true, description: "Grant ULID." }
+    ],
+    flags: [
+      { name: "allow-destructive", type: "boolean", description: "Required to actually revoke." }
+    ],
+    scopes: ["sharing:write"],
+    returns: "None",
+    notes: "Destructive \u2014 gated behind --allow-destructive + a sharing:write key."
+  },
+  {
+    path: ["assign"],
+    summary: "Assign/delegate a node to a member.",
+    args: [{ name: "node", required: true, description: "Node ULID to assign." }],
+    flags: [
+      { name: "to", type: "string", description: "Member ULID to assign to." },
+      { name: "cap", type: "string", description: "Capability (default edit).", default: "edit" }
+    ],
+    scopes: ["sharing:write"],
+    returns: "NodeGrantView"
+  },
+  {
+    path: ["comment"],
+    summary: "Post a comment on a node.",
+    args: [
+      { name: "node", required: true, description: "Node ULID." },
+      { name: "body", required: true, description: "Comment text." }
+    ],
+    flags: [],
+    scopes: ["comments:write"],
+    returns: "CommentView"
+  },
+  {
+    path: ["comment", "list"],
+    summary: "List a node's comment thread.",
+    args: [{ name: "node", required: true, description: "Node ULID." }],
+    flags: [],
+    scopes: ["comments:read"],
+    returns: "CommentView"
+  },
+  {
+    path: ["role", "list"],
+    summary: "List the Space's custom roles.",
+    args: [],
+    flags: [],
+    scopes: ["roles:read"],
+    returns: "RoleView"
+  },
+  {
+    path: ["link", "create"],
+    summary: "Mint a public share-link to a node.",
+    args: [{ name: "node", required: true, description: "Node ULID to link." }],
+    flags: [
+      { name: "cap", type: "string", description: "Capability (default view).", default: "view" },
+      { name: "expires", type: "string", description: "Expiry (ISO date/time)." }
+    ],
+    scopes: ["links:write"],
+    returns: "CreateShareLinkResult",
+    notes: "The signed token is returned once, in the create response."
+  },
+  {
+    path: ["link", "list"],
+    summary: "List the share-links for a node.",
+    args: [{ name: "node", required: true, description: "Node ULID." }],
+    flags: [],
+    scopes: ["links:read"],
+    returns: "ShareLinkPublic"
+  },
+  {
+    path: ["link", "revoke"],
+    summary: "Revoke a share-link (destructive).",
+    args: [{ name: "id", required: true, description: "Share-link ULID." }],
+    flags: [
+      { name: "allow-destructive", type: "boolean", description: "Required to actually revoke." }
+    ],
+    scopes: ["links:write"],
+    returns: "ShareLinkPublic",
+    notes: "Destructive \u2014 gated behind --allow-destructive + a links:write key."
+  },
   {
     path: ["whoami"],
     summary: "Show the tenant and scopes the configured key resolves to.",
@@ -21402,9 +21769,16 @@ function buildManifest() {
     })),
     entities: ENTITIES.map((e) => ({
       name: e.name,
-      operations: e.canGet ? ["list", "get"] : ["list"],
+      operations: entityOperations(e),
       path: `${API_PREFIX}${e.path}`,
       readScope: e.readScope,
+      ...e.write ? { writeScope: e.write.scope } : {},
+      ...e.write?.createInput || e.write?.updateInput ? {
+        inputs: {
+          ...e.write.createInput ? { create: e.write.createInput } : {},
+          ...e.write.updateInput ? { update: e.write.updateInput } : {}
+        }
+      } : {},
       returns: e.returns,
       listFlags: e.listFlags.map((f) => ({
         name: f.name,
@@ -21691,30 +22065,57 @@ async function dispatch(positionals, flags, io, mode, config2) {
   }
   const entity = entityByName(positionals[0] ?? "");
   if (entity) {
-    const op = positionals[1];
-    const rest = positionals.slice(2);
-    const client = requireClient();
-    if (op === "list") {
-      const query = {};
-      for (const f of entity.listFlags) {
-        const value = flagString(flags, f.name);
-        if (value !== undefined)
-          query[f.query ?? f.name] = value;
-        else if (f.required)
-          throw usageError(`\`${entity.name} list\` requires --${f.name}`);
-      }
-      return { data: await client.get(entity.path, { query }), render: renderList };
-    }
-    if (op === "get") {
-      if (!entity.canGet)
-        throw usageError(`\`${entity.name}\` has no get-by-id; use \`${entity.name} list\``);
-      const id = requireArg(rest, 0, "id");
-      return { data: await client.get(`${entity.path}/${id}`), render: renderRecord };
-    }
-    throw usageError(`unknown operation for ${entity.name}: \`${op ?? ""}\` (use list or get)`);
+    return dispatchEntity(entity, positionals.slice(1), flags, requireClient);
   }
   throw usageError(`unknown command: \`${positionals.join(" ")}\` \u2014 run \`do help\``);
 }
+async function dispatchEntity(entity, rest, flags, requireClient) {
+  const op = rest[0];
+  const args = rest.slice(1);
+  const client = requireClient();
+  if (op === "list") {
+    const query = {};
+    for (const f of entity.listFlags) {
+      const value = flagString(flags, f.name);
+      if (value !== undefined)
+        query[f.query ?? f.name] = value;
+      else if (f.required)
+        throw usageError(`\`${entity.name} list\` requires --${f.name}`);
+    }
+    return { data: await client.get(entity.path, { query }), render: renderList };
+  }
+  if (op === "get") {
+    if (!entity.canGet)
+      throw usageError(`\`${entity.name}\` has no get-by-id; use \`${entity.name} list\``);
+    const id = requireArg(args, 0, "id");
+    return { data: await client.get(`${entity.path}/${id}`), render: renderRecord };
+  }
+  if (op === "create") {
+    const write = requireWrite(entity, "create");
+    if (!write.createSchema)
+      throw usageError(`\`${entity.name}\` cannot be created`);
+    const body = parseInput(write.createSchema, { id: ulid3(), ...readDataFlag(flags) });
+    return { data: await client.post(entity.path, body), render: renderRecord };
+  }
+  if (op === "update") {
+    const write = requireWrite(entity, "update");
+    if (!write.updateSchema)
+      throw usageError(`\`${entity.name}\` cannot be updated`);
+    const id = requireArg(args, 0, "id");
+    const body = parseInput(write.updateSchema, readDataFlag(flags));
+    return { data: await client.patch(`${entity.path}/${id}`, body), render: renderRecord };
+  }
+  if (op === "delete") {
+    const write = requireWrite(entity, "delete");
+    if (!write.canDelete)
+      throw usageError(`\`${entity.name}\` cannot be deleted`);
+    const id = requireArg(args, 0, "id");
+    assertDestructiveAllowed(flags, `delete ${entity.name} ${id}`);
+    await client.delete(`${entity.path}/${id}`);
+    return { data: { ok: true, deleted: id }, render: renderRecord };
+  }
+  throw usageError(`unknown operation for ${entity.name}: \`${op ?? ""}\` (use ${entityOperations(entity).join(", ")})`);
+}
 function runFixed(spec, ctx) {
   const key = spec.path.join(" ");
   const handler = HANDLERS[key];
@@ -21775,6 +22176,121 @@ var HANDLERS = {
       render: renderHabit
     };
   },
+  "settings get": async ({ requireClient }) => ({
+    data: await requireClient().get("/settings"),
+    render: renderRecord
+  }),
+  "settings update": async ({ flags, requireClient }) => {
+    const body = parseInput(updateUserSettingsInputSchema, readDataFlag(flags));
+    return { data: await requireClient().patch("/settings", body), render: renderRecord };
+  },
+  "invite create": async ({ flags, requireClient }) => {
+    const body = parseInput(createInviteInputSchema, { id: ulid3(), ...readDataFlag(flags) });
+    return { data: await requireClient().post("/invites", body), render: renderRecord };
+  },
+  "invite list": async ({ requireClient }) => ({
+    data: await requireClient().get("/invites"),
+    render: renderList
+  }),
+  "invite revoke": async ({ args, flags, requireClient }) => {
+    const id = requireArg(args, 0, "invite id");
+    assertDestructiveAllowed(flags, `revoke invite ${id}`);
+    await requireClient().delete(`/invites/${id}`);
+    return { data: { ok: true, revoked: id }, render: renderRecord };
+  },
+  "member list": async ({ requireClient }) => ({
+    data: await requireClient().get("/members"),
+    render: renderList
+  }),
+  "member role": async ({ args, flags, requireClient }) => {
+    const id = requireArg(args, 0, "member id");
+    const role = flagString(flags, "role");
+    const raw = flagString(flags, "data") ? readDataFlag(flags) : role ? { role } : {};
+    const body = parseInput(setMemberRoleInputSchema, raw);
+    return { data: await requireClient().patch(`/members/${id}/role`, body), render: renderRecord };
+  },
+  "member remove": async ({ args, flags, requireClient }) => {
+    const id = requireArg(args, 0, "member id");
+    assertDestructiveAllowed(flags, `remove member ${id}`);
+    await requireClient().delete(`/members/${id}`);
+    return { data: { ok: true, removed: id }, render: renderRecord };
+  },
+  share: async ({ args, flags, requireClient }) => {
+    const node = requireArg(args, 0, "node id");
+    const subjectId = requireFlag(flags, "to", "share needs --to <member-or-role-id>");
+    const body = parseInput(createNodeGrantInputSchema, {
+      id: ulid3(),
+      subjectType: flagString(flags, "subject-type") ?? "member",
+      subjectId,
+      capability: flagString(flags, "cap") ?? "view"
+    });
+    return {
+      data: await requireClient().post(`/sharing/nodes/${node}/grants`, body),
+      render: renderRecord
+    };
+  },
+  "share list": async ({ args, requireClient }) => {
+    const node = requireArg(args, 0, "node id");
+    return { data: await requireClient().get(`/sharing/nodes/${node}/grants`), render: renderList };
+  },
+  "share revoke": async ({ args, flags, requireClient }) => {
+    const node = requireArg(args, 0, "node id");
+    const grant = requireArg(args, 1, "grant id");
+    assertDestructiveAllowed(flags, `revoke grant ${grant}`);
+    await requireClient().delete(`/sharing/nodes/${node}/grants/${grant}`);
+    return { data: { ok: true, revoked: grant }, render: renderRecord };
+  },
+  assign: async ({ args, flags, requireClient }) => {
+    const node = requireArg(args, 0, "node id");
+    const memberId = requireFlag(flags, "to", "assign needs --to <member-id>");
+    const body = parseInput(assignNodeInputSchema, {
+      id: ulid3(),
+      memberId,
+      ...flagString(flags, "cap") ? { capability: flagString(flags, "cap") } : {}
+    });
+    return {
+      data: await requireClient().put(`/sharing/nodes/${node}/assignee`, body),
+      render: renderRecord
+    };
+  },
+  comment: async ({ args, requireClient }) => {
+    const node = requireArg(args, 0, "node id");
+    const body = args.slice(1).join(" ").trim();
+    if (body.length === 0)
+      throw usageError('comment needs text, e.g. `do comment <node> "Nice!"`');
+    const input = parseInput(createCommentInputSchema, { id: ulid3(), nodeId: node, body });
+    return { data: await requireClient().post("/comments", input), render: renderRecord };
+  },
+  "comment list": async ({ args, requireClient }) => {
+    const node = requireArg(args, 0, "node id");
+    return {
+      data: await requireClient().get("/comments", { query: { nodeId: node } }),
+      render: renderList
+    };
+  },
+  "role list": async ({ requireClient }) => ({
+    data: await requireClient().get("/roles"),
+    render: renderList
+  }),
+  "link create": async ({ args, flags, requireClient }) => {
+    const node = requireArg(args, 0, "node id");
+    const body = parseInput(createShareLinkInputSchema, {
+      id: ulid3(),
+      nodeId: node,
+      ...flagString(flags, "cap") ? { capability: flagString(flags, "cap") } : {},
+      ...flagString(flags, "expires") ? { expiresAt: flagString(flags, "expires") } : {}
+    });
+    return { data: await requireClient().post("/share-links", body), render: renderRecord };
+  },
+  "link list": async ({ args, requireClient }) => {
+    const node = requireArg(args, 0, "node id");
+    return { data: await requireClient().get(`/share-links/node/${node}`), render: renderList };
+  },
+  "link revoke": async ({ args, flags, requireClient }) => {
+    const id = requireArg(args, 0, "share-link id");
+    assertDestructiveAllowed(flags, `revoke share-link ${id}`);
+    return { data: await requireClient().delete(`/share-links/${id}`), render: renderRecord };
+  },
   whoami: async ({ requireClient }) => ({
     data: await requireClient().get("/whoami"),
     render: renderWhoami
@@ -21849,6 +22365,12 @@ function requireArg(args, index2, name) {
   }
   return value;
 }
+function requireFlag(flags, name, hint) {
+  const value = flagString(flags, name);
+  if (value === undefined || value.length === 0)
+    throw usageError(hint);
+  return value;
+}
 function assertConfigKey(key) {
   if (!CONFIG_KEYS.includes(key)) {
     throw usageError(`unknown config key \`${key}\` \u2014 valid keys: ${CONFIG_KEYS.join(", ")}`);
@@ -21882,6 +22404,32 @@ function redact(secret) {
     return "********";
   return `${secret.slice(0, 6)}\u2026${secret.slice(-2)}`;
 }
+function requireWrite(entity, op) {
+  if (!entity.write) {
+    throw usageError(`\`${entity.name}\` is read-only \u2014 \`${op}\` is not available`);
+  }
+  return entity.write;
+}
+function readDataFlag(flags) {
+  const raw = flagString(flags, "data");
+  if (raw === undefined)
+    return {};
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw usageError(`--data is not valid JSON: ${err.message}`);
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw usageError("--data must be a JSON object");
+  }
+  return parsed;
+}
+function assertDestructiveAllowed(flags, action) {
+  if (!flagBool(flags, "allow-destructive")) {
+    throw new CliError("destructive_blocked", `refusing to ${action} without --allow-destructive (a guardrail for autonomous agents)`, EXIT.USAGE);
+  }
+}
 
 // src/run.ts
 async function run(argv, io) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robbeverhelst/do",
-  "version": "0.0.1",
+  "version": "1.2.0",
   "private": false,
   "description": "do — the agent-drivable CLI over the public /api/v1 surface",
   "type": "module",