@pitcher/cli-scripts 2.16.0 → 2.17.1

package/README.md

@@ -12,7 +12,7 @@ p command --help
 
 ## MCP server
 
-Run `p mcp` to start a stdio [MCP](https://modelcontextprotocol.io) server that exposes this CLI's commands as tools to an MCP-capable host (Claude Desktop, Claude Code, etc). It wraps 121 tools, one per CLI `run*` function: every command above (including `dsr create` + `dsr bind-landing` and the full `ld` surface) except the five local `scaffold` subcommands (which just print/write a starter file and make no request). `dev-sync` is exposed as a one-shot sync only; the continuous `watch` mode is not available as a tool.
+Run `p mcp` to start a stdio [MCP](https://modelcontextprotocol.io) server that exposes this CLI's commands as tools to an MCP-capable host (Claude Desktop, Claude Code, etc). It wraps 123 tools, one per CLI `run*` function: every command above (including `dsr create`/`update`/`delete`/`bind-landing` and the full `ld` surface) except the five local `scaffold` subcommands (which just print/write a starter file and make no request). `dev-sync` is exposed as a one-shot sync only; the continuous `watch` mode is not available as a tool.
 
 ```bash
 p mcp
@@ -55,7 +55,7 @@ yarn mcpb:pack        # → pitcher.mcpb (validated + packed)
 
 Install by double-clicking `pitcher.mcpb` (or Settings → Extensions → Install Extension). Claude Desktop prompts for the API key (stored in the OS keychain) and organization; both are editable afterward, so switching orgs needs no reinstall.
 
-The bundle reuses the same server as `p mcp` but registers a **content-tool subset (118)** — it omits the developer-only `publish-app` and `dev-sync`/`dev-sync-revert`. The `organization` field accepts a subdomain (`acme`), a bare hostname (`acme.my.pitcher.com`), or a full `https://` URL. Build details (esbuild single-file, version injection) live in `mcpb/` and `CLAUDE.md`.
+The bundle reuses the same server as `p mcp` but registers a **content-tool subset (120)** — it omits the developer-only `publish-app` and `dev-sync`/`dev-sync-revert`. The `organization` field accepts a subdomain (`acme`), a bare hostname (`acme.my.pitcher.com`), or a full `https://` URL. Build details (esbuild single-file, version injection) live in `mcpb/` and `CLAUDE.md`.
 
 This section is a reference only. For app-development conventions (modules, settings, mount points, SFDC), see the `pitcher-apps` skill, not this README.
 
@@ -506,7 +506,11 @@ p metadata-template upsert --instance-id 01... --sections-file ./schema.json --a
 
 ## To run the `dsr` command:
 
-Create and share a Digital Sales Room (a canvas share link) and get a link back in one command. Three subcommands: `create` (build + share, with optional landing-page binding), `bind-landing` (bind/unbind a landing template on an existing share), and `scaffold` (print a starter `{source,security,landing}` spec for `--config-file`).
+Create and share a Digital Sales Room (a canvas share link) and get a link back in one command. Five subcommands: `create` (build + share, with optional landing-page binding), `update` (change or clear the access settings of an existing share), `delete` (revoke a share), `bind-landing` (bind/unbind a landing template on an existing share), and `scaffold` (print a starter `{source,security,landing}` spec for `--config-file`).
+
+The create endpoint is a **get-or-create**: sharing an already-shared canvas returns the existing link and updates only the fields you pass. That is deliberate (it mirrors Admin's "Create link once / Copy link after"), but it means `create` with individual flags can never *remove* a value — omitting a flag leaves the stored value alone. Use `update` for that, and `--clear <field>` to remove one.
+
+A `--config-file` spec is different: its `security` block is sent as written, so the `dsr scaffold` starter's `auth_strategy: any_email`, `valid_until: null` and empty lists would all be written onto an existing share. That is why `--config-file` defaults to `--if-exists error` (individual flags default to `return`); pass `--if-exists return` to apply a spec to an already-shared canvas on purpose.
 
 ```bash
 # simplest — email-gated link (server default auth_strategy=any_email)
@@ -520,11 +524,34 @@ p dsr create --instance-id 01... --sharebox-file-ids 01A,01B --account-id 01...
 # bind/unbind a landing template on an existing share
 p dsr bind-landing --id 01... --landing-template-id 01...
 p dsr bind-landing --id 01... --landing-template-id none
+# refuse to reuse an existing share instead of silently returning it
+p dsr create --canvas-id 01... --if-exists error
+# change an existing share — only the flags you pass are sent
+p dsr update --id 01... --valid-until 2026-12-01T00:00:00Z
+p dsr update --id 01... --auth-strategy specified_domains --allowed-domains acme.com
+# REMOVE a value (this is the only way — omitting the flag is a no-op)
+p dsr update --id 01... --clear valid-until
+p dsr update --id 01... --clear allowed-emails --clear allowed-domains
+# revoke the link entirely (the canvas is kept)
+p dsr delete --id 01...
 # scaffold a spec for --config-file
 p dsr scaffold --out share.json
 ```
 
-Creating needs a share-capable key; **binding a landing page currently needs an editor key** (PIT-7525 will open it to reps for their own DSRs) — a denied bind returns the link with a warning. Discover landing template IDs via `p dsr-landing list`.
+`update` PATCHes `/core/api/protected/shared-links/{id}`, which distinguishes an **absent** key from an **explicit null** — so omitting `--valid-until` leaves the stored expiry exactly as it is, and `--clear valid-until` is what resets it. `--clear` is repeatable and accepts `valid-until`, `allowed-emails`, `allowed-domains` (the CLI sends `null` for the first and `[]` for the lists, matching what each field's server schema accepts). An empty `--allowed-emails`/`--allowed-domains` is rejected on both `create` and `update`, because `""` from an unset shell variable would otherwise be sent as `[]` and wipe the stored list. `--clear` is a separate flag rather than an in-value sentinel such as `--valid-until ""` because an empty string is something a script can produce by accident from an unset variable, and `none` is already a real `--auth-strategy` value. `tags` and `--allow-download` are **create-time only** — the PATCH surface does not accept them, and `--clear` says so rather than dropping them silently.
+
+**Clearing an allow-list is refused while a strategy that needs it is in force**, because an empty allow-list denies every recipient rather than admitting them — the clear would brick the link, not open it. `specified_emails`/`verified_emails` need `allowed-emails`; `specified_domains`/`verified_domains` need `allowed-domains`. The check covers a strategy passed in the same call **and** the one already stored on the share (read from the public `GET /core/api/shared-links/{id}/config`, since the PATCH surface has no GET). If that read fails the update still goes through, with a warning saying the check did not run. Two ways out:
+
+```bash
+# relax the gate in the same call (or in an earlier one)
+p dsr update --id 01... --auth-strategy any_email --clear allowed-emails
+# or just replace the list instead of clearing it
+p dsr update --id 01... --allowed-emails new@acme.com
+```
+
+`create` returns the share as `{ id, type, file, canvas, instance, organization, status, url, short_url }` — **`url` is the full link; there is no `full_url` field.**
+
+Creating, updating and deleting need a share-capable key (`canvas.share` on the link's own instance when `enable_granular_permissions` is on); **binding a landing page currently needs an editor key** (PIT-7525 will open it to reps for their own DSRs) — a denied bind returns the link with a warning. Discover landing template IDs via `p dsr-landing list`.
 
 ## To run the `ld` command:
 

package/dist/src/commands/analytics.d.ts

@@ -83,8 +83,9 @@ export interface AnalyticsUsersOpts extends CommonOpts {
  *   CLI does not expose it.)
  * - `--stats` → `GET /analytics/users/stats`: requires `start_date`/`end_date`
  *   (defaulted via `withDefaultWindow`), and `type` is ALWAYS forced to
- *   `'active-users'` — the wire default `type=all` returns a shape with no
- *   `.items`, which would otherwise silently shape to an empty row set. The
+ *   `'active-users'` — `type` is required on the wire and rejected with a 400
+ *   unless it names a supported statistic (it used to default to a nonexistent
+ *   `all`, which 500'd; see `routes/users.ts` USER_STATS_TYPES). The
  *   page-size param on this route is the camelCase `pageSize` (verified
  *   `users.ts:230`) — the one route in the CLI that reads camelCase on the wire.
  */

package/dist/src/commands/analytics.js

@@ -146,8 +146,9 @@ export async function runAnalyticsPopularity(opts, deps = {}) {
  *   CLI does not expose it.)
  * - `--stats` → `GET /analytics/users/stats`: requires `start_date`/`end_date`
  *   (defaulted via `withDefaultWindow`), and `type` is ALWAYS forced to
- *   `'active-users'` — the wire default `type=all` returns a shape with no
- *   `.items`, which would otherwise silently shape to an empty row set. The
+ *   `'active-users'` — `type` is required on the wire and rejected with a 400
+ *   unless it names a supported statistic (it used to default to a nonexistent
+ *   `all`, which 500'd; see `routes/users.ts` USER_STATS_TYPES). The
  *   page-size param on this route is the camelCase `pageSize` (verified
  *   `users.ts:230`) — the one route in the CLI that reads camelCase on the wire.
  */

package/dist/src/commands/dsr.d.ts

@@ -31,6 +31,27 @@ export interface DsrCreateOpts extends CommonOpts {
     landingTemplateId?: string;
     landingContext?: string;
     configFile?: string;
+    ifExists?: string;
 }
+export declare const IF_EXISTS_MODES: readonly ["return", "error"];
+export type IfExistsMode = (typeof IF_EXISTS_MODES)[number];
 export declare function runDsrCreate(opts: DsrCreateOpts, deps?: DsrDeps): Promise<Envelope<unknown>>;
+export declare const CLEARABLE_UPDATE_FIELDS: readonly ["valid-until", "allowed-emails", "allowed-domains"];
+export type ClearableUpdateField = (typeof CLEARABLE_UPDATE_FIELDS)[number];
+export interface DsrUpdateOpts extends CommonOpts {
+    id?: string;
+    instanceId?: string;
+    authStrategy?: string;
+    allowedEmails?: string[];
+    allowedDomains?: string[];
+    validUntil?: string;
+    allowForward?: boolean;
+    clear?: string[];
+}
+export declare function assembleUpdateBody(opts: DsrUpdateOpts): Record<string, unknown>;
+export declare function runDsrUpdate(opts: DsrUpdateOpts, deps?: DsrDeps): Promise<Envelope<unknown>>;
+export declare function runDsrDelete(opts: CommonOpts & {
+    id?: string;
+    instanceId?: string;
+}, deps?: DsrDeps): Promise<Envelope<unknown>>;
 export declare function createDsrCommand(): Command;

package/dist/src/commands/dsr.js

@@ -156,14 +156,66 @@ function resolveLandingBody(opts, cfgLanding) {
         b.landing_page_context = parseJsonObject(opts.landingContext, 'landing-context');
     return b;
 }
+// ── create collision policy (PIT-7521) ──────────────────────────────────────
+// `POST /core/api/protected/shared-links` is a documented get-or-create ("Shared link
+// created successfully or existing link returned"): a second create for the same canvas
+// hands back the link that already exists, mirroring Admin's "Create link once / Copy
+// link after". `--if-exists return` keeps exactly that and stays the default for individual
+// flags, so nothing scripted with them changes. `--if-exists error` asks for honest create
+// semantics, which the CLI gets from a preflight GET against Django's `shared-links/canvas/{id}`
+// — the same endpoint the server's get-or-create consults. Advisory, not atomic: the server has
+// no create-only mode, so a link minted between the GET and the POST is still returned.
+//
+// `--config-file` defaults to `error` instead. A spec's `security` block is sent verbatim, and
+// the `dsr scaffold` starter fills it with `auth_strategy: any_email`, `[]` lists and
+// `valid_until: null`. Against an existing share the POST writes every key present, so a
+// restricted, time-boxed link would silently open to any email and never expire. Applying a
+// spec to an existing share has to be asked for with `--if-exists return`.
+export const IF_EXISTS_MODES = ['return', 'error'];
+function normalizeIfExists(raw, fromConfigFile) {
+    if (raw === undefined)
+        return fromConfigFile ? 'error' : 'return';
+    const mode = raw.trim().toLowerCase(); // same normalisation as --clear, so the two flags agree
+    if (!IF_EXISTS_MODES.includes(mode))
+        throw createCliError('VALIDATION', `--if-exists must be one of: ${IF_EXISTS_MODES.join(', ')} (got "${raw}")`);
+    return mode;
+}
+async function assertNoExistingShare(client, canvasId, fromConfigFile) {
+    let existing;
+    try {
+        const res = await client.get(`/api/v1/shared-links/canvas/${encodeURIComponent(canvasId)}`);
+        existing = (res.data ?? null);
+    }
+    catch (e) {
+        // 404 is the ONLY answer that means "not shared yet". Anything else (403, 500, a dead
+        // socket) leaves the guard UNRESOLVED, and an unresolved guard must fail rather than
+        // wave the create through as if the canvas were unshared.
+        if (toCliError(e).code === 'NOT_FOUND')
+            return;
+        throw e;
+    }
+    // Any 2xx means a link exists, whatever the body looks like — `id` is only used to name
+    // it in the message, never to decide whether to fail.
+    const known = existing?.id ? ` ${existing.id}` : '';
+    throw createCliError('CONFLICT', `canvas ${canvasId} already has shared link${known} — change it with \`p dsr update${existing?.id ? ` --id ${existing.id}` : ''}\`, or pass --if-exists return to reuse it${fromConfigFile ? ' (the security block of the spec is then written onto the existing share as-is)' : ''}`);
+}
 export async function runDsrCreate(opts, deps = {}) {
     try {
+        const fromConfigFile = opts.configFile !== undefined;
+        const ifExists = normalizeIfExists(opts.ifExists, fromConfigFile);
         const { body, landing: cfgLanding } = assembleSpec(opts);
+        // flags only: a --config-file spec is guarded by its --if-exists error default instead
+        assertNoEmptyLists(opts, (flag) => `omit it, or remove a stored list with \`p dsr update --clear ${flag}\``);
         assertCreateBody(body, opts.instanceId);
         const landingBody = resolveLandingBody(opts, cfgLanding); // parse/validate context BEFORE the network call
         // bind against the same instance the share was created in — a config-file source.instance_id must reach the PUT too
         const effectiveInstanceId = body.instance_id ?? opts.instanceId;
         const client = clientFor(opts, deps);
+        // only the existing-canvas source can collide: --sharebox-file-ids mints a NEW canvas
+        // every time, so there is never a prior link to find
+        const sourceCanvasId = body.canvas_id;
+        if (ifExists === 'error' && sourceCanvasId)
+            await assertNoExistingShare(client, sourceCanvasId, fromConfigFile);
         const res = await client.post(ENDPOINT, body);
         const share = res.data;
         if (!landingBody)
@@ -183,6 +235,178 @@ export async function runDsrCreate(opts, deps = {}) {
         return fail(toCliError(e));
     }
 }
+// ── explicit clear (PIT-7521) ───────────────────────────────────────────────
+// `dsr update` sends ONLY the fields the caller named, so the server's `hasField()`
+// gate leaves every other column alone. That makes "omit the flag" a no-op — correct,
+// but it leaves no way to REMOVE a value that is already set. `--clear <field>` is
+// that way, and it is a separate flag rather than an in-value sentinel
+// (`--valid-until ""` / `--valid-until none`) on purpose:
+//   * an empty string can be produced by ACCIDENT — `--valid-until "$MAYBE_UNSET"` is
+//     ordinary shell, and under a sentinel rule it would silently wipe a live expiry
+//     instead of being the no-op the author meant;
+//   * `none` is already a legal `--auth-strategy` value, so one sentinel would mean
+//     "clear" on one flag and a real value on its neighbour;
+//   * `--clear` is enumerable, so naming a field that CANNOT be cleared fails loudly
+//     instead of being silently dropped into a body the server ignores.
+// `dsr bind-landing --landing-template-id none` keeps its own sentinel: that is
+// pre-existing public behaviour on a different endpoint, not a new choice.
+export const CLEARABLE_UPDATE_FIELDS = ['valid-until', 'allowed-emails', 'allowed-domains'];
+// flag name → wire key + the flag it would contradict
+const CLEARABLE = {
+    'valid-until': { wire: 'valid_until', opt: 'validUntil' },
+    'allowed-emails': { wire: 'allowed_emails', opt: 'allowedEmails' },
+    'allowed-domains': { wire: 'allowed_domains', opt: 'allowedDomains' },
+};
+// Set on create, never on PATCH: `tags` lands on the ShareBox canvas and `allow_download`
+// on canvas metadata, neither of which the shared-links PATCH schema accepts.
+const CREATE_ONLY_FIELDS = new Set(['tags', 'allow-download']);
+// The CLEAR value is per-field and the two shapes are NOT interchangeable. Server-side
+// `valid_until` is `z.string().datetime().nullable()`, so JSON null clears it;
+// `allowed_emails`/`allowed_domains` are plain optional arrays with no `.nullable()`,
+// so a null there is a 400 and an empty array is their clear. Built fresh per call —
+// a shared `[]` literal would be one mutable array handed to every request body.
+function clearValueFor(field) {
+    return field === 'valid-until' ? null : [];
+}
+function normalizeClearFields(raw) {
+    const out = [];
+    for (const entry of raw ?? []) {
+        // accept the flag spelling (valid-until) and the wire spelling (valid_until)
+        const name = entry.trim().toLowerCase().replace(/_/g, '-');
+        if (CREATE_ONLY_FIELDS.has(name))
+            throw createCliError('VALIDATION', `"${name}" is set at create time only — the shared-links PATCH surface does not accept it, so it cannot be cleared`);
+        if (!CLEARABLE_UPDATE_FIELDS.includes(name))
+            throw createCliError('VALIDATION', `--clear must be one of: ${CLEARABLE_UPDATE_FIELDS.join(', ')} (got "${entry}")`);
+        out.push(name);
+    }
+    return out;
+}
+// Mirrors the server's refine, which only fires when auth_strategy is in the body. A PATCH that
+// clears a list without naming a strategy is checked against the STORED strategy in runDsrUpdate.
+function assertUpdateAuth(body) {
+    const strat = body.auth_strategy;
+    if (strat === undefined)
+        return;
+    if (!AUTH_STRATEGIES.includes(strat))
+        throw createCliError('VALIDATION', `--auth-strategy must be one of: ${AUTH_STRATEGIES.join(', ')}`);
+    const emails = body.allowed_emails;
+    const domains = body.allowed_domains;
+    if ((strat === 'specified_emails' || strat === 'verified_emails') && !(emails && emails.length))
+        throw createCliError('VALIDATION', `--allowed-emails is required for --auth-strategy ${strat}`);
+    if ((strat === 'specified_domains' || strat === 'verified_domains') && !(domains && domains.length))
+        throw createCliError('VALIDATION', `--allowed-domains is required for --auth-strategy ${strat}`);
+}
+// `parseTags('')` is `[]`, not undefined, so `--allowed-emails "$MAYBE_UNSET"` would reach the
+// server as an empty array — which is precisely the wire shape that CLEARS the list. That makes
+// an unset shell variable indistinguishable from a deliberate removal, the accident `--clear`
+// exists to rule out. So an empty list is rejected on `update` AND on `create` (whose get-or-create
+// POST writes the [] over an existing share's list), and `--clear` stays the ONE way to remove a
+// value. (Same reasoning covers an MCP caller passing `allowedEmails: []`.)
+function assertNoEmptyLists(opts, hint = (flag) => `use \`--clear ${flag}\` to remove the list`) {
+    const lists = [
+        ['allowed-emails', opts.allowedEmails],
+        ['allowed-domains', opts.allowedDomains],
+    ];
+    for (const [flag, value] of lists) {
+        if (Array.isArray(value) && value.length === 0)
+            throw createCliError('VALIDATION', `--${flag} was empty — ${hint(flag)}`);
+    }
+}
+// A stored strategy that REQUIRES a list, and the list it requires.
+const STRATEGY_REQUIRES = {
+    specified_emails: 'allowed_emails',
+    verified_emails: 'allowed_emails',
+    specified_domains: 'allowed_domains',
+    verified_domains: 'allowed_domains',
+};
+function clearedListFields(body) {
+    return ['allowed_emails', 'allowed_domains'].filter((k) => Array.isArray(body[k]) && body[k].length === 0);
+}
+// The protected PATCH surface has no GET, but the PUBLIC pre-auth config the sharing page reads
+// does expose auth_strategy. Returns null when it cannot be resolved — see the call site for why
+// that is a warning here and a hard failure in the --if-exists preflight.
+async function readStoredAuthStrategy(client, id) {
+    try {
+        const res = await client.get(`/core/api/shared-links/${encodeURIComponent(id)}/config`);
+        const strategy = res.data?.auth_strategy;
+        return typeof strategy === 'string' ? strategy : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function assembleUpdateBody(opts) {
+    const cleared = normalizeClearFields(opts.clear);
+    assertNoEmptyLists(opts);
+    for (const field of cleared) {
+        if (opts[CLEARABLE[field].opt] !== undefined)
+            throw createCliError('VALIDATION', `--clear ${field} conflicts with --${field}: pass one or the other`);
+    }
+    const body = {};
+    if (opts.authStrategy !== undefined)
+        body.auth_strategy = opts.authStrategy;
+    if (opts.allowedEmails !== undefined)
+        body.allowed_emails = opts.allowedEmails;
+    if (opts.allowedDomains !== undefined)
+        body.allowed_domains = opts.allowedDomains;
+    if (opts.validUntil !== undefined)
+        body.valid_until = opts.validUntil;
+    if (opts.allowForward !== undefined)
+        body.allow_forward = opts.allowForward;
+    for (const field of cleared)
+        body[CLEARABLE[field].wire] = clearValueFor(field);
+    if (Object.keys(body).length === 0)
+        throw createCliError('VALIDATION', `dsr update needs at least one field to change (or --clear <${CLEARABLE_UPDATE_FIELDS.join('|')}>)`);
+    assertUpdateAuth(body);
+    return body;
+}
+export async function runDsrUpdate(opts, deps = {}) {
+    try {
+        if (!opts.id)
+            throw createCliError('VALIDATION', '--id is required for dsr update');
+        const body = assembleUpdateBody(opts);
+        const client = clientFor(opts, deps);
+        const warnings = [];
+        // assertUpdateAuth catches "set specified_emails AND clear the list" in one call. The same
+        // end state is reachable by clearing the list alone against a link ALREADY stored that way,
+        // which assertUpdateAuth cannot see. Both viewer gates treat an empty allow-list as deny, so
+        // this bricks the link rather than opening it — a usability guard, not a safety gate. That is
+        // why an unresolved lookup degrades to a warning here while the --if-exists preflight, which
+        // gates a write that would otherwise silently succeed differently, hard-fails instead.
+        const clearedLists = body.auth_strategy === undefined ? clearedListFields(body) : [];
+        if (clearedLists.length > 0) {
+            const stored = await readStoredAuthStrategy(client, opts.id);
+            const required = stored ? STRATEGY_REQUIRES[stored] : undefined;
+            if (stored === null) {
+                warnings.push(`could not read this share's stored auth strategy, so clearing ${clearedLists.join(' and ')} was not checked against it`);
+            }
+            else if (required && clearedLists.includes(required)) {
+                throw createCliError('VALIDATION', `this share's auth strategy is ${stored}, which requires ${required} — clearing it would lock every recipient out. ` +
+                    'Pass --auth-strategy in the same call to relax the gate first.');
+            }
+        }
+        const url = `${ENDPOINT}/${encodeURIComponent(opts.id)}`;
+        const res = await client.patch(url, body, opts.instanceId ? { params: { instance_id: opts.instanceId } } : undefined);
+        return ok(res.data, warnings);
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+export async function runDsrDelete(opts, deps = {}) {
+    try {
+        if (!opts.id)
+            throw createCliError('VALIDATION', '--id is required for dsr delete');
+        const client = clientFor(opts, deps);
+        const url = `${ENDPOINT}/${encodeURIComponent(opts.id)}`;
+        const res = await client.delete(url, opts.instanceId ? { params: { instance_id: opts.instanceId } } : undefined);
+        // the route answers 204 with an empty body — echo the id so the caller has something to log
+        return ok(res.data || { id: opts.id, deleted: true });
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
 export function createDsrCommand() {
     const cmd = new Command('dsr').description('create and share a Digital Sales Room (a canvas share link)');
     withAuthFlags(cmd.command('scaffold'))
@@ -193,7 +417,7 @@ export function createDsrCommand() {
         emitEnvelope(await runDsrScaffold({ ...options, quiet: globals.quiet }), globals);
     });
     withAuthFlags(cmd.command('create'))
-        .description('create + share a DSR (canvas share link) and return the link')
+        .description('create + share a DSR (canvas share link) and return the link (id, url, short_url, canvas)')
         .option('--instance-id <id>', 'Instance ID (required for --sharebox-file-ids)')
         .option('--canvas-id <id>', 'Existing canvas to share (one source required)')
         .option('--sharebox-file-ids <csv>', 'Build a canvas from these file IDs (one source required)', parseTags)
@@ -211,6 +435,11 @@ export function createDsrCommand() {
         .option('--landing-template-id <id>', 'Landing template to bind (optional)')
         .option('--landing-context <json>', 'Landing personalization merge fields (JSON object)')
         .option('--config-file <path>', 'Full {source,security,landing} spec JSON (mutually exclusive with the flags above)')
+        .option('--if-exists <mode>', 'return|error. What to do when the canvas is already shared: `return` hands back the existing link (default ' +
+        'with individual flags), `error` refuses and points at `dsr update` (default with --config-file, whose ' +
+        'security block is sent as-is and would overwrite the existing share). The check is a preflight lookup, so ' +
+        'it is advisory rather than atomic — a link created between the check and the share is still returned. ' +
+        'Never applies to a ShareBox source, which always mints a new canvas.')
         .action(async (options, command) => {
         const globals = command.optsWithGlobals();
         emitEnvelope(await runDsrCreate({ ...options, quiet: globals.quiet }), globals);
@@ -225,5 +454,32 @@ export function createDsrCommand() {
         const globals = command.optsWithGlobals();
         emitEnvelope(await runDsrBindLanding({ ...options, quiet: globals.quiet }), globals);
     });
+    // --allow-forward is declared BEFORE --no-allow-forward on purpose: commander takes a
+    // boolean's default from whichever of the pair it sees first, so the reverse order would
+    // make `allowForward` default to `true` and every update would ship allow_forward: true,
+    // clobbering a rep's opt-out. `create` above relies on the same ordering.
+    withAuthFlags(cmd.command('update'))
+        .description('update an existing share: only the flags you pass are sent; --clear removes a value')
+        .option('--id <id>', 'Shared link ID (required)')
+        .option('--auth-strategy <v>', 'none|any_email|specified_emails|specified_domains|verified_emails|verified_domains')
+        .option('--allowed-emails <csv>', 'Allowed emails (required for specified/verified_emails)', parseTags)
+        .option('--allowed-domains <csv>', 'Allowed domains (required for specified/verified_domains)', parseTags)
+        .option('--valid-until <iso>', 'Expiry (ISO datetime)')
+        .option('--allow-forward', 'Allow recipients to forward')
+        .option('--no-allow-forward', 'Disallow forwarding')
+        .option('--clear <field>', `Remove a value instead of setting one — repeatable. One of: ${CLEARABLE_UPDATE_FIELDS.join(' | ')}`, (value, prev) => [...prev, value], [])
+        .option('--instance-id <id>', 'Instance ID (optional)')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runDsrUpdate({ ...options, quiet: globals.quiet }), globals);
+    });
+    withAuthFlags(cmd.command('delete'))
+        .description('revoke a share link permanently (the canvas itself is kept)')
+        .option('--id <id>', 'Shared link ID (required)')
+        .option('--instance-id <id>', 'Instance ID (optional)')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runDsrDelete({ ...options, quiet: globals.quiet }), globals);
+    });
     return cmd;
 }

package/dist/src/commands/scaffolds.js

@@ -177,11 +177,21 @@ export const ANNOUNCEMENT_SCAFFOLD_JSON = JSON.stringify(ANNOUNCEMENT_SCAFFOLD_D
 /**
  * Starter metadata-field schema for `p metadata-template scaffold`. A working
  * example, not a blank template: one section demonstrating every field `type`
- * (text/number/date/select/multi-select/checkbox/html) and every attribute the
- * serializer accepts. NOTE: `options` (select/multi-select) MUST be
- * { label, value } objects — bare strings are rejected 400. `multi-select`
- * cannot be `is_sortable`. A select/multi-select `default` is an option `value`.
- * Section-level `are_fields_dependent` and field-level `help_text` are optional.
+ * that is usable end-to-end (text/number/date/select/multi-select/checkbox) and
+ * every attribute the serializer accepts. NOTE: `options` (select/multi-select)
+ * MUST be { label, value } objects — bare strings are rejected 400.
+ * `multi-select` cannot be `is_sortable`. A select/multi-select `default` is an
+ * option `value`. Section-level `are_fields_dependent` and field-level
+ * `help_text` are optional.
+ *
+ * Deliberately excludes `html`. Django's MetadataTemplateFieldSerializer still
+ * lists it in TYPE_CHOICES, so an upsert is accepted, but nothing downstream
+ * supports it for file/canvas metadata: the Admin field-type picker has no HTML
+ * entry, the template list renders such a field as "Unknown", and
+ * TYPE_FIELD_CLASSES_MAP (pitcher/serializers/metadataserializers.py) has no
+ * `html` key, so building the per-instance metadata value serializer raises
+ * KeyError. Shipping it in the scaffold handed users a field they could not
+ * edit or populate (PIT-7487 QA).
  */
 const METADATA_TEMPLATE_SCAFFOLD_DATA = [
     {
@@ -256,15 +266,6 @@ const METADATA_TEMPLATE_SCAFFOLD_DATA = [
                 is_pitch_master: false,
                 default: false,
             },
-            {
-                name: 'notes',
-                label: 'Notes',
-                type: 'html',
-                is_required: false,
-                is_filterable: false,
-                is_sortable: false,
-                is_pitch_master: false,
-            },
         ],
     },
 ];

package/dist/src/core/ld.d.ts

@@ -17,8 +17,16 @@ export declare function requireInstance(opts: LdCommonOpts): string;
 export declare function pickTruthy<T extends object>(opts: T, keys: readonly (keyof T)[]): Partial<Record<keyof T, unknown>>;
 /**
  * Resolve the standalone L&D Lambda base URL. Order: --ld-url flag → NG_LD_API_URL env →
- * ld-app app config (api_base_url) via the platform client. Cached per (org, instanceId).
- * The org key can't be region-inferred, so app config (region-correct) is the default.
+ * the installed ld-app record's `metadata.api_base_url` → the ld-app built-in default.
+ * Cached per (org, instanceId).
+ *
+ * PIT-7546: this used to read `/core/api/protected/apps/ld-app/config`, which is a
+ * machine-to-machine route gated on an `x-integrations-token` shared secret. The CLI sends
+ * `x-api-key`, so next-core rejected every call with 'Invalid m2m integrations token' before
+ * the L&D Lambda was ever contacted — one root cause behind all 63 `pitcher_ld_*` failures.
+ * The replacement reads the same row that route's SQL reads (`pitcher_file` where
+ * `app_metadata->>'name' = 'ld-app'` and `instance_id = $2`, `type = 'app'`, not deleted)
+ * over a credential the CLI actually holds.
  */
 export declare function resolveLdBaseUrl(opts: LdCommonOpts, deps?: LdDeps, env?: NodeJS.ProcessEnv): Promise<string>;
 /** Build (or inject, in tests) an axios client pointed at the resolved L&D Lambda base. */

package/dist/src/core/ld.js

@@ -1,7 +1,56 @@
 import { resolveApiKey } from './auth.js';
 import { clientFor, makeClient, toCliError } from './http.js';
+import { resolveBaseUrl } from './baseUrl.js';
 import { createCliError } from './errors.js';
-const LD_APP_CONFIG_PATH = '/core/api/protected/apps/ld-app/config';
+import { MAX_PAGE_SIZE } from './pagination.js';
+const LD_APP_NAME = 'ld-app';
+const FILES_LIST_PATH = '/api/v1/files/';
+/**
+ * Sparse fieldset for the installed-apps scan (`FileViewSet.get_serializer` forwards `?fields=`
+ * to `AlwaysIncludeIdFieldMixin`, which also re-adds `id`). Without it the full `FileSerializer`
+ * renders `content_url`/`thumbnail_url`/`zip_url`/`original_url` for every row — each one a
+ * CloudFront signing — on every single `p ld` invocation, since the cache is per-process.
+ * Measured on a 59-app instance: 153,837 -> 77,402 bytes and no signed URLs.
+ */
+const LD_APP_FIELDS = 'app_metadata,metadata';
+/**
+ * Fallback L&D base URL, kept byte-identical to the ld-app frontend's own default
+ * (`ng-production-apps/ld-app/src/lib/apiClient.ts`). `api_base_url` is an OPTIONAL
+ * per-instance override (`app.config.json`, `is_required: false`), so on every instance
+ * that has never set it the app falls back to this single deployed Lambda.
+ *
+ * ONLY usable from the platform host below — see LD_FALLBACK_PLATFORM_ORIGIN.
+ */
+const LD_FALLBACK_BASE_URL = 'https://cgmfr9gjza.execute-api.eu-west-1.amazonaws.com/dev/api';
+/**
+ * The one platform host the fallback Lambda authenticates against, so the only one whose
+ * API key may travel to it.
+ *
+ * The Lambda lives in the IaC Test account with `DefaultAuthorizer: NONE` (ld-app README
+ * section 2) and validates an incoming `x-api-key` by relaying it verbatim to
+ * `https://dev.my.pitcher.com/api/v1` (`ld-app/server/src/config/index.ts` →
+ * `resolvePitcherApiBaseUrl`, `providers/pitcherApiProvider.ts` → `credentialHeaders`).
+ * Defaulting any other environment's org key onto it would ship that credential into a
+ * test account and then fail validation, surfacing as a misleading AUTH — and `ldClientFor`
+ * sends exactly that key. The L&D server refuses the mirror-image default for the same
+ * stated reason ("would send credential validation and org-membership probes to the wrong
+ * environment"), so the CLI matches it rather than re-deciding.
+ *
+ * The frontend precedent does NOT extend here: it carries a short-lived per-user JWT, not
+ * the org-wide authoring key. Once a prod L&D stack exists, per-instance `api_base_url` is
+ * what points each instance at it — the fallback must never silently stand in.
+ */
+const LD_FALLBACK_PLATFORM_ORIGIN = 'https://dev.my.pitcher.com';
+/**
+ * Safety stop for the installed-apps scan. At 500 records/page this is 10k apps in one
+ * instance — unreachable in practice, so tripping it means the server kept advertising a
+ * `next` page. Fail loudly rather than spin: a silent break would look identical to
+ * "ld-app is not installed", which is the exact misreport paging is here to prevent.
+ */
+const MAX_APP_PAGES = 20;
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
 const baseUrlCache = new Map();
 /** Test-only: reset the resolved-base-URL cache between cases. */
 export function __clearLdBaseUrlCache() {
@@ -36,10 +85,95 @@ function trimUrl(raw, source) {
     // origin + pathname only: strips any userinfo/query/hash; trailing slash trimmed.
     return `${parsed.origin}${parsed.pathname}`.replace(/\/+$/, '');
 }
+/**
+ * Find the installed `ld-app` file record for an instance and return its per-instance
+ * config (`pitcher_file.metadata`), or undefined when the app is not installed.
+ *
+ * Django's `FileFilter` (ng-rest-api `pitcher/views/fileviews.py`) has NO filter on
+ * `app_metadata` — its declared filters and `Meta.fields` cover `name`, `type`, `tags__in`
+ * etc., and `name` is the file's DISPLAY name ('L&D'), not `app_metadata->>'name'`
+ * ('ld-app'). So the name match has to happen client-side, which in turn means paging to
+ * exhaustion: a first-page-only match would report 'not installed' on an instance that
+ * simply has more apps than one page holds.
+ *
+ * If an instance somehow carries two ld-app records, the first in server order wins. That
+ * order is `-modified_at` (`fileviews.py` FileViewSet.ordering), so the most-recently-modified
+ * one does — strictly more deterministic than the `LIMIT 1` with no ORDER BY in the m2m route
+ * this replaces. No dev instance has more than one (measured across all 20 that have it).
+ */
+async function fetchLdAppMetadata(platform, instanceId) {
+    let scanned = 0;
+    let named = 0;
+    let exhausted = false;
+    for (let page = 1; page <= MAX_APP_PAGES; page += 1) {
+        const res = await platform.get(FILES_LIST_PATH, {
+            params: { instance_id: instanceId, type__in: 'app', fields: LD_APP_FIELDS, page, page_size: MAX_PAGE_SIZE },
+        });
+        const body = res.data;
+        // Fail loudly on an unexpected body rather than coercing it to an empty page: that would
+        // surface as 'ld-app is not installed', the exact misreport the paging below is here to
+        // prevent, and it would be indistinguishable from the real thing.
+        if (!isRecord(body) || !Array.isArray(body.results)) {
+            throw createCliError('UNKNOWN', `Unexpected response shape from ${FILES_LIST_PATH} (expected a paginated body)`);
+        }
+        scanned += body.results.length;
+        for (const row of body.results) {
+            const file = row;
+            // A single nameless row is DATA, not a bad response — `app_metadata` is a JSONField
+            // defaulting to `{}`, and such a row is definitively not ld-app, so skipping it is
+            // correct. It also cannot hide ld-app, which has a name and is found by scanning every
+            // row. Hard-failing on it would take out `p ld` for an instance over one junk record.
+            if (typeof file?.app_metadata?.name !== 'string')
+                continue;
+            named += 1;
+            if (file.app_metadata.name !== LD_APP_NAME)
+                continue;
+            // Behaviourally this is just null-safety: the sole consumer reads `.api_base_url`, which
+            // is undefined on a string or array anyway, so `isRecord` and `?? {}` are equivalent for
+            // every input. It is written this way because it narrows without an `as` cast — do not
+            // read the strictness as a contract. What DOES matter is never returning a nullish value:
+            // the caller treats that as "ld-app not installed".
+            return isRecord(file.metadata) ? file.metadata : {};
+        }
+        // DRF's pagination contract for `next` is a non-empty URL string, `null`, or absent.
+        // Anything else means we cannot trust our own stopping condition: a truthy non-string
+        // would otherwise page all the way to the cap before failing, and an empty string would
+        // read as "exhausted" and land on NOT_FOUND. Fail immediately and accurately instead.
+        const next = body.next;
+        if (next !== undefined && next !== null && (typeof next !== 'string' || !next)) {
+            throw createCliError('UNKNOWN', `Unexpected \`next\` in the ${FILES_LIST_PATH} response (expected a URL, null or absent)`);
+        }
+        if (!next) {
+            exhausted = true;
+            break;
+        }
+    }
+    // Ran out of pages before the server ran out of `next`. Throw rather than return: a silent
+    // give-up is indistinguishable from "not installed", the exact misreport paging prevents.
+    if (!exhausted) {
+        throw createCliError('UNKNOWN', `Gave up looking for ${LD_APP_NAME} after ${MAX_APP_PAGES} pages of installed apps. Set --ld-url or NG_LD_API_URL.`);
+    }
+    // The systemic case IS a shape problem: rows came back but not one carried
+    // `app_metadata.name`, so the field we match on is missing wholesale (a dropped `?fields=`
+    // entry, a serializer change). Reporting NOT_FOUND there would claim "ld-app is not
+    // installed" on an instance that has it — the misreport this whole scan is built to avoid.
+    if (scanned > 0 && named === 0) {
+        throw createCliError('UNKNOWN', `No app row from ${FILES_LIST_PATH} carried app_metadata.name (${scanned} scanned) — the files list may no longer return it`);
+    }
+    return undefined;
+}
 /**
  * Resolve the standalone L&D Lambda base URL. Order: --ld-url flag → NG_LD_API_URL env →
- * ld-app app config (api_base_url) via the platform client. Cached per (org, instanceId).
- * The org key can't be region-inferred, so app config (region-correct) is the default.
+ * the installed ld-app record's `metadata.api_base_url` → the ld-app built-in default.
+ * Cached per (org, instanceId).
+ *
+ * PIT-7546: this used to read `/core/api/protected/apps/ld-app/config`, which is a
+ * machine-to-machine route gated on an `x-integrations-token` shared secret. The CLI sends
+ * `x-api-key`, so next-core rejected every call with 'Invalid m2m integrations token' before
+ * the L&D Lambda was ever contacted — one root cause behind all 63 `pitcher_ld_*` failures.
+ * The replacement reads the same row that route's SQL reads (`pitcher_file` where
+ * `app_metadata->>'name' = 'ld-app'` and `instance_id = $2`, `type = 'app'`, not deleted)
+ * over a credential the CLI actually holds.
  */
 export async function resolveLdBaseUrl(opts, deps = {}, env = process.env) {
     const override = opts.ldUrl?.trim() || env.NG_LD_API_URL?.trim();
@@ -48,17 +182,33 @@ export async function resolveLdBaseUrl(opts, deps = {}, env = process.env) {
     if (!opts.instanceId) {
         throw createCliError('VALIDATION', '--instance-id is required to resolve the L&D API URL (or set NG_LD_API_URL)');
     }
-    const cacheKey = `${opts.org ?? 'dev'}:${opts.instanceId}`;
+    // `--url` outranks `--org` in resolveBaseUrl (baseUrl.ts), so keying on org alone lets two
+    // different platform hosts collide on one cached L&D URL within a single process.
+    const cacheKey = `${opts.url ?? opts.org ?? 'dev'}:${opts.instanceId}`;
     const cached = baseUrlCache.get(cacheKey);
     if (cached)
         return cached;
     const platform = deps.platformClient ?? clientFor(opts);
-    const res = await platform.get(LD_APP_CONFIG_PATH, { params: { instance_id: opts.instanceId } });
-    const apiBaseUrl = res.data?.api_base_url;
-    if (typeof apiBaseUrl !== 'string' || !apiBaseUrl) {
-        throw createCliError('NOT_FOUND', 'ld-app is not configured in this instance (no api_base_url). Set --ld-url or NG_LD_API_URL.');
+    const metadata = await fetchLdAppMetadata(platform, opts.instanceId);
+    if (!metadata) {
+        throw createCliError('NOT_FOUND', 'ld-app is not configured in this instance (not installed). Set --ld-url or NG_LD_API_URL.');
+    }
+    // `api_base_url` is an optional override; absent means "use the app's own default" —
+    // but only where that default's credential environment matches ours (see the constant).
+    const apiBaseUrl = metadata.api_base_url;
+    let url;
+    if (typeof apiBaseUrl === 'string' && apiBaseUrl.trim()) {
+        url = trimUrl(apiBaseUrl.trim(), `ld-app config (metadata.api_base_url on instance ${opts.instanceId})`);
+    }
+    else {
+        const platformOrigin = resolveBaseUrl({ org: opts.org, url: opts.url });
+        if (platformOrigin !== LD_FALLBACK_PLATFORM_ORIGIN) {
+            throw createCliError('NOT_FOUND', `ld-app has no api_base_url configured on this instance, and the built-in default only serves ` +
+                `${LD_FALLBACK_PLATFORM_ORIGIN} (this run targets ${platformOrigin}). Set metadata.api_base_url ` +
+                `on the instance, or pass --ld-url / NG_LD_API_URL.`);
+        }
+        url = LD_FALLBACK_BASE_URL;
     }
-    const url = trimUrl(apiBaseUrl, 'ld-app config');
     baseUrlCache.set(cacheKey, url);
     return url;
 }

package/dist/src/mcp/bundled.js

@@ -1,7 +1,7 @@
 import { allTools } from './registry.js';
 // Developer-only tools excluded from the consumer .mcpb bundle. `publish_app` is alwaysDestructive
 // (creates a live, org-visible app release); `dev_sync`/`dev_sync_revert` mutate remote S3 dev state.
-// None are relevant to a non-technical adopter installing the extension. The CLI `p mcp` keeps all 121.
+// None are relevant to a non-technical adopter installing the extension. The CLI `p mcp` keeps all 123.
 export const BUNDLE_EXCLUDED_TOOLS = new Set(['pitcher_publish_app', 'pitcher_dev_sync', 'pitcher_dev_sync_revert']);
 // The tool set the .mcpb bundle registers.
 export const bundledTools = allTools.filter((t) => !BUNDLE_EXCLUDED_TOOLS.has(t.name));

package/dist/src/mcp/prompts/dsr.js

@@ -42,7 +42,19 @@ export const dsrPrompts = [
                 '3. (Optional) To brand the pre-auth page, list templates with `pitcher_dsr_landing_list` and bind one via ' +
                     '`landingTemplateId` — or point the user at `seed_dsr_landing` to author a new one first.',
                 '4. Call `pitcher_dsr_create` with the resolved fields. A denied/failed landing bind returns the link with a ' +
-                    'warning (not a failure) — surface it. Report the returned `short_url`.',
+                    'warning (not a failure) — surface it. Report the returned `url` (the full share link; `short_url` is the ' +
+                    'vanity form and may be absent). There is no `full_url` field.',
+                '5. **To change a share that already exists, use `pitcher_dsr_update`, not another create.** Creating with ' +
+                    'individual fields is a get-or-create: it returns the existing link and only touches the fields you pass, ' +
+                    'so it can never REMOVE a value. To take an expiry off a link, or to drop an allow-list, pass that field in `clear` ' +
+                    '(e.g. `clear: ["valid-until"]`) — leaving the field out is a no-op, not a reset. `pitcher_dsr_delete` ' +
+                    'revokes the link for good.',
+                '6. **Clearing an allow-list is refused while a strategy that needs it is in force.** ' +
+                    '`specified_emails`/`verified_emails` need `allowedEmails`; `specified_domains`/`verified_domains` need ' +
+                    '`allowedDomains`. That applies to the strategy already stored on the share AND to one you pass in the ' +
+                    'same call, because an empty allow-list locks every recipient out. Relax the gate in the same call ' +
+                    '(e.g. `authStrategy: "any_email"` together with `clear: ["allowed-emails"]`) — or just replace the list ' +
+                    'by passing a new `allowedEmails` instead of clearing it. An EMPTY array is rejected: use `clear`.',
             ].join('\n');
             return [{ role: 'user', content: { type: 'text', text } }];
         },

package/dist/src/mcp/tools/analytics.js

@@ -160,7 +160,8 @@ export const analyticsTools = [
         title: 'DSR per-viewer session timeline',
         description: 'Per-viewer session event timeline for a DSR canvas (drill-down for one viewer). Returns the raw, ' +
             'uncapped event list (not summarized). Works with a member key. Requires canvasId and userEmail — ' +
-            'get both from pitcher_analytics_viewers.',
+            'get both from pitcher_analytics_viewers: pass its `normalized_email` (or its `email`) VERBATIM. ' +
+            'Do not tidy the address — the stored identity carries an ` (External)` suffix.',
         inputShape: {
             instanceId: z.string().describe('Instance ID (required)'),
             canvasId: z.string().describe('Canvas ID (required)'),

package/dist/src/mcp/tools/dsr.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { runDsrCreate, runDsrBindLanding } from '../../commands/dsr.js';
+import { runDsrCreate, runDsrBindLanding, runDsrUpdate, runDsrDelete, CLEARABLE_UPDATE_FIELDS, IF_EXISTS_MODES } from '../../commands/dsr.js';
 const AUTH_STRATEGIES = [
     'none', 'any_email', 'specified_emails', 'specified_domains', 'verified_emails', 'verified_domains',
 ];
@@ -7,7 +7,7 @@ export const dsrTools = [
     {
         name: 'pitcher_dsr_create',
         title: 'Create and share a DSR',
-        description: 'Create a Digital Sales Room (a canvas share link) and get a clickable link back. Source is a canvas (canvasId) OR files (shareboxFileIds) - exactly one. Optional email/domain gating and a bound landing-page template. Never hard-fails once a link exists: a failed landing bind returns the link with a warning. Additive.',
+        description: 'Create a Digital Sales Room (a canvas share link) and get a clickable link back. Source is a canvas (canvasId) OR files (shareboxFileIds) - exactly one. Optional email/domain gating and a bound landing-page template. Returns the share: id, url (the full link), short_url, and a nested canvas object - there is no full_url field. This endpoint is a GET-OR-CREATE: with individual fields, sharing an already-shared canvas returns the existing link and only updates the fields you pass, so use pitcher_dsr_update to change or remove a value on an existing share. A configFile spec sends its whole security block (nulls and empty lists included), so for an already-shared canvas it refuses by default (ifExists "error"). A failed landing bind does not fail the call: it returns the link with a warning.',
         inputShape: {
             instanceId: z.string().optional().describe('Instance ID (required for the shareboxFileIds source)'),
             canvasId: z.string().optional().describe('Canvas to share (exactly one of canvasId / shareboxFileIds)'),
@@ -16,8 +16,8 @@ export const dsrTools = [
             accountId: z.string().optional(),
             templateId: z.string().optional(),
             authStrategy: z.enum(AUTH_STRATEGIES).optional().describe('Access gating (server default any_email)'),
-            allowedEmails: z.array(z.string()).optional().describe('Required for specified_emails / verified_emails'),
-            allowedDomains: z.array(z.string()).optional().describe('Required for specified_domains / verified_domains'),
+            allowedEmails: z.array(z.string()).optional().describe('Required for specified_emails / verified_emails. An EMPTY array is rejected'),
+            allowedDomains: z.array(z.string()).optional().describe('Required for specified_domains / verified_domains. An EMPTY array is rejected'),
             validUntil: z.string().optional().describe('Expiry, ISO datetime'),
             allowForward: z.boolean().optional(),
             allowDownload: z.boolean().optional(),
@@ -25,6 +25,10 @@ export const dsrTools = [
             landingTemplateId: z.string().optional().describe('Bind a landing-page template (discover via pitcher_dsr_landing_list)'),
             landingContext: z.string().optional().describe('Landing-page merge fields, a JSON object as a string'),
             configFile: z.string().optional().describe('Path on the MCP server host to a full {source,security,landing} spec JSON; mutually exclusive with the individual flags'),
+            ifExists: z
+                .enum(IF_EXISTS_MODES)
+                .optional()
+                .describe('Canvas already shared: "return" hands back the existing link (default with individual fields), "error" refuses and points at pitcher_dsr_update (default with configFile, whose security block would otherwise overwrite the existing share). Not checked for a ShareBox source, which always mints a new canvas'),
         },
         run: runDsrCreate,
         readOnly: false,
@@ -44,4 +48,45 @@ export const dsrTools = [
         readOnly: false,
         write: true,
     },
+    {
+        name: 'pitcher_dsr_update',
+        title: 'Update a DSR share',
+        description: 'Change the access settings of an EXISTING DSR share (expiry, gating, allowed emails/domains, forwarding). Only the fields you pass are sent, so anything you omit is left exactly as it is. To REMOVE a value rather than set one, name it in `clear` — omitting a field never clears it. Use this instead of re-running pitcher_dsr_create to change or clear a value on an existing share. Note tags and allowDownload are create-time only and cannot be changed here.',
+        inputShape: {
+            id: z.string().describe('Shared-link ID'),
+            authStrategy: z.enum(AUTH_STRATEGIES).optional().describe('Access gating'),
+            allowedEmails: z
+                .array(z.string())
+                .optional()
+                .describe('Required for specified_emails / verified_emails. An EMPTY array is rejected - use clear:["allowed-emails"] to remove the list'),
+            allowedDomains: z
+                .array(z.string())
+                .optional()
+                .describe('Required for specified_domains / verified_domains. An EMPTY array is rejected - use clear:["allowed-domains"] to remove the list'),
+            validUntil: z.string().optional().describe('Expiry, ISO datetime'),
+            allowForward: z.boolean().optional(),
+            clear: z
+                .array(z.enum(CLEARABLE_UPDATE_FIELDS))
+                .optional()
+                .describe('Fields to REMOVE the value of, e.g. ["valid-until"] to make the link never expire. Conflicts with passing the same field a value. Clearing allowed-emails/allowed-domains is REJECTED while a strategy that needs that list is in force - either the one already stored, or one passed as authStrategy in this same call - because an empty allow-list locks every recipient out. Relax the gate first (e.g. authStrategy "any_email") in the same call or a prior one'),
+            instanceId: z.string().optional(),
+        },
+        run: runDsrUpdate,
+        readOnly: false,
+        write: true,
+    },
+    {
+        name: 'pitcher_dsr_delete',
+        title: 'Revoke a DSR share',
+        description: 'Permanently revoke a DSR share link so the URL stops working. The canvas itself is kept. Irreversible - to relax or tighten access instead, use pitcher_dsr_update.',
+        inputShape: {
+            id: z.string().describe('Shared-link ID'),
+            instanceId: z.string().optional(),
+        },
+        run: runDsrDelete,
+        readOnly: false,
+        write: true,
+        // irreversible on every environment, so destructiveHint must not depend on env.prod
+        alwaysDestructive: true,
+    },
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pitcher/cli-scripts",
-  "version": "2.16.0",
+  "version": "2.17.1",
   "description": "The Pitcher CLI for various tasks in its ecosystem.",
   "author": "Pitcher AG",
   "license": "MIT",
@@ -32,7 +32,7 @@
     "@types/node": "^24.13.2",
     "esbuild": "^0.28.1",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.9"
+    "vitest": "^4.1.11"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1",