@netnodeag/kraftwerk 0.38.1 → 0.39.0

package/dist/cli/init.js

@@ -24,6 +24,7 @@ agents: ${DATA_DIR}/agents         # agent definitions
 skills: ${DATA_DIR}/skills         # workspace skills (shared instruction packages)
 # repos:                          # git repositories the agents work on (uncomment both lines to enable)
 #   root: ${DATA_DIR}/repos       # clones land here (git-ignored); a bare \`repos:\` uses repos/ instead
+# vibeables:                      # small apps built live in a chat with a preview pane (uncomment to enable; one folder per app under ${DATA_DIR}/vibeables, versioned with the workspace)
 `;
 const WORKFLOW_TEMPLATE = `# yaml-language-server: $schema=${SCHEMA_URL}
 name: hello

package/dist/cli/kraftwerk.js

@@ -14,6 +14,7 @@ import { runInit } from "./init.js";
 import { registerKnowledgeCommands } from "./knowledge.js";
 import { registerProjectCommands } from "./projects.js";
 import { registerRepoCommands } from "./repos.js";
+import { registerVibeableCommands } from "./vibeables.js";
 import { registerRoutineCommands } from "./routines.js";
 import { listRuns, showRun } from "./runs.js";
 import { runUi } from "./ui.js";
@@ -262,6 +263,7 @@ registerKnowledgeCommands(program);
 registerRoutineCommands(program);
 registerProjectCommands(program);
 registerRepoCommands(program);
+registerVibeableCommands(program);
 program
     .command("ui")
     .description("Start the inspector web UI for this project's runs and workflows")

package/dist/cli/vibeables.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerVibeableCommands(program: Command): void;

package/dist/cli/vibeables.js

@@ -0,0 +1,89 @@
+import chalk from "chalk";
+import Table from "cli-table3";
+import { createVibeable, deleteVibeable, listVibeables } from "../inspector/vibeables.js";
+import { fmtAgo } from "./projects.js";
+import { initContext as prepare } from "./routines.js";
+/**
+ * `kraftwerk vibeables` — the small apps built live in a chat, one folder
+ * each under the vibeables root (`vibeables.root` in kraftwerk.yml). The
+ * same module the inspector uses, so an app created here shows up in every
+ * chat's picker at once:
+ *
+ *   kraftwerk vibeables                    list: name, mode, state
+ *   kraftwerk vibeables create <name>      new app from the starter (index.html, vibeable.yml)
+ *   kraftwerk vibeables remove <name>      delete the folder (its history stays in the workspace git)
+ */
+const die = (msg) => {
+    console.error(chalk.red(msg));
+    process.exit(1);
+};
+export function registerVibeableCommands(program) {
+    const vibeables = program
+        .command("vibeables")
+        .description("Small apps built live in a chat: list, create one from the starter, remove");
+    vibeables
+        .command("list", { isDefault: true })
+        .description("List the apps under the vibeables root")
+        .option("--json", "Machine-readable output")
+        .action(async (opts) => {
+        await prepare();
+        const view = await listVibeables();
+        if (opts.json) {
+            console.log(JSON.stringify(view, null, 2));
+            return;
+        }
+        if (!view.enabled)
+            die(view.error ?? "vibeables are off");
+        if (view.vibeables.length === 0) {
+            console.log(chalk.dim(`No vibeables under ${view.root} yet — \`kraftwerk vibeables create <name>\` starts one.`));
+            return;
+        }
+        const table = new Table({
+            head: ["name", "mode", "state", "changed"].map((h) => chalk.bold(h)),
+            wordWrap: true,
+            colWidths: [24, 30, 22, 14],
+        });
+        for (const v of view.vibeables) {
+            table.push([
+                chalk.cyan(v.slug),
+                v.dev ? `dev: ${v.dev}` : "static",
+                v.configError ? chalk.red(v.configError) : v.hasIndex ? chalk.dim("ready") : chalk.yellow("no index.html yet"),
+                chalk.dim(fmtAgo(v.updatedAt)),
+            ]);
+        }
+        console.log(table.toString());
+        console.log(chalk.dim(view.root ?? ""));
+    });
+    vibeables
+        .command("create")
+        .description("Create an app folder from the starter (index.html, style.css, app.js, vibeable.yml)")
+        .argument("<name>", "Folder name under the root")
+        .option("--json", "Print the new entry as JSON")
+        .action(async (name, opts) => {
+        await prepare();
+        try {
+            const v = await createVibeable(name);
+            if (opts.json)
+                console.log(JSON.stringify(v, null, 2));
+            else
+                console.log(`${chalk.green("✔")} ${chalk.cyan(v.slug)} → ${v.path} ${chalk.dim("(open it from any chat with the vibeable button)")}`);
+        }
+        catch (err) {
+            die(err.message);
+        }
+    });
+    vibeables
+        .command("remove")
+        .description("Delete an app folder; its history stays in the workspace git")
+        .argument("<name>", "Folder name under the root")
+        .action(async (name) => {
+        await prepare();
+        try {
+            await deleteVibeable(name);
+            console.log(`${chalk.green("✔")} removed ${chalk.cyan(name)}`);
+        }
+        catch (err) {
+            die(err.message);
+        }
+    });
+}

