@wrangled/cli 0.3.166 → 0.3.167

package/dist/guide.js

@@ -27,7 +27,8 @@ export const funnelTestExample = {
     min_lift: 0.1,
     people_per_arm: 400,
     decision_rule: "Scale the video if sign-ups per visitor rise at least 10% with cost per sale no worse.",
-    elements: ["hero"],
+    category: "design",
+    subcategory: "hero_image",
     levers: ["clarity"],
     control: { label: "letter at the top", content: "A letter from the founder: why this webinar exists.", url: "https://example.com/signup" },
     variants: [{ label: "video at the top", content: "A 90-second video of the founder saying what the webinar covers.", url: "https://example.com/signup-video" }],
@@ -117,9 +118,9 @@ The \`weekly-loop\` playbook (\`${cli} skill install weekly-loop\` installs it a
 
 ## Trying one change: tests
 
-A test writes down one change to a page or funnel step, tried against what runs now. Each test is kept in the workspace's warehouse, in \`cro_tests\` (one row per test), \`cro_test_arms\` (its sides), \`cro_test_events\` (its history), \`cro_test_results_daily\` (each side's numbers per day) and \`cro_test_reported\` (numbers other tools counted), so you can join tests with visits, sign-ups and sales in one query: \`${cli} warehouse query "SELECT test_id, status, elements FROM cro_tests"\`.
+A test writes down one change to a page or funnel step, tried against what runs now. Each test is kept in the workspace's warehouse, in \`cro_tests\` (one row per test), \`cro_test_arms\` (its sides), \`cro_test_events\` (its history), \`cro_test_results_daily\` (each side's numbers per day) and \`cro_test_reported\` (numbers other tools counted), so you can join tests with visits, sign-ups and sales in one query: \`${cli} warehouse query "SELECT test_id, status, category, subcategory FROM cro_tests"\`.
 
-A test moves through these stages: \`idea\` (only the one change and where are needed), \`planned\` (the full plan is in and the owner said yes), \`running\` (its plan is frozen), then \`decided\`, \`abandoned\` or \`invalid\` (the tracking broke or traffic did not split as planned). Where is a funnel step (\`funnel_key\` and \`step_key\` from the funnels map), a page by its address (\`page_url\`, even one not on the map yet), or both. The full plan is: \`because\` (what led to the idea), \`audience\`, \`expected_lift\` (relative, 0.18 for 18%), \`prediction_confidence\` (low, medium or high), \`disproved_if\`, \`design_type\` (how traffic is split: ad_split_randomized, Meta's own A/B test; ad_split_duplicated, two copies of a campaign, one to each page, which is not a true random split; tool_split, inside a page builder or webinar tool named in a \`design_note\`; link_split; before_after; or adaptive), \`traffic\` (\`{campaigns, optimization_goal, note}\`: which campaigns feed it and what they optimize for, frozen with the plan), \`metric\` (step_conversion, which needs a step, sales_per_visitor, revenue_per_visitor, cost_per_sale or cost_per_lead, spend per sign-up) and \`unit\` (people or sessions), \`guardrails\` (numbers that must not get worse), \`baseline_rate\` with \`baseline_from\` and \`baseline_to\`, \`min_lift\`, \`people_per_arm\`, \`min_days\` and \`max_days\` (14 and 56 unless set), \`decision_rule\`, \`concurrent_changes\`, and the control and 1 to 3 \`variants\`, each with the exact \`content\` it shows and, when a tool runs the split, its \`platform_ref\` (the tool's own id for the side). Tags come from fixed lists: \`elements\` (what changes: headline, subheadline, hero, call_to_action, form, offer, price, guarantee, proof, urgency, page_length, layout, checkout, order_bump, follow_up, tool_or_platform, other) and \`levers\` (why it should work: clarity, relevance, trust, value, urgency, less_effort, motivation, other). \`ice_impact\`, \`ice_confidence\` and \`ice_ease\` (1 to 10) sort the idea list. \`evidence\` quotes the proof, each \`{kind, ref, note}\`, kind one of leak, lesson, customer_words, page, ad or other. A test changes one thing: a \`change\` naming two is refused.
+A test moves through these stages: \`idea\` (only the one change and where are needed), \`planned\` (the full plan is in and the owner said yes), \`running\` (its plan is frozen), then \`decided\`, \`abandoned\` or \`invalid\` (the tracking broke or traffic did not split as planned). Where is a funnel step (\`funnel_key\` and \`step_key\` from the funnels map), a page by its address (\`page_url\`, even one not on the map yet), or both. The full plan is: \`because\` (what led to the idea), \`audience\`, \`expected_lift\` (relative, 0.18 for 18%), \`prediction_confidence\` (low, medium or high), \`disproved_if\`, \`design_type\` (how traffic is split: ad_split_randomized, Meta's own A/B test; ad_split_duplicated, two copies of a campaign, one to each page, which is not a true random split; tool_split, inside a page builder or webinar tool named in a \`design_note\`; link_split; before_after; or adaptive), \`traffic\` (\`{campaigns, optimization_goal, note}\`: which campaigns feed it and what they optimize for, frozen with the plan), \`metric\` (step_conversion, which needs a step, sales_per_visitor, revenue_per_visitor, cost_per_sale or cost_per_lead, spend per sign-up) and \`unit\` (people or sessions), \`guardrails\` (numbers that must not get worse), \`baseline_rate\` with \`baseline_from\` and \`baseline_to\`, \`min_lift\`, \`people_per_arm\`, \`min_days\` and \`max_days\` (14 and 56 unless set), \`decision_rule\`, \`concurrent_changes\`, and the control and 1 to 3 \`variants\`, each with the exact \`content\` it shows and, when a tool runs the split, its \`platform_ref\` (the tool's own id for the side). What a test is mainly about is a \`category\` and its \`subcategory\`, from a fixed list: copy (headline, subheadline, body, call_to_action, bullets, story, other), offer (price, bonus, guarantee, payment_plan, order_bump, upsell, deadline_or_scarcity, other), proof (testimonials, case_study, numbers_and_results, logos_or_press, reviews, other), design (layout, hero_image, video, colors, page_length, mobile, other), form_checkout (form_fields, number_of_steps, checkout_page, other), webinar_event (length, presenter, offer_timing, replay, reminders, other), follow_up (email, text_message, thank_you_page, other), audience_traffic (who_sees_it, ad_angle, optimization_goal, other), tool_platform (webinar_platform, page_builder, checkout_tool, other), and custom, which has no subcategory. Subcategory \`other\` and category \`custom\` need a \`label\` naming what was tested, such as "exit pop-up", kept in lower case. \`also_changed\` lists anything else the test changed, each \`copy.subheadline\`, \`offer.other:<label>\` or \`custom:<label>\`. \`${cli} tests categories\` prints the list and the labels this workspace already uses: reuse one that fits before writing a new one. \`${cli} tests draft\` and \`${cli} tests edit\` take them as flags too: \`--category copy --subcategory headline --also copy.subheadline\`. \`levers\` tag why it should work, from a fixed list: clarity, relevance, trust, value, urgency, less_effort, motivation, other. \`ice_impact\`, \`ice_confidence\` and \`ice_ease\` (1 to 10) sort the idea list. \`evidence\` quotes the proof, each \`{kind, ref, note}\`, kind one of leak, lesson, customer_words, page, ad or other. A test changes one thing: a \`change\` naming two is refused.
 
 Write it as JSON, such as \`${JSON.stringify(funnelTestExample)}\`, and run \`${cli} tests draft --file test.json\`. It gets Adzara-style labels from the change and this month (\`hyp-<slug>\` and \`test-<yyyy-mm>-<slug>\`); give \`hypothesis_id\` and \`test_id\` to reuse Adzara's own, so the results of the ads Adzara published for the test (\`ad_test_results_daily\`, \`ad_hypothesis_results_daily\`) join on the same label. \`${cli} tests edit <test_id> --file changes.json\` changes some fields (null clears one). ${brand.name} shows no approval screen: ask the owner in your own session, then record the yes with \`${cli} tests plan <test_id> --approved-by "<owner>"\`, which refuses a plan with a gap and names every missing field. \`${cli} tests start <test_id>\` marks a planned test as running from today and freezes its plan; an edit after that is still saved, and its history and results say so. Starting changes nothing live: the page still goes live through its own approval, and the ads through ${brand.name}'s Meta commands. Until #2202, an ad split test can be measured only on ads Adzara made before the switch, because its sides are counted from Adzara's labels; a \`before_after\` test still works. \`${cli} tests abandon <test_id> --note "<why>"\` drops one that has not ended, \`${cli} tests invalidate <test_id> --note "<what went wrong>"\` ends a running one whose numbers cannot be trusted, and \`${cli} tests note <test_id> --note "<note>"\` adds to its history. \`${cli} tests [--status <status>] [--funnel <funnel_key>] [--limit <n>]\` lists them, newest first (50 unless \`--limit\`, at most 200), and \`${cli} tests show <test_id>\` shows one with its history.
 
@@ -591,7 +592,7 @@ ${cli} number-alerts [--since <date>]   the key numbers that swung far from norm
 ${cli} facts propose --file <fact.json>   suggest a fact for a person to confirm
 ${cli} lessons [--status active|retired] [--about ads|pages|funnel|messages|cross_channel] [--dimension <d>] | lessons add --file <lesson.json> | lessons retire <id> --note "<why>"   lessons from winners and flops, writing one, retiring one
 ${cli} tests p1   this brand's P1 test ads by verdict, judged on its own sales against its P1 thresholds, with Meta's count beside
-${cli} tests [--status <status>] [--funnel <key>] [--limit <n>] | tests show <id> | tests draft --file <test.json> | tests start <id> | tests abandon <id> [--note "<why>"] | tests results <id> | tests decide <id> --decision <d> [--note "<why>"] | tests report <id> --file <counts.json>   funnel tests, one change each
+${cli} tests [--status <status>] [--funnel <key>] [--limit <n>] | tests show <id> | tests categories | tests draft --file <test.json> | tests start <id> | tests abandon <id> [--note "<why>"] | tests results <id> | tests decide <id> --decision <d> [--note "<why>"] | tests report <id> --file <counts.json>   funnel tests, one change each
 ${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 names [--unparsed]   Meta ad names and the tags each gives; --unparsed lists those that fit no pattern
 ${cli} ads tag-formats   tag every untagged ad's format (image, video or carousel) from Meta's records, free; run it before ads autotag

package/dist/main.js

@@ -41,6 +41,7 @@ const AD_CHANGE_COLUMNS = ["platform", ...GOOGLE_ADS_CHANGE_COLUMNS];
 const SERVER_WAIT_CAP = 50;
 const REVIEW_WAIT_SECONDS = 1800;
 const PROFILE_MESSAGING_USAGE = `profile messaging [--section ${PROFILE_MESSAGING_KINDS.join("|")}] [--offer <offer key>] [--json]`;
+const TEST_CHANGE_FLAGS = '[--category <category> [--subcategory <subcategory>] [--label "<words>"]] [--also <change>]...';
 const PROFILE_ANSWERS_USAGE = "profile answers (--category <category> | --ids <id,id,...>) [--json]";
 const RULES_ADD_USAGE = 'rules add banned_claims|words_to_avoid|required_disclaimers "<text>" [--note <why>]';
 const PROFILE_CHECK_USAGE = "profile check --file ad.json | --input '<json>' | < ad.json [--json]";
@@ -3230,23 +3231,34 @@ const commands = {
             printTest(shown.test, shown.events);
         },
     },
+    "tests categories": {
+        usage: "tests categories   what a test can be about: each category and its subcategories, and the labels this workspace's tests already use",
+        async run(args, options) {
+            if (args.length > 0)
+                throw new CliError("Usage: tests categories", exitCodes.usage);
+            const list = await api(await resolveConnection(options), `${TESTS_PATH}/categories`);
+            if (options.format === "json")
+                return printJson(list);
+            printTestCategories(list);
+        },
+    },
     "tests draft": {
-        usage: "tests draft --file <test.json> | < test.json   write down a test idea: the one change and where (a funnel step or a page); the rest of the plan may come later with tests edit",
+        usage: `tests draft --file <test.json> | < test.json ${TEST_CHANGE_FLAGS}   write down a test idea: the one change and where (a funnel step or a page); the rest of the plan may come later with tests edit`,
         async run(args, options) {
             if (args.length > 0)
-                throw new CliError("Usage: tests draft --file <test.json> | < test.json", exitCodes.usage);
-            const { test } = await api(await resolveConnection(options), TESTS_PATH, await readToolInput(options));
+                throw new CliError(`Usage: tests draft --file <test.json> | < test.json ${TEST_CHANGE_FLAGS}`, exitCodes.usage);
+            const { test } = await api(await resolveConnection(options), TESTS_PATH, withTestChange(await readToolInput(options), options));
             if (options.format === "json")
                 return printJson({ test });
             console.log(`Wrote down test ${test.test_id} as an idea.`);
         },
     },
     "tests edit": {
-        usage: "tests edit <test_id> --file <changes.json> | < changes.json   change some of a test's fields (null clears one); a change to the plan after the start is kept and marked in its history",
+        usage: `tests edit <test_id> [--file <changes.json> | < changes.json] ${TEST_CHANGE_FLAGS}   change some of a test's fields (null clears one); a change to the plan after the start is kept and marked in its history`,
         async run(args, options) {
             if (args.length !== 1)
-                throw new CliError("Usage: tests edit <test_id> --file <changes.json> | < changes.json", exitCodes.usage);
-            const { test } = await api(await resolveConnection(options), testPath(args[0]), await readToolInput(options), "PATCH");
+                throw new CliError(`Usage: tests edit <test_id> [--file <changes.json> | < changes.json] ${TEST_CHANGE_FLAGS}`, exitCodes.usage);
+            const { test } = await api(await resolveConnection(options), testPath(args[0]), withTestChange(await readToolInput(options), options), "PATCH");
             if (options.format === "json")
                 return printJson({ test });
             console.log(`Changed test ${test.test_id} (${test.status}).`);
@@ -4810,6 +4822,27 @@ const VOICE_SUGGESTIONS_PATH = "/api/v1/voice-lists/suggestions";
 const LESSONS_PATH = "/api/v1/lessons";
 const TESTS_PATH = "/api/v1/funnel-tests";
 const TEST_COLUMNS = ["test_id", "status", "where", "change", "metric"];
+/** The test body with the change flags on top: --category, --subcategory and --label give the main change, each --also one more. */
+function withTestChange(body, options) {
+    const flags = {
+        ...(options.category === undefined ? {} : { category: options.category }),
+        ...(options.subcategory === undefined ? {} : { subcategory: options.subcategory }),
+        ...(options.label === undefined ? {} : { label: options.label }),
+        ...(options.also === undefined ? {} : { also_changed: options.also }),
+    };
+    if (Object.keys(flags).length === 0)
+        return body;
+    if (body === null || typeof body !== "object" || Array.isArray(body))
+        throw new CliError("The test file must hold a JSON object to add --category, --subcategory, --label or --also to.", exitCodes.usage);
+    return { ...body, ...flags };
+}
+/** A change as the API returns it, written as also_changed takes it: copy.headline, offer.other:<label> or custom:<label>. */
+const changeText = (c) => (c.category === "custom" ? `custom:${c.label}` : c.label === undefined ? `${c.category}.${c.subcategory}` : `${c.category}.other:${c.label}`);
+function printTestCategories(list) {
+    const lines = list.categories.map((c) => `${c.category} (${c.words}): ${c.subcategories.map((s) => (s.words === s.subcategory.replaceAll("_", " ") ? s.subcategory : `${s.subcategory} (${s.words})`)).join(", ") || "no subcategories; give --label"}`);
+    console.log(lines.join("\n"));
+    console.log(list.labels.length === 0 ? "\nNo labels used yet." : `\nLabels already used (reuse one that fits):\n${renderTable(["category", "label", "tests"], list.labels)}`);
+}
 const testPath = (ref) => `${TESTS_PATH}/${encodeURIComponent(ref)}`;
 function testRow(t) {
     return { test_id: t.test_id, status: t.status, where: testWhere(t), change: excerpt(t.change, 50), metric: t.metric ?? "" };
@@ -4849,7 +4882,9 @@ function printTest(t, events) {
         ...line("Decision rule", t.decision_rule),
         ...line("Also changing", t.concurrent_changes),
         ...line("Traffic", t.traffic && [t.traffic.campaigns?.length && `campaigns ${t.traffic.campaigns.join(", ")}`, t.traffic.optimization_goal && `optimized for ${t.traffic.optimization_goal}`, t.traffic.note].filter(Boolean).join("; ")),
-        ...line("Tags", [...t.elements, ...t.levers].join(", ")),
+        ...line("Category", t.main_change && changeText(t.main_change)),
+        ...line("The test also changes", t.also_changed.map(changeText).join(", ")),
+        ...line("Tags", t.levers.join(", ")),
         ...line("ICE", t.ice_impact !== null || t.ice_confidence !== null || t.ice_ease !== null ? `${t.ice_impact ?? "-"} / ${t.ice_confidence ?? "-"} / ${t.ice_ease ?? "-"}` : null),
         ...(t.evidence.length > 0 ? ["Evidence:", ...t.evidence.map((e) => `  ${e.kind}: ${e.ref}${e.note ? ` (${e.note})` : ""}`)] : []),
         ...line("Started", t.started_on && `${t.started_on}${t.ended_on ? `, ended ${t.ended_on}` : ""}`),
@@ -5338,6 +5373,11 @@ Options:
   --approved-by <name>  tests plan: who said yes to the test's plan, as the owner gave their name in your session
   --outcome <o>         tests decide: what the test found, won, lost, inconclusive or invalid; needed with scale, iterate and stop
   --learning <text>     tests decide: what the test taught, in a sentence, kept on the test
+  --category <c>        tests draft and edit: what the test is mainly about, such as copy (tests categories lists them)
+  --subcategory <s>     tests draft and edit: the part of the category it changes, such as headline
+  --label <words>       tests draft and edit: for subcategory other or category custom, what was tested, such as "exit pop-up"
+  --also <change>       tests draft and edit: something else the test changed, such as copy.subheadline,
+                        offer.other:<label> or custom:<label>; repeat for several
   --about <a>           with lessons, only the lessons with a proof about ads, pages, funnel (steps and tests) or messages
                         (emails, texts and sequences), or cross_channel: proven on two or more of ads, pages and messages
   --dimension <d>       with lessons, only the lessons along that dimension (hook, angle, format, offer, persona, page, funnel_step, follow_up, other); repeat for several
@@ -5625,6 +5665,8 @@ function parseOptions(argv) {
             awareness: { type: "string" },
             confidence: { type: "string" },
             category: { type: "string" },
+            subcategory: { type: "string" },
+            also: { type: "string", multiple: true },
             ids: { type: "string" },
             section: { type: "string" },
             offer: { type: "string" },
@@ -5854,6 +5896,8 @@ function parseOptions(argv) {
             entryTags: Object.fromEntries(Object.entries(entryTagFlags).flatMap(([field, flag]) => (values[flag] === undefined ? [] : [[field, values[flag]]]))),
             confidence: values.confidence,
             category: values.category,
+            subcategory: values.subcategory,
+            also: values.also,
             ids: values.ids,
             section: values.section,
             offer: values.offer,

package/dist/map.js

@@ -83,8 +83,20 @@ export function renderQuestions(map) {
     const note = unmeasured ? ["  Worked out from the nightly counts, so every question shows as not yet until the first nightly run."] : [];
     return `${["Questions", ...note, ...map.questions.flatMap(questionLines)].join("\n")}\n`;
 }
+/** Wrangled's own tables and views, grouped by owner, one line each with its kinds. */
+export function renderOwn(own) {
+    const lines = [`${brand.name}'s own data (not counted yet)`];
+    own.forEach((row, i) => {
+        if (row.owner !== own[i - 1]?.owner)
+            lines.push(`  ${row.owner}`);
+        lines.push(`    ${row.table}   ${row.kinds.join(", ")}`);
+    });
+    return `${lines.join("\n")}\n`;
+}
 export function renderDataMap(map) {
+    // A server from before the own section sends none.
+    const own = map.own?.length ? [renderOwn(map.own)] : [];
     if (map.sources.length === 0)
-        return "No sources connected.\n";
-    return `${map.sources.map((source) => sourceLines(source).join("\n")).join("\n\n")}\n\n${renderQuestions(map)}`;
+        return ["No sources connected.\n", ...own].join("\n");
+    return [`${map.sources.map((source) => sourceLines(source).join("\n")).join("\n\n")}\n`, ...own, renderQuestions(map)].join("\n");
 }

package/dist/playbooks.js

@@ -2017,7 +2017,8 @@ export const croTestExample = {
     min_lift: 0.1,
     people_per_arm: 300,
     decision_rule: "Keep the text if attendance rises at least 10% with unsubscribes no higher.",
-    elements: ["follow_up"],
+    category: "follow_up",
+    subcategory: "text_message",
     levers: ["urgency"],
     control: { label: "today's reminders: an email the day before and an hour before", content: "Email the day before and an hour before; no text." },
     variants: [{ label: "the same reminders plus a text 15 minutes before", content: "We're live in 15 minutes: {link}" }],
@@ -2082,7 +2083,7 @@ ${JSON.stringify(croTestExample)}
 - \`control\` is what runs now; \`variants\` is the changed version, each \`{label, content, page?, url?, item_id?, asset_version?}\`. \`content\` is the exact words or change each side shows.
 - \`metric\` is the number that should move: \`step_conversion\` (only with a \`step_key\`), \`sales_per_visitor\`, \`revenue_per_visitor\`, \`cost_per_sale\` or \`cost_per_lead\` (spend per sign-up), counted by \`unit\` (people or sessions). \`baseline_rate\` is today's rate over \`baseline_from\` to \`baseline_to\`, \`min_lift\` the smallest lift worth finding, \`people_per_arm\` how many each side needs, \`guardrails\` the numbers that must not get worse, and \`decision_rule\` how you will call it. \`min_days\` and \`max_days\` are 14 and 56 unless set.
 - \`design_type\` is how traffic is split: \`ad_split_randomized\` (Meta's own A/B test), \`ad_split_duplicated\` (two copies of a campaign, one to each page; not a true random split), \`tool_split\` (inside a page builder or webinar tool, named in \`design_note\`), \`link_split\`, \`before_after\` or \`adaptive\`. \`traffic\` says which campaigns feed it and what they optimize for. Until #2202, an ad split test is counted only from Adzara's labels, so it can be measured only on ads Adzara made before the switch; for a new test, use \`before_after\`.
-- \`elements\` and \`levers\` tag what changes and why it should work, from \`${cli} guide\`'s fixed lists.
+- \`category\` and \`subcategory\` say what the test is mainly about, and \`also_changed\` anything else it changed: run \`${cli} tests categories\` for the lists and the labels already used, and reuse a label before writing a new one. \`levers\` tag why it should work, from \`${cli} guide\`'s fixed list.
 - \`evidence\` quotes the proof, each \`{kind, ref, note}\` with kind \`leak\`, \`lesson\`, \`customer_words\`, \`page\`, \`ad\` or \`other\`. Start with the leak itself.
 - Give \`hypothesis_id\` and \`test_id\` only to reuse Adzara's own labels; left out, they are made for you.
 

package/package.json

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