@nodetool-ai/project-services 0.8.9-beta.2 → 0.8.9-beta.4

package/dist/example-catalog.js

@@ -0,0 +1,154 @@
+/**
+ * The shipped example workflow catalog: lightweight list entries from the
+ * examples directory or the installed Python packages, and the agent-facing
+ * catalog the MCP tools read.
+ */
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import nodePath from "node:path";
+import { createLogger } from "@nodetool-ai/config";
+import { loadPythonPackageMetadata } from "@nodetool-ai/node-sdk";
+import { isObjectLike, isString, scanExampleNeeds } from "@nodetool-ai/protocol";
+import { withCacheBuster } from "./example-thumbnail.js";
+import { deriveExampleAssetsDir, shippedWorkflowExamplesDir } from "./example-workflows.js";
+const log = createLogger("nodetool.examples");
+// ── Workflow examples ──────────────────────────────────────────────────
+/** URL prefix for example workflow thumbnail images served by this API. */
+const EXAMPLES_THUMBNAILS_PREFIX = "/api/workflows/examples/thumbnails/";
+/**
+ * Read example workflow metadata from a directory of JSON files.
+ * Returns lightweight objects (no graph data) suitable for the /examples list.
+ *
+ * When the sibling `assets` directory exists (e.g.
+ * `packages/base-nodes/nodetool/assets/nodetool-base`), a `thumbnail_url`
+ * pointing to `/api/workflows/examples/thumbnails/<name>` is set so the
+ * frontend can display the pre-generated JPG thumbnails.
+ */
+function buildExamplesFromDir(examplesDir, examplesAssetsFallbackDir, registry) {
+    if (!existsSync(examplesDir))
+        return [];
+    const assetsDir = deriveExampleAssetsDir(examplesDir, examplesAssetsFallbackDir);
+    const now = new Date().toISOString();
+    const workflows = [];
+    let files;
+    try {
+        files = readdirSync(examplesDir)
+            .filter((f) => f.toLowerCase().endsWith(".json"))
+            .sort((a, b) => a.localeCompare(b));
+    }
+    catch (err) {
+        log.warn(`Failed to read examples directory ${examplesDir}: ${err}`);
+        return [];
+    }
+    for (const file of files) {
+        try {
+            const raw = readFileSync(nodePath.join(examplesDir, file), "utf8");
+            const parsed = JSON.parse(raw);
+            const name = isString(parsed.name)
+                ? parsed.name
+                : file.replace(/\.json$/i, "");
+            // Point thumbnail_url to the served JPG when the file exists in
+            // assets. withCacheBuster() appends ?v=<md5-8> so the browser cache
+            // invalidates whenever the JPG is regenerated.
+            const jpgFile = `${name}.jpg`;
+            const jpgPath = nodePath.join(assetsDir, jpgFile);
+            const thumbnailUrl = existsSync(jpgPath)
+                ? withCacheBuster(`${EXAMPLES_THUMBNAILS_PREFIX}${encodeURIComponent(jpgFile)}`, jpgPath)
+                : null;
+            workflows.push({
+                id: file,
+                access: "public",
+                created_at: now,
+                updated_at: now,
+                name,
+                tool_name: null,
+                description: isString(parsed.description) ? parsed.description : "",
+                tags: Array.isArray(parsed.tags) ? parsed.tags.filter(isString) : [],
+                thumbnail: thumbnailUrl ? jpgFile : null,
+                thumbnail_url: thumbnailUrl,
+                graph: { nodes: [], edges: [] },
+                input_schema: null,
+                output_schema: null,
+                settings: null,
+                package_name: isString(parsed.package_name)
+                    ? parsed.package_name
+                    : null,
+                path: null,
+                run_mode: null,
+                workspace_id: null,
+                required_providers: null,
+                required_models: null,
+                needs: scanExampleNeeds(parsed.graph, (nodeType) => registry?.getMetadata(nodeType)?.required_settings),
+                html_app: null,
+                app_doc: isObjectLike(parsed.app_doc) ? parsed.app_doc : null,
+                etag: null
+            });
+        }
+        catch (err) {
+            log.debug(`Skipping invalid example workflow file ${file}: ${err}`);
+        }
+    }
+    return workflows;
+}
+export function buildExampleWorkflows(options) {
+    if (options.examplesDir) {
+        return buildExamplesFromDir(options.examplesDir, options.examplesAssetsFallbackDir, options.registry);
+    }
+    const loaded = loadPythonPackageMetadata({
+        roots: options.metadataRoots,
+        maxDepth: options.metadataMaxDepth
+    });
+    const now = new Date().toISOString();
+    const workflows = [];
+    for (const pkg of loaded.packages) {
+        if (!pkg.examples || pkg.examples.length === 0)
+            continue;
+        for (const ex of pkg.examples) {
+            const meta = ex;
+            workflows.push({
+                id: meta.id ?? "",
+                access: "public",
+                created_at: now,
+                updated_at: now,
+                name: meta.name,
+                tool_name: null,
+                description: meta.description ?? "",
+                tags: meta.tags ?? [],
+                thumbnail: null,
+                thumbnail_url: null,
+                graph: { nodes: [], edges: [] },
+                input_schema: null,
+                output_schema: null,
+                settings: null,
+                package_name: pkg.name,
+                path: null,
+                run_mode: null,
+                workspace_id: null,
+                required_providers: null,
+                required_models: null,
+                html_app: null,
+                app_doc: null,
+                etag: null
+            });
+        }
+    }
+    const shippedDirectory = shippedWorkflowExamplesDir();
+    const shipped = shippedDirectory
+        ? buildExamplesFromDir(shippedDirectory, options.examplesAssetsFallbackDir, options.registry)
+        : [];
+    const seen = new Set();
+    return [...workflows, ...shipped].filter((workflow) => {
+        if (!isObjectLike(workflow)) {
+            return false;
+        }
+        const key = JSON.stringify([
+            workflow.package_name ?? "nodetool-base",
+            isString(workflow.id) && workflow.id !== "" ? workflow.id : workflow.name
+        ]);
+        if (seen.has(key)) {
+            return false;
+        }
+        seen.add(key);
+        return true;
+    });
+}
+//# sourceMappingURL=example-catalog.js.map

