@wrangled/cli 0.3.21 → 0.3.22

package/dist/guide.js

@@ -35,7 +35,7 @@ To read the whole library with your own tools, such as "every email we have" or
 
 ## Know-how library: Creative Cartel
 
-For what has worked for others, such as "how do members test new hooks" or "what do people say about advertorials", search the know-how library: \`${cli} knowledge search "<question>"\`. Today it holds Creative Cartel's library (\`creative-cartel\`), copied into this server every Monday afternoon. It works only when the key has library access (\`${cli} whoami\` says); without it the answer is \`knowledge_not_allowed\`. It finds snippets by their words and by their meaning, and returns them short, never whole documents: each at most 280 characters, with its title, link, kind, caveat, evidence and the day its library was copied in. Evidence \`reported member statement\` is a member's claim, not a checked result; weigh it that way and say so when you use it. The library writes no answer for you: read the snippets and decide. Use your own words: saving text that repeats 12 words in a row from anything in the library is refused with \`copies_library_text\`.
+For what has worked for others, such as "how do members test new hooks" or "what do people say about advertorials", search the know-how library: \`${cli} knowledge search "<question>"\`. Today it holds Creative Cartel's library (\`creative-cartel\`) and the team's own Exodus copy and ad frameworks (\`exodus\`), both copied into this server every Monday afternoon. It works only when the key has library access (\`${cli} whoami\` says); without it the answer is \`knowledge_not_allowed\`. It finds snippets by their words and by their meaning, and returns them short, never whole documents: each at most 280 characters, with its title, link, kind, caveat, evidence and the day its library was copied in. Evidence \`reported member statement\` is a member's claim, not a checked result; weigh it that way and say so when you use it. Evidence \`team method\` is the team's own framework: reason with it, never paste it into client work. The library writes no answer for you: read the snippets and decide. Use your own words: saving text that repeats 12 words in a row from anything in the library is refused with \`copies_library_text\`.
 
 - 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.
 - \`knowledge_not_synced\` means the library has not been copied into this server yet, so nothing was searched; the weekly sync fills it.
@@ -87,7 +87,7 @@ A webhook address lets a tool such as a form or webinar platform push events int
 1. \`${cli} tools list\` shows each tool id (\`provider:tool\`, such as \`kie:nano-banana\`), whether it runs sync or async, and what it makes. \`--format json\` adds each tool's description, cost, and input JSON Schema.
 2. \`${cli} tools run kie:nano-banana --input '{"prompt": "...", "aspectRatio": "1:1"}' --idempotency-key <key>\` starts a run and waits for it (up to \`--wait\` seconds, default 300). Tools cost money. Always pass an idempotency key, and reuse it when you retry, so a retry returns the same run instead of paying twice.
 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.
+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\`.
 
 ## Landing pages
@@ -178,6 +178,12 @@ To have the server tag ads for you, run \`${cli} ads autotag\` (\`--limit <n>\`,
 
 For what worked, query the \`ad_performance_tagged\` view: every Meta ad's daily results with its live tags next to them, \`tags_source\` (\`ad_tags\`, or null when untagged) and \`tags_status\`.
 
+## Content tags
+
+Emails, text messages and landing pages in the content library get the same grammar's tags, by content item id. \`${cli} content tags [<item-id>]\` lists them (\`--kind email|text|page\`, \`--status proposed|confirmed|rejected|replaced\`, \`--limit <n>\`, \`--json\`); by default the live ones. Each row names the version of the item's words it describes (\`contentHash\`). Only the parts that fit the kind are filled: an email's or text's job (invite, reminder, last chance and so on), no job for a page, and no secondary hook for a text, whose format (sms or mms) comes from whether it carries a picture.
+
+To have the server tag them, run \`${cli} content autotag\` (\`--limit <n>\`, 1 to 100, default 25; \`--kind email,text\` to narrow; item ids as arguments for those items; \`--json\`). It takes the items whose current words have no tags yet, the ones that brought in the most sales first, then the most clicks, then the newest, so a repeat run spends nothing on what it already tagged. Items that read the same, such as one email sent to several lists, are asked about once and share the tags. An email whose body was never stored is asked only whether it is marketing, its hook and its job. When an item's words change, its next run replaces its tags, even confirmed ones, since a person confirmed the old words. \`${cli} content to-check\` lists the emails and texts whose tags wait for a person, most sales first, then most clicks; the same rows are in the \`content_tags\` table.
+
 ## Ad words
 
 Tag ads, emails, texts and pages only with the words \`${cli} grammar\` lists (\`--format json\` for the same lists as data): each part's question and allowed values. Persona (who it talks to) and Concept (the one idea it sells) are this client's own lists; the other parts are shared by every client. A persona or concept marked not yet confirmed may be used. A retired one is never used for new tags; an old tag with it counts as the value it was merged into. To suggest new personas and concepts, run \`${cli} grammar propose --file values.json\` with \`{"values": [{"part": "persona", "key": "age_50s_retirement", "label": "In their 50s, worried about retirement", "definition": "People in their 50s who fear their savings will not last.", "examples": ["<SKU>"]}]}\`. You only suggest: a value already on the list is left as it is, and a person confirms, renames, merges or retires values in the app. The \`grammar\` playbook (\`${cli} skill install grammar\` installs it as the \`${GRAMMAR_SKILL_NAME}\` skill; \`${cli} docs grammar\` prints it) walks an agent from the client's ads to a first draft.
@@ -259,7 +265,8 @@ ${cli} tools get <run-id>           show a tool run, waiting for it to finish (-
 ${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 create --run <run-id> [--lineage '<json>' | @file.json]   record a run's output with a new SKU
+${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} 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
@@ -290,6 +297,8 @@ ${cli} facts [--kind <kind>] [--subject <type>[:<ref>]] [--status <status>] [--j
 ${cli} facts propose --file <fact.json>   suggest a fact for a person to confirm
 ${cli} ads tags [--ad <id>] [--status <status>] [--limit <n>] | ads tag --file <tags.json>   the marketing tags of ads not made here, and suggesting them
 ${cli} ads autotag [--limit <n>] [--ad <id>]   have the server propose tags for the biggest spenders not yet tagged
+${cli} content tags [<item-id>] [--kind email|text|page] | content to-check   the marketing tags of emails, texts and landing pages, and those waiting for a person
+${cli} content autotag [<item-id> ...] [--kind email|text|page] [--limit <n>]   have the server propose tags for the emails, texts and pages worth most not yet tagged
 ${cli} grammar [--format json]   every list ads are tagged from, this client's personas and concepts included
 ${cli} grammar propose --file <values.json>   suggest personas and concepts for a person to confirm
 ${cli} voice [--kind opener|objection|phrase] [--limit <n>] [--json]   what customers keep saying, grouped and counted, with real quotes

package/dist/main.js

@@ -500,7 +500,7 @@ const commands = {
                 tool: creative.spec.tool,
                 prompt: creative.spec.input?.prompt,
             };
-            const shown = ["sku", "kind", "status", "tool", "prompt", "lineage", "assetUrl", "copyText", "metaAdId", "toolRunId", "createdAt"];
+            const shown = ["sku", "kind", "status", "tool", "prompt", "lineage", "tags", "tagsStatus", "tagsConfirmedBy", "assetUrl", "copyText", "metaAdId", "toolRunId", "createdAt"];
             console.log(renderTable(["field", "value"], shown.filter((f) => fields[f] != null).map((f) => ({ field: f, value: fields[f] }))));
         },
     },
@@ -522,18 +522,33 @@ const commands = {
         },
     },
     "creatives create": {
-        usage: "creatives create --run <tool-run-id> [--lineage '<json>' | @file.json]",
+        usage: "creatives create --run <tool-run-id> [--lineage '<json>' | @file.json] [--tags '<json>' | @file.json]",
         async run(args, options) {
-            if (args.length > 0 || !options.run)
-                throw new CliError("Usage: creatives create --run <tool-run-id> [--lineage '<json>' | @file.json]", exitCodes.usage);
+            if (args.length > 0 || !options.run) {
+                throw new CliError("Usage: creatives create --run <tool-run-id> [--lineage '<json>' | @file.json] [--tags '<json>' | @file.json]", exitCodes.usage);
+            }
             const lineage = options.lineage === undefined ? undefined : await parseJson(options.lineage, "--lineage");
+            const tags = options.tags === undefined ? undefined : await parseJson(options.tags, "--tags");
             const { creatives } = await api(await resolveConnection(options.apiUrl), "/api/v1/creatives", {
                 runId: options.run,
                 ...(lineage === undefined ? {} : { lineage }),
+                ...(tags === undefined ? {} : { tags }),
             });
             if (options.format === "json")
                 return printJson({ creatives });
-            console.log(renderTable(["sku", "kind", "status", "assetUrl"], creatives));
+            console.log(renderTable(["sku", "kind", "status", "tagsStatus", "assetUrl"], creatives));
+        },
+    },
+    "creatives tag": {
+        usage: "creatives tag <sku> --file <tags.json> | < tags.json   replace a creative's marketing tags; a person confirms them in the app",
+        async run(args, options) {
+            if (args.length !== 1)
+                throw new CliError("Usage: creatives tag <sku> --file <tags.json> | < tags.json", exitCodes.usage);
+            const tags = await readToolInput(options);
+            const { creative } = await api(await resolveConnection(options.apiUrl), `/api/v1/creatives/${encodeURIComponent(args[0])}/tags`, { tags }, "PATCH");
+            if (options.format === "json")
+                return printJson({ creative });
+            console.log(`Tagged ${creative.sku}. The tags read ${creative.tagsStatus} until a person confirms them in the app.`);
         },
     },
     "content create": {
@@ -1186,6 +1201,63 @@ const commands = {
                 console.log("Stopped early: the run's tool spending cap was reached.");
         },
     },
+    "content tags": {
+        usage: "content tags [<item-id>] [--kind email|text|page] [--status <status>] [--limit <n>] [--json]   the marketing tags of emails, texts and landing pages",
+        async run(args, options) {
+            if (args.length > 1)
+                throw new CliError("Usage: content tags [<item-id>] [--kind email|text|page] [--status <status>] [--limit <n>] [--json]", exitCodes.usage);
+            const filters = { item: args[0], kind: options.kind, status: options.status, limit: options.limit };
+            const query = new URLSearchParams(Object.entries(filters).filter((entry) => entry[1] !== undefined));
+            const { tags } = await api(await resolveConnection(options.apiUrl), `${CONTENT_TAGS_PATH}${query.size ? `?${query}` : ""}`);
+            if (options.format === "json")
+                return printJson({ tags });
+            if (tags.length === 0)
+                return console.log("No content tags.");
+            console.log(renderTable(CONTENT_TAG_COLUMNS, tags.map(contentTagRow)));
+        },
+    },
+    "content to-check": {
+        usage: "content to-check [--limit <n>] [--json]   the emails and texts whose tags wait for a person, most sales first, then most clicks",
+        async run(args, options) {
+            if (args.length > 0)
+                throw new CliError("Usage: content to-check [--limit <n>] [--json]", exitCodes.usage);
+            const query = new URLSearchParams({ to_check: "1", ...(options.limit ? { limit: options.limit } : {}) });
+            const { tags } = await api(await resolveConnection(options.apiUrl), `${CONTENT_TAGS_PATH}?${query}`);
+            if (options.format === "json")
+                return printJson({ tags });
+            if (tags.length === 0)
+                return console.log("No email or text tags wait for a person.");
+            console.log(renderTable(["item", "kind", "revenue", "clicks", ...CONTENT_TAG_COLUMNS.slice(4)], tags.map((t) => ({ ...contentTagRow(t), revenue: t.revenue, clicks: t.clicks }))));
+        },
+    },
+    "content autotag": {
+        usage: "content autotag [<item-id> ...] [--kind email|text|page] [--limit <n>] [--json]   propose marketing tags for the emails, texts and landing pages worth most that have none",
+        async run(args, options) {
+            const body = {
+                ...(args.length > 0 ? { item_ids: args } : {}),
+                ...(options.kind ? { kinds: options.kind.split(",") } : {}),
+                ...(options.limit ? { limit: Number(options.limit) } : {}),
+            };
+            const result = await api(await resolveConnection(options.apiUrl), CONTENT_AUTOTAG_PATH, body);
+            if (options.format === "json")
+                return printJson(result);
+            const plural = (n) => `${n} ${n === 1 ? "item" : "items"}`;
+            console.log(`Proposed tags for ${plural(result.proposed.length)}, asking about ${result.groups} ${result.groups === 1 ? "set of words" : "sets of words"} for $${result.costUsd.toFixed(4)}. A person confirms or rejects them in the app.`);
+            if (result.proposed.length > 0)
+                console.log(renderTable(["item", "id", "confidence"], result.proposed.map((p) => ({ item: p.itemId, id: p.id, confidence: p.confidence }))));
+            if (result.kept.length > 0)
+                console.log(`Kept as they are, since a person confirmed their tags: ${result.kept.join(", ")}.`);
+            for (const reason of ["not_marketing", "gate_unclear", "no_content", "not_found", "changed"]) {
+                const ids = result.skipped.filter((s) => s.reason === reason).map((s) => s.itemId);
+                if (ids.length > 0)
+                    console.log(`${CONTENT_SKIP_REASONS[reason]}: ${ids.join(", ")}.`);
+            }
+            for (const failure of result.failed)
+                console.log(`Failed for ${failure.itemIds.join(", ")}: ${failure.error}`);
+            if (result.stopped === "tool_cap")
+                console.log("Stopped early: the run's tool spending cap was reached.");
+        },
+    },
     "facts show": {
         usage: "facts show <id>   one fact with its value and evidence",
         async run(args, options) {
@@ -1716,6 +1788,10 @@ const AD_TAGS_PATH = "/api/v1/ad-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"];
+const CONTENT_TAGS_PATH = "/api/v1/content-tags";
+const CONTENT_SKIP_REASONS = { ...SKIP_REASONS, not_found: "No such email, text or landing page", changed: "Its words changed while it was being tagged, so nothing was saved; the next run tags them" };
+const CONTENT_AUTOTAG_PATH = "/api/v1/content-tags/autotag";
+const CONTENT_TAG_COLUMNS = ["id", "item", "kind", "status", "confidence", "hook", "job", "offer", "angle", "format"];
 const GRAMMAR_PATH = "/api/v1/grammar";
 const VOICE_LISTS_PATH = "/api/v1/voice-lists";
 const VOICE_SUGGESTIONS_PATH = "/api/v1/voice-lists/suggestions";
@@ -1735,6 +1811,10 @@ 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 };
 }
+function contentTagRow(t) {
+    const { hook_kind, hook_spot, job, offer_key, angle, format } = t.tags;
+    return { id: t.id, item: t.itemId, kind: t.kind, status: t.status, confidence: t.confidence, hook: [hook_kind, hook_spot].filter(Boolean).join(" in ") || null, job, offer: offer_key, angle, format };
+}
 function voiceRow(c) {
     return { ref: c.ref, kind: c.kind, "said by": c.supportCount, likes: c.likeSum, label: excerpt(c.label, 60), "top quote": c.evidence[0] ? excerpt(c.evidence[0].quote, 60) : null };
 }
@@ -1852,9 +1932,11 @@ Options:
   --from, --to <n>      with content diff, the two versions to compare (default: the one before the current one, and the current one)
   --sort <column>       how content search sorts: recent (default) or a content_scorecard number, such as click_rate or roas
   --order desc|asc      content search's sort direction (default: desc, best or newest first)
-  --limit <n>           how many results content search, creatives list, campaigns, voice and ads tags return, or how many ads ads autotag tags
-  --library <slug>      with knowledge search, only this library, such as creative-cartel
+  --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 or exodus
   --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
   --workspace <slug>    for worker promote and worker drop: the workspace whose hand they change
   -h, --help            show this help
@@ -1888,6 +1970,7 @@ function parseOptions(argv) {
             limit: { type: "string" },
             run: { type: "string" },
             lineage: { type: "string" },
+            tags: { type: "string" },
             sources: { type: "string" },
             codex: { type: "boolean", default: false },
             agent: { type: "string" },
@@ -1981,6 +2064,7 @@ function parseOptions(argv) {
             limit: values.limit,
             run: values.run,
             lineage: values.lineage,
+            tags: values.tags,
             sources: values.sources,
             codex: values.codex,
             agent: values.agent ?? (process.env[AGENT_ENV] || "meta_ads"),

package/dist/skill-zip.js

@@ -41,10 +41,16 @@ export function unsafeFileName(name) {
         return `empty or . segment in ${name}`;
     return null;
 }
-/** Zips the files; each name is a `/`-separated path inside the skill folder. */
+/**
+ * The time stamped on every zipped file: the earliest a zip can hold. The library recognises a skill version by its
+ * zip's sha256, so the same files must zip to the same bytes on every run. fflate reads the date in local time, and
+ * this one is built in local time, so it encodes the same in every time zone.
+ */
+const ZIP_MTIME = new Date(1980, 0, 1);
+/** Zips the files; each name is a `/`-separated path inside the skill folder. The same files always give the same bytes. */
 export function zipSkillFiles(files) {
     const unix = (mode) => ({ os: 3, attrs: ((0o100000 | mode) << 16) >>> 0 });
-    return zipSync(Object.fromEntries(files.map((f) => [f.name, [f.data, unix(f.executable ? 0o755 : 0o644)]])), { level: 9 });
+    return zipSync(Object.fromEntries(files.map((f) => [f.name, [f.data, unix(f.executable ? 0o755 : 0o644)]])), { level: 9, mtime: ZIP_MTIME });
 }
 /** Reads and checks a skill's zip without trusting any size or name it declares. Throws SkillZipError naming the problem. */
 export function readSkillZip(zip, skillName) {

package/package.json

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