clavarium-binder 0.1.1 → 0.1.2-next.2

package/README.md

@@ -37,6 +37,8 @@ way, universal (nothing in it is specific to Clavarium).
   it, or any state after it, only once a person ticked it. An agent proposes,
   and works on what was approved.
 - **See what it was not given.** Access is given per list: read, or change.
+  It may make a list of its own from a template (`binder new batches`): given
+  to it alone, and seen by a person as any other; a few at most.
 - **Delete.** It archives; a person deletes, and deleted is deleted.
 
 ## Without an application

package/bin/binder.mjs

@@ -23,6 +23,8 @@ export const HELP = `binder: the lists you were given, and their records.
   binder attach ID KIND REF ["title"]  KIND: message, file, asset, branch, link, record
   binder detach ID WHAT
   binder archive ID | binder restore ID
+  binder new TEMPLATE ["title"]        a list of your own, when none you were given fits
+                                       TEMPLATE: batches, development, customers, people, roadmap, simple
   binder serve [--store DIR] [--port N] [--side FOLDER=NAME]
                                        keep a binder yourself, with its page (no application)
 
@@ -33,7 +35,7 @@ You never approve: a person ticks what may go on. Talking with them stays in the
 The folder used is --dir FOLDER, else $BINDER_DIR, else the nearest ${FOLDER} folder from here up.
 binder ${VERSION}`;
 
-const VERBS = ['lists', 'show', 'get', 'search', 'add', 'edit', 'move', 'note', 'attach', 'detach', 'archive', 'restore'];
+const VERBS = ['lists', 'show', 'get', 'search', 'add', 'edit', 'move', 'note', 'attach', 'detach', 'archive', 'restore', 'new'];
 
 /* A command line, read: [op, args] or a refusal. */
 export function read(argv) {
@@ -62,6 +64,7 @@ export function read(argv) {
         case 'note': return rest.length >= 2 ? ['note', { id: rest[0], text: rest.slice(1).join(' ') }] : { refused: 'binder note ID "text"' };
         case 'attach': return rest.length >= 3 ? ['attach', { id: rest[0], kind: rest[1], ref: rest[2], title: rest.slice(3).join(' ') }] : { refused: 'binder attach ID KIND REF ["title"]' };
         case 'detach': return rest.length === 2 ? ['detach', { id: rest[0], what: rest[1] }] : { refused: 'binder detach ID WHAT' };
+        case 'new': return rest[0] ? ['create-list', { template: rest[0], title: rest.slice(1).join(' ') || undefined }] : { refused: 'binder new TEMPLATE ["title"]' };
         case 'archive': case 'restore': return rest[0] ? ['archive', { id: rest[0], restore: verb === 'restore' }] : { refused: `binder ${verb} ID` };
         default: return { refused: 'not understood' };
     }

package/docs/protocol.md

@@ -49,9 +49,28 @@ person, what the record is and why; Markdown-ish (paragraphs, `- ` lists,
 `**bold**`, `[text](https://...)` and bare http(s) links), 4000 characters at
 most, empty to remove it. It is in the history like any other change.
 
-A person's alone (from the screen): `approve`, `delete`, `create-list`,
-`edit-list`, `grant`, `archive-list`, `delete-list`; a note is changed by
-whoever wrote it (`edit-note`).
+A person's alone (from the screen): `approve`, `delete`, `edit-list`,
+`grant`, `archive-list`, `delete-list`; a note is changed by whoever wrote it
+(`edit-note`). `create-list` is a person's, and an agent's from a template
+(`binder new TEMPLATE ["title"]`, MCP `new-list`): the list is given to that
+agent alone, to change, and a person sees it as any; per agent, as many such
+lists not archived as the store's setting `agentLists` says.
+
+## The store's settings
+
+A person's alone to change; anyone reads them. Each change is a line of the
+log, op `edit-settings`, with what changed (`change`), and no list or record.
+
+| Setting | What it is | Range | By default |
+|---|---|---|---|
+| `agentLists` | lists an agent may have made and not archived | 0 to 50 (0: an agent makes none) | 5 |
+
+| Op (keeper) | Args | Gives |
+|---|---|---|
+| `settings` | none | `{agentLists}` |
+| `edit-settings` | `{agentLists}` | `{agentLists}`; an agent is refused |
+
+An agent at the limit is refused, and told the number.
 
 ## The application's side
 
@@ -64,6 +83,10 @@ whoever wrote it (`edit-note`).
 
 And the screen: `mount(element, { call, words, lang, people, picture, openAttached })`
 from `clavarium-binder/ui`, with `ui/binder-ui.css` and `ui/texts/*.json`.
+It gives back `refresh()`, `destroy()`, and `open(id)`: one record shown
+whole, in its list, from elsewhere on the page (a list beside a chat);
+it resolves `false`, saying nothing on the screen, for a record not in a
+list shown.
 
 What a card shows: what is set, nothing about what is empty. The fields set
 make one line under its title; its state is said unless the card is in the

package/host/binder-host.mjs

@@ -71,6 +71,8 @@ export function say(op, data, list) {
         case 'attach': return 'Attached.';
         case 'detach': return 'Taken off.';
         case 'archive': return data.archived ? `Archived #${data.id}.` : `Restored #${data.id}.`;
+        case 'settings': case 'edit-settings': return `Lists an agent may make: ${data.agentLists}.`;
+        case 'create-list': return `Made the list ${data.title} [${data.id}], yours to change: binder add ${data.id} "title".`;
         default: return 'Done.';
     }
 }