package/dist/example-catalog.js.map

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

package/dist/example-thumbnail.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Cache-buster for example workflow thumbnail JPGs.
+ *
+ * Each thumbnail's md5 (first 8 hex chars) is appended to its
+ * `thumbnail_url` as `?v=<hash>` so that browsers drop their cached copy
+ * whenever the JPG is regenerated. Hashes are cached by `(absPath, mtimeMs)`
+ * — re-hashed only when the file is replaced on disk.
+ */
+/**
+ * Return the 8-char md5 of `absPath`'s contents, or `null` if the file is
+ * missing / unreadable. The result is memoised by `(path, mtime)` so the
+ * read+hash happens once per file per process (and once again whenever the
+ * file is regenerated).
+ */
+export declare function thumbnailHash(absPath: string): string | null;
+/**
+ * Append `?v=<md5-8>` to a thumbnail URL, or return the URL unchanged if
+ * the file isn't readable.
+ */
+export declare function withCacheBuster(url: string, absPath: string): string;
+//# sourceMappingURL=example-thumbnail.d.ts.map

package/dist/example-thumbnail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"example-thumbnail.d.ts","sourceRoot":"","sources":["../src/example-thumbnail.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAYH;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAoB5D;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAGpE"}

package/dist/example-thumbnail.js

@@ -0,0 +1,50 @@
+/**
+ * Cache-buster for example workflow thumbnail JPGs.
+ *
+ * Each thumbnail's md5 (first 8 hex chars) is appended to its
+ * `thumbnail_url` as `?v=<hash>` so that browsers drop their cached copy
+ * whenever the JPG is regenerated. Hashes are cached by `(absPath, mtimeMs)`
+ * — re-hashed only when the file is replaced on disk.
+ */
+import { readFileSync, statSync } from "node:fs";
+import { createHash } from "node:crypto";
+const cache = new Map();
+/**
+ * Return the 8-char md5 of `absPath`'s contents, or `null` if the file is
+ * missing / unreadable. The result is memoised by `(path, mtime)` so the
+ * read+hash happens once per file per process (and once again whenever the
+ * file is regenerated).
+ */
+export function thumbnailHash(absPath) {
+    let stat;
+    try {
+        stat = statSync(absPath);
+    }
+    catch {
+        return null;
+    }
+    const cached = cache.get(absPath);
+    if (cached && cached.mtimeMs === stat.mtimeMs)
+        return cached.hash;
+    let hash;
+    try {
+        hash = createHash("md5")
+            .update(readFileSync(absPath))
+            .digest("hex")
+            .slice(0, 8);
+    }
+    catch {
+        return null;
+    }
+    cache.set(absPath, { mtimeMs: stat.mtimeMs, hash });
+    return hash;
+}
+/**
+ * Append `?v=<md5-8>` to a thumbnail URL, or return the URL unchanged if
+ * the file isn't readable.
+ */
+export function withCacheBuster(url, absPath) {
+    const hash = thumbnailHash(absPath);
+    return hash ? `${url}?v=${hash}` : url;
+}
+//# sourceMappingURL=example-thumbnail.js.map

