harborloop 0.3.0 → 0.4.1

package/dist/daemon/install.js

@@ -1,192 +0,0 @@
-import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
-import { homedir } from 'node:os';
-import { join } from 'node:path';
-import { TICK_INTERVAL_MS } from './loop.js';
-export const LAUNCHD_LABEL = 'com.harbor.daemon';
-export const SYSTEMD_UNIT = 'harbor-daemon';
-export function installPlatform(platform = process.platform) {
-    if (platform === 'darwin')
-        return 'darwin';
-    if (platform === 'linux')
-        return 'linux';
-    return 'unsupported';
-}
-export function daemonProgram(argv = process.argv, execPath = process.execPath) {
-    const script = argv[1];
-    if (script === undefined || script === '') {
-        throw new Error('Could not work out which script to schedule. Run `harbor daemon --install` from the installed CLI.');
-    }
-    return { interpreter: execPath, script };
-}
-export function launchAgentPath(home = homedir()) {
-    return join(home, 'Library', 'LaunchAgents', `${LAUNCHD_LABEL}.plist`);
-}
-export function systemdDir(home = homedir()) {
-    return join(home, '.config', 'systemd', 'user');
-}
-const escapeXml = (value) => value.replace(/[<>&'"]/g, (c) => ({ '<': '&lt;', '>': '&gt;', '&': '&amp;', "'": '&apos;', '"': '&quot;' })[c]);
-export function launchAgentPlist(program, harborHome, intervalSeconds = Math.round(TICK_INTERVAL_MS / 1000)) {
-    return `<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-  <key>Label</key>
-  <string>${LAUNCHD_LABEL}</string>
-  <key>ProgramArguments</key>
-  <array>
-    <string>${escapeXml(program.interpreter)}</string>
-    <string>${escapeXml(program.script)}</string>
-    <string>daemon</string>
-    <string>--once</string>
-  </array>
-  <key>RunAtLoad</key>
-  <true/>
-  <key>StartInterval</key>
-  <integer>${intervalSeconds}</integer>
-  <key>ProcessType</key>
-  <string>Background</string>
-  <key>StandardOutPath</key>
-  <string>${escapeXml(join(harborHome, 'daemon.log'))}</string>
-  <key>StandardErrorPath</key>
-  <string>${escapeXml(join(harborHome, 'daemon.log'))}</string>
-</dict>
-</plist>
-`;
-}
-export function systemdService(program) {
-    return `[Unit]
-Description=Harbor — keep this machine's team context current
-Documentation=https://github.com/harbor
-
-[Service]
-Type=oneshot
-ExecStart=${program.interpreter} ${program.script} daemon --once
-`;
-}
-export function systemdTimer(intervalSeconds = Math.round(TICK_INTERVAL_MS / 1000)) {
-    return `[Unit]
-Description=Harbor sync timer
-
-[Timer]
-OnBootSec=1min
-OnUnitActiveSec=${intervalSeconds}s
-Persistent=true
-
-[Install]
-WantedBy=timers.target
-`;
-}
-export function installPlan(input) {
-    const home = input.home ?? homedir();
-    const platform = input.platform ?? installPlatform();
-    if (platform === 'darwin') {
-        const plist = launchAgentPath(home);
-        const domain = `gui/${input.uid ?? process.getuid?.() ?? 0}`;
-        return {
-            platform,
-            files: [{ path: plist, body: launchAgentPlist(input.program, input.harborHome) }],
-            activate: [
-                ['launchctl', 'bootout', domain, plist],
-                ['launchctl', 'bootstrap', domain, plist],
-            ],
-            deactivate: [['launchctl', 'bootout', domain, plist]],
-        };
-    }
-    if (platform === 'linux') {
-        const dir = systemdDir(home);
-        return {
-            platform,
-            files: [
-                {
-                    path: join(dir, `${SYSTEMD_UNIT}.service`),
-                    body: systemdService(input.program),
-                },
-                { path: join(dir, `${SYSTEMD_UNIT}.timer`), body: systemdTimer() },
-            ],
-            activate: [
-                ['systemctl', '--user', 'daemon-reload'],
-                ['systemctl', '--user', 'enable', '--now', `${SYSTEMD_UNIT}.timer`],
-            ],
-            deactivate: [
-                ['systemctl', '--user', 'disable', '--now', `${SYSTEMD_UNIT}.timer`],
-            ],
-        };
-    }
-    return { platform, files: [], activate: [], deactivate: [] };
-}
-export const spawnRunner = async (argv) => {
-    const { execFile } = await import('node:child_process');
-    return new Promise((resolve) => {
-        execFile(argv[0], [...argv.slice(1)], (err, _stdout, stderr) => {
-            resolve({
-                ok: err === null,
-                message: err === null ? '' : (stderr.trim() || err.message),
-            });
-        });
-    });
-};
-export async function installDaemon(input) {
-    const { plan } = input;
-    if (plan.platform === 'unsupported') {
-        return {
-            kind: 'unsupported',
-            files: [],
-            manual: [],
-            detail: 'Scheduling is not wired for this platform yet. Run `harbor daemon` in a terminal, or call `harbor daemon --once` from your own scheduler.',
-        };
-    }
-    const run = input.run ?? spawnRunner;
-    for (const file of plan.files) {
-        await mkdir(join(file.path, '..'), { recursive: true });
-        await writeFile(file.path, file.body, 'utf8');
-    }
-    const manual = [];
-    for (const argv of plan.activate) {
-        const result = await run(argv);
-        if (!result.ok && argv === plan.activate[plan.activate.length - 1]) {
-            manual.push(argv);
-        }
-    }
-    return {
-        kind: manual.length === 0 ? 'installed' : 'partial',
-        files: plan.files.map((f) => f.path),
-        manual,
-        detail: manual.length === 0
-            ? 'Harbor will keep this machine current in the background.'
-            : 'The files are written, but the scheduler did not pick them up. Run the command below by hand.',
-    };
-}
-export async function uninstallDaemon(input) {
-    const { plan } = input;
-    if (plan.platform === 'unsupported') {
-        return {
-            kind: 'unsupported',
-            files: [],
-            manual: [],
-            detail: 'Nothing was scheduled on this platform.',
-        };
-    }
-    const run = input.run ?? spawnRunner;
-    for (const argv of plan.deactivate)
-        await run(argv);
-    for (const file of plan.files)
-        await rm(file.path, { force: true });
-    return {
-        kind: 'removed',
-        files: plan.files.map((f) => f.path),
-        manual: [],
-        detail: 'Background syncing is off. `harbor sync` still works by hand.',
-    };
-}
-export async function installedFiles(plan) {
-    const found = [];
-    for (const file of plan.files) {
-        try {
-            await readFile(file.path, 'utf8');
-            found.push(file.path);
-        }
-        catch {
-        }
-    }
-    return found;
-}

package/dist/daemon/loop.d.ts

@@ -1,15 +0,0 @@
-import type { Endpoints } from '../endpoints.js';
-import { type DaemonTickReport } from './tick.js';
-export declare const TICK_INTERVAL_MS: number;
-export declare function sleepDetected(lastCheckMs: number, nowMs: number, watchdogMs?: number): boolean;
-export interface DaemonLoopOptions {
-    readonly endpoints: Endpoints;
-    readonly intervalMs?: number;
-    readonly env?: NodeJS.ProcessEnv;
-    readonly fetchImpl?: typeof fetch;
-    readonly home?: string;
-    readonly onTick?: (report: DaemonTickReport) => void;
-    readonly onSkipped?: (detail: string) => void;
-    readonly signal?: AbortSignal;
-}
-export declare function runDaemonLoop(opts: DaemonLoopOptions): Promise<void>;

package/dist/daemon/loop.js

@@ -1,84 +0,0 @@
-import { recordTick, writeDaemonHeartbeat, } from './state.js';
-import { runDaemonTick, summarise } from './tick.js';
-export const TICK_INTERVAL_MS = 15 * 60 * 1000;
-const WATCHDOG_MS = 30_000;
-const SLEEP_FACTOR = 4;
-export function sleepDetected(lastCheckMs, nowMs, watchdogMs = WATCHDOG_MS) {
-    return nowMs - lastCheckMs > watchdogMs * SLEEP_FACTOR;
-}
-export async function runDaemonLoop(opts) {
-    const intervalMs = opts.intervalMs ?? TICK_INTERVAL_MS;
-    const identity = {
-        mode: 'loop',
-        startedBy: 'cli',
-        startedAt: new Date().toISOString(),
-        pid: process.pid,
-        intervalMs,
-    };
-    await writeDaemonHeartbeat({ version: 1, ...identity, lastTick: null });
-    let inFlight = null;
-    let queued = null;
-    const request = async (reason) => {
-        if (inFlight) {
-            queued = reason;
-            return inFlight;
-        }
-        inFlight = (async () => {
-            try {
-                const outcome = await runDaemonTick({
-                    endpoints: opts.endpoints,
-                    reason,
-                    ...(opts.env ? { env: opts.env } : {}),
-                    ...(opts.fetchImpl ? { fetchImpl: opts.fetchImpl } : {}),
-                    ...(opts.home === undefined ? {} : { home: opts.home }),
-                });
-                if (outcome.kind === 'contended') {
-                    opts.onSkipped?.(outcome.detail);
-                    return;
-                }
-                await recordTick(summarise(outcome.report), identity);
-                opts.onTick?.(outcome.report);
-            }
-            catch (err) {
-                process.stderr.write(`harbor daemon: tick threw — ${String(err)}\n`);
-            }
-        })();
-        try {
-            await inFlight;
-        }
-        finally {
-            inFlight = null;
-            const next = queued;
-            queued = null;
-            if (next !== null)
-                void request(next);
-        }
-    };
-    await request('startup');
-    return new Promise((resolve) => {
-        let lastCheck = Date.now();
-        let dueAt = Date.now() + intervalMs;
-        const watchdog = setInterval(() => {
-            const now = Date.now();
-            if (sleepDetected(lastCheck, now)) {
-                lastCheck = now;
-                dueAt = now + intervalMs;
-                void request('resume from sleep');
-                return;
-            }
-            lastCheck = now;
-            if (now >= dueAt) {
-                dueAt = now + intervalMs;
-                void request('interval');
-            }
-        }, WATCHDOG_MS);
-        const stop = () => {
-            clearInterval(watchdog);
-            resolve();
-        };
-        if (opts.signal?.aborted)
-            stop();
-        else
-            opts.signal?.addEventListener('abort', stop, { once: true });
-    });
-}

package/dist/daemon/state.d.ts

@@ -1,79 +0,0 @@
-export type TickArm = {
-    readonly kind: 'ok';
-    readonly detail: string;
-} | {
-    readonly kind: 'skipped';
-    readonly detail: string;
-} | {
-    readonly kind: 'failed';
-    readonly detail: string;
-};
-export interface TickSummary {
-    readonly at: string;
-    readonly reason: string;
-    readonly durationMs: number;
-    readonly credential: TickArm;
-    readonly env: TickArm;
-    readonly repos: number;
-    readonly reposFailed: number;
-    readonly report: TickArm;
-}
-export type DaemonMode = 'loop' | 'once';
-export type DaemonRunner = 'cli' | 'app';
-export interface DaemonHeartbeat {
-    readonly version: 1;
-    readonly mode: DaemonMode;
-    readonly startedBy: DaemonRunner;
-    readonly startedAt: string;
-    readonly pid: number;
-    readonly intervalMs: number;
-    readonly lastTick: TickSummary | null;
-}
-export declare function daemonStateFile(): string;
-export declare function tickLeaseFile(): string;
-export declare const TICK_LEASE_STALE_MS = 60000;
-export type TickLease<T> = {
-    readonly kind: 'ran';
-    readonly value: T;
-} | {
-    readonly kind: 'contended';
-    readonly detail: string;
-};
-export declare function withTickLease<T>(critical: () => Promise<T>, opts?: {
-    readonly waitMs?: number;
-}): Promise<TickLease<T>>;
-export declare function readDaemonHeartbeat(): Promise<DaemonHeartbeat | null>;
-export declare function writeDaemonHeartbeat(state: DaemonHeartbeat): Promise<void>;
-export interface DaemonIdentity {
-    readonly mode: DaemonMode;
-    readonly startedBy: DaemonRunner;
-    readonly startedAt: string;
-    readonly pid: number;
-    readonly intervalMs: number;
-}
-export declare function recordTick(summary: TickSummary, identity: DaemonIdentity): Promise<void>;
-export type DaemonVerdict = {
-    readonly kind: 'never_run';
-    readonly detail: string;
-    readonly fix: string;
-} | {
-    readonly kind: 'idle';
-    readonly detail: string;
-    readonly fix: string;
-} | {
-    readonly kind: 'stopped';
-    readonly detail: string;
-    readonly fix: string;
-} | {
-    readonly kind: 'failing';
-    readonly detail: string;
-    readonly fix: string;
-} | {
-    readonly kind: 'degraded';
-    readonly detail: string;
-    readonly fix: string;
-} | {
-    readonly kind: 'ok';
-    readonly detail: string;
-};
-export declare function daemonVerdict(state: DaemonHeartbeat | null, now?: Date): DaemonVerdict;

package/dist/daemon/state.js

@@ -1,213 +0,0 @@
-import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { ensureConfigDir, LockTimeoutError, lockPathFor, readLockHolder, updateFileLocked, withFileLock, } from '../lock.js';
-import { harborDir } from '../paths.js';
-export function daemonStateFile() {
-    return join(harborDir(), 'daemon.json');
-}
-export function tickLeaseFile() {
-    return join(harborDir(), 'daemon.tick');
-}
-export const TICK_LEASE_STALE_MS = 60_000;
-const TICK_LEASE_RENEW_MS = 15_000;
-const TICK_LEASE_WAIT_MS = 0;
-export async function withTickLease(critical, opts = {}) {
-    const target = tickLeaseFile();
-    await ensureConfigDir(harborDir());
-    try {
-        return {
-            kind: 'ran',
-            value: await withFileLock(target, () => critical(), {
-                waitMs: opts.waitMs ?? TICK_LEASE_WAIT_MS,
-                staleMs: TICK_LEASE_STALE_MS,
-                renewMs: TICK_LEASE_RENEW_MS,
-            }),
-        };
-    }
-    catch (err) {
-        if (err instanceof LockTimeoutError && err.lockPath === lockPathFor(target)) {
-            return { kind: 'contended', detail: await describeHolder(target) };
-        }
-        throw err;
-    }
-}
-async function describeHolder(target) {
-    const holder = await readLockHolder(target);
-    if (holder === null) {
-        return 'Another Harbor scheduler on this machine is ticking. Skipped this pass.';
-    }
-    return (`Another Harbor scheduler on this machine is ticking (pid ${holder.pid}, ` +
-        `since ${holder.at}). Skipped this pass.`);
-}
-function parse(raw) {
-    if (raw.trim() === '')
-        return null;
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch {
-        return null;
-    }
-    if (parsed === null || typeof parsed !== 'object')
-        return null;
-    const obj = parsed;
-    if (typeof obj.startedAt !== 'string' || typeof obj.pid !== 'number')
-        return null;
-    return {
-        version: 1,
-        mode: obj.mode === 'once' ? 'once' : 'loop',
-        startedBy: obj.startedBy === 'app' ? 'app' : 'cli',
-        startedAt: obj.startedAt,
-        pid: obj.pid,
-        intervalMs: typeof obj.intervalMs === 'number' ? obj.intervalMs : 0,
-        lastTick: parseTick(obj.lastTick),
-    };
-}
-function parseArm(raw) {
-    const obj = raw !== null && typeof raw === 'object' ? raw : {};
-    const detail = typeof obj.detail === 'string' ? obj.detail : '';
-    return obj.kind === 'ok' || obj.kind === 'failed'
-        ? { kind: obj.kind, detail }
-        : { kind: 'skipped', detail };
-}
-function parseTick(raw) {
-    if (raw === null || typeof raw !== 'object')
-        return null;
-    const obj = raw;
-    if (typeof obj.at !== 'string')
-        return null;
-    return {
-        at: obj.at,
-        reason: typeof obj.reason === 'string' ? obj.reason : '',
-        durationMs: typeof obj.durationMs === 'number' ? obj.durationMs : 0,
-        credential: parseArm(obj.credential),
-        env: parseArm(obj.env),
-        repos: typeof obj.repos === 'number' ? obj.repos : 0,
-        reposFailed: typeof obj.reposFailed === 'number' ? obj.reposFailed : 0,
-        report: parseArm(obj.report),
-    };
-}
-export async function readDaemonHeartbeat() {
-    try {
-        return parse(await readFile(daemonStateFile(), 'utf8'));
-    }
-    catch {
-        return null;
-    }
-}
-export async function writeDaemonHeartbeat(state) {
-    await ensureConfigDir(harborDir());
-    await updateFileLocked(daemonStateFile(), () => `${JSON.stringify(state, null, 2)}\n`);
-}
-export async function recordTick(summary, identity) {
-    await ensureConfigDir(harborDir());
-    await updateFileLocked(daemonStateFile(), (existing) => {
-        const current = parse(existing);
-        const next = {
-            version: 1,
-            mode: identity.mode,
-            startedBy: identity.startedBy,
-            startedAt: current?.mode === identity.mode
-                ? (current?.startedAt ?? identity.startedAt)
-                : identity.startedAt,
-            pid: identity.pid,
-            intervalMs: identity.intervalMs,
-            lastTick: summary,
-        };
-        return `${JSON.stringify(next, null, 2)}\n`;
-    });
-}
-const LATE_AFTER_INTERVALS = 3;
-const MIN_INTERVAL_MS = 60_000;
-function alive(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (err) {
-        return err.code === 'EPERM';
-    }
-}
-export function daemonVerdict(state, now = new Date()) {
-    if (state === null || state.lastTick === null) {
-        return {
-            kind: 'never_run',
-            detail: 'Never run on this machine.',
-            fix: 'Run `harbor daemon --install` to keep context current, or `harbor daemon --once` for a single pass.',
-        };
-    }
-    const tick = state.lastTick;
-    const age = now.getTime() - new Date(tick.at).getTime();
-    const interval = Math.max(state.intervalMs, MIN_INTERVAL_MS);
-    const ago = describeAge(age);
-    if (age > interval * LATE_AFTER_INTERVALS) {
-        return {
-            kind: 'stopped',
-            detail: `Last tick ${ago} — more than ${LATE_AFTER_INTERVALS} intervals ago.`,
-            fix: restart(state.startedBy),
-        };
-    }
-    if (state.mode === 'loop' && !alive(state.pid)) {
-        return {
-            kind: 'stopped',
-            detail: `The process that ticked ${ago} (pid ${state.pid}) is gone.`,
-            fix: restart(state.startedBy),
-        };
-    }
-    if (tick.credential.kind === 'failed') {
-        return {
-            kind: 'failing',
-            detail: `Ticking, but the credential is not: ${tick.credential.detail}`,
-            fix: 'Run `harbor login` — until then nothing this machine syncs will be accepted.',
-        };
-    }
-    if (tick.env.kind === 'failed') {
-        return {
-            kind: 'failing',
-            detail: `Ticking ${ago}, but your own skills and documents did not sync: ${tick.env.detail}`,
-            fix: 'Run `harbor doctor --json` for the transport error, then `harbor daemon --once`.',
-        };
-    }
-    if (tick.credential.kind === 'skipped' && tick.env.kind === 'skipped' && tick.repos === 0) {
-        return {
-            kind: 'idle',
-            detail: `Ticking ${ago}, with nothing to do: ${tick.env.detail}`,
-            fix: 'Run `harbor login`, then `harbor daemon --once`.',
-        };
-    }
-    if (tick.report.kind === 'failed') {
-        return {
-            kind: 'degraded',
-            detail: `Files are current as of ${ago}, but this machine could not report them: ${tick.report.detail}`,
-            fix: 'The distribution map will show this machine as stale until it can.',
-        };
-    }
-    if (tick.reposFailed > 0) {
-        return {
-            kind: 'degraded',
-            detail: `Ticked ${ago} — ${tick.reposFailed} of ${tick.repos} repositories failed.`,
-            fix: 'Run `harbor daemon --once` to see which, or remove folders that have moved.',
-        };
-    }
-    return {
-        kind: 'ok',
-        detail: `Ticked ${ago} — ${tick.repos} ${tick.repos === 1 ? 'repository' : 'repositories'}, reported.`,
-    };
-}
-function restart(startedBy) {
-    return startedBy === 'app'
-        ? 'Open Harbor from Applications, or run `harbor daemon --install` so syncing no longer depends on it.'
-        : 'Start it again with `harbor daemon --install`, or run `harbor daemon --once` now.';
-}
-function describeAge(ms) {
-    if (ms < 90_000)
-        return 'less than a minute ago';
-    const minutes = Math.round(ms / 60_000);
-    if (minutes < 90)
-        return `${minutes} minutes ago`;
-    const hours = Math.round(minutes / 60);
-    if (hours < 48)
-        return `${hours} hours ago`;
-    return `${Math.round(hours / 24)} days ago`;
-}

package/dist/daemon/tick.d.ts

@@ -1,37 +0,0 @@
-import type { Endpoints } from '../endpoints.js';
-import { type TickArm, type TickSummary } from './state.js';
-export declare const REFRESH_WHEN_LESS_THAN_MS: number;
-export interface DaemonTickOptions {
-    readonly endpoints: Endpoints;
-    readonly reason: string;
-    readonly env?: NodeJS.ProcessEnv;
-    readonly fetchImpl?: typeof fetch;
-    readonly home?: string;
-    readonly now?: () => Date;
-    readonly lockWaitMs?: number;
-}
-export interface RepoTick {
-    readonly path: string;
-    readonly originUrl: string;
-    readonly outcome: TickArm;
-}
-export interface DaemonTickReport {
-    readonly startedAt: string;
-    readonly finishedAt: string;
-    readonly reason: string;
-    readonly credential: TickArm;
-    readonly env: TickArm;
-    readonly repos: readonly RepoTick[];
-    readonly report: TickArm;
-    readonly bundleHash?: string;
-    readonly release?: TickArm;
-}
-export type DaemonTickOutcome = {
-    readonly kind: 'ran';
-    readonly report: DaemonTickReport;
-} | {
-    readonly kind: 'contended';
-    readonly detail: string;
-};
-export declare function runDaemonTick(opts: DaemonTickOptions): Promise<DaemonTickOutcome>;
-export declare function summarise(report: DaemonTickReport): TickSummary;