fullstackgtm 0.44.0 → 0.45.0

package/dist/cli/fix.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The resolve gate: exit 0 = safe to create, exit 2 = match found (exists or
+ * ambiguous — do NOT blind-create), exit 1 = error. Built for sync jobs and
+ * webhook handlers to call before any record creation.
+ */
+export declare function resolveCommand(args: string[]): Promise<void>;
+/**
+ * Governed generic writes: build a dry-run patch plan from a snapshot filter
+ * plus field assignments (or --archive). Never writes — approve and apply the
+ * plan like any audit plan; compare-and-set protects every operation.
+ */
+export declare function bulkUpdateCommand(args: string[]): Promise<void>;
+/**
+ * Governed duplicate cleanup: group by a normalized identity key, propose one
+ * merge_records per duplicate group with a deterministic survivor. Never
+ * writes — approve and apply the plan like any audit plan.
+ */
+export declare function dedupeCommand(args: string[]): Promise<void>;
+/**
+ * Ownership handoff playbook: compile one bulk-update-style plan per object
+ * type. Each plan carries its full filter, so eligibility (including the
+ * --except-deal-stage exclusion) is re-verified per record at apply time.
+ */
+export declare function reassignCommand(args: string[]): Promise<void>;
+/**
+ * One-shot composite for a single audit rule: audit → save → suggest →
+ * approve only suggestion-backed operations meeting the confidence bar (plus
+ * operations that carry concrete values and need no human input) → apply
+ * (only with --yes). Every stage goes through the same gates as the manual
+ * chain; placeholder values below the bar stay unapproved.
+ */
+export declare function fixCommand(args: string[]): Promise<void>;
+export declare function suggest(args: string[]): Promise<void>;

package/dist/cli/fix.js

