@pitcher/cli-scripts 2.2.1 → 2.3.0

package/dist/index.js

@@ -5,6 +5,8 @@ import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
 import { createPublishAppCommand } from './src/commands/publishApp.js';
 import { createDevSyncCommand } from './src/commands/devSync.js';
+import { createFilesCommand } from './src/commands/files.js';
+import { createFoldersCommand } from './src/commands/folders.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
@@ -17,4 +19,6 @@ program
     .option('--quiet', 'Suppress non-essential (progress) output');
 program.addCommand(createPublishAppCommand());
 program.addCommand(createDevSyncCommand());
+program.addCommand(createFilesCommand());
+program.addCommand(createFoldersCommand());
 program.parseAsync(process.argv);

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

@@ -0,0 +1,46 @@
+import { Command } from 'commander';
+import axios, { type AxiosInstance } from 'axios';
+import { type CommonOpts } from '../core/http.js';
+import { type Envelope } from '../core/envelope.js';
+export interface FilesDeps {
+    client?: AxiosInstance;
+    put?: typeof axios.put;
+    readFile?: (p: string) => Buffer;
+}
+export declare function runFilesList(opts: CommonOpts & {
+    instanceId?: string;
+    tags?: string;
+    idIn?: string;
+    page?: number;
+    pageSize?: number;
+}, deps?: FilesDeps): Promise<Envelope<{
+    results: unknown[];
+    pagination: Record<string, unknown>;
+}>>;
+export declare function runFilesGet(opts: CommonOpts & {
+    id?: string;
+}, deps?: FilesDeps): Promise<Envelope<unknown>>;
+export declare function runFilesCreate(opts: CommonOpts & {
+    instanceId?: string;
+    name?: string;
+    folderId?: string;
+    filePath?: string;
+    sourceUrl?: string;
+    accessType?: string;
+    tags?: string;
+    metadata?: string;
+    appMetadata?: string;
+}, deps?: FilesDeps): Promise<Envelope<unknown>>;
+export declare function runFilesUpdate(opts: CommonOpts & {
+    id?: string;
+    instanceId?: string;
+    name?: string;
+    folderId?: string;
+    filePath?: string;
+    sourceUrl?: string;
+    accessType?: string;
+    tags?: string;
+    metadata?: string;
+    appMetadata?: string;
+}, deps?: FilesDeps): Promise<Envelope<unknown>>;
+export declare function createFilesCommand(): Command;

package/dist/src/commands/files.js

