@astrosheep/square 0.3.11 → 0.3.13

package/dist/search.d.ts

@@ -0,0 +1,11 @@
+export declare function compileGrepPattern(pattern: string): RegExp;
+export declare function compileFixedPattern(pattern: string): RegExp;
+export declare function compileSearchPattern(pattern: string, fixed: boolean): RegExp;
+export interface GrepSnippet {
+    before: string;
+    match: string;
+    after: string;
+    beforeOmitted: number;
+    afterOmitted: number;
+}
+export declare function grepSnippet(body: string, pattern: string, maxChars: number, fixed?: boolean): GrepSnippet | undefined;

package/dist/square-core.d.ts

@@ -0,0 +1,111 @@
+export type Participant = string;
+export type Reach = 'bell';
+export type Audience = {
+    readonly kind: 'bell';
+} | {
+    readonly kind: 'mentions';
+    readonly names: readonly string[];
+};
+export type ActivityId = `act/${number}`;
+export declare function formatActivityId(index: number): ActivityId;
+export declare function parseActivityId(value: string): number | undefined;
+export interface Hold {
+    active: boolean;
+    at?: number;
+    reason?: string;
+    actor?: Participant;
+}
+export type Act = {
+    kind: 'join';
+    actor: Participant;
+    at?: number;
+} | {
+    kind: 'done';
+    actor: Participant;
+    at?: number;
+    body?: string;
+} | {
+    kind: 'say';
+    actor: Participant;
+    at?: number;
+    body: string;
+    reach?: Reach;
+    reply?: number;
+} | {
+    kind: 'hold';
+    actor?: Participant;
+    at?: number;
+    body?: string;
+} | {
+    kind: 'resume';
+    actor?: Participant;
+    at?: number;
+} | {
+    kind: 'read';
+    actor: Participant;
+    at?: number;
+    through: number;
+};
+export interface SquareValidationOptions {
+    hardCap?: number | null;
+    throttlePerMinute?: number;
+    throttleWindowMs?: number;
+}
+export type Perception = 'full' | 'presence';
+interface ParticipantSnapshot {
+    name: Participant;
+    key: string;
+    joined: boolean;
+    done: boolean;
+    activityCount: number;
+    lastActiveAt?: number;
+    lastReadThrough: number;
+}
+export interface FoldedSquareState {
+    participants: ParticipantSnapshot[];
+    hold: Hold;
+    joined: Participant[];
+    done: Participant[];
+    throttleActivityAts: number[];
+    bellSayAtsByActor: Map<string, number[]>;
+}
+export type ValidationResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'already_joined';
+} | {
+    ok: false;
+    reason: 'not_joined';
+} | {
+    ok: false;
+    reason: 'done';
+} | {
+    ok: false;
+    reason: 'held';
+    hold: Hold;
+} | {
+    ok: false;
+    reason: 'hard_cap';
+    count: number;
+    hardCap: number;
+} | {
+    ok: false;
+    reason: 'throttled';
+    delayMs: number;
+} | {
+    ok: false;
+    reason: 'bell_quota';
+    nextAt: number;
+};
+export declare function extractMentions(body: string): string[];
+export declare function audienceOf(say: {
+    body: string;
+    reach?: Reach;
+}): Audience;
+export declare function audienceIncludes(audience: Audience, name: string): boolean;
+export declare function resolveAudience(audience: Audience, candidateNames: readonly string[]): string[];
+export declare function fold(acts: readonly Act[]): FoldedSquareState;
+export declare function validate(state: FoldedSquareState, act: Act, options?: SquareValidationOptions): ValidationResult;
+export declare function perceive(act: Act, viewer: Participant | string): Perception;
+export {};

package/dist/square-core.js

@@ -1,9 +1,62 @@
+export function formatActivityId(index) {
+    if (!Number.isSafeInteger(index) || index < 0) {
+        throw new Error(`Invalid activity index: ${index}`);
+    }
+    return `act/${index}`;
+}
+export function parseActivityId(value) {
+    if (value === 'act/0')
+        return 0;
+    if (typeof value !== 'string' || !/^act\/[1-9]\d*$/.test(value))
+        return undefined;
+    const index = Number(value.slice(4));
+    return Number.isSafeInteger(index) ? index : undefined;
+}
 function nameKey(name) {
     return name.toLocaleLowerCase();
 }
 function sameName(a, b) {
     return nameKey(a) === nameKey(b);
 }