@@ -104,6 +106,8 @@ export function keeper(dir, { sides = () => [], now = () => Date.now() } = {}) {
                 case 'grant': data = store.grant(a.list, a.to, a.access ?? null, who); break;
                 case 'archive-list': data = store.archiveList(a.list, a.archived !== false, who); break;
                 case 'delete-list': data = store.deleteList(a.list, who); break;
+                case 'settings': data = store.settings(who); break;
+                case 'edit-settings': data = store.editSettings({ agentLists: a.agentLists }, who); break;
                 case 'templates': data = Object.fromEntries(Object.entries(TEMPLATES).map(([k, t]) => [k, t.name])); break;
                 default: return { ok: false, text: `there is no ${oneLine(op, 40)}` };
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clavarium-binder",
-  "version": "0.1.1",
+  "version": "0.1.2-next.2",
   "description": "Clavarium Binder: lists of records kept together by people and AI agents, each with its id (a command and an MCP server for agents, a keeper and a screen for the application). No dependency.",
   "license": "MIT",
   "homepage": "https://github.com/clavarium/clavarium-binder#readme",

package/server/binder.mjs

@@ -23,7 +23,7 @@ import { fileURLToPath } from 'node:url';
 import { randomUUID } from 'node:crypto';
 import { createInterface } from 'node:readline';
 
-export const VERSION = '0.1.1';
+export const VERSION = '0.1.2-next.2';
 export const FOLDER = '.binder';
 /* How long an ask waits for its answer. The keeper answers within a second or two. */
 export const WAIT_MS = 20_000;
@@ -73,6 +73,7 @@ export const TOOLS = [
     { name: 'note', description: 'Add a short note to a record: a decision, a fact, a result. Talking with the person stays in the chat.', inputSchema: { type: 'object', properties: { id: { type: 'string' }, text: { type: 'string' } }, required: ['id', 'text'] } },
     { name: 'attach', description: 'Attach something to a record: a message of the chat, a file, an asset, a branch, a link, another record.', inputSchema: { type: 'object', properties: { id: { type: 'string' }, kind: { type: 'string', enum: ['message', 'file', 'asset', 'branch', 'link', 'record'] }, ref: S('what it is: a path, a URL, repository:branch, a message id, a record number'), title: { type: 'string' } }, required: ['id', 'kind', 'ref'] } },
     { name: 'detach', description: 'Take back something attached to a record.', inputSchema: { type: 'object', properties: { id: { type: 'string' }, what: S('what get shows of it: its ref or its id') }, required: ['id', 'what'] } },
+    { name: 'new-list', description: 'Make a list from a template (batches, development, customers, people, roadmap, simple) when none you were given fits: it is given to you alone, and the person sees it. Batches: the work you propose; the person ticks what you may start.', inputSchema: { type: 'object', properties: { template: S('batches, development, customers, people, roadmap or simple'), title: S('its name; the template\'s by default') }, required: ['template'] } },
     { name: 'archive', description: 'Archive a record (it leaves the list; found again with archived), or restore it.', inputSchema: { type: 'object', properties: { id: { type: 'string' }, restore: { type: 'boolean' } }, required: ['id'] } },
 ];
 /* A tool's arguments as the keeper reads them. */
@@ -90,6 +91,7 @@ export function asked(name, a = {}) {
         case 'attach': return ['attach', { id: a.id, kind: a.kind, ref: a.ref, title: a.title }];
         case 'detach': return ['detach', { id: a.id, what: a.what }];
         case 'archive': return ['archive', { id: a.id, restore: !!a.restore }];
+        case 'new-list': return ['create-list', { template: a.template, title: a.title }];
         default: return null;
     }
 }

