@wrangled/cli 0.3.44 → 0.3.46

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
 
@@ -140,6 +140,7 @@ A webhook address lets a tool such as a form or webinar platform push events int
 3. A run that is still going prints its id. Check it with \`${cli} tools get <run-id>\`. Image results list an \`asset\` link. Save the file with \`${cli} creatives download <asset-link>\`, or fetch the link with your API key as a bearer token; it redirects to a copy that works for 10 minutes.
 4. Record a succeeded run in the ledger with its lineage: \`${cli} creatives create --run <run-id> --lineage '{"persona": "...", "painPoint": "...", "desiredOutcome": "...", "angle": "...", "sourceAd": {"metaAdId": "..."}}'\`. Each output gets a SKU such as \`DLC-000123\`. The SKU goes in the Meta ad name. Lineage is free-text notes; give the ad's marketing tags with \`--tags '<json>'\` or \`--tags @tags.json\`, the same fields as ad tags (see Ad tags), such as \`{"offer_key": "course", "landing_funnel_key": "webinar_to_course", "landing_step_key": "registration_page", "persona": "near_retirement", "angle": "story", "format": "image"}\`. Every output of the run gets them. Values come from \`${cli} grammar\`; persona and concept from this client's lists, and offer, funnel and step from its confirmed map (\`${cli} funnels show\`), where the step must be in that funnel and \`reply\` or \`no_link\` take no step. A value off them is refused with the ones to use. Recording the same run again returns its creatives as they are, tags included; \`${cli} creatives tag <sku> --file tags.json\` is how to change a creative's tags. Your tags read proposed until an Owner or Admin confirms them on the creative's page in Content; after that only a person changes them.
 5. \`${cli} creatives list\` and \`${cli} creatives show <sku>\` read the ledger. \`${cli} creatives download <sku>\` saves a creative's image or video as \`<sku>.<ext>\` in the current folder; \`--out <path>\` names the file or a folder, and \`--open\` opens it. It also takes an asset path or link, such as a \`meta_ad_creatives\` \`image_path\`. \`--format json\` prints \`{ path, bytes, contentType }\`. Copy has no file; its text is in \`${cli} creatives show\`. For performance, query the \`creatives\` table or the \`creative_performance_daily\` view with \`${cli} warehouse query\`.
+6. \`${cli} media list\` lists every image and video the tools made, newest first, whether or not it became a creative: its media id (\`<run id>:<index>\`), tool, prompt, cost and SKU, if any. Narrow it with \`--sku <sku>\`, \`--run <run-id>\` (one batch), \`--tool kie:nano-banana\`, \`--kind image|video\`, \`--since\` and \`--until\` (a day such as \`2026-10-08\`, which \`--until\` counts through its end in UTC, or an ISO time), and \`--limit <n>\` (default 50, at most 200). When more remain it prints the \`--cursor <media-id>\` that shows the next page. A run's cost is split evenly across its outputs and marked as an estimate when the provider did not report a charge. \`${cli} media get <media-id>\` shows the full input that made one, to reuse a good prompt; \`${cli} media download <media-id>\` saves its file, named by its SKU when it has one (\`${cli} creatives download\` takes a media id too). \`--format json\` prints \`{ media, nextCursor }\`.
 
 ## Landing pages
 
@@ -291,9 +292,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
@@ -326,9 +327,12 @@ ${cli} tools run <tool> --input '<json>' [--idempotency-key <key>] [--wait <seco
 ${cli} tools get <run-id>           show a tool run, waiting for it to finish (--wait)
 ${cli} creatives list               list creatives (--status, --kind, --limit)
 ${cli} creatives show <sku>         show one creative with its spec and lineage
-${cli} creatives download <sku | asset-path | asset-link> [--out <path>] [--open]   save a creative's image or video
+${cli} creatives download <sku | media-id | asset-path | asset-link> [--out <path>] [--open]   save a creative's image or video
 ${cli} creatives create --run <run-id> [--lineage '<json>' | @file.json] [--tags '<json>' | @file.json]   record a run's output with a new SKU
 ${cli} creatives tag <sku> --file <tags.json>   replace a creative's marketing tags, proposed until a person confirms them
+${cli} media list                   list every made image and video (--sku, --run, --tool, --kind, --since, --until, --limit, --cursor)
+${cli} media get <media-id>         show the tool, model, full input and cost that made one
+${cli} media download <media-id> [--out <path>] [--open]   save a made image or video
 ${cli} content create --kind <kind> [--body ...] [--file <path>] [--note <why>] [--plan <plan-id>]   save made content with a new SKU
 ${cli} content search [--text <words>] [--mode word|meaning] [--kind <kind>] [--platform <p>] [--origin <o>] [--from <date>] [--to <date>] [--sort <column>] [--order asc|desc] [--limit <n>]   find content with its numbers
 ${cli} content pull <dir> [--kind <kind>] [--platform <p>] [--origin <o>] [--media] [--full]   copy the library to a folder of Markdown files; rerun for changes