@solidnumber/cli 2.15.1 → 2.17.0

package/dist/commands/forms.js

@@ -47,6 +47,7 @@ const chalk_1 = __importDefault(require("chalk"));
 const config_1 = require("../lib/config");
 const api_client_1 = require("../lib/api-client");
 const json_output_1 = require("../lib/json-output");
+const json_arg_1 = require("../lib/json-arg");
 function requireAuth() {
     if (!config_1.config.isLoggedIn()) {
         console.error(chalk_1.default.red('Not logged in. Run `solid auth login` first.'));
@@ -58,31 +59,54 @@ exports.formsCommand = new commander_1.Command('forms')
     .alias('surveys')
     .description('Forms & surveys — CRUD, AI generate, export CSV/Excel/PDF');
 {
-    const { withListFlags } = require('../lib/command-kit');
-    const listCmd = exports.formsCommand.command('list').alias('ls').description('List forms/surveys');
-    withListFlags(listCmd);
+    // ⛔ `list` GOES THROUGH VERBS. It used to read /api/v1/surveys directly, so it
+    // showed a different set than `solid forms status` (no lifecycle, native only,
+    // and blind to lead forms). Two commands in one CLI disagreeing about what
+    // forms exist is worse than either being wrong. One seam, one answer.
+    const listCmd = exports.formsCommand.command('list').alias('ls')
+        .description('Every form, with its lifecycle — across every connected provider');
+    listCmd.option('--provider <name>', 'Only this provider');
+    listCmd.option('--json', 'Output as JSON');
     listCmd.action(async (opts) => {
-        const { runListCommand } = await Promise.resolve().then(() => __importStar(require('../lib/command-kit')));
-        await runListCommand(opts, {
-            spinnerText: 'Loading forms...',
-            errorText: 'Failed to load forms',
-            fetch: async (offset, limit) => (await api_client_1.apiClient.get('/api/v1/surveys', { params: { limit, offset } })).data,
-            extract: (page) => {
-                if (Array.isArray(page))
-                    return page;
-                const d = page;
-                return (d.surveys || d.items || []);
-            },
-            render: (items) => {
-                if (!items.length) {
-                    console.log(chalk_1.default.dim('  No forms yet.'));
-                    return;
+        requireAuth();
+        const s2 = (0, ora_1.default)('Loading forms...').start();
+        try {
+            const providers = opts.provider
+                ? [opts.provider]
+                : ((await callVerb('form.sources')).connected ?? [])
+                    .map((c) => String(c.provider));
+            const rows = [];
+            for (const provider of providers.length ? providers : ['native']) {
+                try {
+                    const out = await callVerb('form.list', { provider });
+                    for (const f of (out.forms ?? [])) {
+                        rows.push({ ...f, provider });
+                    }
                 }
-                for (const f of items) {
-                    console.log(`  ${chalk_1.default.bold(String(f.id))}  ${f.title || f.name}  ${chalk_1.default.dim(String(f.created_at || '').split('T')[0])}`);
-                }
-            },
-        });
+                catch { /* one provider down must not blank the list */ }
+            }
+            if ((0, json_output_1.isJsonOutput)(opts)) {
+                s2.stop();
+                console.log(JSON.stringify({ forms: rows }, null, 2));
+                return;
+            }
+            s2.stop();
+            if (!rows.length) {
+                console.log(chalk_1.default.dim('  No forms yet.'));
+                console.log(chalk_1.default.dim('  Build one:  solid forms build --intent intake --save'));
+                return;
+            }
+            for (const f of rows) {
+                const state = lifecycleOf(f);
+                const answered = Number(f.response_count ?? 0);
+                console.log(`  ${chalk_1.default.bold(String(f.external_id).padEnd(5))} ${lifecycleTag(state).padEnd(16)} ` +
+                    `${String(f.title ?? '').slice(0, 34).padEnd(34)} ` +
+                    `${chalk_1.default.dim(`${answered} answered`)} ${chalk_1.default.dim(String(f.provider))}`);
+            }
+        }
+        catch (e) {
+            fail(s2, 'Failed to load forms', e);
+        }
     });
 }
 exports.formsCommand
@@ -93,17 +117,15 @@ exports.formsCommand
     requireAuth();
     const s = (0, ora_1.default)(`Loading ${id}...`).start();
     try {
-        const res = await api_client_1.apiClient.get(`/api/v1/surveys/${id}`);
-        if ((0, json_output_1.isJsonOutput)(opts)) {
-            s.stop();
-            console.log(JSON.stringify(res.data, null, 2));
-            return;
-        }
-        s.succeed(chalk_1.default.green(`Form ${id}`));
-        console.log(JSON.stringify(res.data, null, 2));
+        // Through the verb, so `get` and `describe` can never disagree about a
+        // form. The verb also carries the lifecycle and the public link, which
+        // /api/v1/surveys/<id> knows nothing about.
+        const out = await callVerb('form.describe', { form_id: String(id), provider: 'native' });
+        s.stop();
+        console.log(JSON.stringify(out, null, 2));
     }
     catch (e) {
-        fail(s, 'Failed', e);
+        fail(s, 'Failed to load the form', e);
     }
 });
 exports.formsCommand
@@ -122,13 +144,37 @@ exports.formsCommand
     }
     const s = (0, ora_1.default)('Creating form...').start();
     try {
-        const res = await api_client_1.apiClient.post('/api/v1/surveys/create', body);
-        s.succeed(chalk_1.default.green(`Form created: ${res.data.id}`));
+        const out = await callVerbConfirmed('survey.create', {
+            title: body.title,
+            questions: body.questions ?? body.fields ?? [],
+            ...(body.description ? { description: body.description } : {}),
+        });
+        if (out.status === 'error' || out.status === 'invalid') {
+            s.fail(chalk_1.default.red(String(out.summary ?? 'Could not create it')));
+            process.exitCode = 1;
+            return;
+        }
+        s.succeed(chalk_1.default.green(`Form created: ${out.survey_id ?? out.id ?? ''}`));
+        console.log(chalk_1.default.dim('  It starts as a draft. Publish when ready:'));
+        console.log(chalk_1.default.dim(`    solid forms publish ${out.survey_id ?? out.id ?? '<id>'}`));
     }
     catch (e) {
-        fail(s, 'Failed', e);
+        fail(s, 'Failed to create the form', e);
     }
 });