@@ -0,0 +1,170 @@
+import { Command } from 'commander';
+import { clientFor, toCliError } from '../core/http.js';
+import { ok, fail } from '../core/envelope.js';
+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';
+export async function runFilesList(
+// NOTE: no folderId — the Django files list has no folder filter (listing a
+// folder's files is a folders-retrieve concern). tags filters via `tags__in`.
+opts, deps = {}) {
+    try {
+        if (!opts.instanceId)
+            throw createCliError('VALIDATION', '--instance-id is required for files list');
+        assertIntFlags(opts);
+        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;
+        const res = await client.get('/api/v1/files/', { params });
+        return ok({ results: res.data.results, pagination: listPaginationEcho(opts, res.data) });
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+export async function runFilesGet(opts, deps = {}) {
+    try {
+        if (!opts.id)
+            throw createCliError('VALIDATION', 'file id is required');
+        const client = clientFor(opts, deps);
+        const res = await client.get(`/api/v1/files/${opts.id}`);
+        return ok(res.data);
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+export async function runFilesCreate(opts, deps = {}) {
+    try {
+        if (!opts.instanceId)
+            throw createCliError('VALIDATION', '--instance-id is required for files create');
+        const client = clientFor(opts, deps);
+        const body = { instance_id: opts.instanceId };
+        if (opts.name)
+            body.name = opts.name;
+        if (opts.folderId)
+            body.folder_id = opts.folderId;
+        const accessType = validateAccessType(opts.accessType);
+        if (accessType)
+            body.access_type = accessType;
+        if (opts.tags)
+            body.tags = parseTags(opts.tags);
+        if (opts.metadata)
+            body.metadata = parseJsonObject(opts.metadata, 'metadata');
+        if (opts.appMetadata)
+            body.app_metadata = parseJsonObject(opts.appMetadata, 'app-metadata');
+        if (opts.filePath && opts.sourceUrl)
+            throw createCliError('VALIDATION', 'pass either --file or --source-url, not both');
+        if (opts.filePath) {
+            body.content_upload_id = await uploadFile(client, { instanceId: opts.instanceId, filePath: opts.filePath }, deps);
+        }
+        else if (opts.sourceUrl) {
+            body.url = opts.sourceUrl;
+        }
+        const res = await client.post('/api/v1/files/', body);
+        return ok(res.data);
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+export async function runFilesUpdate(opts, deps = {}) {
+    try {
+        if (!opts.id)
+            throw createCliError('VALIDATION', 'file id is required');
+        const client = clientFor(opts, deps);
+        const body = {};
+        if (opts.name)
+            body.name = opts.name;
+        if (opts.folderId)
+            body.folder_id = opts.folderId;
+        const accessType = validateAccessType(opts.accessType);
+        if (accessType)
+            body.access_type = accessType;
+        if (opts.tags)
+            body.tags = parseTags(opts.tags);
+        // Metadata is a JSONField the PATCH replaces wholesale — read-merge-write.
+        const metaPatch = opts.metadata ? parseJsonObject(opts.metadata, 'metadata') : undefined;
+        const appMetaPatch = opts.appMetadata ? parseJsonObject(opts.appMetadata, 'app-metadata') : undefined;
+        if (metaPatch || appMetaPatch) {
+            const cur = (await client.get(`/api/v1/files/${opts.id}`)).data;
+            if (metaPatch)
+                body.metadata = deepMerge(cur.metadata, metaPatch);
+            if (appMetaPatch)
+                body.app_metadata = deepMerge(cur.app_metadata, appMetaPatch);
+        }
+        if (opts.filePath && opts.sourceUrl)
+            throw createCliError('VALIDATION', 'pass either --file or --source-url, not both');
+        if (opts.filePath) {
+            if (!opts.instanceId)
+                throw createCliError('VALIDATION', '--instance-id is required with --file');
+            body.content_upload_id = await uploadFile(client, { instanceId: opts.instanceId, filePath: opts.filePath }, deps);
+        }
+        else if (opts.sourceUrl) {
+            body.url = opts.sourceUrl;
+        }
+        const res = await client.patch(`/api/v1/files/${opts.id}`, body);
+        return ok(res.data);
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+export function createFilesCommand() {
+    const cmd = new Command('files').description('manage Pitcher content files');
+    const withAuth = (c) => c
+        .option('--api-key <apiKey>', 'API Key for authentication')
+        .option('--org <organization>', 'Organization subdomain', 'dev')
+        .option('--url <url>', 'Explicit base URL override');
+    withAuth(cmd.command('list'))
+        .requiredOption('--instance-id <id>', 'Instance ID')
+        .option('--id-in <ids>', 'Comma-separated file IDs')
+        .option('--tags <tags>', 'Comma-separated tags (filters via tags__in)')
+        .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) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runFilesList({ ...options, quiet: globals.quiet }), globals);
+    });
+    withAuth(cmd.command('get'))
+        .argument('<id>', 'File ID')
+        .action(async (id, options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runFilesGet({ ...options, id, quiet: globals.quiet }), globals);
+    });
+    withAuth(cmd.command('create'))
+        .requiredOption('--instance-id <id>', 'Instance ID')
+        .option('--name <name>', 'File name')
+        .option('--folder-id <id>', 'Destination folder')
+        .option('--file <path>', 'Local file to upload')
+        .option('--source-url <url>', 'Link/WEB file source URL')
+        .option('--access-type <type>', 'public | restricted | personal')
+        .option('--tags <tags>', 'Comma-separated tags')
+        .option('--metadata <json>', 'metadata JSON object')
+        .option('--app-metadata <json>', 'app_metadata JSON object')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runFilesCreate({ ...options, filePath: options.file, quiet: globals.quiet }), globals);
+    });
+    withAuth(cmd.command('update'))
+        .argument('<id>', 'File ID')
+        .option('--instance-id <id>', 'Instance ID (required only with --file)')
+        .option('--name <name>', 'File name')
+        .option('--folder-id <id>', 'Move to folder')
+        .option('--file <path>', 'Replace binary with local file')
+        .option('--source-url <url>', 'Replace with link/WEB source URL')
+        .option('--access-type <type>', 'public | restricted | personal')
+        .option('--tags <tags>', 'Comma-separated tags')
+        .option('--metadata <json>', 'metadata JSON object (deep-merged)')
+        .option('--app-metadata <json>', 'app_metadata JSON object (deep-merged)')
+        .action(async (id, options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runFilesUpdate({ ...options, id, filePath: options.file, quiet: globals.quiet }), globals);
+    });
+    return cmd;
+}

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