package/dist/config.d.ts

@@ -28,6 +28,8 @@
  *     autosync: pull           # off | pull
  *   repos:                     # git repositories the agents work on (absent = off, bare key = on)
  *     root: kraftwerk-data/repos   # where clones land, relative to the file. Default: repos
+ *   vibeables:                 # small apps built live in a chat, rendered in the inspector (absent = off, bare key = on)
+ *     root: apps               # one folder per app, part of the workspace. Default: kraftwerk-data/vibeables
  */
 /** Stable, versionless URL of the workflow JSON schema (editor validation). */
 export declare const SCHEMA_URL = "https://raw.githubusercontent.com/NETNODEAG/kraftwerk/main/kraftwerk/schema/workflow.schema.json";
@@ -71,6 +73,22 @@ export declare const REPOS_DEFAULT_ROOT = "repos";
  * settings save and the module itself cannot disagree.
  */
 export declare function reposRootFor(project: Project): string | undefined;
+/**
+ * Vibeables: small applications the user builds live with an agent — a chat
+ * with a preview pane. Each is one folder under the root, plain files the
+ * inspector serves (or a dev command it runs). The root is part of the
+ * workspace and synced by the workspace git like agents and knowledge.
+ */
+export interface VibeablesConfig {
+    /** false keeps the block but turns the feature off. Default: true. */
+    enabled?: boolean;
+    /** Where the apps live, relative to the project root. Default: kraftwerk-data/vibeables */
+    root?: string;
+}
+/** Where vibeables live when `vibeables.root` is not set. */
+export declare const VIBEABLES_DEFAULT_ROOT = "kraftwerk-data/vibeables";
+/** Absolute vibeables root when the feature is on, undefined otherwise. */
+export declare function vibeablesRootFor(project: Project): string | undefined;
 /** A directory as a .gitignore entry: relative, forward slashes, no trailing slash; undefined outside the root. */
 export declare function ignoreEntryFor(projectRoot: string, dir: string): string | undefined;
 /** True when .gitignore text already covers the entry (with or without a leading or trailing slash). */
