@legioncodeinc/nectar 0.0.1

package/dist/service/platform.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Platform + scope resolution for nectar's OS service unit (PRD-003b).
+ *
+ * nectar registers itself with the OS so it survives its own crash and a reboot,
+ * mirroring doctor's own self-registration module
+ * (doctor/src/service/platform.ts:1-187) with nectar's own label/unit/task
+ * names and run command. WHICH service manager and at WHICH scope is decided here,
+ * once, from three injected facts (the platform, the home dir, and whether the
+ * process is privileged) so the rest of the service module is pure string + argv
+ * construction and fully hermetic in tests.
+ *
+ * The binding rulings (PRD-003b):
+ *   - macOS   -> launchd, user scope = LaunchAgent (`~/Library/LaunchAgents`).
+ *   - Linux   -> systemd, user scope = `systemctl --user` unit (`~/.config/systemd/user`).
+ *   - Windows -> Scheduled Task (per-user, no admin/UAC) is the default; a Windows
+ *               Service (`sc.exe`) is the enterprise opt-in, never the userland default.
+ *
+ * User scope is the default everywhere (US-003b.3): it needs no root/admin and matches
+ * a per-user `npm i -g`. A privileged context MAY use system scope, but an unprivileged
+ * context MUST fall back to user scope rather than failing the install.
+ *
+ * Built-ins only; this module is pure (its inputs are injected).
+ */
+/** The OS families nectar knows how to register a service on. */
+export type ServicePlatform = "darwin" | "linux" | "win32";
+/** Which service manager backs a plan. */
+export type ServiceManager = "launchd" | "systemd" | "schtasks" | "sc";
+/** The privilege scope a unit is installed at. */
+export type ServiceScope = "user" | "system";
+/**
+ * The stable label the launchd unit is registered under. Decision #32
+ * (2026-07-02, `library/requirements/PRD-DECISIONS-AND-DEFAULTS.md`): the
+ * fleet-wide scheme is reverse-DNS `com.legioncode.<shortname>` with the
+ * product short name `nectar`, superseding the shipped `com.hivenectar.daemon`.
+ */
+export declare const SERVICE_LABEL: "com.legioncode.nectar";
+/** The systemd unit file name (decision #32: `<shortname>.service`). */
+export declare const SYSTEMD_UNIT_NAME: "nectar.service";
+/** The Windows Scheduled Task / Service name (decision #32: the bare short name). */
+export declare const WINDOWS_TASK_NAME: "nectar";
+/** The pre-decision-#32 launchd label, deregistered on install (migration path). */
+export declare const LEGACY_SERVICE_LABEL: "com.hivenectar.daemon";
+/** The pre-decision-#32 systemd unit name, deregistered on install. */
+export declare const LEGACY_SYSTEMD_UNIT_NAME: "hivenectar.service";
+/** The pre-decision-#32 Windows task name, deregistered on install. */
+export declare const LEGACY_WINDOWS_TASK_NAME: "HivenectarDaemon";
+/** The raw facts the resolver consumes (injected so the resolver is hermetic). */
+export interface ServiceEnvironment {
+    /** `process.platform`. An unknown value is rejected by {@link resolveServicePlan}. */
+    readonly platform: NodeJS.Platform;
+    /** The user's home directory (where user-scope units are written). */
+    readonly home: string;
+    /** True iff the process can install a system-scoped unit (root on POSIX, admin on Windows). */
+    readonly privileged: boolean;
+    /** The absolute path to the `nectar` executable the unit will exec. */
+    readonly execPath: string;
+    /**
+     * Opt INTO system scope when privileged (enterprise path). Default false: even as root
+     * we prefer a user unit unless the operator explicitly asked for a system one.
+     */
+    readonly preferSystemScope?: boolean;
+}
+/** The fully-resolved plan: which manager, which scope, and the unit's on-disk location. */
+export interface ServicePlan {
+    /** The normalized platform family. */
+    readonly platform: ServicePlatform;
+    /** The backing service manager. */
+    readonly manager: ServiceManager;
+    /** The resolved install scope (user by default; system only when privileged + opted in). */
+    readonly scope: ServiceScope;
+    /** True when system scope was REQUESTED but the process is unprivileged, so we fell back to user. */
+    readonly fellBackToUser: boolean;
+    /** The absolute path the unit file is written to (plist / systemd unit). Empty for schtasks/sc. */
+    readonly unitPath: string;
+    /** The label/name the unit is registered under. */
+    readonly label: string;
+    /** The executable the unit execs. */
+    readonly execPath: string;
+    /** The home dir (units reference it for logs / working dir). */
+    readonly home: string;
+}
+/** Gather the real {@link ServiceEnvironment} at the edge (the one impure call site). */
+export declare function resolveServiceContext(execPath: string, preferSystemScope?: boolean): ServiceEnvironment;
+/**
+ * Detect whether the current process can install a system-scoped unit. On POSIX that is
+ * uid 0 (root); on Windows there is no cheap built-in admin check without shelling out,
+ * so we conservatively report NOT privileged and let the default per-user Scheduled Task
+ * path win. Never throws.
+ */
+export declare function isPrivileged(): boolean;
+/** Map a raw Node platform to a {@link ServicePlatform}, or null when unsupported. */
+export declare function normalizePlatform(platform: NodeJS.Platform): ServicePlatform | null;
+/**
+ * The on-disk unit path the PRE-decision-#32 install would have used for this
+ * plan's platform + scope. Install removes it (best-effort) so a re-run
+ * migrates a legacy unit instead of leaving two units racing over one daemon.
+ * Empty when the platform keeps no unit file (Windows).
+ */
+export declare function legacyUnitPath(plan: ServicePlan): string;
+/**
+ * Resolve the service plan from the environment. The fallback ordering (US-003b.3):
+ *   1. If system scope was requested AND the process is privileged -> system scope.
+ *   2. Otherwise -> user scope (LaunchAgent / systemd --user / per-user Scheduled Task),
+ *      recording `fellBackToUser` when a system unit was wanted but privilege was absent.
+ *
+ * Throws ONLY for a genuinely unsupported platform; the caller maps that to a clean
+ * "unsupported platform" result rather than a stack trace (US-003b.3).
+ */
+export declare function resolveServicePlan(env: ServiceEnvironment): ServicePlan;
+//# sourceMappingURL=platform.d.ts.map

