@wrangled/cli 0.3.32 → 0.3.33

package/dist/guide.js

@@ -3,6 +3,20 @@ import { brand, envPrefix } from "./brand.js";
 import { BACK_TAG_SKILL_NAME, GRAMMAR_SKILL_NAME, LEARN_NAMES_SKILL_NAME, LESSONS_SKILL_NAME, MAP_OFFERS_SKILL_NAME, PLAYBOOK_CHOICES, STORY_SKILL_NAME } from "./playbooks.js";
 import { PULL_STATE_FILE } from "./pull.js";
 const cli = brand.slug;
+/** The funnel test the guide shows; the app's parser must accept it (src/lib/cli-consistency.test.ts). */
+export const funnelTestExample = {
+    hypothesis: "A video at the top of the sign-up page will get more people to sign up, because buyers on calls say they did not know what the webinar was about.",
+    funnel_key: "webinar",
+    step_key: "signup",
+    variable: "top of the page: letter to video",
+    control: { label: "letter at the top", url: "https://example.com/signup" },
+    variants: [{ label: "video at the top", url: "https://example.com/signup-video" }],
+    metric: "step_conversion",
+    expected_change: "sign-ups per visitor from 22% to 26%",
+    min_people_per_arm: 400,
+    split_method: "adzara_ads",
+    evidence: [{ kind: "customer_words", ref: "sales call 2026-09-30", note: "I didn't know what the webinar was about." }],
+};
 export const guide = `# ${brand.name} CLI
 
 \`${cli}\` gives read-only SQL access to one client's marketing data warehouse (ad spend, orders, and other synced sources), runs paid generation and research tools for that client, and keeps the creative ledger. Each API key belongs to exactly one workspace, and every command works only in that workspace.
@@ -38,6 +52,12 @@ Write one as JSON, \`{"text": "...", "dimension": "hook", "evidence": [{"ad": "<
 
 \`${cli} winners send-to-exodus\` sends the week's winners to Exodus so it makes new ads from them: one package per Facebook page, each winner with its reason, its numbers, and a note of the lessons it proves, persona lessons and the week's freshest customer words. Winners whose page, words or format are unknown are left out and listed with why. \`--week <YYYY-MM-DD>\` picks the week (default: the latest complete week). \`--dry-run\` asks Exodus what it would create or update and writes nothing. Sending the same week again is safe: an unchanged package is not sent twice, and Exodus updates each ad in place. A real send needs the workspace's Exodus brand and a Scrape Creators key on the Exodus account.
 
+## Trying one change: funnel tests
+
+A funnel test writes down one change to a page or funnel step, tried against what runs now: the idea, the funnel and step (\`funnel_key\` and \`step_key\` from the funnels map), the one thing that changes, the control and 1 to 3 changed versions, the number that judges it (\`metric\`: step_conversion, sales_per_visitor, revenue_per_visitor or cost_per_sale) with the change expected and the people each side needs, how traffic is split (\`split_method\`: adzara_ads, before_after, or other with a \`split_note\`), and the evidence it should work (each \`{kind, ref, note}\`, kind one of leak, lesson, customer_words, page, ad or other). A test changes one thing: a \`variable\` naming two is refused, and so is a test with no metric.
+
+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 publishes for the test (\`ad_test_results_daily\`, \`ad_hypothesis_results_daily\`) join on the same label. Approving a test happens outside ${brand.name} for now. \`${cli} tests start <test_id>\` marks a draft as running from today, and changes nothing live: the page still goes live through its own approval, and the ads through Adzara. \`${cli} tests abandon <test_id> --note "<why>"\` drops a draft or running test. \`${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.
+
 ## Content: search before SQL
 
 To find content, such as "the 10 emails with the best click rate", "our 5 best videos by return on ad spend" or "every landing page that mentions the guarantee", use \`${cli} content search\` before writing SQL on the \`content_\` tables.
@@ -325,6 +345,7 @@ ${cli} funnels draft --file <map.json> [--note <why>] [--evidence '<json>' | @fi
 ${cli} facts [--kind <kind>] [--subject <type>[:<ref>]] [--status <status>] [--json] | facts show <id>   settled facts about the data, to treat as true
 ${cli} facts propose --file <fact.json>   suggest a fact for a person to confirm
 ${cli} lessons [--status active|retired] | lessons add --file <lesson.json> | lessons retire <id> --note "<why>"   lessons from winners and flops, writing one, retiring one
+${cli} tests [--status <status>] [--funnel <key>] [--limit <n>] | tests show <id> | tests draft --file <test.json> | tests start <id> | tests abandon <id> [--note "<why>"]   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 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

package/dist/main.js

@@ -1431,6 +1431,70 @@ const commands = {
                     : `Lesson ${lesson.id} already counted this week (${weeks}); its proof was updated.`);
         },
     },
+    tests: {
+        usage: "tests [list] [--status <status>] [--funnel <funnel_key>] [--limit <n>]   the page and funnel tests written down, newest first (50 unless --limit, at most 200)",
+        async run(args, options) {
+            if (!(args.length === 0 || (args.length === 1 && args[0] === "list")))
+                throw new CliError("Usage: tests [list] [--status <status>] [--funnel <funnel_key>] [--limit <n>]", exitCodes.usage);
+            const query = new URLSearchParams();
+            if (options.status)
+                query.set("status", options.status);
+            if (options.funnel)
+                query.set("funnel", options.funnel);
+            if (options.limit)
+                query.set("limit", options.limit);
+            const { tests } = await api(await resolveConnection(options.apiUrl), `${TESTS_PATH}${query.size ? `?${query}` : ""}`);
+            if (options.format === "json")
+                return printJson({ tests });
+            if (tests.length === 0)
+                return console.log("No funnel tests.");
+            console.log(renderTable(TEST_COLUMNS, tests.map(testRow)));
+        },
+    },
+    "tests show": {
+        usage: "tests show <id|test_id>   one funnel test in full",
+        async run(args, options) {
+            if (args.length !== 1)
+                throw new CliError("Usage: tests show <id|test_id>", exitCodes.usage);
+            const { test } = await api(await resolveConnection(options.apiUrl), testPath(args[0]));
+            if (options.format === "json")
+                return printJson({ test });
+            printTest(test);
+        },
+    },
+    "tests draft": {
+        usage: "tests draft --file <test.json> | < test.json   write down a funnel test: one change against a control, a metric and the evidence",
+        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.apiUrl), TESTS_PATH, await readToolInput(options));
+            if (options.format === "json")
+                return printJson({ test });
+            console.log(`Drafted test ${test.test_id} (${test.id}).`);
+        },
+    },
+    "tests start": {
+        usage: "tests start <id|test_id>   mark a draft test as running from today; nothing goes live",
+        async run(args, options) {
+            if (args.length !== 1)
+                throw new CliError("Usage: tests start <id|test_id>", exitCodes.usage);
+            const { test } = await api(await resolveConnection(options.apiUrl), `${testPath(args[0])}/start`, {});
+            if (options.format === "json")
+                return printJson({ test });
+            console.log(`Test ${test.test_id} is running from ${test.started_on}.`);
+        },
+    },
+    "tests abandon": {
+        usage: 'tests abandon <id|test_id> [--note "<why>"]   drop a test that has not ended',
+        async run(args, options) {
+            if (args.length !== 1)
+                throw new CliError('Usage: tests abandon <id|test_id> [--note "<why>"]', exitCodes.usage);
+            const { test } = await api(await resolveConnection(options.apiUrl), `${testPath(args[0])}/abandon`, options.note ? { note: options.note } : {});
+            if (options.format === "json")
+                return printJson({ test });
+            console.log(`Abandoned test ${test.test_id}.`);
+        },
+    },
     "lessons retire": {
         usage: 'lessons retire <id> --note "<why it is no longer true>"   retire a lesson the numbers no longer back; it is kept with why',
         async run(args, options) {
@@ -2065,6 +2129,32 @@ const GRAMMAR_PATH = "/api/v1/grammar";
 const VOICE_LISTS_PATH = "/api/v1/voice-lists";
 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", "funnel", "step", "change", "metric"];
+const testPath = (ref) => `${TESTS_PATH}/${encodeURIComponent(ref)}`;
+function testRow(t) {
+    return { test_id: t.test_id, status: t.status, funnel: t.funnel_key, step: t.step_key, change: excerpt(t.variable, 50), metric: t.metric };
+}
+function printTest(t) {
+    const arm = (a) => [a.label, a.page && `page ${a.page}`, a.url, a.item_id && `item ${a.item_id}`, a.asset_version && `version ${a.asset_version}`].filter(Boolean).join(" · ");
+    const lines = [
+        `${t.test_id} (${t.status})   idea ${t.hypothesis_id}   id ${t.id}`,
+        `Idea: ${t.hypothesis}`,
+        `Where: ${t.funnel_key} / ${t.step_key}`,
+        `The one change: ${t.variable}`,
+        `Stays the same: ${arm(t.control)}`,
+        ...t.variants.map((v, i) => `${t.variants.length === 1 ? "Changed" : `Changed ${i + 1}`}: ${arm(v)}`),
+        `Judged by: ${t.metric}, ${t.expected_change}, ${t.min_people_per_arm} people each side`,
+        `Split: ${t.split_method}${t.split_note ? `, ${t.split_note}` : ""}`,
+        "Evidence:",
+        ...t.evidence.map((e) => `  ${e.kind}: ${e.ref}${e.note ? ` (${e.note})` : ""}`),
+    ];
+    if (t.started_on)
+        lines.push(`Started: ${t.started_on}${t.ended_on ? `, ended ${t.ended_on}` : ""}`);
+    if (t.decision_note)
+        lines.push(`Note: ${t.decision_note}`);
+    console.log(lines.join("\n"));
+}
 const LESSON_COLUMNS = ["id", "seen", "last week", "dimension", "lesson"];
 function lessonRow(l) {
     const row = { id: l.id, seen: l.timesSeen, "last week": l.lastSeenWeek, dimension: l.dimension ?? "", lesson: excerpt(l.text, 100) };
@@ -2223,7 +2313,8 @@ Options:
   --object-type <type>  what that platform's sync calls it (campaign_message or flow_message on klaviyo); needed where
                         the sync matches several kinds, so its next read joins the item
   --notes <text>        what changed in the version skill publish adds
-  --note <why>          why: what content create and edit changed, or why lessons retire says a lesson is no longer true
+  --note <why>          why: what content create and edit changed, why lessons retire says a lesson is no longer true,
+                        or why tests abandon drops one
   --version <n>         the map version funnels show prints (default: the confirmed one)
   --based-on <n>        the map version funnels draft was written from; refused when someone saved since
                         (leave it out only for the first map, when there is neither a map nor a draft)

package/package.json

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