fullstackgtm 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -5,6 +5,45 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and the project adheres to [Semantic Versioning](https://semver.org/).
 The path to 1.0 is planned in [docs/roadmap-to-1.0.md](./docs/roadmap-to-1.0.md).
 
+## [0.19.0] — 2026-06-11
+
+Governed bulk writes, plus fixes from the 0.18 published-artifact verification.
+
+### Added
+
+- **`fullstackgtm bulk-update <account|contact|deal>`** — generic writes
+  through the same plan gate as everything else: `--where` filters (`=`,
+  `!=`, `~` substring, `:empty`/`:notempty`, `|` alternation) select records,
+  `--set`/`--archive`/`--create-task` define the change, and the result is a
+  dry-run patch plan needing explicit approval before `apply` — never a
+  direct write. `--require <field>=<value>` preconditions and
+  `--guard <object>:<where>:<none|some>` cross-record eligibility checks are
+  re-verified at apply time against the live CRM (mid-apply rechecks shrink
+  the audit→apply TOCTOU window); `--max-operations` caps blast radius.
+- Eval tool card teaches agents to encode eligibility conditions in filters
+  rather than hand-selecting record ids.
+
+### Fixed
+
+- `--help` no longer executes: every `market` subcommand now short-circuits
+  to usage before config loads, credential checks, or side effects
+  (`market capture --help` used to *run the capture* — live fetches and
+  manifest writes; `market axes --help` ran the analysis). Top-level
+  commands without bespoke help (`audit`, `snapshot`, `suggest`, …) print
+  usage on `--help` instead of executing (`audit --help` used to silently
+  run the sample audit).
+- `market report --format html` no longer crashes with a bare TypeError on
+  axes missing pole labels: `parseMarketConfig` now requires
+  `negativePole`/`positivePole` on every axis and says so.
+- The 0.18.0 entry below documented the axis shape with a `poles` field that
+  never existed; the real fields are `negativePole`/`positivePole` (entry
+  corrected in place).
+- `forcedToolCall` is now actually exported from the package root, as the
+  0.17.0 entry claimed.
+- MCP `fullstackgtm_market_worksheet`/`_observe` with no
+  `market.config.json` in the server cwd return a "run `fullstackgtm market
+  init`" hint instead of a raw ENOENT.
+
 ## [0.18.0] — 2026-06-11
 
 Axis discovery: earn a strategic 2×2 from the observations instead of
@@ -13,7 +52,7 @@ asserting one.
 ### Added
 
 - **Axes as config** — `axes` in `market.config.json`: each axis is a
-  claim-scoring rubric (`{ id, label, poles, rubric, status, claimScores }`,
+  claim-scoring rubric (`{ id, label, negativePole, positivePole, rubric, status, claimScores }`,
   null = axis doesn't apply to that claim); a vendor's position is the
   intensity-weighted mean (loud=1, quiet=½) of the claims it voices.
   `primaryAxes: [x, y]` picks the report's strategic map. Config validation

package/dist/bulkUpdate.d.ts

@@ -0,0 +1,37 @@
+import type { CanonicalGtmSnapshot, PatchPlan, PlanGuard } from "./types.ts";
+export type BulkUpdateOptions = {
+    objectType: "account" | "contact" | "deal";
+    /** raw --where expressions, AND-ed together; at least one is required */
+    where: string[];
+    /** canonical field → new value; one action only */
+    set?: Record<string, string>;
+    /** propose archive_record instead of field writes */
+    archive?: boolean;
+    /** propose create_task on each matched record with this subject/body text */
+    createTask?: string;
+    /** explicit preconditions (field=value), re-verified at apply time */
+    require?: string[];
+    /**
+     * plan-level guards, raw form "<objectType>:<where>[;<where>…]:<none|some>",
+     * re-evaluated against a fresh snapshot at apply time; failure aborts the
+     * entire plan
+     */
+    guard?: string[];
+    reason?: string;
+    /** refuse to build plans larger than this (default 500 operations) */
+    maxOperations?: number;
+};
+type WhereClause = {
+    field: string;
+    op: "eq" | "neq" | "contains" | "notcontains" | "empty" | "notempty";
+    value?: string;
+    raw: string;
+};
+export declare function parseWhere(expr: string): WhereClause;
+export declare function parseGuard(raw: string): PlanGuard;
+/** Ids of records matching a filter — used for apply-time filter re-verification. */
+export declare function eligibleIds(snapshot: CanonicalGtmSnapshot, objectType: BulkUpdateOptions["objectType"], where: string[]): Set<string>;
+/** Evaluate a plan guard against a snapshot. Returns null when satisfied, else a failure detail. */
+export declare function evaluateGuard(snapshot: CanonicalGtmSnapshot, guard: PlanGuard): string | null;
+export declare function buildBulkUpdatePlan(snapshot: CanonicalGtmSnapshot, options: BulkUpdateOptions): PatchPlan;
+export {};

package/dist/bulkUpdate.js

@@ -0,0 +1,315 @@
+/**
+ * Governed generic writes: `bulk-update` builds a dry-run patch plan from a
+ * filter over the canonical snapshot plus an action (field assignments, an
+ * archive directive, or a task to create). It NEVER writes — the plan flows
+ * through the same plans-approve → apply gate as audit plans.
+ *
+ * Safety model, in layers:
+ *  - every set_field captures the record's live value as `beforeValue`
+ *    (apply refuses the write if the written field drifted);
+ *  - every equality filter on a real record field becomes an automatic
+ *    PRECONDITION, re-verified at apply time (the plan's premise must still
+ *    hold — guards against drift on fields other than the one written);
+ *  - `--require field=value` adds explicit preconditions on top;
+ *  - all operations for one record share a groupId, so multi-field updates
+ *    are all-or-nothing per record.
+ *
+ * Filter grammar (each --where is AND-ed):
+ *   field=value     case-insensitive equality
+ *   field!=value    case-insensitive inequality
+ *   field~value     case-insensitive substring
+ *   field:empty     unset or empty string
+ *   field:notempty  set and non-empty
+ *
+ * Fields are canonical (ownerId, stage, closeDate, amount, domain, name,
+ * email, isClosed, accountId, …). Relational pseudo-fields are available in
+ * filters: deals and contacts get `account.name`, `account.domain`,
+ * `account.ownerId`, `account.contactCount`; accounts get `contactCount`
+ * and `openDealCount`.
+ */
+import { stableHash } from "./rules.js";
+const FIELD_PATTERN = "[a-zA-Z][a-zA-Z0-9_]*(?:\\.[a-zA-Z][a-zA-Z0-9_]*)?";
+export function parseWhere(expr) {
+    const empty = expr.match(new RegExp(`^(${FIELD_PATTERN}):(empty|notempty)$`));
+    if (empty)
+        return { field: empty[1], op: empty[2], raw: expr };
+    const neq = expr.match(new RegExp(`^(${FIELD_PATTERN})!=(.*)$`));
+    if (neq)
+        return { field: neq[1], op: "neq", value: neq[2], raw: expr };
+    const notContains = expr.match(new RegExp(`^(${FIELD_PATTERN})!~(.*)$`));
+    if (notContains)
+        return { field: notContains[1], op: "notcontains", value: notContains[2], raw: expr };
+    const contains = expr.match(new RegExp(`^(${FIELD_PATTERN})~(.*)$`));
+    if (contains)
+        return { field: contains[1], op: "contains", value: contains[2], raw: expr };
+    const eq = expr.match(new RegExp(`^(${FIELD_PATTERN})=(.*)$`));
+    if (eq)
+        return { field: eq[1], op: "eq", value: eq[2], raw: expr };
+    throw new Error(`Cannot parse --where "${expr}". Use field=value, field!=value, field~substring, field!~substring, field:empty, or field:notempty.`);
+}
+function fieldValue(view, field) {
+    const value = view[field];
+    if (value === undefined || value === null)
+        return "";
+    return String(value);
+}
+function matches(view, clause) {
+    const actual = fieldValue(view, clause.field).toLowerCase();
+    // `|` alternation: eq/contains match ANY alternative; neq/notcontains
+    // must hold against ALL alternatives.
+    const alternatives = (clause.value ?? "").toLowerCase().split("|");
+    switch (clause.op) {
+        case "eq":
+            return alternatives.some((a) => actual === a);
+        case "neq":
+            return alternatives.every((a) => actual !== a);
+        case "contains":
+            return alternatives.some((a) => actual.includes(a));
+        case "notcontains":
+            return alternatives.every((a) => !actual.includes(a));
+        case "empty":
+            return actual === "";
+        case "notempty":
+            return actual !== "";
+    }
+}
+const COLLECTIONS = {
+    account: "accounts",
+    contact: "contacts",
+    deal: "deals",
+};
+const RELATIONAL_FIELDS = ["account.name", "account.domain", "account.ownerId", "account.contactCount", "account.openDealStages"];
+/**
+ * Filterable fields per object type. Filters/requires/guards referencing any
+ * other field are rejected at plan time: a typo'd field silently evaluating
+ * to empty would make a ":none" guard pass vacuously — a safety assertion
+ * that never fires. Strictness turns typos into immediate, correctable
+ * errors.
+ */
+const VALID_FIELDS = {
+    account: new Set(["id", "crmId", "name", "domain", "industry", "ownerId", "employeeCount", "annualRevenue", "lastActivityAt", "lastSyncAt", "contactCount", "openDealCount", "openDealStages"]),
+    contact: new Set(["id", "crmId", "accountId", "firstName", "lastName", "email", "phone", "title", "ownerId", "lastSyncAt", ...RELATIONAL_FIELDS]),
+    deal: new Set(["id", "crmId", "accountId", "ownerId", "name", "amount", "currency", "stage", "closeDate", "dealType", "forecastCategory", "nextStep", "probability", "isClosed", "isWon", "lastActivityAt", "lastSyncAt", ...RELATIONAL_FIELDS]),
+};
+function assertValidFields(objectType, clauses, context) {
+    for (const clause of clauses) {
+        if (!VALID_FIELDS[objectType].has(clause.field)) {
+            throw new Error(`Unknown field "${clause.field}" in ${context} "${clause.raw}" for ${objectType}s. Valid fields: ${[...VALID_FIELDS[objectType]].join(", ")}.`);
+        }
+    }
+}
+/**
+ * Fields that are derived in the canonical model (no provider property to
+ * re-read at apply time) or relational — excluded from auto-preconditions.
+ */
+const NON_READABLE_FIELDS = new Set([
+    // derived in the canonical model — no provider property to re-read
+    "isClosed", "isWon", "forecastCategory", "probability", "lastActivityAt", "lastSyncAt",
+    // identity/bookkeeping fields — preconditions on these are meaningless
+    "id", "crmId", "provider", "identities",
+]);
+/** Build the filter-evaluation view: record fields + relational pseudo-fields. */
+function buildViews(snapshot, objectType) {
+    const accountsById = new Map(snapshot.accounts.map((a) => [a.id, a]));
+    const contactCountByAccount = new Map();
+    for (const c of snapshot.contacts) {
+        if (c.accountId)
+            contactCountByAccount.set(c.accountId, (contactCountByAccount.get(c.accountId) ?? 0) + 1);
+    }
+    const openDealCountByAccount = new Map();
+    const openDealStagesByAccount = new Map();
+    for (const d of snapshot.deals) {
+        if (d.accountId && !d.isClosed) {
+            openDealCountByAccount.set(d.accountId, (openDealCountByAccount.get(d.accountId) ?? 0) + 1);
+            const stages = openDealStagesByAccount.get(d.accountId) ?? [];
+            if (d.stage)
+                stages.push(d.stage);
+            openDealStagesByAccount.set(d.accountId, stages);
+        }
+    }
+    const records = snapshot[COLLECTIONS[objectType]];
+    return records.map((record) => {
+        const view = { ...record };
+        if (objectType === "account") {
+            view.contactCount = contactCountByAccount.get(String(record.id)) ?? 0;
+            view.openDealCount = openDealCountByAccount.get(String(record.id)) ?? 0;
+            view.openDealStages = (openDealStagesByAccount.get(String(record.id)) ?? []).join(",");
+        }
+        else {
+            const account = record.accountId ? accountsById.get(String(record.accountId)) : undefined;
+            view["account.name"] = account?.name ?? "";
+            view["account.domain"] = account?.domain ?? "";
+            view["account.ownerId"] = account?.ownerId ?? "";
+            view["account.contactCount"] = account ? (contactCountByAccount.get(account.id) ?? 0) : 0;
+            view["account.openDealStages"] = account ? (openDealStagesByAccount.get(account.id) ?? []).join(",") : "";
+        }
+        return { record, view };
+    });
+}
+export function parseGuard(raw) {
+    const first = raw.indexOf(":");
+    const last = raw.lastIndexOf(":");
+    if (first === -1 || last === first) {
+        throw new Error(`Cannot parse --guard "${raw}". Use <account|contact|deal>:<where>[;<where>…]:<none|some>.`);
+    }
+    const objectType = raw.slice(0, first);
+    const expect = raw.slice(last + 1);
+    const where = raw.slice(first + 1, last).split(";").map((s) => s.trim()).filter(Boolean);
+    if (!["account", "contact", "deal"].includes(objectType) || !["none", "some"].includes(expect) || where.length === 0) {
+        throw new Error(`Cannot parse --guard "${raw}". Use <account|contact|deal>:<where>[;<where>…]:<none|some>.`);
+    }
+    // validate eagerly at plan time: a typo'd guard must fail loudly, never
+    // pass vacuously at apply time
+    assertValidFields(objectType, where.map(parseWhere), "--guard");
+    return { objectType: objectType, where, expect: expect, description: raw };
+}
+/** Ids of records matching a filter — used for apply-time filter re-verification. */
+export function eligibleIds(snapshot, objectType, where) {
+    const clauses = where.map(parseWhere);
+    const views = buildViews(snapshot, objectType);
+    return new Set(views.filter(({ view }) => clauses.every((c) => matches(view, c))).map(({ record }) => String(record.id)));
+}
+/** Evaluate a plan guard against a snapshot. Returns null when satisfied, else a failure detail. */
+export function evaluateGuard(snapshot, guard) {
+    const clauses = guard.where.map(parseWhere);
+    const views = buildViews(snapshot, guard.objectType);
+    const matchCount = views.filter(({ view }) => clauses.every((c) => matches(view, c))).length;
+    const ok = guard.expect === "none" ? matchCount === 0 : matchCount > 0;
+    if (ok)
+        return null;
+    return `Guard failed: expected ${guard.expect === "none" ? "no" : "at least one"} ${guard.objectType}(s) matching [${guard.where.join(" AND ")}], found ${matchCount}.`;
+}
+export function buildBulkUpdatePlan(snapshot, options) {
+    const maxOperations = options.maxOperations ?? 500;
+    if (options.where.length === 0) {
+        throw new Error("bulk-update requires at least one --where filter — refusing to build an unscoped mass write.");
+    }
+    const hasSet = options.set && Object.keys(options.set).length > 0;
+    const actions = [hasSet, options.archive, options.createTask !== undefined].filter(Boolean).length;
+    if (actions !== 1) {
+        throw new Error("bulk-update needs exactly one action: --set <field>=<value> (repeatable), --archive, or --create-task <text>.");
+    }
+    const clauses = options.where.map(parseWhere);
+    assertValidFields(options.objectType, clauses, "--where");
+    const WRITABLE_BLOCKLIST = new Set(["id", "crmId", "contactCount", "openDealCount", "openDealStages"]);
+    for (const field of Object.keys(options.set ?? {})) {
+        if (!VALID_FIELDS[options.objectType].has(field) || WRITABLE_BLOCKLIST.has(field) || field.includes(".")) {
+            throw new Error(`Cannot --set "${field}" on ${options.objectType}s — not a writable canonical field.`);
+        }
+    }
+    const views = buildViews(snapshot, options.objectType);
+    const matched = views.filter(({ view }) => clauses.every((c) => matches(view, c)));
+    if (matched.length > maxOperations) {
+        throw new Error(`Filter matched ${matched.length} ${COLLECTIONS[options.objectType]} — above the ${maxOperations}-record safety cap. Narrow the --where filter or raise --max-operations explicitly.`);
+    }
+    // Preconditions: explicit --require, plus every equality filter on a real
+    // (re-readable, non-relational) field. The premise the plan was built on
+    // is re-verified per record at apply time.
+    const writtenFields = new Set(Object.keys(options.set ?? {}));
+    const preconditionSpecs = [];
+    for (const raw of options.require ?? []) {
+        const clause = parseWhere(raw);
+        if (clause.op !== "eq" || clause.field.includes(".") || (clause.value ?? "").includes("|")) {
+            throw new Error(`--require must be a direct single-value field equality (field=value), got "${raw}".`);
+        }
+        assertValidFields(options.objectType, [clause], "--require");
+        preconditionSpecs.push({ field: clause.field, expectedValue: clause.value ?? "" });
+    }
+    for (const clause of clauses) {
+        if (clause.op !== "eq")
+            continue;
+        if ((clause.value ?? "").includes("|"))
+            continue; // alternations are not single-value preconditions
+        if (clause.field.includes(".") || NON_READABLE_FIELDS.has(clause.field))
+            continue;
+        if (writtenFields.has(clause.field))
+            continue; // beforeValue already guards it
+        if (preconditionSpecs.some((p) => p.field === clause.field))
+            continue;
+        preconditionSpecs.push({ field: clause.field, expectedValue: clause.value ?? "" });
+    }
+    const whereText = options.where.join(" AND ");
+    const action = options.archive
+        ? `archive`
+        : options.createTask !== undefined
+            ? `create task "${options.createTask}"`
+            : `set ${Object.entries(options.set).map(([k, v]) => `${k}=${v}`).join(", ")}`;
+    const reason = options.reason ?? `bulk-update: ${action} where ${whereText}`;
+    const operations = [];
+    for (const { record } of matched) {
+        const objectId = String(record.id);
+        const groupId = `grp_${options.objectType}_${objectId}`;
+        const preconditions = preconditionSpecs.map((p) => ({
+            field: p.field,
+            // expected value is the record's CURRENT canonical value, not the
+            // filter literal — preserves casing/format the provider will echo back
+            expectedValue: record[p.field] ?? p.expectedValue,
+        }));
+        const shared = {
+            objectType: options.objectType,
+            objectId,
+            reason,
+            approvalRequired: true,
+            sourceRuleOrPolicy: "bulk-update",
+            ...(preconditions.length > 0 ? { preconditions } : {}),
+            groupId,
+        };
+        if (options.archive) {
+            operations.push({
+                ...shared,
+                id: `op_${stableHash(`bulk-archive:${options.objectType}:${objectId}:${whereText}`)}`,
+                operation: "archive_record",
+                beforeValue: null,
+                afterValue: null,
+                riskLevel: "high",
+                rollback: "Archived records can be restored from the provider's recycle bin within its retention window.",
+            });
+            continue;
+        }
+        if (options.createTask !== undefined) {
+            operations.push({
+                ...shared,
+                id: `op_${stableHash(`bulk-task:${options.objectType}:${objectId}:${options.createTask}`)}`,
+                operation: "create_task",
+                field: "follow_up_task",
+                beforeValue: null,
+                afterValue: options.createTask,
+                riskLevel: "low",
+                rollback: "Delete the created task.",
+            });
+            continue;
+        }
+        for (const [field, value] of Object.entries(options.set)) {
+            operations.push({
+                ...shared,
+                id: `op_${stableHash(`bulk-set:${options.objectType}:${objectId}:${field}:${value}`)}`,
+                operation: "set_field",
+                field,
+                beforeValue: record[field] ?? null,
+                afterValue: value,
+                riskLevel: "medium",
+                rollback: `Set ${field} back to ${JSON.stringify(record[field] ?? null)}.`,
+            });
+        }
+    }
+    const guards = (options.guard ?? []).map(parseGuard);
+    // guards must hold at plan time too — building a plan whose guard already
+    // fails is a footgun, surface it immediately
+    for (const guard of guards) {
+        const failure = evaluateGuard(snapshot, guard);
+        if (failure)
+            throw new Error(`${failure} The guard already fails against the current snapshot — the plan would never apply.`);
+    }
+    return {
+        id: `patch_plan_${stableHash(`bulk:${snapshot.provider}:${snapshot.generatedAt}:${whereText}:${action}:${operations.length}`)}`,
+        title: `Bulk update: ${options.objectType}s where ${whereText}`,
+        createdAt: snapshot.generatedAt,
+        status: operations.length > 0 ? "needs_approval" : "draft",
+        dryRun: true,
+        summary: `${matched.length} ${COLLECTIONS[options.objectType]} matched (${whereText}); ${operations.length} proposed dry-run operations (${action}).${guards.length > 0 ? ` ${guards.length} apply-time guard(s).` : ""}`,
+        findings: [],
+        operations,
+        filter: { objectType: options.objectType, where: options.where },
+        ...(guards.length > 0 ? { guards } : {}),
+    };
+}

package/dist/cli.js

@@ -24,6 +24,7 @@ import { buildWorksheet, classifyMarket } from "./marketClassify.js";
 import { marketMapToHtml, marketMapToMarkdown } from "./marketReport.js";
 import { DEFAULT_RUBRIC, detectProviderFromKey, extractInsightsLlm, parseRubric, resolveLlmCredential, scoreCallLlm, validateLlmKey, } from "./llm.js";
 import { resolveRecord } from "./resolve.js";
+import { buildBulkUpdatePlan } from "./bulkUpdate.js";
 import { suggestValues } from "./suggest.js";
 function usage() {
     return `FullStackGTM — audit GTM data across providers, propose reviewable patch plans,
@@ -74,6 +75,18 @@ Usage:
                                                against the stored capture it cites before it's accepted — then
                                                compute deterministic front states and drift, render the field
                                                report. refresh = capture → classify → drift → report in one step
+  fullstackgtm bulk-update <account|contact|deal> --where <expr> [--where …] (--set <field>=<value> [--set …] | --archive | --create-task <text>) [--require <field>=<value> …] [--guard <object>:<where>[;<where>]:<none|some> …] [source options] [--save] [--json] [--out <path>]
+                                               governed generic writes: filter the snapshot
+                                               (field=value, field!=value, field~substr, field!~substr,
+                                               field:empty, field:notempty, '|' = any-of; canonical fields
+                                               like ownerId, stage, closeDate, amount; relational
+                                               pseudo-fields account.name/domain/ownerId/contactCount/
+                                               openDealStages on deals and contacts, contactCount/
+                                               openDealCount/openDealStages on accounts) into a dry-run
+                                               patch plan. The full filter is re-verified per record at
+                                               apply time (incl. mid-apply rechecks); equality filters
+                                               double as preconditions; per-record ops apply
+                                               all-or-nothing; guards assert cross-record conditions.
   fullstackgtm suggest --plan-id <id> | --plan <path>  [source options] [--json] [--out <path>]
                                                derive values for requires_human_* placeholders
                                                from snapshot evidence, with confidence + reasons
@@ -751,7 +764,9 @@ function buildCallPlan(parsed, deal, proposed, current, extraNextSteps) {
 async function marketCommand(args) {
     const [subcommand, ...rest] = args;
     const configPath = () => resolve(process.cwd(), option(rest, "--config") ?? "market.config.json");
-    if (!subcommand || subcommand === "--help") {
+    // Catch --help anywhere before loadMarketConfig/credential checks run —
+    // several subcommands (capture, refresh) have side effects on bare invocation.
+    if (!subcommand || subcommand === "--help" || subcommand === "-h" || rest.includes("--help") || rest.includes("-h")) {
         console.log(`Usage:
 market init --category <name> [--out <path>]   write a starter market.config.json
 market capture [--config <path>] [--run <label>]
@@ -1001,6 +1016,51 @@ async function resolveCommand(args) {
     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.
+ */
+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"),
+        createTask: option(rest, "--create-task") ?? undefined,
+        require: repeatedOption(rest, "--require"),
+        guard: repeatedOption(rest, "--guard"),
+        reason: option(rest, "--reason") ?? undefined,
+        maxOperations: numericOption(rest, "--max-operations"),
+    });
+    const out = option(rest, "--out");
+    if (out) {
+        writeFileSync(resolve(process.cwd(), out), `${JSON.stringify(plan, null, 2)}\n`);
+    }
+    if (rest.includes("--save")) {
+        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 (rest.includes("--json")) {
+        console.log(JSON.stringify(plan, null, 2));
+    }
+    else {
+        console.log(patchPlanToMarkdown(plan));
+    }
+}
 async function suggest(args) {
     const planId = option(args, "--plan-id");
     const planPath = option(args, "--plan");
@@ -1710,6 +1770,13 @@ export async function runCli(argv) {
         console.log(readPackageInfo().version);
         return;
     }
+    // Commands without bespoke help fall back to the top-level usage on --help
+    // instead of executing (audit used to silently run the sample audit).
+    // call/market/bulk-update print their own richer help.
+    if (!["call", "market", "bulk-update"].includes(command) && (args.includes("--help") || args.includes("-h"))) {
+        console.log(usage());
+        return;
+    }
     if (command === "login") {
         await login(args);
         return;
@@ -1750,6 +1817,10 @@ export async function runCli(argv) {
         await resolveCommand(args);
         return;
     }
+    if (command === "bulk-update") {
+        await bulkUpdateCommand(args);
+        return;
+    }
     if (command === "market") {
         await marketCommand(args);
         return;

package/dist/connector.d.ts

@@ -18,6 +18,12 @@ export type ApplyPatchPlanOptions = {
      * `readField`.
      */
     checkConflicts?: boolean;
+    /**
+     * For plans carrying a filter or guards: re-run the snapshot checks after
+     * the first applied write and then every N applied writes, so a record
+     * edited mid-apply is conflicted out instead of overwritten. Default 25.
+     */
+    recheckEvery?: number;
 };
 /**
  * Apply an approved subset of a patch plan through a connector.