docs: generate the command catalogue from the command tables

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2 files changed, 39 insertions, 31 deletions

diff --git a/src/commands.c b/src/commands.c
index fe97afa..f30e82a 100644
--- a/src/commands.c
+++ b/src/commands.c
@@ -10,52 +10,64 @@
 /* discovery                                                           */
 /* ------------------------------------------------------------------ */
 
-static yyjson_mut_val *command_json(struct req *r, const struct command *c)
+static yyjson_mut_val *command_json(yyjson_mut_doc *doc,
+                                    const struct command *c)
 {
-    yyjson_mut_val *o = yyjson_mut_obj(r->rdoc);
-    yyjson_mut_obj_add_strcpy(r->rdoc, o, "name", c->name);
-    yyjson_mut_obj_add_strcpy(r->rdoc, o, "summary", c->summary);
-    yyjson_mut_obj_add_bool(r->rdoc, o, "mutating", c->mutating != 0);
-    yyjson_mut_obj_add_bool(r->rdoc, o, "dry_run", c->dry_run != 0);
-    yyjson_mut_val *perm = yyjson_mut_obj(r->rdoc);
-    yyjson_mut_obj_add_strcpy(r->rdoc, perm, "role", perm_name(c->perm));
+    yyjson_mut_val *o = yyjson_mut_obj(doc);
+    yyjson_mut_obj_add_strcpy(doc, o, "name", c->name);
+    yyjson_mut_obj_add_strcpy(doc, o, "summary", c->summary);
+    yyjson_mut_obj_add_bool(doc, o, "mutating", c->mutating != 0);
+    yyjson_mut_obj_add_bool(doc, o, "dry_run", c->dry_run != 0);
+    yyjson_mut_val *perm = yyjson_mut_obj(doc);
+    yyjson_mut_obj_add_strcpy(doc, perm, "role", perm_name(c->perm));
     const char *scope = perm_scope(c->perm);
     if (scope)
-        yyjson_mut_obj_add_strcpy(r->rdoc, perm, "scope", scope);
+        yyjson_mut_obj_add_strcpy(doc, perm, "scope", scope);
     else
-        yyjson_mut_obj_add_null(r->rdoc, perm, "scope");
-    yyjson_mut_obj_add_bool(r->rdoc, perm, "require_org", c->need_org != 0);
-    yyjson_mut_obj_add_val(r->rdoc, o, "permission", perm);
-    yyjson_mut_val *args = yyjson_mut_arr(r->rdoc);
+        yyjson_mut_obj_add_null(doc, perm, "scope");
+    yyjson_mut_obj_add_bool(doc, perm, "require_org", c->need_org != 0);
+    yyjson_mut_obj_add_val(doc, o, "permission", perm);
+    yyjson_mut_val *args = yyjson_mut_arr(doc);
     for (size_t i = 0; i < c->nargs; i++) {
         const struct cmd_arg *a = &c->args[i];
-        yyjson_mut_val *ao = yyjson_mut_arr_add_obj(r->rdoc, args);
-        yyjson_mut_obj_add_strcpy(r->rdoc, ao, "name", a->name);
-        yyjson_mut_obj_add_strcpy(r->rdoc, ao, "type",
+        yyjson_mut_val *ao = yyjson_mut_arr_add_obj(doc, args);
+        yyjson_mut_obj_add_strcpy(doc, ao, "name", a->name);
+        yyjson_mut_obj_add_strcpy(doc, ao, "type",
                                   arg_type_name(a->type));
-        yyjson_mut_obj_add_bool(r->rdoc, ao, "required", a->required != 0);
+        yyjson_mut_obj_add_bool(doc, ao, "required", a->required != 0);
         if (a->def)
-            yyjson_mut_obj_add_strcpy(r->rdoc, ao, "default", a->def);
+            yyjson_mut_obj_add_strcpy(doc, ao, "default", a->def);
         if (a->values) {
-            yyjson_mut_val *vals = yyjson_mut_arr(r->rdoc);
+            yyjson_mut_val *vals = yyjson_mut_arr(doc);
             const char *p = a->values;
             while (*p) {
                 const char *comma = strchr(p, ',');
                 size_t len = comma ? (size_t)(comma - p) : strlen(p);
-                yyjson_mut_arr_add_strn(r->rdoc, vals, p, len);
+                yyjson_mut_arr_add_strn(doc, vals, p, len);
                 if (!comma)
                     break;
                 p = comma + 1;
             }
-            yyjson_mut_obj_add_val(r->rdoc, ao, "values", vals);
+            yyjson_mut_obj_add_val(doc, ao, "values", vals);
         }
         if (a->desc)
-            yyjson_mut_obj_add_strcpy(r->rdoc, ao, "description", a->desc);
+            yyjson_mut_obj_add_strcpy(doc, ao, "description", a->desc);
     }
-    yyjson_mut_obj_add_val(r->rdoc, o, "args", args);
+    yyjson_mut_obj_add_val(doc, o, "args", args);
     return o;
 }
 
+yyjson_mut_val *commands_describe(yyjson_mut_doc *doc)
+{
+    yyjson_mut_val *arr = yyjson_mut_arr(doc);
+    for (size_t t = 0; t < g_command_tables_count; t++) {
+        const struct cmd_table *tab = g_command_tables[t];
+        for (size_t i = 0; i < tab->n; i++)
+            yyjson_mut_arr_add_val(arr, command_json(doc, &tab->cmds[i]));
+    }
+    return arr;
+}
+
 static yyjson_mut_val *h_describe(struct req *r)
 {
     const char *name = arg_str(r->args, "cmd");
@@ -66,16 +78,11 @@ static yyjson_mut_val *h_describe(struct req *r)
         const struct command *c = command_find(name);
         if (!c)
             return fail(r, "NOT_FOUND", "unknown command");
-        yyjson_mut_obj_add_val(r->rdoc, o, "command", command_json(r, c));
+        yyjson_mut_obj_add_val(r->rdoc, o, "command",
+                               command_json(r->rdoc, c));
         return o;
     }
-    yyjson_mut_val *arr = yyjson_mut_arr(r->rdoc);
-    for (size_t t = 0; t < g_command_tables_count; t++) {
-        const struct cmd_table *tab = g_command_tables[t];
-        for (size_t i = 0; i < tab->n; i++)
-            yyjson_mut_arr_add_val(arr, command_json(r, &tab->cmds[i]));
-    }
-    yyjson_mut_obj_add_val(r->rdoc, o, "commands", arr);
+    yyjson_mut_obj_add_val(r->rdoc, o, "commands", commands_describe(r->rdoc));
     return o;
 }
 
diff --git a/src/commands.h b/src/commands.h
index e7e71f6..3bcd447 100644
--- a/src/commands.h
+++ b/src/commands.h
@@ -50,6 +50,7 @@ extern const size_t g_command_tables_count;
 int command_validate_args(const struct command *cmd, yyjson_val *args,
                           char *err, size_t errlen);
 const struct command *command_find(const char *name);
+yyjson_mut_val *commands_describe(yyjson_mut_doc *doc);
 const char *perm_name(enum cmd_perm p);
 const char *perm_scope(enum cmd_perm p);