signalk-container-helper 0.1.0

package/dist/util.d.ts

@@ -0,0 +1,36 @@
+import type { AppLike } from "./types.js";
+/**
+ * Allowed characters for an image tag before it is passed anywhere near the
+ * container runtime. Same guard as the reference plugins (SAFE_TAG).
+ */
+export declare const IMAGE_TAG_PATTERN: RegExp;
+export declare function isValidImageTag(tag: unknown): tag is string;
+/** Normalize an unknown thrown value into a printable message. */
+export declare function errMsg(err: unknown): string;
+export declare function sleep(ms: number): Promise<void>;
+export type ContainerHelperErrorCode = "manager-unavailable" | "no-runtime" | "invalid-tag" | "address-unresolved" | "not-ready" | "recreate-limbo";
+/**
+ * Typed error thrown by ManagedContainer/AdoptedContainer operations.
+ * `reported` is true when the helper already surfaced the message via
+ * `app.setPluginError` — `startSafely` uses it to avoid double-reporting.
+ */
+export declare class ContainerHelperError extends Error {
+    readonly code: ContainerHelperErrorCode;
+    reported: boolean;
+    constructor(code: ContainerHelperErrorCode, message: string, reported?: boolean);
+}
+/**
+ * Signal K calls `plugin.start()` synchronously and ignores a returned
+ * promise — an async `start` that rejects becomes an unhandled rejection with
+ * no plugin error surfaced. Wrap the async body with this from a synchronous
+ * `start()`:
+ *
+ *   start(config) {
+ *     startSafely(app, () => asyncStart(config))
+ *   }
+ *
+ * Errors already reported by the helpers (ContainerHelperError.reported) are
+ * not re-reported; everything else lands in `setPluginError`.
+ */
+export declare function startSafely(app: AppLike, fn: () => Promise<unknown>): void;
+//# sourceMappingURL=util.d.ts.map

package/dist/util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.d.ts","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C;;;GAGG;AACH,eAAO,MAAM,iBAAiB,QAAsB,CAAC;AAErD,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,MAAM,CAO3D;AAED,kEAAkE;AAClE,wBAAgB,MAAM,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAE3C;AAED,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AAED,MAAM,MAAM,wBAAwB,GAChC,qBAAqB,GACrB,YAAY,GACZ,aAAa,GACb,oBAAoB,GACpB,WAAW,GACX,gBAAgB,CAAC;AAErB;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAC;IACxC,QAAQ,EAAE,OAAO,CAAC;gBAGhB,IAAI,EAAE,wBAAwB,EAC9B,OAAO,EAAE,MAAM,EACf,QAAQ,UAAQ;CAOnB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAQ1E"}

package/dist/util.js

@@ -0,0 +1,56 @@
+/**
+ * Allowed characters for an image tag before it is passed anywhere near the
+ * container runtime. Same guard as the reference plugins (SAFE_TAG).
+ */
+export const IMAGE_TAG_PATTERN = /^[a-zA-Z0-9._-]+$/;
+export function isValidImageTag(tag) {
+    return (typeof tag === "string" &&
+        tag.length > 0 &&
+        tag.length <= 128 &&
+        IMAGE_TAG_PATTERN.test(tag));
+}
+/** Normalize an unknown thrown value into a printable message. */
+export function errMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Typed error thrown by ManagedContainer/AdoptedContainer operations.
+ * `reported` is true when the helper already surfaced the message via
+ * `app.setPluginError` — `startSafely` uses it to avoid double-reporting.
+ */
+export class ContainerHelperError extends Error {
+    code;
+    reported;
+    constructor(code, message, reported = false) {
+        super(message);
+        this.name = "ContainerHelperError";
+        this.code = code;
+        this.reported = reported;
+    }
+}
+/**
+ * Signal K calls `plugin.start()` synchronously and ignores a returned
+ * promise — an async `start` that rejects becomes an unhandled rejection with
+ * no plugin error surfaced. Wrap the async body with this from a synchronous
+ * `start()`:
+ *
+ *   start(config) {
+ *     startSafely(app, () => asyncStart(config))
+ *   }
+ *
+ * Errors already reported by the helpers (ContainerHelperError.reported) are
+ * not re-reported; everything else lands in `setPluginError`.
+ */
+export function startSafely(app, fn) {
+    fn().catch((err) => {
+        if (err instanceof ContainerHelperError && err.reported) {
+            app.debug(`startup aborted: ${err.message}`);
+            return;
+        }
+        app.setPluginError(`Startup failed: ${errMsg(err)}`);
+    });
+}
+//# sourceMappingURL=util.js.map

