@astrosheep/square 0.3.4 → 0.3.5

package/dist/help.js

@@ -48,8 +48,9 @@ const COMMANDS = [
     { names: ['hold'], usage: '--as <name> hold [reason | -]', usesSquare: true, summary: 'Raise a hand and pause participant activity.' },
     { names: ['resume'], usage: '--as <name> resume', usesSquare: true, summary: 'Lower the raised hand and resume activity.' },
     {
-        names: ['harness'], usage: 'harness <install <skills|claude|codex|opencode|pi> [-f] | uninstall codex | doctor [codex|opencode|delivery]>', usesSquare: true,
+        names: ['harness'], usage: 'harness <install <skills|claude|codex|opencode|pi> [-f] | uninstall <skills|claude|codex|opencode|pi> | doctor [skills|claude|codex|opencode|pi|delivery]>', usesSquare: true,
         summary: 'Install, remove, or diagnose official harness adapters.',
+        details: ['Targets:', '  skills, claude, codex, opencode, pi  Install, remove, or diagnose one adapter.', '  delivery                              Diagnose delivery only; skips when no readable artifact is selected.'],
     },
     { names: ['compact'], usage: 'compact [--keep N]', usesSquare: true, summary: 'Archive older acts while retaining the latest N.' },
     {

package/dist/index.js

@@ -13,13 +13,16 @@ export * from './presented.js';
 export * from './delivery-health.js';
 export * from './claude-hook.js';
 export * from './harness.js';
-export { extractMentions, countSays, joinedNames, doneNames, isCurrentlyJoined, publicActs, appendAct, withSquareLock, readCursor, } from './runtime.js';
+export { extractMentions, countSays, joinedNames, doneNames, isCurrentlyJoined, publicActs, readCursor, } from './runtime.js';
+export { appendAct, withSquareLock, writeSquareDoc } from './square-store.js';
 import { loadSquare } from './artifact.js';
 import { ackPeerDelta, indexedDelta, peerPublicActs, peerRoomChanges } from './activity-feed.js';
-import { dispatchActNotifications, hasDeliveredMention as hasDeliveredMentionImpl, matchesMentionTarget, waitForDeliveredMention as waitForDeliveredMentionImpl, } from './notifications.js';
+import { hasDeliveredMention as hasDeliveredMentionImpl, matchesMentionTarget, waitForDeliveredMention as waitForDeliveredMentionImpl, } from './notifications.js';
 import { sameName } from './model.js';
-import { SLEEP_MS, WATCH_HEARTBEAT_MS, WATCH_STALE_MS, actStableIndex, appendAct, freshWatchLease, getReadState as getDocReadState, latestIndexedActIndex, markDeliveredMentions, readCursor, withSquareLock, writeSquareDoc, } from './runtime.js';
-import { decideAct, resolveKnownName } from './decisions.js';
+import { SLEEP_MS, WATCH_HEARTBEAT_MS, WATCH_STALE_MS, actStableIndex, freshWatchLease, getReadState as getDocReadState, latestIndexedActIndex, markDeliveredMentions, readCursor, } from './runtime.js';
+import { resolveKnownName } from './decisions.js';
+import { execute } from './square-application.js';
+import { withSquareLock, writeSquareDoc } from './square-store.js';
 export { WATCH_STALE_MS };
 function actRefIndex(ref) {
     if (typeof ref === 'number')
@@ -68,18 +71,32 @@ export function getParticipantPresence(squarePath, name, now = Date.now()) {
 export function isWatching(squarePath, name, now = Date.now()) {
     return getParticipantPresence(squarePath, name, now).watching;
 }
+/** Typed participant intents share the same commit/effect pipeline as the CLI. */
+export async function join(squarePath, name) {
+    await execute(squarePath, { type: 'join', name, now: Date.now() });
+}
+export async function done(squarePath, name, body = '') {
+    await execute(squarePath, { type: 'done', name, body, now: Date.now() });
+}
+export async function hold(squarePath, actor, body = '') {
+    await execute(squarePath, { type: 'hold', actor, body, now: Date.now() });
+}
+export async function resume(squarePath, actor) {
+    await execute(squarePath, { type: 'resume', actor, now: Date.now() });
+}
+export async function say(squarePath, name, body, opts = {}) {
+    await act(squarePath, name, body, opts);
+}
 export async function act(squarePath, name, body, opts = {}) {
-    const sent = await withSquareLock(squarePath, () => {
-        const doc = loadSquare(squarePath);
-        const decision = decideAct(doc, { name, body, force: opts.force ?? false, now: Date.now() });
-        if (decision.type === 'sent') {
-            const appended = appendAct(squarePath, doc, decision.act);
-            return { act: appended, index: actStableIndex(appended) };
-        }
-        throw new Error(`Act rejected: ${decision.type}`);
+    const committed = await execute(squarePath, {
+        type: 'say',
+        name,
+        body,
+        force: opts.force ?? false,
+        now: Date.now(),
     });
-    if (sent)
-        await dispatchActNotifications(squarePath, sent);
+    if (committed.result.type !== 'sent')
+        throw new Error(`Act rejected: ${committed.result.type}`);
 }
 export async function* streamEvents(squarePath, opts = {}) {
     let doc = loadSquare(squarePath);
@@ -106,18 +123,20 @@ export async function* watch(squarePath, opts) {
     const name = resolveKnownName(doc, opts.name);
     const leaseId = `watch_api_${process.pid}_${Date.now()}_${Math.random().toString(36).slice(2)}`;
     let nextHeartbeatAt = Date.now() + WATCH_HEARTBEAT_MS;
-    await withSquareLock(squarePath, () => {
-        doc = loadSquare(squarePath);
-        const existing = freshWatchLease(doc, name);
-        if (existing !== undefined)
-            throw new Error(`${name} already has an active watch.`);
-        const at = Date.now();
-        nextHeartbeatAt = at + WATCH_HEARTBEAT_MS;
-        const participants = byList(opts.by);
-        const filter = { ...(participants ? { participants } : {}), ...(typeof opts.mention === 'string' ? { mention: opts.mention } : {}) };
-        doc.runtime.leases[name] = { leaseId, heartbeatAt: at, expiresAt: at + WATCH_STALE_MS, ...(Object.keys(filter).length > 0 ? { filter } : {}) };
-        writeSquareDoc(squarePath, doc);
+    const at = Date.now();
+    const participants = byList(opts.by);
+    const filter = { ...(participants ? { participants } : {}), ...(typeof opts.mention === 'string' ? { mention: opts.mention } : {}) };
+    const leased = await execute(squarePath, {
+        type: 'lease',
+        name,
+        leaseId,
+        at,
+        expiresAt: at + WATCH_STALE_MS,
+        filter: Object.keys(filter).length === 0 ? undefined : filter,
     });
+    if (leased.result.type === 'active')
+        throw new Error(`${name} already has an active watch.`);
+    nextHeartbeatAt = at + WATCH_HEARTBEAT_MS;
     try {
         while (true) {
             const yielded = await withSquareLock(squarePath, () => {
@@ -152,12 +171,6 @@ export async function* watch(squarePath, opts) {
         }
     }
     finally {
-        await withSquareLock(squarePath, () => {
-            const latest = loadSquare(squarePath);
-            if (latest.runtime.leases[name]?.leaseId !== leaseId)
-                return;
-            delete latest.runtime.leases[name];
-            writeSquareDoc(squarePath, latest);
-        });
+        await execute(squarePath, { type: 'release-lease', name, leaseId });
     }
 }

package/dist/runtime.js

@@ -1,8 +1,4 @@
-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)
@@ -242,23 +238,6 @@ export function markDeliveredMentions(doc, name, delivered, at = Date.now()) {
     }
     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);
 }
@@ -269,36 +248,3 @@ export function freshWatchLease(doc, name, at = Date.now()) {
         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/square-application.js

@@ -0,0 +1,259 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { renderArtifactAct, renderSquare } from './artifact.js';
+import { coreCompact, coreDone, coreHold, coreResume, decideAct, decideJoin, resolveKnownName } from './decisions.js';
+import { partitionPendingDeliveries } from './delivery-health.js';
+import { planRepair } from './doctor.js';
+import { dispatchActNotifications } from './notifications.js';
+import { squareStore } from './square-store.js';
+import { actId, freshWatchLease, touchPresenceCursor } from './runtime.js';
+/**
+ * Publish a dependent persistence file before the Square document. A retained
+ * backup lets a failed document commit restore the prior file exactly.
+ */
+function prepareFileReplacement(filePath, text) {
+    const parent = path.dirname(filePath);
+    const token = `${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}`;
+    const stage = path.join(parent, `.${path.basename(filePath)}.${token}.stage`);
+    const backup = path.join(parent, `.${path.basename(filePath)}.${token}.previous`);
+    let replaced = false;
+    let hadOriginal = false;
+    try {
+        fs.writeFileSync(stage, text);
+        hadOriginal = fs.existsSync(filePath);
+        if (hadOriginal)
+            fs.renameSync(filePath, backup);
+        fs.renameSync(stage, filePath);
+        replaced = true;
+    }
+    catch (error) {
+        try {
+            fs.rmSync(stage, { force: true });
+        }
+        catch { }
+        if (hadOriginal && fs.existsSync(backup) && !fs.existsSync(filePath)) {
+            try {
+                fs.renameSync(backup, filePath);
+            }
+            catch { }
+        }
+        throw error;
+    }
+    return {
+        rollback() {
+            if (replaced)
+                fs.rmSync(filePath, { force: true });
+            if (hadOriginal && fs.existsSync(backup))
+                fs.renameSync(backup, filePath);
+        },
+        finalize() {
+            fs.rmSync(backup, { force: true });
+        },
+    };
+}
+function plan(doc, intent) {
+    switch (intent.type) {
+        case 'join': {
+            const decision = decideJoin(doc, intent.name, intent.now);
+            return { result: decision, acts: [decision.joinAct], afterCommit: [] };
+        }
+        case 'say': {
+            const decision = decideAct(doc, intent);
+            return {
+                result: decision,
+                acts: decision.type === 'sent' ? [decision.act] : [],
+                afterCommit: [],
+            };
+        }
+        case 'hold':
+            return { result: undefined, acts: [coreHold(doc, intent.actor, intent.body, intent.now)], afterCommit: [] };
+        case 'resume':
+            return { result: undefined, acts: [coreResume(doc, intent.actor, intent.now)], afterCommit: [] };
+        case 'done':
+            return { result: undefined, acts: [coreDone(doc, intent.name, intent.body, intent.now)], afterCommit: [] };
+        case 'lease': {
+            const name = resolveKnownName(doc, intent.name);
+            const existing = freshWatchLease(doc, name, intent.at);
+            if (existing !== undefined && !intent.force) {
+                return { result: { type: 'active', lease: existing }, acts: [], afterCommit: [] };
+            }
+            return {
+                result: { type: 'started', name, replaced: existing !== undefined },
+                acts: [],
+                mutateRuntime: (runtime) => {
+                    runtime.leases[name] = {
+                        leaseId: intent.leaseId,
+                        heartbeatAt: intent.at,
+                        expiresAt: intent.expiresAt,
+                        ...(intent.filter === undefined ? {} : { filter: intent.filter }),
+                    };
+                    touchPresenceCursor(doc, name, intent.at, 'watch');
+                },
+                afterCommit: [],
+            };
+        }
+        case 'release-lease': {
+            const name = resolveKnownName(doc, intent.name);
+            if (doc.runtime.leases[name]?.leaseId !== intent.leaseId) {
+                return { result: { released: false }, acts: [], afterCommit: [] };
+            }
+            return {
+                result: { released: true },
+                acts: [],
+                mutateRuntime: (runtime) => { delete runtime.leases[name]; },
+                afterCommit: [],
+            };
+        }
+        case 'consume': {
+            const name = resolveKnownName(doc, intent.name);
+            return {
+                result: { name },
+                acts: [],
+                mutateRuntime: (runtime) => {
+                    const current = runtime.cursors[name];
+                    runtime.cursors[name] = {
+                        consumedThroughIndex: Math.max(current?.consumedThroughIndex ?? -1, intent.throughIndex),
+                        updatedAt: Math.max(current?.updatedAt ?? 0, intent.at),
+                        source: intent.source ?? 'watch',
+                    };
+                },
+                afterCommit: [],
+            };
+        }
+        case 'compact': {
+            const result = coreCompact(doc, intent.keep);
+            const archive = result.archived;
+            return {
+                result,
+                acts: [],
+                replaceDoc: result.doc,
+                preparePersistence: archive.length === 0
+                    ? undefined
+                    : () => {
+                        const existing = fs.existsSync(intent.archivePath) ? fs.readFileSync(intent.archivePath, 'utf8') : '';
+                        const block = archive
+                            .map((act, index) => renderArtifactAct(act, { first: existing === '' && index === 0 }))
+                            .join('\n');
+                        return prepareFileReplacement(intent.archivePath, `${existing}${existing === '' ? '' : '\n'}${block}\n`);
+                    },
+                afterCommit: [],
+            };
+        }
+        case 'reconcile-delivery-backlog': {
+            const { recent, historical } = partitionPendingDeliveries('', { now: intent.now, doc });
+            const actor = intent.actor ?? 'doctor --fix reconcile-backlog';
+            const receipts = historical.filter((item) => doc.runtime.mentionReceipts[item.recipient]?.[actId(item.actIndex)]?.status !== 'delivered');
+            const result = { reconciled: receipts.length, skippedRecent: recent.length, items: historical };
+            return {
+                result,
+                acts: [],
+                ...(receipts.length === 0
+                    ? {}
+                    : {
+                        mutateRuntime: (runtime) => {
+                            for (const item of receipts) {
+                                const recipientReceipts = runtime.mentionReceipts[item.recipient] ?? {};
+                                recipientReceipts[actId(item.actIndex)] = {
+                                    status: 'delivered',
+                                    at: intent.now,
+                                    reason: 'reconciled',
+                                    actor,
+                                };
+                                runtime.mentionReceipts[item.recipient] = recipientReceipts;
+                            }
+                        },
+                    }),
+                afterCommit: [],
+            };
+        }
+        case 'repair':
+            return {
+                result: undefined,
+                acts: [],
+                replaceDoc: intent.doc,
+                preparePersistence: intent.quarantine === undefined || intent.quarantine.blocks.length === 0
+                    ? undefined
+                    : () => {
+                        const existing = fs.existsSync(intent.quarantine.path) ? fs.readFileSync(intent.quarantine.path, 'utf8') : '';
+                        const block = intent.quarantine.blocks.join('\n\n');
+                        return prepareFileReplacement(intent.quarantine.path, `${existing}${existing === '' ? '' : '\n'}${block}\n`);
+                    },
+                afterCommit: [],
+            };
+    }
+}
+async function runEffects(squarePath, effects) {
+    for (const effect of effects) {
+        if (effect.type === 'dispatch-act-notifications') {
+            await dispatchActNotifications(squarePath, effect.item);
+        }
+    }
+}
+function commitPlan(squarePath, doc, planned) {
+    const nextDoc = planned.replaceDoc ?? doc;
+    const applied = squareStore.apply(nextDoc, planned.acts, planned.mutateRuntime);
+    const afterCommit = [
+        ...planned.afterCommit,
+        ...applied.acts.map((item) => ({ type: 'dispatch-act-notifications', item })),
+    ];
+    const committed = { result: planned.result, acts: applied.acts, afterCommit };
+    if (planned.acts.length === 0 && planned.mutateRuntime === undefined && planned.replaceDoc === undefined) {
+        return committed;
+    }
+    let persistence;
+    try {
+        persistence = planned.preparePersistence?.();
+        squareStore.commitOnce(squarePath, nextDoc, committed);
+        persistence?.finalize();
+        return committed;
+    }
+    catch (error) {
+        try {
+            persistence?.rollback();
+        }
+        catch { }
+        throw error;
+    }
+}
+/** The one mutation pipeline shared by package and CLI adapters. */
+export async function execute(squarePath, intent) {
+    const committed = await squareStore.transact(squarePath, (doc) => commitPlan(squarePath, doc, plan(doc, intent)));
+    await runEffects(squarePath, committed.afterCommit);
+    return committed;
+}
+/** Application-owned artifact creation; adapters provide validated options and stdin text only. */
+export async function createSquare(squarePath, options, snippet) {
+    await squareStore.create(squarePath, {
+        force: options.force,
+        text: renderSquare(options, snippet),
+        result: undefined,
+    });
+}
+export async function reconcileBacklog(squarePath, now = Date.now()) {
+    const committed = await execute(squarePath, {
+        type: 'reconcile-delivery-backlog',
+        now,
+    });
+    return committed.result;
+}
+/** Keep artifact repair planning and dependent quarantine persistence inside the application boundary. */
+export async function repairSquare(squarePath) {
+    const result = await squareStore.transactText(squarePath, (text) => {
+        const repair = planRepair(text);
+        if (repair.diagnosis.unfixable || repair.repaired === undefined)
+            return { repair, afterCommit: [] };
+        const quarantinePath = squarePath.replace(/\.md$/, '') + '.quarantine.md';
+        const intent = {
+            type: 'repair',
+            doc: repair.repaired.doc,
+            ...(repair.repaired.quarantinedBlocks.length === 0
+                ? {}
+                : { quarantine: { path: quarantinePath, blocks: repair.repaired.quarantinedBlocks } }),
+        };
+        const committed = commitPlan(squarePath, repair.repaired.doc, plan(repair.repaired.doc, intent));
+        return { repair, afterCommit: committed.afterCommit };
+    });
+    await runEffects(squarePath, result.afterCommit);
+    return result.repair;
+}
+export const application = { execute, plan };

package/dist/square-store.js

@@ -0,0 +1,111 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { emptyRuntimeState, loadSquare, renderSquareDoc, saveRuntimeSidecar } from './artifact.js';
+import { SquareError } from './model.js';
+import { LOCK_RETRY_MS, LOCK_STALE_MS, touchPresenceCursor } from './runtime.js';
+/**
+ * The persistence boundary for Square documents. Callers may derive a plan from
+ * a loaded document, but only the store indexes acts and writes artifact/runtime
+ * state while the per-square lock is held.
+ */
+export class SquareStore {
+    async transact(squarePath, operation) {
+        return withSquareLock(squarePath, async () => operation(loadSquare(squarePath)));
+    }
+    /** Recovery paths inspect raw text under the store lock before publishing a repair. */
+    async transactText(squarePath, operation) {
+        return withSquareLock(squarePath, async () => {
+            try {
+                return await operation(fs.readFileSync(squarePath, 'utf8'));
+            }
+            catch (error) {
+                if (error.code === 'ENOENT') {
+                    throw new SquareError('not_found', `square file not found: ${squarePath}`);
+                }
+                throw error;
+            }
+        });
+    }
+    /** Create the initial artifact under the same per-square lock as later commits. */
+    async create(squarePath, options) {
+        return withSquareLock(squarePath, () => {
+            if (fs.existsSync(squarePath) && !options.force) {
+                throw new SquareError('conflict', `Refusing to overwrite existing square: ${squarePath}\nPass -f to overwrite.`);
+            }
+            const dir = path.dirname(squarePath);
+            const base = path.basename(squarePath);
+            const temporary = path.join(dir, `.${base}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`);
+            fs.mkdirSync(dir, { recursive: true });
+            fs.writeFileSync(temporary, options.text);
+            fs.renameSync(temporary, squarePath);
+            saveRuntimeSidecar(squarePath, emptyRuntimeState(0));
+            return options.result;
+        });
+    }
+    apply(doc, acts, mutateRuntime) {
+        const indexed = [];
+        for (const act of acts) {
+            const stored = { ...act, index: doc.runtime.nextActIndex };
+            doc.runtime.nextActIndex += 1;
+            doc.acts.push(stored);
+            if (stored.actor !== undefined) {
+                touchPresenceCursor(doc, stored.actor, stored.at, stored.kind === 'join' ? 'join' : 'api', stored.index);
+            }
+            indexed.push({ act: stored, index: stored.index });
+        }
+        mutateRuntime?.(doc.runtime);
+        return { acts: indexed };
+    }
+    commitOnce(squarePath, doc, result) {
+        writeSquareDoc(squarePath, doc);
+        return result;
+    }
+}
+export const squareStore = new SquareStore();
+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 applied = squareStore.apply(doc, [act]);
+    squareStore.commitOnce(squarePath, doc, undefined);
+    return applied.acts[0].act;
+}
+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);
+        }
+    }
+}