@astrosheep/square 0.3.2

package/dist/runtime.js

@@ -0,0 +1,304 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { fold } from './square-core.js';
+import { renderSquareDoc, saveRuntimeSidecar } from './artifact.js';
+import { SquareError, findParticipantName, nameKey, sameName, } from './model.js';
+function parseIntegerEnvValue(name, raw, fallback) {
+    if (raw === undefined)
+        return fallback;
+    const value = parseInt(raw, 10);
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new SquareError('invalid_args', `Invalid ${name}: expected a positive integer.`);
+    }
+    return value;
+}
+function parseIntegerEnv(name, fallback) {
+    return parseIntegerEnvValue(name, process.env[name], fallback);
+}
+function parseIntegerEnvAlias(primary, aliases, fallback) {
+    const candidates = [primary, ...aliases];
+    for (const name of candidates) {
+        if (process.env[name] !== undefined)
+            return parseIntegerEnvValue(name, process.env[name], fallback);
+    }
+    return fallback;
+}
+function parseScaleEnv(name, fallback) {
+    const raw = process.env[name];
+    if (raw === undefined)
+        return fallback;
+    const value = parseFloat(raw);
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new SquareError('invalid_args', `Invalid ${name}: expected a positive number.`);
+    }
+    return value;
+}
+function scaledMs(baseMs, scale) {
+    return Math.max(1, Math.round(baseMs * scale));
+}
+export const WATCH_HEARTBEAT_MS = parseIntegerEnv('SQUARE_WATCH_HEARTBEAT_MS', 60000);
+export const SLEEP_MS = parseIntegerEnvAlias('SQUARE_WATCH_POLL_MS', ['SQUARE_SLEEP_MS'], scaledMs(WATCH_HEARTBEAT_MS, parseScaleEnv('SQUARE_WATCH_POLL_SCALE', 1 / 6)));
+export const STALE_MS = parseIntegerEnvAlias('SQUARE_WATCH_QUIET_MS', ['SQUARE_STALE_MS'], scaledMs(WATCH_HEARTBEAT_MS, parseScaleEnv('SQUARE_WATCH_QUIET_SCALE', 5)));
+export const WATCH_STALE_MS = parseIntegerEnv('SQUARE_WATCH_STALE_MS', scaledMs(WATCH_HEARTBEAT_MS, parseScaleEnv('SQUARE_WATCH_STALE_SCALE', 3)));
+export const LOCK_RETRY_MS = parseIntegerEnv('SQUARE_LOCK_RETRY_MS', 25);
+export const LOCK_STALE_MS = parseIntegerEnv('SQUARE_LOCK_STALE_MS', 30000);
+export const THROTTLE_WINDOW_MS = parseIntegerEnv('SQUARE_THROTTLE_WINDOW_MS', 60000);
+export const UNREAD_BLOCK_GRACE_MS = parseIntegerEnv('SQUARE_UNREAD_BLOCK_GRACE_MS', 90000);
+export function nowMs() {
+    const override = process.env.SQUARE_NOW_MS;
+    if (override === undefined)
+        return Date.now();
+    const value = parseInt(override, 10);
+    if (!Number.isFinite(value)) {
+        throw new SquareError('invalid_args', 'Invalid SQUARE_NOW_MS: expected integer milliseconds.');
+    }
+    return value;
+}
+export function extractMentions(body) {
+    const matches = [];
+    const re = /@([\p{L}\p{N}_-]+)/gu;
+    let match;
+    while ((match = re.exec(body)) !== null)
+        matches.push(match[1]);
+    return matches;
+}
+/** Pure mention filter for say acts. Broadcast bodies (no @) match any named viewer. */
+export function matchesMentionTarget(act, mention) {
+    const mentions = extractMentions(act.body);
+    if (mention === true)
+        return mentions.length > 0;
+    if (mentions.length === 0)
+        return true;
+    return mentions.some((name) => sameName(name, mention));
+}
+export function foldedState(doc) {
+    return fold(doc.acts);
+}
+export function rosterNames(doc) {
+    return foldedState(doc).participants.map((participant) => participant.name);
+}
+export function inSquareCount(doc) {
+    return foldedState(doc).joined.length;
+}
+export function resolveRosterName(doc, name) {
+    return findParticipantName(rosterNames(doc), name);
+}
+export function hasQuorum(doc, name, outs) {
+    const peers = rosterNames(doc).filter((participant) => !sameName(participant, name));
+    return peers.length > 0 && peers.every((peer) => outs.has(nameKey(peer)));
+}
+export function countSays(acts, name) {
+    return acts.filter((act) => act.kind === 'say' && sameName(act.actor, name)).length;
+}
+export function sayNumberFor(acts, target) {
+    if (target.kind !== 'say')
+        throw new Error('sayNumberFor only applies to say acts');
+    let number = 0;
+    for (const act of acts) {
+        if (act.kind === 'say' && sameName(act.actor, target.actor))
+            number++;
+        if (act === target)
+            return number;
+        if (target.index !== undefined && act.index === target.index)
+            return number;
+    }
+    throw new Error('target say act is not present in act history');
+}
+export function doneNames(acts) {
+    return new Set(fold(acts).done.map((participant) => nameKey(participant)));
+}
+export function hasJoined(acts, name) {
+    return fold(acts).participants.some((participant) => sameName(participant.name, name) && participant.joined);
+}
+export function joinedNames(acts) {
+    return new Set(acts.filter((act) => act.kind === 'join').map((act) => nameKey(act.actor)));
+}
+export function isCurrentlyJoined(acts, name) {
+    return fold(acts).participants.some((participant) => sameName(participant.name, name) && participant.joined);
+}
+/** Timestamp of the recipient's most recent join act, if any. */
+export function lastJoinAt(acts, name) {
+    let last;
+    for (const act of acts) {
+        if (act.kind === 'join' && sameName(act.actor, name))
+            last = act.at;
+    }
+    return last;
+}
+/** Stable index of the recipient's most recent join act, if any. */
+export function lastJoinIndex(acts, name) {
+    let last;
+    for (const act of acts) {
+        if (act.kind === 'join' && sameName(act.actor, name))
+            last = actStableIndex(act);
+    }
+    return last;
+}
+/** Notifications are live only when they land after the recipient joined. */
+export function isPostJoinActivity(acts, name, actIndex) {
+    const joinIndex = lastJoinIndex(acts, name);
+    return joinIndex !== undefined && actIndex > joinIndex;
+}
+export function actStableIndex(act) {
+    if (act.index === undefined)
+        throw new Error(`act ${act.kind} is missing a stable index`);
+    return act.index;
+}
+export function actId(actOrIndex) {
+    const index = typeof actOrIndex === 'number' ? actOrIndex : actStableIndex(actOrIndex);
+    return `act_${index}`;
+}
+export function getReadState(doc, name) {
+    return doc.runtime.cursors[name] ?? Object.entries(doc.runtime.cursors).find(([participant]) => sameName(participant, name))?.[1];
+}
+export function readCursor(doc, name) {
+    return getReadState(doc, name)?.consumedThroughIndex ?? -1;
+}
+export function currentHold(acts) {
+    const hold = fold(acts).hold;
+    return hold.active ? { active: true, at: hold.at, reason: hold.reason } : { active: false };
+}
+export function publicActs(acts) {
+    return acts.filter((act) => act.kind === 'say' || act.kind === 'done');
+}
+export function roomChangeActs(acts) {
+    return acts.filter((act) => act.kind !== 'say' && act.kind !== 'read');
+}
+export function throttleDelayMs(doc, at) {
+    const limit = doc.throttlePerMinute;
+    if (limit === undefined)
+        return 0;
+    const recent = foldedState(doc).throttleActivityAts.filter((eventAt) => at - eventAt < THROTTLE_WINDOW_MS).sort((a, b) => a - b);
+    if (recent.length < limit)
+        return 0;
+    const releaseAt = recent[recent.length - limit] + THROTTLE_WINDOW_MS;
+    return Math.max(1, releaseAt - at);
+}
+function canonicalRuntimeName(doc, name) {
+    return resolveRosterName(doc, name) ?? name;
+}
+export function advanceCursor(doc, name, index, source = 'watch', updatedAt = Date.now()) {
+    return touchPresenceCursor(doc, name, updatedAt, source, index);
+}
+export function touchPresenceCursor(doc, name, at, source, consumedThroughIndex) {
+    if (!Number.isFinite(at))
+        return false;
+    if (consumedThroughIndex !== undefined && (!Number.isInteger(consumedThroughIndex) || consumedThroughIndex < 0))
+        return false;
+    const key = canonicalRuntimeName(doc, name);
+    const current = getReadState(doc, key);
+    const nextIndex = consumedThroughIndex === undefined
+        ? (current?.consumedThroughIndex ?? readCursor(doc, key))
+        : Math.max(current?.consumedThroughIndex ?? -1, consumedThroughIndex);
+    const updatedAt = current === undefined ? at : Math.max(current.updatedAt, at);
+    if (current?.consumedThroughIndex === nextIndex && current.updatedAt === updatedAt && current.source === source)
+        return false;
+    doc.runtime.cursors[key] = { consumedThroughIndex: nextIndex, updatedAt, source };
+    return true;
+}
+/** The canonical delivery ledger is keyed by (recipient, stable act id). */
+export function deliveryReceipt(doc, name, actOrIndex) {
+    const id = actId(actOrIndex);
+    // Delivery planners and runtime writers pass roster-canonical names. Keeping
+    // this a direct lookup is important: pending/status scans must stay linear in
+    // activities rather than folding the whole square once per notification.
+    return doc.runtime.mentionReceipts[name]?.[id];
+}
+export function isDeliveryDelivered(doc, name, actOrIndex) {
+    return deliveryReceipt(doc, name, actOrIndex)?.status === 'delivered';
+}
+export function recordDeliveredDelivery(doc, name, actOrIndex, receipt) {
+    const key = canonicalRuntimeName(doc, name);
+    const id = actId(actOrIndex);
+    const current = deliveryReceipt(doc, key, actOrIndex);
+    if (current?.status === 'delivered')
+        return false;
+    const receipts = doc.runtime.mentionReceipts[key] ?? {};
+    receipts[id] = { status: 'delivered', ...receipt };
+    doc.runtime.mentionReceipts[key] = receipts;
+    return true;
+}
+export function markDeliveredMention(doc, name, actOrIndex, at = Date.now()) {
+    return recordDeliveredDelivery(doc, name, actOrIndex, { at });
+}
+export function mentionDeliveredStatus(doc, name, actOrIndex) {
+    return isDeliveryDelivered(doc, name, actOrIndex) ? 'delivered' : undefined;
+}
+export function markDeliveredMentions(doc, name, delivered, at = Date.now()) {
+    let changed = false;
+    for (const item of delivered) {
+        const act = item.act;
+        if (act.kind !== 'say')
+            continue;
+        // A cursor says only where feed reading reached. The recipient/act receipt is
+        // the delivery fact, so never create one for a broadcast or unrelated say.
+        const directed = act.reach === 'bell' ||
+            (act.reach !== undefined && sameName(act.reach.beside, name)) ||
+            extractMentions(act.body).some((mention) => sameName(mention, name));
+        if (!directed)
+            continue;
+        changed = markDeliveredMention(doc, name, actStableIndex(act), at) || changed;
+    }
+    return changed;
+}
+export function writeSquareDoc(squarePath, doc) {
+    const dir = path.dirname(squarePath);
+    const base = path.basename(squarePath);
+    const tempPath = path.join(dir, `.${base}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`);
+    fs.writeFileSync(tempPath, renderSquareDoc(doc));
+    fs.renameSync(tempPath, squarePath);
+    saveRuntimeSidecar(squarePath, doc.runtime);
+}
+export function appendAct(squarePath, doc, act) {
+    const indexed = { ...act, index: doc.runtime.nextActIndex };
+    doc.runtime.nextActIndex++;
+    doc.acts.push(indexed);
+    if (indexed.actor !== undefined)
+        touchPresenceCursor(doc, indexed.actor, indexed.at, indexed.kind === 'join' ? 'join' : 'api', actStableIndex(indexed));
+    writeSquareDoc(squarePath, doc);
+    return indexed;
+}
+export function latestIndexedActIndex(items) {
+    return items.reduce((max, item) => Math.max(max, item.index), -1);
+}
+export function freshWatchLease(doc, name, at = Date.now()) {
+    const key = canonicalRuntimeName(doc, name);
+    const lease = doc.runtime.leases[key];
+    if (lease === undefined || lease.expiresAt <= at || at - lease.heartbeatAt > WATCH_STALE_MS)
+        return undefined;
+    return lease;
+}
+export async function withSquareLock(squarePath, fn) {
+    const lockPath = `${squarePath}.lock`;
+    const lockDir = path.dirname(lockPath);
+    fs.mkdirSync(lockDir, { recursive: true });
+    while (true) {
+        try {
+            const fd = fs.openSync(lockPath, 'wx');
+            fs.writeFileSync(fd, `${process.pid}\n${Date.now()}\n`, 'utf8');
+            fs.closeSync(fd);
+            try {
+                return await fn();
+            }
+            finally {
+                try {
+                    fs.unlinkSync(lockPath);
+                }
+                catch { }
+            }
+        }
+        catch (err) {
+            const errno = err;
+            if (errno.code !== 'EEXIST')
+                throw err;
+            try {
+                const stat = fs.statSync(lockPath);
+                if (Date.now() - stat.mtimeMs > LOCK_STALE_MS)
+                    fs.unlinkSync(lockPath);
+            }
+            catch { }
+            await sleep(LOCK_RETRY_MS);
+        }
+    }
+}

