tempest-react-sdk 0.77.0 → 0.78.0

package/bin/lib/openapi/escape.mjs

@@ -180,13 +180,23 @@ function templateText(text) {
  *
  * Static segments are escaped for the template literal; each `{name}` placeholder
  * is matched by the spec's original name against the declared path parameters
- * and becomes `${identifier}`, the variable that parameter was mapped to
- * (`{user-id}` → `${userId}`). A path without placeholders is emitted as a JSON
- * string literal.
+ * and becomes `${encodeIdSegment(identifier)}`, the variable that parameter was
+ * mapped to passed through the SDK's segment encoder (`{user-id}` →
+ * `${encodeIdSegment(userId)}`). A path without placeholders is emitted as a
+ * JSON string literal.
+ *
+ * The encoder is what keeps a runtime value inside its own segment: interpolated
+ * raw, `"../../account"` turned `DELETE /api/comments/{id}` into
+ * `DELETE /account` carrying the Bearer, and `"7?role=admin"` injected a query
+ * string (#499 — the class #438 closed for the data provider). Encoded, `/`, `?`,
+ * `#` and `%` stay in the segment, and `null`, `undefined`, `""`, `"."` and
+ * `".."` throw before the request is built.
  *
  * @param {string} path - The OpenAPI path key ("/users/{user-id}").
- * @param {Map<string, string>} declared - Original name → identifier of each of
- *   the operation's `in: "path"` params.
+ * @param {Map<string, string>} declared - Original name → argument expression of
+ *   each of the operation's `in: "path"` params: the identifier, or the
+ *   identifier with a type assertion when its type is wider than
+ *   `encodeIdSegment` accepts.
  * @returns {string} A TypeScript expression evaluating to the URL.
  * @throws {Error} When a placeholder is not a declared path parameter — there is
  *   no variable it could safely map to.
@@ -202,7 +212,11 @@ export function urlTemplate(path, declared) {
                 `OpenAPI path ${JSON.stringify(path)}: placeholder ${JSON.stringify(name)} is not a declared path parameter.`,
             );
         }
-        out += templateText(path.slice(last, match.index)) + "${" + declared.get(name) + "}";
+        out +=
+            templateText(path.slice(last, match.index)) +
+            "${encodeIdSegment(" +
+            declared.get(name) +
+            ")}";
         last = match.index + match[0].length;
     }
     out += templateText(path.slice(last));

package/bin/lib/openapi/generate.encode.test.mjs

