@astrosheep/square 0.3.84 → 0.3.86

package/dist/cli/express-presentation.js

@@ -8,7 +8,7 @@ import { renderExpression } from '../operation-presentation.js';
 import { formatDuration } from '../time.js';
 export { renderExpression } from '../operation-presentation.js';
 export function saveActivityDraft(squarePath, name, body, now = Date.now()) {
-    const draftDir = path.join(path.dirname(squarePath), 'drafts');
+    const draftDir = path.join(/^[A-Za-z][A-Za-z0-9+.-]*:/.test(squarePath) ? process.cwd() : path.dirname(squarePath), 'drafts');
     fs.mkdirSync(draftDir, { recursive: true });
     const hash = crypto.createHash('sha256').update(body).digest('hex').slice(0, 8);
     const stamp = new Date(now).toISOString().replace(/\.\d{3}Z$/, 'Z').replace(/[:.]/g, '-');
@@ -95,7 +95,6 @@ export async function executeExpression(open, squarePath, requestedName, rawInpu
         if (isSquareError(error)) {
             if (error.code === 'behind' && fresh?.activitySummaries !== undefined) {
                 process.stdout.write(renderActivityBlocked({ ...output, retryCommand,
-                    forceCommand: activityRetryCommand(squarePath, name, opts, true),
                     activitySummaries: fresh.activitySummaries.map((summary) => ({ ...summary, previews: [...summary.previews] })),
                 }));
                 exitCode(1);

package/dist/cli/observation-commands.js

@@ -122,7 +122,7 @@ export const streamCommand = {
     async execute(intent, context) {
         const squarePath = requireSquarePath(context);
         if (!intent.ndjson) {
-            process.stderr.write(`✕ interactive stream was removed\nsquare --location ${quoteShell(path.resolve(context.cwd, squarePath))} stream --ndjson\n`);
+            process.stderr.write(`✕ interactive stream was removed\nsquare --location ${quoteShell(/^[A-Za-z][A-Za-z0-9+.-]*:/.test(squarePath) ? squarePath : path.resolve(context.cwd, squarePath))} stream --ndjson\n`);
             process.exitCode = 2;
             return;
         }

package/dist/help.js

@@ -36,8 +36,8 @@ const COMMANDS = [
     },
     { names: ['listen'], usage: '--as <name> listen <participant>', usesSquare: true, group: 'participant', summary: 'Turn an ear toward one participant\'s future activity.' },
     { names: ['unlisten'], usage: '--as <name> unlisten <participant>', usesSquare: true, group: 'participant', summary: 'Stop listening without blocking that participant\'s mentions or replies.' },
-    { names: ['ignore'], usage: '--as <name> ignore <participant>', usesSquare: true, group: 'participant', summary: 'Ignore one participant\'s future mentions and bare says.' },
-    { names: ['listening'], usage: '--as <name> listening', usesSquare: true, group: 'participant', summary: 'Show who you are turned toward.', details: ['Listening is future-only: the edge is fixed when a say lands; it never rewrites history.'] },
+    { names: ['ignore'], usage: '--as <name> ignore <participant>', usesSquare: true, group: 'participant', summary: 'Stop hearing one participant\'s future activity, except bells.' },
+    { names: ['listening'], usage: '--as <name> listening', usesSquare: true, group: 'participant', summary: 'Show who you are turned toward.', details: ['Listening applies to future activity. What you could hear when an activity landed does not change afterward.'] },
     {
         names: ['catch'], usage: '--as <name> catch [--id <activity-id>] [--now | --idle <duration>] [--from <names>] [--mention] [--limit <count>] [--replace]', usesSquare: true, group: 'participant',
         summary: 'Catch directed conversation since you last looked.',
@@ -46,7 +46,7 @@ const COMMANDS = [
     { names: ['done'], usage: '--as <name> done', usesSquare: true, group: 'participant', summary: 'Step out of the square.', details: ['done takes no message. Use express before leaving to send one.'] },
     {
         names: ['stream'], usage: 'stream [--ndjson [--for <name>] [--last <N> | --after <id>]]', usesSquare: true, hiddenFromIndex: true,
-        summary: 'Follow activity without consuming participant presence.',
+        summary: 'Follow activity without marking it caught.',
         details: ['Options:', '  --ndjson       Emit one JSON event per line.', '  --for <name>   With --ndjson, emit notifications for one participant.', '  --last <N>     Emit the last N eligible activities first (default 10, maximum 100).', '  --after <id>   Resume after a canonical activity id (act/12).'],
     },
     {
@@ -121,7 +121,8 @@ export function renderGlobalHelp() {
     ]);
     return [
         'Usage: square [--location <square>] [--as <name>] <command> [args...]',
-        'Environment: SQUARE_LOCATION sets the CLI location; square-accessing commands require it or --location. SQUARE_PARTICIPANT_NAME sets the participant name.',
+        'Environment: SQUARE_LOCATION sets the CLI location (local artifact path or stdio://name/key); square-accessing commands require it or --location. SQUARE_PARTICIPANT_NAME sets the participant name.',
+        'Backends: SQUARE_BACKENDS_CONFIG selects {backends:{name:{command,args?,cwd?,env?}}}; default ~/.config/square/backends.json. See guides/backends.md.',
         'CLI flags override environment values. Participants join explicitly; no square is joined automatically.',
         '',
         ...commandLines,

package/dist/hints.js

@@ -5,10 +5,9 @@ const EXPRESS_HINTS = [
     "say the half-shaped thing — that's what the square is for",
 ];
 const CATCH_HINTS = [
-    "someone @'d you with something you don't need? reply and tell them to stop reaching you",
-    'someone keeps flooding you? ignore them, then tell your human',
-    "nothing to add? quiet is fine — catching is listening too",
     'want to follow one voice? listen to them; unlisten once you have heard enough',
+    "nothing to add? quiet is fine — catching is listening too",
+    'reply to an activity to reach the person who spoke',
 ];
 /** First activity, then every fifth. */
 export function expressHint(ownActivityCount) {

package/dist/index.d.ts

@@ -5,4 +5,5 @@ export { createDefaultWakeTransport } from './notifications.js';
 export { createHostLedgerPort, FileHostLedgerPort } from './host-ledger-file-adapter.js';
 export type { HostLedgerPort, PresenceRecord, EvidenceRecord } from './host-ledger.js';
 export type { PresentationSinkPort } from './ports.js';
+export type * from './square-backend.js';
 export type * from './square-facade.js';

package/dist/open-square.d.ts

@@ -10,6 +10,7 @@ export interface OpenSquare {
     readonly env?: NodeJS.ProcessEnv;
     /** False when a long-lived owner lent the connection; closing this view leaves it open. */
     readonly ownsArtifact: boolean;
+    readonly automaticDelivery?: boolean;
 }
 export interface SquareBuildOptions {
     markdown: string;
@@ -25,6 +26,7 @@ export interface SquareBuildOptions {
 export interface SquareOpenOptions extends Pick<SquareBuildOptions, 'clock' | 'hostLedger' | 'wakeTransport' | 'env' | 'signal'> {
     /** A caller-owned connection to reuse; this view never closes it. */
     readonly artifact?: SquareArtifactPort;
+    readonly automaticDelivery?: boolean;
 }
 export declare function openSquare(squarePath: string, options?: SquareOpenOptions, control?: OperationControl): Promise<OpenSquare>;
 export declare function buildSquare(squarePath: string, options: SquareBuildOptions): Promise<OpenSquare>;

package/dist/open-square.js

@@ -12,7 +12,7 @@ export async function openSquare(squarePath, options = {}, control) {
     try {
         await artifact.read(facts => facts.header(), control?.signal);
         return {
-            artifact, clock: options.clock ?? Date.now, location: squarePath, env, ownsArtifact: borrowed === undefined,
+            artifact, automaticDelivery: options.automaticDelivery, clock: options.clock ?? Date.now, location: squarePath, env, ownsArtifact: borrowed === undefined,
             hostLedger: options.hostLedger ?? createHostLedgerPort({ rootPath: hostLedgerRoot(env) }),
             wakeTransport: options.wakeTransport,
         };

package/dist/operation-presentation.js

@@ -19,9 +19,9 @@ export function renderJoinResult(data) {
         actNumber: event.kind === 'say' ? entry.sayNumbers[event.index] : undefined,
         perception: entry.perceptions[event.index],
     })).filter(Boolean).join('\n\n');
-    const fallback = after.automaticDeliveryAvailable ? [] : [
+    const fallback = after.automaticDeliveryAvailable ? ['', '· when someone calls you, you’ll hear them here'] : [
         '', `${participantCommandPrefix(after.location, name)} catch --idle 30m`,
-        '  the square has no way to call you — keep this catch open and stay within earshot',
+        '  · stay within earshot — keep this catch open for new activity',
     ];
     const entryLine = data.kind === 'joined' ? '● you stepped into the square'
         : data.kind === 'reconnected' ? '● you are already in the square'
@@ -31,7 +31,6 @@ export function renderJoinResult(data) {
         ? '*the flagstones are where you left them. so is your shadow.*' : entry.scene;
     return withPathOutput(after.location, [
         entryLine, '',
-        "· carved into the fountain's edge: every word here lands on a real ear — speak when someone needs it.",
         ...(entryScene === '' ? [] : ['', entryScene]),
         ...(isRejoin || !entry?.joinContext ? [] : ['', style('dim', 'context'), entry.joinContext]),
         ...(after.enrichmentUnavailable ? ['  · joined; recent activity and context are unavailable right now'] : []),
@@ -103,7 +102,7 @@ export function renderCatchOutcome(squarePath, data, options = {}) {
         perception: activity.perception, mention: options.mention ? name : undefined,
     })).filter(Boolean).join('\n\n');
     const remaining = data.remaining === 0 ? ''
-        : `○ ${data.remaining} matching ${data.remaining === 1 ? 'activity remains' : 'activities remain'}\n${continuationCommand(location, name, options)}`;
+        : `· ${data.remaining} matching ${data.remaining === 1 ? 'activity remains' : 'activities remain'}\n${continuationCommand(location, name, options)}`;
     const terminal = stop === undefined ? '' : renderWatchStatus({
         ...statusOptions, status: stop,
         ...(stop === 'stale' && options.idle !== undefined ? { idleMs: options.idle } : {}),
@@ -136,9 +135,9 @@ function renderHistoryProjection(projection, visible, noTruncate, squarePath) {
         }
     }
     if (chunks.length === 0)
-        return 'latest\n  ○ no public activity in this view';
+        return '○ no activity matches this history query';
     if (preview !== undefined && shown.some((activity) => activity.kind === 'say' && activity.body.length > preview)) {
-        chunks.push(`${commandPrefix(squarePath)} history --no-truncate`);
+        chunks.push(`${commandPrefix(squarePath)} history --at ${shown.map((activity) => formatActivityId(activity.index)).join(',')} --no-truncate`);
     }
     if (anchored.length > 0)
         chunks.push(renderPresenceAnchor(anchored));
@@ -203,7 +202,7 @@ export function renderParticipantsResult(squarePath, data, limit = PARTICIPANTS_
     const tail = participants.length <= limit
         ? []
         : [
-            style('dim', `  ○ ${lines.length} of ${participants.length} participants shown`),
+            style('dim', `  · ${lines.length} of ${participants.length} participants shown`),
             ...(participants.length <= PARTICIPANTS_MAX_LIMIT ? [
                 `${participantsLimitCommand(squarePath, participants.length)}`,
             ] : []),
@@ -315,10 +314,10 @@ export function renderListenerChange(squarePath, verb, data) {
     const target = participantIdentity(projection.target);
     const action = data.activity !== null
         ? verb === 'listen' ? `${actor} turns an ear toward ${target}`
-            : verb === 'ignore' ? `${actor} turns away from ${target}`
-                : `${actor} stops listening to ${target}`
+            : verb === 'ignore' ? `${actor} turns away from ${target} — only bells will reach you from them`
+                : `${actor} stops listening to ${target} — direct mentions and replies still reach you unless ignored`
         : verb === 'listen' ? `${actor} already turns an ear toward ${target}`
-            : verb === 'ignore' ? `${actor} is not turned toward ${target}`
+            : verb === 'ignore' ? `${actor} already ignores ${target} — only bells will reach you from them`
                 : `${actor} is not listening to ${target}`;
     return withPathOutput(squarePath, `${data.activity === null ? '○' : '·'} ${action}`, {
         participantCount: projection.standingCount, held: projection.held,

package/dist/participant-host.d.ts

@@ -2,6 +2,7 @@ import type { HostLedgerPort, PresenceChannel, SquareArtifactPort } from './port
 import { type WakeRoute } from './routes.js';
 export interface HostContext {
     readonly artifact: SquareArtifactPort;
+    readonly automaticDelivery?: boolean;
     readonly clock: () => number;
     readonly location?: string;
     readonly hostLedger?: HostLedgerPort;

package/dist/participant-host.js

@@ -7,7 +7,7 @@ export function processIdentity(env) {
     return found === undefined ? { session: `process:${process.pid}`, channel: 'unknown' } : { session: found.sessionId, channel: found.channel };
 }
 export async function identityRouteDraft(context, participant) {
-    if (context.location === undefined || context.location === 'memory')
+    if (context.automaticDelivery === false || context.location === undefined || context.location === 'memory')
         return undefined;
     const identity = processIdentity(context.env ?? process.env);
     if (identity.channel === 'unknown')

package/dist/presentation.d.ts

@@ -22,7 +22,6 @@ interface ActivityLimitOptions extends ParticipantOutputOptions {
 }
 interface ActivityBlockedOptions extends ParticipantOutputOptions {
     retryCommand: string;
-    forceCommand: string;
     activitySummaries: readonly UnreadActivitySummary[];
     draftPath?: string;
 }

package/dist/presentation.js

@@ -9,6 +9,8 @@ import { formatDuration, formatRelativeTime, formatTimestamp } from './time.js';
 import { grepSnippet } from './search.js';
 import { style } from './tty-style.js';
 export function displayPath(squarePath, cwd = process.cwd()) {
+    if (/^[A-Za-z][A-Za-z0-9+.-]*:/.test(squarePath))
+        return squarePath;
     if (!path.isAbsolute(squarePath))
         return squarePath.split(path.sep).join('/');
     const comparableCwd = fs.realpathSync.native(cwd);
@@ -49,7 +51,7 @@ export function commandPrefix(squarePath) {
     return `square --location ${quoteShell(squarePath)}`;
 }
 export function participantCommandPrefix(squarePath, name) {
-    return `square --location ${quoteShell(path.resolve(squarePath))} --as ${quoteShell(name)}`;
+    return `square --location ${quoteShell(/^[A-Za-z][A-Za-z0-9+.-]*:/.test(squarePath) ? squarePath : path.resolve(squarePath))} --as ${quoteShell(name)}`;
 }
 /** Blocked actions end with a full copy-pasteable recovery command. */
 export function joinRecoveryCommand(squarePath, name) {
@@ -171,7 +173,7 @@ function renderEventCliFacts(event, opts = {}) {
                 ? ` · calls your name across the square — ${participantIdentity(mention)}`
                 : '';
             const replySuffix = event.reply === undefined ? '' : ` · replies to ${replyId(event.reply)}`;
-            const meta = ` #${opts.actNumber ?? 1} · ${eventId(event)} · ${formatRelativeTime(event.at, now)}${mentionSuffix}${replySuffix}`;
+            const meta = ` · ${eventId(event)} · ${formatRelativeTime(event.at, now)}${mentionSuffix}${replySuffix}`;
             return { text: `● ${participantIdentity(event.actor)}${style('dim', meta)}${bodySuffix(body.text)}`, bodyClipped: body.clipped };
         }
         case 'done': {
@@ -190,7 +192,7 @@ export function renderEventCli(event, opts = {}) {
 }
 function renderPresenceOnlySay(event, opts = {}) {
     const targets = event.reach === 'bell' ? [] : event.mentions ?? [];
-    const meta = style('dim', ` #${opts.actNumber ?? 1} · ${eventId(event)} · ${formatRelativeTime(event.at, opts.now)}`);
+    const meta = style('dim', ` · ${eventId(event)} · ${formatRelativeTime(event.at, opts.now)}`);
     if (targets.length === 0) {
         return `● ${participantIdentity(event.actor)}${meta}`;
     }
@@ -251,14 +253,12 @@ export function renderPendingFeed(publicItems, sayNumbers, perceptions, viewer)
 export function renderActivityBlocked(opts) {
     const readNowCommand = `${participantCommandPrefix(opts.squarePath, opts.name)} catch`;
     return withPathOutput(opts.squarePath, [
-        `${style('blocked', '✕')} your activity doesn't land — the square moved behind your back`,
+        `${style('blocked', '✕')} your activity hasn't landed — someone spoke while you were away`,
         ...renderUnreadSummary({ activitySummaries: opts.activitySummaries, viewer: opts.name }),
         ...draftSavedLines(opts.draftPath),
         `${readNowCommand}`,
         '  · take it in, then retry:',
         withDraftInput(opts.retryCommand, opts.draftPath),
-        '  · optional: express over unread activity with --force:',
-        withDraftInput(opts.forceCommand, opts.draftPath),
     ].join('\n'), { participantCount: opts.participantCount, held: opts.held });
 }
 /** An indeterminate or already-committed send only points to inspection, never resend. */
@@ -279,14 +279,14 @@ function holdReasonLines(reason) {
     return text === '' ? [] : [style('dim', `  · ${text}`)];
 }
 function heldMainLine(holder, styled) {
-    const glyph = styled ? style('blocked', '✕') : '✕';
+    const glyph = styled ? style('blocked', '✕') : '·';
     const who = holder === undefined ? 'a hand is raised' : `${participantIdentity(holder)} has a hand raised`;
     return `${glyph} ${who} — voices drop, yours too`;
 }
 export function renderExpressWaiting(opts) {
     if (opts.reason === 'throttled') {
         return [
-            '✕ the square is packed — shoulder to shoulder',
+            '· the square is packed — your activity is waiting',
             `  · a lull opens in ${formatDuration(opts.delayMs)}`,
             '  · --no-wait saves a draft and returns now',
         ].join('\n');
@@ -370,7 +370,7 @@ export function renderActivityLimit(opts) {
     const spoken = opts.count !== undefined && opts.hardCap !== undefined ? ` — ${opts.count}/${opts.hardCap} spoken` : '';
     const doneCommand = `${participantCommandPrefix(opts.squarePath, opts.name)} done`;
     return withPathOutput(opts.squarePath, [
-        `${style('blocked', '✕')} nothing left in you${spoken}`,
+        `${style('blocked', '✕')} you’ve reached your speaking cap${spoken}`,
         ...draftSavedLines(opts.draftPath),
         '  · your draft stays unsent; done only steps out',
         doneCommand,
@@ -425,7 +425,7 @@ export function renderWatchStatus(opts) {
             const spoken = opts.hardCap === undefined || opts.hardCap === null
                 ? ''
                 : ` — ${opts.ownActivityCount ?? 0}/${opts.hardCap} spoken`;
-            return [`${style('blocked', '✕')} nothing left in you${spoken}`, `${participantCommandPrefix(opts.squarePath, opts.name)} done`].join('\n');
+            return [`${style('blocked', '✕')} you’ve reached your speaking cap${spoken}`, `${participantCommandPrefix(opts.squarePath, opts.name)} done`].join('\n');
         }
     }
 }

package/dist/sqlite-square.d.ts

@@ -0,0 +1,42 @@
+import type { ActivityResult, HistoryQuery, HistoryResult, JoinOptions, JoinResult, ObservationOptions, OperationControl, Participant, SquareAtInput, SquareBuildInput, SquareLocation, StatusOptions, StatusResult, ParticipantsResult, RecoveryResult, DiscoveryOptions, InboxOptions, InboxResult, StreamOptions } from './square-facade.js';
+export type * from './square-facade.js';
+export { createSquareResourceOwner } from './open-square.js';
+export { formatActivityId, parseActivityId, MAX_IDENTITY_SET_SIZE } from './square-core.js';
+export { CATCH_DEFAULT_LIMIT, CATCH_MAX_LIMIT } from './catch-decisions.js';
+export { HELD_WAIT_BUDGET_MS } from './runtime.js';
+export { HISTORY_DEFAULT_LIMIT, HISTORY_MAX_LIMIT } from './views.js';
+export { DEFAULT_LIST_DEPTH, MAX_LIST_DEPTH, DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT } from './list.js';
+export declare function squareClock(env: NodeJS.ProcessEnv, clock?: () => number): () => number;
+/** One concrete square resource. Request handles may borrow a server-owned connection. */
+export declare class SqliteSquare {
+    readonly location: string;
+    private readonly square;
+    private readonly defaultParticipant?;
+    private readonly transport;
+    private constructor();
+    static at(input: SquareAtInput, control?: OperationControl, automaticDelivery?: boolean): Promise<SqliteSquare>;
+    static build(input: SquareBuildInput, control?: OperationControl, automaticDelivery?: boolean): Promise<SqliteSquare>;
+    static inMemory(input: Omit<SquareBuildInput, 'path' | 'resources'>): SqliteSquare;
+    private handle;
+    participant(requested?: string): Promise<Participant>;
+    join(requested?: string, options?: JoinOptions, control?: OperationControl): Promise<JoinResult>;
+    doneOwnedSession(name: string, body: string, expectedEpoch: number, control?: OperationControl): Promise<ActivityResult>;
+    implicitJoin(name: string, control?: OperationControl): Promise<{
+        readonly state: 'joined' | 'active' | 'done';
+        readonly participant?: Participant;
+    }>;
+    snapshot(control?: OperationControl): Promise<import("./square-facade.js").SquareSnapshot>;
+    history(query?: HistoryQuery, control?: OperationControl): Promise<HistoryResult>;
+    status(options?: StatusOptions, control?: OperationControl): Promise<StatusResult>;
+    participants(options?: ObservationOptions, control?: OperationControl): Promise<ParticipantsResult>;
+    recovery(requested?: string, control?: OperationControl): Promise<RecoveryResult>;
+    stream(options: StreamOptions, control?: OperationControl): AsyncIterable<import("./square-facade.js").StreamRecord>;
+    recognize(env: NodeJS.ProcessEnv): Promise<Participant | null>;
+    close(): Promise<void>;
+    endOwnedSession(name: string, sessionId: string, expectedEpoch?: number): Promise<ActivityResult | null>;
+    retireEndedSessionRoutes(sessionId: string): Promise<void>;
+}
+export declare function diagnoseSquare(input: SquareLocation, control?: OperationControl): Promise<import("./artifact.js").DiagnoseResult>;
+export declare function migrateSquare(input: SquareLocation, control?: OperationControl): Promise<import("./square-migration.js").MigrationOutcome>;
+export declare function discover(input: SquareAtInput, options?: DiscoveryOptions, control?: OperationControl): Promise<import("./square-facade.js").DiscoveryResult>;
+export declare function inbox(input: SquareAtInput, sessionId: string, options?: InboxOptions, control?: OperationControl): Promise<InboxResult>;