@netnodeag/kraftwerk 0.36.0 → 0.37.0

package/dist/inspector/repos.d.ts

@@ -0,0 +1,118 @@
+import { type Project } from "../config.js";
+/**
+ * Repositories: the git clones an agent works on, kept under one root
+ * inside the project (`repos.root` in kraftwerk.yml, default repos/). The
+ * folder is the registry: whatever has a .git directory directly under the
+ * root is a repository, whoever put it there — this module, the CLI, or an
+ * agent running plain `git clone`. Everything shown about a clone is read
+ * from git on request, so nothing here can go stale.
+ *
+ * The root lives inside the project on purpose: chat sessions run in the
+ * project root, so every harness reaches the clones without extra grants.
+ * It must stay out of the workspace git: `kraftwerk init` ignores it, and
+ * the workspace sync never stages it.
+ *
+ * Like git.ts, every call passes an argument array (nothing reaches a
+ * shell), never prompts, and times out — a clone from a web UI must fail
+ * loudly, not park on a credential prompt nobody sees.
+ */
+export interface RepoInfo {
+    /** Folder name under the root; the id everywhere. */
+    slug: string;
+    /** Absolute path of the clone. */
+    path: string;
+    /** origin url, absent when the clone has no origin. */
+    url?: string;
+    /** Checked-out branch, or "HEAD" when detached. */
+    branch?: string;
+    /** Short hash of HEAD. */
+    head?: string;
+    /** Subject of the HEAD commit. */
+    subject?: string;
+    /** ISO timestamp of the HEAD commit. */
+    committedAt?: string;
+    /** Modified, added, deleted or untracked paths (porcelain count). */
+    dirty: number;
+    /** Commits not on the upstream, or not on any remote when the branch tracks nothing. Absent when git could not tell. */
+    ahead?: number;
+    /** Commits on the upstream not here. Absent when the branch tracks nothing. */
+    behind?: number;
+    /** Set when git could not be read for this folder. */
+    error?: string;
+}
+export interface ReposView {
+    enabled: boolean;
+    root?: string;
+    repos: RepoInfo[];
+    /** Set when the feature is on but unusable, or off. */
+    error?: string;
+}
+export interface AddRepoInput {
+    url: string;
+    name?: string;
+    branch?: string;
+    /** Shallow clone with this many commits of history (`git clone --depth`). */
+    depth?: number;
+}
+/**
+ * A clone is the one call here that can legitimately take long: a large
+ * repository on a slow link is minutes, not seconds. Prompts are already
+ * disabled (git.ts), so a long timeout only ever cuts a transfer that is
+ * still running, and the partial clone is deleted when it does.
+ */
+export declare const CLONE_TIMEOUT: number;
+export declare function safeRepoSlug(slug: string): string;
+/** "https://github.com/org/repo.git" → "repo"; "git@host:org/repo" → "repo". */
+export declare function slugFromUrl(url: string): string;
+/**
+ * The url git gets. `github:org/repo` is the same shorthand `--from`
+ * accepts. Anything starting with a dash would be read as an option, and
+ * empty is empty.
+ */
+export declare function cloneUrl(input: string): string;
+/** Resolve the project and its repos block. `off` when the feature is not on. */
+export declare function openRepos(): Promise<{
+    project?: Project;
+    root?: string;
+    off?: boolean;
+    error?: string;
+}>;
+/** Every clone under the root, alphabetically. Folders without .git are skipped. */
+export declare function listRepos(): Promise<ReposView>;
+/**
+ * Clone into <root>/<slug>. The folder is claimed with a plain mkdir first:
+ * it fails when anything is there already, whatever it is, and two adds of
+ * the same name racing each other cannot both win. Only what this call
+ * created is deleted when the clone fails.
+ */
+export declare function addRepo(input: AddRepoInput): Promise<RepoInfo>;
+/**
+ * Fetch, then fast-forward when the clone is behind and clean. Never merges:
+ * a diverged or dirty clone is reported, and the agent (or a terminal)
+ * sorts it out inside the repo.
+ */
+export declare function updateRepo(slug: string): Promise<{
+    ok: boolean;
+    error?: string;
+    off?: boolean;
+    repo?: RepoInfo;
+}>;
+/**
+ * Delete the clone. Refuses while it holds unpushed or uncommitted work, or
+ * while git cannot tell, unless forced: the clone may be the only copy.
+ */
+export declare function removeRepo(slug: string, force?: boolean): Promise<{
+    ok: boolean;
+    error?: string;
+    off?: boolean;
+    conflict?: boolean;
+}>;
+/**
+ * Make sure the root exists and is ignored by the workspace git: a clone
+ * inside a tracked tree shows up as an untracked gitlink for everyone.
+ * Best effort — a missing .gitignore is created, one that already covers
+ * the root is left alone. Runs before every clone as well as when the
+ * feature is switched on, so a root enabled by editing kraftwerk.yml is
+ * ignored by the time the first clone lands.
+ */
+export declare function ensureReposRoot(): Promise<void>;

