@agent-native/core 0.85.7 → 0.86.0

package/dist/cli/design-connect.d.ts

@@ -1,6 +1,12 @@
 import { type Server } from "node:http";
-declare const BRIDGE_OPERATIONS: readonly ["select", "resolveNodeToFile", "readFile", "applyEdit", "writeFile", "captureSnapshot", "captureState"];
+declare const BRIDGE_OPERATIONS: readonly ["select", "resolveNodeToFile", "readFile", "applyEdit", "writeFile", "captureSnapshot", "captureState", "listFiles"];
 type BridgeOperation = (typeof BRIDGE_OPERATIONS)[number];
+/** Additive manifest capability flags advertised alongside the operation list. */
+declare const MANIFEST_CAPABILITIES: {
+    readonly listFiles: true;
+    readonly readTextFiles: true;
+    readonly writeTextFiles: true;
+};
 export interface DesignConnectArgs {
     url?: string;
     port: number;
@@ -42,6 +48,12 @@ export interface DesignConnectManifest {
         status: "available" | "planned" | "disabled";
         reason?: string;
     }>;
+    /**
+     * Additive high-level capability flags beyond the low-level operation list.
+     * `connect-localhost` persists this so `list-design-source-capabilities` can
+     * reflect readFile/writeFile/listFiles availability for localhost sources.
+     */
+    manifestCapabilities: typeof MANIFEST_CAPABILITIES;
 }
 export interface DesignConnectBridge {
     server: Server;
@@ -57,6 +69,42 @@ export declare function designConnectManifestsTargetSameApp(running: Pick<Design
 export declare function prepareDesignConnectManifest(options?: Partial<DesignConnectArgs> & {
     root?: string;
 }): Promise<DesignConnectManifest>;
+export interface GitignoreRule {
+    /** Raw pattern as read from .gitignore, already trimmed of comments/blank lines. */
+    pattern: string;
+    /** True when the pattern is anchored to the root (leading "/"). */
+    anchored: boolean;
+    /** True when the pattern only matches directories (trailing "/"). */
+    dirOnly: boolean;
+}
+/**
+ * Parse a simple subset of .gitignore syntax: exact names, `dir/`, `*.ext`,
+ * and leading-slash root-anchored patterns. This intentionally does not
+ * implement full gitignore glob semantics (double-star, negation, etc.) —
+ * good enough to keep obviously-ignored build output and local files out of
+ * the workbench file tree.
+ */
+export declare function parseGitignore(contents: string): GitignoreRule[];
+export declare function isIgnoredByGitignore(rules: GitignoreRule[], relPath: string, isDir: boolean): boolean;
+/**
+ * Pure predicate: should this file be excluded from /list-files results?
+ * Combines the always-ignored directory/file names, the parsed .gitignore
+ * rules, the binary-looking extension list, the secret-path blocklist, and
+ * the per-file size cap. `sizeBytes` may be omitted when unknown (the always/
+ * gitignore/binary/secret checks still apply).
+ */
+export declare function shouldExcludeFromListing(relPath: string, options: {
+    gitignore: GitignoreRule[];
+    sizeBytes?: number;
+}): boolean;
+export interface ListedBridgeFile {
+    path: string;
+    size: number;
+}
+export interface ListFilesResult {
+    files: ListedBridgeFile[];
+    truncated: boolean;
+}
 export declare function startDesignConnectBridge(manifest: DesignConnectManifest): Promise<DesignConnectBridge>;
 /**
  * Resolve the design app URL from an explicit value or environment variables.

package/dist/cli/design-connect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"design-connect.d.ts","sourceRoot":"","sources":["../../src/cli/design-connect.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"design-connect.d.ts","sourceRoot":"","sources":["../../src/cli/design-connect.ts"],"names":[],"mappings":"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"}

package/dist/cli/design-connect.js

@@ -22,7 +22,14 @@ const BRIDGE_OPERATIONS = [
     "writeFile",
     "captureSnapshot",
     "captureState",
+    "listFiles",
 ];
+/** Additive manifest capability flags advertised alongside the operation list. */
+const MANIFEST_CAPABILITIES = {
+    listFiles: true,
+    readTextFiles: true,
+    writeTextFiles: true,
+};
 function stringFlagValue(argv, index, flag) {
     const value = argv[index + 1];
     if (!value || value.startsWith("-")) {
@@ -382,6 +389,7 @@ export async function prepareDesignConnectManifest(options = {}) {
         routes,
         routeCount: routes.length,
         generatedAt,
+        manifestCapabilities: MANIFEST_CAPABILITIES,
         capabilities: BRIDGE_OPERATIONS.map((operation) => ({
             operation,
             status: "available",
@@ -474,6 +482,13 @@ async function readRequestBody(req) {
  * Resolve `targetDir` under `rootPath` with realpath so that symlinks and
  * traversal sequences (../../etc) cannot escape the root.  Throws if the
  * resolved path does not start with the resolved root.
+ *
+ * This also guards against a symlink LEAF inside root (e.g.
+ * `rootPath/link.css` -> `/Users/me/.ssh/id_rsa`): the parent-directory
+ * realpath check alone would pass confinement because the parent is inside
+ * root, letting reads/writes silently follow the symlink outside root. After
+ * the parent check we additionally lstat the target itself — if it exists and
+ * is a symlink, or if its realpath resolves outside `resolvedRoot`, we reject.
  */
 async function assertPathInside(rootPath, targetPath) {
     const resolvedRoot = await fs.realpath(rootPath).catch(() => {
@@ -502,15 +517,99 @@ async function assertPathInside(rootPath, targetPath) {
         resolvedParent !== resolvedRoot) {
         throw new Error(`Path traversal detected: resolved target is outside root`);
     }
+    // Reject a symlink LEAF, even though its parent directory is confined to
+    // root. A pre-existing symlink at the target path (file or directory) could
+    // otherwise be followed straight out of root by the caller's subsequent
+    // fs.readFile/fs.writeFile call.
+    const targetAbsolute = path.resolve(rootPath, targetPath);
+    const lstat = await fs.lstat(targetAbsolute).catch(() => null);
+    if (lstat?.isSymbolicLink()) {
+        throw new Error(`Path traversal detected: "${targetPath}" is a symlink, which is not allowed inside the connected root`);
+    }
+    if (lstat) {
+        const resolvedTarget = await fs.realpath(targetAbsolute).catch(() => null);
+        if (resolvedTarget &&
+            resolvedTarget !== resolvedRoot &&
+            !resolvedTarget.startsWith(resolvedRoot + path.sep)) {
+            throw new Error(`Path traversal detected: "${targetPath}" resolves outside the connected root`);
+        }
+    }
 }
 /** Allowed file extensions for write/apply-edit operations. */
-const ALLOWED_WRITE_EXTENSIONS = new Set([".html", ".htm", ".css"]);
+const ALLOWED_WRITE_EXTENSIONS = new Set([
+    ".html",
+    ".htm",
+    ".css",
+    ".scss",
+    ".less",
+    ".js",
+    ".jsx",
+    ".ts",
+    ".tsx",
+    ".mjs",
+    ".cjs",
+    ".json",
+    ".md",
+    ".mdx",
+    ".vue",
+    ".svelte",
+    ".astro",
+    ".txt",
+    ".yml",
+    ".yaml",
+    ".svg",
+]);
 function assertAllowedExtension(relPath) {
     const ext = path.extname(relPath).toLowerCase();
     if (!ALLOWED_WRITE_EXTENSIONS.has(ext)) {
-        throw new Error(`Write rejected: only .html, .htm, and .css files may be written via the bridge (got ${ext || "(no extension)"})`);
+        throw new Error(`Write rejected: extension "${ext || "(no extension)"}" is not in the allowed text-file list for bridge writes.`);
+    }
+}
+/**
+ * Blocklist for secret-looking paths. Applied to /read-file, /write-file,
+ * /apply-edit, AND /list-files so secrets are never returned or served
+ * through the bridge, even to a caller holding a valid write grant. Reads of
+ * other dotfiles (.gitignore, .prettierrc, etc.) remain allowed.
+ *
+ * All comparisons are case-insensitive: macOS's default filesystem (and
+ * Windows) is case-insensitive, so ".ENV", "ID_RSA", or "KEY.PEM" refer to
+ * the exact same on-disk file as their lowercase form and must be blocked
+ * identically.
+ */
+function isBlockedSecretPath(relPath) {
+    const normalized = normalizeSlash(relPath).replace(/^\/+/, "").toLowerCase();
+    const segments = normalized.split("/").filter(Boolean);
+    if (segments.some((segment) => segment === ".git"))
+        return true;
+    const basename = segments[segments.length - 1] ?? normalized;
+    if (/^\.env/.test(basename))
+        return true;
+    if (/\.pem$/.test(basename))
+        return true;
+    if (/\.key$/.test(basename))
+        return true;
+    if (/^id_rsa/.test(basename))
+        return true;
+    return false;
+}
+function assertNotBlockedSecretPath(relPath) {
+    if (isBlockedSecretPath(relPath)) {
+        throw new Error(`Access rejected: "${relPath}" matches a blocked secret-file pattern.`);
     }
 }
+/**
+ * Compute a cheap, stable version identifier for a file from its stat: mtime
+ * plus size. Not a content hash — it is only meant to detect "did this file
+ * change on disk since the caller last read it", the same tradeoff the inline
+ * (SQL-backed) workspace provider's versionHash already makes. Returns
+ * undefined when the file does not exist (new-file case).
+ */
+async function computeVersionHash(absolutePath) {
+    const stat = await fs.stat(absolutePath).catch(() => null);
+    if (!stat)
+        return undefined;
+    return `${stat.mtimeMs}-${stat.size}`;
+}
 function countOccurrences(haystack, needle) {
     if (!needle)
         return 0;
@@ -524,6 +623,258 @@ function countOccurrences(haystack, needle) {
     }
     return count;
 }
+// ── /list-files: recursive walk with .gitignore + always-ignore + size/binary
+// filtering ───────────────────────────────────────────────────────────────
+/** Directories always excluded from /list-files, regardless of .gitignore. */
+const ALWAYS_IGNORED_DIR_NAMES = new Set([
+    ".git",
+    "node_modules",
+    "dist",
+    "build",
+    ".next",
+    ".output",
+    ".nuxt",
+    "coverage",
+    ".cache",
+]);
+const ALWAYS_IGNORED_FILE_NAMES = new Set([".DS_Store"]);
+/** Binary-looking extensions skipped from /list-files results. */
+const BINARY_LOOKING_EXTENSIONS = new Set([
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".gif",
+    ".webp",
+    ".ico",
+    ".woff",
+    ".woff2",
+    ".ttf",
+    ".otf",
+    ".eot",
+    ".mp3",
+    ".mp4",
+    ".mov",
+    ".webm",
+    ".zip",
+    ".gz",
+    ".tar",
+    ".pdf",
+    ".wasm",
+    ".fig",
+    ".sketch",
+]);
+const LIST_FILES_MAX_ENTRIES = 20_000;
+const LIST_FILES_MAX_BYTES = 2 * 1024 * 1024;
+/**
+ * Parse a simple subset of .gitignore syntax: exact names, `dir/`, `*.ext`,
+ * and leading-slash root-anchored patterns. This intentionally does not
+ * implement full gitignore glob semantics (double-star, negation, etc.) —
+ * good enough to keep obviously-ignored build output and local files out of
+ * the workbench file tree.
+ */
+export function parseGitignore(contents) {
+    const rules = [];
+    for (const rawLine of contents.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        if (line.startsWith("!"))
+            continue; // negation unsupported in this subset
+        const anchored = line.startsWith("/");
+        const withoutAnchor = anchored ? line.slice(1) : line;
+        const dirOnly = withoutAnchor.endsWith("/");
+        const pattern = dirOnly ? withoutAnchor.slice(0, -1) : withoutAnchor;
+        if (!pattern)
+            continue;
+        rules.push({ pattern, anchored, dirOnly });
+    }
+    return rules;
+}
+function globToRegExp(pattern) {
+    let out = "";
+    for (const char of pattern) {
+        if (char === "*")
+            out += "[^/]*";
+        else if (char === "?")
+            out += "[^/]";
+        else
+            out += char.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    }
+    return new RegExp(`^${out}$`);
+}
+/**
+ * Test one path segment (or full relative path, for anchored patterns)
+ * against a parsed gitignore rule.
+ */
+function ruleMatches(rule, relPath, isDir) {
+    if (rule.dirOnly && !isDir)
+        return false;
+    const regex = globToRegExp(rule.pattern);
+    if (rule.anchored) {
+        return regex.test(relPath);
+    }
+    // Unanchored: match against any path segment (basename) or the full path,
+    // mirroring gitignore's "matches at any depth" behavior for simple patterns.
+    const segments = relPath.split("/");
+    return segments.some((segment) => regex.test(segment)) || regex.test(relPath);
+}
+export function isIgnoredByGitignore(rules, relPath, isDir) {
+    return rules.some((rule) => ruleMatches(rule, relPath, isDir));
+}
+/**
+ * Pure predicate: should this file be excluded from /list-files results?
+ * Combines the always-ignored directory/file names, the parsed .gitignore
+ * rules, the binary-looking extension list, the secret-path blocklist, and
+ * the per-file size cap. `sizeBytes` may be omitted when unknown (the always/
+ * gitignore/binary/secret checks still apply).
+ */
+export function shouldExcludeFromListing(relPath, options) {
+    const normalized = normalizeSlash(relPath).replace(/^\/+/, "");
+    const segments = normalized.split("/").filter(Boolean);
+    if (segments.some((segment) => ALWAYS_IGNORED_DIR_NAMES.has(segment))) {
+        return true;
+    }
+    const basename = segments[segments.length - 1] ?? normalized;
+    if (ALWAYS_IGNORED_FILE_NAMES.has(basename))
+        return true;
+    if (isBlockedSecretPath(normalized))
+        return true;
+    if (isIgnoredByGitignore(options.gitignore, normalized, false))
+        return true;
+    // A `dir/` gitignore rule matches the file's ancestor directories too, not
+    // just the file itself (e.g. "build-output/" must ignore
+    // "build-output/index.html").
+    for (let depth = 1; depth < segments.length; depth += 1) {
+        const ancestorPath = segments.slice(0, depth).join("/");
+        if (isIgnoredByGitignore(options.gitignore, ancestorPath, true)) {
+            return true;
+        }
+    }
+    const ext = path.extname(basename).toLowerCase();
+    if (BINARY_LOOKING_EXTENSIONS.has(ext))
+        return true;
+    if (typeof options.sizeBytes === "number" &&
+        options.sizeBytes > LIST_FILES_MAX_BYTES) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Should this directory be pruned entirely from the walk? Cheaper than
+ * checking every descendant file individually once a directory itself is
+ * ignored (always-ignored names, gitignore dir rules, or the .git/secret
+ * blocklist).
+ */
+function shouldPruneDirectory(relPath, gitignore) {
+    const normalized = normalizeSlash(relPath).replace(/^\/+/, "");
+    const segments = normalized.split("/").filter(Boolean);
+    const basename = segments[segments.length - 1] ?? normalized;
+    if (ALWAYS_IGNORED_DIR_NAMES.has(basename))
+        return true;
+    if (basename === ".git")
+        return true;
+    if (isIgnoredByGitignore(gitignore, normalized, true))
+        return true;
+    return false;
+}
+/**
+ * Recursively walk `rootPath`, honoring .gitignore + the always-ignore list +
+ * binary/size/secret filtering, never following symlinks that would escape
+ * root (delegates to `assertPathInside`'s realpath confinement per-entry).
+ * Caps at `LIST_FILES_MAX_ENTRIES` and reports `truncated` when the cap is
+ * hit.
+ */
+async function walkBridgeFiles(rootPath) {
+    let gitignore = [];
+    try {
+        const raw = await fs.readFile(path.join(rootPath, ".gitignore"), "utf8");
+        gitignore = parseGitignore(raw);
+    }
+    catch {
+        // No root .gitignore — proceed with only the always-ignore list.
+    }
+    const files = [];
+    let truncated = false;
+    const resolvedRoot = await fs.realpath(rootPath);
+    async function walk(absoluteDir, relDir) {
+        if (truncated)
+            return;
+        let entries;
+        try {
+            entries = await fs.readdir(absoluteDir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        // Sort for deterministic output.
+        entries.sort((a, b) => a.name.localeCompare(b.name));
+        for (const entry of entries) {
+            if (truncated)
+                return;
+            const relPath = relDir ? `${relDir}/${entry.name}` : entry.name;
+            const absolutePath = path.join(absoluteDir, entry.name);
+            if (entry.isSymbolicLink()) {
+                // Never follow symlinks that escape root; resolve and re-check.
+                let real;
+                try {
+                    real = await fs.realpath(absolutePath);
+                }
+                catch {
+                    continue;
+                }
+                if (real !== resolvedRoot &&
+                    !real.startsWith(resolvedRoot + path.sep)) {
+                    continue;
+                }
+                const stat = await fs.stat(absolutePath).catch(() => null);
+                if (!stat)
+                    continue;
+                if (stat.isDirectory()) {
+                    if (shouldPruneDirectory(relPath, gitignore))
+                        continue;
+                    await walk(absolutePath, relPath);
+                }
+                else if (stat.isFile()) {
+                    if (!shouldExcludeFromListing(relPath, {
+                        gitignore,
+                        sizeBytes: stat.size,
+                    })) {
+                        files.push({ path: normalizeSlash(relPath), size: stat.size });
+                        if (files.length >= LIST_FILES_MAX_ENTRIES) {
+                            truncated = true;
+                            return;
+                        }
+                    }
+                }
+                continue;
+            }
+            if (entry.isDirectory()) {
+                if (shouldPruneDirectory(relPath, gitignore))
+                    continue;
+                await walk(absolutePath, relPath);
+                continue;
+            }
+            if (entry.isFile()) {
+                const stat = await fs.stat(absolutePath).catch(() => null);
+                if (!stat)
+                    continue;
+                if (shouldExcludeFromListing(relPath, {
+                    gitignore,
+                    sizeBytes: stat.size,
+                })) {
+                    continue;
+                }
+                files.push({ path: normalizeSlash(relPath), size: stat.size });
+                if (files.length >= LIST_FILES_MAX_ENTRIES) {
+                    truncated = true;
+                    return;
+                }
+            }
+        }
+    }
+    await walk(resolvedRoot, "");
+    return { files, truncated };
+}
 export async function startDesignConnectBridge(manifest) {
     // Mint a cryptographically random per-rootPath bridge token.  This token is
     // kept in-process only and is never emitted via the public GET routes so that
@@ -588,7 +939,8 @@ export async function startDesignConnectBridge(manifest) {
         // ── Token-gated write endpoints (POST only) ───────────────────────────
         if (pathname === "/read-file" ||
             pathname === "/write-file" ||
-            pathname === "/apply-edit") {
+            pathname === "/apply-edit" ||
+            pathname === "/list-files") {
             if (req.method !== "POST") {
                 sendJson(res, 405, { ok: false, error: "method not allowed" });
                 return;
@@ -617,15 +969,35 @@ export async function startDesignConnectBridge(manifest) {
                 try {
                     const raw = await readRequestBody(req);
                     const body = JSON.parse(raw);
+                    if (pathname === "/list-files") {
+                        try {
+                            const result = await walkBridgeFiles(manifest.rootPath);
+                            sendJson(res, 200, {
+                                ok: true,
+                                files: result.files,
+                                truncated: result.truncated,
+                            });
+                        }
+                        catch (err) {
+                            sendJson(res, 500, {
+                                ok: false,
+                                error: `list-files failed: ${err instanceof Error ? err.message : String(err)}`,
+                            });
+                        }
+                        return;
+                    }
                     const relPath = typeof body["relPath"] === "string" ? body["relPath"] : undefined;
                     if (!relPath) {
                         sendJson(res, 400, { ok: false, error: "relPath is required" });
                         return;
                     }
                     await assertPathInside(manifest.rootPath, relPath);
+                    assertNotBlockedSecretPath(relPath);
                     const absolutePath = path.resolve(manifest.rootPath, relPath);
                     if (pathname === "/read-file") {
-                        // Read-file: no extension restriction — agents need to read any file.
+                        // Read-file: no extension restriction (agents need to read any
+                        // non-secret file), but the secret-path blocklist above still
+                        // applies to .env*, *.pem, *.key, id_rsa*, and anything under .git/.
                         let content;
                         try {
                             content = await fs.readFile(absolutePath, "utf8");
@@ -645,11 +1017,31 @@ export async function startDesignConnectBridge(manifest) {
                             }
                             return;
                         }
-                        sendJson(res, 200, { ok: true, content });
+                        const versionHash = await computeVersionHash(absolutePath);
+                        sendJson(res, 200, { ok: true, content, versionHash });
                         return;
                     }
-                    // write-file and apply-edit only allow .html/.htm/.css.
+                    // write-file and apply-edit only allow known text/code extensions.
                     assertAllowedExtension(relPath);
+                    // Optional optimistic-concurrency check: when the caller supplies
+                    // expectedVersionHash, compare it against the file's CURRENT hash
+                    // before writing. A missing file is treated as no-conflict (new
+                    // file case) so first-time writes always succeed.
+                    const expectedVersionHash = typeof body["expectedVersionHash"] === "string"
+                        ? body["expectedVersionHash"]
+                        : undefined;
+                    if (expectedVersionHash !== undefined) {
+                        const currentVersionHash = await computeVersionHash(absolutePath);
+                        if (currentVersionHash !== undefined &&
+                            currentVersionHash !== expectedVersionHash) {
+                            sendJson(res, 409, {
+                                ok: false,
+                                error: "version conflict",
+                                currentVersionHash,
+                            });
+                            return;
+                        }
+                    }
                     if (pathname === "/write-file") {
                         const content = typeof body["content"] === "string"
                             ? body["content"]
@@ -663,7 +1055,8 @@ export async function startDesignConnectBridge(manifest) {
                         }
                         await fs.mkdir(path.dirname(absolutePath), { recursive: true });
                         await fs.writeFile(absolutePath, content, "utf8");
-                        sendJson(res, 200, { ok: true, relPath });
+                        const versionHash = await computeVersionHash(absolutePath);
+                        sendJson(res, 200, { ok: true, relPath, versionHash });
                         return;
                     }
                     // /apply-edit: supports either full replace ({content}) or
@@ -674,7 +1067,13 @@ export async function startDesignConnectBridge(manifest) {
                         // distinguish intent.
                         await fs.mkdir(path.dirname(absolutePath), { recursive: true });
                         await fs.writeFile(absolutePath, body["content"], "utf8");
-                        sendJson(res, 200, { ok: true, relPath, method: "replace" });
+                        const versionHash = await computeVersionHash(absolutePath);
+                        sendJson(res, 200, {
+                            ok: true,
+                            relPath,
+                            method: "replace",
+                            versionHash,
+                        });
                         return;
                     }
                     const search = typeof body["search"] === "string" ? body["search"] : undefined;
@@ -732,7 +1131,13 @@ export async function startDesignConnectBridge(manifest) {
                     }
                     const updated = existing.replace(search, replace);
                     await fs.writeFile(absolutePath, updated, "utf8");
-                    sendJson(res, 200, { ok: true, relPath, method: "patch" });
+                    const versionHash = await computeVersionHash(absolutePath);
+                    sendJson(res, 200, {
+                        ok: true,
+                        relPath,
+                        method: "patch",
+                        versionHash,
+                    });
                 }
                 catch (err) {
                     sendJson(res, 500, {