@@ -0,0 +1,33 @@
+import { Command } from 'commander';
+import type { AxiosInstance } from 'axios';
+import { type CommonOpts } from '../core/http.js';
+import { type Envelope } from '../core/envelope.js';
+export interface FoldersDeps {
+    client?: AxiosInstance;
+}
+export declare function runFoldersList(opts: CommonOpts & {
+    instanceId?: string;
+    page?: number;
+    pageSize?: number;
+}, deps?: FoldersDeps): Promise<Envelope<{
+    results: unknown[];
+    pagination: Record<string, unknown>;
+}>>;
+export declare function runFoldersGet(opts: CommonOpts & {
+    id?: string;
+    root?: boolean;
+    instanceId?: string;
+}, deps?: FoldersDeps): Promise<Envelope<unknown>>;
+export declare function runFoldersCreate(opts: CommonOpts & {
+    name?: string;
+    parentFolderId?: string;
+    accessType?: string;
+    rules?: string;
+}, deps?: FoldersDeps): Promise<Envelope<unknown>>;
+export declare function runFoldersUpdate(opts: CommonOpts & {
+    id?: string;
+    name?: string;
+    accessType?: string;
+    rules?: string;
+}, deps?: FoldersDeps): Promise<Envelope<unknown>>;
+export declare function createFoldersCommand(): Command;

package/dist/src/commands/folders.js

@@ -0,0 +1,123 @@
+import { Command } from 'commander';
+import { clientFor, toCliError } from '../core/http.js';
+import { ok, fail } from '../core/envelope.js';
+import { createCliError } from '../core/errors.js';
+import { emitEnvelope } from '../core/output.js';
+import { listPageParams, listPaginationEcho } from '../core/pagination.js';
+import { parseJsonArray, validateAccessType, assertIntFlags } from '../schema/content.js';
+export async function runFoldersList(opts, deps = {}) {
+    try {
+        if (!opts.instanceId)
+            throw createCliError('VALIDATION', '--instance-id is required for folders list');
+        assertIntFlags(opts);
+        const client = clientFor(opts, deps);
+        const params = { instance_id: opts.instanceId, ...listPageParams(opts) };
+        const res = await client.get('/api/v1/folders/', { params });
+        return ok({ results: res.data.results, pagination: listPaginationEcho(opts, res.data) });
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+export async function runFoldersGet(opts, deps = {}) {
+    try {
+        if (opts.root && opts.id)
+            throw createCliError('VALIDATION', 'pass either a folder id or --root, not both');
+        if (!opts.root && !opts.id)
+            throw createCliError('VALIDATION', 'a folder id or --root is required');
+        const client = clientFor(opts, deps);
+        if (opts.root) {
+            if (!opts.instanceId)
+                throw createCliError('VALIDATION', '--instance-id is required with --root');
+            const res = await client.get(`/api/v1/folders/root/${opts.instanceId}`);
+            return ok(res.data);
+        }
+        const res = await client.get(`/api/v1/folders/${opts.id}`);
+        return ok(res.data);
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+export async function runFoldersCreate(opts, deps = {}) {
+    try {
+        if (!opts.name)
+            throw createCliError('VALIDATION', '--name is required for folders create');
+        if (!opts.parentFolderId)
+            throw createCliError('VALIDATION', '--parent-folder-id is required for folders create');
+        const client = clientFor(opts, deps);
+        const body = { name: opts.name, parent_folder_id: opts.parentFolderId };
+        const accessType = validateAccessType(opts.accessType);
+        if (accessType)
+            body.access_type = accessType;
+        if (opts.rules)
+            body.rules = parseJsonArray(opts.rules, 'rules');
+        const res = await client.post('/api/v1/folders/', body);
+        return ok(res.data);
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+export async function runFoldersUpdate(opts, deps = {}) {
+    try {
+        if (!opts.id)
+            throw createCliError('VALIDATION', 'folder id is required');
+        const client = clientFor(opts, deps);
+        const body = {};
+        if (opts.name)
+            body.name = opts.name;
+        const accessType = validateAccessType(opts.accessType);
+        if (accessType)
+            body.access_type = accessType;
+        if (opts.rules)
+            body.rules = parseJsonArray(opts.rules, 'rules');
+        const res = await client.patch(`/api/v1/folders/${opts.id}`, body);
+        return ok(res.data);
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+export function createFoldersCommand() {
+    const cmd = new Command('folders').description('manage Pitcher content folders');
+    const withAuth = (c) => c
+        .option('--api-key <apiKey>', 'API Key for authentication')
+        .option('--org <organization>', 'Organization subdomain', 'dev')
+        .option('--url <url>', 'Explicit base URL override');
+    withAuth(cmd.command('list'))
+        .requiredOption('--instance-id <id>', 'Instance ID')
+        .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) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runFoldersList({ ...options, quiet: globals.quiet }), globals);
+    });
+    withAuth(cmd.command('get'))
+        .argument('[id]', 'Folder ID (omit and use --root for the instance root)')
+        .option('--root', 'Fetch the instance root folder')
+        .option('--instance-id <id>', 'Instance ID (required with --root)')
+        .action(async (id, options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runFoldersGet({ ...options, id, quiet: globals.quiet }), globals);
+    });
+    withAuth(cmd.command('create'))
+        .requiredOption('--name <name>', 'Folder name')
+        .requiredOption('--parent-folder-id <id>', 'Parent folder ID')
+        .option('--access-type <type>', 'public | restricted | personal')
+        .option('--rules <json>', 'Smart-folder rules JSON array')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runFoldersCreate({ ...options, quiet: globals.quiet }), globals);
+    });
+    withAuth(cmd.command('update'))
+        .argument('<id>', 'Folder ID')
+        .option('--name <name>', 'Folder name')
+        .option('--access-type <type>', 'public | restricted | personal')
+        .option('--rules <json>', 'Smart-folder rules JSON array (replaces existing)')
+        .action(async (id, options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runFoldersUpdate({ ...options, id, quiet: globals.quiet }), globals);
+    });
+    return cmd;
+}