package/dist/service/platform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.d.ts","sourceRoot":"","sources":["../../src/service/platform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,iEAAiE;AACjE,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC;AAE3D,0CAA0C;AAC1C,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,SAAS,GAAG,UAAU,GAAG,IAAI,CAAC;AAEvE,kDAAkD;AAClD,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE7C;;;;;GAKG;AACH,eAAO,MAAM,aAAa,EAAG,uBAAgC,CAAC;AAE9D,wEAAwE;AACxE,eAAO,MAAM,iBAAiB,EAAG,gBAAyB,CAAC;AAE3D,qFAAqF;AACrF,eAAO,MAAM,iBAAiB,EAAG,QAAiB,CAAC;AAEnD,oFAAoF;AACpF,eAAO,MAAM,oBAAoB,EAAG,uBAAgC,CAAC;AAErE,uEAAuE;AACvE,eAAO,MAAM,wBAAwB,EAAG,oBAA6B,CAAC;AAEtE,uEAAuE;AACvE,eAAO,MAAM,wBAAwB,EAAG,kBAA2B,CAAC;AAEpE,kFAAkF;AAClF,MAAM,WAAW,kBAAkB;IACjC,sFAAsF;IACtF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;IACnC,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+FAA+F;IAC/F,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;CACtC;AAED,4FAA4F;AAC5F,MAAM,WAAW,WAAW;IAC1B,sCAAsC;IACtC,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,mCAAmC;IACnC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,4FAA4F;IAC5F,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,qGAAqG;IACrG,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,mGAAmG;IACnG,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,mDAAmD;IACnD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qCAAqC;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,gEAAgE;IAChE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,yFAAyF;AACzF,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,iBAAiB,UAAQ,GAAG,kBAAkB,CAQrG;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,IAAI,OAAO,CAQtC;AAED,sFAAsF;AACtF,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,CAAC,QAAQ,GAAG,eAAe,GAAG,IAAI,CAGnF;AA4BD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CAaxD;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,kBAAkB,GAAG,WAAW,CAiCvE"}

package/dist/service/platform.js