package/server/store.mjs

@@ -15,7 +15,12 @@
  * WHO is { id, kind, name }: kind "person" or "agent". A person may do
  * anything. An agent reads or writes a list only where it was given access, and
  * never approves: a record reaches a gate state (or one after it) only once a
- * person approved it.
+ * person approved it. An agent may make a list from a template (as many as a
+ * person set, 5 unless they said): it is given that list alone, to change, and
+ * a person sees it as any.
+ *
+ * SETTINGS: the store's own, a person's alone to change, in the history too.
+ *   agentLists   lists an agent may have made and not archived (0 to 50; 0: none)
  */
 import { readFileSync, writeFileSync, appendFileSync, renameSync, mkdirSync, existsSync, lstatSync } from 'node:fs';
 import { join } from 'node:path';
@@ -23,6 +28,11 @@ import { randomUUID } from 'node:crypto';
 import { seed, TEMPLATES, VIEWS, FIELD_TYPES } from './templates.mjs';
 
 export const TITLE_MAX = 200;
+/* Lists an agent may have made and not archived: 5 until a person sets it (settings.agentLists), 0 to 50. */
+export const AGENT_LISTS_DEFAULT = 5;
+export const AGENT_LISTS_TOP = 50;
+/* The default, by its former name. */
+export const AGENT_LISTS_MAX = AGENT_LISTS_DEFAULT;
 export const NOTE_MAX = 2000;
 /* A record's description: a few lines for a person, what it is and why (Markdown-ish: paragraphs, "- " lists, **bold**, links). */
 export const DESCRIPTION_MAX = 4000;
@@ -114,6 +124,9 @@ export function openStore(dir, { now = () => Date.now() } = {}) {
         count: Object.values(s.records).filter((r) => r.list === l.id && !r.archived).length });
 
     /* Whether a record's title, description or notes hold `q` (lower case). */
