@cloudcrane/blackbox 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chirag Phor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,27 @@
-# Temporary Holding Version
+# @cloudcrane/blackbox
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Blackbox CLI: write a CloudCrane app spec from your app's code, check it,
+and build or preview the app it describes. See the
+[Blackbox repo](https://github.com/cloudcrane-dev/blackbox) for what a spec is.
+
+```
+npx @cloudcrane/blackbox extract . --hints blackbox.hints.json --out blackbox/plans
+npx @cloudcrane/blackbox validate blackbox/plans/spec.json
+npx @cloudcrane/blackbox build blackbox/plans/spec.json --out app.html
+npx @cloudcrane/blackbox preview blackbox/plans/spec.json
+npx @cloudcrane/blackbox diff . --range main..HEAD
+```
+
+| Command                | What it does                                                                                   |
+| ---------------------- | ---------------------------------------------------------------------------------------------- |
+| `extract <repo>`       | Writes `spec.json`, `provenance.json` and `report.md` from your code and `blackbox.hints.json` |
+| `diff <repo>`          | Lists the parts of the spec whose cited code changed                                           |
+| `validate <spec.json>` | Checks the schema, the A2UI screens, the rules against their examples, and for leaked code     |
+| `build <spec.json>`    | Builds the app page; the same bytes every time                                                 |
+| `preview <spec.json>`  | Serves the app locally under CloudCrane's content security policy                              |
+
+Extraction runs on your machine. It reads your code; it never runs it and sends
+nothing anywhere. Keep `provenance.json` and `blackbox.hints.json` to yourself:
+they name your files.
+
+Node 22.5 or later. MIT licensed.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { build, diff, extract, preview, validate } from "./commands.js";
+// blackbox: write a CloudCrane app spec from an app's code, see what a code
+// change touched, and validate, build and preview a spec.
+const USAGE = `blackbox <command> <path> [options]
+
+  extract  <repo> [--hints FILE] [--out DIR]   write a spec from an app's code and its blackbox.hints.json
+  diff     <repo> [--module ID] [--range A..B] which parts of the spec a code change touched
+  validate <spec.json>                 check a spec: schema, A2UI surface, rules, leaks
+  build    <spec.json> [--out FILE]    build the app page (the same bytes every time)
+  preview  <spec.json> [--port N]      serve the app here, under CloudCrane's security policy`;
+const print = (o) => {
+    for (const l of o.lines)
+        (o.ok ? console.log : console.error)(l);
+    return o.ok ? 0 : 1;
+};
+async function main(argv) {
+    const { positionals, values } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            out: { type: "string" },
+            port: { type: "string" },
+            hints: { type: "string" },
+            module: { type: "string" },
+            range: { type: "string" },
+            help: { type: "boolean", short: "h" },
+        },
+    });
+    const [command, file] = positionals;
+    if (values.help || !command) {
+        console.log(USAGE);
+        return command ? 0 : 1;
+    }
+    if (!file) {
+        console.error(`${command} needs a spec file.\n\n${USAGE}`);
+        return 1;
+    }
+    if (command === "extract")
+        return print(extract(file, values.hints, values.out));
+    if (command === "diff")
+        return print(diff(file, values.module, values.range));
+    if (command === "validate")
+        return print(validate(file));
+    if (command === "build")
+        return print(build(file, values.out));
+    if (command === "preview") {
+        const { url } = await preview(file, values.port ? Number(values.port) : 5420);
+        console.log(`Previewing at ${url} (Ctrl+C to stop)`);
+        return new Promise(() => { });
+    }
+    console.error(`Unknown command: ${command}\n\n${USAGE}`);
+    return 1;
+}
+main(process.argv.slice(2)).then((code) => process.exit(code), (e) => {
+    console.error(e.message);
+    process.exit(1);
+});

package/dist/commands.d.ts

@@ -0,0 +1,18 @@
+import { type Server } from "node:http";
+export type Outcome = {
+    ok: boolean;
+    lines: string[];
+};
+/** blackbox validate <spec.json>: every problem, or that it's ready. */
+export declare function validate(file: string): Outcome;
+/** blackbox build <spec.json> [--out app.html]: the app page and its hash. */
+export declare function build(file: string, out?: string): Outcome;
+/** blackbox preview <spec.json> [--port 5420]: the app as a phone gets it, on this machine, under CloudCrane's policy. */
+export declare function preview(file: string, port?: number): Promise<{
+    server: Server;
+    url: string;
+}>;
+/** blackbox extract <repo> [--hints FILE] [--out DIR]: the spec, its provenance and a report, from an app's code and hints. */
+export declare function extract(repo: string, hintsFile?: string, outDir?: string): Outcome;
+/** blackbox diff <repo> [--module ID] [--range A..B]: which parts of the spec a change to the code touched. */
+export declare function diff(repo: string, module?: string, range?: string): Outcome;

package/dist/commands.js

