@cardanvil/frame-kit 0.3.0 → 0.4.0

package/README.md

@@ -74,6 +74,25 @@ reports everything; under GitHub Actions they become inline annotations.
 
 Exit codes: `0` clean, `1` one or more frames failed, `2` used wrongly.
 
+### Frames you do not want to ship
+
+A descriptor can opt its frame out of every build:
+
+```json
+{
+  "id": "com.example.example",
+  "private": true,
+  "author": { "name": "Your Name" },
+  "license": "CC-BY-4.0"
+}
+```
+
+`validate` still loads and checks it; `build` reports it as skipped and packs
+nothing, so it never reaches a bundle, the index, or a release. That is the
+combination a worked example needs — a reference frame stays in the repository
+and stays correct, without an `id` that is permanent identity ending up in
+somebody's release by accident.
+
 ### `--watch`
 
 `build --watch` builds once, then rebuilds only the frames whose files changed,

package/dist/cli/atomic.d.ts

@@ -5,7 +5,8 @@
  * written — Card Anvil re-reads a bundle the moment it changes. Writing in
  * place would hand it a truncated zip whenever the timing was unlucky, so
  * every output is written to a temp file and renamed into position, which is
- * atomic on every platform this runs on.
+ * atomic on every platform this runs on — see {@link renameWhenFree} for the
+ * one thing Windows asks for in return.
  */
 export declare function writeFileAtomic(file: string, data: string | Uint8Array): Promise<void>;
 /** Streams to `file` atomically. Returns the number of bytes written. */

package/dist/cli/atomic.js

