@wrangled/cli 0.3.44 → 0.3.45

package/dist/api.js

@@ -1,8 +1,8 @@
 import { mkdir, readFile, rm } from "node:fs/promises";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { brand, envPrefix } from "./brand.js";
-import { writeFileAtomic } from "./files.js";
+import { RUN_ROOT_ENV, writeFileAtomic } from "./files.js";
 export const exitCodes = { ok: 0, error: 1, usage: 2, auth: 3, interrupted: 130 };
 export class CliError extends Error {
     exitCode;
@@ -30,8 +30,17 @@ export const IMPORT_NAME_PATTERN = /^[a-z][a-z0-9_]{0,40}$/;
 export function credentialsPath(configHome = process.env.XDG_CONFIG_HOME || join(homedir(), ".config")) {
     return join(configHome, brand.slug, "credentials.json");
 }
-export async function readCredentials() {
-    const path = credentialsPath();
+const CLIENT_NAME = /^[a-z0-9][a-z0-9-]*$/;
+/** The file that names a folder's client; it holds only the name, never a key. */
+export const CLIENT_FILE = `.${brand.slug}-client`;
+export function parseClientName(name) {
+    if (!CLIENT_NAME.test(name)) {
+        throw new CliError(`'${name}' is not a client name: use lowercase letters, digits and dashes, starting with a letter or digit.`, exitCodes.usage);
+    }
+    return name;
+}
+export async function readSavedLogins(configHome) {
+    const path = credentialsPath(configHome);
     let text;
     try {
         text = await readFile(path, "utf8");
@@ -41,38 +50,146 @@ export async function readCredentials() {
             return null;
         throw error;
     }
-    const credentials = parseCredentials(text);
-    if (!credentials)
+    const saved = parseSavedLogins(text);
+    if (!saved)
         throw new UnreadableCredentialsError(path);
-    return credentials;
+    return saved;
 }
-function parseCredentials(text) {
+function parseSavedLogins(text) {
+    let value;
     try {
-        const value = JSON.parse(text);
-        if (typeof value?.apiKey !== "string" || typeof value.apiUrl !== "string")
-            return null;
-        return { apiKey: value.apiKey, apiUrl: value.apiUrl };
+        value = JSON.parse(text);
     }
     catch {
         return null;
     }
+    if (typeof value !== "object" || value === null)
+        return null;
+    const { apiKey, apiUrl, clients } = value;
+    const top = parseLogin({ apiKey, apiUrl });
+    if (top === null && (apiKey !== undefined || apiUrl !== undefined))
+        return null;
+    // No prototype, so a client named like an Object method (`constructor`) finds nothing rather than a function.
+    const named = Object.create(null);
+    if (clients !== undefined) {
+        if (typeof clients !== "object" || clients === null || Array.isArray(clients))
+            return null;
+        for (const [name, entry] of Object.entries(clients)) {
+            const login = parseLogin(entry);
+            if (!CLIENT_NAME.test(name) || login === null)
+                return null;
+            named[name] = login;
+        }
+    }
+    if (top === null && Object.keys(named).length === 0)
+        return null;
+    return { default: top, clients: named };
 }
-export async function writeCredentials(credentials, configHome) {
-    const path = credentialsPath(configHome);
+function parseLogin(value) {
+    const { apiKey, apiUrl } = (value ?? {});
+    return typeof apiKey === "string" && typeof apiUrl === "string" ? { apiKey, apiUrl } : null;
+}
+/** Saves `credentials` as the default login, or as the named client's, keeping every other saved login. */
+export async function writeCredentials(credentials, options = {}) {
+    const path = credentialsPath(options.configHome);
     await mkdir(dirname(path), { recursive: true, mode: 0o700 });
-    await writeFileAtomic(path, `${JSON.stringify(credentials, null, 2)}\n`, 0o600);
+    const saved = (await readSavedLogins(options.configHome).catch(ignoreUnreadable)) ?? { default: null, clients: {} };
+    const next = options.client === undefined ? { ...saved, default: credentials } : { ...saved, clients: { ...saved.clients, [options.client]: credentials } };
+    await writeSavedLogins(path, next);
     return path;
 }
-export async function removeCredentials() {
-    await rm(credentialsPath(), { force: true });
+/** Removes the default login, or the named client's, keeping the rest; the file goes once nothing is left in it. */
+export async function removeCredentials(client) {
+    const path = credentialsPath();
+    const saved = await readSavedLogins().catch(ignoreUnreadable);
+    const clients = { ...saved?.clients };
+    if (client !== undefined)
+        delete clients[client];
+    const next = { default: client === undefined ? null : (saved?.default ?? null), clients };
+    if (next.default === null && Object.keys(clients).length === 0)
+        return rm(path, { force: true });
+    await writeSavedLogins(path, next);
+}
+async function writeSavedLogins(path, saved) {
+    const file = { ...saved.default, ...(Object.keys(saved.clients).length > 0 && { clients: saved.clients }) };
+    await writeFileAtomic(path, `${JSON.stringify(file, null, 2)}\n`, 0o600);
+}
+/** An unreadable file is replaced by the next login, as nothing in it can be used. */
+function ignoreUnreadable(error) {
+    if (error instanceof UnreadableCredentialsError)
+        return null;
+    throw error;
+}
+/** The API key env var beats `--client`, which beats the nearest client file above `cwd`, which beats the default login. */
+export async function chooseClient(clientFlag, cwd = process.cwd()) {
+    const flagged = clientFlag === undefined ? undefined : parseClientName(clientFlag);
+    if (process.env[`${envPrefix}_API_KEY`])
+        return { source: "env" };
+    if (flagged !== undefined)
+        return { source: "flag", client: flagged };
+    // A scheduled hand's run holds only its own default key, and must not be steered by files outside its folder.
+    if (process.env[RUN_ROOT_ENV])
+        return { source: "default" };
+    const found = await findClientFile(cwd);
+    return found ? { source: "folder", ...found } : { source: "default" };
+}
+async function findClientFile(from) {
+    for (let dir = resolve(from);; dir = dirname(dir)) {
+        const path = join(dir, CLIENT_FILE);
+        const text = await readFile(path, "utf8").catch((error) => {
+            if (error.code === "ENOENT" || error.code === "ENOTDIR")
+                return null;
+            throw new CliError(`Could not read the client file at ${path} (${error.code ?? error.message}), so the client to use is unknown.`, exitCodes.usage);
+        });
+        if (text !== null)
+            return { client: parseClientFile(text, path), path };
+        if (dirname(dir) === dir)
+            return null;
+    }
 }
-export async function resolveConnection(apiUrlFlag) {
-    const stored = await readCredentials();
-    const apiKey = process.env[`${envPrefix}_API_KEY`] || stored?.apiKey;
-    if (!apiKey) {
-        throw new CliError(`Not logged in. Run \`${brand.slug} login\` or set ${envPrefix}_API_KEY.`, exitCodes.auth);
+function parseClientFile(text, path) {
+    const malformed = new CliError(`The client file at ${path} is malformed. It should hold {"client": "<name>"}, a lowercase name with letters, digits and dashes.`, exitCodes.usage);
+    let value;
+    try {
+        value = JSON.parse(text);
     }
-    return { apiUrl: resolveApiUrl(apiUrlFlag, stored), apiKey };
+    catch {
+        throw malformed;
+    }
+    const client = value?.client;
+    if (typeof client !== "string" || !CLIENT_NAME.test(client))
+        throw malformed;
+    return client;
+}
+export async function resolveLogin(options) {
+    const choice = await chooseClient(options.client);
+    const saved = await readSavedLogins();
+    if (choice.source === "env") {
+        return { choice, connection: { apiUrl: resolveApiUrl(options.apiUrl, saved?.default ?? null), apiKey: process.env[`${envPrefix}_API_KEY`] } };
+    }
+    if (choice.source === "default") {
+        if (!saved?.default)
+            throw new CliError(`Not logged in. Run \`${brand.slug} login\` or set ${envPrefix}_API_KEY.`, exitCodes.auth);
+        return { choice, connection: { apiUrl: resolveApiUrl(options.apiUrl, saved.default), apiKey: saved.default.apiKey } };
+    }
+    const login = saved?.clients[choice.client];
+    const relogin = `\`${brand.slug} login --client ${choice.client}\``;
+    if (!login) {
+        const why = choice.source === "folder" ? `, named by ${choice.path}` : "";
+        throw new CliError(`No saved key for client ${choice.client}${why}. Run ${relogin}.`, exitCodes.auth);
+    }
+    const apiUrl = resolveApiUrl(options.apiUrl, login);
+    return { choice, connection: { apiUrl, apiKey: login.apiKey, rejected: `The API key for client ${choice.client} was rejected by ${apiUrl}. Run ${relogin} with a valid key.` } };
+}
+export async function resolveConnection(options) {
+    return (await resolveLogin(options)).connection;
+}
+/** The API URL the chosen login points at, for connections that carry another key; a missing or unreadable login is no error. */
+export async function chosenApiUrl(options) {
+    const choice = await chooseClient(options.client);
+    const saved = await readSavedLogins().catch(ignoreUnreadable);
+    const login = choice.source === "flag" || choice.source === "folder" ? saved?.clients[choice.client] : saved?.default;
+    return resolveApiUrl(options.apiUrl, login ?? null);
 }
 export function resolveApiUrl(apiUrlFlag, stored) {
     return (apiUrlFlag || process.env[`${envPrefix}_API_URL`] || stored?.apiUrl || brand.apiUrl).replace(/\/+$/, "");

package/dist/guide.js

@@ -23,8 +23,8 @@ export const guide = `# ${brand.name} CLI
 
 ## Setup
 
-1. Check the login: \`${cli} whoami\`. It prints the workspace name, slug, and id, and whether the key has library access.
-2. If it exits with code 3, you are not logged in. Ask the user to run \`${cli} login\` in their own terminal. It prompts for the key without showing it. Never ask for the key in chat and never put it on a command line, where it lands in shell history and logs. In CI, the key comes from the \`${envPrefix}_API_KEY\` environment variable.
+1. Check the login: \`${cli} whoami\`. It prints the workspace name, slug, and id, whether the key has library access, and which client's key is in use and why.
+2. If it exits with code 3, you are not logged in. Ask the user to run the \`${cli} login\` command the error names (\`${cli} login --client <name>\` for a named client) in their own terminal. It prompts for the key without showing it. Never ask for the key in chat and never put it on a command line, where it lands in shell history and logs. In CI, the key comes from the \`${envPrefix}_API_KEY\` environment variable.
 
 ## Start with the data guide
 
@@ -291,9 +291,9 @@ A scheduled hand's run acts as its skill's agent, the way the Facebook ads agent
 ## Commands
 
 \`\`\`
-${cli} login                        validate a key (prompted, piped, or ${envPrefix}_API_KEY) and save it
-${cli} logout                       delete saved credentials
-${cli} whoami                       show the current workspace and library access
+${cli} login [--client <name>]      validate a key (prompted, piped, or ${envPrefix}_API_KEY) and save it, as the default or under a client's name
+${cli} logout [--client <name>]     delete the default saved login, or one client's
+${cli} whoami                       show the current workspace, library access, and which client's key is in use and why
 ${cli} knowledge search "<question>" [--limit <n>] [--kind <kind>] [--hook-kind <v> ...]   short, cited snippets from the know-how libraries (keys with library access)
 ${cli} knowledge tag <entry-id> --hook-kind <v> --confidence <c>   tag a library entry with the marketing grammar (or --file tags.json)
 ${cli} guide                        what this workspace's data holds, how fresh it is, and what is missing: read it first