@@ -0,0 +1,92 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { createServer } from "node:http";
+import { validateSpec } from "@cloudcrane/app-spec";
+import { compile, CompileError } from "@cloudcrane/app-runtime";
+import { appCsp } from "./csp.js";
+import { extract as extractSpec } from "./extract.js";
+import { touchedBy } from "./diff.js";
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+const readSpec = (file) => {
+    try {
+        return JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch (e) {
+        throw new Error(`Couldn't read ${file} as JSON: ${e.message}`);
+    }
+};
+/** blackbox validate <spec.json>: every problem, or that it's ready. */
+export function validate(file) {
+    const { spec, problems } = validateSpec(readSpec(file));
+    if (spec)
+        return {
+            ok: true,
+            lines: [`${file}: ready. ${spec.journeys.length} journeys, ${spec.promises.length} promises, ${Object.keys(spec.logic.functions).length} rules.`],
+        };
+    return { ok: false, lines: [`${file}: ${problems.length} problem${problems.length === 1 ? "" : "s"}`, ...problems.map((p) => `  ${p.at}: ${p.problem}`)] };
+}
+/** blackbox build <spec.json> [--out app.html]: the app page and its hash. */
+export function build(file, out) {
+    try {
+        const { html, sha256, runtime } = compile(readSpec(file));
+        if (out)
+            writeFileSync(out, html);
+        return { ok: true, lines: [`${out ?? "(not written)"}: ${Buffer.byteLength(html)} bytes, sha256 ${sha256}, ${runtime}`] };
+    }
+    catch (e) {
+        if (e instanceof CompileError)
+            return { ok: false, lines: [`${file} can't be built:`, ...e.problems.map((p) => `  ${p.at}: ${p.problem}`)] };
+        throw e;
+    }
+}
+/** blackbox preview <spec.json> [--port 5420]: the app as a phone gets it, on this machine, under CloudCrane's policy. */
+export function preview(file, port = 5420) {
+    const spec = readSpec(file);
+    const { html } = compile(spec);
+    const csp = appCsp((spec.network ?? []).map((n) => n.site));
+    const server = createServer((req, res) => {
+        if (req.url !== "/" && req.url !== "/index.html") {
+            res.writeHead(404).end();
+            return;
+        }
+        res.writeHead(200, {
+            "content-type": "text/html; charset=utf-8",
+            "content-security-policy": csp,
+            "cache-control": "no-store",
+            "x-content-type-options": "nosniff",
+        });
+        res.end(html);
+    });
+    return new Promise((resolve) => server.listen(port, "127.0.0.1", () => resolve({ server, url: `http://127.0.0.1:${server.address().port}/` })));
+}
+/** blackbox extract <repo> [--hints FILE] [--out DIR]: the spec, its provenance and a report, from an app's code and hints. */
+export function extract(repo, hintsFile = join(repo, "blackbox.hints.json"), outDir) {
+    const hints = readSpec(hintsFile);
+    const r = extractSpec(repo, hints);
+    const dir = outDir ?? join(repo, "blackbox", hints.module.id);
+    mkdirSync(dir, { recursive: true });
+    // canonical-ish: stable key order and two-space indents, so a re-run with nothing changed writes the same bytes.
+    const stable = (v) => `${JSON.stringify(v, (_k, x) => (x && typeof x === "object" && !Array.isArray(x) ? Object.fromEntries(Object.entries(x).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) : x), 2)}\n`;
+    writeFileSync(join(dir, "spec.json"), stable(r.spec ?? r.draft));
+    writeFileSync(join(dir, "provenance.json"), stable(r.provenance));
+    writeFileSync(join(dir, "report.md"), r.report);
+    return {
+        ok: !!r.spec,
+        lines: [r.report.split("\n")[2], `Wrote ${dir}/spec.json, provenance.json and report.md`, ...r.problems.map((p) => `  ${p.at}: ${p.problem}`)],
+    };
+}
+/** blackbox diff <repo> [--module ID] [--range A..B]: which parts of the spec a change to the code touched. */
+export function diff(repo, module, range) {
+    const id = module ?? readSpec(join(repo, "blackbox.hints.json")).module.id;
+    const provenance = readSpec(join(repo, "blackbox", id, "provenance.json"));
+    const touched = touchedBy(repo, provenance, range);
+    if (!touched.length)
+        return { ok: true, lines: [`Nothing in the ${id} spec is touched${range ? ` by ${range}` : " by the uncommitted changes"}.`] };
+    return {
+        ok: true,
+        lines: [
+            `${touched.length} part${touched.length === 1 ? "" : "s"} of the ${id} spec touched; run blackbox extract to regenerate:`,
+            ...touched.map((t) => `  ${t.pointer} (${t.why}: ${t.file}:${t.lines.join("-")})`),
+        ],
+    };
+}

package/dist/csp.d.ts

@@ -0,0 +1 @@
+export declare function appCsp(sites: readonly string[]): string;

package/dist/csp.js

@@ -0,0 +1,24 @@
+// The security policy CloudCrane's apps host serves every app with (appCsp in
+// CloudCrane's apps-host/host.rules.ts), word for word, so a preview behaves as
+// the app will on a phone: no scripts, styles or fonts from other sites, no eval,
+// and only the sites the spec lists reachable.
+const SITE = /^(?=.{1,253}$)([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/;
+export function appCsp(sites) {
+    const listed = [...new Set(sites.map((s) => s.toLowerCase()))].filter((s) => SITE.test(s));
+    const https = listed.map((s) => ` https://${s}`).join("");
+    const connect = listed.map((s) => ` https://${s} wss://${s}`).join("");
+    return [
+        "default-src 'none'",
+        "script-src 'self' 'unsafe-inline'",
+        "style-src 'self' 'unsafe-inline'",
+        `img-src 'self' data: blob:${https}`,
+        "media-src 'self' data: blob:",
+        "font-src 'self' data:",
+        `connect-src 'self'${connect}`,
+        "manifest-src 'self'",
+        "worker-src 'self'",
+        "form-action 'self'",
+        "frame-ancestors 'none'",
+        "base-uri 'none'",
+    ].join("; ");
+}

package/dist/diff.d.ts

@@ -0,0 +1,8 @@
+import type { Provenance } from "./extract.js";
+export type Touched = {
+    pointer: string;
+    file: string;
+    lines: [number, number];
+    why: "changed" | "deleted" | "renamed";
+};
+export declare function touchedBy(repo: string, provenance: Provenance, range?: string): Touched[];

package/dist/diff.js

@@ -0,0 +1,28 @@
+import { execFileSync } from "node:child_process";
+import { parseDiff, touches } from "veridic/staleness";
+export function touchedBy(repo, provenance, range) {
+    const files = new Set(Object.values(provenance.elements).flatMap((cs) => cs.filter((c) => c.how !== "hint").map((c) => c.file)));
+    if (!files.size)
+        return [];
+    const args = ["diff", "--unified=0", "-M", "--no-color", "--no-ext-diff", ...(range ? [range] : []), "--", ...[...files].sort()];
+    const changes = parseDiff(execFileSync("git", args, { cwd: repo, encoding: "utf8" }));
+    const out = [];
+    for (const [pointer, cites] of Object.entries(provenance.elements).sort(([a], [b]) => (a < b ? -1 : 1))) {
+        for (const c of cites) {
+            if (c.how === "hint")
+                continue;
+            const change = changes.get(c.file);
+            if (!change)
+                continue;
+            if (change.status === "deleted" || change.status === "renamed") {
+                out.push({ pointer, file: c.file, lines: c.lines, why: change.status });
+                break;
+            }
+            if (change.hunks.some((h) => touches(h, c.lines[0], c.lines[1]))) {
+                out.push({ pointer, file: c.file, lines: c.lines, why: "changed" });
+                break;
+            }
+        }
+    }
+    return out;
+}

package/dist/extract.d.ts

@@ -0,0 +1,46 @@
+import { type Problem, type Spec } from "@cloudcrane/app-spec";
+export declare const GENERATOR = "blackbox@0.1.0";
+/** blackbox.hints.json: where things are, and what the readers can't find yet (as spec parts). */
+export type Hints = {
+    module: Spec["module"];
+    /** roles: a theme colour's name → the token path(s) it sets, like ["color", "primary"] or [["color", "on-background"], ["color", "on-surface"]]. */
+    theme?: {
+        file: string;
+        mode?: "dark" | "light";
+        roles?: Record<string, string[] | string[][]>;
+    };
+    rules?: {
+        files: string[];
+        tests?: string[];
+    };
+    tokens?: Record<string, unknown>;
+    surface: Spec["surface"];
+    data: Spec["data"];
+    logic?: Partial<Spec["logic"]>;
+    network?: Spec["network"];
+    journeys: Spec["journeys"];
+    promises?: Spec["promises"];
+    tests?: Spec["tests"];
+    mods?: Spec["mods"];
+};
+export type Citation = {
+    file: string;
+    lines: [number, number];
+    hash: string;
+    how: "flutter-theme" | "ts-pure" | "ts-vectors" | "hint";
+    symbol?: string;
+};
+export type Provenance = {
+    generator: string;
+    spec: string;
+    source: string;
+    elements: Record<string, Citation[]>;
+};
+export type Extracted = {
+    spec: Spec | null;
+    draft: unknown;
+    provenance: Provenance;
+    report: string;
+    problems: Problem[];
+};
+export declare function extract(repo: string, hints: Hints): Extracted;

package/dist/extract.js

@@ -0,0 +1,160 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { canonical, validateSpec } from "@cloudcrane/app-spec";
+import { RUNTIME_VERSION } from "@cloudcrane/app-runtime";
+import { citeHash } from "veridic/citations";
+import { readFlutterTheme, ROLES } from "./readers/flutter-theme.js";
+import { translateModule } from "./readers/ts-pure.js";
+import { harvestVectors } from "./readers/ts-vectors.js";
+import { shingleLeaks } from "./shingles.js";
+// blackbox extract: a CloudCrane spec from an app's own code, plus the partner's
+// hints for what can't be read yet. Read, never run. What's read is cited in
+// provenance.json (stays in the partner's repo): each spec element, by JSON
+// Pointer, with the file, lines and a hash of those lines (Veridic's citeHash),
+// and how it was found. The spec itself holds no code and no paths: the
+// validator and the leak gates refuse any.
+export const GENERATOR = "blackbox@0.1.0";
+const escapePointer = (s) => s.replace(/~/g, "~0").replace(/\//g, "~1");
+const sha = (s) => createHash("sha256").update(s).digest("hex");
+export function extract(repo, hints) {
+    const read = (file) => readFileSync(join(repo, file), "utf8");
+    const cite = (file, [a, b], how, symbol) => {
+        const lines = read(file)
+            .split("\n")
+            .slice(a - 1, b);
+        return { file, lines: [a, b], hash: citeHash(lines), how, ...(symbol ? { symbol } : {}) };
+    };
+    const elements = {};
+    const add = (pointer, c) => (elements[pointer] ??= []).push(c);
+    const notes = [];
+    const cited = new Set();
+    // Tokens: the theme's colours by role, its font and radius; the hints may add or override.
+    const tokens = {};
+    if (hints.theme) {
+        const { file, mode = "dark", roles = {} } = hints.theme;
+        cited.add(file);
+        const theme = readFlutterTheme(read(file));
+        const map = { ...ROLES, ...roles };
+        for (const c of theme.colors) {
+            const role = map[c.name];
+            if (!role)
+                continue;
+            const paths = (Array.isArray(role[0]) ? role : [role]);
+            for (const [group, name] of paths) {
+                (tokens[group] ??= { $type: "color" })[name] = { $value: mode === "dark" ? c.dark : c.light };
+                add(`/tokens/${escapePointer(group)}/${escapePointer(name)}`, cite(file, [c.line, c.line], "flutter-theme", c.name));
+            }
+        }
+        if (theme.font) {
+            tokens["font-family"] = { $type: "fontFamily", $value: [theme.font.family, "system-ui", "sans-serif"] };
+            add("/tokens/font-family", cite(file, [theme.font.line, theme.font.line], "flutter-theme"));
+        }
+        if (theme.radius) {
+            tokens["border-radius"] = { $type: "dimension", $value: { value: theme.radius.value, unit: "px" } };
+            add("/tokens/border-radius", cite(file, [theme.radius.line, theme.radius.line], "flutter-theme"));
+        }
+    }
+    for (const [group, value] of Object.entries(hints.tokens ?? {})) {
+        if (value && typeof value === "object" && !("$value" in value)) {
+            tokens[group] = { ...(tokens[group] ?? {}), ...value };
+            for (const k of Object.keys(value))
+                if (!k.startsWith("$"))
+                    add(`/tokens/${escapePointer(group)}/${escapePointer(k)}`, { file: "blackbox.hints.json", lines: [0, 0], hash: "", how: "hint" });
+        }
+        else {
+            tokens[group] = value;
+            add(`/tokens/${escapePointer(group)}`, { file: "blackbox.hints.json", lines: [0, 0], hash: "", how: "hint" });
+        }
+    }
+    // Rules: the pure functions translated to CEL, vectors from the module's own tests.
+    const consts = {};
+    const functions = {};
+    const vectors = [];
+    for (const file of hints.rules?.files ?? []) {
+        cited.add(file);
+        const t = translateModule(read(file), file);
+        for (const c of t.consts) {
+            consts[c.name] = c.value;
+            add(`/logic/consts/${c.name}`, cite(file, c.lines, "ts-pure", c.name));
+        }
+        for (const f of t.functions) {
+            functions[f.name] = { params: f.params, cel: f.cel };
+            add(`/logic/functions/${f.name}`, cite(file, f.lines, "ts-pure", f.name));
+        }
+        for (const s of t.skipped)
+            notes.push(`- ${s.name} (${file.split("/").pop()}): not translated, ${s.why}`);
+    }
+    for (const file of hints.rules?.tests ?? []) {
+        cited.add(file);
+        const { vectors: found, leftOut } = harvestVectors(read(file), new Set(Object.keys(functions)), file);
+        for (const v of found) {
+            add(`/logic/vectors/${vectors.length}`, cite(file, [v.line, v.line], "ts-vectors", v.fn));
+            vectors.push({ fn: v.fn, in: v.in, out: v.out, from: "recorded" });
+        }
+        if (leftOut)
+            notes.push(`- ${leftOut} test call${leftOut === 1 ? "" : "s"} in ${file.split("/").pop()} not read as vectors (in a loop, or not plain values)`);
+    }
+    for (const [name, f] of Object.entries(hints.logic?.functions ?? {})) {
+        if (name in functions)
+            notes.push(`- ${name}: the hints' version replaces the translated one`);
+        functions[name] = f;
+        elements[`/logic/functions/${name}`] = [{ file: "blackbox.hints.json", lines: [0, 0], hash: "", how: "hint" }];
+    }
+    for (const v of hints.logic?.vectors ?? []) {
+        add(`/logic/vectors/${vectors.length}`, { file: "blackbox.hints.json", lines: [0, 0], hash: "", how: "hint" });
+        vectors.push(v);
+    }
+    for (const pointer of Object.keys(hints.logic?.computed ?? {}))
+        add(`/logic/computed/${escapePointer(pointer)}`, { file: "blackbox.hints.json", lines: [0, 0], hash: "", how: "hint" });
+    // The source's fingerprint: every cited file's content, by name, hashed. A hash, never the code.
+    const files = [...cited].sort();
+    const fingerprint = sha(files.map((f) => `${f}\0${sha(readFileSync(join(repo, f)))}`).join("\n"));
+    const draft = {
+        v: 1,
+        manifest: { runtime: RUNTIME_VERSION, generator: GENERATOR, source: { fingerprint: `sha256:${fingerprint}` } },
+        module: hints.module,
+        tokens,
+        surface: hints.surface,
+        data: hints.data,
+        logic: { consts: { ...consts, ...(hints.logic?.consts ?? {}) }, functions, computed: hints.logic?.computed ?? {}, vectors },
+        network: hints.network ?? [],
+        journeys: hints.journeys,
+        promises: hints.promises ?? [],
+        tests: hints.tests ?? [],
+        mods: hints.mods ?? { open: [], locked: [] },
+    };
+    for (const part of ["surface", "data", "journeys", "promises", "tests", "mods", "network", "module"])
+        if (part in hints)
+            add(`/${part}`, { file: "blackbox.hints.json", lines: [0, 0], hash: "", how: "hint" });
+    const { spec, problems } = validateSpec(draft);
+    // The second gate: nothing in the spec (outside its CEL rules) repeats the source's own words.
+    const shingles = shingleLeaks(draft, files.map(read));
+    const all = [...problems, ...shingles];
+    const counts = {};
+    for (const cs of Object.values(elements))
+        for (const c of cs)
+            counts[c.how] = (counts[c.how] ?? 0) + 1;
+    const report = [
+        `# ${hints.module.name}: what Blackbox read`,
+        "",
+        `Spec ${all.length ? `**not ready**: ${all.length} problem${all.length === 1 ? "" : "s"}` : "ready"}. Generated by ${GENERATOR} for runtime ${RUNTIME_VERSION}, from ${files.length} source files (fingerprint ${fingerprint.slice(0, 12)}).`,
+        "",
+        "## Where each part came from",
+        "",
+        ...Object.entries(counts)
+            .sort()
+            .map(([how, n]) => `- ${how}: ${n}`),
+        "",
+        `Read from the code: ${Object.keys(tokens).length ? "design tokens, " : ""}${Object.keys(functions).length - Object.keys(hints.logic?.functions ?? {}).length} rules, ${vectors.filter((v) => v.from === "recorded").length} vectors from the module's own tests.`,
+        "From hints: the screens, the saved-data shape, composed rules and computed values, journeys and promises.",
+        "",
+        "## Left out",
+        "",
+        ...(notes.length ? notes : ["- nothing"]),
+        "",
+        ...(all.length ? ["## Problems", "", ...all.map((p) => `- ${p.at}: ${p.problem}`), ""] : []),
+    ].join("\n");
+    const provenance = { generator: GENERATOR, spec: spec ? sha(canonical(spec)) : "", source: `sha256:${fingerprint}`, elements };
+    return { spec: all.length ? null : spec, draft, provenance, report, problems: all };
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { build, preview, validate, type Outcome } from "./commands.js";
+export { appCsp } from "./csp.js";
+export { extract, type Hints, type Provenance } from "./extract.js";
+export { touchedBy, type Touched } from "./diff.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+// Blackbox: write, check, build and preview CloudCrane app specs.
+export { build, preview, validate } from "./commands.js";
+export { appCsp } from "./csp.js";
+export { extract } from "./extract.js";
+export { touchedBy } from "./diff.js";

package/dist/readers/flutter-theme.d.ts

@@ -0,0 +1,20 @@
+export type ThemeColor = {
+    name: string;
+    dark: string;
+    light: string;
+    line: number;
+};
+export type FlutterTheme = {
+    colors: ThemeColor[];
+    font: {
+        family: string;
+        line: number;
+    } | null;
+    radius: {
+        value: number;
+        line: number;
+    } | null;
+};
+export declare function readFlutterTheme(source: string): FlutterTheme;
+/** Common Flutter colour names → the A2UI theme variable they set (tokens' paths). A hint can add or override. */
+export declare const ROLES: Record<string, string[]>;

package/dist/readers/flutter-theme.js

@@ -0,0 +1,68 @@
+// A Flutter theme's colours, font and corner radius, read from its Dart source:
+// `static Color get name => dark ? const Color(0xAARRGGBB) : const Color(...)`
+// (or one colour, or Colors.white / Colors.black), `GoogleFonts.<family>(`, and
+// `BorderRadius.circular(<n>)` / `double radius = <n>`. Reading text, not
+// running Dart. Each value keeps its line, for provenance.
+const NAMED = { white: "#ffffff", black: "#000000", transparent: "#00000000" };
+/** 0xAARRGGBB as #rrggbb (or #rrggbbaa when not opaque). */
+function hexOf(argb) {
+    const v = argb.toLowerCase().replace(/^0x/, "").padStart(8, "f");
+    const [a, rgb] = [v.slice(0, 2), v.slice(2)];
+    return a === "ff" ? `#${rgb}` : `#${rgb}${a}`;
+}
+const colorIn = (s) => {
+    const hex = /Color\(\s*(0x[0-9a-fA-F]{6,8})\s*\)/.exec(s);
+    if (hex)
+        return hexOf(hex[1]);
+    const named = /Colors\.(\w+)\b/.exec(s);
+    return named && NAMED[named[1]] ? NAMED[named[1]] : null;
+};
+/** "atkinsonHyperlegible" → "Atkinson Hyperlegible". */
+const familyName = (camel) => camel.replace(/([a-z])([A-Z])/g, "$1 $2").replace(/^./, (c) => c.toUpperCase());
+export function readFlutterTheme(source) {
+    const colors = [];
+    let font = null;
+    let radius = null;
+    source.split("\n").forEach((text, i) => {
+        const line = i + 1;
+        const getter = /static\s+(?:const\s+)?Color\s+get\s+(\w+)\s*=>\s*(.+);/.exec(text) ?? /static\s+(?:const\s+)?Color\s+(\w+)\s*=\s*(.+);/.exec(text);
+        if (getter) {
+            const [, name, value] = getter;
+            const branch = /^(.*?)\?(.*):(.*)$/.exec(value);
+            const dark = branch ? colorIn(branch[2]) : colorIn(value);
+            const light = branch ? colorIn(branch[3]) : dark;
+            if (dark && light)
+                colors.push({ name: name, dark, light, line });
+        }
+        const f = /GoogleFonts\.(\w+?)(?:TextTheme)?\(/.exec(text);
+        if (f && !font)
+            font = { family: familyName(f[1]), line };
+        const r = /double\s+radius\s*=\s*(\d+(?:\.\d+)?)/.exec(text) ?? /BorderRadius\.circular\(\s*(\d+(?:\.\d+)?)\s*\)/.exec(text);
+        if (r && !radius)
+            radius = { value: Number(r[1]), line };
+    });
+    return { colors, font, radius };
+}
+/** Common Flutter colour names → the A2UI theme variable they set (tokens' paths). A hint can add or override. */
+export const ROLES = {
+    primaryColor: ["color", "primary"],
+    primary: ["color", "primary"],
+    primaryForeground: ["color", "on-primary"],
+    onPrimary: ["color", "on-primary"],
+    background: ["color", "background"],
+    scaffoldBackgroundColor: ["color", "background"],
+    cardColor: ["color", "surface"],
+    surfaceColor: ["color", "surface"],
+    surface: ["color", "surface"],
+    cardBorder: ["color", "border"],
+    borderColor: ["color", "border"],
+    foreground: ["color", "on-background"],
+    onSurface: ["color", "on-surface"],
+    mutedForeground: ["text", "caption-color"],
+    inputColor: ["color", "input"],
+    successColor: ["color", "success"],
+    amber: ["color", "warning"],
+    warningColor: ["color", "warning"],
+    destructive: ["color", "error"],
+    errorColor: ["color", "error"],
+};

package/dist/readers/ts-pure.d.ts

@@ -0,0 +1,20 @@
+export type Translated = {
+    consts: {
+        name: string;
+        value: number | string | boolean;
+        lines: [number, number];
+    }[];
+    functions: {
+        name: string;
+        params: string[];
+        cel: string;
+        lines: [number, number];
+    }[];
+    skipped: {
+        name: string;
+        why: string;
+        lines: [number, number];
+    }[];
+};
+/** The pure rules in a TypeScript module, as CEL, with what couldn't be translated and why. */
+export declare function translateModule(source: string, file?: string): Translated;

package/dist/readers/ts-pure.js

@@ -0,0 +1,176 @@
+import ts from "typescript";
+class Untranslatable extends Error {
+}
+const no = (why) => {
+    throw new Untranslatable(why);
+};
+const BINARY = {
+    [ts.SyntaxKind.PlusToken]: "+",
+    [ts.SyntaxKind.MinusToken]: "-",
+    [ts.SyntaxKind.AsteriskToken]: "*",
+    [ts.SyntaxKind.PercentToken]: "%",
+    [ts.SyntaxKind.LessThanToken]: "<",
+    [ts.SyntaxKind.LessThanEqualsToken]: "<=",
+    [ts.SyntaxKind.GreaterThanToken]: ">",
+    [ts.SyntaxKind.GreaterThanEqualsToken]: ">=",
+    [ts.SyntaxKind.EqualsEqualsEqualsToken]: "==",
+    [ts.SyntaxKind.EqualsEqualsToken]: "==",
+    [ts.SyntaxKind.ExclamationEqualsEqualsToken]: "!=",
+    [ts.SyntaxKind.ExclamationEqualsToken]: "!=",
+    [ts.SyntaxKind.AmpersandAmpersandToken]: "&&",
+    [ts.SyntaxKind.BarBarToken]: "||",
+};
+function expr(n, s) {
+    if (ts.isParenthesizedExpression(n))
+        return `(${expr(n.expression, s)})`;
+    if (ts.isNumericLiteral(n))
+        return n.text;
+    if (ts.isStringLiteral(n))
+        return JSON.stringify(n.text);
+    if (n.kind === ts.SyntaxKind.TrueKeyword)
+        return "true";
+    if (n.kind === ts.SyntaxKind.FalseKeyword)
+        return "false";
+    if (n.kind === ts.SyntaxKind.NullKeyword)
+        return "null";
+    if (ts.isIdentifier(n)) {
+        if (n.text === "undefined")
+            return "null";
+        if (s.fields.has(n.text))
+            return s.fields.get(n.text);
+        if (s.params.has(n.text) || s.locals.has(n.text) || s.known.has(n.text))
+            return n.text;
+        return no(`uses ${n.text}, which isn't a parameter or something in this file`);
+    }
+    if (ts.isPropertyAccessExpression(n) && ts.isIdentifier(n.expression) && s.params.has(n.expression.text))
+        return `${n.expression.text}.${n.name.text}`;
+    if (ts.isPrefixUnaryExpression(n)) {
+        if (n.operator === ts.SyntaxKind.ExclamationToken)
+            return `!${expr(n.operand, s)}`;
+        if (n.operator === ts.SyntaxKind.MinusToken)
+            return `-${expr(n.operand, s)}`;
+        return no("a ++ or -- changes a value");
+    }
+    if (ts.isBinaryExpression(n)) {
+        if (n.operatorToken.kind === ts.SyntaxKind.SlashToken)
+            return no("division: CEL divides whole numbers differently");
+        const op = BINARY[n.operatorToken.kind];
+        if (!op)
+            return no(`the ${ts.tokenToString(n.operatorToken.kind) ?? "operator"} operator`);
+        return `${expr(n.left, s)} ${op} ${expr(n.right, s)}`;
+    }
+    if (ts.isConditionalExpression(n))
+        return `${expr(n.condition, s)} ? ${expr(n.whenTrue, s)} : ${expr(n.whenFalse, s)}`;
+    if (ts.isCallExpression(n)) {
+        const args = n.arguments.map((a) => expr(a, s));
+        const callee = n.expression;
+        if (ts.isPropertyAccessExpression(callee) && ts.isIdentifier(callee.expression) && callee.expression.text === "Math") {
+            const m = callee.name.text;
+            if ((m === "max" || m === "min") && args.length === 2) {
+                const [a, b] = args;
+                return `(${a} ${m === "max" ? ">" : "<"} ${b} ? ${a} : ${b})`;
+            }
+            return no(`Math.${m}`);
+        }
+        if (ts.isIdentifier(callee) && s.known.has(callee.text))
+            return `${callee.text}(${args.join(", ")})`;
+        return no(`calls ${callee.getText()}, which isn't in this file`);
+    }
+    return no(`a ${ts.SyntaxKind[n.kind]}`);
+}
+/** A function body as one CEL expression, built from its last statement back. */
+function body(statements, s) {
+    const [first, ...rest] = statements;
+    if (!first)
+        return no("it can end without returning");
+    if (ts.isReturnStatement(first)) {
+        if (!first.expression)
+            return no("it returns nothing");
+        return expr(first.expression, s);
+    }
+    if (ts.isIfStatement(first)) {
+        const thenReturn = ts.isBlock(first.thenStatement) ? first.thenStatement.statements : [first.thenStatement];
+        if (first.elseStatement) {
+            const elseReturn = ts.isBlock(first.elseStatement) ? first.elseStatement.statements : [first.elseStatement];
+            return `${expr(first.expression, s)} ? ${body(thenReturn, s)} : ${body([...elseReturn, ...rest], s)}`;
+        }
+        return `${expr(first.expression, s)} ? ${body(thenReturn, s)} : ${body(rest, s)}`;
+    }
+    if (ts.isVariableStatement(first) && first.declarationList.flags & ts.NodeFlags.Const) {
+        const [d] = first.declarationList.declarations;
+        if (!d || first.declarationList.declarations.length !== 1 || !d.initializer)
+            return no("a declaration it can't follow");
+        // const { a, b } = opts;  →  a and b read opts.a and opts.b
+        if (ts.isObjectBindingPattern(d.name) && ts.isIdentifier(d.initializer) && s.params.has(d.initializer.text)) {
+            for (const el of d.name.elements) {
+                if (!ts.isIdentifier(el.name) || el.initializer || el.dotDotDotToken)
+                    return no("a destructuring it can't follow");
+                const field = el.propertyName && ts.isIdentifier(el.propertyName) ? el.propertyName.text : el.name.text;
+                s.fields.set(el.name.text, `${d.initializer.text}.${field}`);
+            }
+            return body(rest, s);
+        }
+        if (!ts.isIdentifier(d.name))
+            return no("a declaration it can't follow");
+        const value = expr(d.initializer, s);
+        s.locals.add(d.name.text);
+        return `cel.bind(${d.name.text}, ${value}, ${body(rest, s)})`;
+    }
+    return no(`a ${ts.SyntaxKind[first.kind]} statement`);
+}
+const linesOf = (sf, n) => [
+    sf.getLineAndCharacterOfPosition(n.getStart(sf)).line + 1,
+    sf.getLineAndCharacterOfPosition(n.getEnd()).line + 1,
+];
+/** The pure rules in a TypeScript module, as CEL, with what couldn't be translated and why. */
+export function translateModule(source, file = "module.ts") {
+    const sf = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const out = { consts: [], functions: [], skipped: [] };
+    const known = new Set();
+    for (const st of sf.statements) {
+        if (ts.isFunctionDeclaration(st) && st.name)
+            known.add(st.name.text);
+        if (ts.isVariableStatement(st))
+            for (const d of st.declarationList.declarations)
+                if (ts.isIdentifier(d.name))
+                    known.add(d.name.text);
+    }
+    for (const st of sf.statements) {
+        if (ts.isVariableStatement(st) && st.declarationList.flags & ts.NodeFlags.Const) {
+            for (const d of st.declarationList.declarations) {
+                if (!ts.isIdentifier(d.name) || !d.initializer)
+                    continue;
+                const i = d.initializer;
+                const literal = ts.isNumericLiteral(i)
+                    ? Number(i.text)
+                    : ts.isStringLiteral(i)
+                        ? i.text
+                        : i.kind === ts.SyntaxKind.TrueKeyword
+                            ? true
+                            : i.kind === ts.SyntaxKind.FalseKeyword
+                                ? false
+                                : undefined;
+                if (literal !== undefined)
+                    out.consts.push({ name: d.name.text, value: literal, lines: linesOf(sf, st) });
+                else
+                    out.skipped.push({ name: d.name.text, why: "a constant that isn't a plain value", lines: linesOf(sf, st) });
+            }
+        }
+        if (ts.isFunctionDeclaration(st) && st.name && st.body) {
+            const name = st.name.text;
+            try {
+                if (st.asteriskToken || st.modifiers?.some((m) => m.kind === ts.SyntaxKind.AsyncKeyword))
+                    no("it's async or a generator");
+                const params = st.parameters.map((p) => ts.isIdentifier(p.name) && !p.initializer && !p.dotDotDotToken ? p.name.text : no("a parameter with a default, rest or pattern"));
+                const scope = { params: new Set(params), fields: new Map(), locals: new Set(), known };
+                out.functions.push({ name, params, cel: body(st.body.statements, scope), lines: linesOf(sf, st) });
+            }
+            catch (e) {
+                if (!(e instanceof Untranslatable))
+                    throw e;
+                out.skipped.push({ name, why: e.message, lines: linesOf(sf, st) });
+            }
+        }
+    }
+    return out;
+}

package/dist/readers/ts-vectors.d.ts

@@ -0,0 +1,11 @@
+export type Vector = {
+    fn: string;
+    in: unknown[];
+    out: unknown;
+    line: number;
+};
+/** Literal vectors for `functions` found in a test file, and how many calls had to be left out. */
+export declare function harvestVectors(source: string, functions: Set<string>, file?: string): {
+    vectors: Vector[];
+    leftOut: number;
+};

package/dist/readers/ts-vectors.js

@@ -0,0 +1,86 @@
+import ts from "typescript";
+function literal(n) {
+    if (ts.isParenthesizedExpression(n))
+        return literal(n.expression);
+    if (ts.isNumericLiteral(n))
+        return { ok: true, value: Number(n.text) };
+    if (ts.isStringLiteral(n) || ts.isNoSubstitutionTemplateLiteral(n))
+        return { ok: true, value: n.text };
+    if (n.kind === ts.SyntaxKind.TrueKeyword)
+        return { ok: true, value: true };
+    if (n.kind === ts.SyntaxKind.FalseKeyword)
+        return { ok: true, value: false };
+    if (n.kind === ts.SyntaxKind.NullKeyword)
+        return { ok: true, value: null };
+    if (ts.isPrefixUnaryExpression(n) && n.operator === ts.SyntaxKind.MinusToken && ts.isNumericLiteral(n.operand))
+        return { ok: true, value: -Number(n.operand.text) };
+    if (ts.isArrayLiteralExpression(n)) {
+        const items = n.elements.map((e) => literal(e));
+        return items.every((i) => i.ok) ? { ok: true, value: items.map((i) => i.value) } : { ok: false };
+    }
+    if (ts.isObjectLiteralExpression(n)) {
+        const out = {};
+        for (const p of n.properties) {
+            if (!ts.isPropertyAssignment(p) || !(ts.isIdentifier(p.name) || ts.isStringLiteral(p.name)))
+                return { ok: false };
+            const v = literal(p.initializer);
+            if (!v.ok)
+                return { ok: false };
+            out[p.name.text] = v.value;
+        }
+        return { ok: true, value: out };
+    }
+    return { ok: false };
+}
+const inLoop = (n) => {
+    for (let p = n.parent; p; p = p.parent)
+        if (ts.isForStatement(p) || ts.isForOfStatement(p) || ts.isForInStatement(p) || ts.isWhileStatement(p) || ts.isDoStatement(p))
+            return true;
+    return false;
+};
+/** Literal vectors for `functions` found in a test file, and how many calls had to be left out. */
+export function harvestVectors(source, functions, file = "test.ts") {
+    const sf = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const vectors = [];
+    let leftOut = 0;
+    const visit = (n) => {
+        if (ts.isCallExpression(n)) {
+            let actual;
+            let expected;
+            const callee = n.expression;
+            // assert.equal(actual, expected) and friends
+            if (ts.isPropertyAccessExpression(callee) &&
+                ts.isIdentifier(callee.expression) &&
+                callee.expression.text === "assert" &&
+                /^(equal|strictEqual|deepEqual|deepStrictEqual)$/.test(callee.name.text)) {
+                [actual, expected] = n.arguments;
+            }
+            // expect(actual).toBe(expected) / toEqual / toStrictEqual
+            if (ts.isPropertyAccessExpression(callee) &&
+                /^(toBe|toEqual|toStrictEqual)$/.test(callee.name.text) &&
+                ts.isCallExpression(callee.expression) &&
+                ts.isIdentifier(callee.expression.expression) &&
+                callee.expression.expression.text === "expect") {
+                actual = callee.expression.arguments[0];
+                expected = n.arguments[0];
+            }
+            if (actual && expected && ts.isCallExpression(actual) && ts.isIdentifier(actual.expression) && functions.has(actual.expression.text)) {
+                const args = actual.arguments.map(literal);
+                const out = literal(expected);
+                if (!inLoop(n) && args.every((a) => a.ok) && out.ok) {
+                    vectors.push({
+                        fn: actual.expression.text,
+                        in: args.map((a) => a.value),
+                        out: out.value,
+                        line: sf.getLineAndCharacterOfPosition(n.getStart(sf)).line + 1,
+                    });
+                }
+                else
+                    leftOut++;
+            }
+        }
+        ts.forEachChild(n, visit);
+    };
+    visit(sf);
+    return { vectors, leftOut };
+}

package/dist/shingles.d.ts

@@ -0,0 +1,3 @@
+import type { Problem } from "@cloudcrane/app-spec";
+/** Strings in `spec` that repeat 8 tokens running from any of `sources`. */
+export declare function shingleLeaks(spec: unknown, sources: string[]): Problem[];

package/dist/shingles.js

@@ -0,0 +1,46 @@
+// The second leak gate, against the partner's own source: no string in a spec
+// may contain a run of 8 consecutive tokens (words, numbers, punctuation) that
+// also appears in a source file it was read from. The static scan in app-spec
+// catches code by its shape; this catches it by being copied, whatever its
+// shape. CEL rules are exempt: they're translated from the source by design and
+// checked by vectors instead. A2UI bindings (${/path}) are the standard's syntax.
+const SIZE = 8;
+const tokens = (s) => s.match(/[A-Za-z_$][\w$]*|\d+(?:\.\d+)?|[^\s\w]/g) ?? [];
+function shinglesOf(text) {
+    const out = new Set();
+    const t = tokens(text);
+    for (let i = 0; i + SIZE <= t.length; i++)
+        out.add(t.slice(i, i + SIZE).join(" "));
+    return out;
+}
+const CEL_AT = [/^\/logic\/functions\/[^/]+\/cel$/, /^\/logic\/computed\/.+$/, /^\/data\/migrations\/\d+\/cel$/];
+const escape = (k) => k.replace(/~/g, "~0").replace(/\//g, "~1");
+function* strings(v, at = "") {
+    if (typeof v === "string")
+        yield [at, v];
+    else if (Array.isArray(v))
+        for (let i = 0; i < v.length; i++)
+            yield* strings(v[i], `${at}/${i}`);
+    else if (v && typeof v === "object")
+        for (const [k, x] of Object.entries(v))
+            yield* strings(x, `${at}/${escape(k)}`);
+}
+/** Strings in `spec` that repeat 8 tokens running from any of `sources`. */
+export function shingleLeaks(spec, sources) {
+    const known = new Set();
+    for (const s of sources)
+        for (const sh of shinglesOf(s))
+            known.add(sh);
+    const problems = [];
+    for (const [at, raw] of strings(spec)) {
+        if (CEL_AT.some((r) => r.test(at)))
+            continue;
+        const text = raw.replace(/\$\{[^}]*\}/g, " ");
+        for (const sh of shinglesOf(text))
+            if (known.has(sh)) {
+                problems.push({ at, problem: `repeats the source word for word ("${sh.slice(0, 60)}")` });
+                break;
+            }
+    }
+    return problems;
+}

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "@cloudcrane/blackbox",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Turns an app's code into a CloudCrane app spec with no code in it, checks it, and builds or previews the app it describes.",
+  "keywords": [
+    "cloudcrane",
+    "blackbox",
+    "app-spec",
+    "port",
+    "cli"
+  ],
+  "homepage": "https://github.com/cloudcrane-dev/blackbox/tree/main/packages/blackbox#readme",
+  "bugs": {
+    "url": "https://github.com/cloudcrane-dev/blackbox/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cloudcrane-dev/blackbox.git",
+    "directory": "packages/blackbox"
+  },
+  "license": "MIT",
+  "author": "Chirag Phor",
+  "type": "module",
+  "engines": {
+    "node": ">=22.5"
+  },
+  "bin": {
+    "blackbox": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "typescript": "~5.9.3",
+    "veridic": "^0.14.0",
+    "zod": "^3.25.76",
+    "@cloudcrane/app-runtime": "^0.1.0",
+    "@cloudcrane/app-spec": "^0.1.0"
+  },
+  "devDependencies": {
+    "tsx": "4.23.15"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
 }