@protoboxai/codeloop 0.3.0

package/dist/lib/run.js

@@ -0,0 +1,215 @@
+import { spawnSync } from 'child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { AGENT_RUNS_DIR, briefPath, buildBrief, runAgent } from './agent.js';
+import { findCard, inLane, readCards, safeName } from './cards.js';
+import { lastDueSlot } from './cron.js';
+import { advanceCard, awaitsApproval, createCard, loadEngineConfig, recordEvent, RefusalError, runCheck, waitingOnOwner } from './engine.js';
+import { nextHint } from './flow.js';
+import { loadLane, loadLanes, shellQuote } from './lane.js';
+import { clock } from './clock.js';
+import { withLock } from './lock.js';
+export const LAST_RUN = '.codeloop/state/last-run.json';
+const FIRST_RUN_LOOKBACK_MS = 24 * 60 * 60 * 1000;
+// The slot is a local time (cron is local), so its date in the title is the local one too.
+const localDate = (d) => `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+const GIT_VALUE = {
+    'git.commit': ['rev-parse', 'HEAD'],
+    'git.tag': ['for-each-ref', '--sort=-creatordate', '--count=1', '--format=%(refname:short)', 'refs/tags'],
+};
+function git(projectDir, args) {
+    const run = spawnSync('git', args, { cwd: projectDir, encoding: 'utf-8' });
+    return run.status === 0 ? run.stdout.trim() : '';
+}
+export function runDue(projectDir, now = clock()) {
+    const file = join(projectDir, LAST_RUN);
+    // Two schedulers started together must not both see the same slot as new.
+    const result = withLock(file, () => startDue(projectDir, file, now));
+    for (const { id } of active(projectDir)) {
+        try {
+            result.advanced.push({ id, outcome: advanceCard(projectDir, id, { now, unattended: true }).outcome });
+        }
+        catch (e) {
+            if (!(e instanceof RefusalError))
+                throw e;
+            result.advanced.push({ id, outcome: 'refused', note: e.message });
+        }
+    }
+    return result;
+}
+const DAY_MS = 24 * 60 * 60 * 1000;
+const active = (projectDir) => readCards(projectDir).cards.filter(c => inLane(c) && !c.gate);
+const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+// An agent-start with no agent-run after it, younger than the timeout: another run is in the middle of this stage.
+function running(card, agent, now) {
+    const last = card.events.filter(e => e.stage === card.stage && (e.action === 'agent-start' || e.action === 'agent-run')).at(-1);
+    return last?.action === 'agent-start' && now.getTime() - new Date(last.at).getTime() < agent.timeoutMinutes * 60_000 + 60_000;
+}
+/** Why no agent may start for this card now, from the board as given. `planned` counts starts a dry run has already listed. */
+function limit(projectDir, cards, card, lane, agent, now, planned = 0) {
+    const ahead = cards.filter(c => c.lane === lane.id && inLane(c)).findIndex(c => c.id === card.id);
+    if (lane.wip !== undefined && ahead >= lane.wip)
+        return `lane ${lane.id} works on ${plural(lane.wip, 'card', 'cards')} at a time (wip); this one waits its turn`;
+    const { gatesPerDay } = loadEngineConfig(projectDir);
+    const parked = waitingOnOwner(cards);
+    if (gatesPerDay !== undefined && parked >= gatesPerDay)
+        return `${plural(parked, 'card is', 'cards are')} waiting on you (capacity.gates_per_day is ${gatesPerDay}); clear the inbox first`;
+    const starts = planned + cards.flatMap(c => c.events).filter(e => e.action === 'agent-start' && e.agent === agent.name && now.getTime() - new Date(e.at).getTime() < DAY_MS).length;
+    if (starts >= agent.maxRunsPerDay)
+        return `agent ${agent.name} has started ${plural(starts, 'time', 'times')} in the last 24 hours (max_runs_per_day is ${agent.maxRunsPerDay})`;
+    return undefined;
+}
+// null when the card needs no agent: its stage has no command to check the work with, or the check passes already.
+async function agentStep(projectDir, id, agent, now) {
+    const card = findCard(readCards(projectDir).cards, id);
+    const lane = loadLane(projectDir, card.lane);
+    const stage = lane.stages.find(s => s.id === card.stage);
+    if (!stage?.done?.cmd)
+        return null;
+    const step = { id, stage: stage.id, agent: agent.name };
+    if (awaitsApproval(card, stage))
+        return { ...step, started: false, reason: `${stage.id} is a public step that has not been approved` };
+    if (running(card, agent, now))
+        return { ...step, started: false, busy: true, reason: `agent ${agent.name} is still running on ${stage.id} from an earlier run` };
+    // A rejection asks for the work to be done again, so the agent is started with the note even
+    // though the check that passed before the gate still passes. Once per rejection.
+    const asked = card.events.filter(e => e.stage === stage.id && (e.action === 'reject' || e.action === 'agent-start')).at(-1);
+    if (asked?.action !== 'reject' && runCheck(projectDir, card, stage)?.passed)
+        return null;
+    let log = '';
+    try {
+        // The limits are judged on the same read of the board the start is written against.
+        recordEvent(projectDir, id, (cards, current) => {
+            const reason = limit(projectDir, cards, current, lane, agent, now);
+            if (reason)
+                throw new RefusalError(reason);
+            const n = current.events.filter(e => e.action === 'agent-start' && e.stage === stage.id).length + 1;
+            log = `${AGENT_RUNS_DIR}/${id}-${safeName(stage.id, 'stage id')}-${n}.log`;
+            return { action: 'agent-start', agent: agent.name, log };
+        }, now);
+    }
+    catch (e) {
+        if (!(e instanceof RefusalError))
+            throw e;
+        return { ...step, started: false, reason: e.message };
+    }
+    const brief = join(projectDir, briefPath(card));
+    mkdirSync(dirname(brief), { recursive: true });
+    writeFileSync(brief, buildBrief(projectDir, card));
+    const run = await runAgent(projectDir, agent, brief, join(projectDir, log));
+    const note = run.timedOut ? `timed out after ${agent.timeoutMinutes} minutes` : run.exit === null ? 'was killed' : undefined;
+    recordEvent(projectDir, id, () => ({ action: 'agent-run', agent: agent.name, exit: run.exit, durationMs: run.durationMs, log, ...(note ? { note } : {}) }), new Date(now.getTime() + run.durationMs));
+    return { ...step, started: true, exit: run.exit, durationMs: run.durationMs, log };
+}
+/** `runDue`, with an agent started first on each card whose stage check does not pass yet. One stage per card. */
+export async function runDueWithAgent(projectDir, agent, now = clock()) {
+    const file = join(projectDir, LAST_RUN);
+    const result = { ...withLock(file, () => startDue(projectDir, file, now)), agents: [] };
+    for (const { id, stage } of active(projectDir)) {
+        try {
+            const step = await agentStep(projectDir, id, agent, now);
+            if (step) {
+                const { busy, ...entry } = step;
+                result.agents.push(entry);
+                if (busy)
+                    continue;
+            }
+            const card = findCard(readCards(projectDir).cards, id);
+            if (card.stage !== stage || card.gate) {
+                result.advanced.push({ id, outcome: 'refused', note: 'the card was moved while the agent ran; nothing more this run' });
+                continue;
+            }
+            // What an agent just did is a new attempt even when it left the output as it was, so it is
+            // judged and counted. Without that a failing agent would be started again on every run.
+            const advance = advanceCard(projectDir, id, { now: new Date(now.getTime() + (step?.durationMs ?? 0)), unattended: !step?.started });
+            const failed = step?.started && (advance.outcome === 'failed' || advance.outcome === 'stuck');
+            result.advanced.push({ id, outcome: advance.outcome, ...(failed ? { next: nextHint(projectDir, advance.card, advance.outcome === 'failed' ? advance.output ?? '' : undefined) } : {}) });
+        }
+        catch (e) {
+            if (!(e instanceof RefusalError))
+                throw e;
+            result.advanced.push({ id, outcome: 'refused', note: e.message });
+        }
+    }
+    return result;
+}
+/** What a run would do, for `--dry-run`. Nothing is started, checked or written. */
+export function planRun(projectDir, agent, now = clock()) {
+    const { cards } = readCards(projectDir);
+    let planned = 0;
+    return cards.filter(c => inLane(c) && !c.gate).map(card => {
+        const lane = loadLane(projectDir, card.lane);
+        const stage = lane.stages.find(s => s.id === card.stage);
+        if (!agent || !stage?.done?.cmd)
+            return `${card.id}: would run the ${card.stage} check and move the card if it passes`;
+        const reason = awaitsApproval(card, stage)
+            ? `${stage.id} is a public step that has not been approved`
+            : running(card, agent, now)
+                ? `agent ${agent.name} is still running on ${stage.id} from an earlier run`
+                : limit(projectDir, cards, card, lane, agent, now, planned);
+        if (reason)
+            return `${card.id}: would not start agent ${agent.name} on ${stage.id}: ${reason}`;
+        planned++;
+        return `${card.id}: would start agent ${agent.name} on ${stage.id} unless its check already passes: ${agent.cmd.replaceAll('{brief}', shellQuote(join(projectDir, briefPath(card))))}`;
+    });
+}
+function startDue(projectDir, file, now) {
+    const last = existsSync(file) ? JSON.parse(readFileSync(file, 'utf-8')) : null;
+    const after = last ? new Date(last.at) : new Date(now.getTime() - FIRST_RUN_LOOKBACK_MS);
+    const slots = { ...(last?.slots ?? {}) };
+    const seen = { ...(last?.git ?? {}) };
+    const result = { created: [], skipped: [], advanced: [] };
+    for (const lane of loadLanes(projectDir)) {
+        const args = GIT_VALUE[lane.trigger?.on ?? ''];
+        if (!args)
+            continue;
+        const value = git(projectDir, args);
+        // The last value is recorded per lane, so the same HEAD or tag starts one card however often this runs.
+        if (!value || seen[lane.id] === value)
+            continue;
+        try {
+            const label = lane.trigger.on === 'git.commit' ? value.slice(0, 7) : value;
+            const card = createCard(projectDir, { lane: lane.id, title: `${lane.id} ${label}`, now, note: `${lane.trigger.on} ${value}` });
+            result.created.push({ lane: lane.id, id: card.id, slot: value, trigger: `${lane.trigger.on} ${label}` });
+            seen[lane.id] = value;
+        }
+        catch (e) {
+            if (!(e instanceof RefusalError))
+                throw e;
+            result.skipped.push({ lane: lane.id, reason: e.message });
+        }
+    }
+    for (const lane of loadLanes(projectDir)) {
+        if (!lane.trigger?.cron)
+            continue;
+        // One lane's unreadable schedule is that lane's problem; the others still run.
+        let due;
+        try {
+            due = lastDueSlot(lane.trigger.cron, after, now);
+        }
+        catch (e) {
+            result.skipped.push({ lane: lane.id, reason: e.message });
+            continue;
+        }
+        const slot = due?.toISOString();
+        // The slot is recorded per lane, so a re-run inside the same window cannot create a second card.
+        if (!slot || slots[lane.id] === slot)
+            continue;
+        try {
+            const card = createCard(projectDir, { lane: lane.id, title: `${lane.id} ${localDate(due)}`, now, note: `cron ${lane.trigger.cron}` });
+            result.created.push({ lane: lane.id, id: card.id, slot, trigger: `cron ${lane.trigger.cron}` });
+            slots[lane.id] = slot;
+        }
+        catch (e) {
+            if (!(e instanceof RefusalError))
+                throw e;
+            result.skipped.push({ lane: lane.id, reason: e.message });
+        }
+    }
+    // A refused slot must be found again next run, so the window start only moves when nothing was skipped.
+    const at = result.skipped.length ? after.toISOString() : now.toISOString();
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify({ at, slots, git: seen }, null, 2) + '\n');
+    return result;
+}
+//# sourceMappingURL=run.js.map

package/dist/lib/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../src/lib/run.ts"],"names":[],"mappings":"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"}

package/dist/lib/scaffold.d.ts

@@ -0,0 +1,16 @@
+export type ToolId = 'claude' | 'cursor' | 'codex';
+export interface ScaffoldResult {
+    created: string[];
+    skipped: string[];
+}
+export declare function scaffold(projectDir: string, starterFile: string, tools: ToolId[]): ScaffoldResult;
+/** Copies the GitHub workflows from templates/ci. An existing workflow file is never overwritten. */
+export declare function installCi(projectDir: string): ScaffoldResult;
+/** Installs the commit-msg hook. An existing hook that is not ours is left alone. */
+export declare function installHooks(projectDir: string): {
+    installed: boolean;
+    path: string;
+    reason?: string;
+};
+export declare function getTemplateVersion(templatePath: string): string | null;
+export declare function getInstalledVersion(projectDir: string, filePath: string): string | null;

package/dist/lib/scaffold.js

@@ -0,0 +1,175 @@
+import fse from 'fs-extra';
+import { spawnSync } from 'child_process';
+import { join, dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+const { copySync, ensureDirSync, existsSync, readdirSync, readFileSync, writeFileSync } = fse;
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// Walk up from dist/lib/ to package root
+const PACKAGE_ROOT = join(__dirname, '..', '..');
+/**
+ * Map template commands to tool-specific destinations.
+ *
+ * Claude Code: .claude/commands/*.md (markdown with frontmatter)
+ * Cursor:      .cursor/commands/*.md (same format — Cursor supports this natively)
+ * Codex:       .agents/skills/<name>/SKILL.md (YAML frontmatter with name/description)
+ */
+function getCommandDestinations(tools) {
+    const commands = ['design', 'plan', 'manage', 'test', 'commit', 'qa', 'deploy', 'debug', 'reflect', 'ship'];
+    const files = [];
+    for (const cmd of commands) {
+        const source = `templates/commands/${cmd}.md`;
+        if (tools.includes('claude')) {
+            files.push({ source, destination: `.claude/commands/${cmd}.md`, overwrite: false });
+        }
+        if (tools.includes('cursor')) {
+            files.push({ source, destination: `.cursor/commands/${cmd}.md`, overwrite: false });
+        }
+        if (tools.includes('codex')) {
+            files.push({ source, destination: `.agents/skills/${cmd}/SKILL.md`, overwrite: false });
+        }
+    }
+    return files;
+}
+function getLaneFiles() {
+    const dir = join(PACKAGE_ROOT, 'templates/lanes');
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter(f => f.endsWith('.yaml'))
+        .map(f => ({ source: `templates/lanes/${f}`, destination: `.codeloop/lanes/${f}`, overwrite: false }));
+}
+function getKnowledgeFiles() {
+    return [
+        ...getLaneFiles(),
+        { source: 'templates/codeloop/rules.md', destination: '.codeloop/rules.md', overwrite: false },
+        { source: 'templates/codeloop/gotchas.md', destination: '.codeloop/gotchas.md', overwrite: false },
+        { source: 'templates/codeloop/patterns.md', destination: '.codeloop/patterns.md', overwrite: false },
+        { source: 'templates/codeloop/principles.md', destination: '.codeloop/principles.md', overwrite: false },
+        { source: 'templates/codeloop/board.json', destination: '.codeloop/board.json', overwrite: false },
+        { source: 'templates/codeloop/.gitignore', destination: '.codeloop/.gitignore', overwrite: false },
+        { source: 'templates/tasks/todo.md', destination: 'tasks/todo.md', overwrite: false },
+    ];
+}
+export function scaffold(projectDir, starterFile, tools) {
+    const result = { created: [], skipped: [] };
+    // 1. Copy command files to tool-specific directories
+    const commandFiles = getCommandDestinations(tools);
+    for (const file of commandFiles) {
+        const destPath = join(projectDir, file.destination);
+        const srcPath = join(PACKAGE_ROOT, file.source);
+        if (!existsSync(srcPath))
+            continue;
+        if (existsSync(destPath) && !file.overwrite) {
+            result.skipped.push(file.destination);
+            continue;
+        }
+        ensureDirSync(dirname(destPath));
+        copySync(srcPath, destPath);
+        result.created.push(file.destination);
+    }
+    // 2. Copy knowledge files → .codeloop/
+    for (const file of getKnowledgeFiles()) {
+        const destPath = join(projectDir, file.destination);
+        const srcPath = join(PACKAGE_ROOT, file.source);
+        if (!existsSync(srcPath))
+            continue;
+        if (existsSync(destPath) && !file.overwrite) {
+            result.skipped.push(file.destination);
+            continue;
+        }
+        ensureDirSync(dirname(destPath));
+        copySync(srcPath, destPath);
+        result.created.push(file.destination);
+    }
+    // 3. Append seed content to knowledge files based on stack
+    const stackId = starterFile.replace('.yaml', '');
+    const seedTargets = [
+        {
+            knowledge: '.codeloop/gotchas.md',
+            seeds: ['templates/seeds/universal-gotchas.md', `templates/seeds/${stackId}-gotchas.md`],
+        },
+        {
+            knowledge: '.codeloop/patterns.md',
+            seeds: ['templates/seeds/universal-patterns.md', `templates/seeds/${stackId}-patterns.md`],
+        },
+    ];
+    for (const target of seedTargets) {
+        const destPath = join(projectDir, target.knowledge);
+        // Only append seeds to files we just created (not pre-existing ones)
+        if (!result.created.includes(target.knowledge))
+            continue;
+        if (!existsSync(destPath))
+            continue;
+        let content = readFileSync(destPath, 'utf-8');
+        for (const seedSource of target.seeds) {
+            const seedPath = join(PACKAGE_ROOT, seedSource);
+            if (existsSync(seedPath)) {
+                content += '\n' + readFileSync(seedPath, 'utf-8').trimEnd() + '\n';
+            }
+        }
+        writeFileSync(destPath, content);
+    }
+    // 4. Copy starter config → .codeloop/config.yaml
+    const configDest = join(projectDir, '.codeloop/config.yaml');
+    if (!existsSync(configDest)) {
+        const starterPath = join(PACKAGE_ROOT, 'starters', starterFile);
+        if (existsSync(starterPath)) {
+            ensureDirSync(dirname(configDest));
+            copySync(starterPath, configDest);
+            result.created.push('.codeloop/config.yaml');
+        }
+    }
+    else {
+        result.skipped.push('.codeloop/config.yaml');
+    }
+    return result;
+}
+/** Copies the GitHub workflows from templates/ci. An existing workflow file is never overwritten. */
+export function installCi(projectDir) {
+    const result = { created: [], skipped: [] };
+    const dir = join(PACKAGE_ROOT, 'templates/ci');
+    for (const file of readdirSync(dir).filter(f => f.endsWith('.yml'))) {
+        const destination = `.github/workflows/${file}`;
+        const dest = join(projectDir, destination);
+        if (existsSync(dest)) {
+            result.skipped.push(destination);
+            continue;
+        }
+        ensureDirSync(dirname(dest));
+        copySync(join(dir, file), dest);
+        result.created.push(destination);
+    }
+    return result;
+}
+/** Installs the commit-msg hook. An existing hook that is not ours is left alone. */
+export function installHooks(projectDir) {
+    const run = spawnSync('git', ['rev-parse', '--git-path', 'hooks'], { cwd: projectDir, encoding: 'utf-8' });
+    if (run.status !== 0)
+        return { installed: false, path: '', reason: 'not a git repository' };
+    const path = join(resolve(projectDir, run.stdout.trim()), 'commit-msg');
+    const source = readFileSync(join(PACKAGE_ROOT, 'templates/hooks/commit-msg'), 'utf-8');
+    if (existsSync(path) && readFileSync(path, 'utf-8') !== source) {
+        return { installed: false, path, reason: 'a different commit-msg hook already exists' };
+    }
+    ensureDirSync(dirname(path));
+    writeFileSync(path, source, { mode: 0o755 });
+    return { installed: true, path };
+}
+export function getTemplateVersion(templatePath) {
+    const fullPath = join(PACKAGE_ROOT, templatePath);
+    if (!existsSync(fullPath))
+        return null;
+    const content = readFileSync(fullPath, 'utf-8');
+    const match = content.match(/<!--\s*codeloop-version:\s*([\d.]+)\s*-->/);
+    return match ? match[1] : null;
+}
+export function getInstalledVersion(projectDir, filePath) {
+    const fullPath = join(projectDir, filePath);
+    if (!existsSync(fullPath))
+        return null;
+    const content = readFileSync(fullPath, 'utf-8');
+    const match = content.match(/<!--\s*codeloop-version:\s*([\d.]+)\s*-->/);
+    return match ? match[1] : null;
+}
+//# sourceMappingURL=scaffold.js.map

package/dist/lib/scaffold.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.js","sourceRoot":"","sources":["../../src/lib/scaffold.ts"],"names":[],"mappings":"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"}

package/dist/lib/scan.d.ts

@@ -0,0 +1,22 @@
+export declare const SCAN_DIR = ".codeloop/state/scan";
+export interface ScanResult {
+    name: string;
+    /** baseline: first text seen, stored and nothing proposed. already-proposed: a card for this change exists. */
+    outcome: 'proposed' | 'already-proposed' | 'unchanged' | 'baseline' | 'skipped';
+    card?: string;
+    reason?: string;
+}
+/** A changelog page as lines of text. HTML headings become `#` lines so a heading can be told from a sentence. */
+export declare function pageText(raw: string): string;
+/** Lines of `after` that `before` does not have, in page order. */
+export declare function newLines(before: string, after: string): string[];
+/**
+ * Reads each competitor page's changelog, compares it with the text stored from the last scan and,
+ * when new text appeared, proposes one card in the plan lane for that competitor. The card waits
+ * for the owner; nothing starts it. `fromFile` supplies the page text instead of fetching.
+ */
+export declare function scanCompetitors(projectDir: string, opts?: {
+    fromFile?: string;
+    only?: string;
+    now?: Date;
+}): Promise<ScanResult[]>;