@@ -0,0 +1,344 @@
+// Extracted verbatim from src/cli.ts (mechanical split, no behavior change).
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { auditSnapshot, defaultPolicy } from "../audit.js";
+import { loadConfig, mergePolicy, resolveConfiguredRules } from "../config.js";
+import { applyPatchPlan } from "../connector.js";
+import { patchPlanToMarkdown } from "../format.js";
+import { createFilePlanStore } from "../planStore.js";
+import { resolveRecord } from "../resolve.js";
+import { buildBulkUpdatePlan } from "../bulkUpdate.js";
+import { buildDedupePlan } from "../dedupe.js";
+import { buildReassignPlans } from "../reassign.js";
+import { suggestValues } from "../suggest.js";
+import { confirmRequested, connectorFor, isOptionValue, numericOption, option, readSnapshot, repeatedOption, saveRequested } from "./shared.js";
+import { box, colorEnabled, createStatusLine, paint } from "./ui.js";
+/**
+ * The resolve gate: exit 0 = safe to create, exit 2 = match found (exists or
+ * ambiguous — do NOT blind-create), exit 1 = error. Built for sync jobs and
+ * webhook handlers to call before any record creation.
+ */
+export async function resolveCommand(args) {
+    const [objectType, ...rest] = args;
+    if (!objectType || !["account", "contact", "deal"].includes(objectType)) {
+        throw new Error("Usage: fullstackgtm resolve <account|contact|deal> [--name N] [--domain D] [--email E] [--account-id A] [source options] [--json]");
+    }
+    const candidate = {
+        objectType: objectType,
+        name: option(rest, "--name") ?? undefined,
+        domain: option(rest, "--domain") ?? undefined,
+        email: option(rest, "--email") ?? undefined,
+        accountId: option(rest, "--account-id") ?? undefined,
+    };
+    const snapshot = await readSnapshot(rest);
+    const result = resolveRecord(snapshot, candidate);
+    if (rest.includes("--json")) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        const marker = result.verdict === "safe_to_create" ? "✓" : result.verdict === "exists" ? "=" : "?";
+        console.log(`${marker} [${result.verdict}] ${result.reason}`);
+        for (const m of result.matches) {
+            console.log(`    ${m.id} "${m.name}" — matched by ${m.matchedBy}: ${m.detail}`);
+        }
+    }
+    if (result.verdict !== "safe_to_create")
+        process.exitCode = 2;
+}
+/**
+ * Governed generic writes: build a dry-run patch plan from a snapshot filter
+ * plus field assignments (or --archive). Never writes — approve and apply the
+ * plan like any audit plan; compare-and-set protects every operation.
+ */
+export async function bulkUpdateCommand(args) {
+    const [objectType, ...rest] = args;
+    if (!objectType || !["account", "contact", "deal"].includes(objectType)) {
+        throw new Error("Usage: fullstackgtm bulk-update <account|contact|deal> --where <field=value|field!=value|field~substr|field:empty|field:notempty> [--where …] (--set <field>=<value> [--set …] | --archive) [source options] [--reason <text>] [--max-operations <n>] [--save] [--out <path>] [--json]");
+    }
+    const where = repeatedOption(rest, "--where");
+    const set = {};
+    for (const pair of repeatedOption(rest, "--set")) {
+        const separator = pair.indexOf("=");
+        if (separator === -1)
+            throw new Error(`--set must look like <field>=<value>, got "${pair}"`);
+        set[pair.slice(0, separator)] = pair.slice(separator + 1);
+    }
+    const snapshot = await readSnapshot(rest);
+    const plan = buildBulkUpdatePlan(snapshot, {
+        objectType: objectType,
+        where,
+        set: Object.keys(set).length > 0 ? set : undefined,
+        archive: rest.includes("--archive"),
+        forceArchiveDuplicates: rest.includes("--force-archive-duplicates"),
+        createTask: option(rest, "--create-task") ?? undefined,
+        require: repeatedOption(rest, "--require"),
+        guard: repeatedOption(rest, "--guard"),
+        reason: option(rest, "--reason") ?? undefined,
+        maxOperations: numericOption(rest, "--max-operations"),
+        // --today resolves the comparison `today` literal (e.g. closeDate<today);
+        // defaults to the system date inside buildBulkUpdatePlan when omitted.
+        today: option(rest, "--today") ?? undefined,
+    });
+    await emitPlan(plan, rest);
+}
+/** Shared plan output plumbing: --out, --save (with the approve/apply hint), --json or markdown. */
+async function emitPlan(plan, args) {
+    const out = option(args, "--out");
+    if (out) {
+        writeFileSync(resolve(process.cwd(), out), `${JSON.stringify(plan, null, 2)}\n`);
+    }
+    if (saveRequested(args)) {
+        await createFilePlanStore().save(plan);
+        console.error(`Saved plan ${plan.id} (${plan.operations.length} operations). Review with \`fullstackgtm plans show ${plan.id}\`, approve with \`fullstackgtm plans approve ${plan.id} --operations <ids|all>\`, then \`fullstackgtm apply --plan-id ${plan.id} --provider <name>\`.`);
+    }
+    if (args.includes("--json")) {
+        console.log(JSON.stringify(plan, null, 2));
+    }
+    else {
+        console.log(patchPlanToMarkdown(plan));
+    }
+}
+/**
+ * Governed duplicate cleanup: group by a normalized identity key, propose one
+ * merge_records per duplicate group with a deterministic survivor. Never
+ * writes — approve and apply the plan like any audit plan.
+ */
+export async function dedupeCommand(args) {
+    const [objectType, ...rest] = args;
+    if (!objectType || !["account", "contact", "deal"].includes(objectType)) {
+        throw new Error("Usage: fullstackgtm dedupe <account|contact|deal> --key <domain|email|name> [--keep richest|oldest] [source options] [--reason <text>] [--max-operations <n>] [--save] [--out <path>] [--json]");
+    }
+    const key = option(rest, "--key");
+    if (!key || !["domain", "email", "name"].includes(key)) {
+        throw new Error("dedupe requires --key <domain|email|name> (the identity field duplicates share).");
+    }
+    const keep = option(rest, "--keep") ?? undefined;
+    const snapshot = await readSnapshot(rest);
+    const plan = buildDedupePlan(snapshot, {
+        objectType: objectType,
+        key: key,
+        keep: (keep ?? undefined),
+        reason: option(rest, "--reason") ?? undefined,
+        maxOperations: numericOption(rest, "--max-operations"),
+    });
+    await emitPlan(plan, rest);
+}
+/**
+ * Ownership handoff playbook: compile one bulk-update-style plan per object
+ * type. Each plan carries its full filter, so eligibility (including the
+ * --except-deal-stage exclusion) is re-verified per record at apply time.
+ */
+export async function reassignCommand(args) {
+    const from = option(args, "--from");
+    const to = option(args, "--to");
+    const assignUnowned = args.includes("--assign-unowned");
+    if (!to || (!from && !assignUnowned)) {
+        throw new Error("Usage: fullstackgtm reassign (--from <ownerId> | --assign-unowned) --to <ownerId> [--objects account,contact,deal] [--where <expr> …] [--except-deal-stage <stage>] [--include-closed-deals] [source options] [--reason <text>] [--max-operations <n>] [--save] [--out <path>] [--json]\n\n--assign-unowned claims every OWNERLESS record (ownerId:empty) for --to — the backfill twin of `enrich acquire`'s create-time assignment.");
+    }
+    const objects = option(args, "--objects")
+        ?.split(",")
+        .map((value) => value.trim())
+        .filter(Boolean);
+    const snapshot = await readSnapshot(args);
+    const plans = buildReassignPlans(snapshot, {
+        fromOwnerId: from ?? undefined,
+        toOwnerId: to,
+        assignUnowned,
+        objects,
+        where: repeatedOption(args, "--where"),
+        exceptDealStage: option(args, "--except-deal-stage") ?? undefined,
+        includeClosedDeals: args.includes("--include-closed-deals"),
+        reason: option(args, "--reason") ?? undefined,
+        maxOperations: numericOption(args, "--max-operations"),
+    });
+    const out = option(args, "--out");
+    if (out) {
+        writeFileSync(resolve(process.cwd(), out), `${JSON.stringify(plans, null, 2)}\n`);
+    }
+    if (args.includes("--json")) {
+        console.log(JSON.stringify(plans, null, 2));
+        return;
+    }
+    const store = saveRequested(args) ? createFilePlanStore() : null;
+    for (const plan of plans) {
+        if (store)
+            await store.save(plan);
+        console.log(`${plan.id}  ${String(plan.operations.length).padStart(3)} operation(s)  ${plan.title}`);
+        console.log(`    ${plan.summary}`);
+    }
+    if (store) {
+        console.log(`\nSaved ${plans.length} plan(s). For each: \`fullstackgtm plans show <id>\`, \`fullstackgtm plans approve <id> --operations <ids|all>\`, then \`fullstackgtm apply --plan-id <id> --provider <name>\`.`);
+    }
+    else {
+        console.log("\nDry run only — re-run with --save to store the plans for approval.");
+    }
+}
+/**
+ * One-shot composite for a single audit rule: audit → save → suggest →
+ * approve only suggestion-backed operations meeting the confidence bar (plus
+ * operations that carry concrete values and need no human input) → apply
+ * (only with --yes). Every stage goes through the same gates as the manual
+ * chain; placeholder values below the bar stay unapproved.
+ */
+export async function fixCommand(args) {
+    const ruleId = option(args, "--rule");
+    const provider = option(args, "--provider");
+    if (!ruleId || !provider) {
+        throw new Error("Usage: fullstackgtm fix --rule <ruleId> --provider <name> [--min-confidence high|low] [--include-creates] [--today <iso>] [--yes|--confirm] [--dry-run]");
+    }
+    const minConfidence = option(args, "--min-confidence") ?? "high";
+    if (!["high", "low"].includes(minConfidence)) {
+        throw new Error("--min-confidence must be high or low");
+    }
+    const includeCreates = args.includes("--include-creates");
+    const loaded = loadConfig(option(args, "--config") ?? undefined);
+    const configured = await resolveConfiguredRules(loaded);
+    const rule = configured.find((candidate) => candidate.id === ruleId);
+    if (!rule) {
+        throw new Error(`Unknown rule: ${ruleId}. Available rules: ${configured.map((r) => r.id).join(", ")}`);
+    }
+    const policy = mergePolicy(defaultPolicy(), loaded?.config);
+    const today = option(args, "--today");
+    if (today)
+        policy.today = today;
+    const snapshot = await readSnapshot(args);
+    const plan = auditSnapshot(snapshot, policy, [rule]);
+    if (plan.operations.length === 0) {
+        console.log(`fix ${ruleId}: audit proposed 0 operations — nothing to fix.`);
+        return;
+    }
+    const store = createFilePlanStore();
+    await store.save(plan);
+    const suggestions = suggestValues(plan, snapshot);
+    const accepted = new Set(minConfidence === "low" ? ["high", "low"] : ["high"]);
+    const overrides = {};
+    let belowBar = 0;
+    for (const suggestion of suggestions) {
+        if (suggestion.suggestedValue &&
+            (accepted.has(suggestion.confidence) || (includeCreates && suggestion.confidence === "create"))) {
+            overrides[suggestion.operationId] = suggestion.suggestedValue;
+        }
+        else {
+            belowBar += 1;
+        }
+    }
+    // Approve operations whose placeholder got a qualifying suggested value,
+    // plus operations that already carry a concrete value (no human input
+    // needed — nothing to guess). Everything else stays unapproved.
+    const placeholderIds = new Set(suggestions.map((suggestion) => suggestion.operationId));
+    const approvedIds = plan.operations
+        .map((operation) => operation.id)
+        .filter((id) => overrides[id] !== undefined || !placeholderIds.has(id));
+    const lines = [
+        `fix ${ruleId} via ${provider}:`,
+        `  proposed:  ${plan.operations.length} operation(s) — plan ${plan.id} (saved)`,
+        `  suggested: ${Object.keys(overrides).length} value(s) at ${minConfidence}+ confidence${includeCreates ? " (creates included)" : ""}${belowBar > 0 ? `; ${belowBar} below the bar (left unapproved)` : ""}`,
+        `  approved:  ${approvedIds.length} of ${plan.operations.length}`,
+    ];
+    if (approvedIds.length === 0) {
+        lines.push("  applied:   0 — no operation met the confidence bar");
+        console.log(lines.join("\n"));
+        console.log(`\nWiden with --min-confidence low / --include-creates, or approve manually: \`fullstackgtm plans approve ${plan.id} --operations <ids> --value <opId>=<value>\`.`);
+        return;
+    }
+    await store.approveOperations(plan.id, approvedIds, overrides);
+    // `--confirm` is the standardized alias for the legacy `--yes`; `--dry-run`
+    // wins over both and locks the stop-before-apply path.
+    if (!confirmRequested(args, "--yes")) {
+        lines.push("  applied:   0 (stopped before apply — pass --yes to write)");
+        console.log(lines.join("\n"));
+        // The decision moment: frame the exact command that writes. Rich-only —
+        // piped output keeps the plain two-line hint byte-for-byte.
+        const p = paint(colorEnabled(process.stdout));
+        if (p.enabled) {
+            console.log("");
+            console.log(box([`fullstackgtm apply --plan-id ${plan.id} --provider ${provider}`], p, "Apply with").join("\n"));
+        }
+        else {
+            console.log(`\nApply with:\n  fullstackgtm apply --plan-id ${plan.id} --provider ${provider}`);
+        }
+        return;
+    }
+    const connector = await connectorFor(provider, args);
+    // Live safety ticker on interactive terminals (stderr; inert otherwise).
+    const ticker = createStatusLine();
+    let run;
+    try {
+        run = await applyPatchPlan(connector, plan, {
+            approvedOperationIds: approvedIds,
+            valueOverrides: overrides,
+            onOperation: ticker.active
+                ? (progress) => ticker.set(`Applying ${progress.completed}/${progress.total} · ✓ ${progress.applied} applied · ${progress.failed} failed · ${progress.conflicts} conflict${progress.conflicts === 1 ? "" : "s"}`)
+                : undefined,
+        });
+    }
+    finally {
+        ticker.done();
+    }
+    await store.recordRun(plan.id, run);
+    const counts = { applied: 0, conflict: 0, skipped: 0, failed: 0 };
+    for (const result of run.results)
+        counts[result.status] = (counts[result.status] ?? 0) + 1;
+    lines.push(`  applied:   ${counts.applied} · conflicts: ${counts.conflict} · skipped: ${counts.skipped} · failed: ${counts.failed}`);
+    console.log(lines.join("\n"));
+    if (run.status === "failed")
+        process.exitCode = 1;
+}
+export async function suggest(args) {
+    const planId = option(args, "--plan-id");
+    const planPath = option(args, "--plan");
+    if (!planId && !planPath) {
+        // Same legible guess as `apply <id>`: name the exact corrected command.
+        const positional = args.find((arg) => !arg.startsWith("-") && !isOptionValue(args, arg));
+        if (positional) {
+            throw new Error(`suggest takes the plan as a flag, not a positional. Try: fullstackgtm suggest --plan-id ${positional}`);
+        }
+        throw new Error("suggest requires --plan <path> or --plan-id <id>");
+    }
+    let plan;
+    if (planId) {
+        const stored = await createFilePlanStore().get(planId);
+        if (!stored)
+            throw new Error(`No stored plan with id ${planId}.`);
+        plan = stored.plan;
+    }
+    else {
+        plan = JSON.parse(readFileSync(resolve(process.cwd(), planPath), "utf8"));
+    }
+    const snapshot = await readSnapshot(args);
+    const suggestions = suggestValues(plan, snapshot);
+    const payload = { planId: planId ?? planPath, suggestions };
+    const outPath = option(args, "--out");
+    if (outPath)
+        writeFileSync(resolve(process.cwd(), outPath), `${JSON.stringify(payload, null, 2)}\n`);
+    if (args.includes("--json")) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+    }
+    if (suggestions.length === 0) {
+        console.log("No requires_human_* placeholder operations in this plan — nothing to suggest.");
+        return;
+    }
+    const byConfidence = {};
+    for (const s of suggestions)
+        byConfidence[s.confidence] = (byConfidence[s.confidence] ?? 0) + 1;
+    console.log(`Suggestions for ${suggestions.length} placeholder operation(s):\n`);
+    for (const s of suggestions) {
+        const marker = s.confidence === "high" ? "✓" : s.confidence === "low" ? "~" : s.confidence === "create" ? "+" : "✗";
+        console.log(`${marker} [${s.confidence}] ${s.operationId} ${s.objectName ?? s.objectId}`);
+        console.log(`    ${s.suggestedValue ? `→ ${s.suggestedValue}` : "(no suggestion)"} — ${s.reason}`);
+    }
+    console.log(`\n${Object.entries(byConfidence).map(([k, v]) => `${k}: ${v}`).join(" · ")}`);
+    if (planId && (byConfidence.high ?? 0) > 0 && !outPath) {
+        console.log(`\nChain it:\n  fullstackgtm suggest --plan-id ${planId} ${snapshotSourceHint(args)}--out suggestions.json\n  fullstackgtm plans approve ${planId} --values-from suggestions.json\n  fullstackgtm apply --plan-id ${planId} --provider <name>`);
+    }
+}
+function snapshotSourceHint(args) {
+    const provider = option(args, "--provider");
+    if (provider)
+        return `--provider ${provider} `;
+    const input = option(args, "--input");
+    if (input)
+        return `--input ${input} `;
+    return "";
+}

package/dist/cli/help.d.ts

@@ -0,0 +1,25 @@
+import type { Paint } from "./ui.ts";
+export declare function usage(): string;
+export type HelpEntry = {
+    summary: string;
+    phase: string;
+    synopsis: string[];
+    detail?: string;
+    options?: Array<[string, string]>;
+    seeAlso?: string[];
+};
+export declare const HELP: Record<string, HelpEntry>;
+export declare const BESPOKE_HELP: string[];
+export declare function shortUsage(): string;
+/**
+ * Interactive-terminal styling for the short front door: a dimmed one-line
+ * brand header (name · version · active profile), bold title and command
+ * names, cyan lifecycle-group titles. Never applied to piped output — the
+ * plain shortUsage() text stays byte-identical (and `capabilities` keeps
+ * deriving from the HELP table, which this never touches).
+ */
+export declare function stylizeShortUsage(text: string, p: Paint, info: {
+    version: string;
+    profile: string;
+}): string;
+export declare function commandHelp(command: string): string;