@netnodeag/kraftwerk 0.48.0 → 0.49.0

package/dist/inspector/instances.js

@@ -14,25 +14,28 @@ import { selfCommand } from "./self-command.js";
  * Registered ports are verified by probing /api/meta on read; entries
  * that stop answering are pruned, so crashes leave no ghosts.
  *
- * projects/<hash(root)>.json — durable. One record per project root that
+ * workspaces/<hash(root)>.json — durable. One record per workspace root that
  * ever ran the inspector on this machine, keyed by the root and never
  * pruned automatically. Everything else (name, icon, port) is derived from
  * the root's kraftwerk.yml at read time, so it is always current. A
  * project that is not running can be started again from the switcher or
- * `kraftwerk projects start` — that is what makes a killed UI findable.
+ * `kraftwerk workspaces start` — that is what makes a killed UI findable.
  * The record also carries the project's agent roster (written whenever the
  * instance reads it), so the ⌘K palette can list every workspace's agents
  * from a handful of small files without probing anything.
  */
 const HOME = path.join(os.homedir(), ".kraftwerk");
 const INSTANCES_DIR = path.join(HOME, "instances");
-const PROJECTS_DIR = path.join(HOME, "projects");
+const WORKSPACES_DIR = path.join(HOME, "workspaces");
+/** Where the records lived before 0.49 (`kraftwerk projects`); moved over once, see migrateRegistry. */
+const LEGACY_WORKSPACES_DIR = path.join(HOME, "projects");
 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(absolutePath(root)).digest("hex").slice(0, 16);