+// ⛔ WHAT IS STILL ON REST, AND WHY — checked 2026-08-26, not assumed.
+//
+//   update / delete   no survey.update or survey.delete verb exists. Inventing
+//                     a CLI-only path to a destructive operation is worse than
+//                     an honest REST call; these move when the verbs do.
+//   export            no verb — it streams a file (csv/excel/pdf), which the
+//                     JSON verb envelope has no shape for.
+//   followup          /surveys/<id>/followup drafts follow-ups to RESPONSES.
+//                     review.followup is a different thing entirely (it takes a
+//                     rating and drafts a REVIEW reply), so routing one to the
+//                     other would silently change what the command does.
+//
+// Everything else in this file goes through the verb layer.
 exports.formsCommand
     .command('update <id>')
     .description('Update a form')
@@ -173,46 +219,68 @@ exports.formsCommand
     requireAuth();
     const s = (0, ora_1.default)('Generating form...').start();
     try {
-        const res = await api_client_1.apiClient.post('/api/v1/surveys/generate', { prompt });
-        s.succeed(chalk_1.default.green(`Form generated: ${res.data.id}`));
+        const out = await callVerbConfirmed('survey.generate', { prompt });
+        if (out.status === 'error' || out.status === 'invalid') {
+            s.fail(chalk_1.default.red(String(out.summary ?? 'Could not generate it')));
+            process.exitCode = 1;
+            return;
+        }
+        s.succeed(chalk_1.default.green(`Form generated: ${out.survey_id ?? out.id ?? ''}`));
+        console.log(chalk_1.default.dim('  Read it before publishing:  solid forms describe '
+            + String(out.survey_id ?? out.id ?? '<id>')));
     }
     catch (e) {
-        fail(s, 'Failed', e);
+        fail(s, 'Failed to generate the form', e);
     }
 });
 exports.formsCommand
     .command('optimize <id>')
