@cloudcrane/app-spec 0.0.0-stage → 0.1.1

package/dist/src/schema.js

@@ -0,0 +1,137 @@
+import { z } from "zod";
+// The CloudCrane app spec: an A2UI surface (the screens) in a small envelope for
+// what A2UI doesn't cover. Nothing in it is code from the app it came from:
+// screens are A2UI components, the look is DTCG design tokens, rules are CEL
+// expressions, saved data is described by a JSON Schema. Strict throughout, so a
+// field the spec doesn't define (where code could hide) is refused.
+/** A neutral id: lower-case words, dots, dashes, underscores. Partner symbol names live only in provenance. */
+export const Id = z.string().regex(/^[a-z][a-zA-Z0-9_.-]{0,63}$/, "an id: a letter, then letters, digits, . _ or -, at most 64");
+/** A CEL identifier (constants and parameters): letters, digits and underscores. */
+export const CelName = z.string().regex(/^[A-Za-z_][A-Za-z0-9_]{0,63}$/, "a CEL identifier: letters, digits and _");
+/** An RFC 6901 JSON Pointer. */
+export const Pointer = z.string().regex(/^(\/([^~/]|~[01])*)*$/, "a JSON Pointer, like /saved/days");
+/** A pointer, or a pointer ending in /* for everything under it (mod points). */
+export const PointerPattern = z.string().regex(/^(\/([^~/*]|~[01])*)*(\/\*)?$/, "a JSON Pointer, optionally ending in /*");
+const Text = (max) => z.string().min(1).max(max);
+/** DTCG Format 2025.10 (designtokens.org): a token has $value; a group holds tokens and groups. */
+const DTCG_TYPES = [
+    "color",
+    "dimension",
+    "fontFamily",
+    "fontWeight",
+    "duration",
+    "cubicBezier",
+    "number",
+    "strokeStyle",
+    "border",
+    "transition",
+    "shadow",
+    "gradient",
+    "typography",
+];
+export const Tokens = z.lazy(() => z
+    .object({ $value: z.unknown().optional(), $type: z.enum(DTCG_TYPES).optional(), $description: z.string().max(200).optional() })
+    .catchall(Tokens)
+    .superRefine((node, ctx) => {
+    const children = Object.keys(node).filter((k) => !k.startsWith("$"));
+    if (node.$value !== undefined && children.length)
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "a token can't also be a group" });
+    for (const k of children)
+        if (!/^[A-Za-z0-9_-]{1,40}$/.test(k))
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: `token name "${k}"` });
+}));
+/** A CEL expression (cel.dev); parsed and checked by the logic validator. */
+const Cel = z.string().min(1).max(4000);
+export const SpecSchema = z
+    .object({
+    v: z.literal(1),
+    manifest: z
+        .object({
+        runtime: z.string().regex(/^\d+\.\d+\.\d+$/, "the runtime version, like 0.1.0"),
+        generator: Text(80),
+        source: z.object({ fingerprint: z.string().regex(/^sha256:[0-9a-f]{64}$/, "sha256:<64 hex>: a hash of the source, never the source") }).strict(),
+    })
+        .strict(),
+    module: z
+        .object({
+        id: Id,
+        name: Text(60),
+        purpose: Text(400),
+        /** How CloudCrane lists it: one of its icon names, its category, up to five tags (CloudCrane checks them). */
+        icon: z
+            .string()
+            .regex(/^[a-z][a-z0-9-]{0,39}$/)
+            .optional(),
+        category: z
+            .string()
+            .regex(/^[a-z][a-z0-9-]{0,39}$/)
+            .optional(),
+        tags: z
+            .array(z
+            .string()
+            .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/)
+            .max(24))
+            .max(5)
+            .optional(),
+    })
+        .strict(),
+    tokens: Tokens,
+    /** A2UI v0.9.1 messages, the way A2UI's own samples hold them; checked by surfaceProblems. */
+    surface: z.object({ catalog: z.string().url(), messages: z.array(z.record(z.unknown())).min(2).max(200) }).strict(),
+    data: z
+        .object({
+        version: z.number().int().min(1),
+        /** Where it's saved on the phone. */
+        key: z.string().regex(/^[a-z][a-z0-9._-]{0,63}$/),
+        /** The part of the A2UI data model that's saved; the rest is screen state. */
+        persist: Pointer,
+        /** JSON Schema of the saved data. */
+        schema: z.record(z.unknown()),
+        initial: z.unknown(),
+        /**
+         * Two-way views: the runtime keeps `path` equal to the data at `source` (a
+         * pointer with A2UI's ${/path} interpolation, like /saved/days/${/ui/selected}),
+         * and writes edits made through the view back there. For lists a screen shows
+         * by a choice the person makes, since A2UI templates take a fixed path.
+         */
+        views: z
+            .array(z.object({ path: Pointer, source: z.string().regex(/^(\/([^~/$]|~[01]|\$\{\/[^}]*\})*)+$/, "a pointer, with ${/path} parts") }).strict())
+            .max(10)
+            .default([]),
+        /** Each step turns version `from` into `to`, as a CEL expression over `saved`. */
+        migrations: z.array(z.object({ from: z.number().int().min(1), to: z.number().int().min(2), cel: Cel }).strict()),
+    })
+        .strict(),
+    logic: z
+        .object({
+        consts: z.record(CelName, z.union([z.number(), z.string(), z.boolean()])).default({}),
+        functions: z.record(CelName, z.object({ params: z.array(CelName).max(8), cel: Cel }).strict()).default({}),
+        /** Values the screens read, kept up to date: a data-model pointer and the CEL that computes it. */
+        computed: z.record(Pointer, Cel).default({}),
+        /** Examples each function must reproduce: recorded from the source's own tests, or given. */
+        vectors: z.array(z.object({ fn: CelName, in: z.array(z.unknown()).max(8), out: z.unknown(), from: z.enum(["recorded", "hint"]) }).strict()).default([]),
+    })
+        .strict(),
+    network: z
+        .array(z.object({ site: z.string().regex(/^[a-z0-9.-]+\.[a-z]{2,}$/), why: Text(300) }).strict())
+        .max(5)
+        .default([]),
+    journeys: z
+        .array(z
+        .object({
+        id: z.string().regex(/^J-\d+$/),
+        title: Text(120),
+        steps: z.array(z.object({ id: z.string().regex(/^J-\d+\.\d+$/), text: Text(400) }).strict()).min(1),
+    })
+        .strict())
+        .min(1),
+    promises: z.array(z.object({ id: z.string().regex(/^P-\d+$/), text: Text(400), kind: z.literal("data").optional() }).strict()).default([]),
+    /** CloudCrane's test steps, as its blueprint tests take them; CloudCrane checks their shape. */
+    tests: z.array(z.record(z.unknown())).max(30).default([]),
+    /** What a remix may change and what stays as the partner made it. */
+    mods: z
+        .object({ open: z.array(PointerPattern), locked: z.array(PointerPattern) })
+        .strict()
+        .default({ open: [], locked: [] }),
+})
+    .strict();

