@canra/cli 0.4.0 → 0.5.0

package/README.md

@@ -29,7 +29,8 @@ canra search json
 | `canra remove <owner>/<name>` | Delete a fetched spec from `.canra/specs/` |
 | `canra login` | Save a registry URL and API token |
 | `canra whoami` | Show which account your saved token belongs to |
-| `canra publish <file.spec.md>` | Publish a spec (needs a token) |
+| `canra publish <file.spec.md> [--accepts <suggestion-id>]` | Publish a spec (needs a token); `--accepts` marks that suggestion on the spec accepted |
+| `canra suggest <owner>/<name> --title "..." [--body "..."] [--file <path.spec.md>]` | Suggest a change to a spec you don't own (needs a token); `--file` attaches a full edited spec, which the owner reviews as a diff |
 | `canra logout` | Remove saved credentials |
 | `canra version` / `canra help` | Version and usage |
 

package/canra.js

@@ -95,6 +95,7 @@ async function fetchRegistry(url, opts) {
 // meant to be driven by agents whose arguments may come from untrusted content.
 const OWNER_RE = /^[a-z][a-z0-9_-]{1,38}[a-z0-9]$/;
 const NAME_RE = /^[a-z][a-z0-9-]*$/;
+const SUGGESTION_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
 
 // Specs are namespaced by (owner, name), like GitHub repos. Parse an
 // "<owner>/<name>[@version]" argument, exiting with usage help on anything else.
@@ -324,13 +325,21 @@ async function cmdPublish(args) {
   // belong to instead of your own scope.
   const ownerAt = args.indexOf("--owner");
   const owner = ownerAt >= 0 ? args[ownerAt + 1] : null;
-  const filePath = args.find((a, i) => !a.startsWith("--") && (ownerAt < 0 || i !== ownerAt + 1));
+  const acceptsAt = args.indexOf("--accepts");
+  const accepts = acceptsAt >= 0 ? args[acceptsAt + 1] : null;
+  const filePath = args.find(
+    (a, i) => !a.startsWith("--") && (ownerAt < 0 || i !== ownerAt + 1) && (acceptsAt < 0 || i !== acceptsAt + 1),
+  );
   if (ownerAt >= 0 && (!owner || !OWNER_RE.test(owner))) {
     console.error("Error: --owner needs a valid organization name");
     process.exit(1);
   }
+  if (acceptsAt >= 0 && (!accepts || accepts.startsWith("--") || !SUGGESTION_ID_RE.test(accepts))) {
+    console.error("Error: --accepts needs a suggestion id");
+    process.exit(1);
+  }
   if (!filePath) {
-    console.error("Usage: canra publish <file> [--owner <org>]");
+    console.error("Usage: canra publish <file> [--owner <org>] [--accepts <suggestion-id>]");
     process.exit(1);
   }
 
@@ -347,6 +356,7 @@ async function cmdPublish(args) {
   const content = fs.readFileSync(filePath, "utf8");
   const registry = getRegistry();
   const headers = authHeaders();
+  if (accepts) headers["X-Suggestion"] = accepts;
 
   const target = owner ? `${registry}/api/specs?owner=${encodeURIComponent(owner)}` : `${registry}/api/specs`;
   const res = await fetchRegistry(target, {
@@ -362,6 +372,65 @@ async function cmdPublish(args) {
 
   const spec = await res.json();
   console.log(`Published ${printable(spec.name)}@${printable(spec.version)}`);
+  if (accepts) {
+    const id = printable(spec.suggestion?.id ?? accepts);
+    if (spec.suggestion?.status === "accepted") console.log(`Suggestion ${id} accepted`);
+    else console.warn(`Warning: Suggestion ${id} was not accepted (not open or not for this spec)`);
+  }
+}
+
+async function cmdSuggest(args) {
+  const usage = 'canra suggest <owner>/<name> --title "..." [--body "..."] [--file <path.spec.md>]';
+  const flags = { "--title": null, "--body": null, "--file": null };
+  let target = null;
+  for (let i = 0; i < args.length; i++) {
+    if (Object.hasOwn(flags, args[i])) {
+      const value = args[i + 1];
+      if (value === undefined || value.startsWith("--")) {
+        console.error(`Error: ${args[i]} needs a value`);
+        console.error(`Usage: ${usage}`);
+        process.exit(1);
+      }
+      flags[args[i]] = value;
+      i++;
+    } else if (!args[i].startsWith("--") && target === null) {
+      target = args[i];
+    }
+  }
+  const title = flags["--title"]?.trim();
+  if (!target || !title) {
+    console.error(`Usage: ${usage}`);
+    process.exit(1);
+  }
+  const ref = parseSpecRef(target, usage);
+  if (ref.version !== null) {
+    console.error("Error: suggestions apply to the latest version; leave off @<version>");
+    console.error(`Usage: ${usage}`);
+    process.exit(1);
+  }
+
+  const payload = { title, body: flags["--body"] ?? "" };
+  if (flags["--file"]) {
+    if (!fs.existsSync(flags["--file"])) {
+      console.error(`Error: file not found: ${flags["--file"]}`);
+      process.exit(1);
+    }
+    payload.content = fs.readFileSync(flags["--file"], "utf8");
+  }
+
+  const registry = getRegistry();
+  const res = await fetchRegistry(`${specApiUrl(registry, ref)}/suggestions`, {
+    method: "POST",
+    body: JSON.stringify(payload),
+    headers: { ...authHeaders(), "Content-Type": "application/json" },
+  });
+  if (!res.ok) {
+    const body = await res.text();
+    console.error(`Error: ${res.status} - ${printable(body)}`);
+    process.exit(1);
+  }
+  const created = await res.json();
+  console.log(`Suggestion filed: ${printable(registry)}${printable(created.url)}`);
 }
 
 async function cmdLogin() {
@@ -703,9 +772,13 @@ Commands:
                            Download a spec (latest, or a pinned version) and
                            save it, hash-verified, to .canra/specs/
   search <query>           Search registry, print formatted results
-  publish <file> [--owner <org>]
+  publish <file> [--owner <org>] [--accepts <suggestion-id>]
                            Publish a spec file (requires auth token); --owner
-                           publishes into an organization you belong to
+                           publishes into an organization you belong to;
+                           --accepts marks that suggestion accepted
+  suggest <owner>/<name> --title "..." [--body "..."] [--file <path.spec.md>]
+                           Suggest a change to a spec (requires auth token);
+                           --file proposes an edited spec as a diff
   login                    Prompt for registry URL and token
   logout                   Remove saved credentials
   whoami                   Print the user your saved token authenticates as
@@ -742,6 +815,9 @@ async function main() {
     case "publish":
       await cmdPublish(args.slice(1));
       break;
+    case "suggest":
+      await cmdSuggest(args.slice(1));
+      break;
     case "login":
       await cmdLogin();
       break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canra/cli",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "CLI for Canra, the registry of machine-readable specs: fetch, search, and publish specs.",
   "keywords": [
     "canra",