@wrangled/cli 0.3.24 → 0.3.26

package/dist/api.js

@@ -16,6 +16,11 @@ export class UnreadableCredentialsError extends CliError {
         super(`The saved credentials at ${path} are unreadable. Run \`${brand.slug} login\` again.`, exitCodes.auth);
     }
 }
+/**
+ * The grammar fields library entries are tagged with, and the CLI flag for each; the server's list is entryTagFields
+ * in src/lib/knowledge/tags.ts. format's flag is --ad-format, because --format picks the output.
+ */
+export const entryTagFlags = { angle: "angle", hook_kind: "hook-kind", format: "ad-format", awareness: "awareness" };
 /** Copies of the server's IMPORT_LIMITS and import name rule; src/lib/cli-consistency.test.ts keeps them in step. */
 export const IMPORT_LIMITS = { bytes: 50 * 1024 * 1024, rows: 1_000_000, columns: 500 };
 export const IMPORT_NAME_PATTERN = /^[a-z][a-z0-9_]{0,40}$/;

package/dist/guide.js

@@ -44,6 +44,8 @@ For what has worked for others, such as "how do members test new hooks" or "what
 - The question is 1 to 4000 characters. \`--limit\` is 1 to 12 (default 5). \`--kind\` (message, transcript, document, note) keeps one kind of source. \`--library <slug>\` keeps one library.
 - \`--library meta-policy\` searches Meta's own advertising standards, copied from Meta's site every Monday. Before you write or judge an ad, check its claims there, such as income, health or before-and-after claims: \`${cli} knowledge search --library meta-policy "income claims"\`. Its evidence is \`meta_published_policy\`, Meta's published rule; Meta's reviewers still decide each ad.
 - \`knowledge_not_synced\` means the library has not been copied into this server yet, so nothing was searched; the weekly sync fills it.
+- Library entries carry the marketing grammar's tags: \`--angle\`, \`--hook-kind\`, \`--ad-format\` and \`--awareness\` (the ad tag fields angle, hook_kind, format and awareness, with the same values). Give any of them to keep to entries tagged that way; the question is then optional, and without one the entries come surest tags first. With a tag filter the answer also lists this workspace's own Meta ads whose live tags hold the same values, with their lifetime spend and results, biggest spend first (at most 20): what the library says next to how it went for this client.
+- Each result shows its entry id and tags. Tag an entry you read with \`${cli} knowledge tag <entry-id> --hook-kind big_win --confidence medium\` (several flags at once is fine), take a wrong tag off with \`--remove\`, or tag a batch with \`${cli} knowledge tag --file tags.json\`, where the file is \`{"tags": [{"entry_id", "field", "value", "confidence"}]}\` (up to 500; \`"remove": true\` in place of confidence takes one off). Values off the grammar's list are refused.
 
 ## Query workflow: schema first
 
@@ -244,7 +246,8 @@ A scheduled hand's run acts as its skill's agent, the way the Facebook ads agent
 ${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} knowledge search "<question>" [--limit <n>] [--kind <kind>]   short, cited snippets from the Creative Cartel know-how library (keys with library access)
+${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
 ${cli} brief [--from <date>] [--to <date>] [--channel <channel>] [--campaign <id>] [--top <n>]   the offer, voice, best and worst ads, pages, results and audience: start here before writing ads
 ${cli} winners [--week <date>] [--top <n>]   which Facebook ads won and flopped this week and over 30 days, judged on first-touch sales

package/dist/main.js

@@ -4,7 +4,7 @@ import { mkdir, readFile, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, extname, join, resolve } from "node:path";
 import { parseArgs } from "node:util";
-import { api, ApiError, apiDownload, apiText, apiUpload, CliError, exitCodes, getSigned, IMPORT_LIMITS, IMPORT_NAME_PATTERN, putSigned, readCredentials, removeCredentials, resolveApiUrl, resolveConnection, UnreadableCredentialsError, writeCredentials, streamSigned, } from "./api.js";
+import { api, ApiError, apiDownload, apiText, apiUpload, CliError, exitCodes, getSigned, IMPORT_LIMITS, IMPORT_NAME_PATTERN, putSigned, readCredentials, removeCredentials, resolveApiUrl, resolveConnection, UnreadableCredentialsError, writeCredentials, entryTagFlags, streamSigned, } from "./api.js";
 import { brand, envPrefix } from "./brand.js";
 import { firstSymlink, inRunFolder, writeFileAtomic } from "./files.js";
 import { guide, skill } from "./guide.js";
@@ -57,23 +57,55 @@ const commands = {
         },
     },
     "knowledge search": {
-        usage: 'knowledge search "<question>" [--limit <n>] [--kind message|transcript|document|note] [--library <slug>]',
+        usage: 'knowledge search ["<question>"] [--limit <n>] [--kind message|transcript|document|note] [--library <slug>] [--angle <v>] [--hook-kind <v>] [--ad-format <v>] [--awareness <v>]',
         async run(args, options) {
-            if (args.length !== 1)
-                throw new CliError('Usage: knowledge search "<question>" [--limit <n>] [--kind <kind>] [--library <slug>]; put the question in quotes', exitCodes.usage);
-            const query = new URLSearchParams({ q: args[0] });
+            const filters = Object.entries(options.entryTags);
+            if (args.length > 1 || (args.length === 0 && filters.length === 0)) {
+                throw new CliError('Usage: knowledge search "<question>" [--limit <n>] [--kind <kind>] [--library <slug>] [--angle <v>] [--hook-kind <v>] [--ad-format <v>] [--awareness <v>]; put the question in quotes, or give a tag filter', exitCodes.usage);
+            }
+            const query = new URLSearchParams(args[0] === undefined ? {} : { q: args[0] });
             if (options.limit !== undefined)
                 query.set("limit", options.limit);
             if (options.kind !== undefined)
                 query.set("kind", options.kind);
             if (options.library !== undefined)
                 query.set("library", options.library);
-            const { results } = await api(await resolveConnection(options.apiUrl), `/api/v1/knowledge/search?${query}`);
+            for (const [field, value] of filters)
+                query.set(field, value);
+            const answer = await api(await resolveConnection(options.apiUrl), `/api/v1/knowledge/search?${query}`);
             if (options.format === "json")
-                return printJson({ results });
-            if (results.length === 0)
-                return console.log("Nothing in the library matched.");
-            console.log(results.map(knowledgeBlock).join("\n\n"));
+                return printJson(answer);
+            console.log(answer.results.length === 0 ? "Nothing in the library matched." : answer.results.map(knowledgeBlock).join("\n\n"));
+            if (answer.yourAds === undefined)
+                return;
+            const tagged = filters.map(([field, value]) => `${field} ${value}`).join(", ");
+            if (answer.yourAds.length === 0)
+                return console.log(`\nNone of your ads is tagged ${tagged}.`);
+            console.log(`\nYour ads tagged ${tagged}, biggest spend first:`);
+            console.log(renderTable(["ad", "name", "tags", "spend", "results"], answer.yourAds.map(yourAdRow)));
+        },
+    },
+    "knowledge tag": {
+        usage: "knowledge tag <entry-id> [--angle <v>] [--hook-kind <v>] [--ad-format <v>] [--awareness <v>] --confidence high|medium|low [--remove] | --file <tags.json>   tag library entries with the marketing grammar",
+        async run(args, options) {
+            const usage = "Usage: knowledge tag <entry-id> [--angle <v>] [--hook-kind <v>] [--ad-format <v>] [--awareness <v>] --confidence high|medium|low [--remove], or knowledge tag --file <tags.json>";
+            const filters = Object.entries(options.entryTags);
+            if (args.length > 1 || (args.length === 1 && filters.length === 0))
+                throw new CliError(usage, exitCodes.usage);
+            const body = args.length === 1
+                ? {
+                    tags: filters.map(([field, value]) => ({
+                        entry_id: args[0],
+                        field,
+                        value,
+                        ...(options.remove ? { remove: true } : { confidence: options.confidence }),
+                    })),
+                }
+                : await readToolInput(options);
+            const result = await api(await resolveConnection(options.apiUrl), KNOWLEDGE_TAGS_PATH, body);
+            if (options.format === "json")
+                return printJson(result);
+            console.log(`Tagged ${result.tagged}, took off ${result.removed}.`);
         },
     },
     "warehouse schema": {
@@ -1294,7 +1326,11 @@ const commands = {
             const { fact } = await api(await resolveConnection(options.apiUrl), `${FACTS_PATH}/${encodeURIComponent(args[0])}`);
             if (options.format === "json")
                 return printJson({ fact });
-            printFields({ ...factRow(fact), summary: fact.summary, value: fact.value, evidence: fact.evidence, author: fact.author, "confirmed by": fact.confirmedBy, "decided by": fact.decidedBy, replaces: fact.replaces });
+            const nameKey = fact.key === NAME_KEY ? nameKeyLines(fact.value) : null;
+            const value = nameKey ? { means: fact.value.means } : { value: fact.value };
+            printFields({ ...factRow(fact), summary: fact.summary, ...value, evidence: fact.evidence, author: fact.author, "confirmed by": fact.confirmedBy, "decided by": fact.decidedBy, replaces: fact.replaces });
+            if (nameKey)
+                console.log(nameKey.join("\n"));
         },
     },
     "facts propose": {
@@ -1867,6 +1903,7 @@ function printReport(title, report, labels, numbers) {
 const agentPath = (options) => `/api/v1/agents/${encodeURIComponent(options.agent)}`;
 const FACTS_PATH = "/api/v1/facts";
 const AD_TAGS_PATH = "/api/v1/ad-tags";
+const KNOWLEDGE_TAGS_PATH = "/api/v1/knowledge/tags";
 const AD_AUTOTAG_PATH = "/api/v1/ad-tags/autotag";
 const SKIP_REASONS = { not_marketing: "Not marketing, so only that answer was saved", gate_unclear: "Could not tell whether it is marketing, so only that was saved", no_content: "Nothing to read", not_found: "No such ad" };
 const AD_TAG_COLUMNS = ["id", "ad", "status", "confidence", "offer", "persona", "angle", "hook", "format", "author"];
@@ -1888,8 +1925,16 @@ function knowledgeBlock(r, i) {
     lines.push(`   ${r.snippet}`);
     if (r.caveat)
         lines.push(`   Caveat: ${r.caveat}`);
+    if (r.entryId) {
+        const tags = Object.entries(r.tags ?? {}).flatMap(([field, values]) => values.map((value) => `${field} ${value}`));
+        lines.push(`   Entry ${r.entryId}${tags.length > 0 ? `, tagged ${tags.join(", ")}` : ""}`);
+    }
     return lines.join("\n");
 }
+function yourAdRow(a) {
+    const results = a.results === null ? null : `${a.results} ${a.resultType ?? ""}`.trim();
+    return { ad: a.adId, name: a.adName, tags: `${a.tagStatus}, ${a.tagConfidence}`, spend: a.spend === null ? null : `${a.spend.toFixed(2)} ${a.currency ?? ""}`.trim(), results };
+}
 function adTagRow(t) {
     const { offer_key, persona, angle, hook_kind, hook_spot, format, style } = t.tags;
     return { id: t.id, ad: t.adId, status: t.status, confidence: t.confidence, offer: offer_key, persona, angle, hook: [hook_kind, hook_spot].filter(Boolean).join(" in ") || null, format: [format, style].filter(Boolean).join(", ") || null, author: t.author };
@@ -1907,6 +1952,27 @@ function voiceLineRow(l) {
 function factRow(f) {
     return { id: f.id, kind: f.kind, subject: `${f.subjectType}:${f.subjectRef}`, key: f.key, status: f.status, summary: excerpt(f.summary, 80) };
 }
+/** The definition key that holds a workspace's name key: the server's NameKey, read here without its schema. */
+const NAME_KEY = "ad_name_key";
+const NAME_LEVELS = { campaign: "campaign", ad_set: "ad set", ad: "ad" };
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const arrayOf = (v) => (Array.isArray(v) ? v.filter(isObject) : []);
+/** A name key as lines a person reads: each pattern with an example name and what its segments mean, then the questions left. Null when the value holds none. */
+function nameKeyLines(value) {
+    const nameKey = isObject(value) && isObject(value.name_key) ? value.name_key : null;
+    if (!nameKey || !isObject(nameKey.levels))
+        return null;
+    const levels = nameKey.levels;
+    const patterns = Object.entries(NAME_LEVELS).flatMap(([level, label]) => arrayOf(levels[level]).map((pattern) => {
+        const segments = arrayOf(pattern.segments).map((s) => {
+            const meaning = typeof s.label === "string" ? s.label : String(s.meaning ?? "unknown").replaceAll("_", " ");
+            return `${String(s.name)} = ${meaning}${s.certainty === "guess" ? " (a guess)" : ""}`;
+        });
+        return `- ${label} names like ${String(pattern.example)}: ${segments.join("; ")}`;
+    }));
+    const questions = arrayOf(nameKey.open_questions).map((q) => `- ${String(q.text)}`);
+    return ["", "Name patterns:", ...(patterns.length > 0 ? patterns : ["- none yet"]), "", "Open questions:", ...(questions.length > 0 ? questions : ["- none"])];
+}
 const STORIES_PATH = "/api/v1/stories";
 function printStory(story) {
     const corrects = story.previousId ? `, correcting ${story.previousId}` : "";
@@ -2022,6 +2088,10 @@ Options:
   --limit <n>           how many results content search, creatives list, campaigns, voice, ads tags, content tags and content to-check
                         return, or how many ads ads autotag tags and how many items content autotag tags
   --library <slug>      with knowledge search, only this library: creative-cartel, exodus or meta-policy
+  --angle, --hook-kind, --ad-format, --awareness <value>   with knowledge search, only library entries tagged that way, and
+                        your own ads tagged the same way with their results; with knowledge tag, the tags to put on an entry
+  --confidence high|medium|low   with knowledge tag, how sure you are of the tags
+  --remove              with knowledge tag, take the tags off instead
   --ad <id>             with ads tags, only this Meta ad's tags; with ads autotag, only this ad
   --kind email|text|page   with content tags and content autotag, only that kind (content autotag takes a comma list)
   --max-seconds <n>     stop a runner's run after this many seconds, if that comes before its deadline
@@ -2122,6 +2192,12 @@ function parseOptions(argv) {
             step: { type: "string" },
             workspace: { type: "string" },
             "max-seconds": { type: "string" },
+            angle: { type: "string" },
+            "hook-kind": { type: "string" },
+            "ad-format": { type: "string" },
+            awareness: { type: "string" },
+            confidence: { type: "string" },
+            remove: { type: "boolean", default: false },
             help: { type: "boolean", short: "h", default: false },
         },
     });
@@ -2219,6 +2295,9 @@ function parseOptions(argv) {
             step: values.step,
             workspace: values.workspace,
             maxSeconds,
+            entryTags: Object.fromEntries(Object.entries(entryTagFlags).flatMap(([field, flag]) => (values[flag] === undefined ? [] : [[field, values[flag]]]))),
+            confidence: values.confidence,
+            remove: values.remove,
         },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wrangled/cli",
-  "version": "0.3.24",
+  "version": "0.3.26",
   "description": "Command-line access to your marketing data warehouse, for people and coding agents",
   "type": "module",
   "bin": {