Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
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.jsonindex 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.jsonindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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;+}