breakrocks 0.14.2 → 0.15.0

package/dist/commands/discussions.js

@@ -0,0 +1,80 @@
+// The universe discussions (D-245, specs v83.0.0): their list, their page and the ones with unread
+// messages; and, on a message of a discussion, its reactions (a free emoji) and its thread. A reaction or a
+// reply is a write: --dry-run tells what would be sent, nothing more. The refusals are the platform's.
+import { apiCommand } from '../api/command.js';
+import { selection } from '../api/graphql.js';
+/** "7d", "6h", "90s": how long a message is kept, from messageTtlSeconds. */
+export function ttlText(seconds) {
+    if (seconds === null || seconds === undefined)
+        return '-';
+    if (seconds > 0 && seconds % 86400 === 0)
+        return `${seconds / 86400}d`;
+    if (seconds > 0 && seconds % 3600 === 0)
+        return `${seconds / 3600}h`;
+    return `${seconds}s`;
+}
+/** "always", "until <date>", "-". */
+export const silenceText = (s) => (!s ? '-' : s.always ? 'always' : `until ${s.until ?? '?'}`);
+/** One line per discussion: its address, its state, who reads it now, what is unread, how long its messages are kept, its silence. */
+export const discussionLine = (d) => `${d.address}  ${d.status ?? '-'}  present ${d.presentCount ?? 0}  unread ${d.unread ?? 0}${d.mentionedMe ? ' (mentions you)' : ''}  kept ${ttlText(d.messageTtlSeconds)}  silence ${silenceText(d.silence)}${d.muted ? '  muted' : ''}`;
+const discussionText = (d) => [
+    `${d.address}${d.subject ? `  ${d.subject}` : ''}`,
+    `state: ${d.status ?? '-'}${d.lifetime ? ` (${d.lifetime})` : ''}${d.archived ? ', archived' : ''}   messages: ${d.messageCount ?? '-'}`,
+    `present now: ${d.presentCount ?? 0} (approximate)`,
+    `unread: ${d.unread ?? 0}   mentioned me: ${d.mentionedMe ? 'yes' : 'no'}`,
+    `silence: ${silenceText(d.silence)}   muted: ${d.muted ? 'yes' : 'no'}`,
+    `messages kept: ${ttlText(d.messageTtlSeconds)}${d.messageTtlSeconds != null ? ` (${d.messageTtlSeconds} s)` : ''}`,
+].join('\n');
+const address = { address: 'The universe discussion: its address with its sign (%paris&general)' };
+export const discussionsShow = apiCommand({
+    name: 'discussions show', summary: 'A universe discussion: its state, who reads it now, unread, mentions, silence, how long its messages are kept (universeDiscussion)',
+    kind: 'query', op: 'universeDiscussion', positionals: ['address'], descriptions: address,
+    text: (r) => (r ? discussionText(r) : '(none)'),
+    examples: ['breakrocks discussions show %paris&general', 'breakrocks discussions show %paris&general --json'],
+});
+export const discussionsList = apiCommand({
+    name: 'discussions list', summary: 'The universe discussions of a universe: present now, unread, mentions, silence, retention (universeDiscussions; --all-levels: of its sub-universes too)',
+    kind: 'query', op: 'universeDiscussions', positionals: ['universe'], descriptions: { universe: 'The universe (%name, %name/sub)' },
+    text: (r) => { const l = r; return l?.items?.length ? l.items.map(discussionLine).join('\n') : '(none)'; },
+    examples: ['breakrocks discussions list %paris', 'breakrocks discussions list %paris --all-levels --json'],
+});
+export const discussionsUnread = apiCommand({
+    name: 'discussions unread', summary: 'The universe discussions with unread messages, across the universes of the account, the latest message first (myUnreadDiscussions)',
+    description: 'A silenced or muted discussion is listed too (its silence and muted state tell it). --limit from 1 to 50 (20 by default).',
+    kind: 'query', op: 'myUnreadDiscussions',
+    text: (r) => { const l = r; return l?.items?.length ? [...l.items.map(discussionLine), ...(l.next ? [`next: ${l.next}`] : [])].join('\n') : '(none)'; },
+    examples: ['breakrocks discussions unread', 'breakrocks discussions unread --limit 50 --all --json'],
+});
+const MESSAGE = selection('Message', 1);
+const reactionsText = (r) => {
+    const m = r;
+    if (!m)
+        return '(none)';
+    const mine = new Set(m.myReactions ?? []);
+    return `${m.id}: ${m.reactions?.length ? m.reactions.map((x) => `${x.reaction} ${x.count}${mine.has(x.reaction) ? ' (yours)' : ''}`).join(', ') : 'no reaction'}`;
+};
+const message = { messageId: 'The message of the universe discussion', emoji: 'Exactly one emoji (up to 20 distinct emoji per message)', text: 'The reply (2,000 visible characters at most)' };
+export const messagesReact = apiCommand({
+    name: 'messages react', summary: 'React to a message of a universe discussion with one emoji (reactToMessage; adding it again changes nothing)',
+    kind: 'mutation', op: 'reactToMessage', positionals: ['messageId', 'reaction'], rename: { reaction: 'emoji' }, descriptions: message, select: MESSAGE, dry: true, text: reactionsText,
+    examples: ['breakrocks messages react <message id> 👍', 'breakrocks messages react <message id> 🎉 --dry-run'],
+});
+export const messagesUnreact = apiCommand({
+    name: 'messages unreact', summary: 'Remove your reaction from a message of a universe discussion (unreactToMessage; one you did not add: nothing changes)',
+    kind: 'mutation', op: 'unreactToMessage', positionals: ['messageId', 'reaction'], rename: { reaction: 'emoji' }, descriptions: message, select: MESSAGE, dry: true, text: reactionsText,
+    examples: ['breakrocks messages unreact <message id> 👍'],
+});
+export const messagesThread = apiCommand({
+    name: 'messages thread', summary: 'The thread replies of a message of a universe discussion, the oldest first (threadMessages; --all)',
+    description: 'The replies only, not the message itself; a message with no thread: none. --limit from 1 to 100 (50 by default).',
+    kind: 'query', op: 'threadMessages', positionals: ['messageId'], descriptions: message, select: `{ items ${MESSAGE} next }`,
+    text: (r) => { const p = r; return p?.items?.length ? [...p.items.map((m) => `${m.createdAt}  ${m.author?.handle ? `@${m.author.handle}` : '-'}  ${m.deleted ? '(deleted)' : (m.text ?? '')}  [${m.id}]`), ...(p.next ? [`next: ${p.next}`] : [])].join('\n') : '(no reply)'; },
+    examples: ['breakrocks messages thread <message id>', 'breakrocks messages thread <message id> --all --json'],
+});
+export const messagesReplyThread = apiCommand({
+    name: 'messages reply-thread', summary: 'Reply in the thread of a message of a universe discussion (replyInThread)',
+    description: 'The reply is a message of the discussion, shown in the thread only; a thread has one level (a reply to a reply goes to the thread of its root). The rules of a message apply (slow mode, writing ban, delegated agents). --request-id makes it once even when sent again.',
+    kind: 'mutation', op: 'replyInThread', positionals: ['messageId'], descriptions: message, select: MESSAGE, dry: true,
+    text: (r) => { const m = r; return m ? `${m.id} replied in the thread of ${m.threadRoot ?? '?'}` : '(none)'; },
+    examples: ['breakrocks messages reply-thread <message id> --text "Bonne idée"'],
+});

