@canra/cli 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Canra Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,57 @@
-# Temporary Holding Version
+# @canra/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Command-line client for [Canra](https://canra.dev), a registry of machine-readable specifications (library APIs, protocols, data formats). Fetch a spec, generate an implementation in any language, and check it against the spec's test vectors.
+
+Runs on Node 20+ or Bun. No install needed:
+
+```sh
+npx @canra/cli search json
+npx @canra/cli info canra/json
+npx @canra/cli fetch canra/json
+```
+
+## Commands
+
+Or install it to get the `canra` command:
+
+```sh
+npm install -g @canra/cli
+canra search json
+```
+
+| Command | What it does |
+|---|---|
+| `canra search <query>` | Search the registry |
+| `canra info <owner>/<name>` | Show a spec's metadata |
+| `canra fetch <owner>/<name>[@version]` | Save a spec's metadata to `.canra/specs/<owner>/<name>/` |
+| `canra outdated` | Check fetched specs for newer versions |
+| `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 logout` | Remove saved credentials |
+| `canra version` / `canra help` | Version and usage |
+
+## Publishing
+
+Create an API token at **canra.dev → Account → API tokens**, then:
+
+```sh
+npx @canra/cli login        # paste the token when asked
+npx @canra/cli publish my-spec.spec.md
+```
+
+Credentials are stored in `~/.canra/config.json`.
+
+## For agents
+
+You may not need the CLI at all:
+
+- Raw spec markdown: `https://canra.dev/specs/{owner}/{name}.md`
+- Site index for LLMs: `https://canra.dev/llms.txt`
+- Remote MCP server (no auth): `https://canra.dev/mcp`, e.g. `claude mcp add --transport http canra https://canra.dev/mcp`
+
+API docs: https://canra.dev/docs/api
+
+## License
+
+MIT

package/canra.js