package/dist/lib/scan.js

@@ -0,0 +1,85 @@
+import { createHash } from 'crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import { listCompetitors } from './competitors.js';
+import { proposeCard } from './engine.js';
+import { clock } from './clock.js';
+import { withLock } from './lock.js';
+export const SCAN_DIR = '.codeloop/state/scan';
+const PLAN_LANE = 'plan';
+const FETCH_TIMEOUT_MS = 10_000;
+const EXCERPT_LINES = 12;
+const TITLE_CHARS = 80;
+const ENTITIES = { '&nbsp;': ' ', '&amp;': '&', '&lt;': '<', '&gt;': '>', '&quot;': '"', '&#39;': "'" };
+/** A changelog page as lines of text. HTML headings become `#` lines so a heading can be told from a sentence. */
+export function pageText(raw) {
+    const text = /<\/?(html|body|h[1-6]|p|div|li)\b/i.test(raw)
+        ? raw
+            .replace(/<(script|style)\b[\s\S]*?<\/\1>/gi, '')
+            .replace(/<h[1-6]\b[^>]*>/gi, '\n# ')
+            .replace(/<li\b[^>]*>/gi, '\n- ')
+            .replace(/<\/(h[1-6]|p|div|li|ul|ol|tr|section|article)>|<br\s*\/?>/gi, '\n')
+            .replace(/<[^>]+>/g, '')
+            .replace(/&nbsp;|&amp;|&lt;|&gt;|&quot;|&#39;/g, e => ENTITIES[e])
+        : raw;
+    return text.split('\n').map(l => l.replace(/\s+/g, ' ').trim()).filter(Boolean).join('\n') + '\n';
+}
+/** Lines of `after` that `before` does not have, in page order. */
+export function newLines(before, after) {
+    const seen = new Set(before.split('\n'));
+    return after.split('\n').filter(l => l && !seen.has(l));
+}
+async function fetchText(url) {
+    try {
+        const res = await fetch(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS), headers: { 'user-agent': 'codeloop-scan' } });
+        return res.ok ? { text: await res.text() } : { reason: `${url} answered ${res.status}` };
+    }
+    catch (e) {
+        const cause = e.cause;
+        return { reason: `${url} did not answer (${cause?.code ?? e.message})` };
+    }
+}
+/**
+ * Reads each competitor page's changelog, compares it with the text stored from the last scan and,
+ * when new text appeared, proposes one card in the plan lane for that competitor. The card waits
+ * for the owner; nothing starts it. `fromFile` supplies the page text instead of fetching.
+ */
+export async function scanCompetitors(projectDir, opts = {}) {
+    const results = [];
+    const now = opts.now ?? clock();
+    for (const competitor of listCompetitors(projectDir).filter(c => c.changelog && (!opts.only || c.name === opts.only))) {
+        const fetched = opts.fromFile ? { text: readFileSync(resolve(projectDir, opts.fromFile), 'utf-8') } : await fetchText(competitor.changelog);
+        if ('reason' in fetched) {
+            results.push({ name: competitor.name, outcome: 'skipped', reason: fetched.reason });
+            continue;
+        }
+        const text = pageText(fetched.text);
+        const stored = join(projectDir, SCAN_DIR, `${competitor.name}.txt`);
+        results.push(withLock(stored, () => {
+            const before = existsSync(stored) ? readFileSync(stored, 'utf-8') : null;
+            const fresh = before === null ? [] : newLines(before, text);
+            let result = { name: competitor.name, outcome: before === null ? 'baseline' : 'unchanged' };
+            if (fresh.length) {
+                const headline = (fresh.find(l => l.startsWith('#')) ?? fresh[0]).replace(/^[#\-*\s]+/, '').slice(0, TITLE_CHARS);
+                const excerpt = fresh.slice(0, EXCERPT_LINES).join('\n');
+                const { card, created } = proposeCard(projectDir, {
+                    lane: PLAN_LANE,
+                    title: `${competitor.title} shipped: ${headline}`,
+                    description: `New on ${competitor.title}'s changelog, seen ${now.toISOString().slice(0, 10)}:\n\n${excerpt}${fresh.length > EXCERPT_LINES ? `\n(${fresh.length - EXCERPT_LINES} more new lines)` : ''}\n\nSource: ${competitor.changelog}`,
+                    source: competitor.changelog,
+                    // The change itself names the card, so the same new text cannot produce a second one.
+                    dedupe: `scan:${competitor.name}:${createHash('sha1').update(fresh.join('\n')).digest('hex').slice(0, 16)}`,
+                    role: 'engine',
+                    now,
+                });
+                result = { name: competitor.name, outcome: created ? 'proposed' : 'already-proposed', card: card.id };
+            }
+            // Stored after the card exists: a crash in between repeats the proposal, which `dedupe` absorbs.
+            mkdirSync(dirname(stored), { recursive: true });
+            writeFileSync(stored, text);
+            return result;
+        }));
+    }
+    return results;
+}
+//# sourceMappingURL=scan.js.map

package/dist/lib/scan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan.js","sourceRoot":"","sources":["../../src/lib/scan.ts"],"names":[],"mappings":"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"}

package/dist/lib/schedule.d.ts

@@ -0,0 +1,20 @@
+export declare const RUN_LOG = ".codeloop/state/run.log";
+/** `30m`, `1h`, `6h`: only intervals that divide the hour or the day, since cron cannot say "every 45 minutes". */
+export declare function everyToCron(every: string): string;
+/**
+ * One crontab line. cron starts with a bare PATH, so the PATH of the installing shell is written
+ * into the line: the agent command (claude, codex) has to be found at 3am too.
+ */
+export declare function scheduleLine(projectDir: string, opts: {
+    cron: string;
+    agent?: string | true;
+    entry?: string;
+    path?: string;
+}): string;
+export declare function installSchedule(projectDir: string, line: string, crontab?: string): void;
+export declare function removeSchedule(projectDir: string, crontab?: string): boolean;
+export declare function scheduleStatus(projectDir: string, crontab?: string): {
+    line?: string;
+    lastRun?: Date;
+    lastOutput?: string;
+};