@canra/cli 0.3.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.
@@ -306,9 +307,13 @@ async function cmdSearch(query) {
   console.log(`${"-".repeat(nameWidth)} ${"-".repeat(versionWidth)} ${"-".repeat(descWidth)}`);
 
   for (const spec of specs) {
-    const name = (spec.name || "").padEnd(nameWidth).slice(0, nameWidth);
-    const version = (spec.version || "").padEnd(versionWidth).slice(0, versionWidth);
-    const desc = (spec.description || spec.title || "").slice(0, descWidth).replace(/\n/g, " ");
+    const name = printable(spec.name).padEnd(nameWidth).slice(0, nameWidth);
+    const version = printable(spec.version).padEnd(versionWidth).slice(0, versionWidth);
+    const desc = printable(
+      String(spec.description || spec.title || "")
+        .replace(/\s+/g, " ")
+        .trim(),
+    ).slice(0, descWidth);
     console.log(`${name} ${version} ${desc}`);
   }
 
@@ -320,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);
   }
 
@@ -343,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, {
@@ -352,12 +366,71 @@ async function cmdPublish(args) {
   });
   if (!res.ok) {
     const body = await res.text();
-    console.error(`Error: ${res.status} - ${body}`);
+    console.error(`Error: ${res.status} - ${printable(body)}`);
     process.exit(1);
   }
 
   const spec = await res.json();
-  console.log(`Published ${spec.name}@${spec.version}`);
+  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() {
@@ -419,9 +492,9 @@ async function cmdWhoami() {
     process.exit(1);
   }
   const me = await res.json();
-  console.log(me.user);
+  console.log(printable(me.user));
   console.log(`  Registry: ${registry}`);
-  if (me.scopes?.length) console.log(`  Scopes:   ${me.scopes.join(", ")}`);
+  if (me.scopes?.length) console.log(`  Scopes:   ${printable(me.scopes.join(", "))}`);
 }
 
 async function cmdInfo(specArg) {
@@ -446,16 +519,16 @@ async function cmdInfo(specArg) {
   }
 
   const spec = await res.json();
-  console.log(`${ref.owner}/${ref.name}@${spec.version}`);
-  if (spec.title) console.log(`  Title:       ${spec.title}`);
-  if (spec.status) console.log(`  Status:      ${spec.status}`);
-  if (spec.difficulty) console.log(`  Difficulty:  ${spec.difficulty}`);
-  if (spec.tags?.length) console.log(`  Tags:        ${spec.tags.join(", ")}`);
-  if (spec.functions?.length) console.log(`  Functions:   ${spec.functions.join(", ")}`);
-  if (spec.types?.length) console.log(`  Types:       ${spec.types.join(", ")}`);
-  if (spec.test_vectors_inline) console.log(`  Test vectors: ${spec.test_vectors_inline} inline`);
-  if (spec.owner) console.log(`  Owner:       ${spec.owner}`);
-  if (spec.updated_at) console.log(`  Updated:     ${spec.updated_at}`);
+  console.log(`${ref.owner}/${ref.name}@${printable(spec.version)}`);
+  if (spec.title) console.log(`  Title:       ${printable(spec.title)}`);
+  if (spec.status) console.log(`  Status:      ${printable(spec.status)}`);
+  if (spec.difficulty) console.log(`  Difficulty:  ${printable(spec.difficulty)}`);
+  if (spec.tags?.length) console.log(`  Tags:        ${printable(spec.tags.join(", "))}`);
+  if (spec.functions?.length) console.log(`  Functions:   ${printable(spec.functions.join(", "))}`);
+  if (spec.types?.length) console.log(`  Types:       ${printable(spec.types.join(", "))}`);
+  if (spec.test_vectors_inline) console.log(`  Test vectors: ${printable(spec.test_vectors_inline)} inline`);
+  if (spec.owner) console.log(`  Owner:       ${printable(spec.owner)}`);
+  if (spec.updated_at) console.log(`  Updated:     ${printable(spec.updated_at)}`);
 }
 
 // The server rejects more than MAX_REFS (website/outdated.js) entries per request.
@@ -699,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
@@ -738,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.3.0",
+  "version": "0.5.0",
   "description": "CLI for Canra, the registry of machine-readable specs: fetch, search, and publish specs.",
   "keywords": [
     "canra",