@@ -0,0 +1,120 @@
+import ts from "typescript";
+import { describe, expect, it } from "vitest";
+
+import { encodeIdSegment } from "../../../src/data";
+import { createApiClient } from "../../../src/http";
+import { generate } from "./generate.mjs";
+
+const BASE = "https://api.example.test";
+
+/**
+ * Transpile one generated `service.ts` and load it as CommonJS, resolving
+ * `tempest-react-sdk` to the SDK's real source — so the call goes through the
+ * genuine `encodeIdSegment` and `createApiClient`, not a stub of either.
+ *
+ * @param {string} source - The generated `service.ts` contents.
+ * @returns {Record<string, unknown>} The module's exports.
+ */
+function load(source) {
+    const { outputText } = ts.transpileModule(source, {
+        compilerOptions: { module: ts.ModuleKind.CommonJS, target: ts.ScriptTarget.ES2022 },
+    });
+    const module = { exports: {} };
+    const require = (id) => {
+        if (id === "tempest-react-sdk") return { encodeIdSegment };
+        throw new Error(`unexpected import ${id}`);
+    };
+    new Function("exports", "require", "module", outputText)(module.exports, require, module);
+    return module.exports;
+}
+
+/**
+ * Generate a one-route `comments` service (`GET`/`DELETE /api/comments/{id}`)
+ * bound to a real `ApiClient` whose `fetcher` records every request.
+ *
+ * @param {object} [schema] - The `id` path parameter's schema.
+ * @param {string} [baseURL] - The client's base URL.
+ * @returns {{ service: Record<string, Function>, seen: string[], source: string }}
+ */
+function commentsService(schema = { type: "string" }, baseURL = BASE) {
+    const op = (operationId) => ({
+        operationId,
+        tags: ["comments"],
+        parameters: [{ name: "id", in: "path", required: true, schema }],
+        responses: { 204: { description: "x" } },
+    });
+    const { files } = generate({
+        openapi: "3.1.0",
+        info: { title: "t", version: "1" },
+        paths: { "/api/comments/{id}": { get: op("getComment"), delete: op("deleteComment") } },
+    });
+    const source = files["comments/service.ts"];
+    const seen = [];
+    const api = createApiClient({
+        baseURL,
+        getToken: () => "DUMMY_TOKEN",
+        fetcher: async (url, init) => {
+            seen.push(`${init?.method ?? "GET"} ${String(url)}`);
+            return new Response(null, { status: 204 });
+        },
+    });
+    const { CommentsService } = load(source);
+    return { service: new CommentsService(api), seen, source };
+}
+
+describe("generate — path params are encoded into one segment (#499, as #438 did for the data provider)", () => {
+    it.each([
+        ["../../account", "..%2F..%2Faccount"],
+        ["../x", "..%2Fx"],
+        ["%2e%2e/%2e%2e/account", "%252e%252e%2F%252e%252e%2Faccount"],
+        ["7?a=b", "7%3Fa%3Db"],
+        ["7?role=admin", "7%3Frole%3Dadmin"],
+        ["7#x", "7%23x"],
+    ])("a hostile id %j stays one segment under /api/comments", async (id, segment) => {
+        const { service, seen } = commentsService();
+        await service.deleteComment(id);
+        expect(seen).toEqual([`DELETE ${BASE}/api/comments/${segment}`]);
+    });
+
+    it("a base URL prefix cannot be escaped with extra dot-segments", async () => {
+        const { service, seen } = commentsService({ type: "string" }, `${BASE}/v1`);
+        await service.deleteComment("../../../account");
+        expect(seen).toEqual([`DELETE ${BASE}/v1/api/comments/..%2F..%2F..%2Faccount`]);
+    });
+
+    it.each(["", ".", ".."])("the dot-segment id %j throws before any request", async (id) => {
+        const { service, seen } = commentsService();
+        await expect(service.deleteComment(id)).rejects.toThrow(TypeError);
+        expect(seen).toEqual([]);
+    });
+
+    it("null and undefined from an untyped caller throw instead of becoming a literal segment", async () => {
+        const { service, seen } = commentsService();
+        await expect(service.getComment(null)).rejects.toThrow(TypeError);
+        await expect(service.getComment(undefined)).rejects.toThrow(TypeError);
+        expect(seen).toEqual([]);
+    });
+
+    it("a numeric id is still sent as its decimal segment", async () => {
+        const { service, seen, source } = commentsService({ type: "integer" });
+        expect(source).toContain("async getComment(id: number): Promise<void>");
+        await service.getComment(7);
+        expect(seen).toEqual([`GET ${BASE}/api/comments/7`]);
+    });
+
+    it.each([
+        ["a boolean", { type: "boolean" }, true, "true"],
+        ["an array", { type: "array", items: { type: "string" } }, ["a", "b/c"], "a%2Cb%2Fc"],
+        ["a nullable string", { type: ["string", "null"] }, "a/b", "a%2Fb"],
+    ])("%s path param is encoded too", async (_kind, schema, value, segment) => {
+        const { service, seen } = commentsService(schema);
+        await service.getComment(value);
+        expect(seen).toEqual([`GET ${BASE}/api/comments/${segment}`]);
+    });
+
+    it("a nullable path param still rejects null at runtime", async () => {
+        const { service, seen } = commentsService({ type: ["string", "null"] });
+        await expect(service.getComment(null)).rejects.toThrow(TypeError);
+        expect(seen).toEqual([]);
+    });
+});

