@nodetool-ai/config 0.7.0-rc.23 → 0.8.1

package/dist/package-asset-registry.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Runtime asset registry — the single source of truth for data files that
+ * packages ship next to their compiled code and load at runtime (provider
+ * manifests today).
+ *
+ * Three layers consume it and must agree, which is exactly why it is one
+ * list instead of three conventions:
+ *
+ * 1. `package-assets.ts` — runtime resolution. Refuses to load a file that
+ *    is not registered, so a forgotten registration fails loudly in dev
+ *    instead of silently in the packaged app.
+ * 2. `scripts/bundle-backend.mjs` — stages every entry next to the
+ *    bundled server.mjs and fails the build when a source file is missing
+ *    or an on-disk manifest is not registered.
+ * 3. `scripts/verify-backend-bundle.mjs` — final artifact check
+ *    that every manifest referenced by server.mjs is staged.
+ *
+ * `path` is relative to the owning package's `dist/`. Basenames must be
+ * unique across the registry: the packaged layout is flat, every file lands
+ * directly next to server.mjs.
+ *
+ * This module must stay free of imports — build scripts load it straight
+ * from `dist/` without pulling in the rest of the config package.
+ */
+export interface PackageAssetRef {
+    /** npm package that ships the file, e.g. "@nodetool-ai/kie-nodes". */
+    pkg: string;
+    /** File path relative to the package's dist/, e.g. "kie-manifest.json". */
+    path: string;
+}
+export declare const PACKAGE_RUNTIME_ASSETS: readonly PackageAssetRef[];
+/**
+ * A directory of runtime files a package ships next to its sources rather than
+ * inside `dist/`, staged into the bundle as a directory instead of flattened
+ * by basename.
+ *
+ * Separate from {@link PACKAGE_RUNTIME_ASSETS} because the resolution rule is
+ * different in both halves: the source is the package root, not its build
+ * output (font binaries are inputs, and copying three megabytes through `tsc`
+ * would only duplicate them), and the staged copy keeps its directory, because
+ * the web serves the files by name over HTTP. The purpose is the same one C6
+ * names — the bundler stages it, the verifier checks it, so an unstaged file
+ * fails the build instead of the product.
+ */
+export interface PackageAssetDirRef {
+    /** npm package that ships the directory, e.g. "@nodetool-ai/timeline". */
+    pkg: string;
+    /** Directory relative to the package ROOT, e.g. "fonts". */
+    path: string;
+    /** Directory name under the bundle root the files are staged into. */
+    bundleDir: string;
+    /**
+     * Every file that must be present, in the source directory and in the
+     * artifact. Named rather than globbed: a build that silently ships nine of
+     * ten faces renders one family as a fallback, which looks like a design
+     * choice rather than a packaging bug.
+     */
+    files: readonly string[];
+}
+/**
+ * The bundled font corpus (D8). The file list mirrors `BUNDLED_FONT_FILES` in
+ * `@nodetool-ai/timeline`; this module imports nothing, so
+ * `packages/execution/tests/timeline-font-registry.test.ts` is what holds the
+ * two lists together.
+ */
+export declare const PACKAGE_RUNTIME_ASSET_DIRS: readonly PackageAssetDirRef[];
+/**
+ * Where the sandbox packs that ship with NodeTool live, in the repo and in the
+ * packaged artifact. Every host reads one of these two locations, so both names
+ * live here rather than in each script.
+ *
+ * The packs are config-only npm packages (a `nodetool.sandboxModules` manifest
+ * plus a SKILL.md) that no host code may import, so they are not workspaces and
+ * npm never links them into `node_modules`. Discovery therefore reads them from
+ * disk: `packages/sandbox-packs/` in a checkout, and `_sandbox/` next to
+ * `server.mjs` in the bundle, where `bundle-backend.mjs` stages every one of
+ * them and `verify-backend-bundle.mjs` checks the staged tree against each
+ * pack's own manifest. Both are directories of package directories, which is
+ * what {@link listPackageDirs} in `@nodetool-ai/node-sdk` enumerates — scoped
+ * names sit one level deeper, exactly as in `node_modules`.
+ *
+ * Staging is a scan, not a list: a pack added to the source directory ships
+ * without touching this file.
+ */
+export declare const SHIPPED_SANDBOX_PACKS_SOURCE_DIR = "packages/sandbox-packs";
+/** The staged copy's directory name, relative to the bundled `server.mjs`. */
+export declare const SHIPPED_SANDBOX_PACKS_BUNDLE_DIR = "_sandbox";
+/**
+ * The system skills that ship with NodeTool.
+ *
+ * A system skill is a `SKILL.md` — frontmatter naming it, Markdown body — under
+ * a directory of its own, read-only at runtime. Same two-root shape as the
+ * sandbox packs above and for the same reason: nothing imports them, so npm
+ * links nothing, and each host reads them from where its own build put them.
+ * `NODETOOL_SYSTEM_SKILLS_DIR` overrides both.
+ */
+export declare const SHIPPED_SYSTEM_SKILLS_SOURCE_DIR = "packages/system-skills";
+/** The staged copy's directory name, relative to the bundled `server.mjs`. */
+export declare const SHIPPED_SYSTEM_SKILLS_BUNDLE_DIR = "_skills";
+/** Registry lookup by exact pkg + path. */
+export declare function findPackageAsset(pkg: string, path: string, registry?: readonly PackageAssetRef[]): PackageAssetRef | undefined;
+//# sourceMappingURL=package-asset-registry.d.ts.map