package/dist/util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.js","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,mBAAmB,CAAC;AAErD,MAAM,UAAU,eAAe,CAAC,GAAY;IAC1C,OAAO,CACL,OAAO,GAAG,KAAK,QAAQ;QACvB,GAAG,CAAC,MAAM,GAAG,CAAC;QACd,GAAG,CAAC,MAAM,IAAI,GAAG;QACjB,iBAAiB,CAAC,IAAI,CAAC,GAAG,CAAC,CAC5B,CAAC;AACJ,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,MAAM,CAAC,GAAY;IACjC,OAAO,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,EAAU;IAC9B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC;AAUD;;;;GAIG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IACpC,IAAI,CAA2B;IACxC,QAAQ,CAAU;IAElB,YACE,IAA8B,EAC9B,OAAe,EACf,QAAQ,GAAG,KAAK;QAEhB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,WAAW,CAAC,GAAY,EAAE,EAA0B;IAClE,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;QAC1B,IAAI,GAAG,YAAY,oBAAoB,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC;YACxD,GAAG,CAAC,KAAK,CAAC,oBAAoB,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;YAC7C,OAAO;QACT,CAAC;QACD,GAAG,CAAC,cAAc,CAAC,mBAAmB,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACvD,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/version-source.d.ts

@@ -0,0 +1,23 @@
+import type { UpdateServiceApi, VersionSource } from "./types.js";
+/**
+ * Declarative version-source description, resolved against
+ * `manager.updates.sources` at registration time so callers don't need the
+ * manager in hand while declaring their options.
+ */
+export type VersionSourceSpec = {
+    /** GitHub repo, e.g. "questdb/questdb". */
+    githubReleases: string;
+    allowPrerelease?: boolean;
+    tagPrefix?: string;
+    /** Personal access token — lifts the 60/hr anonymous rate limit. */
+    token?: string;
+} | {
+    /** Docker Hub image, e.g. "questdb/questdb". */
+    dockerHubTags: string;
+    filter?: (tag: string) => boolean;
+} | {
+    /** Bring your own VersionSource implementation. */
+    custom: VersionSource;
+};
+export declare function buildVersionSource(updates: UpdateServiceApi, spec: VersionSourceSpec): VersionSource;
+//# sourceMappingURL=version-source.d.ts.map

package/dist/version-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-source.d.ts","sourceRoot":"","sources":["../src/version-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAElE;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GACzB;IACE,2CAA2C;IAC3C,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GACD;IACE,gDAAgD;IAChD,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;CACnC,GACD;IACE,mDAAmD;IACnD,MAAM,EAAE,aAAa,CAAC;CACvB,CAAC;AAEN,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,gBAAgB,EACzB,IAAI,EAAE,iBAAiB,GACtB,aAAa,CAUf"}

package/dist/version-source.js

@@ -0,0 +1,12 @@
+export function buildVersionSource(updates, spec) {
+    if ("custom" in spec) {
+        return spec.custom;
+    }
+    if ("githubReleases" in spec) {
+        const { githubReleases, ...options } = spec;
+        return updates.sources.githubReleases(githubReleases, options);
+    }
+    const { dockerHubTags, ...options } = spec;
+    return updates.sources.dockerHubTags(dockerHubTags, options);
+}
+//# sourceMappingURL=version-source.js.map

package/dist/version-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-source.js","sourceRoot":"","sources":["../src/version-source.ts"],"names":[],"mappings":"AA0BA,MAAM,UAAU,kBAAkB,CAChC,OAAyB,EACzB,IAAuB;IAEvB,IAAI,QAAQ,IAAI,IAAI,EAAE,CAAC;QACrB,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IACD,IAAI,gBAAgB,IAAI,IAAI,EAAE,CAAC;QAC7B,MAAM,EAAE,cAAc,EAAE,GAAG,OAAO,EAAE,GAAG,IAAI,CAAC;QAC5C,OAAO,OAAO,CAAC,OAAO,CAAC,cAAc,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;IACjE,CAAC;IACD,MAAM,EAAE,aAAa,EAAE,GAAG,OAAO,EAAE,GAAG,IAAI,CAAC;IAC3C,OAAO,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;AAC/D,CAAC"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "signalk-container-helper",
+  "version": "0.1.0",
+  "description": "Helper library for Signal K plugins that manage containers via the signalk-container plugin",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "SPEC.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run typecheck:test && vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "typecheck:test": "tsc --noEmit --project tsconfig.test.json",
+    "prettier": "prettier --write .",
+    "lint": "eslint --fix",
+    "format": "npm run prettier && npm run lint",
+    "ci-lint": "eslint && prettier --check .",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "signalk",
+    "signalk-container",
+    "signalk-plugin",
+    "docker",
+    "podman",
+    "container"
+  ],
+  "author": "hoeken",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=24"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^24.0.0",
+    "eslint": "^10.2.0",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^17.4.0",
+    "prettier": "^3.8.1",
+    "signalk-container": "^1.23.2",
+    "typescript": "^5.5.0",
+    "typescript-eslint": "^8.58.0",
+    "vitest": "^3.0.0"
+  }
+}