package/dist/src/commands/publishApp.js

@@ -24,9 +24,13 @@ function isVersionAlreadyExistsError(e) {
     const err = e;
     if (err?.response?.status !== 400)
         return false;
-    const data = err.response?.data;
-    const text = typeof data === 'string' ? data : JSON.stringify(data ?? '');
-    return /already exists/i.test(text);
+    // Only the version-release conflict — which the API reports in DRF
+    // `non_field_errors` — is a benign no-op. Don't scan the whole body: an
+    // unrelated 400 that merely mentions "already exists" (e.g. a field-level
+    // name/identifier conflict when creating a NEW app) is a real failure.
+    const nonField = err.response?.data?.non_field_errors;
+    const messages = Array.isArray(nonField) ? nonField : typeof nonField === 'string' ? [nonField] : [];
+    return messages.some((m) => typeof m === 'string' && /version .* already exists/i.test(m));
 }
 function buildVersion(now) {
     const year = now.getFullYear();

package/dist/src/core/baseUrl.js

@@ -6,10 +6,10 @@ export function resolveBaseUrl(opts) {
             parsed = new URL(opts.url);
         }
         catch {
-            throw createCliError('VALIDATION', `Invalid --publish-url: ${opts.url}`);
+            throw createCliError('VALIDATION', `Invalid base URL: ${opts.url}`);
         }
         if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
-            throw createCliError('VALIDATION', `--publish-url must be an http(s) URL: ${opts.url}`);
+            throw createCliError('VALIDATION', `Base URL must be an http(s) URL: ${opts.url}`);
         }
         return parsed.origin;
     }

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

@@ -1,6 +1,16 @@
 import { type AxiosInstance } from 'axios';
 import { type CliError } from './errors.js';
 export declare function makeClient(baseUrl: string, apiKey: string): AxiosInstance;