package/dist/package-asset-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-asset-registry.d.ts","sourceRoot":"","sources":["../src/package-asset-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,MAAM,WAAW,eAAe;IAC9B,sEAAsE;IACtE,GAAG,EAAE,MAAM,CAAC;IACZ,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;CACd;AAED,eAAO,MAAM,sBAAsB,EAAE,SAAS,eAAe,EAU5D,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,kBAAkB;IACjC,0EAA0E;IAC1E,GAAG,EAAE,MAAM,CAAC;IACZ,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAED;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,EAAE,SAAS,kBAAkB,EA0EnE,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,gCAAgC,2BAA2B,CAAC;AAEzE,8EAA8E;AAC9E,eAAO,MAAM,gCAAgC,aAAa,CAAC;AAE3D;;;;;;;;GAQG;AACH,eAAO,MAAM,gCAAgC,2BAA2B,CAAC;AAEzE,8EAA8E;AAC9E,eAAO,MAAM,gCAAgC,YAAY,CAAC;AAE1D,2CAA2C;AAC3C,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,QAAQ,GAAE,SAAS,eAAe,EAA2B,GAC5D,eAAe,GAAG,SAAS,CAE7B"}

package/dist/package-asset-registry.js

@@ -0,0 +1,154 @@
+/**
+ * Runtime asset registry — the single source of truth for data files that
+ * packages ship next to their compiled code and load at runtime (provider
+ * manifests today).
+ *
+ * Three layers consume it and must agree, which is exactly why it is one
+ * list instead of three conventions:
+ *
+ * 1. `package-assets.ts` — runtime resolution. Refuses to load a file that
+ *    is not registered, so a forgotten registration fails loudly in dev
+ *    instead of silently in the packaged app.
+ * 2. `scripts/bundle-backend.mjs` — stages every entry next to the
+ *    bundled server.mjs and fails the build when a source file is missing
+ *    or an on-disk manifest is not registered.
+ * 3. `scripts/verify-backend-bundle.mjs` — final artifact check
+ *    that every manifest referenced by server.mjs is staged.
+ *
+ * `path` is relative to the owning package's `dist/`. Basenames must be
+ * unique across the registry: the packaged layout is flat, every file lands
+ * directly next to server.mjs.
+ *
+ * This module must stay free of imports — build scripts load it straight
+ * from `dist/` without pulling in the rest of the config package.
+ */
+export const PACKAGE_RUNTIME_ASSETS = [
+    { pkg: "@nodetool-ai/atlascloud-nodes", path: "atlascloud-manifest.json" },
+    { pkg: "@nodetool-ai/higgsfield-nodes", path: "higgsfield-manifest.json" },
+    { pkg: "@nodetool-ai/fal-nodes", path: "fal-manifest.json" },
+    { pkg: "@nodetool-ai/kie-nodes", path: "kie-manifest.json" },
+    { pkg: "@nodetool-ai/replicate-nodes", path: "replicate-manifest.json" },
+    { pkg: "@nodetool-ai/runtime", path: "providers/aki-manifest.json" },
+    { pkg: "@nodetool-ai/together-nodes", path: "together-manifest.json" },
+    { pkg: "@nodetool-ai/topaz-nodes", path: "topaz-manifest.json" },
+    { pkg: "@nodetool-ai/video-nodes", path: "render3d-page.js" }
+];
+/**
+ * The bundled font corpus (D8). The file list mirrors `BUNDLED_FONT_FILES` in
+ * `@nodetool-ai/timeline`; this module imports nothing, so
+ * `packages/execution/tests/timeline-font-registry.test.ts` is what holds the
+ * two lists together.
+ */
+export const PACKAGE_RUNTIME_ASSET_DIRS = [
+    {
+        pkg: "@nodetool-ai/timeline",
+        path: "fonts",
+        bundleDir: "fonts",
+        files: [
+            "BebasNeue-Regular.ttf",
+            "Inter-ExtraBold.ttf",
+            "Inter-Italic-Variable.ttf",
+            "Inter-SemiBold.ttf",
+            "Inter-Variable.ttf",
+            "JetBrainsMono-Italic-Variable.ttf",
+            "JetBrainsMono-Variable.ttf",
+            "Lora-Italic-Variable.ttf",
+            "Lora-Variable.ttf",
+            "OFL-BebasNeue.txt",
+            "OFL-Inter.txt",
+            "OFL-JetBrainsMono.txt",
+            "OFL-Lora.txt",
+            "OFL-PlayfairDisplay.txt",
+            "OFL-SpaceGrotesk.txt",
+            "PlayfairDisplay-Italic-Variable.ttf",
+            "PlayfairDisplay-Variable.ttf",
+            "SpaceGrotesk-Variable.ttf"
+        ]
+    },
+    {
+        // The shipped timeline compositions (D11). Built by
+        // `scripts/build-example-compositions.mjs` from
+        // `scripts/example-compositions/compositions.mjs`, and read straight off
+        // disk by the `compositions` capability module — no database, no user — so
+        // an unstaged file means `list_compositions` reports only what a user has
+        // saved and the shipped half silently disappears from the packaged app.
+        pkg: "@nodetool-ai/base-nodes",
+        path: "nodetool/examples/compositions",
+        bundleDir: "examples/compositions",
+        files: [
+            "callout.composition.json",
+            "caption-bar.composition.json",
+            "cta-end-card.composition.json",
+            "logo-sting.composition.json",
+            "lower-third.composition.json",
+            "number-ticker.composition.json",
+            "title-slam.composition.json",
+            "window-frame.composition.json",
+            "word-cards.composition.json",
+            "title-card.composition.json"
+        ]
+    },
+    {
+        // The Blender op scripts (D5). Staged whole next to the bundled server;
+        // every file is named so an unstaged module fails the build instead of
+        // the product.
+        pkg: "@nodetool-ai/blender-nodes",
+        path: "blender_ops",
+        bundleDir: "_blender_ops",
+        files: [
+            "run_job.py",
+            "framing.py",
+            "errors.py",
+            "depth.py",
+            "exr.py",
+            "ops/__init__.py",
+            "ops/common.py",
+            "ops/render_image.py",
+            "ops/render_passes.py",
+            "ops/render_animation.py",
+            "ops/prepare_for_engine.py",
+            "ops/export_model.py",
+            "tests/test_framing.py",
+            "tests/test_depth.py",
+            "tests/test_exr.py"
+        ]
+    }
+];
+/**
+ * Where the sandbox packs that ship with NodeTool live, in the repo and in the
+ * packaged artifact. Every host reads one of these two locations, so both names
+ * live here rather than in each script.
+ *
+ * The packs are config-only npm packages (a `nodetool.sandboxModules` manifest
+ * plus a SKILL.md) that no host code may import, so they are not workspaces and
+ * npm never links them into `node_modules`. Discovery therefore reads them from
+ * disk: `packages/sandbox-packs/` in a checkout, and `_sandbox/` next to
+ * `server.mjs` in the bundle, where `bundle-backend.mjs` stages every one of
+ * them and `verify-backend-bundle.mjs` checks the staged tree against each
+ * pack's own manifest. Both are directories of package directories, which is
+ * what {@link listPackageDirs} in `@nodetool-ai/node-sdk` enumerates — scoped
+ * names sit one level deeper, exactly as in `node_modules`.
+ *
+ * Staging is a scan, not a list: a pack added to the source directory ships
+ * without touching this file.
+ */
+export const SHIPPED_SANDBOX_PACKS_SOURCE_DIR = "packages/sandbox-packs";
+/** The staged copy's directory name, relative to the bundled `server.mjs`. */
+export const SHIPPED_SANDBOX_PACKS_BUNDLE_DIR = "_sandbox";
+/**
+ * The system skills that ship with NodeTool.
+ *
+ * A system skill is a `SKILL.md` — frontmatter naming it, Markdown body — under
+ * a directory of its own, read-only at runtime. Same two-root shape as the
+ * sandbox packs above and for the same reason: nothing imports them, so npm
+ * links nothing, and each host reads them from where its own build put them.
+ * `NODETOOL_SYSTEM_SKILLS_DIR` overrides both.
+ */
+export const SHIPPED_SYSTEM_SKILLS_SOURCE_DIR = "packages/system-skills";
+/** The staged copy's directory name, relative to the bundled `server.mjs`. */
+export const SHIPPED_SYSTEM_SKILLS_BUNDLE_DIR = "_skills";
+/** Registry lookup by exact pkg + path. */
+export function findPackageAsset(pkg, path, registry = PACKAGE_RUNTIME_ASSETS) {
+    return registry.find((a) => a.pkg === pkg && a.path === path);
+}
+//# sourceMappingURL=package-asset-registry.js.map

