@astrosheep/square 0.3.4 → 0.3.5

package/codex-plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "square",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "Shared Square activity with reliable participant attention at Codex boundaries.",
   "author": {
     "name": "Square"

package/dist/activity.js

@@ -4,10 +4,10 @@ import path from 'node:path';
 import { setTimeout as sleep } from 'node:timers/promises';
 import { loadSquare } from './artifact.js';
 import { SquareError, validateName } from './model.js';
-import { dispatchActNotifications } from './notifications.js';
 import { actHintLine, renderActivityBlocked, renderActivityLimit, renderActNoWait, renderActWaiting, renderPendingFeed, withActivityNextOutput, } from './presentation.js';
-import { appendAct, currentHold, inSquareCount, nowMs, SLEEP_MS, withSquareLock, resolveRosterName } from './runtime.js';
-import { decideAct, resolveKnownName } from './decisions.js';
+import { currentHold, inSquareCount, nowMs, SLEEP_MS, resolveRosterName } from './runtime.js';
+import { resolveKnownName } from './decisions.js';
+import { execute } from './square-application.js';
 import { formatTimestamp } from './time.js';
 function draftDirFor(squarePath) {
     return path.join(path.dirname(squarePath), 'drafts');
@@ -68,19 +68,21 @@ export async function cmdActivity(squarePath, name, activity, resolveBody, opts)
             : { beside: resolveKnownName(doc, opts.reach.beside) };
     let announcedWait;
     while (true) {
-        const { decision, sent, headerCount, held } = await withSquareLock(squarePath, () => {
-            const freshDoc = loadSquare(squarePath);
-            const d = decideAct(freshDoc, { name, body, force, now: nowMs(), reach });
-            if (d.type === 'sent') {
-                const appended = appendAct(squarePath, freshDoc, d.act);
-                return { decision: d, sent: { act: appended, index: appended.index }, headerCount: inSquareCount(freshDoc), held: currentHold(freshDoc.acts).active };
-            }
-            return { decision: d, sent: undefined, headerCount: inSquareCount(freshDoc), held: currentHold(freshDoc.acts).active };
+        const committed = await execute(squarePath, {
+            type: 'say',
+            name,
+            body,
+            force,
+            now: nowMs(),
+            ...(reach === undefined ? {} : { reach }),
         });
+        const decision = committed.result;
+        const sent = committed.acts[0];
+        const freshDoc = loadSquare(squarePath);
+        const headerCount = inSquareCount(freshDoc);
+        const held = currentHold(freshDoc.acts).active;
         switch (decision.type) {
             case 'sent': {
-                if (sent)
-                    await dispatchActNotifications(squarePath, sent);
                 const hasPending = decision.pendingPublic.length > 0 || decision.pendingRoomChanges.length > 0;
                 const pending = hasPending ? `\n\n${renderPendingFeed(decision.pendingPublic, decision.pendingRoomChanges)}` : '';
                 const hint = actHintLine(decision.ownActCount);

package/dist/cli/context.js

@@ -0,0 +1,143 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { loadSquare } from '../artifact.js';
+import { commandUsageHint } from '../help.js';
+import { parseParticipantList, validateParticipantName } from '../model.js';
+export const DEFAULT_SQUARE_PATH = '.square/SQUARE.md';
+export function readStdinSync() {
+    try {
+        return fs.readFileSync(0, 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+export function resolveBody(arg) {
+    return arg === '-' ? readStdinSync() : arg;
+}
+export function readPipedBodyFallback() {
+    if (process.stdin.isTTY)
+        return undefined;
+    const content = readStdinSync();
+    return content.trim() === '' ? undefined : content;
+}
+export function fail(message, exitCode = 2) {
+    process.stderr.write(`${message}\n`);
+    process.exit(exitCode);
+}
+export function usage(command) {
+    process.stderr.write(`✕ invalid arguments${command === '' ? '' : ` for ${command}`}\n`);
+    process.stderr.write(commandUsageHint(command || undefined));
+    process.exit(2);
+}
+export function requireValue(args, index, flag) {
+    const value = args[index + 1];
+    if (value === undefined || value.startsWith('--'))
+        fail(`Missing value for ${flag}.`);
+    return value;
+}
+export function parseDurationMs(value, flag) {
+    const match = value.match(/^([1-9]\d*)(ms|s|m|h)$/);
+    if (!match)
+        fail(`Invalid ${flag}: expected a positive duration with unit ms, s, m, or h (for example 500ms, 30s, 3m, 1h).`);
+    const amount = Number.parseInt(match[1], 10);
+    const multiplier = { ms: 1, s: 1000, m: 60000, h: 3600000 };
+    const milliseconds = amount * multiplier[match[2]];
+    if (!Number.isSafeInteger(milliseconds))
+        fail(`Invalid ${flag}: duration is too large.`);
+    return milliseconds;
+}
+export function parsePositiveInteger(value, flag) {
+    if (!/^[1-9]\d*$/.test(value))
+        fail(`Invalid ${flag}: expected a positive integer.`);
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed))
+        fail(`Invalid ${flag}: value is too large.`);
+    return parsed;
+}
+export function parseNonNegativeInteger(value, flag) {
+    if (!/^\d+$/.test(value))
+        fail(`Invalid ${flag}: expected a non-negative integer.`);
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed))
+        fail(`Invalid ${flag}: value is too large.`);
+    return parsed;
+}
+export function parseHardCap(value) {
+    if (value === '-1')
+        return null;
+    if (!/^[1-9]\d*$/.test(value))
+        fail('Invalid build option: --cap must be a positive integer or -1.');
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed))
+        fail('Invalid build option: --cap must be a positive integer or -1.');
+    return parsed;
+}
+export function parseNameList(value, flag) {
+    const names = parseParticipantList(value);
+    if (names.length === 0)
+        fail(`Invalid ${flag}: expected at least one participant name.`);
+    for (const name of names)
+        validateParticipantName(name);
+    return names;
+}
+export function requireParticipant(name) {
+    if (!name)
+        fail('Missing required option: --as <name>.');
+    validateParticipantName(name);
+    return name;
+}
+function resolveDefaultSquarePath() {
+    const directory = path.join(process.cwd(), '.square');
+    let entries;
+    try {
+        entries = fs.readdirSync(directory, { withFileTypes: true });
+    }
+    catch {
+        return { path: DEFAULT_SQUARE_PATH, multiple: false };
+    }
+    const candidates = [];
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith('.md'))
+            continue;
+        const fullPath = path.join(directory, entry.name);
+        try {
+            const doc = loadSquare(fullPath);
+            candidates.push({ relPath: path.relative(process.cwd(), fullPath), at: doc.acts.at(-1)?.at ?? fs.statSync(fullPath).mtimeMs });
+        }
+        catch {
+            // Unreadable artifacts are not implicit command targets.
+        }
+    }
+    candidates.sort((a, b) => b.at - a.at);
+    return { path: candidates[0]?.relPath ?? DEFAULT_SQUARE_PATH, multiple: candidates.length > 1 };
+}
+export function parseGlobalArgs(rawArgs) {
+    const args = [...rawArgs];
+    let requestedPath;
+    let name;
+    for (let index = 0; index < args.length; index++) {
+        if (args[index] === '--square-path') {
+            requestedPath = requireValue(args, index, args[index]);
+            args.splice(index, 2);
+            index -= 1;
+        }
+        else if (args[index] === '--as') {
+            name = requireValue(args, index, args[index]);
+            args.splice(index, 2);
+            index -= 1;
+        }
+    }
+    if (name !== undefined)
+        validateParticipantName(name);
+    const explicitSquarePath = requestedPath !== undefined;
+    const command = args[0];
+    const resolved = !explicitSquarePath && !['ls', 'list', 'version'].includes(command ?? '')
+        ? resolveDefaultSquarePath()
+        : { path: requestedPath ?? DEFAULT_SQUARE_PATH, multiple: false };
+    return { squarePath: resolved.path, explicitSquarePath, multipleSquares: resolved.multiple, name, args };
+}
+export function defaultContext(command, squarePath, name) {
+    return { command, squarePath, name, homeDir: os.homedir() };
+}

package/dist/cli/harness-command.js

@@ -0,0 +1,50 @@
+import os from 'node:os';
+import { executeHarnessTarget, harnessTargets, } from '../harness.js';
+export const harnessCommand = {
+    parse(argv) {
+        const action = argv[0];
+        if (action !== 'install' && action !== 'uninstall' && action !== 'doctor') {
+            throw new Error('harness requires install, uninstall, or doctor');
+        }
+        const rest = argv.slice(1);
+        const option = rest.find((argument) => argument.startsWith('-') && argument !== '-f' && argument !== '--force');
+        if (option !== undefined)
+            throw new Error(`Unknown harness option: ${option}`);
+        return {
+            action,
+            target: rest.find((argument) => !argument.startsWith('-')),
+            force: rest.includes('-f') || rest.includes('--force'),
+        };
+    },
+    async execute(intent, context) {
+        if (intent.target === undefined && intent.action !== 'doctor') {
+            throw new Error('harness install/uninstall requires an explicit target: skills | claude | codex | opencode | pi');
+        }
+        const targetNames = intent.target === undefined
+            ? harnessTargets().map((target) => target.name)
+            : [intent.target];
+        const results = [];
+        for (const target of targetNames) {
+            results.push(await executeHarnessTarget(target, intent.action, {
+                homeDir: context.homeDir,
+                squarePath: context.squarePath,
+                force: intent.force,
+            }));
+        }
+        return {
+            notes: results.flatMap((result) => result.notes),
+            lines: results.flatMap((result) => result.lines),
+        };
+    },
+    present(result) {
+        process.stdout.write(formatHarnessResult(result));
+    },
+};
+export function formatHarnessResult(result) {
+    return `${[...result.notes, ...result.lines].join('\n')}\n`;
+}
+export function runHarnessCommand(argv, squarePath) {
+    const context = { homeDir: os.homedir(), squarePath: squarePath ?? '.square/SQUARE.md', command: 'harness' };
+    const intent = harnessCommand.parse(argv, context);
+    return Promise.resolve(harnessCommand.execute(intent, context)).then(formatHarnessResult);
+}

package/dist/cli/maintenance-commands.js

@@ -0,0 +1,92 @@
+import fs from 'node:fs';
+import { diagnoseSquare, loadSquare } from '../artifact.js';
+import { doctorDeliveryHealth, findStalePendingMentions } from '../delivery-health.js';
+import { renderDoctorClean, renderDoctorProblems, renderDoctorRepaired, renderDoctorUnfixable, withPathOutput, } from '../presentation.js';
+import { inSquareCount } from '../runtime.js';
+import { reconcileBacklog, repairSquare } from '../square-application.js';
+import { SquareError } from '../model.js';
+import { fail, usage } from './context.js';
+function readSquareText(squarePath) {
+    try {
+        return fs.readFileSync(squarePath, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            throw new SquareError('not_found', `square file not found: ${squarePath}`);
+        throw error;
+    }
+}
+function quarantinePath(squarePath) {
+    return squarePath.replace(/\.md$/, '') + '.quarantine.md';
+}
+export const doctorCommand = {
+    parse(argv, context) {
+        let fix = false;
+        let reconcileBacklog = false;
+        for (let index = 0; index < argv.length; index++) {
+            const argument = argv[index];
+            if (argument === '--fix')
+                fix = true;
+            else if (argument === 'reconcile-backlog')
+                reconcileBacklog = true;
+            else if (argument === '--before') {
+                index += 1;
+                if (argv[index] === undefined)
+                    usage(context.command);
+            }
+            else
+                usage(context.command);
+        }
+        if (reconcileBacklog && !fix)
+            fail('doctor reconcile-backlog requires --fix.');
+        return { fix, reconcileBacklog };
+    },
+    async execute(intent, context) {
+        if (!intent.fix) {
+            const diagnosis = diagnoseSquare(readSquareText(context.squarePath));
+            if (diagnosis.unfixable) {
+                return {
+                    output: withPathOutput(context.squarePath, renderDoctorUnfixable(diagnosis.unfixable), { participantCount: inSquareCount(loadSquare(context.squarePath)) }),
+                    exitCode: 2,
+                };
+            }
+            const summary = diagnosis.problems.length === 0 ? renderDoctorClean() : renderDoctorProblems(diagnosis.problems);
+            const delivery = doctorDeliveryHealth(context.squarePath).join('\n');
+            const stale = findStalePendingMentions(context.squarePath);
+            return {
+                output: withPathOutput(context.squarePath, `${summary}\n\n${delivery}`, { participantCount: inSquareCount(loadSquare(context.squarePath)) }),
+                exitCode: diagnosis.problems.length === 0 && stale.length === 0 ? 0 : 1,
+            };
+        }
+        if (intent.reconcileBacklog) {
+            const result = await reconcileBacklog(context.squarePath);
+            const delivery = doctorDeliveryHealth(context.squarePath).join('\n');
+            return {
+                output: withPathOutput(context.squarePath, [
+                    `✓ reconciled ${result.reconciled} backlog receipt(s) as delivered(reason=reconciled)`,
+                    result.skippedRecent > 0 ? `· left ${result.skippedRecent} recent liveness failure(s) untouched` : '· no recent liveness failures present',
+                    '',
+                    delivery,
+                ].join('\n'), { participantCount: inSquareCount(loadSquare(context.squarePath)) }),
+                exitCode: result.skippedRecent > 0 ? 1 : 0,
+            };
+        }
+        const repair = await repairSquare(context.squarePath);
+        if (repair.diagnosis.unfixable) {
+            return {
+                output: withPathOutput(context.squarePath, renderDoctorUnfixable(repair.diagnosis.unfixable), { participantCount: inSquareCount(loadSquare(context.squarePath)) }),
+                exitCode: 2,
+            };
+        }
+        const repaired = repair.repaired;
+        const sidecar = quarantinePath(context.squarePath);
+        return {
+            output: withPathOutput(context.squarePath, renderDoctorRepaired(repaired.actions, repaired.quarantinedBlocks.length, repaired.quarantinedBlocks.length > 0 ? sidecar : undefined), { participantCount: inSquareCount(loadSquare(context.squarePath)) }),
+        };
+    },
+    present(result) {
+        process.stdout.write(result.output);
+        if (result.exitCode !== undefined)
+            process.exit(result.exitCode);
+    },
+};

package/dist/cli/meta-commands.js

@@ -0,0 +1,31 @@
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { renderGlobalHelp, renderSubcommandHelp } from '../help.js';
+import { fail } from './context.js';
+export const helpCommand = {
+    parse(argv) {
+        if (argv.length > 1)
+            fail('Usage: square help [command]');
+        return { command: argv[0] };
+    },
+    execute(intent) {
+        if (intent.command === undefined)
+            return renderGlobalHelp();
+        const rendered = renderSubcommandHelp(intent.command);
+        if (rendered === undefined)
+            fail(`unknown command: ${intent.command}\nrun 'square help' to list every command`);
+        return rendered;
+    },
+    present: (result) => process.stdout.write(result),
+};
+export const versionCommand = {
+    parse() {
+        return undefined;
+    },
+    execute() {
+        const packagePath = fileURLToPath(new URL('../../package.json', import.meta.url));
+        const packageJson = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
+        return `${packageJson.version ?? 'unknown'}\n`;
+    },
+    present: (result) => process.stdout.write(result),
+};