-    .description('AI-optimize an existing form (shorter, better copy)')
-    .action(async (id) => {
+    .description('ADA reviews the questions — suggestions only, nothing changes')
+    .option('--json', 'Output as JSON')
+    .action(async (id, opts) => {
     requireAuth();
-    const s = (0, ora_1.default)('Optimizing...').start();
+    const sp = (0, ora_1.default)('Looking it over...').start();
     try {
-        await api_client_1.apiClient.post(`/api/v1/surveys/${id}/optimize`);
-        s.succeed(chalk_1.default.green('Optimized'));
+        const out = await callVerb('survey.optimize', { survey_id: Number(id) });
+        if ((0, json_output_1.isJsonOutput)(opts)) {
+            sp.stop();
+            console.log(JSON.stringify(out, null, 2));
+            return;
+        }
+        sp.stop();
+        const analysis = (out.analysis ?? {});
+        const suggestions = (analysis.suggested_improvements ?? []);
+        if (!suggestions.length) {
+            console.log(chalk_1.default.dim('  Nothing to change — it reads well.'));
+            return;
+        }
+        console.log(chalk_1.default.dim('  Suggestions only — nothing changes until you change it.'));
+        for (const sg of suggestions) {
+            console.log(`  ${chalk_1.default.yellow('*')} ${sg.issue}`);
+            if (sg.fix)
+                console.log(`      ${chalk_1.default.dim('fix:')} ${sg.fix}`);
+            if (sg.impact)
+                console.log(`      ${chalk_1.default.dim('why:')} ${sg.impact}`);
+        }
     }
     catch (e) {
-        fail(s, 'Failed', e);
+        fail(sp, 'Failed to look it over', e);
     }
 });
 exports.formsCommand
     .command('analyze <id>')
-    .description('AI analyze submissions for insights')
+    .description('What the answers add up to')
     .option('--json', 'Output as JSON')
-    .action(async (id, opts) => {
+    .action(async (id) => {
     requireAuth();
-    const s = (0, ora_1.default)('Analyzing...').start();
+    const sp = (0, ora_1.default)('Analyzing...').start();
     try {
-        const res = await api_client_1.apiClient.post(`/api/v1/surveys/${id}/analyze`);
-        if ((0, json_output_1.isJsonOutput)(opts)) {
-            s.stop();
-            console.log(JSON.stringify(res.data, null, 2));
-            return;
-        }
-        s.succeed(chalk_1.default.green('Analysis'));
-        console.log(JSON.stringify(res.data, null, 2));
+        const out = await callVerb('survey.analyze', { survey_id: Number(id) });
+        sp.stop();
+        console.log(JSON.stringify(out, null, 2));
     }
     catch (e) {
-        fail(s, 'Failed', e);
+        fail(sp, 'Failed to analyze', e);
     }
 });
 exports.formsCommand
@@ -232,17 +300,47 @@ exports.formsCommand
 });
 exports.formsCommand
     .command('embed <id>')
-    .description('Get embed code / public link for a form')
-    .action(async (id) => {
+    .description('Paste-ready embed for a live form — iframe, link, or button')
+    .option('--provider <name>', 'Form provider', 'native')
+    .option('--as <kind>', 'iframe | link | button', 'iframe')
+    .action(async (id, opts) => {
     requireAuth();
-    const s = (0, ora_1.default)('Loading embed...').start();
+    // ⛔ THE DOOR, NOT THE LEGACY LINK. This read /api/v1/surveys/<id>/embed —
+    // the pre-lifecycle system's public URL — so after the standing door shipped
+    // (2026-08-20) `solid forms embed` was handing out the OLD address while
+    // `solid forms link` handed out the new one. Two commands, two answers, one
+    // of them wrong.
+    const sp = (0, ora_1.default)('Building the embed...').start();
+    let out;
     try {
-        const res = await api_client_1.apiClient.get(`/api/v1/surveys/${id}/embed`);
-        s.succeed(chalk_1.default.green('Embed'));
-        console.log(JSON.stringify(res.data, null, 2));
+        out = await callVerb('form.describe', { form_id: String(id), provider: opts.provider });
     }
     catch (e) {
-        fail(s, 'Failed', e);
+        fail(sp, 'Failed to build the embed', e);
+        return;
+    }
+    const url = out.public_url ?? out.public_path;
+    if (!url) {
+        sp.fail(chalk_1.default.yellow(`No public address — this form is ${String(out.lifecycle ?? 'not live')}.`));
+        console.error(chalk_1.default.dim('  Only a live form can be embedded. Publish it first:'));
+        console.error(chalk_1.default.dim(`    solid forms publish ${id}`));
+        process.exitCode = 1;
+        return;
+    }
+    sp.stop();
+    const title = String(out.title ?? 'Form');
+    const kind = String(opts.as).toLowerCase();
+    if (kind === 'link') {
+        console.log(`<a href="${url}">${title}</a>`);
+    }
+    else if (kind === 'button') {
+        console.log(`<a href="${url}" style="display:inline-block;padding:12px 20px;border-radius:8px;` +
+            `background:#0f5346;color:#fff;text-decoration:none;font-weight:600">${title}</a>`);
+    }
+    else {
+        console.log(`<!-- ${title} — answers land in your CRM -->\n` +
+            `<iframe src="${url}" title="${title}" width="100%" height="640" ` +
+            `style="border:0;border-radius:12px" loading="lazy"></iframe>`);
     }
 });
 exports.formsCommand
@@ -274,11 +372,675 @@ exports.formsCommand
         fail(s, 'Failed', e);
     }
 });
+// ── the verb seam ──────────────────────────────────────────────────────────
+//
+// ⛔ EVERYTHING BELOW CALLS VERBS, NOT REST. The commands above this line wrap
+// /api/v1/surveys — the authoring endpoints that predate the forms platform —
+// and they are why `solid forms` knew nothing about the lifecycle, the
+// respondent-facing reads, or a form's public address. New work goes through
+// the verb layer so the CLI, the dashboard, MCP and an agent on a live call
+// all get the same validation, consent and tenant scoping.
+//
+// ⛔ NEVER SEND company_id. The backend binds the tenant from the authenticated
+// principal; a CLI that could pass one is a CLI that could pass someone else's.
+async function callVerb(name, payload = {}) {
+    // ⛔ ONLY THE VERB IS HYPHENATED, NEVER THE NAMESPACE. The backend routes
+    // `<ns>/<verb-with-hyphens>` (controllers/agent_verb_index.py::_verb_http_endpoint),
+    // and plenty of namespaces carry underscores — call_flow, comms_workflow,
+    // agent_config. Hyphenating the whole name would 404 every one of them.
+    const [ns, ...rest] = name.split('.');
+    const verb = rest.join('.').replace(/_/g, '-');
+    const endpoint = verb ? `/api/v1/agent/${ns}/${verb}` : `/api/v1/agent/${ns}`;
+    const res = await api_client_1.apiClient.post(endpoint, payload);
+    const body = res.data;
+    // The envelope is {ok, result} on some surfaces and the bare result on others.
+    return (body && typeof body === 'object' && 'result' in body ? body.result : body);
+}
+/** A write verb. Consent travels as `confirm: true` — the backend refuses without it. */
+async function callVerbConfirmed(name, payload = {}) {
+    return callVerb(name, { ...payload, confirm: true });
+}
+function lifecycleOf(f) {
+    if ((f.status ?? 'published') === 'draft')
+        return 'draft';
+    return f.is_active === false ? 'paused' : 'live';
+}
+function lifecycleTag(state) {
+    return state === 'live' ? chalk_1.default.green('live')
+        : state === 'draft' ? chalk_1.default.yellow('draft')
+            : chalk_1.default.dim('paused');
+}
+exports.formsCommand
+    .command('describe <id>')
+    .description('The questions as a respondent meets them, plus lifecycle + public link')
+    .option('--provider <name>', 'Form provider', 'native')
+    .option('--json', 'Output as JSON')
+    .action(async (id, opts) => {
+    requireAuth();
+    const s = (0, ora_1.default)(`Reading ${id}...`).start();
+    try {
+        const out = await callVerb('form.describe', { form_id: String(id), provider: opts.provider });
+        if ((0, json_output_1.isJsonOutput)(opts)) {
+            s.stop();
+            console.log(JSON.stringify(out, null, 2));
+            return;
+        }
+        s.stop();
+        const questions = (out.questions ?? []);
+        console.log(`  ${chalk_1.default.bold(String(out.title ?? id))}  ${lifecycleTag(String(out.lifecycle ?? ''))}`);
+        if (out.public_url)
+            console.log(`  ${chalk_1.default.dim('public link')}  ${chalk_1.default.cyan(String(out.public_url))}`);
+        else if (out.public_path)
+            console.log(`  ${chalk_1.default.dim('public path')}  ${String(out.public_path)}`);
+        console.log(`  ${chalk_1.default.dim(`${questions.length} question${questions.length === 1 ? '' : 's'}`)}`);
+        questions.forEach((q, i) => {
+            const req = q.required ? chalk_1.default.dim(' (required)') : '';
+            console.log(`    ${String(i + 1).padStart(2, '0')}  ${chalk_1.default.dim(String(q.kind).padEnd(8))} ${q.prompt}${req}`);
+        });
+    }
+    catch (e) {
+        fail(s, 'Failed to read the form', e);
+    }
+});
+exports.formsCommand
+    .command('publish <id>')
+    .description('Publish a draft — it starts taking answers')
+    .action(async (id) => {
+    requireAuth();
+    const s = (0, ora_1.default)(`Publishing ${id}...`).start();
+    try {
+        const out = await callVerbConfirmed('survey.publish', { survey_id: Number(id) });
+        if (out.status === 'error' || out.status === 'not_found') {
+            s.fail(chalk_1.default.red(String(out.summary ?? 'Could not publish')));
+            process.exit(1);
+        }
+        s.succeed(chalk_1.default.green('Published — live and taking answers'));
+        try {
+            const d = await callVerb('form.describe', { form_id: String(id), provider: 'native' });
+            if (d.public_url)
+                console.log(`  ${chalk_1.default.dim('public link')}  ${chalk_1.default.cyan(String(d.public_url))}`);
+        }
+        catch { /* the publish still succeeded */ }
+    }
+    catch (e) {
+        fail(s, 'Failed to publish', e);
+    }
+});
+exports.formsCommand
+    .command('pause <id>')
+    .description('Stop taking new answers. Every answer already given is kept')
+    .action(async (id) => {
+    requireAuth();
+    const s = (0, ora_1.default)(`Pausing ${id}...`).start();
+    try {
+        const out = await callVerbConfirmed('survey.set_live', { survey_id: Number(id), live: false });
+        if (out.status === 'invalid' || out.status === 'error') {
+            s.fail(chalk_1.default.red(String(out.summary ?? 'Could not pause it')));
+            process.exit(1);
+        }
+        s.succeed(chalk_1.default.green('Paused — every answer kept, no new ones'));
+    }
+    catch (e) {
+        fail(s, 'Failed to pause', e);
+    }
+});
+exports.formsCommand
+    .command('resume <id>')
+    .description('Take answers again on a paused form')
+    .action(async (id) => {
+    requireAuth();
+    const s = (0, ora_1.default)(`Resuming ${id}...`).start();
+    try {
+        const out = await callVerbConfirmed('survey.set_live', { survey_id: Number(id), live: true });
+        if (out.status === 'invalid' || out.status === 'error') {
+            s.fail(chalk_1.default.red(String(out.summary ?? 'Could not resume it')));
+            process.exit(1);
+        }
+        s.succeed(chalk_1.default.green('Live — taking answers again'));
+    }
+    catch (e) {
+        fail(s, 'Failed to resume', e);
+    }
+});
+exports.formsCommand
+    .command('link <id>')
+    .description("The form's standing public URL — the one address you can share anywhere")
+    .option('--provider <name>', 'Form provider', 'native')
+    .action(async (id, opts) => {
+    requireAuth();
+    const s = (0, ora_1.default)('Resolving...').start();
+    // ⛔ THE EXIT LIVES OUTSIDE THE try. An intentional process.exit inside it
+    // is caught by the error handler below and reported as "Failed to resolve
+    // the link" — the command would then exit 0 with a misleading message.
+    let out;
+    try {
+        out = await callVerb('form.describe', { form_id: String(id), provider: opts.provider });
+    }
+    catch (e) {
+        fail(s, 'Failed to resolve the link', e);
+        return;
+    }
+    if (out.public_url || out.public_path) {
+        s.stop();
+        // Bare URL on stdout so it pipes into pbcopy, a QR generator, anything.
+        console.log(String(out.public_url ?? out.public_path));
+        return;
+    }
+    s.fail(chalk_1.default.yellow(`No public link — this form is ${String(out.lifecycle ?? 'not live')}.`));
+    console.error(chalk_1.default.dim('  Only a live form has a public address. Publish it first:'));
+    console.error(chalk_1.default.dim(`    solid forms publish ${id}`));
+    process.exit(1);
+});
+exports.formsCommand
+    .command('responses <id>')
+    .description('What people actually answered')
+    .option('--provider <name>', 'Form provider', 'native')
+    .option('--limit <n>', 'How many to show', '25')
+    .option('--json', 'Output as JSON')
+    .action(async (id, opts) => {
+    requireAuth();
+    const s = (0, ora_1.default)('Loading responses...').start();
+    try {
+        const out = await callVerb('form.responses', {
+            form_id: String(id), provider: opts.provider, per_page: Number(opts.limit),
+        });
+        if ((0, json_output_1.isJsonOutput)(opts)) {
+            s.stop();
+            console.log(JSON.stringify(out, null, 2));
+            return;
+        }
+        s.stop();
+        const rows = (out.responses ?? []);
+        if (!rows.length) {
+            console.log(chalk_1.default.dim('  Nothing answered yet.'));
+            return;
+        }
+        for (const r of rows) {
+            const when = String(r.completed_at ?? r.created_at ?? '').split('T')[0];
+            const channels = Array.isArray(r.channels) ? r.channels.join('+') : '';
+            console.log(`  ${chalk_1.default.bold(String(r.external_id ?? r.id ?? ''))}  ${chalk_1.default.dim(when)}  ${chalk_1.default.dim(channels)}`);
+            for (const [k, v] of Object.entries((r.answers ?? {}))) {
+                console.log(`      ${chalk_1.default.dim(k)}: ${String(v)}`);
+            }
+        }
+    }
+    catch (e) {
+        fail(s, 'Failed to load responses', e);
+    }
+});
+exports.formsCommand
+    .command('status')
+    .description('Every form with its lifecycle — the CLI view of the library')
+    .option('--provider <name>', 'Form provider', 'native')
+    .option('--json', 'Output as JSON')
+    .action(async (opts) => {
+    requireAuth();
+    const s = (0, ora_1.default)('Loading...').start();
+    try {
+        const out = await callVerb('form.list', { provider: opts.provider });
+        if ((0, json_output_1.isJsonOutput)(opts)) {
+            s.stop();
+            console.log(JSON.stringify(out, null, 2));
+            return;
+        }
+        s.stop();
+        const rows = (out.forms ?? []);
+        if (!rows.length) {
+            console.log(chalk_1.default.dim('  No forms yet.'));
+            return;
+        }
+        for (const f of rows) {
+            const state = lifecycleOf(f);
+            const answered = Number(f.response_count ?? 0);
+            console.log(`  ${chalk_1.default.bold(String(f.external_id).padEnd(5))} ${lifecycleTag(state).padEnd(16)} ` +
+                `${String(f.title ?? '').padEnd(34)} ${chalk_1.default.dim(`${answered} answered`)}`);
+        }
+    }
+    catch (e) {
+        fail(s, 'Failed to load forms', e);
+    }
+});
+// ── moments: WHEN a form goes out ──────────────────────────────────────────
+//
+// The dashboard's most-prompted next step after publishing, and it had no CLI
+// surface at all — so an AI could publish a form and then nothing could ever
+// send it.
+const momentsCmd = exports.formsCommand.command('moments')
+    .description('When a form goes out — the tenant\'s moments');
+momentsCmd
+    .command('list', { isDefault: true })
+    .description('Every moment, and which form (if any) it sends')
+    .option('--json', 'Output as JSON')
+    .action(async (opts) => {
+    requireAuth();
+    const sp = (0, ora_1.default)('Loading moments...').start();
+    try {
+        const out = await callVerb('form.triggers');
+        if ((0, json_output_1.isJsonOutput)(opts)) {
+            sp.stop();
+            console.log(JSON.stringify(out, null, 2));
+            return;
+        }
+        sp.stop();
+        const rows = (out.triggers ?? []);
+        if (!rows.length) {
+            console.log(chalk_1.default.dim('  No moments available.'));
+            return;
+        }
+        for (const t of rows) {
+            const on = t.configured ? chalk_1.default.green('on ') : chalk_1.default.dim('off');
+            const what = t.configured && t.form_id
+                ? `sends form ${t.form_id} ${t.stage === 'before' ? 'beforehand' : 'afterwards'}`
+                : chalk_1.default.dim('nothing set');
+            console.log(`  ${on}  ${String(t.event).padEnd(24)} ${what}`);
+        }
+        console.log(chalk_1.default.dim('\n  Wire one:  solid forms moments set <event> --form <id>'));
+    }
+    catch (e) {
+        fail(sp, 'Failed to load moments', e);
+    }
+});
+momentsCmd
+    .command('set <event>')
+    .description('Send a form at this moment')
+    .requiredOption('--form <id>', 'The form to send')
+    .option('--provider <name>', 'Form provider', 'native')
+    .option('--stage <when>', 'before | after')
+    .action(async (event, opts) => {
+    requireAuth();
+    const sp = (0, ora_1.default)(`Wiring ${event}...`).start();
+    try {
+        const out = await callVerbConfirmed('form.configure_trigger', {
+            event, form_id: String(opts.form), provider: opts.provider,
+            enabled: true, ...(opts.stage ? { stage: opts.stage } : {}),
+        });
+        if (out.status === 'invalid' || out.status === 'error') {
+            sp.fail(chalk_1.default.red(String(out.summary ?? 'Could not wire it')));
+            process.exitCode = 1;
+            return;
+        }
+        sp.succeed(chalk_1.default.green(`${event} now sends form ${opts.form}`));
+    }
+    catch (e) {
+        fail(sp, 'Failed to wire the moment', e);
+    }
+});
+momentsCmd
+    .command('off <event>')
+    .description('Stop sending anything at this moment')
+    .action(async (event) => {
+    requireAuth();
+    const sp = (0, ora_1.default)(`Switching ${event} off...`).start();
+    try {
+        const out = await callVerbConfirmed('form.configure_trigger', { event, enabled: false });
+        if (out.status === 'invalid' || out.status === 'error') {
+            sp.fail(chalk_1.default.red(String(out.summary ?? 'Could not switch it off')));
+            process.exitCode = 1;
+            return;
+        }
+        sp.succeed(chalk_1.default.green(`${event} sends nothing now`));
+    }
+    catch (e) {
+        fail(sp, 'Failed to switch it off', e);
+    }
+});
+// ── reviews: where a happy customer is sent ────────────────────────────────
+const reviewsCmd = exports.formsCommand.command('reviews')
+    .description('Where happy customers are asked to leave a review');
+reviewsCmd
+    .command('list', { isDefault: true })
+    .description('The review destinations this tenant has set')
+    .option('--json', 'Output as JSON')
+    .action(async (opts) => {
+    requireAuth();
+    const sp = (0, ora_1.default)('Loading destinations...').start();
+    try {
+        const out = await callVerb('review.destinations');
+        if ((0, json_output_1.isJsonOutput)(opts)) {
+            sp.stop();
+            console.log(JSON.stringify(out, null, 2));
+            return;
+        }
+        sp.stop();
+        const rows = (out.destinations ?? []);
+        if (!rows.length) {
+            console.log(chalk_1.default.dim('  No review destinations yet.'));
+            console.log(chalk_1.default.dim('  Set one:  solid forms reviews set google <url>'));
+            return;
+        }
+        for (const d of rows)
+            console.log(`  ${String(d.platform).padEnd(12)} ${d.url}`);
+    }
+    catch (e) {
+        fail(sp, 'Failed to load destinations', e);
+    }
+});
+reviewsCmd
+    .command('set <platform> <url>')
+    .description('Point future review requests at this link')
+    .action(async (platform, url) => {
+    requireAuth();
+    const sp = (0, ora_1.default)('Saving...').start();
+    try {
+        const out = await callVerbConfirmed('review.set_destination', { platform, url });
+        if (out.status === 'invalid' || out.status === 'error') {
+            sp.fail(chalk_1.default.red(String(out.summary ?? 'Could not save it')));
+            process.exitCode = 1;
+            return;
+        }
+        sp.succeed(chalk_1.default.green(`${platform} review link saved`));
+    }
+    catch (e) {
+        fail(sp, 'Failed to save', e);
+    }
+});
+// ── build: a starter playbook, in THIS tenant's words ──────────────────────
+exports.formsCommand
+    .command('build')
+    .description("Draft a form for this business — in its own industry's words")
+    .option('--intent <kind>', 'intake | feedback | lead_qualify | onboarding', 'intake')
+    .option('--save', 'Save it as a draft (nothing is saved without this)')
+    .option('--title <text>', 'Title to save it under')
+    .option('--json', 'Output as JSON')
+    .action(async (opts) => {
+    requireAuth();
+    const sp = (0, ora_1.default)('Drafting...').start();
+    try {
+        // ⛔ kb_sub_code IS NOT PASSED. The verb resolves THIS tenant's industry
+        // from their own company row; sending one from the CLI would be guessing
+        // at someone's business. See mcp/tools/form_session_verbs._tenant_kb_sub_code.
+        const draft = await callVerb('playbook.suggest', { intent: opts.intent });
+        if (draft.status === 'invalid' || draft.status === 'error') {
+            sp.fail(chalk_1.default.red(String(draft.summary ?? 'Could not draft it')));
+            process.exitCode = 1;
+            return;
+        }
+        if ((0, json_output_1.isJsonOutput)(opts) && !opts.save) {
+            sp.stop();
+            console.log(JSON.stringify(draft, null, 2));
+            return;
+        }
+        sp.stop();
+        const preview = (draft.preview ?? draft.steps ?? []);
+        console.log(`  ${chalk_1.default.bold(String(draft.title ?? opts.intent))}  ${chalk_1.default.dim(`(${preview.length} steps)`)}`);
+        preview.forEach((st, i) => {
+            console.log(`    ${String(i + 1).padStart(2, '0')}  ${chalk_1.default.dim(String(st.kind ?? 'question').padEnd(8))} ${st.prompt ?? ''}`);
+        });
+        if (!opts.save) {
+            console.log(chalk_1.default.dim('\n  Nothing saved. Add --save to keep it as a draft.'));
+            return;
+        }
+        const sp2 = (0, ora_1.default)('Saving as a draft...').start();
+        const saved = await callVerbConfirmed('playbook.save', {
+            title: opts.title ?? String(draft.title ?? `${opts.intent} form`),
+            steps: draft.steps ?? [],
+            ...(draft.outcomes ? { outcomes: draft.outcomes } : {}),
+        });
+        if (saved.status === 'invalid' || saved.status === 'error') {
+            sp2.fail(chalk_1.default.red(String(saved.summary ?? 'Could not save it')));
+            process.exitCode = 1;
+            return;
+        }
+        sp2.succeed(chalk_1.default.green(`Saved as a draft (${saved.playbook_id ?? saved.form_id ?? '?'})`));
+        console.log(chalk_1.default.dim(`  Publish when it's ready:  solid forms publish ${saved.playbook_id ?? saved.form_id ?? '<id>'}`));
+    }
+    catch (e) {
+        fail(sp, 'Failed to build', e);
+    }
+});
+// ── walk: answer a form from the terminal, exactly as an agent does ─────────
+//
+// The CLI equivalent of the Live Form bench: next_question → capture → submit,
+// the same three verbs a voice agent uses mid-call. Scriptable on purpose, so
+// an AI can drive it non-interactively.
+exports.formsCommand
+    .command('walk <id>')
+    .description('Answer a form the way an agent does — next question, capture, submit')
+    .option('--provider <name>', 'Form provider', 'native')
+    .option('--session <ref>', 'Continue an existing session')
+    .option('--question <id>', 'The question being answered (with --answer)')
+    .option('--answer <value>', 'Record an answer, then show what is next')
+    .option('--submit', 'Finish and persist the response')
+    .option('--branching', 'Walk the PLAYBOOK — branches, message and action steps, skips honoured')
+    .option('--answers <json>', 'With --branching: answers so far, as {"q1":"yes"} or @file.json')
+    .option('--json', 'Output as JSON')
+    .action(async (id, opts) => {
+    requireAuth();
+    const base = { form_id: String(id), provider: opts.provider };
+    const sp = (0, ora_1.default)('Working...').start();
+    // ⛔ BRANCHES DO NOT TRAVEL THROUGH form.next_question. That verb walks by
+    // POSITION — a branched playbook served through it asks every question in
+    // order (the superset), which is safe for a form but wrong for a quiz whose
+    // skips are the point. playbook.next_step is the real walk, and it takes the
+    // answers as a MAP rather than a session ref, so this mode is stateless and
+    // scriptable: pass back what you have, get the next step.
+    if (opts.branching) {
+        let answered = {};
+        if (opts.answers) {
+            const parsed = (0, json_arg_1.parseJsonArg)('answers', opts.answers);
+            if (parsed && typeof parsed === 'object')
+                answered = parsed;
+        }
+        if (opts.answer !== undefined) {
+            if (!opts.question) {
+                sp.fail(chalk_1.default.red('--answer needs --question <id>'));
+                process.exitCode = 1;
+                return;
+            }
+            answered[String(opts.question)] = opts.answer;
+        }
+        try {
+            const out = await callVerb('playbook.next_step', {
+                playbook_id: String(id), answered,
+            });
+            sp.stop();
+            if (out.status === 'error' || out.status === 'invalid') {
+                console.error(chalk_1.default.red(String(out.summary ?? 'Could not walk it')));
+                process.exitCode = 1;
+                return;
+            }
+            if ((0, json_output_1.isJsonOutput)(opts)) {
+                console.log(JSON.stringify({ ...out, answered }, null, 2));
+                return;
+            }
+            console.log(`  ${chalk_1.default.bold(String(out.title ?? id))}  ${chalk_1.default.dim(`${out.answered_count ?? 0} answered`)}`);
+            if (out.complete) {
+                console.log(chalk_1.default.green('  The playbook is finished.'));
+                console.log(chalk_1.default.dim(`  Score it:  solid forms quiz ${id} --answers '${JSON.stringify(answered)}'`));
+                return;
+            }
+            const step = (out.step ?? {});
+            const kind = String(step.kind ?? 'question');
+            console.log(`  ${chalk_1.default.dim(kind.padEnd(8))} ${chalk_1.default.bold(String(step.prompt ?? ''))}`);
+            if (kind === 'action') {
+                // The verb NAME comes back; the AGENT calls it. Say so rather than
+                // implying the CLI just did something.
+                console.log(`  ${chalk_1.default.dim('the agent would call')} ${chalk_1.default.cyan(String(step.verb ?? '—'))}`);
+                if (step.verb_args && Object.keys(step.verb_args).length) {
+                    console.log(`  ${chalk_1.default.dim('with')} ${JSON.stringify(step.verb_args)}`);
+                }
+            }
+            if (Array.isArray(step.choices) && step.choices.length) {
+                console.log(`  ${chalk_1.default.dim('choices:')} ${step.choices.join(' / ')}`);
+            }
+            const next = { ...answered, [String(step.id ?? 'q')]: '...' };
+            console.log(chalk_1.default.dim(`\n  Answer it:  solid forms walk ${id} --branching --question ${step.id}` +
+                ` --answer "..." --answers '${JSON.stringify(answered)}'`));
+            void next;
+            return;
+        }
+        catch (e) {
+            fail(sp, 'Failed to walk the playbook', e);
+            return;
+        }
+    }
+    try {
+        if (opts.submit) {
+            const out = await callVerbConfirmed('form.submit', {
+                ...base, ...(opts.session ? { session_ref: opts.session } : {}),
+            });
+            sp.stop();
+            if (out.status === 'invalid') {
+                console.error(chalk_1.default.yellow(String(out.summary)));
+                process.exitCode = 1;
+                return;
+            }
+            if ((0, json_output_1.isJsonOutput)(opts)) {
+                console.log(JSON.stringify(out, null, 2));
+                return;
+            }
+            console.log(chalk_1.default.green(`  Submitted — response ${out.response_id ?? ''}`));
+            if (out.contact_id) {
+                console.log(`  ${chalk_1.default.dim('landed on contact')} ${out.contact_id}` +
+                    (out.contact_created ? chalk_1.default.dim(' (new lead)') : ''));
+            }
+            return;
+        }
+        let session = opts.session;
+        if (opts.answer !== undefined) {
+            if (!opts.question) {
+                sp.fail(chalk_1.default.red('--answer needs --question <id>'));
+                process.exitCode = 1;
+                return;
+            }
+            const cap = await callVerbConfirmed('form.capture', {
+                ...base, question_id: String(opts.question), value: opts.answer,
+                channel: 'cli', ...(session ? { session_ref: session } : {}),
+            });
+            session = String(cap.session_ref ?? session ?? '');
+        }
+        const next = await callVerb('form.next_question', {
+            ...base, ...(session ? { session_ref: session } : {}),
+        });
+        sp.stop();
+        if ((0, json_output_1.isJsonOutput)(opts)) {
+            console.log(JSON.stringify({ ...next, session_ref: session }, null, 2));
+            return;
+        }
+        if (session)
+            console.log(`  ${chalk_1.default.dim('session')} ${session}`);
+        if (next.complete) {
+            console.log(chalk_1.default.green('  Every question answered.'));
+            console.log(chalk_1.default.dim(`  Finish it:  solid forms walk ${id} --session ${session ?? ''} --submit`));
+            return;
+        }
+        const q = (next.next_question ?? {});
+        console.log(`  ${chalk_1.default.bold(String(q.prompt ?? ''))}`);
+        console.log(`  ${chalk_1.default.dim(`${q.kind}${q.required ? ', required' : ''}`)}`);
+        if (Array.isArray(q.choices) && q.choices.length) {
+            console.log(`  ${chalk_1.default.dim('choices:')} ${q.choices.join(' / ')}`);
+        }
+        console.log(chalk_1.default.dim(`\n  Answer it:  solid forms walk ${id} --question ${q.id}` +
+            ` --answer "..."${session ? ` --session ${session}` : ''}`));
+    }
+    catch (e) {
+        fail(sp, 'Failed', e);
+    }
+});
+// ── quiz: score a run and see which band it lands in ───────────────────────
+//
+// A quiz's scoring is server-side ONLY — the answer key never travels with the
+// questions, which is right, and it meant a tenant could not check their own
+// bands without finding a real respondent. This scores a hypothetical run.
+exports.formsCommand
+    .command('quiz <id>')
+    .description('Score a set of answers against a quiz and show the outcome band')
+    .requiredOption('--answers <json>', 'The answers to score: \'{"q1":"yes"}\' or @file.json')
+    .option('--json', 'Output as JSON')
+    .action(async (id, opts) => {
+    requireAuth();
+    const answered = (0, json_arg_1.parseJsonArg)('answers', opts.answers);
+    if (!answered || typeof answered !== 'object' || Array.isArray(answered)) {
+        console.error(chalk_1.default.red('--answers must be a JSON object of question_id -> value'));
+        console.error(chalk_1.default.dim('  e.g.  --answers \'{"experience":"none","budget":"high"}\''));
+        process.exitCode = 1;
+        return;
+    }
+    const sp = (0, ora_1.default)('Scoring...').start();
+    let out;
+    try {
+        // kb_sub_code omitted — the saved playbook carries its own industry.
+        out = await callVerb('quiz.result', { playbook_id: String(id), answered });
+    }
+    catch (e) {
+        fail(sp, 'Failed to score it', e);
+        return;
+    }
+    if (out.status === 'error' || out.status === 'invalid') {
+        sp.fail(chalk_1.default.red(String(out.summary ?? 'Could not score it')));
+        process.exitCode = 1;
+        return;
+    }
+    if ((0, json_output_1.isJsonOutput)(opts)) {
+        sp.stop();
+        console.log(JSON.stringify(out, null, 2));
+        return;
+    }
+    sp.stop();
+    console.log(`  ${chalk_1.default.bold(String(out.title ?? id))}`);
+    if (out.is_quiz === false) {
+        console.log(chalk_1.default.yellow('  This playbook does not score — no points on its steps and no outcome bands.'));
+        console.log(chalk_1.default.dim('  Add scoring to its steps, or walk it as a form:  solid forms walk ' + id));
+        return;
+    }
+    const pct = out.percent !== undefined && out.percent !== null ? ` (${Math.round(Number(out.percent))}%)` : '';
+    console.log(`  ${chalk_1.default.dim('score')} ${out.score ?? 0}${out.max !== undefined ? `/${out.max}` : ''}${pct}`);
+    const band = (out.outcome ?? null);
+    if (!band || (!band.title && !band.message)) {
+        // ⛔ A SCORE THAT LANDS NOWHERE IS THE DEFECT WORTH SEEING. The dashboard
+        // flags it too: a respondent who finishes and is told nothing.
+        console.log(chalk_1.default.yellow('  ⚠ This score lands in NO outcome band — a respondent would be told nothing.'));
+        console.log(chalk_1.default.dim('  Check the band bounds cover every possible score.'));
+        process.exitCode = 1;
+        return;
+    }
+    if (band.title)
+        console.log(`  ${chalk_1.default.green(String(band.title))}`);
+    if (band.message)
+        console.log(`  ${String(band.message)}`);
+    if (band.verb) {
+        console.log(`  ${chalk_1.default.dim('the agent would then call')} ${chalk_1.default.cyan(String(band.verb))}` +
+            (band.verb_args && Object.keys(band.verb_args).length
+                ? ` ${chalk_1.default.dim(JSON.stringify(band.verb_args))}` : ''));
+    }
+});
+// ── vocabulary: the nouns this tenant's customers actually use ──────────────
+exports.formsCommand
+    .command('vocabulary')
+    .alias('words')
+    .description("This business's own words — what its customers are called, and its appointments")
+    .option('--lang <code>', 'Language', 'en')
+    .option('--json', 'Output as JSON')
+    .action(async (opts) => {
+    requireAuth();
+    const sp = (0, ora_1.default)('Loading...').start();
+    try {
+        // kb_sub_code omitted deliberately — the verb resolves this tenant's own.
+        const out = await callVerb('playbook.vocabulary', { lang: opts.lang });
+        if ((0, json_output_1.isJsonOutput)(opts)) {
+            sp.stop();
+            console.log(JSON.stringify(out, null, 2));
+            return;
+        }
+        sp.stop();
+        const terms = (out.terms ?? {});
+        console.log(`  ${chalk_1.default.dim('industry code')} ${out.kb_sub_code ?? chalk_1.default.dim('none set')}`);
+        for (const [k, v] of Object.entries(terms)) {
+            console.log(`  ${chalk_1.default.dim(k.padEnd(16))} ${v}`);
+        }
+    }
+    catch (e) {
+        fail(sp, 'Failed to load the vocabulary', e);
+    }
+});
 const command_kit_1 = require("../lib/command-kit");
 (0, command_kit_1.appendExamples)(exports.formsCommand, [
-    { cmd: 'solid forms list', why: 'All forms + surveys' },
-    { cmd: 'solid forms create --title "Contact" --prompt "email + message"', why: 'AI-generate a form' },
-    { cmd: 'solid forms export <id> --format csv', why: 'Dump responses to CSV' },
-    { cmd: 'solid forms responses <id> --since 7d', why: 'Recent submissions' },
+    { cmd: 'solid forms list', why: 'Every form with its lifecycle, across every provider' },
+    { cmd: 'solid forms build --intent intake --save', why: "A starter in this industry's own words" },
+    { cmd: 'solid forms publish <id>', why: 'A draft starts taking answers' },
+    { cmd: 'solid forms link <id>', why: "The form's shareable URL, bare on stdout" },
+    { cmd: 'solid forms moments set appointment_booked --form <id>', why: 'Make something actually send it' },
+    { cmd: 'solid forms walk <id>', why: 'Answer it the way an agent does, from the terminal' },
+    { cmd: 'solid forms responses <id>', why: 'What people actually answered' },
 ]);
 //# sourceMappingURL=forms.js.map