package/dist/package-asset-registry.js.map

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

package/dist/package-assets.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Guarded access to registered package runtime assets.
+ *
+ * Packages ship data files (provider manifests) next to their compiled code
+ * and load them at runtime. The file's location differs by deployment:
+ *
+ * - **dev / npm install**: the file resolves through package exports, e.g.
+ *   `@nodetool-ai/kie-nodes/kie-manifest.json` → `<pkg>/dist/kie-manifest.json`.
+ * - **packaged Electron app**: esbuild flattens the whole backend into one
+ *   `server.mjs`, so `import.meta.url`-relative paths all point at the bundle
+ *   root, where `bundle-backend.mjs` stages each file by basename.
+ *
+ * This module is the single choke point for those loads. Every asset must be
+ * declared in `package-asset-registry.ts` — an unregistered ref throws
+ * immediately, in dev, with the fix in the message. Resolution outcomes are
+ * recorded and queryable via `getPackageAssetResolutions()` for diagnostics.
+ */
+import { type PackageAssetRef } from "./package-asset-registry.js";
+/** How a requested asset resolved, for startup/health diagnostics. */
+export interface PackageAssetResolution {
+    pkg: string;
+    path: string;
+    /** Absolute path the asset resolved to, or null when resolution failed. */
+    resolvedPath: string | null;
+    /** "package" = via package exports (dev/npm), "importer" = next to the importing module (packaged bundle). */
+    via: "package" | "importer" | null;
+    error?: string;
+}
+/** Every asset requested so far and how it resolved. */
+export declare function getPackageAssetResolutions(): PackageAssetResolution[];
+/**
+ * Resolve a registered asset to an absolute file path.
+ *
+ * Tries package-exports resolution first (dev / npm layout), then a file with
+ * the asset's basename next to the importing module (the flattened packaged
+ * layout — and the dev layout for same-package assets). Throws with both
+ * attempted locations when neither exists.
+ *
+ * @param ref - Registered asset (pkg + dist-relative path).
+ * @param importerUrl - The caller's `import.meta.url`. Required: in the
+ *   packaged app it points at the bundle root where assets are staged.
+ * @param registry - Overridable for tests only.
+ */
+export declare function resolvePackageAssetPath(ref: PackageAssetRef, importerUrl: string, registry?: readonly PackageAssetRef[]): string;
+/**
+ * Load a registered JSON asset. Loads through `require` rather than an `fs`
+ * read: the values flow into provider API requests, and a module load keeps
+ * static, trusted data from being modelled as untrusted file input
+ * (CodeQL js/file-access-to-http) — and gets caching for free.
+ */
+export declare function loadPackageAssetJson<T>(ref: PackageAssetRef, importerUrl: string, registry?: readonly PackageAssetRef[]): T;
+//# sourceMappingURL=package-assets.d.ts.map