-const projectFile = (root) => path.join(PROJECTS_DIR, `${projectKey(root)}.json`);
+/** File name of a root's record: a hash of the absolute root, the same under the old and the new directory. */
+export const workspaceRecordName = (root) => `${createHash("sha1").update(absolutePath(root)).digest("hex").slice(0, 16)}.json`;
+const recordFile = (root) => path.join(WORKSPACES_DIR, workspaceRecordName(root));
 /** ~/… for display. */
 export const tildify = (p) => {
     const home = os.homedir();
@@ -132,8 +135,38 @@ export async function discoverInstances() {
     cache = { at: Date.now(), entries };
     return entries;
 }
-/* ---------- projects (durable) ---------- */
-async function readProject(file) {
+/* ---------- workspaces (durable) ---------- */
+let migrated = null;
+/**
+ * Records were written under ~/.kraftwerk/projects until 0.48. Copy them
+ * into the new directory once per process, never overwriting a record
+ * that is already there, so a machine that upgrades keeps every workspace
+ * it knew. The old directory stays: an inspector of an older version may
+ * still be running and reading it. forgetWorkspace drops a record from
+ * both, so a forgotten workspace does not come back on the next start.
+ * Best-effort like everything else in this registry.
+ */
+function migrateRegistry() {
+    return (migrated ??= (async () => {
+        let legacy;
+        try {
+            legacy = await fs.readdir(LEGACY_WORKSPACES_DIR);
+        }
+        catch {
+            return;
+        }
+        try {
+            await fs.mkdir(WORKSPACES_DIR, { recursive: true });
+            for (const f of legacy) {
+                if (!f.endsWith(".json"))
+                    continue;
+                await fs.copyFile(path.join(LEGACY_WORKSPACES_DIR, f), path.join(WORKSPACES_DIR, f), fsSync.constants.COPYFILE_EXCL).catch(() => { });
+            }
+        }
+        catch { }
+    })());
+}
+async function readRecord(file) {
     try {
         const rec = JSON.parse(await fs.readFile(file, "utf8"));
         if (typeof rec.root !== "string")
@@ -153,12 +186,13 @@ async function readProject(file) {
     }
 }
 /** Upsert the project record for a root (call on every inspector start). */
-export async function registerProject(root) {
+export async function registerWorkspace(root) {
+    await migrateRegistry();
     const abs = absolutePath(root);
     const now = new Date().toISOString();
     try {
-        await fs.mkdir(PROJECTS_DIR, { recursive: true });
-        const prev = await readProject(projectFile(abs));
+        await fs.mkdir(WORKSPACES_DIR, { recursive: true });
+        const prev = await readRecord(recordFile(abs));
         const rec = {
             root: abs,
             firstSeen: prev?.firstSeen || now,
@@ -167,7 +201,7 @@ export async function registerProject(root) {
             ...(prev?.agents ? { agents: prev.agents } : {}),
             ...(prev?.channels ? { channels: prev.channels } : {}),
         };
-        await fs.writeFile(projectFile(abs), JSON.stringify(rec, null, 2));
+        await fs.writeFile(recordFile(abs), JSON.stringify(rec, null, 2));
     }
     catch { } // best-effort, like the instance file
 }
@@ -178,13 +212,14 @@ const synced = new Map();
  * changes when the list did. Roots with no record (a CLI run in a project
  * that never started the inspector) are left alone.
  */
-async function syncProjectList(root, key, list) {
+async function syncWorkspaceList(root, key, list) {
+    await migrateRegistry();
     const stamp = `${root}\n${JSON.stringify(list)}`;
     if (synced.get(key) === stamp)
         return;
     try {
-        const file = projectFile(root);
-        const rec = await readProject(file);
+        const file = recordFile(root);
+        const rec = await readRecord(file);
         if (!rec)
             return;
         await fs.writeFile(file, JSON.stringify({ ...rec, [key]: list }, null, 2));
@@ -192,41 +227,46 @@ async function syncProjectList(root, key, list) {
     }
     catch { }
 }
-export const syncProjectAgents = (root, agents) => syncProjectList(root, "agents", agents);
-export const syncProjectChannels = (root, channels) => syncProjectList(root, "channels", channels);
+export const syncWorkspaceAgents = (root, agents) => syncWorkspaceList(root, "agents", agents);
+export const syncWorkspaceChannels = (root, channels) => syncWorkspaceList(root, "channels", channels);
 /** Stamp lastStopped on clean shutdown. Sync so exit handlers can call it. */
-export function markProjectStopped() {
+export function markWorkspaceStopped() {
     if (!selfRoot)
         return;
     try {
-        const file = projectFile(selfRoot);
+        const file = recordFile(selfRoot);
         const rec = JSON.parse(fsSync.readFileSync(file, "utf8"));
         rec.lastStopped = new Date().toISOString();
         fsSync.writeFileSync(file, JSON.stringify(rec, null, 2));
     }
     catch { }
 }
-/** All known projects, most recently started first. */
-export async function listProjects() {
+/** All known workspaces, most recently started first. */
+export async function listWorkspaceRecords() {
+    await migrateRegistry();
     let files;
     try {
-        files = await fs.readdir(PROJECTS_DIR);
+        files = await fs.readdir(WORKSPACES_DIR);
     }
     catch {
         return [];
     }
-    const recs = await Promise.all(files.filter((f) => f.endsWith(".json")).map((f) => readProject(path.join(PROJECTS_DIR, f))));
+    const recs = await Promise.all(files.filter((f) => f.endsWith(".json")).map((f) => readRecord(path.join(WORKSPACES_DIR, f))));
     return recs
         .filter((r) => r != null)
         .sort((a, b) => b.lastStarted.localeCompare(a.lastStarted));
 }
-/** Drop a project record (the root itself is untouched). */
-export async function forgetProject(root) {
+/** Drop a workspace record (the root itself is untouched) — from the legacy directory too, see migrateRegistry. */
+export async function forgetWorkspace(root) {
+    await migrateRegistry();
+    const legacy = fs.unlink(path.join(LEGACY_WORKSPACES_DIR, workspaceRecordName(root))).catch(() => { });
     try {
-        await fs.unlink(projectFile(root));
+        await fs.unlink(recordFile(root));
+        await legacy;
         return true;
     }
     catch {
+        await legacy;
         return false;
     }
 }
@@ -268,7 +308,7 @@ let wsCache = null;
 export async function discoverWorkspaces() {
     if (wsCache && Date.now() - wsCache.at < 5_000)
         return wsCache.entries;
-    const [projects, live] = await Promise.all([listProjects(), discoverInstances()]);
+    const [projects, live] = await Promise.all([listWorkspaceRecords(), discoverInstances()]);
     const liveByRoot = new Map(live.filter((i) => i.root).map((i) => [i.root, i]));
     const consumed = new Set();
     const entries = (await Promise.all(projects
@@ -353,7 +393,7 @@ export async function listWorkspacesDetailed() {
     const all = [...others];
     if (selfRoot && selfPort) {
         const d = await describeRoot(selfRoot);
-        const rec = await readProject(projectFile(selfRoot));
+        const rec = await readRecord(recordFile(selfRoot));
         all.unshift({
             name: d.name,
             icon: d.icon,
@@ -373,7 +413,7 @@ export async function listWorkspacesDetailed() {
         const base = { ...e, current, state: e.live ? "running" : "stopped" };
         if (!e.root)
             return base;
-        const rec = await readProject(projectFile(e.root));
+        const rec = await readRecord(recordFile(e.root));
         base.firstSeen = rec?.firstSeen;
         base.startCount = rec?.startCount;
         // "missing" = the folder is gone; "orphaned" = it is still there but
@@ -418,7 +458,7 @@ export async function listWorkspacesDetailed() {
  * Waits up to ~5s for the new inspector to answer so callers can link
  * straight to it.
  */
-export async function startProject(root) {
+export async function startWorkspace(root) {
     const abs = absolutePath(root);
     const { name, port, exists } = await describeRoot(abs);
     if (!exists)
@@ -441,7 +481,7 @@ export async function startProject(root) {
     let stdio = ["ignore", "ignore", "ignore"];
     try {
         await fs.mkdir(LOGS_DIR, { recursive: true });
-        log = path.join(LOGS_DIR, `${projectKey(abs)}.log`);
+        log = path.join(LOGS_DIR, workspaceRecordName(abs).replace(/\.json$/, ".log"));
         const fd = fsSync.openSync(log, "a");
         fsSync.writeSync(fd, `\n--- ${new Date().toISOString()} start ${name} (${abs}) ---\n`);
         stdio = ["ignore", fd, fd];
@@ -487,7 +527,7 @@ export async function startProject(root) {
  * follows. Matched by root, or by url for instances from older versions
  * that registered no root. Waits up to ~5s for the port to go quiet.
  */
-export async function stopProject(target) {
+export async function stopWorkspace(target) {
     if (target.root && absolutePath(target.root) === selfRoot) {
         return { ok: false, error: "that is this workspace — stop it from its own terminal or pid" };
     }

package/dist/inspector/notifications.js

@@ -43,6 +43,8 @@ export function clipBody(text) {
 export function chatHref(meta) {
     if (meta.scope.kind === "channel")
         return `/channels/${meta.scope.slug}`;
+    if (meta.scope.kind === "project")
+        return `/projects/${meta.scope.slug}/chat/${meta.id}`;
     return meta.scope.kind === "agent" ? `/agents/${meta.scope.slug}/chat/${meta.id}` : `/agents/chats/${meta.id}`;
 }
 export async function pushNotification(input) {

package/dist/inspector/projects.d.ts

@@ -0,0 +1,167 @@
+import { type Project } from "../config.js";
+import type { ChatAgentId } from "./chat/types.js";
+/**
+ * Projects: a goal with everything the agents need to reach it gathered in
+ * one folder — the brief, the systems of record where the truth is managed
+ * outside kraftwerk, and links to the workspace's knowledge, vibeables,
+ * repositories, workflows and agents. Working in a project is chat: a
+ * session scoped to it carries all of this as context (sessions.ts).
+ *
+ * One folder per project under the projects root (`projects.root` in
+ * kraftwerk.yml, default kraftwerk-data/projects/). Like agents and
+ * knowledge it is part of the workspace: versioned by the workspace git,
+ * no repository of its own. The folder is the registry — whatever
+ * directory under the root holds a project.yml is a project.
+ *
+ *   projects/<slug>/project.yml   # title, status, goal, harness/model/effort, records, links (slug lists)
+ *   projects/<slug>/brief.md      # the goal in full: what done looks like, constraints, stakeholders
+ *   projects/<slug>/state.md      # current state, rewritten at the end of a session
+ *   projects/<slug>/log.md        # append-only: decisions, milestones (newest first, stamped)
+ *
+ * Links are one-directional lists of slugs; a target that does not exist
+ * is reported ("configured but not found"), never an error — the same
+ * rule agent knowledge follows. A system of record is context, not a
+ * credential and not a grant: it says where the truth lives and how it is
+ * usually reached, and the harness decides what the agent may call.
+ */
+export declare const PROJECT_FILE = "project.yml";
+export declare const PROJECT_STATUSES: readonly ["active", "paused", "done", "archived"];
+export type ProjectStatus = (typeof PROJECT_STATUSES)[number];
+/** Where truth is managed outside kraftwerk: a tool, a folder, a board. */
+export interface SystemOfRecord {
+    /** my-netnode | google-drive | github | bitbucket | notion | slack | url | anything else (rendered by name). */
+    kind: string;
+    /** Display name ("Figma board", "Contracts folder"). */
+    title?: string;
+    url?: string;
+    /** For tools with workspaces or boards: the id the agent needs (a my.netnode.ch workspace, a Slack channel). */
+    workspace?: string;
+    /** What lives there and how it is usually reached ("tickets and roadmap, `my` CLI"). */
+    note?: string;
+}
+/** What kraftwerk knows about a record kind: a label and what such a place usually holds. */
+export declare const RECORD_KINDS: Record<string, {
+    label: string;
+    hint: string;
+}>;
+export declare const LINK_KINDS: readonly ["knowledge", "vibeables", "repos", "workflows", "agents"];
+export type LinkKind = (typeof LINK_KINDS)[number];
+export interface ProjectDef {
+    slug: string;
+    title: string;
+    status: ProjectStatus;
+    /** One line: what the project is for. brief.md holds the long form. */
+    goal: string;
+    /** Harness every chat in the project runs on, like an agent's. Default: claude. */
+    harness: ChatAgentId;
+    /** Model for that harness; absent = the harness default. */
+    model?: string;
+    /** Reasoning effort (low … max); absent = the harness default. */
+    effort?: string;
+    records: SystemOfRecord[];
+    /** OKF bundle names. */
+    knowledge: string[];
+    /** Folder names under the vibeables root. */
+    vibeables: string[];
+    /** Folder names under the repos root. */
+    repos: string[];
+    /** Workflow slugs. */
+    workflows: string[];
+    /** Agent slugs. */
+    agents: string[];
+}
+export interface ProjectSummary extends ProjectDef {
+    /** Absolute folder path. */
+    path: string;
+    /** Newest change inside the folder. */
+    updatedAt?: string;
+    /** Set when project.yml exists but is unusable; the rest shows defaults. */
+    configError?: string;
+}
+/** One linked slug and whether its target exists right now. */
+export interface LinkState {
+    slug: string;
+    found: boolean;
+    /** Display name of the target when found (an agent's name, a workflow's description). */
+    label?: string;
+}
+export type ProjectLinks = Record<LinkKind, LinkState[]>;
+export interface ProjectDetail extends ProjectSummary {
+    brief: string;
+    state: string;
+    log: string;
+    links: ProjectLinks;
+}
+export interface ProjectsView {
+    enabled: boolean;
+    root?: string;
+    projects: ProjectSummary[];
+    /** Set when the feature is off or the root cannot be read. */
+    error?: string;
+}
+/** Every field optional: omitted = untouched. */
+export interface SaveProjectInput {
+    title?: string;
+    status?: string;
+    goal?: string;
+    harness?: string;
+    model?: string;
+    effort?: string;
+    records?: unknown;
+    knowledge?: unknown;
+    vibeables?: unknown;
+    repos?: unknown;
+    workflows?: unknown;
+    agents?: unknown;
+    brief?: string;
+    state?: string;
+}
+export declare function safeProjectSlug(slug: string): string;
+/** Derive a slug from a title: "Relaunch netnode.ch" -> "relaunch-netnode-ch". */
+export declare function projectSlugFromTitle(title: string): string;
+export declare function openProjects(): Promise<{
+    project?: Project;
+    root?: string;
+    off?: boolean;
+    error?: string;
+}>;
+/** Make sure the root exists; runs when the feature is switched on. */
+export declare function ensureProjectsRoot(): Promise<void>;
+/** Every project under the root: active ones first, then by title. */
+export declare function listProjects(): Promise<ProjectsView>;
+/** Which of the linked slugs exist right now, with a display label for the ones that do. */
+export declare function resolveLinks(def: ProjectDef): Promise<ProjectLinks>;
+/** One project with its files and link states; null when the folder is not a project. */
+export declare function getProject(slug: string): Promise<ProjectDetail | null>;
+/** The files a fresh project starts with. */
+export declare function projectStarter(def: ProjectDef): Record<string, string>;
+export declare function createProject(input: {
+    title: string;
+    goal?: string;
+    slug?: string;
+    harness?: string;
+    model?: string;
+    effort?: string;
+}): Promise<ProjectDetail>;
+/** Merge the given fields into project.yml (and brief/state when given); lists replace wholesale. */
+export declare function saveProject(slug: string, input: SaveProjectInput): Promise<ProjectDetail>;
+/** Add or remove one slug in a link list. */
+export declare function linkProject(slug: string, kind: string, target: string, remove?: boolean): Promise<ProjectDetail>;
+/**
+ * Prepend an entry under today's heading in log.md (newest first, like a
+ * knowledge bundle's log). The actor is stamped so a line written by an
+ * agent reads as such next to a human's.
+ */
+export declare function appendProjectLog(slug: string, entry: string, actor: string): Promise<string>;
+/** Remove the folder; its history stays in the workspace git. */
+export declare function deleteProject(slug: string): Promise<void>;
+/** One line per system of record: what it is, where, and what usually lives there. */
+export declare function recordLine(r: SystemOfRecord): string;
+/**
+ * The "## …" blocks a project chat starts with: brief, state, records,
+ * every link with how to reach it, and how to keep the project current.
+ * `actor` is stamped on log entries the agent writes.
+ */
+export declare function projectContext(slug: string, actor: string, opts?: {
+    member?: boolean;
+}): Promise<string>;