@netnodeag/kraftwerk 0.37.0 → 0.38.0

package/dist/cli/projects.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import chalk from "chalk";
+import { absolutePath } from "../config.js";
 import Table from "cli-table3";
 import { discoverWorkspaces, forgetProject, startProject, stopProject, tildify, } from "../inspector/instances.js";
 /**
@@ -43,7 +44,7 @@ const status = (e) => {
 /** Match a ref against known workspaces; `needRoot` excludes rootless live instances (start/forget need a root). */
 async function resolveRef(ref, needRoot = true) {
     const all = (await discoverWorkspaces()).filter((e) => e.root || !needRoot);
-    const abs = path.resolve(ref);
+    const abs = absolutePath(ref);
     const port = /^\d+$/.test(ref) ? `http://localhost:${ref}` : `http://${ref.replace(/^https?:\/\//, "")}`;
     const hits = all.filter((e) => e.root === abs ||
         e.root === ref ||

package/dist/cli/ui.js

@@ -4,7 +4,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn, spawnSync } from "node:child_process";
 import chalk from "chalk";
-import { resolveProject } from "../config.js";
+import { absolutePath, resolveProject } from "../config.js";
 import { selfCommand } from "../inspector/self-command.js";
 import { RESTART_EXIT_CODE, startInspector } from "../inspector/server.js";
 /**
@@ -52,7 +52,7 @@ export async function runUi(cwd, opts) {
         return superviseUi(opts);
     const staticDir = ensureBuilt();
     const project = await resolveProject(cwd);
-    const outputDir = opts.output ? path.resolve(cwd, opts.output) : project.outputDir;
+    const outputDir = opts.output ? absolutePath(opts.output, cwd) : project.outputDir;
     // Port precedence: --port flag > kraftwerk.yml `port` > 1981.
     const port = opts.port ? Number(opts.port) : (project.config.port ?? 1981);
     await startInspector({ outputDir, staticDir, port, projectRoot: project.root });

package/dist/config.d.ts

@@ -11,6 +11,7 @@
  *
  *   name: my-project           # display name (inspector header, "environment")
  *   icon: "⚡"                  # emoji shown as inspector favicon
+ *   color: "#c2410c"           # accent for this workspace in the switcher (default: derived from the root)
  *   port: 1981                 # port `kraftwerk ui` listens on
  *   workflows: src/workflows   # workflows root, relative to the file
  *   output: output             # run-artifact directory, relative to the file
@@ -88,6 +89,8 @@ export interface ProjectConfig {
     name?: string;
     /** Emoji used as the inspector favicon (browser-tab icon). */
     icon?: string;
+    /** Accent colour (#rgb / #rrggbb) for this workspace in the switcher. Default: derived from the root path. */
+    color?: string;
     /** Port `kraftwerk ui` listens on. Default: 1981 (CLI --port wins). */
     port?: number;
     /** Workflows root relative to the project root. */
@@ -120,6 +123,14 @@ export interface Project {
     outputDir: string;
 }
 /** True when the path exists and is a directory. */
+/**
+ * A user-supplied path as an absolute one: a leading `~` is the home
+ * directory (shells expand it, JSON bodies and quoted args do not), then
+ * path.resolve. Every path that gets stored or compared — registry roots,
+ * `--output`, project refs — goes through here so nothing ever persists
+ * `~/…` or `<cwd>/~/…`.
+ */
+export declare function absolutePath(p: string, from?: string): string;
 export declare const isDir: (p: string) => Promise<boolean>;
 /**
  * Resolve the project for a cwd: walk up until a kraftwerk.yml or a

package/dist/config.js

@@ -1,4 +1,5 @@
 import { readFile, stat } from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
 import { parse } from "yaml";
 /**
@@ -14,6 +15,7 @@ import { parse } from "yaml";
  *
  *   name: my-project           # display name (inspector header, "environment")
  *   icon: "⚡"                  # emoji shown as inspector favicon
+ *   color: "#c2410c"           # accent for this workspace in the switcher (default: derived from the root)
  *   port: 1981                 # port `kraftwerk ui` listens on
  *   workflows: src/workflows   # workflows root, relative to the file
  *   output: output             # run-artifact directory, relative to the file
@@ -63,6 +65,18 @@ export function gitignoreHas(text, entry) {
 }
 const exists = async (p) => !!(await stat(p).catch(() => null));
 /** True when the path exists and is a directory. */
+/**
+ * A user-supplied path as an absolute one: a leading `~` is the home
+ * directory (shells expand it, JSON bodies and quoted args do not), then
+ * path.resolve. Every path that gets stored or compared — registry roots,
+ * `--output`, project refs — goes through here so nothing ever persists
+ * `~/…` or `<cwd>/~/…`.
+ */
+export function absolutePath(p, from = process.cwd()) {
+    if (p === "~" || p.startsWith("~/") || p.startsWith("~\\"))
+        p = path.join(os.homedir(), p.slice(1));
+    return path.resolve(from, p);
+}
 export const isDir = async (p) => (await stat(p).catch(() => null))?.isDirectory() ?? false;
 async function findConfigFile(dir) {
     for (const name of CONFIG_FILENAMES) {
@@ -113,7 +127,7 @@ export async function resolveProject(cwd) {
     const root = gitFallback ?? start;
     return { root, config: {}, outputDir: path.join(root, "output") };
 }
-const KNOWN_KEYS = ["name", "icon", "port", "workflows", "output", "knowledge", "agents", "skills", "switcher", "git", "repos"];
+const KNOWN_KEYS = ["name", "icon", "color", "port", "workflows", "output", "knowledge", "agents", "skills", "switcher", "git", "repos"];
 async function loadConfig(configPath) {
     let raw;
     try {
@@ -138,6 +152,11 @@ async function loadConfig(configPath) {
                 throw new Error(`${path.basename(configPath)}: port must be an integer`);
             }
         }
+        else if (key === "color") {
+            if (typeof config[key] !== "string" || !/^#([0-9a-f]{3}|[0-9a-f]{6})$/i.test(config[key])) {
+                throw new Error(`${path.basename(configPath)}: color must be a hex colour like "#c2410c"`);
+            }
+        }
         else if (key === "switcher") {
             validateSwitcher(configPath, config[key]);
         }

package/dist/inspector/instances.d.ts

@@ -15,6 +15,10 @@ export interface DiscoveredInstance {
     name: string;
     url: string;
     icon?: string;
+    /** kraftwerk.yml `color`, if set. */
+    color?: string;
+    /** True when the name comes from kraftwerk.yml (false = folder name). */
+    named?: boolean;
     live: true;
     root?: string;
     /** Server process id (what to signal to stop it). */
@@ -29,6 +33,10 @@ export interface WorkspaceEntry {
     /** Where the inspector answers (live) or would answer once started. */
     url: string;
     icon?: string;
+    /** kraftwerk.yml `color`, if set; the UI derives one from the root otherwise. */
+    color?: string;
+    /** True when the name comes from kraftwerk.yml, false when it is just the folder name. */
+    named?: boolean;
     live: boolean;
     root?: string;
     /** Root with ~ for the home dir — what the UI prints. */

package/dist/inspector/instances.js

@@ -3,7 +3,7 @@ import { createHash } from "node:crypto";
 import fsSync, { promises as fs } from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { isDir, resolveProject } from "../config.js";
+import { absolutePath, isDir, resolveProject } from "../config.js";
 import { selfCommand } from "./self-command.js";
 /**
  * Two registries under ~/.kraftwerk, two lifecycles:
@@ -31,7 +31,7 @@ const LOGS_DIR = path.join(HOME, "logs");
 const selfFile = () => path.join(INSTANCES_DIR, `${process.pid}.json`);
 let selfPort = null;
 let selfRoot = null;
-const projectKey = (root) => createHash("sha1").update(path.resolve(root)).digest("hex").slice(0, 16);
+const projectKey = (root) => createHash("sha1").update(absolutePath(root)).digest("hex").slice(0, 16);
 const projectFile = (root) => path.join(PROJECTS_DIR, `${projectKey(root)}.json`);
 /** ~/… for display. */
 export const tildify = (p) => {
@@ -42,7 +42,7 @@ export const tildify = (p) => {
 /** Write this instance's registry file (call once the server listens). */
 export async function registerInstance(port, root) {
     selfPort = port;
-    selfRoot = path.resolve(root);
+    selfRoot = absolutePath(root);
     try {
         await fs.mkdir(INSTANCES_DIR, { recursive: true });
         const rec = { pid: process.pid, port, startedAt: new Date().toISOString(), root: selfRoot };
@@ -86,6 +86,8 @@ async function probeAt(host, port) {
             name: meta.projectName || `localhost:${port}`,
             url: `http://localhost:${port}`,
             icon: meta.projectIcon || undefined,
+            color: meta.projectColor || undefined,
+            named: typeof meta.projectNamed === "boolean" ? meta.projectNamed : undefined,
             live: true,
         };
     }
@@ -151,7 +153,7 @@ async function readProject(file) {
 }
 /** Upsert the project record for a root (call on every inspector start). */
 export async function registerProject(root) {
-    const abs = path.resolve(root);
+    const abs = absolutePath(root);
     const now = new Date().toISOString();
     try {
         await fs.mkdir(PROJECTS_DIR, { recursive: true });
@@ -232,7 +234,7 @@ export async function forgetProject(root) {
  * so without this check a stale record would wear its parent's identity.
  */
 async function describeRoot(root) {
-    const fallback = { name: path.basename(root), port: 1981, exists: false };
+    const fallback = { name: path.basename(root), named: false, port: 1981, exists: false };
     if (!(await isDir(root)))
         return fallback;
     try {
@@ -241,7 +243,9 @@ async function describeRoot(root) {
             return fallback;
         return {
             name: project.config.name ?? path.basename(project.root),
+            named: !!project.config.name,
             icon: project.config.icon || undefined,
+            color: project.config.color || undefined,
             port: project.config.port ?? 1981,
             exists: true,
         };
@@ -278,15 +282,29 @@ export async function discoverWorkspaces() {
         }
         if (running) {
             consumed.add(running);
-            return { ...base, name: running.name, url: running.url, icon: running.icon, live: true, exists: true };
+            // An instance from before 0.38 answers without color/named — read them from its root.
+            if (running.named === undefined)
+                d = await describeRoot(p.root);
+            return {
+                ...base,
+                name: running.name,
+                url: running.url,
+                icon: running.icon,
+                color: running.color ?? d?.color,
+                named: running.named ?? d?.named,
+                live: true,
+                exists: true,
+            };
         }
-        return { ...base, name: d.name, url: `http://localhost:${d.port}`, icon: d.icon, live: false, exists: d.exists };
+        return { ...base, name: d.name, url: `http://localhost:${d.port}`, icon: d.icon, color: d.color, named: d.named, live: false, exists: d.exists };
     }))).concat(await Promise.all(live
         .filter((i) => !consumed.has(i))
         .map(async (i) => ({
         name: i.name,
         url: i.url,
         icon: i.icon,
+        color: i.color,
+        named: i.named,
         live: true,
         root: i.root,
         rootLabel: i.root ? tildify(i.root) : undefined,
@@ -335,6 +353,8 @@ export async function listWorkspacesDetailed() {
         all.unshift({
             name: d.name,
             icon: d.icon,
+            color: d.color,
+            named: d.named,
             url: `http://localhost:${selfPort}`,
             live: true,
             root: selfRoot,
@@ -395,7 +415,7 @@ export async function listWorkspacesDetailed() {
  * straight to it.
  */
 export async function startProject(root) {
-    const abs = path.resolve(root);
+    const abs = absolutePath(root);
     const { name, port, exists } = await describeRoot(abs);
     if (!exists)
         return { ok: false, error: `not a project directory (missing or moved): ${abs}` };
@@ -464,12 +484,12 @@ export async function startProject(root) {
  * that registered no root. Waits up to ~5s for the port to go quiet.
  */
 export async function stopProject(target) {
-    if (target.root && path.resolve(target.root) === selfRoot) {
+    if (target.root && absolutePath(target.root) === selfRoot) {
         return { ok: false, error: "that is this workspace — stop it from its own terminal or pid" };
     }
     cache = wsCache = null;
     const live = await discoverInstances();
-    const inst = live.find((i) => (target.root && i.root === path.resolve(target.root)) || (target.url && i.url === target.url));
+    const inst = live.find((i) => (target.root && i.root === absolutePath(target.root)) || (target.url && i.url === target.url));
     if (!inst)
         return { ok: false, error: "not running" };
     try {

package/dist/inspector/server.js

@@ -213,6 +213,8 @@ async function handleApi(req, res, url) {
             restartable: supervised(),
             projectName,
             projectIcon: project?.config.icon ?? "",
+            projectColor: project?.config.color ?? "",
+            projectNamed: !!project?.config.name,
             projectRoot: project?.root ?? getProjectRoot(),
             projectRootLabel: tildify(project?.root ?? getProjectRoot()),
             git: (project?.config.git && project.config.git.enabled !== false) === true,

package/dist/inspector/settings.d.ts

@@ -20,6 +20,8 @@ export interface SaveSettingsInput {
     /** Omitted = untouched; empty string = remove the key. */
     name?: string;
     icon?: string;
+    /** Omitted = untouched; empty string = remove the key. Hex colour otherwise. */
+    color?: string;
     /** Omitted = untouched; empty list = remove the key. */
     switcher?: SwitcherEntry[];
     /** Omitted = untouched. See cleanGit for how the block is written. */

package/dist/inspector/settings.js

@@ -94,6 +94,13 @@ export async function saveSettings(input) {
         throw new Error("name must be a string");
     if (input.icon !== undefined && typeof input.icon !== "string")
         throw new Error("icon must be a string");
+    if (input.color !== undefined) {
+        if (typeof input.color !== "string")
+            throw new Error("color must be a string");
+        if (input.color.trim() && !/^#([0-9a-f]{3}|[0-9a-f]{6})$/i.test(input.color.trim())) {
+            throw new Error('color must be a hex colour like "#c2410c"');
+        }
+    }
     const switcher = input.switcher === undefined ? undefined : cleanSwitcher(input.switcher);
     const project = await resolveProject(getProjectRoot());
     const configPath = project.configPath ?? path.join(project.root, "kraftwerk.yml");
@@ -111,6 +118,7 @@ export async function saveSettings(input) {
     };
     setOrDelete("name", input.name?.trim());
     setOrDelete("icon", input.icon?.trim());
+    setOrDelete("color", input.color?.trim());
     setOrDelete("switcher", switcher);
     if (input.git !== undefined) {
         const git = cleanGit(input.git);