package/dist/package-assets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-assets.d.ts","sourceRoot":"","sources":["../src/package-assets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,6BAA6B,CAAC;AAcrC,sEAAsE;AACtE,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,8GAA8G;IAC9G,GAAG,EAAE,SAAS,GAAG,UAAU,GAAG,IAAI,CAAC;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAID,wDAAwD;AACxD,wBAAgB,0BAA0B,IAAI,sBAAsB,EAAE,CAErE;AAWD;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,eAAe,EACpB,WAAW,EAAE,MAAM,EACnB,QAAQ,GAAE,SAAS,eAAe,EAA2B,GAC5D,MAAM,CA2CR;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,GAAG,EAAE,eAAe,EACpB,WAAW,EAAE,MAAM,EACnB,QAAQ,GAAE,SAAS,eAAe,EAA2B,GAC5D,CAAC,CAOH"}

package/dist/package-assets.js

@@ -0,0 +1,98 @@
+/**
+ * Guarded access to registered package runtime assets.
+ *
+ * Packages ship data files (provider manifests) next to their compiled code
+ * and load them at runtime. The file's location differs by deployment:
+ *
+ * - **dev / npm install**: the file resolves through package exports, e.g.
+ *   `@nodetool-ai/kie-nodes/kie-manifest.json` → `<pkg>/dist/kie-manifest.json`.
+ * - **packaged Electron app**: esbuild flattens the whole backend into one
+ *   `server.mjs`, so `import.meta.url`-relative paths all point at the bundle
+ *   root, where `bundle-backend.mjs` stages each file by basename.
+ *
+ * This module is the single choke point for those loads. Every asset must be
+ * declared in `package-asset-registry.ts` — an unregistered ref throws
+ * immediately, in dev, with the fix in the message. Resolution outcomes are
+ * recorded and queryable via `getPackageAssetResolutions()` for diagnostics.
+ */
+import { IS_NODE, getNodeBuiltinSync } from "./node-import.js";
+import { createLogger } from "./logging.js";
+import { PACKAGE_RUNTIME_ASSETS, findPackageAsset } from "./package-asset-registry.js";
+const log = createLogger("nodetool.config.package-assets");
+const nodeModule = getNodeBuiltinSync("node:module");
+const nodeFs = getNodeBuiltinSync("node:fs");
+const nodeUrl = getNodeBuiltinSync("node:url");
+const resolutions = new Map();
+/** Every asset requested so far and how it resolved. */
+export function getPackageAssetResolutions() {
+    return [...resolutions.values()];
+}
+function record(resolution) {
+    resolutions.set(`${resolution.pkg}/${resolution.path}`, resolution);
+}
+function basenameOf(assetPath) {
+    const parts = assetPath.split("/");
+    return parts[parts.length - 1];
+}
+/**
+ * Resolve a registered asset to an absolute file path.
+ *
+ * Tries package-exports resolution first (dev / npm layout), then a file with
+ * the asset's basename next to the importing module (the flattened packaged
+ * layout — and the dev layout for same-package assets). Throws with both
+ * attempted locations when neither exists.
+ *
+ * @param ref - Registered asset (pkg + dist-relative path).
+ * @param importerUrl - The caller's `import.meta.url`. Required: in the
+ *   packaged app it points at the bundle root where assets are staged.
+ * @param registry - Overridable for tests only.
+ */
+export function resolvePackageAssetPath(ref, importerUrl, registry = PACKAGE_RUNTIME_ASSETS) {
+    if (!findPackageAsset(ref.pkg, ref.path, registry)) {
+        throw new Error(`Package asset ${ref.pkg}/${ref.path} is not registered. Add it to ` +
+            `PACKAGE_RUNTIME_ASSETS in @nodetool-ai/config/src/package-asset-registry.ts ` +
+            `so the Electron packaging stages and verifies it.`);
+    }
+    if (!IS_NODE || !nodeModule || !nodeFs || !nodeUrl) {
+        throw new Error(`Package asset ${ref.pkg}/${ref.path} requested on a non-Node runtime.`);
+    }
+    const req = nodeModule.createRequire(importerUrl);
+    const specifier = `${ref.pkg}/${ref.path}`;
+    try {
+        const resolved = req.resolve(specifier);
+        record({ pkg: ref.pkg, path: ref.path, resolvedPath: resolved, via: "package" });
+        return resolved;
+    }
+    catch {
+        // Not resolvable through package exports — try the flattened layout.
+    }
+    const candidate = nodeUrl.fileURLToPath(new URL(basenameOf(ref.path), importerUrl));
+    if (nodeFs.existsSync(candidate)) {
+        record({ pkg: ref.pkg, path: ref.path, resolvedPath: candidate, via: "importer" });
+        return candidate;
+    }
+    const message = `Package asset ${ref.pkg}/${ref.path} not found. Tried package ` +
+        `resolution of "${specifier}" and "${candidate}" (relative to the ` +
+        `importer). In dev, check the owning package's build copies the file ` +
+        `into dist/ and its exports map the subpath. In the packaged app, check ` +
+        `scripts/bundle-backend.mjs staged it (verify-backend-bundle ` +
+        `should have failed the build).`;
+    record({ pkg: ref.pkg, path: ref.path, resolvedPath: null, via: null, error: message });
+    log.warn(message);
+    throw new Error(message);
+}
+/**
+ * Load a registered JSON asset. Loads through `require` rather than an `fs`
+ * read: the values flow into provider API requests, and a module load keeps
+ * static, trusted data from being modelled as untrusted file input
+ * (CodeQL js/file-access-to-http) — and gets caching for free.
+ */
+export function loadPackageAssetJson(ref, importerUrl, registry = PACKAGE_RUNTIME_ASSETS) {
+    const resolved = resolvePackageAssetPath(ref, importerUrl, registry);
+    const req = nodeModule.createRequire(importerUrl);
+    // SAFETY: `T` is the shape the caller names for this registered asset;
+    // `resolvePackageAssetPath` has already checked the ref against the registry,
+    // so what `require` returns is that asset's JSON and nothing else.
+    return req(resolved);
+}
+//# sourceMappingURL=package-assets.js.map