+    /* The store's settings, as they are now (a store from before them has the defaults). */
+    const settingsNow = () => ({ agentLists: Number.isInteger(s.settings?.agentLists) ? s.settings.agentLists : AGENT_LISTS_DEFAULT });
+
     const said = (r, q) => r.title.toLowerCase().includes(q) || (r.description ?? '').toLowerCase().includes(q) || r.notes.some((n) => n.text.toLowerCase().includes(q));
 
     const api = {
@@ -163,16 +176,21 @@ export function openStore(dir, { now = () => Date.now() } = {}) {
             return out;
         },
 
-        /* ---- lists: a person's ---- */
+        /* ---- lists: a person's; an agent makes one too, from a template, given to itself alone ---- */
         createList({ template = 'simple', title, lang = 'en' } = {}, who) {
             const w = whoOf(who);
-            if (!isPerson(w)) no('only a person makes a list');
             if (Object.keys(s.lists).length >= LISTS_MAX) no(`${LISTS_MAX} lists at most`);
+            if (!isPerson(w)) {
+                if (!Object.hasOwn(TEMPLATES, String(template))) no(`a list is made from a template: ${Object.keys(TEMPLATES).join(', ')}`);
+                const most = settingsNow().agentLists;
+                if (most === 0) no('a person set 0 lists an agent may make: use one you were given');
+                if (Object.values(s.lists).filter((l) => l.by === w.id && !l.archived).length >= most) no(`${most} lists made by you at most, as a person set: use one of yours`);
+            }
             const base = seed(template, lang);
             const name = oneLine(title, TITLE_MAX) || base.title;
             let id = key(name) || 'list';
             for (let i = 2; s.lists[id]; i++) id = `${key(name) || 'list'}-${i}`;
-            s.lists[id] = { id, ...base, title: name, access: {}, created: stamp(), by: w.id };
+            s.lists[id] = { id, ...base, title: name, access: isPerson(w) ? {} : { [w.id]: 'write' }, created: stamp(), by: w.id };
             save(); log(w, 'create-list', { list: id, change: { title: name, template } });
             return s.lists[id];
         },
@@ -241,6 +259,23 @@ export function openStore(dir, { now = () => Date.now() } = {}) {
             return true;
         },
 
+        /* ---- the store's settings: anyone reads them, a person changes them ---- */
+        settings(who) { whoOf(who); return settingsNow(); },
+        editSettings({ agentLists } = {}, who) {
+            const w = whoOf(who);
+            if (!isPerson(w)) no('only a person changes the settings');
+            const change = {};
+            if (agentLists !== undefined) {
+                const n = typeof agentLists === 'string' && agentLists.trim() !== '' ? Number(agentLists) : agentLists;
+                if (!Number.isInteger(n) || n < 0 || n > AGENT_LISTS_TOP) no(`lists an agent may make: a whole number from 0 to ${AGENT_LISTS_TOP}`);
+                change.agentLists = n;
+            }
+            if (!Object.keys(change).length) return settingsNow();
+            s.settings = { ...s.settings, ...change };
+            save(); log(w, 'edit-settings', { change });
+            return settingsNow();
+        },
+
         /* ---- records ---- */
         add(given, { title, description, state, fields, owners, due, note } = {}, who) {
             const w = whoOf(who);

package/ui/binder-ui.css

@@ -149,6 +149,7 @@ button.binder-who:hover span:not(.binder-dot) { text-decoration: underline; text
 .binder-history { display: flex; flex-direction: column; gap: .3rem; margin-bottom: 1rem; }
 .binder-box { border: 1px solid var(--binder-line); border-radius: var(--binder-radius); background: var(--binder-panel); padding: .7rem .9rem; display: flex; flex-direction: column; gap: .55rem; min-width: 0; }
 .binder-box h3 { font-size: .75rem; letter-spacing: .06em; text-transform: uppercase; color: var(--binder-dim); display: flex; justify-content: space-between; }
+.binder-box input[data-setting] { width: 6em; align-self: flex-start; }
 .binder-log { color: var(--binder-dim); font-size: .85em; }
 .binder-log time { font-variant-numeric: tabular-nums; margin-right: .6em; }
 .binder .binder-warn { color: var(--binder-danger); }

package/ui/binder-ui.js

@@ -11,6 +11,7 @@
  *       openAttached: (a) => void,             a thing attached opened by the page (a message, a file...)
  *   });
  *   b.refresh();   something changed: read again
+ *   b.open(id);    a record shown whole, in its list (resolves false when it is not in a list shown)
  *   b.destroy();
  *
  * Built element by element: nothing a record holds is ever read as HTML.
@@ -21,7 +22,7 @@ export const KEYS = Object.freeze(['lists', 'new-list', 'new-item', 'no-lists',
     'states', 'fields', 'access', 'read', 'write', 'none', 'save', 'empty', 'archived', 'show-archived', 'gate', 'done', 'add-state', 'add-field',
     'kind-message', 'kind-file', 'kind-asset', 'kind-branch', 'kind-link', 'kind-record', 'what', 'name', 'type', 'saved', 'edited', 'by', 'mine', 'all',
     'delete-list', 'delete-list-sure', 'archive-list', 'no-records', 'search', 'description', 'edit', 'more', 'approve', 'add', 'ok',
-    'add-what', 'owner', 'attachment', 'tools', 'cover',
+    'add-what', 'owner', 'attachment', 'tools', 'cover', 'agent-lists',
     'op-add', 'op-edit', 'op-move', 'op-note', 'op-edit-note', 'op-remove-note', 'op-attach', 'op-detach', 'op-archive', 'op-restore', 'op-delete']);
 const KINDS = ['message', 'file', 'asset', 'branch', 'link', 'record'];
 const ICON = { message: '💬', file: '📄', asset: '🗄', branch: '⑂', link: '🔗', record: '▣' };
@@ -161,7 +162,7 @@ export function rich(text) {
 export function mount(root, { call, words = {}, lang = 'en', people = () => [], picture = () => null, openAttached = null } = {}) {
     const w = (k) => words[k] ?? k;
     /* open: what of a record is being changed ('states', 'who', 'description', 'attach'); draft: what was typed, kept across a repaint. */
-    const ui = { lists: [], at: null, data: null, view: null, record: null, mode: 'list', archived: false, mine: false, error: '', open: null, more: false, draft: {}, focus: false };
+    const ui = { lists: [], at: null, data: null, view: null, record: null, mode: 'list', archived: false, mine: false, error: '', open: null, more: false, draft: {}, focus: false, settings: null };
     const box = h('div', { class: 'binder' });
     root.replaceChildren(box);
     let alive = true;
@@ -193,7 +194,7 @@ export function mount(root, { call, words = {}, lang = 'en', people = () => [],
         const menu = ui.open === 'tools' ? h('div', { class: 'binder-menu binder-menu-end', role: 'menu' },
             item(ui.mine, w('mine'), 'mine', () => flip('mine')),
             item(ui.archived, w('archived'), 'archived', () => flip('archived')),
-            l.access === 'write' && l.grants ? item(null, w('settings'), 'settings', () => { ui.open = null; ui.mode = 'settings'; paint(); }) : null) : null;
+            l.access === 'write' && l.grants ? item(null, w('settings'), 'settings', () => { ui.open = null; ui.mode = 'settings'; paint(); void readSettings(); }) : null) : null;
         const chip = (k) => (ui[k] ? h('button', { type: 'button', class: 'binder-chip', 'aria-pressed': 'true', 'data-act': `off-${k}`, onclick: () => flip(k) }, w(k === 'mine' ? 'mine' : 'archived'), h('span', { 'aria-hidden': 'true' }, ' ×')) : null);
         return h('div', { class: 'binder-bar' },
             h('h2', {}, l.title), chip('mine'), chip('archived'),
@@ -422,6 +423,11 @@ export function mount(root, { call, words = {}, lang = 'en', people = () => [],
             attached, addRow, notes, more);
     }
 
+    /* The store's settings, read when its page opens; asked quietly (a keeper without them shows none). */
+    async function readSettings() {
+        try { const r = await call('settings', {}); ui.settings = r?.ok ? r.data : null; } catch { ui.settings = null; }
+        if (ui.mode === 'settings') paint();
+    }
     function settings(l) {
         const title = h('input', { type: 'text', value: l.title, 'aria-label': w('title') });
         const states = l.states.map((s) => ({ ...s }));
@@ -448,12 +454,18 @@ export function mount(root, { call, words = {}, lang = 'en', people = () => [],
         const sure = h('span', { class: 'binder-sure', hidden: true }, w('delete-list-sure'),
             h('button', { type: 'button', class: 'binder-danger', onclick: () => void soft(ask('delete-list', { list: l.id })).then(() => { ui.mode = 'list'; ui.at = null; return refresh(); }) }, w('delete')),
             h('button', { type: 'button', class: 'binder-ghost', onclick: () => { sure.hidden = true; } }, w('cancel')));
+        function agentLists() {
+            const n = h('input', { type: 'number', min: '0', max: '50', step: '1', inputmode: 'numeric', value: String(ui.settings.agentLists), 'aria-label': w('agent-lists'), 'data-setting': 'agentLists' });
+            n.addEventListener('change', () => void soft(ask('edit-settings', { agentLists: n.value })).then((got) => { if (got) ui.settings = got; paint(); }));
+            return n;
+        }
         return h('div', { class: 'binder-page binder-settings' },
             h('div', { class: 'binder-bar' }, h('button', { type: 'button', class: 'binder-ghost', onclick: () => { ui.mode = 'list'; paint(); } }, `‹ ${l.title}`)),
             h('section', { class: 'binder-box' }, h('h3', {}, w('title')), title),
             h('section', { class: 'binder-box' }, h('h3', {}, w('states')), stateRows),
             h('section', { class: 'binder-box' }, h('h3', {}, w('fields')), fieldRows),
             grants.length ? h('section', { class: 'binder-box' }, h('h3', {}, w('access')), grants) : null,
+            ui.settings ? h('section', { class: 'binder-box' }, h('h3', {}, w('agent-lists')), agentLists()) : null,
             h('div', { class: 'binder-actions' },
                 h('button', { type: 'button', class: 'binder-ghost', onclick: () => void soft(ask('archive-list', { list: l.id })).then(() => { ui.mode = 'list'; ui.at = null; return refresh(); }) }, w('archive-list')),
                 h('button', { type: 'button', class: 'binder-ghost', onclick: () => { sure.hidden = false; } }, w('delete-list')), sure,
@@ -491,5 +503,20 @@ export function mount(root, { call, words = {}, lang = 'en', people = () => [],
     document.addEventListener('pointerdown', away);
     document.addEventListener('keydown', escape);
     void refresh();
-    return { refresh, destroy() { alive = false; document.removeEventListener('pointerdown', away); document.removeEventListener('keydown', escape); box.remove(); }, get state() { return { at: ui.at, mode: ui.mode } } };
+    /* One record opened, from elsewhere on the page (a list beside a chat): its list, then it. */
+    async function openRecord(id) {
+        if (!alive) return false;
+        try {
+            /* Asked quietly: a record not found says nothing on the screen. */
+            const got = await call('get', { id: String(id ?? '') });
+            if (!got?.ok) return false;
+            const d = got.data;
+            if (!ui.lists.some((l) => l.id === d.list.id)) await load();
+            if (!ui.lists.some((l) => l.id === d.list.id)) return false;
+            if (ui.at !== d.list.id) { ui.at = d.list.id; ui.view = null; ui.data = await ask('show', { list: ui.at, archived: ui.archived, mine: ui.mine }); }
+            leave(); ui.record = d; ui.mode = 'record'; paint();
+            return true;
+        } catch { return false; }
+    }
+    return { refresh, open: openRecord, destroy() { alive = false; document.removeEventListener('pointerdown', away); document.removeEventListener('keydown', escape); box.remove(); }, get state() { return { at: ui.at, mode: ui.mode } } };
 }

package/ui/texts/en.json

@@ -69,6 +69,7 @@
   "attachment": "Attachment",
   "tools": "More",
   "cover": "Cover",
+  "agent-lists": "Lists an agent may make",
   "op-add": "Created",
   "op-edit": "Edited",
   "op-move": "Moved",

package/ui/texts/fr.json

@@ -69,6 +69,7 @@
   "attachment": "Pièce jointe",
   "tools": "Plus",
   "cover": "À la une",
+  "agent-lists": "Classeurs qu'une IA peut créer",
   "op-add": "Créée",
   "op-edit": "Modifiée",
   "op-move": "Déplacée",