@@ -109,6 +127,8 @@ export interface ProjectConfig {
     git?: GitConfig;
     /** Repositories the agents work on. Absent = off. */
     repos?: ReposConfig;
+    /** Vibeables: apps built live in a chat. Absent = off. */
+    vibeables?: VibeablesConfig;
 }
 export interface Project {
     /** Absolute project root the CLI operates on. */

package/dist/config.js

@@ -32,6 +32,8 @@ import { parse } from "yaml";
  *     autosync: pull           # off | pull
  *   repos:                     # git repositories the agents work on (absent = off, bare key = on)
  *     root: kraftwerk-data/repos   # where clones land, relative to the file. Default: repos
+ *   vibeables:                 # small apps built live in a chat, rendered in the inspector (absent = off, bare key = on)
+ *     root: apps               # one folder per app, part of the workspace. Default: kraftwerk-data/vibeables
  */
 /** Stable, versionless URL of the workflow JSON schema (editor validation). */
 export const SCHEMA_URL = "https://raw.githubusercontent.com/NETNODEAG/kraftwerk/main/kraftwerk/schema/workflow.schema.json";
@@ -52,6 +54,15 @@ export function reposRootFor(project) {
         return undefined;
     return path.resolve(project.root, r.root ?? REPOS_DEFAULT_ROOT);
 }
+/** Where vibeables live when `vibeables.root` is not set. */
+export const VIBEABLES_DEFAULT_ROOT = "kraftwerk-data/vibeables";
+/** Absolute vibeables root when the feature is on, undefined otherwise. */
+export function vibeablesRootFor(project) {
+    const v = project.config.vibeables;
+    if (!v || v.enabled === false)
+        return undefined;
+    return path.resolve(project.root, v.root ?? VIBEABLES_DEFAULT_ROOT);
+}
 /** A directory as a .gitignore entry: relative, forward slashes, no trailing slash; undefined outside the root. */
 export function ignoreEntryFor(projectRoot, dir) {
     const rel = path.relative(projectRoot, path.resolve(projectRoot, dir)).split(path.sep).join("/");
@@ -127,7 +138,7 @@ export async function resolveProject(cwd) {
     const root = gitFallback ?? start;
     return { root, config: {}, outputDir: path.join(root, "output") };
 }
-const KNOWN_KEYS = ["name", "icon", "color", "port", "workflows", "output", "knowledge", "agents", "skills", "switcher", "git", "repos"];
+const KNOWN_KEYS = ["name", "icon", "color", "port", "workflows", "output", "knowledge", "agents", "skills", "switcher", "git", "repos", "vibeables"];
 async function loadConfig(configPath) {
     let raw;
     try {
@@ -171,7 +182,12 @@ async function loadConfig(configPath) {
         else if (key === "repos") {
             if (config[key] === null)
                 config[key] = {};
-            validateRepos(configPath, config[key]);
+            validateRootBlock(configPath, "repos", config[key]);
+        }
+        else if (key === "vibeables") {
+            if (config[key] === null)
+                config[key] = {};
+            validateRootBlock(configPath, "vibeables", config[key]);
         }
         else if (typeof config[key] !== "string") {
             throw new Error(`${path.basename(configPath)}: ${key} must be a string`);
@@ -232,26 +248,29 @@ function validateGit(configPath, value) {
         throw new Error(`${file}: git.autosync must be "off" or "pull"`);
     }
 }
-function validateRepos(configPath, value) {
+/**
+ * `repos` and `vibeables` share one shape: { enabled?, root? }. The root
+ * must never be the project itself or anything outside it — it is what
+ * remove/delete operate under, and what the workspace git may stage.
+ */
+function validateRootBlock(configPath, block, value) {
     const file = path.basename(configPath);
     if (typeof value !== "object" || value === null || Array.isArray(value)) {
-        throw new Error(`${file}: repos must be a mapping (enabled, root)`);
+        throw new Error(`${file}: ${block} must be a mapping (enabled, root)`);
     }
     const r = value;
     for (const key of Object.keys(r)) {
         if (!["enabled", "root"].includes(key)) {
-            throw new Error(`${file}: repos.${key} is unknown (allowed: enabled, root)`);
+            throw new Error(`${file}: ${block}.${key} is unknown (allowed: enabled, root)`);
         }
     }
     if (r.enabled !== undefined && typeof r.enabled !== "boolean") {
-        throw new Error(`${file}: repos.enabled must be true or false`);
+        throw new Error(`${file}: ${block}.enabled must be true or false`);
     }
     if (r.root !== undefined && (typeof r.root !== "string" || !r.root.trim())) {
-        throw new Error(`${file}: repos.root must be a non-empty string`);
+        throw new Error(`${file}: ${block}.root must be a non-empty string`);
     }
-    // The root is what `repos remove --force` deletes under, so it must never
-    // be the project itself or anything outside it.
     if (typeof r.root === "string" && !ignoreEntryFor(path.dirname(configPath), r.root.trim())) {
-        throw new Error(`${file}: repos.root must be a directory inside the project (not ".", ".." or an absolute path outside it)`);
+        throw new Error(`${file}: ${block}.root must be a directory inside the project (not ".", ".." or an absolute path outside it)`);
     }
 }

package/dist/inspector/chat/sessions.d.ts

@@ -18,6 +18,17 @@ export declare function getChat(id: string): Promise<{
 export declare function postMessage(id: string, text: string): Promise<{
     error?: string;
 }>;
+/**
+ * Open a vibeable in the chat (or close it with null). The agent's cwd
+ * becomes the app folder, so the running subprocess is dropped and the next
+ * message spawns one there with fresh context. Refused while a turn runs:
+ * the agent would keep editing in the old folder.
+ */
+export declare function setChatVibeable(id: string, slug: string | null): Promise<{
+    error?: string;
+    status?: number;
+    meta?: ChatMeta;
+}>;
 export declare function resolvePermission(id: string, requestId: string, optionId: string | null): Promise<{
     error?: string;
 }>;

package/dist/inspector/chat/sessions.js

@@ -7,6 +7,7 @@ import { listSkills, readSkill } from "../skills.js";
 import { listWorkflows } from "../workflows.js";
 import { getAgent, listAgents } from "../agents.js";
 import { listRepos } from "../repos.js";
+import { resolveVibeable, vibeableStatus, VIBEABLE_CONFIG_FILE } from "../vibeables.js";
 import { startAcpBackend } from "./acp.js";
 import { startPiBackend } from "./pi.js";
 import { appendEvent, listChatMetas, newChatId, readEvents, readMeta, safeChatDir, writeMeta, } from "./store.js";
@@ -168,6 +169,43 @@ async function reposContext() {
         `\`npx kraftwerk repos\` lists them, \`update <name>\` fetches and fast-forwards a clean clone, \`remove <name>\` ` +
         `deletes one. A repository the user mentions that is not listed is not cloned yet — offer to add it.`);
 }
+/**
+ * "## Vibeable" block: the chat has an app folder open in the preview pane.
+ * The agent works inside that folder, and everything it saves is what the
+ * user sees next — so the block spells out how the preview runs and what
+ * the sandbox rules out.
+ */
+async function vibeableContext(slug) {
+    const st = await vibeableStatus(slug).catch(() => null);
+    if (!st) {
+        return `## Vibeable\nThis chat had the vibeable "${slug}" open in its preview pane, but its folder is gone. Tell the user; do not recreate it unasked.`;
+    }
+    const dev = st.dev;
+    const mode = dev?.running
+        ? `A dev server is running (\`${dev.command}\`, port ${dev.port}${dev.ready ? "" : ", not answering yet"}); the pane shows it.`
+        : st.config.dev
+            ? `${VIBEABLE_CONFIG_FILE} declares \`dev: ${st.config.dev}\`; the dev server is not running, so the pane shows the static folder until the user starts it with the play button.`
+            : `No dev command: the pane shows the folder${st.config.dir ? ` ${st.config.dir}/` : ""} served as-is.`;
+    return (`## Vibeable: ${slug}\n` +
+        `You are building a small piece of software live with the user. Your working directory is its folder: ${st.path}. ` +
+        `The user sees it rendered in a preview pane next to this chat, and every file you save reloads that preview within a second — ` +
+        `work in small visible steps, and describe what changed instead of pasting code. Think ad-hoc software, not a website: a dashboard, ` +
+        `a slideshow, a calculator, a tracker with a backend — whatever the user asks for.\n\n` +
+        `Current state: ${mode}${st.configError ? ` (${st.configError} — fix it)` : ""}\n\n` +
+        `How the preview runs:\n` +
+        `- Static mode (default): the inspector serves the folder directly at /vibeables/${slug}/ — index.html is the entry; plain HTML, CSS and ` +
+        `JavaScript with no build step. Use relative URLs (./app.js, not /app.js). ES modules and CDN imports (https://esm.sh/<pkg>) work. ` +
+        `The static preview is a sandboxed document: no localStorage, no cookies, no calls into the inspector's own /api. Keep state in memory, ` +
+        `or move to dev mode when it must persist.\n` +
+        `- Dev mode: when the app needs a build tool, a backend or a database, write ${VIBEABLE_CONFIG_FILE} with \`dev: <command>\` ` +
+        `(e.g. \`npm run dev\`, \`node server.js\`, \`python3 -m http.server $PORT\`). kraftwerk starts it inside the folder with PORT in the ` +
+        `environment and the pane embeds that server; the command must listen on $PORT (or declare \`port:\` when it cannot). Optional ` +
+        `\`dir:\` picks the folder for static mode (e.g. dist). The app brings its own backend and storage — a small node server writing JSON ` +
+        `files, SQLite, an external API — nothing of that is provided by kraftwerk.\n\n` +
+        `Rules: the folder is part of this workspace and versioned with it — do not run git yourself, the user reviews and commits from the ` +
+        `inspector's Git screen; keep secrets out of the folder (.env is git-ignored, node_modules too); leave ${VIBEABLE_CONFIG_FILE} valid YAML; ` +
+        `when you switch the app to dev mode, say so and ask the user to press play in the pane. Reply briefly — the preview shows the result.`);
+}
 /** Base context per scope; scopeContext() appends the shared skills block. */
 async function baseScopeContext(scope, agent) {
     if (scope.kind === "agent") {
@@ -301,19 +339,22 @@ const RENDERING_BLOCK = `## Chat rendering\n` +
     `with ![alt](/api/runs/<run-id>/file?name=picture.png&raw=1), or link any artifact the same way. ` +
     `Prefer these relative /api/... URLs over file paths when showing results: they render directly ` +
     `in this chat and keep working wherever the inspector is reachable.`;
-async function scopeContext(scope, agent) {
+async function scopeContext(meta) {
+    const { scope, agent } = meta;
     // The repositories block reads every clone from git, so it runs alongside
     // the rest instead of adding its spawns to the first prompt's latency.
-    const [base, repos, skills] = await Promise.all([
+    const [base, repos, vibe, skills] = await Promise.all([
         baseScopeContext(scope, agent),
         scope.kind === "agent" || scope.kind === "kraftwerk" ? reposContext() : Promise.resolve(""),
+        meta.vibeable ? vibeableContext(meta.vibeable) : Promise.resolve(""),
         availableSkills(scope),
     ]);
-    return [base, repos, RENDERING_BLOCK, skillsBlock(skills)].filter(Boolean).join("\n\n");
+    return [base, repos, vibe, RENDERING_BLOCK, skillsBlock(skills)].filter(Boolean).join("\n\n");
 }
 /* ---------- backend lifecycle ---------- */
 /** Agent sessions carry the agent's model/effort; resolved live so edits apply to new backends. */
-async function backendTuning(scope, agent) {
+async function backendTuning(meta) {
+    const { scope, agent } = meta;
     const tuning = {};
     if (scope.kind === "agent") {
         const def = await getAgent(scope.slug).catch(() => null);
@@ -327,7 +368,8 @@ async function backendTuning(scope, agent) {
     }
     // Run chats live in the run folder — grant claude the project root so
     // project-level skills and files stay reachable.
-    if (scope.kind === "run" && agent === "claude")
+    // A vibeable session works inside the app folder for the same reason.
+    if ((scope.kind === "run" || meta.vibeable) && agent === "claude")
         tuning.addDirs = [getProjectRoot()];
     // pi loads skills only when told: hand it every visible skill folder.
     if (agent === "pi") {
@@ -365,7 +407,7 @@ async function ensureBackend(state) {
         },
     };
     const { agent, cwd } = state.meta;
-    const tuning = await backendTuning(state.meta.scope, agent);
+    const tuning = await backendTuning(state.meta);
     state.backend =
         agent === "pi"
             ? startPiBackend(cwd, hooks, tuning)
@@ -376,8 +418,10 @@ async function ensureBackend(state) {
     return state.backend;
 }
 /* ---------- public API (used by server.ts) ---------- */
+/** Where a chat's agent runs when no vibeable is open: the run folder for run chats, else the project root. */
+const defaultCwd = (scope) => (scope.kind === "run" ? safeRunDir(scope.runId) : getProjectRoot());
 export async function createChat(opts) {
-    const cwd = opts.scope.kind === "run" ? safeRunDir(opts.scope.runId) : getProjectRoot();
+    const cwd = defaultCwd(opts.scope);
     const now = new Date().toISOString();
     const meta = {
         id: newChatId(),
@@ -432,9 +476,7 @@ export async function postMessage(id, text) {
     void (async () => {
         try {
             const backend = await ensureBackend(state);
-            const context = state.needsContext
-                ? await scopeContext(state.meta.scope, state.meta.agent)
-                : "";
+            const context = state.needsContext ? await scopeContext(state.meta) : "";
             state.needsContext = false;
             // "/<skill> args" expands to the skill's instructions for the agent;
             // the thread keeps the short form the user typed.
@@ -461,6 +503,40 @@ export async function postMessage(id, text) {
     })();
     return {};
 }
+/**
+ * Open a vibeable in the chat (or close it with null). The agent's cwd
+ * becomes the app folder, so the running subprocess is dropped and the next
+ * message spawns one there with fresh context. Refused while a turn runs:
+ * the agent would keep editing in the old folder.
+ */
+export async function setChatVibeable(id, slug) {
+    const state = await loadState(id);
+    if (!state)
+        return { error: "not found", status: 404 };
+    if (state.busy)
+        return { error: "agent is still working — wait for the turn to finish", status: 409 };
+    if (slug) {
+        let dir;
+        try {
+            dir = (await resolveVibeable(slug)).dir;
+        }
+        catch (err) {
+            const msg = err.message;
+            return { error: msg, status: /^no vibeable/.test(msg) ? 404 : /are off/.test(msg) ? 409 : 400 };
+        }
+        state.meta.vibeable = slug;
+        state.meta.cwd = dir;
+    }
+    else {
+        delete state.meta.vibeable;
+        state.meta.cwd = defaultCwd(state.meta.scope);
+    }
+    state.meta.updatedAt = new Date().toISOString();
+    await writeMeta(state.meta);
+    dropBackend(state);
+    state.needsContext = true;
+    return { meta: state.meta };
+}
 export async function resolvePermission(id, requestId, optionId) {
     const state = await loadState(id);
     if (!state)

package/dist/inspector/chat/types.d.ts

@@ -27,6 +27,8 @@ export interface ChatMeta {
     title: string;
     cwd: string;
     scope: ChatScope;
+    /** Slug of the vibeable open in this chat's preview pane (cwd is its folder while set). */
+    vibeable?: string;
     createdAt: string;
     updatedAt: string;
 }

package/dist/inspector/git.js

@@ -1,7 +1,7 @@
 import { spawn } from "node:child_process";
 import { realpathSync } from "node:fs";
 import path from "node:path";
-import { reposRootFor, resolveProject } from "../config.js";
+import { reposRootFor, resolveProject, vibeablesRootFor } from "../config.js";
 import { ENV_FILE } from "../runner/docker.js";
 import { getOutputDir, getProjectRoot } from "./context.js";
 /**
@@ -190,7 +190,7 @@ async function checkedOut(repo) {
 }
 /**
  * The roots that may be committed, as repo-relative paths: the workflows,
- * knowledge, agents and skills roots this project declares, plus
+ * knowledge, agents, skills and vibeables roots this project declares, plus
  * kraftwerk.yml. The output directory is excluded even when it lives inside
  * one of them.
  */
@@ -217,6 +217,8 @@ function scopeFor({ project, repoRoot }) {
         path.resolve(project.root, project.config.knowledge ?? "knowledge"),
         path.resolve(project.root, project.config.agents ?? "agents"),
         path.resolve(project.root, project.config.skills ?? "skills"),
+        // Vibeables are the workspace's own apps: versioned with it, unlike clones.
+        vibeablesRootFor(project),
         project.configPath,
     ];
     const mapped = roots.filter((r) => !!r).map(rel).filter((r) => !!r);
@@ -393,7 +395,7 @@ export async function gitStatus(fresh = false) {
     const blocked = all.filter((f) => !f.syncable).sort(byPath);
     const blockedHidden = Math.max(0, blocked.length - MAX_BLOCKED);
     const scopeError = scope.wholeRepo
-        ? "A configured root points at the repository root, which would put the whole repo in scope. Narrow workflows/knowledge/agents/skills in kraftwerk.yml."
+        ? "A configured root points at the repository root, which would put the whole repo in scope. Narrow workflows/knowledge/agents/skills/vibeables in kraftwerk.yml."
         : undefined;
     const value = {
         ...base,

package/dist/inspector/mtime.d.ts

@@ -0,0 +1,3 @@
+export declare function newestMtime(dir: string, depth?: number, budget?: {
+    files: number;
+}): Promise<number>;

package/dist/inspector/mtime.js

@@ -0,0 +1,31 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+/**
+ * Newest mtime under a folder, for "changed 5m ago" on lists of folders. A
+ * directory's own mtime only moves when an entry is added or removed, not
+ * when a file inside is edited, so the walk looks at files. Bounded: git
+ * internals, dependencies and dot entries are skipped, depth is capped, and
+ * a huge tree stops early — the number is a hint, not an audit.
+ */
+const SKIP = /^(\.git|node_modules|\.cache|\.vite|\.next|vendor|dist|build|target)$/;
+export async function newestMtime(dir, depth = 0, budget = { files: 2_000 }) {
+    let newest = 0;
+    const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+    for (const e of entries) {
+        if (budget.files-- <= 0)
+            break;
+        if (SKIP.test(e.name) || e.name.startsWith("."))
+            continue;
+        const abs = path.join(dir, e.name);
+        if (e.isDirectory()) {
+            if (depth < 4)
+                newest = Math.max(newest, await newestMtime(abs, depth + 1, budget));
+        }
+        else {
+            const st = await fs.stat(abs).catch(() => null);
+            if (st)
+                newest = Math.max(newest, st.mtimeMs);
+        }
+    }
+    return newest;
+}

package/dist/inspector/repos.d.ts

@@ -37,6 +37,8 @@ export interface RepoInfo {
     ahead?: number;
     /** Commits on the upstream not here. Absent when the branch tracks nothing. */
     behind?: number;
+    /** Newest change in the working tree (.git, node_modules and dot entries excluded); lists sort by it. */
+    updatedAt?: string;
     /** Set when git could not be read for this folder. */
     error?: string;
 }

package/dist/inspector/repos.js

@@ -2,6 +2,7 @@ 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 { newestMtime } from "./mtime.js";
 import { git, gitNet, sshCommandFor } from "./git.js";
 /**
  * A clone is the one call here that can legitimately take long: a large
@@ -61,11 +62,14 @@ export async function openRepos() {
 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([
+    const [status, log, origin, newest] = 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),
+        newestMtime(dir),
     ]);
+    if (newest)
+        info.updatedAt = new Date(newest).toISOString();
     if (!status.ok)
         return { ...info, error: status.stderr || "not a git repository" };
     if (origin.ok)