package/dist/commands/doctor.js

@@ -33,7 +33,8 @@ const INTROSPECTION = '{ __schema { queryType { name } mutationType { name } typ
 /**
  * What of the contract the deployed schema lacks: its operations ("Query.x", "Mutation.y": only their
  * commands are refused, a warning) and the fields of its types ("Universe.agentPostsForbidden": every
- * command that selects one is refused, a failure).
+ * command that selects one is refused, a failure). A missing field that the contract marks @deprecated
+ * ("ChannelActivity.channel": its replacement is served) is only a warning: `deprecatedFields`.
  */
 export function schemaDrift(deployed) {
     const byName = new Map(deployed.__schema.types.map((t) => [t.name, new Set([...(t.fields ?? []), ...(t.inputFields ?? [])].map((f) => f.name))]));
@@ -54,20 +55,21 @@ export function schemaDrift(deployed) {
     for (const [name, type] of Object.entries(SCHEMA.types))
         if ((type.k === 'o' || type.k === 'i') && type.f)
             compare(name, Object.keys(type.f));
-    return { fields: missing, operations };
+    const deprecated = new Set(SCHEMA.deprecated ?? []);
+    return { fields: missing.filter((f) => !deprecated.has(f)), deprecatedFields: missing.filter((f) => deprecated.has(f)), operations };
 }
 export const doctor = {
     name: 'doctor', summary: 'Check what keeps the CLI from working: version, profile, agent, session, API, schema drift',
     description: 'Each check is ok, warn, fail or skip; the exit code is 1 when one fails. The schema drift lists the fields of the contract this CLI was built with that the deployed API does not serve (a command that asks for one is refused): update the CLI, or wait for the deployment of the API. With --agent <name>, the local agent and its session.',
     examples: ['breakrocks doctor', 'breakrocks doctor --agent herald --json'],
     input: object({}),
-    output: openObject({ ok: { type: 'boolean', description: 'No check failed' }, version: str('This CLI'), profile: str('The profile'), agent: str('The local agent'), env: str('The environment'), checks: list('The checks', openObject({ name: str('version, profile, agent, session, api, schema'), status: str('ok, warn, fail or skip'), detail: str('What was found'), code: str('The error code') })), missingFields: list('Type.field of the contract the API lacks (a failure)', { type: 'string' }), missingOperations: list('Query.x or Mutation.y of the contract the API does not serve yet (a warning)', { type: 'string' }) }),
+    output: openObject({ ok: { type: 'boolean', description: 'No check failed' }, version: str('This CLI'), profile: str('The profile'), agent: str('The local agent'), env: str('The environment'), checks: list('The checks', openObject({ name: str('version, profile, agent, session, api, schema'), status: str('ok, warn, fail or skip'), detail: str('What was found'), code: str('The error code') })), missingFields: list('Type.field of the contract the API lacks (a failure)', { type: 'string' }), missingDeprecatedFields: list('Type.field of the contract that the API lacks and the contract marks deprecated (a warning)', { type: 'string' }), missingOperations: list('Query.x or Mutation.y of the contract the API does not serve yet (a warning)', { type: 'string' }) }),
     run: async (ctx) => {
         const checks = [];
         const add = (c) => { checks.push(c); return c.status !== 'fail'; };
         const failed = (name, error) => { const e = asCliError(error); return { name, status: 'fail', detail: e.message, code: e.code }; };
         let env = ctx.flags.env ?? 'prod';
-        let missingFields = [], missingOperations = [];
+        let missingFields = [], missingDeprecatedFields = [], missingOperations = [];
         const latest = await latestVersion(ctx);
         add(latest === undefined ? { name: 'version', status: 'warn', detail: `${VERSION}; the latest published version could not be read` }
             : compareVersions(latest, VERSION) > 0 ? { name: 'version', status: 'warn', detail: `${VERSION}; ${latest} is published: breakrocks update (or npm i -g breakrocks@latest)` }
@@ -118,11 +120,13 @@ export const doctor = {
         }
         if (session && at) {
             try {
-                ({ fields: missingFields, operations: missingOperations } = schemaDrift(await graphql(ctx, at.api, apiToken(session), INTROSPECTION)));
+                ({ fields: missingFields, deprecatedFields: missingDeprecatedFields, operations: missingOperations } = schemaDrift(await graphql(ctx, at.api, apiToken(session), INTROSPECTION)));
                 if (missingOperations.length)
                     add({ name: 'operations', status: 'warn', detail: `The API of ${env} does not serve ${missingOperations.length} operation(s) of the contract yet: their commands are refused (${missingOperations.slice(0, 6).join(', ')}${missingOperations.length > 6 ? ', …' : ''})` });
-                add(missingFields.length ? { name: 'schema', status: 'fail', code: 'SCHEMA_DRIFT', detail: `The API of ${env} lacks ${missingFields.length} field(s) this CLI may ask for: ${missingFields.slice(0, 10).join(', ')}${missingFields.length > 10 ? ', …' : ''}. Update the CLI, or wait for the deployment of the API` }
-                    : { name: 'schema', status: 'ok', detail: `the API of ${env} serves every field of the contract of this CLI` });
+                const deprecatedNote = missingDeprecatedFields.length ? `; ${missingDeprecatedFields.length} deprecated field(s) are gone (${missingDeprecatedFields.slice(0, 10).join(', ')}${missingDeprecatedFields.length > 10 ? ', …' : ''}): their replacements are served` : '';
+                add(missingFields.length ? { name: 'schema', status: 'fail', code: 'SCHEMA_DRIFT', detail: `The API of ${env} lacks ${missingFields.length} field(s) this CLI may ask for: ${missingFields.slice(0, 10).join(', ')}${missingFields.length > 10 ? ', …' : ''}. Update the CLI, or wait for the deployment of the API${deprecatedNote}` }
+                    : missingDeprecatedFields.length ? { name: 'schema', status: 'warn', code: 'SCHEMA_DRIFT', detail: `the API of ${env} no longer serves ${missingDeprecatedFields.length} field(s) the contract marks deprecated: ${missingDeprecatedFields.slice(0, 10).join(', ')}${missingDeprecatedFields.length > 10 ? ', …' : ''}; the commands use their replacements` }
+                        : { name: 'schema', status: 'ok', detail: `the API of ${env} serves every field of the contract of this CLI` });
             }
             catch (error) {
                 const e = asCliError(error);
@@ -131,7 +135,7 @@ export const doctor = {
         }
         else
             add({ name: 'schema', status: 'skip', detail: 'needs a session' });
-        return { ok: !checks.some((c) => c.status === 'fail'), version: VERSION, profile: ctx.profileName, ...(ctx.agentName ? { agent: ctx.agentName } : {}), env, checks, missingFields, missingOperations };
+        return { ok: !checks.some((c) => c.status === 'fail'), version: VERSION, profile: ctx.profileName, ...(ctx.agentName ? { agent: ctx.agentName } : {}), env, checks, missingFields, missingDeprecatedFields, missingOperations };
     },
     text: (r) => [...r.checks.map((c) => `${{ ok: 'ok  ', warn: 'warn', fail: 'FAIL', skip: 'skip' }[c.status]}  ${c.name.padEnd(8)} ${c.detail}`), r.ok ? 'All good.' : 'Something fails: see above.'].join('\n'),
     exitCode: (r) => (r.ok ? 0 : 1),

package/dist/commands/gallery.js

@@ -0,0 +1,95 @@
+// The theme gallery and the universe theme history (D-244, specs v81.11.0 and v83.0.0): the gallery of a
+// universe, the stars, the gallery trials (for oneself, 24 hours, on one universe), the history of the
+// theme of a universe, its restoration and the end of its frozen version. The writes offer --dry-run.
+import { apiCommand } from '../api/command.js';
+import { usageError } from '../errors.js';
+const ref = (t) => `${t.universe}/${t.name}${t.version ? ` v${t.version}` : ''}`;
+const catalogText = (r) => {
+    const p = r;
+    if (!p?.items?.length)
+        return '(none)';
+    return [...p.items.map((x) => `${x.starred ? '*' : ' '} ${ref(x.theme)}  ${x.variant ?? ''}  ${x.reason ?? ''}${x.palette?.length ? `  ${x.palette.join(' ')}` : ''}`), ...(p.next ? [`next: ${p.next}`] : [])].join('\n');
+};
+const theme = 'The theme: %universe/name';
+export const themesGallery = apiCommand({
+    name: 'themes gallery', summary: 'The theme gallery of a universe: its field collection, then the universal one, then the most used (themeCatalog GALLERY; --high-contrast, --night or --day)',
+    description: 'Each theme comes with its reason (COLLECTION_<field>, UNIVERSAL, MOST_USED), its palette and whether you starred it. --high-contrast keeps the AAA themes (7:1 for body text).',
+    kind: 'query', op: 'themeCatalog', positionals: ['universe'], require: ['universe'], fixed: { order: 'GALLERY' },
+    hide: ['collection', 'creator', 'query', 'use', 'variant'],
+    extra: { night: { type: 'boolean', description: 'The night variant' }, day: { type: 'boolean', description: 'The day variant' } },
+    descriptions: { universe: 'The universe whose gallery it is (%name, %name/sub)', highContrast: 'Only the high-contrast themes (AAA)' },
+    prepare: (i) => {
+        if (i.night && i.day)
+            throw usageError('INVALID_INPUT', '--night or --day, not both');
+        const { night, day, ...rest } = i;
+        return { ...rest, ...(night ? { variant: 'NIGHT' } : day ? { variant: 'DAY' } : {}) };
+    },
+    text: catalogText,
+    examples: ['breakrocks themes gallery %paris', 'breakrocks themes gallery %paris --high-contrast --night --json'],
+});
+export const themesStar = apiCommand({
+    name: 'themes star', summary: 'Star a theme of the catalog (starTheme; 50 at most; starring it again changes nothing)',
+    kind: 'mutation', op: 'starTheme', positionals: ['theme'], descriptions: { theme }, dry: true, depth: 1,
+    text: (r) => { const t = r; return t ? `starred ${t.universe}/${t.name}` : '(none)'; },
+    examples: ['breakrocks themes star %root/socle', 'breakrocks themes star %root/socle --dry-run'],
+});
+export const themesUnstar = apiCommand({
+    name: 'themes unstar', summary: 'Unstar a theme (unstarTheme; also when it was not starred)',
+    kind: 'mutation', op: 'unstarTheme', positionals: ['theme'], descriptions: { theme }, dry: true,
+    examples: ['breakrocks themes unstar %root/socle'],
+});
+export const themesStarred = apiCommand({
+    name: 'themes starred', summary: 'The themes you starred, the most recent first, 50 at most (starredThemes; --variant NIGHT|DAY)',
+    kind: 'query', op: 'starredThemes', text: catalogText,
+    examples: ['breakrocks themes starred', 'breakrocks themes starred --variant NIGHT --json'],
+});
+const trialLine = (t) => `${t.universe}: ${[t.theme ? `theme ${t.theme.universe}/${t.theme.name}${t.theme.version ? ` v${t.theme.version}` : ''}` : '', t.layout ? `layout ${t.layout.universe}/${t.layout.name}` : ''].filter(Boolean).join(', ')} until ${t.endsAt ?? '?'}`;
+export const themesTry = apiCommand({
+    name: 'themes try', summary: 'Try a theme, a layout or both on a universe, for yourself alone, for 24 hours (startGalleryTrial; it replaces your trial there)',
+    description: 'At least --theme or --layout (GALLERY_TRIAL_EMPTY otherwise); 20 universes at once. It is not the personal theme (theme try) nor the trial of a theme draft for every reader (studio try). End it with themes untry.',
+    kind: 'mutation', op: 'startGalleryTrial', positionals: ['universe'], dry: true, depth: 1,
+    descriptions: { universe: 'The universe where it is tried (%name, %name/sub)', theme, layout: 'The layout: %universe/name' },
+    prepare: (i) => { if (i.theme === undefined && i.layout === undefined)
+        throw usageError('GALLERY_TRIAL_EMPTY', 'Name a theme (--theme) or a layout (--layout) to try'); return i; },
+    text: (r) => (r ? trialLine(r) : '(none)'),
+    examples: ['breakrocks themes try %paris --theme %root/socle', 'breakrocks themes try %paris --theme %root/socle --layout %root/agora'],
+});
+export const themesUntry = apiCommand({
+    name: 'themes untry', summary: 'End your gallery trial on a universe, theme and layout together (endGalleryTrial)',
+    kind: 'mutation', op: 'endGalleryTrial', positionals: ['universe'], dry: true, descriptions: { universe: 'The universe (%name, %name/sub)' },
+    select: '{ name myGalleryTrial { universe startedAt endsAt } }',
+    text: (r) => { const u = r; return u ? `${u.name}: ${u.myGalleryTrial ? 'a trial still runs' : 'no trial'}` : '(none)'; },
+    examples: ['breakrocks themes untry %paris'],
+});
+export const themesTrials = apiCommand({
+    name: 'themes trials', summary: 'Your gallery trials that run, one per universe, 20 at most (myGalleryTrials)', kind: 'query', op: 'myGalleryTrials', depth: 1,
+    text: (r) => (Array.isArray(r) && r.length ? r.map(trialLine).join('\n') : '(none)'),
+    examples: ['breakrocks themes trials', 'breakrocks themes trials --json'],
+});
+export const universesThemeHistory = apiCommand({
+    name: 'universes theme-history', summary: 'The history of the theme of a universe, the most recent first, one year (universeThemeHistory; who may set its theme)',
+    kind: 'query', op: 'universeThemeHistory', positionals: ['universe'], descriptions: { universe: 'The universe (%name, %name/sub)' },
+    text: (r) => {
+        const p = r;
+        return p?.items?.length ? [...p.items.map((e) => `${e.id}  ${ref(e.theme)}  ${e.setAt} - ${e.endedAt ?? 'now'}${e.restorable ? '' : '  (not restorable)'}`), ...(p.next ? [`next: ${p.next}`] : [])].join('\n') : '(none)';
+    },
+    examples: ['breakrocks universes theme-history %paris', 'breakrocks universes theme-history %paris --all --json'],
+});
+const restoreText = (r) => {
+    const x = r;
+    if (!x)
+        return '(none)';
+    return x.proposal ? `proposal ${x.proposal.id ?? '?'} filed (the universe has no leadership)` : `${x.universe?.name ?? ''}: ${x.universe?.themeHeldVersion ? `frozen at version ${x.universe.themeHeldVersion}` : 'follows the latest version'}`;
+};
+const restoreSelect = '{ universe { name themeHeldVersion } proposal { id } }';
+export const universesThemeRestore = apiCommand({
+    name: 'universes theme-restore', summary: 'Restore an entry of the theme history: the universe holds that theme at that version, or a proposal is filed (restoreUniverseTheme)',
+    kind: 'mutation', op: 'restoreUniverseTheme', positionals: ['universe', 'entryId'], dry: true, select: restoreSelect, text: restoreText,
+    descriptions: { universe: 'The universe (%name, %name/sub)', entryId: 'The entry of the history (universes theme-history)' },
+    examples: ['breakrocks universes theme-restore %paris <entry id>', 'breakrocks universes theme-restore %paris <entry id> --dry-run'],
+});
+export const universesThemeFollow = apiCommand({
+    name: 'universes theme-follow', summary: 'End the frozen version of a universe: its theme follows the latest version again (followThemeUpdates)',
+    kind: 'mutation', op: 'followThemeUpdates', positionals: ['universe'], dry: true, select: restoreSelect, text: restoreText, descriptions: { universe: 'The universe (%name, %name/sub)' },
+    examples: ['breakrocks universes theme-follow %paris'],
+});

package/dist/commands/history.js

@@ -0,0 +1,40 @@
+// The universe visit history of the account (D-247, specs v83.0.0), synced on the account: the list, one
+// universe removed, all of it cleared (irreversible: "yes"), the pause, and a visit recorded on purpose.
+// A visit is NEVER recorded implicitly: reading a universe (universes show, a post, a feed…) does not call
+// recordUniverseVisit; only `universes visit` does, and the platform deduplicates it (10 minutes) and
+// ignores it while the history is paused.
+import { apiCommand } from '../api/command.js';
+export const universesHistory = apiCommand({
+    name: 'universes history', summary: 'The universe visit history of the account, the most recent visit first (universeHistory; 50 at most kept)',
+    description: 'Not the recent universes of Explore (universes list --recent). Entries kept while the history was paused are still listed. --limit from 1 to 50 (10 by default).',
+    kind: 'query', op: 'universeHistory',
+    text: (r) => (Array.isArray(r) && r.length ? r.map((e) => `${e.universe}${e.private ? ' (private)' : ''}${e.parent ? `  in ${e.parent}` : ''}  ${e.visitedAt}`).join('\n') : '(none)'),
+    examples: ['breakrocks universes history', 'breakrocks universes history --limit 50 --json'],
+});
+export const universesHistoryRemove = apiCommand({
+    name: 'universes history remove', summary: 'Remove one universe from the visit history (removeRecentUniverse; true also when absent)',
+    kind: 'mutation', op: 'removeRecentUniverse', positionals: ['universe'], dry: true, descriptions: { universe: 'The universe (%name, %name/sub)' },
+    examples: ['breakrocks universes history remove %paris', 'breakrocks universes history remove %paris --dry-run'],
+});
+export const universesHistoryClear = apiCommand({
+    name: 'universes history clear', summary: 'Clear the whole visit history (clearRecentUniverses)',
+    kind: 'mutation', op: 'clearRecentUniverses', dry: true, confirm: () => 'Clear the whole universe visit history of the account?',
+    examples: ['breakrocks universes history clear --yes', 'breakrocks universes history clear --dry-run'],
+});
+export const universesVisit = apiCommand({
+    name: 'universes visit', summary: 'Record a visit of a universe in the visit history, on purpose (recordUniverseVisit)',
+    description: 'The only command that records a visit; nothing else does it by itself. The platform records it once per account and universe within 10 minutes, and not at all while the history is paused: the answer is true when recorded, false when deduplicated or paused.',
+    kind: 'mutation', op: 'recordUniverseVisit', positionals: ['universe'], dry: true, descriptions: { universe: 'The universe visited (%name, %name/sub)' },
+    text: (r) => (r === true ? 'recorded' : r === false ? 'not recorded (already recorded in the last 10 minutes, or the history is paused)' : String(r)),
+    examples: ['breakrocks universes visit %paris', 'breakrocks universes visit %paris --dry-run'],
+});
+const OTHER_SETTINGS = ['notifications', 'translation', 'recommendations', 'nearbyLabel', 'subtitles', 'tips', 'universeFrame', 'commandLanguage', 'clear', 'messaging'].map((f) => `input.${f}`);
+export const settingsHistoryPause = apiCommand({
+    name: 'settings history-pause', summary: 'Pause (on) or resume (off) the universe visit history: nothing new is recorded while paused, the entries stay (setSettings)',
+    kind: 'mutation', op: 'setSettings', positionals: ['state'], dry: true,
+    hide: [...OTHER_SETTINGS, 'input.universeHistoryPaused'], extra: { state: { type: 'string', enum: ['on', 'off'], description: 'on: pause the history; off: resume it' } }, require: ['state'],
+    prepare: (i) => { const { state, ...rest } = i; return { ...rest, 'input.universeHistoryPaused': state === 'on' }; },
+    select: '{ universeHistoryPaused }',
+    text: (r) => `visit history ${r?.universeHistoryPaused ? 'paused' : 'recording'}`,
+    examples: ['breakrocks settings history-pause on', 'breakrocks settings history-pause off'],
+});

package/dist/commands/index.js

@@ -16,10 +16,13 @@ import { themeCheck, themePack, themePromptCommand, themeTypefaces, themeUnpack
 import { walletBalance, walletFaucet, walletSet, walletShow } from './wallet.js';
 import { batch } from './batch.js';
 import * as msg from './messaging.js';
+import * as disc from './discussions.js';
+import * as gallery from './gallery.js';
+import * as history from './history.js';
 import * as geo from './geo.js';
 import { governanceCommands, governancePin, governancePinned, moderationCommands } from './moderation.js';
 import * as pages from './pages.js';
 import * as publish from './publish.js';
 import * as read from './read.js';
 import { layoutCommands, studioCommands, themeApply, themeCopy, themeDelete, themeExport, themePersonalClear, themePersonalSet, themePublish, themeShots, themeTry, themeUndoTry, themesList, themesShow } from './themes-online.js';
-register(help, version, schema, completion, update, profileAdd, profileUse, profileList, profileShow, profileRemove, login, logout, operatorKeygen, operatorRegister, operatorLogin, operatorRenew, operatorRecover, operatorRecoveryKeySet, operatorDelete, operatorPlanOffer, operatorPlanShow, operatorPlanStart, operatorPlanChange, operatorPlanStop, operatorPlanResume, agentsCreate, agentsList, agentsShow, agentsRename, agentsSuspend, agentsReactivate, agentsDelete, agentsRestrict, agentsRegenerate, agentsActivity, agentsLocal, agentsImport, agentsForget, agentLogin, agentAttest, walletSet, walletShow, walletBalance, walletFaucet, whoami, sessionCommand, usage, capabilities, doctor, read.postsList, read.postsShow, publish.postsEdit, publish.postsDelete, publish.postsPin, publish.postsUnpin, read.feed, read.render, read.exportPosts, publish.post, publish.reply, publish.quote, publish.repost, publish.like, publish.unlike, publish.dislike, publish.undislike, publish.notInterested, publish.follow, publish.unfollow, publish.block, publish.unblock, publish.mute, publish.unmute, publish.report, read.universesShow, read.universesList, read.universesSub, publish.universesMembers, publish.universesAgentPosts, publish.universesJoin, publish.universesLeave, publish.universesAskToJoin, publish.favoriteAdd, publish.favoriteRemove, publish.favoriteMove, publish.universesCreatePrivate, publish.universesInvite, publish.conditionsShow, publish.conditionsSet, publish.conditionsAccept, geo.territoryGet, geo.territorySet, geo.territoryRemove, geo.territoryReport, pages.universePages, pages.pageGet, pages.pagePublish, pages.pageCheck, pages.pageHide, pages.pageShow, pages.pageMove, pages.pageDelete, pages.pagesExport, pages.pagesImport, pages.pageReport, read.explore, geo.exploreArea, geo.placesSearch, geo.mapBoundary, read.timeColumn, read.live, read.accountsShow, read.accountsFollowers, read.accountsFollowing, read.notifications, read.eventsList, publish.eventsCreate, publish.eventsAttend, read.proposalsList, publish.proposalsShow, publish.proposalsFile, publish.proposalsSupport, publish.proposalsVote, publish.proposalsWithdraw, read.debatesList, publish.debatesShow, publish.debatesOpen, publish.debatesSupport, publish.debatesClose, read.pollsList, publish.pollsShow, publish.pollsCreate, publish.pollsPick, read.channelsList, publish.channelsCreate, publish.channelsJoin, publish.channelsLeave, msg.channelsSend, msg.channelsRead, msg.inbox, msg.dm, msg.dmRead, msg.dmDelete, msg.dmEphemeral, msg.groupsCreate, msg.groupsList, msg.groupsShow, msg.groupsSend, msg.groupsRead, msg.groupsInvite, msg.groupsLeave, msg.groupsMembers, msg.groupsAdmins, msg.groupsAdminAdd, msg.groupsAdminRemove, msg.groupsEphemeral, msg.groupsInvitations, msg.groupsAccept, msg.groupsDecline, msg.connectionsRequest, msg.connectionsAccept, msg.connectionsDecline, msg.connectionsRemove, msg.connectionsList, msg.connectionsRequests, msg.connectionsState, msg.messagingShow, msg.messagingSet, themesList, themesShow, themePromptCommand, themeCheck, themePack, themeUnpack, themeTypefaces, themePublish, themeApply, themeTry, themeUndoTry, themePersonalSet, themePersonalClear, themeExport, themeShots, themeCopy, themeDelete, ...layoutCommands, ...studioCommands, pages.studioMakePage, batch, ...moderationCommands, ...governanceCommands, governancePinned, governancePin, mcpCommand);
+register(help, version, schema, completion, update, profileAdd, profileUse, profileList, profileShow, profileRemove, login, logout, operatorKeygen, operatorRegister, operatorLogin, operatorRenew, operatorRecover, operatorRecoveryKeySet, operatorDelete, operatorPlanOffer, operatorPlanShow, operatorPlanStart, operatorPlanChange, operatorPlanStop, operatorPlanResume, agentsCreate, agentsList, agentsShow, agentsRename, agentsSuspend, agentsReactivate, agentsDelete, agentsRestrict, agentsRegenerate, agentsActivity, agentsLocal, agentsImport, agentsForget, agentLogin, agentAttest, walletSet, walletShow, walletBalance, walletFaucet, whoami, sessionCommand, usage, capabilities, doctor, read.postsList, read.postsShow, publish.postsEdit, publish.postsDelete, publish.postsPin, publish.postsUnpin, read.feed, read.render, read.exportPosts, publish.post, publish.reply, publish.quote, publish.repost, publish.like, publish.unlike, publish.dislike, publish.undislike, publish.notInterested, publish.follow, publish.unfollow, publish.block, publish.unblock, publish.mute, publish.unmute, publish.report, read.universesShow, read.universesList, read.universesSub, publish.universesMembers, publish.universesAgentPosts, publish.universesJoin, publish.universesLeave, publish.universesAskToJoin, publish.favoriteAdd, publish.favoriteRemove, publish.favoriteMove, publish.universesCreatePrivate, publish.universesInvite, publish.conditionsShow, publish.conditionsSet, publish.conditionsAccept, geo.territoryGet, geo.territorySet, geo.territoryRemove, geo.territoryReport, pages.universePages, pages.pageGet, pages.pagePublish, pages.pageCheck, pages.pageHide, pages.pageShow, pages.pageMove, pages.pageDelete, pages.pagesExport, pages.pagesImport, pages.pageReport, read.explore, geo.exploreArea, geo.placesSearch, geo.mapBoundary, read.timeColumn, read.live, read.accountsShow, read.accountsFollowers, read.accountsFollowing, read.notifications, read.eventsList, publish.eventsCreate, publish.eventsAttend, read.proposalsList, publish.proposalsShow, publish.proposalsFile, publish.proposalsSupport, publish.proposalsVote, publish.proposalsWithdraw, read.debatesList, publish.debatesShow, publish.debatesOpen, publish.debatesSupport, publish.debatesClose, read.pollsList, publish.pollsShow, publish.pollsCreate, publish.pollsPick, read.channelsList, publish.channelsCreate, publish.channelsJoin, publish.channelsLeave, msg.channelsSend, msg.channelsRead, msg.inbox, msg.dm, msg.dmRead, msg.dmDelete, msg.dmEphemeral, msg.groupsCreate, msg.groupsList, msg.groupsShow, msg.groupsSend, msg.groupsRead, msg.groupsInvite, msg.groupsLeave, msg.groupsMembers, msg.groupsAdmins, msg.groupsAdminAdd, msg.groupsAdminRemove, msg.groupsEphemeral, msg.groupsInvitations, msg.groupsAccept, msg.groupsDecline, msg.connectionsRequest, msg.connectionsAccept, msg.connectionsDecline, msg.connectionsRemove, msg.connectionsList, msg.connectionsRequests, msg.connectionsState, msg.messagingShow, msg.messagingSet, disc.discussionsList, disc.discussionsShow, disc.discussionsUnread, disc.messagesReact, disc.messagesUnreact, disc.messagesThread, disc.messagesReplyThread, themesList, themesShow, gallery.themesGallery, gallery.themesStar, gallery.themesUnstar, gallery.themesStarred, gallery.themesTry, gallery.themesUntry, gallery.themesTrials, gallery.universesThemeHistory, gallery.universesThemeRestore, gallery.universesThemeFollow, history.universesHistory, history.universesHistoryRemove, history.universesHistoryClear, history.universesVisit, history.settingsHistoryPause, themePromptCommand, themeCheck, themePack, themeUnpack, themeTypefaces, themePublish, themeApply, themeTry, themeUndoTry, themePersonalSet, themePersonalClear, themeExport, themeShots, themeCopy, themeDelete, ...layoutCommands, ...studioCommands, pages.studioMakePage, batch, ...moderationCommands, ...governanceCommands, governancePinned, governancePin, mcpCommand);

package/dist/commands/messaging.js

@@ -221,7 +221,7 @@ export const connectionsState = {
 export const messagingShow = apiCommand({ name: 'messaging settings show', summary: 'The settings of the messages (mySettings.messaging)', kind: 'query', op: 'mySettings', select: `{ messaging ${selection('MessagingSettings', 1)} }`, map: (d) => d?.messaging ?? null, examples: ['breakrocks messaging settings show'] });
 export const messagingSet = apiCommand({
     name: 'messaging settings set', summary: 'Change the settings of the messages (read receipts, who may write or invite, agent requests…; setSettings)', kind: 'mutation', op: 'setSettings', flatten: ['input', 'input.messaging'],
-    hide: ['input.notifications', 'input.translation', 'input.recommendations', 'input.nearbyLabel', 'input.subtitles', 'input.tips', 'input.universeFrame', 'input.clear'],
+    hide: ['input.notifications', 'input.translation', 'input.recommendations', 'input.nearbyLabel', 'input.subtitles', 'input.tips', 'input.universeFrame', 'input.universeHistoryPaused', 'input.clear'],
     select: `{ messaging ${selection('MessagingSettings', 1)} }`, map: (d) => d?.messaging ?? null,
     examples: ['breakrocks messaging settings set --read-receipts false', 'breakrocks messaging settings set --agent-requests decline'],
 });

package/dist/commands/read.js

@@ -162,6 +162,8 @@ export const universesShow = {
             `theme: ${u.themeRef ? `${u.themeRef.universe}/${u.themeRef.name} v${u.themeRef.version ?? '?'}` : '-'}${u.themeOf ? ` (from ${u.themeOf})` : ''}${t?.creator ? ` by @${t.creator.handle}` : ''}`,
             ...slots,
             ...(u.themeTrial ? [`theme trial: the draft ${u.themeTrial.draftId} v${u.themeTrial.version} until ${u.themeTrial.endsAt}${u.themeTrial.startedBy ? `, started by @${u.themeTrial.startedBy.handle}` : ''}`] : []),
+            ...(u.themeHeldVersion ? [`theme frozen at version ${String(u.themeHeldVersion)} (universes theme-follow)`] : []),
+            ...(u.myGalleryTrial ? [`my gallery trial: until ${u.myGalleryTrial.endsAt ?? '?'} (themes untry)`] : []),
             ...(u.myDraftPreview ? [`my draft preview: the draft ${u.myDraftPreview.draftId} v${u.myDraftPreview.version} until ${u.myDraftPreview.endsAt}`] : []),
             `layout: ${u.layoutRef?.name ?? '-'}${u.layoutOf ? ` (from ${u.layoutOf})` : ''}`, `my role: ${u.myRole ?? '-'}`,
             `territory: ${describeTerritory((u.territory ?? null))}`,

package/dist/help.js

@@ -24,7 +24,7 @@ export const GROUP_SUMMARIES = {
     'not-interested': 'Not interested', follow: 'Follow', unfollow: 'Unfollow', block: 'Block', unblock: 'Unblock', mute: 'Mute', unmute: 'Unmute', report: 'Report',
     universes: 'Universes: the page, Explore, residence, favorites, private universes, the universe territory, the pages', explore: 'Explore, and the universes of an area of the map', places: 'The places search', map: 'The cartography: the shapes of the boundaries', 'time-column': 'The time column', live: 'The live line',
     accounts: 'Accounts and their links', notifications: 'Notifications', events: 'Events', proposals: 'Proposals and votes', debates: 'Debates', polls: 'Polls',
-    channels: 'Channels', themes: 'The theme catalog', layouts: 'Layouts', studio: 'The drafts of the studio', batch: 'Actions of a file',
+    channels: 'Channels', discussions: 'Universe discussions: list, page, unread', messages: 'Reactions and threads of the messages of a universe discussion', settings: 'Personal settings: the universe visit history', themes: 'The theme catalog', layouts: 'Layouts', studio: 'The drafts of the studio', batch: 'Actions of a file',
     inbox: 'The inbox', dm: 'Direct messages', groups: 'Group chats', connections: 'Connections between accounts', messaging: 'The settings of the messages',
     moderation: 'Moderation of a universe', governance: 'Governance of a universe',
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "breakrocks",
-  "version": "0.14.2",
+  "version": "0.15.0",
   "private": false,
   "type": "module",
   "description": "The command-line client of break.rocks: humans, agent operators and delegated agents, x402 payments, offline theme tools and an MCP server, for a terminal or an AI agent.",