package/dist/search.js

@@ -0,0 +1,54 @@
+// Shared activity-body search semantics for filtering and presentation.
+// Regex mode intentionally uses JavaScript's built-in engine: patterns come from
+// the local CLI user and are not treated as a hostile multi-tenant input. Use
+// --fixed for literal text; do not claim regex mode has ReDoS protection.
+import { SquareError } from './model.js';
+function escapeRegex(pattern) {
+    return pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+export function compileGrepPattern(pattern) {
+    try {
+        return new RegExp(pattern, 'i');
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message.replace(/^Invalid regular expression:\s*/i, '') : 'invalid expression';
+        throw new SquareError('invalid_args', `Invalid --grep regex: ${detail}`);
+    }
+}
+export function compileFixedPattern(pattern) {
+    return new RegExp(escapeRegex(pattern), 'i');
+}
+export function compileSearchPattern(pattern, fixed) {
+    return fixed ? compileFixedPattern(pattern) : compileGrepPattern(pattern);
+}
+function compactWhitespace(text) {
+    return text.replace(/\s+/g, ' ');
+}
+export function grepSnippet(body, pattern, maxChars, fixed = false) {
+    const found = compileSearchPattern(pattern, fixed).exec(body);
+    if (found === null)
+        return undefined;
+    const beforeAll = [...body.slice(0, found.index)];
+    const matchAll = [...found[0]];
+    const afterAll = [...body.slice(found.index + found[0].length)];
+    const shownMatch = matchAll.slice(0, maxChars);
+    let remaining = Math.max(0, maxChars - shownMatch.length);
+    let beforeTake = Math.min(beforeAll.length, Math.floor(remaining / 2));
+    let afterTake = Math.min(afterAll.length, remaining - beforeTake);
+    // Give unused context budget to whichever side still has text.
+    remaining -= beforeTake + afterTake;
+    if (remaining > 0) {
+        const extraBefore = Math.min(remaining, beforeAll.length - beforeTake);
+        beforeTake += extraBefore;
+        remaining -= extraBefore;
+    }
+    if (remaining > 0)
+        afterTake += Math.min(remaining, afterAll.length - afterTake);
+    return {
+        before: compactWhitespace(beforeAll.slice(-beforeTake).join('')),
+        match: compactWhitespace(shownMatch.join('')),
+        after: compactWhitespace(afterAll.slice(0, afterTake).join('')),
+        beforeOmitted: beforeAll.length - beforeTake,
+        afterOmitted: afterAll.length - afterTake + Math.max(0, matchAll.length - shownMatch.length),
+    };
+}

package/dist/square-core.js

@@ -0,0 +1,183 @@
+function nameKey(name) {
+    return name.toLocaleLowerCase();
+}
+function sameName(a, b) {
+    return nameKey(a) === nameKey(b);
+}
+function actorOf(act) {
+    if ('actor' in act && typeof act.actor === 'string')
+        return act.actor;
+    return undefined;
+}
+function touchParticipant(byKey, ordered, actor) {
+    const key = nameKey(actor);
+    const existing = byKey.get(key);
+    if (existing !== undefined)
+        return existing;
+    const created = {
+        name: actor,
+        key,
+        joined: false,
+        done: false,
+        activityCount: 0,
+        lastReadThrough: -1,
+    };
+    byKey.set(key, created);
+    ordered.push(created);
+    return created;
+}
+export function isWarm(lastSeen, now, threshold) {
+    if (lastSeen === undefined)
+        return false;
+    if (!Number.isFinite(lastSeen) || !Number.isFinite(now) || !Number.isFinite(threshold) || threshold <= 0)
+        return false;
+    const delta = now - lastSeen;
+    return delta >= 0 && delta <= threshold;
+}
+function pushThrottleAt(state, at) {
+    if (typeof at === 'number' && Number.isFinite(at))
+        state.throttleActivityAts.push(at);
+}
+function currentParticipant(state, participant) {
+    return state.participants.find((item) => sameName(item.name, participant));
+}
+function pushBellAt(state, actor, at) {
+    if (typeof at !== 'number' || !Number.isFinite(at))
+        return;
+    const key = nameKey(actor);
+    const current = state.bellSayAtsByActor.get(key) ?? [];
+    current.push(at);
+    state.bellSayAtsByActor.set(key, current);
+}
+function bellRecentAt(state, actor, at, windowMs) {
+    const events = state.bellSayAtsByActor.get(nameKey(actor)) ?? [];
+    let latest;
+    for (const eventAt of events) {
+        if (at - eventAt >= windowMs)
+            continue;
+        latest = latest === undefined ? eventAt : Math.max(latest, eventAt);
+    }
+    return latest;
+}
+export function fold(acts, options = {}) {
+    const ordered = [];
+    const byKey = new Map();
+    const hold = { active: false };
+    const state = {
+        participants: ordered,
+        hold,
+        joined: [],
+        done: [],
+        throttleActivityAts: [],
+        bellSayAtsByActor: new Map(),
+    };
+    for (const act of acts) {
+        const actor = actorOf(act);
+        const snapshot = actor === undefined ? undefined : touchParticipant(byKey, ordered, actor);
+        switch (act.kind) {
+            case 'join':
+                if (snapshot !== undefined) {
+                    snapshot.joined = true;
+                    snapshot.done = false;
+                    snapshot.lastActiveAt = act.at ?? snapshot.lastActiveAt;
+                }
+                break;
+            case 'done':
+                if (snapshot !== undefined) {
+                    snapshot.joined = false;
+                    snapshot.done = true;
+                    snapshot.lastActiveAt = act.at ?? snapshot.lastActiveAt;
+                }
+                break;
+            case 'say':
+                if (snapshot !== undefined) {
+                    snapshot.activityCount += 1;
+                    snapshot.lastActiveAt = act.at ?? snapshot.lastActiveAt;
+                }
+                pushThrottleAt(state, act.at);
+                if (act.reach === 'bell')
+                    pushBellAt(state, act.actor, act.at);
+                break;
+            case 'hold':
+                hold.active = true;
+                hold.at = act.at;
+                hold.reason = act.body;
+                hold.actor = act.actor;
+                break;
+            case 'resume':
+                hold.active = false;
+                delete hold.at;
+                delete hold.reason;
+                delete hold.actor;
+                break;
+            case 'read':
+                if (snapshot !== undefined) {
+                    snapshot.lastReadThrough = Math.max(snapshot.lastReadThrough, act.through);
+                }
+                break;
+        }
+    }
+    state.joined = ordered.filter((item) => item.joined).map((item) => item.name);
+    state.done = ordered.filter((item) => item.done).map((item) => item.name);
+    return state;
+}
+export function validate(state, act, options = {}) {
+    const actor = actorOf(act);
+    const current = actor === undefined ? undefined : currentParticipant(state, actor);
+    switch (act.kind) {
+        case 'join':
+            return current?.joined ? { ok: false, reason: 'already_joined' } : { ok: true };
+        case 'done':
+            if (current?.done)
+                return { ok: false, reason: 'done' };
+            if (current?.joined !== true)
+                return { ok: false, reason: 'not_joined' };
+            return { ok: true };
+        case 'say': {
+            if (current?.done)
+                return { ok: false, reason: 'done' };
+            if (state.hold.active)
+                return { ok: false, reason: 'held', hold: state.hold };
+            const activityCount = current?.activityCount ?? 0;
+            if (options.hardCap !== undefined && options.hardCap !== null && activityCount >= options.hardCap) {
+                return { ok: false, reason: 'hard_cap', count: activityCount, hardCap: options.hardCap };
+            }
+            const limit = options.throttlePerMinute;
+            const at = act.at;
+            if (act.reach === 'bell' && typeof at === 'number' && Number.isFinite(at)) {
+                const bellWindowMs = 60 * 60 * 1000;
+                const latestBellAt = bellRecentAt(state, act.actor, at, bellWindowMs);
+                if (latestBellAt !== undefined) {
+                    return { ok: false, reason: 'bell_quota', nextAt: latestBellAt + bellWindowMs };
+                }
+            }
+            if (limit !== undefined && typeof at === 'number' && Number.isFinite(at)) {
+                const windowMs = options.throttleWindowMs ?? 60000;
+                const recent = state.throttleActivityAts.filter((eventAt) => at - eventAt < windowMs).sort((a, b) => a - b);
+                if (recent.length >= limit) {
+                    const releaseAt = recent[recent.length - limit] + windowMs;
+                    const delayMs = Math.max(1, releaseAt - at);
+                    return { ok: false, reason: 'throttled', delayMs };
+                }
+            }
+            return { ok: true };
+        }
+        case 'hold':
+        case 'resume':
+        case 'read':
+            return { ok: true };
+    }
+}
+export function perceive(state, act, viewer, options = {}) {
+    void state;
+    if (act.kind !== 'say')
+        return 'full';
+    const actor = act.actor;
+    if ((options.includeActor ?? true) && sameName(actor, viewer))
+        return 'full';
+    if (act.reach === undefined || act.reach === 'bell')
+        return 'full';
+    if (sameName(act.reach.beside, viewer))
+        return 'full';
+    return 'presence';
+}