Skip to content

Commit e738e10

Browse files
feat(core): export findProjects to list the HyperFrames projects on a machine (#4627)
* feat(cli): hyperframes projects finds the HyperFrames projects on this machine * refactor(core): keep the project rule's comment share under its package's * fix(cli): projects keeps Spotlight hits under a symlinked root and refuses a missing root * style(cli): format the projects walker and its tests * fix(cli): projects tests pass under a symlinked temp folder and a bad root errors on stderr * test(cli): projects tests hold on Windows and cover an unreadable root * style(cli): format the projects command and tests * refactor(cli): split the projects Spotlight check and regenerate the skills manifest * refactor(core): findProjects moves to @hyperframes/core/projects so Desktop can import it * chore(core): publish the projects subpath * fix(core): findProjects fails on a root it cannot read instead of finding nothing * docs(core): name the project marker writers without naming one app * refactor(core): ship findProjects as a core export only, with no CLI command * feat(core): findProjects stops on an abort signal and defaults to the home folder * fix(core): findProjects checks an aborted signal first and stops when onProject throws
1 parent ea494b4 commit e738e10

7 files changed

Lines changed: 456 additions & 0 deletions

File tree

‎packages/core/package-subpaths.json‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -110,6 +110,12 @@
110110
"types": "./dist/compiler/index.d.ts",
111111
"environments": ["bun", "node"]
112112
},
113+
"./projects": {
114+
"source": "./src/projects.ts",
115+
"runtime": "./dist/projects.js",
116+
"types": "./dist/projects.d.ts",
117+
"environments": ["bun", "node"]
118+
},
113119
"./audio-fx": {
114120
"source": "./src/audioFx.ts",
115121
"runtime": "./dist/audioFx.js",

‎packages/core/package.json‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -124,6 +124,12 @@
124124
"import": "./src/compiler/index.ts",
125125
"types": "./src/compiler/index.ts"
126126
},
127+
"./projects": {
128+
"bun": "./src/projects.ts",
129+
"node": "./dist/projects.js",
130+
"import": "./src/projects.ts",
131+
"types": "./src/projects.ts"
132+
},
127133
"./audio-fx": {
128134
"bun": "./src/audioFx.ts",
129135
"node": "./dist/audioFx.js",
@@ -512,6 +518,10 @@
512518
"import": "./dist/compiler/index.js",
513519
"types": "./dist/compiler/index.d.ts"
514520
},
521+
"./projects": {
522+
"import": "./dist/projects.js",
523+
"types": "./dist/projects.d.ts"
524+
},
515525
"./audio-fx": {
516526
"import": "./dist/audioFx.js",
517527
"types": "./dist/audioFx.d.ts"

‎packages/core/src/index.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -276,6 +276,7 @@ export {
276276
} from "./inline-scripts/parityContract";
277277
export { redactKnownPaths, redactTelemetryString } from "./telemetryRedaction";
278278
export { isSafePath, realpath, resolveWithinProject } from "./safePath";
279+
export { isHyperframesProject, PROJECT_MARKER_FILES } from "./projectRule";
279280
export type {
280281
HyperframePickerApi,
281282
HyperframePickerBoundingBox,
Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
import { describe, expect, it } from "vitest";
2+
import { isHyperframesProject } from "./projectRule";
3+
4+
describe("isHyperframesProject", () => {
5+
it.each(["hyperframes.json", "meta.json", "project.json"])(
6+
"counts a folder with index.html and %s",
7+
(marker) => {
8+
expect(isHyperframesProject(["index.html", marker, "assets"])).toBe(true);
9+
},
10+
);
11+
12+
it("does not count index.html alone, or a marker without index.html", () => {
13+
expect(isHyperframesProject(["index.html", "package.json"])).toBe(false);
14+
expect(isHyperframesProject(["hyperframes.json", "README.md"])).toBe(false);
15+
});
16+
});

‎packages/core/src/projectRule.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
/** Files that `hyperframes init` or another HyperFrames tool writes at a project's root, next to its `index.html`. */
2+
export const PROJECT_MARKER_FILES = ["hyperframes.json", "meta.json", "project.json"] as const;
3+
4+
export function isHyperframesProject(fileNames: Iterable<string>): boolean {
5+
const names = new Set(fileNames);
6+
return names.has("index.html") && PROJECT_MARKER_FILES.some((name) => names.has(name));
7+
}

‎packages/core/src/projects.test.ts‎

Lines changed: 237 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,237 @@
1+
import {
2+
chmodSync,
3+
mkdirSync,
4+
mkdtempSync,
5+
realpathSync,
6+
rmSync,
7+
symlinkSync,
8+
writeFileSync,
9+
} from "node:fs";
10+
import { tmpdir } from "node:os";
11+
import { join, relative, sep } from "node:path";
12+
import { afterEach, describe, expect, it, vi } from "vitest";
13+
import { findProjects, type FoundProject } from "./projects";
14+
15+
const roots: string[] = [];
16+
afterEach(() => {
17+
vi.unstubAllEnvs();
18+
for (const root of roots.splice(0)) {
19+
chmodSync(root, 0o755);
20+
rmSync(root, { recursive: true, force: true });
21+
}
22+
});
23+
24+
function tree(files: string[]): string {
25+
const root = realpathSync.native(mkdtempSync(join(tmpdir(), "hf-find-projects-")));
26+
roots.push(root);
27+
for (const file of files) {
28+
mkdirSync(join(root, file, ".."), { recursive: true });
29+
writeFileSync(join(root, file), file.endsWith(".git") ? "gitdir: ../.git/modules/x" : "");
30+
}
31+
return root;
32+
}
33+
34+
async function find(root: string, spotlight: string[] = []): Promise<FoundProject[]> {
35+
const found: FoundProject[] = [];
36+
await findProjects({
37+
root,
38+
onProject: (project) => found.push(project),
39+
spotlight: async () => spotlight.map((path) => join(root, path)),
40+
});
41+
return found;
42+
}
43+
44+
const paths = (root: string, found: FoundProject[]) =>
45+
found.map((project) => relative(root, project.path).split(sep).join("/")).sort();
46+
47+
describe("findProjects", () => {
48+
it("finds a folder with index.html and a project marker, and nothing else", async () => {
49+
const root = tree([
50+
"film/index.html",
51+
"film/meta.json",
52+
"site/index.html",
53+
"notes/project.json",
54+
]);
55+
56+
const found = await find(root);
57+
58+
expect(paths(root, found)).toEqual(["film"]);
59+
expect(found[0]).toMatchObject({ name: "film", source: "walk" });
60+
expect(Date.parse(found[0]!.mtime)).toBeGreaterThan(0);
61+
});
62+
63+
it("skips node_modules and hidden folders", async () => {
64+
const root = tree([
65+
"app/node_modules/pkg/index.html",
66+
"app/node_modules/pkg/project.json",
67+
".cache/film/index.html",
68+
".cache/film/meta.json",
69+
]);
70+
71+
expect(await find(root)).toEqual([]);
72+
});
73+
74+
it("skips a git worktree copy but walks a submodule", async () => {
75+
const root = tree([
76+
"repo-copy/film/index.html",
77+
"repo-copy/film/meta.json",
78+
"vendor/sub/.git",
79+
"vendor/sub/film/index.html",
80+
"vendor/sub/film/hyperframes.json",
81+
]);
82+
writeFileSync(join(root, "repo-copy", ".git"), "gitdir: /src/repo/.git/worktrees/repo-copy\n");
83+
84+
expect(paths(root, await find(root))).toEqual(["vendor/sub/film"]);
85+
});
86+
87+
it("skips Library in the home folder but not a folder named Library elsewhere", async () => {
88+
const root = tree([
89+
"Library/film/index.html",
90+
"Library/film/meta.json",
91+
"Movies/Library/film/index.html",
92+
"Movies/Library/film/meta.json",
93+
]);
94+
vi.stubEnv("HOME", root + sep);
95+
vi.stubEnv("USERPROFILE", root + sep);
96+
97+
const found = await find(root, ["Library/film/meta.json", "Movies/Library/film/meta.json"]);
98+
99+
expect(paths(root, found)).toEqual(["Movies/Library/film"]);
100+
});
101+
102+
it("searches the home folder when no root is given", async () => {
103+
const root = tree(["film/index.html", "film/meta.json"]);
104+
vi.stubEnv("HOME", root);
105+
vi.stubEnv("USERPROFILE", root);
106+
const found: FoundProject[] = [];
107+
108+
await findProjects({ onProject: (project) => found.push(project), spotlight: async () => [] });
109+
110+
expect(paths(root, found)).toEqual(["film"]);
111+
});
112+
113+
it("stops reporting and rejects once its signal is aborted", async () => {
114+
const root = tree(
115+
Array.from({ length: 200 }, (_, i) => [`f${i}/index.html`, `f${i}/meta.json`]).flat(),
116+
);
117+
const controller = new AbortController();
118+
const found: FoundProject[] = [];
119+
const search = findProjects({
120+
root,
121+
signal: controller.signal,
122+
spotlight: async () => [],
123+
onProject: (project) => {
124+
found.push(project);
125+
controller.abort();
126+
},
127+
});
128+
129+
await expect(search).rejects.toMatchObject({ name: "AbortError" });
130+
expect(found).toHaveLength(1);
131+
});
132+
133+
it("stops the search when onProject throws", async () => {
134+
const root = tree(
135+
Array.from({ length: 200 }, (_, i) => [`f${i}/index.html`, `f${i}/meta.json`]).flat(),
136+
);
137+
const onProject = vi.fn(() => {
138+
throw new Error("list is closed");
139+
});
140+
141+
await expect(findProjects({ root, onProject, spotlight: async () => [] })).rejects.toThrow(
142+
"list is closed",
143+
);
144+
expect(onProject).toHaveBeenCalledTimes(1);
145+
});
146+
147+
it("does not start when its signal is already aborted", async () => {
148+
const onProject = vi.fn();
149+
const search = findProjects({
150+
root: join(tree([]), "missing"),
151+
onProject,
152+
signal: AbortSignal.abort(),
153+
});
154+
155+
await expect(search).rejects.toMatchObject({ name: "AbortError" });
156+
expect(onProject).not.toHaveBeenCalled();
157+
});
158+
159+
it("does not look for projects inside a project", async () => {
160+
const root = tree([
161+
"film/index.html",
162+
"film/hyperframes.json",
163+
"film/compositions/intro/index.html",
164+
"film/compositions/intro/meta.json",
165+
]);
166+
167+
expect(paths(root, await find(root))).toEqual(["film"]);
168+
});
169+
170+
it("searches a root that is itself a git worktree copy", async () => {
171+
const root = tree(["film/index.html", "film/meta.json"]);
172+
writeFileSync(join(root, ".git"), "gitdir: /src/repo/.git/worktrees/copy\n");
173+
174+
expect(paths(root, await find(root))).toEqual(["film"]);
175+
});
176+
177+
it.skipIf(process.platform === "win32" || process.getuid?.() === 0)(
178+
"finishes past a symlink loop and an unreadable folder",
179+
async () => {
180+
const root = tree([
181+
"film/index.html",
182+
"film/meta.json",
183+
"locked/film/index.html",
184+
"locked/film/meta.json",
185+
]);
186+
symlinkSync(root, join(root, "loop"), "dir");
187+
chmodSync(join(root, "locked"), 0o000);
188+
189+
try {
190+
expect(paths(root, await find(root))).toEqual(["film"]);
191+
} finally {
192+
chmodSync(join(root, "locked"), 0o755);
193+
}
194+
},
195+
);
196+
197+
it("fails on a root that is missing or not a folder instead of finding nothing", async () => {
198+
const root = tree(["file.txt"]);
199+
await expect(find(join(root, "missing"))).rejects.toMatchObject({ code: "ENOENT" });
200+
await expect(find(join(root, "file.txt"))).rejects.toMatchObject({ code: "ENOTDIR" });
201+
});
202+
203+
it.skipIf(process.platform === "win32" || process.getuid?.() === 0)(
204+
"fails on a root it may not read instead of finding nothing",
205+
async () => {
206+
const root = tree([]);
207+
chmodSync(root, 0o000);
208+
await expect(find(root)).rejects.toMatchObject({ code: "EACCES" });
209+
},
210+
);
211+
212+
it("reports a Spotlight hit once, and only where the walk would also count it", async () => {
213+
const root = tree([
214+
"film/index.html",
215+
"film/meta.json",
216+
"film/compositions/intro/index.html",
217+
"film/compositions/intro/meta.json",
218+
"app/node_modules/pkg/index.html",
219+
"app/node_modules/pkg/project.json",
220+
"repo-copy/film/index.html",
221+
"repo-copy/film/meta.json",
222+
"readme/meta.json",
223+
]);
224+
writeFileSync(join(root, "repo-copy", ".git"), "gitdir: /src/repo/.git/worktrees/repo-copy\n");
225+
226+
const found = await find(root, [
227+
"film/meta.json",
228+
"film/compositions/intro/meta.json",
229+
"app/node_modules/pkg/project.json",
230+
"repo-copy/film/meta.json",
231+
"readme/meta.json",
232+
"../elsewhere/meta.json",
233+
]);
234+
235+
expect(paths(root, found)).toEqual(["film"]);
236+
});
237+
});

0 commit comments

Comments
 (0)