@@ -2,6 +2,7 @@ import { createWriteStream } from "node:fs";
 import { copyFile, rename, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { pipeline } from "node:stream/promises";
+import { setTimeout as delay } from "node:timers/promises";
 /**
  * A temp name beside the destination.
  *
@@ -15,6 +16,49 @@ function tempFor(file) {
 async function discard(temp) {
     await rm(temp, { force: true });
 }
+/**
+ * What Windows reports when something else has the destination open.
+ *
+ * `EBUSY` and `EACCES` for the same situation on network shares and some
+ * antivirus filters.
+ */
+const HELD_OPEN = new Set(["EPERM", "EACCES", "EBUSY"]);
+/** Backoff between rename attempts. */
+const RETRY_DELAYS_MS = [10, 20, 40, 80, 160, 320, 640, 1000];
+const TOTAL_WAIT_MS = RETRY_DELAYS_MS.reduce((a, b) => a + b, 0);
+/**
+ * Renames, waiting out anything that has the destination open.
+ *
+ * POSIX lets a file be replaced while it is being read. Windows does not: a
+ * rename onto a path some process holds open fails outright. A linked folder
+ * exists precisely to be read — Card Anvil re-reads a bundle whenever it
+ * changes — so a rebuild that lands mid-read hits this, and so do antivirus
+ * and search indexers, which open files briefly on their own schedule.
+ *
+ * Waiting is the whole fix: whatever holds the file is finishing a read that
+ * takes milliseconds. A real permission problem still fails, two seconds later.
+ */
+async function renameWhenFree(temp, file) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            await rename(temp, file);
+            return;
+        }
+        catch (cause) {
+            const code = cause.code ?? "";
+            if (!HELD_OPEN.has(code)) {
+                throw cause;
+            }
+            const wait = RETRY_DELAYS_MS[attempt];
+            if (wait === undefined) {
+                // `EPERM: operation not permitted, rename` says nothing about what to
+                // do. Whatever is holding the file is the thing to go and close.
+                throw new Error(`could not replace ${path.basename(file)}: something still has it open after ${String(TOTAL_WAIT_MS)}ms (${code}). On Windows a file cannot be replaced while another process holds it — close whatever is reading it, or point the build somewhere else.`, { cause });
+            }
+            await delay(wait);
+        }
+    }
+}
 /**
  * Writes `file` so that a reader never sees a partial one.
  *
@@ -22,13 +66,14 @@ async function discard(temp) {
  * written — Card Anvil re-reads a bundle the moment it changes. Writing in
  * place would hand it a truncated zip whenever the timing was unlucky, so
  * every output is written to a temp file and renamed into position, which is
- * atomic on every platform this runs on.
+ * atomic on every platform this runs on — see {@link renameWhenFree} for the
+ * one thing Windows asks for in return.
  */
 export async function writeFileAtomic(file, data) {
     const temp = tempFor(file);
     try {
         await writeFile(temp, data);
-        await rename(temp, file);
+        await renameWhenFree(temp, file);
     }
     catch (cause) {
         await discard(temp);
@@ -47,7 +92,7 @@ stream) {
     });
     try {
         await pipeline(stream, createWriteStream(temp));
-        await rename(temp, file);
+        await renameWhenFree(temp, file);
         return bytes;
     }
     catch (cause) {
@@ -60,7 +105,7 @@ export async function copyFileAtomic(source, dest) {
     const temp = tempFor(dest);
     try {
         await copyFile(source, temp);
-        await rename(temp, dest);
+        await renameWhenFree(temp, dest);
     }
     catch (cause) {
         await discard(temp);

package/dist/cli/build.d.ts

@@ -25,6 +25,8 @@ export interface BuiltFrame {
 }
 export interface BuildResult {
     frames: BuiltFrame[];
+    /** Frames marked `private` in their descriptor. Checked, then left alone. */
+    skipped: LoadedFrame[];
     /** Written to `<out>/frame-index.json` unless nothing built. */
     index?: FrameIndex;
 }

package/dist/cli/build.js

@@ -5,6 +5,7 @@ import { DEFAULT_CANVAS_HEIGHT, DEFAULT_CANVAS_WIDTH, } from "../schema/frame.js
 import { loadFrames } from "./api.js";
 import { copyFileAtomic, writeFileAtomic } from "./atomic.js";
 import { describeBytes, writeBundle } from "./bundle.js";
+import { relativePosix } from "./discover.js";
 import { PackagingError } from "./errors.js";
 import { FRAME_INDEX_FILENAME, buildIndex, downloadBase, } from "./frameIndex.js";
 import { hashFile, mapWithConcurrency } from "./hash.js";
@@ -29,17 +30,33 @@ existingServer) {
             `optionally with a pre-release suffix.`);
     }
     const loaded = await loadFrames(options, reporter, existingServer);
+    // Validated above like any other frame, then dropped: `private` says this
+    // one exists to be read, not shipped.
+    const skipped = loaded.filter((frame) => frame.discovered.meta.private);
+    const shippable = loaded.filter((frame) => !frame.discovered.meta.private);
+    for (const frame of skipped) {
+        // Silence would look like a broken build to whoever asked for this frame
+        // by name. Frames merely swept up by a whole-repository build say nothing.
+        if (options.only?.includes(frame.discovered.slug)) {
+            reporter.warn({
+                frame: frame.discovered.slug,
+                file: relativePosix(path.resolve(options.root), frame.discovered.metaFile),
+                message: `is private, so it was not built. Remove "private" from its ` +
+                    `frame.meta.json to ship it.`,
+            });
+        }
+    }
     const outDir = path.resolve(options.outDir);
     await mkdir(outDir, { recursive: true });
     const built = [];
-    for (const frame of loaded) {
+    for (const frame of shippable) {
         const result = await buildOne(frame, outDir, options, reporter);
         if (result) {
             built.push(result);
         }
     }
     if (built.length === 0) {
-        return { frames: built };
+        return { frames: built, skipped };
     }
     const index = buildIndex({
         version: options.version,
@@ -50,7 +67,7 @@ existingServer) {
         frames: built.map((frame) => frame.entry),
     });
     await writeFileAtomic(path.join(outDir, FRAME_INDEX_FILENAME), stableStringify(index));
-    return { frames: built, index };
+    return { frames: built, skipped, index };
 }
 async function buildOne(loaded, outDir, options, reporter) {
     const slug = loaded.discovered.slug;

package/dist/cli/main.js

@@ -35,7 +35,8 @@ build only:
                         in the index
   --watch               rebuild a frame whenever its source changes
 
-A frame is any directory containing a frame.meta.json.
+A frame is any directory containing a frame.meta.json. One with "private": true
+is checked by validate but never built.
 `;
 /** 0 clean · 1 one or more frames failed · 2 the command was used wrongly. */
 const EXIT = { ok: 0, failed: 1, usage: 2 };
@@ -119,7 +120,7 @@ async function runBuild(root, only, values) {
         return EXIT.ok;
     }
     const reporter = new Reporter();
-    const { frames: built } = await buildFrames({
+    const { frames: built, skipped } = await buildFrames({
         root,
         only,
         outDir: values.out,
@@ -140,6 +141,11 @@ async function runBuild(root, only, values) {
                 bundle: frame.bundleName,
                 bytes: frame.bytes,
             })),
+            skipped: skipped.map((frame) => ({
+                id: frame.discovered.meta.id,
+                slug: frame.discovered.slug,
+                reason: "private",
+            })),
             problems: reporter.problems,
         }, null, 2));
     }
@@ -148,6 +154,9 @@ async function runBuild(root, only, values) {
         for (const frame of built) {
             console.log(`${frame.bundleName}  ${describeBytes(frame.bytes)}`);
         }
+        for (const frame of skipped) {
+            console.log(`${frame.discovered.slug}  skipped (private)`);
+        }
         summarise(reporter, built.length);
     }
     return reporter.ok ? EXIT.ok : EXIT.failed;

package/dist/cli/watch.js

@@ -156,6 +156,9 @@ export async function slugsFor(root, changed, only) {
         if (!owner) {
             return undefined; // outside every frame — something shared changed
         }
+        if (owner.meta.private) {
+            continue; // a build would skip it anyway; do not announce a rebuild
+        }
         if (wanted.size === 0 || wanted.has(owner.slug)) {
             slugs.add(owner.slug);
         }

package/dist/schema/frameMeta.d.ts

@@ -14,6 +14,7 @@ export declare const FrameMetaSchema: z.ZodObject<{
     slug: z.ZodOptional<z.ZodString>;
     entry: z.ZodDefault<z.ZodString>;
     export: z.ZodDefault<z.ZodString>;
+    private: z.ZodDefault<z.ZodBoolean>;
     author: z.ZodObject<{
         name: z.ZodString;
         url: z.ZodOptional<z.ZodURL>;

package/dist/schema/frameMeta.js

@@ -33,6 +33,18 @@ export const FrameMetaSchema = z.object({
     entry: z.string().default("./index.ts"),
     /** Named export to read from `entry`. */
     export: z.string().default("default"),
+    /**
+     * Keeps the frame out of every build: it is never packaged, never indexed
+     * and never released. `validate` still loads and checks it, so a frame
+     * nobody ships cannot quietly rot.
+     *
+     * The author template's `example` frame is the case this exists for. It has
+     * to stay in the repository because `new-frame` copies it, but an id is
+     * permanent identity — publishing it would put the same
+     * `com.example.example` in every release by every author who forgot to
+     * delete it.
+     */
+    private: z.boolean().default(false),
     author: z.object({
         name: z.string().min(1),
         url: z.url().optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cardanvil/frame-kit",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "The contract Card Anvil frames are authored against: schemas, types, authoring helpers, and the distributable manifest format.",
   "license": "MIT",
   "type": "module",

package/schema/frame-meta.schema.json

@@ -40,6 +40,10 @@
       "minLength": 1,
       "type": "string"
     },
+    "private": {
+      "default": false,
+      "type": "boolean"
+    },
     "slug": {
       "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
       "type": "string"