package/dist/package-assets.js.map

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

package/dist/paths.d.ts

@@ -5,6 +5,10 @@
  * re-implement OS detection or XDG logic.
  *
  * Priority: explicit env var > platform default.
+ *
+ * The `node:path` / `node:os` / `node:url` imports are loaded lazily via
+ * top-level dynamic import so this module loads on non-Node runtimes
+ * (browser, Edge). All exported functions throw if invoked off-Node.
  */
 /**
  * Base directory for all Nodetool user data.
@@ -16,7 +20,8 @@
  * - macOS/Linux: $XDG_DATA_HOME/nodetool  (fallback: ~/.local/share/nodetool)
  */
 export declare function getNodetoolDataDir(): string;
-/** Default path for the main SQLite database. Override with DB_PATH. */
+export declare function getPostgresDatabaseUrl(): string | undefined;
+/** Default path for the main SQLite database. Override with DB_PATH or DATABASE_URL. */
 export declare function getDefaultDbPath(): string;
 /** Default path for the vector store database. Override with VECTORSTORE_DB_PATH. */
 export declare function getDefaultVectorstoreDbPath(): string;
@@ -32,38 +37,62 @@ export declare function getDefaultAssetsPath(): string;
  */
 export declare function getDefaultTransformersJsCacheDir(): string;
 /**
- * Public domain for permanent assets (set via ASSET_DOMAIN env var).
+ * Per-user cache root for derived artifacts NodeTool can always rebuild.
+ *
+ * Separate from {@link getNodetoolDataDir} on purpose: everything under here is
+ * safe to delete. Override with NODETOOL_CACHE_DIR.
  *
- * When set, asset URLs are built as `https://<domain>/<key>` instead of
- * `/api/storage/<key>`. Accepts bare hostnames (`assets.nodetool.ai`) or
- * full origins (`https://assets.nodetool.ai`). Returns `undefined` when not
- * configured.
+ * - Windows:     %LOCALAPPDATA%\nodetool\cache
+ * - macOS/Linux: $XDG_CACHE_HOME/nodetool  (fallback: ~/.cache/nodetool)
+ */
+export declare function getNodetoolCacheDir(): string;
+/**
+ * Return the absolute filesystem path for a storage key.
+ * Use this on the server side for direct file reads.
+ */
+export declare function getAssetFilePath(key: string): string;
+/**
+ * Build a client-facing URL for a storage key.
+ * Returns `/api/storage/<key>` — served by the local HTTP server (file
+ * backend) or proxied/redirected to cloud storage by the storage handler.
  */
