Skip to content

Write HTML. Render video. Built for agents.

feat(core): export findProjects to list the HyperFrames projects on a machine (#4627)

Miguel Ángele738e1026793
diff --git a/packages/core/package-subpaths.json b/packages/core/package-subpaths.json
index 472887c5aa..870ad5a1cf 100644
--- a/packages/core/package-subpaths.json
+++ b/packages/core/package-subpaths.json
@@ -110,6 +110,12 @@
"types": "./dist/compiler/index.d.ts",
"environments": ["bun", "node"]
},
+ "./projects": {
+ "source": "./src/projects.ts",
+ "runtime": "./dist/projects.js",
+ "types": "./dist/projects.d.ts",
+ "environments": ["bun", "node"]
+ },
"./audio-fx": {
"source": "./src/audioFx.ts",
"runtime": "./dist/audioFx.js",
diff --git a/packages/core/package.json b/packages/core/package.json
index e8f255e63f..ee7338da60 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -124,6 +124,12 @@
"import": "./src/compiler/index.ts",
"types": "./src/compiler/index.ts"
},
+ "./projects": {
+ "bun": "./src/projects.ts",
+ "node": "./dist/projects.js",
+ "import": "./src/projects.ts",
+ "types": "./src/projects.ts"
+ },
"./audio-fx": {
"bun": "./src/audioFx.ts",
"node": "./dist/audioFx.js",
@@ -512,6 +518,10 @@
"import": "./dist/compiler/index.js",
"types": "./dist/compiler/index.d.ts"
},
+ "./projects": {
+ "import": "./dist/projects.js",
+ "types": "./dist/projects.d.ts"
+ },
"./audio-fx": {
"import": "./dist/audioFx.js",
"types": "./dist/audioFx.d.ts"
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 2d159f18e6..5c8c3abfbf 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -276,6 +276,7 @@ export {
} from "./inline-scripts/parityContract";
export { redactKnownPaths, redactTelemetryString } from "./telemetryRedaction";
export { isSafePath, realpath, resolveWithinProject } from "./safePath";
+export { isHyperframesProject, PROJECT_MARKER_FILES } from "./projectRule";
export type {
HyperframePickerApi,
HyperframePickerBoundingBox,
diff --git a/packages/core/src/projectRule.test.ts b/packages/core/src/projectRule.test.ts
new file mode 100644
index 0000000000..9179af04d9
--- /dev/null
+++ b/packages/core/src/projectRule.test.ts
@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+import { isHyperframesProject } from "./projectRule";
+
+describe("isHyperframesProject", () => {
+ it.each(["hyperframes.json", "meta.json", "project.json"])(
+ "counts a folder with index.html and %s",
+ (marker) => {
+ expect(isHyperframesProject(["index.html", marker, "assets"])).toBe(true);
+ },
+ );
+
+ it("does not count index.html alone, or a marker without index.html", () => {
+ expect(isHyperframesProject(["index.html", "package.json"])).toBe(false);
+ expect(isHyperframesProject(["hyperframes.json", "README.md"])).toBe(false);
+ });
+});
diff --git a/packages/core/src/projectRule.ts b/packages/core/src/projectRule.ts
new file mode 100644
index 0000000000..732d37c4d2
--- /dev/null
+++ b/packages/core/src/projectRule.ts
@@ -0,0 +1,7 @@
+/** Files that `hyperframes init` or another HyperFrames tool writes at a project's root, next to its `index.html`. */
+export const PROJECT_MARKER_FILES = ["hyperframes.json", "meta.json", "project.json"] as const;
+
+export function isHyperframesProject(fileNames: Iterable<string>): boolean {
+ const names = new Set(fileNames);
+ return names.has("index.html") && PROJECT_MARKER_FILES.some((name) => names.has(name));
+}
diff --git a/packages/core/src/projects.test.ts b/packages/core/src/projects.test.ts
new file mode 100644
index 0000000000..242d9cbfa6
--- /dev/null
+++ b/packages/core/src/projects.test.ts
@@ -0,0 +1,237 @@
+import {
+ chmodSync,
+ mkdirSync,
+ mkdtempSync,
+ realpathSync,
+ rmSync,
+ symlinkSync,
+ writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join, relative, sep } from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { findProjects, type FoundProject } from "./projects";
+
+const roots: string[] = [];
+afterEach(() => {
+ vi.unstubAllEnvs();
+ for (const root of roots.splice(0)) {
+ chmodSync(root, 0o755);
+ rmSync(root, { recursive: true, force: true });
+ }
+});
+
+function tree(files: string[]): string {
+ const root = realpathSync.native(mkdtempSync(join(tmpdir(), "hf-find-projects-")));
+ roots.push(root);
+ for (const file of files) {
+ mkdirSync(join(root, file, ".."), { recursive: true });
+ writeFileSync(join(root, file), file.endsWith(".git") ? "gitdir: ../.git/modules/x" : "");
+ }
+ return root;
+}
+
+async function find(root: string, spotlight: string[] = []): Promise<FoundProject[]> {
+ const found: FoundProject[] = [];
+ await findProjects({
+ root,
+ onProject: (project) => found.push(project),
+ spotlight: async () => spotlight.map((path) => join(root, path)),
+ });
+ return found;
+}
+
+const paths = (root: string, found: FoundProject[]) =>
+ found.map((project) => relative(root, project.path).split(sep).join("/")).sort();
+
+describe("findProjects", () => {
+ it("finds a folder with index.html and a project marker, and nothing else", async () => {
+ const root = tree([
+ "film/index.html",
+ "film/meta.json",
+ "site/index.html",
+ "notes/project.json",
+ ]);
+
+ const found = await find(root);
+
+ expect(paths(root, found)).toEqual(["film"]);
+ expect(found[0]).toMatchObject({ name: "film", source: "walk" });
+ expect(Date.parse(found[0]!.mtime)).toBeGreaterThan(0);
+ });
+
+ it("skips node_modules and hidden folders", async () => {
+ const root = tree([
+ "app/node_modules/pkg/index.html",
+ "app/node_modules/pkg/project.json",
+ ".cache/film/index.html",
+ ".cache/film/meta.json",
+ ]);
+
+ expect(await find(root)).toEqual([]);
+ });
+
+ it("skips a git worktree copy but walks a submodule", async () => {
+ const root = tree([
+ "repo-copy/film/index.html",
+ "repo-copy/film/meta.json",
+ "vendor/sub/.git",
+ "vendor/sub/film/index.html",
+ "vendor/sub/film/hyperframes.json",
+ ]);
+ writeFileSync(join(root, "repo-copy", ".git"), "gitdir: /src/repo/.git/worktrees/repo-copy\n");
+
+ expect(paths(root, await find(root))).toEqual(["vendor/sub/film"]);
+ });
+
+ it("skips Library in the home folder but not a folder named Library elsewhere", async () => {
+ const root = tree([
+ "Library/film/index.html",
+ "Library/film/meta.json",
+ "Movies/Library/film/index.html",
+ "Movies/Library/film/meta.json",
+ ]);
+ vi.stubEnv("HOME", root + sep);
+ vi.stubEnv("USERPROFILE", root + sep);
+
+ const found = await find(root, ["Library/film/meta.json", "Movies/Library/film/meta.json"]);
+
+ expect(paths(root, found)).toEqual(["Movies/Library/film"]);
+ });
+
+ it("searches the home folder when no root is given", async () => {
+ const root = tree(["film/index.html", "film/meta.json"]);
+ vi.stubEnv("HOME", root);
+ vi.stubEnv("USERPROFILE", root);
+ const found: FoundProject[] = [];
+
+ await findProjects({ onProject: (project) => found.push(project), spotlight: async () => [] });
+
+ expect(paths(root, found)).toEqual(["film"]);
+ });
+
+ it("stops reporting and rejects once its signal is aborted", async () => {
+ const root = tree(
+ Array.from({ length: 200 }, (_, i) => [`f${i}/index.html`, `f${i}/meta.json`]).flat(),
+ );
+ const controller = new AbortController();
+ const found: FoundProject[] = [];
+ const search = findProjects({
+ root,
+ signal: controller.signal,
+ spotlight: async () => [],
+ onProject: (project) => {
+ found.push(project);
+ controller.abort();
+ },
+ });
+
+ await expect(search).rejects.toMatchObject({ name: "AbortError" });
+ expect(found).toHaveLength(1);
+ });
+
+ it("stops the search when onProject throws", async () => {
+ const root = tree(
+ Array.from({ length: 200 }, (_, i) => [`f${i}/index.html`, `f${i}/meta.json`]).flat(),
+ );
+ const onProject = vi.fn(() => {
+ throw new Error("list is closed");
+ });
+
+ await expect(findProjects({ root, onProject, spotlight: async () => [] })).rejects.toThrow(
+ "list is closed",
+ );
+ expect(onProject).toHaveBeenCalledTimes(1);
+ });
+
+ it("does not start when its signal is already aborted", async () => {
+ const onProject = vi.fn();
+ const search = findProjects({
+ root: join(tree([]), "missing"),
+ onProject,
+ signal: AbortSignal.abort(),
+ });
+
+ await expect(search).rejects.toMatchObject({ name: "AbortError" });
+ expect(onProject).not.toHaveBeenCalled();
+ });
+
+ it("does not look for projects inside a project", async () => {
+ const root = tree([
+ "film/index.html",
+ "film/hyperframes.json",
+ "film/compositions/intro/index.html",
+ "film/compositions/intro/meta.json",
+ ]);
+
+ expect(paths(root, await find(root))).toEqual(["film"]);
+ });
+
+ it("searches a root that is itself a git worktree copy", async () => {
+ const root = tree(["film/index.html", "film/meta.json"]);
+ writeFileSync(join(root, ".git"), "gitdir: /src/repo/.git/worktrees/copy\n");
+
+ expect(paths(root, await find(root))).toEqual(["film"]);
+ });
+
+ it.skipIf(process.platform === "win32" || process.getuid?.() === 0)(
+ "finishes past a symlink loop and an unreadable folder",
+ async () => {
+ const root = tree([
+ "film/index.html",
+ "film/meta.json",
+ "locked/film/index.html",
+ "locked/film/meta.json",
+ ]);
+ symlinkSync(root, join(root, "loop"), "dir");
+ chmodSync(join(root, "locked"), 0o000);
+
+ try {
+ expect(paths(root, await find(root))).toEqual(["film"]);
+ } finally {
+ chmodSync(join(root, "locked"), 0o755);
+ }
+ },
+ );
+
+ it("fails on a root that is missing or not a folder instead of finding nothing", async () => {
+ const root = tree(["file.txt"]);
+ await expect(find(join(root, "missing"))).rejects.toMatchObject({ code: "ENOENT" });
+ await expect(find(join(root, "file.txt"))).rejects.toMatchObject({ code: "ENOTDIR" });
+ });
+
+ it.skipIf(process.platform === "win32" || process.getuid?.() === 0)(
+ "fails on a root it may not read instead of finding nothing",
+ async () => {
+ const root = tree([]);
+ chmodSync(root, 0o000);
+ await expect(find(root)).rejects.toMatchObject({ code: "EACCES" });
+ },
+ );
+
+ it("reports a Spotlight hit once, and only where the walk would also count it", async () => {
+ const root = tree([
+ "film/index.html",
+ "film/meta.json",
+ "film/compositions/intro/index.html",
+ "film/compositions/intro/meta.json",
+ "app/node_modules/pkg/index.html",
+ "app/node_modules/pkg/project.json",
+ "repo-copy/film/index.html",
+ "repo-copy/film/meta.json",
+ "readme/meta.json",
+ ]);
+ writeFileSync(join(root, "repo-copy", ".git"), "gitdir: /src/repo/.git/worktrees/repo-copy\n");
+
+ const found = await find(root, [
+ "film/meta.json",
+ "film/compositions/intro/meta.json",
+ "app/node_modules/pkg/project.json",
+ "repo-copy/film/meta.json",
+ "readme/meta.json",
+ "../elsewhere/meta.json",
+ ]);
+
+ expect(paths(root, found)).toEqual(["film"]);
+ });
+});
diff --git a/packages/core/src/projects.ts b/packages/core/src/projects.ts
new file mode 100644
index 0000000000..636f67540d
--- /dev/null
+++ b/packages/core/src/projects.ts
@@ -0,0 +1,179 @@
+import { execFile } from "node:child_process";
+import type { Dirent } from "node:fs";
+import { readFile, readdir, realpath, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, relative, sep } from "node:path";
+import { isHyperframesProject, PROJECT_MARKER_FILES } from "./projectRule";
+
+export { isHyperframesProject, PROJECT_MARKER_FILES };
+
+export interface FoundProject {
+ path: string;
+ name: string;
+ source: "spotlight" | "walk";
+ mtime: string;
+}
+
+export interface FindProjectsOptions {
+ /** Defaults to the home folder. */
+ root?: string;
+ onProject: (project: FoundProject) => void;
+ /** Stops the search: no `onProject` call after it fires, and the promise rejects with its reason. */
+ signal?: AbortSignal;
+ /** Paths of marker files already indexed under `root`; defaults to Spotlight on macOS. */
+ spotlight?: (root: string, signal?: AbortSignal) => Promise<string[]>;
+}
+
+const WALK_CONCURRENCY = 64;
+
+async function readEntries(dir: string): Promise<Dirent[] | null> {
+ try {
+ return await readdir(dir, { withFileTypes: true });
+ } catch {
+ return null;
+ }
+}
+
+/** A linked git worktree: its `.git` is a file naming a folder under the main repo's `.git/worktrees/`. */
+async function isWorktreeCopy(dir: string, entries: Dirent[]): Promise<boolean> {
+ if (!entries.some((entry) => entry.name === ".git" && entry.isFile())) return false;
+ const gitFile = await readFile(join(dir, ".git"), "utf8").catch(() => "");
+ return /[\\/]worktrees[\\/]/.test(gitFile);
+}
+
+const fileNames = (entries: Dirent[]) =>
+ entries.filter((entry) => !entry.isDirectory()).map((entry) => entry.name);
+
+function spotlightMarkers(root: string, signal?: AbortSignal): Promise<string[]> {
+ if (process.platform !== "darwin") return Promise.resolve([]);
+ const query = PROJECT_MARKER_FILES.map((name) => `kMDItemFSName == "${name}"`).join(" || ");
+ return new Promise((resolve) => {
+ execFile(
+ "mdfind",
+ ["-onlyin", root, query],
+ { timeout: 10_000, maxBuffer: 64 * 1024 * 1024, signal },
+ (error, stdout) => resolve(error ? [] : stdout.split("\n").filter(Boolean)),
+ );
+ });
+}
+
+/** Rejects with the file system error when `root` itself cannot be read; unreadable folders below it are skipped. */
+export async function findProjects({
+ root: givenRoot = homedir(),
+ onProject,
+ signal,
+ spotlight = spotlightMarkers,
+}: FindProjectsOptions): Promise<number> {
+ signal?.throwIfAborted();
+ const root = await realpath(givenRoot).catch(() => givenRoot);
+ await readdir(root);
+ const home = await realpath(homedir()).catch(() => homedir());
+ const skippedDir = (parent: string, name: string) =>
+ name.startsWith(".") || name === "node_modules" || (name === "Library" && parent === home);
+ const reported = new Set<string>();
+ let onProjectThrew = false;
+ const stopped = () => onProjectThrew || signal?.aborted;
+ const entriesByDir = new Map<string, Promise<Dirent[] | null>>();
+ const entriesOf = (dir: string) => {
+ let entries = entriesByDir.get(dir);
+ if (!entries) entriesByDir.set(dir, (entries = readEntries(dir)));
+ return entries;
+ };
+
+ async function report(dir: string, source: FoundProject["source"]) {
+ const real = await realpath(dir).catch(() => dir);
+ if (reported.has(real)) return;
+ reported.add(real);
+ const index = await stat(join(dir, "index.html")).catch(() => null);
+ if (stopped()) return;
+ try {
+ onProject({
+ path: dir,
+ name: basename(dir),
+ source,
+ mtime: (index?.mtime ?? new Date(0)).toISOString(),
+ });
+ } catch (error) {
+ onProjectThrew = true;
+ throw error;
+ }
+ }
+
+ async function walk() {
+ const pending = [root];
+ let active = 0;
+ let failure: unknown;
+ const visit = async (dir: string) => {
+ const entries = await readEntries(dir);
+ if (!entries || (dir !== root && (await isWorktreeCopy(dir, entries)))) return;
+ if (isHyperframesProject(fileNames(entries))) return report(dir, "walk");
+ for (const entry of entries) {
+ if (entry.isDirectory() && !skippedDir(dir, entry.name))
+ pending.push(join(dir, entry.name));
+ }
+ };
+ await new Promise<void>((done) => {
+ const pump = () => {
+ while (active < WALK_CONCURRENCY && pending.length > 0 && !stopped()) {
+ active++;
+ void visit(pending.pop()!)
+ .catch((error: unknown) => {
+ failure ??= error;
+ })
+ .finally(() => {
+ active--;
+ pump();
+ });
+ }
+ if (active === 0 && (pending.length === 0 || stopped())) done();
+ };
+ pump();
+ });
+ if (failure) throw failure;
+ }
+
+ // Folder names from the root down to `dir`, or null if the walk would skip one of them by name.
+ function namesBelowRoot(dir: string): string[] | null {
+ const inside = relative(root, dir);
+ if (inside.startsWith("..") || isAbsolute(inside)) return null;
+ const names = inside === "" ? [] : inside.split(sep);
+ let parent = root;
+ for (const name of names) {
+ if (skippedDir(parent, name)) return null;
+ parent = join(parent, name);
+ }
+ return names;
+ }
+
+ async function walkStopsAt(dir: string): Promise<boolean> {
+ const entries = await entriesOf(dir);
+ return !entries || (dir !== root && (await isWorktreeCopy(dir, entries)));
+ }
+
+ async function walkWouldReach(dir: string): Promise<boolean> {
+ const names = namesBelowRoot(dir);
+ if (!names) return false;
+ let current = root;
+ for (const name of names) {
+ if (await walkStopsAt(current)) return false;
+ if (isHyperframesProject(fileNames((await entriesOf(current))!))) return false;
+ current = join(current, name);
+ }
+ return !(await walkStopsAt(current));
+ }
+
+ async function fromSpotlight() {
+ const dirs = new Set((await spotlight(root, signal)).map((marker) => dirname(marker)));
+ await Promise.all(
+ [...dirs].map(async (dir) => {
+ if (stopped() || !(await walkWouldReach(dir))) return;
+ const entries = await entriesOf(dir);
+ if (entries && isHyperframesProject(fileNames(entries))) await report(dir, "spotlight");
+ }),
+ );
+ }
+
+ await Promise.all([fromSpotlight(), walk()]);
+ signal?.throwIfAborted();
+ return reported.size;
+}