package/dist/inspector/repos.js

@@ -0,0 +1,249 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { gitignoreHas, ignoreEntryFor, reposRootFor, resolveProject } from "../config.js";
+import { getProjectRoot } from "./context.js";
+import { git, gitNet, sshCommandFor } from "./git.js";
+/**
+ * A clone is the one call here that can legitimately take long: a large
+ * repository on a slow link is minutes, not seconds. Prompts are already
+ * disabled (git.ts), so a long timeout only ever cuts a transfer that is
+ * still running, and the partial clone is deleted when it does.
+ */
+export const CLONE_TIMEOUT = 30 * 60_000;
+const SLUG_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+export function safeRepoSlug(slug) {
+    if (!SLUG_RE.test(slug) || slug === "." || slug === "..")
+        throw new Error(`invalid repository name "${slug}"`);
+    return slug;
+}
+/** "https://github.com/org/repo.git" → "repo"; "git@host:org/repo" → "repo". */
+export function slugFromUrl(url) {
+    const last = url.replace(/[/:]+$/, "").split(/[/:]/).pop() ?? "";
+    const slug = last.replace(/\.git$/, "");
+    return safeRepoSlug(slug);
+}
+/**
+ * The url git gets. `github:org/repo` is the same shorthand `--from`
+ * accepts. Anything starting with a dash would be read as an option, and
+ * empty is empty.
+ */
+export function cloneUrl(input) {
+    const url = input.trim();
+    if (!url)
+        throw new Error("url is required");
+    if (url.startsWith("-"))
+        throw new Error(`invalid url "${url}"`);
+    const gh = /^github:([\w.-]+\/[\w.-]+?)(?:\.git)?\/?$/.exec(url);
+    if (gh)
+        return `https://github.com/${gh[1]}.git`;
+    return url;
+}
+/** Resolve the project and its repos block. `off` when the feature is not on. */
+export async function openRepos() {
+    let project;
+    try {
+        project = await resolveProject(getProjectRoot());
+    }
+    catch (err) {
+        return { error: err.message };
+    }
+    const root = reposRootFor(project);
+    if (!root)
+        return { off: true, error: "repositories are off (enable them in settings or add `repos:` to kraftwerk.yml)" };
+    return { project, root };
+}
+/**
+ * Everything about a clone in three git calls. `status --porcelain=v2
+ * --branch` carries the branch, its upstream, ahead/behind and the change
+ * list in one spawn; `log` the head; `remote` the origin. Only a branch
+ * without upstream costs one more call.
+ */
+async function inspect(root, slug) {
+    const dir = path.join(root, slug);
+    const info = { slug, path: dir, dirty: 0 };
+    const [status, log, origin] = await Promise.all([
+        git(["status", "--porcelain=v2", "--branch", "--untracked-files=normal"], dir),
+        git(["log", "-1", "--format=%h%x00%s%x00%cI"], dir),
+        git(["remote", "get-url", "origin"], dir),
+    ]);
+    if (!status.ok)
+        return { ...info, error: status.stderr || "not a git repository" };
+    if (origin.ok)
+        info.url = origin.stdout.trim();
+    if (log.ok) {
+        const [head, subject, committedAt] = log.stdout.trim().split("\0");
+        info.head = head;
+        info.subject = subject;
+        info.committedAt = committedAt;
+    }
+    let hasUpstream = false;
+    for (const line of status.stdout.split("\n")) {
+        if (!line.trim())
+            continue;
+        if (!line.startsWith("# ")) {
+            info.dirty++;
+            continue;
+        }
+        const [key, ...rest] = line.slice(2).split(" ");
+        const value = rest.join(" ");
+        if (key === "branch.head")
+            info.branch = value === "(detached)" ? "HEAD" : value;
+        else if (key === "branch.upstream")
+            hasUpstream = true;
+        else if (key === "branch.ab") {
+            const m = /^\+(\d+) -(\d+)$/.exec(value);
+            if (m) {
+                info.ahead = Number(m[1]);
+                info.behind = Number(m[2]);
+            }
+        }
+    }
+    if (!hasUpstream || info.ahead === undefined) {
+        // No upstream (a branch made locally, a detached HEAD): count what no
+        // remote has, so the remove guard still knows about unpushed work.
+        const local = await git(["rev-list", "--count", "HEAD", "--not", "--remotes"], dir);
+        if (local.ok && /^\d+$/.test(local.stdout.trim()))
+            info.ahead = Number(local.stdout.trim());
+    }
+    return info;
+}
+/** Every clone under the root, alphabetically. Folders without .git are skipped. */
+export async function listRepos() {
+    const opened = await openRepos();
+    if (!opened.root)
+        return { enabled: false, repos: [], error: opened.error };
+    const root = opened.root;
+    const entries = await fs.readdir(root, { withFileTypes: true }).catch(() => []);
+    const slugs = [];
+    for (const e of entries) {
+        if (!e.isDirectory() || !SLUG_RE.test(e.name))
+            continue;
+        if (await fs.stat(path.join(root, e.name, ".git")).catch(() => null))
+            slugs.push(e.name);
+    }
+    slugs.sort((a, b) => a.localeCompare(b));
+    const repos = await Promise.all(slugs.map((s) => inspect(root, s)));
+    return { enabled: true, root, repos };
+}
+const cloneError = (r) => (r.stderr || r.stdout || "git clone failed").split("\n").filter((l) => l.trim()).slice(-3).join(" ");
+/**
+ * Clone into <root>/<slug>. The folder is claimed with a plain mkdir first:
+ * it fails when anything is there already, whatever it is, and two adds of
+ * the same name racing each other cannot both win. Only what this call
+ * created is deleted when the clone fails.
+ */
+export async function addRepo(input) {
+    const opened = await openRepos();
+    if (!opened.root || !opened.project)
+        throw new Error(opened.error ?? "repositories are off");
+    const url = cloneUrl(input.url);
+    const slug = input.name?.trim() ? safeRepoSlug(input.name.trim()) : slugFromUrl(url);
+    const branch = input.branch?.trim();
+    if (branch && (branch.startsWith("-") || /\s/.test(branch)))
+        throw new Error(`invalid branch "${branch}"`);
+    if (input.depth !== undefined && (!Number.isInteger(input.depth) || input.depth < 1))
+        throw new Error(`invalid depth "${input.depth}"`);
+    const dest = path.join(opened.root, slug);
+    await prepareRoot(opened.project, opened.root);
+    try {
+        await fs.mkdir(dest);
+    }
+    catch (err) {
+        if (err.code === "EEXIST")
+            throw new Error(`"${slug}" already exists under ${opened.root}`);
+        throw err;
+    }
+    const args = [
+        "-c", "protocol.ext.allow=never", "clone",
+        ...(branch ? ["--branch", branch] : []),
+        ...(input.depth ? ["--depth", String(input.depth)] : []),
+        "--", url, dest,
+    ];
+    const r = await git(args, opened.root, CLONE_TIMEOUT, { GIT_SSH_COMMAND: await sshCommandFor(opened.project.root) });
+    if (!r.ok) {
+        await fs.rm(dest, { recursive: true, force: true }).catch(() => { });
+        throw new Error(cloneError(r));
+    }
+    return inspect(opened.root, slug);
+}
+/**
+ * Fetch, then fast-forward when the clone is behind and clean. Never merges:
+ * a diverged or dirty clone is reported, and the agent (or a terminal)
+ * sorts it out inside the repo.
+ */
+export async function updateRepo(slug) {
+    safeRepoSlug(slug);
+    const opened = await openRepos();
+    if (!opened.root)
+        return { ok: false, off: true, error: opened.error };
+    const dir = path.join(opened.root, slug);
+    if (!(await fs.stat(path.join(dir, ".git")).catch(() => null)))
+        return { ok: false, error: `no repository "${slug}"` };
+    const fetched = await gitNet(["fetch", "--prune"], dir);
+    if (!fetched.ok)
+        return { ok: false, error: fetched.stderr || "git fetch failed", repo: await inspect(opened.root, slug) };
+    let repo = await inspect(opened.root, slug);
+    if (repo.behind && !repo.ahead && repo.dirty === 0) {
+        const pulled = await git(["merge", "--ff-only", "@{upstream}"], dir);
+        if (!pulled.ok)
+            return { ok: false, error: pulled.stderr || "fast-forward failed", repo };
+        repo = await inspect(opened.root, slug);
+    }
+    else if (repo.behind && (repo.ahead || repo.dirty)) {
+        return { ok: true, error: repo.ahead ? "diverged from upstream, not fast-forwarded" : "local changes, not fast-forwarded", repo };
+    }
+    return { ok: true, repo };
+}
+/**
+ * Delete the clone. Refuses while it holds unpushed or uncommitted work, or
+ * while git cannot tell, unless forced: the clone may be the only copy.
+ */
+export async function removeRepo(slug, force = false) {
+    safeRepoSlug(slug);
+    const opened = await openRepos();
+    if (!opened.root)
+        return { ok: false, off: true, error: opened.error };
+    const dir = path.join(opened.root, slug);
+    if (!(await fs.stat(path.join(dir, ".git")).catch(() => null)))
+        return { ok: false, error: `no repository "${slug}"` };
+    if (!force) {
+        const repo = await inspect(opened.root, slug);
+        if (repo.error)
+            return { ok: false, conflict: true, error: `"${slug}" cannot be read (${repo.error}); remove it with --force` };
+        if (repo.dirty)
+            return { ok: false, conflict: true, error: `"${slug}" has ${repo.dirty} uncommitted change(s)` };
+        if (repo.ahead === undefined)
+            return { ok: false, conflict: true, error: `"${slug}": cannot tell whether it has unpushed commits; remove it with --force` };
+        if (repo.ahead)
+            return { ok: false, conflict: true, error: `"${slug}" has ${repo.ahead} unpushed commit(s)` };
+    }
+    await fs.rm(dir, { recursive: true, force: true });
+    return { ok: true };
+}
+/**
+ * Make sure the root exists and is ignored by the workspace git: a clone
+ * inside a tracked tree shows up as an untracked gitlink for everyone.
+ * Best effort — a missing .gitignore is created, one that already covers
+ * the root is left alone. Runs before every clone as well as when the
+ * feature is switched on, so a root enabled by editing kraftwerk.yml is
+ * ignored by the time the first clone lands.
+ */
+export async function ensureReposRoot() {
+    const project = await resolveProject(getProjectRoot());
+    const root = reposRootFor(project);
+    if (!root)
+        return;
+    await prepareRoot(project, root);
+}
+async function prepareRoot(project, root) {
+    await fs.mkdir(root, { recursive: true });
+    const entry = ignoreEntryFor(project.root, root);
+    if (!entry)
+        return;
+    const ignorePath = path.join(project.root, ".gitignore");
+    const existing = await fs.readFile(ignorePath, "utf8").catch(() => null);
+    if (existing !== null && gitignoreHas(existing, entry))
+        return;
+    const line = `${entry}/\n`;
+    await fs.writeFile(ignorePath, existing === null ? line : `${existing}${existing.endsWith("\n") ? "" : "\n"}${line}`).catch(() => { });
+}