-export declare function getAssetDomain(): string | undefined;
+export declare function buildAssetUrl(key: string): string;
 /**
- * Public domain for temporary assets (set via TEMP_DOMAIN env var).
+ * Root under which NodeTool keeps the workspace folders it manages itself.
  *
- * Applied to keys with the `temp/` prefix. Accepts bare hostnames or full
- * origins. Returns `undefined` when not configured, in which case temp URLs
- * fall back to `ASSET_DOMAIN` (if set) or the `/api/storage/` path.
+ * A managed workspace is the one every user gets without picking a folder, so
+ * a chat turn always has somewhere bounded to read and write. It lives under
+ * the data dir rather than the cache dir: an agent's outputs are user data, not
+ * a derived artifact that is safe to delete. Override with
+ * NODETOOL_WORKSPACES_DIR — a server deployment points it at a mounted volume.
  */
-export declare function getTempDomain(): string | undefined;
+export declare function getManagedWorkspacesDir(): string;
 /**
- * Return the absolute filesystem path for a storage key.
+ * Storage key prefix of a user's workspace on a deployment that keeps
+ * workspaces in object storage rather than on a disk.
  *
- * Use this on the server side whenever you need to read an asset from disk.
- * Never pass the result to a browser client — use `buildAssetUrl` for that.
+ * The same sanitizing as {@link getManagedWorkspaceDir}: the user id is one
+ * key segment, and a `/` or `..` inside it would otherwise reach another
+ * user's prefix.
  */
