looply-cli 0.5.8 → 0.5.9

package/dist/machine-settings.d.ts

@@ -0,0 +1,188 @@
+import { DEFAULT_MIN_FREE_GB, type MachineSettings, type WorkspacesReport, type WorkspacesSource } from '@looply/core';
+/**
+ * WHERE THIS MACHINE'S CHECKOUTS GO, AND HOW MUCH DISK THEY MAY TAKE.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * 🔴 ON 2026-10-16 CHECKOUTS FILLED THE OWNER'S C: (about 100 GB). 0.5.7 gave
+ * the machine a local file for it; this lets the machine's OWNER choose the same
+ * thing remotely — from the Looply console or AutoRyn — per machine.
+ *
+ * PRECEDENCE, per field:
+ *   1. the machine's own say: `LOOPLY_WORKSPACES_ROOT`, then
+ *      `~/.looply/machine-settings.json` (`workspacesRoot`, `checkoutsCapGb`,
+ *      `minFreeGb`);
+ *   2. the remote setting, as this machine last heard it (cached here, so an
+ *      offline machine keeps what it was last told);
+ *   3. the default: `~/.looply/workspaces`, no cap, 20 GB free.
+ *
+ * 🔴 A REMOTE FOLDER IS CHECKED ON THIS MACHINE BEFORE IT IS USED. The server
+ * can only check a path's shape; whether it is on a local fixed drive, outside
+ * every served repository and outside `~/.looply`, not a system folder, and
+ * creatable and writable is a fact about this machine. A folder that fails is
+ * REFUSED IN WORDS and the previous folder stays in effect — the refusal travels
+ * on the heartbeat so the console and AutoRyn can show it.
+ *
+ * ⚠️ A CHANGE APPLIES TO NEW CHECKOUTS ONLY. Every folder checkouts were ever
+ * made in is remembered (`knownWorkspacesBases`), so a run already going
+ * finishes where it is and its checkout is reaped where it is.
+ *
+ * Files, all under `~/.looply` (machine-level, never inside a repository):
+ *   machine-settings.json          the machine's own say (a person writes it)
+ *   machine-settings-remote.json   the remote setting and the verdict on its folder
+ *   workspaces-bases.json          every folder checkouts were made in
+ *   checkouts-usage.json           GB used by checkouts, measured now and then
+ */
+export { DEFAULT_MIN_FREE_GB };
+export declare const MACHINE_SETTINGS_FILE = "machine-settings.json";
+export declare const REMOTE_MACHINE_SETTINGS_FILE = "machine-settings-remote.json";
+export declare const WORKSPACES_BASES_FILE = "workspaces-bases.json";
+export declare const CHECKOUTS_USAGE_FILE = "checkouts-usage.json";
+export declare const WORKSPACES_DIR = "workspaces";
+/** How long a usage measurement is trusted before it is taken again. */
+export declare const USAGE_MAX_AGE_MS: number;
+export declare const defaultWorkspacesBase: (home?: string) => string;
+export interface LocalMachineSettings {
+    workspacesRoot?: string;
+    checkoutsCapGb?: number;
+    minFreeGb?: number;
+}
+/**
+ * `~/.looply/machine-settings.json`, checked. Absent is `{}`.
+ *
+ * ⚠️ AN UNUSABLE LOCAL SETTING THROWS, as it did in 0.5.7: falling back to the
+ * home drive silently is the exact outcome the setting exists to prevent, and a
+ * person wrote this file on this machine and can fix it.
+ */
+export declare function readLocalMachineSettings(home?: string): LocalMachineSettings;
+/** The verdict on the remote folder, as this machine reached it. */
+export interface FolderVerdict {
+    /** The remote value judged. */
+    value: string;
+    ok: boolean;
+    /** Why not, in words a person can act on. */
+    because: string | null;
+    checkedAt: string;
+}
+export interface RemoteMachineSettingsCache {
+    settings: MachineSettings;
+    updatedAt: string | null;
+    fetchedAt: string;
+    /** The remote folder actually in use: the last one that passed. Null: the default. */
+    inEffect: string | null;
+    /** The last verdict on `settings.workspacesRoot`, when there is one. */
+    verdict: FolderVerdict | null;
+}
+export declare function readRemoteMachineSettings(home?: string): RemoteMachineSettingsCache | null;
+export declare function writeRemoteMachineSettings(home: string, value: RemoteMachineSettingsCache): void;
+export type DriveKind = 'fixed' | 'removable' | 'network' | 'cdrom' | 'ram' | 'unknown' | 'missing';
+/**
+ * What kind of drive `path` is on. Windows only asks; elsewhere every local
+ * path is answered `fixed` (a POSIX machine has no drive letters to judge).
+ */
+export declare function nodeDriveKind(path: string, platform?: NodeJS.Platform): DriveKind;
+export interface FolderCheckDeps {
+    home: string;
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+    /** Every repository this machine serves, and every folder it scans for them. */
+    servedPaths: readonly string[];
+    driveKind?: (path: string) => DriveKind;
+    /** Create the folder and prove a file can be written in it; throws with the reason. */
+    probeWritable?: (path: string) => void;
+}
+export declare function nodeProbeWritable(path: string): void;
+/**
+ * Why `folder` may not hold this machine's checkouts, or null when it may.
+ * The answer is the sentence the console and the ticket show.
+ */
+export declare function checkoutFolderProblem(folder: string, deps: FolderCheckDeps): string | null;
+export interface EffectiveWorkspaces {
+    /** Where new checkouts go. */
+    base: string;
+    source: WorkspacesSource;
+    /** Why the remote folder is not the one in use, or null. */
+    refused: string | null;
+    minFreeGb: number;
+    /** Null: no cap. */
+    capGb: number | null;
+}
+/**
+ * What applies right now, from the three sources in order. Reads two small
+ * files; never asks the server and never checks a folder (the pull did that).
+ */
+export declare function effectiveWorkspaces(home?: string, env?: NodeJS.ProcessEnv): EffectiveWorkspaces;
+/**
+ * Remember that checkouts are being made under `base`, so a later change of
+ * folder does not hide them from the reaper. Idempotent; never throws.
+ */
+export declare function rememberWorkspacesBase(base: string, home?: string): void;
+/**
+ * Every folder checkouts may sit in: the current one first, then every one
+ * remembered, then the default. Only folders that exist are returned unless
+ * `existingOnly` is false.
+ */
+export declare function knownWorkspacesBases(home?: string, includeCurrent?: boolean): string[];
+export interface CheckoutsUsage {
+    usedGb: number;
+    /** How many checkouts that is, so a new one can be estimated. */
+    checkouts: number;
+    measuredAt: string;
+}
+/** Free GB on the drive that holds `dir` (or its nearest existing parent). */
+export declare function freeGbAt(dir: string): number | null;
+/**
+ * Bytes under `dir`, walking without following links (a carried
+ * `node_modules` link must not count its target, and a junction must not walk
+ * the user's repository). Yields to the event loop as it goes, so a daemon's
+ * heartbeat is never held by a big tree.
+ */
+export declare function bytesUnder(dir: string): Promise<number>;
+/**
+ * Measure every checkout under every known folder: `<base>/<project key>/<checkout>`.
+ * Junction/symlink entries are not followed (see `bytesUnder`).
+ */
+export declare function measureCheckouts(bases: readonly string[], now?: Date): Promise<CheckoutsUsage>;
+export declare function readCheckoutsUsage(home?: string): CheckoutsUsage | null;
+/**
+ * Measure again when the last measurement is older than `maxAgeMs`. Many
+ * daemons share this machine, so one claims the measurement and the others
+ * use what is there. Never throws.
+ */
+export declare function refreshCheckoutsUsage(home?: string, opts?: {
+    maxAgeMs?: number;
+    now?: () => number;
+    measure?: (bases: readonly string[]) => Promise<CheckoutsUsage>;
+}): Promise<CheckoutsUsage | null>;
+export interface RoomDeps {
+    freeGb?: (dir: string) => number | null;
+    /** Used GB right now; the cached measurement unless a caller measured. */
+    usage?: CheckoutsUsage | null;
+}
+/**
+ * Why no new checkout may be made under `root` right now, or null when one may.
+ * Minimum free space first (the drive), then the cap (Looply's share of it).
+ * The answer is a sentence a person can act on, because it is what the run and
+ * the ticket say.
+ */
+export declare function checkoutRoomProblem(root: string, eff: Pick<EffectiveWorkspaces, 'minFreeGb' | 'capGb'>, deps?: RoomDeps): string | null;
+/** What the heartbeat says about checkouts. Never throws: presence is worth more. */
+export declare function workspacesReport(home?: string, deps?: RoomDeps): WorkspacesReport | undefined;
+export interface MachineSettingsPullDeps {
+    /** `GET /v1/machine/settings`. */
+    fetch(): Promise<unknown>;
+    home?: string;
+    /** Served repositories and scanned folders, for the folder check. */
+    servedPaths(): readonly string[];
+    log(line: string): void;
+    now?(): number;
+    checkFolder?: (folder: string, deps: FolderCheckDeps) => string | null;
+    /** Measure checkout usage when it is stale; tests pass a no-op. */
+    refreshUsage?: () => Promise<unknown>;
+}
+export type MachineSettingsPullResult = 'updated' | 'unchanged' | 'failed';
+/**
+ * One pull: ask the server for this machine's settings, check a new folder on
+ * this machine, and write the cache. A failure keeps what the cache holds.
+ */
+export declare function makeMachineSettingsPull(deps: MachineSettingsPullDeps): () => Promise<MachineSettingsPullResult>;
+//# sourceMappingURL=machine-settings.d.ts.map