package/dist/src/validate.d.ts

@@ -0,0 +1,6 @@
+import { type Catalog, type Problem } from "./a2ui.js";
+import { type Spec } from "./schema.js";
+export declare function validateSpec(input: unknown, catalog?: Catalog): {
+    spec: Spec | null;
+    problems: Problem[];
+};

package/dist/src/validate.js

@@ -0,0 +1,54 @@
+import { surfaceProblems } from "./a2ui.js";
+import { catalogFor } from "./catalog.js";
+import { leakProblems } from "./leak.js";
+import { logicProblems } from "./logic.js";
+import { SpecSchema } from "./schema.js";
+// Everything wrong with a spec, collected rather than stopping at the first: the
+// envelope's shape, then the A2UI surface, then references between parts.
+const pathOf = (path) => path
+    .map((p) => (typeof p === "number" ? `[${p}]` : `.${p}`))
+    .join("")
+    .replace(/^\./, "");
+export function validateSpec(input, catalog) {
+    const parsed = SpecSchema.safeParse(input);
+    if (!parsed.success)
+        return { spec: null, problems: parsed.error.issues.map((i) => ({ at: pathOf(i.path) || "spec", problem: i.message })) };
+    const spec = parsed.data;
+    // The surface is checked against the catalog it names (CloudCrane's, or A2UI's basic one).
+    const named = catalog ?? catalogFor(spec.surface.catalog);
+    if (!named)
+        return { spec: null, problems: [{ at: "surface.catalog", problem: "not a catalog this runtime has" }] };
+    const problems = [...surfaceProblems(spec.surface.messages, named)];
+    const catalogId = spec.surface.messages[0].createSurface?.catalogId;
+    if (catalogId && catalogId !== spec.surface.catalog)
+        problems.push({ at: "surface.catalog", problem: "must be the catalog createSurface names" });
+    const ids = new Set();
+    for (const j of spec.journeys) {
+        if (ids.has(j.id))
+            problems.push({ at: `journeys ${j.id}`, problem: "duplicate id" });
+        ids.add(j.id);
+        for (const s of j.steps) {
+            if (!s.id.startsWith(`${j.id}.`))
+                problems.push({ at: `journeys ${s.id}`, problem: `a step of ${j.id} is numbered ${j.id}.n` });
+            if (ids.has(s.id))
+                problems.push({ at: `journeys ${s.id}`, problem: "duplicate id" });
+            ids.add(s.id);
+        }
+    }
+    for (const p of spec.promises) {
+        if (ids.has(p.id))
+            problems.push({ at: `promises ${p.id}`, problem: "duplicate id" });
+        ids.add(p.id);
+    }
+    for (const v of spec.logic.vectors)
+        if (!(v.fn in spec.logic.functions))
+            problems.push({ at: `logic.vectors ${v.fn}`, problem: "no such function" });
+    for (const m of spec.data.migrations)
+        if (m.to !== m.from + 1 || m.to > spec.data.version)
+            problems.push({ at: `data.migrations ${m.from}`, problem: "steps go one version at a time, up to data.version" });
+    problems.push(...logicProblems(spec), ...leakProblems(spec));
+    for (const locked of spec.mods.locked)
+        if (spec.mods.open.includes(locked))
+            problems.push({ at: `mods ${locked}`, problem: "both open and locked" });
+    return { spec: problems.length ? null : spec, problems };
+}