+export interface CommonOpts {
+    apiKey?: string;
+    org?: string;
+    url?: string;
+    quiet?: boolean;
+}
+/** Resolve auth + base URL into a client, or use an injected one (tests). */
+export declare function clientFor(opts: CommonOpts, deps?: {
+    client?: AxiosInstance;
+}): AxiosInstance;
 /**
  * Build a human-readable message from a server error body. Handles DRF shapes:
  * a `detail`/`error` string, `non_field_errors`, and field-level error arrays

package/dist/src/core/http.js

@@ -1,4 +1,6 @@
 import axios from 'axios';
+import { resolveApiKey } from './auth.js';
+import { resolveBaseUrl } from './baseUrl.js';
 import { createCliError, isCliError } from './errors.js';
 export function makeClient(baseUrl, apiKey) {
     return axios.create({
@@ -9,6 +11,10 @@ export function makeClient(baseUrl, apiKey) {
         },
     });
 }
+/** Resolve auth + base URL into a client, or use an injected one (tests). */
+export function clientFor(opts, deps = {}) {
+    return deps.client ?? makeClient(resolveBaseUrl({ org: opts.org, url: opts.url }), resolveApiKey(opts));
+}
 /**
  * Build a human-readable message from a server error body. Handles DRF shapes:
  * a `detail`/`error` string, `non_field_errors`, and field-level error arrays

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

@@ -0,0 +1,19 @@
+export declare const MAX_PAGE_SIZE = 500;
+export interface PageOpts {
+    page?: number;
+    pageSize?: number;
+}
+/** Page query params to merge into a list request (clamped so sent === echoed). */
+export declare function listPageParams(opts: PageOpts): Record<string, number>;
+/**
+ * Pagination block echoed in the envelope. `count`/`next`/`previous` are
+ * server-truth. `page_size` is echoed ONLY when the caller set it (the clamped
+ * value we sent) — we don't fabricate a default, because the server can apply a
+ * different window than requested (e.g. Django ignores page_size when `id__in`
+ * is present), so a guessed value would misreport what actually happened.
+ */
+export declare function listPaginationEcho(opts: PageOpts, res: {
+    count?: unknown;
+    next?: unknown;
+    previous?: unknown;
+}): Record<string, unknown>;

package/dist/src/core/pagination.js

@@ -0,0 +1,33 @@
+// Shared list-pagination helpers so the page-size cap and default live in ONE
+// place (files.ts and folders.ts both consume these — see PR #4956 review).
+export const MAX_PAGE_SIZE = 500;
+function clampPageSize(pageSize) {
+    return pageSize ? Math.min(pageSize, MAX_PAGE_SIZE) : undefined;
+}
+/** Page query params to merge into a list request (clamped so sent === echoed). */
+export function listPageParams(opts) {
+    const params = {};
+    if (opts.page !== undefined)
+        params.page = opts.page;
+    const pageSize = clampPageSize(opts.pageSize);
+    if (pageSize !== undefined)
+        params.page_size = pageSize;
+    return params;
+}
+/**
+ * Pagination block echoed in the envelope. `count`/`next`/`previous` are
+ * server-truth. `page_size` is echoed ONLY when the caller set it (the clamped
+ * value we sent) — we don't fabricate a default, because the server can apply a
+ * different window than requested (e.g. Django ignores page_size when `id__in`
+ * is present), so a guessed value would misreport what actually happened.
+ */
+export function listPaginationEcho(opts, res) {
+    const pageSize = clampPageSize(opts.pageSize);
+    return {
+        count: res.count,
+        next: res.next,
+        previous: res.previous,
+        page: opts.page ?? 1,
+        ...(pageSize !== undefined ? { page_size: pageSize } : {}),
+    };
+}

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

@@ -0,0 +1,15 @@
+import axios, { type AxiosInstance } from 'axios';
+export interface UploadDeps {
+    put?: typeof axios.put;
+    readFile?: (p: string) => Buffer;
+}
+/**
+ * Upload a local file via the presigned-URL flow and return its content_upload_id.
+ * The S3 PUT uses a BARE axios call (not the Pitcher client) so it carries no
+ * x-api-key, and sends Content-Type equal to the server-signed `type` — omitting
+ * or mismatching it yields a 403 SignatureDoesNotMatch.
+ */
+export declare function uploadFile(client: AxiosInstance, opts: {
+    instanceId: string;
+    filePath: string;
+}, deps?: UploadDeps): Promise<string>;

package/dist/src/core/upload.js