package/dist/machine-settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine-settings.d.ts","sourceRoot":"","sources":["../src/machine-settings.ts"],"names":[],"mappings":"AAYA,OAAO,EACL,mBAAmB,EAGnB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACtB,MAAM,cAAc,CAAC;AAItB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAE,mBAAmB,EAAE,CAAC;AAC/B,eAAO,MAAM,qBAAqB,0BAA0B,CAAC;AAC7D,eAAO,MAAM,4BAA4B,iCAAiC,CAAC;AAC3E,eAAO,MAAM,qBAAqB,0BAA0B,CAAC;AAC7D,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAC3D,eAAO,MAAM,cAAc,eAAe,CAAC;AAE3C,wEAAwE;AACxE,eAAO,MAAM,gBAAgB,QAAc,CAAC;AAQ5C,eAAO,MAAM,qBAAqB,GAAI,OAAM,MAAkB,KAAG,MAAgD,CAAC;AA6BlH,MAAM,WAAW,oBAAoB;IACnC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,GAAE,MAAkB,GAAG,oBAAoB,CAqCvF;AAID,oEAAoE;AACpE,MAAM,WAAW,aAAa;IAC5B,+BAA+B;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,OAAO,CAAC;IACZ,6CAA6C;IAC7C,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,EAAE,eAAe,CAAC;IAC1B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,sFAAsF;IACtF,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,wEAAwE;IACxE,OAAO,EAAE,aAAa,GAAG,IAAI,CAAC;CAC/B;AAED,wBAAgB,yBAAyB,CAAC,IAAI,GAAE,MAAkB,GAAG,0BAA0B,GAAG,IAAI,CA0BrG;AAED,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,0BAA0B,GAAG,IAAI,CAEhG;AAID,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,GAAG,KAAK,GAAG,SAAS,GAAG,SAAS,CAAC;AAEpG;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAAG,SAAS,CA0BnG;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,gFAAgF;IAChF,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,SAAS,CAAC;IACxC,uFAAuF;IACvF,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACxC;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAKpD;AAoCD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,MAAM,GAAG,IAAI,CA2C1F;AAID,MAAM,WAAW,mBAAmB;IAClC,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,gBAAgB,CAAC;IACzB,4DAA4D;IAC5D,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,oBAAoB;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,GAAE,MAAkB,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,mBAAmB,CAqCvH;AAID;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,MAAkB,GAAG,IAAI,CASnF;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,GAAE,MAAkB,EAAE,cAAc,UAAO,GAAG,MAAM,EAAE,CAsB9F;AAID,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,8EAA8E;AAC9E,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAYnD;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA0B7D;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,GAAE,IAAiB,GAAG,OAAO,CAAC,cAAc,CAAC,CA0BhH;AAED,wBAAgB,kBAAkB,CAAC,IAAI,GAAE,MAAkB,GAAG,cAAc,GAAG,IAAI,CAQlF;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CACzC,IAAI,GAAE,MAAkB,EACxB,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,KAAK,OAAO,CAAC,cAAc,CAAC,CAAA;CAAO,GACpH,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAiBhC;AAID,MAAM,WAAW,QAAQ;IACvB,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IACxC,0EAA0E;IAC1E,KAAK,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;CAC/B;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,IAAI,CAAC,mBAAmB,EAAE,WAAW,GAAG,OAAO,CAAC,EACrD,IAAI,GAAE,QAAa,GAClB,MAAM,GAAG,IAAI,CAyBf;AAED,qFAAqF;AACrF,wBAAgB,gBAAgB,CAAC,IAAI,GAAE,MAAkB,EAAE,IAAI,GAAE,QAAa,GAAG,gBAAgB,GAAG,SAAS,CAgC5G;AAID,MAAM,WAAW,uBAAuB;IACtC,kCAAkC;IAClC,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,WAAW,IAAI,SAAS,MAAM,EAAE,CAAC;IACjC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,GAAG,CAAC,IAAI,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,KAAK,MAAM,GAAG,IAAI,CAAC;IACvE,mEAAmE;IACnE,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CACvC;AAED,MAAM,MAAM,yBAAyB,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;AAE3E;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,uBAAuB,GAAG,MAAM,OAAO,CAAC,yBAAyB,CAAC,CA4F/G"}