+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;
+}
+function uniqueMentionNames(names) {
+    const unique = [];
+    for (const name of names) {
+        if (unique.some((existing) => sameName(existing, name)))
+            continue;
+        unique.push(name);
+    }
+    return unique;
+}
+export function audienceOf(say) {
+    if (say.reach === 'bell')
+        return { kind: 'bell' };
+    return { kind: 'mentions', names: uniqueMentionNames(extractMentions(say.body)) };
+}
+export function audienceIncludes(audience, name) {
+    if (audience.kind === 'bell')
+        return true;
+    return audience.names.some((mentioned) => sameName(mentioned, name));
+}
+export function resolveAudience(audience, candidateNames) {
+    if (audience.kind === 'bell')
+        return [...candidateNames];
+    const resolved = [];
+    for (const mention of audience.names) {
+        const known = candidateNames.find((candidate) => sameName(candidate, mention));
+        if (known !== undefined && !resolved.some((existing) => sameName(existing, known))) {
+            resolved.push(known);
+        }
+    }
+    return resolved;
+}
 function actorOf(act) {
     if ('actor' in act && typeof act.actor === 'string')
         return act.actor;
@@ -128,6 +181,8 @@ export function validate(state, act, options = {}) {
         case 'say': {
             if (current?.done)
                 return { ok: false, reason: 'done' };
+            if (current?.joined !== true)
+                return { ok: false, reason: 'not_joined' };
             if (state.hold.active)
                 return { ok: false, reason: 'held', hold: state.hold };
             const activityCount = current?.activityCount ?? 0;
@@ -156,20 +211,19 @@ export function validate(state, act, options = {}) {
         }
         case 'hold':
         case 'resume':
+            if (current?.done)
+                return { ok: false, reason: 'done' };
+            if (current?.joined !== true)
+                return { ok: false, reason: 'not_joined' };
+            return { ok: true };
         case 'read':
             return { ok: true };
     }
 }
-export function perceive(state, act, viewer) {
-    void state;
+export function perceive(act, viewer) {
     if (act.kind !== 'say')
         return 'full';
-    const actor = act.actor;
-    if (sameName(actor, viewer))
-        return 'full';
-    if (act.reach === undefined || act.reach === 'bell')
-        return 'full';
-    if (sameName(act.reach.beside, viewer))
+    if (sameName(act.actor, viewer))
         return 'full';
-    return 'presence';
+    return audienceIncludes(audienceOf(act), viewer) ? 'full' : 'presence';
 }

package/dist/square-facade.d.ts

@@ -0,0 +1,86 @@
+import type { ActivityId, Perception, Reach } from './square-core.js';
+export interface Activity {
+    readonly id: ActivityId;
+    readonly at: number;
+    readonly kind: 'join' | 'say' | 'done' | 'hold' | 'resume';
+    readonly actor: string;
+    readonly body?: string;
+    readonly mentions: readonly string[];
+    readonly reply?: ActivityId;
+}
+export interface WakeNotifier {
+    wake(recipients: readonly string[], activity: Activity): void;
+}
+export interface PerceivedActivity extends Activity {
+    readonly perception: Perception;
+}
+export interface ExpressOptions {
+    readonly force?: boolean;
+    readonly reach?: Reach;
+    readonly reply?: ActivityId;
+}
+export interface ExpressResult {
+    readonly activity: Activity;
+}
+export interface CatchOptions {
+    readonly idle?: number;
+    readonly from?: readonly string[];
+    readonly mention?: boolean;
+}
+export interface CatchResult {
+    readonly activities: readonly PerceivedActivity[];
+    readonly consumedThrough: ActivityId | null;
+    readonly idleExpired: boolean;
+}
+export interface HistoryQuery {
+    readonly limit?: number;
+    readonly order?: 'asc' | 'desc';
+    readonly all?: boolean;
+    readonly full?: boolean;
+    readonly grep?: string;
+    readonly from?: readonly string[];
+    readonly mention?: boolean;
+}
+export interface ParticipantStatus {
+    readonly name: string;
+    readonly state: 'joined' | 'done';
+    readonly consumedThrough: ActivityId | null;
+    readonly watching: boolean;
+}
+export interface SquareSnapshot {
+    readonly context: string;
+    readonly actCount: number;
+    readonly hardCap: number | null;
+    readonly throttlePerMinute?: number;
+    readonly held: {
+        readonly by: string;
+        readonly reason?: string;
+    } | null;
+    readonly participants: readonly ParticipantStatus[];
+    delivered(name: string, id: ActivityId): boolean;
+}
+export type SquareSource = {
+    path: string;
+};
+export interface OpenOptions {
+    clock?: () => number;
+    notifier?: WakeNotifier;
+}
+export interface SquareAtInput extends SquareSource, OpenOptions {
+}
+export interface SquareBuildInput extends SquareSource {
+    markdown: string;
+    hardCap?: number | null;
+    throttlePerMinute?: number;
+    clock?: () => number;
+    notifier?: WakeNotifier;
+}
+export interface Participant {
+    readonly name: string;
+    express(body: string, options?: ExpressOptions): Promise<ExpressResult>;
+    catch(options?: CatchOptions): Promise<CatchResult>;
+    history(query?: HistoryQuery): Promise<PerceivedActivity[]>;
+    hold(reason?: string): Promise<ExpressResult>;
+    resume(): Promise<ExpressResult>;
+    done(body?: string): Promise<ExpressResult>;
+}

package/dist/square-facade.js

@@ -0,0 +1 @@
+export {};

package/dist/square-file-adapter.d.ts

@@ -0,0 +1,18 @@
+import { type BuildOptions, type HardCap } from './model.js';
+import type { OpenSquare } from './open-square.js';
+import type { WakeNotifier } from './square-facade.js';
+/** File-owned artifact creation for the CLI and path-backed public facade. */
+export declare function createSquare(squarePath: string, options: BuildOptions & {
+    hardCap: HardCap;
+}, snippet: string): Promise<void>;
+export interface SquareBuildOptions {
+    markdown: string;
+    hardCap?: number | null;
+    throttlePerMinute?: number;
+    clock?: () => number;
+    notifier?: WakeNotifier;
+}
+export declare function openSquare(squarePath: string, options?: Pick<SquareBuildOptions, 'clock' | 'notifier'>): Promise<OpenSquare>;
+export declare function probeSquare(squarePath: string): OpenSquare | undefined;
+export declare function buildSquare(squarePath: string, options: SquareBuildOptions): Promise<OpenSquare>;
+export declare function buildMemorySquare(options: SquareBuildOptions): OpenSquare;

package/dist/square-file-adapter.js

@@ -0,0 +1,70 @@
+import fs from 'node:fs';
+import { createSquareState, probeSquareFile, writeSquareSnapshot, withSquareFileLock, openSquareCell, createMemoryCell, } from './square-storage.js';
+import { InternalSquareError, SquareError, } from './model.js';
+/** The current CLI file mutation boundary. */
+function writeSquareState(squarePath, squareState) {
+    writeSquareSnapshot(squarePath, squareState);
+}
+/** File-owned artifact creation for the CLI and path-backed public facade. */
+export async function createSquare(squarePath, options, snippet) {
+    await withSquareFileLock(squarePath, () => {
+        if (fs.existsSync(squarePath) && !options.force) {
+            throw new InternalSquareError('conflict', `Refusing to overwrite existing square: ${squarePath}\nPass -f to overwrite.`);
+        }
+        writeSquareSnapshot(squarePath, createSquareState(options, snippet));
+    });
+}
+function validateBuildOptions(options) {
+    if (options.hardCap !== undefined && options.hardCap !== null
+        && (!Number.isSafeInteger(options.hardCap) || options.hardCap < 1)) {
+        throw new SquareError('invalid_args', 'hardCap must be a positive integer or null');
+    }
+    if (options.throttlePerMinute !== undefined
+        && (!Number.isSafeInteger(options.throttlePerMinute) || options.throttlePerMinute < 1)) {
+        throw new SquareError('invalid_args', 'throttlePerMinute must be a positive integer');
+    }
+}
+export async function openSquare(squarePath, options = {}) {
+    const cell = openSquareCell(squarePath);
+    try {
+        await cell.read();
+        return { cell, clock: options.clock ?? Date.now, ...(options.notifier === undefined ? {} : { notifier: options.notifier }), location: squarePath };
+    }
+    catch (error) {
+        await cell.close();
+        if (error instanceof InternalSquareError && error.code === 'not_found') {
+            throw new SquareError('unavailable', `Square is unavailable at ${squarePath}`);
+        }
+        throw error;
+    }
+}
+export function probeSquare(squarePath) {
+    const state = probeSquareFile(squarePath);
+    return state === undefined ? undefined : { cell: createMemoryCell(state), clock: Date.now, location: squarePath };
+}
+export async function buildSquare(squarePath, options) {
+    validateBuildOptions(options);
+    try {
+        await createSquare(squarePath, {
+            force: false,
+            hardCap: options.hardCap ?? null,
+            ...(options.throttlePerMinute === undefined ? {} : { throttlePerMinute: options.throttlePerMinute }),
+        }, options.markdown);
+    }
+    catch (error) {
+        if (error instanceof InternalSquareError && error.code === 'conflict') {
+            throw new SquareError('io', `Cannot build over an existing square at ${squarePath}`);
+        }
+        throw error;
+    }
+    return openSquare(squarePath, options);
+}
+export function buildMemorySquare(options) {
+    validateBuildOptions(options);
+    const squareState = createSquareState({
+        force: false,
+        hardCap: options.hardCap ?? null,
+        ...(options.throttlePerMinute === undefined ? {} : { throttlePerMinute: options.throttlePerMinute }),
+    }, options.markdown);
+    return { cell: createMemoryCell(squareState), clock: options.clock ?? Date.now, ...(options.notifier === undefined ? {} : { notifier: options.notifier }), location: 'memory' };
+}

package/dist/square-storage.d.ts

@@ -0,0 +1,20 @@
+import { createSquareState, diagnoseSquareFile as diagnoseArtifactFile } from './artifact.js';
+import type { StateCell } from './state-cell.js';
+import { type SquareState } from './model.js';
+/**
+ * The only production module allowed to cross the .square byte boundary.
+ * Consumers receive a SquareState and never need to know which codec or lock
+ * protects it.
+ */
+export { createSquareState, };
+export declare function readSquareFile(squarePath: string): SquareState;
+export declare function probeSquareFile(squarePath: string): SquareState | undefined;
+export declare function diagnoseSquareFile(squarePath: string): ReturnType<typeof diagnoseArtifactFile>;
+export declare function writeSquareSnapshot(squarePath: string, squareState: SquareState): void;
+export declare function withSquareFileLock<T>(squarePath: string, fn: () => T | Promise<T>): Promise<T>;
+/** In-process cell for fast application tests and embedded consumers. */
+export declare function createMemoryCell(initial: SquareState): StateCell;
+/** File-backed cell retaining the existing .square codec and lock boundary. */
+export declare function createFileCell(squarePath: string): StateCell;
+/** Application-facing file cell factory; keeps storage choice behind this module. */
+export declare function openSquareCell(squarePath: string): StateCell;

package/dist/square-storage.js

@@ -0,0 +1,171 @@
+import { setTimeout as sleep } from 'node:timers/promises';
+import fs from 'node:fs';
+import { createSquareState, diagnoseSquareFile as diagnoseArtifactFile, loadSquare, probeSquare, writeSquareFile, } from './artifact.js';
+import { withFileLock } from './file-lock.js';
+import { LOCK_RETRY_MS, LOCK_STALE_MS } from './runtime.js';
+/**
+ * The only production module allowed to cross the .square byte boundary.
+ * Consumers receive a SquareState and never need to know which codec or lock
+ * protects it.
+ */
+export { createSquareState, };
+export function readSquareFile(squarePath) {
+    return loadSquare(squarePath);
+}
+export function probeSquareFile(squarePath) {
+    return probeSquare(squarePath);
+}
+export function diagnoseSquareFile(squarePath) {
+    return diagnoseArtifactFile(squarePath);
+}
+export function writeSquareSnapshot(squarePath, squareState) {
+    writeSquareFile(squarePath, squareState);
+}
+export function withSquareFileLock(squarePath, fn) {
+    return withFileLock(`${squarePath}.lock`, { retryMs: LOCK_RETRY_MS, staleMs: LOCK_STALE_MS }, fn);
+}
+function cloneState(squareState) {
+    return structuredClone(squareState);
+}
+function assertCellOpen(closed) {
+    if (closed)
+        throw new Error('StateCell is closed');
+}
+/** In-process cell for fast application tests and embedded consumers. */
+export function createMemoryCell(initial) {
+    let state = cloneState(initial);
+    let version = 0;
+    let closed = false;
+    let tail = Promise.resolve();
+    const waiters = new Set();
+    function publish() {
+        for (const waiter of [...waiters]) {
+            if (version <= waiter.since)
+                continue;
+            clearTimeout(waiter.timer);
+            waiters.delete(waiter);
+            waiter.resolve(true);
+        }
+    }
+    const cell = {
+        transact(fn) {
+            assertCellOpen(closed);
+            let operation;
+            operation = tail.then(() => {
+                assertCellOpen(closed);
+                const working = cloneState(state);
+                const outcome = fn(working, version);
+                if (outcome.state !== undefined) {
+                    state = cloneState(outcome.state);
+                    version += 1;
+                    publish();
+                }
+                return outcome.result;
+            });
+            tail = operation.then(() => undefined, () => undefined);
+            return operation;
+        },
+        async read() {
+            assertCellOpen(closed);
+            await tail;
+            return { state: cloneState(state), version };
+        },
+        changed(sinceVersion, timeoutMs) {
+            assertCellOpen(closed);
+            if (version > sinceVersion)
+                return Promise.resolve(true);
+            if (timeoutMs <= 0)
+                return Promise.resolve(false);
+            return new Promise((resolve) => {
+                const waiter = {
+                    since: sinceVersion,
+                    resolve,
+                    timer: setTimeout(() => {
+                        waiters.delete(waiter);
+                        resolve(false);
+                    }, timeoutMs),
+                };
+                waiters.add(waiter);
+            });
+        },
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            await tail;
+            for (const waiter of [...waiters]) {
+                clearTimeout(waiter.timer);
+                waiters.delete(waiter);
+                waiter.resolve(false);
+            }
+        },
+    };
+    return cell;
+}
+function fileFingerprint(squarePath) {
+    try {
+        const stat = fs.statSync(squarePath);
+        return `${stat.ino}:${stat.size}:${stat.mtimeMs}:${stat.ctimeMs}`;
+    }
+    catch {
+        return 'missing';
+    }
+}
+/** File-backed cell retaining the existing .square codec and lock boundary. */
+export function createFileCell(squarePath) {
+    let closed = false;
+    let version = 0;
+    let fingerprint = fileFingerprint(squarePath);
+    function observe() {
+        const next = fileFingerprint(squarePath);
+        if (next === fingerprint)
+            return;
+        fingerprint = next;
+        version += 1;
+    }
+    return {
+        async transact(fn) {
+            assertCellOpen(closed);
+            return withFileLock(`${squarePath}.lock`, { retryMs: LOCK_RETRY_MS, staleMs: LOCK_STALE_MS }, () => {
+                assertCellOpen(closed);
+                observe();
+                const current = readSquareFile(squarePath);
+                const working = cloneState(current);
+                const outcome = fn(working, version);
+                if (outcome.state !== undefined) {
+                    writeSquareSnapshot(squarePath, outcome.state);
+                    fingerprint = fileFingerprint(squarePath);
+                    version += 1;
+                }
+                return outcome.result;
+            });
+        },
+        async read() {
+            assertCellOpen(closed);
+            observe();
+            const state = readSquareFile(squarePath);
+            return { state: cloneState(state), version };
+        },
+        async changed(sinceVersion, timeoutMs) {
+            assertCellOpen(closed);
+            const deadline = Date.now() + Math.max(0, timeoutMs);
+            while (true) {
+                observe();
+                if (version > sinceVersion)
+                    return true;
+                const remaining = deadline - Date.now();
+                if (remaining <= 0)
+                    return false;
+                await sleep(Math.min(25, remaining));
+                assertCellOpen(closed);
+            }
+        },
+        async close() {
+            closed = true;
+        },
+    };
+}
+/** Application-facing file cell factory; keeps storage choice behind this module. */
+export function openSquareCell(squarePath) {
+    return createFileCell(squarePath);
+}

package/dist/square-wiring.d.ts

@@ -0,0 +1,19 @@
+import type { Activity, HistoryQuery, ParticipantStatus, SquareSnapshot } from './square-facade.js';
+import type { Participant, SquareAtInput, SquareBuildInput } from './square-facade.js';
+export declare class Square {
+    readonly location: string;
+    private readonly square;
+    private constructor();
+    static at(input: SquareAtInput): Promise<Square>;
+    static build(input: SquareBuildInput): Promise<Square>;
+    static inMemory(input: Omit<SquareBuildInput, 'path'>): Square;
+    join(name: string): Promise<Participant>;
+    participants(): Promise<ParticipantStatus[]>;
+    snapshot(): Promise<SquareSnapshot>;
+    history(query?: HistoryQuery): Promise<Activity[]>;
+    close(): Promise<void>;
+}
+export declare function openParticipant(input: SquareAtInput, name: string): Promise<{
+    readonly participant: Participant;
+    close(): Promise<void>;
+}>;

package/dist/square-wiring.js

@@ -0,0 +1,70 @@
+import { closeOpenSquare } from './open-square.js';
+import { buildMemorySquare, buildSquare, openSquare } from './square-file-adapter.js';
+import { done, express, hold, join, resume } from './landing.js';
+import { catchUp } from './presence.js';
+import { history, participantHistory, participants, resolveParticipant, snapshot } from './views.js';
+class ParticipantHandle {
+    name;
+    square;
+    constructor(name, square) {
+        this.name = name;
+        this.square = square;
+    }
+    express(body, options) {
+        return express(this.square, this.name, body, options);
+    }
+    catch(options) {
+        return catchUp(this.square, this.name, options);
+    }
+    history(query) {
+        return participantHistory(this.square, this.name, query);
+    }
+    hold(reason) {
+        return hold(this.square, this.name, reason);
+    }
+    resume() {
+        return resume(this.square, this.name);
+    }
+    done(body) {
+        return done(this.square, this.name, body);
+    }
+}
+export class Square {
+    location;
+    square;
+    constructor(location, square) {
+        this.location = location;
+        this.square = square;
+    }
+    static async at(input) {
+        return new Square(input.path, await openSquare(input.path, input));
+    }
+    static async build(input) {
+        return new Square(input.path, await buildSquare(input.path, input));
+    }
+    static inMemory(input) {
+        return new Square('memory', buildMemorySquare(input));
+    }
+    async join(name) {
+        const joined = await join(this.square, name);
+        return new ParticipantHandle(joined.name, this.square);
+    }
+    participants() { return participants(this.square); }
+    snapshot() { return snapshot(this.square); }
+    history(query) { return history(this.square, query); }
+    close() { return closeOpenSquare(this.square); }
+}
+export async function openParticipant(input, name) {
+    const square = await openSquare(input.path, input);
+    try {
+        const known = await resolveParticipant(square, name);
+        return {
+            participant: new ParticipantHandle(known.name, square),
+            close: () => closeOpenSquare(square),
+        };
+    }
+    catch (error) {
+        await closeOpenSquare(square);
+        throw error;
+    }
+}

package/dist/square.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};