@@ -0,0 +1,30 @@
+import fs from 'fs';
+import path from 'path';
+import axios from 'axios';
+import { createCliError } from './errors.js';
+/**
+ * Upload a local file via the presigned-URL flow and return its content_upload_id.
+ * The S3 PUT uses a BARE axios call (not the Pitcher client) so it carries no
+ * x-api-key, and sends Content-Type equal to the server-signed `type` — omitting
+ * or mismatching it yields a 403 SignatureDoesNotMatch.
+ */
+export async function uploadFile(client, opts, deps = {}) {
+    const readFile = deps.readFile ?? fs.readFileSync;
+    const put = deps.put ?? axios.put;
+    const resolved = path.resolve(opts.filePath);
+    const buffer = readFile(resolved);
+    const name = path.basename(resolved);
+    const createRes = await client.post('/api/v1/uploads/', {
+        name,
+        size: buffer.length,
+        instance_id: opts.instanceId,
+    });
+    const { id, presigned_url, type } = createRes.data;
+    // `type` is required: it's the server-signed Content-Type; sending undefined
+    // yields an opaque S3 403 SignatureDoesNotMatch instead of a clear error.
+    if (!id || !presigned_url || !type) {
+        throw createCliError('NETWORK', 'Upload init failed: /uploads response missing id, presigned_url, or type');
+    }
+    await put(presigned_url, buffer, { headers: { 'Content-Type': type } });
+    return id;
+}

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

@@ -0,0 +1,9 @@
+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 assertIntFlags(opts: {
+    page?: number;
+    pageSize?: number;
+}): void;
+export declare function deepMerge(base: unknown, patch: Record<string, unknown>): Record<string, unknown>;

package/dist/src/schema/content.js

@@ -0,0 +1,57 @@
+import { createCliError } from '../core/errors.js';
+const ACCESS_TYPES = ['public', 'restricted', 'personal'];
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function parseJson(raw, flagName) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw createCliError('VALIDATION', `--${flagName} must be valid JSON`);
+    }
+}
+export function parseJsonObject(raw, flagName) {
+    const parsed = parseJson(raw, flagName);
+    if (!isPlainObject(parsed))
+        throw createCliError('VALIDATION', `--${flagName} must be a JSON object`);
+    return parsed;
+}
+export function parseJsonArray(raw, flagName) {
+    const parsed = parseJson(raw, flagName);
+    if (!Array.isArray(parsed))
+        throw createCliError('VALIDATION', `--${flagName} must be a JSON array`);
+    return parsed;
+}
+export function parseTags(raw) {
+    return raw.split(',').map((t) => t.trim()).filter(Boolean);
+}
+export function validateAccessType(v) {
+    if (v === undefined)
+        return undefined;
+    if (!ACCESS_TYPES.includes(v)) {
+        throw createCliError('VALIDATION', `--access-type must be one of: ${ACCESS_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) {
+    const checks = [
+        ['page', opts.page],
+        ['page-size', opts.pageSize],
+    ];
+    for (const [flag, val] of checks) {
+        if (val !== undefined && (!Number.isInteger(val) || val < 1)) {
+            throw createCliError('VALIDATION', `--${flag} must be a positive integer`);
+        }
+    }
+}
+export function deepMerge(base, patch) {
+    const out = isPlainObject(base) ? { ...base } : {};
+    for (const [k, v] of Object.entries(patch)) {
+        const cur = out[k];
+        out[k] = isPlainObject(v) && isPlainObject(cur) ? deepMerge(cur, v) : v;
+    }
+    return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pitcher/cli-scripts",
-  "version": "2.2.1",
+  "version": "2.3.0",
   "description": "The Pitcher CLI for various tasks in its ecosystem.",
   "author": "Pitcher AG",
   "license": "MIT",
@@ -26,13 +26,13 @@
   ],
   "devDependencies": {
     "@types/archiver": "^7.0.0",
-    "@types/node": "^24.10.9",
+    "@types/node": "^24.13.2",
     "typescript": "^6.0.3",
     "vitest": "^4.1.9"
   },
   "dependencies": {
     "archiver": "^7.0.1",
-    "axios": "^1.16.0",
+    "axios": "^1.18.1",
     "chokidar": "^5.0.0",
     "commander": "^14.0.3",
     "form-data": "^4.0.6"