@canra/cli 0.4.0 → 0.6.0

package/README.md

@@ -29,10 +29,13 @@ 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 |
 
+`<owner>` is a user or organization name in any case: `Canra/json` and `canra/json` are the same spec, saved under the lowercase owner in `.canra/specs/`.
+
 ## Vendoring specs
 
 Commit `.canra/` to source control. The saved specs are the record of which spec versions your project implemented (a version is exact and immutable). After `canra update`, `git diff .canra/` shows what changed in each spec.

package/canra.js

@@ -89,12 +89,13 @@ async function fetchRegistry(url, opts) {
 
 // --- Spec references ---
 
-// Mirror the server's naming rules (route-utils.js USERNAME_RE, specs-api.js
+// Mirror the server's naming rules (username.js USERNAME_RE and grandfathered names, specs-api.js
 // NAME_RE). Owner and name become local path segments under .canra/specs/, so
 // anything path-like ("..", ".", backslashes) must be rejected here — the CLI is
 // 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 OWNER_RE = /^(?:(?=.{1,39}$)[a-z0-9]+(?:-[a-z0-9]+)*|[a-z][a-z0-9_-]{1,38}[a-z0-9])$/i;
 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.
@@ -196,7 +197,7 @@ function refuseSymlinks(paths) {
 
 function localSpecPaths(owner, name) {
   const specsDir = path.join(LOCAL_DIR, "specs");
-  const ownerDir = path.join(specsDir, owner);
+  const ownerDir = path.join(specsDir, owner.toLowerCase());
   return [LOCAL_DIR, specsDir, ownerDir, path.join(ownerDir, name)];
 }
 
@@ -206,8 +207,10 @@ function frontmatterFunctionCount(text) {
   return list ? (list[1].match(/"(?:[^"\\]|\\.)*"/g) || []).length : 0;
 }
 
+// Owner directories are lowercased everywhere (here, localSpecPaths, deleteLocalSpec) so Canra/json and
+// canra/json are one local spec on case-sensitive and case-insensitive filesystems alike.
 function localSpecDir(owner, name) {
-  return path.join(LOCAL_DIR, "specs", owner, name);
+  return path.join(LOCAL_DIR, "specs", owner.toLowerCase(), name);
 }
 
 async function downloadSpec(registry, { owner, name, version }) {
@@ -324,13 +327,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 +358,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 +374,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() {
@@ -605,7 +676,7 @@ function deleteLocalSpec(owner, name) {
   if (!dir.startsWith(specsRoot + path.sep)) throw new Error(`unexpected local path for ${owner}/${name}`);
   refuseSymlinks(localSpecPaths(owner, name));
   fs.rmSync(dir, { recursive: true, force: true });
-  const ownerDir = path.join(LOCAL_DIR, "specs", owner);
+  const ownerDir = path.join(LOCAL_DIR, "specs", owner.toLowerCase());
   if (fs.readdirSync(ownerDir).length === 0) fs.rmdirSync(ownerDir);
 }
 
@@ -641,7 +712,7 @@ async function cmdUpdate(specArg) {
 
   let refs = scanLocalSpecs();
   if (only) {
-    refs = refs.filter((r) => r.owner === only.owner && r.name === only.name);
+    refs = refs.filter((r) => r.owner.toLowerCase() === only.owner.toLowerCase() && r.name === only.name);
     if (refs.length === 0) {
       console.error(`Error: ${only.owner}/${only.name} is not fetched locally. Run \`canra fetch\` first.`);
       process.exit(1);
@@ -672,7 +743,7 @@ async function cmdUpdate(specArg) {
       if (!OWNER_RE.test(toOwner) || (target && target[2] !== row.name)) {
         throw new Error(`unexpected move target '${printable(row.moved_to)}'`);
       }
-      const moving = toOwner !== row.owner;
+      const moving = toOwner.toLowerCase() !== row.owner.toLowerCase();
       if (moving && fs.existsSync(localSpecDir(toOwner, row.name))) {
         throw new Error(`${toOwner}/${row.name} is already fetched locally; remove one of the two copies`);
       }
@@ -703,9 +774,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 +817,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.6.0",
   "description": "CLI for Canra, the registry of machine-readable specs: fetch, search, and publish specs.",
   "keywords": [
     "canra",