@cardanvil/frame-kit 0.3.1 → 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/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.1",
+  "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"