package/bin/lib/openapi/generate.hostile.test.mjs

@@ -6,6 +6,7 @@ import vm from "node:vm";
 import ts from "typescript";
 import { describe, expect, it } from "vitest";
 
+import { encodeIdSegment } from "../../../src/data";
 import { generate } from "./generate.mjs";
 
 const require = createRequire(import.meta.url);
@@ -14,7 +15,9 @@ const require = createRequire(import.meta.url);
  *
  * The context gets its own `globalThis`, so any `globalThis.PWNED_*` an injected
  * statement sets lands on `context` and the test can read it back. `zod` is the
- * real package; `./schemas` resolves to the module evaluated before it.
+ * real package, `tempest-react-sdk` exposes the real `encodeIdSegment` every path
+ * parameter goes through (#499); `./schemas` resolves to the module evaluated
+ * before it.
  *
  * @param {string} source - The generated `.ts` contents.
  * @param {object} context - The VM context shared by the group's files.
@@ -33,7 +36,8 @@ function evaluate(source, context, modules) {
     const module = { exports: {} };
     const localRequire = (id) => {
         if (id in modules) return modules[id];
-        if (id === "zod" || id === "tempest-react-sdk") return id === "zod" ? require("zod") : {};
+        if (id === "zod") return require("zod");
+        if (id === "tempest-react-sdk") return { encodeIdSegment };
         throw new Error(`unexpected import ${id}`);
     };
     vm.runInContext(`(function (exports, require, module) {\n${outputText}\n})`, context)(
@@ -398,7 +402,7 @@ const REPO = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
  *
  * Files live in a virtual folder under the repository so `zod` resolves from its
  * `node_modules`; `tempest-react-sdk` is swapped for a stub with the three types
- * the generator imports from it.
+ * and the `encodeIdSegment` value the generator imports from it.
  *
  * @param {Record<string, string>} files - The generator output.
  * @param {string} slug - The group folder.
@@ -409,7 +413,7 @@ function typecheck(files, slug) {
     const virtual = new Map(
         ["schemas.ts", "types.ts", "service.ts"].map((f) => [
             join(root, f),
-            files[`${slug}/${f}`].replace('from "tempest-react-sdk"', 'from "./sdk"'),
+            files[`${slug}/${f}`].replaceAll('from "tempest-react-sdk"', 'from "./sdk"'),
         ]),
     );
     virtual.set(
@@ -419,6 +423,7 @@ function typecheck(files, slug) {
             "export type ApiClient = { get: Call; post: Call; put: Call; patch: Call; delete: Call };",
             "export type OffsetPage<T> = { items: T[]; total: number };",
             "export type CursorPage<T> = { items: T[]; next_cursor: string | null };",
+            "export declare function encodeIdSegment(id: string | number): string;",
         ].join("\n"),
     );
     const options = {
@@ -451,11 +456,11 @@ const JSON_BODY = (ref) => ({
 const JSON_OK = (ref) => ({ 200: JSON_BODY(ref) });
 
 describe("generate — names that collide with what the generator itself declares", () => {
-    it("a path parameter named body, params or S is renamed, not duplicated or shadowing", async () => {
+    it("a path parameter named body, params, S or encodeIdSegment is renamed, not duplicated or shadowing", async () => {
         const { files } = generate(
             spec(
                 {
-                    "/a/{body}/{params}/{S}": {
+                    "/a/{body}/{params}/{S}/{encodeIdSegment}": {
                         post: {
                             tags: ["t"],
                             operationId: "send",
@@ -463,6 +468,7 @@ describe("generate — names that collide with what the generator itself declare
                                 { name: "body", in: "path", required: true },
                                 { name: "params", in: "path", required: true },
                                 { name: "S", in: "path", required: true },
+                                { name: "encodeIdSegment", in: "path", required: true },
                                 { name: "q", in: "query" },
                             ],
                             requestBody: JSON_BODY("Req"),
@@ -479,8 +485,11 @@ describe("generate — names that collide with what the generator itself declare
         const mod = evaluate(files["t/service.ts"], context, { "./schemas": S });
         const calls = [];
         const api = { post: async (url, opts) => calls.push({ url, opts }) };
-        await new mod.TService(api).send("b", "p", "s", { k: 1 }, { q: "x" });
-        expect(calls).toEqual([{ url: "/a/b/p/s", opts: { body: { k: 1 }, params: { q: "x" } } }]);
+        await new mod.TService(api).send("b", "p", "s", "e/x", { k: 1 }, { q: "x" });
+        expect(files["t/service.ts"]).toContain("${encodeIdSegment(encodeIdSegmentParam)}");
+        expect(calls).toEqual([
+            { url: "/a/b/p/s/e%2Fx", opts: { body: { k: 1 }, params: { q: "x" } } },
+        ]);
     });
 
     it("an operationId of constructor or api becomes a distinct method", async () => {
@@ -541,7 +550,16 @@ describe("generate — names that collide with what the generator itself declare
                 size: { type: "integer" },
             },
         };
-        const names = ["ApiClient", "OffsetPage", "CursorPage", "Promise", "Record", "z", "S"];
+        const names = [
+            "ApiClient",
+            "OffsetPage",
+            "CursorPage",
+            "Promise",
+            "Record",
+            "z",
+            "S",
+            "encodeIdSegment",
+        ];
         const paths = Object.fromEntries(
             names.map((n, i) => [
                 `/n${i}`,
@@ -556,10 +574,21 @@ describe("generate — names that collide with what the generator itself declare
                 },
             },
         };
+        paths["/p/{id}"] = {
+            get: {
+                tags: ["t"],
+                parameters: [{ name: "id", in: "path", required: true }],
+                responses: OK,
+            },
+        };
         const schemas = Object.fromEntries(names.map((n) => [n, { type: "object" }]));
         schemas.Page = page;
         const { files } = generate(spec(paths, schemas));
         expect(files["t/service.ts"]).toContain("OffsetPage<_Promise>");
+        expect(files["t/service.ts"]).toContain(
+            'import { encodeIdSegment } from "tempest-react-sdk";',
+        );
+        expect(files["t/types.ts"]).toContain("export type _encodeIdSegment =");
         expect(typecheck(files, "t")).toEqual([]);
     });
 

package/bin/lib/openapi/generate.mjs

@@ -51,11 +51,34 @@ const CLASS_MEMBERS = ["constructor", "api"];
 
 /**
  * Names a generated method body uses besides its path parameters: the `body` and
- * `params` arguments and the `S` schemas import. A path parameter that maps to one
- * of them becomes `<name>Param` (`{body}` → `bodyParam`), so it neither duplicates
- * an argument nor shadows the import.
+ * `params` arguments, the `S` schemas import and the `encodeIdSegment` import. A
+ * path parameter that maps to one of them becomes `<name>Param` (`{body}` →
+ * `bodyParam`), so it neither duplicates an argument nor shadows the import.
  */
-const METHOD_LOCALS = new Set(["body", "params", "S"]);
+const METHOD_LOCALS = new Set(["body", "params", "S", "encodeIdSegment"]);
+
+/**
+ * Whether a path parameter's schema only ever produces a `string` or a `number` —
+ * the types `encodeIdSegment(id: string | number)` accepts — so the generated call
+ * can pass the argument as is.
+ *
+ * `$ref` chains are followed, and `anyOf`/`oneOf`/single-member `allOf` qualify
+ * when every branch does. `null`, `boolean`, arrays, objects and anything
+ * unrecognised do not.
+ *
+ * @param {object | undefined} schema - The parameter's schema.
+ * @param {Record<string, object>} schemas - `components.schemas`.
+ * @param {number} [depth] - Recursion guard for self-referencing unions.
+ * @returns {boolean} `true` when the TypeScript type is assignable to `string | number`.
+ */
+function isSegmentScalar(schema, schemas, depth = 0) {
+    const node = resolveSchema(schema, schemas);
+    if (!node || typeof node !== "object" || depth > 16) return false;
+    const branches = node.anyOf ?? node.oneOf ?? (node.allOf?.length === 1 ? node.allOf : null);
+    if (branches) return branches.every((b) => isSegmentScalar(b, schemas, depth + 1));
+    if (node.nullable || Array.isArray(node.type)) return false;
+    return node.type === "string" || node.type === "integer" || node.type === "number";
+}
 
 /**
  * Check every `pattern` in a schema compiles as a JavaScript regex.
@@ -311,8 +334,13 @@ export function generate(doc) {
         const sdkTypes = ["ApiClient"];
         if (body.includes("OffsetPage<")) sdkTypes.push("OffsetPage");
         if (body.includes("CursorPage<")) sdkTypes.push("CursorPage");
+        const sdkValues = body.includes("encodeIdSegment(")
+            ? `import { encodeIdSegment } from "tempest-react-sdk";\n`
+            : "";
         files[`${slug}/service.ts`] =
-            `import type { ${sdkTypes.join(", ")} } from "tempest-react-sdk";\n\n` +
+            `import type { ${sdkTypes.join(", ")} } from "tempest-react-sdk";\n` +
+            sdkValues +
+            "\n" +
             schemaImport +
             typeImport +
             `\n/** Generated service for the "${commentText(tag)}" routes. Inject an ApiClient (createApiClient). */\n` +
@@ -353,6 +381,13 @@ function emitMethod(method, path, op, schemas, usedNames = new Set()) {
         return METHOD_LOCALS.has(id) ? `${id}Param` : id;
     };
     const paramIds = new Map(pathParams.map((p) => [p.name, paramId(p.name)]));
+    const segmentArgs = new Map(
+        pathParams.map((p) => {
+            const id = paramIds.get(p.name);
+            const schema = p.schema ?? { type: "string" };
+            return [p.name, isSegmentScalar(schema, schemas) ? id : `${id} as never`];
+        }),
+    );
     assertNoCollision(
         [
             ...[...paramIds],
@@ -389,7 +424,7 @@ function emitMethod(method, path, op, schemas, usedNames = new Set()) {
         args.push(`params: { ${q} }`);
     }
 
-    const url = urlTemplate(path, paramIds);
+    const url = urlTemplate(path, segmentArgs);
 
     const callOpts = [];
     if (body) callOpts.push("body");

package/bin/lib/openapi/generate.test.mjs

@@ -122,8 +122,13 @@ describe("generate — FastAPI-style spec", () => {
         // create with Zod input validation
         expect(svc).toContain("S.UserCreateSchema.parse(body);");
         expect(svc).toMatch(/async createUser\(body: UserCreate\): Promise<User>/);
-        // path param interpolation
         expect(svc).toMatch(/async getUser\(id: number\): Promise<User>/);
-        expect(svc).toContain("return this.api.get<User>(`/users/${id}`);");
+    });
+
+    it("wraps every path param in encodeIdSegment — the raw `${id}` this used to pin sent '../../account' to /account with the Bearer (#499, the class #438 closed)", () => {
+        const svc = files["users/service.ts"];
+        expect(svc).not.toContain("`/users/${id}`");
+        expect(svc).toContain("return this.api.get<User>(`/users/${encodeIdSegment(id)}`);");
+        expect(svc).toContain('import { encodeIdSegment } from "tempest-react-sdk";');
     });
 });

package/bin/lib/openapi/schema-to-zod.mjs

@@ -14,9 +14,10 @@ export function refName(ref) {
 
 /**
  * Names the generated files declare, import or rely on as globals next to the
- * schema types: the SDK types `service.ts` imports, the `z` and `S` imports, and
- * the `Promise` / `Record` globals the emitted signatures use. A schema with one
- * of these names would collide with the import or shadow the global.
+ * schema types: the SDK types and the `encodeIdSegment` value `service.ts`
+ * imports, the `z` and `S` imports, and the `Promise` / `Record` globals the
+ * emitted signatures use. A schema with one of these names would collide with
+ * the import or shadow the global.
  */
 export const GENERATED_NAMES = new Set([
     "ApiClient",
@@ -25,6 +26,7 @@ export const GENERATED_NAMES = new Set([
     "Promise",
     "Record",
     "S",
+    "encodeIdSegment",
     "z",
 ]);
 

package/bin/tempest-gen.test.mjs

@@ -0,0 +1,188 @@
+import { spawnSync } from "node:child_process";
+import {
+    existsSync,
+    mkdirSync,
+    mkdtempSync,
+    readdirSync,
+    readFileSync,
+    rmSync,
+    symlinkSync,
+    writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+const CLI = join(dirname(fileURLToPath(import.meta.url)), "tempest.mjs");
+
+const SPEC = {
+    openapi: "3.0.0",
+    info: { title: "t", version: "1" },
+    paths: {
+        "/users": {
+            get: {
+                tags: ["users"],
+                operationId: "listUsers",
+                responses: { 200: { description: "ok" } },
+            },
+        },
+    },
+};
+
+/**
+ * Every file under `dir`, relative, sorted — `[]` when nothing was written.
+ *
+ * @param {string} dir - Absolute folder.
+ * @returns {string[]}
+ */
+function filesUnder(dir) {
+    return readdirSync(dir, { recursive: true }).sort();
+}
+
+describe("tempest gen api / gen icons — write containment (#484)", () => {
+    let cwd;
+    let outside;
+
+    beforeEach(() => {
+        cwd = mkdtempSync(join(tmpdir(), "tempest-gen-cli-"));
+        outside = mkdtempSync(join(tmpdir(), "tempest-gen-outside-"));
+        mkdirSync(join(cwd, "src"));
+        writeFileSync(join(cwd, "spec.json"), JSON.stringify(SPEC));
+    });
+
+    afterEach(() => {
+        rmSync(cwd, { recursive: true, force: true });
+        rmSync(outside, { recursive: true, force: true });
+    });
+
+    /**
+     * Run the `tempest` CLI in the temporary project.
+     *
+     * @param {string[]} args - CLI arguments.
+     * @returns {{ status: number | null, out: string }}
+     */
+    function tempest(...args) {
+        const result = spawnSync(process.execPath, [CLI, ...args], { cwd, encoding: "utf8" });
+        return { status: result.status, out: result.stdout + result.stderr };
+    }
+
+    it("gen api still writes into a regular src/api", () => {
+        const { status } = tempest("gen", "api", "spec.json");
+        expect(status).toBe(0);
+        expect(existsSync(join(cwd, "src", "api", "users", "service.ts"))).toBe(true);
+    });
+
+    it("gen api refuses a src/api that is a symlink leaving the project", () => {
+        symlinkSync(outside, join(cwd, "src", "api"));
+
+        const { status, out } = tempest("gen", "api", "spec.json");
+
+        expect(status).toBe(1);
+        expect(out).toMatch(/src\/api is a symlink/);
+        expect(filesUnder(outside)).toEqual([]);
+    });
+
+    it("gen api refuses a symlinked --out even when it points inside the project", () => {
+        mkdirSync(join(cwd, "elsewhere"));
+        symlinkSync(join(cwd, "elsewhere"), join(cwd, "src", "api"));
+
+        const { status, out } = tempest("gen", "api", "spec.json");
+
+        expect(status).toBe(1);
+        expect(out).toMatch(/symlink/);
+        expect(filesUnder(join(cwd, "elsewhere"))).toEqual([]);
+    });
+
+    it("gen api refuses a dangling symlink, which writeFile would follow and create", () => {
+        symlinkSync(join(outside, "not-yet"), join(cwd, "src", "api"));
+
+        const { status, out } = tempest("gen", "api", "spec.json");
+
+        expect(status).toBe(1);
+        expect(out).toMatch(/symlink/);
+        expect(existsSync(join(outside, "not-yet"))).toBe(false);
+    });
+
+    it("gen api refuses a symlinked route-group folder below --out, before writing anything", () => {
+        mkdirSync(join(cwd, "src", "api"));
+        symlinkSync(outside, join(cwd, "src", "api", "users"));
+
+        const { status, out } = tempest("gen", "api", "spec.json");
+
+        expect(status).toBe(1);
+        expect(out).toMatch(/src\/api\/users is a symlink/);
+        expect(filesUnder(outside)).toEqual([]);
+        expect(filesUnder(join(cwd, "src", "api"))).toEqual(["users"]);
+    });
+
+    it("gen api refuses a generated file that is a symlink", () => {
+        mkdirSync(join(cwd, "src", "api"));
+        const victim = join(outside, "victim.ts");
+        writeFileSync(victim, "SENTINEL");
+        symlinkSync(victim, join(cwd, "src", "api", "index.ts"));
+
+        const { status, out } = tempest("gen", "api", "spec.json");
+
+        expect(status).toBe(1);
+        expect(out).toMatch(/src\/api\/index\.ts is a symlink/);
+        expect(readFileSync(victim, "utf8")).toBe("SENTINEL");
+    });
+
+    it("gen api refuses an --out whose existing ancestor is a symlink leaving the project", () => {
+        symlinkSync(outside, join(cwd, "gen"));
+
+        const { status, out } = tempest("gen", "api", "spec.json", "--out", "gen/api");
+
+        expect(status).toBe(1);
+        expect(out).toMatch(/outside the project/);
+        expect(filesUnder(outside)).toEqual([]);
+    });
+
+    it("gen api refuses an --out outside the project", () => {
+        const { status, out } = tempest("gen", "api", "spec.json", "--out", outside);
+        expect(status).toBe(1);
+        expect(out).toMatch(/outside the project/);
+        expect(filesUnder(outside)).toEqual([]);
+    });
+
+    it("gen icons refuses a src/icons.generated.ts that is a symlink", () => {
+        const victim = join(outside, "victim.ts");
+        writeFileSync(victim, "SENTINEL");
+        symlinkSync(victim, join(cwd, "src", "icons.generated.ts"));
+
+        const { status, out } = tempest("gen", "icons");
+
+        expect(status).toBe(1);
+        expect(out).toMatch(/src\/icons\.generated\.ts is a symlink/);
+        expect(readFileSync(victim, "utf8")).toBe("SENTINEL");
+    });
+
+    it("gen icons refuses a dangling symlink at the output", () => {
+        symlinkSync(join(outside, "not-yet.ts"), join(cwd, "src", "icons.generated.ts"));
+
+        const { status, out } = tempest("gen", "icons");
+
+        expect(status).toBe(1);
+        expect(out).toMatch(/symlink/);
+        expect(existsSync(join(outside, "not-yet.ts"))).toBe(false);
+    });
+
+    it("gen icons refuses an --out whose folder is a symlink leaving the project", () => {
+        symlinkSync(outside, join(cwd, "gen"));
+
+        const { status, out } = tempest("gen", "icons", "--out", "gen/icons.ts");
+
+        expect(status).toBe(1);
+        expect(out).toMatch(/gen is a symlink/);
+        expect(filesUnder(outside)).toEqual([]);
+    });
+
+    it("gen icons refuses an --out outside the project", () => {
+        const { status, out } = tempest("gen", "icons", "--out", join(outside, "icons.ts"));
+        expect(status).toBe(1);
+        expect(out).toMatch(/outside the project/);
+        expect(filesUnder(outside)).toEqual([]);
+    });
+});