package/dist/inspector/server.js

@@ -13,6 +13,7 @@ import { deleteAgentSkill, getSkill, listAgentSkills, listSkills, readSkill, sav
 import { discoverWorkspaces, forgetProject, listWorkspacesDetailed, markProjectStopped, registerInstance, registerProject, startProject, stopProject, tildify, unregisterInstance, } from "./instances.js";
 import { gitCommit, gitDiff, gitFetch, gitPull, gitPush, gitStatus, startGitSync, } from "./git.js";
 import { getSettings, saveSettings } from "./settings.js";
+import { addRepo, listRepos, openRepos, removeRepo, updateRepo } from "./repos.js";
 import { searchAgents } from "./search.js";
 import { deleteRoutine, routineStatuses, runRoutineNow, saveRoutine, startRoutineScheduler, } from "./routines.js";
 /**
@@ -215,6 +216,7 @@ async function handleApi(req, res, url) {
             projectRoot: project?.root ?? getProjectRoot(),
             projectRootLabel: tildify(project?.root ?? getProjectRoot()),
             git: (project?.config.git && project.config.git.enabled !== false) === true,
+            repos: (project?.config.repos && project.config.repos.enabled !== false) === true,
             switcher,
         });
     }
@@ -250,6 +252,46 @@ async function handleApi(req, res, url) {
         const result = await run();
         return json(res, result, result.ok ? 200 : 409);
     }
+    // GET /api/repos — every clone under the repos root, read live from git
+    if (seg.length === 2 && seg[1] === "repos" && method === "GET") {
+        return json(res, await listRepos());
+    }
+    // POST /api/repos {url, name?, branch?, depth?} — clone into the root
+    if (seg.length === 2 && seg[1] === "repos" && method === "POST") {
+        if ((await openRepos()).off)
+            return json(res, { error: "repositories are off" }, 409);
+        try {
+            const body = JSON.parse(await readBody(req));
+            const str = (v) => (typeof v === "string" ? v : undefined);
+            const depth = body.depth === undefined ? undefined : typeof body.depth === "number" ? body.depth : Number.NaN;
+            const repo = await addRepo({ url: str(body.url) ?? "", name: str(body.name), branch: str(body.branch), depth });
+            return json(res, repo, 201);
+        }
+        catch (err) {
+            return json(res, { error: err.message }, 400);
+        }
+    }
+    // POST /api/repos/<slug>/update — fetch, fast-forward when clean
+    if (seg.length === 4 && seg[1] === "repos" && seg[3] === "update" && method === "POST") {
+        try {
+            const result = await updateRepo(seg[2]);
+            return json(res, result, result.ok ? 200 : result.repo || result.off ? 409 : 404);
+        }
+        catch (err) {
+            return json(res, { error: err.message }, 400);
+        }
+    }
+    // DELETE /api/repos/<slug>[?force=1] — remove the clone; 409 while it holds unpushed or uncommitted work
+    if (seg.length === 3 && seg[1] === "repos" && method === "DELETE") {
+        try {
+            const force = ["1", "true"].includes(url.searchParams.get("force") ?? "");
+            const result = await removeRepo(seg[2], force);
+            return json(res, result, result.ok ? 200 : result.conflict || result.off ? 409 : 404);
+        }
+        catch (err) {
+            return json(res, { error: err.message }, 400);
+        }
+    }
     // GET /api/search/agents — active agents of every reachable workspace (the ⌘K palette)
     if (seg.length === 3 && seg[1] === "search" && seg[2] === "agents" && method === "GET") {
         return json(res, await searchAgents());
@@ -301,7 +343,7 @@ async function handleApi(req, res, url) {
     if (seg.length === 2 && seg[1] === "settings" && method === "GET") {
         return json(res, await getSettings());
     }
-    // PUT /api/settings — write the UI-editable subset (name, icon, switcher, git) back
+    // PUT /api/settings — write the UI-editable subset (name, icon, switcher, git, repos) back
     if (seg.length === 2 && seg[1] === "settings" && method === "PUT") {
         try {
             const input = JSON.parse(await readBody(req));

package/dist/inspector/settings.d.ts

@@ -1,7 +1,7 @@
 import { type ProjectConfig, type SwitcherEntry } from "../config.js";
 /**
  * Workspace settings: read kraftwerk.yml for the UI and write the
- * UI-editable subset (name, icon, switcher, git) back. Edits go through the
+ * UI-editable subset (name, icon, switcher, git, repos) back. Edits go through the
  * yaml Document API so comments and every other key survive untouched;
  * a missing kraftwerk.yml is created at the project root on first save.
  */
@@ -24,6 +24,12 @@ export interface SaveSettingsInput {
     switcher?: SwitcherEntry[];
     /** Omitted = untouched. See cleanGit for how the block is written. */
     git?: GitSettingsInput;
+    /** Omitted = untouched. Same rules as git: off with defaults = no block. */
+    repos?: ReposSettingsInput;
+}
+export interface ReposSettingsInput {
+    enabled: boolean;
+    root?: string;
 }
 /** The git form as the settings screen posts it. Every field but `enabled` may be blank. */
 export interface GitSettingsInput {

package/dist/inspector/settings.js

@@ -1,8 +1,9 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { parseDocument } from "yaml";
-import { resolveProject } from "../config.js";
+import { ignoreEntryFor, REPOS_DEFAULT_ROOT, resolveProject } from "../config.js";
 import { getProjectRoot } from "./context.js";
+import { ensureReposRoot } from "./repos.js";
 const GIT_DEFAULTS = { remote: "origin", interval: 300, autosync: "pull" };
 export async function getSettings() {
     const project = await resolveProject(getProjectRoot());
@@ -69,6 +70,25 @@ function cleanGit(value) {
         return null;
     return { enabled: false, ...out };
 }
+/** The repos block to write; null when the feature is off and nothing else is set. */
+function cleanRepos(value, projectRoot) {
+    if (typeof value !== "object" || value === null)
+        throw new Error("repos must be an object");
+    if (typeof value.enabled !== "boolean")
+        throw new Error("repos.enabled must be true or false");
+    const out = {};
+    const root = typeof value.root === "string" ? value.root.trim().replace(/\/+$/, "") : "";
+    if (root && !ignoreEntryFor(projectRoot, root)) {
+        throw new Error('repos.root must be a directory inside the project (not ".", ".." or an absolute path outside it)');
+    }
+    if (root && root !== REPOS_DEFAULT_ROOT)
+        out.root = root;
+    if (value.enabled)
+        return out;
+    if (Object.keys(out).length === 0)
+        return null;
+    return { enabled: false, ...out };
+}
 export async function saveSettings(input) {
     if (input.name !== undefined && typeof input.name !== "string")
         throw new Error("name must be a string");
@@ -99,6 +119,17 @@ export async function saveSettings(input) {
         else
             doc.set("git", git);
     }
+    if (input.repos !== undefined) {
+        const repos = cleanRepos(input.repos, project.root);
+        if (repos === null)
+            doc.delete("repos");
+        else
+            doc.set("repos", repos);
+    }
     await fs.writeFile(configPath, doc.toString());
+    // Turning repositories on prepares the folder so the first clone and the
+    // workspace git both find it in the right state.
+    if (input.repos?.enabled)
+        await ensureReposRoot().catch(() => { });
     return getSettings();
 }