@@ -0,0 +1,467 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import readline from "node:readline";
+
+// Runs under Node >= 20 (via `npx canra`) and Bun: only node: built-ins and fetch.
+// The version comes from package.json, so a release only bumps one place.
+const VERSION = JSON.parse(fs.readFileSync(new URL("./package.json", import.meta.url), "utf8")).version;
+const CONFIG_DIR = path.join(os.homedir(), ".canra");
+const CONFIG_PATH = path.join(CONFIG_DIR, "config.json");
+const LOCAL_DIR = ".canra";
+
+// --- Config helpers ---
+
+function readConfig() {
+  try {
+    return JSON.parse(fs.readFileSync(CONFIG_PATH, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function writeConfig(config) {
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  fs.writeFileSync(CONFIG_PATH, `${JSON.stringify(config, null, 2)}\n`);
+}
+
+function getRegistry() {
+  const config = readConfig();
+  return config.registry || "https://canra.dev";
+}
+
+function getToken() {
+  const config = readConfig();
+  return config.token || null;
+}
+
+function authHeaders() {
+  const token = getToken();
+  if (!token) {
+    console.error("Error: not logged in. Run `canra login` first.");
+    process.exit(1);
+  }
+  return { Authorization: `Bearer ${token}` };
+}
+
+/**
+ * Fetch from the registry, exiting with a uniform "could not connect" message on
+ * a network failure. Returns the Response; callers handle non-2xx (`res.ok`),
+ * which varies per command.
+ */
+async function fetchRegistry(url, opts) {
+  try {
+    return await fetch(url, opts);
+  } catch (err) {
+    console.error(`Error: could not connect to registry at ${getRegistry()}`);
+    console.error(err.message);
+    process.exit(1);
+  }
+}
+
+// --- Spec references ---
+
+// Mirror the server's naming rules (route-utils.js USERNAME_RE, 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 NAME_RE = /^[a-z][a-z0-9-]*$/;
+
+// Specs are namespaced by (owner, name), like GitHub repos. Parse an
+// "<owner>/<name>[@version]" argument, exiting with usage help on anything else.
+function parseSpecRef(arg, usage) {
+  const at = arg.indexOf("@");
+  const ref = at === -1 ? arg : arg.slice(0, at);
+  const version = at === -1 ? null : arg.slice(at + 1);
+  const parts = ref.split("/");
+  if (
+    parts.length !== 2 ||
+    !OWNER_RE.test(parts[0]) ||
+    !NAME_RE.test(parts[1]) ||
+    version === "" ||
+    version?.includes("@")
+  ) {
+    console.error(`Error: specs are referenced as <owner>/<name> (got '${arg}')`);
+    console.error(`Usage: ${usage}`);
+    process.exit(1);
+  }
+  return { owner: parts[0], name: parts[1], version };
+}
+
+function specApiUrl(registry, { owner, name }) {
+  return `${registry}/api/specs/${encodeURIComponent(owner)}/${encodeURIComponent(name)}`;
+}
+
+// --- Prompt helper ---
+
+function prompt(question) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+// --- Commands ---
+
+async function cmdFetch(specArg) {
+  if (!specArg) {
+    console.error("Usage: canra fetch <owner>/<name>[@version]");
+    process.exit(1);
+  }
+
+  const ref = parseSpecRef(specArg, "canra fetch <owner>/<name>[@version]");
+
+  const registry = getRegistry();
+  const url = specApiUrl(registry, ref);
+
+  const res = await fetchRegistry(url);
+  if (!res.ok) {
+    const body = await res.text();
+    console.error(`Error: ${res.status} - ${body}`);
+    process.exit(1);
+  }
+
+  const spec = await res.json();
+
+  // The registry serves only the latest version; never save a different one under
+  // a pinned request.
+  if (ref.version && ref.version !== spec.version) {
+    console.error(
+      `Error: ${ref.owner}/${ref.name}@${ref.version} is not available (the registry serves the latest, ${spec.version})`,
+    );
+    process.exit(1);
+  }
+
+  // Save metadata locally
+  const specDir = path.join(LOCAL_DIR, "specs", ref.owner, ref.name);
+  fs.mkdirSync(specDir, { recursive: true });
+  fs.writeFileSync(path.join(specDir, "metadata.json"), `${JSON.stringify(spec, null, 2)}\n`);
+
+  const fnCount = (spec.functions || []).length;
+  console.log(`Fetched ${ref.owner}/${ref.name}@${spec.version} (${fnCount} function${fnCount !== 1 ? "s" : ""})`);
+  console.log(`  Saved to ${specDir}/metadata.json`);
+}
+
+async function cmdSearch(query) {
+  if (!query) {
+    console.error("Usage: canra search <query>");
+    process.exit(1);
+  }
+
+  const registry = getRegistry();
+  const url = `${registry}/api/search?q=${encodeURIComponent(query)}`;
+
+  const res = await fetchRegistry(url);
+  if (!res.ok) {
+    console.error(`Error: ${res.status}`);
+    process.exit(1);
+  }
+
+  const data = await res.json();
+  // Handle both array response and paginated response
+  const specs = Array.isArray(data) ? data : data.specs || [];
+
+  if (specs.length === 0) {
+    console.log("No specs found.");
+    return;
+  }
+
+  // Print formatted table
+  const nameWidth = 20;
+  const versionWidth = 10;
+  const descWidth = 60;
+
+  console.log(`${"NAME".padEnd(nameWidth)} ${"VERSION".padEnd(versionWidth)} DESCRIPTION`);
+  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, " ");
+    console.log(`${name} ${version} ${desc}`);
+  }
+
+  console.log(`\n${specs.length} result${specs.length !== 1 ? "s" : ""}`);
+}
+
+async function cmdPublish(filePath) {
+  if (!filePath) {
+    console.error("Usage: canra publish <file>");
+    process.exit(1);
+  }
+
+  if (!filePath.endsWith(".spec.md")) {
+    console.error("Error: file must have .spec.md extension");
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(filePath)) {
+    console.error(`Error: file not found: ${filePath}`);
+    process.exit(1);
+  }
+
+  const content = fs.readFileSync(filePath, "utf8");
+  const registry = getRegistry();
+  const headers = authHeaders();
+
+  const res = await fetchRegistry(`${registry}/api/specs`, {
+    method: "POST",
+    body: content,
+    headers,
+  });
+  if (!res.ok) {
+    const body = await res.text();
+    console.error(`Error: ${res.status} - ${body}`);
+    process.exit(1);
+  }
+
+  const spec = await res.json();
+  console.log(`Published ${spec.name}@${spec.version}`);
+}
+
+async function cmdLogin() {
+  const currentConfig = readConfig();
+  const defaultRegistry = currentConfig.registry || "https://canra.dev";
+
+  const registry = (await prompt(`Registry URL (${defaultRegistry}): `)) || defaultRegistry;
+  const token = await prompt("API token: ");
+
+  if (!token) {
+    console.error("Error: token is required");
+    process.exit(1);
+  }
+
+  // Try to verify the token
+  try {
+    const res = await fetch(`${registry}/api/tokens`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    if (res.ok) {
+      console.log("Token verified.");
+    } else {
+      console.log(`Warning: could not verify token (server returned ${res.status}). Saving anyway.`);
+    }
+  } catch {
+    console.log("Warning: could not reach registry to verify token. Saving anyway.");
+  }
+
+  writeConfig({ registry, token });
+  console.log(`Logged in to ${registry}`);
+}
+
+function cmdLogout() {
+  if (fs.existsSync(CONFIG_PATH)) {
+    fs.unlinkSync(CONFIG_PATH);
+    console.log("Logged out. Credentials removed.");
+  } else {
+    console.log("Not logged in.");
+  }
+}
+
+async function cmdWhoami() {
+  const registry = getRegistry();
+  const res = await fetchRegistry(`${registry}/api/auth/whoami`, { headers: authHeaders() });
+  if (res.status === 401) {
+    console.error(`Error: the saved token was rejected by ${registry}. Run \`canra login\` again.`);
+    process.exit(1);
+  }
+  if (!res.ok) {
+    console.error(`Error: ${res.status}`);
+    process.exit(1);
+  }
+  const me = await res.json();
+  console.log(me.user);
+  console.log(`  Registry: ${registry}`);
+  if (me.scopes?.length) console.log(`  Scopes:   ${me.scopes.join(", ")}`);
+}
+
+async function cmdInfo(specArg) {
+  if (!specArg) {
+    console.error("Usage: canra info <owner>/<name>");
+    process.exit(1);
+  }
+
+  const ref = parseSpecRef(specArg, "canra info <owner>/<name>");
+
+  const registry = getRegistry();
+  const url = specApiUrl(registry, ref);
+
+  const res = await fetchRegistry(url);
+  if (!res.ok) {
+    if (res.status === 404) {
+      console.error(`Error: spec '${specArg}' not found`);
+    } else {
+      console.error(`Error: ${res.status}`);
+    }
+    process.exit(1);
+  }
+
+  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}`);
+}
+
+async function cmdOutdated() {
+  const specsDir = path.join(LOCAL_DIR, "specs");
+  if (!fs.existsSync(specsDir)) {
+    console.log("No local specs found. Run `canra fetch <owner>/<name>` first.");
+    return;
+  }
+
+  const registry = getRegistry();
+  // Fetched specs live at .canra/specs/<owner>/<name>/metadata.json.
+  const refs = [];
+  try {
+    for (const owner of fs.readdirSync(specsDir)) {
+      const ownerDir = path.join(specsDir, owner);
+      if (!fs.statSync(ownerDir).isDirectory()) continue;
+      for (const name of fs.readdirSync(ownerDir)) {
+        if (fs.existsSync(path.join(ownerDir, name, "metadata.json"))) refs.push({ owner, name });
+      }
+    }
+  } catch {
+    console.log("No local specs found.");
+    return;
+  }
+
+  if (refs.length === 0) {
+    console.log("No local specs found.");
+    return;
+  }
+
+  const nameWidth = 20;
+  const versionWidth = 12;
+  console.log(`${"SPEC".padEnd(nameWidth)} ${"LOCAL".padEnd(versionWidth)} LATEST`);
+  console.log(`${"-".repeat(nameWidth)} ${"-".repeat(versionWidth)} ${"-".repeat(versionWidth)}`);
+
+  let outdatedCount = 0;
+  for (const ref of refs) {
+    const label = `${ref.owner}/${ref.name}`;
+    const metaPath = path.join(specsDir, ref.owner, ref.name, "metadata.json");
+    let local;
+    try {
+      local = JSON.parse(fs.readFileSync(metaPath, "utf8"));
+    } catch {
+      continue;
+    }
+
+    let res;
+    try {
+      res = await fetch(specApiUrl(registry, ref));
+    } catch {
+      continue;
+    }
+    if (!res.ok) continue;
+
+    const remote = await res.json();
+    if (local.version !== remote.version) {
+      console.log(`${label.padEnd(nameWidth)} ${(local.version || "?").padEnd(versionWidth)} ${remote.version}`);
+      outdatedCount++;
+    }
+  }
+
+  if (outdatedCount === 0) {
+    console.log("\nAll specs are up to date.");
+  } else {
+    console.log(`\n${outdatedCount} outdated spec${outdatedCount !== 1 ? "s" : ""}.`);
+  }
+}
+
+function cmdHelp() {
+  console.log(`canra - Package Spec Registry CLI v${VERSION}
+
+Usage: canra <command> [args]
+
+Commands:
+  fetch <owner>/<name>[@version]
+                           Fetch spec from registry, save to .canra/specs/
+  search <query>           Search registry, print formatted results
+  publish <file>           Publish a spec file (requires auth token)
+  login                    Prompt for registry URL and token
+  logout                   Remove saved credentials
+  whoami                   Print the user your saved token authenticates as
+  info <owner>/<name>      Print spec metadata
+  outdated                 Check local specs for newer versions
+  help                     Print this help message
+  version                  Print CLI version
+
+Config stored at ~/.canra/config.json`);
+}
+
+function cmdVersion() {
+  console.log(VERSION);
+}
+
+// --- Main ---
+
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+  const arg = args.slice(1).join(" ");
+
+  switch (command) {
+    case "fetch":
+      await cmdFetch(args[1]);
+      break;
+    case "search":
+      await cmdSearch(arg);
+      break;
+    case "publish":
+      await cmdPublish(args[1]);
+      break;
+    case "login":
+      await cmdLogin();
+      break;
+    case "logout":
+      cmdLogout();
+      break;
+    case "whoami":
+      await cmdWhoami();
+      break;
+    case "info":
+      await cmdInfo(args[1]);
+      break;
+    case "outdated":
+      await cmdOutdated();
+      break;
+    case "version":
+    case "--version":
+    case "-v":
+      cmdVersion();
+      break;
+    case "help":
+    case "--help":
+    case "-h":
+    case undefined:
+      cmdHelp();
+      break;
+    default:
+      console.error(`Unknown command: ${command}`);
+      console.error('Run "canra help" for usage.');
+      process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error(`Error: ${err.message}`);
+  process.exit(1);
+});
+
+export { readConfig, writeConfig, VERSION };

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@canra/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "CLI for Canra, the registry of machine-readable specs: fetch, search, and publish specs.",
+  "keywords": [
+    "canra",
+    "spec",
+    "specification",
+    "registry",
+    "cli",
+    "agents",
+    "llm"
+  ],
+  "homepage": "https://canra.dev/docs/api",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "bin": {
+    "canra": "canra.js"
+  },
+  "files": [
+    "canra.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/canra-dev/canra.git",
+    "directory": "cli"
+  }
+}