package/dist/example-thumbnail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"example-thumbnail.js","sourceRoot":"","sources":["../src/example-thumbnail.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAOzC,MAAM,KAAK,GAAG,IAAI,GAAG,EAAsB,CAAC;AAE5C;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,OAAe;IAC3C,IAAI,IAAiC,CAAC;IACtC,IAAI,CAAC;QACH,IAAI,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAClC,IAAI,MAAM,IAAI,MAAM,CAAC,OAAO,KAAK,IAAI,CAAC,OAAO;QAAE,OAAO,MAAM,CAAC,IAAI,CAAC;IAClE,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC;aACrB,MAAM,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;aAC7B,MAAM,CAAC,KAAK,CAAC;aACb,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACjB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;IACpD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW,EAAE,OAAe;IAC1D,MAAM,IAAI,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IACpC,OAAO,IAAI,CAAC,CAAC,CAAC,GAAG,GAAG,MAAM,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;AACzC,CAAC"}

package/dist/example-workflows.d.ts

@@ -0,0 +1,22 @@
+interface ExampleWorkflowLoadOptions {
+    examplesDir?: string;
+    /** Fallback thumbnail directory when the sibling of examplesDir has no JPGs. */
+    examplesAssetsFallbackDir?: string;
+    metadataRoots?: string[];
+    metadataMaxDepth?: number;
+}
+/** Default examples shipped inside the npm package or bundled server. */
+export declare function shippedWorkflowExamplesDir(): string | undefined;
+/**
+ * Resolve the directory containing gallery thumbnail JPGs/PNGs for an examples dir.
+ * Prefer the sibling `assets/<package>` layout; fall back to bundled assets when
+ * examples are mounted elsewhere (common in Docker compose overrides).
+ */
+export declare function deriveExampleAssetsDir(examplesDir: string, fallbackAssetsDir?: string | null): string;
+/** Resolve a display name, slug, or filename to an on-disk example JSON path. */
+export declare function resolveExampleJsonPath(examplesDir: string, exampleRef: string): string | null;
+/** Load a full example workflow JSON (including graph) for workflow creation. */
+export declare function loadExampleGraph(packageName: string, exampleRef: string, options?: ExampleWorkflowLoadOptions): Record<string, unknown> | null;
+export declare function defaultExamplePackageName(options: ExampleWorkflowLoadOptions): string | null;
+export {};
+//# sourceMappingURL=example-workflows.d.ts.map

package/dist/example-workflows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"example-workflows.d.ts","sourceRoot":"","sources":["../src/example-workflows.ts"],"names":[],"mappings":"AAMA,UAAU,0BAA0B;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gFAAgF;IAChF,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,yEAAyE;AACzE,wBAAgB,0BAA0B,IAAI,MAAM,GAAG,SAAS,CAO/D;AAaD;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,EACnB,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,GAChC,MAAM,CAiBR;AAED,iFAAiF;AACjF,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,GACjB,MAAM,GAAG,IAAI,CAwDf;AAyCD,iFAAiF;AACjF,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,0BAA+B,GACvC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAchC;AAED,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,0BAA0B,GAClC,MAAM,GAAG,IAAI,CAMf"}

package/dist/example-workflows.js

