@01.software/cli 0.10.3 → 0.10.5

package/dist/index.js

@@ -8,7 +8,7 @@ import { Command } from "commander";
 import {
   CollectionClient,
   ServerCommerceClient
-} from "@01.software/sdk";
+} from "@01.software/sdk/server";
 
 // src/lib/credentials.ts
 import {
@@ -166,6 +166,9 @@ function classifyError(err) {
       if (isPermissionCode(code)) {
         return { type: "permission", code };
       }
+      if (code === "auth_error" || code === "permission_error") {
+        return { type: "permission", code: "credential_invalid" };
+      }
       if (isDegradedCode(code)) {
         const out = { type: "degraded", code };
         if (typeof obj.retryAfter === "number") {
@@ -187,7 +190,7 @@ function classifyError(err) {
     }
     const name = typeof obj.name === "string" ? obj.name : void 0;
     const status = typeof obj.status === "number" ? obj.status : void 0;
-    if (name === "ConfigError" || status === 401) {
+    if (name === "ConfigError" || name === "AuthError" || name === "PermissionError" || status === 401 || status === 403) {
       return { type: "permission", code: "credential_invalid" };
     }
     if (name === "NetworkError" || name === "TimeoutError" || status === 408 || status === 503) {
@@ -440,7 +443,14 @@ function exitWithError(error, options = {}) {
 function isValidBearerToken(secret) {
   return secret.startsWith("sk01_") || secret.startsWith("pat01_");
 }
-function resolveClient(apiKeyFlag) {
+function credentialError(detail) {
+  return {
+    type: "permission",
+    code: "credential_invalid",
+    detail
+  };
+}
+function resolveClientCredentials(apiKeyFlag) {
   let publishableKey = process.env.SOFTWARE_PUBLISHABLE_KEY;
   let secretKey = apiKeyFlag ?? process.env.SOFTWARE_SECRET_KEY;
   if (!publishableKey || !secretKey) {
@@ -458,29 +468,25 @@ function resolveClient(apiKeyFlag) {
     }
   }
   if (!publishableKey || !secretKey) {
-    exitWithError({
-      type: "permission",
-      code: "credential_invalid",
-      detail: {
-        message: t("AuthenticationRequired"),
-        steps: [
-          t("RunLoginToAuthenticate"),
-          t("PassApiKey"),
-          t("SetEnvVars")
-        ]
-      }
+    throw credentialError({
+      message: t("AuthenticationRequired"),
+      steps: [
+        t("RunLoginToAuthenticate"),
+        t("PassApiKey"),
+        t("SetEnvVars")
+      ]
     });
   }
   if (!isValidBearerToken(secretKey)) {
-    exitWithError({
-      type: "permission",
-      code: "credential_invalid",
-      detail: {
-        message: t("InvalidApiKeyFormat"),
-        suggestion: t("RetiredHexCredentialsRejected")
-      }
+    throw credentialError({
+      message: t("InvalidApiKeyFormat"),
+      suggestion: t("RetiredHexCredentialsRejected")
     });
   }
+  return { publishableKey, secretKey };
+}
+function resolveClientOrThrow(apiKeyFlag) {
+  const { publishableKey, secretKey } = resolveClientCredentials(apiKeyFlag);
   const serverOptions = { publishableKey, secretKey };
   return {
     collections: new CollectionClient(
@@ -495,11 +501,37 @@ function resolveClient(apiKeyFlag) {
     secretKey
   };
 }
+function resolveClient(apiKeyFlag) {
+  try {
+    return resolveClientOrThrow(apiKeyFlag);
+  } catch (error) {
+    exitWithError(error);
+  }
+}
 
 // src/commands/crud.ts
 import { readFileSync as readFileSync2 } from "fs";
 import { basename } from "path";
+
+// src/lib/collections.ts
 import { COLLECTIONS } from "@01.software/sdk";
+function validateCollection(name) {
+  if (COLLECTIONS.includes(name)) {
+    return name;
+  }
+  const normalized = name.replace(/-/g, "").toLowerCase();
+  const suggestions = COLLECTIONS.filter((collection) => {
+    const candidate = collection.replace(/-/g, "").toLowerCase();
+    return candidate.startsWith(normalized) || normalized.startsWith(candidate) || normalized.length >= 3 && candidate.includes(normalized);
+  }).slice(0, 5);
+  const hint = suggestions.length > 0 ? `Did you mean: ${suggestions.join(", ")}?` : 'Run "01 --help" for available collections.';
+  throw new Error(`Unknown collection "${name}". ${hint}`);
+}
+function parseSelect(input) {
+  return Object.fromEntries(
+    input.split(",").map((field) => field.trim()).map((field) => [field, true])
+  );
+}
 
 // src/lib/parse.ts
 function failArg(label, value, expectedKind) {
@@ -581,21 +613,6 @@ function readFileAsBlob(filePath) {
   const buffer = readFileSync2(filePath);
   return { blob: new Blob([buffer]), filename: basename(filePath) };
 }
-function validateCollection(name) {
-  if (!COLLECTIONS.includes(name)) {
-    const normalized = name.replace(/-/g, "").toLowerCase();
-    const suggestions = COLLECTIONS.filter((c) => {
-      const cn = c.replace(/-/g, "").toLowerCase();
-      return cn.startsWith(normalized) || normalized.startsWith(cn) || normalized.length >= 3 && cn.includes(normalized);
-    }).slice(0, 5);
-    const hint = suggestions.length > 0 ? `Did you mean: ${suggestions.join(", ")}?` : 'Run "01 --help" for available collections.';
-    throw new Error(`Unknown collection "${name}". ${hint}`);
-  }
-  return name;
-}
-function parseSelect(input) {
-  return Object.fromEntries(input.split(",").map((f) => [f.trim(), true]));
-}
 function registerCrudCommands(program2, getClient2, getFormat2) {
   program2.command("query <collection>").description("Query documents from a collection").option("--where <json>", "Filter conditions (JSON)").option("--limit <n>", "Max results", (v) => parseInt(v, 10)).option("--page <n>", "Page number", (v) => parseInt(v, 10)).option("--sort <field>", "Sort field (prefix with - for descending)").option(
     "--depth <n>",
@@ -1850,6 +1867,207 @@ Prerequisites:
   });
 }
 
+// src/commands/agent.ts
+import { COLLECTIONS as COLLECTIONS3 } from "@01.software/sdk";
+
+// src/lib/agent-output.ts
+function stringifyAgentJson(data, options = {}) {
+  return options.pretty ? JSON.stringify(data, null, 2) : JSON.stringify(data);
+}
+function asRecord(value) {
+  return value && typeof value === "object" ? value : null;
+}
+function errorMessage(error) {
+  const raw = asRecord(error);
+  if (raw) {
+    if (typeof raw.message === "string" && raw.message.length > 0) {
+      return raw.message;
+    }
+    if (raw.detail && typeof raw.detail === "object" && typeof raw.detail.message === "string") {
+      return String(raw.detail.message);
+    }
+  }
+  if (error instanceof Error && error.message.length > 0) {
+    return error.message;
+  }
+  if (typeof error === "string" && error.length > 0) {
+    return error;
+  }
+  return "Internal error";
+}
+function isRawNotFound(error) {
+  const raw = asRecord(error);
+  return raw?.status === 404 || raw?.code === "not_found" || raw?.name === "GoneError";
+}
+function agentErrorExitCode(code) {
+  switch (code) {
+    case "INVALID_INPUT":
+      return 2;
+    case "AUTH_FAILED":
+      return 3;
+    case "NOT_FOUND":
+      return 4;
+    case "INTERNAL":
+      return 1;
+  }
+}
+function classifyAgentError(error) {
+  const adminError = classifyError(error);
+  const message = errorMessage(error);
+  if (isRawNotFound(error) || adminError.code === "not_found") {
+    return { error: { code: "NOT_FOUND", message } };
+  }
+  if (adminError.type === "permission") {
+    return { error: { code: "AUTH_FAILED", message } };
+  }
+  if (adminError.type === "validation" && adminError.code !== "unknown") {
+    return { error: { code: "INVALID_INPUT", message } };
+  }
+  return { error: { code: "INTERNAL", message } };
+}
+function printAgentSuccess(data, options = {}) {
+  console.log(stringifyAgentJson(data, options));
+}
+function printAgentError(error, options = {}) {
+  const envelope = classifyAgentError(error);
+  console.log(stringifyAgentJson(envelope, options));
+  return envelope;
+}
+function exitWithAgentError(error, options = {}) {
+  const envelope = printAgentError(error, options);
+  process.exit(agentErrorExitCode(envelope.error.code));
+}
+
+// src/commands/agent.ts
+var AGENT_PROTOCOL_VERSION = "1";
+function buildStableAgentFields() {
+  return {
+    id: { type: "string", queryable: true },
+    createdAt: { type: "string", queryable: true },
+    updatedAt: { type: "string", queryable: true }
+  };
+}
+function invalidInput(message, field, value) {
+  const error = new Error(message);
+  Object.assign(error, {
+    type: "validation",
+    code: "invalid_argument",
+    field,
+    detail: { message, value, field }
+  });
+  return error;
+}
+function parsePositiveInteger(value, field) {
+  if (value == null) return void 0;
+  if (/^[1-9]\d*$/.test(value)) return Number(value);
+  throw invalidInput(`--${field} must be a positive integer`, field, value);
+}
+function handleCommanderError(error) {
+  if (error.code === "commander.helpDisplayed") {
+    process.exit(error.exitCode);
+  }
+  exitWithAgentError(invalidInput(error.message, "command"));
+}
+function configureAgentParser(command) {
+  command.configureOutput({
+    writeErr: () => {
+    },
+    writeOut: (str) => {
+      process.stdout.write(str);
+    }
+  });
+  command.exitOverride(handleCommanderError);
+  return command;
+}
+function parseWhere(value) {
+  if (value == null) return void 0;
+  try {
+    const parsed = JSON.parse(value);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed;
+    }
+  } catch {
+    throw invalidInput("--where must be a JSON object", "where", value);
+  }
+  throw invalidInput("--where must be a JSON object", "where", value);
+}
+function buildAgentManifest() {
+  const collections = {};
+  for (const collection of COLLECTIONS3) {
+    collections[collection] = {
+      operations: ["query", "get"],
+      fields: buildStableAgentFields()
+    };
+  }
+  return {
+    version: AGENT_PROTOCOL_VERSION,
+    collections
+  };
+}
+function validateAgentCollection(collection) {
+  try {
+    return validateCollection(collection);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : `Unknown collection "${collection}".`;
+    throw invalidInput(message, "collection", collection);
+  }
+}
+function registerAgentCommands(program2, getClient2) {
+  const agent = configureAgentParser(
+    program2.command("agent").description("Machine-stable CLI namespace for coding agents").addHelpText(
+      "after",
+      "\nContract: docs/agent-cli-contract.md\nJSON only on stdout; no TTY effects."
+    )
+  );
+  configureAgentParser(
+    agent.command("manifest").description("Print the Agent CLI protocol manifest").option("--pretty", "Print 2-space indented JSON").action((opts) => {
+      printAgentSuccess(buildAgentManifest(), { pretty: Boolean(opts.pretty) });
+    })
+  );
+  configureAgentParser(
+    agent.command("query <collection>").description("Query documents from a collection").option("--where <json>", "Filter conditions as a JSON object").option("--limit <n>", "Max results").option("--page <n>", "Page number").option("--sort <field>", "Sort field; prefix with - for descending").option("--select <fields>", "Comma-separated fields to select").option("--pretty", "Print 2-space indented JSON").action(
+      async (collection, opts) => {
+        try {
+          const col = validateAgentCollection(collection);
+          const options = {};
+          const where = parseWhere(opts.where);
+          const limit = parsePositiveInteger(opts.limit, "limit");
+          const page = parsePositiveInteger(opts.page, "page");
+          if (where) options.where = where;
+          if (limit != null) options.limit = limit;
+          if (page != null) options.page = page;
+          if (opts.sort) options.sort = opts.sort;
+          if (opts.select) options.select = parseSelect(opts.select);
+          const client = getClient2();
+          const result = await client.collections.from(col).find(options);
+          printAgentSuccess(result, { pretty: Boolean(opts.pretty) });
+        } catch (error) {
+          exitWithAgentError(error, { pretty: Boolean(opts.pretty) });
+        }
+      }
+    )
+  );
+  configureAgentParser(
+    agent.command("get <collection> [id]").description("Get a document by ID").option("--select <fields>", "Comma-separated fields to select").option("--pretty", "Print 2-space indented JSON").action(
+      async (collection, id, opts) => {
+        try {
+          const col = validateAgentCollection(collection);
+          if (!id) {
+            throw invalidInput("Missing required argument: id", "id");
+          }
+          const options = {};
+          if (opts.select) options.select = parseSelect(opts.select);
+          const client = getClient2();
+          const result = await client.collections.from(col).findById(id, options);
+          printAgentSuccess(result, { pretty: Boolean(opts.pretty) });
+        } catch (error) {
+          exitWithAgentError(error, { pretty: Boolean(opts.pretty) });
+        }
+      }
+    )
+  );
+}
+
 // src/index.ts
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
@@ -1865,6 +2083,8 @@ process.on("unhandledRejection", (err) => {
   exitWithError(err, { format: getFormat() });
 });
 var getClient = () => resolveClient(program.opts().apiKey);
+var getAgentClient = () => resolveClientOrThrow(program.opts().apiKey);
+registerAgentCommands(program, getAgentClient);
 registerCrudCommands(program, getClient, getFormat);
 registerOrderCommands(program, getClient, getFormat);
 registerReturnCommands(program, getClient, getFormat);