hymnkeep 0.1.0 → 0.1.2

package/README.md

@@ -30,19 +30,50 @@ hymnkeep put "Gathering Hymn" "O Come, All Ye Faithful" --day 2026-12-27
 hymnkeep put Psalm "Psalm 98" --at "Sun 8:00 AM" --preview
 hymnkeep add-slot "Communion Meditation" --at "Sun 8:00 AM"
 hymnkeep remove-slot Postlude --at Vigil
+hymnkeep remove-slot Communion --at "Sun 8:00 AM" --holding "Ave Maria"
 
 hymnkeep assign "Karis Wolfe" --job Cantor --day 2026-12-27
 hymnkeep assign "Adult Choir" --at "Sun 11:00 AM"
 hymnkeep unassign "Karis Wolfe" --at Vigil
-hymnkeep copy --from "Sat 5:30 PM" --to "Sun 8:00 AM"
+hymnkeep copy --from "Sat 5:30 PM" --to "Sun 8:00 AM" --replace
+
+hymnkeep upload "Shepherd Me (SATB).pdf" --to "Shepherd Me, O God" --part SATB
+hymnkeep upload melody.mp3 --to "Gather Us In" --for tune --part Melody
+```
+
+A command acts on every service of the day unless `--at` names some. Every
+command that changes something takes `--preview`, which says what it would do
+and writes nothing. `--json` prints what Hymnkeep sent, for scripts.
+
+`remove-slot` takes one place from each service. Where a service has the slot
+more than once, it takes the empty one, or the one holding the piece
+`--holding` names. `copy` onto a service that already has music needs
+`--replace` (take the first service's music instead) or `--add` (put it after).
+
+`upload` takes PDF and MP3 files up to 64 MB, onto a piece in your library.
+`--for` puts the file on something the piece reads from instead of the piece
+itself: its tune, its text, or one book's printing, by name.
+
+## Any call
+
+Everything else Hymnkeep can do is one call away. `hymnkeep api` lists the
+calls, and `hymnkeep api <name> …` makes one:
+
+```sh
+hymnkeep api occasions.index from=2026-11-01 to=2026-11-30
+hymnkeep api music.library archived:=true q=gather
+hymnkeep api services.slots.update occasion=<id> service=<id> slot=<id> piece_id=<id> 'spread[<service id>]=replace'
+hymnkeep api music.files.store piece=<id> file=@score.pdf belongs_to=tune --preview
 ```
 
-A command acts on every service of the day unless `--at` names some.
-`--preview` says what it would do and writes nothing. `--json` prints what
-Hymnkeep sent, for scripts.
+- `name=text` for text, and `name:=<json>` for a number, `true`, `null` or a list.
+- `a[b]=value` for a nested field, and `a[]=value` to add to a list.
+- `file=@path` for a file to upload; the call then goes as a form.
+- `--data '<json>'` gives the whole body at once; pairs are added to it.
+- `--preview` shows what would be sent, and sends nothing.
 
-Everything else Hymnkeep can do is one call away: `hymnkeep api` lists the
-calls, and `hymnkeep api <name> key=value …` makes one.
+Ids go in the address, and the other fields where the call takes them. A field
+the call does not list is still sent, with a note saying so.
 
 ## In an AI app
 

package/dist/cli.js

@@ -5,7 +5,8 @@ import { stdin, stdout } from 'node:process';
 import { HymnkeepError, Hymnkeep } from './client.js';
 import { communityFrom, forget, load, save } from './config.js';
 import { serve } from './mcp.js';
-import { call, operation, operations } from './operations.js';
+import { describe, operation, operations, request, send } from './operations.js';
+import { parsePairs } from './params.js';
 import * as tasks from './tasks.js';
 const program = new Command();
 program
@@ -114,8 +115,13 @@ where(program
     .description('Put a piece in a place at every service named, replacing what the place held.')
     .option('--both', 'where the place holds something else, sing both instead of replacing')
     .option('--preview', 'say what it would do, and write nothing')).action((slot, piece, o) => run(() => tasks.put(api(), { when: o.day, slot, piece: piece.join(' '), services: o.at, both: o.both, preview: o.preview })));
-where(program.command('add-slot').argument('<slot>', 'a slot name').description('Add a slot, empty, to every service named.')).action((slot, o) => run(() => tasks.addSlot(api(), { when: o.day, slot, services: o.at })));
-where(program.command('remove-slot').argument('<slot>', 'a slot name').description('Take a slot off every service named.')).action((slot, o) => run(() => tasks.removeSlot(api(), { when: o.day, slot, services: o.at })));
+where(program.command('add-slot').argument('<slot>', 'a slot name').description('Add a slot, empty, to every service named.').option('--preview', 'say what it would do, and write nothing')).action((slot, o) => run(() => tasks.addSlot(api(), { when: o.day, slot, services: o.at, preview: o.preview })));
+where(program
+    .command('remove-slot')
+    .argument('<slot>', 'a slot name')
+    .description('Take a slot, and whatever is in it, off every service named: one place a service.')
+    .option('--holding <piece>', 'where a service has the slot more than once, the one holding this piece')
+    .option('--preview', 'say what it would do, and write nothing')).action((slot, o) => run(() => tasks.removeSlot(api(), { when: o.day, slot, services: o.at, holding: o.holding, preview: o.preview })));
 where(program
     .command('assign')
     .argument('<who...>', 'a person or an ensemble, by name')
@@ -127,21 +133,39 @@ where(program
     .command('unassign')
     .argument('<who...>', 'a person or an ensemble, by name')
     .description('Take a person or an ensemble off every service named.')
-    .option('--job <job>', 'only where they do this job')).action((who, o) => run(() => tasks.unassign(api(), { when: o.day, who: who.join(' '), job: o.job, services: o.at })));
+    .option('--job <job>', 'only where they do this job')
+    .option('--preview', 'say what it would do, and write nothing')).action((who, o) => run(() => tasks.unassign(api(), { when: o.day, who: who.join(' '), job: o.job, services: o.at, preview: o.preview })));
 program
     .command('copy')
     .description("Copy one service's music onto another of the same day.")
     .requiredOption('--from <service>')
     .requiredOption('--to <service>')
     .option('--day <day>', 'a date or an occasion id; the next occasion if left out')
-    .option('--replace', "replace the second service's music rather than adding after it")
-    .action((o) => run(() => tasks.copy(api(), { when: o.day, from: o.from, to: o.to, replace: o.replace })));
+    .option('--replace', "replace the second service's music with the first's")
+    .option('--add', "put the first service's music after what the second has")
+    .option('--preview', 'say what it would do, and write nothing')
+    .action((o) => run(() => tasks.copy(api(), { when: o.day, from: o.from, to: o.to, replace: o.replace, add: o.add, preview: o.preview })));
+program
+    .command('upload')
+    .argument('<files...>', 'PDF or MP3 files, up to 64 MB each')
+    .requiredOption('--to <piece>', 'the piece in the library, by title or id')
+    .option('--for <place>', "where on the piece the file belongs: the tune, the text, or one book's printing (by its name); the piece itself if left out")
+    .option('--part <part>', 'a part the file holds ("Melody", "SATB"); repeat for more', collect)
+    .option('--preview', 'say what it would do, and send nothing')
+    .description('Upload scores and recordings to a piece in the library.')
+    .action((files, o) => run(() => tasks.upload(api(), { files, piece: o.to, place: o.for, parts: o.part, preview: o.preview })));
 program
     .command('api')
     .argument('[call]', 'a call by name; every call is listed if left out')
-    .argument('[params...]', 'name=value for each of its ids and fields')
+    .argument('[params...]', 'its ids and fields: name=text, name:=<json> for a number, true, null or a list, a[b]=value for a nested field, a[]=value to add to a list, file=@path for a file to upload')
     .description('Any call the API offers, by name: the command-line door to everything.')
-    .option('--data <json>', 'the whole body of a write, as JSON')
+    .option('--data <json>', 'the whole body of a write, as JSON; name=value pairs are added to it')
+    .option('--preview', 'show what would be sent, and send nothing')
+    .addHelpText('after', `
+Examples:
+  hymnkeep api occasions.index from=2026-11-01 to=2026-11-30
+  hymnkeep api music.library archived:=true q=gather
+  hymnkeep api music.files.store piece=<id> file=@score.pdf belongs_to=tune --preview`)
     .action(async (name, params, o) => {
     if (!name) {
         for (const op of operations()) {
@@ -150,12 +174,18 @@ program
         return;
     }
     const op = operation(name);
-    const values = o.data ? JSON.parse(o.data) : {};
-    for (const pair of params) {
-        const at = pair.indexOf('=');
-        values[pair.slice(0, at)] = pair.slice(at + 1);
+    const values = parsePairs(params, o.data ? JSON.parse(o.data) : {});
+    const known = new Set([...op.pathParams, ...op.queryParams.map((p) => p.name), ...Object.keys((op.body?.properties ?? {}))]);
+    const unknown = Object.keys(values).filter((field) => !known.has(field));
+    if (unknown.length) {
+        process.stderr.write(`Note: ${op.id} does not list ${unknown.join(', ')}; sending ${unknown.length === 1 ? 'it' : 'them'} anyway.\n`);
+    }
+    const laid = request(op, values);
+    if (o.preview) {
+        stdout.write(`${describe(laid, load()?.url ? api().base : '')}\n`);
+        return;
     }
-    stdout.write(`${JSON.stringify(await call(api(), op, values), null, 2)}\n`);
+    stdout.write(`${JSON.stringify(await send(api(), laid), null, 2)}\n`);
 });
 program
     .command('mcp')

package/dist/client.js

@@ -23,9 +23,20 @@ export class Hymnkeep {
         return this.credentials.community;
     }
     /** `path` is under `/api/p/{community}`, as `occasions` or `occasions/{id}`. */
+    /** Where calls go, for a preview to show. */
+    get base() {
+        return `${this.credentials.url}/api/p/${encodeURIComponent(this.credentials.community)}/`;
+    }
+    /**
+     * `query` is either pairs already named as Laravel reads them, or a plain
+     * object; `form` is a form with files in it, sent instead of a JSON body.
+     */
     async request(method, path, options = {}) {
-        const url = new URL(`${this.credentials.url}/api/p/${encodeURIComponent(this.credentials.community)}/${path.replace(/^\/+/, '')}`);
-        for (const [name, value] of Object.entries(options.query ?? {})) {
+        const url = new URL(`${this.base}${path.replace(/^\/+/, '')}`);
+        if (Array.isArray(options.query)) {
+            options.query.forEach(([name, value]) => url.searchParams.append(name, value));
+        }
+        for (const [name, value] of Array.isArray(options.query) ? [] : Object.entries(options.query ?? {})) {
             if (value === undefined || value === null) {
                 continue;
             }
@@ -33,7 +44,7 @@ export class Hymnkeep {
                 value.forEach((each) => url.searchParams.append(`${name}[]`, String(each)));
             }
             else {
-                url.searchParams.set(name, String(value));
+                url.searchParams.set(name, typeof value === 'boolean' ? (value ? '1' : '0') : String(value));
             }
         }
         const response = await fetch(url, {
@@ -41,10 +52,10 @@ export class Hymnkeep {
             headers: {
                 Authorization: `Bearer ${this.credentials.key}`,
                 Accept: 'application/json',
-                ...(options.body === undefined ? {} : { 'Content-Type': 'application/json' }),
+                ...(options.body === undefined || options.form ? {} : { 'Content-Type': 'application/json' }),
                 'User-Agent': 'hymnkeep-cli',
             },
-            body: options.body === undefined ? undefined : JSON.stringify(options.body),
+            body: options.form ?? (options.body === undefined ? undefined : JSON.stringify(options.body)),
         });
         const text = await response.text();
         const json = text === '' ? null : safeJson(text);

package/dist/mcp.js

@@ -2,7 +2,8 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 import { HymnkeepError } from './client.js';
-import { call, operation, operations } from './operations.js';
+import { describe, operation, operations, request, send } from './operations.js';
+import { Upload } from './params.js';
 import * as tasks from './tasks.js';
 const day = z.string().optional().describe('A date (YYYY-MM-DD) or an occasion id. The next occasion if left out.');
 const at = z.array(z.string()).optional().describe('Services by their time or name ("Sun 8:00 AM", "Vigil"). Every service of the day if left out.');
@@ -27,7 +28,7 @@ async function reply(task) {
     }
 }
 export function build(api) {
-    const server = new McpServer({ name: 'hymnkeep', version: '0.1.0' }, { instructions: INSTRUCTIONS });
+    const server = new McpServer({ name: 'hymnkeep', version: '0.1.2' }, { instructions: INSTRUCTIONS });
     server.registerTool('whoami', { description: 'Who this key is: the community, the person, their role, and whether it may write.', annotations: READ }, () => reply(() => tasks.whoami(api)));
     server.registerTool('week', { description: "An occasion's services, its music place by place (where services differ, each one's), and who is on each service.", inputSchema: { day }, annotations: READ }, ({ day: when }) => reply(() => tasks.show(api, when)));
     server.registerTool('occasions', {
@@ -45,7 +46,7 @@ export function build(api) {
         inputSchema: {
             date: z.string().describe('YYYY-MM-DD'),
             templates: z.array(z.string()).optional().describe('Template ids. The ones the day ticks itself if left out.'),
-            answers: z.record(z.string()).optional().describe("Each question's key and the chosen option's value."),
+            answers: z.record(z.string(), z.string()).optional().describe("Each question's key and the chosen option's value."),
             preview,
         },
         annotations: WRITE,
@@ -64,10 +65,14 @@ export function build(api) {
     }, ({ day: when, slot, piece, services, both, preview: look }) => reply(() => tasks.put(api, { when, slot, piece, services, both, preview: look })));
     server.registerTool('add_slot', {
         description: 'Add a slot, empty, to the services named, at the end of each one\'s list.',
-        inputSchema: { day, slot: z.string().describe("A slot name from the community's list."), services: at },
+        inputSchema: { day, slot: z.string().describe("A slot name from the community's list."), services: at, preview },
         annotations: WRITE,
-    }, ({ day: when, slot, services }) => reply(() => tasks.addSlot(api, { when, slot, services })));
-    server.registerTool('remove_slot', { description: 'Take a slot, and whatever is in it, off the services named.', inputSchema: { day, slot: z.string(), services: at }, annotations: REMOVE }, ({ day: when, slot, services }) => reply(() => tasks.removeSlot(api, { when, slot, services })));
+    }, ({ day: when, slot, services, preview: look }) => reply(() => tasks.addSlot(api, { when, slot, services, preview: look })));
+    server.registerTool('remove_slot', {
+        description: 'Take a slot, and whatever is in it, off the services named: one place a service. Where a service has the slot twice, the empty one goes, or the one holding the piece named.',
+        inputSchema: { day, slot: z.string(), services: at, holding: z.string().optional().describe('The piece in the place to take, where a service has the slot more than once.'), preview },
+        annotations: REMOVE,
+    }, ({ day: when, slot, services, holding, preview: look }) => reply(() => tasks.removeSlot(api, { when, slot, services, holding, preview: look })));
     server.registerTool('assign_musician', {
         description: 'Assign a person to a job, or an ensemble, at the services named. Where someone else does that job, they are replaced unless both is true.',
         inputSchema: {
@@ -80,12 +85,19 @@ export function build(api) {
         },
         annotations: WRITE,
     }, ({ day: when, who, job, services, both, preview: look }) => reply(() => tasks.assign(api, { when, who, job, services, both, preview: look })));
-    server.registerTool('unassign_musician', { description: 'Take a person or an ensemble off the services named.', inputSchema: { day, who: z.string(), job: z.string().optional(), services: at }, annotations: REMOVE }, ({ day: when, who, job, services }) => reply(() => tasks.unassign(api, { when, who, job, services })));
+    server.registerTool('unassign_musician', { description: 'Take a person or an ensemble off the services named.', inputSchema: { day, who: z.string(), job: z.string().optional(), services: at, preview }, annotations: REMOVE }, ({ day: when, who, job, services, preview: look }) => reply(() => tasks.unassign(api, { when, who, job, services, preview: look })));
     server.registerTool('copy_music', {
         description: "Copy one service's music onto another of the same day, after what it has, or replacing it.",
-        inputSchema: { day, from: z.string(), to: z.string(), replace: z.boolean().optional() },
+        inputSchema: {
+            day,
+            from: z.string(),
+            to: z.string(),
+            replace: z.boolean().optional().describe("Take the first service's music instead of the second's."),
+            add: z.boolean().optional().describe("Put the first service's music after the second's. One of the two is needed when the second has music."),
+            preview,
+        },
         annotations: WRITE,
-    }, ({ day: when, from, to, replace }) => reply(() => tasks.copy(api, { when, from, to, replace })));
+    }, ({ day: when, from, to, replace, add, preview: look }) => reply(() => tasks.copy(api, { when, from, to, replace, add, preview: look })));
     server.registerTool('api_calls', {
         description: 'Every call the Hymnkeep API offers, by name, for what the other tools do not cover. Filter by words in the name or summary.',
         inputSchema: { search: z.string().optional() },
@@ -98,15 +110,46 @@ export function build(api) {
         };
     }));
     server.registerTool('api_call', {
-        description: 'Make one API call by name (see api_calls), with its ids and fields in params. A call whose method is not GET writes: say what it will change first.',
-        inputSchema: { name: z.string(), params: z.record(z.unknown()).optional() },
+        description: 'Make one API call by name (see api_calls), with its ids and fields in params. A field that takes a file takes {"file": "<path on this computer>"}. A call whose method is not GET writes: use preview first and show the person.',
+        inputSchema: { name: z.string(), params: z.record(z.string(), z.unknown()).optional(), preview },
         annotations: WRITE,
-    }, ({ name, params }) => reply(async () => {
-        const data = await call(api, operation(name), params ?? {});
-        return { data, text: `${name} done.` };
+    }, ({ name, params, preview: look }) => reply(async () => {
+        const laid = request(operation(name), withFiles(params ?? {}));
+        if (look) {
+            return { data: laid, text: describe(laid, api.base) };
+        }
+        return { data: await send(api, laid), text: `${name} done.` };
     }));
+    server.registerTool('upload_file', {
+        description: "Upload a PDF or MP3 (up to 64 MB) from this computer to a piece in the library: on the piece, or on its tune, its text or one book's printing, with the parts it holds.",
+        inputSchema: {
+            path: z.string().describe('The file on this computer.'),
+            piece: z.string().describe('The piece in the library, by title or id.'),
+            place: z.string().optional().describe("Where on the piece: the tune, the text, or a book's printing, by name. The piece itself if left out."),
+            parts: z.array(z.string()).optional().describe('Parts the file holds, by name ("Melody", "SATB").'),
+            preview,
+        },
+        annotations: WRITE,
+    }, ({ path, piece, place, parts, preview: look }) => reply(() => tasks.upload(api, { files: [path], piece, place, parts, preview: look })));
     return server;
 }
+/** `{"file": "<path>"}` in a call's params is a file to send. */
+function withFiles(params) {
+    const walk = (value) => {
+        if (Array.isArray(value)) {
+            return value.map(walk);
+        }
+        if (value && typeof value === 'object') {
+            const entries = Object.entries(value);
+            if (entries.length === 1 && entries[0][0] === 'file' && typeof entries[0][1] === 'string') {
+                return new Upload(entries[0][1]);
+            }
+            return Object.fromEntries(entries.map(([key, each]) => [key, walk(each)]));
+        }
+        return value;
+    };
+    return walk(params);
+}
 export async function serve(api) {
     await build(api).connect(new StdioServerTransport());
 }

package/dist/operations.js

@@ -1,6 +1,7 @@
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { fit, flatten, hasUpload, Upload } from './params.js';
 const PREFIX = '/api/p/{community}';
 let cached = null;
 /** Every call, read from the description that ships beside the program. */
@@ -18,7 +19,8 @@ export function operations() {
         tag: op.tags[0] ?? '',
         pathParams: (op.parameters ?? []).filter((p) => p.in === 'path' && p.name !== 'community').map((p) => p.name),
         queryParams: (op.parameters ?? []).filter((p) => p.in === 'query').map((p) => ({ name: p.name.replace(/\[\]$/, ''), required: p.required, schema: p.schema })),
-        body: op.requestBody?.content['application/json'].schema ?? null,
+        body: op.requestBody ? (Object.values(op.requestBody.content)[0]?.schema ?? null) : null,
+        form: op.requestBody?.content['multipart/form-data'] !== undefined,
         writes: method !== 'get',
     })));
     return cached;
@@ -31,10 +33,12 @@ export function operation(id) {
     return found;
 }
 /**
- * Makes one call: the path's ids from `params`, the rest as the query of a
- * read or the body of a write.
+ * Lays one call out: the path's ids from `params`, then each field where the
+ * description puts it, in the query or the body. A field the description
+ * does not know goes in the query of a read and the body of a write. A body
+ * with a file in it goes as a form.
  */
-export async function call(api, op, params) {
+export function request(op, params) {
     const rest = { ...params };
     let path = op.path;
     for (const name of op.pathParams) {
@@ -45,8 +49,68 @@ export async function call(api, op, params) {
         path = path.replace(`{${name}}`, encodeURIComponent(String(value)));
         delete rest[name];
     }
-    if (!op.writes || op.method === 'DELETE') {
-        return api.request(op.method, path, { query: rest });
+    const query = {};
+    const body = {};
+    const fields = (op.body?.properties ?? {});
+    for (const [name, value] of Object.entries(rest)) {
+        const inQuery = op.queryParams.find((param) => param.name === name);
+        if (inQuery) {
+            query[name] = fit(value, inQuery.schema);
+        }
+        else if (name in fields || (op.writes && op.method !== 'DELETE') || op.body !== null) {
+            body[name] = fit(value, fields[name]);
+        }
+        else {
+            query[name] = value;
+        }
+    }
+    const hasBody = op.body !== null || Object.keys(body).length > 0;
+    return {
+        method: op.method,
+        path,
+        query: flatten(query).map(([name, value]) => [name, value instanceof Upload ? value.path : value]),
+        body: hasBody ? body : null,
+        form: op.form || hasUpload(body),
+    };
+}
+/** Sends a call laid out by `request`. */
+export function send(api, laid) {
+    if (laid.form && laid.body) {
+        const form = new FormData();
+        for (const [name, value] of flatten(laid.body)) {
+            if (value instanceof Upload) {
+                form.append(name, value.blob(), value.name);
+            }
+            else {
+                form.append(name, value);
+            }
+        }
+        // A form only goes by POST; Laravel reads PATCH and PUT forms through `_method`.
+        if (laid.method !== 'POST') {
+            form.append('_method', laid.method);
+        }
+        return api.request('POST', laid.path, { query: laid.query, form });
+    }
+    return api.request(laid.method, laid.path, { query: laid.query, body: laid.body ?? undefined });
+}
+/** What a call would send, for a person to read before it is sent. */
+export function describe(laid, base = '') {
+    const query = laid.query.length ? `?${laid.query.map(([n, v]) => `${n}=${encodeURIComponent(v)}`).join('&')}` : '';
+    const lines = [`Would send ${laid.method} ${base}${laid.path}${query}`];
+    if (laid.body) {
+        if (laid.form) {
+            for (const [name, value] of flatten(laid.body)) {
+                lines.push(value instanceof Upload ? `  ${name}: the file ${value.path} (${Math.ceil(value.size / 1024)} KB, ${value.type})` : `  ${name}: ${value}`);
+            }
+        }
+        else {
+            lines.push(JSON.stringify(laid.body, null, 2).replace(/^/gm, '  '));
+        }
     }
-    return api.request(op.method, path, { body: rest });
+    lines.push('Nothing was sent.');
+    return lines.join('\n');
+}
+/** Makes one call. */
+export function call(api, op, params) {
+    return send(api, request(op, params));
 }

package/dist/params.js

@@ -0,0 +1,166 @@
+import { readFileSync, statSync } from 'node:fs';
+import { basename, extname } from 'node:path';
+/** A file named on the command line as `field=@path`, read only when it is sent. */
+export class Upload {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+    get name() {
+        return basename(this.path);
+    }
+    get size() {
+        return statSync(this.path).size;
+    }
+    get type() {
+        return { '.pdf': 'application/pdf', '.mp3': 'audio/mpeg' }[extname(this.path).toLowerCase()] ?? 'application/octet-stream';
+    }
+    blob() {
+        return new Blob([readFileSync(this.path)], { type: this.type });
+    }
+    toJSON() {
+        return `@${this.path}`;
+    }
+}
+/**
+ * Reads `name=value` pairs as the old HQ tool did: `key=text`, `key:=<json>`
+ * for a number, true, null or a list, `a[b]=value` for a nested field,
+ * `a[]=value` to add to a list, and `file=@path` for a file to upload.
+ */
+export function parsePairs(pairs, into = {}) {
+    for (const pair of pairs) {
+        const json = pair.match(/^([^=:]+):=(.*)$/s);
+        const text = json ? null : pair.match(/^([^=]+)=(.*)$/s);
+        if (!json && !text) {
+            throw new Error(`"${pair}" needs a value: name=value, or name:=<json> for a number, true or a list.`);
+        }
+        const [, key, raw] = (json ?? text);
+        let value;
+        if (json) {
+            try {
+                value = JSON.parse(raw);
+            }
+            catch {
+                throw new Error(`"${key}:=" takes JSON, and ${raw} is not JSON. For text, write ${key}=${raw}.`);
+            }
+        }
+        else {
+            value = raw.startsWith('@') && raw.length > 1 ? upload(raw.slice(1)) : raw;
+        }
+        place(into, path(key), value);
+    }
+    return into;
+}
+function upload(file) {
+    try {
+        statSync(file);
+    }
+    catch {
+        throw new Error(`There is no file at ${file}.`);
+    }
+    return new Upload(file);
+}
+/** `a[b][]` → ['a', 'b', '']. */
+function path(key) {
+    const match = key.match(/^([^[\]]+)((?:\[[^[\]]*\])*)$/);
+    if (!match) {
+        throw new Error(`"${key}" is not a field name: write a, a[b] or a[].`);
+    }
+    return [match[1], ...[...match[2].matchAll(/\[([^[\]]*)\]/g)].map((m) => m[1])];
+}
+function place(into, keys, value) {
+    const [head, ...rest] = keys;
+    const container = into;
+    if (rest.length === 0) {
+        if (head === '' && Array.isArray(into)) {
+            into.push(value);
+        }
+        else {
+            container[head] = value;
+        }
+        return;
+    }
+    const next = rest[0] === '' ? [] : {};
+    if (head === '' && Array.isArray(into)) {
+        into.push(next);
+        place(next, rest, value);
+        return;
+    }
+    if (container[head] === undefined || typeof container[head] !== 'object' || container[head] === null) {
+        container[head] = next;
+    }
+    place(container[head], rest, value);
+}
+const typeOf = (schema) => (schema?.type === undefined ? [] : Array.isArray(schema.type) ? schema.type : [schema.type]);
+/**
+ * Fits what was typed to what the call takes: one value where a list is
+ * wanted becomes a list of one, and "true", "false" and numbers typed as
+ * text become what the field expects.
+ */
+export function fit(value, schema) {
+    if (schema === undefined || value === null || value instanceof Upload) {
+        return value;
+    }
+    const types = typeOf(schema);
+    if (types.includes('array') && !Array.isArray(value)) {
+        return [fit(value, schema.items)];
+    }
+    if (Array.isArray(value)) {
+        return value.map((each) => fit(each, schema.items));
+    }
+    if (typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([key, each]) => [key, fit(each, schema.properties?.[key])]));
+    }
+    if (typeof value === 'string') {
+        if (types.includes('boolean') && !types.includes('string') && /^(true|false|1|0|yes|no)$/i.test(value)) {
+            return /^(true|1|yes)$/i.test(value);
+        }
+        if ((types.includes('integer') || types.includes('number')) && !types.includes('string') && value.trim() !== '' && Number.isFinite(Number(value))) {
+            return Number(value);
+        }
+    }
+    return value;
+}
+export function hasUpload(value) {
+    if (value instanceof Upload) {
+        return true;
+    }
+    if (Array.isArray(value)) {
+        return value.some(hasUpload);
+    }
+    return typeof value === 'object' && value !== null && Object.values(value).some(hasUpload);
+}
+/**
+ * Flattens a value into bracketed names, `a[0]`, `a[b]`, as Laravel reads a
+ * query string or a form. True and false go as 1 and 0, which is the only
+ * spelling its boolean rule takes outside JSON.
+ */
+export function flatten(values) {
+    const out = [];
+    const walk = (name, value) => {
+        if (value === null || value === undefined) {
+            out.push([name, '']);
+        }
+        else if (value instanceof Upload) {
+            out.push([name, value]);
+        }
+        else if (Array.isArray(value)) {
+            value.forEach((each, index) => walk(`${name}[${index}]`, each));
+        }
+        else if (typeof value === 'object') {
+            for (const [key, each] of Object.entries(value)) {
+                walk(`${name}[${key}]`, each);
+            }
+        }
+        else if (typeof value === 'boolean') {
+            out.push([name, value ? '1' : '0']);
+        }
+        else {
+            out.push([name, String(value)]);
+        }
+    };
+    for (const [key, value] of Object.entries(values)) {
+        walk(key, value);
+    }
+    return out;
+}

package/dist/tasks.js

@@ -1,3 +1,4 @@
+import { Upload } from './params.js';
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const DATE = /^\d{4}-\d{2}-\d{2}$/;
 export function today() {
@@ -21,7 +22,10 @@ function pick(items, wanted, name, what) {
         return found[0];
     }
     const names = (found.length > 1 ? found : items).map((item) => `  ${name(item)[0]}`).join('\n');
-    throw new Error(found.length > 1 ? `More than one ${what} matches "${wanted}":\n${names}` : `No ${what} matches "${wanted}". There are:\n${names}`);
+    if (found.length > 1) {
+        throw new Error(`More than one ${what} matches "${wanted}":\n${names}`);
+    }
+    throw new Error(items.length === 0 ? `No ${what} matches "${wanted}".` : `No ${what} matches "${wanted}". There are:\n${names}`);
 }
 export async function whoami(api) {
     const me = await api.get('whoami');
@@ -184,6 +188,9 @@ export async function addSlot(api, options) {
     const targets = services(found, options.services);
     const { data: slots } = await api.get('slots');
     const slot = pick(slots.filter((s) => !s.hidden), options.slot, (s) => [s.name], 'slot name');
+    if (options.preview) {
+        return { data: { slot, services: targets }, text: `Would add ${slot.name}, empty, at ${targets.map((t) => t.display).join(', ')}. Nothing was sent.` };
+    }
     const reply = await api.post(`occasions/${found.id}/day/slots`, { slot_id: slot.id, service_ids: targets.map((t) => t.id) });
     return { data: reply, text: `Added ${slot.name} at ${targets.map((t) => t.display).join(', ')}.` };
 }
@@ -192,9 +199,30 @@ export async function removeSlot(api, options) {
     const found = await day(api, options.when);
     const targets = services(found, options.services);
     const slotName = pick(uniqueSlots(found), options.slot, (s) => [s.name], 'slot').name;
-    const rows = found.music.filter((row) => row.slot === slotName && targets.some((t) => t.id === row.service_id));
+    const rows = [];
+    // One place a service, never more: where a service has the slot twice,
+    // the empty one goes, or the one holding the piece named.
+    for (const service of targets) {
+        const here = found.music.filter((row) => row.slot === slotName && row.service_id === service.id);
+        const held = options.holding ? here.filter((row) => has(row.title, options.holding)) : here;
+        if (here.length === 0 || (options.holding && held.length === 0)) {
+            continue;
+        }
+        const empty = held.filter((row) => !row.piece_id);
+        if (held.length > 1 && empty.length === 0 && new Set(held.map((row) => row.piece_id)).size > 1) {
+            throw new Error(`${service.display} has ${slotName} ${held.length} times: ${held.map((row) => title(row)).join(', ')}. Say which with --holding <piece>.`);
+        }
+        rows.push(empty[0] ?? held[0]);
+    }
+    if (rows.length === 0) {
+        throw new Error(`None of those services has ${slotName}${options.holding ? ` holding ${options.holding}` : ''}.`);
+    }
+    const where = rows.map((row) => `${found.services.find((s) => s.id === row.service_id)?.display}${row.piece_id ? ` (holding ${title(row)})` : ''}`).join(', ');
+    if (options.preview) {
+        return { data: { remove: rows }, text: `Would take ${slotName} off ${where}. Nothing was sent.` };
+    }
     const reply = await api.post(`occasions/${found.id}/day/slots/remove`, { ids: rows.map((row) => row.id) });
-    return { data: reply, text: `Removed ${slotName} from ${rows.map((row) => found.services.find((s) => s.id === row.service_id)?.display).join(', ')}.` };
+    return { data: reply, text: `Took ${slotName} off ${where}.` };
 }
 /** A person in a job, or an ensemble, at every service named: those where someone else does the job have them replaced. */
 export async function assign(api, options) {
@@ -234,13 +262,18 @@ export async function unassign(api, options) {
     for (const service of targets) {
         const rows = (found.people[service.id] ?? []).filter((a) => a.status !== 'cancelled' && same(a.party, options.who) && (!options.job || same(a.job, options.job)));
         for (const row of rows) {
-            await api.delete(`occasions/${found.id}/services/${service.id}/assignments/${row.id}`);
+            if (!options.preview) {
+                await api.delete(`occasions/${found.id}/services/${service.id}/assignments/${row.id}`);
+            }
             gone.push(service.display);
         }
     }
     if (gone.length === 0) {
         throw new Error(`${options.who} is not on ${targets.map((t) => t.display).join(', ')}.`);
     }
+    if (options.preview) {
+        return { data: { remove: gone }, text: `Would take ${options.who} off ${gone.join(', ')}. Nothing was sent.` };
+    }
     return { data: { removed: gone }, text: `Took ${options.who} off ${gone.join(', ')}.` };
 }
 /** One service's music onto another's, replacing it or after it. */
@@ -248,8 +281,21 @@ export async function copy(api, options) {
     const found = await day(api, options.when);
     const [from] = services(found, [options.from]);
     const [to] = services(found, [options.to]);
+    if (options.replace && options.add) {
+        throw new Error('Say --replace or --add, not both.');
+    }
+    // Adding after music that is already there doubles every place both
+    // services have, so a service with music in it waits to be told which.
+    const there = found.music.filter((row) => row.service_id === to.id);
+    if (there.length > 0 && !options.replace && !options.add) {
+        throw new Error(`${to.display} already has music in ${there.length} places. Say --replace to take ${from.display}'s instead, or --add to put it after.`);
+    }
+    const how = options.replace ? ', replacing what it had' : there.length > 0 ? ', after what it had' : '';
+    if (options.preview) {
+        return { data: { from, to, replace: options.replace ?? false }, text: `Would copy ${from.display}'s music to ${to.display}${how}. Nothing was sent.` };
+    }
     const reply = await api.post(`occasions/${found.id}/services/${to.id}/copy`, { from_service_id: from.id, replace: options.replace ?? false });
