@pitcher/cli-scripts 2.15.0 → 2.17.0

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/files.d.ts

@@ -11,6 +11,7 @@ export declare function runFilesList(opts: CommonOpts & {
     instanceId?: string;
     tags?: string;
     idIn?: string;
+    type?: string;
     page?: number;
     pageSize?: number;
 }, deps?: FilesDeps): Promise<Envelope<{

package/dist/src/commands/files.js

@@ -5,7 +5,7 @@ import { createCliError } from '../core/errors.js';
 import { emitEnvelope } from '../core/output.js';
 import { uploadFile } from '../core/upload.js';
 import { listPageParams, listPaginationEcho } from '../core/pagination.js';
-import { parseTags, parseJsonObject, validateAccessType, deepMerge, assertIntFlags } from '../schema/content.js';
+import { parseTags, parseJsonObject, validateAccessType, validateFileType, deepMerge, assertIntFlags } from '../schema/content.js';
 import { withAuthFlags } from './withAuth.js';
 export async function runFilesList(
 // NOTE: no folderId — the Django files list has no folder filter (listing a
@@ -15,12 +15,25 @@ opts, deps = {}) {
         if (!opts.instanceId)
             throw createCliError('VALIDATION', '--instance-id is required for files list');
         assertIntFlags(opts);
+        const type = validateFileType(opts.type);
         const client = clientFor(opts, deps);
         const params = { instance_id: opts.instanceId, ...listPageParams(opts) };
         if (opts.idIn)
             params.id__in = opts.idIn;
         if (opts.tags)
             params.tags__in = opts.tags;
+        // Installable apps are file records too (type=app). Exclude them by default so a "list files"
+        // request returns real content, not the instance's installed apps. `--type <content|asset|app>`
+        // isolates one type and always wins; `--type all` restores the unfiltered listing. An explicit
+        // --id-in lookup bypasses the default exclusion — fetching a file by id is a targeted lookup, not
+        // a browse, so it must return that record whatever its type (an explicit --type still applies).
+        // Uses type__in to match the tags__in/id__in CSV convention above (a single value is a valid filter).
+        if (type && type !== 'all') {
+            params.type__in = type;
+        }
+        else if (!type && !opts.idIn) {
+            params.type__in = 'content,asset';
+        }
         const res = await client.get('/api/v1/files/', { params });
         return ok({ results: res.data.results, pagination: listPaginationEcho(opts, res.data) });
     }
@@ -122,6 +135,7 @@ export function createFilesCommand() {
         .option('--instance-id <id>', 'Instance ID (required)')
         .option('--id-in <ids>', 'Comma-separated file IDs')
         .option('--tags <tags>', 'Comma-separated tags (filters via tags__in)')
+        .option('--type <type>', 'File type: content, asset, app, or all (default excludes installable apps)')
         .option('--page <n>', 'Page number', (v) => parseInt(v, 10))
         .option('--page-size <n>', 'Page size (max 500)', (v) => parseInt(v, 10))
         .action(async (options, command) => {

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/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/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/dist/src/mcp/tools/files.js

@@ -1,14 +1,21 @@
 import { z } from 'zod';
 import { runFilesList, runFilesGet, runFilesCreate, runFilesUpdate } from '../../commands/files.js';
+import { FILE_TYPES } from '../../schema/content.js';
 export const filesTools = [
     {
         name: 'pitcher_files_list',
         title: 'List files',
-        description: 'List content files in an instance. Filter by tags or specific IDs.',
+        description: 'List content files in an instance. Installed apps are stored as file records too, but are ' +
+            'EXCLUDED by default (content + assets only) so a "list files" request returns real content. ' +
+            'Pass type="app" for installed apps only, or type="all" to include everything. Filter by tags or specific IDs.',
         inputShape: {
             instanceId: z.string().describe('Instance ID (required)'),
             idIn: z.string().optional().describe('Comma-separated file IDs'),
             tags: z.string().optional().describe('Comma-separated tags'),
+            type: z
+                .enum(FILE_TYPES)
+                .optional()
+                .describe('File type filter. Omit to list content + assets (installed apps excluded); "app" = apps only; "all" = everything including apps.'),
             page: z.number().int().optional(),
             pageSize: z.number().int().optional(),
         },

package/dist/src/schema/content.d.ts

@@ -1,8 +1,10 @@
+export declare const FILE_TYPES: readonly ["content", "asset", "app", "all"];
 export declare function isPlainObject(v: unknown): v is Record<string, unknown>;
 export declare function parseJsonObject(raw: string, flagName: string): Record<string, unknown>;
 export declare function parseJsonArray(raw: string, flagName: string): unknown[];
 export declare function parseTags(raw: string): string[];
 export declare function validateAccessType(v: string | undefined): string | undefined;
+export declare function validateFileType(v: string | undefined): string | undefined;
 export declare function assertIntFlags(opts: {
     page?: number;
     pageSize?: number;

package/dist/src/schema/content.js

@@ -1,5 +1,10 @@
 import { createCliError } from '../core/errors.js';
 const ACCESS_TYPES = ['public', 'restricted', 'personal'];
+// File record types on Django's `pitcher_file.type` column, plus the `all` escape hatch.
+// Installable apps are stored as file records (type=app), so `p files list` excludes them by default;
+// `all` opts back into the unfiltered listing. See validateFileType / runFilesList.
+// Exported so the MCP `pitcher_files_list` tool sources its zod enum from the same list (no drift).
+export const FILE_TYPES = ['content', 'asset', 'app', 'all'];
 export function isPlainObject(v) {
     return typeof v === 'object' && v !== null && !Array.isArray(v);
 }
@@ -37,6 +42,14 @@ export function validateAccessType(v) {
     }
     return v;
 }
+export function validateFileType(v) {
+    if (v === undefined)
+        return undefined;
+    if (!FILE_TYPES.includes(v)) {
+        throw createCliError('VALIDATION', `--type must be one of: ${FILE_TYPES.join(', ')}`);
+    }
+    return v;
+}
 // Guards against NaN reaching the request (commander's parseInt yields NaN on
 // non-numeric input, e.g. `--page abc`).
 export function assertIntFlags(opts) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pitcher/cli-scripts",
-  "version": "2.15.0",
+  "version": "2.17.0",
   "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",