-export declare function getAssetFilePath(key: string): string;
+export declare function managedWorkspaceKey(userId: string): string;
 /**
- * Build a **client-facing** URL for an asset identified by its storage key.
+ * Absolute path of a user's managed default workspace.
  *
- * The key is the storage-relative path (e.g. `abc.png` or `temp/uuid.png`).
- * When ASSET_DOMAIN / TEMP_DOMAIN are configured, returns an absolute CDN URL.
- * Otherwise returns `/api/storage/<key>` — a dev-mode path that the browser
- * can reach via the Vite proxy or the local HTTP server.
+ * The user id is a path segment, so anything that is not a safe filename
+ * character is replaced — a user id from an external identity provider can
+ * carry `/`, `:` or `..`, and each of those would escape the workspaces root.
+ */
+export declare function getManagedWorkspaceDir(userId: string): string;
+/**
+ * Whether this deployment backs workspaces with a local folder or with the
+ * object storage it already uses for assets.
  *
- * Do NOT use this for server-side file reads. Use `getAssetFilePath` instead.
+ * Production has no durable disk worth writing a user's files to — a Fly
+ * machine is replaced and the folder goes with it — so a cloud workspace is a
+ * key prefix in the asset bucket. `NODETOOL_WORKSPACE_STORAGE` overrides the
+ * default either way, which is how a self-hosted server with a mounted volume
+ * keeps local workspaces, and how a local install can be pointed at S3.
  */
-export declare function buildAssetUrl(key: string): string;
+export declare function workspaceStorageKind(): "local" | "cloud";
 //# sourceMappingURL=paths.d.ts.map

package/dist/paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAY3C;AAED,wEAAwE;AACxE,wBAAgB,gBAAgB,IAAI,MAAM,CAIzC;AAED,qFAAqF;AACrF,wBAAgB,2BAA2B,IAAI,MAAM,CAKpD;AAED,wFAAwF;AACxF,wBAAgB,oBAAoB,IAAI,MAAM,CAM7C;AAED;;;;;;;GAOG;AACH,wBAAgB,gCAAgC,IAAI,MAAM,CAKzD;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,IAAI,MAAM,GAAG,SAAS,CAGnD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,IAAI,MAAM,GAAG,SAAS,CAGlD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAoBjD"}
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA0BH;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAa3C;AAqBD,wBAAgB,sBAAsB,IAAI,MAAM,GAAG,SAAS,CAO3D;AA+CD,wFAAwF;AACxF,wBAAgB,gBAAgB,IAAI,MAAM,CAOzC;AAED,qFAAqF;AACrF,wBAAgB,2BAA2B,IAAI,MAAM,CAKpD;AAED,wFAAwF;AACxF,wBAAgB,oBAAoB,IAAI,MAAM,CAM7C;AAED;;;;;;;GAOG;AACH,wBAAgB,gCAAgC,IAAI,MAAM,CAKzD;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAe5C;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAUjD;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAKhD;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE7D;AAOD;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,GAAG,OAAO,CAIxD"}