@@ -0,0 +1,157 @@
+/**
+ * Platform + scope resolution for nectar's OS service unit (PRD-003b).
+ *
+ * nectar registers itself with the OS so it survives its own crash and a reboot,
+ * mirroring doctor's own self-registration module
+ * (doctor/src/service/platform.ts:1-187) with nectar's own label/unit/task
+ * names and run command. WHICH service manager and at WHICH scope is decided here,
+ * once, from three injected facts (the platform, the home dir, and whether the
+ * process is privileged) so the rest of the service module is pure string + argv
+ * construction and fully hermetic in tests.
+ *
+ * The binding rulings (PRD-003b):
+ *   - macOS   -> launchd, user scope = LaunchAgent (`~/Library/LaunchAgents`).
+ *   - Linux   -> systemd, user scope = `systemctl --user` unit (`~/.config/systemd/user`).
+ *   - Windows -> Scheduled Task (per-user, no admin/UAC) is the default; a Windows
+ *               Service (`sc.exe`) is the enterprise opt-in, never the userland default.
+ *
+ * User scope is the default everywhere (US-003b.3): it needs no root/admin and matches
+ * a per-user `npm i -g`. A privileged context MAY use system scope, but an unprivileged
+ * context MUST fall back to user scope rather than failing the install.
+ *
+ * Built-ins only; this module is pure (its inputs are injected).
+ */
+import { homedir, userInfo } from "node:os";
+/**
+ * The stable label the launchd unit is registered under. Decision #32
+ * (2026-07-02, `library/requirements/PRD-DECISIONS-AND-DEFAULTS.md`): the
+ * fleet-wide scheme is reverse-DNS `com.legioncode.<shortname>` with the
+ * product short name `nectar`, superseding the shipped `com.hivenectar.daemon`.
+ */
+export const SERVICE_LABEL = "com.legioncode.nectar";
+/** The systemd unit file name (decision #32: `<shortname>.service`). */
+export const SYSTEMD_UNIT_NAME = "nectar.service";
+/** The Windows Scheduled Task / Service name (decision #32: the bare short name). */
+export const WINDOWS_TASK_NAME = "nectar";
+/** The pre-decision-#32 launchd label, deregistered on install (migration path). */
+export const LEGACY_SERVICE_LABEL = "com.hivenectar.daemon";
+/** The pre-decision-#32 systemd unit name, deregistered on install. */
+export const LEGACY_SYSTEMD_UNIT_NAME = "hivenectar.service";
+/** The pre-decision-#32 Windows task name, deregistered on install. */
+export const LEGACY_WINDOWS_TASK_NAME = "HivenectarDaemon";
+/** Gather the real {@link ServiceEnvironment} at the edge (the one impure call site). */
+export function resolveServiceContext(execPath, preferSystemScope = false) {
+    return {
+        platform: process.platform,
+        home: homedir(),
+        privileged: isPrivileged(),
+        execPath,
+        preferSystemScope,
+    };
+}
+/**
+ * Detect whether the current process can install a system-scoped unit. On POSIX that is
+ * uid 0 (root); on Windows there is no cheap built-in admin check without shelling out,
+ * so we conservatively report NOT privileged and let the default per-user Scheduled Task
+ * path win. Never throws.
+ */
+export function isPrivileged() {
+    try {
+        if (process.platform === "win32")
+            return false;
+        const uid = userInfo().uid;
+        return uid === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** Map a raw Node platform to a {@link ServicePlatform}, or null when unsupported. */
+export function normalizePlatform(platform) {
+    if (platform === "darwin" || platform === "linux" || platform === "win32")
+        return platform;
+    return null;
+}
+/** Build the user-scope unit path for a given platform (where we WRITE the plist/unit file). */
+function userUnitPath(platform, home) {
+    switch (platform) {
+        case "darwin":
+            return `${home}/Library/LaunchAgents/${SERVICE_LABEL}.plist`;
+        case "linux":
+            return `${home}/.config/systemd/user/${SYSTEMD_UNIT_NAME}`;
+        case "win32":
+            // Scheduled Task is registered via schtasks (no file we own on disk).
+            return "";
+    }
+}
+/** Build the system-scope unit path for a given platform. */
+function systemUnitPath(platform) {
+    switch (platform) {
+        case "darwin":
+            return `/Library/LaunchDaemons/${SERVICE_LABEL}.plist`;
+        case "linux":
+            return `/etc/systemd/system/${SYSTEMD_UNIT_NAME}`;
+        case "win32":
+            // Windows Service is registered via sc.exe (no unit file we own on disk).
+            return "";
+    }
+}
+/**
+ * The on-disk unit path the PRE-decision-#32 install would have used for this
+ * plan's platform + scope. Install removes it (best-effort) so a re-run
+ * migrates a legacy unit instead of leaving two units racing over one daemon.
+ * Empty when the platform keeps no unit file (Windows).
+ */
+export function legacyUnitPath(plan) {
+    switch (plan.platform) {
+        case "darwin":
+            return plan.scope === "system"
+                ? `/Library/LaunchDaemons/${LEGACY_SERVICE_LABEL}.plist`
+                : `${plan.home}/Library/LaunchAgents/${LEGACY_SERVICE_LABEL}.plist`;
+        case "linux":
+            return plan.scope === "system"
+                ? `/etc/systemd/system/${LEGACY_SYSTEMD_UNIT_NAME}`
+                : `${plan.home}/.config/systemd/user/${LEGACY_SYSTEMD_UNIT_NAME}`;
+        case "win32":
+            return "";
+    }
+}
+/**
+ * Resolve the service plan from the environment. The fallback ordering (US-003b.3):
+ *   1. If system scope was requested AND the process is privileged -> system scope.
+ *   2. Otherwise -> user scope (LaunchAgent / systemd --user / per-user Scheduled Task),
+ *      recording `fellBackToUser` when a system unit was wanted but privilege was absent.
+ *
+ * Throws ONLY for a genuinely unsupported platform; the caller maps that to a clean
+ * "unsupported platform" result rather than a stack trace (US-003b.3).
+ */
+export function resolveServicePlan(env) {
+    const platform = normalizePlatform(env.platform);
+    if (platform === null) {
+        throw new Error(`unsupported platform: ${env.platform}`);
+    }
+    const wantsSystem = env.preferSystemScope === true;
+    const canSystem = env.privileged;
+    const scope = wantsSystem && canSystem ? "system" : "user";
+    const fellBackToUser = wantsSystem && !canSystem;
+    const manager = platform === "darwin"
+        ? "launchd"
+        : platform === "linux"
+            ? "systemd"
+            : // Windows: per-user Scheduled Task by default; Windows Service (sc) only at system scope.
+                scope === "system"
+                    ? "sc"
+                    : "schtasks";
+    const unitPath = scope === "system" ? systemUnitPath(platform) : userUnitPath(platform, env.home);
+    return {
+        platform,
+        manager,
+        scope,
+        fellBackToUser,
+        unitPath,
+        label: SERVICE_LABEL,
+        execPath: env.execPath,
+        home: env.home,
+    };
+}
+//# sourceMappingURL=platform.js.map

package/dist/service/platform.js.map

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

package/dist/service/templates.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The vendored per-OS service-unit TEMPLATES for nectar (PRD-003b).
+ *
+ * Mirrors doctor's own unit templates (doctor/src/service/templates.ts)
+ * with nectar's run command (`daemon`, not `run`) and nectar's label/unit
+ * names (src/service/platform.ts). Three pure string builders, one per service
+ * manager, that render the unit text from a {@link ServicePlan}. No I/O, no
+ * shell-out - just deterministic text a test can snapshot-assert.
+ *
+ * Every template encodes the two non-negotiables of self-supervision (PRD-003b
+ * Goals):
+ *   - restart-on-crash  (launchd `KeepAlive`, systemd `Restart=always`, schtasks
+ *                        `RestartOnFailure`);
+ *   - start-on-boot     (launchd `RunAtLoad`, systemd `WantedBy=default.target`,
+ *                        schtasks `LogonTrigger`).
+ *
+ * Built-ins only; XML/plist are hand-built with the few entities they need escaped.
+ */
+import { SERVICE_LABEL, type ServicePlan } from "./platform.js";
+/** The subcommand nectar's unit execs to start the process (no shell). */
+export declare const NECTAR_RUN_COMMAND: "daemon";
+/**
+ * The directory the launchd unit writes stdout/stderr logs into
+ * (`<home>/.honeycomb/nectar`). Single-sourced here so the install path
+ * (`service/index.ts`) creates exactly the directory the plist references,
+ * rather than the daemon silently losing its logs on macOS (NEC-042 item 2 /
+ * AC-018l.9). Forward slashes match the plist's own path style.
+ */
+export declare function launchdLogDir(home: string): string;
+/**
+ * Seconds the OS waits before restarting a crashed nectar on POSIX. Used by the
+ * launchd `ThrottleInterval` and the systemd `RestartSec` directives; both take
+ * seconds. Mirrors doctor's `RESTART_SEC` (doctor/src/service/templates.ts).
+ */
+export declare const RESTART_SEC: 5;
+/**
+ * The Windows Task Scheduler `RestartOnFailure`/`Interval` duration as an ISO-8601
+ * time interval. Task Scheduler REJECTS sub-minute intervals; the minimum it accepts
+ * is `PT1M`. This is Windows-only; POSIX keeps `RESTART_SEC` (seconds). Mirrors
+ * doctor's `WINDOWS_RESTART_INTERVAL`.
+ */
+export declare const WINDOWS_RESTART_INTERVAL: "PT1M";
+/**
+ * systemd restart rate-limiting window (seconds) and burst count (daemon-api
+ * review H4). The old template disabled rate limiting (`StartLimitIntervalSec=0`),
+ * so a genuinely broken unit crash-looped every {@link RESTART_SEC} seconds
+ * forever. A finite burst over a finite window makes systemd give up and surface
+ * a failed state instead of burning CPU and journal space indefinitely.
+ */
+export declare const START_LIMIT_INTERVAL_SEC: 60;
+export declare const START_LIMIT_BURST: 5;
+/**
+ * Quote a single token for a systemd `ExecStart` line. systemd does NOT invoke a
+ * shell, but a bare token splits on whitespace, so a space-bearing exec path would
+ * mis-split. Wrapping the token in double quotes preserves the spaces.
+ */
+export declare function quoteSystemdToken(value: string): string;
+/** Escape the five XML predefined entities so an exec path with `&`/quotes cannot break the doc. */
+export declare function escapeXml(value: string): string;
+/**
+ * Render a launchd plist (macOS). `RunAtLoad` = start-on-boot/login; `KeepAlive` =
+ * restart-on-crash. `ProgramArguments` is an argv array (no shell), so a path with
+ * spaces is safe. Logs go under the user's home so a LaunchAgent never needs root.
+ */
+export declare function renderLaunchdPlist(plan: ServicePlan): string;
+/**
+ * Render a systemd unit (Linux). `Restart=always` + `RestartSec` = restart-on-crash;
+ * `WantedBy=default.target` (with `systemctl --user enable`) = start-on-login/boot.
+ * `Type=simple` because nectar stays in the foreground of its own process.
+ */
+export declare function renderSystemdUnit(plan: ServicePlan): string;
+/**
+ * Render a Windows Scheduled Task definition XML (per-user, the Windows DEFAULT).
+ * The `LogonTrigger` starts it at user logon (start-on-boot equivalent without
+ * admin); `RestartOnFailure` gives restart-on-crash; `MultipleInstancesPolicy=IgnoreNew`
+ * keeps a single instance (pairs with nectar's single-instance lock, PRD-003a).
+ * `<Command>`/`<Arguments>` are separate (no shell parsing).
+ *
+ * Consumed via `schtasks /Create /XML <file>`, so the per-user task needs no admin/UAC.
+ * Uses {@link WINDOWS_RESTART_INTERVAL} (`PT1M`), NOT {@link RESTART_SEC}: Task
+ * Scheduler rejects sub-minute intervals.
+ */
+export declare function renderScheduledTaskXml(plan: ServicePlan): string;
+/** The single entry point: render whichever unit text the plan's manager needs. */
+export declare function renderUnit(plan: ServicePlan): string;
+/** Re-export the label so callers building argv share one source of truth. */
+export { SERVICE_LABEL };
+//# sourceMappingURL=templates.d.ts.map

package/dist/service/templates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../src/service/templates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,aAAa,EAAqB,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAEnF,0EAA0E;AAC1E,eAAO,MAAM,kBAAkB,EAAG,QAAiB,CAAC;AAEpD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW,EAAG,CAAU,CAAC;AAEtC;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,EAAG,MAAe,CAAC;AAExD;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,EAAG,EAAW,CAAC;AACpD,eAAO,MAAM,iBAAiB,EAAG,CAAU,CAAC;AAE5C;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,oGAAoG;AACpG,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAO/C;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CAgC5D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CAyB3D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CA2ChE;AAED,mFAAmF;AACnF,wBAAgB,UAAU,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CAapD;AAED,8EAA8E;AAC9E,OAAO,EAAE,aAAa,EAAE,CAAC"}

package/dist/service/templates.js

@@ -0,0 +1,212 @@
+/**
+ * The vendored per-OS service-unit TEMPLATES for nectar (PRD-003b).
+ *
+ * Mirrors doctor's own unit templates (doctor/src/service/templates.ts)
+ * with nectar's run command (`daemon`, not `run`) and nectar's label/unit
+ * names (src/service/platform.ts). Three pure string builders, one per service
+ * manager, that render the unit text from a {@link ServicePlan}. No I/O, no
+ * shell-out - just deterministic text a test can snapshot-assert.
+ *
+ * Every template encodes the two non-negotiables of self-supervision (PRD-003b
+ * Goals):
+ *   - restart-on-crash  (launchd `KeepAlive`, systemd `Restart=always`, schtasks
+ *                        `RestartOnFailure`);
+ *   - start-on-boot     (launchd `RunAtLoad`, systemd `WantedBy=default.target`,
+ *                        schtasks `LogonTrigger`).
+ *
+ * Built-ins only; XML/plist are hand-built with the few entities they need escaped.
+ */
+import { SERVICE_LABEL, WINDOWS_TASK_NAME } from "./platform.js";
+/** The subcommand nectar's unit execs to start the process (no shell). */
+export const NECTAR_RUN_COMMAND = "daemon";
+/**
+ * The directory the launchd unit writes stdout/stderr logs into
+ * (`<home>/.honeycomb/nectar`). Single-sourced here so the install path
+ * (`service/index.ts`) creates exactly the directory the plist references,
+ * rather than the daemon silently losing its logs on macOS (NEC-042 item 2 /
+ * AC-018l.9). Forward slashes match the plist's own path style.
+ */
+export function launchdLogDir(home) {
+    return `${home}/.honeycomb/nectar`;
+}
+/**
+ * Seconds the OS waits before restarting a crashed nectar on POSIX. Used by the
+ * launchd `ThrottleInterval` and the systemd `RestartSec` directives; both take
+ * seconds. Mirrors doctor's `RESTART_SEC` (doctor/src/service/templates.ts).
+ */
+export const RESTART_SEC = 5;
+/**
+ * The Windows Task Scheduler `RestartOnFailure`/`Interval` duration as an ISO-8601
+ * time interval. Task Scheduler REJECTS sub-minute intervals; the minimum it accepts
+ * is `PT1M`. This is Windows-only; POSIX keeps `RESTART_SEC` (seconds). Mirrors
+ * doctor's `WINDOWS_RESTART_INTERVAL`.
+ */
+export const WINDOWS_RESTART_INTERVAL = "PT1M";
+/**
+ * systemd restart rate-limiting window (seconds) and burst count (daemon-api
+ * review H4). The old template disabled rate limiting (`StartLimitIntervalSec=0`),
+ * so a genuinely broken unit crash-looped every {@link RESTART_SEC} seconds
+ * forever. A finite burst over a finite window makes systemd give up and surface
+ * a failed state instead of burning CPU and journal space indefinitely.
+ */
+export const START_LIMIT_INTERVAL_SEC = 60;
+export const START_LIMIT_BURST = 5;
+/**
+ * Quote a single token for a systemd `ExecStart` line. systemd does NOT invoke a
+ * shell, but a bare token splits on whitespace, so a space-bearing exec path would
+ * mis-split. Wrapping the token in double quotes preserves the spaces.
+ */
+export function quoteSystemdToken(value) {
+    return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+}
+/** Escape the five XML predefined entities so an exec path with `&`/quotes cannot break the doc. */
+export function escapeXml(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&apos;");
+}
+/**
+ * Render a launchd plist (macOS). `RunAtLoad` = start-on-boot/login; `KeepAlive` =
+ * restart-on-crash. `ProgramArguments` is an argv array (no shell), so a path with
+ * spaces is safe. Logs go under the user's home so a LaunchAgent never needs root.
+ */
+export function renderLaunchdPlist(plan) {
+    const node = escapeXml(process.execPath);
+    const exec = escapeXml(plan.execPath);
+    const logDir = escapeXml(launchdLogDir(plan.home));
+    const label = escapeXml(plan.label);
+    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>${label}</string>
+	<key>ProgramArguments</key>
+	<array>
+		<string>${node}</string>
+		<string>${exec}</string>
+		<string>${NECTAR_RUN_COMMAND}</string>
+	</array>
+	<key>RunAtLoad</key>
+	<true/>
+	<key>KeepAlive</key>
+	<true/>
+	<key>ThrottleInterval</key>
+	<integer>${RESTART_SEC}</integer>
+	<key>ProcessType</key>
+	<string>Background</string>
+	<key>StandardOutPath</key>
+	<string>${logDir}/launchd.out.log</string>
+	<key>StandardErrorPath</key>
+	<string>${logDir}/launchd.err.log</string>
+</dict>
+</plist>
+`;
+}
+/**
+ * Render a systemd unit (Linux). `Restart=always` + `RestartSec` = restart-on-crash;
+ * `WantedBy=default.target` (with `systemctl --user enable`) = start-on-login/boot.
+ * `Type=simple` because nectar stays in the foreground of its own process.
+ */
+export function renderSystemdUnit(plan) {
+    // Prefix `process.execPath` (the node interpreter) exactly as the launchd and
+    // Scheduled Task templates do (daemon-api review H4): execing the CLI entry
+    // directly relied on `node` being on the systemd user manager's PATH, which it
+    // is not on an nvm/fnm/volta install, producing an infinite crash loop. Both
+    // tokens are quoted so a space-bearing path cannot mis-split into two argv
+    // tokens; the run subcommand is a fixed literal with no spaces.
+    const node = quoteSystemdToken(process.execPath);
+    const exec = quoteSystemdToken(plan.execPath);
+    return `[Unit]
+Description=nectar - semantic memory layer daemon
+Documentation=https://get.theapiary.sh
+After=network.target
+StartLimitIntervalSec=${START_LIMIT_INTERVAL_SEC}
+StartLimitBurst=${START_LIMIT_BURST}
+
+[Service]
+Type=simple
+ExecStart=${node} ${exec} ${NECTAR_RUN_COMMAND}
+Restart=always
+RestartSec=${RESTART_SEC}
+
+[Install]
+WantedBy=default.target
+`;
+}
+/**
+ * Render a Windows Scheduled Task definition XML (per-user, the Windows DEFAULT).
+ * The `LogonTrigger` starts it at user logon (start-on-boot equivalent without
+ * admin); `RestartOnFailure` gives restart-on-crash; `MultipleInstancesPolicy=IgnoreNew`
+ * keeps a single instance (pairs with nectar's single-instance lock, PRD-003a).
+ * `<Command>`/`<Arguments>` are separate (no shell parsing).
+ *
+ * Consumed via `schtasks /Create /XML <file>`, so the per-user task needs no admin/UAC.
+ * Uses {@link WINDOWS_RESTART_INTERVAL} (`PT1M`), NOT {@link RESTART_SEC}: Task
+ * Scheduler rejects sub-minute intervals.
+ */
+export function renderScheduledTaskXml(plan) {
+    const node = escapeXml(process.execPath);
+    const exec = escapeXml(plan.execPath);
+    return `<?xml version="1.0" encoding="UTF-16"?>
+<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo>
+    <Description>nectar - semantic memory layer daemon</Description>
+    <URI>\\${escapeXml(WINDOWS_TASK_NAME)}</URI>
+  </RegistrationInfo>
+  <Triggers>
+    <LogonTrigger>
+      <Enabled>true</Enabled>
+    </LogonTrigger>
+  </Triggers>
+  <Principals>
+    <Principal id="Author">
+      <LogonType>InteractiveToken</LogonType>
+      <RunLevel>LeastPrivilege</RunLevel>
+    </Principal>
+  </Principals>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <AllowHardTerminate>true</AllowHardTerminate>
+    <StartWhenAvailable>true</StartWhenAvailable>
+    <RunOnlyIfNetworkAvailable>false</RunOnlyIfNetworkAvailable>
+    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>
+    <Enabled>true</Enabled>
+    <Hidden>false</Hidden>
+    <RestartOnFailure>
+      <Interval>${WINDOWS_RESTART_INTERVAL}</Interval>
+      <Count>999</Count>
+    </RestartOnFailure>
+  </Settings>
+  <Actions Context="Author">
+    <Exec>
+      <Command>${node}</Command>
+      <Arguments>"${exec}" ${NECTAR_RUN_COMMAND}</Arguments>
+    </Exec>
+  </Actions>
+</Task>
+`;
+}
+/** The single entry point: render whichever unit text the plan's manager needs. */
+export function renderUnit(plan) {
+    switch (plan.manager) {
+        case "launchd":
+            return renderLaunchdPlist(plan);
+        case "systemd":
+            return renderSystemdUnit(plan);
+        case "schtasks":
+        case "sc":
+            // Both Windows backends consume the same Scheduled-Task XML when file-based; sc.exe
+            // (system service) is created via argv (see argv.ts) and does not use this template,
+            // but a single renderer keeps the XML available for the schtasks path.
+            return renderScheduledTaskXml(plan);
+    }
+}
+/** Re-export the label so callers building argv share one source of truth. */
+export { SERVICE_LABEL };
+//# sourceMappingURL=templates.js.map

package/dist/service/templates.js.map

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

package/dist/source-graph/deeplake-credentials.d.ts

@@ -0,0 +1,57 @@
+/** The SHARED credentials directory name under the user's home. */
+export declare const CREDENTIALS_DIR_NAME = ".deeplake";
+/** The credentials file name within the dir. */
+export declare const CREDENTIALS_FILE_NAME = "credentials.json";
+/** The canonical Deep Lake API base URL used when a file omits `apiUrl`. */
+export declare const DEFAULT_DEEPLAKE_API_URL = "https://api.deeplake.ai";
+/** The validated Deep Lake connection details the transport is built from. */
+export interface DeepLakeCredentials {
+    /** Deep Lake HTTP query endpoint. Defaults to {@link DEFAULT_DEEPLAKE_API_URL}. */
+    readonly apiUrl: string;
+    /** The org-bound bearer token (SECRET; never logged in full). */
+    readonly token: string;
+    /** The org id the token is bound to. */
+    readonly orgId: string;
+    /** The active workspace id. */
+    readonly workspaceId: string;
+}
+/**
+ * Options for {@link loadDeepLakeCredentials}, injectable so a test points the
+ * file read at a temp dir without touching the real `~/.deeplake` (mirrors
+ * honeycomb's `CredentialsFileProviderOptions`). All optional.
+ */
+export interface LoadCredentialsOptions {
+    /** Override the credentials directory (tests). Defaults to `~/.deeplake`. */
+    readonly dir?: string;
+}
+/**
+ * Structured, fail-closed rejection. Carries exactly which fields were missing
+ * or invalid so a caller (or an operator reading a log line) knows what to
+ * fix without the loader ever echoing the file's contents (which may hold the
+ * token).
+ */
+export declare class DeepLakeCredentialsError extends Error {
+    readonly missing: readonly string[];
+    constructor(missing: readonly string[]);
+}
+/** Resolve the credentials directory, honoring the test override. */
+export declare function credentialsDir(options?: LoadCredentialsOptions): string;
+/** Resolve the full credentials file path within the (possibly overridden) dir. */
+export declare function credentialsPath(options?: LoadCredentialsOptions): string;
+/**
+ * Load and validate `~/.deeplake/credentials.json` (or the overridden dir in
+ * `options.dir`). Throws {@link DeepLakeCredentialsError} listing every
+ * problem found: a missing file, invalid JSON, a non-object payload, or a
+ * missing/empty `token` / `orgId` / `workspaceId`. Never returns a partial
+ * credential — the caller either gets a fully-populated `DeepLakeCredentials`
+ * or a clear, typed reason it could not.
+ */
+export declare function loadDeepLakeCredentials(options?: LoadCredentialsOptions): DeepLakeCredentials;
+/**
+ * Redact a token for logs and errors. Never echoes a token in full: keeps the
+ * last 4 chars for correlation, masks the rest. An empty/short value collapses
+ * to a fixed mask so length isn't leaked either. Mirrors honeycomb's
+ * `redactToken` (`src/daemon/runtime/auth/credentials-store.ts:254-257`).
+ */
+export declare function redactToken(value: string): string;
+//# sourceMappingURL=deeplake-credentials.d.ts.map

package/dist/source-graph/deeplake-credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deeplake-credentials.d.ts","sourceRoot":"","sources":["../../src/source-graph/deeplake-credentials.ts"],"names":[],"mappings":"AA4BA,mEAAmE;AACnE,eAAO,MAAM,oBAAoB,cAAc,CAAC;AAChD,gDAAgD;AAChD,eAAO,MAAM,qBAAqB,qBAAqB,CAAC;AACxD,4EAA4E;AAC5E,eAAO,MAAM,wBAAwB,4BAA4B,CAAC;AAElE,8EAA8E;AAC9E,MAAM,WAAW,mBAAmB;IAClC,mFAAmF;IACnF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iEAAiE;IACjE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,wCAAwC;IACxC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,+BAA+B;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,6EAA6E;IAC7E,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;gBACxB,OAAO,EAAE,SAAS,MAAM,EAAE;CAKvC;AAED,qEAAqE;AACrE,wBAAgB,cAAc,CAAC,OAAO,GAAE,sBAA2B,GAAG,MAAM,CAE3E;AAED,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,MAAM,CAE5E;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,GAAE,sBAA2B,GAAG,mBAAmB,CAkCjG;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGjD"}