@@ -0,0 +1,141 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import nodePath from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadPythonPackageMetadata } from "@nodetool-ai/node-sdk";
+import { isString } from "@nodetool-ai/protocol";
+/** Default examples shipped inside the npm package or bundled server. */
+export function shippedWorkflowExamplesDir() {
+    const here = nodePath.dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        nodePath.join(here, "examples", "nodetool-base"),
+        nodePath.resolve(here, "../../base-nodes/nodetool/examples/nodetool-base")
+    ];
+    return candidates.find((directory) => existsSync(directory));
+}
+function directoryHasGalleryThumbnails(dir) {
+    if (!existsSync(dir)) {
+        return false;
+    }
+    try {
+        return readdirSync(dir).some((file) => /\.(jpg|jpeg|png)$/i.test(file));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve the directory containing gallery thumbnail JPGs/PNGs for an examples dir.
+ * Prefer the sibling `assets/<package>` layout; fall back to bundled assets when
+ * examples are mounted elsewhere (common in Docker compose overrides).
+ */
+export function deriveExampleAssetsDir(examplesDir, fallbackAssetsDir) {
+    const derived = nodePath.join(nodePath.dirname(nodePath.dirname(examplesDir)), "assets", nodePath.basename(examplesDir));
+    if (directoryHasGalleryThumbnails(derived)) {
+        return derived;
+    }
+    if (fallbackAssetsDir &&
+        existsSync(fallbackAssetsDir) &&
+        directoryHasGalleryThumbnails(fallbackAssetsDir)) {
+        return fallbackAssetsDir;
+    }
+    return derived;
+}
+/** Resolve a display name, slug, or filename to an on-disk example JSON path. */
+export function resolveExampleJsonPath(examplesDir, exampleRef) {
+    const ref = exampleRef.trim();
+    if (!ref) {
+        return null;
+    }
+    const directCandidates = ref.toLowerCase().endsWith(".json")
+        ? [nodePath.join(examplesDir, nodePath.basename(ref))]
+        : [
+            nodePath.join(examplesDir, `${ref}.json`),
+            nodePath.join(examplesDir, ref)
+        ];
+    for (const candidate of directCandidates) {
+        // The ref is caller input: a candidate outside the examples directory
+        // (`../../x`) would read any JSON file on the host.
+        const rel = nodePath.relative(examplesDir, candidate);
+        if (!rel || rel.startsWith("..") || nodePath.isAbsolute(rel)) {
+            continue;
+        }
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    let files;
+    try {
+        files = readdirSync(examplesDir).filter((file) => file.toLowerCase().endsWith(".json"));
+    }
+    catch {
+        return null;
+    }
+    for (const file of files) {
+        if (file === ref || file === `${ref}.json`) {
+            return nodePath.join(examplesDir, file);
+        }
+    }
+    for (const file of files) {
+        try {
+            const raw = readFileSync(nodePath.join(examplesDir, file), "utf8");
+            const parsed = JSON.parse(raw);
+            if (isString(parsed.name) && parsed.name === ref) {
+                return nodePath.join(examplesDir, file);
+            }
+            if (isString(parsed.id) && parsed.id === ref) {
+                return nodePath.join(examplesDir, file);
+            }
+        }
+        catch {
+            // skip invalid example files
+        }
+    }
+    return null;
+}
+function loadExampleGraphFromDir(examplesDir, exampleRef) {
+    const examplePath = resolveExampleJsonPath(examplesDir, exampleRef);
+    if (!examplePath) {
+        return null;
+    }
+    try {
+        const raw = readFileSync(examplePath, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function loadExampleGraphFromPythonPackage(packageName, exampleRef, options) {
+    const loaded = loadPythonPackageMetadata({
+        roots: options.metadataRoots,
+        maxDepth: options.metadataMaxDepth
+    });
+    const pkg = loaded.packages.find((p) => p.name === packageName);
+    if (!pkg?.sourceFolder) {
+        return null;
+    }
+    const examplesDir = nodePath.join(pkg.sourceFolder, "nodetool", "examples", pkg.name);
+    return loadExampleGraphFromDir(examplesDir, exampleRef);
+}
+/** Load a full example workflow JSON (including graph) for workflow creation. */
+export function loadExampleGraph(packageName, exampleRef, options = {}) {
+    const examplesDir = options.examplesDir ?? shippedWorkflowExamplesDir();
+    if (examplesDir && existsSync(examplesDir) && (options.examplesDir || !packageName || packageName === nodePath.basename(examplesDir))) {
+        const fromDir = loadExampleGraphFromDir(examplesDir, exampleRef);
+        if (fromDir) {
+            return fromDir;
+        }
+    }
+    if (packageName) {
+        return loadExampleGraphFromPythonPackage(packageName, exampleRef, options);
+    }
+    return null;
+}
+export function defaultExamplePackageName(options) {
+    const examplesDir = options.examplesDir ?? shippedWorkflowExamplesDir();
+    if (examplesDir && existsSync(examplesDir)) {
+        return nodePath.basename(examplesDir);
+    }
+    return null;
+}
+//# sourceMappingURL=example-workflows.js.map

package/dist/example-workflows.js.map

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