-    return { data: reply, text: `Copied ${from.display}'s music to ${to.display}${options.replace ? ', replacing what it had' : ''}.` };
+    return { data: reply, text: `Copied ${from.display}'s music to ${to.display}${how}.` };
 }
 /**
  * A date planned from its templates: what they would write, and any question
@@ -286,3 +332,65 @@ export async function plan(api, options) {
     });
     return { data: reply, text: `Planned ${preview.day.name} on ${options.date}.\n\n${describeDay(reply.data)}` };
 }
+/**
+ * Files (PDF or MP3, up to 64 MB) onto a piece in the library: on the piece
+ * itself, or on a step it reads from (its tune, its text, one book's
+ * printing), with the parts each file holds.
+ */
+export async function upload(api, options) {
+    const files = options.files.map((path) => new Upload(path));
+    const bad = files.filter((file) => !['application/pdf', 'audio/mpeg'].includes(file.type));
+    if (bad.length) {
+        throw new Error(`Hymnkeep takes PDF and MP3 files only: ${bad.map((f) => f.name).join(', ')}.`);
+    }
+    const big = files.filter((file) => file.size > 64 * 1024 * 1024);
+    if (big.length) {
+        throw new Error(`Hymnkeep takes files up to 64 MB: ${big.map((f) => f.name).join(', ')} ${big.length === 1 ? 'is' : 'are'} larger.`);
+    }
+    const pieceId = UUID.test(options.piece) ? options.piece : await libraryPiece(api, options.piece);
+    const { data: shown } = await api.get(`music/${pieceId}`);
+    const places = (shown.belongs_to_options ?? []);
+    const place = options.place ? pick(places, options.place, (p) => [p.label, p.value, p.kind], 'place on this piece') : places.find((p) => p.value === 'piece');
+    const parts = options.parts?.length ? await partIds(api, options.parts) : [];
+    const where = `${shown.display_title ?? shown.title}${place && place.value !== 'piece' ? `, on ${place.label.charAt(0).toLowerCase()}${place.label.slice(1)}` : ''}`;
+    const partText = parts.length ? ` as ${parts.map((p) => p.name).join(', ')}` : '';
+    if (options.preview) {
+        return {
+            data: { piece: pieceId, belongs_to: place?.value ?? 'piece', parts: parts.map((p) => p.id), files: files.map((f) => ({ path: f.path, bytes: f.size, type: f.type })) },
+            text: `Would upload ${files.map((f) => f.name).join(', ')} to ${where}${partText}. Nothing was sent.`,
+        };
+    }
+    const added = [];
+    for (const file of files) {
+        const form = new FormData();
+        form.append('file', file.blob(), file.name);
+        if (place) {
+            form.append('belongs_to', String(place.value));
+        }
+        const reply = await api.request('POST', `music/${pieceId}/files`, { form });
+        if (parts.length) {
+            await api.patch(`music/${pieceId}/files/${reply.file_id}`, { part_ids: parts.map((p) => p.id) });
+        }
+        added.push({ id: reply.file_id, name: file.name });
+    }
+    return { data: { piece: pieceId, files: added }, text: `Uploaded ${added.map((f) => f.name).join(', ')} to ${where}${partText}.` };
+}
+/** A piece in the library by its title. A hymn the community has only in a book has no files of its own to take. */
+async function libraryPiece(api, wanted) {
+    const { data } = await api.get('music/library', { q: wanted });
+    try {
+        return pick(data, wanted, (p) => [p.title, p.display_title].filter(Boolean), 'piece in the library').id;
+    }
+    catch (error) {
+        const { data: found } = await api.get('music', { q: wanted });
+        if (found.pieces.some((p) => !p.id && p.work_id)) {
+            throw new Error(`"${wanted}" is in a hymnal but not in your library, and a file needs a piece in the library. Add it to the library in Hymnkeep first.`);
+        }
+        throw error;
+    }
+}
+async function partIds(api, names) {
+    const { data } = await api.get('parts');
+    const live = data.filter((p) => !p.archived);
+    return names.map((name) => pick(live, name, (p) => [p.name], 'part'));
+}

package/package.json

@@ -1,8 +1,12 @@
 {
     "name": "hymnkeep",
-    "version": "0.1.0",
+    "version": "0.1.2",
     "description": "Hymnkeep from the command line, and as an MCP server for AI apps.",
     "license": "SEE LICENSE IN LICENSE",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/SirRotsen/hymnkeep-cli.git"
+    },
     "type": "module",
     "bin": {
         "hymnkeep": "dist/cli.js"
@@ -25,7 +29,7 @@
     "dependencies": {
         "@modelcontextprotocol/sdk": "1.32.2",
         "commander": "15.0.0",
-        "zod": "3.25.76"
+        "zod": "4.6.7"
     },
     "devDependencies": {
         "@types/node": "22.20.5",